This is TheLogtalkHandbook-3.101.0.info, produced by makeinfo version
7.3 from TheLogtalkHandbook-3.101.0.texi.

     The Logtalk Handbook v3.101.0, Jul 23, 2026

     Paulo Moura

     Copyright © 1998-2026, Paulo Moura

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


   Generated by Sphinx 7.4.7.


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

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

     The Logtalk Handbook v3.101.0, Jul 23, 2026

     Paulo Moura

     Copyright © 1998-2026, Paulo Moura

* Menu:

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

 -- The Detailed Node Listing --

User Manual

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

Main features

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

Nomenclature

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

Messages

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

Objects

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

Objects, prototypes, classes, and instances

* Prototypes::
* Classes::

Parametric objects

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

Object directives

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

Built-in objects

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

Protocols

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

Protocol directives

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

Built-in protocols

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

Categories

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

Category directives

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

Built-in categories

* The built-in category core_messages::

Predicates

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

Declaring predicates

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

Defining predicates

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

Built-in methods

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

Calling Prolog predicates

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

Inheritance

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

Protocol inheritance

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

Implementation inheritance

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

Event-driven programming

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

Definitions

* Event::
* Monitor::

Event handling

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

Multi-threading programming

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

Multi-threading built-in predicates

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

Error handling

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

Compiler warnings and errors

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

Runtime errors

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

Reflection

* Structural reflection::
* Behavioral reflection::

Structural reflection

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

Writing and running applications

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

Source files

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

Compiler flags

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

Printing messages and asking questions

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

Term and goal expansion

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

Documenting

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

Debugging

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

Defining breakpoints

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

Customizing term writing

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

Debugging messages

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

Performance

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

Installing Logtalk

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

Hardware and software requirements

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

Distribution overview

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

Prolog integration and migration

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

Encapsulating plain Prolog code in objects

* Prolog multifile predicates::

Compiling Prolog modules as objects

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

Reference Manual

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

Grammar

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

Entity relations

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

Entity identifiers

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

Terms

* Object terms::
* Category terms::

Directives

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

Control constructs

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

Message sending

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

(::)/2

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

(::)/1

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

Message delegation

* []/1::

[]/1

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

Calling imported and inherited predicates

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

(^^)/1

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

Calling predicates in this

* (@)/1: @ /1.

(@)/1

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

Calling external predicates

* {}/1::

{}/1

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

Context switching calls

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

(<<)/2

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

Directives

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

Source file directives

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

encoding/1

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

include/1

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

initialization/1

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

op/3

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

set_logtalk_flag/2

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

Conditional compilation directives

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

if/1

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

elif/1

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

else/0

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

endif/0

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

Entity directives

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

built_in/0

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

category/1-4

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

dynamic/0

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

end_category/0

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

end_object/0

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

end_protocol/0

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

info/1

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

object/1-5

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

protocol/1-2

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

threaded/0

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

uses/1

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

use_module/1

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

Predicate directives

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

alias/2

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

coinductive/1

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

discontiguous/1

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

dynamic/1

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

info/2

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

meta_predicate/1

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

meta_non_terminal/1

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

mode/2

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

mode_non_terminal/2

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

multifile/1

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

private/1

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

protected/1

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

public/1

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

synchronized/1

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

uses/2

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

use_module/2

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

Built-in predicates

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

Enumerating objects, categories and protocols

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

current_category/1

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

current_object/1

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

current_protocol/1

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

Enumerating objects, categories and protocols properties

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

category_property/2

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

object_property/2

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

protocol_property/2

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

Creating new objects, categories and protocols

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

create_category/4

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

create_object/4

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

create_protocol/3

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

Abolishing objects, categories and protocols

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

abolish_category/1

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

abolish_object/1

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

abolish_protocol/1

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

Objects, categories, and protocols relations

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

extends_object/2-3

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

extends_protocol/2-3

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

extends_category/2-3

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

implements_protocol/2-3

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

conforms_to_protocol/2-3

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

complements_object/2

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

imports_category/2-3

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

instantiates_class/2-3

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

specializes_class/2-3

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

Event handling

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

abolish_events/5

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

current_event/5

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

define_events/5

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

Multi-threading

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

threaded/1

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

threaded_call/1-2

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

threaded_once/1-2

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

threaded_ignore/1

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

threaded_exit/1-2

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

threaded_peek/1-2

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

threaded_cancel/1

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

threaded_wait/1

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

threaded_notify/1

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

Multi-threading engines

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

threaded_engine_create/3

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

threaded_engine_destroy/1

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

threaded_engine/1

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

threaded_engine_self/1

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

threaded_engine_next/2

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

threaded_engine_next_reified/2

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

threaded_engine_yield/1

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

threaded_engine_post/2

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

threaded_engine_fetch/1

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

Compiling and loading source files

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

logtalk_compile/1

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

logtalk_compile/2

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

logtalk_load/1

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

logtalk_load/2

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

logtalk_make/0

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

logtalk_make/1

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

logtalk_make_target_action/1

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

logtalk_library_path/2

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

logtalk_load_context/2

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

Flags

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

current_logtalk_flag/2

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

set_logtalk_flag/2

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

create_logtalk_flag/3

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

Linter

* logtalk_linter_hook/7::

logtalk_linter_hook/7

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

Built-in methods

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

Logic and control

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

!/0

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

true/0

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

fail/0

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

false/0

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

repeat/0

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

Execution context

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

context/1

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

parameter/2

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

self/1

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

sender/1

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

this/1

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

Reflection

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

current_op/3

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

current_predicate/1

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

predicate_property/2

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

Database

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

abolish/1

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

asserta/1

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

assertz/1

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

clause/2

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

retract/1

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

retractall/1

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

Meta-calls

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

call/1-N

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

ignore/1

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

once/1

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

(\+)/1

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

Error handling

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

catch/3

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

throw/1

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

instantiation_error/0

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

uninstantiation_error/1

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

type_error/2

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

domain_error/2

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

consistency_error/3

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

existence_error/2

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

permission_error/3

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

representation_error/1

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

evaluation_error/1

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

resource_error/1

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

syntax_error/1

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

system_error/0

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

All solutions

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

bagof/3

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

findall/3

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

findall/4

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

forall/2

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

setof/3

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

Event handling

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

before/3

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

after/3

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

Message forwarding

* forward/1::

forward/1

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

Definite clause grammar rules

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

call//1-N

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

eos//0

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

phrase//1

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

phrase/2

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

phrase/3

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

Term and goal expansion

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

expand_term/2

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

term_expansion/2

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

expand_goal/2

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

goal_expansion/2

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

Coinduction hooks

* coinductive_success_hook/1-2::

coinductive_success_hook/1-2

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

Message printing

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

print_message/3

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

message_tokens//2

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

message_hook/4

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

message_prefix_stream/4

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

message_prefix_file/6

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

print_message_tokens/3

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

print_message_token/4

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

Question asking

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

ask_question/5

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

question_hook/6

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

question_prompt_stream/4

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

Tutorial

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

List predicates

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

Dynamic object attributes

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

A reflective class-based system

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

Profiling programs

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

FAQ

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

General

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

Compatibility

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

Installation

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

Portability

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

Programming

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

Troubleshooting

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

Usability

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

Deployment

* Can I create standalone applications with Logtalk?::

Performance

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

Licensing

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

Support

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

Developer Tools

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

Overview

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

Tools requirements

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

assertions

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

code_metrics

* API documentation: API documentation<2>.
* Loading: Loading<2>.
* Testing: Testing<2>.
* Available metrics::
* Coupling metrics::
* Lack of cohesion metric::
* WMC metric::
* RFC metric::
* Cognitive complexity metric::
* Lines metric::
* Maintainability index metric::
* Halstead metric::
* UPN metric::
* Cyclomatic complexity metric::
* Usage::
* Excluding code from analysis::
* Defining new metrics::
* Third-party tools::
* Applying metrics to Prolog modules::
* Applying metrics to plain Prolog code::

dead_code_scanner

* API documentation: API documentation<3>.
* Loading: Loading<3>.
* Testing: Testing<3>.
* Usage: Usage<2>.
* Excluding code from analysis: Excluding code from analysis<2>.
* Machine-readable summaries::
* Machine-readable preflight warnings::
* Finding classes and confidence::
* SARIF reports::
* Integration with the make tool::
* Caveats::
* Scanning Prolog modules::
* Scanning plain Prolog files::
* Known issues::

debug_messages

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

debugger

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

diagrams

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

Requirements

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

doclet

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

help

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

issue_creator

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

lgtdoc

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

lgtunit

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

Exporting test results

* xUnit XML format::
* TAP output format::
* CTRF JSON format::
* Subunit formats::

Exporting code coverage results

* Simple XML format::
* Cobertura XML format::
* LCOV format::

linter

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

linter_reporter

* API documentation: API documentation<11>.
* Loading: Loading<12>.
* Testing: Testing<10>.
* Usage: Usage<7>.
* Options::

make

* API documentation: API documentation<12>.
* Help with warnings: Help with warnings<2>.
* Known issues: Known issues<6>.

mutation_testing

* API documentation: API documentation<13>.
* Loading: Loading<13>.
* Testing: Testing<11>.
* Features::
* Default mutators::
* Usage: Usage<8>.
* Limitations::
* Options: Options<2>.
* Sampling semantics::
* Defining new mutators::

Sampling semantics

* Sampling modes::
* Sampling usage in practice::

packs

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

ports_profiler

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

profiler

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

sarif

* API documentation: API documentation<16>.
* Loading: Loading<17>.
* Testing: Testing<15>.
* Usage: Usage<10>.
* Diagnostics producers::
* Report visualization::

sbom

* API documentation: API documentation<17>.
* Loading: Loading<18>.
* Testing: Testing<16>.
* Usage: Usage<11>.
* Known issues: Known issues<9>.

tool_diagnostics

* API documentation: API documentation<18>.
* Loading: Loading<19>.
* Protocol overview::
* Term conventions::
* Usage: Usage<12>.

tutor

* API documentation: API documentation<19>.
* Loading: Loading<20>.
* Usage: Usage<13>.

wrapper

* API documentation: API documentation<20>.
* Loading: Loading<21>.
* Workflows::
* Customization: Customization<3>.
* Current limitations::

Libraries

* Overview: Overview<2>.
* adaptive_boosting_classifier::
* agglomerative_clusterer::
* amqp::
* anomaly_detection_protocols::
* application::
* apriori_pattern_miner::
* arbitrary::
* arrangements::
* assignvars::
* avro::
* base32::
* base58::
* base64::
* base85::
* basic_types::
* bayesian_ridge_regression::
* borda_ranker::
* bradley_terry_ranker::
* c45_classifier::
* cartesian_products::
* cbor::
* character_sets::
* ccsds_frames::
* ccsds_link_profiles::
* ccsds_packet_services::
* ccsds_packetization::
* ccsds_packets::
* ccsds_tc_services::
* ccsds_time_codes::
* ccsds_time_fields::
* classification_protocols::
* clo_span_pattern_miner::
* clustering_protocols::
* colley_ranker::
* combinations::
* command_line_options::
* core::
* copeland_ranker::
* coroutining::
* crypto::
* crs_projections::
* csv::
* cuid2::
* cusum_anomaly_detector::
* datalog::
* dates::
* dates_tz::
* dbscan_clusterer::
* dependents::
* deques::
* derangements::
* dictionaries::
* dif::
* dimension_reduction_protocols::
* eclat_pattern_miner::
* edcg::
* elastic_net_regression::
* elo_ranker::
* events::
* ewma_anomaly_detector::
* expand_library_alias_paths::
* expecteds::
* format::
* fp_growth_pattern_miner::
* frequent_pattern_mining_protocols::
* gaussian_mixture_clusterer::
* gaussian_process_regression::
* genint::
* gensym::
* geojson::
* geospatial::
* git::
* glicko2_ranker::
* glicko2_periodic_ranker::
* gradient_boosting_classifier::
* gradient_boosting_regression::
* grammars::
* graphs::
* gravatar::
* gsp_pattern_miner::
* hashes::
* hdbscan_clusterer::
* heaps::
* hierarchical_clustering::
* hierarchies::
* hmac::
* hodge_rank::
* hook_flows::
* hook_objects::
* html::
* http_authenticate::
* http_client::
* http_client_core::
* http_cookies::
* http_core::
* http_cors::
* http_digest::
* http_directory_listing::
* http_htmx::
* http_multipart::
* http_parameters::
* http_router::
* http_server::
* http_server_core::
* http_session::
* http_socket_transport::
* http_process_transport::
* http_static_files::
* http_websocket::
* http_websocket_frames::
* http_websocket_handshake::
* http_websocket_messages::
* http_websocket_service::
* http_websocket_session::
* ica_projection::
* ids::
* ieee_754::
* intervals::
* iqr_anomaly_detector::
* iso_639::
* iso_3166::
* iso_4217::
* iso_9362::
* iso_13616::
* isolation_forest_anomaly_detector::
* java::
* json::
* json_graph::
* json_ld::
* json_lines::
* json_patch::
* json_path::
* json_pointer::
* json_rpc::
* json_schema::
* jwt::
* kcenters_clusterer::
* kemeny_young_ranker::
* kernel_svm_classifier::
* kernel_pca_projection::
* kmeans_clusterer::
* kmedians_clusterer::
* kmedoids_clusterer::
* kmodes_clusterer::
* knn_classifier::
* knn_distance_anomaly_detector::
* knn_regression::
* kprototypes_clusterer::
* ksuid::
* lasso_regression::
* lda_classifier::
* lda_projection::
* linda::
* linear_algebra::
* linear_regression::
* linear_svm_classifier::
* listing::
* lof_anomaly_detector::
* logging::
* logistic_regression_classifier::
* loops::
* massey_ranker::
* mcp_server::
* memcached::
* message_pack::
* meta::
* meta_compiler::
* mime_types::
* modified_z_score_anomaly_detector::
* mutations::
* multisets::
* nanoid::
* naive_bayes_classifier::
* nearest_centroid_classifier::
* nested_dictionaries::
* nmea::
* nmf_projection::
* open_api::
* open_ai::
* open_id::
* optics_clusterer::
* optionals::
* options::
* os::
* otp::
* partitions::
* pattern_mining_protocols::
* pca_projection::
* permutations::
* plackett_luce_ranker::
* plackett_luce_last_ranker::
* pls_projection::
* prefix_span_pattern_miner::
* probabilistic_pca_projection::
* process::
* protobuf::
* qda_classifier::
* queues::
* random::
* random_forest_classifier::
* random_forest_regression::
* random_projection::
* rank_centrality::
* ranked_pairs::
* ranking_protocols::
* reader::
* recorded_database::
* redis::
* regression_protocols::
* regression_tree::
* regularized_bradley_terry_ranker::
* rest::
* ridge_regression::
* s3::
* schulze_ranker::
* sequential_pattern_mining_protocols::
* sets::
* sgd_classifier::
* snowflakeid::
* sockets::
* spade_pattern_miner::
* simulated_annealing::
* statistics::
* stemming::
* stomp::
* string_distance::
* strings::
* subsequences::
* term_io::
* thurstone_mosteller_ranker::
* time_scales::
* timeout::
* tle_orbits::
* toml::
* toon::
* truncated_svd_projection::
* tsv::
* types::
* tzif::
* ulid::
* unicode_data::
* union_find::
* url::
* uuid::
* validations::
* wkt_wkb::
* yaml::
* z_score_anomaly_detector::
* zippers::

Overview

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

adaptive_boosting_classifier

* API documentation: API documentation<21>.
* Loading: Loading<22>.
* Testing: Testing<17>.
* Features: Features<2>.
* Options: Options<3>.
* Classifier representation::
* References::
* Usage: Usage<14>.

Usage

* Learning a Classifier::
* Making Predictions::
* Exporting the Classifier::
* Using a Saved Classifier::
* Printing the Classifier::

agglomerative_clusterer

* API documentation: API documentation<22>.
* Loading: Loading<23>.
* Testing: Testing<18>.
* Features: Features<3>.
* Options: Options<4>.
* Clusterer representation::
* Diagnostics::

amqp

* API documentation: API documentation<23>.
* Loading: Loading<24>.
* Testing: Testing<19>.
* Features: Features<4>.
* Usage: Usage<15>.
* Connection Pooling::
* Binary Frame Encoding::
* Data Types::
* Float/Double Encoding/Decoding::
* Error Handling::
* Comparison with STOMP::
* Future Work::
* Known Limitations and Issues::
* AMQP 1.0 vs AMQP 0-9-1: AMQP 1 0 vs AMQP 0-9-1.

Usage

* Connecting to an AMQP server::
* Opening a channel::
* Declaring exchanges and queues::
* Publishing messages::
* Consuming messages::
* Synchronous get::
* Quality of Service::
* Transactions::
* Publisher Confirms (RabbitMQ extension): Publisher Confirms RabbitMQ extension.
* Closing connections::

Connection Pooling

* Defining a pool::
* Initializing the pool::
* Acquiring and releasing connections::
* Using with_connection/1::
* Pool statistics::
* Resizing the pool::
* Destroying the pool::
* Creating pools dynamically::

Binary Frame Encoding

* Frame structure::
* Encoding/decoding frames::

anomaly_detection_protocols

* Export header format::
* API documentation: API documentation<24>.
* Loading: Loading<25>.
* Testing: Testing<20>.
* Test datasets::

application

* API documentation: API documentation<25>.
* Loading: Loading<26>.
* Testing: Testing<21>.
* Usage: Usage<16>.

apriori_pattern_miner

* API documentation: API documentation<26>.
* Loading: Loading<27>.
* Testing: Testing<22>.
* Features: Features<5>.
* Options: Options<5>.
* Pattern miner representation::
* References: References<2>.

arbitrary

* API documentation: API documentation<27>.
* Loading: Loading<28>.
* Testing: Testing<23>.
* Pre-defined types::
* Usage: Usage<17>.
* Defining new generators and shrinkers::
* Scoped generators and shrinkers::
* Reproducing sequences of arbitrary terms::
* Default size of generated terms::
* Known issues: Known issues<10>.

arrangements

* API documentation: API documentation<28>.
* Loading: Loading<29>.
* Testing: Testing<24>.

assignvars

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

avro

* API documentation: API documentation<30>.
* Loading: Loading<31>.
* Testing: Testing<26>.
* Schema representation::
* Data representation::
* Schema Examples::
* Encoding::
* Decoding::

base32

* API documentation: API documentation<31>.
* Loading: Loading<32>.
* Testing: Testing<27>.
* Encoding: Encoding<2>.
* Decoding: Decoding<2>.

base58

* API documentation: API documentation<32>.
* Loading: Loading<33>.
* Testing: Testing<28>.
* Encoding: Encoding<3>.
* Decoding: Decoding<3>.

base64

* API documentation: API documentation<33>.
* Loading: Loading<34>.
* Testing: Testing<29>.
* Encoding: Encoding<4>.
* Decoding: Decoding<4>.

base85

* API documentation: API documentation<34>.
* Loading: Loading<35>.
* Testing: Testing<30>.
* Encoding: Encoding<5>.
* Decoding: Decoding<5>.

basic_types

* API documentation: API documentation<35>.
* Loading: Loading<36>.
* Testing: Testing<31>.

bayesian_ridge_regression

* API documentation: API documentation<36>.
* Loading: Loading<37>.
* Testing: Testing<32>.
* Features: Features<6>.
* Regressor representation::
* Diagnostics syntax::
* Options: Options<6>.

borda_ranker

* API documentation: API documentation<37>.
* Loading: Loading<38>.
* Testing: Testing<33>.
* Features: Features<7>.
* Scoring semantics::
* Usage: Usage<18>.
* Diagnostics syntax: Diagnostics syntax<2>.
* Options: Options<7>.
* Ranker representation::
* References: References<3>.

Usage

* Learning a ranker::
* Inspecting diagnostics::
* Ranking candidate items::
* Exporting the ranker::

bradley_terry_ranker

* API documentation: API documentation<38>.
* Loading: Loading<39>.
* Testing: Testing<34>.
* Features: Features<8>.
* Dataset requirements::
* Usage: Usage<19>.
* Diagnostics syntax: Diagnostics syntax<3>.
* Options: Options<8>.
* Ranker representation: Ranker representation<2>.
* References: References<4>.

Usage

* Learning a ranker: Learning a ranker<2>.
* Inspecting diagnostics: Inspecting diagnostics<2>.

Diagnostics syntax

* Ranking candidate items: Ranking candidate items<2>.
* Exporting the ranker: Exporting the ranker<2>.

c45_classifier

* API documentation: API documentation<39>.
* Loading: Loading<40>.
* Testing: Testing<35>.
* Implemented features::
* Learned tree representation::
* Limitations: Limitations<2>.
* References: References<5>.
* Usage: Usage<20>.

cartesian_products

* API documentation: API documentation<40>.
* Loading: Loading<41>.
* Testing: Testing<36>.

cbor

* Representation::
* Encoding: Encoding<6>.
* Decoding: Decoding<6>.
* API documentation: API documentation<41>.
* Loading: Loading<42>.
* Testing: Testing<37>.

character_sets

* API documentation: API documentation<42>.
* Loading: Loading<43>.
* Testing: Testing<38>.
* Usage: Usage<21>.

ccsds_frames

* API documentation: API documentation<43>.
* Loading: Loading<44>.
* Testing: Testing<39>.
* Available entities::
* Representation: Representation<2>.
* Parsing and generating::
* Types::
* Facade helpers::

ccsds_link_profiles

* API documentation: API documentation<44>.
* Loading: Loading<45>.
* Testing: Testing<40>.
* Representation: Representation<3>.
* Public API::
* Parsing and generating: Parsing and generating<2>.
* Packet helpers::

ccsds_packet_services

* API documentation: API documentation<45>.
* Loading: Loading<46>.
* Testing: Testing<41>.
* Representation: Representation<4>.
* Packet-zone helpers::
* Telemetry transfer frame helpers::
* Advanced orbiting systems helpers::
* Cross-frame packet reassembly::
* Scope::

ccsds_packetization

* API documentation: API documentation<46>.
* Loading: Loading<47>.
* Testing: Testing<42>.
* Representation: Representation<5>.
* Packetization::
* Events::
* Idle packets::

ccsds_packets

* API documentation: API documentation<47>.
* Loading: Loading<48>.
* Testing: Testing<43>.
* Packet Structure::
* Representation: Representation<6>.
* Parsing::
* Generating::
* Accessor Predicates::
* Types and arbitrary generators::

ccsds_tc_services

* API documentation: API documentation<48>.
* Loading: Loading<49>.
* Testing: Testing<44>.
* Representation: Representation<7>.
* Scope: Scope<2>.
* Examples: Examples<166>.

ccsds_time_codes

* API documentation: API documentation<49>.
* Loading: Loading<50>.
* Testing: Testing<45>.
* Available entities: Available entities<2>.
* Representation: Representation<8>.
* Parsing and generating: Parsing and generating<3>.
* Unix time conversion::
* Types and arbitrary generators: Types and arbitrary generators<2>.

ccsds_time_fields

* API documentation: API documentation<50>.
* Loading: Loading<51>.
* Testing: Testing<46>.
* Representation: Representation<9>.
* Parsing and generating: Parsing and generating<4>.
* Descriptor helpers::

classification_protocols

* Shared category::
* Diagnostics: Diagnostics<2>.
* Export header format: Export header format<2>.
* API documentation: API documentation<51>.
* Loading: Loading<52>.
* Testing: Testing<47>.
* Test datasets: Test datasets<2>.

clo_span_pattern_miner

* API documentation: API documentation<52>.
* Loading: Loading<53>.
* Testing: Testing<48>.
* Features: Features<9>.
* Options: Options<9>.
* Pattern miner representation: Pattern miner representation<2>.
* References: References<6>.

clustering_protocols

* API documentation: API documentation<53>.
* Loading: Loading<54>.
* Testing: Testing<49>.
* Test datasets: Test datasets<3>.

colley_ranker

* API documentation: API documentation<54>.
* Loading: Loading<55>.
* Testing: Testing<50>.
* Features: Features<10>.
* Scoring semantics: Scoring semantics<2>.
* Usage: Usage<22>.
* Diagnostics syntax: Diagnostics syntax<4>.
* Ranker representation: Ranker representation<3>.
* References: References<7>.

Usage

* Learning a ranker: Learning a ranker<3>.
* Inspecting diagnostics: Inspecting diagnostics<3>.
* Ranking candidate items: Ranking candidate items<3>.
* Exporting the ranker: Exporting the ranker<3>.

combinations

* API documentation: API documentation<55>.
* Loading: Loading<56>.
* Testing: Testing<51>.

command_line_options

* API documentation: API documentation<56>.
* Loading: Loading<57>.
* Testing: Testing<52>.
* Terminology::
* Defining option objects::
* Validating option definitions::
* Example option objects::
* Parsing command-line arguments::
* Generating help text::
* Help options::
* Parse options::
* Notes and tips::

core

* API documentation: API documentation<57>.
* Loading: Loading<58>.
* Testing: Testing<53>.

copeland_ranker

* API documentation: API documentation<58>.
* Loading: Loading<59>.
* Testing: Testing<54>.
* Features: Features<11>.
* Scoring semantics: Scoring semantics<3>.
* Usage: Usage<23>.
* Diagnostics syntax: Diagnostics syntax<5>.
* Options: Options<10>.
* Ranker representation: Ranker representation<4>.
* References: References<8>.

Usage

* Learning a ranker: Learning a ranker<4>.
* Inspecting diagnostics: Inspecting diagnostics<4>.
* Ranking candidate items: Ranking candidate items<4>.
* Exporting the ranker: Exporting the ranker<4>.

coroutining

* API documentation: API documentation<59>.
* Loading: Loading<60>.
* Testing: Testing<55>.
* Usage: Usage<24>.

crypto

* API documentation: API documentation<60>.
* Loading: Loading<61>.
* Testing: Testing<56>.
* Examples: Examples<167>.

crs_projections

* API documentation: API documentation<61>.
* Loading: Loading<62>.
* Testing: Testing<57>.
* Supported coordinate reference systems::
* Usage: Usage<25>.
* Notes::

csv

* API documentation: API documentation<62>.
* Loading: Loading<63>.
* Testing: Testing<58>.
* Usage: Usage<26>.

cuid2

* API documentation: API documentation<63>.
* Loading: Loading<64>.
* Testing: Testing<59>.
* Usage: Usage<27>.

cusum_anomaly_detector

* API documentation: API documentation<64>.
* Loading: Loading<65>.
* Testing: Testing<60>.
* Features: Features<12>.
* Options: Options<11>.
* Detector representation::
* Notes: Notes<2>.

datalog

* API documentation: API documentation<65>.
* Loading: Loading<66>.
* Testing: Testing<61>.
* Scope: Scope<3>.
* Public API overview::
* Basic usage::
* Limitations: Limitations<3>.

dates

* API documentation: API documentation<66>.
* Loading: Loading<67>.
* Testing: Testing<62>.

dates_tz

* API documentation: API documentation<67>.
* Loading: Loading<68>.
* Testing: Testing<63>.
* Usage: Usage<28>.
* Examples: Examples<168>.
* Notes: Notes<3>.

dbscan_clusterer

* API documentation: API documentation<68>.
* Loading: Loading<69>.
* Testing: Testing<64>.
* Features: Features<13>.
* Options: Options<12>.
* Clusterer representation: Clusterer representation<2>.
* References: References<9>.

dependents

* API documentation: API documentation<69>.
* Loading: Loading<70>.

deques

* API documentation: API documentation<70>.
* Loading: Loading<71>.
* Testing: Testing<65>.
* Usage: Usage<29>.

derangements

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

dictionaries

* API documentation: API documentation<72>.
* Loading: Loading<73>.
* Testing: Testing<67>.
* Usage: Usage<30>.
* Credits: Credits<2>.

dif

* API documentation: API documentation<73>.
* Loading: Loading<74>.
* Testing: Testing<68>.
* Usage: Usage<31>.

dimension_reduction_protocols

* API documentation: API documentation<74>.
* Loading: Loading<75>.
* Common options::
* Testing: Testing<69>.
* Test datasets: Test datasets<4>.

eclat_pattern_miner

* API documentation: API documentation<75>.
* Loading: Loading<76>.
* Testing: Testing<70>.
* Features: Features<14>.
* Options: Options<13>.
* Pattern miner representation: Pattern miner representation<3>.
* References: References<10>.

edcg

* API documentation: API documentation<76>.
* Loading: Loading<77>.
* Testing: Testing<71>.
* Usage: Usage<32>.
* Introduction::
* Syntax::
* Declaration of Predicates::
* Declaration of Accumulators::
* Declaration of Passed Arguments::
* Additional documentation::

elastic_net_regression

* API documentation: API documentation<77>.
* Loading: Loading<78>.
* Testing: Testing<72>.
* Features: Features<15>.
* Regressor representation: Regressor representation<2>.
* Diagnostics syntax: Diagnostics syntax<6>.
* Options: Options<14>.

elo_ranker

* API documentation: API documentation<78>.
* Loading: Loading<79>.
* Testing: Testing<73>.
* Features: Features<16>.
* Rating semantics::
* Usage: Usage<33>.
* Options: Options<15>.
* Ranker representation: Ranker representation<5>.
* References: References<11>.

Usage

* Learning a ranker: Learning a ranker<5>.
* Inspecting diagnostics: Inspecting diagnostics<5>.
* Ranking candidate items: Ranking candidate items<5>.
* Exporting the ranker: Exporting the ranker<5>.

events

* API documentation: API documentation<79>.
* Loading: Loading<80>.

ewma_anomaly_detector

* API documentation: API documentation<80>.
* Loading: Loading<81>.
* Testing: Testing<74>.
* Features: Features<17>.
* Options: Options<16>.
* Detector representation: Detector representation<2>.
* Notes: Notes<4>.

expand_library_alias_paths

* API documentation: API documentation<81>.
* Loading: Loading<82>.
* Usage: Usage<34>.

expecteds

* API documentation: API documentation<82>.
* Loading: Loading<83>.
* Testing: Testing<75>.
* Usage: Usage<35>.
* See also::

format

* API documentation: API documentation<83>.
* Loading: Loading<84>.
* Testing: Testing<76>.
* Usage: Usage<36>.
* Portability: Portability<2>.

fp_growth_pattern_miner

* API documentation: API documentation<84>.
* Loading: Loading<85>.
* Testing: Testing<77>.
* Features: Features<18>.
* Options: Options<17>.
* Pattern miner representation: Pattern miner representation<4>.
* References: References<12>.

frequent_pattern_mining_protocols

* API documentation: API documentation<85>.
* Loading: Loading<86>.
* Testing: Testing<78>.
* Test datasets: Test datasets<5>.

gaussian_mixture_clusterer

* API documentation: API documentation<86>.
* Loading: Loading<87>.
* Testing: Testing<79>.
* Features: Features<19>.
* Gaussian-Mixture-Specific Prediction API::
* Options: Options<18>.
* Clusterer representation: Clusterer representation<3>.

gaussian_process_regression

* API documentation: API documentation<87>.
* Loading: Loading<88>.
* Testing: Testing<80>.
* Features: Features<20>.
* Regressor representation: Regressor representation<3>.
* Prediction API::
* Diagnostics syntax: Diagnostics syntax<7>.
* Options: Options<19>.

genint

* API documentation: API documentation<88>.
* Loading: Loading<89>.
* Testing: Testing<81>.
* Usage: Usage<37>.

gensym

* API documentation: API documentation<89>.
* Loading: Loading<90>.
* Testing: Testing<82>.
* Usage: Usage<38>.

geojson

* API documentation: API documentation<90>.
* Loading: Loading<91>.
* Testing: Testing<83>.
* Representation: Representation<10>.
* Examples: Examples<169>.
* Notes: Notes<5>.

geospatial

* API documentation: API documentation<91>.
* Loading: Loading<92>.
* Testing: Testing<84>.
* Available predicates::
* Notes: Notes<6>.
* Usage: Usage<39>.

git

* API documentation: API documentation<92>.
* Loading: Loading<93>.
* Testing: Testing<85>.
* Usage: Usage<40>.

glicko2_ranker

* API documentation: API documentation<93>.
* Loading: Loading<94>.
* Testing: Testing<86>.
* Features: Features<21>.
* Rating semantics: Rating semantics<2>.
* Usage: Usage<41>.
* Options: Options<20>.
* Diagnostics syntax: Diagnostics syntax<8>.
* Ranker representation: Ranker representation<6>.
* References: References<13>.

Usage

* Learning a ranker: Learning a ranker<6>.
* Inspecting diagnostics: Inspecting diagnostics<6>.
* Ranking candidate items: Ranking candidate items<6>.
* Exporting the ranker: Exporting the ranker<6>.

glicko2_periodic_ranker

* API documentation: API documentation<94>.
* Loading: Loading<95>.
* Testing: Testing<87>.
* Features: Features<22>.
* Rating semantics: Rating semantics<3>.
* Usage: Usage<42>.
* Options: Options<21>.
* Diagnostics syntax: Diagnostics syntax<9>.
* Ranker representation: Ranker representation<7>.
* References: References<14>.

Usage

* Learning a ranker: Learning a ranker<7>.
* Inspecting diagnostics: Inspecting diagnostics<7>.
* Ranking candidate items: Ranking candidate items<7>.
* Exporting the ranker: Exporting the ranker<7>.

gradient_boosting_classifier

* API documentation: API documentation<95>.
* Loading: Loading<96>.
* Testing: Testing<88>.
* Features: Features<23>.
* Options: Options<22>.
* Usage: Usage<43>.
* Classifier representation: Classifier representation<2>.
* References: References<15>.

Usage

* Learning a classifier::
* Making predictions::
* Exporting the classifier::

gradient_boosting_regression

* API documentation: API documentation<96>.
* Loading: Loading<97>.
* Testing: Testing<89>.
* Features: Features<24>.
* Regressor representation: Regressor representation<4>.
* Diagnostics syntax: Diagnostics syntax<10>.
* Options: Options<23>.

grammars

* API documentation: API documentation<97>.
* Loading: Loading<98>.
* Testing: Testing<90>.
* Usage: Usage<44>.

graphs

* API documentation: API documentation<98>.
* Loading: Loading<99>.
* Testing: Testing<91>.
* Usage: Usage<45>.

Usage

* Graph types::
* Creating graphs::
* Querying graphs::
* Undirected graphs::

gravatar

* API documentation: API documentation<99>.
* Loading: Loading<100>.
* Testing: Testing<92>.
* Basic usage: Basic usage<2>.

gsp_pattern_miner

* API documentation: API documentation<100>.
* Loading: Loading<101>.
* Testing: Testing<93>.
* Features: Features<25>.
* Options: Options<24>.
* Pattern miner representation: Pattern miner representation<5>.
* References: References<16>.

hashes

* API documentation: API documentation<101>.
* Loading: Loading<102>.
* Testing: Testing<94>.
* Supported hash algorithms::
* HMAC compatibility::
* Segmented hashing::
* Examples: Examples<170>.

hdbscan_clusterer

* API documentation: API documentation<102>.
* Loading: Loading<103>.
* Testing: Testing<95>.
* Features: Features<26>.
* Options: Options<25>.
* Clusterer representation: Clusterer representation<4>.

heaps

* API documentation: API documentation<103>.
* Loading: Loading<104>.
* Testing: Testing<96>.
* Usage: Usage<46>.
* Credits: Credits<3>.

hierarchical_clustering

* API documentation: API documentation<104>.
* Loading: Loading<105>.
* Testing: Testing<97>.
* Features: Features<27>.
* Options: Options<26>.
* Clusterer representation: Clusterer representation<5>.
* Additional API::
* Diagnostics: Diagnostics<3>.

hierarchies

* API documentation: API documentation<105>.
* Loading: Loading<106>.
* Testing: Testing<98>.

hmac

* API documentation: API documentation<106>.
* Loading: Loading<107>.
* Testing: Testing<99>.
* Examples: Examples<171>.

hodge_rank

* API documentation: API documentation<107>.
* Loading: Loading<108>.
* Testing: Testing<100>.
* Features: Features<28>.
* Scoring semantics: Scoring semantics<4>.
* Residual semantics::
* Usage: Usage<47>.
* Diagnostics syntax: Diagnostics syntax<11>.
* Ranker representation: Ranker representation<8>.
* References: References<17>.

Usage

* Learning a ranker: Learning a ranker<8>.
* Inspecting residuals::

hook_flows

* API documentation: API documentation<108>.
* Loading: Loading<109>.
* Testing: Testing<101>.
* Usage: Usage<48>.

hook_objects

* API documentation: API documentation<109>.
* Loading: Loading<110>.
* Testing: Testing<102>.
* Usage: Usage<49>.

Usage

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

html

* API documentation: API documentation<110>.
* Loading: Loading<111>.
* Testing: Testing<103>.
* Generating a HTML document::
* Generating a HTML fragment::
* Working with callbacks to generate content::
* Working with resource declarations::
* Aggregating and ordering resources::
* Working with custom elements::

http_authenticate

* API documentation: API documentation<111>.
* Loading: Loading<112>.
* Testing: Testing<104>.
* Usage overview::
* Current scope::
* Option validation::
* Non-implemented features::

http_client

* API documentation: API documentation<112>.
* Loading: Loading<113>.
* Testing: Testing<105>.
* Usage examples::
* Current scope: Current scope<2>.
* Multipart workflow::
* WebSocket workflow::
* Current limitations: Current limitations<2>.

http_client_core

* API documentation: API documentation<113>.
* Loading: Loading<114>.
* Testing: Testing<106>.
* Current scope: Current scope<3>.
* Framing rules::
* Current limitations: Current limitations<3>.

http_cookies

* API documentation: API documentation<114>.
* Loading: Loading<115>.
* Testing: Testing<107>.
* Usage: Usage<50>.

http_core

* API documentation: API documentation<115>.
* Loading: Loading<116>.
* Testing: Testing<108>.
* Layering::
* Current scope: Current scope<4>.
* Normalized terms::
* Current limitations: Current limitations<4>.

http_cors

* API documentation: API documentation<116>.
* Loading: Loading<117>.
* Testing: Testing<109>.
* Current scope: Current scope<5>.
* Route-level overrides::
* Router integration::
* Plain handler integration::
* Current limitations: Current limitations<5>.

http_digest

* API documentation: API documentation<117>.
* Loading: Loading<118>.
* Testing: Testing<110>.
* Usage overview: Usage overview<2>.
* Current scope: Current scope<6>.
* Non-implemented features: Non-implemented features<2>.

http_directory_listing

* API documentation: API documentation<118>.
* Loading: Loading<119>.
* Testing: Testing<111>.
* Current scope: Current scope<7>.

http_htmx

* API documentation: API documentation<119>.
* Loading: Loading<120>.
* Testing: Testing<112>.
* Current scope: Current scope<8>.

http_multipart

* API documentation: API documentation<120>.
* Loading: Loading<121>.
* Testing: Testing<113>.
* Current scope: Current scope<9>.
* Form-data descriptors::
* Normalized terms: Normalized terms<2>.
* Current workflow::
* Current limitations: Current limitations<6>.

http_parameters

* API documentation: API documentation<121>.
* Loading: Loading<122>.
* Testing: Testing<114>.
* Declarations::
* Error handling: Error handling<3>.
* Router integration: Router integration<2>.

http_router

* API documentation: API documentation<122>.
* Loading: Loading<123>.
* Testing: Testing<115>.
* Layering: Layering<2>.
* Current scope: Current scope<10>.
* Route declarations::
* Path templates::
* Request annotations::
* Route metadata::
* Route authorization::
* Content negotiation::
* Middleware chaining::
* Response middleware::
* HEAD fallback::
* OPTIONS handling::
* Custom bad-request responses::
* Custom error responses::
* Custom negotiation failures::
* OpenAPI derivation::
* Current limitations: Current limitations<7>.

http_server

* API documentation: API documentation<123>.
* Loading: Loading<124>.
* Testing: Testing<116>.
* Bounded serving::
* Open-ended serving::
* HTTPS::
* Handling server requests::
* Options: Options<27>.

http_server_core

* API documentation: API documentation<124>.
* Loading: Loading<125>.
* Testing: Testing<117>.
* Usage examples: Usage examples<2>.
* Current scope: Current scope<11>.
* Framing rules: Framing rules<2>.
* Multipart workflow: Multipart workflow<2>.
* WebSocket handshake workflow::
* Current limitations: Current limitations<8>.

http_session

* API documentation: API documentation<125>.
* Loading: Loading<126>.
* Testing: Testing<118>.
* Usage overview: Usage overview<3>.
* Current scope: Current scope<12>.
* Current limitations: Current limitations<9>.

http_socket_transport

* API documentation: API documentation<126>.
* Loading: Loading<127>.
* Testing: Testing<119>.
* Current scope: Current scope<13>.
* WebSocket handshake workflow: WebSocket handshake workflow<2>.
* Current limitations: Current limitations<10>.

http_process_transport

* Requirements: Requirements<6>.
* API documentation: API documentation<127>.
* Loading: Loading<128>.
* Testing: Testing<120>.
* Current scope: Current scope<14>.
* Current limitations: Current limitations<11>.
* Live smoke tests::

http_static_files

* API documentation: API documentation<128>.
* Loading: Loading<129>.
* Testing: Testing<121>.
* Current scope: Current scope<15>.

http_websocket

* API documentation: API documentation<129>.
* Loading: Loading<130>.
* Testing: Testing<122>.
* Current scope: Current scope<16>.
* Current workflow: Current workflow<2>.
* Lower-level layers::

http_websocket_frames

* API documentation: API documentation<130>.
* Loading: Loading<131>.
* Testing: Testing<123>.
* Current scope: Current scope<17>.
* Normalized terms: Normalized terms<3>.
* Valid properties::
* Current workflow: Current workflow<3>.
* Current limitations: Current limitations<12>.

http_websocket_handshake

* API documentation: API documentation<131>.
* Loading: Loading<132>.
* Testing: Testing<124>.
* Current scope: Current scope<18>.
* Current workflow: Current workflow<4>.

http_websocket_messages

* API documentation: API documentation<132>.
* Loading: Loading<133>.
* Testing: Testing<125>.
* Current scope: Current scope<19>.
* Normalized terms: Normalized terms<4>.
* Current workflow: Current workflow<5>.
* Current limitations: Current limitations<13>.

http_websocket_service

* API documentation: API documentation<133>.
* Loading: Loading<134>.
* Testing: Testing<126>.
* Current scope: Current scope<20>.
* Higher-level session loop::
* Registry-backed server helper::
* Backends without thread support::
* Current workflow: Current workflow<6>.
* Current limitations: Current limitations<14>.

http_websocket_session

* API documentation: API documentation<134>.
* Loading: Loading<135>.
* Testing: Testing<127>.
* Current scope: Current scope<21>.
* Role-aware objects::
* Stateful reads::
* Automatic control handling::
* Outgoing fragmentation::
* Current workflow: Current workflow<7>.
* Current limitations: Current limitations<15>.

ica_projection

* API documentation: API documentation<135>.
* Loading: Loading<136>.
* Testing: Testing<128>.
* Features: Features<29>.
* Options: Options<28>.
* Usage: Usage<51>.
* Dimension reducer representation::
* References: References<18>.

Usage

* Learning a reducer::
* Transforming new instances::
* Exporting and reusing the reducer::

ids

* API documentation: API documentation<136>.
* Loading: Loading<137>.
* Testing: Testing<129>.
* Usage: Usage<52>.

ieee_754

* Loading: Loading<138>.
* Testing: Testing<130>.
* Object model::
* Value representation::
* Public API: Public API<2>.
* Semantics::

intervals

* Practical limits::
* API documentation: API documentation<137>.
* Loading: Loading<139>.
* Testing: Testing<131>.
* Examples: Examples<172>.

iqr_anomaly_detector

* API documentation: API documentation<138>.
* Loading: Loading<140>.
* Testing: Testing<132>.
* Features: Features<30>.
* Options: Options<29>.
* Detector representation: Detector representation<3>.
* Notes: Notes<7>.

iso_639

* API documentation: API documentation<139>.
* Loading: Loading<141>.
* Testing: Testing<133>.

iso_3166

* API documentation: API documentation<140>.
* Loading: Loading<142>.
* Testing: Testing<134>.

iso_4217

* API documentation: API documentation<141>.
* Loading: Loading<143>.
* Testing: Testing<135>.

iso_9362

* API documentation: API documentation<142>.
* Loading: Loading<144>.
* Testing: Testing<136>.

iso_13616

* API documentation: API documentation<143>.
* Loading: Loading<145>.
* Testing: Testing<137>.

isolation_forest_anomaly_detector

* API documentation: API documentation<144>.
* Loading: Loading<146>.
* Testing: Testing<138>.
* Implemented features: Implemented features<2>.
* Options: Options<30>.
* Detector representation: Detector representation<4>.
* Limitations: Limitations<4>.
* References: References<19>.
* Usage: Usage<53>.

java

* API documentation: API documentation<145>.
* Loading: Loading<147>.
* Testing: Testing<139>.
* Usage: Usage<54>.
* Known issues: Known issues<11>.

json

* API documentation: API documentation<146>.
* Loading: Loading<148>.
* Testing: Testing<140>.
* Representation: Representation<11>.
* Encoding: Encoding<7>.
* Decoding: Decoding<7>.
* Known issues: Known issues<12>.

json_graph

* API documentation: API documentation<147>.
* Loading: Loading<149>.
* Testing: Testing<141>.
* Usage: Usage<55>.
* Roundtrip and fixture coverage::

json_ld

* API documentation: API documentation<148>.
* Loading: Loading<150>.
* Testing: Testing<142>.
* Parsing: Parsing<2>.
* Generating: Generating<2>.
* Expansion::
* Compaction::
* Flattening::
* Framing::
* Implemented Features::
* Known Limitations::
* Representation: Representation<12>.

json_lines

* API documentation: API documentation<149>.
* Loading: Loading<151>.
* Testing: Testing<143>.
* Representation: Representation<13>.
* Encoding: Encoding<8>.
* Decoding: Decoding<8>.
* Known issues: Known issues<13>.

json_patch

* API documentation: API documentation<150>.
* Loading: Loading<152>.
* Testing: Testing<144>.
* Representation: Representation<14>.
* Patch document structure::
* Valid operations::
* Path rules::
* Representation notes::
* Failure and errors::

json_path

* Current implementation status::
* API documentation: API documentation<151>.
* Loading: Loading<153>.
* Testing: Testing<145>.
* Representation: Representation<15>.
* Examples: Examples<173>.

json_pointer

* API documentation: API documentation<152>.
* Loading: Loading<154>.
* Testing: Testing<146>.
* Representation: Representation<16>.
* Examples: Examples<174>.

json_rpc

* API documentation: API documentation<153>.
* Loading: Loading<155>.
* Testing: Testing<147>.
* Usage: Usage<56>.
* API summary::

Usage

* Constructing JSON-RPC 2.0 messages: Constructing JSON-RPC 2 0 messages.
* Standard error constructors::
* Encoding and decoding::
* Message classification::
* Field extraction::
* Stream I/O (client and server API): Stream I/O client and server API.
* Content-Length framed I/O (LSP/MCP protocols): Content-Length framed I/O LSP/MCP protocols.

API summary

* Message construction::
* Standard error responses::
* Encoding and decoding: Encoding and decoding<2>.
* Message classification: Message classification<2>.
* Field extraction: Field extraction<2>.
* Stream I/O::

json_schema

* API documentation: API documentation<154>.
* Loading: Loading<156>.
* Testing: Testing<148>.
* Schema Parsing::
* Validation::
* Supported Keywords::
* Known Limitations: Known Limitations<2>.

jwt

* Requirements: Requirements<7>.
* API documentation: API documentation<155>.
* Loading: Loading<157>.
* Testing: Testing<149>.
* Options: Options<31>.
* Validation policy::
* Basic usage: Basic usage<3>.

kcenters_clusterer

* API documentation: API documentation<156>.
* Loading: Loading<158>.
* Testing: Testing<150>.
* Features: Features<31>.
* Options: Options<32>.
* Diagnostics: Diagnostics<4>.
* Clusterer representation: Clusterer representation<6>.
* References: References<20>.

kemeny_young_ranker

* API documentation: API documentation<157>.
* Loading: Loading<159>.
* Testing: Testing<151>.
* Features: Features<32>.
* Usage: Usage<57>.
* Options: Options<33>.
* Scoring semantics: Scoring semantics<5>.
* Diagnostics syntax: Diagnostics syntax<12>.
* Ranker representation: Ranker representation<9>.
* Notes: Notes<8>.
* References: References<21>.

Usage

* Learning a ranker: Learning a ranker<9>.
* Inspecting the learned consensus::
* Ranking candidate items: Ranking candidate items<8>.

kernel_svm_classifier

* API documentation: API documentation<158>.
* Loading: Loading<160>.
* Testing: Testing<152>.
* Features: Features<33>.
* Options: Options<34>.
* Usage: Usage<58>.
* Classifier representation: Classifier representation<3>.
* References: References<22>.

Usage

* Learning a classifier: Learning a classifier<2>.
* Making predictions: Making predictions<2>.
* Exporting the classifier: Exporting the classifier<2>.

kernel_pca_projection

* API documentation: API documentation<159>.
* Loading: Loading<161>.
* Testing: Testing<153>.
* Features: Features<34>.
* Options: Options<35>.
* Usage: Usage<59>.
* Dimension reducer representation: Dimension reducer representation<2>.
* References: References<23>.

Usage

* Learning a reducer: Learning a reducer<2>.
* Transforming new instances: Transforming new instances<2>.
* Exporting and reusing the reducer: Exporting and reusing the reducer<2>.

kmeans_clusterer

* API documentation: API documentation<160>.
* Loading: Loading<162>.
* Testing: Testing<154>.
* Features: Features<35>.
* Options: Options<36>.
* Diagnostics: Diagnostics<5>.
* Clusterer representation: Clusterer representation<7>.
* References: References<24>.

kmedians_clusterer

* API documentation: API documentation<161>.
* Loading: Loading<163>.
* Testing: Testing<155>.
* Features: Features<36>.
* Options: Options<37>.
* Diagnostics: Diagnostics<6>.
* Clusterer representation: Clusterer representation<8>.
* References: References<25>.

kmedoids_clusterer

* API documentation: API documentation<162>.
* Loading: Loading<164>.
* Testing: Testing<156>.
* Features: Features<37>.
* Options: Options<38>.
* Diagnostics: Diagnostics<7>.
* Clusterer representation: Clusterer representation<9>.
* References: References<26>.

kmodes_clusterer

* API documentation: API documentation<163>.
* Loading: Loading<165>.
* Testing: Testing<157>.
* Features: Features<38>.
* Options: Options<39>.
* Diagnostics: Diagnostics<8>.
* Clusterer representation: Clusterer representation<10>.
* References: References<27>.

knn_classifier

* API documentation: API documentation<164>.
* Loading: Loading<166>.
* Testing: Testing<158>.
* Features: Features<39>.
* Usage: Usage<60>.
* Options: Options<40>.
* Classifier representation: Classifier representation<4>.
* References: References<28>.

Usage

* Learning a Classifier: Learning a Classifier<2>.
* Making Predictions: Making Predictions<2>.
* Exporting the Classifier: Exporting the Classifier<2>.
* Using a learned classifier::

knn_distance_anomaly_detector

* API documentation: API documentation<165>.
* Loading: Loading<167>.
* Testing: Testing<159>.
* Features: Features<40>.
* Options: Options<41>.
* Detector representation: Detector representation<5>.
* References: References<29>.

knn_regression

* API documentation: API documentation<166>.
* Loading: Loading<168>.
* Testing: Testing<160>.
* Features: Features<41>.
* Regressor representation: Regressor representation<5>.
* Diagnostics syntax: Diagnostics syntax<13>.
* Options: Options<42>.

kprototypes_clusterer

* API documentation: API documentation<167>.
* Loading: Loading<169>.
* Testing: Testing<161>.
* Features: Features<42>.
* Options: Options<43>.
* Distance Function::
* Clusterer representation: Clusterer representation<11>.
* References: References<30>.

ksuid

* API documentation: API documentation<168>.
* Loading: Loading<170>.
* Testing: Testing<162>.
* Usage: Usage<61>.

lasso_regression

* API documentation: API documentation<169>.
* Loading: Loading<171>.
* Testing: Testing<163>.
* Features: Features<43>.
* Regressor representation: Regressor representation<6>.
* Diagnostics syntax: Diagnostics syntax<14>.
* Options: Options<44>.

lda_classifier

* API documentation: API documentation<170>.
* Loading: Loading<172>.
* Testing: Testing<164>.
* Features: Features<44>.
* Options: Options<45>.
* Usage: Usage<62>.
* Classifier representation: Classifier representation<5>.
* References: References<31>.

Usage

* Learning a classifier: Learning a classifier<3>.
* Making predictions: Making predictions<3>.
* Exporting the classifier: Exporting the classifier<3>.

lda_projection

* API documentation: API documentation<171>.
* Loading: Loading<173>.
* Testing: Testing<165>.
* Features: Features<45>.
* Options: Options<46>.
* Usage: Usage<63>.
* Dimension reducer representation: Dimension reducer representation<3>.
* References: References<32>.

Usage

* Learning a reducer: Learning a reducer<3>.
* Transforming new instances: Transforming new instances<3>.
* Exporting and reusing the reducer: Exporting and reusing the reducer<3>.

linda

* API documentation: API documentation<172>.
* Loading: Loading<174>.
* Testing: Testing<166>.
* Usage: Usage<64>.
* Examples: Examples<175>.
* API Summary::
* Known issues: Known issues<14>.
* See also: See also<2>.

Usage

* Starting a server::
* Connecting a client::
* Tuple operations::
* Disconnecting::
* Timeout control::

Examples

* Producer-Consumer::
* Critical Region::
* Synchronization::

API Summary

* Server predicates::
* Client predicates::
* Tuple predicates (single/default server): Tuple predicates single/default server.
* Tuple predicates (multiple servers): Tuple predicates multiple servers.

linear_algebra

* API documentation: API documentation<173>.
* Loading: Loading<175>.
* Testing: Testing<167>.

linear_regression

* API documentation: API documentation<174>.
* Loading: Loading<176>.
* Testing: Testing<168>.
* Features: Features<46>.
* Regressor representation: Regressor representation<7>.
* Diagnostics syntax: Diagnostics syntax<15>.
* Options: Options<47>.

linear_svm_classifier

* API documentation: API documentation<175>.
* Loading: Loading<177>.
* Testing: Testing<169>.
* Features: Features<47>.
* Options: Options<48>.
* Usage: Usage<65>.
* Classifier representation: Classifier representation<6>.
* References: References<33>.

Usage

* Learning a classifier: Learning a classifier<4>.
* Making predictions: Making predictions<4>.
* Exporting the classifier: Exporting the classifier<4>.

listing

* API documentation: API documentation<176>.
* Loading: Loading<178>.
* Testing: Testing<170>.
* Usage: Usage<66>.

lof_anomaly_detector

* API documentation: API documentation<177>.
* Loading: Loading<179>.
* Testing: Testing<171>.
* Features: Features<48>.
* Options: Options<49>.
* Detector representation: Detector representation<6>.
* References: References<34>.

logging

* API documentation: API documentation<178>.
* Loading: Loading<180>.

logistic_regression_classifier

* API documentation: API documentation<179>.
* Loading: Loading<181>.
* Testing: Testing<172>.
* Features: Features<49>.
* Options: Options<50>.
* Usage: Usage<67>.
* Classifier representation: Classifier representation<7>.
* References: References<35>.

Usage

* Learning a classifier: Learning a classifier<5>.
* Making predictions: Making predictions<5>.
* Exporting the classifier: Exporting the classifier<5>.

loops

* API documentation: API documentation<180>.
* Loading: Loading<182>.
* Testing: Testing<173>.
* Usage: Usage<68>.

massey_ranker

* API documentation: API documentation<181>.
* Loading: Loading<183>.
* Testing: Testing<174>.
* Features: Features<50>.
* Scoring semantics: Scoring semantics<6>.
* Usage: Usage<69>.
* Diagnostics syntax: Diagnostics syntax<16>.
* Ranker representation: Ranker representation<10>.
* References: References<36>.

Usage

* Learning a ranker: Learning a ranker<10>.
* Inspecting diagnostics: Inspecting diagnostics<8>.
* Ranking candidate items: Ranking candidate items<9>.
* Exporting the ranker: Exporting the ranker<8>.

mcp_server

* API documentation: API documentation<182>.
* Loading: Loading<184>.
* Testing: Testing<175>.
* Usage: Usage<70>.
* Error handling: Error handling<4>.
* Protocol::
* Supported MCP methods::

Usage

* Implementing the tool protocol::
* Auto-dispatch vs. custom tool_call/3: Auto-dispatch vs custom tool_call/3.
* Output schemas (structured tool output): Output schemas structured tool output.
* Starting the server for debugging::
* MCP client configuration::
* Elicitation (interactive tools): Elicitation interactive tools.
* Prompts (prompt templates): Prompts prompt templates.
* Resources (data exposure): Resources data exposure.

memcached

* API documentation: API documentation<183>.
* Loading: Loading<185>.
* Testing: Testing<176>.
* Protocol Version::
* Features: Features<51>.
* Usage: Usage<71>.
* API Summary: API Summary<2>.
* Error Handling: Error Handling<2>.
* Key Format::
* Expiration Times::

Usage

* Connecting to a Memcached server::
* Storing data::
* Retrieving data::
* Check-and-Set (CAS): Check-and-Set CAS.
* Deleting data::
* Increment/Decrement::
* Touch and Get-and-Touch::
* Server management::
* Disconnecting: Disconnecting<2>.

API Summary

* Connection management::
* Storage commands::
* Retrieval commands::
* Deletion::
* Increment/Decrement: Increment/Decrement<2>.
* Touch::
* Server commands::

message_pack

* API documentation: API documentation<184>.
* Loading: Loading<186>.
* Testing: Testing<177>.
* Representation: Representation<17>.
* Notes: Notes<9>.

meta

* API documentation: API documentation<185>.
* Loading: Loading<187>.
* Testing: Testing<178>.
* Usage: Usage<72>.

meta_compiler

* API documentation: API documentation<186>.
* Loading: Loading<188>.
* Testing: Testing<179>.
* Usage: Usage<73>.
* Known issues: Known issues<15>.

mime_types

* API documentation: API documentation<187>.
* Loading: Loading<189>.
* Testing: Testing<180>.
* Usage: Usage<74>.

modified_z_score_anomaly_detector

* API documentation: API documentation<188>.
* Loading: Loading<190>.
* Testing: Testing<181>.
* Features: Features<52>.
* Options: Options<51>.
* Detector representation: Detector representation<7>.
* Notes: Notes<10>.

mutations

* API documentation: API documentation<189>.
* Loading: Loading<191>.
* Testing: Testing<182>.
* Usage: Usage<75>.

multisets

* API documentation: API documentation<190>.
* Loading: Loading<192>.
* Testing: Testing<183>.

nanoid

* API documentation: API documentation<191>.
* Loading: Loading<193>.
* Testing: Testing<184>.
* Usage: Usage<76>.

naive_bayes_classifier

* API documentation: API documentation<192>.
* Loading: Loading<194>.
* Testing: Testing<185>.
* Features: Features<53>.
* Usage: Usage<77>.
* Classifier representation: Classifier representation<8>.
* References: References<37>.

Usage

* Learning a Classifier: Learning a Classifier<3>.
* Making Predictions: Making Predictions<3>.
* Exporting the Classifier: Exporting the Classifier<3>.
* Using a learned classifier: Using a learned classifier<2>.

nearest_centroid_classifier

* API documentation: API documentation<193>.
* Loading: Loading<195>.
* Testing: Testing<186>.
* Features: Features<54>.
* Usage: Usage<78>.
* Options: Options<52>.
* Classifier representation: Classifier representation<9>.
* References: References<38>.

Usage

* Learning a Classifier: Learning a Classifier<4>.
* Making Predictions: Making Predictions<4>.
* Exporting the Classifier: Exporting the Classifier<4>.
* Using a learned classifier: Using a learned classifier<3>.

nested_dictionaries

* API documentation: API documentation<194>.
* Loading: Loading<196>.
* Testing: Testing<187>.
* Usage: Usage<79>.
* Curly term representation::

nmea

* API documentation: API documentation<195>.
* Loading: Loading<197>.
* Testing: Testing<188>.
* Public API: Public API<3>.
* Raw Sentence Representation::
* Typed data/2 Results::
* Date Rule::
* Current Scope::

nmf_projection

* API documentation: API documentation<196>.
* Loading: Loading<198>.
* Testing: Testing<189>.
* Features: Features<55>.
* Options: Options<53>.
* Usage: Usage<80>.
* Dimension reducer representation: Dimension reducer representation<4>.
* References: References<39>.

open_api

* Layering: Layering<3>.
* API documentation: API documentation<197>.
* Loading: Loading<199>.
* Testing: Testing<190>.
* Current scope: Current scope<22>.
* Current limitations: Current limitations<16>.
* Provider descriptors::
* Usage: Usage<81>.

Provider descriptors

* API metadata::
* Server descriptors::
* Top-level security defaults::
* Operation descriptors::
* Reusable schemas::
* Reusable security schemes::

open_ai

* Loading: Loading<200>.
* Testing: Testing<191>.
* Current scope: Current scope<23>.
* Basic client usage::
* Basic server usage::

open_id

* Loading: Loading<201>.
* Testing: Testing<192>.
* Basic usage: Basic usage<4>.
* Current scope: Current scope<24>.
* Current limitations: Current limitations<17>.

optics_clusterer

* API documentation: API documentation<198>.
* Loading: Loading<202>.
* Testing: Testing<193>.
* Features: Features<56>.
* Options: Options<54>.
* Clusterer representation: Clusterer representation<12>.

optionals

* API documentation: API documentation<199>.
* Loading: Loading<203>.
* Testing: Testing<194>.
* Usage: Usage<82>.
* See also: See also<3>.

options

* API documentation: API documentation<200>.
* Loading: Loading<204>.
* Testing: Testing<195>.
* Usage: Usage<83>.

os

* API documentation: API documentation<201>.
* Loading: Loading<205>.
* Testing: Testing<196>.
* Known issues: Known issues<16>.

otp

* API documentation: API documentation<202>.
* Loading: Loading<206>.
* Testing: Testing<197>.
* Public predicates::
* Secrets::
* Generation::
* Verification::
* Hash support::
* Bounded-backend limitation::

partitions

* API documentation: API documentation<203>.
* Loading: Loading<207>.
* Testing: Testing<198>.

pattern_mining_protocols

* API documentation: API documentation<204>.
* Loading: Loading<208>.
* Testing: Testing<199>.
* Common options: Common options<2>.
* Diagnostics: Diagnostics<9>.
* Related support libraries::

pca_projection

* API documentation: API documentation<205>.
* Loading: Loading<209>.
* Testing: Testing<200>.
* Features: Features<57>.
* Options: Options<55>.
* Usage: Usage<84>.
* Dimension reducer representation: Dimension reducer representation<5>.
* References: References<40>.

Usage

* Learning a reducer: Learning a reducer<4>.
* Transforming new instances: Transforming new instances<4>.
* Exporting and reusing the reducer: Exporting and reusing the reducer<4>.

permutations

* API documentation: API documentation<206>.
* Loading: Loading<210>.
* Testing: Testing<201>.

plackett_luce_ranker

* API documentation: API documentation<207>.
* Loading: Loading<211>.
* Testing: Testing<202>.
* Features: Features<58>.
* Dataset requirements: Dataset requirements<2>.
* Usage: Usage<85>.
* Diagnostics syntax: Diagnostics syntax<17>.
* Options: Options<56>.
* Ranker representation: Ranker representation<11>.
* See also: See also<4>.

Usage

* Learning a ranker: Learning a ranker<11>.
* Inspecting diagnostics: Inspecting diagnostics<9>.

Diagnostics syntax

* Ranking candidate items: Ranking candidate items<10>.
* Exporting the ranker: Exporting the ranker<9>.

plackett_luce_last_ranker

* API documentation: API documentation<208>.
* Loading: Loading<212>.
* Testing: Testing<203>.
* Features: Features<59>.
* Dataset requirements: Dataset requirements<3>.
* Usage: Usage<86>.
* Diagnostics syntax: Diagnostics syntax<18>.
* Options: Options<57>.
* Ranker representation: Ranker representation<12>.
* See also: See also<5>.
* References: References<41>.

Usage

* Learning a ranker: Learning a ranker<12>.
* Inspecting diagnostics: Inspecting diagnostics<10>.

Diagnostics syntax

* Ranking candidate items: Ranking candidate items<11>.
* Exporting the ranker: Exporting the ranker<10>.

pls_projection

* API documentation: API documentation<209>.
* Loading: Loading<213>.
* Testing: Testing<204>.
* Features: Features<60>.
* Options: Options<58>.
* Usage: Usage<87>.
* Dimension reducer representation: Dimension reducer representation<6>.
* References: References<42>.

Usage

* Learning a reducer: Learning a reducer<5>.
* Transforming new instances: Transforming new instances<5>.
* Exporting and reusing the reducer: Exporting and reusing the reducer<5>.

prefix_span_pattern_miner

* API documentation: API documentation<210>.
* Loading: Loading<214>.
* Testing: Testing<205>.
* Features: Features<61>.
* Options: Options<59>.
* Pattern miner representation: Pattern miner representation<6>.
* References: References<43>.

probabilistic_pca_projection

* API documentation: API documentation<211>.
* Loading: Loading<215>.
* Testing: Testing<206>.
* Features: Features<62>.
* Options: Options<60>.
* Usage: Usage<88>.
* Dimension reducer representation: Dimension reducer representation<7>.
* References: References<44>.

Usage

* Learning a reducer: Learning a reducer<6>.
* Transforming new instances: Transforming new instances<6>.
* Exporting and reusing the reducer: Exporting and reusing the reducer<6>.

process

* API documentation: API documentation<212>.
* Loading: Loading<216>.
* Testing: Testing<207>.
* Usage: Usage<89>.

protobuf

* API documentation: API documentation<213>.
* Loading: Loading<217>.
* Testing: Testing<208>.
* Protocol Buffers Overview::
* Schema Representation::
* Data Representation::
* Encoding: Encoding<9>.
* Decoding: Decoding<9>.
* Wire Format Details::
* Binary Format Compatibility::
* Examples and Test Files::
* Further Reading::

Schema Representation

* Supported Types::
* Schema Examples: Schema Examples<2>.

Supported Types

* Scalar Value Types::
* Complex Types::

Encoding

* Simple Value Encoding::
* Message Encoding::
* Including Schema in Output::

Decoding

* Parsing with Schema Embedded::
* Parsing with Known Schema::
* Parsing from Different Sources::

Examples and Test Files

* person.proto: person proto.
* addressbook.proto: addressbook proto.
* Performance Considerations::

qda_classifier

* API documentation: API documentation<214>.
* Loading: Loading<218>.
* Testing: Testing<209>.
* Features: Features<63>.
* Options: Options<61>.
* Usage: Usage<90>.
* Classifier representation: Classifier representation<10>.
* References: References<45>.

Usage

* Learning a classifier: Learning a classifier<6>.
* Making predictions: Making predictions<6>.
* Exporting the classifier: Exporting the classifier<6>.

queues

* API documentation: API documentation<215>.
* Loading: Loading<219>.
* Testing: Testing<210>.
* Usage: Usage<91>.

random

* API documentation: API documentation<216>.
* Loading: Loading<220>.
* Testing: Testing<211>.
* Algorithms::
* Usage: Usage<92>.

random_forest_classifier

* API documentation: API documentation<217>.
* Loading: Loading<221>.
* Testing: Testing<212>.
* Features: Features<64>.
* Options: Options<62>.
* Classifier representation: Classifier representation<11>.
* References: References<46>.
* Usage: Usage<93>.

Usage

* Learning a Classifier: Learning a Classifier<5>.
* Making Predictions: Making Predictions<5>.
* Exporting the Classifier: Exporting the Classifier<5>.
* Using a Saved Classifier: Using a Saved Classifier<2>.
* Printing the Classifier: Printing the Classifier<2>.

random_forest_regression

* API documentation: API documentation<218>.
* Loading: Loading<222>.
* Testing: Testing<213>.
* Features: Features<65>.
* Regressor representation: Regressor representation<8>.
* Diagnostics syntax: Diagnostics syntax<19>.
* Options: Options<63>.

random_projection

* API documentation: API documentation<219>.
* Loading: Loading<223>.
* Testing: Testing<214>.
* Features: Features<66>.
* Options: Options<64>.
* Usage: Usage<94>.
* Dimension reducer representation: Dimension reducer representation<8>.
* References: References<47>.

Usage

* Learning a reducer: Learning a reducer<7>.
* Transforming new instances: Transforming new instances<7>.
* Exporting and reusing the reducer: Exporting and reusing the reducer<7>.

rank_centrality

* API documentation: API documentation<220>.
* Loading: Loading<224>.
* Testing: Testing<215>.
* Features: Features<67>.
* Dataset requirements: Dataset requirements<4>.
* Usage: Usage<95>.
* Diagnostics syntax: Diagnostics syntax<20>.
* Options: Options<65>.
* Ranker representation: Ranker representation<13>.
* References: References<48>.

Usage

* Learning a ranker: Learning a ranker<13>.
* Inspecting diagnostics: Inspecting diagnostics<11>.

Diagnostics syntax

* Ranking candidate items: Ranking candidate items<12>.
* Exporting the ranker: Exporting the ranker<11>.

ranked_pairs

* API documentation: API documentation<221>.
* Loading: Loading<225>.
* Testing: Testing<216>.
* Features: Features<68>.
* Usage: Usage<96>.
* Diagnostics syntax: Diagnostics syntax<21>.
* Options: Options<66>.
* Scoring semantics: Scoring semantics<7>.
* Ranker representation: Ranker representation<14>.
* See also: See also<6>.

Usage

* Learning a ranker: Learning a ranker<14>.
* Inspecting diagnostics: Inspecting diagnostics<12>.
* Ranking candidate items: Ranking candidate items<13>.
* Inspecting locked pairs::
* Exporting the ranker: Exporting the ranker<12>.

ranking_protocols

* Protocol requirements::
* Shared categories::
* Diagnostics: Diagnostics<10>.
* Export header format: Export header format<3>.
* API documentation: API documentation<222>.
* Loading: Loading<226>.
* Testing: Testing<217>.
* Test datasets: Test datasets<6>.

reader

* API documentation: API documentation<223>.
* Loading: Loading<227>.
* Testing: Testing<218>.

recorded_database

* API documentation: API documentation<224>.
* Loading: Loading<228>.
* Testing: Testing<219>.
* Usage: Usage<97>.
* Known issues: Known issues<17>.

redis

* API documentation: API documentation<225>.
* Loading: Loading<229>.
* Testing: Testing<220>.
* Supported Redis Features::
* Credits: Credits<4>.
* Known issues: Known issues<18>.

Supported Redis Features

* Connection Management::
* String Operations::
* Key Operations::
* Hash Operations::
* List Operations::
* Set Operations::
* Sorted Set Operations::
* Usage Examples::

regression_protocols

* API documentation: API documentation<226>.
* Loading: Loading<230>.
* Testing: Testing<221>.
* Test datasets: Test datasets<7>.

regression_tree

* API documentation: API documentation<227>.
* Loading: Loading<231>.
* Testing: Testing<222>.
* Export header format: Export header format<4>.
* Features: Features<69>.
* Regressor representation: Regressor representation<9>.
* Diagnostics syntax: Diagnostics syntax<22>.
* Options: Options<67>.

regularized_bradley_terry_ranker

* API documentation: API documentation<228>.
* Loading: Loading<232>.
* Testing: Testing<223>.
* Features: Features<70>.
* Dataset requirements: Dataset requirements<5>.
* Usage: Usage<98>.
* Diagnostics syntax: Diagnostics syntax<23>.
* Options: Options<68>.
* Ranker representation: Ranker representation<15>.
* References: References<49>.

Usage

* Learning a ranker: Learning a ranker<15>.
* Inspecting diagnostics: Inspecting diagnostics<13>.

Diagnostics syntax

* Ranking candidate items: Ranking candidate items<14>.
* Exporting the ranker: Exporting the ranker<13>.

rest

* Layering: Layering<4>.
* API documentation: API documentation<229>.
* Loading: Loading<233>.
* Testing: Testing<224>.
* Current scope: Current scope<25>.
* OpenAPI integration::
* Current limitations: Current limitations<18>.

ridge_regression

* API documentation: API documentation<230>.
* Loading: Loading<234>.
* Testing: Testing<225>.
* Features: Features<71>.
* Regressor representation: Regressor representation<10>.
* Diagnostics syntax: Diagnostics syntax<24>.
* Options: Options<69>.

s3

* API documentation: API documentation<231>.
* Loading: Loading<235>.
* Testing: Testing<226>.
* Current scope: Current scope<26>.
* Basic usage: Basic usage<5>.
* Current limitations: Current limitations<19>.

schulze_ranker

* API documentation: API documentation<232>.
* Loading: Loading<236>.
* Testing: Testing<227>.
* Features: Features<72>.
* Options: Options<70>.
* Strongest paths::
* Diagnostics syntax: Diagnostics syntax<25>.
* Ranker representation: Ranker representation<16>.

sequential_pattern_mining_protocols

* API documentation: API documentation<233>.
* Loading: Loading<237>.
* Testing: Testing<228>.
* Test datasets: Test datasets<8>.

sets

* API documentation: API documentation<234>.
* Loading: Loading<238>.
* Testing: Testing<229>.
* Usage: Usage<99>.
* Credits: Credits<5>.

sgd_classifier

* API documentation: API documentation<235>.
* Loading: Loading<239>.
* Testing: Testing<230>.
* Features: Features<73>.
* Options: Options<71>.
* Usage: Usage<100>.
* Classifier representation: Classifier representation<12>.
* References: References<50>.

Usage

* Learning a classifier: Learning a classifier<7>.
* Making predictions: Making predictions<7>.
* Exporting the classifier: Exporting the classifier<7>.

snowflakeid

* API documentation: API documentation<236>.
* Loading: Loading<240>.
* Testing: Testing<231>.
* Usage: Usage<101>.

sockets

* Design rationale::
* API documentation: API documentation<237>.
* Loading: Loading<241>.
* Testing: Testing<232>.
* Usage: Usage<102>.
* API Summary: API Summary<3>.
* Backend-specific notes::
* Known issues: Known issues<19>.

Usage

* Creating a client connection::
* Creating a server::
* Getting the current host name::

Backend-specific notes

* Stream representation::
* Binary and text modes::

spade_pattern_miner

* API documentation: API documentation<238>.
* Loading: Loading<242>.
* Testing: Testing<233>.
* Features: Features<74>.
* Options: Options<72>.
* Pattern miner representation: Pattern miner representation<7>.
* References: References<51>.

simulated_annealing

* API documentation: API documentation<239>.
* Loading: Loading<243>.
* Testing: Testing<234>.
* Features: Features<75>.
* Defining a problem::
* Options: Options<73>.
* Run statistics::
* Usage: Usage<103>.

Usage

* Defining a problem: Defining a problem<2>.
* Running the algorithm::
* Running with custom options::
* Running with statistics::
* Reproducible runs with seed::
* Reheating restarts::
* Auto-temperature estimation::
* Using a custom random number generator::

statistics

* API documentation: API documentation<240>.
* Loading: Loading<244>.
* Testing: Testing<235>.
* API overview::

API overview

* Aggregation::
* Extremes and Range::
* Central Tendency::
* Measures of Position / Quantiles::
* Measures of Dispersion::
* Measures of Shape::
* Measures of Association::
* Error Metrics::
* Normalization::
* Frequency / Counting::
* Validation: Validation<2>.

stemming

* API documentation: API documentation<241>.
* Loading: Loading<245>.
* Testing: Testing<236>.
* Usage: Usage<104>.
* Algorithms: Algorithms<2>.
* Choosing an Algorithm::
* Known Limitations: Known Limitations<3>.

Usage

* Porter Stemmer::
* Lovins Stemmer::

Algorithms

* Porter Stemmer: Porter Stemmer<2>.
* Lovins Stemmer: Lovins Stemmer<2>.

stomp

* Protocol Version: Protocol Version<2>.
* Features: Features<76>.
* API documentation: API documentation<242>.
* Loading: Loading<246>.
* Testing: Testing<237>.
* Usage: Usage<105>.
* API Summary: API Summary<4>.
* Connection Options::
* Send Options::
* Subscribe Options::
* Receive Options::
* Error Handling: Error Handling<3>.

Usage

* Connecting to a STOMP server::
* Sending messages::
* Subscribing to destinations::
* Receiving messages::
* Acknowledging messages::
* Unsubscribing::
* Transactions: Transactions<2>.
* Disconnecting: Disconnecting<3>.
* Heartbeat handling::
* Working with frames::

API Summary

* Connection management: Connection management<2>.
* Messaging::
* Acknowledgment::
* Transactions: Transactions<3>.
* Heartbeat::
* Frame inspection::

string_distance

* API documentation: API documentation<243>.
* Loading: Loading<247>.
* Testing: Testing<238>.
* Algorithms: Algorithms<3>.

strings

* API documentation: API documentation<244>.
* Loading: Loading<248>.
* Testing: Testing<239>.
* Predicates: Predicates<2>.

subsequences

* API documentation: API documentation<245>.
* Loading: Loading<249>.
* Testing: Testing<240>.

term_io

* API documentation: API documentation<246>.
* Loading: Loading<250>.
* Testing: Testing<241>.

thurstone_mosteller_ranker

* API documentation: API documentation<247>.
* Loading: Loading<251>.
* Testing: Testing<242>.
* Features: Features<77>.
* Scoring semantics: Scoring semantics<8>.
* Options: Options<74>.
* Diagnostics syntax: Diagnostics syntax<26>.
* Ranker representation: Ranker representation<17>.

time_scales

* API documentation: API documentation<248>.
* Loading: Loading<252>.
* Testing: Testing<243>.
* Features: Features<78>.
* Limitations: Limitations<5>.
* Representation: Representation<18>.
* Examples: Examples<176>.

timeout

* API documentation: API documentation<249>.
* Loading: Loading<253>.
* Testing: Testing<244>.
* Known issues: Known issues<20>.

tle_orbits

* API documentation: API documentation<250>.
* Loading: Loading<254>.
* Testing: Testing<245>.
* Representation: Representation<19>.
* Public API: Public API<4>.
* Examples: Examples<177>.
* Notes: Notes<11>.

toml

* API documentation: API documentation<251>.
* Loading: Loading<255>.
* Testing: Testing<246>.
* Status::
* Representation: Representation<20>.
* Examples: Examples<178>.
* Notes: Notes<12>.

Examples

* Parsing a TOML String::
* Parsing with Curly Table Representation::
* Generating TOML::

toon

* API documentation: API documentation<252>.
* Loading: Loading<256>.
* Testing: Testing<247>.
* Representation: Representation<21>.
* TOON format features::
* Usage examples: Usage examples<3>.

Representation

* Objects: Objects<2>.
* Arrays::
* Primitives::

truncated_svd_projection

* API documentation: API documentation<253>.
* Loading: Loading<257>.
* Testing: Testing<248>.
* Features: Features<79>.
* Options: Options<75>.
* Usage: Usage<106>.
* Dimension reducer representation: Dimension reducer representation<9>.
* References: References<52>.

Usage

* Learning a reducer: Learning a reducer<8>.
* Transforming new instances: Transforming new instances<8>.
* Exporting and reusing the reducer: Exporting and reusing the reducer<8>.

tsv

* API documentation: API documentation<254>.
* Loading: Loading<258>.
* Testing: Testing<249>.
* Usage: Usage<107>.

types

* API documentation: API documentation<255>.
* Loading: Loading<259>.
* Testing: Testing<250>.
* Type-checking: Type-checking<2>.
* Defining new types::
* Examples: Examples<179>.

tzif

* API documentation: API documentation<256>.
* Loading: Loading<260>.
* Testing: Testing<251>.
* Representation: Representation<22>.
* Zone identifier validation::
* Local Queries::
* Examples: Examples<180>.
* Known issues: Known issues<21>.

ulid

* API documentation: API documentation<257>.
* Loading: Loading<261>.
* Testing: Testing<252>.
* Generating ULIDs::
* Type-checking ULIDs::

unicode_data

* Authors::
* License::
* Website::
* Description: Description<165>.
* Requirements: Requirements<8>.
* Usage: Usage<108>.
* Known issues: Known issues<22>.
* Acknowledgements::
* Files and API Summary::

Files and API Summary

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

union_find

* API documentation: API documentation<258>.
* Loading: Loading<262>.
* Testing: Testing<253>.
* Usage: Usage<109>.

url

* API documentation: API documentation<259>.
* Loading: Loading<263>.
* Testing: Testing<254>.
* Usage: Usage<110>.

uuid

* API documentation: API documentation<260>.
* Loading: Loading<264>.
* Testing: Testing<255>.
* Generating version 1 UUIDs::
* Generating version 4 UUIDs::
* Generating version 3 UUIDs::
* Generating version 5 UUIDs::
* Generating version 7 UUIDs::
* Generating the Nil and Max UUIDs::

validations

* API documentation: API documentation<261>.
* Loading: Loading<265>.
* Testing: Testing<256>.
* Usage: Usage<111>.
* Comparison with the expecteds library::
* See also: See also<7>.

Comparison with the expecteds library

* Example; form validation with error accumulation: Example form validation with error accumulation.

wkt_wkb

* API documentation: API documentation<262>.
* Loading: Loading<266>.
* Testing: Testing<257>.
* Representation: Representation<23>.
* Sources and sinks::
* Examples: Examples<181>.
* Notes: Notes<13>.

yaml

* API documentation: API documentation<263>.
* Loading: Loading<267>.
* Testing: Testing<258>.
* API::
* Data Representation: Data Representation<2>.
* Examples: Examples<182>.
* Features: Features<80>.
* Supported YAML Features::
* Limitations: Limitations<6>.
* Error Handling: Error Handling<4>.
* File Organization::
* Test Files::
* Performance Considerations: Performance Considerations<2>.
* Integration with Other Libraries::
* Future Enhancements::
* See Also::

API

* Parsing: Parsing<3>.
* Generating: Generating<3>.
* Multi-Document Parsing::
* Multi-Document Generation::

Examples

* Parsing a Simple YAML String::
* Parsing a YAML List::
* Parsing a YAML File::
* Generating YAML from a Term::
* Generating YAML to a File::
* Working with Nested Structures::

z_score_anomaly_detector

* API documentation: API documentation<264>.
* Loading: Loading<268>.
* Testing: Testing<259>.
* Features: Features<81>.
* Options: Options<76>.
* Detector representation: Detector representation<8>.
* Notes: Notes<14>.

zippers

* API documentation: API documentation<265>.
* Loading: Loading<269>.
* Testing: Testing<260>.

Ports

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

fcube

* API documentation: API documentation<266>.
* Loading: Loading<270>.
* Testing: Testing<261>.

metagol

* API documentation: API documentation<267>.
* Loading: Loading<271>.
* Testing: Testing<262>.

toychr

* API documentation: API documentation<268>.
* Loading: Loading<272>.
* Testing: Testing<263>.

Contributions

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

flags

* API documentation: API documentation<269>.
* Loading: Loading<273>.
* Testing: Testing<264>.

iso8601

* API documentation: API documentation<270>.
* Loading: Loading<274>.
* Testing: Testing<265>.

pddl_parser

* API documentation: API documentation<271>.
* Loading: Loading<275>.
* Testing: Testing<266>.

xml_parser

* API documentation: API documentation<272>.
* Loading: Loading<276>.
* Testing: Testing<267>.
* Known issues: Known issues<23>.


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

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

* Menu:

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


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

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

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

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

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

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


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

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

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

Logtalk provides the following features:

* Menu:

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


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

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

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

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


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

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

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


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

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

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


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

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

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


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

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

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


File: TheLogtalkHandbook-3.101.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.101.0.info,  Node: Private protected and public inheritance,  Next: Private protected and public object predicates,  Prev: Separation between interface and implementation,  Up: Main features

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

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


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

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

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


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

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

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


File: TheLogtalkHandbook-3.101.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.101.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.101.0.info,  Node: Compatibility with most Prolog systems and the ISO standard,  Next: Performance,  Prev: Smooth learning curve,  Up: Main features

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

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


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

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

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

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

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

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


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

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

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

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

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

* Menu:

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


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

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

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

'arbitrary goals as directives'

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

'calling a predicate'

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

'closed-world assumption semantics'

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

'compiling and loading source files'

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

'debugging'

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

'directive operators'

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

'encapsulation'

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

'entity loading'

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

'flags scope'

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

'meta-predicate call semantics'

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

'operators scope'

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

'predicates scope'

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

'predicate declaration'

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

'predicate loading conflicts'

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


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

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

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

'abstract class'

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

'assignment statement'

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

'block'

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

'class'

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

'class method'

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

'class variable'

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

'inheritance'

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

'instance'

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

'instance method'

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

'instance variable'

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

'message'

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

'message selector'

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

'metaclass'

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

'method'

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

'method categories'

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

'object'

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

'pool variables*'

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

'protocol'

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

'self'

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

'subclass'

     Same definition in Logtalk.

'super'

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

'superclass'

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


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

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

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

'abstract class'

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

'base class'

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

'data member'

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

'constructor function'

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

'derived class'

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

'destructor function'

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

'friend function'

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

'instance'

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

'member'

     Logtalk uses the term *note predicate: 61.

'member function'

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

'namespace'

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

'nested class'

     Logtalk does not support nested classes.

'static member'

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

'template'

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

'this'

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

'virtual member function'

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


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

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

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

'abstract class'

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

'abstract method'

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

'assertion'

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

'class'

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

'extends'

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

'interface'

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

'callback method'

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

'constructor'

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

'final'

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

'inner class'

     Inner classes are not supported in Logtalk.

'instance'

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

'method'

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

'method call'

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

'method signature'

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

'package'

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

'reflection'

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

'static'

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

'static method'

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

'static variable'

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

'super'

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

'synchronized'

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

'this'

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


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

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

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

'abstract class'

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

'abstract method'

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

'class'

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

'dictionary'

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

'function'

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

'function object'

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

'import path'

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

'lambda'

     Logtalk natively supports lambda expressions.

'list'

     Lists are compound terms with native syntax support.

'list comprehensions'

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

'loader'

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

'loop'

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

'metaclass'

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

'method'

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

'method resolution order'

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

'object'

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

'package'

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

'set'

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

'string'

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

'tuple'

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

'variable'

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

'while loop'

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


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

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

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

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

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

* Menu:

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


File: TheLogtalkHandbook-3.101.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.101.0.info,  Node: Sending a message to an object,  Next: Delegating a message to an object,  Prev: Operators used in message-sending,  Up: Messages

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

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

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

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


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

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

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

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

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


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

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

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

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

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


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

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

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

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

This is semantically equivalent to:

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

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


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

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

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

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

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

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

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


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

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

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

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

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

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

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

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


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

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

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

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


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

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

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


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

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

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

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

* Menu:

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

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

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

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


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

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

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

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

* Menu:

* Prototypes::
* Classes::


File: TheLogtalkHandbook-3.101.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.101.0.info,  Node: Classes,  Prev: Prototypes,  Up: Objects prototypes classes and instances

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

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


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

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

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

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

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

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

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

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

An object can import one or more categories:

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

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

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

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

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

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

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

A class may specialize another class, its superclass:

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

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

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

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

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

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

     :- set_logtalk_flag(unknown_entities, silent).


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

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


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

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


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

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

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

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

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

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

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


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

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

Parametric objects have a compound term as identifier where all the
arguments of the compound term are variables.  These variables can be
bound when sending a message or become bound when a message to the
object succeeds, thus acting as 'object parameters'.  The object
predicates can be coded to depend on those parameters, which are
'logical variables' shared by all object predicates.  Parametric objects
can also be used to associate a set of predicates to terms that share a
common functor and arity.

As a consequence of parameters being logical variables, when defining,
for example, a parametric object ‘foo/1’, ‘foo(bar)’ and ‘foo(baz)’ are
different parameterizations of the same object, not distinct objects.

* Menu:

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


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

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

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

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

         ...
         bar(_Bar_).

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

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

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

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

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

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

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

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

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

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

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


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

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

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

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

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

     :- end_object.

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

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

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

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

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

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

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


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

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

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

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

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


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

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

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

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

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

For example, the call:

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

is equivalent to compiling and loading the object:

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

         :- dynamic.

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

     :- end_object.

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


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

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

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

     | ?- abolish_object(Object).

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


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

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

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

* Menu:

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


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

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

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

     :- initialization(Goal).

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

     :- object(foo).

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

         init :-
             ... .

         ...

     :- end_object.

Or a message to another object:

     :- object(assembler).

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

     :- end_object.

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

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

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

     :- end_object.

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


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

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

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

     :- dynamic.

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


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

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

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


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

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

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

     :- object(cities).

         :- public(city/4).

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

     :- end_object.

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

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


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

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

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


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

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

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

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

     | ?- instantiates_class(Instance, Class).

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

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

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

     | ?- specializes_class(Class, Superclass).

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

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

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

     | ?- extends_object(Object, Parent).

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

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

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

     | ?- imports_category(Object, Category).

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

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

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

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

or, if we also want to consider inherited protocols:

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

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

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

     | ?- complements_object(Category, Object).

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


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

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

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

     | ?- object_property(Object, Property).

The following object properties are supported:

‘static’

     The object is static

‘dynamic’

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

‘built_in’

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

‘threaded’

     The object supports/makes multi-threading calls

‘file(Path)’

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

‘file(Basename, Directory)’

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

‘lines(BeginLine, EndLine)’

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

‘directive(BeginLine, EndLine)’

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

‘context_switching_calls’

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

‘dynamic_declarations’

     The object supports dynamic declarations of predicates

‘events’

     Messages sent from the object generate events

‘source_data’

     Source data available for the object

‘info(List)’

     List of the compound term representation of the object ‘info/1’
     pairs with the key as functor.

‘complements(Permission)’

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

‘complements’

     The object supports complementing categories

‘public(Resources)’

     List of public predicates and operators declared by the object

‘protected(Resources)’

     List of protected predicates and operators declared by the object

‘private(Resources)’

     List of private predicates and operators declared by the object

‘declares(Predicate, Properties)’

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

‘defines(Predicate, Properties)’

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

‘includes(Predicate, Entity, Properties)’

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

‘provides(Predicate, Entity, Properties)’

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

‘references(Reference, Properties)’

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

‘alias(Entity, Properties)’

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

‘alias(Predicate, Properties)’

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

‘calls(Call, Properties)’

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

‘updates(Predicate, Properties)’

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

‘number_of_clauses(Number)’

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

‘number_of_rules(Number)’

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

‘number_of_user_clauses(Number)’

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

‘number_of_user_rules(Number)’

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

‘debugging’

     The object is compiled in debug mode

‘module’

     The object resulted from the compilation of a Prolog module

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

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

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


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

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

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

* Menu:

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


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

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

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

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

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

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


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

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

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

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

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


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

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

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


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

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

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

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

* Menu:

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

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

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

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

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


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

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

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

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

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

     :- protocol(Protocol).
         ...
     :- end_protocol.

If a protocol extends one or more protocols, then the opening directive
will be:

     :- protocol(Protocol,
         extends([Protocol1, Protocol2, ...])).
         ...
     :- end_protocol.

In order to maximize protocol reuse, all predicates specified in a
protocol should relate to the same functionality.  Therefore, the only
recommended use of protocol extension is when you need both a minimal
protocol and an extended version of the same protocol with additional,
convenient predicates.


File: TheLogtalkHandbook-3.101.0.info,  Node: Finding defined protocols,  Next: Creating a new protocol at runtime,  Prev: Defining a new protocol,  Up: Protocols

1.6.2 Finding defined protocols
-------------------------------

We can find, by backtracking, all defined protocols by using the *note
current_protocol/1: e0. built-in predicate with a unbound argument:

     | ?- current_protocol(Protocol).

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


File: TheLogtalkHandbook-3.101.0.info,  Node: Creating a new protocol at runtime,  Next: Abolishing an existing protocol,  Prev: Finding defined protocols,  Up: Protocols

1.6.3 Creating a new protocol at runtime
----------------------------------------

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

     | ?- create_protocol(Protocol, Relations, Directives).

The first argument should be either a variable or the name of the new
protocol (a Prolog atom, which must not match an existing entity name).
The remaining two arguments correspond to the relations described in the
opening protocol directive and to the protocol directives.

For instance, the call:

     | ?- create_protocol(ppp, [extends(qqq)], [public([foo/1, bar/1])]).

is equivalent to compiling and loading the protocol:

     :- protocol(ppp,
         extends(qqq)).

         :- dynamic.

         :- public([foo/1, bar/1]).

     :- end_protocol.

If we need to create a lot of (dynamic) protocols at runtime, then it is
best to define a metaclass or a prototype with a predicate that will
call this built-in predicate in order to provide more sophisticated
behavior.


File: TheLogtalkHandbook-3.101.0.info,  Node: Abolishing an existing protocol,  Next: Protocol directives,  Prev: Creating a new protocol at runtime,  Up: Protocols

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

Dynamic protocols can be abolished using the *note abolish_protocol/1:
e6. built-in predicate:

     | ?- abolish_protocol(Protocol).

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


File: TheLogtalkHandbook-3.101.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.101.0.info,  Node: Dynamic protocols,  Next: Protocol documentation,  Up: Protocol directives

1.6.5.1 Dynamic protocols
.........................

As usually happens with Prolog code, a protocol can be either static or
dynamic.  A protocol created during the execution of a program is always
dynamic.  A protocol defined in a file can be either dynamic or static.
Dynamic protocols are declared by using the *note dynamic/0: b1.
directive in the protocol source code:

     :- dynamic.

The directive must precede any predicate directives.  Please be aware
that using dynamic code results in a performance hit when compared to
static code.  We should only use dynamic protocols when these need to be
abolished during program execution.


File: TheLogtalkHandbook-3.101.0.info,  Node: Protocol documentation,  Next: Loading files into a protocol,  Prev: Dynamic protocols,  Up: Protocol directives

1.6.5.2 Protocol documentation
..............................

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


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading files into a protocol,  Prev: Protocol documentation,  Up: Protocol directives

1.6.5.3 Loading files into a protocol
.....................................

The *note include/1: b8. directive can be used to load the contents of a
file into a protocol.  See the *note Objects: 91. section for an example
of using this directive.


File: TheLogtalkHandbook-3.101.0.info,  Node: Protocol relationships,  Next: Protocol properties,  Prev: Protocol directives,  Up: Protocols

1.6.6 Protocol relationships
----------------------------

Logtalk provides two sets of built-in predicates that enable us to query
the system about the relationships that a protocol has with other
entities.

The *note extends_protocol/2-3: f0. built-in predicates return all pairs
of protocols so that the first one extends the second:

     | ?- extends_protocol(Protocol1, Protocol2).

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

     | ?- extends_protocol(Protocol1, Protocol2, Scope).

To find which objects or categories implement which protocols, we can
call the *note implements_protocol/2-3: c1. built-in predicates:

     | ?- implements_protocol(ObjectOrCategory, Protocol).

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

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

Note that, if we use a non-instantiated variable for the first argument,
we will need to use the *note current_object/1: a6. or *note
current_category/1: f1. built-in predicates to identify the kind of
entity returned.


File: TheLogtalkHandbook-3.101.0.info,  Node: Protocol properties,  Next: Implementing protocols,  Prev: Protocol relationships,  Up: Protocols

1.6.7 Protocol properties
-------------------------

We can find the properties of defined protocols by calling the *note
protocol_property/2: f4. built-in predicate:

     | ?- protocol_property(Protocol, Property).

A protocol may have the property ‘static’, ‘dynamic’, or ‘built_in’.
Dynamic protocols can be abolished in runtime by calling the *note
abolish_protocol/1: e6. built-in predicate.  Depending on the *note
backend Prolog compiler: 34, a protocol may have additional properties
related to the source file where it is defined.

The following protocol properties are supported:

‘static’

     The protocol is static

‘dynamic’

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

‘built_in’

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

‘source_data’

     Source data available for the protocol

‘info(List)’

     List of the compound term representation of the object ‘info/1’
     pairs with the key as functor.

‘file(Path)’

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

‘file(Basename, Directory)’

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

‘lines(BeginLine, EndLine)’

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

‘directive(BeginLine, EndLine)’

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

‘public(Resources)’

     List of public predicates and operators declared by the protocol

‘protected(Resources)’

     List of protected predicates and operators declared by the protocol

‘private(Resources)’

     List of private predicates and operators declared by the protocol

‘declares(Predicate, Properties)’

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

‘alias(Predicate, Properties)’

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

Some of the properties, such as line numbers, are only available when
the protocol is defined in a source file compiled with the *note
source_data: cc. flag turned on.


File: TheLogtalkHandbook-3.101.0.info,  Node: Implementing protocols,  Next: Built-in protocols,  Prev: Protocol properties,  Up: Protocols

1.6.8 Implementing protocols
----------------------------

Any number of objects or categories can implement a protocol.  The
syntax is very simple:

     :- object(Object,
         implements(Protocol)).
         ...
     :- end_object.

or, in the case of a category:

     :- category(Object,
         implements(Protocol)).
         ...
     :- end_category.

To make all public predicates declared via an implemented protocol
protected or to make all public and protected predicates private we
prefix the protocol’s name with the corresponding keyword.  For
instance:

     :- object(Object,
         implements(private::Protocol)).
         ...
     :- end_object.

or:

     :- object(Object,
         implements(protected::Protocol)).
         ...
     :- end_object.

Omitting the scope keyword is equivalent to writing:

     :- object(Object,
         implements(public::Protocol)).
         ...
     :- end_object.

The same rules apply to protocols implemented by categories.


File: TheLogtalkHandbook-3.101.0.info,  Node: Built-in protocols,  Next: Multi-threading applications<2>,  Prev: Implementing protocols,  Up: Protocols

1.6.9 Built-in protocols
------------------------

Logtalk defines a set of built-in protocols that are always available
for any application.

* Menu:

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


File: TheLogtalkHandbook-3.101.0.info,  Node: The built-in protocol expanding,  Next: The built-in protocol monitoring,  Up: Built-in protocols

1.6.9.1 The built-in protocol ‘expanding’
.........................................

The built-in expanding(1) protocol declares the *note term_expansion/2:
fc. and *note goal_expansion/2: fd. predicates.  See the description of
the *note hook: fe. compiler flag for more details.

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

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


File: TheLogtalkHandbook-3.101.0.info,  Node: The built-in protocol monitoring,  Next: The built-in protocol forwarding,  Prev: The built-in protocol expanding,  Up: Built-in protocols

1.6.9.2 The built-in protocol ‘monitoring’
..........................................

The built-in monitoring(1) protocol declares the *note before/3: 101.
and *note after/3: 102. public event handler predicates.  See the *note
Event-driven programming: 6d. section for more details.

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

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


File: TheLogtalkHandbook-3.101.0.info,  Node: The built-in protocol forwarding,  Prev: The built-in protocol monitoring,  Up: Built-in protocols

1.6.9.3 The built-in protocol ‘forwarding’
..........................................

The built-in forwarding(1) protocol declares the *note forward/1: 105.
user-defined message forwarding handler, which is automatically called
(if defined) by the runtime for any message that the receiving object
does not understand.  See also the *note []/1: 81. control construct.

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

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


File: TheLogtalkHandbook-3.101.0.info,  Node: Multi-threading applications<2>,  Prev: Built-in protocols,  Up: Protocols

1.6.10 Multi-threading applications
-----------------------------------

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


File: TheLogtalkHandbook-3.101.0.info,  Node: Categories,  Next: Predicates,  Prev: Protocols,  Up: User Manual

1.7 Categories
==============

Categories are 'fine-grained units of code reuse' and can be regarded as
a dual concept of protocols.  Categories provide a way to encapsulate a
set of related predicate declarations and definitions that do not
represent a complete object and that only make sense when composed with
other predicates.  Categories may also be used to break a complex object
into functional units.  A category can be imported by several objects
(without code duplication), including objects participating in prototype
or class-based hierarchies.  This concept of categories shares some
ideas with Smalltalk-80 functional categories *note [Goldberg83]: 1c,
Flavors mix-ins *note [Moon86]: 10a. (without necessarily implying
multi-inheritance), and Objective-C categories *note [Cox86]: 1d.
Categories may also 'complement' existing objects, thus providing a
*note hot patching: 10b. mechanism inspired by the Objective-C
categories functionality.

Logtalk defines a built-in category, core_messages(1), which is
described at the end of this section.

* Menu:

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

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

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


File: TheLogtalkHandbook-3.101.0.info,  Node: Defining a new category,  Next: Hot patching,  Up: Categories

1.7.1 Defining a new category
-----------------------------

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

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

Category code (directives and predicates) is textually encapsulated by
using two Logtalk directives: *note category/1-4: 10e. and *note
end_category/0: 10f.  The most simple category will be one that is
self-contained, not depending on any other Logtalk entity:

     :- category(Category).
         ...
     :- end_category.

If a category implements one or more protocols, then the opening
directive will be:

     :- category(Category,
         implements([Protocol1, Protocol2, ...])).
         ...
     :- end_category.

A category may be defined as a composition of other categories by
writing:

     :- category(Category,
         extends([Category1, Category2, ...])).
         ...
     :- end_category.

This feature should only be used when extending a category without
breaking its functional cohesion (for example, when a modified version
of a category is needed for importing on several unrelated objects).
The preferred way of composing several categories is by importing them
into an object.  When a category overrides a predicate defined in an
extended category, the overridden definition can still be called by
using the *note (^^)/1: 5d. control construct.

Categories cannot inherit from objects.  In addition, categories cannot
define clauses for dynamic predicates.  This restriction applies because
a category can be imported by several objects and because we cannot use
the database handling built-in methods with categories (messages can
only be sent to objects).  A consequence of this restriction is that a
category cannot declare a predicate (or non-terminal) as both multifile
and dynamic.  However, categories may contain declarations for dynamic
predicates, and they can contain predicates that handle dynamic
predicates.  For example:

     :- category(attributes).

         :- public(attribute/2).
         :- public(set_attribute/2).
         :- public(del_attribute/2).

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

         attribute(Attribute, Value) :-
             % called in the context of "self"
             ::attribute_(Attribute, Value).

         set_attribute(Attribute, Value) :-
             % retract old clauses in "self"
             ::retractall(attribute_(Attribute, _)),
             % assert new clause in "self"
             ::assertz(attribute_(Attribute, Value)).

         del_attribute(Attribute, Value) :-
             % retract clause in "self"
             ::retract(attribute_(Attribute, Value)).

     :- end_category.

Each object importing this category will have its own ‘attribute_/2’
private and dynamic predicate.  The predicates ‘attribute/2’,
‘set_attribute/2’, and ‘del_attribute/2’ always access and modify the
dynamic predicate contained in the object receiving the corresponding
messages (i.e., 'self').  But it’s also possible to define predicates
that handle dynamic predicates in the context of 'this' instead of
'self'.  For example:

     :- category(attributes).

         :- public(attribute/2).
         :- public(set_attribute/2).
         :- public(del_attribute/2).

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

         attribute(Attribute, Value) :-
             % call in the context of "this"
             attribute_(Attribute, Value).

         set_attribute(Attribute, Value) :-
             % retract old clauses in "this"
             retractall(attribute_(Attribute, _)),
             % asserts clause in "this"
             assertz(attribute_(Attribute, Value)).

         del_attribute(Attribute, Value) :-
             % retract clause in "this"
             retract(attribute_(Attribute, Value)).

     :- end_category.

When defining a category that declares and handles dynamic predicates,
working in the context of 'this' ties those dynamic predicates to the
object importing the category, while working in the context of 'self'
allows each object inheriting from the object that imports the category
to have its own set of clauses for those dynamic predicates.


File: TheLogtalkHandbook-3.101.0.info,  Node: Hot patching,  Next: Finding defined categories,  Prev: Defining a new category,  Up: Categories

1.7.2 Hot patching
------------------

A category may also explicitly complement one or more existing objects,
thus providing *note hot patching: 10b. functionality inspired by
Objective-C categories:

     :- category(Category,
         complements([Object1, Object2, ....])).
         ...
     :- end_category.

This allows us to add missing directives (e.g., to define *note aliases:
ca. for complemented object predicates), replace broken predicate
definitions, add new predicates, and add protocols and categories to
existing objects without requiring access or modifications to their
source code.  Common scenarios are adding logging or debugging
predicates to a set of objects.  Complemented objects need to be
compiled with the *note complements: 112. compiler flag set ‘allow’ (to
allow both patching and adding functionality) or ‘restrict’ (to allow
only adding new functionality).  A complementing category takes
preference over a previously loaded complementing category for the same
object, thus allowing patching a previous patch if necessary.

When replacing a predicate definition, it is possible to call the
overridden definition in the object from the new definition in the
category by using the *note (@)/1: 113. control construct.  This
construct is only meaningful when used within categories and requires a
compile-time bound goal argument, which is called in *note this: 114.
(i.e., in the context of the complemented object or the object importing
a category).  As an example, consider the following object:

     :- object(bird).

         :- set_logtalk_flag(complements, allow).

         :- public(make_sound/0).
         make_sound :-
             write('Chirp, chirp!'), nl.

     :- end_object.

We can use the ‘(@)/1’ control construct to wrap the original
‘make_sound/0’ predicate definition by writing:

     :- category(logging,
         complements(bird)).

         make_sound :-
             write('Started making sound...'), nl,
             @make_sound,
             write('... finished making sound.'), nl.

     :- end_category.

After loading the object and the category, calling the ‘make_sound/0’
predicate will result in the following output:

     | ?- bird::make_sound.

     Started making sound...
     Chirp, chirp!
     ... finished making sound.
     yes

Note that *note super calls: 115. from predicates defined in
complementing categories lookup inherited definitions as if the calls
were made from the complemented object instead of the category
ancestors.  This allows more comprehensive object patching.  But it also
means that, if you want to patch an object so that it imports a category
that extends another category and uses super calls to access the
extended category predicates, you will need to define a (possibly empty)
complementing category that extends the category that you want to add.

An unfortunate consequence of allowing an object to be patched at
runtime using a complementing category is that it disables the use of
*note static binding: 35. optimizations for messages sent to the
complemented object, as it can always be later patched, thus rendering
the static binding optimizations invalid.

Another important caveat is that, while a complementing category can
replace a predicate definition, local callers of the replaced predicate
will still call the non-patched version of the predicate.  This is a
consequence of the lack of a portable solution at the *note backend
Prolog compiler: 34. level for replacing static predicate definitions.


File: TheLogtalkHandbook-3.101.0.info,  Node: Finding defined categories,  Next: Creating a new category at runtime,  Prev: Hot patching,  Up: Categories

1.7.3 Finding defined categories
--------------------------------

We can find, by backtracking, all defined categories by using the *note
current_category/1: f1. built-in predicate with an unbound argument:

     | ?- current_category(Category).

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


File: TheLogtalkHandbook-3.101.0.info,  Node: Creating a new category at runtime,  Next: Abolishing an existing category,  Prev: Finding defined categories,  Up: Categories

1.7.4 Creating a new category at runtime
----------------------------------------

A category can be dynamically created at runtime by using the *note
create_category/4: 11a. built-in predicate:

     | ?- create_category(Category, Relations, Directives, Clauses).

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

For example, the call:

     | ?- create_category(
              ccc,
              [implements(ppp)],
              [private(bar/1)],
              [(foo(X):-bar(X)), bar(1), bar(2)]
          ).

is equivalent to compiling and loading the category:

     :- category(ccc,
         implements(ppp)).

         :- dynamic.

         :- private(bar/1).

         foo(X) :-
             bar(X).

         bar(1).
         bar(2).

     :- end_category.

If we need to create a lot of (dynamic) categories at runtime, then it
is best to define a metaclass or a prototype with a predicate that will
call this built-in predicate in order to provide more sophisticated
behavior.


File: TheLogtalkHandbook-3.101.0.info,  Node: Abolishing an existing category,  Next: Category directives,  Prev: Creating a new category at runtime,  Up: Categories

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

Dynamic categories can be abolished using the *note abolish_category/1:
f5. built-in predicate:

     | ?- abolish_category(Category).

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


File: TheLogtalkHandbook-3.101.0.info,  Node: Category directives,  Next: Category relationships,  Prev: Abolishing an existing category,  Up: Categories

1.7.6 Category directives
-------------------------

Category directives are used to define category properties, document
category dependencies on other Logtalk entities, and load the contents
of files into a category.

* Menu:

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


File: TheLogtalkHandbook-3.101.0.info,  Node: Dynamic categories,  Next: Category documentation,  Up: Category directives

1.7.6.1 Dynamic categories
..........................

As usually happens with Prolog code, a category can be either static or
dynamic.  A category created during the execution of a program is always
dynamic.  A category defined in a file can be either dynamic or static.
Dynamic categories are declared by using the *note dynamic/0: b1.
directive in the category source code:

     :- dynamic.

The directive must precede any predicate directives or clauses.  Please
be aware that using dynamic code results in a performance hit when
compared to static code.  We should only use dynamic categories when
these need to be abolished during program execution.


File: TheLogtalkHandbook-3.101.0.info,  Node: Category documentation,  Next: Loading files into a category,  Prev: Dynamic categories,  Up: Category directives

1.7.6.2 Category documentation
..............................

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


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading files into a category,  Next: Declaring object aliases<2>,  Prev: Category documentation,  Up: Category directives

1.7.6.3 Loading files into a category
.....................................

The *note include/1: b8. directive can be used to load the contents of a
file into a category.  See the *note Objects: 91. section for an example
of using this directive.


File: TheLogtalkHandbook-3.101.0.info,  Node: Declaring object aliases<2>,  Prev: Loading files into a category,  Up: Category directives

1.7.6.4 Declaring object aliases
................................

The *note uses/1: 4a. directive can be used to declare object aliases.
The typical uses of this directive are to shorten long object names and
to simplify experimenting with different object implementations of the
same protocol when using explicit message-sending.


File: TheLogtalkHandbook-3.101.0.info,  Node: Category relationships,  Next: Category properties,  Prev: Category directives,  Up: Categories

1.7.7 Category relationships
----------------------------

Logtalk provides two sets of built-in predicates that enable us to query
the system about the relationships that a category has with other
entities.

The built-in predicates *note implements_protocol/2-3: c1. and *note
conforms_to_protocol/2-3: c2. allow us to find which categories
implement which protocols:

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

or, if we also want to consider inherited protocols:

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

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

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

     | ?- imports_category(Object, Category).

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

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

Note that a category may be imported by several objects.

To find which categories extend other categories, we can use the *note
extends_category/2-3: 129. built-in predicates:

     | ?- extends_category(Category1, Category2).

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

     | ?- extends_category(Category1, Category2, Scope).

Note that a category may be extended by several categories.

To find which categories explicitly complement existing objects we can
use the *note complements_object/2: c3. built-in predicate:

     | ?- complements_object(Category, Object).

Note that a category may explicitly complement several objects.


File: TheLogtalkHandbook-3.101.0.info,  Node: Category properties,  Next: Importing categories,  Prev: Category relationships,  Up: Categories

1.7.8 Category properties
-------------------------

We can find the properties of defined categories by calling the built-in
predicate *note category_property/2: 12c.:

     | ?- category_property(Category, Property).

The following category properties are supported:

‘static’

     The category is static

‘dynamic’

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

‘built_in’

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

‘file(Path)’

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

‘file(Basename, Directory)’

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

‘lines(BeginLine, EndLine)’

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

‘directive(BeginLine, EndLine)’

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

‘events’

     Messages sent from the category generate events

‘source_data’

     Source data available for the category

‘info(List)’

     List of the compound term representation of the object ‘info/1’
     pairs with the key as functor.

‘public(Resources)’

     List of public predicates and operators declared by the category

‘protected(Resources)’

     List of protected predicates and operators declared by the category

‘private(Resources)’

     List of private predicates and operators declared by the category

‘declares(Predicate, Properties)’

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

‘defines(Predicate, Properties)’

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

‘includes(Predicate, Entity, Properties)’

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

‘provides(Predicate, Entity, Properties)’

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

‘references(Reference, Properties)’

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

‘alias(Entity, Properties)’

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

‘alias(Predicate, Properties)’

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

‘calls(Call, Properties)’

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

‘updates(Predicate, Properties)’

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

‘number_of_clauses(Number)’

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

‘number_of_rules(Number)’

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

‘number_of_user_clauses(Number)’

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

‘number_of_user_rules(Number)’

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

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

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


File: TheLogtalkHandbook-3.101.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.101.0.info,  Node: Calling category predicates,  Next: Parametric categories,  Prev: Importing categories,  Up: Categories

1.7.10 Calling category predicates
----------------------------------

Category predicates can be called from within an object by sending a
message to 'self' or using a 'super' call.  Consider the following
category:

     :- category(output).

         :- public(out/1).

         out(X) :-
             write(X), nl.

     :- end_category.

The predicate ‘out/1’ can be called from within an object importing the
category by simply sending a message to 'self'.  For example:

     :- object(worker,
         imports(output)).

         ...
         do(Task) :-
             execute(Task, Result),
             ::out(Result).
         ...

     :- end_object.

This is the recommended way of calling a category predicate that can be
specialized/overridden in a descendant object, as the predicate
definition lookup will start from 'self'.

A direct call to a predicate definition found in an imported category
can be made using the *note (^^)/1: 5d. control construct.  For example:

     :- object(worker,
         imports(output)).

         ...
         do(Task) :-
             execute(Task, Result),
             ^^out(Result).
         ...

     :- end_object.

This alternative should only be used when the user knows a priori that
the category predicates will not be specialized or redefined by
descendant objects of the object importing the category.  Its advantage
is that, when the *note optimize: 8c. flag is turned on, the Logtalk
compiler will try to optimize the calls by using *note static binding:
35.  When *note dynamic binding: 36. is used due to e.g.  the lack of
sufficient information at compilation time, the performance is similar
to calling the category predicate using a message to *note self: 69. (in
both cases, a predicate lookup caching mechanism is used).


File: TheLogtalkHandbook-3.101.0.info,  Node: Parametric categories,  Next: Built-in categories,  Prev: Calling category predicates,  Up: Categories

1.7.11 Parametric categories
----------------------------

Category predicates can be parameterized in the same way as object
predicates by using a compound term as the category identifier where all
the arguments of the compound term are variables.  These variables, the
'category parameters', are 'logical variables' and can be accessed by
calling the *note parameter/2: a2. or *note this/1: 68. built-in local
methods in the category predicate clauses or by using *note parameter
variables: a1.

As a consequence of parameters being logical variables, when defining,
for example, a parametric category named ‘foo/1’, ‘foo(bar)’ and
‘foo(baz)’ are different parameterizations of the same category, not
distinct categories.

Category parameter values can be defined by the importing objects.  For
example:

     :- object(speech(Season, Event),
         imports([dress(Season), speech(Event)])).
         ...
     :- end_object.

Note that access to category parameters is only possible from within the
category.  In particular, calls to the *note this/1: 68. built-in local
method from category predicates always access the importing object
identifier (and thus object parameters, not category parameters).


File: TheLogtalkHandbook-3.101.0.info,  Node: Built-in categories,  Next: Multi-threading applications<3>,  Prev: Parametric categories,  Up: Categories

1.7.12 Built-in categories
--------------------------

Logtalk defines a built-in category that is always available for any
application.

* Menu:

* The built-in category core_messages::


File: TheLogtalkHandbook-3.101.0.info,  Node: The built-in category core_messages,  Up: Built-in categories

1.7.12.1 The built-in category ‘core_messages’
..............................................

The built-in core_messages(1) category provides default translations for
all compiler and runtime printed messages, such as warnings and errors.
It does not define any public predicates.

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

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


File: TheLogtalkHandbook-3.101.0.info,  Node: Multi-threading applications<3>,  Prev: Built-in categories,  Up: Categories

1.7.13 Multi-threading applications
-----------------------------------

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


File: TheLogtalkHandbook-3.101.0.info,  Node: Predicates,  Next: Inheritance,  Prev: Categories,  Up: User Manual

1.8 Predicates
==============

Predicate directives and clauses can be encapsulated inside objects and
categories.  Protocols can only contain predicate directives.  From the
point of view of a traditional imperative object-oriented language,
predicates allow both object state and object behavior to be
represented.  Mutable object state can be represented using dynamic
object predicates but should only be used when strictly necessary, as it
breaks declarative semantics.

* Menu:

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


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

1.8.1 Reserved predicate names
------------------------------

For practical and performance reasons, some predicate names have a fixed
interpretation.  These predicates are declared in the built-in
protocols.  They are: *note goal_expansion/2: fd. and *note
term_expansion/2: fc, declared in the expanding(1) protocol; *note
before/3: 101. and *note after/3: 102, declared in the monitoring(2)
protocol; and *note forward/1: 105, declared in the forwarding(3)
protocol.  By default, the compiler prints a warning when a definition
for one of these predicates is found but the reference to the
corresponding built-in protocol is missing.

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

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

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

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


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

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

Logtalk provides a clear distinction between 'declaring a predicate' and
'defining a predicate' and thus clear *note closed-world assumption: 6a.
semantics.  Messages or calls for declared but undefined predicates
fail.  Messages or calls for unknown (i.e., non-declared) predicates
throw an error.  Note that this is a fundamental requirement for
supporting *note protocols: d9.: we must be able to declare a predicate
without necessarily defining it.

All object (or category) predicates that we want to access from other
objects (or categories) must be explicitly declared.  A predicate
declaration must contain, at least, a 'scope' directive.  Other
directives may be used to document the predicate or to ensure proper
compilation of the predicate clauses.

* Menu:

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


File: TheLogtalkHandbook-3.101.0.info,  Node: Scope directives,  Next: Mode directive,  Up: Declaring predicates

1.8.2.1 Scope directives
........................

A predicate scope directive specifies 'from where' the predicate can be
called, i.e.  its 'visibility'.  Predicates can be 'public',
'protected', 'private', or 'local'.  Public predicates can be called
from any object.  Protected predicates can only be called from the
container object or from a container descendant.  Private predicates can
only be called from the container object.  Predicates are local when
they are not declared in a scope directive.  Local predicates, like
private predicates, can only be called from the container object (or
category), but they are 'invisible' to the reflection built-in methods
(*note current_predicate/1: 141. and *note predicate_property/2: 142.)
and to the message error handling mechanisms (i.e., sending a message
corresponding to a local predicate results in a ‘predicate_declaration’
existence error instead of a scope error).

The scope declarations are made using the directives *note public/1:
143, *note protected/1: 144, and *note private/1: 145.  For example:

     :- public(init/1).

     :- protected(valid_init_option/1).

     :- private(process_init_options/1).

If a predicate does not have a (local or inherited) scope declaration,
it is assumed that the predicate is local.  Note that we do not need to
write scope declarations for all defined predicates.  One exception is
local dynamic predicates: declaring them as private predicates may allow
the Logtalk compiler to generate optimized code for asserting and
retracting clauses.

Note that a predicate scope directive doesn’t specify 'where' a
predicate is, or can be, defined.  For example, a private predicate can
only be called from an object holding its scope directive.  But it can
be defined in descendant objects.  A typical example is an object
playing the role of a class defining a private (possibly dynamic)
predicate for its descendant instances.  Only the class can call (and
possibly assert/retract clauses for) the predicate, but its clauses can
be found/defined in the instances themselves.

Scope directives may also be used to declare grammar rule non-terminals
and operators.  For example:

     :- public(url//1).

     :- public(op(800, fx, tag)).

Note that, in the case of operators, the operator definitions don’t
become global when the entity containing the directives is compiled and
loaded.  This prevents an application from breaking when, for example,
an updated third-party library adds new operators.  It also allows
loading entities that provide conflicting operator definitions.  Here
the usual programming idiom is to copy the operator definitions to a
‘uses/2’ directive.  For example, the *note lgtunit: 146. tool makes
available a ‘(=~=)/2’ predicate (for approximate float equality) that is
intended to be used as an infix operator:

     :- uses(lgtunit, [
         op(700, xfx, =~=), (=~=)/2
     ]).

Thus, in practice, the solution to use library entity operators in
client entities is the same for using library entity predicates with
implicit message-sending.


File: TheLogtalkHandbook-3.101.0.info,  Node: Mode directive,  Next: Meta-predicate directive,  Prev: Scope directives,  Up: Declaring predicates

1.8.2.2 Mode directive
......................

Often predicates can only be called using specific argument patterns.
The valid arguments and instantiation modes of those arguments can be
documented using the *note mode/2: 149. directive (in the case of
'non-terminals', there’s also a *note mode_non_terminal/2: 14a.
directive).  For example:

     :- mode(member(?term, ?list), zero_or_more).
The first directive argument describes a valid 'calling mode'.  The
minimum information will be the instantiation mode of each argument.
The first four possible values are described in the ISO Prolog Core
standard *note [ISO95]: 31. (but with the meaning of the ‘-’
instantiation mode redefined here).  The remaining two can also be found
in use in some Prolog systems.

‘+’

     Argument must be instantiated (but not necessarily ground).

‘-’

     Argument should be a free (non-instantiated) variable.  When bound,
     the call will unify the computed term with the given argument.

‘?’

     Argument can either be instantiated or free.

‘@’

     Argument will not be further instantiated (modified).

‘++’

     Argument must be ground.

‘--’

     Argument must be unbound.  Used mainly when returning an opaque
     term (e.g., a stream handle).

Note that the ‘+’ and ‘@’ instantiation modes have the same meaning for
atomic arguments.  E.g.  you can write either ‘+atom’ or ‘@atom’ but the
first alternative is preferred.

The ISO ‘-’ instantiation mode is equivalent to the Logtalk ‘--’ mode,
allowing the use ‘-’ to document predicates with output arguments that
don’t require those arguments to be unbound at call time and also accept
bound arguments without throwing an exception.

These six mode atoms are also declared as prefix operators by the
Logtalk compiler.  This makes it possible to include type information
for each argument as in the example above.  Some possible type values
are: ‘event’, ‘object’, ‘category’, ‘protocol’, ‘callable’, ‘term’,
‘nonvar’, ‘var’, ‘atomic’, ‘atom’, ‘number’, ‘integer’, ‘float’,
‘compound’, and ‘list’.  The first four are Logtalk specific.  The
remaining are common Prolog types.  We can also use our own types that
can be either atoms or ground compound terms.  See the *note types: 14c.
library documentation for an extensive list of pre-defined types that
cover most common use cases.  The second directive argument documents
the 'number of proofs', but not necessarily distinct solutions, for the
specified mode.  As an example, the ‘member(X, [1,1,1,1])’ goal has only
one distinct solution but four proofs for that solution.  Note that
different modes for the same predicate often have different determinism.
The possible values are:

‘zero’

     Predicate always fails (e.g., the ‘false/0’ standard predicate).

‘one’

     Predicate always succeeds once (e.g., the ‘flush_output/0’ standard
     predicate).

‘zero_or_one’

     Predicate either fails or succeeds (e.g., the ‘atom/1’ standard
     predicate).

‘zero_or_more’

     Predicate has zero or more proofs (e.g., the ‘current_predicate/1’
     standard predicate).

‘one_or_more’

     Predicate has one or more proofs (e.g., the ‘repeat/0’ standard
     predicate).

‘zero_or_error’

     Predicate either fails or throws an error.

‘one_or_error’

     Predicate either succeeds once or throws an error (e.g., the
     ‘open/3’ standard predicate).

‘zero_or_one_or_error’

     Predicate succeeds once or fails or throws an error (e.g., the
     ‘get_char/1’ standard predicate).

‘zero_or_more_or_error’

     Predicate may fail or succeed multiple times or throw an error
     (e.g., the ‘retract/1’ standard predicate).

‘one_or_more_or_error’

     Predicate may succeed one or more times or throw an error.

‘error’

     Predicate will throw an error (e.g., the ‘type_error/2’ built-in
     method).

The last six values support documenting that some call modes may throw
an error or will throw an error 'despite the call arguments complying
with the expected types and instantiation modes'.  As an example,
consider the ‘open/3’ standard predicate:

     :- mode(open(@source_sink, @io_mode, --stream), one_or_error).

In this case, the mode directive tells the user that a valid call can
still throw an error (there may be e.g.  a permission error opening the
specified source or sink).

Notice that using the ‘zero’, ‘one’, ‘zero_or_one’, ‘zero_or_more’, or
‘one_or_more’ modes is not only for predicates that never throw an
exception; they can also be used for any predicate that doesn’t throw an
exception when the arguments are valid.  For example, the
‘current_predicate/1’ standard predicate throws an exception if the
argument is neither a variable nor a predicate indicator, but it
succeeds zero or more times when its argument is valid:

     :- mode(current_predicate(?predicate_indicator), zero_or_more).

Some predicates have more than one valid mode, thus implying several
mode directives.  For example, to document the possible use modes of the
standard ‘atom_concat/3’ predicate, we would write:

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

The first ‘mode/2’ directive specifies that the ‘atom_concat/3’
predicate can be used to split an atom into a prefix and a suffix.  The
second ‘mode/2’ directive specifies that concatenating two atoms results
in a new atom.  There are often several alternative ‘mode/2’ directives
that can be used to specify a predicate.  For example, an alternative to
the second ‘mode/2’ directive above would be:

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

In this case, the same information is provided by both alternatives.
But the first alternative is simpler and thus preferred.

Some old Prolog compilers supported some sort of mode directives to
improve performance.  To the best of my knowledge, there is no modern
Prolog compiler supporting this kind of directive for that purpose.  The
current Logtalk version simply parses this directive for collecting its
information for use in the *note reflection API: 48. (assuming the *note
source_data: cc. flag is turned on).  In any case, the use of mode
directives is a good starting point for documenting your predicates.


File: TheLogtalkHandbook-3.101.0.info,  Node: Meta-predicate directive,  Next: Discontiguous directive,  Prev: Mode directive,  Up: Declaring predicates

1.8.2.3 Meta-predicate directive
................................

Some predicates may have arguments that will be called as goals,
interpreted as *note closures: 14f. that will be used for constructing
goals, or passing meta-arguments to calls to other meta-predicates.  To
ensure that these goals will be executed in the correct context (i.e.,
in the *note calling context: 150, not in the meta-predicate *note
definition context: 151.), we need to use the *note meta_predicate/1:
152. directive (in the case of 'meta non-terminals', there’s also a
*note meta_non_terminal/1: 153. directive).  For example:

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

The meta-predicate mode arguments in this directive have the following
meaning:

‘0’

     Meta-argument that will be called as a goal.

‘N’

     Meta-argument that will be a closure used to construct a call by
     extending it with ‘N’ arguments.  The value of ‘N’ must be a
     positive integer.

‘::’

     Argument that is context-aware but that will not be called as a
     goal or a closure.  It can contain, however, sub-terms that will be
     called as goals or closures.

‘^’

     Goal that may be existentially quantified (‘Vars^Goal’).

‘*’

     Normal argument.

The following meta-predicate mode arguments are for use only when
writing backend Prolog *note adapter files: 154. to deal with
proprietary built-in meta-predicates and meta-directives:

‘/’

     Predicate indicator (‘Name/Arity’), list of predicate indicators,
     or conjunction of predicate indicators.

‘//’

     Non-terminal indicator (‘Name//Arity’), list of predicate
     indicators, or conjunction of predicate indicators.

‘[0]’

     List of goals.

‘[N]’

     List of closures.

‘[/]’

     List of predicate indicators.

‘[//]’

     List of non-terminal indicators.

To the best of my knowledge, the use of non-negative integers to specify
closures was first introduced on Quintus Prolog for providing
information for predicate cross-reference tools.

Note that Logtalk meta-predicate semantics are different from Prolog
meta-predicate semantics (assuming a predicate-based module system as
common):

   - Meta-arguments are always called in the meta-predicate calling
     context, independent of using explicit or implicit message-sending
     (to the object defining the meta-predicate when not local).  Most
     Prolog systems have different semantics for explicit versus
     implicit module qualification.

   - Logtalk is not based on a predicate prefixing mechanism.
     Therefore, the meta-predicate directive is required for any
     predicate with meta-arguments (including when simply passing the
     meta-arguments to a call to another meta-predicate).  This is
     usually not required in Prolog systems due to the module prefixing
     of meta-arguments.

   - Sending a message from a meta-predicate definition to call a
     meta-predicate defined in another object resets the calling context
     for any passed meta-argument to the object sending the message
     (including for messages to 'self').  Meta-arguments behave
     differently in Prolog systems due to their module prefixing.

   - Logtalk protects from common scenarios where specially crafted
     meta-predicate definitions are used to break object (and category)
     encapsulation by changing the meta-arguments passed by client code
     or trying to subvert the implicit calling context to call client
     predicates other than the predicates passed as meta-arguments.

     Warning: As each Logtalk entity is independently compiled, this
     directive must be included in every object or category that
     contains a definition for the described meta-predicate, even if the
     meta-predicate declaration is inherited from another entity, to
     ensure proper compilation of meta-arguments.


File: TheLogtalkHandbook-3.101.0.info,  Node: Discontiguous directive,  Next: Dynamic directive,  Prev: Meta-predicate directive,  Up: Declaring predicates

1.8.2.4 Discontiguous directive
...............................

The clause of an object (or category) predicate may not be contiguous.
In that case, we must declare the predicate discontiguous by using the
*note discontiguous/1: 157. directive:

     :- discontiguous(foo/1).

This is a directive that we should avoid using: it makes your code
harder to read, and it is not supported by some Prolog backends.

     Warning: As each Logtalk entity is compiled independently of other
     entities, this directive must be included in every object or
     category that contains a definition for the described predicate
     (even if the predicate declaration is inherited from another
     entity).


File: TheLogtalkHandbook-3.101.0.info,  Node: Dynamic directive,  Next: Operator directive,  Prev: Discontiguous directive,  Up: Declaring predicates

1.8.2.5 Dynamic directive
.........................

An object predicate can be static or dynamic.  By default, all
predicates (and non-terminals) of static objects defined in source files
are static.  To declare a dynamic predicate (or non-terminal), we use
the *note dynamic/1: 15a. directive.  For example:

     :- dynamic(foo/1).

Predicates of objects dynamically created at runtime (using the *note
create_object/4: 62. built-in predicate) and predicates of dynamic
objects defined in source files (using the *note dynamic/0: b1.
directive) are implicitly dynamic.

Dynamic predicates can be used to represent persistent mutable object
state.  Note that static objects may declare and define dynamic
predicates.  Categories can only declare dynamic predicates (with the
importing objects holding the predicate definitions).

     Warning: As each Logtalk entity is compiled independently from
     other entities, this directive must be included in every object
     that contains a definition for the described predicate (even if the
     predicate declaration is inherited from another object or imported
     from a category).  If we omit the dynamic declaration then the
     predicate definition will be compiled static.


File: TheLogtalkHandbook-3.101.0.info,  Node: Operator directive,  Next: Uses directive,  Prev: Dynamic directive,  Up: Declaring predicates

1.8.2.6 Operator directive
..........................

An object (or category) predicate can be declared as an operator using
the familiar *note op/3: 15d. directive:

     :- op(Priority, Specifier, Operator).

Operators are local to the object (or category) where they are declared.
This means that, if you declare a public predicate as an operator, you
cannot use operator notation when sending to an object (where the
predicate is visible) the respective message (as this would imply
visibility of the operator declaration in the context of the 'sender' of
the message).  If you want to declare global operators and, at the same
time, use them inside an entity, just write the corresponding directives
at the top of your source file, before the entity opening directive.

Note that operators can also be declared using a scope directive.  Only
these operators are visible to the *note current_op/3: 15e. reflection
method.

When the same operators are used on several entities within the same
source file, the corresponding directives must either be repeated in
each entity or appear before any entity that uses them.  But in the
later case, this results in a global scope for the operators.  If you
prefer the operators to be local to the source file, just 'undefine'
them at the end of the file.  For example:

     % before any entity that uses the operator
     :- op(400, xfx, results).

     ...

     % after all entities that used the operator
     :- op(0, xfx, results).

Global operators can be declared in the application loader file.


File: TheLogtalkHandbook-3.101.0.info,  Node: Uses directive,  Next: Alias directive,  Prev: Operator directive,  Up: Declaring predicates

1.8.2.7 Uses directive
......................

When a predicate makes heavy use of predicates defined on other objects,
its predicate clauses can be verbose due to all the necessary
message-sending goals.  Consider the following example:

     foo :-
         ...,
         findall(X, list::member(X, L), A),
         list::append(A, B, C),
         list::select(Y, C, R),
         ...

Logtalk provides a directive, *note uses/2: 4b, which allows us to
simplify the code above.  One of the usage templates for this directive
is:

     :- uses(Object, [
         Name1/Arity1, Name2/Arity2, ...
     ]).

Rewriting the code above using this directive results in a simplified
and more readable predicate definition:

     :- uses(list, [
         append/3, member/2, select/3
     ]).

     foo :-
         ...,
         findall(X, member(X, L), A),
         append(A, B, C),
         select(Y, C, R),
         ...

Logtalk also supports an extended version of this directive that allows
the declaration of *note predicate aliases: ca. using the notation
‘Predicate as Alias’ (or the alternative notation ‘Predicate::Alias’).
For example:

     :- uses(btrees, [new/1 as new_btree/1]).
     :- uses(queues, [new/1 as new_queue/1]).

You may use this extended version for solving conflicts between
predicates declared on several ‘uses/2’ directives or just for giving
new names to the predicates that will be more meaningful on their using
context.

Predicate aliases can also be used to define *note predicate shorthands:
161, simplifying code maintenance.  For example:

     :- uses(pretty_printer, [
         indent(4, Term) as indent(Term)
     ]).

Assuming multiple calls to the shorthand, a change to the indent value
will require a change to a single line instead of changing every call.

Another common use of predicate aliases is changing the order of the
predicate arguments without using *note lambda expressions: 162.  For
example:

     :- uses(meta, [
         fold_left(Closure, Result0, List, Result) as foldl(Closure, List, Result0, Result)
     ]).

See the directive documentation for details and other examples.

The ‘uses/2’ directive allows simpler predicate definitions as long as
there are no conflicts between the predicates declared in the directive
and the predicates defined in the object (or category) containing the
directive.  A predicate (or its alias if defined) cannot be listed in
more than one ‘uses/2’ directive.  In addition, a ‘uses/2’ directive
cannot list a predicate (or its alias if defined) that is defined in the
object (or category) containing the directive.  Any conflicts are
reported by Logtalk as compilation errors.

The object identifier argument can also be a *note parameter variable:
a1. when using the directive in a parametric object or a parametric
category.  In this case, *note dynamic binding: 36. will necessarily be
used for all listed predicates (and non-terminals).  The parameter
variable must be instantiated at runtime when the messages are sent.
This feature simplifies experimenting with multiple implementations of
the same protocol (for example, to evaluate the performance of each
implementation for a particular case).  It also simplifies writing tests
that check multiple implementations of the same protocol.

An object (or category) can make a predicate listed in a ‘uses/2’ (or
‘use_module/2’) directive part of its protocol by simply adding a scope
directive for the predicate.  For example, in the ‘statistics’ library
we have:

     :- public(modes/2).
     :- uses(numberlist, [modes/2]).

Therefore, a goal such as ‘sample::modes(Sample, Modes)’ implicitly
calls ‘numberlist::modes(Sample, Modes)’ without requiring an explicit
local definition for the ‘modes/2’ predicate (which would trigger a
compilation error).


File: TheLogtalkHandbook-3.101.0.info,  Node: Alias directive,  Next: Documenting directive,  Prev: Uses directive,  Up: Declaring predicates

1.8.2.8 Alias directive
.......................

Logtalk allows the definition of an alternative name for an inherited or
imported predicate (or for an inherited or imported grammar rule
non-terminal) through the use of the *note alias/2: 165. directive:

     :- alias(Entity, [
         Predicate1 as Alias1,
         Predicate2 as Alias2,
         ...
     ]).

This directive can be used in objects, protocols, or categories.  The
first argument, ‘Entity’, must be an entity referenced in the opening
directive of the entity containing the ‘alias/2’ directive.  It can be
an extended or implemented protocol, an imported category, an extended
prototype, an instantiated class, or a specialized class.  The second
argument is a list of pairs of predicate indicators (or grammar rule
non-terminal indicators) using the ‘as’ infix operator.

A common use for the ‘alias/2’ directive is to give an alternative name
to an inherited predicate in order to improve readability.  For example:

     :- object(square,
         extends(rectangle)).

         :- alias(rectangle, [width/1 as side/1]).

         ...

     :- end_object.

The directive allows both ‘width/1’ and ‘side/1’ to be used as messages
to the object ‘square’.  Thus, using this directive, there is no need to
explicitly declare and define a “new” ‘side/1’ predicate.  Note that the
‘alias/2’ directive does not rename a predicate, it only provides an
alternative, additional name; the original name continues to be
available (although it may be masked due to the default inheritance
conflict mechanism).

Another common use for this directive is to solve conflicts when two
inherited predicates have the same name and arity.  We may want to call
the predicate that is masked out by the Logtalk lookup algorithm (see
the *note Inheritance: 8. section) or we may need to call both
predicates.  This is simply accomplished by using the ‘alias/2’
directive to give alternative names to masked-out or conflicting
predicates.  Consider the following example:

     :- object(my_data_structure,
         extends(list, set)).

         :- alias(list, [member/2 as list_member/2]).
         :- alias(set,  [member/2 as set_member/2]).

         ...

     :- end_object.

Assuming that both ‘list’ and ‘set’ objects define a ‘member/2’
predicate, without the ‘alias/2’ directives, only the definition of
‘member/2’ predicate in the object ‘list’ would be visible on the object
‘my_data_structure’, as a result of the application of the Logtalk
predicate lookup algorithm.  By using the ‘alias/2’ directives, all the
following messages would be valid (assuming a public scope for the
predicates):

     % uses list member/2
     | ?- my_data_structure::list_member(X, L).

     % uses set member/2
     | ?- my_data_structure::set_member(X, L).

     % uses list member/2
     | ?- my_data_structure::member(X, L).

When used this way, the ‘alias/2’ directive provides functionality
similar to programming constructs of other object-oriented languages
that support multi-inheritance (the most notable example probably being
the renaming of inherited features in Eiffel).

Note that the ‘alias/2’ directive never hides a predicate that is
visible on the entity containing the directive as a result of the
Logtalk lookup algorithm.  However, it may be used to make visible a
predicate that otherwise would be masked by another predicate, as
illustrated in the above example.

The ‘alias/2’ directive may also be used to give access to an inherited
predicate, which otherwise would be masked by another inherited
predicate, while keeping the original name as follows:

     :- object(my_data_structure,
         extends(list, set)).

         :- alias(list, [member/2 as list_member/2]).
         :- alias(set,  [member/2 as set_member/2]).

         member(X, L) :-
             ^^set_member(X, L).

         ...

     :- end_object.

Thus, when sending the message ‘member/2’ to ‘my_data_structure’, the
predicate definition in ‘set’ will be used instead of the one contained
in ‘list’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Documenting directive,  Next: Multifile directive,  Prev: Alias directive,  Up: Declaring predicates

1.8.2.9 Documenting directive
.............................

A predicate can be documented with arbitrary user-defined information by
using the *note info/2: 168. directive:

     :- info(Name/Arity, List).

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


File: TheLogtalkHandbook-3.101.0.info,  Node: Multifile directive,  Next: Coinductive directive,  Prev: Documenting directive,  Up: Declaring predicates

1.8.2.10 Multifile directive
............................

A predicate can be declared *note multifile: 16b. by using the *note
multifile/1: 16c. directive:

     :- multifile(Name/Arity).

This allows clauses for a predicate to be defined in several objects
and/or categories.  This is a directive that should be used with care.
It’s commonly used in the definition of *note hook predicates: 16d.
Multifile predicates (and non-terminals) may also be declared dynamic
using the same predicate (or non-terminal) notation (multifile
predicates are static by default).

Logtalk precludes using a multifile predicate for breaking object
encapsulation by checking that the object (or category) declaring the
predicate (using a scope directive) defines it also as multifile.  This
entity is said to contain the 'primary declaration' for the multifile
predicate.  Entities containing primary multifile predicate declarations
must always be compiled before entities defining clauses for those
multifile predicates.  The Logtalk compiler will print a warning if the
scope directive is missing.  Note also that the ‘multifile/1’ directive
is mandatory when defining multifile predicates.

Consider the following simple example:

     :- object(main).

         :- public(a/1).
         :- multifile(a/1).
         a(1).

     :- end_object.

After compiling and loading the ‘main’ object, we can define other
objects (or categories) that contribute with clauses for the multifile
predicate.  For example:

     :- object(other).

         :- multifile(main::a/1).
         main::a(2).
         main::a(X) :-
             b(X).

         b(3).
         b(4).

     :- end_object.

After compiling and loading the above objects, you can use queries such
as:

     | ?- main::a(X).

     X = 1 ;
     X = 2 ;
     X = 3 ;
     X = 4
     yes

Note that the order of multifile predicate clauses depends on several
factors, including loading order and compiler implementation details.
Therefore, your code should never assume or rely on a specific order of
the multifile predicate clauses.

When a clause of a multifile predicate is a rule, its body is compiled
within the context of the object or category defining the clause.  This
allows clauses for multifile predicates to call local object or category
predicates.  But the values of the 'sender', 'this', and 'self' in the
implicit execution context are passed from the clause head to the clause
body.  This is necessary to ensure that these values are always valid
and to allow multifile predicate clauses to be defined in categories.  A
call to the ‘parameter/2’ execution context methods, however, retrieves
parameters of the entity defining the clause, not from the entity for
which the clause is defined.  The parameters of the entity for which the
clause is defined can be accessed by simple unification at the clause
head.

Multifile predicate rules should not contain cuts, as these may prevent
other clauses for the predicate from being used by callers.  The
compiler prints by default a warning when a cut is found in a multifile
predicate definition.

Local calls to the database methods from multifile predicate clauses
defined in an object take place in the object’s own database instead of
the database of the entity holding the multifile predicate primary
declaration.  Similarly, local calls to the ‘expand_term/2’ and
‘expand_goal/2’ methods from a multifile predicate clause look for
clauses of the ‘term_expansion/2’ and ‘goal_expansion/2’ hook predicates
starting from the entity defining the clause instead of the entity
holding the multifile predicate primary declaration.  Local calls to the
‘current_predicate/1’, ‘predicate_property/2’, and ‘current_op/3’
methods from multifile predicate clauses defined in an object also
lookup predicates and their properties in the object’s own database
instead of the database of the entity holding the multifile predicate
primary declaration.


File: TheLogtalkHandbook-3.101.0.info,  Node: Coinductive directive,  Next: Synchronized directive,  Prev: Multifile directive,  Up: Declaring predicates

1.8.2.11 Coinductive directive
..............................

A predicate can be declared *note coinductive: 170. by using the *note
coinductive/1: 171. directive.  For example:

     :- coinductive(comember/2).

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


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

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

A predicate can be declared *note synchronized: 175. by using the *note
synchronized/1: 74. directive.  For example:

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

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


File: TheLogtalkHandbook-3.101.0.info,  Node: Defining predicates,  Next: Definite clause grammar rules,  Prev: Declaring predicates,  Up: Predicates

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

* Menu:

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


File: TheLogtalkHandbook-3.101.0.info,  Node: Object predicates,  Next: Category predicates,  Up: Defining predicates

1.8.3.1 Object predicates
.........................

We define object predicates as we have always defined Prolog predicates,
the only difference being that we have four more control structures (the
three message-sending operators plus the external call operator) to play
with.  For example, if we wish to define an object containing common
utility list predicates like ‘append/2’ or ‘member/2’ we could write
something like:

     :- object(list).

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

         :- public(member/2).
         member(H, [H| _]).
         member(H, [_| T]) :-
             member(H, T).

     :- end_object.

Note that, abstracting from the opening and closing object directives
and the scope directives, what we have written is also valid Prolog
code.  Calls in a predicate definition body default to the local
predicates unless we use the message-sending operators or the external
call operator.  This simplifies conversion from plain Prolog code to
Logtalk objects: often we just need to add the necessary encapsulation
and scope directives to the old code.


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

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

A category can only contain clauses for static predicates.  But there
are no restrictions in declaring and calling dynamic predicates from
inside a category.  Because a category can be imported by multiple
objects, dynamic predicates must be called either in the context of
*note self: 69, using the *note message to self: 17d. control structure,
*note (;;)/1: 5c, or in the context of *note this: 114. (i.e., in the
context of the object importing the category).  For example, if we want
to define a category implementing attributes using the dynamic database
of 'self' we could write:

     :- category(attributes).

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

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

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

         set(Var, Value) :-
             ::retractall(attribute_(Var, _)),
             ::asserta(attribute_(Var, Value).

     :- end_category.

In this case, the ‘get/2’ and ‘set/2’ predicates will always
access/update the correct definition, contained in the object receiving
the messages.

In alternative, if we want a category implementing attributes using the
dynamic database of 'this', we would write instead:

     :- category(attributes).

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

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

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

         set(Var, Value) :-
             retractall(attribute_(Var, _)),
             asserta(attribute_(Var, Value).

     :- end_category.

In this case, each object importing the category will have its own
clauses for the ‘attribute_/2’ private dynamic predicate.


File: TheLogtalkHandbook-3.101.0.info,  Node: Meta-predicates,  Next: Lambda expressions,  Prev: Category predicates,  Up: Defining predicates

1.8.3.3 Meta-predicates
.......................

Meta-predicates may be defined inside objects and categories as any
other predicate.  A meta-predicate is declared using the *note
meta_predicate/1: 152. directive as described earlier in this section.
When defining a meta-predicate, the arguments in the clause heads
corresponding to the meta-arguments must be variables.  All
meta-arguments are called in the context of the object or category
calling the meta-predicate.  In particular, when sending a message that
corresponds to a meta-predicate, the meta-arguments are called in the
context of the object or category sending the message.

The most simple example is a meta-predicate with a meta-argument that is
called as a goal.  E.g.  the *note ignore/1: 180. built-in predicate
could be defined as:

     :- public(ignore/1).
     :- meta_predicate(ignore(0)).

     ignore(Goal) :-
        (Goal -> true; true).

The ‘0’ in the meta-predicate template tells us that the meta-argument
is a goal that will be called by the meta-predicate.

Some meta-predicates have meta-arguments that are not goals but *note
closures: 14f.  Logtalk supports the definition of meta-predicates that
are called with closures instead of goals as long as the definition uses
the *note call/1-N: 181. built-in predicate to call the closure with the
additional arguments.  A classical example is a list mapping predicate:

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

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

Note that in this case the meta-predicate directive specifies that the
closure will be extended with exactly one additional argument.  When
calling a meta-predicate, a closure can correspond to a user-defined
predicate, a built-in predicate, a *note lambda expression: 182, or a
control construct.

In some cases, it is not a meta-argument but one of its sub-terms that
is called as a goal or used as a closure.  For example:

     :- public(call_all/1).
     :- meta_predicate(call_all(::)).

     call_all([]).
     call_all([Goal| Goals]) :-
         call(Goal),
         call_all(Goals).

The ‘::’ mode indicator in the meta-predicate template allows the
corresponding argument in the meta-predicate definition to be a
non-variable term and instructs the compiler to look into the argument
sub-terms for goal and closure *note meta-variables: 183.

When a meta-predicate calls another meta-predicate, both predicates
require ‘meta_predicate/1’ directives.  For example, the ‘map/2’
meta-predicate defined above is usually implemented by exchanging the
argument order to take advantage of first-argument indexing:

     :- meta_predicate(map(1, *)).
     map(Closure, List) :-
         map_(List, Closure).

     :- meta_predicate(map_(*, 1)).
     map_([], _).
     map_([Head| Tail], Closure) :-
         call(Closure, Head),
         map_(Tail, Closure).

Note that Logtalk, unlike most Prolog module systems, is not based on a
predicate prefixing mechanism.  Thus, the meta-argument calling context
is not part of the meta-argument itself.


File: TheLogtalkHandbook-3.101.0.info,  Node: Lambda expressions,  Next: Redefining built-in predicates,  Prev: Meta-predicates,  Up: Defining predicates

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

The use of lambda expressions(1) as meta-predicate goal and *note
closure: 14f. arguments often saves writing auxiliary predicates for the
sole purpose of calling the meta-predicates.  A simple example of a
lambda expression is:

     | ?- meta::map([X,Y]>>(Y is 2*X), [1,2,3], Ys).
     Ys = [2,4,6]
     yes

In this example, a lambda expression, ‘[X,Y]>>(Y is 2*X)’, is used as an
argument to the ‘map/3’ list mapping predicate, defined in the library
object ‘meta’, in order to double the elements of a list of integers.
Using a lambda expression avoids writing an auxiliary predicate for the
sole purpose of doubling the list elements.  The 'lambda parameters' are
represented by the list ‘[X,Y]’, which is connected to the 'lambda
goal', ‘(Y is 2*X)’, by the ‘(>>)/2’ operator.  The ‘map/3’ predicate
calls the lambda goal with fresh/unique variables, represented by the
‘X’ and ‘Y’ parameters, for each pair of elements of the second and
third list arguments.

Currying is supported.  I.e.  it is possible to write a lambda
expression whose goal is another lambda expression.  The above example
can be rewritten as:

     | ?- meta::map([X]>>([Y]>>(Y is 2*X)), [1,2,3], Ys).
     Ys = [2,4,6]
     yes

Lambda expressions may also contain 'lambda-free variables'.  I.e.
variables that are global to the lambda expression and shared with the
surrounding meta-call context.  Consider the following variant of the
previous example:

     | ?- between(1, 3, N), meta::map({N}/[X,Y]>>(Y is N*X), [1,2,3], L).
     N = 1, L = [1,2,3] ;
     N = 2, L = [2,4,6] ;
     N = 3, L = [3,6,9]
     yes

In this case, the lambda-free variable, ‘N’, bound by the ‘between/3’
goal, is fixed across all implicit calls made by the ‘map/3’ goal.

A second example of free variables in a lambda expression using GNU
Prolog as the backend compiler:

     | ?- meta::map({Z}/[X,Y]>>(Z#=X+Y), [1,2,3], Zs).
     Z = _#22(3..268435455)
     Zs = [_#3(2..268435454),_#66(1..268435453),_#110(0..268435452)]
     yes

The ISO Prolog construct ‘{}/1’ is used for representing the lambda-free
variables as this representation is often associated with set
representation.  Note that the order of the free variables is of no
consequence (on the other hand, a list is used for the lambda parameters
as their order does matter).

Both lambda free variables and lambda parameters can be any Prolog term.
Consider the following example by Markus Triska:

     | ?- meta::map([A-B,B-A]>>true, [1-a,2-b,3-c], Zs).
     Zs = [a-1,b-2,c-3]
     yes

Lambda expressions can be used, as expected, in non-deterministic
queries, as in the following example using SWI-Prolog as the backend
compiler and Markus Triska’s CLP(FD) library:

     | ?- meta::map({Z}/[X,Y]>>(clpfd:(Z#=X+Y)), Xs, Ys).
     Xs = [],
     Ys = [] ;
     Xs = [_G1369],
     Ys = [_G1378],
     _G1369+_G1378#=Z ;
     Xs = [_G1579, _G1582],
     Ys = [_G1591, _G1594],
     _G1582+_G1594#=Z,
     _G1579+_G1591#=Z ;
     Xs = [_G1789, _G1792, _G1795],
     Ys = [_G1804, _G1807, _G1810],
     _G1795+_G1810#=Z,
     _G1792+_G1807#=Z,
     _G1789+_G1804#=Z ;
     ...

As illustrated by the above examples, lambda expression syntax reuses
the ISO Prolog construct ‘{}/1’ and the standard operators ‘(/)/2’ and
‘(>>)/2’, thus avoiding defining new operators, which is always tricky
for a portable system such as Logtalk.  The operator ‘(>>)/2’ was chosen
as it suggests an arrow, similar to the syntax used in other languages
such as OCaml and Haskell to connect lambda parameters with lambda
functions.  This syntax was also chosen in order to simplify parsing,
error checking, and compilation of lambda expressions.  The full
specification of the lambda expression syntax can be found in the *note
language grammar: 185.

The compiler checks whenever possible that all variables in a lambda
expression are either classified as free variables or as lambda
parameters.  Non-classified variables in a lambda goal (including any
anonymous variables) should be regarded as a programming error.  The
compiler also checks whenever possible if a variable is classified as
both a free variable and a lambda parameter.  There are a few cases
where a variable playing a dual role is intended, but, in general, this
also results from a programming error.  A third check verifies that no
lambda parameter variable is used elsewhere in a clause.  Such cases are
either programming errors, when the variable appears before the lambda
expression, or bad programming style, when the variable is used after
the lambda expression.  These linter warnings are controlled by the
*note lambda_variables: 186. flag.  Note that the dynamic features of
the language and lack of sufficient information at compile-time may
prevent the compiler from checking all uses of lambda expressions.  To
improve linter coverage, compile code using lambda expressions with the
*note optimize flag: 8c. turned on, as that will result in additional
cases of meta-arguments being evaluated for possible optimizations.

     Warning: Variables listed in lambda parameters must not be shared
     with other goals in a clause.

An optimizing meta-predicate and lambda expression compiler, based on
the *note term-expansion mechanism: cb, is provided as a standard
library for practical performance.

A common use of lambda expressions as closure meta-arguments is to
workaround closures always being extended by 'appending' additional
arguments to construct a goal.  For example, assume that we want to
filter a list of atoms by a given length.  We can use the standard
‘atom_length/2’ predicate despite the argument order by writing:

     filter(Length, Atoms, Filtered) :-
         meta::include({Length}/[Atom]>>atom_length(Atom,Length), Atoms, Filtered).

But Logtalk supports a faster alternative by using predicate aliases to
change the argument order when calling library or built-in predicates:

     :- uses(user, [
        atom_length(Atom, Length) as length_atom(Length, Atom)
     ]).

     filter(Length, Atoms, Filtered) :-
         meta::include(length_atom(Length), Atoms, Filtered).

In this case, the performance is no longer dependent on compiling away
lambda expressions.  The resulting code is also easier to read (and thus
debug and maintain).  But the ‘uses/2’ directive is implicitly defining
an auxiliary predicate, which is exactly what we wanted to avoid in the
first place by using a lambda expression.

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

   (1) https://en.wikipedia.org/wiki/Lambda_calculus


File: TheLogtalkHandbook-3.101.0.info,  Node: Redefining built-in predicates,  Prev: Lambda expressions,  Up: Defining predicates

1.8.3.5 Redefining built-in predicates
......................................

Logtalk built-in predicates and Prolog built-in predicates can be
redefined inside objects and categories.  Although the redefinition of
Logtalk built-in predicates should be avoided, the support for
redefining Prolog built-in predicates is a practical requirement given
the different sets of proprietary built-in predicates provided by
backend Prolog systems.

The compiler supports a *note redefined_built_ins: 189. flag, whose
default value is ‘silent’, that can be set to ‘warning’ to alert the
user of any redefined Logtalk or Prolog built-in predicate.

The redefinition of Prolog built-in predicates can be combined with the
*note conditional compilation directives: 18a. when writing portable
applications where some of the supported backends don’t provide a
built-in predicate found in the other backends.  As an example, consider
the de facto standard ‘msort/2’ predicate (which sorts a list while
keeping duplicates).  This predicate is provided as a built-in predicate
in most but not all backends.  The ‘list’ library object includes the
code:

     :- if(predicate_property(msort(_, _), built_in)).

         msort(List, Sorted) :-
             {msort(List, Sorted)}.

     :- else.

         length(List, Length) :-
             ...

     :- endif.

I.e.  the object will use the built-in predicate when available.
Otherwise, it will use the predicate definition provided by the ‘list’
object.

The redefinition of built-in predicates can also be accomplished using
*note predicate shorthands: 161.  This can be useful when porting code
while minimizing the changes.  For example, assume that existing code
uses the ‘format/2’ de facto standard predicate for writing messages.
To convert the code to use the *note message printing mechanism: 18b, we
could write:

     :- uses(logtalk, [
         print_message(comment, core, Format+Arguments) as format(Format, Arguments)
     ]).

     process(Crate, Contents) :-
         format('Processing crate ~w...', [Crate]),
         ...,
         format('Filing with ~w...', [Contents]),
         ....

The predicate shorthand instructs the compiler to rewrite all ‘format/2’
goals as ‘logtalk::print_message/3’ goals, thus allowing us to reuse the
code without changes.


File: TheLogtalkHandbook-3.101.0.info,  Node: Definite clause grammar rules,  Next: Built-in methods,  Prev: Defining predicates,  Up: Predicates

1.8.4 Definite clause grammar rules
-----------------------------------

Definite clause grammar rules (DCGs) provide a convenient notation to
represent the parsing and rewrite rules common of most grammars in
Prolog.  In Logtalk, definite clause grammar rules can be encapsulated
in objects and categories.  Currently, the ISO/IEC WG17 group is working
on a draft specification for a definite clause grammars Prolog standard.
Therefore, in the meantime, Logtalk follows the common practice of
Prolog compilers supporting definite clause grammars, extending it to
support calling grammar rules contained in categories and objects.  A
common example of a definite clause grammar is the definition of a set
of rules for parsing simple arithmetic expressions:

     :- object(calculator).

         :- public(parse/2).

         parse(Expression, Value) :-
             phrase(expr(Value), Expression).

         expr(Z) --> term(X), "+", expr(Y), {Z is X + Y}.
         expr(Z) --> term(X), "-", expr(Y), {Z is X - Y}.
         expr(X) --> term(X).

         term(Z) --> number(X), "*", term(Y), {Z is X * Y}.
         term(Z) --> number(X), "/", term(Y), {Z is X / Y}.
         term(Z) --> number(Z).

         number(C) --> "+", number(C).
         number(C) --> "-", number(X), {C is -X}.
         number(X) --> [C], {0'0 =< C, C =< 0'9, X is C - 0'0}.

     :- end_object.

After compiling and loading this object, we can test the grammar rules
using the ‘parse/2’ message:

     | ?- calculator::parse("1+2-3*4", Result).

     Result = -9
     yes

The non-terminals can be called from predicates using the private
built-in methods *note phrase/2: 18e. and *note phrase/3: 18f. as shown
in the example above.  When we want to use the built-in methods
‘phrase/2’ and ‘phrase/3’, the non-terminal used as in the first
argument must be within the scope of the 'sender'.  For the above
example, assuming that we want the predicate corresponding to the
‘expr//1’ non-terminal to be public, the corresponding scope directive
would be:

     :- public(expr//1).

The ‘//’ infix operator used above tells the Logtalk compiler that the
scope directive refers to a grammar rule non-terminal, not to a
predicate.  The idea is that the predicate corresponding to the
translation of the ‘expr//1’ non-terminal will have a number of
arguments equal to one plus the number of additional arguments necessary
for processing the implicit difference list of tokens.

In the body of a grammar rule, we can call rules that are inherited from
ancestor objects, imported from categories, or contained in other
objects.  This is accomplished by using non-terminals as messages.
Using a non-terminal as a message to 'self' allows us to call grammar
rules in categories and ancestor objects.  To call grammar rules
encapsulated in other objects, we use a non-terminal as a message to
those objects.  Consider the following example, containing grammar rules
for parsing natural language sentences:

     :- object(sentence,
         imports(determiners, nouns, verbs)).

         :- public(parse/2).

         parse(List, true) :-
             phrase(sentence, List).
         parse(_, false).

         sentence --> noun_phrase, verb_phrase.

         noun_phrase --> ::determiner, ::noun.
         noun_phrase --> ::noun.

         verb_phrase --> ::verb.
         verb_phrase --> ::verb, noun_phrase.

     :- end_object.

The categories imported by the object would contain the necessary
grammar rules for parsing determiners, nouns, and verbs.  For example:

     :- category(determiners).

         :- private(determiner//0).

         determiner --> [the].
         determiner --> [a].

     :- end_category.

Along with the message-sending operators (‘(::)/1’, ‘(::)/2’, and
‘(^^)/1’), we may also use other control constructs such as ‘(<<)/2’,
‘(\+)/1’, ‘!/0’, ‘(;)/2’, ‘(->)/2’, ‘{}/1’, ‘call//1-N’, and ‘catch/3’
in the body of a grammar rule.  When using a backend Prolog compiler
that supports modules, we may also use the ‘(:)/2’ control construct.

     Warning: The semantics of ‘(\+)/1’ and ‘(->)/2’ control constructs
     in grammar rules with a terminal or a non-terminal in the 'first'
     argument are problematic due to unrestricted lookahead that may or
     may not be valid depending on the grammar rule implicit arguments.
     By default, the linter will print warnings for such calls
     (controlled by the *note grammar_rules: 190. flag).  Preferably
     restrict the use of the ‘(\+)/1’ control construct to ‘{}/1’
     arguments and the use of the ‘(->)/2’ control construct to ‘{}/1’
     test arguments.

In addition, grammar rules may contain meta-calls (a variable taking the
place of a non-terminal), which are translated to calls of the built-in
method ‘phrase//1’.  The *note meta_non_terminal/1: 153. directive
allows the declaration of non-terminals that have arguments that are
meta-called from grammar rules.  For example:

     :- meta_non_terminal(zero_or_more(1, *)).

     zero_or_more(Closure, [Terminal| Terminals]) -->
         call(Closure, Terminal), !, zero_or_more(Closure, Terminals).
     zero_or_more(_, []) -->
         [].

You may have noticed that Logtalk defines *note {}/1: 191. as a control
construct for bypassing the compiler when compiling a clause body goal.
As exemplified above, this is the same control construct that is used in
grammar rules for bypassing the expansion of rule body goals when a rule
is converted into a clause.  Both control constructs can be combined in
order to call a goal from a grammar rule body, while bypassing at the
same time the Logtalk compiler.  Consider the following example:

     bar :-
         write('bar predicate called'), nl.


     :- object(bypass).

         :- public(foo//0).

         foo --> {{bar}}.

     :- end_object.

After compiling and loading this code, we may try the following query:

     | ?- logtalk << phrase(bypass::foo, _, _).

     bar predicate called
     yes

This is the expected result, as the expansion of the grammar rule into a
clause leaves the ‘{bar}’ goal untouched, which, in turn, is converted
into the goal ‘bar’ when the clause is compiled.  Note that we tested
the ‘bypass::foo//0’ non-terminal by calling the ‘phrase/3’ built-in
method in the context of the ‘logtalk’ built-in object.  This workaround
is necessary due to the Prolog backend implementation of the ‘phrase/3’
predicate not being aware of the Logtalk ‘(::)/2’ message-sending
control construct semantics.

A grammar rule non-terminal may be declared as dynamic or discontiguous,
as any object predicate, using the same ‘Name//Arity’ notation
illustrated above for the scope directives.  In addition, grammar rule
non-terminals can be documented using the *note info/2: 168. directive,
as in the following example:

     :- public(sentence//0).

     :- info(sentence//0, [
         comment is 'Rewrites sentence into noun and verb phrases.'
     ]).

     Note: Future Logtalk versions may compile grammar rules differently
     from Prolog traditional compilation to prevent name clashes between
     non-terminals and predicates.  Therefore, you should always call
     non-terminals from predicates using the ‘phrase/2-3’ built-in
     methods and always call predicates from grammar rules using the
     ‘call//1’ built-in method.  This recommended practice, besides
     making your code forward compatible with future Logtalk versions,
     also makes the code more clear.  The linter prints warnings when
     these guidelines are not followed (notably, when a predicate is
     called as a non-terminal or a non-terminal is called as a
     predicate).


File: TheLogtalkHandbook-3.101.0.info,  Node: Built-in methods,  Next: Predicate properties,  Prev: Definite clause grammar rules,  Up: Predicates

1.8.5 Built-in methods
----------------------

Built-in methods are built-in object and category predicates.  These
include methods to access message execution context, to find sets of
solutions, to inspect objects, for database handling, for term and goal
expansion, and for printing messages.  Some of them are counterparts to
standard Prolog built-in predicates that take into account Logtalk
semantics.  Similar to Prolog built-in predicates, built-in methods
cannot be redefined.

* Menu:

* Logic and control methods::
* Execution context methods::
* Error handling and throwing methods::
* Database methods::
* Meta-call methods::
* All solutions methods::
* Reflection methods::
* Definite clause grammar parsing methods and non-terminals::


File: TheLogtalkHandbook-3.101.0.info,  Node: Logic and control methods,  Next: Execution context methods,  Up: Built-in methods

1.8.5.1 Logic and control methods
.................................

The *note !/0: 196, *note true/0: 197, *note fail/0: 198, *note false/0:
199, and *note repeat/0: 19a. standard control constructs and logic
predicates are interpreted as built-in public methods and thus can be
used as messages to any object.  In practice, they are only used as
messages when sending multiple messages to the same object (see the
section on *note message broadcasting: 84.).


File: TheLogtalkHandbook-3.101.0.info,  Node: Execution context methods,  Next: Error handling and throwing methods,  Prev: Logic and control methods,  Up: Built-in methods

1.8.5.2 Execution context methods
.................................

Logtalk defines five built-in private methods to access an object
execution context.  These methods are in the common usage scenarios
translated to a single unification performed at compile-time with a
clause head context argument.  Therefore, they can be freely used
without worrying about performance penalties.  When called from inside a
category, these methods refer to the execution context of the object
importing the category.  These methods are private and cannot be used as
messages to objects.

To find the object that received the message under execution, we may use
the *note self/1: 67. method.  We may also retrieve the object that has
sent the message under execution using the *note sender/1: 19d. method.

The method *note this/1: 68. enables us to retrieve the name of the
object for which the predicate clause whose body is being executed is
defined instead of using the name directly.  This helps to avoid
breaking the code if we decide to change the object name and forget to
change the name references.  This method may also be used from within a
category.  In this case, the method returns the object importing the
category on whose behalf the predicate clause is being executed.

Here is a short example including calls to these three object execution
context methods:

     :- object(test).

         :- public(test/0).

         test :-
             this(This),
             write('Calling predicate definition in '),
             writeq(This), nl,
             self(Self),
             write('to answer a message received by '),
             writeq(Self), nl,
             sender(Sender),
             write('that was sent by '),
             writeq(Sender), nl, nl.

     :- end_object.


     :- object(descendant,
         extends(test)).

     :- end_object.

After compiling and loading these two objects, we can try the following
goal:

     | ?- descendant::test.

     Calling predicate definition in test
     to answer a message received by descendant
     that was sent by user
     yes

Note that the goals ‘self(Self)’, ‘sender(Sender)’, and ‘this(This)’,
being translated to unifications with the clause head context arguments
at compile-time, are effectively removed from the clause body.
Therefore, a clause such as:

     predicate(Arg) :-
         self(Self),
         atom(Arg),
         ... .

is compiled with the goal ‘atom(Arg)’ as the first condition on the
clause body.  As such, the use of these context execution methods does
not interfere with the optimizations that some Prolog compilers perform
when the first clause body condition is a call to a built-in type-test
predicate or a comparison operator.

For parametric objects and categories, the method *note parameter/2: a2.
enables us to retrieve current parameter values (see the section on
*note parametric objects: 66. for a detailed description).  For example:

     :- object(block(_Color)).

         :- public(test/0).

         test :-
             parameter(1, Color),
             write('Color parameter value is '),
             writeq(Color), nl.

     :- end_object.

An alternative to the ‘parameter/2’ predicate is to use *note parameter
variables: a1.:

     :- object(block(_Color_)).

         :- public(test/0).

         test :-
             write('Color parameter value is '),
             writeq(_Color_), nl.

     :- end_object.

After compiling and loading either version of the object, we can try the
following goal:

     | ?- block(blue)::test.

     Color parameter value is blue
     yes

Calls to the ‘parameter/2’ method are translated to a compile-time
unification when the second argument is a variable.  When the second
argument is bound, the calls are translated to a call to the built-in
predicate ‘arg/3’.

When type-checking predicate arguments, it is often useful to include
the predicate execution context when reporting an argument error.  The
*note context/1: 19e. method provides access to that context.  For
example, assume a predicate ‘foo/2’ that takes an atom and an integer as
arguments.  We could type-check the arguments by writing (using the
library ‘type’ object):

     foo(A, N) :-
         % type-check arguments
         context(Context),
         type::check(atom, A, Context),
         type::check(integer, N, Context),
         % arguments are fine; go ahead
         ... .


File: TheLogtalkHandbook-3.101.0.info,  Node: Error handling and throwing methods,  Next: Database methods,  Prev: Execution context methods,  Up: Built-in methods

1.8.5.3 Error handling and throwing methods
...........................................

Besides the *note catch/3: 1a1. and *note throw/1: 1a2. methods
inherited from Prolog, Logtalk also provides a set of convenience
methods to throw standard ‘error/2’ exception terms: *note
instantiation_error/0: 1a3, *note uninstantiation_error/1: 1a4, *note
type_error/2: 1a5, *note domain_error/2: 1a6, *note existence_error/2:
1a7, *note permission_error/3: 1a8, *note representation_error/1: 1a9,
*note evaluation_error/1: 1aa, *note resource_error/1: 1ab, *note
syntax_error/1: 1ac, and *note system_error/0: 1ad.  When using these
methods, the second argument of the ‘error/2’ exception term is bound to
the execution context (as it would be provided by the *note context/1:
19e. method).


File: TheLogtalkHandbook-3.101.0.info,  Node: Database methods,  Next: Meta-call methods,  Prev: Error handling and throwing methods,  Up: Built-in methods

1.8.5.4 Database methods
........................

Logtalk provides a set of built-in methods for *note object database:
1b0. handling similar to the usual database Prolog predicates: *note
abolish/1: 1b1, *note asserta/1: 1b2, *note assertz/1: 1b3, *note
clause/2: 1b4, *note retract/1: 1b5, and *note retractall/1: 1b6.  These
methods always operate on the database of the object receiving the
corresponding message.  When called locally, these predicates take into
account any *note uses/2: 4b. or *note use_module/2: 4d. directives that
refer to the dynamic predicate being handled.  For example, in the
following object, the clauses for the ‘data/1’ predicate are retracted
and asserted in ‘user’ due to the ‘uses/2’ directive:

     :- object(an_object).

         :- uses(user, [data/1]).

         :- public(some_predicate/1).
         some_predicate(Arg) :-
             retractall(data(_)),
             assertz(data(Arg)).

     :- end_object.

When working with dynamic grammar rule non-terminals, you may use the
built-in method *note expand_term/2: 1b7. convert a grammar rule into a
clause that can then be used with the database methods.

Logtalk also supports ‘asserta/2’, ‘assertz/2’, ‘clause/3’, and
‘erase/1’ built-in methods when run with a backend that supports the
corresponding legacy built-in predicates that work with *note clause
references: 1b8.


File: TheLogtalkHandbook-3.101.0.info,  Node: Meta-call methods,  Next: All solutions methods,  Prev: Database methods,  Up: Built-in methods

1.8.5.5 Meta-call methods
.........................

Logtalk supports the generalized *note call/1-N: 181. meta-predicate.
This built-in private meta-predicate must be used in the implementation
of meta-predicates that work with *note closures: 14f. instead of goals.
In addition, Logtalk supports the built-in private meta-predicates *note
ignore/1: 180, *note once/1: 1bb, and *note (\+)/1: 1bc.  These methods
cannot be used as messages to objects.


File: TheLogtalkHandbook-3.101.0.info,  Node: All solutions methods,  Next: Reflection methods,  Prev: Meta-call methods,  Up: Built-in methods

1.8.5.6 All solutions methods
.............................

The usual all solutions meta-predicates are built-in private methods in
Logtalk: *note bagof/3: 1bf, *note findall/3: 1c0, *note findall/4: 1c1,
and *note setof/3: 1c2.  There is also a *note forall/2: 1c3. method
that implements generate-and-test loops.  These methods cannot be used
as messages to objects.


File: TheLogtalkHandbook-3.101.0.info,  Node: Reflection methods,  Next: Definite clause grammar parsing methods and non-terminals,  Prev: All solutions methods,  Up: Built-in methods

1.8.5.7 Reflection methods
..........................

Logtalk provides a comprehensive set of built-in predicates and built-in
methods for querying about entities and predicates.  Some of the
information, however, requires that the source files are compiled with
the *note source_data: cc. flag turned on.

The *note reflection API: 48. supports two different views on entities
and their contents, which we may call the 'transparent box view' and the
'black box view'.  In the transparent box view, we look into an entity
disregarding how it will be used and returning all information available
on it, including predicate declarations and predicate definitions.  This
view is supported by the entity property built-in predicates.  In the
black box view, we look into an entity from a usage point of view using
built-in methods for inspecting object operators and predicates that are
within scope from where we are making the call: *note current_op/3: 15e,
which returns operator specifications; *note predicate_property/2: 142,
which returns predicate properties; and *note current_predicate/1: 141,
which enables us to query about user-defined predicate definitions.  See
below for a more detailed description of these methods.


File: TheLogtalkHandbook-3.101.0.info,  Node: Definite clause grammar parsing methods and non-terminals,  Prev: Reflection methods,  Up: Built-in methods

1.8.5.8 Definite clause grammar parsing methods and non-terminals
.................................................................

Logtalk supports two definite clause grammar parsing built-in private
methods, *note phrase/2: 18e. and *note phrase/3: 18f, with definitions
similar to the predicates with the same name found on most Prolog
compilers that support definite clause grammars.  These methods cannot
be used as messages to objects.

Logtalk also supports *note phrase//1: 1c8, *note call//1-N: 1c9, and
*note eos//0: 1ca. built-in non-terminals.  The ‘call//1-N’
non-terminals take a *note closure: 14f. (which can be a lambda
expression) plus zero or more additional arguments and are processed by
appending the input list of tokens and the list of remaining tokens to
the arguments.


File: TheLogtalkHandbook-3.101.0.info,  Node: Predicate properties,  Next: Finding declared predicates,  Prev: Built-in methods,  Up: Predicates

1.8.6 Predicate properties
--------------------------

We can find the properties of visible predicates by calling the *note
predicate_property/2: 142. built-in method.  For example:

     | ?- bar::predicate_property(foo(_), Property).

Note that this method takes into account the predicate’s scope
declarations.  In the above example, the call will only return
properties for public predicates.

An object’s set of visible predicates is the union of all the predicates
declared for the object with all the built-in methods and all the
Logtalk and Prolog built-in predicates.

The following predicate properties are supported:

‘scope(Scope)’

     The predicate scope (useful for finding the predicate scope with a
     single call to ‘predicate_property/2’)

‘public’, ‘protected’, ‘private’

     The predicate scope (useful for testing if a predicate has a
     specific scope)

‘static’, ‘dynamic’

     All predicates are either static or dynamic (note, however, that a
     dynamic predicate can only be abolished if it was dynamically
     declared)

‘logtalk’, ‘prolog’, ‘foreign’

     A predicate can be defined in Logtalk source code, Prolog code, or
     in foreign code (e.g., in C)

‘built_in’

     The predicate is a built-in predicate

‘multifile’

     The predicate is declared multifile (i.e., it can have clauses
     defined in multiple files or entities)

‘meta_predicate(Template)’

     The predicate is declared as a meta-predicate with the specified
     template

‘coinductive(Template)’

     The predicate is declared as a coinductive predicate with the
     specified template

‘declared_in(Entity)’

     The predicate is declared (using a scope directive) in the
     specified entity

‘defined_in(Entity)’

     The predicate definition is looked up in the specified entity (note
     that this property does not necessarily imply that clauses for the
     predicate exist in ‘Entity’; the predicate can simply be false as
     per the *note closed-world assumption: 6a.)

‘redefined_from(Entity)’

     The predicate is a redefinition of a predicate definition inherited
     from the specified entity

‘non_terminal(NonTerminal//Arity)’

     The predicate resulted from the compilation of the specified
     grammar rule non-terminal

‘alias_of(Predicate)’

     The predicate (name) is an alias for the specified predicate

‘alias_declared_in(Entity)’

     The predicate alias is declared in the specified entity

‘synchronized’

     The predicate is declared as synchronized (i.e., it’s a
     deterministic predicate synchronized using a mutex when using a
     backend Prolog compiler supporting a compatible multi-threading
     implementation)

Some properties are only available when the entities are defined in
source files and when those source files are compiled with the *note
source_data: cc. flag turned on:

‘recursive’

     The predicate definition includes at least one recursive rule

‘inline’

     The predicate definition is inlined

‘auxiliary’

     The predicate is not user-defined but rather automatically
     generated by the compiler or the *note term-expansion mechanism:
     cb.

‘mode(Mode, Solutions)’

     Instantiation, type, and determinism mode for the predicate (which
     can have multiple modes)

‘info(ListOfPairs)’

     Documentation key-value pairs as specified in the user-defined
     ‘info/2’ directive

‘number_of_clauses(N)’

     The number of clauses for the predicate existing at compilation
     time (note that this property is not updated at runtime when
     asserting and retracting clauses for dynamic predicates)

‘number_of_rules(N)’

     The number of rules for the predicate existing at compilation time
     (note that this property is not updated at runtime when asserting
     and retracting clauses for dynamic predicates)

‘declared_in(Entity, Line)’

     The predicate is declared (using a scope directive) in the
     specified entity in a source file at the specified line (if
     applicable)

‘defined_in(Entity, Line)’

     The predicate is defined in the specified entity in a source file
     at the specified line (if applicable)

‘redefined_from(Entity, Line)’

     The predicate is a redefinition of a predicate definition inherited
     from the specified entity, which is defined in a source file at the
     specified line (if applicable)

‘alias_declared_in(Entity, Line)’

     The *note predicate alias: ca. is declared in the specified entity
     in a source file at the specified line (if applicable)

The properties ‘declared_in/1-2’, ‘defined_in/1-2’, and
‘redefined_from/1-2’ do not apply to built-in methods and Logtalk or
Prolog built-in predicates.  Note that if a predicate is declared in a
category imported by the object, it will be the category name — not the
object name — that will be returned by the property ‘declared_in/1’.
The same is true for protocol declared predicates.

Some properties, such as line numbers, are only available when the
entity holding the predicates is defined in a source file compiled with
the *note source_data: cc. flag turned on.  Moreover, line numbers are
only supported in *note backend Prolog compilers: 34. that provide
access to the start line of a read term.  When such support is not
available, the value ‘-1’ is returned for the start and end lines.


File: TheLogtalkHandbook-3.101.0.info,  Node: Finding declared predicates,  Next: Calling Prolog predicates,  Prev: Predicate properties,  Up: Predicates

1.8.7 Finding declared predicates
---------------------------------

We can find, by backtracking, all visible user predicates by calling the
*note current_predicate/1: 141. built-in method.  This method takes into
account predicate scope declarations.  For example, the following call
will only return user predicates that are declared public:

     | ?- some_object::current_predicate(Name/Arity).

The predicate property ‘non_terminal/1’ may be used to retrieve all
grammar rule non-terminals declared for an object.  For example:

     current_non_terminal(Object, Name//Args) :-
         Object::current_predicate(Name/Arity),
         functor(Predicate, Functor, Arity),
         Object::predicate_property(Predicate, non_terminal(Name//Args)).

Usually, the non-terminal and the corresponding predicate share the same
functor, but users should not rely on this always being true.


File: TheLogtalkHandbook-3.101.0.info,  Node: Calling Prolog predicates,  Next: Defining Prolog multifile predicates,  Prev: Finding declared predicates,  Up: Predicates

1.8.8 Calling Prolog predicates
-------------------------------

Logtalk is designed for both 'robustness' and 'portability'.  In the
context of calling Prolog predicates, robustness requires that the
compilation of Logtalk source code must not have 'accidental'
dependencies on Prolog code that happens to be loaded at the time of the
compilation.  One immediate consequence is that only Prolog 'built-in'
predicates are visible from within objects and categories.  But Prolog
systems provide a widely diverse set of built-in predicates, easily
raising portability issues.  Relying on non-standard predicates is often
unavoidable, however, due to the narrow scope of Prolog standards.
Logtalk applications may also require calling user-defined Prolog
predicates, either in ‘user’ or in Prolog modules.

* Menu:

* Calling Prolog built-in predicates::
* Calling Prolog non-standard built-in meta-predicates::
* Calling Prolog foreign predicates::
* Calling Prolog user-defined plain predicates::
* Calling Prolog module predicates::
* Calling Prolog module meta-predicates::


File: TheLogtalkHandbook-3.101.0.info,  Node: Calling Prolog built-in predicates,  Next: Calling Prolog non-standard built-in meta-predicates,  Up: Calling Prolog predicates

1.8.8.1 Calling Prolog built-in predicates
..........................................

In predicate clauses and object ‘initialization/1’ directives, predicate
calls that are not prefixed with a message-sending, super call, or
module qualification operator (‘::’, ‘^^’, or ‘:’), are compiled to
either calls to local predicates or as calls to Logtalk/Prolog built-in
predicates.  A predicate call is compiled as a call to a local predicate
if the object (or category) contains a scope directive, a multifile
directive, a dynamic directive, or a definition for the called
predicate.  When that is not the case, the compiler checks if the call
corresponds to a Logtalk or Prolog built-in predicate.  Consider the
following example:

     foo :-
         ...,
         write(bar),
         ...

The call to the ‘write/1’ predicate will be compiled as a call to the
corresponding Prolog standard built-in predicate unless the object (or
category) containing the above definition also contains a predicate
named ‘write/1’ or a directive for the predicate.

When calling non-standard Prolog built-in predicates or using
non-standard Prolog arithmetic functions, we may run into portability
problems while trying your applications with different backend Prolog
compilers.  We can use the compiler *note portability flag: 1d1. to
generate warnings for calls to non-standard predicates and arithmetic
functions.  We can also help document those calls using the *note
uses/2: 4b. directive.  For example, a few Prolog systems provide an
‘atom_string/2’ non-standard predicate.  We can write (in the object or
category calling the predicate):

     :- uses(user, [atom_string/2])

This directive is based on the fact that built-in predicates are visible
in plain Prolog (i.e., in ‘user’).  Besides helping to document the
dependency on a non-standard built-in predicate, this directive will
also silence the compiler portability warning.


File: TheLogtalkHandbook-3.101.0.info,  Node: Calling Prolog non-standard built-in meta-predicates,  Next: Calling Prolog foreign predicates,  Prev: Calling Prolog built-in predicates,  Up: Calling Prolog predicates

1.8.8.2 Calling Prolog non-standard built-in meta-predicates
............................................................

Prolog built-in meta-predicates may only be called locally within
objects or categories, i.e.  they cannot be used as messages.  Compiling
calls to non-standard, Prolog built-in meta-predicates can be tricky,
however, as there is no standard way of checking if a built-in predicate
is also a meta-predicate and finding out which are its meta-arguments.
But Logtalk supports overriding the original meta-predicate template
when not programmatically available or usable.  For example, assume a
‘det_call/1’ Prolog built-in meta-predicate that takes a goal as
argument.  We can add to the object (or category) calling it the
directive:

     :- meta_predicate(user::det_call(0)).

Another solution is to explicitly declare non-standard built-in Prolog
meta-predicates in the corresponding adapter file using the internal
predicate ‘'$lgt_prolog_meta_predicate'/3’.  For example:

     '$lgt_prolog_meta_predicate'(det_call(_), det_call(0), predicate).

The third argument can be either the atom ‘predicate’ or the atom
‘control_construct’, a distinction that is useful when compiling in
debug mode.


File: TheLogtalkHandbook-3.101.0.info,  Node: Calling Prolog foreign predicates,  Next: Calling Prolog user-defined plain predicates,  Prev: Calling Prolog non-standard built-in meta-predicates,  Up: Calling Prolog predicates

1.8.8.3 Calling Prolog foreign predicates
.........................................

Prolog systems often support defining ‘foreign’ predicates, i.e.
predicates defined using languages other than Prolog using a ‘foreign
language interface’.  There isn’t, however, any standard for defining,
making available, and recognizing foreign predicates.  From a Logtalk
perspective, the two most common scenarios are calling a foreign
predicate (from within an object or a category) and making a set of
foreign predicates available as part of an object (or category)
protocol.  Assuming, as this is the most common case, that foreign
predicates are globally visible once made available (using a Prolog
system-specific loading or linking procedure), we can simply call them
as user-defined plain predicates, as explained in the next section.
When defining an object (or category) that makes available foreign
predicates, the advisable solution is to name the predicates after the
object (or category) and then define object (or category) predicates
that call the foreign predicates.  Most backend adapter files include
support for recognizing foreign predicates that allows the Logtalk
compiler to inline calls to the predicates (thus avoiding call
indirection overheads).


File: TheLogtalkHandbook-3.101.0.info,  Node: Calling Prolog user-defined plain predicates,  Next: Calling Prolog module predicates,  Prev: Calling Prolog foreign predicates,  Up: Calling Prolog predicates

1.8.8.4 Calling Prolog user-defined plain predicates
....................................................

User-defined Prolog plain predicates (i.e., predicates that are not
defined in a Prolog module) can be called from within objects or
categories by sending the corresponding message to ‘user’.  For example:

     foo :-
         ...,
         user::bar,
         ...

In alternative, we can use the *note uses/2: 4b. directive and write:

     :- uses(user, [bar/0]).

     foo :-
         ...,
         bar,
         ...

Note that ‘user’ is a pseudo-object in Logtalk containing all predicate
definitions that are not encapsulated (either in a Logtalk entity or a
Prolog module).

When the Prolog predicate is not a meta-predicate, we can also use the
*note {}/1: 191. compiler bypass control construct.  For example:

     foo :-
         ...,
         {bar},
         ...

But note that in this case the *note reflection API: 48. will not record
the dependency of the ‘foo/0’ predicate on the Prolog ‘bar/0’ predicate
as we are effectively bypassing the compiler.


File: TheLogtalkHandbook-3.101.0.info,  Node: Calling Prolog module predicates,  Next: Calling Prolog module meta-predicates,  Prev: Calling Prolog user-defined plain predicates,  Up: Calling Prolog predicates

1.8.8.5 Calling Prolog module predicates
........................................

Prolog module predicates can be called from within objects or categories
by using explicit qualification.  For example:

     foo :-
         ...,
         module:bar,
         ...

You can also use the *note use_module/2: 4d. directive to call the
module predicates using implicit qualification:

     :- use_module(module, [bar/0]).

     foo :-
         ...,
         bar,
         ...

Note that the first argument of the ‘use_module/2’ directive, when used
within an object or a category, is a 'module name', not a 'file
specification' (also be aware that Prolog modules are sometimes defined
in files with names that differ from the module names).

As loading a Prolog module varies between Prolog systems, the actual
loading directive or goal is preferably done from the application *note
loader file: 4f.  An advantage of this approach is that it contributes
to a clean separation between 'loading' and 'using' a resource, with the
loader file being the central point that loads all application resources
(complex applications often use a 'hierarchy' of loader files, but the
main idea remains the same).

As an example, assume that we need to call predicates defined in a
CLP(FD) Prolog library, which can be loaded using ‘library(clpfd)’ as
the file specification.  In the loader file, we would add:

     :- use_module(library(clpfd), []).

Specifying an empty import list is often used to avoid adding the
module-exported predicates to plain Prolog.  In the objects and
categories we can then call the library predicates, using implicit or
explicit qualification, as explained.  For example:

     :- object(puzzle).

         :- public(puzzle/1).

         :- use_module(clpfd, [
             all_different/1, ins/2, label/1,
             (#=)/2, (#\=)/2,
             op(700, xfx, #=), op(700, xfx, #\=)
         ]).

         puzzle([S,E,N,D] + [M,O,R,E] = [M,O,N,E,Y]) :-
             Vars = [S,E,N,D,M,O,R,Y],
             Vars ins 0..9,
             all_different(Vars),
                       S*1000 + E*100 + N*10 + D +
                       M*1000 + O*100 + R*10 + E #=
             M*10000 + O*1000 + N*100 + E*10 + Y,
             M #\= 0, S #\= 0,
             label([M,O,N,E,Y]).

     :- end_object.

     Warning: The actual module code 'must' be loaded prior to the
     compilation of Logtalk source code that uses it.  In particular,
     programmers should not expect that the module be auto-loaded
     (including when using a backend Prolog compiler that supports an
     auto-loading mechanism).

The module identifier argument can also be a *note parameter variable:
a1. when using the directive in a parametric object or a parametric
category.  In this case, dynamic binding will necessarily be used for
all listed predicates (and non-terminals).  The parameter variable must
be instantiated at runtime when the calls are made.

Logtalk supports the declaration of *note predicate aliases: ca. and
*note predicate shorthands: 161. in ‘use_module/2’ directives used
within objects and categories.  For example, the ECLiPSe IC Constraint
Solvers define a ‘(::)/2’ variable domain operator that clashes with the
Logtalk ‘(::)/2’ message-sending operator.  We can solve the conflict by
writing:

     :- use_module(ic, [(::)/2 as ins/2]).

With this directive, calls to the ‘ins/2’ predicate alias will be
automatically compiled by Logtalk to calls to the ‘(::)/2’ predicate in
the ‘ic’ module.


File: TheLogtalkHandbook-3.101.0.info,  Node: Calling Prolog module meta-predicates,  Prev: Calling Prolog module predicates,  Up: Calling Prolog predicates

1.8.8.6 Calling Prolog module meta-predicates
.............................................

The Logtalk library provides implementations of common meta-predicates,
which can be used in place of module meta-predicates (e.g., list mapping
meta-predicates).  If that is not the case, the Logtalk compiler may
need help to understand the module meta-predicate templates.  Despite
some recent progress in standardization of the syntax of
‘meta_predicate/1’ directives and of the ‘meta_predicate/1’ property
returned by the ‘predicate_property/2’ reflection predicate, portability
is still a major problem.  Thus, Logtalk allows the original
‘meta_predicate/1’ directive to be 'overridden' with a local directive
that Logtalk can make sense of.  It also allows providing a
‘meta_predicate/1’ directive when it’s missing from the module defining
the meta-predicate.  Note that Logtalk is not based on a predicate
prefixing mechanism as found in module systems.  This fundamental
difference precludes an automated solution at the Logtalk compiler
level.

As an example, assume that you want to call from an object (or a
category) a module meta-predicate with the following meta-predicate
directive:

     :- module(foo, [bar/2]).

     :- meta_predicate(bar(*, :)).

The ‘:’ meta-argument specifier is ambiguous.  It tell us that the
second argument of the meta-predicate is module sensitive, but it does
not tell us 'how'.  Some legacy module libraries and some Prolog systems
use ‘:’ to mean ‘0’ (i.e., a meta-argument that will be meta-called).
Some others use ‘:’ for meta-arguments that are not meta-called but that
still need to be augmented with module information.  Whichever the case,
the Logtalk compiler doesn’t have enough information to unambiguously
parse the directive and correctly compile the meta-arguments in the
meta-predicate call.  Therefore, the Logtalk compiler will generate an
error stating that ‘:’ is not a valid meta-argument specifier when
trying to compile a ‘foo:bar/2’ goal.  There are two alternative
solutions for this problem.  The advised solution is to override the
meta-predicate directive by writing, inside the object (or category)
where the meta-predicate is called:

     :- meta_predicate(foo:bar(*, *)).

or:

     :- meta_predicate(foo:bar(*, 0)).

depending on the true meaning of the second meta-argument.  The second
alternative, only usable when the meta-argument can be handled as a
normal argument, is to simply use the *note {}/1: 191. compiler bypass
control construct to call the meta-predicate as-is:

     ... :- {foo:bar(..., ...)}, ...

The downside of this alternative is that it hides the dependency on the
module library from the reflection API and thus from the developer
tools.


File: TheLogtalkHandbook-3.101.0.info,  Node: Defining Prolog multifile predicates,  Next: Asserting and retracting Prolog predicates,  Prev: Calling Prolog predicates,  Up: Predicates

1.8.9 Defining Prolog multifile predicates
------------------------------------------

Some Prolog module libraries, e.g.  constraint packages, expect clauses
for some library predicates to be defined in other modules.  This is
accomplished by declaring the library predicate 'multifile' and by
explicitly prefixing predicate clause heads with the library module
identifier.  For example:

     :- multifile(clpfd:run_propagator/2).
     clpfd:run_propagator(..., ...) :-
         ...

Logtalk supports the definition of Prolog module multifile predicates in
objects and categories.  While the clause head is compiled as-is, the
clause body is compiled in the same way as a regular object or category
predicate, thus allowing calls to local object or category predicates.
For example:

     :- object(...).

         :- multifile(clpfd:run_propagator/2).
         clpfd:run_propagator(..., ...) :-
             % calls to local object predicates
             ...

     :- end_object.

The Logtalk compiler will print a warning if the ‘multifile/1’ directive
is missing.  These multifile predicates may also be declared dynamic
using the same ‘Module:Name/Arity’ notation.


File: TheLogtalkHandbook-3.101.0.info,  Node: Asserting and retracting Prolog predicates,  Prev: Defining Prolog multifile predicates,  Up: Predicates

1.8.10 Asserting and retracting Prolog predicates
-------------------------------------------------

To assert and retract clauses for Prolog dynamic predicates, we can use
an explicitly qualified module argument.  For example:

     :- object(...).

         :- dynamic(m:bar/1).

         foo(X) :-
             retractall(m:bar(_)),
             assertz(m:bar(X)),
             ...

     :- end_object.

In alternative, we can use *note use_module/2: 4d. directives to declare
the module predicates.  For example:

     :- object(...).

         :- use_module(m, [bar/1]).
         :- dynamic(m:bar/1).

         foo(X) :-
             % retract and assert bar/1 clauses in module m
             retractall(bar(_)),
             assertz(bar(X)),
             ...

     :- end_object.

When the Prolog dynamic predicates are defined in ‘user’, the
recommended and most portable practice (as not all backends support a
module system) is to use a *note uses/2: 4b. directive:

     :- object(...).

         :- uses(user, [bar/1]).
         :- dynamic(user::bar/1).

         foo(X) :-
             % retract and assert bar/1 clauses in user
             retractall(bar(_)),
             assertz(bar(X)),
             ...

     :- end_object.

Note that in the alternatives using ‘uses/2’ or ‘use_module/2’
directives, the argument of the database handling predicates must be
known at compile-time.  If that is not the case, you must use either an
explicitly-qualified argument or the *note {}/1: 191. control construct
instead.  For example:

     :- object(...).

         add(X) :-
             % assert clause X in module m
             assertz(m:X),
             ...

         remove(Y) :-
             % retract all clauses in user whose head unifies with Y
             {retractall(Y)},
             ...

     :- end_object.


File: TheLogtalkHandbook-3.101.0.info,  Node: Inheritance,  Next: Event-driven programming,  Prev: Predicates,  Up: User Manual

1.9 Inheritance
===============

The inheritance mechanisms found in object-oriented programming
languages allow the specialization of previously defined objects,
avoiding the unnecessary repetition of code and allowing the definition
of common functionality for sets of objects.  In the context of logic
programming, we can interpret inheritance as a form of 'theory
extension': an object will virtually contain, besides its own
predicates, all the predicates inherited from other objects that are not
redefined locally.  Inheritance is not, however, the only mechanism for
theory extension.  Logtalk also supports 'composition' using *note
categories: 109.

Logtalk uses a depth-first lookup procedure for finding predicate
declarations and predicate definitions, as explained below, when a *note
message: 79. is sent to an object.  The lookup procedures locate the
entity holding the *note predicate declaration: 57. and the entity
holding the *note predicate definition: 58. using the predicate name and
arity.  The *note alias/2: 165. predicate directive may be used for
defining alternative names for inherited predicates, for solving
inheritance conflicts, and for giving access to all inherited
definitions (thus overriding the default lookup procedure).

The lookup procedures are used when sending a message (using the *note
(;;)/2: 7e, *note (;;)/1: 5c, and *note []/1: 81. control constructs)
and when making 'super' calls (using the *note (^^)/1: 5d. control
construct).  The exact details of the lookup procedures depend on the
*note role: 93. played by the object receiving the message or making the
'super' call, as explained next.  The lookup procedures are also used by
the *note current_predicate/1: 141. and *note predicate_property/2: 142.
reflection predicates.

* Menu:

* Protocol inheritance::
* Implementation inheritance::
* Public, protected, and private inheritance: Public protected and private inheritance.
* Multiple inheritance::
* Composition versus multiple inheritance::


File: TheLogtalkHandbook-3.101.0.info,  Node: Protocol inheritance,  Next: Implementation inheritance,  Up: Inheritance

1.9.1 Protocol inheritance
--------------------------

Protocol inheritance refers to the inheritance of predicate declarations
(*note scope directives: 1e4.).  These can be contained in objects,
protocols, or categories.  Logtalk supports single and multi-inheritance
of protocols: an object or a category may implement several protocols,
and a protocol may extend several protocols.

* Menu:

* Lookup order for prototype hierarchies::
* Lookup order for class hierarchies::


File: TheLogtalkHandbook-3.101.0.info,  Node: Lookup order for prototype hierarchies,  Next: Lookup order for class hierarchies,  Up: Protocol inheritance

1.9.1.1 Lookup order for prototype hierarchies
..............................................

The lookup order for predicate declarations is first the object, second
the implemented protocols (and the protocols that these may extend),
third the imported categories (and the protocols that they may
implement), and finally the objects that the object extends (following
their declaration order).  This lookup is performed in depth-first
order.  When an object inherits two different declarations for the same
predicate, by default, only the first one will be considered.


File: TheLogtalkHandbook-3.101.0.info,  Node: Lookup order for class hierarchies,  Prev: Lookup order for prototype hierarchies,  Up: Protocol inheritance

1.9.1.2 Lookup order for class hierarchies
..........................................

The lookup order for predicate declarations is first the object classes
(following their declaration order), second the classes implemented
protocols (and the protocols that these may extend), third the classes
imported categories (and the protocols that they may implement), and
finally the superclasses of the object classes.  This lookup is
performed in depth-first order.  If the object inherits two different
declarations for the same predicate, by default, only the first one will
be considered.


File: TheLogtalkHandbook-3.101.0.info,  Node: Implementation inheritance,  Next: Public protected and private inheritance,  Prev: Protocol inheritance,  Up: Inheritance

1.9.2 Implementation inheritance
--------------------------------

Implementation inheritance refers to the inheritance of predicate
definitions.  These can be contained in objects or in categories.
Logtalk supports multi-inheritance of implementation: an object may
import several categories or extend, specialize, or instantiate several
objects.

* Menu:

* Lookup order for prototype hierarchies: Lookup order for prototype hierarchies<2>.
* Lookup order for class hierarchies: Lookup order for class hierarchies<2>.
* Redefining inherited predicate definitions::
* Specializing inherited predicate definitions::
* Union of inherited and local predicate definitions::
* Selective inheritance of predicate definitions::


File: TheLogtalkHandbook-3.101.0.info,  Node: Lookup order for prototype hierarchies<2>,  Next: Lookup order for class hierarchies<2>,  Up: Implementation inheritance

1.9.2.1 Lookup order for prototype hierarchies
..............................................

The lookup order for predicate definitions is similar to the lookup for
predicate declarations, except that implemented protocols are ignored
(as they can only contain predicate directives).


File: TheLogtalkHandbook-3.101.0.info,  Node: Lookup order for class hierarchies<2>,  Next: Redefining inherited predicate definitions,  Prev: Lookup order for prototype hierarchies<2>,  Up: Implementation inheritance

1.9.2.2 Lookup order for class hierarchies
..........................................

The lookup order for predicate definitions is similar to the lookup for
predicate declarations, except that implemented protocols are ignored
(as they can only contain predicate directives) and that the lookup
starts at the instance itself (that received the message) before
proceeding, if no predicate definition is found there, to the instance
classes imported categories and then to the class superclasses.


File: TheLogtalkHandbook-3.101.0.info,  Node: Redefining inherited predicate definitions,  Next: Specializing inherited predicate definitions,  Prev: Lookup order for class hierarchies<2>,  Up: Implementation inheritance

1.9.2.3 Redefining inherited predicate definitions
..................................................

When we define a predicate that is already inherited from an ancestor
object or an imported category, the inherited definition is hidden by
the new definition.  This is called inheritance overriding: a local
definition overrides any inherited definitions.  For example, assume
that we have the following two objects:

     :- object(root).

         :- public(bar/1).
         bar(root).

         :- public(foo/1).
         foo(root).

     :- end_object.


     :- object(descendant,
         extends(root)).

         foo(descendant).

     :- end_object.

After compiling and loading these objects, we can check the overriding
behavior by trying the following queries:

     | ?- root::(bar(Bar), foo(Foo)).

     Bar = root
     Foo = root
     yes


     | ?- descendant::(bar(Bar), foo(Foo)).

     Bar = root
     Foo = descendant
     yes

However, we can explicitly code other behaviors.  Some examples follow.


File: TheLogtalkHandbook-3.101.0.info,  Node: Specializing inherited predicate definitions,  Next: Union of inherited and local predicate definitions,  Prev: Redefining inherited predicate definitions,  Up: Implementation inheritance

1.9.2.4 Specializing inherited predicate definitions
....................................................

Specialization of inherited definitions: the new definition calls the
inherited definition and makes additional calls.  This is accomplished
by calling the *note (^^)/1: 5d. 'super call' operator in the new
definition.  For example, assume a ‘init/0’ predicate that must account
for object specific initializations along the inheritance chain:

     :- object(root).

         :- public(init/0).

         init :-
             write('root init'), nl.

     :- end_object.


     :- object(descendant,
         extends(root)).

         init :-
             write('descendant init'), nl,
             ^^init.

     :- end_object.

     | ?- descendant::init.

     descendant init
     root init
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: Union of inherited and local predicate definitions,  Next: Selective inheritance of predicate definitions,  Prev: Specializing inherited predicate definitions,  Up: Implementation inheritance

1.9.2.5 Union of inherited and local predicate definitions
..........................................................

Union of the new with the inherited definitions: all the definitions are
taken into account, the calling order being defined by the inheritance
mechanisms.  This can be accomplished by writing a clause that just
calls, using the *note (^^)/1: 5d. 'super call' operator, the inherited
definitions.  The relative position of this clause among the other
definition clauses sets the calling order for the local and inherited
definitions.  For example:

     :- object(root).

         :- public(foo/1).

         foo(1).
         foo(2).

     :- end_object.


     :- object(descendant,
         extends(root)).

         foo(3).
         foo(Foo) :-
             ^^foo(Foo).

     :- end_object.

     | ?- descendant::foo(Foo).

     Foo = 3 ;
     Foo = 1 ;
     Foo = 2 ;
     no


File: TheLogtalkHandbook-3.101.0.info,  Node: Selective inheritance of predicate definitions,  Prev: Union of inherited and local predicate definitions,  Up: Implementation inheritance

1.9.2.6 Selective inheritance of predicate definitions
......................................................

Selective inheritance of predicate definitions (also known as
differential inheritance) is normally used in the representation of
exceptions to inherited default definitions.  We can use the *note
(^^)/1: 5d. 'super call' operator to test and possibly reject some of
the inherited definitions.  A common example is representing flightless
birds:

     :- object(bird).

         :- public(mode/1).

         mode(walks).
         mode(flies).

     :- end_object.


     :- object(penguin,
         extends(bird)).

         mode(swims).
         mode(Mode) :-
             ^^mode(Mode),
             Mode \== flies.

     :- end_object.

     | ?- penguin::mode(Mode).

     Mode = swims ;
     Mode = walks ;
     no


File: TheLogtalkHandbook-3.101.0.info,  Node: Public protected and private inheritance,  Next: Multiple inheritance,  Prev: Implementation inheritance,  Up: Inheritance

1.9.3 Public, protected, and private inheritance
------------------------------------------------

To make all *note public predicates: 53. declared via implemented
protocols, imported categories, or ancestor objects *note protected
predicates: 54. or to make all public and protected predicates *note
private predicates: 55, we prefix the entity’s name with the
corresponding keyword.  For example:

     :- object(Object,
         implements(private::Protocol)).

         % all the Protocol public and protected
         % predicates become private predicates
         % for the Object clients

         ...

     :- end_object.

or:

     :- object(Class,
         specializes(protected::Superclass)).

         % all the Superclass public predicates become
         % protected predicates for the Class clients

         ...

     :- end_object.

Omitting the scope keyword is equivalent to using the public scope
keyword.  For example:

     :- object(Object,
         imports(public::Category)).

         ...

     :- end_object.

This is the same as:

     :- object(Object,
         imports(Category)).

         ...

     :- end_object.

This way we ensure backward compatibility with older Logtalk versions
and a simplified syntax when protected or private inheritance is not
used.


File: TheLogtalkHandbook-3.101.0.info,  Node: Multiple inheritance,  Next: Composition versus multiple inheritance,  Prev: Public protected and private inheritance,  Up: Inheritance

1.9.4 Multiple inheritance
--------------------------

Logtalk supports multiple inheritance by enabling an object to extend,
instantiate, or specialize more than one object.  Likewise, a protocol
may extend multiple protocols, and a category may extend multiple
categories.  In this case, the depth-first lookup algorithms described
above traverse the list of entities per relation from left to right.
Consider as an example the following object opening directive:

     :- object(foo,
         extends((bar, baz))).

The lookup procedure will look first into the parent object ‘bar’ and
its related entities before looking into the parent object ‘baz’.  The
*note alias/2: 165. predicate directive can always be used to solve
multiple inheritance conflicts.  It should also be noted that the
multi-inheritance support does not affect performance when we use single
inheritance.


File: TheLogtalkHandbook-3.101.0.info,  Node: Composition versus multiple inheritance,  Prev: Multiple inheritance,  Up: Inheritance

1.9.5 Composition versus multiple inheritance
---------------------------------------------

It is not possible to discuss inheritance mechanisms without referring
to the long and probably endless debate on single versus multiple
inheritance.  The single inheritance mechanism can be implemented
efficiently, but it imposes several limitations on reusing, even if the
multiple characteristics we intend to inherit are orthogonal.  On the
other hand, the multiple inheritance mechanisms are attractive in their
apparent capability of modeling complex situations.  However, they
include a potential for conflict between inherited definitions whose
variety does not allow a single and satisfactory solution for all the
cases.

No solution that we might consider satisfactory for all the problems
presented by the multiple inheritance mechanisms has been found.  From
the simplicity of some extensions that use the Prolog search strategy,
such as *note [McCabe92]: 28. or *note [Moss94]: 1fc, to the
sophisticated algorithms of CLOS *note [Bobrow_et_al_88]: 1fd, there is
no adequate solution for all the situations.  Besides, the use of
multiple inheritance carries some complex problems in the domain of
software engineering, particularly in the reuse and maintenance of the
applications.  All these problems are substantially reduced if we
preferably use in our software development composition mechanisms
instead of specialization mechanisms *note [Taenzer89]: 1fe.  Multiple
inheritance is best used as an analysis and project abstraction, rather
than as an implementation technique *note [Shan_et_al_93]: 1ff.  Note
that Logtalk provides first-class support for composition using *note
categories: 109.


File: TheLogtalkHandbook-3.101.0.info,  Node: Event-driven programming,  Next: Multi-threading programming,  Prev: Inheritance,  Up: User Manual

1.10 Event-driven programming
=============================

The addition of event-driven programming capacities to the Logtalk
language *note [Moura94]: 9d. is based on a simple but powerful idea:

     The computations must result not only from message-sending but also
     from the 'observation' of message-sending.

The need to associate computations to the occurrence of events was very
early recognized in knowledge representation languages, programming
languages *note [Stefik_et_al_86]: 202, *note [Moon86]: 10a, operative
systems *note [Tanenbaum87]: 203, and graphical user interfaces.

With the integration between object-oriented and event-driven
programming, we intend to achieve the following goals:

   * Minimize the 'coupling' between objects.  An object should only
     contain what is intrinsic to it.  If an object observes another
     object, that means that it should depend only on the public
     protocol of the object observed and not on the implementation of
     that protocol.

   * Provide a mechanism for building 'reflexive systems' in Logtalk
     based on the dynamic behavior of objects in complement to the
     reflective information on object predicates and relations.

   * Provide a mechanism for easily defining method 'pre- and
     post-conditions' that can be toggled using the *note events: 89.
     compiler flag.  The pre- and post-conditions may be defined in the
     same object containing the methods or distributed between several
     objects acting as method monitors.

   * Provide a 'publish-subscribe' mechanism where public messages play
     the role of events.

* Menu:

* Definitions::
* Event generation::
* Communicating events to monitors::
* Performance concerns::
* Monitor semantics::
* Activation order of monitors::
* Event handling::


File: TheLogtalkHandbook-3.101.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.101.0.info,  Node: Event,  Next: Monitor,  Up: Definitions

1.10.1.1 Event
..............

In an object-oriented system, all computations start through message
sending.  It thus becomes quite natural to declare that the only event
that can occur in this kind of system is precisely the sending of a
message.  An event can thus be represented by the ordered tuple
‘(Object, Message, Sender)’.

If we consider message processing an indivisible activity, we can
interpret the sending of a message and the return of the control to the
object that has sent the message as two distinct events.  This
distinction allows us to have more precise control over a system’s
dynamic behavior.  In Logtalk, these two types of events have been named
‘before’ and ‘after’, respectively for sending a message and for
returning control to the sender.  Therefore, we refine our event
representation using the ordered tuple ‘(Event, Object, Message,
Sender)’.

The implementation of events in Logtalk enjoys the following properties:

Independence between the two types of events

     We can choose to watch only one event type or to process each one
     of the events associated with a message-sending goal in an
     independent way.

All events are automatically generated by the message-sending mechanism

     The task of generating events is transparently accomplished by the
     message-sending mechanism.  The user only needs to define the
     events that will be monitored.

The events watched at any moment can be dynamically changed during program execution

     The notion of event allows the user not only to have the
     possibility of observing but also of controlling and modifying an
     application behavior, namely by dynamically changing the observed
     events during program execution.  It is our goal to provide the
     user with the possibility of modeling the largest number of
     situations.


File: TheLogtalkHandbook-3.101.0.info,  Node: Monitor,  Prev: Event,  Up: Definitions

1.10.1.2 Monitor
................

Complementary to the notion of event is the notion of monitor.  A
monitor is an object that is automatically notified by the
message-sending mechanism whenever a registered event occurs.  Any
object that defines the event-handling predicates can play the role of a
monitor.

The implementation of monitors in Logtalk enjoys the following
properties:

Any object can act as a monitor

     The monitor status is a role that any object can perform during its
     existence.  The minimum protocol necessary is declared in the
     built-in monitoring(1) protocol.  Strictly speaking, the reference
     to this protocol is only needed when specializing event handlers.
     Nevertheless, it is considered good programming practice to always
     refer to the protocol when defining event handlers.

Unlimited number of monitors for each event

     Several monitors can observe the same event for distinct reasons.
     Therefore, the number of monitors per event is bounded only by the
     available computing resources.

The monitor status of an object can be dynamically changed at runtime

     This property does not imply that an object must be dynamic to act
     as a monitor (the monitor status of an object is not stored in the
     object).

Event handlers cannot modify the event arguments

     Notably, if the message contains unbound variables, these cannot be
     bound by the calls to the monitor event handlers.

   ---------- Footnotes ----------

   (1) ../../apis/monitoring_0.html#monitoring-0


File: TheLogtalkHandbook-3.101.0.info,  Node: Event generation,  Next: Communicating events to monitors,  Prev: Definitions,  Up: Event-driven programming

1.10.2 Event generation
-----------------------

Assuming that the *note events: 89. flag is set to ‘allow’ for the
object (or category) sending the messages we want to observe, for each
message that is sent using the *note (;;)/2: 7e. control construct, the
runtime system automatically generates two events.  The first — 'before
event' — is generated when the message is sent.  The second — 'after
event' — is generated after the message has successfully been executed.

Note that 'self' messages (using the *note (;;)/1: 5c. control
construct) and 'super' calls (using the *note (^^)/1: 5d. control
construct) don’t generate events.


File: TheLogtalkHandbook-3.101.0.info,  Node: Communicating events to monitors,  Next: Performance concerns,  Prev: Event generation,  Up: Event-driven programming

1.10.3 Communicating events to monitors
---------------------------------------

Whenever a spied event occurs, the message-sending mechanism calls the
corresponding event handlers directly for all registered monitors.
These calls are internally made, thus bypassing the message-sending
primitives in order to avoid potential endless loops.  The event
handlers consist of user definitions for the public predicates declared
in the built-in monitoring(1) protocol (see below for more details).

   ---------- Footnotes ----------

   (1) ../../apis/monitoring_0.html#monitoring-0


File: TheLogtalkHandbook-3.101.0.info,  Node: Performance concerns,  Next: Monitor semantics,  Prev: Communicating events to monitors,  Up: Event-driven programming

1.10.4 Performance concerns
---------------------------

Ideally, the existence of monitored messages should not affect the
processing of the remaining messages.  On the other hand, for each
message that has been sent, the system must verify if its respective
event is monitored.  Whenever possible, this verification should be
performed in constant time and independently of the number of monitored
events.  The representation of events takes advantage of the first
argument indexing performed by most Prolog compilers, which ensure — in
the general case — access in constant time.

Event support can be turned off on a per-object (or per-category) basis
using the *note events: 89. compiler flag.  With event support turned
off, Logtalk uses optimized code for processing message-sending calls
that skips the checking of monitored events, resulting in a small but
measurable performance improvement.


File: TheLogtalkHandbook-3.101.0.info,  Node: Monitor semantics,  Next: Activation order of monitors,  Prev: Performance concerns,  Up: Event-driven programming

1.10.5 Monitor semantics
------------------------

The established semantics for monitor actions consists of considering
its success as a necessary condition so that a message can succeed:

   - All actions associated with events of type ‘before’ must succeed so
     that the message processing can start.

   - All actions associated with events of type ‘after’ also have to
     succeed so that the message itself succeeds.  The failure of any
     action associated with an event of type ‘after’ forces backtracking
     over the message execution (the failure of a monitor never causes
     backtracking over the preceding monitor actions).

Note that this is the most general choice.  If we require a transparent
presence of monitors in a message processing, we just have to define the
monitor actions in such a way that they never fail (which is very simple
to accomplish).


File: TheLogtalkHandbook-3.101.0.info,  Node: Activation order of monitors,  Next: Event handling,  Prev: Monitor semantics,  Up: Event-driven programming

1.10.6 Activation order of monitors
-----------------------------------

Ideally, whenever there are several monitors defined for the same event,
the calling order should not interfere with the result.  However, this
is not always possible.  In the case of an event of type ‘before’, the
failure of a monitor prevents a message from being sent and prevents the
execution of the remaining monitors.  In the case of an event of type
‘after’, a monitor failure will force backtracking over message
execution.  Different orders of monitor activation can therefore lead to
different results if the monitor actions imply object modifications
unrecoverable in case of backtracking.  Therefore, the order for monitor
activation should be assumed as arbitrary.  In effect, to assume or to
try to impose a specific sequence requires a global knowledge of an
application dynamics, which is not always possible.  Furthermore, that
knowledge can reveal itself as incorrect if there is any change in the
execution conditions.  Note that, given the independence between
monitors, it does not make sense that a failure forces backtracking over
the actions previously executed.


File: TheLogtalkHandbook-3.101.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.101.0.info,  Node: Defining new events,  Next: Abolishing defined events,  Up: Event handling

1.10.7.1 Defining new events
............................

New events can be defined using the *note define_events/5: 218. built-in
predicate:

     | ?- define_events(Event, Object, Message, Sender, Monitor).

Note that if any of the ‘Event’, ‘Object’, ‘Message’, and ‘Sender’
arguments is a free variable or contains free variables, this call will
define a 'set' of matching events.


File: TheLogtalkHandbook-3.101.0.info,  Node: Abolishing defined events,  Next: Finding defined events,  Prev: Defining new events,  Up: Event handling

1.10.7.2 Abolishing defined events
..................................

Events that are no longer needed may be abolished using the *note
abolish_events/5: 21b. built-in predicate:

     | ?- abolish_events(Event, Object, Message, Sender, Monitor).

If called with free variables, this goal will remove all matching
events.


File: TheLogtalkHandbook-3.101.0.info,  Node: Finding defined events,  Next: Defining event handlers,  Prev: Abolishing defined events,  Up: Event handling

1.10.7.3 Finding defined events
...............................

The events that are currently defined can be retrieved using the *note
current_event/5: 21e. built-in predicate:

     | ?- current_event(Event, Object, Message, Sender, Monitor).

Note that this predicate will return 'sets' of matching events if some
of the returned arguments are free variables or contain free variables.


File: TheLogtalkHandbook-3.101.0.info,  Node: Defining event handlers,  Prev: Finding defined events,  Up: Event handling

1.10.7.4 Defining event handlers
................................

The monitoring(1) built-in protocol declares two public predicates,
*note before/3: 101. and *note after/3: 102, that are automatically
called to handle ‘before’ and ‘after’ events.  Any object that plays the
role of monitor must define one or both of these event handler methods:

     before(Object, Message, Sender) :-
         ... .

     after(Object, Message, Sender) :-
         ... .

The arguments in both methods are instantiated by the message-sending
mechanism when a monitored event occurs.  For example, assume that we
want to define a monitor called ‘tracer’ that will track any message
sent to an object by printing a descriptive text to the standard output.
Its definition could be something like:

     :- object(tracer,
         % built-in protocol for event handler methods
         implements(monitoring)).

         before(Object, Message, Sender) :-
             write('call: '), writeq(Object),
             write(' <-- '), writeq(Message),
             write(' from '), writeq(Sender), nl.

         after(Object, Message, Sender) :-
             write('exit: '), writeq(Object),
             write(' <-- '), writeq(Message),
             write(' from '), writeq(Sender), nl.

     :- end_object.

Assume that we also have the following object:

     :- object(any).

         :- public(bar/1).
         bar(bar).

         :- public(foo/1).
         foo(foo).

     :- end_object.

After compiling and loading both objects and setting the *note events:
89. flag to ‘allow’, we can start tracing every message sent to any
object by calling the *note define_events/5: 218. built-in predicate:

     | ?- set_logtalk_flag(events, allow).

     yes

     | ?- define_events(_, _, _, _, tracer).

     yes

From now on, every message sent from ‘user’ to any object will be traced
to the standard output stream:

     | ?- any::bar(X).

     call: any <-- bar(X) from user
     exit: any <-- bar(bar) from user
     X = bar

     yes

To stop tracing, we can use the *note abolish_events/5: 21b. built-in
predicate:

     | ?- abolish_events(_, _, _, _, tracer).

     yes

The monitoring(2) protocol declares the event handlers as public
predicates.  If necessary, *note protected or private implementation of
the protocol: f7. may be used in order to change the scope of the event
handler predicates.  Note that the message-sending processing mechanism
is able to call the event handlers irrespective of their scope.
Nevertheless, the scope of the event handlers may be restricted in order
to prevent other objects from calling them.

The pseudo-object *note user: cf. can also act as a monitor.  This
object expects the ‘before/3’ and ‘after/3’ predicates to be defined in
the plain Prolog database.  To avoid predicate existence errors when
setting ‘user’ as a monitor, this object declares the predicates
multifile.  Thus, any plain Prolog code defining the predicates should
include the directives:

     :- multifile(before/3).
     :- multifile(after/3).

   ---------- Footnotes ----------

   (1) ../../apis/monitoring_0.html#monitoring-0

   (2) ../../apis/monitoring_0.html#monitoring-0


File: TheLogtalkHandbook-3.101.0.info,  Node: Multi-threading programming,  Next: Error handling,  Prev: Event-driven programming,  Up: User Manual

1.11 Multi-threading programming
================================

Logtalk provides 'experimental' support for multi-threading programming
on selected Prolog compilers.  Logtalk makes use of the low-level Prolog
built-in predicates that implement message queues and interface with
POSIX threads and mutexes (or a suitable emulation), providing a small
set of high-level predicates and directives that allows programmers to
easily take advantage of modern multi-processor and multi-core computers
without worrying about the tricky details of creating, synchronizing, or
communicating with threads, mutexes, and message queues.  Logtalk
multi-threading programming integrates with object-oriented programming
by providing a 'threaded engines' API, enabling objects and categories
to prove goals concurrently, and supporting synchronous and asynchronous
messages.

* Menu:

* Enabling multi-threading support::
* Enabling objects to make multi-threading calls::
* Multi-threading built-in predicates::
* One-way asynchronous calls::
* Asynchronous calls and synchronized predicates::
* Synchronizing threads through notifications::
* Threaded engines::
* Multi-threading performance::


File: TheLogtalkHandbook-3.101.0.info,  Node: Enabling multi-threading support,  Next: Enabling objects to make multi-threading calls,  Up: Multi-threading programming

1.11.1 Enabling multi-threading support
---------------------------------------

Multi-threading support may be disabled by default.  It can be enabled
on the Prolog adapter files of supported compilers by setting the
read-only *note threads: 225. compiler flag to ‘supported’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Enabling objects to make multi-threading calls,  Next: Multi-threading built-in predicates,  Prev: Enabling multi-threading support,  Up: Multi-threading programming

1.11.2 Enabling objects to make multi-threading calls
-----------------------------------------------------

The *note threaded/0: 228. object directive is used to enable an object
to make multi-threading calls:

     :- threaded.


File: TheLogtalkHandbook-3.101.0.info,  Node: Multi-threading built-in predicates,  Next: One-way asynchronous calls,  Prev: Enabling objects to make multi-threading calls,  Up: Multi-threading programming

1.11.3 Multi-threading built-in predicates
------------------------------------------

Logtalk provides a small set of built-in predicates for multi-threading
programming.  For simple tasks where you simply want to prove a set of
goals, each one in its own thread, Logtalk provides a *note threaded/1:
22b. built-in predicate.  The remaining predicates allow for
fine-grained control, including postponing retrieval of thread goal
results at a later time, supporting non-deterministic thread goals, and
making 'one-way' asynchronous calls.  Together, these predicates provide
high-level support for multi-threading programming, covering most common
use cases.

* Menu:

* Proving goals concurrently using threads::
* Proving goals asynchronously using threads::


File: TheLogtalkHandbook-3.101.0.info,  Node: Proving goals concurrently using threads,  Next: Proving goals asynchronously using threads,  Up: Multi-threading built-in predicates

1.11.3.1 Proving goals concurrently using threads
.................................................

A set of goals may be proved concurrently by calling the Logtalk
built-in predicate *note threaded/1: 22b.  Each goal in the set runs in
its own thread.

When the ‘threaded/1’ predicate argument is a 'conjunction' of goals,
the predicate call is akin to 'and-parallelism'.  For example, assume
that we want to find all the prime numbers in a given interval, ‘[N,
M]’.  We can split the interval into two parts and then span two threads
to compute the prime numbers in each sub-interval:

     prime_numbers(N, M, Primes) :-
         M > N,
         N1 is N + (M - N) // 2,
         N2 is N1 + 1,
         threaded((
             prime_numbers(N2, M, [], Acc),
             prime_numbers(N, N1, Acc, Primes)
         )).

     prime_numbers(N, M, Acc, Primes) :-
         ...

The ‘threaded/1’ call terminates when the two implicit threads
terminate.  In a computer with two or more processors (or with a
processor with two or more cores), the code above can be expected to
provide better computation times when compared with single-threaded code
for sufficiently large intervals.

When the ‘threaded/1’ predicate argument is a 'disjunction' of goals,
the predicate call is akin to 'or-parallelism', here reinterpreted as a
set of goals 'competing' to find a solution.  For example, consider the
different methods that we can use to find the roots of real functions.
Depending on the function, some methods will be faster than others.
Some methods will converge to the solution while others may diverge and
never find it.  We can try all the methods simultaneously by writing:

     find_root(Function, A, B, Error, Zero) :-
         threaded((
             bisection::find_root(Function, A, B, Error, Zero)
         ;   newton::find_root(Function, A, B, Error, Zero)
         ;   muller::find_root(Function, A, B, Error, Zero)
         )).

The above ‘threaded/1’ goal succeeds when one of the implicit threads
succeeds in finding the function root, leading to the termination of all
the remaining competing threads.

The ‘threaded/1’ built-in predicate is most useful for lengthy,
independent, deterministic computations where the computational costs of
each goal outweigh the overhead of the implicit thread creation and
management.


File: TheLogtalkHandbook-3.101.0.info,  Node: Proving goals asynchronously using threads,  Prev: Proving goals concurrently using threads,  Up: Multi-threading built-in predicates

1.11.3.2 Proving goals asynchronously using threads
...................................................

A goal may be proved asynchronously using a new thread by calling the
*note threaded_call/1-2: 230. built-in predicate .  Calls to this
predicate are always true and return immediately (assuming a callable
argument).  The term representing the goal is copied, not shared with
the thread.  The thread computes the first solution to the goal, posts
it to the implicit message queue of the object from where the
‘threaded_call/1’ predicate was called, and suspends waiting for either
a request for an alternative solution or for the program to commit to
the current solution.

The results of proving a goal asynchronously in a new thread may be
later retrieved by calling the *note threaded_exit/1-2: 231. built-in
predicate within the same object where the call to the ‘threaded_call/1’
predicate was made.  The ‘threaded_exit/1’ calls suspend execution until
the results of the ‘threaded_call/1’ calls are sent back to the object
message queue.

The ‘threaded_exit/1’ predicate allows us to retrieve alternative
solutions through backtracking (if you want to commit to the first
solution, you may use the *note threaded_once/1-2: 232. predicate
instead of the ‘threaded_call/1’ predicate).  For example, assuming a
‘lists’ object implementing the usual ‘member/2’ predicate, we could
write:

     | ?- threaded_call(lists::member(X, [1,2,3])).

     X = _G189
     yes

     | ?- threaded_exit(lists::member(X, [1,2,3])).

     X = 1 ;
     X = 2 ;
     X = 3 ;
     no

In this case, the ‘threaded_call/1’ and the ‘threaded_exit/1’ calls are
made within the pseudo-object ‘user’.  The implicit thread running the
‘lists::member/2’ goal suspends itself after providing a solution,
waiting for a request for an alternative solution; the thread is
automatically terminated when the runtime engine detects that
backtracking to the ‘threaded_exit/1’ call is no longer possible.

Calls to the ‘threaded_exit/1’ predicate block the caller until the
object message queue receives the reply to the asynchronous call.  The
predicate *note threaded_peek/1-2: 233. may be used to check if a reply
is already available without removing it from the thread queue.  The
‘threaded_peek/1’ predicate call succeeds or fails immediately without
blocking the caller.  However, keep in mind that repeated use of this
predicate is equivalent to polling a message queue, which may hurt
performance.

Be careful when using the ‘threaded_exit/1’ predicate inside
failure-driven loops.  When all the solutions have been found (and the
thread generating them is therefore terminated), re-calling the
predicate will generate an exception.  Note that failing instead of
throwing an exception is not an acceptable solution, as it could be
misinterpreted as a failure of the ‘threaded_call/1’ argument.

The example in the previous section with prime numbers could be
rewritten using the ‘threaded_call/1’ and ‘threaded_exit/1’ predicates:

     prime_numbers(N, M, Primes) :-
         M > N,
         N1 is N + (M - N) // 2,
         N2 is N1 + 1,
         threaded_call(prime_numbers(N2, M, [], Acc)),
         threaded_call(prime_numbers(N, N1, Acc, Primes)),
         threaded_exit(prime_numbers(N2, M, [], Acc)),
         threaded_exit(prime_numbers(N, N1, Acc, Primes)).

     prime_numbers(N, M, Acc, Primes) :-
         ...

When using asynchronous calls, the link between a ‘threaded_exit/1’ call
and the corresponding ‘threaded_call/1’ call is established using
unification.  If there are multiple ‘threaded_call/1’ calls for a
matching ‘threaded_exit/1’ call, the connection can potentially be
established with any of them (this is akin to what happens with
tabling).  Nevertheless, you can easily use a call 'tag' by using the
alternative *note threaded_call/2: 230, *note threaded_once/2: 232, and
*note threaded_exit/2: 231. built-in predicates.  For example:

     ?- threaded_call(member(X, [1,2,3]), Tag).

     Tag = 1
     yes

     ?- threaded_call(member(X, [1,2,3]), Tag).

     Tag = 2
     yes

     ?- threaded_exit(member(X, [1,2,3]), 2).

     X = 1 ;
     X = 2 ;
     X = 3
     yes

When using these predicates, the tags shall be considered as an opaque
term; users shall not rely on its type.  Tagged asynchronous calls can
be canceled by using the *note threaded_cancel/1: 234. predicate.


File: TheLogtalkHandbook-3.101.0.info,  Node: One-way asynchronous calls,  Next: Asynchronous calls and synchronized predicates,  Prev: Multi-threading built-in predicates,  Up: Multi-threading programming

1.11.4 One-way asynchronous calls
---------------------------------

Sometimes we want to prove a goal in a new thread without caring about
the results.  This may be accomplished by using the built-in predicate
*note threaded_ignore/1: 237.  For example, assume that we are
developing a multi-agent application where an agent may send a “happy
birthday” message to another agent.  We could write:

     ..., threaded_ignore(agent::happy_birthday), ...

The call succeeds with no reply of the goal success, failure, or even
exception ever being sent back to the object making the call.  Note that
this predicate implicitly performs a deterministic call of its argument.


File: TheLogtalkHandbook-3.101.0.info,  Node: Asynchronous calls and synchronized predicates,  Next: Synchronizing threads through notifications,  Prev: One-way asynchronous calls,  Up: Multi-threading programming

1.11.5 Asynchronous calls and synchronized predicates
-----------------------------------------------------

Proving a goal asynchronously using a new thread may lead to problems
when the goal results in side effects such as input/output operations or
modifications to an *note object database: 1b0.  For example, if a new
thread is started with the same goal before the first one finished its
job, we may end up with mixed output, a corrupted database, or
unexpected goal failures.  In order to solve this problem, predicates
(and grammar rule non-terminals) with side effects can be declared as
'synchronized' by using the *note synchronized/1: 74. predicate
directive.  Proving a query to a synchronized predicate (or synchronized
non-terminal) is internally protected by a mutex, thus allowing for easy
thread synchronization.  For example:

     % ensure thread synchronization
     :- synchronized(db_update/1).

     db_update(Update) :-
         % predicate with side-effects
         ...

A second example: assume an object defining two predicates for writing,
respectively, even and odd numbers in a given interval to the standard
output.  Given a large interval, a goal such as:

     | ?- threaded_call(obj::odd_numbers(1,100)),
          threaded_call(obj::even_numbers(1,100)).

     1 3 2 4 6 8 5 7 10 ...
     ...

will most likely result in a mixed-up output.  By declaring the
‘odd_numbers/2’ and ‘even_numbers/2’ predicates synchronized:

     :- synchronized([
         odd_numbers/2,
         even_numbers/2]).

one goal will only start after the other one finished:

     | ?- threaded_ignore(obj::odd_numbers(1,99)),
          threaded_ignore(obj::even_numbers(1,99)).

     1 3 5 7 9 11 ...
     ...
     2 4 6 8 10 12 ...
     ...

Note that, in a more realistic scenario, the two ‘threaded_ignore/1’
calls would be made concurrently from different objects.  Using the same
synchronized directive for a set of predicates implies that they all use
the same mutex, as required for this example.

As each Logtalk entity is independently compiled, this directive must be
included in every object or category that contains a definition for the
described predicate, even if the predicate declaration is inherited from
another entity, in order to ensure proper compilation.  Note that a
synchronized predicate cannot be declared dynamic.  To ensure atomic
updates of a dynamic predicate, declare as synchronized the predicate
performing the update.

Synchronized predicates may be used as wrappers for messages sent to
objects that are not multi-threading aware.  For example, assume a ‘log’
object defining a ‘write_log_entry/2’ predicate that writes log entries
to a file, thus using side effects on its implementation.  We can
specify and define, for example, a ‘sync_write_log_entry/2’ predicate as
follows:

     :- synchronized(sync_write_log_entry/2).

     sync_write_log_entry(File, Entry) :-
         log::write_log_entry(File, Entry).

and then call the ‘sync_write_log_entry/2’ predicate instead of the
‘write_log_entry/2’ predicate from multi-threaded code.

The synchronization directive may be used when defining objects that may
be reused in both single-threaded and multi-threaded Logtalk
applications.  The directive simply makes calls to the synchronized
predicates deterministic when the objects are used in a single-threaded
application.


File: TheLogtalkHandbook-3.101.0.info,  Node: Synchronizing threads through notifications,  Next: Threaded engines,  Prev: Asynchronous calls and synchronized predicates,  Up: Multi-threading programming

1.11.6 Synchronizing threads through notifications
--------------------------------------------------

Declaring a set of predicates as synchronized can only ensure that they
are not executed at the same time by different threads.  Sometimes we
need to suspend a thread not on a synchronization lock but on some
condition that must hold true for a thread goal to proceed.  I.e.  we
want a thread goal to be suspended until a condition becomes true
instead of simply failing.  The built-in predicate *note
threaded_wait/1: 23b. allows us to suspend a predicate execution
(running in its own thread) until a notification is received.
Notifications are posted using the built-in predicate *note
threaded_notify/1: 23c.  A notification is a Prolog term that a
programmer chooses to represent some condition becoming true.  Any
Prolog term can be used as a notification argument for these predicates.
Related calls to the ‘threaded_wait/1’ and ‘threaded_notify/1’ must be
made within the same object, 'this', as the object message queue is used
internally for posting and retrieving notifications.

Each notification posted by a call to the ‘threaded_notify/1’ predicate
is consumed by a single ‘threaded_wait/1’ predicate call (i.e., these
predicates implement a peer-to-peer mechanism).  Care should be taken to
avoid deadlocks when two (or more) threads both wait and post
notifications to each other.


File: TheLogtalkHandbook-3.101.0.info,  Node: Threaded engines,  Next: Multi-threading performance,  Prev: Synchronizing threads through notifications,  Up: Multi-threading programming

1.11.7 Threaded engines
-----------------------

Threaded engines provide an alternative to the multi-threading
predicates described in the previous sections.  An 'engine' is a
computing thread whose solutions can be lazily computed and retrieved.
In addition, an engine also supports a term queue that allows passing
arbitrary terms to the engine.

An engine is created by calling the *note threaded_engine_create/3: 23f.
built-in predicate.  For example:

     | ?- threaded_engine_create(X, member(X, [1,2,3]), worker).
     yes

The first argument is an 'answer template' to be used for retrieving
solution bindings.  The user can name the engine, as in this example
where the atom ‘worker’ is used, or have the runtime generate a name,
which should be treated as an opaque term.

Engines are scoped by the object within which the
‘threaded_engine_create/3’ call takes place.  Thus, different objects
can create engines with the same names with no conflicts.  Moreover,
engines share the visible predicates of the object creating them.

The engine computes the first solution of its goal argument and suspends
waiting for it to be retrieved.  Solutions can be retrieved one at a
time using the *note threaded_engine_next/2: 240. built-in predicate:

     | ?- threaded_engine_next(worker, X).
     X = 1
     yes

The call blocks until a solution is available and fails if there are no
solutions left.  After returning a solution, this predicate signals the
engine to start computing the next one.  Note that this predicate is
deterministic.  In contrast with the ‘threaded_exit/1-2’ built-in
predicates, retrieving the next solution requires calling the predicate
again instead of backtracking into its call.  For example:

     collect_all(Engine, [Answer| Answers]) :-
         threaded_engine_next(Engine, Answer),
         !,
         collect_all(Engine, Answers).
     collect_all(_, []).

There is also a reified alternative version of the predicate, *note
threaded_engine_next_reified/2: 241, which returns ‘the(Answer)’, ‘no’,
and ‘exception(Error)’ terms as answers.  Using this predicate,
collecting all solutions to an engine uses a different programming
pattern:

     ... :-
         ...,
         threaded_engine_next_reified(Engine, Reified),
         collect_all_reified(Reified, Engine, Answers),
         ...

     collect_all_reified(no, _, []).
     collect_all_reified(the(Answer), Engine, [Answer| Answers]) :-
         threaded_engine_next_reified(Engine, Reified),
         collect_all_reified(Reified, Engine, Answers).

Engines must be explicitly terminated using the *note
threaded_engine_destroy/1: 242. built-in predicate:

     | ?- threaded_engine_destroy(worker).
     yes

A common usage pattern for engines is to define a recursive predicate
that uses the engine term queue to retrieve a task to be performed.  For
example, assume we define the following predicate:

     loop :-
         threaded_engine_fetch(Task),
         handle(Task),
         loop.

The *note threaded_engine_fetch/1: 243. built-in predicate fetches a
task for the engine term queue.  The engine clients would use the *note
threaded_engine_post/2: 244. built-in predicate to post tasks into the
engine term queue.  The engine would be created using the call:

     | ?- threaded_engine_create(none, loop, worker).

     yes

The ‘handle/1’ predicate, after performing a task, can use the *note
threaded_engine_yield/1: 245. built-in predicate to make the task
results available for consumption using the ‘threaded_engine_next/2’ and
‘threaded_engine_next_reified/2’ built-in predicates.  Blocking
semantics are used by these two predicates: the
‘threaded_engine_yield/1’ predicate blocks until the returned solution
is consumed, while the ‘threaded_engine_next/2’ predicate blocks until a
solution becomes available.


File: TheLogtalkHandbook-3.101.0.info,  Node: Multi-threading performance,  Prev: Threaded engines,  Up: Multi-threading programming

1.11.8 Multi-threading performance
----------------------------------

The performance of multi-threading applications is highly dependent on
the *note backend Prolog compiler: 34, the operating-system, and the use
of *note dynamic binding: 36. and dynamic predicates.  All compatible
backend Prolog compilers that support multi-threading features make use
of POSIX threads or 'pthreads'.  The performance of the underlying
pthreads implementation can exhibit significant differences between
operating systems.  An important point is synchronized access to dynamic
predicates.  As different threads may try to simultaneously access and
update dynamic predicates, these operations may use a lock-free
algorithm or be protected by a lock, usually implemented using a mutex.
In the latter case, poor mutex lock operating-system performance,
combined with a large number of collisions by several threads trying to
acquire the same lock, can result in severe performance penalties.
Thus, whenever possible, avoid using dynamic predicates and dynamic
binding.


File: TheLogtalkHandbook-3.101.0.info,  Node: Error handling,  Next: Reflection,  Prev: Multi-threading programming,  Up: User Manual

1.12 Error handling
===================

Error handling is accomplished in Logtalk by using the standard
‘catch/3’ and ‘throw/1’ predicates *note [ISO95]: 31. together with a
set of built-in methods that simplify generating errors decorated with
expected context.

Errors thrown by Logtalk have, whenever possible, the following format:

     error(Error, logtalk(Goal, ExecutionContext))

In this exception term, ‘Goal’ is the goal that triggered the error
‘Error’ and ‘ExecutionContext’ is the context in which ‘Goal’ is called.
For example:

     error(
         permission_error(modify,private_predicate,p/0),
         logtalk(foo::abolish(p/0), _)
     )

Note, however, that ‘Goal’ and ‘ExecutionContext’ can be unbound or only
partially instantiated when the corresponding information is not
available (e.g., due to compiler optimizations that throw away the
necessary error context information).  The ‘ExecutionContext’ argument
is an opaque term that can be decoded using the
logtalk::execution_context/7(1) predicate.

* Menu:

* Raising Exceptions::
* Type-checking::
* Expected terms::
* Compiler warnings and errors::
* Runtime errors::

   ---------- Footnotes ----------

   (1) ../../apis/logtalk_0.html#logtalk-0-execution-context-7


File: TheLogtalkHandbook-3.101.0.info,  Node: Raising Exceptions,  Next: Type-checking,  Up: Error handling

1.12.1 Raising Exceptions
-------------------------

The *note error handling section: 24c. in the reference manual lists a
set of convenient built-in methods that generate ‘error/2’ exception
terms with the expected context argument.  For example, instead of
manually constructing a type error as in:

     ...,
     context(Context),
     throw(error(type_error(atom, 42), Context)).

we can simply write:

     ...,
     type_error(atom, 42).

The provided error built-in methods cover all standard error types found
in the ISO Prolog Core standard.


File: TheLogtalkHandbook-3.101.0.info,  Node: Type-checking,  Next: Expected terms,  Prev: Raising Exceptions,  Up: Error handling

1.12.2 Type-checking
--------------------

One of the most common cases where errors may be generated is when
type-checking predicate arguments and input data before processing it.
The standard library includes a type(1) object that defines an extensive
set of types, together with predicates for validating and checking
terms.  The set of types is user extensible.  New types can be defined
by adding clauses for the ‘type/1’ and ‘check/2’ multifile predicates.
For example, assume that we want to be able to check 'temperatures'
expressed in Celsius, Fahrenheit, or Kelvin scales.  We start by
declaring (in an object or category) the new type:

     :- multifile(type::type/1).
     type::type(temperature(_Unit)).

Next, we need to define the actual code that would verify that a
temperature is valid.  As the different scales use a different value for
absolute zero, we can write:

     :- multifile(type::check/2).
     type::check(temperature(Unit), Term) :-
         check_temperature(Unit, Term).

     % given that temperature has only a lower bound, we make use of the library
     % property/2 type to define the necessary test expression for each unit
     check_temperature(celsius, Term) :-
         type::check(property(float, [Temperature]>>(Temperature >= -273.15)), Term).
     check_temperature(fahrenheit, Term) :-
         type::check(property(float, [Temperature]>>(Temperature >= -459.67)), Term).
     check_temperature(kelvin, Term) :-
         type::check(property(float, [Temperature]>>(Temperature >= 0.0)), Term).

With this definition, a term is first checked that it is a float value
before checking that it is in the expected open interval.  But how do we
use this new type?  If we just want to test if a temperature is valid,
we can write:

     ..., type::valid(temperature(celsius), 42.0), ...

The type::valid/2(2) predicate succeeds or fails depending on the second
argument being of the type specified in the first argument.  If instead
of success or failure we want to generate an error for invalid values,
we can use the type::check/2(3) predicate instead:

     ..., type::check(temperature(celsius), 42.0), ...

If we require an ‘error/2’ exception term with the error context, we can
use instead the type::check/3(4) predicate:

     ...,
     context(Context),
     type::check(temperature(celsius), 42.0, Context),
     ...

Note that ‘context/1’ calls are inlined and messages to the library
‘type’ object use *note static binding: 35. when compiling with the
*note optimize flag: 8c. turned on, thus enabling efficient
type-checking.

   ---------- Footnotes ----------

   (1) ../../apis/type_0.html#type-0

   (2) ../../apis/type_0.html#type-0-valid-2

   (3) ../../apis/type_0.html#type-0-check-2

   (4) ../../apis/type_0.html#type-0-check-3


File: TheLogtalkHandbook-3.101.0.info,  Node: Expected terms,  Next: Compiler warnings and errors,  Prev: Type-checking,  Up: Error handling

1.12.3 Expected terms
---------------------

Support for representing and handling 'expected terms' is provided by
the *note expecteds: 24f. library.  Expected terms allow deferring
errors to later stages of an application in lieu to raising an exception
as soon as an error is detected.


File: TheLogtalkHandbook-3.101.0.info,  Node: Compiler warnings and errors,  Next: Runtime errors,  Prev: Expected terms,  Up: Error handling

1.12.4 Compiler warnings and errors
-----------------------------------

The current Logtalk compiler uses the standard ‘read_term/3’ built-in
predicate to read and compile a Logtalk source file.  This improves the
compatibility with *note backend Prolog compilers: 34. and their
proprietary syntax extensions and standard compliance quirks.  But one
consequence of this design choice is that invalid Prolog terms or syntax
errors may abort the compilation process with limited information given
to the user (due to the inherent limitations of the ‘read_term/3’
predicate).

Assuming that all the terms in a source file are valid, there is a set
of errors and potential errors, described below, that the compiler will
try to detect and report, depending on the used compiler flags (see the
*note Compiler flags: 251. section of this manual on lint flags for
details).

* Menu:

* Unknown entities::
* Singleton variables::
* Redefinition of Prolog built-in predicates::
* Redefinition of Logtalk built-in predicates::
* Redefinition of Logtalk built-in methods::
* Misspell calls of local predicates::
* Portability warnings::
* Deprecated elements::
* Missing directives::
* Duplicated directives::
* Duplicated clauses::
* Goals that are always true or false::
* Trivial fails::
* Suspicious calls::
* Lambda variables::
* Redefinition of predicates declared in uses/2 or use_module/2 directives::
* Other warnings and errors::


File: TheLogtalkHandbook-3.101.0.info,  Node: Unknown entities,  Next: Singleton variables,  Up: Compiler warnings and errors

1.12.4.1 Unknown entities
.........................

The Logtalk compiler warns about any referenced entity that is not
currently loaded.  The warning may reveal a misspelled entity name or
just an entity that will be loaded later.  Out-of-order loading should
be avoided when possible as it prevents some code optimizations, such as
*note static binding: 35. of messages to methods.


File: TheLogtalkHandbook-3.101.0.info,  Node: Singleton variables,  Next: Redefinition of Prolog built-in predicates,  Prev: Unknown entities,  Up: Compiler warnings and errors

1.12.4.2 Singleton variables
............................

Singleton variables in a clause are often misspelled variables and, as
such, are one of the most common errors when programming in Prolog.
Assuming that the *note backend Prolog compiler: 34. implementation of
the ‘read_term/3’ predicate supports the standard ‘singletons/1’ option,
the compiler warns about any singleton variable found while compiling a
source file.


File: TheLogtalkHandbook-3.101.0.info,  Node: Redefinition of Prolog built-in predicates,  Next: Redefinition of Logtalk built-in predicates,  Prev: Singleton variables,  Up: Compiler warnings and errors

1.12.4.3 Redefinition of Prolog built-in predicates
...................................................

The Logtalk compiler will warn us of any redefinition of a Prolog
built-in predicate inside an object or category.  Sometimes the
redefinition is intended.  In other cases, the user may not be aware
that a particular *note backend Prolog compiler: 34. may already provide
the predicate as a built-in predicate or may want to ensure code
portability among several Prolog compilers with different sets of
built-in predicates.


File: TheLogtalkHandbook-3.101.0.info,  Node: Redefinition of Logtalk built-in predicates,  Next: Redefinition of Logtalk built-in methods,  Prev: Redefinition of Prolog built-in predicates,  Up: Compiler warnings and errors

1.12.4.4 Redefinition of Logtalk built-in predicates
....................................................

Similar to the redefinition of Prolog built-in predicates, the Logtalk
compiler will warn us if we try to redefine a Logtalk built-in.  But the
redefinition will probably be an error in most (if not all) cases.


File: TheLogtalkHandbook-3.101.0.info,  Node: Redefinition of Logtalk built-in methods,  Next: Misspell calls of local predicates,  Prev: Redefinition of Logtalk built-in predicates,  Up: Compiler warnings and errors

1.12.4.5 Redefinition of Logtalk built-in methods
.................................................

An error will be thrown if we attempt to redefine a Logtalk built-in
method inside an entity.  The default behavior is to report the error
and abort the compilation of the offending entity.


File: TheLogtalkHandbook-3.101.0.info,  Node: Misspell calls of local predicates,  Next: Portability warnings,  Prev: Redefinition of Logtalk built-in methods,  Up: Compiler warnings and errors

1.12.4.6 Misspell calls of local predicates
...........................................

A warning will be reported if Logtalk finds (in the body of a predicate
definition) a call to a local predicate that is not defined, built-in
(either in Prolog or in Logtalk) or declared dynamic.  In most cases
these calls are simple misspell errors.


File: TheLogtalkHandbook-3.101.0.info,  Node: Portability warnings,  Next: Deprecated elements,  Prev: Misspell calls of local predicates,  Up: Compiler warnings and errors

1.12.4.7 Portability warnings
.............................

A warning will be reported if a predicate clause contains a call to a
non-standard built-in predicate or arithmetic function.  Portability
warnings are also reported for non-standard flags or flag values.  These
warnings often cannot be avoided due to the limited scope of the ISO
Prolog standard.


File: TheLogtalkHandbook-3.101.0.info,  Node: Deprecated elements,  Next: Missing directives,  Prev: Portability warnings,  Up: Compiler warnings and errors

1.12.4.8 Deprecated elements
............................

A warning will be reported if a deprecated directive, control construct,
or predicate is used.  These warnings should be fixed as soon as
possible, as support for any deprecated features will likely be
discontinued in future versions.


File: TheLogtalkHandbook-3.101.0.info,  Node: Missing directives,  Next: Duplicated directives,  Prev: Deprecated elements,  Up: Compiler warnings and errors

1.12.4.9 Missing directives
...........................

A warning will be reported for any missing dynamic, discontiguous,
meta-predicate, and public predicate directive.


File: TheLogtalkHandbook-3.101.0.info,  Node: Duplicated directives,  Next: Duplicated clauses,  Prev: Missing directives,  Up: Compiler warnings and errors

1.12.4.10 Duplicated directives
...............................

A warning will be reported for any duplicated scope, multifile, dynamic,
discontiguous, meta-predicate, and meta-non-terminal directives.  Note
that conflicting directives for the same predicate are handled as
errors, not as duplicated directive warnings.


File: TheLogtalkHandbook-3.101.0.info,  Node: Duplicated clauses,  Next: Goals that are always true or false,  Prev: Duplicated directives,  Up: Compiler warnings and errors

1.12.4.11 Duplicated clauses
............................

A warning will be reported for any duplicated entity clauses.  This
check is computationally heavy, however, and usually turned off by
default.


File: TheLogtalkHandbook-3.101.0.info,  Node: Goals that are always true or false,  Next: Trivial fails,  Prev: Duplicated clauses,  Up: Compiler warnings and errors

1.12.4.12 Goals that are always true or false
.............................................

A warning will be reported for any goal that is always true or false.
This is usually caused by typos in the code.  For example, writing ‘X ==
y’ instead of ‘X == Y’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Trivial fails,  Next: Suspicious calls,  Prev: Goals that are always true or false,  Up: Compiler warnings and errors

1.12.4.13 Trivial fails
.......................

A warning will be reported for any call to a local static predicate with
no matching clause.


File: TheLogtalkHandbook-3.101.0.info,  Node: Suspicious calls,  Next: Lambda variables,  Prev: Trivial fails,  Up: Compiler warnings and errors

1.12.4.14 Suspicious calls
..........................

A warning will be reported for calls that are syntactically correct but
most likely a semantic error.  An example is *note (;;)/1: 5c. calls in
clauses that apparently are meant to implement recursive predicate
definitions where the user intention is to call the local predicate
definition.


File: TheLogtalkHandbook-3.101.0.info,  Node: Lambda variables,  Next: Redefinition of predicates declared in uses/2 or use_module/2 directives,  Prev: Suspicious calls,  Up: Compiler warnings and errors

1.12.4.15 Lambda variables
..........................

A warning will be reported for *note lambda expressions: 182. with
unclassified variables (not listed as either *note lambda free: 270. or
*note lambda parameter: 271. variables), for variables playing a dual
role (as both lambda free and lambda parameter variables), and for
lambda parameters used elsewhere in a clause.


File: TheLogtalkHandbook-3.101.0.info,  Node: Redefinition of predicates declared in uses/2 or use_module/2 directives,  Next: Other warnings and errors,  Prev: Lambda variables,  Up: Compiler warnings and errors

1.12.4.16 Redefinition of predicates declared in ‘uses/2’ or ‘use_module/2’ directives
......................................................................................

A error will be reported for any attempt to define locally a predicate
that is already declared in an *note uses/2: 4b. or *note use_module/2:
4d. directive.


File: TheLogtalkHandbook-3.101.0.info,  Node: Other warnings and errors,  Prev: Redefinition of predicates declared in uses/2 or use_module/2 directives,  Up: Compiler warnings and errors

1.12.4.17 Other warnings and errors
...................................

The Logtalk compiler will throw an error if it finds a predicate clause
or a directive that cannot be parsed.  The default behavior is to report
the error and abort the compilation.


File: TheLogtalkHandbook-3.101.0.info,  Node: Runtime errors,  Prev: Compiler warnings and errors,  Up: Error handling

1.12.5 Runtime errors
---------------------

This section briefly describes runtime errors that result from misuse of
Logtalk built-in predicates, built-in methods, or from message-sending.
For a complete and detailed description of runtime errors, please
consult the Reference Manual.

* Menu:

* Logtalk built-in predicates::
* Logtalk built-in methods::
* Message sending::


File: TheLogtalkHandbook-3.101.0.info,  Node: Logtalk built-in predicates,  Next: Logtalk built-in methods,  Up: Runtime errors

1.12.5.1 Logtalk built-in predicates
....................................

Most Logtalk built-in predicates check the type and mode of the calling
arguments, throwing an exception in case of misuse.


File: TheLogtalkHandbook-3.101.0.info,  Node: Logtalk built-in methods,  Next: Message sending,  Prev: Logtalk built-in predicates,  Up: Runtime errors

1.12.5.2 Logtalk built-in methods
.................................

Most Logtalk built-in method check the type and mode of the calling
arguments, throwing an exception in case of misuse.


File: TheLogtalkHandbook-3.101.0.info,  Node: Message sending,  Prev: Logtalk built-in methods,  Up: Runtime errors

1.12.5.3 Message sending
........................

The message-sending mechanisms always check if the receiver of a message
is a defined object and if the message corresponds to a declared
predicate within the scope of the sender.  The built-in protocol
forwarding(1) declares a predicate, *note forward/1: 105, which is
automatically called (if defined) by the runtime for any message that
the receiving object does not understand.  The usual definition for this
error handler is to delegate or forward the message to another object
that might be able to answer it:

     forward(Message) :-
         % forward the message while preserving the sender
         [Object::Message].

If preserving the original sender is not required, this definition can
be simplified to:

     forward(Message) :-
         Object::Message.

More sophisticated definitions are, of course, possible.

   ---------- Footnotes ----------

   (1) ../../apis/forwarding_0.html#forwarding-0


File: TheLogtalkHandbook-3.101.0.info,  Node: Reflection,  Next: Writing and running applications,  Prev: Error handling,  Up: User Manual

1.13 Reflection
===============

Logtalk provides support for both 'structural' and 'behavioral'
reflection.  Structural reflection supports computations over an
application structure.  Behavioral reflection supports computations over
what an application does while running.  The structural and behavioral
reflection APIs are used by all the *note developer tools: 280, which
are regular applications.

* Menu:

* Structural reflection::
* Behavioral reflection::


File: TheLogtalkHandbook-3.101.0.info,  Node: Structural reflection,  Next: Behavioral reflection,  Up: Reflection

1.13.1 Structural reflection
----------------------------

Structural reflection allows querying the properties of objects,
categories, protocols, and predicates.  This API provides two views on
the structure of an application: a 'transparent-box view' and a
'black-box view', described next.

* Menu:

* Transparent-box view::
* Black-box view::


File: TheLogtalkHandbook-3.101.0.info,  Node: Transparent-box view,  Next: Black-box view,  Up: Structural reflection

1.13.1.1 Transparent-box view
.............................

The transparent-box view provides a structural view of the contents and
properties of entities, predicates, and source files akin to accessing
the corresponding source code.  I.e.  this is the view we use when
asking questions such as: 'What predicates are declared in this
protocol?'  'Which predicates are called by this predicate?'  'Where are
clauses for this multifile predicate defined?'

For entities, built-in predicates are provided for *note enumerating
entities: 284, *note enumerating entity properties: 6f. (including
entity declared, defined, called, and updated predicates; i.e.  full
predicate cross-referencing data), and *note enumerating entity
relations: 285. (for full entity cross-referencing data).  For a
detailed description of the supported entity properties, see the
sections on *note object properties: c5, *note protocol properties: f3,
and *note category properties: 12a.  For examples of querying entity
relations, see the sections on *note object relations: bc, *note
protocol relations: ef, and *note category relations: 127.

     Note: Some entity and predicate properties are only available when
     the source files are compiled with the *note source_data: cc. flag
     turned on.

The logtalk(1) built-in object provides predicates for querying loaded
source files and their properties.

   ---------- Footnotes ----------

   (1) ../../apis/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.101.0.info,  Node: Black-box view,  Prev: Transparent-box view,  Up: Structural reflection

1.13.1.2 Black-box view
.......................

The black-box view provides a view that takes into account entity
encapsulation and thus only allows querying about predicates and
operators that are within the scope of the entity calling the reflection
methods.  This is the view we use when asking questions such as: 'What
messages can be sent to this object?'

Built-in methods are provided for querying the *note predicates that are
declared and can be called or used as messages: 141. and for querying
the *note predicate properties: 142.  It is also possible to enumerate
*note entity operators: 15e.  See the sections on *note finding declared
predicates: 1ce. and on *note predicate properties: 1cc. for more
details.


File: TheLogtalkHandbook-3.101.0.info,  Node: Behavioral reflection,  Prev: Structural reflection,  Up: Reflection

1.13.2 Behavioral reflection
----------------------------

Behavioral reflection provides insight on what an application does when
running.  Specifically, by observing and acting on the messages being
exchanged between objects.  See the section on *note event-driven
programming: 6d. for details.  There is also a *note dependents: 289.
library that provides an implementation of Smalltalk dependents
mechanism.

For use in debugging tools, there is also a small reflection API
providing *note trace and debug event predicates: d5. provided by the
logtalk(1) built-in object.

   ---------- Footnotes ----------

   (1) ../../apis/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.101.0.info,  Node: Writing and running applications,  Next: Printing messages and asking questions,  Prev: Reflection,  Up: User Manual

1.14 Writing and running applications
=====================================

For successful programming in Logtalk, you need a good working knowledge
of Prolog and an understanding of the principles of object-oriented
programming.  Most guidelines for writing good Prolog code apply as well
to Logtalk programming.  To those guidelines, you should add the basics
of good object-oriented design.

One of the advantages of a system like Logtalk is that it enables us to
use the currently available object-oriented methodologies, tools, and
metrics *note [Champaux92]: 28d. in logic programming.  That said,
writing applications in Logtalk is similar to writing applications in
Prolog: we define new predicates describing what is true about our
domain objects, about our problem solution.  We encapsulate our
predicate directives and definitions inside new objects, categories, and
protocols that we create by hand with a text editor or by using the
Logtalk built-in predicates.  Some of the information collected during
the analysis and design phases can be integrated into the objects,
categories, and protocols that we define by using the available entity
and predicate documenting directives.

* Menu:

* Starting Logtalk::
* Running parallel Logtalk processes::
* Source files::
* Multi-pass compiler::
* Compiling and loading your applications::
* Compiler errors, warnings, and comments: Compiler errors warnings and comments.
* Loader files::
* Libraries of source files::
* Settings files::
* Compiler linter::
* Compiler flags::
* Reloading source files::
* Batch processing::
* Optimizing performance::
* Portable applications::
* Conditional compilation::
* Avoiding common errors::
* Coding style guidelines::


File: TheLogtalkHandbook-3.101.0.info,  Node: Starting Logtalk,  Next: Running parallel Logtalk processes,  Up: Writing and running applications

1.14.1 Starting Logtalk
-----------------------

We run Logtalk inside a normal Prolog session, after loading the
necessary files.  Logtalk extends but does not modify your Prolog
compiler.  We can freely mix Prolog queries with the sending of
messages, and our applications can be made of both normal Prolog clauses
and object definitions.

Depending on your Logtalk installation, you may use a script or a
shortcut to start Logtalk with your chosen Prolog compiler.  On POSIX
operating-systems, Bash shell integration scripts should be available
from the command-line.  On Windows, PowerShell integration scripts
should be available from the command-line and integration shortcuts
should be available from the Start Menu.  Scripts are named upon the
used backend Prolog compilers.

For example, assuming a POSIX operating-system and GNU Prolog as the
backend:

     $ gplgt
     ...

Depending on your Logtalk installation, you may need to type instead
‘gplgt.sh’.  On Windows, using PowerShell 7.2 or a later version and
ECLiPSe as the backend:

     PS> eclipselgt.ps1
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Running parallel Logtalk processes,  Next: Source files,  Prev: Starting Logtalk,  Up: Writing and running applications

1.14.2 Running parallel Logtalk processes
-----------------------------------------

Running parallel Logtalk processes is enabled by setting the *note
clean: 292. flag to ‘on’.  This is the default flag value in the backend
adapter files.  With this setting, the intermediate Prolog files
generated by the Logtalk compiler include the process identifier in the
names, thus preventing file name clashes when running parallel
processes.  When the flag is turned off, the generated intermediate
Prolog file names don’t include the process identifier and are kept
between runs.  This is usually done to avoid repeated recompilation of
stable code when developing large applications or when running multiple
test sets for performance (by avoiding repeated recompilation of the
*note lgtunit: 146. tool).

To run parallel Logtalk processes with the ‘clean’ flag turned off, each
process must use its own *note scratch directory: 293.  This is
accomplished by defining the ‘scratch_directory’ library alias to a
per-process location 'before' loading the compiler/runtime.  For
example, assuming we’re using GNU Prolog as the backend, a possible
definition could be:

     :- multifile(logtalk_library_path/2).
     :- dynamic(logtalk_library_path/2).

     logtalk_library_path(scratch_directory, Directory) :-
         temporary_name(lgtXXXXXX, Name),
         decompose_file_name(Name, _, Prefix, _),
         atom_concat('/tmp/', Prefix, Directory),
         (   file_exists(Directory) ->
             true
         ;   make_directory(Directory)
         ).

Assuming the code above is saved in a
‘parallel_logtalk_processes_setup.pl’ file, we would then start Logtalk
using:

     $ gplgt --init-goal "consult('parallel_logtalk_processes_setup.pl')"

The details on how to define and load the definition of the
‘scratch_directory’ library alias are, however, backend specific (due to
the lack of Prolog standardization) and possibly also operating-system
specific (different locations for the temporary directory).  The Logtalk
library includes a ‘parallel_logtalk_processes_setup.pl’ file with
support for selected backends and usage instructions.


File: TheLogtalkHandbook-3.101.0.info,  Node: Source files,  Next: Multi-pass compiler,  Prev: Running parallel Logtalk processes,  Up: Writing and running applications

1.14.3 Source files
-------------------

Logtalk source files may define any number of entities (objects,
categories, or protocols).  Source files may also contain Prolog code
interleaved with Logtalk entity definitions.  Plain Prolog code is
usually copied as-is to the corresponding Prolog output file (except, of
course, if subject to the *note term-expansion mechanism: cb.).  Prolog
modules are compiled as objects.  The following Prolog directives are
processed when read (thus affecting the compilation of the source code
that follows): ‘ensure_loaded/1’, ‘use_module/1-2’, ‘op/3’, and
‘set_prolog_flag/2’.  The *note initialization/1: 42. directive may be
used for defining an initialization goal to be executed when loading a
source file.

Logtalk source files can include the text of other files by using the
*note include/1: b8. directive.  Although there is also a standard
Prolog ‘include/1’ directive, any occurrences of this directive in a
Logtalk source file is handled by the Logtalk compiler, not by the *note
backend Prolog compiler: 34, to improve portability.

When writing a Logtalk source file, the following advice applies:

   - When practical and when performance is critical, define each entity
     on its own source file.

   - Source file loading order can impact performance (e.g., if an
     object imports a category defined in a source file loaded after the
     object source file, no static binding optimizations will be
     possible).

   - Initialization directives that result in the compilation and
     loading of other source files (e.g., libraries) should preferably
     be written in the application loader file to ensure the
     availability of the entities they define when compiling the
     application source files (thus enabling static binding
     optimizations).

Note that you can use the logtalk::loaded_files_topological_sort/1(1)
and logtalk::loaded_files_topological_sort/2(2) predicates to find an
optimal file loading order to eliminate compilation warnings due to
files being loaded before their dependencies.  In the case of simple
applications with no library dependencies:

     ?- {loader}.  % load you application code
     ...

     ?- logtalk::loaded_files_topological_sort(Sorted).
     Sorted = [...]

Use the file basenames from the returned list to update the application
driver files (typically, ‘loader.lgt’ and ‘tester.lgt’).

In more complex applications with external library dependencies, define
a library alies for your application (e.g., ‘my_app’) and use ot get an
initial list of your application files:

     ?- {my_app(loader)}.  % load you application code
     ...

     ?- findall(Path, logtalk::loaded_file_property(Path, library(my_app)), Paths),
        logtalk::loaded_files_topological_sort(Paths, Sorted).
        Sorted = [...]

Note that the ‘Sorted’ list will include the loader file itself.

* Menu:

* Naming conventions::
* Source file text encoding::

   ---------- Footnotes ----------

   (1) 
../../apis/logtalk_0.html#logtalk-0-loaded-files-topological-sort-1

   (2) 
../../apis/logtalk_0.html#logtalk-0-loaded-files-topological-sort-2


File: TheLogtalkHandbook-3.101.0.info,  Node: Naming conventions,  Next: Source file text encoding,  Up: Source files

1.14.3.1 Naming conventions
...........................

When defining each entity in its own source file, it is recommended that
the source file be named after the entity identifier.  For parametric
objects, the identifier arity can be appended to the identifier functor.
By default, all Logtalk source files use the extension ‘.lgt’ but this
is optional and can be set in the adapter files.  For example, we may
define an object named ‘vehicle’ and save it in a ‘vehicle.lgt’ source
file.  A ‘sort(_)’ parametric object would be saved it on a ‘sort_1.lgt’
source file.


File: TheLogtalkHandbook-3.101.0.info,  Node: Source file text encoding,  Prev: Naming conventions,  Up: Source files

1.14.3.2 Source file text encoding
..................................

The text encoding used in a source file may be declared using the *note
encoding/1: 298. directive when running Logtalk with backend Prolog
compilers that support multiple encodings (check the *note
encoding_directive: 299. flag in the adapter file of your Prolog
compiler).


File: TheLogtalkHandbook-3.101.0.info,  Node: Multi-pass compiler,  Next: Compiling and loading your applications,  Prev: Source files,  Up: Writing and running applications

1.14.4 Multi-pass compiler
--------------------------

Logtalk is implemented using a 'multi-pass' compiler.  In comparison,
some Prolog systems use a multi-pass compiler while others use a
single-pass compiler.  While there are pros and cons with each solution,
the most relevant consequence in this context is for the content of
source files.  In Logtalk, entities and predicates only become available
(for the runtime system) after the source file is successfully compiled
and loaded.  This may prevent some compiler optimizations, notably *note
static binding: 35, if some of the referred entities are defined in the
same source file.  On the other hand, the order of predicate directives
and predicate definitions is irrelevant.  In contrast, in a system
implemented using a single-pass compiler, the order of the source file
terms can and often is significant for proper and successful
compilation.  In these systems, predicates may become available for
calling as soon as they are compiled, even if the rest of the source
file is yet to be compiled.

The Logtalk compiler reads source files using the Prolog standard
‘read_term/3’ predicate.  This ensures compatibility with any syntax
extensions that the used backend may implement.  In the first compiler
stage, all source file terms are read, and data about all defined
entities, directives, predicates, and grammar rules is collected.  Any
defined *note term-expansion rules: cb. are applied to the read terms.
Grammar rules are expanded into predicate clauses unless expanded by
user-defined term-expansion rules.  The second stage compiles all
initialization goals and clause bodies, taking advantage of the data
collected in the first stage and applying any defined goal-expansion
rules.  Depending on the compilation mode, the generated code can be
instrumented for debugging tools or optimized for performance.  Linter
checks are performed during these two first stages.  The final step in
the second stage is to write the generated intermediate Prolog code into
a temporary file.  In the third and final stage, this intermediate
Prolog file is compiled and loaded by the used backend.  These
intermediate files are deleted by default after loading (see the *note
clean: 292. flag description for details).


File: TheLogtalkHandbook-3.101.0.info,  Node: Compiling and loading your applications,  Next: Compiler errors warnings and comments,  Prev: Multi-pass compiler,  Up: Writing and running applications

1.14.5 Compiling and loading your applications
----------------------------------------------

Your applications will be made of source files containing your objects,
protocols, and categories.  The source files can be compiled to disk by
calling the *note logtalk_compile/1: 29e. built-in predicate:

     | ?- logtalk_compile([source_file1, source_file2, ...]).

This predicate runs the compiler on each file and, if no fatal errors
are found, outputs Prolog source files that can then be consulted or
compiled in the usual way by your Prolog compiler.

To compile to disk and also load into memory the source files, we can
use the *note logtalk_load/1: 46. built-in predicate:

     | ?- logtalk_load([source_file1, source_file2, ...]).

This predicate works in the same way as the predicate
‘logtalk_compile/1’ but also loads the compiled files into memory.

Both predicates expect a source file name or a list of source file names
as an argument.  The Logtalk source file name extension, as defined in
the adapter file (by default, ‘.lgt’), can be omitted.

If you have more than a few source files, then you may want to use a
*note loader file: 4f. helper file containing the calls to the
‘logtalk_load/1-2’ predicates.  Consulting or compiling the loader file
will then compile and load all your Logtalk entities into memory (see
below for details).

With most *note backend Prolog compilers: 34, you can use the shorthand
‘{File}’ for ‘logtalk_load(File)’ and ‘{File1, File2, ...}’ for
‘logtalk_load([File1, File2, ...])’.  The use these shorthands should be
restricted to the Logtalk/Prolog top-level interpreter, as they are not
part of the language specification and may be commented out in case of
conflicts with backend Prolog compiler features.

The built-in predicate *note logtalk_make/0: 29f. can be used to reload
all modified source files.  With most backend Prolog compilers, you can
also use the ‘{*}’ top-level shortcut.  Files are also reloaded when the
compilation mode changes.  An extended version of this predicate, *note
logtalk_make/1: 2a0, accepts multiple targets, including ‘all’, ‘clean’,
‘check’, ‘circular’, ‘documentation’, ‘caches’, ‘debug’, ‘normal’, and
‘optimal’.  For example, assume that you have loaded your application
files and found a bug.  You can easily recompile the files in debug mode
by using the ‘logtalk_make(debug)’ goal.  After debugging and fixing the
bug, you can reload the files in normal mode using the
‘logtalk_make(normal)’ or in optimized mode using the
‘logtalk_make(optimal)’ goal.  See the predicates documentation for a
complete list of targets and top-level shortcuts.  In particular, the
‘logtalk_make(clean)’ goal can be specially useful before switching
backend Prolog compilers, as the generated intermediate files may not be
compatible.  The ‘logtalk_make(caches)’ goal is usually used when
benchmarking compiler performance improvements.


File: TheLogtalkHandbook-3.101.0.info,  Node: Compiler errors warnings and comments,  Next: Loader files,  Prev: Compiling and loading your applications,  Up: Writing and running applications

1.14.6 Compiler errors, warnings, and comments
----------------------------------------------

Following a Prolog tradition inherited from Quintus Prolog, the compiler
prefixes (by default) errors with a ‘!’ and warnings with a ‘*’.  For
example:

     !     Existence error: directive object/1 does not exist
     !       in directive end_object/0
     !       in file /home/jdoe/logtalk/examples/errors/unmatched_directive.lgt at or above line 27

     *     No matching clause for goal: baz(a)
     *       while compiling object main_include_compiler_warning
     *       in file /home/jdoe/logtalk/examples/errors/include_compiler_warning.lgt between lines 38-39

Compiler comments are prefixed by ‘%’.  For example:

     ?- {ack(loader)}.
     % [ /home/jdoe/logtalk/examples/ack/ack.lgt loaded ]
     % [ /home/jdoe/logtalk/examples/ack/loader.lgt loaded ]
     % (0 warnings)
     true.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loader files,  Next: Libraries of source files,  Prev: Compiler errors warnings and comments,  Up: Writing and running applications

1.14.7 Loader files
-------------------

If you look into the Logtalk distribution, you will notice that most
source code directories (e.g., of tools, libraries, and examples)
contain a 'driver file' that can be used to load all included source
files and any required libraries.  These loader files are usually named
‘loader.lgt’ or contain the word 'loader' in their name.  Loader files
are ordinary source files and thus compiled and loaded like any source
file.  By also defining a loader file for your project, you can then
load it by simply typing:

     | ?- {loader}.

Another driver file, usually named ‘tester.lgt’ (or containing the word
'tester' in its name) is commonly used to load and run tests.  By also
defining a tester file for your project, you can then run its tests by
simply typing:

     | ?- {tester}.

Usually these driver files contain calls to the built-in predicates
*note set_logtalk_flag/2: 51. (e.g., for setting global,
'project-specific', flag values) and *note logtalk_load/1: 46. or *note
logtalk_load/2: 4e. (for loading project files), wrapped inside a Prolog
‘initialization/1’ directive for portability.  For instance, if your
code is split into three source files named ‘source1.lgt’,
‘source2.lgt’, and ‘source3.lgt’, then the contents of your loader file
could be:

     :- initialization((
         % set project-specific global flags
         set_logtalk_flag(events, allow),
         % load the project source files
         logtalk_load([source1, source2, source3])
     )).

Another example of directives that are often used in a loader file would
be ‘op/3’ directives declaring global operators needed by your project.
Loader files are also often used for setting source file-specific
compiler flags (this is useful even when you only have a single source
file if you always load it with the same set of compiler flags).  For
example:

     :- initialization((
         % set project-specific global flags
         set_logtalk_flag(source_data, off),
         % load the project source files
         logtalk_load(
             [source1, source2, source3],
             % source file-specific flags
             [portability(warning)]),
         logtalk_load(
             [source4, source5],
             % source file-specific flags
             [portability(silent)])
     )).

To take the best advantage of loader and tester files, define a clause
for the multifile and dynamic ‘logtalk_library_path/2’ predicate for the
directory containing your source files as explained in the next section.

When your project also uses Prolog module resources, the loader file is
also the advised place to load them, preferably without any exports.
For example:

     :- use_module(library(clpfd), []).
     ...

     :- initialization((
         ...
     )).

Complex projects often use a main loader file that loads the loader
files of each of the project components.  Thus, loader files provide a
central point to understand a project organization and dependencies.

It is worth mentioning a common mistake when writing the first loader
files.  New users sometimes try to set compiler flags using
‘logtalk_load/2’ when loading a loader file.  For example, by writing:

     | ?- logtalk_load(loader, [optimize(on)]).

This will not work as you might expect, as the compiler flags will only
be used in the compilation of the ‘loader.lgt’ file itself and will not
affect the compilation of files loaded through the ‘initialization/1’
directive contained on the loader file.


File: TheLogtalkHandbook-3.101.0.info,  Node: Libraries of source files,  Next: Settings files,  Prev: Loader files,  Up: Writing and running applications

1.14.8 Libraries of source files
--------------------------------

Logtalk defines a 'library' simply as a directory containing source
files.  Library locations can be specified by defining or asserting
clauses for the dynamic and multifile predicate *note
logtalk_library_path/2: 2a7.  For example:

     :- multifile(logtalk_library_path/2).
     :- dynamic(logtalk_library_path/2).

     logtalk_library_path(shapes, '$LOGTALKUSER/examples/shapes/').

The first argument of the predicate is used as an alias for the path on
the second argument.  Library aliases may also be used on the second
argument.  For example:

     :- multifile(logtalk_library_path/2).
     :- dynamic(logtalk_library_path/2).

     logtalk_library_path(lgtuser, '$LOGTALKUSER/').
     logtalk_library_path(examples, lgtuser('examples/')).
     logtalk_library_path(viewpoints, examples('viewpoints/')).

This allows us to load a library source file without the need to first
change the current working directory to the library directory and then
back to the original directory.  For example, in order to load a
‘loader.lgt’ file, contained in a library named ‘viewpoints’, we just
need to type:

     | ?- logtalk_load(viewpoints(loader)).

The best way to take advantage of this feature is to load at startup a
source file containing clauses for the ‘logtalk_library_path/2’
predicate needed for all available libraries (typically, using a *note
settings file: 49, as discussed below).  This allows us to load library
source files or entire libraries without worrying about library paths,
improving code portability.  The directory paths on the second argument
should always end with the path directory separator character.  Most
backend Prolog compilers allow the use of environment variables in the
second argument of the ‘logtalk_library_path/2’ predicate.  Use of POSIX
relative paths (e.g., ‘'../'’ or ‘'./'’) for top-level library
directories (e.g., ‘lgtuser’ in the example above) is not advised, as
different backend Prolog compilers may start with different initial
working directories, which may result in portability problems of your
loader files.

This *note library notation: 2a8. provides functionality inspired by the
‘file_search_path/2’ mechanism introduced by Quintus Prolog and later
adopted by some other Prolog compilers but with a key difference: there
is no fragile search mechanism, and the Logtalk ‘make’ can be used to
check for duplicated library aliases.  Multiple definitions for the same
alias are problematic when using external dependencies, as any
third-party update to those dependencies can introduce file name
clashes.  Note that the potential for these clashes cannot be reliably
minimized by a careful ordering of the ‘logtalk_library_path/2’
predicate clauses due to this predicate being multifile and dynamic.


File: TheLogtalkHandbook-3.101.0.info,  Node: Settings files,  Next: Compiler linter,  Prev: Libraries of source files,  Up: Writing and running applications

1.14.9 Settings files
---------------------

Although it is always possible to edit the *note backend Prolog
compiler: 34. adapter files, the recommended solution to customize
compiler flags is to create a ‘settings.lgt’ file in the Logtalk user
folder or in the user home folder.  Depending on the backend Prolog
compiler and the operating-system, is also possible to define
per-project settings files by creating a ‘settings.lgt’ file in the
project directory and by starting Logtalk from this directory.  At
startup, Logtalk tries to load a ‘settings.lgt’ file from the following
directories, searched in sequence:

   - Startup directory (‘$LOGTALK_STARTUP_DIRECTORY’)

   - Logtalk user directory (‘$LOGTALKUSER’)

   - User home directory (‘$HOME’; ‘%USERPROFILE%’ on Windows if
     ‘%HOME%’ is not defined)

   - Application data directory (‘%APPDATA%\Logtalk’; only on Windows)

   - Config directory (‘$XDG_CONFIG_HOME/logtalk’)

   - Default config directory (‘$HOME/.config/logtalk/’)

The startup directory is only searched when the read-only *note
settings_file: 2ab. flag is set to ‘allow’.  When no settings files are
found, Logtalk will use the default compiler flag values set on the
backend Prolog compiler adapter files.  When limitations of the backend
Prolog compiler or the operating-system prevent Logtalk from finding the
settings files, these can always be loaded manually after Logtalk
startup.

Settings files are normal Logtalk source files (although when
automatically loaded by Logtalk they are compiled and loaded silently
with any errors being reported but otherwise ignored).  The usual
contents is an ‘initialization/1’ Prolog directive containing calls to
the *note set_logtalk_flag/2: 51. Logtalk built-in predicate and
asserting clauses for the *note logtalk_library_path/2: 2a7. multifile
dynamic predicate.  Note that the *note set_logtalk_flag/2: 50.
directive cannot be used as its scope is local to the source file being
compiled.

One of the troubles of writing portable applications is the different
feature sets of Prolog compilers.  Using the Logtalk support for
conditional compilation and the *note prolog_dialect: 2ac. flag we can
write a single settings file that can be used with several *note backend
Prolog compilers: 34.:

     :- if(current_logtalk_flag(prolog_dialect, yap)).

         % YAP specific settings
         ...

     :- elif(current_logtalk_flag(prolog_dialect, gnu)).

         % GNU Prolog specific settings
         ...

     :- else.

         % generic Prolog settings

     :- endif.

The Logtalk distribution includes a ‘samples/settings-sample.lgt’ sample
file with commented out code snippets for common settings.


File: TheLogtalkHandbook-3.101.0.info,  Node: Compiler linter,  Next: Compiler flags,  Prev: Settings files,  Up: Writing and running applications

1.14.10 Compiler linter
-----------------------

The compiler includes a *note linter: 2af. that checks for a wide range
of possible problems in source files.  Notably, the compiler checks for
unknown entities, unknown predicates, undefined predicates (i.e.,
predicates that are declared but not defined), missing directives
(including missing ‘dynamic/1’ and ‘meta_predicate/1’ directives),
redefined built-in predicates, calls to non-portable predicates,
singleton variables, goals that are always true or always false (i.e.,
goals that can be replaced by ‘true’ or ‘fail’), and trivial fails
(i.e., calls to predicates with no match clauses).  Most of the linter
warnings are controlled by *note compiler flags: 2b0.  See the next
section for details.


File: TheLogtalkHandbook-3.101.0.info,  Node: Compiler flags,  Next: Reloading source files,  Prev: Compiler linter,  Up: Writing and running applications

1.14.11 Compiler flags
----------------------

The *note logtalk_load/1: 46. and *note logtalk_compile/1: 29e. always
use the current set of default compiler flags as specified in your
settings file and the Logtalk adapter files or changed for the current
session using the built-in predicate *note set_logtalk_flag/2: 51.
Although the default flag values cover the usual cases, you may want to
use a different set of flag values while compiling or loading some of
your Logtalk source files.  This can be accomplished by using the *note
logtalk_load/2: 4e. or the *note logtalk_compile/2: 2b2. built-in
predicates.  These two predicates accept a list of options affecting how
a Logtalk source file is compiled and loaded:

     | ?- logtalk_compile(Files, Options).

or:

     | ?- logtalk_load(Files, Options).

In fact, the ‘logtalk_load/1’ and ‘logtalk_compile/1’ predicates are
just shortcuts to the extended versions called with the default compiler
flag values.  The options are represented by a compound term where the
functor is the flag name and the sole argument is the flag value.

We may also change the default flag values from the ones loaded from the
adapter file by using the *note set_logtalk_flag/2: 51. built-in
predicate.  For example:

     | ?- set_logtalk_flag(unknown_entities, silent).

The current default flags values can be enumerated using the *note
current_logtalk_flag/2: 2b3. built-in predicate:

     | ?- current_logtalk_flag(unknown_entities, Value).

     Value = silent
     yes

Logtalk also implements a *note set_logtalk_flag/2: 50. directive, which
can be used to set flags within a source file or within an entity.  For
example:

     % compile objects in this source file with event support
     :- set_logtalk_flag(events, allow).

     :- object(foo).

         % compile this object with support
         % for dynamic predicate declarations
         :- set_logtalk_flag(dynamic_declarations, allow).
         ...

     :- end_object.

     ...

Note that the scope of the ‘set_logtalk_flag/2’ directive is local to
the entity or to the source file containing it.

     Note: Applications should never rely on default flag values for
     working properly.  Whenever the compilation of a source file or an
     entity requires a specific flag value, the flag should be set
     explicitly in the entity, in the source file, or in the loader
     file.

* Menu:

* Read-only flags::
* Version flags::
* Lint flags::
* Optional features compilation flags::
* Backend Prolog compiler and loader flags::
* Other flags::
* User-defined flags::


File: TheLogtalkHandbook-3.101.0.info,  Node: Read-only flags,  Next: Version flags,  Up: Compiler flags

1.14.11.1 Read-only flags
.........................

Some flags have read-only values and thus cannot be changed at runtime.
Their values are defined in the Prolog backend *note adapter files: 154.
These are:

‘settings_file’

     Allows or disables loading of a *note settings file: 49. at
     startup.  Possible values are ‘allow’, ‘restrict’, and ‘deny’.  The
     usual default value is ‘allow’ but it can be changed by editing the
     adapter file when e.g.  embedding Logtalk in a compiled
     application.  With a value of ‘allow’, settings files are searched
     in the startup directory, in the Logtalk user directory, in the
     user home directory, in the ‘APPDATA’ if running on Windows, and in
     the XDG configuration directory.  With a value of ‘restrict’, the
     search for the settings files skips the startup directory.

‘prolog_dialect’

     Identifier of the *note backend Prolog compiler: 34. (an atom).
     This flag can be used for *note conditional compilation: 18a. of
     Prolog compiler specific code.

‘prolog_version’

     Version of the *note backend Prolog compiler: 34. (a compound term,
     ‘v(Major, Minor, Patch)’, whose arguments are integers).  This flag
     availability depends on the Prolog compiler.  Checking the value of
     this flag fails for any Prolog compiler that does not provide
     access to version data.

‘prolog_compatible_version’

     Compatible version of the *note backend Prolog compiler: 34. (a
     compound term, usually with the format ‘@>=(v(Major, Minor,
     Patch))’, whose arguments are integers).  This flag availability
     depends on the Prolog compiler.  Checking the value of this flag
     fails for any Prolog compiler that does not provide access to
     version data.

‘unicode’

     Informs Logtalk if the *note backend Prolog compiler: 34. supports
     the Unicode standard.  Possible flag values are ‘unsupported’,
     ‘full’ (all Unicode planes supported), and ‘bmp’ (supports only the
     Basic Multilingual Plane).

‘encoding_directive’

     Informs Logtalk if the *note backend Prolog compiler: 34. supports
     the *note encoding/1: 298. directive.  This directive is used for
     declaring the text encoding of source files.  Possible flag values
     are ‘unsupported’, ‘full’ (can be used in both Logtalk source files
     and compiler generated Prolog files), and ‘source’ (can be used
     only in Logtalk source files).

‘sockets’

     Informs Logtalk if the *note backend Prolog compiler: 34. provides
     compatible sockets support.  Possible flag values are ‘unsupported’
     and ‘supported’.

‘tabling’

     Informs Logtalk if the *note backend Prolog compiler: 34. provides
     tabling programming support.  Possible flag values are
     ‘unsupported’ and ‘supported’.

‘engines’

     Informs if the *note backend Prolog compiler: 34. provides the
     required low level multi-threading programming support for Logtalk
     *note threaded engines: 2bb.  Possible flag values are
     ‘unsupported’ and ‘supported’.

‘threads’

     Informs if the *note backend Prolog compiler: 34. provides the
     required low level multi-threading programming support for all
     high-level Logtalk *note multi-threading features: 73.  Possible
     flag values are ‘unsupported’ and ‘supported’.

‘modules’

     Informs Logtalk if the *note backend Prolog compiler: 34. provides
     suitable module support.  Possible flag values are ‘unsupported’
     and ‘supported’ (independently of this flag, Logtalk provides
     limited support for compiling Prolog modules as objects).

‘coinduction’

     Informs Logtalk if the *note backend Prolog compiler: 34. provides
     the required minimal support for cyclic terms necessary for working
     with *note coinductive predicates: 170.  Possible flag values are
     ‘unsupported’ and ‘supported’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Version flags,  Next: Lint flags,  Prev: Read-only flags,  Up: Compiler flags

1.14.11.2 Version flags
.......................

‘version_data(Value)’

     Read-only flag whose value is the compound term
     ‘logtalk(Major,Minor,Patch,Status)’.  The first three arguments are
     integers and the last argument is an atom, possibly empty,
     representing version status: ‘aN’ for alpha versions, ‘bN’ for beta
     versions, ‘rcN’ for release candidates (with ‘N’ being a natural
     number), and ‘stable’ for stable versions.  The ‘version_data’ flag
     is also a de facto standard for Prolog compilers.


File: TheLogtalkHandbook-3.101.0.info,  Node: Lint flags,  Next: Optional features compilation flags,  Prev: Version flags,  Up: Compiler flags

1.14.11.3 Lint flags
....................

‘linter(Option)’

     Meta-flag for managing the values of all the linter flags as a
     group.  Possible option values are ‘on’ to set all the individual
     linter flags to ‘warning’, ‘off’ to set all the individual linter
     flags to ‘silent’, and ‘default’ to set all the individual linter
     flag values to their defaults as defined in the backend adapter
     files (the usual default).  This flag 'must' always be defined in
     the backend adapter files with the value of ‘default’.

‘unknown_entities(Option)’

     Controls the unknown entity warnings, resulting from loading an
     entity that references some other entity that is not currently
     loaded.  Possible option values are ‘warning’ (the usual default)
     and ‘silent’.  Note that these warnings are not always avoidable,
     specially when using reflective designs of class-based hierarchies.

‘unknown_predicates(Option)’

     Defines the compiler behavior when unknown messages or calls to
     unknown predicates (or non-terminals) are found.  An unknown
     message is a message sent to an object that is not part of the
     object protocol.  An unknown predicate is a called predicate that
     is neither locally declared or defined.  Possible option values are
     ‘error’, ‘warning’ (the usual default), and ‘silent’ (not
     recommended).

‘undefined_predicates(Option)’

     Defines the compiler behavior when calls to declared but undefined
     predicates (or non-terminals) are found.  Note that these calls
     will fail at runtime as per closed-world assumption.  Possible
     option values are ‘error’, ‘warning’ (the usual default), and
     ‘silent’ (not recommended).

‘steadfastness(Option)’

     Controls warnings about 'possible' non *note steadfast: 2c5.
     predicate definitions due to variable aliasing at a clause head and
     a cut in the clause body.  Possible option values are ‘warning’ and
     ‘silent’ (the usual default due to the possibility of false
     positives).

‘portability(Option)’

     Controls the non-ISO specified Prolog built-in predicate and
     non-ISO specified Prolog built-in arithmetic function calls
     warnings plus use of non-standard Prolog flags and/or flag values.
     Possible option values are ‘warning’ and ‘silent’ (the usual
     default).

‘deprecated(Option)’

     Controls the deprecated predicate warnings.  Possible option values
     are ‘warning’ (the usual default) and ‘silent’.

‘missing_directives(Option)’

     Controls the missing predicate directive warnings.  Possible option
     values are ‘warning’ (the usual default) and ‘silent’ (not
     recommended).

‘duplicated_directives(Option)’

     Controls the duplicated predicate directive warnings.  Possible
     option values are ‘warning’ (the usual default) and ‘silent’ (not
     recommended).  Note that conflicting directives for the same
     predicate are handled as errors, not as duplicated directive
     warnings.

‘trivial_goal_fails(Option)’

     Controls the printing of warnings for calls to local static
     predicates with no matching clauses.  Possible option values are
     ‘warning’ (the usual default) and ‘silent’ (not recommended).

‘always_true_or_false_goals(Option)’

     Controls the printing of warnings for goals that are always true or
     false.  Possible option values are ‘warning’ (the usual default)
     and ‘silent’ (not recommended).  A unexpected exception in the goal
     being checked is also reported.

‘grammar_rules(Option)’

     Controls the printing of grammar rules related warnings.  Possible
     option values are ‘warning’ (the usual default) and ‘silent’ (not
     recommended).

‘arithmetic_expressions(Option)’

     Controls the printing of arithmetic expressions related warnings.
     Possible option values are ‘warning’ (the usual default) and
     ‘silent’ (not recommended).

‘lambda_variables(Option)’

     Controls the printing of lambda variable related warnings.
     Possible option values are ‘warning’ (the usual default) and
     ‘silent’ (not recommended).

‘suspicious_calls(Option)’

     Controls the printing of suspicious call warnings.  Possible option
     values are ‘warning’ (the usual default) and ‘silent’ (not
     recommended).

‘redefined_built_ins(Option)’

     Controls the Logtalk and Prolog built-in predicate redefinition
     warnings.  Possible option values are ‘warning’ and ‘silent’ (the
     usual default).  Warnings about redefined Prolog built-in
     predicates are often the result of running a Logtalk application on
     several Prolog compilers, as each Prolog compiler defines its set
     of built-in predicates.

‘redefined_operators(Option)’

     Controls the Logtalk and Prolog built-in operator redefinition
     warnings.  Possible option values are ‘warning’ (the usual default)
     and ‘silent’.  Redefining Logtalk operators or standard Prolog
     operators can break term parsing, causing syntax errors or change
     how terms are parsed, introducing bugs.

‘singleton_variables(Option)’

     Controls the singleton variable warnings.  Possible option values
     are ‘warning’ (the usual default) and ‘silent’ (not recommended).

‘naming(Option)’

     Controls warnings about entity, predicate, and variable names per
     official coding guidelines (which advise using underscores for
     entity and predicate names and camel case for variable names).
     Additionally, variable names should not differ only in case.
     Possible option values are ‘warning’ and ‘silent’ (the usual
     default due to the current limitation to ASCII names and the
     computational cost of the checks).

‘duplicated_clauses(Option)’

     Controls warnings of duplicated entity clauses (and duplicated
     entity grammar rules).  Possible option values are ‘warning’ and
     ‘silent’ (the usual default due to the required heavy
     computations).  When the term-expansion mechanism is used and
     results in duplicated clauses, the reported line numbers are for
     lines of the original clauses that were expanded.

‘disjunctions(Option)’

     Controls warnings on clauses where the body is a disjunction.
     Possible option values are ‘warning’ (the usual default) and
     ‘silent’.  As per coding guidelines, in most cases, these clauses
     can be rewritten using a clause per disjunction branch for improved
     code readability.

‘conditionals(Option)’

     Controls warnings on if-then-else and soft-cut control constructs.
     Possible option values are ‘warning’ (the usual default) and
     ‘silent’.  Warnings include misuse of cuts, potential bugs in the
     test part, and missing else part (lack of compliance with coding
     guidelines).

‘catchall_catch(Option)’

     Controls warnings on ‘catch/3’ goals that catch all exceptions.
     Possible option values are ‘warning’ and ‘silent’ (the usual
     default).  Lack of standardization often makes it tricky or
     cumbersome to avoid too generic ‘catch/3’ goals when writing
     portable code.

‘left_recursion(Option)’

     Controls warnings of left-recursion on clauses and grammar rules.
     Specifically, when the clause or grammar rule head and the leftmost
     goal in the body are variants.  Possible option values are
     ‘warning’ (the usual default) and ‘silent’.

‘tail_recursive(Option)’

     Controls warnings of non-tail recursive predicate (and
     non-terminal) definitions.  The lint check does not detect all
     cases of non-tail recursive predicate definitions, however.  Also,
     definitions that make two or more recursive calls are not reported
     as usually they cannot be changed to be tail recursive.  Possible
     option values are ‘warning’ and ‘silent’ (the usual default).

‘encodings(Option)’

     Controls the source file text encoding warnings.  Possible option
     values are ‘warning’ (the usual default) and ‘silent’.

‘general(Option)’

     Controls warnings that are not controlled by a specific flag.
     Possible option values are ‘warning’ (the usual default) and
     ‘silent’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Optional features compilation flags,  Next: Backend Prolog compiler and loader flags,  Prev: Lint flags,  Up: Compiler flags

1.14.11.4 Optional features compilation flags
.............................................

‘complements(Option)’

     Allows objects to be compiled with support for complementing
     categories turned off in order to improve performance and security.
     Possible option values are ‘allow’ (allow complementing categories
     to override local object predicate declarations and definitions),
     ‘restrict’ (allow complementing categories to add predicate
     declarations and definitions to an object but not to override
     them), and ‘deny’ (ignore complementing categories; the usual
     default).  This option can be used on a per-object basis.  Note
     that changing this option is of no consequence for objects already
     compiled and loaded.

‘dynamic_declarations(Option)’

     Allows objects to be compiled with support for dynamic declaration
     of new predicates turned off in order to improve performance and
     security.  Possible option values are ‘allow’ and ‘deny’ (the usual
     default).  This option can be used on a per-object basis.  Note
     that changing this option is of no consequence for objects already
     compiled and loaded.  This option is only checked when sending an
     *note asserta/1: 1b2. or *note assertz/1: 1b3. message to an
     object.  Local asserting of new predicates is always allowed.

‘events(Option)’

     Allows message-sending calls to be compiled with or without *note
     event-driven programming: 6d. support.  Possible option values are
     ‘allow’ and ‘deny’ (the usual default).  Objects (and categories)
     compiled with this option set to ‘deny’ use optimized code for
     message-sending calls that do not trigger events.  As such, this
     option can be used on a per-object (or per-category) basis.  Note
     that changing this option is of no consequence for objects already
     compiled and loaded.

‘context_switching_calls(Option)’

     Allows context-switching calls (‘(<<)/2’) to be either allowed or
     denied.  Possible option values are ‘allow’ and ‘deny’.  The
     default flag value is ‘allow’.  Note that changing this option is
     of no consequence for objects already compiled and loaded.


File: TheLogtalkHandbook-3.101.0.info,  Node: Backend Prolog compiler and loader flags,  Next: Other flags,  Prev: Optional features compilation flags,  Up: Compiler flags

1.14.11.5 Backend Prolog compiler and loader flags
..................................................

‘underscore_variables(Option)’

     Controls the interpretation of variables that start with an
     underscore (excluding the anonymous variable) that occur once in a
     term as either don’t care variables or singleton variables.
     Possible option values are ‘dont_care’ (the default for all
     supported backends) and ‘singletons’.  Although a changeable flag,
     its value is backend dependent and thus expected to be set only in
     the backend adapter files.

‘prolog_compiler(Flags)’

     List of compiler flags for the generated Prolog files.  The valid
     flags are specific to the used Prolog backend compiler.  The usual
     default is the empty list.  These flags are passed to the backend
     Prolog compiler built-in predicate that is responsible for
     compiling to disk a Prolog file.  For Prolog compilers that don’t
     provide separate predicates for compiling and loading a file, use
     instead the *note prolog_loader: 2de. 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.101.0.info,  Node: Other flags,  Next: User-defined flags,  Prev: Backend Prolog compiler and loader flags,  Up: Compiler flags

1.14.11.6 Other flags
.....................

‘scratch_directory(Directory)’

     Sets the directory to be used to store the temporary files
     generated when compiling Logtalk source files.  This directory can
     be specified using an atom or using *note library notation: 2a8.
     The directory must always end with a slash.  The default value is a
     sub-directory of the source files directory, either ‘'./lgt_tmp/'’
     or ‘'./.lgt_tmp/'’ (depending on the backend Prolog compiler and
     operating-system).  Relative directories must always start with
     ‘'./'’ due to the lack of a portable solution to check if a path is
     relative or absolute.  The default value set on the *note backend
     Prolog compiler: 34. adapter file can be overridden by defining the
     ‘scratch_directory’ library alias (see the *note
     logtalk_library_path/2: 2a7. predicate documentation for details).

‘report(Option)’

     Controls the default printing of messages.  Possible option values
     are ‘on’ (by usual default, print all messages that are not
     intercepted by the user), ‘warnings’ (only print warning and error
     messages that are not intercepted by the user), and ‘off’ (do not
     print any messages that are not intercepted by the user).

‘code_prefix(Character)’

     Enables the definition of prefix for all functors of Prolog code
     generated by the Logtalk compiler.  The option value must be a
     single character atom.  Its default value is ‘'$'’.  Specifying a
     code prefix provides a way to solve possible conflicts between
     Logtalk compiled code and other Prolog code.  In addition, some
     Prolog compilers automatically hide predicates whose functor starts
     with a specific prefix, such as the character ‘$’.  Although this
     is not a read-only flag, it should only be changed at startup time
     and 'before' loading any source files.  When changing this flag
     (e.g., from a *note settings file: 49.), restart with the *note
     clean: 292. flag turned on to ensure that any compiled files using
     the old ‘code_prefix’ value will be recompiled.

‘optimize(Option)’

     Controls the compiler optimizations.  Possible option values are
     ‘on’ (used by default for deployment) and ‘off’ (used by default
     for development).  Compiler optimizations include the use of static
     binding whenever possible, the removal of redundant calls to
     ‘true/0’ from predicate clauses, the removal of redundant
     unifications when compiling grammar rules, and inlining of
     predicate definitions with a single clause that links to a local
     predicate, to a plain Prolog built-in (or foreign) predicate, or to
     a Prolog module predicate with the same arguments.  Care should be
     taken when developing applications with this flag turned on as
     changing and reloading a file may render *note static binding: 35.
     optimizations invalid for code defined in other loaded files.
     Turning on this flag automatically turns off the *note debug: 2e3.
     flag.

‘source_data(Option)’

     Defines how much information is retained when compiling a source
     file.  Possible option values are ‘on’ (the usual default for
     development) and ‘off’.  With this flag set to ‘on’, Logtalk will
     keep the information represented using documenting directives plus
     source location data (including source file names and line
     numbers).  This information can be retrieved using the *note
     reflection API: 48. and is useful for documenting, debugging, and
     integration with third-party development tools.  This flag can be
     turned off in order to generate more compact code.

‘debug(Option)’

     Controls the compilation of source files in debug mode (the Logtalk
     default debugger can only be used with files compiled in this
     mode).  Also controls, by default, printing of ‘debug>’ and
     ‘debug(Topic)’ messages.  Possible option values are ‘on’ and ‘off’
     (the usual default).  Turning on this flag automatically turns off
     the *note optimize: 8c. flag.

‘reload(Option)’

     Defines the reloading behavior for source files.  Possible option
     values are ‘skip’ (skip reloading of already loaded files; this
     value can be used to get similar functionality to the Prolog
     directive ‘ensure_loaded/1’ but should be used only with fully
     debugged code), ‘changed’ (the usual default; reload files only
     when they are changed since last loaded, provided that any explicit
     flags and the compilation mode are the same as before), and
     ‘always’ (always reload files).

‘relative_to(Directory)’

     Defines a base directory for resolving relative source file paths.
     The default value is the directory of the source file being
     compiled.

‘hook(Object)’

     Allows the definition of an object (which can be the pseudo-object
     user(1)) implementing the expanding(2) built-in protocol.  The hook
     object must be compiled and loaded when this option is used.  It’s
     also possible to specify a Prolog module instead of a Logtalk
     object, but the module must be pre-loaded, and its identifier must
     be different from any object identifier.

‘clean(Option)’

     Controls cleaning of the intermediate Prolog files generated when
     compiling Logtalk source files.  Possible option values are ‘off’
     and ‘on’ (the usual default).  When turned on, intermediate files
     are deleted after loading, and all source files are recompiled
     disregarding any existing intermediate files.  When turned off, the
     intermediate files are kept.  This is useful when embedding
     applications, which requires collecting the intermediate code, and
     when working on large applications to avoid repeated recompilation
     of stable code.  The flag must be turned on when changing
     compilation modes, changing flags such as *note code_prefix: 2e2,
     or when turning on linter flags that are off by default without at
     the same time making changes to the application source files
     themselves, as any existing intermediate files would not be
     recompiled as necessary due to file timestamps not changing.

   ---------- Footnotes ----------

   (1) ../../apis/user_0.html#user-0

   (2) ../../apis/expanding_0.html#expanding-0


File: TheLogtalkHandbook-3.101.0.info,  Node: User-defined flags,  Prev: Other flags,  Up: Compiler flags

1.14.11.7 User-defined flags
............................

Logtalk provides a *note create_logtalk_flag/3: 2e7. predicate that can
be used for defining new flags.


File: TheLogtalkHandbook-3.101.0.info,  Node: Reloading source files,  Next: Batch processing,  Prev: Compiler flags,  Up: Writing and running applications

1.14.12 Reloading source files
------------------------------

As a general rule, reloading source files should never occur in
production code and should be handled with care in development code.
Reloading a Logtalk source file usually requires reloading the
intermediate Prolog file that is generated by the Logtalk compiler.  The
problem is that there is no standard behavior for reloading Prolog
files.  For static predicates, almost all Prolog compilers replace the
old definitions with the new ones.  However, for dynamic predicates, the
behavior depends on the Prolog compiler.  Most compilers replace the old
definitions, but some of them simply append the new ones, which usually
leads to trouble.  See the compatibility notes for the backend Prolog
compiler you intend to use for more information.  There is an additional
potential problem when using multi-threading programming.  Reloading a
threaded object does not recreate from scratch its old message queue,
which may still be in use (e.g., threads may be waiting on it).

When using library entities and stable code, you can avoid reloading the
corresponding source files (and, therefore, recompiling them) by setting
the *note reload: 2e4. compiler flag to ‘skip’.  For code under
development, you can turn off the *note clean: 292. flag to avoid
recompiling files that have not been modified since the last compilation
(assuming that backend Prolog compiler that you are using supports
retrieving file modification dates).  You can disable deleting the
intermediate files generated when compiling source files by changing the
default flag value in your settings file, by using the corresponding
compiler flag with the compiling and loading built-in predicates, or,
for the remaining of a working session, by using the call:

     | ?- set_logtalk_flag(clean, off).

Some caveats that you should be aware of.  First, some warnings that
might be produced when compiling a source file will not show up if the
corresponding object file is up-to-date because the source file is not
being (re)compiled.  Second, if you are using several Prolog compilers
with Logtalk, be sure to perform the first compilation of your source
files with the ‘clean’ flag turned off: the intermediate Prolog files
generated by the Logtalk compiler may not be compatible across Prolog
compilers or even for the same Prolog compiler across operating systems
(e.g., due to the use of different character encodings or end-of-line
characters).


File: TheLogtalkHandbook-3.101.0.info,  Node: Batch processing,  Next: Optimizing performance,  Prev: Reloading source files,  Up: Writing and running applications

1.14.13 Batch processing
------------------------

When doing batch processing, you probably want to turn off the *note
report: 2e1. 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.101.0.info,  Node: Optimizing performance,  Next: Portable applications,  Prev: Batch processing,  Up: Writing and running applications

1.14.14 Optimizing performance
------------------------------

The default compiler flag settings are appropriate for the 'development'
but not necessarily for the 'deployment' of applications.  To minimize
the generated code size, turn the *note source_data: cc. flag off.  To
optimize runtime performance, turn on the *note optimize: 8c. flag.
Your chosen backend Prolog compiler may also provide performance-related
flags; check its documentation.

Pay special attention to file compilation/loading order.  Whenever
possible, compile and load your files by taking into account file
dependencies.  By default, the compiler will print a warning whenever a
file references an entity that is not yet loaded.  Solving these
warnings is key for optimal performance by enabling *note static
binding: 35. optimizations.  For a clear picture of file dependencies,
use the *note diagrams: 2ee. tool to generate a file dependency diagram
for your application.

Minimize the use of dynamic predicates.  Parametric objects can often be
used in alternative.  When dynamic predicates cannot be avoided, try to
make them private.  Declaring a dynamic predicate also as a private
predicate allows the compiler to optimize local calls to the database
methods (e.g., *note assertz/1: 1b3. and *note retract/1: 1b5.) that
modify the predicate.

Sending a *note message to self: 17d. implies *note dynamic binding: 36,
but there are often cases where *note (;;)/1: 5c. is misused to call an
imported or inherited predicate that is never going to be redefined in a
descendant.  In these cases, a *note super call: 115, *note (^^)/1: 5d,
can be used instead with the benefit of often enabling static binding.
Most of the guidelines for writing efficient Prolog code also apply to
Logtalk code.  In particular, define your predicates to take advantage
of first-argument indexing.  In the case of recursive predicates, define
them as tail-recursive predicates whenever possible.

See the *note section on performance: 38. for a detailed discussion on
Logtalk performance.


File: TheLogtalkHandbook-3.101.0.info,  Node: Portable applications,  Next: Conditional compilation,  Prev: Optimizing performance,  Up: Writing and running applications

1.14.15 Portable applications
-----------------------------

Logtalk is compatible with most modern standards-compliant Prolog
compilers.  However, this does not necessarily imply that your Logtalk
applications will have the same level of portability.  If possible, you
should only use in your applications Logtalk built-in predicates and ISO
Prolog-specified built-in predicates and arithmetic functions.  If you
need to use built-in predicates (or built-in arithmetic functions) that
may not be available in other Prolog compilers, you should try to
encapsulate the non-portable code in a small number of objects and
provide a portable 'interface' for that code through the use of Logtalk
protocols.  An example will be code that access operating-system
specific features.  The Logtalk compiler can warn you of the use of
non-ISO-specified built-in predicates and arithmetic functions by using
the *note portability: 1d1. compiler flag.


File: TheLogtalkHandbook-3.101.0.info,  Node: Conditional compilation,  Next: Avoiding common errors,  Prev: Portable applications,  Up: Writing and running applications

1.14.16 Conditional compilation
-------------------------------

Logtalk supports conditional compilation within source files using the
*note if/1: 2f3, *note elif/1: 2f4, *note else/0: 2f5, and *note
endif/0: 2f6. 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.101.0.info,  Node: Avoiding common errors,  Next: Coding style guidelines,  Prev: Conditional compilation,  Up: Writing and running applications

1.14.17 Avoiding common errors
------------------------------

Try to write objects and protocol documentation 'before' writing any
other code; if you are having trouble documenting a predicate, perhaps
you need to go back to the design stage.

Try to avoid lengthy hierarchies.  Composition is often a better choice
over inheritance for defining new objects (Logtalk supports
component-based programming through the use of *note categories: 109.).
In addition, prototype-based hierarchies are semantically simpler than
class-based hierarchies.

Dynamic predicates or dynamic entities are sometimes needed, but we
should always try to minimize the use of non-logical features such as
asserts and retracts.

Since each Logtalk entity is independently compiled, if an object
inherits a dynamic or a meta-predicate predicate, then the respective
directives must be repeated to ensure a correct compilation.

In general, Logtalk does not verify if a user predicate call/return
arguments comply with the declared modes.  On the other hand, Logtalk
built-in predicates, built-in methods, and message-sending control
structures are fully checked for calling mode errors.

Logtalk error handling strongly depends on the ISO compliance of the
chosen Prolog compiler.  For instance, the error terms that are
generated by some Logtalk built-in predicates assume that the Prolog
built-in predicates behave as defined in the ISO standard regarding
error conditions.  In particular, if your Prolog compiler does not
support a ‘read_term/3’ built-in predicate compliant with the ISO Prolog
Standard definition, then the current version of the Logtalk compiler
may not be able to detect misspelled variables in your source code.


File: TheLogtalkHandbook-3.101.0.info,  Node: Coding style guidelines,  Prev: Avoiding common errors,  Up: Writing and running applications

1.14.18 Coding style guidelines
-------------------------------

It is suggested that all code between an entity opening and closing
directives be indented by one tab stop.  When defining entity code, both
directives and predicates, Prolog coding style guidelines may be
applied.  All Logtalk source files, examples, and standard library
entities use tabs (the recommended setting is a tab width equivalent to
4 spaces) for laying out code.  Closely related entities can be defined
in the same source file.  However, for the best performance, is often
necessary to have an entity per source file.  Entities that might be
useful in different contexts (such as library entities) are best defined
in their own source files.

A detailed coding style guide is available at the Logtalk official
website.


File: TheLogtalkHandbook-3.101.0.info,  Node: Printing messages and asking questions,  Next: Term and goal expansion,  Prev: Writing and running applications,  Up: User Manual

1.15 Printing messages and asking questions
===========================================

Applications, components, and libraries often print all sorts of
messages.  These include banners, logging, debugging, and computation
results messages.  But also, in some cases, user interaction messages.
However, the authors of applications, components, and libraries often
cannot anticipate the context where their software will be used and thus
decide which and when messages should be displayed, suppressed, or
diverted.  Consider the different components in a Logtalk application
development and deployment.  At the base level, you have the Logtalk
compiler and runtime.  The compiler writes messages related to e.g.
compiling and loading files, compiling entities, and compilation
warnings and errors.  The runtime may write banner messages or throw
execution errors that may result in printing human-level messages.  The
development environment can be console-based, or you may be using a GUI
tool such as PDT. In the latter case, PDT needs to intercept the Logtalk
compiler and runtime messages to present the relevant information using
its GUI. Then you have all the other components in a typical
application.  For example, your own libraries and third-party libraries.
The libraries may want to print messages on their own, e.g.  banners,
debugging information, or logging information.  As you assemble all your
application components, you want to have the final word on which
messages are printed, where, and when.  Uncontrolled message printing by
libraries could potentially disrupt application flow, expose
implementation details, spam the user with irrelevant details, or break
user interfaces.

The solution is to decouple the calls to print a message from the actual
printing of the output text.  The same is true for calls to read user
input.  By decoupling the call to input some data from the actual read
of the data, we can easily switch from, for example, a command-line
interface to a GUI input dialog or even automate providing the data
(e.g., when automating testing of the user interaction).

Logtalk provides a solution based on the 'structured message printing
mechanism' that was introduced by Quintus Prolog, where it was
apparently implemented by Dave Bowen (thanks to Richard O’Keefe for the
historical bits).  This mechanism gives the programmer full control of
message printing, allowing it to filter, rewrite, or redirect any
message.  Variations of this mechanism can also be found in some Prolog
systems, including SICStus Prolog, SWI-Prolog, and YAP. Based on this
mechanism, Logtalk introduces an extension that also allows abstracting
asking a user for input.  Both mechanisms are implemented by the
logtalk(1) built-in object and described in this section.  The message
printing mechanism is extensively used by the Logtalk compiler itself
and by the developer tools.  The question-asking mechanism is used e.g.
in the *note debugger: 2fd. tool.

* Menu:

* Printing messages::
* Message tokenization::
* Meta-messages::
* Defining message prefixes and output streams::
* Defining message prefixes and output files::
* Intercepting messages::
* Asking questions::
* Intercepting questions::
* Multi-threading applications: Multi-threading applications<4>.

   ---------- Footnotes ----------

   (1) ../../apis/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.101.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: 2ff.  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: 2e1.
     flag to ‘warnings’ or ‘off’)

‘help’

     messages printed in reply to the user asking for help (mostly for
     helping port existing Prolog code)

‘information’ and ‘information(Group)’

     messages usually printed in reply to a user’s request for
     information

‘silent’ and ‘silent(Group)’

     not printed by default (but can be intercepted using the
     ‘message_hook/4’ predicate)

‘comment’ and ‘comment(Group)’

     useful but usually not essential messages (can be suppressed by
     setting the *note report: 2e1. 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: 2e1. 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:
     2e3. flag is turned on; the ‘print_message/3’ goals for these
     messages are suppressed by the compiler when the *note optimize:
     8c. flag is turned on)

‘question, question(Group)’

     questions to a user

Using a compound term allows easy partitioning of messages of the same
kind in different groups.  Note that you can define your own alternative
message kind identifiers for your own components, together with suitable
definitions for their associated prefixes and output streams.

The second argument of ‘print_message/3’ represents the 'component'
defining the message being printed.  In this context, 'component' is a
generic term that can designate, e.g., a tool, a library, or some
sub-system in a large application.  In our example, the component name
is ‘core’, identifying the Logtalk compiler/runtime.  This argument was
introduced to provide multiple namespaces for message terms and thus
simplify programming-in-the-large by allowing easy filtering of all
messages from a specific component and also avoiding conflicts when two
components happen to define the same message term (e.g., ‘banner’).
Users should choose and use a unique name for a component, which usually
is the name of the component itself.  For example, all messages from the
*note lgtunit: 146. tool use ‘lgtunit’ for the component argument.  The
compiler and runtime are interpreted as a single component designated as
‘core’.

The third argument of ‘print_message/3’ is the message itself,
represented by a term.  In the above example, the message term is
‘banner’.  Using a term to represent a message instead of a string with
the message text itself has significant advantages.  Notably, it allows
using a compound term for easy parameterization of the message text and
simplifies machine processing, localization of applications, and message
interception.  For example:

     | ?- logtalk::print_message(comment, core, redefining_entity(object, foo)).

     % Redefining object foo
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: Message tokenization,  Next: Meta-messages,  Prev: Printing messages,  Up: Printing messages and asking questions

1.15.2 Message tokenization
---------------------------

The use of message terms requires a solution for generating the actual
text of the messages.  This is supported by defining grammar rules for
the *note logtalk;;message_tokens//2: 301. multifile non-terminal, which
translates a message term, for a given component, to a list of tokens.
For example:

     :- multifile(logtalk::message_tokens//2).
     :- dynamic(logtalk::message_tokens//2).

     logtalk::message_tokens(redefining_entity(Type, Entity), core) -->
         ['Redefining ~w ~q'-[Type, Entity], nl].

The following tokens can be used when translating a message:

‘at_same_line’

     Signals a following part to a multi-part message with no line break
     in between; this token is ignored when it’s not the first in the
     list of tokens

‘tab(Expression)’

     Evaluate the argument as an arithmetic expression and write the
     resulting number of spaces; this token is ignored when the number
     of spaces is not positive

‘nl’

     Change line in the output stream

‘flush’

     Flush the output stream (by calling the ‘flush_output/1’ standard
     predicate)

‘Format-Arguments’

     ‘Format’ must be an atom and ‘Arguments’ must be a list of format
     arguments (the token arguments are passed to a call to the
     ‘format/3’ de facto standard predicate)

‘term(Term, Options)’

     ‘Term’ can be any term and ‘Options’ must be a list of valid
     ‘write_term/3’ output options (the token arguments are passed to a
     call to the ‘write_term/3’ standard predicate)

‘ansi(Attributes, Format, Arguments)’

     Taken from SWI-Prolog; by default, do nothing; can be used for
     styled output

‘begin(Kind, Var)’

     Taken from SWI-Prolog; by default, do nothing; can be used together
     with ‘end(Var)’ to wrap a sequence of message tokens

‘end(Var)’

     Taken from SWI-Prolog; by default, do nothing

The ‘logtalk’ object also defines public predicates for printing a list
of tokens, for hooking into printing an individual token, and for
setting default output streams and message prefixes.  For example, the
SWI-Prolog adapter file uses the print message token hook predicate to
enable coloring of messages printed on a console.


File: TheLogtalkHandbook-3.101.0.info,  Node: Meta-messages,  Next: Defining message prefixes and output streams,  Prev: Message tokenization,  Up: Printing messages and asking questions

1.15.3 Meta-messages
--------------------

Defining tokenization rules for every message is not always necessary,
however.  Logtalk defines several 'meta-messages' that are handy for
simple cases and temporary messages only used during application
development, notably debugging messages.  See the *note Debugging
messages: 303. section and the logtalk built-in object(1) remarks
section for details.

   ---------- Footnotes ----------

   (1) ../../apis/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.101.0.info,  Node: Defining message prefixes and output streams,  Next: Defining message prefixes and output files,  Prev: Meta-messages,  Up: Printing messages and asking questions

1.15.4 Defining message prefixes and output streams
---------------------------------------------------

The *note logtalk;;message_prefix_stream/4: 305. hook predicate can be
used to define a message line prefix and an output stream for printing
messages of a given kind and component.  For example:

     :- multifile(logtalk::message_prefix_stream/4).
     :- dynamic(logtalk::message_prefix_stream/4).

     logtalk::message_prefix_stream(comment, my_app, '% ', user_output).
     logtalk::message_prefix_stream(warning, my_app, '* ', user_error).

A single clause at most is expected per message kind and component pair.
When this predicate is not defined for a given kind and component pair,
the following defaults are used:

     kind_prefix_stream(banner,         '',       user_output).
     kind_prefix_stream(help,           '',       user_output).
     kind_prefix_stream(question,       '',       user_output).
     kind_prefix_stream(question(_),    '',       user_output).
     kind_prefix_stream(information,    '% ',     user_output).
     kind_prefix_stream(information(_), '% ',     user_output).
     kind_prefix_stream(comment,        '% ',     user_output).
     kind_prefix_stream(comment(_),     '% ',     user_output).
     kind_prefix_stream(warning,        '*     ', user_error).
     kind_prefix_stream(warning(_),     '*     ', user_error).
     kind_prefix_stream(error,          '!     ', user_error).
     kind_prefix_stream(error(_),       '!     ', user_error).
     kind_prefix_stream(debug,          '>>> ',   user_error).
     kind_prefix_stream(debug(_),       '>>> ',   user_error).

When the message kind is unknown, ‘information’ is used instead.


File: TheLogtalkHandbook-3.101.0.info,  Node: Defining message prefixes and output files,  Next: Intercepting messages,  Prev: Defining message prefixes and output streams,  Up: Printing messages and asking questions

1.15.5 Defining message prefixes and output files
-------------------------------------------------

Some applications require copying and saving messages without diverting
them from their default stream.  For simple cases, this can be
accomplished by intercepting the messages using the *note
logtalk;;message_hook/4: 307. multifile hook predicate (see next
section).  In more complex cases, where messages are already intercepted
for a different purpose, it can be tricky to use multiple definitions of
the ‘message_hook/4’ predicate as the order of the clauses of a multiple
predicate cannot be assumed in general (for all ‘message_hook/4’
predicate definitions to run, all but the last one to be called must
fail).  Using a single 'master' definition is also not ideal as it would
result in strong coupling instead of a clean separation of concerns.

The experimental *note logtalk;;message_prefix_file/6: 308. hook
predicate can be used to define a message line prefix and an output file
for copying messages of a given kind and component pair.  For example:

     :- multifile(logtalk::message_prefix_file/6).
     :- dynamic(logtalk::message_prefix_file/6).

     logtalk::message_prefix_file(error,   app, '! ', 'log.txt', append, []).
     logtalk::message_prefix_file(warning, app, '! ', 'log.txt', append, []).

A single clause at most is expected per message kind and component pair.

This predicate is called by default by the message printing mechanism.
Definitions of the ‘message_hook/4’ hook predicate are free to decide if
the ‘logtalk::message_prefix_file/6’ predicate should be called and
acted upon.


File: TheLogtalkHandbook-3.101.0.info,  Node: Intercepting messages,  Next: Asking questions,  Prev: Defining message prefixes and output files,  Up: Printing messages and asking questions

1.15.6 Intercepting messages
----------------------------

Calls to the *note logtalk;;print_message/3: 2ff. predicate can be
intercepted by defining clauses for the *note logtalk;;message_hook/4:
307. multifile hook predicate.  This predicate can suppress, rewrite,
and divert messages.

As a first example, assume that you want to make Logtalk startup less
verbose by suppressing printing of the default compiler flag values.
This can be easily accomplished by defining the following category in a
settings file:

     :- category(my_terse_logtalk_startup_settings).

         :- multifile(logtalk::message_hook/4).
         :- dynamic(logtalk::message_hook/4).

         logtalk::message_hook(default_flags, comment(settings), core, _).

     :- end_category.

The printing message mechanism automatically calls the ‘message_hook/4’
hook predicate.  When this call succeeds, the mechanism assumes that the
message has been successfully handled.

As another example, assume that you want to print all otherwise silent
compiler messages:

     :- category(my_verbose_logtalk_message_settings).

         :- multifile(logtalk::message_hook/4).
         :- dynamic(logtalk::message_hook/4).

         logtalk::message_hook(_Message, silent, core, Tokens) :-
             logtalk::message_prefix_stream(comment, core, Prefix, Stream),
             logtalk::print_message_tokens(Stream, Prefix, Tokens).

         logtalk::message_hook(_Message, silent(Key), core, Tokens) :-
             logtalk::message_prefix_stream(comment(Key), core, Prefix, Stream),
             logtalk::print_message_tokens(Stream, Prefix, Tokens).

     :- end_category.


File: TheLogtalkHandbook-3.101.0.info,  Node: Asking questions,  Next: Intercepting questions,  Prev: Intercepting messages,  Up: Printing messages and asking questions

1.15.7 Asking questions
-----------------------

Logtalk 'structured question-asking' mechanism complements the message
printing mechanism.  It provides an abstraction for the common task of
asking a user a question and reading back its reply.  By default, this
mechanism writes the question, writes a prompt, and reads the answer
using the current user input and output streams but allows all steps to
be intercepted, filtered, rewritten, and redirected.  Two typical
examples are using a GUI dialog for asking questions and automatically
providing answers to specific questions.

The question-asking mechanism works in tandem with the message printing
mechanism, using it to print the question text and a prompt.  It
provides an asking predicate and a hook predicate, both declared and
defined in the ‘logtalk’ built-in object.  The asking predicate, *note
logtalk;;ask_question/5: 30c, is used for asking a question and reading
the answer.  Assume that we defined the following message tokenization
and question prompt and stream:

     :- category(hitchhikers_guide_to_the_galaxy).

         :- multifile(logtalk::message_tokens//2).
         :- dynamic(logtalk::message_tokens//2).

         % abstract the question text using the atom ultimate_question;
         % the second argument, hitchhikers, is the application component
         logtalk::message_tokens(ultimate_question, hitchhikers) -->
             ['The answer to the ultimate question of life, the universe and everything is?'-[], nl].

        :- multifile(logtalk::question_prompt_stream/4).
        :- dynamic(logtalk::question_prompt_stream/4).

        % the prompt is specified here instead of being part of the question text
        % as it will be repeated if the answer doesn't satisfy the question closure
        logtalk::question_prompt_stream(question, hitchhikers, '> ', user_input).

     :- end_category.

After compiling and loading this category, we can now ask the ultimate
question:

     | ?- logtalk::ask_question(question, hitchhikers, ultimate_question, '=='(42), N).

     The answer to the ultimate question of life, the universe and everything is?
     > 42.

     N = 42
     yes

Note that the fourth argument, ‘'=='(42)’ in our example, is a *note
closure: 14f. that is used to check the answers provided by the user.
The question is repeated until the goal constructed by extending the
closure with the user answer succeeds.  For example:

     | ?- logtalk::ask_question(question, hitchhikers, ultimate_question, '=='(42), N).
     The answer to the ultimate question of life, the universe and everything is?
     > icecream.
     > tea.
     > 42.

     N = 42
     yes

Practical usage examples of this mechanism can be found, e.g., in the
‘debugger’ tool where it’s used to abstract the user interaction when
tracing a goal execution in debug mode.


File: TheLogtalkHandbook-3.101.0.info,  Node: Intercepting questions,  Next: Multi-threading applications<4>,  Prev: Asking questions,  Up: Printing messages and asking questions

1.15.8 Intercepting questions
-----------------------------

Calls to the *note logtalk;;ask_question/5: 30c. predicate can be
intercepted by defining clauses for the *note logtalk;;question_hook/6:
30e. multifile hook predicate.  This predicate can suppress, rewrite,
and divert questions.  For example, assume that we want to automate
testing and thus cannot rely on someone manually providing answers:

     :- category(hitchhikers_fixed_answers).

         :- multifile(logtalk::question_hook/6).
         :- dynamic(logtalk::question_hook/6).

         logtalk::question_hook(ultimate_question, question, hitchhikers, _, _, 42).

     :- end_category.

After compiling and loading this category, trying the question again
will now skip asking the user:

     | ?- logtalk::ask_question(question, hitchhikers, ultimate_question, '=='(42), N).

     N = 42
     yes

In a practical case, the fixed answer would be used for follow-up goals
being tested.  The question-answer read loop (which calls the question
check closure) is not used when a fixed answer is provided using the
‘logtalk::question_hook/6’ predicate thus preventing the creation of
endless loops.  For example, the following query succeeds:

     | ?- logtalk::ask_question(question, hitchhikers, ultimate_question, '=='(41), N).

     N = 42
     yes

Note that the ‘logtalk::question_hook/6’ predicate takes as argument the
closure specified in the ‘logtalk::ask_question/5’ call, allowing a
fixed answer to be checked before being returned.


File: TheLogtalkHandbook-3.101.0.info,  Node: Multi-threading applications<4>,  Prev: Intercepting questions,  Up: Printing messages and asking questions

1.15.9 Multi-threading applications
-----------------------------------

When writing multi-threading applications, user-defined predicates
calling methods such as ‘print_message/3’ or ‘ask_question/5’ may need
to be declared synchronized in order to avoid race conditions.


File: TheLogtalkHandbook-3.101.0.info,  Node: Term and goal expansion,  Next: Documenting,  Prev: Printing messages and asking questions,  Up: User Manual

1.16 Term and goal expansion
============================

Logtalk supports a 'term and goal expansion mechanism' that can be used
to define source-to-source transformations.  Two common uses are the
definition of language extensions and domain-specific languages.

Logtalk improves upon the term-expansion mechanism found on some Prolog
systems by providing the user with fine-grained control on 'if', 'when',
and 'how' expansions are applied.  It allows declaring in a source file
itself which expansions, if any, will be used when compiling it.  It
allows declaring which expansions will be used when compiling a file
using compile and loading predicate options.  It also allows defining a
default expansion for all source files.  It defines a concept of 'hook
objects' that can be used as building blocks to create custom and
reusable 'expansion workflows' with explicit and well-defined semantics.
It prevents the simple act of loading expansion rules affecting
subsequent compilation of files.  It prevents conflicts between groups
of expansion rules of different origins.  It avoids a set of buggy
expansion rules from breaking other sets of expansion rules.

* Menu:

* Defining expansions::
* Expanding grammar rules::
* Bypassing expansions::
* Hook objects::
* Virtual source file terms and loading context::
* Default compiler expansion workflow::
* User defined expansion workflows::
* Using Prolog defined expansions::
* Debugging expansions::


File: TheLogtalkHandbook-3.101.0.info,  Node: Defining expansions,  Next: Expanding grammar rules,  Up: Term and goal expansion

1.16.1 Defining expansions
--------------------------

Term and goal expansions are defined using, respectively, the predicates
*note term_expansion/2: fc. and *note goal_expansion/2: fd, which are
declared in the expanding(1) built-in protocol.  Note that, unlike
Prolog systems also providing these two predicates, they are 'not'
declared as *note multifile predicates: 16b. in the protocol.  This
design decision is key for giving the programmer full control of the
expansion process and preventing the problems inflicting most of the
Prolog systems that provide a term-expansion mechanism.

An example of an object defining expansion rules:

     :- object(an_object,
         implements(expanding)).

         term_expansion(ping, pong).
         term_expansion(
             colors,
             [white, yellow, blue, green, read, black]
         ).

         goal_expansion(a, b).
         goal_expansion(b, c).
         goal_expansion(X is Expression, true) :-
             catch(X is Expression, _, fail).

     :- end_object.

These predicates can be explicitly called using the *note expand_term/2:
1b7. and *note expand_goal/2: 313. built-in methods or called
automatically by the compiler when compiling a source file (see the
section below on 'hook objects').

In the case of source files referenced in *note include/1: b8.
directives, expansions are only applied automatically when the
directives are found in source files, not when used as arguments in the
*note create_object/4: 62, *note create_protocol/3: e3, and *note
create_category/4: 11a, predicates.  This restriction prevents
inconsistent results when, for example, an expansion is defined for a
predicate with clauses found in both an included file and as argument in
a call to the ‘create_object/4’ predicate.

Clauses for the ‘term_expansion/2’ predicate are called until one of
them succeeds.  The returned expansion can be a single term or a list of
terms (including the empty list).  For example:

     | ?- an_object::expand_term(ping, Term).

     Term = pong
     yes

     | ?- an_object::expand_term(colors, Colors).

     Colors = [white, yellow, blue, green, read, black]
     yes

When no ‘term_expansion/2’ clause applies, the same term that we are
trying to expand is returned:

     | ?- an_object::expand_term(sounds, Sounds).

     Sounds = sounds
     yes

Clauses for the ‘goal_expansion/2’ predicate are recursively called on
the expanded goal until a fixed point is reached.  For example:

     | ?- an_object::expand_goal(a, Goal).

     Goal = c
     yes

     | ?- an_object::expand_goal(X is 3+2*5, Goal).

     X = 13,
     Goal = true
     yes

When no ‘goal_expansion/2’ clause applies, the same goal that we are
trying to expand is returned:

     | ?- an_object::expand_goal(3 =:= 5, Goal).

     Goal = (3=:=5)
     yes

The goal-expansion mechanism prevents an infinite loop when expanding a
goal by checking that a goal to be expanded was not the result from a
previous expansion of the same goal.  For example, consider the
following object:

     :- object(fixed_point,
         implements(expanding)).

         goal_expansion(a, b).
         goal_expansion(b, c).
         goal_expansion(c, (a -> b; c)).

     :- end_object.

The expansion of the goal ‘a’ results in the goal ‘(a -> b; c)’ with no
attempt to further expand the ‘a’, ‘b’, and ‘c’ goals as they have
already been expanded.

Goal-expansion applies to goal arguments of control constructs,
meta-arguments in built-in or ‘user’ defined meta-predicates,
meta-arguments in local user-defined meta-predicates, meta-arguments in
meta-predicate messages when static binding is possible, and
‘initialization/1’, ‘if/1’, and ‘elif/1’ directives.

   ---------- Footnotes ----------

   (1) ../../apis/expanding_0.html#expanding-0


File: TheLogtalkHandbook-3.101.0.info,  Node: Expanding grammar rules,  Next: Bypassing expansions,  Prev: Defining expansions,  Up: Term and goal expansion

1.16.2 Expanding grammar rules
------------------------------

A common term expansion is the translation of grammar rules into
predicate clauses.  This transformation is performed automatically by
the compiler when a source file entity defines grammar rules.  It can
also be done explicitly by calling the ‘expand_term/2’ built-in method.
For example:

     | ?- logtalk::expand_term((a --> b, c), Clause).

     Clause = (a(A,B) :- b(A,C), c(C,B))
     yes

Note that the default translation of grammar rules can be overridden by
defining clauses for the *note term_expansion/2: fc. predicate.


File: TheLogtalkHandbook-3.101.0.info,  Node: Bypassing expansions,  Next: Hook objects,  Prev: Expanding grammar rules,  Up: Term and goal expansion

1.16.3 Bypassing expansions
---------------------------

Terms and goals wrapped by the *note {}/1: 191. control construct are
not expanded.  For example:

     | ?- an_object::expand_term({ping}, Term).

     Term = {ping}
     yes

     | ?- an_object::expand_goal({a}, Goal).

     Goal = {a}
     yes

This also applies to source file terms and source file goals when using
hook objects (discussed next).


File: TheLogtalkHandbook-3.101.0.info,  Node: Hook objects,  Next: Virtual source file terms and loading context,  Prev: Bypassing expansions,  Up: Term and goal expansion

1.16.4 Hook objects
-------------------

Term and goal expansion of a source file during its compilation is
performed by using 'hook objects'.  A hook object is simply an object
implementing the expanding(1) built-in protocol and defining clauses for
the term and goal expansion hook predicates.  Hook objects must be
compiled and loaded prior to being used to expand a source file.

To compile a source file using a hook object, we can use the *note hook:
fe. compiler flag in the second argument of the *note logtalk_compile/2:
2b2. and *note logtalk_load/2: 4e. built-in predicates.  For example:

     | ?- logtalk_load(source_file, [hook(hook_object)]).
     ...

In alternative, we can use a *note set_logtalk_flag/2: 50. directive in
the source file itself.  For example:

     :- set_logtalk_flag(hook, hook_object).

To use multiple hook objects in the same source file, simply write each
directive before the block of code that it should handle.  For example:

     :- object(h1,
         implements(expanding)).

         term_expansion((:- public(a/0)), (:- public(b/0))).
         term_expansion(a, b).

     :- end_object.

     :- object(h2,
         implements(expanding)).

         term_expansion((:- public(a/0)), (:- public(c/0))).
         term_expansion(a, c).

     :- end_object.

     :- set_logtalk_flag(hook, h1).

     :- object(s1).

         :- public(a/0).
         a.

     :- end_object.


     :- set_logtalk_flag(hook, h2).

     :- object(s2).

         :- public(a/0).
         a.

     :- end_object.

     | ?- {h1, h2, s}.
     ...

     | ?- s1::b.
     yes

     | ?- s2::c.
     yes

It is also possible to define a default hook object by defining a global
value for the ‘hook’ flag by calling the *note set_logtalk_flag/2: 51.
predicate.  For example:

     | ?- set_logtalk_flag(hook, hook_object).

     yes

Note that, due to the ‘set_logtalk_flag/2’ directive being local to a
source file, using it to specify a hook object will override any defined
default hook object or any hook object specified as a
‘logtalk_compile/2’ or ‘logtalk_load/2’ predicate compiler option for
compiling or loading the source file.

     Note: Clauses for the ‘term_expansion/2’ and ‘goal_expansion/2’
     predicates defined within an object or a category are never used in
     the compilation of the object or the category itself.

   ---------- Footnotes ----------

   (1) ../../apis/expanding_0.html#expanding-0


File: TheLogtalkHandbook-3.101.0.info,  Node: Virtual source file terms and loading context,  Next: Default compiler expansion workflow,  Prev: Hook objects,  Up: Term and goal expansion

1.16.5 Virtual source file terms and loading context
----------------------------------------------------

When using a hook object to expand the terms of a source file, two
virtual file terms are generated: ‘begin_of_file’ and ‘end_of_file’.
These terms allow the user to define term-expansions before and after
the actual source file terms.

Logtalk also provides a *note logtalk_load_context/2: 318. built-in
predicate that can be used to access the compilation/loading context
when performing expansions.  The *note logtalk: d1. built-in object also
provides a set of predicates that can be useful, notably when adding
Logtalk support for language extensions originally developed for Prolog.

As an example of using the virtual terms and the
‘logtalk_load_context/2’ predicate, assume that you want to convert
plain Prolog files to Logtalk by wrapping the Prolog code in each file
using an object (named after the file) that implements a given protocol.
This could be accomplished by defining the following hook object:

     :- object(wrapper(_Protocol_),
         implements(expanding)).

         term_expansion(begin_of_file, (:- object(Name,implements(_Protocol_)))) :-
             logtalk_load_context(file, File),
             os::decompose_file_name(File,_ , Name, _).

         term_expansion(end_of_file, (:- end_object)).

     :- end_object.

Assuming, e.g., ‘my_car.pl’ and ‘lease_car.pl’ files to be wrapped and a
‘car_protocol’ protocol, we could then load them using:

     | ?- logtalk_load(
              ['my_car.pl', 'lease_car.pl'],
              [hook(wrapper(car_protocol))]
          ).

     yes

     Note: When a source file also contains plain Prolog directives and
     predicates, these are term-expanded but not goal-expanded (with the
     exception of the ‘initialization/1’, ‘if/1’, and ‘elif/1’
     directives, where the goal argument is expanded to improve code
     portability across backends).


File: TheLogtalkHandbook-3.101.0.info,  Node: Default compiler expansion workflow,  Next: User defined expansion workflows,  Prev: Virtual source file terms and loading context,  Up: Term and goal expansion

1.16.6 Default compiler expansion workflow
------------------------------------------

When *note compiling a source file: 29b, the compiler will first try, by
default, the source file-specific hook object specified using a local
‘set_logtalk_flag/2’ directive, if defined.  If that expansion fails, it
tries the hook object specified using the ‘hook/1’ compiler option in
the ‘logtalk_compile/2’ or ‘logtalk_load/2’ goal that compiles or loads
the file, if defined.  If that expansion fails, it tries the default
hook object, if defined.  If that expansion also fails, the compiler
tries the Prolog dialect-specific expansion rules found in the *note
adapter file: 154. (which are used to support non-standard Prolog
features).


File: TheLogtalkHandbook-3.101.0.info,  Node: User defined expansion workflows,  Next: Using Prolog defined expansions,  Prev: Default compiler expansion workflow,  Up: Term and goal expansion

1.16.7 User defined expansion workflows
---------------------------------------

Sometimes we have multiple hook objects that we need to combine and use
in the compilation of a source file.  Logtalk includes a *note
hook_flows: 31b. library that supports two basic expansion workflows: a
pipeline(1) of hook objects, where the expansion results from a hook
object are fed to the next hook object in the pipeline, and a set(2) of
hook objects, where expansions are tried until one of them succeeds.
These workflows are implemented as parametric objects, allowing
combining them to implement more sophisticated expansion workflows.
There is also a *note hook_objects: 31c. library that provides
convenient hook objects for defining custom expansion workflows.  This
library includes a hook object that can be used to restore the default
expansion workflow used by the compiler.

For example, assuming that you want to apply the Prolog backend-specific
expansion rules defined in its adapter file, using the
backend_adapter_hook(3) library object, passing the resulting terms to
your own expansion when compiling a source file, we could use the goal:

     | ?- logtalk_load(
              source,
              [hook(hook_pipeline([backend_adapter_hook, my_expansion]))]
          ).

As a second example, we can prevent expansion of a source file using the
library object identity_hook(4) by adding as the first term in a source
file the directive:

     :- set_logtalk_flag(hook, identity_hook).

The file will be compiled as-is as any hook object (specified as a
compiler option or as a default hook object) and any backend adapter
expansion rules are overridden by the directive.

   ---------- Footnotes ----------

   (1) ../../apis/hook_pipeline_1.html#hook-pipeline-1

   (2) ../../apis/hook_set_1.html#hook-set-1

   (3) ../../apis/backend_adapter_hook_0.html#backend-adapter-hook-0

   (4) ../../apis/identity_hook_0.html#identity-hook-0


File: TheLogtalkHandbook-3.101.0.info,  Node: Using Prolog defined expansions,  Next: Debugging expansions,  Prev: User defined expansion workflows,  Up: Term and goal expansion

1.16.8 Using Prolog defined expansions
--------------------------------------

In order to use clauses for the ‘term_expansion/2’ and
‘goal_expansion/2’ predicates defined in plain Prolog, simply specify
the pseudo-object ‘user’ as the hook object when compiling source files.
When using *note backend Prolog compilers: 34. that support a module
system, it can also be specified a module containing clauses for the
expanding predicates as long as the module name doesn’t coincide with an
object name.  When defining a custom workflow, the library object
prolog_module_hook/1(1) can be used as a workflow step.  For example,
assuming a module ‘functions’ defining expansion rules that we want to
use:

     | ?- logtalk_load(
              source,
              [hook(hook_set([prolog_module_hook(functions), my_expansion]))]
          ).

But note that Prolog module libraries may provide definitions of the
expansion predicates that are not compatible with the Logtalk compiler.
In particular, when setting the hook object to ‘user’, be aware of any
Prolog library that is loaded, possibly by default or implicitly by the
Prolog system, that may be contributing definitions of the expansion
predicates.  It is usually safer to define a specific hook object for
combining multiple expansions in a fully controlled way.

     Note: The ‘user’ object declares ‘term_expansion/2’ and
     ‘goal_expansion/2’ as multifile and dynamic predicates.  This helps
     in avoiding predicate existence errors when compiling source files
     with the ‘hook’ flag set to ‘user’ as these predicates are only
     natively declared by some of the supported backend Prolog
     compilers.

   ---------- Footnotes ----------

   (1) ../../apis/prolog_module_hook_1.html#prolog-module-hook-1


File: TheLogtalkHandbook-3.101.0.info,  Node: Debugging expansions,  Prev: Using Prolog defined expansions,  Up: Term and goal expansion

1.16.9 Debugging expansions
---------------------------

The ‘term_expansion/2’ and ‘goal_expansion/2’ predicates can be *note
debugged: 47. like any other object predicates.  Note that expansions
can often be manually tested by sending *note expand_term/2: 1b7. and
*note expand_goal/2: 313. messages to a hook object with the term or
goal whose expansion you want to check as argument.  An alternative to
the debugging tools is to use a *note monitor: 31f. for the runtime
messages that call the predicates.  For example, assume a
‘expansions_debug.lgt’ file with the contents:

     :- initialization(
         define_events(after, edcg, _, _, expansions_debug)
     ).


     :- object(expansions_debug,
         implements(monitoring)).

         after(edcg, term_expansion(T,E), _) :-
             writeq(term_expansion(T,E)), nl.

     :- end_object.

We can use this monitor to help debug the expansion rules of the *note
edcg: 320. library when applied to the ‘edcgs’ example using the
queries:

     | ?- {expansions_debug}.
     ...

     | ?- set_logtalk_flag(events, allow).
     yes

     | ?- {edcgs(loader)}.
     ...
     term_expansion(begin_of_file,begin_of_file)
     term_expansion((:-object(gemini)),[(:-object(gemini)),(:-op(1200,xfx,-->>))])
     term_expansion(acc_info(castor,A,B,C,true),[])
     term_expansion(pass_info(pollux),[])
     term_expansion(pred_info(p,1,[castor,pollux]),[])
     term_expansion(pred_info(q,1,[castor,pollux]),[])
     term_expansion(pred_info(r,1,[castor,pollux]),[])
     term_expansion((p(A)-->>B is A+1,q(B),r(B)),(p(A,C,D,E):-B is A+1,q(B,C,F,E),r(B,F,D,E)))
     term_expansion((q(A)-->>[]),(q(A,B,B,C):-true))
     term_expansion((r(A)-->>[]),(r(A,B,B,C):-true))
     term_expansion(end_of_file,end_of_file)
     ...

This solution does not require compiling the ‘edcg’ hook object in debug
mode or access to its source code (e.g., to modify its expansion rules
to emit debug messages).  We could also simply use the ‘user’
pseudo-object as the monitor object:

     | ?- assertz((
              after(_, term_expansion(T,E), _) :-
                 writeq(term_expansion(T,E)), nl
          )).
     yes

     | ?- define_events(after, edcg, _, Sender, user).
     yes

Another alternative is to use a pipeline of hook objects with the
library ‘hook_pipeline/1’ and ‘write_to_stream_hook’ objects to write
the expansion results to a file.  For example, using the ‘unique.lgt’
test file from the ‘edcgs’ library directory:

     | ?- {hook_flows(loader), hook_objects(loader)}.
     ...

     | ?- open('unique_expanded.lgt', write, Stream),
          logtalk_compile(
              unique,
              [hook(hook_pipeline([edcg,write_to_stream_hook(Stream,[quoted(true)])]))]
          ),
          close(Stream).
     ...

The generated ‘unique_expanded.lgt’ file will contain the clauses
resulting from the expansion of the EDCG rules found in the ‘unique.lgt’
file by the ‘edcg’ hook object expansion.


File: TheLogtalkHandbook-3.101.0.info,  Node: Documenting,  Next: Debugging,  Prev: Term and goal expansion,  Up: User Manual

1.17 Documenting
================

Assuming that the *note source_data: cc. flag is turned on, the compiler
saves all relevant documenting information collected when compiling a
source file.  The provided *note lgtdoc: 323. tool can access this
information by using the *note reflection: 48. support and generate a
documentation file for each compiled entity (object, protocol, or
category) in XML format.  Contents of the XML file include the entity
name, type, and compilation mode (static or dynamic), the entity
relations with other entities, and a description of any declared
predicates (name, compilation mode, scope, …).  The XML documentation
files can be enriched with arbitrary user-defined information, either
about an entity or about its predicates, by using documentation
directives.  The ‘lgtdoc’ tool includes POSIX and Windows scripts for
converting the XML documentation files to several final formats (such as
HTML and PDF).

Logtalk supports two documentation directives for providing arbitrary
user-defined information about an entity or a predicate.  These two
directives complement other directives that also provide important
documentation information, such as the *note mode/2: 149. and *note
meta_predicate/1: 152. directives.

* Menu:

* Entity documenting directives::
* Predicate documenting directives::
* Describing predicates::
* Documenting predicate exceptions::
* Processing and viewing documenting files::
* Inline formatting in comments text::
* Diagrams::


File: TheLogtalkHandbook-3.101.0.info,  Node: Entity documenting directives,  Next: Predicate documenting directives,  Up: Documenting

1.17.1 Entity documenting directives
------------------------------------

Arbitrary user-defined entity information can be represented using the
*note info/1: b4. directive:

     :- info([
         Key1 is Value1,
         Key2 is Value2,
         ...
     ]).

In this pattern, keys should be atoms and values should be bound terms.
The following keys are predefined and may be processed specially by
Logtalk tools:

‘comment’

     Comment describing the entity purpose (an atom).  End the comment
     with a period (full stop).  As a style guideline, don’t use overly
     long comments.  If you need to provide additional details, use the
     ‘fails_if’ and ‘remarks’ keys.

‘author’

     Entity author(s) (an atom or a compound term ‘{entity}’ where
     ‘entity’ is the name of an XML entity in a user-defined
     ‘custom.ent’ file).

‘version’

     Version number (a ‘Major:Minor:Patch’ compound term) Following the
     Semantic Versioning guidelines(1) is strongly advised.

‘date’

     Date of last modification in ISO 8601 standard format
     (‘Year-Month-Day’ where ‘Year’, ‘Month’, and ‘Day’ are integers).

‘parameters’

     Parameter names and descriptions for parametric entities (a list of
     ‘Name-Description’ pairs where both names and descriptions are
     atoms).  End the ‘Description’ with a period (full stop).

‘parnames’

     Parameter names for parametric entities (a list of atoms; a simpler
     version of the previous key, used when parameter descriptions are
     deemed unnecessary).

‘copyright’

     Copyright notice for the entity source code (an atom or a compound
     term ‘{entity}’ where ‘entity’ is the name of an XML entity defined
     in a user-defined ‘custom.ent’ file).

‘license’

     License terms for the entity source code; usually, just the license
     name (an atom or a compound term ‘{entity}’ where ‘entity’ is the
     name of an XML entity in a user-defined ‘custom.ent’ file).
     License names should, whenever possible, be a license identifier as
     specified in the SPDX standard(2).

‘remarks’

     List of general remarks about the entity using ‘Topic-Text’ pairs
     where both the topic and the text must be atoms.  End the ‘Text’
     with a period (full stop).

‘see_also’

     List of related entities (using the entity identifiers, which can
     be atoms or compound terms).

For example:

     :- info([
         version is 2:1:0,
         author is 'Paulo Moura',
         date is 2000-11-20,
         comment is 'Building representation.',
         diagram is 'UML Class Diagram #312'
     ]).

Use only the keywords that make sense for your application, and remember
that you are free to invent your own keywords.  All key-value pairs can
be retrieved programmatically using the *note reflection API: 48. and
are visible to the *note lgtdoc: 323. tool (which includes them in the
generated documentation).

   ---------- Footnotes ----------

   (1) https://semver.org

   (2) https://spdx.org/licenses/


File: TheLogtalkHandbook-3.101.0.info,  Node: Predicate documenting directives,  Next: Describing predicates,  Prev: Entity documenting directives,  Up: Documenting

1.17.2 Predicate documenting directives
---------------------------------------

Arbitrary user-defined predicate information can be represented using
the *note info/2: 168. directive:

     :- info(Name/Arity, [
         Key1 is Value1,
         Key2 is Value2,
         ...
     ]).

The first argument can also a grammar rule non-terminal indicator,
‘Name//Arity’.  Keys should be atoms.  Values should be bound terms.
The following keys are predefined and may be processed specially by
Logtalk tools:

‘comment’

     Comment describing the predicate (or non-terminal) purpose (an
     atom).  End the comment with a period (full stop).  As a style
     guideline, don’t use overly long comments.  If you need to provide
     additional details, use the ‘remarks’ key.

‘fails_if’

     Comment describing failing conditions for the predicate.  As a
     style guideline, don’t use overly long comments.  If you need to
     provide additional details, use the ‘remarks’ key.

‘arguments’

     Names and descriptions of predicate arguments for pretty print
     output (a list of ‘Name-Description’ pairs where both names and
     descriptions are atoms).  End the ‘Description’ with a period (full
     stop).

‘argnames’

     Names of predicate arguments for pretty print output (a list of
     atoms; a simpler version of the previous key, used when argument
     descriptions are deemed unnecessary).

‘allocation’

     Objects where we should define the predicate.  Some possible values
     are ‘container’, ‘descendants’, ‘instances’, ‘classes’,
     ‘subclasses’, and ‘any’.

‘redefinition’

     Describes if a predicate is expected to be redefined and, if so, in
     what way.  Some possible values are ‘never’, ‘free’, ‘specialize’,
     ‘call_super_first’, ‘call_super_last’.

‘exceptions’

     List of possible exceptions thrown by the predicate using
     ‘Description-Exception’ pairs.  The description must be an atom.
     The exception term must be a ground term.

‘examples’

     List of typical predicate call examples using the format
     ‘Description-Goal-Bindings’.  The description must be an atom with
     the goal term sharing variables with the bindings.  The variable
     bindings term uses the format ‘{Variable = Term, ...}’.  When there
     are no variable bindings, the success or failure of the predicate
     call should be represented by the terms ‘{true}’ or ‘{false}’,
     respectively (you can also use in alternative the terms ‘{yes}’ or
     ‘{no}’).

‘remarks’

     List of general remarks about the predicate using ‘Topic-Text’
     pairs where both the topic and the text must be atoms.  End the
     ‘Text’ with a period (full stop).

‘since’

     Version that added the predicate (‘Major:Minor:Patch’).

‘see_also’

     List of related predicates and non-terminals (using the predicate
     and non-terminal indicators).

For example:

     :- info(color/1, [
         comment is 'Table of defined colors.',
         argnames is ['Color'],
         constraint is 'Up to four visible colors allowed.',
         examples is [
            'Check that the color blue is defined' - color(blue) - {true}
         ]
     ]).

As with the ‘info/1’ directive, use only the keywords that make sense
for your application and remember that you are free to invent your own
keywords.  All key-value pairs can also be retrieved programmatically
using the *note reflection API: 48. and are visible to the *note lgtdoc:
323. tool (which includes them in the generated documentation).


File: TheLogtalkHandbook-3.101.0.info,  Node: Describing predicates,  Next: Documenting predicate exceptions,  Prev: Predicate documenting directives,  Up: Documenting

1.17.3 Describing predicates
----------------------------

The value of the ‘comment’ key, possibly extended with the ‘remarks’
key, should describe a predicate purpose and, when applicable, the
circumstances under which a call may fail.  Descriptions should be
consistent across library and application APIs.  Some guidelines:

1.  When starting the description with a verb, use the 'third-person
singular simple present form'.  For example, write ‘'Runs ...'’, ‘'Calls
...'’, ‘'Compares ...'’, ‘'Parses ...'’, ‘'Generates ...'’, ‘'Converts
...'’, ‘'Creates ...'’, ‘'Maps ...'’, ‘'Merges ...'’, ‘'Finds ...'’,
etc.

2.  Predicates that are pure logical relations often have descriptions
starting with ‘'True iff ...'’ or ‘'True if ...'’.

3.  Predicates with multiple solutions often have descriptions starting
with ‘'Enumerates, by backtracking, all ...'’ or ‘'Enumerates, by
backtracking, the ...'’.

4.  Predicate call failure conditions often have descriptions with one
or more sentences starting with ‘'Fails when ...'’ or ‘'Fails if ...'’.

If you’re not sure how best to describe a predicate, look for examples
in the Logtalk libraries and developer tools APIs documentation.


File: TheLogtalkHandbook-3.101.0.info,  Node: Documenting predicate exceptions,  Next: Processing and viewing documenting files,  Prev: Describing predicates,  Up: Documenting

1.17.4 Documenting predicate exceptions
---------------------------------------

As described above, the ‘info/2’ predicate directive supports an
‘exceptions’ key that allows us to list all exceptions that may occur
when calling a predicate.  For example:

     :- info(check_option/1, [
         comment is 'Succeeds if the option is valid. Throws an error otherwise.',
         argnames is ['Option'],
         exceptions is [
             '``Option`` is a variable' - instantiation_error,
             '``Option`` is neither a variable nor a compound term' - type_error(compound, 'Option'),
             '``Option`` is a compound term but not a valid option' - domain_error(option, 'Option')
         ]
     ]).

When possible, only standard exceptions should be used.  See e.g.  the
*note error handling methods: 24c. section for a full list.  The
argument names should be the same as those provided in the ‘arguments’
or ‘argnames’ keys.  Exceptions are usually listed starting with
instantiation and uninstantiation errors, followed by type errors, and
then domain errors.  These may then be followed by permission,
existence, evaluation, representation, or resource errors.

For each exception, use of 'controlled language' as found, e.g., in the
ISO Prolog Core standard and this Handbook is advised.  Some examples:

Instantiation error when one or more arguments cannot be a variable

     ‘Argument’ is a variable

     ‘Argument1’ and ‘Argument2’ are variables

Instantiation error when a closed list with bound elements is required

     ‘Argument’ is a partial list or a list with an element ‘Element’
     which is a variable

Uninstantiation error when an argument is not a variable

     ‘Argument’ is not a variable

Type error when an argument is not a variable but also not of the expected type

     ‘Argument’ is neither a variable nor a TYPE

     ‘Argument’ is neither a partial list nor a list

Type error when an element of a list is not a variable but is not of the expected type

     An element ‘Element’ of the ‘Argument’ list is neither a variable
     nor a TYPE

Domain error when an argument is of the correct type but not in the expected domain

     ‘Argument’ is a TYPE but not a valid DOMAIN

     ‘Argument’ is an integer that is less than zero

Domain error when an element of a list is of the correct type but not in the expected domain

     An element ‘Element’ of the ‘Argument’ list is a TYPE but not a
     valid DOMAIN

Existence error when an entity of a given kind does not exist

     The KIND ‘Argument’ does not exist

Other classes of errors have a less rigid style.  In case of doubt, look
for examples in this Handbook, in the APIs documentation, and in
standard documents.


File: TheLogtalkHandbook-3.101.0.info,  Node: Processing and viewing documenting files,  Next: Inline formatting in comments text,  Prev: Documenting predicate exceptions,  Up: Documenting

1.17.5 Processing and viewing documenting files
-----------------------------------------------

The *note lgtdoc: 323. tool generates an XML documenting file per
entity.  It can also generate library, directory, entity, and predicate
indexes when documenting libraries and directories.  For example,
assuming the default filename extensions, a ‘trace’ object and a
‘sort(_)’ parametric object will result in ‘trace_0.xml’ and
‘sort_1.xml’ XML files.

Each entity XML file contains references to two other files, an XML
specification file and a XSLT stylesheet file.  The XML specification
file can be either a DTD file (‘logtalk_entity.dtd’) or an XML Scheme
file (‘logtalk_entity.xsd’).  The XSLT stylesheet file is responsible
for converting the XML files to some desired format such as HTML or PDF.
The default names for the XML specification file and the XSL stylesheet
file are defined by the *note lgtdoc: 323. tool but can be overridden by
passing a list of options to the tool predicates.  The ‘lgtdoc/xml’
sub-directory in the Logtalk installation directory contains the XML
specification files described above, along with several sample XSL
stylesheet files and sample scripts for converting XML documenting files
to several formats (e.g., reStructuredText, Markdown, HTML, and PDF).
For example, assume that you want to generate the API documentation for
the ‘types’ library:

     | ?- {types(loader)}.
     ....

     | ?- {lgtdoc(loader)}.
     ....

     | ?- lgtdoc::library(types).
     ...

The above queries will result in the creation of a ‘xml_docs’ in your
current directory by default.  Assuming that we want to generate
Sphinx-based documentation and that we are using a POSIX
operating-system, the next steps would be:

     $ cd xml_docs
     $ lgt2rst -s -m

The ‘lgt2rst’ script will ask a few questions (project name, author,
version, …).  After its completion, the generated HTML files will be
found in the ‘_build/html’ directory by default:

     $ open _build/html/index.html

For Windows operating-systems, PowerShell scripts are available.  For
example, assuming that we want to generate HTML documentation, we could
run in a PowerShell window:

     PS > cd xml_docs
     PS > lgt2html.ps1 -p saxon

After completion, the generated HTML files will be found in the
‘xml_docs’ directory by default.

See the ‘NOTES’ file in the tool directory for details, specially on the
XSLT processor dependencies.  You may use the supplied sample files as a
starting point for generating the documentation of your Logtalk
applications.

The Logtalk DTD file, ‘logtalk_entity.dtd’, contains a reference to a
user-customizable file, ‘custom.ent’, which declares XML entities for
source code author names, license terms, and copyright strings.  After
editing the ‘custom.ent’ file to reflect your personal data, you may use
the XML entities on ‘info/1’ documenting directives.  For example,
assuming that the XML entities are named 'author', 'license', and
'copyright' we may write:

     :- info([
         version is 1:1:0,
         author is {author},
         license is {license},
         copyright is {copyright}
     ]).

The entity references are replaced by the value of the corresponding XML
entity when the XML documenting files are processed ('not' when they are
generated; this notation is just a shortcut to take advantage of XML
entities).

The *note lgtdoc: 323. tool supports a set of options that can be used
to control the generation of the XML documentation files.  See the tool
documentation for details.  There is also a *note doclet: 32e. tool that
allows automating the steps required to generate the documentation for
an application.


File: TheLogtalkHandbook-3.101.0.info,  Node: Inline formatting in comments text,  Next: Diagrams,  Prev: Processing and viewing documenting files,  Up: Documenting

1.17.6 Inline formatting in comments text
-----------------------------------------

Inline formatting in comments text can be accomplished by using Markdown
or reStructuredText syntax and converting XML documenting files to
Markdown or reStructuredText files (and these, if required, to e.g.
HTML, ePub, or PDF formats).  Note that Markdown and reStructuredText
common syntax elements are enough for most API documentation:

     Mark *italic text* with one asterisk.
     Mark **bold text** with two asterisks.
     Mark ``monospaced text`` with two backquotes.

Rendering this block as markup gives:

     Mark 'italic text' with one asterisk.  Mark 'bold text' with two
     asterisks.  Mark ‘monospaced text’ with two backquotes.

As single backquotes have different purposes in Markdown (monospaced
text) and reStructuredText (domain- or application-dependent meaning),
never use them.  This also avoids doubts if there’s an inline formatting
typo in text meant to be rendered as monospaced text (usually inline
code fragments).


File: TheLogtalkHandbook-3.101.0.info,  Node: Diagrams,  Prev: Inline formatting in comments text,  Up: Documenting

1.17.7 Diagrams
---------------

The *note diagrams: 2ee. tool supports a wide range of diagrams that can
also help in documenting an application.  The generated diagrams can
include URL links to both source code and API documentation.  They can
also be linked, connecting, for example, high level diagrams to detail
diagrams.  These features allow diagrams to be an effective solution for
navigating and understanding the structure and implementation of an
application.  This tool uses the same *note reflection API: 48. as the
‘lgtdoc’ tool and thus has access to the same source data.  See the tool
documentation for details.


File: TheLogtalkHandbook-3.101.0.info,  Node: Debugging,  Next: Performance<2>,  Prev: Documenting,  Up: User Manual

1.18 Debugging
==============

The Logtalk distribution includes a command-line *note debugger: 2fd.
tool implemented as a Logtalk application using the debugging API. It
can be loaded at the top-level interpreter by typing:

     | ?- logtalk_load(debugger(loader)).

It can also be loaded automatically at startup time by using a *note
settings file: 49.

The *note debugger: 2fd. tool includes the debugging features found in
traditional Prolog debuggers.  There are some differences, however,
between the usual implementation of Prolog debuggers and the current
implementation of the Logtalk debugger that you should be aware of.
First, unlike most Prolog debuggers, the Logtalk debugger is not a
built-in feature but a regular Logtalk application using documented
debugging hook predicates.  This translates to a different, although
similar, set of debugging features when compared with some of the more
sophisticated Prolog debuggers.  Second, debugging is only possible for
entities compiled in debug mode.  When compiling an entity in debug
mode, Logtalk decorates clauses with source information to allow tracing
of the goal execution.  Third, the tool provides several types of
breakpoints (for pausing and interacting with the debugger) and also log
points, while most Prolog systems are limited to traditional predicate
spy points.

* Menu:

* Compiling source files in debug mode::
* Procedure box model::
* Activating the debugger::
* Defining breakpoints::
* Defining log points::
* Tracing program execution::
* Debugging using breakpoints::
* Debugging commands::
* Customizing term writing::
* Context-switching calls::
* Debugging messages::
* Using the term-expansion mechanism for debugging::
* Ports profiling::
* Debug and trace events::
* Source-level debugger::


File: TheLogtalkHandbook-3.101.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: 2e3. compiler flag.  The default value for this flag, usually
‘off’, is defined in the *note backend adapter files: 154.  Its default
value may be changed globally at runtime by calling:

     | ?- set_logtalk_flag(debug, on).

Implicitly, this goal also turns off the ‘optimize’ flag.  In
alternative, if we want to compile only some source files in debug mode,
we may instead write:

     | ?- logtalk_load([file1, file2, ...], [debug(on)]).

The *note logtalk_make/1: 2a0. built-in predicate can also be used to
recompile all loaded files (that were compiled without using explicit
values for the *note debug: 2e3. and *note optimize: 8c. compiler flags
in a ‘logtalk_load/2’ call or in a *note loader file: 4f, if used) in
debug mode:

     | ?- logtalk_make(debug).

With most *note backend Prolog compilers: 34, the ‘{+d}’ top-level
shortcut can also be used.  After debugging, the files can be recompiled
in normal or optimized mode using, respectively, the ‘{+n}’ or ‘{+o}’
top-level shortcuts.

     Warning: The *note clean: 292. compiler flag should be turned on
     whenever the *note debug: 2e3. flag is turned on at runtime.  This
     is necessary because debug code would not be generated for files
     previously compiled in normal or optimized mode if there are no
     changes to the source files.

After loading the debugger, we may check (or enumerate by backtracking),
all loaded entities compiled in debug mode as follows:

     | ?- debugger::debugging(Entity).

To compile only a specific entity in debug mode, use the *note
set_logtalk_flag/2: 50. directive inside the entity.  To compile all
entities in a source file in debug mode, use the *note
set_logtalk_flag/2: 50. directive at the beginning of the file.


File: TheLogtalkHandbook-3.101.0.info,  Node: Procedure box model,  Next: Activating the debugger,  Prev: Compiling source files in debug mode,  Up: Debugging

1.18.2 Procedure box model
--------------------------

Logtalk uses a 'procedure box model' similar to those found on most
Prolog systems.  The traditional Prolog procedure box model defines four
ports ('call', 'exit', 'redo', and 'fail') for describing control flow
when calling a predicate:

     ‘call’
          predicate call
     ‘exit’
          success of a predicate call
     ‘redo’
          backtracking into a predicate call
     ‘fail’
          failure of a predicate call

Logtalk, as found on some recent Prolog systems, adds a port for dealing
with exceptions thrown when calling a predicate:

     ‘exception’
          predicate call throws an exception

In addition to the ports described above, Logtalk adds two more ports,
‘fact’ and ‘rule’, which show the result of the unification of a goal
with, respectively, a fact and a rule head:

     ‘fact’
          unification success between a goal and a fact
     ‘rule’
          unification success between a goal and a rule head

Following Prolog tradition, the user may define for which ports the
debugger should pause for user interaction by specifying a list of
'leashed' ports.  Unleashed ports are just printed with no pause for
user interaction when tracing.  For example:

     | ?- debugger::leash([call, exit, fail]).

Alternatively, the user may use an atom abbreviation for a pre-defined
set of ports.  For example:

     | ?- debugger::leash(loose).

The abbreviations defined in Logtalk are similar to those defined on
some Prolog compilers:

     ‘none’
          ‘[]’
     ‘loose’
          ‘[fact, rule, call]’
     ‘half’
          ‘[fact, rule, call, redo]’
     ‘tight’
          ‘[fact, rule, call, redo, fail, exception]’
     ‘full’
          ‘[fact, rule, call, exit, redo, fail, exception]’

By default, the debugger pauses at every port for user interaction.


File: TheLogtalkHandbook-3.101.0.info,  Node: Activating the debugger,  Next: Defining breakpoints,  Prev: Procedure box model,  Up: Debugging

1.18.3 Activating the debugger
------------------------------

The debuggerp::trace/0(1) and debuggerp::debug/0(2) predicates
implicitly select the ‘debugger’ tool as the active *note debug handler:
339.  If you have additional debug handlers loaded (e.g., the
‘ports_profiler’ tool), those would no longer be active (there can be
only one active debug handler at any given time).  The
debuggerp::nodebug/0(3) predicate implicitly deselects the ‘debugger’
tool as the active debug handler.

   ---------- Footnotes ----------

   (1) ../../apis/debuggerp_0.html#debuggerp-0-trace-0

   (2) ../../apis/debuggerp_0.html#debuggerp-0-debug-0

   (3) ../../apis/debuggerp_0.html#debuggerp-0-nodebug-0


File: TheLogtalkHandbook-3.101.0.info,  Node: Defining breakpoints,  Next: Defining log points,  Prev: Activating the debugger,  Up: Debugging

1.18.4 Defining breakpoints
---------------------------

The ‘debugger’ tool provides the following breakpoint types where the
debugger pauses at a leashed port for user interaction:

   - 

     Predicate breakpoints

          Traditional Prolog spy points are defined using a predicate
          (or a non-terminal) indicator.  The debugger pauses for user
          input at all ports for the predicate (or non-terminal).

   - 

     Clause breakpoints

          Defined using the location of a clause.  The debugger pauses
          for user input at unification ports.

   - 

     Conditional breakpoints

          Defined using the location of a clause and a condition for
          pausing for user input at an unification port.

   - 

     Hit count breakpoints

          Defined using the location of a clause and an unification
          count expression as a condition for pausing for user input at
          an unification port.

   - 

     Triggered breakpoints

          Defined using the location of a clause and another breakpoint
          that must be hit first as a condition for pausing for user
          input at an unification port.

   - 

     Context breakpoints

          Defined using execution context and goal templates as a
          condition for pausing for user input at all ports.

Clause breakpoints are checked when the current goal successfully
unifies with a clause head.  To simplify their definition, these are
specified using the entity identifier instead of the file name (as all
entities share a single namespace, an entity can only be defined in a
single file) and the first line number of the clause head.  But note
that only some Prolog backends provide accurate source file term line
numbers.  Check the *note debugger: 2fd. tool documentation for details.

* Menu:

* Defining predicate and clause breakpoints::
* Defining conditional breakpoints::
* Defining hit count breakpoints::
* Defining triggered breakpoints::
* Defining context breakpoints::
* Removing all breakpoints::


File: TheLogtalkHandbook-3.101.0.info,  Node: Defining predicate and clause breakpoints,  Next: Defining conditional breakpoints,  Up: Defining breakpoints

1.18.4.1 Defining predicate and clause breakpoints
..................................................

Predicate and clause breakpoints can be defined using the debugger
‘spy/1’ predicate.  The argument can be a predicate indicator
(‘Name/Arity’), a non-terminal indicator (‘Name//Arity’), a clause
location (expressed as an ‘Entity-Line’ pair), or a list of breakpoints.
Predicate and non-terminal indicators can also be qualified with a
specific object or category identifiers.  For example:

     | ?- debugger::spy(person-42).

     Clause breakpoint added.
     yes

     | ?- debugger::spy(foo/2).

     Predicate breakpoint added.
     yes

     | ?- debugger::spy(qux::baz/3).

     Entity predicate breakpoint added.
     yes

     | ?- debugger::spy([foo/4, bar//1, agent-99]).

     All specified breakpoints added.
     yes

Note that setting a clause breakpoint implicitly removes any existing
conditional breakpoint, triggered breakpoint, or log point for the same
clause.

Unconditional clause and predicate breakpoints can be removed by using
the debugger ‘nospy/1’ predicate.  The argument can also be a list of
breakpoints or a non-instantiated variable, in which case all
breakpoints will be removed.  For example:

     | ?- debugger::nospy(_).

     All matching predicate and clause breakpoints removed.
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: Defining conditional breakpoints,  Next: Defining hit count breakpoints,  Prev: Defining predicate and clause breakpoints,  Up: Defining breakpoints

1.18.4.2 Defining conditional breakpoints
.........................................

Conditional clause breakpoints are specified using the debugger ‘spy/3’
predicate.  The first two arguments are the entity and the line of a
clause head.  The third argument is the condition, which can be a lambda
expression, an unification count expression (see next section), or
another breakpoint (see next below).

The supported lambda expressions are ‘[Count, N, Goal]>>Condition’ and
‘[Goal]>>Condition’ where ‘Count’ is the unification count, ‘N’ is the
goal invocation number, and ‘Goal’ is the goal that unified with the
clause head; ‘Condition’ is called in the context of the ‘user’
pseudo-object and must not have any side effects.  Some examples:

     | ?- debugger::spy(planet, 76, [weight(m1,_)]>>true).

     Conditional breakpoint added.
     yes

Note that setting a conditional breakpoint will remove any existing
clause breakpoint or log point for the same location.

Conditional breakpoints can be removed by using the debugger ‘nospy/3’
predicate.  For example:

     | ?- debugger::nospy(planet, _, _).

     All matching conditional breakpoints removed.
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: Defining hit count breakpoints,  Next: Defining triggered breakpoints,  Prev: Defining conditional breakpoints,  Up: Defining breakpoints

1.18.4.3 Defining hit count breakpoints
.......................................

Conditional clause breakpoints that depend on the unification count are
known as 'hit count' clause breakpoints.  The debugger pauses at a hit
count breakpoint depending on an unification count expression:

   - ‘>(Count)’ - break when the unification count is greater than
     ‘Count’

   - ‘>=(Count)’ - break when the unification count is greater than or
     equal to ‘Count’

   - ‘=:=(Count)’ - break when the unification count is equal to ‘Count’

   - ‘=<(Count)’ - break when the unification count is less than or
     equal to ‘Count’

   - ‘<(Count)’ - break when the unification count is less than ‘Count’

   - ‘mod(M)’ - break when the unification count modulo ‘M’ is zero

   - ‘Count’ - break when the unification count is greater than or equal
     to ‘Count’

For example:

     | ?- debugger::spy(planet, 41, =<(2)).

     Conditional breakpoint added.
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: Defining triggered breakpoints,  Next: Defining context breakpoints,  Prev: Defining hit count breakpoints,  Up: Defining breakpoints

1.18.4.4 Defining triggered breakpoints
.......................................

Conditional clause breakpoints that depend on other clause breakpoint or
on a log point are known as 'triggered' clause breakpoints.  The
debugger only pauses at a triggered breakpoint if the clause breakpoint
or log point it depends on is hit first.  For example:

     | ?- debugger::spy(mars, 98, planet-76).

     Triggered breakpoint added.
     yes

In this case, the debugger will break for user interaction at the
unification port for the clause in the source file defining the ‘mars’
object at line 98 if and only if the debugger paused earlier at the
unification port for the clause in the source file defining the ‘planet’
category at line 76.

The debugger prints a ‘^’ character at the beginning of the line for
easy recognition of triggered breakpoints.


File: TheLogtalkHandbook-3.101.0.info,  Node: Defining context breakpoints,  Next: Removing all breakpoints,  Prev: Defining triggered breakpoints,  Up: Defining breakpoints

1.18.4.5 Defining context breakpoints
.....................................

A context breakpoint is a tuple describing a message execution context
and a goal:

     (Sender, This, Self, Goal)

The debugger pauses for user interaction whenever the breakpoint goal
and execution context subsume the goal currently being executed and its
execution context.  The user may establish any number of context
breakpoints as necessary.  For example, in order to call the debugger
whenever a predicate defined on an object named ‘foo’ is called, we may
define the following context breakpoint:

     | ?- debugger::spy(_, foo, _, _).

     Context breakpoint set.
     yes

For example, we can spy all calls to a ‘foo/2’ predicate with a ‘bar’
atom in the second argument by setting the condition:

     | ?- debugger::spy(_, _, _, foo(_, bar)).

     Context breakpoint set.
     yes

The debugger ‘nospy/4’ predicate may be used to remove all matching
breakpoints.  For example, the call:

     | ?- debugger::nospy(_, _, foo, _).

     All matching context breakpoints removed.
     yes

will remove all context breakpoints where the value of *note self: 69.
is the atom ‘foo’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Removing all breakpoints,  Prev: Defining context breakpoints,  Up: Defining breakpoints

1.18.4.6 Removing all breakpoints
.................................

We can remove all breakpoints by using the debugger ‘nospyall/0’
predicate:

     | ?- debugger::nospyall.

     All breakpoints removed.
     yes

There’s also a ‘reset/0’ predicate that can be used to reset the
debugger to its default settings and delete all defined breakpoints and
log points.


File: TheLogtalkHandbook-3.101.0.info,  Node: Defining log points,  Next: Tracing program execution,  Prev: Defining breakpoints,  Up: Debugging

1.18.5 Defining log points
--------------------------

Logtalk log points are similar to clause breakpoints.  Therefore, the
line number must correspond to the first line of an entity clause.  When
the debugger reaches a log point at an unification port, it prints a log
message and continues without pausing execution for reading a port
command.  When the log message is an empty atom, the default port output
message is printed.  When the log message starts with a ‘%’ character,
the default port output message is printed, followed by the log message.
In these two cases, the debugger prints a ‘@’ character at the beginning
of the line for easy recognition of log points output.  When the log
message is neither empty nor starts with a ‘%’ character, the log
message is printed instead of the default port output message.  In this
case, the message can contain ‘$KEYWORD’ placeholders that are expanded
at runtime.  The valid keywords are:

   - ‘PORT’

   - ‘ENTITY’

   - ‘CLAUSE_NUMBER’

   - ‘FILE’

   - ‘LINE’

   - ‘UNIFICATION_COUNT’

   - ‘INVOCATION_NUMBER’

   - ‘GOAL’

   - ‘PREDICATE’

   - ‘EXECUTION_CONTEXT’

   - ‘SENDER’

   - ‘THIS’

   - ‘SELF’

   - ‘METACALL_CONTEXT’

   - ‘COINDUCTION_STACK’

   - ‘THREAD’

Log points are defined using the ‘log/3’ predicate.  For example:

     | ?- debugger::log(agent, 99, '% At the secret headquarters!').
          Log point added.
     yes

     | ?- debugger::log(loop, 42, 'Message $PREDICATE from $SENDER at thread $THREAD').
          Log point added.
     yes

The ‘logging/3’ and ‘nolog/3’ predicate can be used to, respectively,
query and remove log points.  There’s also a ‘nologall/0’ predicate that
removes all log points.

Note that setting a log point will remove any existing clause breakpoint
for the same location.


File: TheLogtalkHandbook-3.101.0.info,  Node: Tracing program execution,  Next: Debugging using breakpoints,  Prev: Defining log points,  Up: Debugging

1.18.6 Tracing program execution
--------------------------------

Logtalk allows tracing of execution for all objects compiled in debug
mode.  To start the debugger in trace mode, write:

     | ?- debugger::trace.

     yes

Next, type the query to be debugged.  For example, using the ‘family’
example in the Logtalk distribution compiled for debugging:

     | ?- addams::sister(Sister, Sibling).
          Call: (1) sister(_1082,_1104) ?
          Rule: (1) sister(_1082,_1104) ?
          Call: (2) ::female(_1082) ?
          Call: (3) female(_1082) ?
          Fact: (3) female(morticia) ?
         *Exit: (3) female(morticia) ?
         *Exit: (2) ::female(morticia) ?
         ...

While tracing, the debugger will pause for user input at each leashed
port, printing an informative message.  Each trace line starts with the
port, followed by the goal invocation number, followed by the goal.  The
invocation numbers are unique and allow us to correlate the ports used
for a goal.  In the output above, you can see, for example, that the
goal ‘::female(_1082)’ succeeds with the answer ‘::female(morticia)’.
The debugger also provides determinism information by prefixing the
‘exit’ port with a ‘*’ character when a call succeeds with choice-points
pending, thus indicating that there might be alternative solutions for
the goal.

Note that breakpoints are ignored when tracing.  But when a breakpoint
is set for the current predicate or clause, the debugger prints, before
the port name and number, a ‘+’ character for predicate breakpoints, a
‘#’ character for clause breakpoints, a ‘?’ character for conditional
clause breakpoints, a ‘^’ for triggered breakpoints, and a ‘*’ character
for context breakpoints.  For example:

     | ?- debugger::spy(female/2).

     yes

     | ?- addams::sister(Sister, Sibling).
          Call: (1) sister(_1078,_1100) ?
          Rule: (1) sister(_1078,_1100) ?
          Call: (2) ::female(_1078) ?
       +  Call: (3) female(_1078) ?

To stop tracing (but still allowing the debugger to pause at the defined
breakpoints), write:

     | ?- debugger::notrace.

     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: Debugging using breakpoints,  Next: Debugging commands,  Prev: Tracing program execution,  Up: Debugging

1.18.7 Debugging using breakpoints
----------------------------------

Tracing a program execution may generate large amounts of debugging
data.  Debugging using breakpoints allows the user to concentrate on
specific points of the code.  To start a debugging session using
breakpoints, write:

     | ?- debugger::debug.

     yes

For example, assuming the predicate breakpoint we set in the previous
section on the ‘female/1’ predicate:

     | ?- addams::sister(Sister, Sibling).
       +  Call: (3) female(_1078) ?

To stop the debugger, write:

     | ?- debugger::nodebug.

     yes

Note that stopping the debugger does not remove any defined breakpoints
or log points.


File: TheLogtalkHandbook-3.101.0.info,  Node: Debugging commands,  Next: Customizing term writing,  Prev: Debugging using breakpoints,  Up: Debugging

1.18.8 Debugging commands
-------------------------

The debugger pauses for user interaction at leashed ports when tracing
and when hitting a breakpoint.  The following commands are available:

‘c’ — creep

     go on; you may use the spacebar, return, or enter keys in
     alternative

‘l’ — leap

     continues execution until the next breakpoint is found

‘s’ — skip

     skips tracing for the current goal; valid at call, redo, and
     unification ports

‘S’ - Skip

     similar to skip but displaying all intermediate ports unleashed

‘q’ — quasi-skip

     skips tracing until returning to the current goal or reaching a
     breakpoint; valid at call and redo ports

‘r’ — retry

     retries the current goal but side-effects are not undone; valid at
     the fail port

‘j’ — jump

     reads invocation number and continues execution until a port is
     reached for that number

‘z’ — zap

     reads either a port name and continues execution until that port is
     reached or a negated port name (e.g.  ‘-exit’) and continues
     execution until a port other than the negated port is reached

‘i’ — ignore

     ignores goal, assumes that it succeeded; valid at call and redo
     ports

‘f’ — fail

     forces backtracking; may also be used to convert an exception into
     a failure

‘n’ — nodebug

     turns off debugging

‘N’ — notrace

     turns off tracing

‘@’ — command; ‘!’ can be used in alternative

     reads and executes a query

‘b’ — break

     suspends execution and starts new interpreter; type ‘end_of_file’
     to terminate

‘a’ — abort

     returns to top level interpreter

‘Q’ — quit

     quits Logtalk

‘p’ — print

     writes current goal using the ‘print/1’ predicate if available

‘d’ — display

     writes current goal without using operator notation

‘w’ — write

     writes current goal quoting atoms if necessary

‘$’ — dollar

     outputs the compiled form of the current goal (for low-level
     debugging)

‘x’ — context

     prints execution context

‘.’ — file

     prints file, entity, predicate, and line number information at an
     unification port

‘e’ — exception

     prints exception term thrown by the current goal

‘E’ — raise exception

     reads and throws an exception term

‘=’ — debugging

     prints debugging information

‘<’ — write depth

     sets the write term depth (set to ‘0’ to reset)

‘*’ — add

     adds a context breakpoint for the current goal

‘/’ — remove

     removes a context breakpoint for the current goal

‘+’ — add

     adds a predicate breakpoint for the current goal

‘-’ — remove

     removes a predicate breakpoint for the current goal

‘#’ — add

     adds a breakpoint for the current clause

‘|’ — remove

     removes a breakpoint for the current clause

‘h’ — condensed help

     prints list of command options

‘?’ — extended help

     prints list of command options


File: TheLogtalkHandbook-3.101.0.info,  Node: Customizing term writing,  Next: Context-switching calls,  Prev: Debugging commands,  Up: Debugging

1.18.9 Customizing term writing
-------------------------------

Debugging complex applications often requires customizing term writing.
The available options are limiting the writing depth of large compound
terms and using the ‘p’ command at a leashed port.  This command uses
the ‘format/3’ de facto standard predicate with the ‘~p’ formatting
option to delegate writing the term to the ‘print/1’ predicate.  But
note that some backends don’t support this formatting option.

* Menu:

* Term write depth::
* Custom term writing::


File: TheLogtalkHandbook-3.101.0.info,  Node: Term write depth,  Next: Custom term writing,  Up: Customizing term writing

1.18.9.1 Term write depth
.........................

The terms written by the debugger can be quite large depending on the
application being debugged.  As described in the previous section, the
debugger accepts the ‘<’ command to set the maximum write term depth for
compound terms.  This command requires that the used *note backend
Prolog compiler: 34. supports the non-standard but common ‘max_depth/1’
option for the ‘write_term/3’ predicate.  When the compound term being
written is deeply nested, the sub-terms are only written up to the
specified depth with the omitted sub-terms replaced usually by ‘...’.
For example:

     | ?- write_term([0,1,2,3,4,5,6,7,8,9], [max_depth(5)]).

     [0,1,2,3,4|...]
     yes

The default maximum depth depends on the backend.  To print compound
terms without a depth limit, set it explicitly to zero if necessary.
The debuggerp::write_max_depth/1(1) and
debuggerp::set_write_max_depth/1(2) predicates can be used to query and
set the default maximum depth.

   ---------- Footnotes ----------

   (1) ../../apis/debuggerp_0.html#debuggerp-0-write-max-depth-1

   (2) ../../apis/debuggerp_0.html#debuggerp-0-set-write-max-depth-1


File: TheLogtalkHandbook-3.101.0.info,  Node: Custom term writing,  Prev: Term write depth,  Up: Customizing term writing

1.18.9.2 Custom term writing
............................

The implicit use of the traditional ‘print/1’ predicate (using the ‘p’
command) and the ‘portray/1’ user-defined hook predicate requires
backend Prolog compiler support for these predicates.  See the
documentation of the backend you intend to use for details.  As an
example, assuming the following ‘portray/1’ definition:

     portray(e(V1,V2)) :-
         format('~q ---> ~q~n', [V1,V2]).

Calling the ‘print/1’ predicate with e.g.  a ‘e(x1,x7)’ compound term
argument will output:

     | ?- print(e(x1,x7)).

     x1 ---> x7
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: Context-switching calls,  Next: Debugging messages,  Prev: Customizing term writing,  Up: Debugging

1.18.10 Context-switching calls
-------------------------------

Logtalk provides a debugging control construct, *note (<<)/2: c7, which
allows the execution of a query within the context of an object.  Common
debugging uses include checking an object local predicates (e.g.
predicates representing internal dynamic state) and sending a message
from within an object.  This control construct may also be used to write
unit tests.

Consider the following toy example:

     :- object(broken).

         :- public(a/1).

         a(A) :- b(A, B), c(B).
         b(1, 2). b(2, 4). b(3, 6).
         c(3).

     :- end_object.

Something is wrong when we try the object public predicate, ‘a/1’:

     | ?- broken::a(A).

     no

For helping in diagnosing the problem, instead of compiling the object
in debug mode and doing a 'trace' of the query to check the clauses for
the non-public predicates, we can instead simply type:

     | ?- broken << c(C).

     C = 3
     yes

The ‘(<<)/2’ control construct works by switching the execution context
to the object in the first argument and then compiling and executing the
second argument within that context:

     | ?- broken << (self(Self), sender(Sender), this(This)).

     Self = broken
     Sender = broken
     This = broken

     yes

As exemplified above, the ‘(<<)/2’ control construct allows you to call
an object local and private predicates.  However, it is important to
stress that we are not bypassing or defeating an object predicate scope
directives.  The calls take place within the context of the specified
object, not within the context of the object making the ‘(<<)/2’ call.
Thus, the ‘(<<)/2’ control construct implements a form of
'execution-context-switching'.

The availability of the ‘(<<)/2’ control construct is controlled by the
*note context_switching_calls: 2da. compiler flag (its default value is
defined in the adapter files of the backend Prolog compilers).


File: TheLogtalkHandbook-3.101.0.info,  Node: Debugging messages,  Next: Using the term-expansion mechanism for debugging,  Prev: Context-switching calls,  Up: Debugging

1.18.11 Debugging messages
--------------------------

Messages generated by calls to the *note logtalk;;print_message/3: 2ff.
predicate where the message kind is either ‘debug’ or ‘debug(Group)’ are
only printed, by default, when the *note debug: 2e3. flag is turned on.
Moreover, these predicate calls are suppressed by the compiler when the
*note optimize: 8c. flag is turned on.  Note that actual printing of
debug messages does not require compiling the code in debug mode, only
turning on the ‘debug’ flag.

* Menu:

* Meta-messages: Meta-messages<2>.
* Selective printing of debug messages::


File: TheLogtalkHandbook-3.101.0.info,  Node: Meta-messages<2>,  Next: Selective printing of debug messages,  Up: Debugging messages

1.18.11.1 Meta-messages
.......................

To avoid having to define *note message_tokens//2: 301. grammar rules
for translating each and every debug message, Logtalk provides default
tokenization for seven 'meta-messages' that cover the most common cases:

‘@Message’

     By default, the message is printed as passed to the ‘write/1’
     predicate followed by a newline.

‘Key-Value’

     By default, the message is printed as ‘Key: Value’ followed by a
     newline.  The key is printed as passed to the ‘write/1’ predicate
     while the value is printed as passed to the ‘writeq/1’ predicate.

‘Format+Arguments’

     By default, the message is printed as passed to the ‘format/2’
     predicate.

‘List’

     By default, the list items are printed indented, one per line.  The
     items are preceded by a dash and can be ‘@Message’, ‘Key-Value’, or
     ‘Format+Arguments’ messages.  If that is not the case, the item is
     printed as passed to the ‘writeq/1’ predicate.

‘Title::List’

     By default, the title is printed, followed by a newline and the
     indented list items, one per line.  The items are printed as in the
     ‘List’ meta message.

‘[Stream,Prefix]>>Goal’

     By default, call user-defined printing ‘Goal’ in the context of
     ‘user’.  The use of a lambda expression allows passing the message
     stream and prefix.  Printing the prefix is delegated to the goal.

‘[Stream]>>Goal’

     By default, call user-defined printing ‘Goal’ in the context of
     ‘user’.  The use of a lambda expression allows passing the message
     stream.

Some simple examples of using these meta-messages:

     | ?- logtalk::print_message(debug, core, @'Phase 1 completed').
     yes

     | ?- logtalk::print_message(debug, core, [Stream]>>write(Stream,foo)).
     yes

     | ?- set_logtalk_flag(debug, on).
     yes

     | ?- logtalk::print_message(debug, core, [Stream]>>write(Stream,foo)).
     foo
     yes

     | ?- logtalk::print_message(debug, core, @'Phase 1 completed').
     >>> Phase 1 completed
     yes

     | ?- logtalk::print_message(debug, core, answer-42).
     >>> answer: 42
     yes

     | ?- logtalk::print_message(debug, core, 'Position: <~d,~d>'+[42,23]).
     >>> Position: <42,23>
     yes

     | ?- logtalk::print_message(debug, core, [arthur,ford,marvin]).
     >>> - arthur
     >>> - ford
     >>> - marvin
     yes

     | ?- logtalk::print_message(debug, core, names::[arthur,ford,marvin]).
     >>> names:
     >>> - arthur
     >>> - ford
     >>> - marvin
     yes

The ‘>>>’ prefix is the default message prefix for ‘debug’ messages.  It
can be redefined using the *note logtalk;;message_prefix_stream/4: 305.
hook predicate.  For example:

     :- multifile(logtalk::message_prefix_stream/4).
     :- dynamic(logtalk::message_prefix_stream/4).

     logtalk::message_prefix_stream(debug, core, '(dbg) ', user_error).

Debugging messages only output information by default.  These messages
can, however, be *note intercepted: 30a. to perform other actions.


File: TheLogtalkHandbook-3.101.0.info,  Node: Selective printing of debug messages,  Prev: Meta-messages<2>,  Up: Debugging messages

1.18.11.2 Selective printing of debug messages
..............................................

By default, all debug messages are either printed or skipped, depending
on the *note debug: 2e3. and *note optimize: 8c. flags.  When the code
is not compiled in optimal mode, the *note debug_messages: 353. tool
allows selective enabling of debug messages per *note component: 354.
and per debug group.  For example, to enable all ‘debug’ and
‘debug(Group)’ messages for the ‘parser’ component:

     % upon loading the tool, all messages are disabled by default:
     | ?- logtalk_load(debug_messages(loader)).
     ...

     % enable both debug and debug(_) messages:
     | ?- debug_messages::enable(parser).
     yes

To enable only ‘debug(tokenization)’ messages for the ‘parser’
component:

     % first disable any and all enabled messages:
     | ?- debug_messages::disable(parser).
     yes

     % enable only debug(tokenization) messages:
     | ?- debug_messages::enable(parser, tokenization).
     yes

See the tool documentation for more details.


File: TheLogtalkHandbook-3.101.0.info,  Node: Using the term-expansion mechanism for debugging,  Next: Ports profiling,  Prev: Debugging messages,  Up: Debugging

1.18.12 Using the term-expansion mechanism for debugging
--------------------------------------------------------

The *note term-expansion mechanism: cb. can also be used for conditional
compilation of debugging goals.  For example, the *note hook_objects:
31c. library provides a print_goal_hook(1) object that simplifies
printing entity goals before or after calling them by simply prefixing
them with an operator.  See the library and hook object documentation
for details.  You can also define your own specialized hook objects for
custom debugging tasks.

   ---------- Footnotes ----------

   (1) ../../apis/print_goal_hook_0.html#print-goal-hook-0


File: TheLogtalkHandbook-3.101.0.info,  Node: Ports profiling,  Next: Debug and trace events,  Prev: Using the term-expansion mechanism for debugging,  Up: Debugging

1.18.13 Ports profiling
-----------------------

The Logtalk distribution includes a *note ports_profiler: 359. tool
based on the same procedure box model described above.  This tool is
specially useful for debugging performance issues (e.g., due to lack of
determinism or unexpected backtracking).  See the tool documentation for
details.


File: TheLogtalkHandbook-3.101.0.info,  Node: Debug and trace events,  Next: Source-level debugger,  Prev: Ports profiling,  Up: Debugging

1.18.14 Debug and trace events
------------------------------

The debugging API defines two multifile predicates,
logtalk::trace_event/2(1) and logtalk::debug_handler/3(2) for handling
trace and debug events.  It also provides a logtalk::debug_handler/1(3)
multifile predicate that allows an object (or a category) to declare
itself as a debug handler provider.  The Logtalk ‘debugger’ and
‘ports_profiler’ tools are regular applications that are implemented
using this API, which can also be used to implement alternative or new
debugging-related tools.  See the API documentation for details and the
source code of the ‘debugger’ and ‘ports_profiler’ tools for usage
examples.

To define a new debug handler provider, add (to an object or category)
clauses for the ‘debug_handler/1’ and ‘debug_handler/3’ predicates.  For
example:

     % declare my_debug_handler as a debug handler provider
     :- multifile(logtalk::debug_handler/1).
     logtalk::debug_handler(my_debug_handler).

     % handle debug events
     :- multifile(logtalk::debug_handler/3).
     logtalk::debug_handler(my_debug_handler, Event, ExCtx) :-
         debug_handler(Event, ExCtx).

     debug_handler(fact(Entity,Fact,Clause,File,Line), ExCtx) :-
         ...
     debug_handler(rule(Entity,Head,Clause,File,Line), ExCtx) :-
         ...
     debug_handler(top_goal(Goal, TGoal), ExCtx) :-
         ...
     debug_handler(goal(Goal, TGoal), ExCtx) :-
         ...

Your debug handler provider should also either automatically call the
logtalk::activate_debug_handler/1(4) and
logtalk::deactivate_debug_handler/0(5) predicate or provide public
predicates to simplify calling these predicates.  For example:

     :- public(start/0).
     start :-
        logtalk::activate_debug_handler(my_debug_handler).

     :- public(stop/0).
     stop :-
        logtalk::deactivate_debug_handler.

If you only need to define a trace event handler, then simply define
clauses for the logtalk::trace_event/2(6) multifile predicate:

     :- multifile(logtalk::trace_event/2).
     :- dynamic(logtalk::trace_event/2).

     % the Logtalk runtime calls all defined logtalk::trace_event/2 hooks using
     % a failure-driven loop; thus we don't have to worry about handling all
     % events or failing after handling an event to give other hooks a chance
     logtalk::trace_event(fact(Entity, Fact, N, _, _), _) :-
         ...
     logtalk::trace_event(rule(Entity, Head, N, _, _), _) :-
         ...

   ---------- Footnotes ----------

   (1) ../../apis/logtalk_0.html#logtalk-0-trace-event-2

   (2) ../../apis/logtalk_0.html#logtalk-0-debug-handler-3

   (3) ../../apis/logtalk_0.html#logtalk-0-debug-handler-1

   (4) ../../apis/logtalk_0.html#logtalk-0-activate-debug-handler-1

   (5) ../../apis/logtalk_0.html#logtalk-0-deactivate-debug-handler-0

   (6) ../../apis/logtalk_0.html#logtalk-0-trace-event-2


File: TheLogtalkHandbook-3.101.0.info,  Node: Source-level debugger,  Prev: Debug and trace events,  Up: Debugging

1.18.15 Source-level debugger
-----------------------------

A minimal source-level debugger is provided by the Logtalk for VSCode
extension: when debugging in the integrated terminal using the
‘debugger’ tool, the current clause (at leashed unification ports) is
shown in the active editor window.  The extension can also be used with
VSCodium.  See its documentation for more details.


File: TheLogtalkHandbook-3.101.0.info,  Node: Performance<2>,  Next: Installing Logtalk,  Prev: Debugging,  Up: User Manual

1.19 Performance
================

Logtalk is implemented as a 'trans-compiler' to Prolog.  When compiling
predicates, it preserves in the generated Prolog code all cases of
first-argument indexing and tail-recursion.  In practice, this means
that if you know how to write efficient Prolog predicates, you already
know the basics of how to write efficient Logtalk predicates.

The Logtalk compiler appends a single argument to the compiled form of
all entity predicate clauses.  This hidden argument is used to pass the
*note execution-context: 35f. when proving a query.  In the common case
where a predicate makes no calls to the *note execution-context
predicates: 360. and *note message-sending control constructs: 361. and
is neither a meta-predicate nor a coinductive predicate, the
execution-context is simply passed between goals.  In this case, with
most backend Prolog virtual machines, the cost of this extra argument is
null or negligible.  When the execution-context needs to be accessed
(e.g. to fetch the value of *note self: 69. for a *note (;;)/1: 5c.
call) there may be a small inherent overhead due to the access to the
individual arguments of the compound term used to represent the
execution-context.

* Menu:

* Source code compilation modes::
* Source code compilation order::
* Local predicate calls::
* Calls to imported or inherited predicates::
* Calls to module predicates::
* Messages: Messages<2>.
* Automatic expansion of built-in meta-predicates::
* Inlining::
* Generated code simplification and optimizations::
* Size of the generated code::
* Circular references::
* Debug mode overhead::
* Other considerations::


File: TheLogtalkHandbook-3.101.0.info,  Node: Source code compilation modes,  Next: Source code compilation order,  Up: Performance<2>

1.19.1 Source code compilation modes
------------------------------------

Source code can be compiled in 'optimal', 'normal', or 'debug' mode,
depending on the *note optimize: 8c. and *note debug: 2e3. compiler
flags.  Optimal mode is used when deploying an application, while normal
and debug modes are used when developing an application.  Compiling code
in optimal mode enables several optimizations, notably the use of *note
static binding: 35. whenever enough information is available at
compile-time.  In debug mode, most optimizations are turned off, and the
code is instrumented to generate *note debug events: d5. that enable
developer tools such as the *note command-line debugger: 2fd. and the
*note ports profiler: 359.


File: TheLogtalkHandbook-3.101.0.info,  Node: Source code compilation order,  Next: Local predicate calls,  Prev: Source code compilation modes,  Up: Performance<2>

1.19.2 Source code compilation order
------------------------------------

Static binding optimizations, notably message sending and super calls,
require referenced code to be compiled before the calls so that the
calls can be resolved at compile time.  The compiler prints warnings
when the file compilation/loading order is not ideal (controlled by the
*note unknown_entities: 2c1. flag).  See the *note Source files: 294.
section on using the logtalk::loaded_files_topological_sort/1(1) and
logtalk::loaded_files_topological_sort/2(2) predicates to find an
optimal file loading order.  See the *note Source files: 294. section
for details.  See also the section below on circular references.

   ---------- Footnotes ----------

   (1) 
../../apis/logtalk_0.html#logtalk-0-loaded-files-topological-sort-1

   (2) 
../../apis/logtalk_0.html#logtalk-0-loaded-files-topological-sort-2


File: TheLogtalkHandbook-3.101.0.info,  Node: Local predicate calls,  Next: Calls to imported or inherited predicates,  Prev: Source code compilation order,  Up: Performance<2>

1.19.3 Local predicate calls
----------------------------

Local calls to object (or category) predicates have zero overhead in
terms of the number of inferences, as expected, compared with local
Prolog calls.


File: TheLogtalkHandbook-3.101.0.info,  Node: Calls to imported or inherited predicates,  Next: Calls to module predicates,  Prev: Local predicate calls,  Up: Performance<2>

1.19.4 Calls to imported or inherited predicates
------------------------------------------------

Assuming the *note optimize: 8c. flag is turned on and a static
predicate, *note (^^)/1: 5d. calls have zero overhead in terms of number
of inferences.


File: TheLogtalkHandbook-3.101.0.info,  Node: Calls to module predicates,  Next: Messages<2>,  Prev: Calls to imported or inherited predicates,  Up: Performance<2>

1.19.5 Calls to module predicates
---------------------------------

Local calls from an object (or category) to a module predicate have zero
overhead (assuming both the module and the predicate are bound at
compile-time).


File: TheLogtalkHandbook-3.101.0.info,  Node: Messages<2>,  Next: Automatic expansion of built-in meta-predicates,  Prev: Calls to module predicates,  Up: Performance<2>

1.19.6 Messages
---------------

Logtalk implements *note static binding: 35. and *note dynamic binding:
36. for message-sending calls.  For dynamic binding, a caching mechanism
is used by the runtime.  It’s useful to measure the performance overhead
in 'number of logic inferences' compared with plain Prolog and Prolog
modules.  Note that the number of logic inferences is a metric
independent of the chosen backend Prolog compiler.  The results for
Logtalk 3.17.0 and later versions are:

   - Static binding: 0

   - Dynamic binding (object bound at compile-time): +1

   - Dynamic binding (object bound at runtime): +2

Static binding is the common case with libraries and most application
code; it requires compiling code with the *note optimize: 8c. flag
turned on.  Dynamic binding numbers are after the first call (i.e.
after the generalization of the query is cached).  All numbers with the
*note events: 89. flag set to ‘deny’ (setting this flag to ‘allow’ adds
an overhead of +5 inferences to the results above; note that this flag
can be defined on a per-object basis as needed instead of globally and
thus minimizing the performance impact).

The dynamic binding caches assume the used *note backend Prolog
compiler: 34. does indexing of dynamic predicates.  This is a common
feature of modern Prolog systems, but the actual details vary from
system to system and may have an impact on dynamic binding performance.

Note that messages to 'self' (*note (;;)/1: 5c. calls) and messages to
an object (*note (;;)/2: 7e. calls) from the top-level interpreter
always use dynamic binding, as the object that receives the message is
only known at runtime.

Messages sent from Prolog modules may use static binding depending on
the used backend Prolog compiler native support for goal-expansion.
Consult the Prolog compiler documentation and adapter file notes for
details.

     Warning: Some Prolog systems provide a ‘time/1’ predicate that also
     reports the number of inferences.  But the reported numbers are
     often misleading when the predicate is called from the top-level.
     Besides common top-level bookkeeping operations (e.g., keeping
     track of goal history or applying goal-expansion) that may
     influence the inference counting, the Logtalk runtime code for a
     ‘(::)/2’ top-level goal is necessarily different from the code
     generated for a ‘(::)/2’ goal from a compiled object, as it
     requires 'runtime' compilation of the goal into the same low-level
     message-sending primitive (assuming dynamic-binding is also
     required for the compiled object goal).


File: TheLogtalkHandbook-3.101.0.info,  Node: Automatic expansion of built-in meta-predicates,  Next: Inlining,  Prev: Messages<2>,  Up: Performance<2>

1.19.7 Automatic expansion of built-in meta-predicates
------------------------------------------------------

The compiler always expands calls to the *note forall/2: 1c3, *note
once/1: 1bb, and *note ignore/1: 180. meta-predicates into equivalent
definitions using the negation and conditional control constructs.  It
also expands calls to the *note call/1-N: 181, *note phrase/2: 18e, and
*note phrase/3: 18f. meta-predicates when the first argument is bound.
These expansions are performed independently of the ‘optimize’ flag
value.


File: TheLogtalkHandbook-3.101.0.info,  Node: Inlining,  Next: Generated code simplification and optimizations,  Prev: Automatic expansion of built-in meta-predicates,  Up: Performance<2>

1.19.8 Inlining
---------------

When the *note optimize: 8c. flag is turned on, the Logtalk compiler
performs 'inlining' of predicate calls whenever possible.  This includes
calls to Prolog predicates that are either built-in, foreign, or defined
in a module (including ‘user’).  Inlining notably allows wrapping module
or foreign predicates using an object without introducing any overhead.
In the specific case of the *note execution-context predicates: 19c,
calls are inlined independently of the ‘optimize’ flag value.


File: TheLogtalkHandbook-3.101.0.info,  Node: Generated code simplification and optimizations,  Next: Size of the generated code,  Prev: Inlining,  Up: Performance<2>

1.19.9 Generated code simplification and optimizations
------------------------------------------------------

When the *note optimize: 8c. flag is turned on, the Logtalk compiler
simplifies and optimizes generated clauses (including those resulting
from the compilation of grammar rules), by flattening conjunctions,
folding left unifications (e.g. generated as a by-product of the
compilation of grammar rules), and removing redundant calls to ‘true/0’.

When using *note lambda expressions: 162. and library meta-predicates,
use the *note meta_compiler: 36b. library to avoid most meta-call
overheads.


File: TheLogtalkHandbook-3.101.0.info,  Node: Size of the generated code,  Next: Circular references,  Prev: Generated code simplification and optimizations,  Up: Performance<2>

1.19.10 Size of the generated code
----------------------------------

The size of the intermediate Prolog code generated by the compiler is
proportional to the size of the source code.  Assuming that the *note
term-expansion mechanism: cb. is not used, each predicate clause in the
source code is compiled into a single predicate clause.  But the Logtalk
compiler also generates internal tables for the defined entities, for
the entity relations, and for the declared and defined predicates.
These tables enable support for fundamental features such as *note
inheritance: 8. and *note reflection: 48.  The size of these tables is
proportional to the number of entities, entity relations, and predicate
declarations and definitions.  When the *note source_data: cc. is turned
on (the default when 'developing' an application), the generated code
also includes additional data about the source code, such as entity and
predicate positions in a source file.  This data enables advanced
developer tool functionality.  But it is usually not required when
'deploying' an application.  Thus, turning this flag off is a common
setting for minimizing an application footprint.


File: TheLogtalkHandbook-3.101.0.info,  Node: Circular references,  Next: Debug mode overhead,  Prev: Size of the generated code,  Up: Performance<2>

1.19.11 Circular references
---------------------------

Circular references, i.e.  two objects sending messages to each other,
are relatively costly and should be avoided if possible as they prevent
using static binding for the messages sent from the first loaded object
to the second object.  The *note logtalk_make(circular): 2a0. goal (or
its ‘{@}’ top-level abbreviation) can be used to scan for circular
entity dependencies.


File: TheLogtalkHandbook-3.101.0.info,  Node: Debug mode overhead,  Next: Other considerations,  Prev: Circular references,  Up: Performance<2>

1.19.12 Debug mode overhead
---------------------------

Code compiled in debug mode runs slower, as expected, when compared with
normal or optimized mode.  The overhead depends on the number of 'debug
events' generated when running the application.  A debug event is simply
a pass on a call or unification port of the *note procedure box model:
336.  These debug events can be intercepted by defined clauses for the
logtalk::trace_event/2(1) and logtalk::debug_handler/3(2) multifile
predicates.  With no application (such as a debugger or a port profiler)
loaded defining clauses for these predicates, each goal has an overhead
of four extra inferences due to the runtime checking for a definition of
the hook predicates and a meta-call of the user goal.  The clause head
unification events result in one or more inferences per goal (depending
on the number of clauses whose head unifies with the goal and
backtracking).  In practice, this overhead translates to code compiled
in debug mode running typically ~2x to ~7x slower than code compiled in
normal or optimized mode, depending on the application (the exact
overhead is proportional to the number of passes on the call and
unification ports; deterministic code often results in a relatively
larger overhead when compared with code performing significant
backtracking).

   ---------- Footnotes ----------

   (1) ../../apis/logtalk_0.html#logtalk-0-trace-event-2

   (2) ../../apis/logtalk_0.html#logtalk-0-debug-handler-3


File: TheLogtalkHandbook-3.101.0.info,  Node: Other considerations,  Prev: Debug mode overhead,  Up: Performance<2>

1.19.13 Other considerations
----------------------------

One aspect of performance that affects both Logtalk and Prolog code is
the characteristics of the Prolog VM. The Logtalk distribution includes
two examples, bench(1) and benchmarks(2), to help evaluate performance
with specific backend Prolog systems.  A table with benchmark results(3)
for a subset of the supported systems is also available at the Logtalk
website.  But note that multiple factors affect the performance of an
application.  The benchmark examples and their results only provide a
partial assessment.

   ---------- Footnotes ----------

   (1) 
https://github.com/LogtalkDotOrg/logtalk3/tree/master/examples/bench

   (2) 
https://github.com/LogtalkDotOrg/logtalk3/tree/master/examples/benchmarks

   (3) https://logtalk.org/performance.html


File: TheLogtalkHandbook-3.101.0.info,  Node: Installing Logtalk,  Next: Prolog integration and migration,  Prev: Performance<2>,  Up: User Manual

1.20 Installing Logtalk
=======================

This page provides an overview of Logtalk installation requirements and
instructions and a description of the files contained in the Logtalk
distribution.  For detailed, up-to-date installation and configuration
instructions, please see the ‘README.md’, ‘INSTALL.md’, and
‘CUSTOMIZE.md’ files distributed with Logtalk.  The broad compatibility
of Logtalk, both with Prolog compilers and operating-systems, together
with all the possible user scenarios, means that installation can vary
from very simple, by running an installer or a couple of scripts, to the
need of patching both Logtalk and Prolog compilers to workaround the
lack of strong Prolog standards or to cope with the requirements of less
common operating-systems.

The preferred installation scenario is to have Logtalk installed in a
system-wide location, thus available for all users, and a local copy of
user-modifiable files on each user home directory (even when you are the
single user of your computer).  This scenario allows each user to
independently customize Logtalk and to freely modify the provided
libraries and programming examples.  Logtalk installers, installation
shell scripts, and Prolog integration scripts favor this installation
scenario, although alternative installation scenarios are always
possible.  The installers set two environment variables, ‘LOGTALKHOME’
and ‘LOGTALKUSER’, pointing, respectively, to the Logtalk installation
folder and to the Logtalk user folder.

User applications should preferably be kept outside of the Logtalk user
folder created by the installation process, as updating Logtalk often
results in updating the contents of this folder.  If your applications
depend on customizations to the distribution files, backup those changes
before updating Logtalk.

* Menu:

* Hardware and software requirements::
* Logtalk installers::
* Source distribution::
* Distribution overview::


File: TheLogtalkHandbook-3.101.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.101.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.101.0.info,  Node: Prolog compiler,  Prev: Computer and operating system,  Up: Hardware and software requirements

1.20.1.2 Prolog compiler
........................

Logtalk requires a *note backend Prolog compiler: 34. supporting
official and de facto standards.  Capabilities needed by Logtalk that
are not defined in the official ISO Prolog Core standard include:

   - access to predicate properties

   - operating-system access predicates

   - de facto standard predicates not (yet) specified in the official
     standard

Logtalk needs access to the predicate property ‘built_in’ to properly
compile objects and categories that contain Prolog built-in predicate
calls.  In addition, some Logtalk built-ins need to know the
dynamic/static status of predicates to ensure correct application.  The
ISO standard for Prolog modules defines a ‘predicate_property/2’
predicate that is already implemented by most Prolog compilers.  Note
that if these capabilities are not built-in the user cannot easily
define them.

For optimal performance, Logtalk requires that the Prolog compiler
supports 'first-argument indexing' for both static and dynamic code
(most modern compilers support this feature).

Since most Prolog compilers are moving closer to the ISO Prolog standard
*note [ISO95]: 31, it is advisable that you try to use the most recent
version of your favorite Prolog compiler.


File: TheLogtalkHandbook-3.101.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.101.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.101.0.info,  Node: Distribution overview,  Prev: Source distribution,  Up: Installing Logtalk

1.20.4 Distribution overview
----------------------------

In the Logtalk installation directory, you will find the following files
and directories:

‘ACKNOWLEDGMENTS.md’ - List of authors, contributors, sponsors, and open
source credits

‘BIBLIOGRAPHY.bib’ – Logtalk bibliography in BibTeX format

‘CITATION.cff’ - Information on how to cite Logtalk

‘CODE_OF_CONDUCT.md’ - Code of conduct for contributors and users
posting on support forums

‘CUSTOMIZE.md’ – Logtalk end-user customization instructions

‘INSTALL.md’ – Logtalk installation instructions

‘LICENSE.txt’ – Logtalk user license

‘NOTICE.txt’ – Logtalk copyright notice

‘QUICK_START.md’ – Quick start instructions for those that do not like
to read manuals

‘README.md’ – several useful pieces of information

‘RELEASE_NOTES.md’ – release notes for this version

‘UPGRADING.md’ – instructions on how to upgrade your programs to the
current Logtalk version

‘VERSION.txt’ – file containing the current Logtalk version number (used
for compatibility checking when upgrading Logtalk)

‘adapters’

     ‘NOTES.md’ – notes on the provided adapter files

     ‘template.pl’ – template adapter file

     ‘...’ – specific adapter files

‘coding’

     ‘NOTES.md’ – notes on syntax highlighter and text editor support
     files providing syntax coloring for publishing and editing Logtalk
     source code

     ‘...’ – syntax coloring support files

‘contributions’

     ‘NOTES.md’ – notes on the user-contributed code

     ‘...’ – user-contributed code files

‘core’

     ‘NOTES.md’ – notes on the current status of the compiler and
     runtime

     ‘...’ – core source files

‘docs/apis’

     ‘NOTES.md’ – notes on the provided documentation for core, library,
     tools, and contributions entities

     ‘index.html’ – root document for all entities documentation

     ‘...’ – other entity documentation files

‘docs/handbook’

     ‘NOTES.md’ – notes on the provided documentation

     ‘bibliography.html’ – bibliography

     ‘glossary.html’ – glossary

     ‘index.html’ – root document for all documentation

     ‘...’ – other documentation files

‘docs/man’

     ‘...’ – POSIX man pages for the shell scripts

‘examples’

     ‘NOTES.md’ – short description of the provided examples

     ‘ack’

          ‘NOTES.md’ – example notes and sample queries

          ‘loader.lgt’ – loader utility file for the example objects

          ‘...’ – ack example source files

     ‘...’ – other examples

‘integration’

     ‘NOTES.md’ – notes on scripts for Logtalk integration with Prolog
     compilers

     ‘...’ – Prolog integration scripts

‘library’

     ‘NOTES.md’ – short description of the library contents

     ‘all_loader.lgt’ – loader utility file for all library entities

     ‘...’ – library source files

‘paths’

     ‘NOTES.md’ – description on how to setup library and example paths

     ‘paths.pl’ – default library and example paths

‘ports’

     ‘NOTES.md’ – description of included ports of third-party software

     ‘...’ – ports

‘samples’

     ‘loader-sample.lgt’ – sample loader file for user applications

     ‘settings-sample.lgt’ – sample file for user-defined Logtalk
     settings

     ‘tester-sample.lgt’ – sample file for helping to automate running
     user application unit tests

     ‘tests-sample.lgt’ – sample file for writing user application unit
     tests

‘scratch’

     ‘NOTES.md’ – notes on the scratch directory

‘scripts’

     ‘NOTES.md’ – notes on scripts for Logtalk user setup, packaging,
     and installation

     ‘...’ – packaging, installation, and setup scripts

‘tests’

     ‘NOTES.md’ – notes on the current status of the unit tests

     ‘...’ – unit tests for built-in features

‘tools’

     ‘NOTES.md’ – notes on the provided programming tools

     ‘...’ – programming tools

* Menu:

* Adapter files::
* Compiler and runtime::
* Library::
* Examples::
* Logtalk source files::


File: TheLogtalkHandbook-3.101.0.info,  Node: Adapter files,  Next: Compiler and runtime,  Up: Distribution overview

1.20.4.1 Adapter files
......................

Adapter files provide the glue code between the Logtalk compiler/runtime
and a Prolog compiler.  Each adapter file contains two sets of
predicates: ISO Prolog standard predicates and directives not built-in
in the target Prolog compiler and Logtalk specific predicates.

Logtalk already includes ready-to-use adapter files for most academic
and commercial Prolog compilers.  If an adapter file is not available
for the compiler that you intend to use, then you need to build a new
one, starting from the included ‘template.pl’ file.  Start by making a
copy of the template file.  Carefully check (or complete if needed) each
listed definition.  If your Prolog compiler conforms to the ISO
standard, this task should only take you a few minutes.  In most cases,
you can borrow code from the predefined adapter files.  If you are
unsure that your Prolog compiler provides all the ISO predicates needed
by Logtalk, try to run the system by setting the unknown predicate error
handler to report as an error any call to a missing predicate.  Better
yet, switch to a modern, ISO-compliant, Prolog compiler.  If you send me
your adapter file, with a reference to the target Prolog compiler, maybe
I can include it in the next release of Logtalk.

The adapter files specify 'default' values for most of the Logtalk *note
compiler flags: 251.  They also specify values for read-only flags that
are used to describe Prolog backend-specific features.


File: TheLogtalkHandbook-3.101.0.info,  Node: Compiler and runtime,  Next: Library,  Prev: Adapter files,  Up: Distribution overview

1.20.4.2 Compiler and runtime
.............................

The ‘core’ sub-directory contains the Prolog and Logtalk source files
that implement the Logtalk compiler and the Logtalk runtime.  The
compiler and the runtime may be split in two (or more) separate files or
combined into a single file, depending on the Logtalk release that you
are installing.


File: TheLogtalkHandbook-3.101.0.info,  Node: Library,  Next: Examples,  Prev: Compiler and runtime,  Up: Distribution overview

1.20.4.3 Library
................

The Logtalk distribution includes a standard library of useful objects,
categories, and protocols.  Read the corresponding ‘NOTES.md’ file for
details about the library contents.


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples,  Next: Logtalk source files,  Prev: Library,  Up: Distribution overview

1.20.4.4 Examples
.................

The Logtalk distribution includes a large number of programming
examples.  The sources of each one of these examples can be found
included in a subdirectory with the same name, inside the directory
examples.  The majority of these examples include tests and a file named
‘SCRIPT.txt’ with sample calls.  Some examples may depend on other
examples and library objects to work properly.  Read the corresponding
‘NOTES.md’ file for details before running an example.


File: TheLogtalkHandbook-3.101.0.info,  Node: Logtalk source files,  Prev: Examples,  Up: Distribution overview

1.20.4.5 Logtalk source files
.............................

Logtalk source files are text files containing one or more entity
definitions (objects, categories, or protocols).  The Logtalk source
files may also contain plain Prolog code.  The extension ‘.lgt’ is
normally used.  Logtalk compiles these files to plain Prolog by
appending to the file name a suffix derived from the extension and by
replacing the ‘.lgt’ extension with ‘.pl’ (‘.pl’ is the default Prolog
extension; if your Prolog compiler expects the Prolog source filenames
to end with a specific, different extension, you can set it in the
corresponding adapter file).


File: TheLogtalkHandbook-3.101.0.info,  Node: Prolog integration and migration,  Prev: Installing Logtalk,  Up: User Manual

1.21 Prolog integration and migration
=====================================

This section provides suggestions for integrating and migrating plain
Prolog code and Prolog module code to Logtalk.  Detailed instructions
are provided for encapsulating plain Prolog code in objects, converting
Prolog modules into objects, and compiling and reusing Prolog modules as
objects from inside Logtalk.  An interesting application of the
techniques described in this section is a solution for running a Prolog
application that uses modules on a Prolog compiler with no module
system.  The *note wrapper: 38c. tool can be used to help in migrating
Prolog code.

* Menu:

* Source files with both Prolog code and Logtalk code::
* Encapsulating plain Prolog code in objects::
* Converting Prolog modules into objects::
* Compiling Prolog modules as objects::
* Dealing with proprietary Prolog directives and predicates::
* Calling Prolog module predicates: Calling Prolog module predicates<2>.
* Loading converted Prolog applications::


File: TheLogtalkHandbook-3.101.0.info,  Node: Source files with both Prolog code and Logtalk code,  Next: Encapsulating plain Prolog code in objects,  Up: Prolog integration and migration

1.21.1 Source files with both Prolog code and Logtalk code
----------------------------------------------------------

Logtalk source files may contain plain Prolog code intermixed with
Logtalk code.  The Logtalk compiler simply copies the plain Prolog code
as-is to the generated Prolog file.  With Prolog modules, it is assumed
that the module code starts with a ‘module/1-2’ directive and ends at
the end of the file.  There is no module ending directive that would
allow us to define more than one module per file.  In fact, most, if not
all, Prolog module systems always define a single module per file.  Some
of them mandate that the ‘module/1-2’ directive be the first term in a
source file.  As such, when the Logtalk compiler finds a ‘module/1-2’
directive, it assumes that all code that follows until the end of the
file belongs to the module.


File: TheLogtalkHandbook-3.101.0.info,  Node: Encapsulating plain Prolog code in objects,  Next: Converting Prolog modules into objects,  Prev: Source files with both Prolog code and Logtalk code,  Up: Prolog integration and migration

1.21.2 Encapsulating plain Prolog code in objects
-------------------------------------------------

Most applications consist of several plain Prolog source files, each one
defining a few top-level predicates and auxiliary predicates that are
not meant to be directly called by the user.  Encapsulating plain Prolog
code in objects allows us to make clear the different roles of each
predicate, to hide implementation details, to prevent auxiliary
predicates from being called outside the object, and to take advantage
of Logtalk advanced code encapsulating and reusing features.  It also
simplifies using its developer tools.

Encapsulating Prolog code using Logtalk objects is simple.  First, for
each source file, add an opening object directive, *note object/1-5: 9a,
to the beginning of the file and an ending object directive, *note
end_object/0: 9b, to the end of the file.  Choose an object name that
reflects the purpose of the source file code (this is a good opportunity
for code refactoring if necessary).  Second, add *note public/1: 143.
predicate directives for the top-level predicates that are used directly
by the user or called from other source files.  Third, we need to be
able to call from inside an object predicates defined in other source
files/objects.  The easiest solution, which has the advantage of not
requiring any changes to the predicate definitions, is to use the *note
uses/2: 4b. directive.  If your Prolog compiler supports
cross-referencing tools, you may use them to help you make sure that all
calls to predicates on other source files/objects are listed in the
*note uses/2: 4b. directives.  The Logtalk ‘wrapper’ tool can also help
in detecting cross-predicate calls.  Compiling the resulting objects
with the Logtalk *note unknown_predicates: 2c2. and *note portability:
1d1. flags set to ‘warning’ will help you identify calls to predicates
defined in other converted source files and possible portability issues.

* Menu:

* Prolog multifile predicates::


File: TheLogtalkHandbook-3.101.0.info,  Node: Prolog multifile predicates,  Up: Encapsulating plain Prolog code in objects

1.21.2.1 Prolog multifile predicates
....................................

Prolog 'multifile' predicates are used when clauses for the same
predicate are spread among several source files.  When encapsulating
plain Prolog code that uses multifile predicates, it’s often the case
that the clauses of the multifile predicates get spread between
different objects and categories, but conversion is straight-forward.
In the Logtalk object (or category) holding the multifile predicate
*note primary declaration: 393, add a *note predicate scope directive:
13f. and a *note multifile/1: 16a. directive.  In all other objects (or
categories) defining clauses for the multifile predicate, add a
‘multifile/1’ directive and predicate clauses using the format:

     :- multifile(Entity::Name/Arity).

     Entity::Functor(...) :-
         ...

See the *note section: 16a. on the ‘multifile/1’ predicate directive for
more information.  An alternative solution is to simply keep the clauses
for the multifile predicates as plain Prolog code and define, if
necessary, a parametric object to encapsulate all predicates working
with the multifile predicate clauses.  For example, assume the following
‘multifile/1’ directive:

     % city(Name, District, Population, Neighbors)
     :- multifile(city/4).

We can define a parametric object with ‘city/4’ as its identifier:

     :- object(city(_Name, _District, _Population, _Neighbors)).

         % predicates for working with city/4 clauses

     :- end_object.

This solution is preferred when the multifile predicates are used to
represent large tables of data.  See the section on *note parametric
objects: 66. for more details.


File: TheLogtalkHandbook-3.101.0.info,  Node: Converting Prolog modules into objects,  Next: Compiling Prolog modules as objects,  Prev: Encapsulating plain Prolog code in objects,  Up: Prolog integration and migration

1.21.3 Converting Prolog modules into objects
---------------------------------------------

Converting Prolog modules into objects may allow an application to run
on a wider range of Prolog compilers, overcoming portability problems.
Some Prolog compilers don’t support a module system.  Among those Prolog
compilers that support a module system, the lack of standardization
leads to several issues, notably with semantics, operators, and
meta-predicates.  In addition, the conversion allows you to take
advantage of Logtalk more powerful abstraction and reuse mechanisms,
such as separation between interface and implementation, inheritance,
parametric objects, and categories.  It also allows you to take full
advantage of Logtalk developer tools for improved productivity.

Converting a Prolog module into an object is simplified when the
directives used in the module are supported by Logtalk (see the listing
in the next section).  Assuming that this is the case, apply the
following steps:

  1. Convert the module ‘module/1’ directive into an *note object/1: 9a.
     opening object directive, using the module name as the object name.
     For ‘module/2’ directives apply the same conversion and convert the
     list of exported predicates into *note public/1: 143. predicate
     directives.  Add a closing object directive, *note end_object/0:
     9b, at the end of the source code.

  2. Convert any ‘export/1’ directives into ‘public/1’ predicate
     directives.

  3. Convert any ‘use_module/1’ directives for modules that will not be
     converted to objects into ‘use_module/2’ directives (see next
     section), replacing the file spec in the first argument with the
     module name.

  4. Convert any ‘use_module/1-2’ directives referencing other modules
     also being converted to objects into Logtalk *note uses/2: 4b.
     directives.

  5. Convert each ‘reexport/1’ directive into a *note uses/2: 4b.
     directive and ‘public/1’ predicate directives (see next section).

  6. Convert any ‘meta_predicate/1’ directives into Logtalk *note
     meta_predicate/1: 152. directives by replacing the module
     meta-argument indicator, ‘:’, with the Logtalk meta-argument
     indicator ‘0’ for goal meta-arguments.  For closure meta-arguments,
     use an integer denoting the number of additional arguments that
     will be appended to construct a goal.  Arguments that are not
     meta-arguments are represented by the ‘*’ character.  Do not use
     argument mode indicators such as ‘?’, or ‘+’, or ‘-’ as Logtalk
     supports *note mode directives: 148.

  7. Convert any explicit qualified calls to module predicates to
     messages by replacing the ‘(:)/2’ operator with the *note (;;)/2:
     7e. message-sending operator when the referenced modules are also
     being converted into objects.  Calls in the pseudo-module ‘user’
     can be encapsulated using the *note {}/1: 191. Logtalk external
     call control construct.  You can also use instead a *note uses/2:
     4b. directive where the first argument would be the atom ‘user’ and
     the second argument a list of all external predicates.  This
     alternative has the advantages of not requiring changes to the code
     making the predicate calls and of better visibility for the
     documenting and diagramming tools.

  8. If your module uses the database built-in predicates to implement
     module-local mutable state using dynamic predicates, add both *note
     private/1: 145. and *note dynamic/1: 15a. directives for each
     dynamic predicate.

  9. If your module declares or defines clauses for multifile module
     predicates, replace the ‘(:)/2’ functor by ‘(::)/2’ in the
     ‘multifile/1’ directives and in the clause heads for all modules
     defining the multifile predicates that are also being converted
     into objects; if that is not the case, just keep the ‘multifile/1’
     directives and the clause heads as-is.

  10. Compile the resulting objects with the Logtalk *note
     unknown_predicates: 2c2, and *note portability: 1d1. flags set to
     ‘warning’ to help you locate possible issues and calls to
     proprietary Prolog built-in predicates and to predicates defined on
     other converted modules.  In order to improve code portability,
     check the Logtalk library for possible alternatives to the use of
     proprietary Prolog built-in predicates.

Before converting your modules to objects, you may try to compile them
first as objects (using the *note logtalk_compile/1: 29e. Logtalk
built-in predicates) to help identify any issues that must be dealt with
when doing the conversion to objects.  Note that Logtalk supports
compiling Prolog files as Logtalk source code without requiring changes
to the file name extensions.


File: TheLogtalkHandbook-3.101.0.info,  Node: Compiling Prolog modules as objects,  Next: Dealing with proprietary Prolog directives and predicates,  Prev: Converting Prolog modules into objects,  Up: Prolog integration and migration

1.21.4 Compiling Prolog modules as objects
------------------------------------------

A possible alternative to porting Prolog code to Logtalk is to compile
the Prolog source files using the ‘logtalk_load/1-2’ and
‘logtalk_compile/1-2’ predicates.  The Logtalk compiler provides partial
support for compiling Prolog modules as Logtalk objects.  This support
may allow using modules from a backend Prolog system in a different
backend Prolog system, although its main purpose is to help in porting
existing Prolog code to Logtalk in order to benefit from its extended
language features and its developer tools.  Why partial support?
Although there is an ISO Prolog standard for modules, it is (rightfully)
ignored by most implementers and vendors (due to its flaws and deviation
from common practice).  In addition, there is no de facto standard for
module systems, despite otherwise frequent misleading claims.  Key
system differences include the set of implemented module directives, the
directive semantics, the handling of operators, the locality of flags,
and the integration of term-expansion mechanisms (when provided).
Another potential issue is that, when compiling modules as objects,
Logtalk assumes that any referenced module (e.g., using ‘use_module/1-2’
directives) is also being compiled as an object.  If that’s not the
case, the compiled module calls being compiled as message-sending goals
will still work for normal predicates but will not work for
meta-predicates called using implicit module qualification.  The reason
is that, unlike in Logtalk, calls to implicitly and explicitly qualified
module meta-predicates have different semantics.  Follows a discussion
of other limitations of this approach that you should be aware of.

* Menu:

* Supported module directives::
* Unsupported module directives::
* Modules using a term-expansion mechanism::
* File search paths::


File: TheLogtalkHandbook-3.101.0.info,  Node: Supported module directives,  Next: Unsupported module directives,  Up: Compiling Prolog modules as objects

1.21.4.1 Supported module directives
....................................

Currently, Logtalk supports the following module directives:

‘module/1’

     The module name becomes the object name.

‘module/2’

     The module name becomes the object name.  The exported predicates
     become public object predicates.  The exported grammar rule
     non-terminals become public grammar rule non-terminals.  The
     exported operators become public object operators but are not
     active elsewhere when loading the code.

‘use_module/2’

     This directive is compiled as a Logtalk *note uses/2: 4b. directive
     in order to ensure correct compilation of the module predicate
     clauses.  The first argument of this directive must be the module
     'name' (an atom), not a module file specification (the adapter
     files attempt to use the Prolog dialect level term-expansion
     mechanism to find the module name from the module file
     specification).  Note that the module is not automatically loaded
     by Logtalk (as it would be when compiling the directive using
     Prolog instead of Logtalk; the programmer may also want the
     specified module to be compiled as an object).  The second argument
     must be a predicate indicator (‘Name/Arity’), a grammar rule
     non-terminal indicator (‘Name//Arity’), a operator declaration, or
     a list of predicate indicators, grammar rule non-terminal
     indicators, and operator declarations.  Predicate aliases can be
     declared using the notation ‘Name/Arity as Alias/Arity’ or, in
     alternative, the notation ‘Name/Arity:Alias/Arity’.  Similar for
     non-terminal aliases.

‘export/1’

     Exported predicates are compiled as public object predicates.  The
     argument must be a predicate indicator (‘Name/Arity’), a grammar
     rule non-terminal indicator (‘Name//Arity’), an operator
     declaration, or a list of predicate indicators, grammar rule
     non-terminal indicators, and operator declarations.

‘reexport/2’

     Reexported predicates are compiled as public object predicates.
     The first argument is the module name.  The second argument must be
     a predicate indicator (‘Name/Arity’), a grammar rule non-terminal
     indicator (‘Name//Arity’), an operator declaration, or a list of
     predicate indicators, grammar rule non-terminal indicators, and
     operator declarations.  Predicate aliases can be declared using the
     notation ‘Name/Arity as Alias/Arity’ or, in alternative, the
     notation ‘Name/Arity:Alias/Arity’.  Similar for non-terminal
     aliases.

‘meta_predicate/1’

     Module meta-predicates become object meta-predicates.  All
     meta-predicates must be declared using the *note meta_predicate/1:
     152. directive using Logtalk syntax for normal arguments and
     meta-arguments.  Note that Prolog module meta-predicates and
     Logtalk meta-predicates don’t share the same explicit-qualification
     calling semantics: in Logtalk, meta-arguments are always called in
     the context of the *note sender: 39a.  Moreover, Logtalk is not
     based on the predicate-prefixing mechanism common to most Prolog
     module systems.

A common issue when compiling modules as objects is the use of the atoms
‘dynamic’, ‘discontiguous’, and ‘multifile’ as operators in directives.
For better portability, avoid this usage.  For example, write:

     :- dynamic([foo/1, bar/2]).

instead of:

     :- dynamic foo/1, bar/2.

Another common issue is missing ‘meta_predicate/1’, ‘dynamic/1’,
‘discontiguous/1’, and ‘multifile/1’ predicate directives.  The Logtalk
compiler supports detection of missing directives (by setting its *note
missing_directives: 2c7. flag to ‘warning’).

When compiling modules as objects, you probably don’t need event support
turned on.  You may use the *note events: 89. compiler flag to ‘deny’ in
the Logtalk compiling and loading built-in methods for a small
performance gain for the compiled code.


File: TheLogtalkHandbook-3.101.0.info,  Node: Unsupported module directives,  Next: Modules using a term-expansion mechanism,  Prev: Supported module directives,  Up: Compiling Prolog modules as objects

1.21.4.2 Unsupported module directives
......................................

The ‘reexport/1’ and ‘use_module/1’ directives are not directly
supported by the Logtalk compiler.  But most Prolog adapter files
provide support for compiling these directives using Logtalk’s first
stage of its *note term-expansion mechanism: cb.  Nevertheless, these
directives can be converted, respectively, into a sequence of ‘:-
use_module/2’ and ‘export/1’ directives and ‘use_module/2’ directives by
finding which predicates exported by the specified modules are
reexported or imported into the module containing the directive.  For
‘use_module/1’ directives, finding the names of the imported predicates
that are actually used is easy.  First, comment out the directive and
compile the file (making sure that the *note unknown_predicates: 2c2.
compiler flag is set to ‘warning’).  Logtalk will print a warning with a
list of predicates that are called but never defined.  Second, use this
list to replace the ‘use_module/1’ directives by ‘use_module/2’
directives.  You should then be able to compile the modified Prolog
module as an object.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modules using a term-expansion mechanism,  Next: File search paths,  Prev: Unsupported module directives,  Up: Compiling Prolog modules as objects

1.21.4.3 Modules using a term-expansion mechanism
.................................................

Although Logtalk supports *note term and goal expansion mechanisms: cb,
the usage semantics are different from similar mechanisms found in some
Prolog compilers.  In particular, Logtalk does not support defining term
and goal expansions clauses in a source file for expanding the source
file itself.  Logtalk forces a clean separation between expansion
clauses and the source files that will be subject to source-to-source
expansions by using *note hook objects: 39f.  But hook objects also
provide a working solution here when the expansion code is separated
from the code to be expanded.  Logtalk supports using a module as a hook
object as long as its name doesn’t coincide with the name of an object
and that the module uses ‘term_expansion/2’ and ‘goal_expansion/2’
predicates.  Assuming that’s the case, before attempting to compile the
modules as objects, set the default hook object to the module containing
the expansion code.  For example, if the expansions are stored in a
‘system’ module:

     | ?- set_logtalk_flag(hook, system).
     ...

This, however, may not be enough, as expansions may be stored in
multiple modules.  A common example is to use a module named ‘prolog’
for system expansions and to store the user-defined expansions in
‘user’.  The Logtalk library provides a solution for these scenarios.
Using the ‘hook_flows’ library we can select multiple hook objects or
hook modules.  For example, assuming expansions stored on both ‘user’
and ‘system’ modules:

     | ?- logtalk_load(hook_flows(loader)).
     ...

     | ?- set_logtalk_flag(hook, hook_set([user, system])).
     ...

After these queries, we can try to compile the modules and look for
other porting or portability issues.  A well-know issue is Prolog module
term-expansions calling predicates such as ‘prolog_load_context/2’,
which will always fail when it’s the Logtalk compiler instead of the
Prolog compiler loading a source file.  In some of these cases, it may
be possible to rewrite the expansion rules to use the *note
logtalk_load_context/2: 318. predicate instead.


File: TheLogtalkHandbook-3.101.0.info,  Node: File search paths,  Prev: Modules using a term-expansion mechanism,  Up: Compiling Prolog modules as objects

1.21.4.4 File search paths
..........................

Some Prolog systems provide a mechanism for defining file search paths
(this mechanism works differently from Logtalk own support for defining
library path aliases).  When porting Prolog code that defines file
search paths, e.g.  for finding module libraries, it often helps to load
the pristine Prolog application before attempting to compile its source
files as Logtalk source files.  Depending on the Prolog backend, this
may allow the file search paths to be used when compiling modules as
objects that use file directives such as ‘use_module/2’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Dealing with proprietary Prolog directives and predicates,  Next: Calling Prolog module predicates<2>,  Prev: Compiling Prolog modules as objects,  Up: Prolog integration and migration

1.21.5 Dealing with proprietary Prolog directives and predicates
----------------------------------------------------------------

Most Prolog compilers define proprietary, non-standard directives and
predicates that may be used in both plain code and module code.
Non-standard Prolog built-in predicates are usually not problematic, as
Logtalk is usually able to identify and compile them correctly (but see
the notes on built-in meta-predicates for possible caveats).  However,
Logtalk will generate compilation errors on source files containing
proprietary directives unless you first specify how the directives
should be handled.  Several actions are possible on a per-directive
basis: ignoring the directive (i.e., do not copy the directive, although
a goal can be proved as a consequence), rewriting and copying the
directive to the generated Prolog files, or rewriting and recompiling
the resulting directive.  To specify these actions, the adapter files
contain clauses for the internal ‘'$lgt_prolog_term_expansion'/2’
predicate.  For example, assume that a given Prolog compiler defines a
‘comment/2’ directive for predicates using the format:

     :- comment(foo/2, "Brief description of the predicate").

We can rewrite this predicate into a Logtalk ‘info/2’ directive by
defining a suitable clause for the ‘'$lgt_prolog_term_expansion'/2’
predicate:

     '$lgt_prolog_term_expansion'(
             (:- comment(F/A, String)),
             (:- info(F/A, [comment is Atom]))
     ) :-
         atom_codes(Atom, String).

This Logtalk feature can be used to allow compilation of legacy Prolog
code without the need of changing the sources.  When used, it is
advisable to set the *note portability: 1d1. compiler flag to ‘warning’
in order to more easily identify source files that are likely
non-portable across Prolog compilers.

A second example, where a proprietary Prolog directive is discarded
after triggering a side effect:

     '$lgt_prolog_term_expansion'(
             (:- load_foreign_files(Files,Libs,InitRoutine)),
             []
     ) :-
         load_foreign_files(Files,Libs,InitRoutine).

In this case, although the directive is not copied to the generated
Prolog file, the foreign library files are loaded as a side effect of
the Logtalk compiler calling the ‘'$lgt_prolog_term_expansion'/2’ hook
predicate.


File: TheLogtalkHandbook-3.101.0.info,  Node: Calling Prolog module predicates<2>,  Next: Loading converted Prolog applications,  Prev: Dealing with proprietary Prolog directives and predicates,  Up: Prolog integration and migration

1.21.6 Calling Prolog module predicates
---------------------------------------

Prolog module predicates can be called from within objects or categories
by simply using explicit module qualification, i.e.  by writing
‘Module:Goal’ or ‘Goal@Module’ (depending on the module system).
Logtalk also supports the use of ‘use_module/2’ directives in objects
and categories (with the restriction that the first argument of the
directive must be the actual module name and not the module file name or
the module file path).  In this case, these directives are parsed in a
similar way to Logtalk *note uses/2: 4b. directives, with calls to the
specified module predicates being automatically translated to
‘Module:Goal’ calls.

As a general rule, the Prolog modules should be loaded (e.g., in the
auxiliary Logtalk loader files) 'before' compiling objects that make use
of module predicates.  Moreover, the Logtalk compiler does not generate
code for the automatic loading of modules referenced in ‘use_module/1-2’
directives.  This is a consequence of the lack of standardization of
these directives, whose first argument can be a module name, a straight
file name, or a file name using some kind of library notation, depending
on the *note backend Prolog compiler: 34.  Worse, modules are sometimes
defined in files with names different from the module names, requiring
finding, opening, and reading the file in order to find the actual
module name.

Logtalk allows you to send a message to a module in order to call one of
its predicates.  This is usually not advised as it implies a performance
penalty when compared to just using the ‘Module:Call’ notation.
Moreover, this works only if there is no object with the same name as
the module you are targeting.  This feature is necessary, however, in
order to properly support the compilation of modules containing
‘use_module/2’ directives as objects.  If the modules specified in the
‘use_module/2’ directives are not compiled as objects but are instead
loaded as-is by Prolog, the exported predicates would need to be called
using the ‘Module:Call’ notation but the converted module will be
calling them through message-sending.  Thus, this feature ensures that,
on a module compiled as an object, any predicate calling other module
predicates will work as expected, either these other modules are loaded
as-is or also compiled as objects.

For more details, see the *note Calling Prolog predicates: 3e. section.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading converted Prolog applications,  Prev: Calling Prolog module predicates<2>,  Up: Prolog integration and migration

1.21.7 Loading converted Prolog applications
--------------------------------------------

Logtalk strongly favors and advises users to provide a main *note loader
file: 2a4. for applications that explicitly load any required libraries
and the application source files.  In contrast, Prolog applications
often either scatter loading of source files from multiple files or use
implicit loading of source files via ‘use_module/1-2’ directives.  Due
to this frequent ad-hoc approach, it’s common to find Prolog
applications with duplicated loading directives, and where loading order
ignores the dependencies between source files.  These issues are easily
exposed by the Logtalk linter when compiling Prolog files as Logtalk
files.  Also common are Prolog files with multiple circular
dependencies.  While this should not affect the 'semantics' of the
ported code, it may cause some performance penalties as it prevents the
Logtalk compiler from optimizing the message sending goals using
static-binding.  It also makes the application architecture more
difficult to understand.  The definition of explicit loader files
provides a good opportunity for sorting out loading order and circular
dependencies, with the linter warnings providing hints for possible code
refactoring to eliminate these issues.  The *note diagrams: 2ee. tool
supports directory and file loading and dependency diagrams that are
also useful in understanding applications architecture.


File: TheLogtalkHandbook-3.101.0.info,  Node: Reference Manual,  Next: Tutorial,  Prev: User Manual,  Up: Top

2 Reference Manual
******************

* Menu:

* Grammar::
* Control constructs::
* Directives: Directives<2>.
* Built-in predicates::
* Built-in methods: Built-in methods<2>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Grammar,  Next: Control constructs,  Up: Reference Manual

2.1 Grammar
===========

The Logtalk grammar is here described using W3C-style Extended
Backus-Naur Form syntax.  Non-terminal symbols not defined here can be
found in the ISO Prolog Core standard.  Terminal symbols are represented
between double-quotes.

* Menu:

* Entities::
* Object definition::
* Category definition::
* Protocol definition::
* Entity relations::
* Entity identifiers::
* Source files: Source files<2>.
* Source file names::
* Terms::
* Directives::
* Clauses and goals::
* Lambda expressions: Lambda expressions<2>.
* Entity properties::
* Predicate properties: Predicate properties<2>.
* Compiler flags: Compiler flags<2>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Entities,  Next: Object definition,  Up: Grammar

2.1.1 Entities
--------------

     entity ::=
        object
        | category
        | protocol


File: TheLogtalkHandbook-3.101.0.info,  Node: Object definition,  Next: Category definition,  Prev: Entities,  Up: Grammar

2.1.2 Object definition
-----------------------

     object ::=
        begin_object_directive ( object_term )* end_object_directive

     begin_object_directive ::=
        ":- object(" object_identifier ( "," object_relations )? ")."

     end_object_directive ::=
        ":- end_object."

     object_relations ::=
        prototype_relations
        | non_prototype_relations

     prototype_relations ::=
        prototype_relation
        | prototype_relation "," prototype_relations

     prototype_relation ::=
        implements_protocols
        | imports_categories
        | extends_objects

     non_prototype_relations ::=
        non_prototype_relation
        | non_prototype_relation "," non_prototype_relations

     non_prototype_relation ::=
        implements_protocols
        | imports_categories
        | instantiates_classes
        | specializes_classes


File: TheLogtalkHandbook-3.101.0.info,  Node: Category definition,  Next: Protocol definition,  Prev: Object definition,  Up: Grammar

2.1.3 Category definition
-------------------------

     category ::=
        begin_category_directive  ( category_term )* end_category_directive

     begin_category_directive ::=
        ":- category(" category_identifier ( "," category_relations )? ")."

     end_category_directive ::=
        ":- end_category."

     category_relations ::=
        category_relation
        | category_relation "," category_relations

     category_relation ::=
        implements_protocols
        | extends_categories
        | complements_objects


File: TheLogtalkHandbook-3.101.0.info,  Node: Protocol definition,  Next: Entity relations,  Prev: Category definition,  Up: Grammar

2.1.4 Protocol definition
-------------------------

     protocol ::=
        begin_protocol_directive  ( protocol_directive )* end_protocol_directive

     begin_protocol_directive ::=
        ":- protocol(" protocol_identifier ( "," extends_protocols)? ")."

     end_protocol_directive ::=
        ":- end_protocol."


File: TheLogtalkHandbook-3.101.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.101.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_list ::=
        "[" implemented_protocol ("," implemented_protocol)* "]"


File: TheLogtalkHandbook-3.101.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_list ::=
        "[" extended_protocol ("," extended_protocol)* "]"


File: TheLogtalkHandbook-3.101.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_list ::=
        "[" imported_category ("," imported_category)* "]"


File: TheLogtalkHandbook-3.101.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_list ::=
        "[" extended_object ("," extended_object)* "]"


File: TheLogtalkHandbook-3.101.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_list ::=
        "[" extended_category ("," extended_category)* "]"


File: TheLogtalkHandbook-3.101.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_list ::=
        "[" instantiated_object ("," instantiated_object)* "]"


File: TheLogtalkHandbook-3.101.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_list ::=
        "[" specialized_object ("," specialized_object)* "]"


File: TheLogtalkHandbook-3.101.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_list ::=
        "[" object_identifier ("," object_identifier)* "]"


File: TheLogtalkHandbook-3.101.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.101.0.info,  Node: Entity identifiers,  Next: Source files<2>,  Prev: Entity relations,  Up: Grammar

2.1.6 Entity identifiers
------------------------

     entity_identifier ::=
        object_identifier
        | protocol_identifier
        | category_identifier

* Menu:

* Object identifiers::
* Category identifiers::
* Protocol identifiers::
* Module identifiers::


File: TheLogtalkHandbook-3.101.0.info,  Node: Object identifiers,  Next: Category identifiers,  Up: Entity identifiers

2.1.6.1 Object identifiers
..........................

     object_identifier ::=
        atom
        | compound


File: TheLogtalkHandbook-3.101.0.info,  Node: Category identifiers,  Next: Protocol identifiers,  Prev: Object identifiers,  Up: Entity identifiers

2.1.6.2 Category identifiers
............................

     category_identifier ::=
        atom
        | compound


File: TheLogtalkHandbook-3.101.0.info,  Node: Protocol identifiers,  Next: Module identifiers,  Prev: Category identifiers,  Up: Entity identifiers

2.1.6.3 Protocol identifiers
............................

     protocol_identifier ::=
        atom


File: TheLogtalkHandbook-3.101.0.info,  Node: Module identifiers,  Prev: Protocol identifiers,  Up: Entity identifiers

2.1.6.4 Module identifiers
..........................

     module_identifier ::=
        atom


File: TheLogtalkHandbook-3.101.0.info,  Node: Source files<2>,  Next: Source file names,  Prev: Entity identifiers,  Up: Grammar

2.1.7 Source files
------------------

     source_file ::=
        ( source_file_content )*

     source_file_content ::=
        source_file_directive
        | clause
        | grammar_rule
        | entity


File: TheLogtalkHandbook-3.101.0.info,  Node: Source file names,  Next: Terms,  Prev: Source files<2>,  Up: Grammar

2.1.8 Source file names
-----------------------

     source_file_name ::=
        atom
        | library_source_file_name

     library_source_file_name ::=
        library_name "(" atom ")"

     library_name ::=
        atom


File: TheLogtalkHandbook-3.101.0.info,  Node: Terms,  Next: Directives,  Prev: Source file names,  Up: Grammar

2.1.9 Terms
-----------

* Menu:

* Object terms::
* Category terms::


File: TheLogtalkHandbook-3.101.0.info,  Node: Object terms,  Next: Category terms,  Up: Terms

2.1.9.1 Object terms
....................

     object_term ::=
        object_directive
        | clause
        | grammar_rule


File: TheLogtalkHandbook-3.101.0.info,  Node: Category terms,  Prev: Object terms,  Up: Terms

2.1.9.2 Category terms
......................

     category_term ::=
        category_directive
        | clause
        | grammar_rule


File: TheLogtalkHandbook-3.101.0.info,  Node: Directives,  Next: Clauses and goals,  Prev: Terms,  Up: Grammar

2.1.10 Directives
-----------------

* Menu:

* Source file directives::
* Conditional compilation directives::
* Object directives: Object directives<2>.
* Category directives: Category directives<2>.
* Protocol directives: Protocol directives<2>.
* Predicate directives::


File: TheLogtalkHandbook-3.101.0.info,  Node: Source file directives,  Next: Conditional compilation directives,  Up: Directives

2.1.10.1 Source file directives
...............................

     source_file_directive ::=
        ":- encoding(" atom ")."
        | ":- set_logtalk_flag(" atom "," nonvar ")."
        | ":- include(" source_file_name ")."
        | prolog_directive


File: TheLogtalkHandbook-3.101.0.info,  Node: Conditional compilation directives,  Next: Object directives<2>,  Prev: Source file directives,  Up: Directives

2.1.10.2 Conditional compilation directives
...........................................

     conditional_compilation_directive ::=
        ":- if(" callable ")."
        | ":- elif(" callable ")."
        | ":- else."
        | ":- endif."


File: TheLogtalkHandbook-3.101.0.info,  Node: Object directives<2>,  Next: Category directives<2>,  Prev: Conditional compilation directives,  Up: Directives

2.1.10.3 Object directives
..........................

     object_directive ::=
        ":- initialization(" callable ")."
        | ":- built_in."
        | ":- threaded."
        | ":- dynamic."
        | ":- info(" entity_info_list ")."
        | ":- set_logtalk_flag(" atom "," nonvar ")."
        | ":- include(" source_file_name ")."
        | ":- uses(" object_alias_list ")."
        | ":- use_module(" module_alias_list ")."
        | conditional_compilation_directive
        | predicate_directive


File: TheLogtalkHandbook-3.101.0.info,  Node: Category directives<2>,  Next: Protocol directives<2>,  Prev: Object directives<2>,  Up: Directives

2.1.10.4 Category directives
............................

     category_directive ::=
        ":- built_in."
        | ":- dynamic."
        | ":- info(" entity_info_list ")."
        | ":- set_logtalk_flag(" atom "," nonvar ")."
        | ":- include(" source_file_name ")."
        | ":- uses(" object_alias_list ")."
        | ":- use_module(" module_alias_list ")."
        | conditional_compilation_directive
        | predicate_directive


File: TheLogtalkHandbook-3.101.0.info,  Node: Protocol directives<2>,  Next: Predicate directives,  Prev: Category directives<2>,  Up: Directives

2.1.10.5 Protocol directives
............................

     protocol_directive ::=
        ":- built_in."
        | ":- dynamic."
        | ":- info(" entity_info_list ")."
        | ":- set_logtalk_flag(" atom "," nonvar ")."
        | ":- include(" source_file_name ")."
        | conditional_compilation_directive
        | predicate_directive


File: TheLogtalkHandbook-3.101.0.info,  Node: Predicate directives,  Prev: Protocol directives<2>,  Up: Directives

2.1.10.6 Predicate directives
.............................

     predicate_directive ::=
        alias_directive
        | synchronized_directive
        | uses_directive
        | use_module_directive
        | scope_directive
        | mode_directive
        | mode_non_terminal_directive
        | meta_predicate_directive
        | meta_non_terminal_directive
        | info_directive
        | dynamic_directive
        | discontiguous_directive
        | multifile_directive
        | coinductive_directive
        | operator_directive

     alias_directive ::=
        ":- alias(" entity_identifier "," alias_directive_resource_list ")."

     synchronized_directive ::=
        ":- synchronized(" synchronized_directive_resource_term ")."

     uses_directive ::=
        ":- uses(" ( object_identifier | parameter_variable ) "," uses_directive_resource_list ")."

     use_module_directive ::=
        ":- use_module(" ( module_identifier | parameter_variable ) "," use_module_directive_resource_list ")."

     scope_directive ::=
        ":- public(" scope_directive_resource_term ")."
        | ":- protected(" scope_directive_resource_term ")."
        | ":- private(" scope_directive_resource_term ")."

     mode_directive ::=
        ":- mode(" predicate_mode_term "," number_of_proofs ")."

     mode_non_terminal_directive ::=
        ":- mode_non_terminal(" non_terminal_mode_term "," number_of_proofs ")."

     meta_predicate_directive ::=
        ":- meta_predicate(" meta_predicate_template_term ")."

     meta_non_terminal_directive ::=
        ":- meta_non_terminal(" meta_non_terminal_template_term ")."

     info_directive ::=
        ":- info(" ( predicate_indicator | non_terminal_indicator ) "," predicate_info_list ")."

     dynamic_directive ::=
        ":- dynamic(" qualified_directive_resource_term ")."

     discontiguous_directive ::=
        ":- discontiguous(" qualified_directive_resource_term ")."

     multifile_directive ::=
        ":- multifile(" qualified_directive_resource_term ")."

     coinductive_directive ::=
        ":- coinductive(" ( predicate_indicator_term | coinductive_predicate_template_term ) ")."

     parameter_variable ::=
        _variable_

     scope_directive_resource_term ::=
        scope_directive_resource
        | scope_directive_resource_sequence
        | scope_directive_resource_list

     scope_directive_resource ::=
        predicate_indicator
        | non_terminal_indicator
        | operator

     scope_directive_resource_sequence ::=
        "(" scope_directive_resource ("," scope_directive_resource)* ")"

     scope_directive_resource_list ::=
        "[" scope_directive_resource ("," scope_directive_resource)* "]"

     entity_resources_list ::=
        predicate_indicator_list
        | operator_list

     predicate_indicator_term ::=
        predicate_indicator
        | predicate_indicator_sequence
        | predicate_indicator_list

     predicate_indicator_sequence ::=
        "(" predicate_indicator ("," predicate_indicator)* ")"

     predicate_indicator_list ::=
        "[" predicate_indicator ("," predicate_indicator)* "]"

     alias_directive_resource ::=
        predicate_indicator_alias
        | non_terminal_indicator_alias

     alias_directive_resource_sequence ::=
        "(" alias_directive_resource ("," alias_directive_resource)* ")"

     alias_directive_resource_list ::=
        "[" alias_directive_resource ("," alias_directive_resource)* "]"

     synchronized_directive_resource_term ::=
        synchronized_directive_resource
        | synchronized_directive_resource_sequence
        | synchronized_directive_resource_list

     synchronized_directive_resource ::=
        predicate_indicator
        | non_terminal_indicator

     synchronized_directive_resource_sequence ::=
        "(" synchronized_directive_resource ("," synchronized_directive_resource)* ")"

     synchronized_directive_resource_list ::=
        "[" synchronized_directive_resource ("," synchronized_directive_resource)* "]"

     uses_directive_resource ::=
        predicate_indicator_alias
        | non_terminal_indicator_alias
        | predicate_indicator
        | non_terminal_indicator
        | predicate_template_alias
        | operator

     uses_directive_resource_sequence ::=
        "(" uses_directive_resource ("," uses_directive_resource)* ")"

     uses_directive_resource_list ::=
        "[" uses_directive_resource ("," uses_directive_resource)* "]"

     use_module_directive_resource ::=
        predicate_indicator_alias
        | non_terminal_indicator_alias
        | predicate_indicator
        | non_terminal_indicator
        | predicate_template_alias
        | operator

     use_module_directive_resource_sequence ::=
        "(" use_module_directive_resource ("," use_module_directive_resource)* ")"

     use_module_directive_resource_list ::=
        "[" use_module_directive_resource ("," use_module_directive_resource)* "]"

     qualified_directive_resource_term ::=
        qualified_directive_resource
        | qualified_directive_resource_sequence
        | qualified_directive_resource_list

     qualified_directive_resource_sequence ::=
        "(" qualified_directive_resource_term ("," qualified_directive_resource_term)* ")"

     qualified_directive_resource_list ::=
        "[" qualified_directive_resource_term ("," qualified_directive_resource_term)* "]"

     qualified_directive_resource ::=
        predicate_indicator
        | non_terminal_indicator
        | object_identifier "::" ( predicate_indicator | non_terminal_indicator)
        | category_identifier "::" ( predicate_indicator | non_terminal_indicator)
        | module_identifier ":" ( predicate_indicator | non_terminal_indicator)

     predicate_indicator_alias ::=
        predicate_indicator "as" predicate_indicator

     predicate_template_alias ::=
        callable "as" callable

     non_terminal_indicator ::=
        functor "//" arity

     non_terminal_indicator_alias ::=
        non_terminal_indicator "as" non_terminal_indicator

     operator_sequence ::=
        operator specification
        | operator specification "," operator_sequence

     operator_list ::=
        "[" operator_sequence "]"

     coinductive_predicate_template_term ::=
        coinductive_predicate_template
        | coinductive_predicate_template_sequence
        | coinductive_predicate_template_list

     coinductive_predicate_template_sequence ::=
        "(" coinductive_predicate_template ("," coinductive_predicate_template)* ")"

     coinductive_predicate_template_list ::=
        "[" coinductive_predicate_template ("," coinductive_predicate_template)* "]"

     coinductive_predicate_template ::=
        atom "(" coinductive_mode_terms ")"

     coinductive_mode_terms ::=
        coinductive_mode_term
        | coinductive_mode_terms "," coinductive_mode_terms

     coinductive_mode_term ::=
        "+"
        | "-"

     predicate_mode_term ::=
        atom "(" mode_terms ")"

     non_terminal_mode_term ::=
        atom "(" mode_terms ")"

     mode_terms ::=
        mode_term
        |mode_term "," mode_terms

     mode_term ::=
        "@"  type?
        | "+" type?
        | "-" type?
        | "?" type?
        | "++" type?
        | "--" type?

     type ::=
        prolog_type | logtalk_type | user_defined_type

     prolog_type ::=
        "term"
        | "nonvar"
        | "var"
        | "compound"
        | "ground"
        | "callable"
        | "list"
        | "atomic"
        | "atom"
        | "number"
        | "integer"
        | "float"

     logtalk_type ::=
        "object"
        | "category"
        | "protocol"
        | "event"

     user_defined_type ::=
        atom
        | compound

     number_of_proofs ::=
        "zero"
        | "zero_or_one"
        | "zero_or_more"
        | "one"
        | "one_or_more"
        | "zero_or_error"
        | "one_or_error"
        | "zero_or_one_or_error"
        | "zero_or_more_or_error"
        | "one_or_more_or_error"
        | "error"

     meta_predicate_template_term ::=
        meta_predicate_template
        | meta_predicate_template_sequence
        | meta_predicate_template_list

     meta_predicate_template_sequence ::=
        "(" meta_predicate_template ("," meta_predicate_template)* ")"

     meta_predicate_template_list ::=
        "[" meta_predicate_template ("," meta_predicate_template)* "]"

     meta_predicate_template ::=
        object_identifier "::" atom "(" meta_predicate_specifiers ")"
        | category_identifier "::" atom "(" meta_predicate_specifiers ")"
        | module_identifier ":" atom "(" meta_predicate_specifiers ")"
        | atom "(" meta_predicate_specifiers ")"

     meta_predicate_specifiers ::=
        meta_predicate_specifier
        | meta_predicate_specifier "," meta_predicate_specifiers

     meta_predicate_specifier ::=
        non_negative_integer
        | "::"
        | "^"
        | "*"

     meta_non_terminal_template_term ::=
        meta_predicate_template_term

     entity_info_pair ::=
        entity_info_item "is" nonvar

     entity_info_list ::=
        "[" entity_info_pair ("," entity_info_pair)* "]"

     entity_info_item ::=
        "comment"
        | "remarks"
        | "author"
        | "version"
        | "date"
        | "copyright"
        | "license"
        | "parameters"
        | "parnames"
        | "see_also"
        | atom

     predicate_info_pair ::=
        predicate_info_item "is" nonvar

     predicate_info_list ::=
        "[" predicate_info_pair ("," predicate_info_pair)* "]"

     predicate_info_item ::=
        "comment"
        | "remarks"
        | "arguments"
        | "argnames"
        | "redefinition"
        | "allocation"
        | "examples"
        | "exceptions"
        | "see_also"
        | atom

     object_alias ::=
        object_identifier "as" object_identifier

     object_alias_list ::=
        "[" object_alias ("," object_alias)* "]"

     module_alias ::=
        module_identifier "as" module_identifier

     module_alias_list ::=
        "[" module_alias ("," module_alias)* "]"


File: TheLogtalkHandbook-3.101.0.info,  Node: Clauses and goals,  Next: Lambda expressions<2>,  Prev: Directives,  Up: Grammar

2.1.11 Clauses and goals
------------------------

     clause ::=
        object_identifier "::" head ":-" body
        | module_identifier ":" head ":-" body
        | head ":-" body
        | object_identifier "::" fact
        | module_identifier ":" fact
        | fact

     goal ::=
        message_sending
        | super_call
        | external_call
        | context_switching_call
        | callable

     message_sending ::=
        message_to_object
        | message_delegation
        | message_to_self

     message_to_object ::=
        receiver "::" messages

     message_delegation ::=
        "[" message_to_object "]"

     message_to_self ::=
        "::" messages

     super_call ::=
        "^^" message

     messages ::=
        message
        | "(" message "," messages ")"
        | "(" message ";" messages ")"
        | "(" message "->" messages ")"

     message ::=
        callable
        | variable

     receiver ::=
        "{" callable "}"
        | object_identifier
        | variable

     external_call ::=
        "{" callable "}"

     context_switching_call ::=
        object_identifier "<<" callable


File: TheLogtalkHandbook-3.101.0.info,  Node: Lambda expressions<2>,  Next: Entity properties,  Prev: Clauses and goals,  Up: Grammar

2.1.12 Lambda expressions
-------------------------

     lambda_expression ::=
        lambda_free_variables "/" lambda_parameters ">>" callable
        | lambda_free_variables "/" callable
        | lambda_parameters ">>" callable

     lambda_free_variables ::=
        "{" variables? "}"

     lambda_parameters ::=
        "[" terms? "]"

     variables ::=
        variable
        | variable "," variables

     terms ::=
        term
        | term "," terms


File: TheLogtalkHandbook-3.101.0.info,  Node: Entity properties,  Next: Predicate properties<2>,  Prev: Lambda expressions<2>,  Up: Grammar

2.1.13 Entity properties
------------------------

     category_property ::=
        "static"
        | "dynamic"
        | "built_in"
        | "file(" atom ")"
        | "file(" atom "," atom ")"
        | "lines(" integer "," integer ")"
        | "directive(" integer "," integer ")"
        | "events"
        | "source_data"
        | "public(" entity_resources_list ")"
        | "protected(" entity_resources_list ")"
        | "private(" entity_resources_list ")"
        | "declares(" predicate_indicator "," predicate_declaration_property_list ")"
        | "defines(" predicate_indicator "," predicate_definition_property_list ")"
        | "includes(" predicate_indicator "," ( object_identifier | category_identifier ) "," predicate_definition_property_list ")"
        | "provides(" predicate_indicator "," ( object_identifier | category_identifier ) "," predicate_definition_property_list ")"
        | "references(" reference "," reference_property_list ")"
        | "alias(" ( object_identifier | module_identifier ) "," entity_alias_property_list ")"
        | "alias(" predicate_indicator "," predicate_alias_property_list ")"
        | "calls(" predicate "," predicate_call_update_property_list ")"
        | "updates(" predicate "," predicate_call_update_property_list ")"
        | "number_of_clauses(" integer ")"
        | "number_of_rules(" integer ")"
        | "number_of_user_clauses(" integer ")"
        | "number_of_user_rules(" integer ")"
        | "debugging"

     object_property ::=
        "static"
        | "dynamic"
        | "built_in"
        | "threaded"
        | "file(" atom ")"
        | "file(" atom "," atom ")"
        | "lines(" integer "," integer ")"
        | "directive(" integer "," integer ")"
        | "context_switching_calls"
        | "dynamic_declarations"
        | "events"
        | "source_data"
        | "complements(" ( "allow" | "restrict" ) ")"
        | "complements"
        | "public(" entity_resources_list ")"
        | "protected(" entity_resources_list ")"
        | "private(" entity_resources_list ")"
        | "declares(" predicate_indicator "," predicate_declaration_property_list ")"
        | "defines(" predicate_indicator "," predicate_definition_property_list ")"
        | "includes(" predicate_indicator "," ( object_identifier | category_identifier ) "," predicate_definition_property_list ")"
        | "provides(" predicate_indicator "," ( object_identifier | category_identifier ) "," predicate_definition_property_list ")"
        | "references(" reference "," reference_property_list ")"
        | "alias(" ( object_identifier | module_identifier ) "," entity_alias_property_list ")"
        | "alias(" predicate_indicator "," predicate_alias_property_list ")"
        | "calls(" predicate "," predicate_call_update_property_list ")"
        | "updates(" predicate "," predicate_call_update_property_list ")"
        | "number_of_clauses(" integer ")"
        | "number_of_rules(" integer ")"
        | "number_of_user_clauses(" integer ")"
        | "number_of_user_rules(" integer ")"
        | "module"
        | "debugging"

     protocol_property ::=
        "static"
        | "dynamic"
        | "built_in"
        | "source_data"
        | "file(" atom ")"
        | "file(" atom "," atom ")"
        | "lines(" integer "," integer ")"
        | "directive(" integer "," integer ")"
        | "public(" entity_resources_list ")"
        | "protected(" entity_resources_list ")"
        | "private(" entity_resources_list ")"
        | "declares(" predicate_indicator "," predicate_declaration_property_list ")"
        | "alias(" predicate_indicator "," predicate_alias_property_list ")"
        | "debugging"

     predicate_declaration_property_list ::=
        "[" predicate_declaration_property ("," predicate_declaration_property)* "]"

     predicate_declaration_property ::=
        "static"
        | "dynamic"
        | "scope(" scope ")"
        | "private"
        | "protected"
        | "public"
        | "coinductive"
        | "multifile"
        | "synchronized"
        | "meta_predicate(" meta_predicate_template ")"
        | "coinductive(" coinductive_predicate_template ")"
        | "non_terminal(" non_terminal_indicator ")"
        | "include(" atom ")"
        | "lines(" integer  "," integer ")"
        | "line_count(" integer ")"
        | "mode(" predicate_mode_term "," number_of_proofs ")"
        | "info(" list ")"

     predicate_definition_property_list ::=
        "[" predicate_definition_property ("," predicate_definition_property)* "]"

     predicate_definition_property ::=
        "inline"
        | "auxiliary"
        | "non_terminal(" non_terminal_indicator ")"
        | "include(" atom ")"
        | "lines(" integer  "," integer ")"
        | "line_count(" integer ")"
        | "number_of_clauses(" integer ")"
        | "number_of_rules(" integer ")"

     entity_alias_property_list ::=
        "[" entity_alias_property ("," entity_alias_property)* "]"

     entity_alias_property ::=
        "object"
        | "module"
        | "for(" ( object_identifier | module_identifier ) ")"
        | "include(" atom ")"
        | "lines(" integer  "," integer ")"
        | "line_count(" integer ")"

     predicate_alias_property_list ::=
        "[" predicate_alias_property ("," predicate_alias_property)* "]"

     predicate_alias_property ::=
        "predicate"
        | "for(" predicate_indicator ")"
        | "from(" entity_identifier ")"
        | "non_terminal(" non_terminal_indicator ")"
        | "include(" atom ")"
        | "lines(" integer  "," integer ")"
        | "line_count(" integer ")"

     predicate ::=
        predicate_indicator
        | "^^" predicate_indicator
        | "::" predicate_indicator
        | ( variable | object_identifier ) "::" predicate_indicator
        | ( variable | module_identifier ) ":" predicate_indicator

     predicate_call_update_property_list ::=
        "[" predicate_call_update_property ("," predicate_call_update_property)* "]"

     predicate_call_update_property ::=
        "caller(" predicate_indicator ")"
        | "include(" atom ")"
        | "lines(" integer  "," integer ")"
        | "line_count(" integer ")"
        | "alias(" predicate_indicator ")"
        | "non_terminal(" non_terminal_indicator ")"

     reference ::=
        object_identifier | category_identifier
        | ( object_identifier | category_identifier ) "::" predicate_indicator

     reference_property ::=
        "in(" ( "multifile" | "dynamic" | "discontiguous" | "meta_predicate" | "meta_non_terminal" | "clause" ) ")"
        | "include(" atom ")"
        | "lines(" integer  "," integer ")"
        | "line_count(" integer ")"
        | "non_terminal(" non_terminal_indicator ")"

     reference_property_list ::=
        "[" reference_property ("," reference_property)* "]"


File: TheLogtalkHandbook-3.101.0.info,  Node: Predicate properties<2>,  Next: Compiler flags<2>,  Prev: Entity properties,  Up: Grammar

2.1.14 Predicate properties
---------------------------

     predicate_property ::=
        "static"
        | "dynamic"
        | "scope(" scope ")"
        | "private"
        | "protected"
        | "public"
        | "logtalk"
        | "prolog"
        | "foreign"
        | "coinductive(" coinductive_predicate_template ")"
        | "multifile"
        | "synchronized"
        | "built_in"
        | "inline"
        | "recursive"
        | "declared_in(" entity_identifier ")"
        | "defined_in(" ( object_identifier | category_identifier ) ")"
        | "redefined_from(" ( object_identifier | category_identifier ) ")"
        | "meta_predicate(" meta_predicate_template ")"
        | "alias_of(" callable ")"
        | "alias_declared_in(" entity_identifier ")"
        | "non_terminal(" non_terminal_indicator ")"
        | "mode(" predicate_mode_term "," number_of_proofs ")"
        | "info(" list ")"
        | "number_of_clauses(" integer ")"
        | "number_of_rules(" integer ")"
        | "declared_in(" entity_identifier "," line_count ")"
        | "defined_in(" ( object_identifier | category_identifier ) "," line_count ")"
        | "redefined_from(" ( object_identifier | category_identifier ) "," line_count ")"
        | "alias_declared_in(" entity_identifier "," line_count ")"

     line_count ::=
        integer


File: TheLogtalkHandbook-3.101.0.info,  Node: Compiler flags<2>,  Prev: Predicate properties<2>,  Up: Grammar

2.1.15 Compiler flags
---------------------

     compiler_flag ::=
        flag "(" flag_value ")"


File: TheLogtalkHandbook-3.101.0.info,  Node: Control constructs,  Next: Directives<2>,  Prev: Grammar,  Up: Reference Manual

2.2 Control constructs
======================

* Menu:

* Message sending: Message sending<2>.
* Message delegation::
* Calling imported and inherited predicates: Calling imported and inherited predicates<2>.
* Calling predicates in this::
* Calling external predicates::
* Context switching calls::


File: TheLogtalkHandbook-3.101.0.info,  Node: Message sending<2>,  Next: Message delegation,  Up: Control constructs

2.2.1 Message sending
---------------------

'control construct'

* Menu:

* (;;)/2: /2.
* (;;)/1: /1.


File: TheLogtalkHandbook-3.101.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.101.0.info,  Node: Description,  Next: Modes and number of proofs,  Up: /2

2.2.1.2 Description
...................

     Object::Message
     {Proxy}::Message

Sends a message to an object.  The message argument must match a *note
public: 143. predicate of the receiver object.  When the message
corresponds to a *note protected: 144. or *note private: 145. predicate,
the call is only valid if the *note sender: 39a. matches the *note
predicate scope container: 3fa.  When the predicate is declared but not
defined, the message simply fails (as per the *note closed-world
assumption: 6a.).

When the predicate used to answer the message is a *note meta-predicate:
52, the *note calling context: 150. for the predicate meta-arguments is
the object sending the message.

The ‘{Proxy}::Message’ syntax allows simplified access to *note
parametric object proxies: 3fb.  Its operational semantics is equivalent
to the conjunction ‘(call(Proxy), Proxy::Message)’.  I.e.  ‘Proxy’ is
proved within the context of the pseudo-object *note user: cf. and, if
successful, the ‘Proxy’ term is used as an object identifier.
Exceptions thrown when proving ‘Proxy’ are handled by the ‘(::)/2’
control construct.  This control construct supports backtracking over
the ‘{Proxy}’ goal.

The lookups for the message declaration and the corresponding method are
performed using a depth-first strategy.  Depending on the value of the
*note optimize: 8c. flag, these lookups are performed at compile-time
whenever sufficient information is available.  When the lookups are
performed at runtime, a caching mechanism is used to improve performance
for subsequent messages.  See the User Manual section on *note
performance: 38. for details.


File: TheLogtalkHandbook-3.101.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.101.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.101.0.info,  Node: Examples<2>,  Prev: Errors,  Up: /2

2.2.1.5 Examples
................

     | ?- list::member(X, [1, 2, 3]).

     X = 1 ;
     X = 2 ;
     X = 3
     yes

See also
........

*note (;;)/1: 5c, *note (^^)/1: 5d, *note []/1: 81.

'control construct'


File: TheLogtalkHandbook-3.101.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.101.0.info,  Node: Description<2>,  Next: Modes and number of proofs<2>,  Up: /1

2.2.1.7 Description
...................

     ::Message

Sends a message to *note self: 69.  Can only be used in the body of a
predicate definition.  The argument should match a *note public: 143. or
*note protected: 144. predicate of 'self'.  It may also match a *note
private: 145. predicate if the predicate is within the scope of the
object where the method making the call is defined, if imported from a
category, if used from within a category, or when using private
inheritance.  When the predicate is declared but not defined, the
message simply fails (as per the *note closed-world assumption: 6a.).

When the predicate used to answer the message is a *note meta-predicate:
52, the *note calling context: 150. for the predicate meta-arguments is
the object sending the message.

The lookups for the message declaration and the corresponding method are
performed using a depth-first strategy.  A message to 'self' necessarily
implies the use of *note dynamic binding: 36. but a caching mechanism is
used to improve performance in subsequent messages.  See the User Manual
section on *note performance: 38. for details.


File: TheLogtalkHandbook-3.101.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.101.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.101.0.info,  Node: Examples<3>,  Prev: Errors<2>,  Up: /1

2.2.1.10 Examples
.................

     area(Area) :-
         ::width(Width),
         ::height(Height),
         Area is Width * Height.

See also
........

*note (;;)/2: 7e, *note (^^)/1: 5d, *note []/1: 81.


File: TheLogtalkHandbook-3.101.0.info,  Node: Message delegation,  Next: Calling imported and inherited predicates<2>,  Prev: Message sending<2>,  Up: Control constructs

2.2.2 Message delegation
------------------------

'control construct'

* Menu:

* []/1::


File: TheLogtalkHandbook-3.101.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.101.0.info,  Node: Description<3>,  Next: Modes and number of proofs<3>,  Up: []/1

2.2.2.2 Description
...................

     [Object::Message]
     [{Proxy}::Message]

This control construct allows the programmer to send a message to an
object while preserving the original sender and meta-call context.  It
is mainly used in the definition of object handlers for unknown
messages.  This functionality is usually known as 'delegation' but be
aware that this is an overloaded word that can mean different things in
different object-oriented programming languages.

To prevent the use of this control construct to break object
encapsulation, an attempt to delegate a message to the original sender
results in an error.  The remaining error conditions are the same as the
*note (;;)/2: 7e. control construct.

Note that, despite the correct functor for this control construct being
(traditionally) ‘'.'/2’, we refer to it as ‘[]/1’ simply to emphasize
that the syntax is a list with a single element.


File: TheLogtalkHandbook-3.101.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.101.0.info,  Node: Errors<3>,  Next: Examples<4>,  Prev: Modes and number of proofs<3>,  Up: []/1

2.2.2.4 Errors
..............

     ‘Object’ is a variable:
          ‘instantiation_error’
     Object is neither a variable nor an object identifier:
          ‘type_error(object_identifier, Object)’
     ‘Object’ does not exist:
          ‘existence_error(object, Object)’
     ‘Object’ and the original 'sender' are the same object:
          ‘permission_error(access, object, Sender)’
          
     ‘Proxy’ is a variable:
          ‘instantiation_error’
     ‘Proxy’ is neither a variable nor an object identifier:
          ‘type_error(object_identifier, Proxy)’
     ‘Proxy’, with predicate indicator ‘Name/Arity’, does not exist in the ‘user’ pseudo-object:
          ‘existence_error(procedure, Name/Arity)’
          
     ‘Message’ is a variable:
          ‘instantiation_error’
     ‘Message’ is neither a variable nor a callable term:
          ‘type_error(callable, Message)’
     ‘Message’, with predicate indicator ‘Name/Arity’, is declared private:
          ‘permission_error(access, private_predicate, Name/Arity)’
     ‘Message’, with predicate indicator ‘Name/Arity’, is declared protected:
          ‘permission_error(access, protected_predicate, Name/Arity)’
     ‘Message’, with predicate indicator ‘Name/Arity’, is not declared:
          ‘existence_error(predicate_declaration, Name/Arity)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<4>,  Prev: Errors<3>,  Up: []/1

2.2.2.5 Examples
................

     % delegate unknown messages to the "backup" object:
     forward(Message) :-
         [backup::Message].

See also
........

*note (;;)/2: 7e, *note (;;)/1: 5c, *note (^^)/1: 5d, *note forward/1:
105.


File: TheLogtalkHandbook-3.101.0.info,  Node: Calling imported and inherited predicates<2>,  Next: Calling predicates in this,  Prev: Message delegation,  Up: Control constructs

2.2.3 Calling imported and inherited predicates
-----------------------------------------------

'control construct'

* Menu:

* (^^)/1: ^^ /1.


File: TheLogtalkHandbook-3.101.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.101.0.info,  Node: Description<4>,  Next: Modes and number of proofs<4>,  Up: ^^ /1

2.2.3.2 Description
...................

     ^^Predicate

Calls an imported or inherited predicate definition.  The call fails if
the predicate is declared but there is no imported or inherited
predicate definition (as per the *note closed-world assumption: 6a.).
This control construct may be used within objects or categories in the
body of a predicate definition.

This control construct preserves the implicit execution context *note
self: 69. and *note sender: 39a. arguments (plus the meta-call context
and coinduction stack when applicable) when calling the inherited (or
imported) predicate definition.

The lookups for the predicate declaration and the predicate definition
are performed using a depth-first strategy.  Depending on the value of
the *note optimize: 8c. flag, these lookups are performed at
compile-time when the predicate is static and sufficient information is
available.  When the lookups are performed at runtime, a caching
mechanism is used to improve performance in subsequent calls.  See the
User Manual section on *note performance: 38. for details.

When the call is made from within an object, the lookup for the
predicate definition starts at the imported categories, if any.  If an
imported predicate definition is not found, the lookup proceeds to the
ancestor objects.  Calls from predicates defined in complementing
categories lookup inherited definitions as if the calls were made from
the complemented object, thus allowing more comprehensive object
patching.  For other categories, the predicate definition lookup is
restricted to the extended categories.

The called predicate should be declared *note public: 143. or *note
protected: 144.  It may also be declared *note private: 145. if within
the scope of the entity where the method making the call is defined.

This control construct is a generalization of the Smalltalk 'super'
keyword to take into account Logtalk support for prototypes and
categories besides classes.


File: TheLogtalkHandbook-3.101.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.101.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.101.0.info,  Node: Examples<5>,  Prev: Errors<4>,  Up: ^^ /1

2.2.3.5 Examples
................

     % specialize the inherited definition
     % of the init/0 predicate:
     init :-
         assertz(counter(0)),
         ^^init.

See also
........

*note (;;)/2: 7e, *note (;;)/1: 5c, *note []/1: 81.


File: TheLogtalkHandbook-3.101.0.info,  Node: Calling predicates in this,  Next: Calling external predicates,  Prev: Calling imported and inherited predicates<2>,  Up: Control constructs

2.2.4 Calling predicates in 'this'
----------------------------------

'control construct'

* Menu:

* (@)/1: @ /1.


File: TheLogtalkHandbook-3.101.0.info,  Node: @ /1,  Up: Calling predicates in this

2.2.4.1 ‘(@)/1’
...............

* Menu:

* Description: Description<5>.
* Modes and number of proofs: Modes and number of proofs<5>.
* Errors: Errors<5>.
* Examples: Examples<6>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<5>,  Next: Modes and number of proofs<5>,  Up: @ /1

2.2.4.2 Description
...................

     @Predicate

Calls a predicate definition in *note this: 114.  The argument must be a
callable term at compile-time.  The predicate must be declared (by a
scope directive).  This control construct provides access to predicate
definitions in 'this' from categories.  For example, it allows
overriding a predicate definition from a complementing category with a
new definition that calls goals before and after calling the overridden
definition (the overriding definition is sometimes described in other
programming languages as an 'around method').  When used within an
object, it’s the same as calling its argument.


File: TheLogtalkHandbook-3.101.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.101.0.info,  Node: Errors<5>,  Next: Examples<6>,  Prev: Modes and number of proofs<5>,  Up: @ /1

2.2.4.4 Errors
..............

     ‘Predicate’, with predicate indicator ‘Name/Arity’, is not declared:
          ‘existence_error(predicate_declaration, Name/Arity)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<6>,  Prev: Errors<5>,  Up: @ /1

2.2.4.5 Examples
................

Assuming an object declaring a ‘make_sound/0’ predicate, define an
'around method' in a complementing category:

     make_sound :-
         write('Started making sound...'), nl,
         @make_sound,
         write('... finished making sound.'), nl.

See also
........

*note (;;)/2: 7e, *note (;;)/1: 5c, *note []/1: 81.


File: TheLogtalkHandbook-3.101.0.info,  Node: Calling external predicates,  Next: Context switching calls,  Prev: Calling predicates in this,  Up: Control constructs

2.2.5 Calling external predicates
---------------------------------

'control construct'

* Menu:

* {}/1::


File: TheLogtalkHandbook-3.101.0.info,  Node: {}/1,  Up: Calling external predicates

2.2.5.1 ‘{}/1’
..............

* Menu:

* Description: Description<6>.
* Modes and number of proofs: Modes and number of proofs<6>.
* Errors: Errors<6>.
* Examples: Examples<7>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<6>,  Next: Modes and number of proofs<6>,  Up: {}/1

2.2.5.2 Description
...................

     {Goal}
     {Closure}
     {Term}

This control construct allows the programmer to bypass the Logtalk
compiler (including its linter but not its optimizer) in multiple
contexts:

   - Calling a goal as-is (from within an object or category) in the
     context of the *note user: cf. pseudo-object.

   - Extending a closure as-is with the remaining arguments of a *note
     call/2-N: 181. call in order to construct a goal that will be
     called within the context of the ‘user’ pseudo-object.

   - Wrapping a source file term (either a clause or a directive) or a
     source file goal to bypass the *note term-expansion mechanism: cb.

   - Using it in place of an object identifier when sending a message.
     In this case, its argument is proved as a goal within the context
     of the ‘user’ pseudo-object with the resulting term being used as
     an object identifier in the message-sending goal.  This feature is
     mainly used with *note parametric objects: 426. when their
     identifiers correspond to predicates defined in ‘user’.

   - Using it as a message to an object.  This is mainly useful when the
     message is a *note conjunction of messages: 84. where some of goals
     are calls to Prolog built-in predicates.

     Note: This control construct is opaque to cuts when used to wrap a
     goal (thus ensuring the same semantics independently of the
     argument being bound at compile-time or at runtime).


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<6>,  Next: Errors<6>,  Prev: Description<6>,  Up: {}/1

2.2.5.3 Modes and number of proofs
..................................

     {+callable} - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<6>,  Next: Examples<7>,  Prev: Modes and number of proofs<6>,  Up: {}/1

2.2.5.4 Errors
..............

     ‘Goal’ is a variable:
          ‘instantiation_error’
     ‘Goal’ is neither a variable nor a callable term:
          ‘type_error(callable, Goal)’
          
     ‘Closure’ is a variable:
          ‘instantiation_error’
     ‘Closure’ is neither a variable nor a callable term:
          ‘type_error(callable, Closure)’
          
     ‘Term’ is a variable:
          ‘instantiation_error’
     ‘Term’ is neither a variable nor a callable term:
          ‘type_error(callable, Term)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<7>,  Prev: Errors<6>,  Up: {}/1

2.2.5.5 Examples
................

     % overload the standard (<)/2 operator by
     % calling its standard built-in definition:
     N1/D1 < N2/D2 :-
         {N1*D2 < N2*D1}.

     % call a closure in the context of "user":
     call_in_user(F, X, Y, Z) :-
         call({F}, X, Y, Z).

     % bypass the compiler for a proprietary backend directive:
     {:- load_foreign_resource(file)}.

     % use parametric object proxies:
     | ?- {circle(Id, Radius, Color)}::area(Area).
     ...

     % use Prolog built-in predicates as messages:
     | ?- logtalk::{write('hello world!'), nl}.
     hello world!
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: Context switching calls,  Prev: Calling external predicates,  Up: Control constructs

2.2.6 Context switching calls
-----------------------------

'control construct'

* Menu:

* (<<)/2: << /2.


File: TheLogtalkHandbook-3.101.0.info,  Node: << /2,  Up: Context switching calls

2.2.6.1 ‘(<<)/2’
................

* Menu:

* Description: Description<7>.
* Modes and number of proofs: Modes and number of proofs<7>.
* Errors: Errors<7>.
* Examples: Examples<8>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<7>,  Next: Modes and number of proofs<7>,  Up: << /2

2.2.6.2 Description
...................

     Object<<Goal
     {Proxy}<<Goal

Debugging control construct.  Calls a goal within the context of the
specified object.  The goal is called with the following execution
context:

   - *note sender: 39a, *note this: 114, and *note self: 69. values set
     to the object

   - empty meta-call context

   - empty coinduction stack

The goal may need to be written between parenthesis to avoid parsing
errors due to operator conflicts.  This control construct should only be
used for debugging or for writing unit tests.  This control construct
can only be used for objects compiled with the *note
context_switching_calls: 2da. compiler flag set to ‘allow’.  Set this
compiler flag to ‘deny’ to disable this control construct and thus
prevent using it to break encapsulation when deploying applications.

The ‘{Proxy}<<Goal’ syntax allows simplified access to *note parametric
object proxies: 3fb.  Its operational semantics is equivalent to the
goal conjunction ‘(call(Proxy), Proxy<<Goal)’.  I.e.  ‘Proxy’ is proved
within the context of the pseudo-object *note user: cf. and, if
successful, the goal term is used as a parametric object identifier.
Exceptions thrown when proving ‘Proxy’ are handled by the ‘(<<)/2’
control construct.  This syntax construct supports backtracking over the
‘{Proxy}’ goal.

Caveat: although the goal argument is fully compiled before calling,
some necessary information for the second compiler pass may not be
available at runtime.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<7>,  Next: Errors<7>,  Prev: Description<7>,  Up: << /2

2.2.6.3 Modes and number of proofs
..................................

     +object_identifier<<+callable - zero_or_more
     {+object_identifier}<<+callable - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<7>,  Next: Examples<8>,  Prev: Modes and number of proofs<7>,  Up: << /2

2.2.6.4 Errors
..............

     ‘Object’ is a variable:
          ‘instantiation_error’
     ‘Object’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Object)’
     ‘Object’ does not contain a local definition for the Goal predicate:
          ‘existence_error(procedure, Goal)’
     ‘Object’ does not exist:
          ‘existence_error(object, Object)’
     ‘Object’ was created/compiled with support for context-switching calls turned off:
          ‘permission_error(access, database, Goal)’
          
     ‘Proxy’ is a variable:
          ‘instantiation_error’
     ‘Proxy’ is neither a variable nor an object identifier:
          ‘type_error(object_identifier, Proxy)’
     The predicate ‘Proxy’ does not exist in the ‘user’ pseudo-object:
          ‘existence_error(procedure, ProxyFunctor/ProxyArity)’
          
     ‘Goal’ is a variable:
          ‘instantiation_error’
     ‘Goal’ is neither a variable nor a callable term:
          ‘type_error(callable, Goal)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<8>,  Prev: Errors<7>,  Up: << /2

2.2.6.5 Examples
................

     % call the member/2 predicate in the
     % context of the "list" object:
     test(member) :-
         list << member(1, [1]).


File: TheLogtalkHandbook-3.101.0.info,  Node: Directives<2>,  Next: Built-in predicates,  Prev: Control constructs,  Up: Reference Manual

2.3 Directives
==============

* Menu:

* Source file directives: Source file directives<2>.
* Conditional compilation directives: Conditional compilation directives<2>.
* Entity directives::
* Predicate directives: Predicate directives<2>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Source file directives<2>,  Next: Conditional compilation directives<2>,  Up: Directives<2>

2.3.1 Source file directives
----------------------------

'directive'

* Menu:

* encoding/1::
* include/1::
* initialization/1::
* op/3::
* set_logtalk_flag/2::


File: TheLogtalkHandbook-3.101.0.info,  Node: encoding/1,  Next: include/1,  Up: Source file directives<2>

2.3.1.1 ‘encoding/1’
....................

* Menu:

* Description: Description<8>.
* Template and modes::
* Examples: Examples<9>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<8>,  Next: Template and modes,  Up: encoding/1

2.3.1.2 Description
...................

     encoding(Encoding)

Declares the source file text encoding.  Requires a *note backend Prolog
compiler: 34. supporting the chosen encoding.  When used, this directive
must be the first term in the source file in the first line.  This
directive is also supported in files included in a main file or in a
dynamically created entity using *note include/1: b8. directives.

The encoding used in a source file (and, in the case of a Unicode
encoding, any BOM present) will be used for the intermediate Prolog file
generated by the compiler.  Logtalk uses the encoding names specified by
IANA(1). In those cases where a preferred MIME name alias is specified,
the alias is used instead.  Examples includes ‘'US-ASCII'’,
‘'ISO-8859-1'’, ‘'ISO-8859-2'’, ‘'ISO-8859-15'’, ‘'UCS-2'’, ‘'UCS-2LE'’,
‘'UCS-2BE'’, ‘'UTF-8'’, ‘'UTF-16'’, ‘'UTF-16LE'’, ‘'UTF-16BE'’,
‘'UTF-32'’, ‘'UTF-32LE'’, ‘'UTF-32BE'’, ‘'Shift_JIS'’, and ‘'EUC-JP'’.
When writing portable code that cannot be expressed using ASCII,
‘'UTF-8'’ is the most commonly supported Unicode encoding.

The backend Prolog compiler adapter files define a table that translates
between the Logtalk and Prolog specific atoms that represent each
supported encoding.  The *note encoding_directive: 299. read-only flag
can be used to find if a backend supports this directive and how.

   ---------- Footnotes ----------

   (1) 
http://www.iana.org/assignments/character-sets/character-sets.xhtml


File: TheLogtalkHandbook-3.101.0.info,  Node: Template and modes,  Next: Examples<9>,  Prev: Description<8>,  Up: encoding/1

2.3.1.3 Template and modes
..........................

     encoding(+atom)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<9>,  Prev: Template and modes,  Up: encoding/1

2.3.1.4 Examples
................

     :- encoding('UTF-8').

'directive'


File: TheLogtalkHandbook-3.101.0.info,  Node: include/1,  Next: initialization/1,  Prev: encoding/1,  Up: Source file directives<2>

2.3.1.5 ‘include/1’
...................

* Menu:

* Description: Description<9>.
* Template and modes: Template and modes<2>.
* Examples: Examples<10>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<9>,  Next: Template and modes<2>,  Up: include/1

2.3.1.6 Description
...................

     include(File)

Includes a file contents, which must be valid terms, at the place of
occurrence of the directive.  The file can be specified as a relative
path, an absolute path, or using *note library notation: 2a8. and is
expanded as a source file name.  Relative paths are interpreted as
relative to the path of the file containing the directive.  The file
extension is optional (the recognized Logtalk and Prolog file extensions
are defined in the *note backend adapter files: 154.).

When using the *note reflection API: 48, predicates from an included
file can be distinguished from predicates from the main file by looking
for the ‘include/1’ predicate declaration property or the ‘include/1’
predicate definition property.  For the included predicates, the
‘line_count/1’ property stores the term line number in the included
file.

This directive can be used as either a source file directive or an
entity directive.  As an entity directive, it can be used both in
entities defined in source files and with the entity creation built-in
predicates.  In the latter case, the file should be specified using an
absolute path or using library notation (which expands to a full path)
to avoid a fragile dependency on the current working directory.

Included files may contain an *note encoding/1: 298. directive, which
may specify the same encoding of the main file or a different encoding.

     Warning: The use of nested included files (i.e., included files
     including other files) is only partially supported.  Notably, the
     reflection API currently only keeps track of the included files
     dependency on the main file.  Although this allows predicates such
     as ‘logtalk_make/0-1’ to work correctly, it prevents full code
     navigation features in supported IDEs for predicates defined in the
     nested included files.

     When using this directive as an argument in calls to the *note
     create_object/4: 62, *note create_category/4: 11a, and *note
     create_protocol/3: e3. built-in predicates, the objects,
     categories, and protocols will not be recreated or redefined when
     the included file(s) are modified and the *note logtalk_make/0:
     29f. predicate or the *note logtalk_make/1: 2a0. (with target
     ‘all’) predicates are called.


File: TheLogtalkHandbook-3.101.0.info,  Node: Template and modes<2>,  Next: Examples<10>,  Prev: Description<9>,  Up: include/1

2.3.1.7 Template and modes
..........................

     include(@source_file_name)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<10>,  Prev: Template and modes<2>,  Up: include/1

2.3.1.8 Examples
................

     % include the "raw_1.txt" text file found
     % on the "data" library directory:
     :- include(data('raw_1.txt')).

     % include a "factbase.pl" file in the same directory
     % of the source file containing the directive:
     :- include('factbase.pl').

     % include a file given its absolute path:
     :- include('/home/me/databases/countries.pl').

     % create a wrapper object for a Prolog file using
     % library notation to define the file path:
     | ?- create_object(cities, [], [public(city/4), include(geo('cities.pl'))], []).

'directive'


File: TheLogtalkHandbook-3.101.0.info,  Node: initialization/1,  Next: op/3,  Prev: include/1,  Up: Source file directives<2>

2.3.1.9 ‘initialization/1’
..........................

* Menu:

* Description: Description<10>.
* Template and modes: Template and modes<3>.
* Examples: Examples<11>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<10>,  Next: Template and modes<3>,  Up: initialization/1

2.3.1.10 Description
....................

     initialization(Goal)

When used within an object, this directive defines a goal to be called
after the object has been successfully loaded into memory.  When used at
a global level within a source file, this directive defines a goal to be
called after the source file is successfully compiled and loaded into
memory.

The loading context can be accessed from this directive by calling the
*note logtalk_load_context/2: 318. predicate.  Note that the usable
loading context keys depend on the directive scope (file or object).

Multiple initialization directives can be used in a source file or in an
object.  Their goals will be called in the same order as the directives
at loading time.

     Note: Arbitrary goals cannot be used as directives in source files.
     Any goal that should be automatically called when a source file is
     loaded must be wrapped using this directive.

     Categories and protocols cannot contain ‘initialization/1’
     directives as the initialization goals would lack a complete *note
     execution context: 35f. that is only available for objects.

Although technically a global ‘initialization/1’ directive in a source
file is a Prolog directive, calls to Logtalk built-in predicates from it
are usually compiled to improve portability, improve performance, and
provide better support for embedded applications.

     Warning: Some backend Prolog compilers declare the atom
     ‘initialization’ as an operator for a lighter syntax.  But this
     makes the code non-portable and is therefore a practice best
     avoided.


File: TheLogtalkHandbook-3.101.0.info,  Node: Template and modes<3>,  Next: Examples<11>,  Prev: Description<10>,  Up: initialization/1

2.3.1.11 Template and modes
...........................

     initialization(@callable)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<11>,  Prev: Template and modes<3>,  Up: initialization/1

2.3.1.12 Examples
.................

     % call the init/0 predicate after loading the
     % source file containing the directive

     :- initialization(init).

     % print a debug message after loading a
     % source file defining an object

     :- object(log).

         :- initialization(start_date).

         start_date :-
             os::date_time(Year, Month, Day, _, _, _, _),
             logtalk::print_message(debug, my_app, 'Starting date: ~d-~d-~d~n'+[Year,Month,Day]).

     :- end_object.

See also
........

*note logtalk_load_context/2: 318.

'directive'


File: TheLogtalkHandbook-3.101.0.info,  Node: op/3,  Next: set_logtalk_flag/2,  Prev: initialization/1,  Up: Source file directives<2>

2.3.1.13 ‘op/3’
...............

* Menu:

* Description: Description<11>.
* Template and modes: Template and modes<4>.
* Examples: Examples<12>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<11>,  Next: Template and modes<4>,  Up: op/3

2.3.1.14 Description
....................

     op(Precedence, Associativity, Operator)
     op(Precedence, Associativity, [Operator, ...])

Declares operators.  Global operators can be declared inside a source
file by writing the respective directives before the entity opening
directives.  Operators declared inside entities have local scope.  Calls
to the standard term input and output predicates take into account any
locally defined operators.


File: TheLogtalkHandbook-3.101.0.info,  Node: Template and modes<4>,  Next: Examples<12>,  Prev: Description<11>,  Up: op/3

2.3.1.15 Template and modes
...........................

     op(+integer, +associativity, +atom_or_atom_list)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<12>,  Prev: Template and modes<4>,  Up: op/3

2.3.1.16 Examples
.................

Some of the predicate argument instantiation mode operators used by
Logtalk:

     :- op(200, fy, +).
     :- op(200, fy, ?).
     :- op(200, fy, @).
     :- op(200, fy, -).

An example of using entity local operators.  Consider the following
‘ops.lgt’ file:

     :- initialization((write(<=>(1,2)), nl)).

     :- object(ops).

         :- op(700, xfx, <=>).

         :- public(w/1).
         w(Term) :-
             write(Term), nl.

         :- public(r/1).
         r(Term) :-
             read(Term).

     :- end_object.

Loading the file automatically calls the initialization goal.  Compare
its output with the output of the ‘ops::w/1’ predicate.  Compare also
reading a term from within the ‘ops’ object versus reading from ‘user’.

     | ?- {ops}.
     <=>(1,2)
     true.

     | ?- ops::w(<=>(1,2)).
     1<=>2
     true.

     | ?- ops::r(T).
     |: 3<=>4.

     T = <=>(3, 4).

     | ?- read(T).
     |: 5<=>6.

     SYNTAX ERROR: operator expected

See also
........

*note current_op/3: 15e.

'directive'


File: TheLogtalkHandbook-3.101.0.info,  Node: set_logtalk_flag/2,  Prev: op/3,  Up: Source file directives<2>

2.3.1.17 ‘set_logtalk_flag/2’
.............................

* Menu:

* Description: Description<12>.
* Template and modes: Template and modes<5>.
* Errors: Errors<8>.
* Examples: Examples<13>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<12>,  Next: Template and modes<5>,  Up: set_logtalk_flag/2

2.3.1.18 Description
....................

     set_logtalk_flag(Flag, Value)

Sets local flag values.  The scope of this directive is the entity or
the source file containing it.  For global scope, use the corresponding
*note set_logtalk_flag/2: 51. built-in predicate called from an *note
initialization/1: 42. directive.  For a description of the predefined
compiler flags, consult the *note Compiler flags: 251. section in the
User Manual.  The directive affects the compilation of all terms that
follow it within the scope of the directive.


File: TheLogtalkHandbook-3.101.0.info,  Node: Template and modes<5>,  Next: Errors<8>,  Prev: Description<12>,  Up: set_logtalk_flag/2

2.3.1.19 Template and modes
...........................

     set_logtalk_flag(+atom, +nonvar)


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<8>,  Next: Examples<13>,  Prev: Template and modes<5>,  Up: set_logtalk_flag/2

2.3.1.20 Errors
...............

     Flag is a variable:
          ‘instantiation_error’
     Value is a variable:
          ‘instantiation_error’
     Flag is not an atom:
          ‘type_error(atom, Flag)’
     Flag is neither a variable nor a valid flag:
          ‘domain_error(flag, Flag)’
     Value is not a valid value for flag Flag:
          ‘domain_error(flag_value, Flag + Value)’
     Flag is a read-only flag:
          ‘permission_error(modify, flag, Flag)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<13>,  Prev: Errors<8>,  Up: set_logtalk_flag/2

2.3.1.21 Examples
.................

     % turn off the compiler unknown entity warnings
     % during the compilation of this source file:
     :- set_logtalk_flag(unknown_entities, silent).


     :- object(...).

         % generate events for messages sent from this object:
         :- set_logtalk_flag(events, allow).
         ...

         % turn off suspicious call lint checks for the next predicate:
         :- set_logtalk_flag(suspicious_calls, silent).
         foo :-
             ...
         :- set_logtalk_flag(suspicious_calls, warning).
         ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Conditional compilation directives<2>,  Next: Entity directives,  Prev: Source file directives<2>,  Up: Directives<2>

2.3.2 Conditional compilation directives
----------------------------------------

'directive'

* Menu:

* if/1::
* elif/1::
* else/0::
* endif/0::


File: TheLogtalkHandbook-3.101.0.info,  Node: if/1,  Next: elif/1,  Up: Conditional compilation directives<2>

2.3.2.1 ‘if/1’
..............

* Menu:

* Description: Description<13>.
* Template and modes: Template and modes<6>.
* Examples: Examples<14>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<13>,  Next: Template and modes<6>,  Up: if/1

2.3.2.2 Description
...................

     if(Goal)

Starts an 'if-then' branch when performing conditional compilation.  The
code following the directive is compiled iff ‘Goal’ is true.  If ‘Goal’
throws an error instead of either succeeding or failing, the error is
reported by the compiler and compilation of the enclosing source file or
entity is aborted.  The goal is *note expanded: cb. when the directive
occurs in a source file.  Conditional compilation directives can be
nested.

     Warning: Conditional compilation goals 'cannot' depend on predicate
     definitions contained in the same source file that contains the
     conditional compilation directives (as those predicates only become
     available after the file is successfully compiled and loaded).

     Conditional compilation directives are currently not supported in
     included files when the conditional code includes ‘op/3’ directives
     or ‘uses/2’/‘use_module/2’ directives with ‘op/3’ arguments.


File: TheLogtalkHandbook-3.101.0.info,  Node: Template and modes<6>,  Next: Examples<14>,  Prev: Description<13>,  Up: if/1

2.3.2.3 Template and modes
..........................

     if(@callable)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<14>,  Prev: Template and modes<6>,  Up: if/1

2.3.2.4 Examples
................

A common example is checking if a built-in predicate exists and
providing a definition when the predicate is absent:

     :- if(\+ predicate_property(length(_,_), built_in)).

         length(List, Length) :-
             ...

     :- endif.

Another common example is conditionally including code for a specific
backend Prolog compiler:

     :- if(current_logtalk_flag(prolog_dialect, swi)).

         % SWI-Prolog specific code
         :- set_prolog_flag(double_quotes, codes).

     :- endif.

If necessary, test goal errors can be converted into failures using the
standard ‘catch/3’ control construct.  For example:

     :- if(catch(\+ log(7,_), _, fail)).

        % define the legacy log/2 predicate
        log(X, Y) :- Y is log(X).

     :- endif.

See also
........

*note elif/1: 2f4, *note else/0: 2f5, *note endif/0: 2f6.

'directive'


File: TheLogtalkHandbook-3.101.0.info,  Node: elif/1,  Next: else/0,  Prev: if/1,  Up: Conditional compilation directives<2>

2.3.2.5 ‘elif/1’
................

* Menu:

* Description: Description<14>.
* Template and modes: Template and modes<7>.
* Examples: Examples<15>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<14>,  Next: Template and modes<7>,  Up: elif/1

2.3.2.6 Description
...................

     elif(Goal)

Supports embedded conditionals when performing conditional compilation.
The code following the directive is compiled iff ‘Goal’ is true.  If
‘Goal’ throws an error instead of either succeeding or failing, the
error is reported by the compiler and compilation of the enclosing
source file or entity is aborted.  The goal is *note expanded: cb. when
the directive occurs in a source file.

     Warning: Conditional compilation goals 'cannot' depend on predicate
     definitions contained in the same source file that contains the
     conditional compilation directives (as those predicates only become
     available after the file is successfully compiled and loaded).

     Conditional compilation directives are currently not supported in
     included files when the conditional code includes ‘op/3’ directives
     or ‘uses/2’/‘use_module/2’ directives with ‘op/3’ arguments.


File: TheLogtalkHandbook-3.101.0.info,  Node: Template and modes<7>,  Next: Examples<15>,  Prev: Description<14>,  Up: elif/1

2.3.2.7 Template and modes
..........................

     elif(@callable)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<15>,  Prev: Template and modes<7>,  Up: elif/1

2.3.2.8 Examples
................

     :- if(current_prolog_flag(double_quotes, codes)).

         ...

     :- elif(current_prolog_flag(double_quotes, chars)).

         ...

     :- elif(current_prolog_flag(double_quotes, atom)).

         ...

     :- endif.

See also
........

*note else/0: 2f5, *note endif/0: 2f6, *note if/1: 2f3.

'directive'


File: TheLogtalkHandbook-3.101.0.info,  Node: else/0,  Next: endif/0,  Prev: elif/1,  Up: Conditional compilation directives<2>

2.3.2.9 ‘else/0’
................

* Menu:

* Description: Description<15>.
* Template and modes: Template and modes<8>.
* Examples: Examples<16>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<15>,  Next: Template and modes<8>,  Up: else/0

2.3.2.10 Description
....................

     else

Starts an 'else' branch when performing conditional compilation.  The
code following this directive is compiled iff the goal in the matching
*note if/1: 2f3. or *note elif/1: 2f4. directive is false.


File: TheLogtalkHandbook-3.101.0.info,  Node: Template and modes<8>,  Next: Examples<16>,  Prev: Description<15>,  Up: else/0

2.3.2.11 Template and modes
...........................

     else


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<16>,  Prev: Template and modes<8>,  Up: else/0

2.3.2.12 Examples
.................

An example where a hypothetical application would have some limitations
that the user should be made aware of when running on a backend Prolog
compiler with bounded arithmetic:

     :- if(current_prolog_flag(bounded, true)).

         :- initialization(
             logtalk::print_message(warning,app,bounded_arithmetic)
         ).

     :- else.

         :- initialization(
             logtalk::print_message(comment,app,unbounded_arithmetic)
         ).

     :- endif.

See also
........

*note elif/1: 2f4, *note endif/0: 2f6, *note if/1: 2f3.

'directive'


File: TheLogtalkHandbook-3.101.0.info,  Node: endif/0,  Prev: else/0,  Up: Conditional compilation directives<2>

2.3.2.13 ‘endif/0’
..................

* Menu:

* Description: Description<16>.
* Template and modes: Template and modes<9>.
* Examples: Examples<17>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<16>,  Next: Template and modes<9>,  Up: endif/0

2.3.2.14 Description
....................

     endif

Ends conditional compilation for the matching *note if/1: 2f3.
directive.


File: TheLogtalkHandbook-3.101.0.info,  Node: Template and modes<9>,  Next: Examples<17>,  Prev: Description<16>,  Up: endif/0

2.3.2.15 Template and modes
...........................

     endif


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<17>,  Prev: Template and modes<9>,  Up: endif/0

2.3.2.16 Examples
.................

     :- if(date::today(_,5,25)).

         :- initialization(write('Happy Towel Day!\n')).

     :- endif.

See also
........

*note elif/1: 2f4, *note else/0: 2f5, *note if/1: 2f3.


File: TheLogtalkHandbook-3.101.0.info,  Node: Entity directives,  Next: Predicate directives<2>,  Prev: Conditional compilation directives<2>,  Up: Directives<2>

2.3.3 Entity directives
-----------------------

'directive'

* Menu:

* built_in/0::
* category/1-4::
* dynamic/0::
* end_category/0::
* end_object/0::
* end_protocol/0::
* info/1::
* object/1-5::
* protocol/1-2::
* threaded/0::
* uses/1::
* use_module/1::


File: TheLogtalkHandbook-3.101.0.info,  Node: built_in/0,  Next: category/1-4,  Up: Entity directives

2.3.3.1 ‘built_in/0’
....................

* Menu:

* Description: Description<17>.
* Template and modes: Template and modes<10>.
* Examples: Examples<18>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<17>,  Next: Template and modes<10>,  Up: built_in/0

2.3.3.2 Description
...................

     built_in

Declares an entity as built-in.  Built-in entities must be static and
cannot be redefined once loaded.  This directive is used in the
pre-defined protocols, categories, and objects that are automatically
loaded at startup.


File: TheLogtalkHandbook-3.101.0.info,  Node: Template and modes<10>,  Next: Examples<18>,  Prev: Description<17>,  Up: built_in/0

2.3.3.3 Template and modes
..........................

     built_in


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<18>,  Prev: Template and modes<10>,  Up: built_in/0

2.3.3.4 Examples
................

     :- built_in.

'directive'


File: TheLogtalkHandbook-3.101.0.info,  Node: category/1-4,  Next: dynamic/0,  Prev: built_in/0,  Up: Entity directives

2.3.3.5 ‘category/1-4’
......................

* Menu:

* Description: Description<18>.
* Template and modes: Template and modes<11>.
* Examples: Examples<19>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<18>,  Next: Template and modes<11>,  Up: category/1-4

2.3.3.6 Description
...................

     category(Category)

     category(Category,
         implements(Protocols))

     category(Category,
         extends(Categories))

     category(Category,
         complements(Objects))

     category(Category,
         implements(Protocols),
         extends(Categories))

     category(Category,
         implements(Protocols),
         complements(Objects))

     category(Category,
         extends(Categories),
         complements(Objects))

     category(Category,
         implements(Protocols),
         extends(Categories),
         complements(Objects))

Starting category directive.


File: TheLogtalkHandbook-3.101.0.info,  Node: Template and modes<11>,  Next: Examples<19>,  Prev: Description<18>,  Up: category/1-4

2.3.3.7 Template and modes
..........................

     category(+category_identifier)

     category(+category_identifier,
         implements(+implemented_protocols))

     category(+category_identifier,
         extends(+extended_categories))

     category(+category_identifier,
         complements(+complemented_objects))

     category(+category_identifier,
         implements(+implemented_protocols),
         extends(+extended_categories))

     category(+category_identifier,
         implements(+implemented_protocols),
         complements(+complemented_objects))

     category(+category_identifier,
         extends(+extended_categories),
         complements(+complemented_objects))

     category(+category_identifier,
         implements(+implemented_protocols),
         extends(+extended_categories),
         complements(+complemented_objects))


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<19>,  Prev: Template and modes<11>,  Up: category/1-4

2.3.3.8 Examples
................

     :- category(monitoring).

     :- category(monitoring,
         implements(monitoringp)).

     :- category(attributes,
         implements(protected::variables)).

     :- category(extended,
         extends(minimal)).

     :- category(logging,
         implements(monitoring),
         complements(employee)).

See also
........

*note end_category/0: 10f.

'directive'


File: TheLogtalkHandbook-3.101.0.info,  Node: dynamic/0,  Next: end_category/0,  Prev: category/1-4,  Up: Entity directives

2.3.3.9 ‘dynamic/0’
...................

* Menu:

* Description: Description<19>.
* Template and modes: Template and modes<12>.
* Examples: Examples<20>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<19>,  Next: Template and modes<12>,  Up: dynamic/0

2.3.3.10 Description
....................

     dynamic

Declares an entity and its contents as dynamic.  Dynamic entities can be
abolished at runtime.

As entities created at runtime (using the *note create_object/4: 62,
*note create_protocol/3: e3, and *note create_category/4: 11a. built-in
predicates) are always dynamic, this directive is only necessary in the
rare cases where we want to define dynamic entities in source files.

     Warning: Some backend Prolog compilers declare the atom ‘dynamic’
     as an operator for a lighter syntax, forcing writing this atom
     between parenthesis when using this directive.


File: TheLogtalkHandbook-3.101.0.info,  Node: Template and modes<12>,  Next: Examples<20>,  Prev: Description<19>,  Up: dynamic/0

2.3.3.11 Template and modes
...........................

     dynamic


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<20>,  Prev: Template and modes<12>,  Up: dynamic/0

2.3.3.12 Examples
.................

     :- dynamic.

See also
........

*note dynamic/1: 15a, *note object_property/2: c6, *note
protocol_property/2: f4, *note category_property/2: 12c.

'directive'


File: TheLogtalkHandbook-3.101.0.info,  Node: end_category/0,  Next: end_object/0,  Prev: dynamic/0,  Up: Entity directives

2.3.3.13 ‘end_category/0’
.........................

* Menu:

* Description: Description<20>.
* Template and modes: Template and modes<13>.
* Examples: Examples<21>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<20>,  Next: Template and modes<13>,  Up: end_category/0

2.3.3.14 Description
....................

     end_category

Ending category directive.


File: TheLogtalkHandbook-3.101.0.info,  Node: Template and modes<13>,  Next: Examples<21>,  Prev: Description<20>,  Up: end_category/0

2.3.3.15 Template and modes
...........................

     end_category


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<21>,  Prev: Template and modes<13>,  Up: end_category/0

2.3.3.16 Examples
.................

     :- end_category.

See also
........

*note category/1-4: 10e.

'directive'


File: TheLogtalkHandbook-3.101.0.info,  Node: end_object/0,  Next: end_protocol/0,  Prev: end_category/0,  Up: Entity directives

2.3.3.17 ‘end_object/0’
.......................

* Menu:

* Description: Description<21>.
* Template and modes: Template and modes<14>.
* Examples: Examples<22>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<21>,  Next: Template and modes<14>,  Up: end_object/0

2.3.3.18 Description
....................

     end_object

Ending object directive.


File: TheLogtalkHandbook-3.101.0.info,  Node: Template and modes<14>,  Next: Examples<22>,  Prev: Description<21>,  Up: end_object/0

2.3.3.19 Template and modes
...........................

     end_object


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<22>,  Prev: Template and modes<14>,  Up: end_object/0

2.3.3.20 Examples
.................

     :- end_object.

See also
........

*note object/1-5: 9a.

'directive'


File: TheLogtalkHandbook-3.101.0.info,  Node: end_protocol/0,  Next: info/1,  Prev: end_object/0,  Up: Entity directives

2.3.3.21 ‘end_protocol/0’
.........................

* Menu:

* Description: Description<22>.
* Template and modes: Template and modes<15>.
* Examples: Examples<23>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<22>,  Next: Template and modes<15>,  Up: end_protocol/0

2.3.3.22 Description
....................

     end_protocol

Ending protocol directive.


File: TheLogtalkHandbook-3.101.0.info,  Node: Template and modes<15>,  Next: Examples<23>,  Prev: Description<22>,  Up: end_protocol/0

2.3.3.23 Template and modes
...........................

     end_protocol


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<23>,  Prev: Template and modes<15>,  Up: end_protocol/0

2.3.3.24 Examples
.................

     :- end_protocol.

See also
........

*note protocol/1-2: dc.

'directive'


File: TheLogtalkHandbook-3.101.0.info,  Node: info/1,  Next: object/1-5,  Prev: end_protocol/0,  Up: Entity directives

2.3.3.25 ‘info/1’
.................

* Menu:

* Description: Description<23>.
* Template and modes: Template and modes<16>.
* Examples: Examples<24>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<23>,  Next: Template and modes<16>,  Up: info/1

2.3.3.26 Description
....................

     info([Key is Value, ...])

Documentation directive for objects, protocols, and categories.  The
directive argument is a list of pairs using the format 'Key is Value'.
See the *note Entity documenting directives: 324. section for a
description of the default keys.


File: TheLogtalkHandbook-3.101.0.info,  Node: Template and modes<16>,  Next: Examples<24>,  Prev: Description<23>,  Up: info/1

2.3.3.27 Template and modes
...........................

     info(+entity_info_list)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<24>,  Prev: Template and modes<16>,  Up: info/1

2.3.3.28 Examples
.................

     :- info([
         version is 1:0:0,
         author is 'Paulo Moura',
         date is 2000-11-20,
         comment is 'List protocol.'
     ]).

See also
........

*note info/2: 168, *note object_property/2: c6, *note
protocol_property/2: f4, *note category_property/2: 12c.

'directive'


File: TheLogtalkHandbook-3.101.0.info,  Node: object/1-5,  Next: protocol/1-2,  Prev: info/1,  Up: Entity directives

2.3.3.29 ‘object/1-5’
.....................

* Menu:

* Description: Description<24>.
* Template and modes: Template and modes<17>.
* Examples: Examples<25>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<24>,  Next: Template and modes<17>,  Up: object/1-5

2.3.3.30 Description
....................

'Stand-alone objects (prototypes)'

     object(Object)

     object(Object,
         implements(Protocols))

     object(Object,
         imports(Categories))

     object(Object,
         implements(Protocols),
         imports(Categories))

'Prototype extensions'

     object(Object,
         extends(Objects))

     object(Object,
         implements(Protocols),
         extends(Objects))

     object(Object,
         imports(Categories),
         extends(Objects))

     object(Object,
         implements(Protocols),
         imports(Categories),
         extends(Objects))

'Class instances'

     object(Object,
         instantiates(Classes))

     object(Object,
         implements(Protocols),
         instantiates(Classes))

     object(Object,
         imports(Categories),
         instantiates(Classes))

     object(Object,
         implements(Protocols),
         imports(Categories),
         instantiates(Classes))

'Classes'

     object(Object,
         specializes(Classes))

     object(Object,
         implements(Protocols),
         specializes(Classes))

     object(Object,
         imports(Categories),
         specializes(Classes))

     object(Object,
         implements(Protocols),
         imports(Categories),
         specializes(Classes))

'Classes with metaclasses'

     object(Object,
         instantiates(Classes),
         specializes(Classes))

     object(Object,
         implements(Protocols),
         instantiates(Classes),
         specializes(Classes))

     object(Object,
         imports(Categories),
         instantiates(Classes),
         specializes(Classes))

     object(Object,
         implements(Protocols),
         imports(Categories),
         instantiates(Classes),
         specializes(Classes))

Starting object directive.


File: TheLogtalkHandbook-3.101.0.info,  Node: Template and modes<17>,  Next: Examples<25>,  Prev: Description<24>,  Up: object/1-5

2.3.3.31 Template and modes
...........................

'Stand-alone objects (prototypes)'

     object(+object_identifier)

     object(+object_identifier,
         implements(+implemented_protocols))

     object(+object_identifier,
         imports(+imported_categories))

     object(+object_identifier,
         implements(+implemented_protocols),
         imports(+imported_categories))

'Prototype extensions'

     object(+object_identifier,
         extends(+extended_objects))

     object(+object_identifier,
         implements(+implemented_protocols),
         extends(+extended_objects))

     object(+object_identifier,
         imports(+imported_categories),
         extends(+extended_objects))

     object(+object_identifier,
         implements(+implemented_protocols),
         imports(+imported_categories),
         extends(+extended_objects))

'Class instances'

     object(+object_identifier,
         instantiates(+instantiated_objects))

     object(+object_identifier,
         implements(+implemented_protocols),
         instantiates(+instantiated_objects))

     object(+object_identifier,
         imports(+imported_categories),
         instantiates(+instantiated_objects))

     object(+object_identifier,
         implements(+implemented_protocols),
         imports(+imported_categories),
         instantiates(+instantiated_objects))

'Classes'

     object(+object_identifier,
         specializes(+specialized_objects))

     object(+object_identifier,
         implements(+implemented_protocols),
         specializes(+specialized_objects))

     object(+object_identifier,
         imports(+imported_categories),
         specializes(+specialized_objects))

     object(+object_identifier,
         implements(+implemented_protocols),
         imports(+imported_categories),
         specializes(+specialized_objects))

'Class with metaclasses'

     object(+object_identifier,
         instantiates(+instantiated_objects),
         specializes(+specialized_objects))

     object(+object_identifier,
         implements(+implemented_protocols),
         instantiates(+instantiated_objects),
         specializes(+specialized_objects))

     object(+object_identifier,
         imports(+imported_categories),
         instantiates(+instantiated_objects),
         specializes(+specialized_objects))

     object(+object_identifier,
         implements(+implemented_protocols),
         imports(+imported_categories),
         instantiates(+instantiated_objects),
         specializes(+specialized_objects))


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<25>,  Prev: Template and modes<17>,  Up: object/1-5

2.3.3.32 Examples
.................

     :- object(list).

     :- object(list,
         implements(listp)).

     :- object(list,
         extends(compound)).

     :- object(list,
         implements(listp),
         extends(compound)).

     :- object(object,
         imports(initialization),
         instantiates(class)).

     :- object(abstract_class,
         instantiates(class),
         specializes(object)).

     :- object(agent,
         imports(private::attributes)).

See also
........

*note end_object/0: 9b.

'directive'


File: TheLogtalkHandbook-3.101.0.info,  Node: protocol/1-2,  Next: threaded/0,  Prev: object/1-5,  Up: Entity directives

2.3.3.33 ‘protocol/1-2’
.......................

* Menu:

* Description: Description<25>.
* Template and modes: Template and modes<18>.
* Examples: Examples<26>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<25>,  Next: Template and modes<18>,  Up: protocol/1-2

2.3.3.34 Description
....................

     protocol(Protocol)

     protocol(Protocol,
         extends(Protocols))

Starting protocol directive.


File: TheLogtalkHandbook-3.101.0.info,  Node: Template and modes<18>,  Next: Examples<26>,  Prev: Description<25>,  Up: protocol/1-2

2.3.3.35 Template and modes
...........................

     protocol(+protocol_identifier)

     protocol(+protocol_identifier,
         extends(+extended_protocols))


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<26>,  Prev: Template and modes<18>,  Up: protocol/1-2

2.3.3.36 Examples
.................

     :- protocol(listp).

     :- protocol(listp,
         extends(compoundp)).

     :- protocol(queuep,
         extends(protected::listp)).

See also
........

*note end_protocol/0: dd.

'directive'


File: TheLogtalkHandbook-3.101.0.info,  Node: threaded/0,  Next: uses/1,  Prev: protocol/1-2,  Up: Entity directives

2.3.3.37 ‘threaded/0’
.....................

* Menu:

* Description: Description<26>.
* Template and modes: Template and modes<19>.
* Examples: Examples<27>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<26>,  Next: Template and modes<19>,  Up: threaded/0

2.3.3.38 Description
....................

     threaded

Declares that an object supports threaded engines, concurrent calls, and
asynchronous messages.  Any object containing calls to the built-in
multi-threading predicates (or importing a category that contains such
calls) must include this directive.

This directive results in the automatic creation and set up of an object
message queue when the object is loaded or created at runtime.  Object
message queues are used for exchanging thread notifications and for
storing concurrent goal solutions and replies to the multi-threading
calls made within the object.  The message queue for the *note user: cf.
pseudo-object is automatically created at Logtalk startup (provided that
multi-threading programming is supported and enabled for the chosen
*note backend Prolog compiler: 34.).

     Note: This directive requires a *note backend Prolog compiler: 34.
     providing compatible multi-threading primitives.  The value of the
     read-only *note threads: 225. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.101.0.info,  Node: Template and modes<19>,  Next: Examples<27>,  Prev: Description<26>,  Up: threaded/0

2.3.3.39 Template and modes
...........................

     threaded


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<27>,  Prev: Template and modes<19>,  Up: threaded/0

2.3.3.40 Examples
.................

     :- threaded.

See also
........

*note synchronized/1: 74, *note object_property/2: c6.

'directive'


File: TheLogtalkHandbook-3.101.0.info,  Node: uses/1,  Next: use_module/1,  Prev: threaded/0,  Up: Entity directives

2.3.3.41 ‘uses/1’
.................

* Menu:

* Description: Description<27>.
* Template and modes: Template and modes<20>.
* Examples: Examples<28>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<27>,  Next: Template and modes<20>,  Up: uses/1

2.3.3.42 Description
....................

     uses([Object as Alias, ...])

Declares object aliases.  Typically used to shorten long object names,
to simplify and consistently send messages to parameterized objects, and
to simplify using or experimenting with different object implementations
of the same protocol when using explicit message-sending.  Object
aliases are local to the object (or category) where they are defined.

The objects being aliased can be *note parameter variables: a1. or
parametric objects where one or more parameters are parameter variables
when using the directive in a parametric object or a parametric category
defined in a source file (the common case).

Declaring multiple aliases for the same object is allowed.  But repeated
declarations of the same alias, declaring an alias for an object alias,
and redefining an alias to reference a different object are reported as
compilation errors.

To enable the use of *note static binding: 35, and thus optimal
message-sending performance, the objects should be loaded before
compiling the entities that call their predicates.


File: TheLogtalkHandbook-3.101.0.info,  Node: Template and modes<20>,  Next: Examples<28>,  Prev: Description<27>,  Up: uses/1

2.3.3.43 Template and modes
...........................

     uses(+object_alias_list)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<28>,  Prev: Template and modes<20>,  Up: uses/1

2.3.3.44 Examples
.................

     :- object(foo(_HeapType_, _OptionsObject_)).

         :- uses([
             fast_random as rnd,
             time(utc) as time,
             heap(_HeapType_) as heap,
             _OptionsObject_ as options
         ]).

         bar :-
             ...,
             % the same as fast_random::permutation(L, P)
             rnd::permutation(L, P),
             % the same as heap(_HeapType_)::as_heap(L, H)
             heap::as_heap(L, H),
             % the same as _OptionsObject_::get(foo, X)
             options::get(foo, X),
             % the same as time(utc)::now(T)
             time::now(T),
             ...

See also
........

*note uses/2: 4b, *note use_module/1: 4c, *note use_module/2: 4d.

'directive'


File: TheLogtalkHandbook-3.101.0.info,  Node: use_module/1,  Prev: uses/1,  Up: Entity directives

2.3.3.45 ‘use_module/1’
.......................

* Menu:

* Description: Description<28>.
* Template and modes: Template and modes<21>.
* Examples: Examples<29>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<28>,  Next: Template and modes<21>,  Up: use_module/1

2.3.3.46 Description
....................

     use_module([Module as Alias, ...])

Declares module aliases.  Typically used to shorten long module names
and to simplify using or experimenting with different module
implementations of the same predicates when using explicitly-qualified
calls.  Module aliases are local to the object (or category) where they
are defined.

The modules being aliased can be *note parameter variables: a1. when
using the directive in a parametric object or a parametric category
defined in a source file (the common case).

Declaring multiple aliases for the same module is allowed.  But repeated
declarations of the same alias, declaring an alias for a module alias,
and redefining an alias to reference a different module are reported as
compilation errors.

To enable the use of *note static binding: 35, and thus optimal
predicate call performance, the modules should be loaded before
compiling the entities that call their predicates.

Note that this directive semantics differs from the directive with the
same name found on some Prolog implementations where it is used to load
a module and import all its exported predicates.


File: TheLogtalkHandbook-3.101.0.info,  Node: Template and modes<21>,  Next: Examples<29>,  Prev: Description<28>,  Up: use_module/1

2.3.3.47 Template and modes
...........................

     use_module(+module_alias_list)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<29>,  Prev: Template and modes<21>,  Up: use_module/1

2.3.3.48 Examples
.................

     :- object(foo(_DataModule_)).

         :- use_module([
             data_noise_handler as cleaner,
             _DataModule_ as data
         ]).

         bar :-
             ...,
             % the same as _DataModule_:xy(X, Y)
             data:xy(X, Y),
             % the same as data_noise_handler:filter(X, Y)
             cleaner:filter(X, Y, Z),
             ...

See also
........

*note uses/1: 4a, *note uses/2: 4b, *note use_module/2: 4d.


File: TheLogtalkHandbook-3.101.0.info,  Node: Predicate directives<2>,  Prev: Entity directives,  Up: Directives<2>

2.3.4 Predicate directives
--------------------------

'directive'

* Menu:

* alias/2::
* coinductive/1::
* discontiguous/1::
* dynamic/1::
* info/2::
* meta_predicate/1::
* meta_non_terminal/1::
* mode/2::
* mode_non_terminal/2::
* multifile/1::
* private/1::
* protected/1::
* public/1::
* synchronized/1::
* uses/2::
* use_module/2::


File: TheLogtalkHandbook-3.101.0.info,  Node: alias/2,  Next: coinductive/1,  Up: Predicate directives<2>

2.3.4.1 ‘alias/2’
.................

* Menu:

* Description: Description<29>.
* Template and modes: Template and modes<22>.
* Examples: Examples<30>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<29>,  Next: Template and modes<22>,  Up: alias/2

2.3.4.2 Description
...................

     alias(Entity, [Name/Arity as Alias/Arity, ...])
     alias(Entity, [Name//Arity as Alias//Arity, ...])

Declares predicate and grammar rule non-terminal *note aliases: ca.  A
predicate (non-terminal) alias is an alternative name for a predicate
(non-terminal) declared or defined in an extended protocol, an
implemented protocol, an extended category, an imported category, an
extended prototype, an instantiated class, or a specialized class.
Predicate aliases may be used to solve conflicts between imported or
inherited predicates.  It may also be used to give a predicate
(non-terminal) a name more appropriate in its usage context.  This
directive may be used in objects, protocols, and categories.

Predicate (and non-terminal) aliases are specified using (preferably)
the notation ‘Name/Arity as Alias/Arity’ or, in alternative, the
notation ‘Name/Arity::Alias/Arity’.

It is also possible to declare predicate and grammar rule non-terminal
aliases in implicit qualification directives for sending messages to
objects and calling module predicates.


File: TheLogtalkHandbook-3.101.0.info,  Node: Template and modes<22>,  Next: Examples<30>,  Prev: Description<29>,  Up: alias/2

2.3.4.3 Template and modes
..........................

     alias(@entity_identifier, +list(predicate_indicator_alias))
     alias(@entity_identifier, +list(non_terminal_indicator_alias))


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<30>,  Prev: Template and modes<22>,  Up: alias/2

2.3.4.4 Examples
................

     % resolve a predicate name conflict:
     :- alias(list, [member/2 as list_member/2]).
     :- alias(set,  [member/2 as set_member/2]).

     % define an alternative name for a non-terminal:
     :- alias(words, [singular//0 as peculiar//0]).

See also
........

*note uses/2: 4b, *note use_module/2: 4d, *note uses/1: 4a.

'directive'


File: TheLogtalkHandbook-3.101.0.info,  Node: coinductive/1,  Next: discontiguous/1,  Prev: alias/2,  Up: Predicate directives<2>

2.3.4.5 ‘coinductive/1’
.......................

* Menu:

* Description: Description<30>.
* Template and modes: Template and modes<23>.
* Examples: Examples<31>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<30>,  Next: Template and modes<23>,  Up: coinductive/1

2.3.4.6 Description
...................

     coinductive(Name/Arity)
     coinductive((Name/Arity, ...))
     coinductive([Name/Arity, ...])

     coinductive(Name//Arity)
     coinductive((Name//Arity, ...))
     coinductive([Name//Arity, ...])

     coinductive(Template)
     coinductive((Template1, ...))
     coinductive([Template1, ...])

This is an 'experimental' directive, used for declaring *note
coinductive: 170. predicates.  Requires a *note backend Prolog compiler:
34. with minimal support for cyclic terms.  The current implementation
of coinduction allows the generation of only the 'basic cycles' but all
valid solutions should be recognized.  Use a predicate indicator or a
non-terminal indicator as argument when all the coinductive predicate
arguments are relevant for coinductive success.  Use a template when
only some coinductive predicate arguments (represented by a “‘+’”)
should be considered when testing for coinductive success (represent the
arguments that should be disregarded by a “‘-’“).  It’s possible to
define local *note coinductive_success_hook/1-2: 4b3. 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.101.0.info,  Node: Template and modes<23>,  Next: Examples<31>,  Prev: Description<30>,  Up: coinductive/1

2.3.4.7 Template and modes
..........................

     coinductive(+predicate_indicator_term)
     coinductive(+non_terminal_indicator_term)
     coinductive(+coinductive_predicate_template_term)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<31>,  Prev: Template and modes<23>,  Up: coinductive/1

2.3.4.8 Examples
................

     :- coinductive(comember/2).
     :- coinductive(ones_and_zeros//0).
     :- coinductive(controller(+,+,+,-,-)).

See also
........

*note coinductive_success_hook/1-2: 4b3, *note predicate_property/2:
142.

'directive'


File: TheLogtalkHandbook-3.101.0.info,  Node: discontiguous/1,  Next: dynamic/1,  Prev: coinductive/1,  Up: Predicate directives<2>

2.3.4.9 ‘discontiguous/1’
.........................

* Menu:

* Description: Description<31>.
* Template and modes: Template and modes<24>.
* Examples: Examples<32>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<31>,  Next: Template and modes<24>,  Up: discontiguous/1

2.3.4.10 Description
....................

     discontiguous(Name/Arity)
     discontiguous((Name/Arity, ...))
     discontiguous([Name/Arity, ...])

     discontiguous(Entity::Name/Arity)
     discontiguous((Entity::Name/Arity, ...))
     discontiguous([Entity::Name/Arity, ...])

     discontiguous(Module:Name/Arity)
     discontiguous((Module:Name/Arity, ...))
     discontiguous([Module:Name/Arity, ...])

     discontiguous(Name//Arity)
     discontiguous((Name//Arity, ...))
     discontiguous([Name//Arity, ...])

     discontiguous(Entity::Name//Arity)
     discontiguous((Entity::Name//Arity, ...))
     discontiguous([Entity::Name//Arity, ...])

     discontiguous(Module:Name//Arity)
     discontiguous((Module:Name//Arity, ...))
     discontiguous([Module:Name//Arity, ...])

Declares *note discontiguous: 4b9. predicates and discontiguous grammar
rule non-terminals.  The use of this directive should be avoided as not
all *note backend Prolog compilers: 34. support discontiguous
predicates.

     Warning: Some backend Prolog compilers declare the atom
     ‘discontiguous’ as an operator for a lighter syntax.  But this
     makes the code non-portable and is therefore a practice best
     avoided.


File: TheLogtalkHandbook-3.101.0.info,  Node: Template and modes<24>,  Next: Examples<32>,  Prev: Description<31>,  Up: discontiguous/1

2.3.4.11 Template and modes
...........................

     discontiguous(+predicate_indicator_term)
     discontiguous(+non_terminal_indicator_term)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<32>,  Prev: Template and modes<24>,  Up: discontiguous/1

2.3.4.12 Examples
.................

     :- discontiguous(counter/1).

     :- discontiguous((lives/2, works/2)).

     :- discontiguous([db/4, key/2, file/3]).

'directive'


File: TheLogtalkHandbook-3.101.0.info,  Node: dynamic/1,  Next: info/2,  Prev: discontiguous/1,  Up: Predicate directives<2>

2.3.4.13 ‘dynamic/1’
....................

* Menu:

* Description: Description<32>.
* Template and modes: Template and modes<25>.
* Examples: Examples<33>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<32>,  Next: Template and modes<25>,  Up: dynamic/1

2.3.4.14 Description
....................

     dynamic(Name/Arity)
     dynamic((Name/Arity, ...))
     dynamic([Name/Arity, ...])

     dynamic(Entity::Name/Arity)
     dynamic((Entity::Name/Arity, ...))
     dynamic([Entity::Name/Arity, ...])

     dynamic(Module:Name/Arity)
     dynamic((Module:Name/Arity, ...))
     dynamic([Module:Name/Arity, ...])

     dynamic(Name//Arity)
     dynamic((Name//Arity, ...))
     dynamic([Name//Arity, ...])

     dynamic(Entity::Name//Arity)
     dynamic((Entity::Name//Arity, ...))
     dynamic([Entity::Name//Arity, ...])

     dynamic(Module:Name//Arity)
     dynamic((Module:Name//Arity, ...))
     dynamic([Module:Name//Arity, ...])

Declares *note dynamic: 4bf. predicates and dynamic grammar rule
non-terminals.  Note that an object can be static and have both static
and dynamic predicates/non-terminals.  When the dynamic predicates are
local to an object, declaring them also as *note private predicates:
145. allows the Logtalk compiler to generate optimized code for
asserting and retracting predicate clauses.  Categories can also contain
dynamic predicate directives but cannot contain clauses for dynamic
predicates.

The predicate indicators (or non-terminal indicators) can be explicitly
qualified with an object, category, or module identifier when the
predicates (or non-terminals) are also declared *note multifile: 16c.

Note that dynamic predicates cannot be declared synchronized (when
necessary, declare the predicates updating the dynamic predicates as
*note synchronized: 74.).

     Warning: Some backend Prolog compilers declare the atom ‘dynamic’
     as an operator for a lighter syntax.  But this makes the code
     non-portable and is therefore a practice best avoided.


File: TheLogtalkHandbook-3.101.0.info,  Node: Template and modes<25>,  Next: Examples<33>,  Prev: Description<32>,  Up: dynamic/1

2.3.4.15 Template and modes
...........................

     dynamic(+qualified_predicate_indicator_term)
     dynamic(+qualified_non_terminal_indicator_term)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<33>,  Prev: Template and modes<25>,  Up: dynamic/1

2.3.4.16 Examples
.................

     :- dynamic(counter/1).

     :- dynamic((lives/2, works/2)).

     :- dynamic([db/4, key/2, file/3]).

See also
........

*note dynamic/0: b1, *note predicate_property/2: 142.

'directive'


File: TheLogtalkHandbook-3.101.0.info,  Node: info/2,  Next: meta_predicate/1,  Prev: dynamic/1,  Up: Predicate directives<2>

2.3.4.17 ‘info/2’
.................

* Menu:

* Description: Description<33>.
* Template and modes: Template and modes<26>.
* Examples: Examples<34>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<33>,  Next: Template and modes<26>,  Up: info/2

2.3.4.18 Description
....................

     info(Name/Arity, [Key is Value, ...])
     info(Name//Arity, [Key is Value, ...])

Documentation directive for predicates and grammar rule non-terminals.
The first argument is either a predicate indicator or a grammar rule
non-terminal indicator.  The second argument is a list of pairs using
the format 'Key is Value'.  See the *note Predicate documenting
directives: 326. section for a description of the default keys.


File: TheLogtalkHandbook-3.101.0.info,  Node: Template and modes<26>,  Next: Examples<34>,  Prev: Description<33>,  Up: info/2

2.3.4.19 Template and modes
...........................

     info(+predicate_indicator, +predicate_info_list)
     info(+non_terminal_indicator, +predicate_info_list)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<34>,  Prev: Template and modes<26>,  Up: info/2

2.3.4.20 Examples
.................

     :- info(empty/1, [
         comment is 'True if the argument is an empty list.',
         argnames is ['List']
     ]).

     :- info(sentence//0, [
         comment is 'Rewrites a sentence into a noun phrase and a verb phrase.'
     ]).

See also
........

*note info/1: b4, *note mode/2: 149, *note predicate_property/2: 142.

'directive'


File: TheLogtalkHandbook-3.101.0.info,  Node: meta_predicate/1,  Next: meta_non_terminal/1,  Prev: info/2,  Up: Predicate directives<2>

2.3.4.21 ‘meta_predicate/1’
...........................

* Menu:

* Description: Description<34>.
* Template and modes: Template and modes<27>.
* Examples: Examples<35>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<34>,  Next: Template and modes<27>,  Up: meta_predicate/1

2.3.4.22 Description
....................

     meta_predicate(Template)
     meta_predicate((Template, ...))
     meta_predicate([Template, ...])

     meta_predicate(Entity::Template)
     meta_predicate((Entity::Template, ...))
     meta_predicate([Entity::Template, ...])

     meta_predicate(Module:Template)
     meta_predicate((Module:Template, ...))
     meta_predicate([Module:Template, ...])

Declares *note meta-predicates: 52, i.e., predicates that have arguments
interpreted as goals, arguments interpreted as *note closures: 14f. used
to construct goals, or arguments with sub-terms that will be interpreted
as goals or closures.  Meta-arguments are always called in the
meta-predicate *note calling context: 150, not in the meta-predicate
*note definition context: 151.

Meta-arguments which are goals are represented by the integer ‘0’.
Meta-arguments which are closures are represented by a positive integer,
‘N’, representing the number of additional arguments that will be
appended to the closure in order to construct the corresponding goal
(typically by calling the *note call/1-N: 181. built-in method).
Meta-arguments with sub-terms that will be interpreted as goals or
closures are represented by ‘::’.  Meta-arguments that will be called
using the ‘bagof/3’ or ‘setof/3’ predicates and that can thus be
existentially-qualified are represented by the atom ‘^’.  Normal
arguments are represented by the atom ‘*’.

Logtalk allows the use of this directive to override the original
meta-predicate directive.  This is sometimes necessary when calling
Prolog built-in meta-predicates or Prolog module meta-predicates due to
the lack of standardization of the syntax of the meta-predicate
templates.  Another case is when a meta-predicate directive is missing.
The compiler requires access to correct and non-ambiguous meta-predicate
templates to correctly compile calls to Prolog meta-predicates.

     Warning: Some backend Prolog compilers declare the atom
     ‘meta_predicate’ as an operator for a lighter syntax.  But this
     makes the code non-portable and is therefore a practice best
     avoided.


File: TheLogtalkHandbook-3.101.0.info,  Node: Template and modes<27>,  Next: Examples<35>,  Prev: Description<34>,  Up: meta_predicate/1

2.3.4.23 Template and modes
...........................

     meta_predicate(+meta_predicate_template_term)

     meta_predicate(+object_identifier::+meta_predicate_template_term)
     meta_predicate(+category_identifier::+meta_predicate_template_term)

     meta_predicate(+module_identifier:+meta_predicate_template_term)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<35>,  Prev: Template and modes<27>,  Up: meta_predicate/1

2.3.4.24 Examples
.................

     % findall/3 second argument is interpreted as a goal:
     :- meta_predicate(findall(*, 0, *)).

     % both forall/2 arguments are interpreted as goals:
     :- meta_predicate(forall(0, 0)).

     % maplist/3 first argument is interpreted as a closure
     % that will be expanded to a goal by appending two
     % arguments:
     :- meta_predicate(maplist(2, *, *)).

See also
........

*note meta_non_terminal/1: 153, *note predicate_property/2: 142.

'directive'


File: TheLogtalkHandbook-3.101.0.info,  Node: meta_non_terminal/1,  Next: mode/2,  Prev: meta_predicate/1,  Up: Predicate directives<2>

2.3.4.25 ‘meta_non_terminal/1’
..............................

* Menu:

* Description: Description<35>.
* Template and modes: Template and modes<28>.
* Examples: Examples<36>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<35>,  Next: Template and modes<28>,  Up: meta_non_terminal/1

2.3.4.26 Description
....................

     meta_non_terminal(Template)
     meta_non_terminal((Template, ...))
     meta_non_terminal([Template, ...])

     meta_non_terminal(Entity::Template)
     meta_non_terminal((Entity::Template, ...))
     meta_non_terminal([Entity::Template, ...])

     meta_non_terminal(Module:Template)
     meta_non_terminal((Module:Template, ...))
     meta_non_terminal([Module:Template, ...])

Declares meta-non-terminals, i.e., non-terminals that have arguments
that will be called as non-terminals (or grammar rule bodies).  An
argument may also be a *note closure: 14f. instead of a goal if the
non-terminal uses the *note call//1-N: 1c9. built-in methods to
construct and call the actual non-terminal from the closure and the
additional arguments or the *note phrase//1: 1c8. built-in method.

Meta-arguments which are non-terminals are represented by the integer
‘0’.  Meta-arguments which are closures are represented by a positive
integer, ‘N’, representing the number of additional arguments that will
be appended to the closure in order to construct the corresponding
meta-call.  Normal arguments are represented by the atom ‘*’.
Meta-arguments are always called in the meta-non-terminal calling
context, not in the meta-non-terminal definition context.


File: TheLogtalkHandbook-3.101.0.info,  Node: Template and modes<28>,  Next: Examples<36>,  Prev: Description<35>,  Up: meta_non_terminal/1

2.3.4.27 Template and modes
...........................

     meta_non_terminal(+meta_non_terminal_template_term)

     meta_non_terminal(+object_identifier::+meta_non_terminal_template_term)
     meta_non_terminal(+category_identifier::+meta_non_terminal_template_term)

     meta_non_terminal(+module_identifier:+meta_non_terminal_template_term)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<36>,  Prev: Template and modes<28>,  Up: meta_non_terminal/1

2.3.4.28 Examples
.................

     :- meta_non_terminal(phrase(1, *)).
     phrase(X, T) --> call(X, T).

See also
........

*note meta_predicate/1: 152, *note predicate_property/2: 142.

'directive'


File: TheLogtalkHandbook-3.101.0.info,  Node: mode/2,  Next: mode_non_terminal/2,  Prev: meta_non_terminal/1,  Up: Predicate directives<2>

2.3.4.29 ‘mode/2’
.................

* Menu:

* Description: Description<36>.
* Template and modes: Template and modes<29>.
* Examples: Examples<37>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<36>,  Next: Template and modes<29>,  Up: mode/2

2.3.4.30 Description
....................

     mode(Mode, NumberOfProofs)

Most predicates can be used with several instantiations modes.  This
directive enables the specification of each *note instantiation mode:
14b. and the corresponding *note number of proofs: 14d. (but not
necessarily distinct solutions).  The instantiation mode of each
argument can include type information.


File: TheLogtalkHandbook-3.101.0.info,  Node: Template and modes<29>,  Next: Examples<37>,  Prev: Description<36>,  Up: mode/2

2.3.4.31 Template and modes
...........................

     mode(+predicate_mode_term, +number_of_proofs)
     mode(+non_terminal_mode_term, +number_of_proofs)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<37>,  Prev: Template and modes<29>,  Up: mode/2

2.3.4.32 Examples
.................

     :- mode(atom_concat(-atom, -atom, +atom), one_or_more).
     :- mode(atom_concat(+atom, +atom, -atom), one).

     :- mode(var(@term), zero_or_one).

     :- mode(solve(+callable, -list(atom)), zero_or_one).

See also
........

*note mode_non_terminal/2: 14a, *note info/2: 168, *note
predicate_property/2: 142.

'directive'


File: TheLogtalkHandbook-3.101.0.info,  Node: mode_non_terminal/2,  Next: multifile/1,  Prev: mode/2,  Up: Predicate directives<2>

2.3.4.33 ‘mode_non_terminal/2’
..............................

* Menu:

* Description: Description<37>.
* Template and modes: Template and modes<30>.
* Examples: Examples<38>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<37>,  Next: Template and modes<30>,  Up: mode_non_terminal/2

2.3.4.34 Description
....................

     mode_non_terminal(Mode, NumberOfProofs)

Most non-terminals can be used with several instantiations modes.  This
directive enables the specification of each *note instantiation mode:
14b. and the corresponding *note number of proofs: 14d. (but not
necessarily distinct solutions).  The instantiation mode of each
argument can include type information.


File: TheLogtalkHandbook-3.101.0.info,  Node: Template and modes<30>,  Next: Examples<38>,  Prev: Description<37>,  Up: mode_non_terminal/2

2.3.4.35 Template and modes
...........................

     mode_non_terminal(+predicate_mode_term, +number_of_proofs)
     mode_non_terminal(+non_terminal_mode_term, +number_of_proofs)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<38>,  Prev: Template and modes<30>,  Up: mode_non_terminal/2

2.3.4.36 Examples
.................

     :- mode_non_terminal(zero_or_more(-list(atomic)), one).

See also
........

*note mode/2: 149, *note info/2: 168, *note predicate_property/2: 142.

'directive'


File: TheLogtalkHandbook-3.101.0.info,  Node: multifile/1,  Next: private/1,  Prev: mode_non_terminal/2,  Up: Predicate directives<2>

2.3.4.37 ‘multifile/1’
......................

* Menu:

* Description: Description<38>.
* Template and modes: Template and modes<31>.
* Examples: Examples<39>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<38>,  Next: Template and modes<31>,  Up: multifile/1

2.3.4.38 Description
....................

     multifile(Name/Arity)
     multifile((Name/Arity, ...))
     multifile([Name/Arity, ...])

     multifile(Entity::Name/Arity)
     multifile((Entity::Name/Arity, ...))
     multifile([Entity::Name/Arity, ...])

     multifile(Module:Name/Arity)
     multifile((Module:Name/Arity, ...))
     multifile([Module:Name/Arity, ...])

     multifile(Name//Arity)
     multifile((Name//Arity, ...))
     multifile([Name//Arity, ...])

     multifile(Entity::Name//Arity)
     multifile((Entity::Name//Arity, ...))
     multifile([Entity::Name//Arity, ...])

     multifile(Module:Name//Arity)
     multifile((Module:Name//Arity, ...))
     multifile([Module:Name//Arity, ...])

Declares *note multifile: 16b. predicates and multifile grammar rule
non-terminals.  In the case of object or category multifile predicates,
the predicate (or non-terminal) must also have a *note scope directive:
1e4. in the object or category holding its 'primary declaration' (i.e.,
the declaration without the ‘Entity::’ prefix).  Entities holding
multifile predicate primary declarations must be compiled and loaded
prior to any entities contributing with clauses for the multifile
predicates (to prevent using multifile predicates to break entity
encapsulation).

Protocols cannot declare or define multifile predicates as protocols
cannot contain predicate definitions.

     Warning: Some backend Prolog compilers declare the atom ‘multifile’
     as an operator for a lighter syntax.  But this makes the code
     non-portable and is therefore a practice best avoided.


File: TheLogtalkHandbook-3.101.0.info,  Node: Template and modes<31>,  Next: Examples<39>,  Prev: Description<38>,  Up: multifile/1

2.3.4.39 Template and modes
...........................

     multifile(+qualified_predicate_indicator_term)
     multifile(+qualified_non_terminal_indicator_term)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<39>,  Prev: Template and modes<31>,  Up: multifile/1

2.3.4.40 Examples
.................

     :- multifile(table/3).
     :- multifile(user::hook/2).

See also
........

*note public/1: 143, *note protected/1: 144, *note private/1: 145, *note
predicate_property/2: 142.

'directive'


File: TheLogtalkHandbook-3.101.0.info,  Node: private/1,  Next: protected/1,  Prev: multifile/1,  Up: Predicate directives<2>

2.3.4.41 ‘private/1’
....................

* Menu:

* Description: Description<39>.
* Template and modes: Template and modes<32>.
* Examples: Examples<40>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<39>,  Next: Template and modes<32>,  Up: private/1

2.3.4.42 Description
....................

     private(Name/Arity)
     private((Name/Arity, ...))
     private([Name/Arity, ...])

     private(Name//Arity)
     private((Name//Arity, ...))
     private([Name//Arity, ...])


     private(op(Precedence,Associativity,Operator))
     private((op(Precedence,Associativity,Operator), ...))
     private([op(Precedence,Associativity,Operator), ...])

Declares *note private: 55. predicates, private grammar rule
non-terminals, and private operators.  A private predicate can only be
called from the object containing the private directive.  A private
non-terminal can only be used in a call of the *note phrase/2: 18e. and
*note phrase/3: 18f. methods from the object containing the private
directive.


File: TheLogtalkHandbook-3.101.0.info,  Node: Template and modes<32>,  Next: Examples<40>,  Prev: Description<39>,  Up: private/1

2.3.4.43 Template and modes
...........................

     private(+predicate_indicator_term)
     private(+non_terminal_indicator_term)
     private(+operator_declaration)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<40>,  Prev: Template and modes<32>,  Up: private/1

2.3.4.44 Examples
.................

     :- private(counter/1).

     :- private((init/1, free/1)).

     :- private([data/3, key/1, keys/1]).

See also
........

*note protected/1: 144, *note public/1: 143, *note predicate_property/2:
142.

'directive'


File: TheLogtalkHandbook-3.101.0.info,  Node: protected/1,  Next: public/1,  Prev: private/1,  Up: Predicate directives<2>

2.3.4.45 ‘protected/1’
......................

* Menu:

* Description: Description<40>.
* Template and modes: Template and modes<33>.
* Examples: Examples<41>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<40>,  Next: Template and modes<33>,  Up: protected/1

2.3.4.46 Description
....................

     protected(Name/Arity)
     protected((Name/Arity, ...))
     protected([Name/Arity, ...])

     protected(Name//Arity)
     protected((Name//Arity, ...))
     protected([Name//Arity, ...])

     protected(op(Precedence,Associativity,Operator))
     protected((op(Precedence,Associativity,Operator), ...))
     protected([op(Precedence,Associativity,Operator), ...])

Declares *note protected: 54. predicates, protected grammar rule
non-terminals, and protected operators.  A protected predicate can only
be called from the object containing the directive or from an object
that inherits the directive.  A protected non-terminal can only be used
as an argument in a *note phrase/2: 18e. and *note phrase/3: 18f. calls
from the object containing the directive or from an object that inherits
the directive.

     Note: Protected operators are not inherited but declaring them
     provides a reusable specification for using them in descendant
     objects (or categories).


File: TheLogtalkHandbook-3.101.0.info,  Node: Template and modes<33>,  Next: Examples<41>,  Prev: Description<40>,  Up: protected/1

2.3.4.47 Template and modes
...........................

     protected(+predicate_indicator_term)
     protected(+non_terminal_indicator_term)
     protected(+operator_declaration)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<41>,  Prev: Template and modes<33>,  Up: protected/1

2.3.4.48 Examples
.................

     :- protected(init/1).

     :- protected((print/2, convert/4)).

     :- protected([load/1, save/3]).

See also
........

*note private/1: 145, *note public/1: 143, *note predicate_property/2:
142.

'directive'


File: TheLogtalkHandbook-3.101.0.info,  Node: public/1,  Next: synchronized/1,  Prev: protected/1,  Up: Predicate directives<2>

2.3.4.49 ‘public/1’
...................

* Menu:

* Description: Description<41>.
* Template and modes: Template and modes<34>.
* Examples: Examples<42>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<41>,  Next: Template and modes<34>,  Up: public/1

2.3.4.50 Description
....................

     public(Name/Arity)
     public((Name/Arity, ...))
     public([Name/Arity, ...])

     public(Name//Arity)
     public((Name//Arity, ...))
     public([Name//Arity, ...])

     public(op(Precedence,Associativity,Operator))
     public((op(Precedence,Associativity,Operator), ...))
     public([op(Precedence,Associativity,Operator), ...])

Declares *note public: 53. predicates, public grammar rule
non-terminals, and public operators.  A public predicate can be called
from any object.  A public non-terminal can be used as an argument in
*note phrase/2: 18e. and *note phrase/3: 18f. calls from any object.

     Note: Declaring a public operator does not make it global when the
     entity holding the scope directive is compiled and loaded.  But
     declaring public operators provides a reusable specification for
     using them in the entity clients (e.g., in *note uses/2: 4b.
     directives).


File: TheLogtalkHandbook-3.101.0.info,  Node: Template and modes<34>,  Next: Examples<42>,  Prev: Description<41>,  Up: public/1

2.3.4.51 Template and modes
...........................

     public(+predicate_indicator_term)
     public(+non_terminal_indicator_term)
     public(+operator_declaration)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<42>,  Prev: Template and modes<34>,  Up: public/1

2.3.4.52 Examples
.................

     :- public(ancestor/1).

     :- public((instance/1, instances/1)).

     :- public([leaf/1, leaves/1]).

See also
........

*note private/1: 145, *note protected/1: 144, *note
predicate_property/2: 142.

'directive'


File: TheLogtalkHandbook-3.101.0.info,  Node: synchronized/1,  Next: uses/2,  Prev: public/1,  Up: Predicate directives<2>

2.3.4.53 ‘synchronized/1’
.........................

* Menu:

* Description: Description<42>.
* Template and modes: Template and modes<35>.
* Examples: Examples<43>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<42>,  Next: Template and modes<35>,  Up: synchronized/1

2.3.4.54 Description
....................

     synchronized(Name/Arity)
     synchronized((Name/Arity, ...))
     synchronized([Name/Arity, ...])

     synchronized(Name//Arity)
     synchronized((Name//Arity, ...))
     synchronized([Name//Arity, ...])

Declares *note synchronized: 175. predicates and synchronized grammar
rule non-terminals.  The most common use is for predicates that have
side effects (e.g., asserting or retracting clauses for a dynamic
predicate) in multi-threaded applications.  A synchronized predicate (or
synchronized non-terminal) is protected by a mutex in order to allow for
thread synchronization when proving a call to the predicate (or
non-terminal).

All predicates (and non-terminals) declared in the same synchronized
directive share the same mutex.  In order to use a separate mutex for
each predicate (non-terminal) so that they are independently
synchronized, a per-predicate synchronized directive must be used.

     Warning: Declaring a predicate synchronized implicitly makes it
     'deterministic'.  When using a single-threaded *note backend Prolog
     compiler: 34, calls to synchronized predicates behave as wrapped by
     the standard *note once/1: 1bb. meta-predicate.

Note that synchronized predicates cannot be declared *note dynamic: 15a.
(when necessary, declare the predicates updating the dynamic predicates
as synchronized).


File: TheLogtalkHandbook-3.101.0.info,  Node: Template and modes<35>,  Next: Examples<43>,  Prev: Description<42>,  Up: synchronized/1

2.3.4.55 Template and modes
...........................

     synchronized(+predicate_indicator_term)
     synchronized(+non_terminal_indicator_term)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<43>,  Prev: Template and modes<35>,  Up: synchronized/1

2.3.4.56 Examples
.................

     :- synchronized(db_update/1).

     :- synchronized((write_stream/2, read_stream/2)).

     :- synchronized([add_to_queue/2, remove_from_queue/2]).

See also
........

*note predicate_property/2: 142.

'directive'


File: TheLogtalkHandbook-3.101.0.info,  Node: uses/2,  Next: use_module/2,  Prev: synchronized/1,  Up: Predicate directives<2>

2.3.4.57 ‘uses/2’
.................

* Menu:

* Description: Description<43>.
* Template and modes: Template and modes<36>.
* Examples: Examples<44>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<43>,  Next: Template and modes<36>,  Up: uses/2

2.3.4.58 Description
....................

     uses(Object, [Name/Arity, ...])
     uses(Object, [Name/Arity as Alias/Arity, ...])

     uses(Object, [Predicate as Alias, ...])

     uses(Object, [Name//Arity, ...])
     uses(Object, [Name//Arity as Alias//Arity, ...])

     uses(Object, [op(Precedence, Associativity, Operator), ...])

Declares that all calls made from predicates (or non-terminals) defined
in the category or object containing the directive to the specified
predicates (or non-terminals) are to be interpreted as messages to the
specified object.  Thus, this directive may be used to simplify writing
of predicate definitions by allowing the programmer to omit the
‘Object::’ prefix when using the predicates listed in the directive (as
long as the calls do not occur as arguments for non-standard Prolog
meta-predicates not declared in the adapter files).  It is also possible
to include operator declarations in the second argument.

This directive is also taken into account when compiling calls to the
*note database: 1af. and *note reflection: 1c4. built-in methods by
looking into these methods predicate arguments if bound at compile-time.

It is possible to specify a predicate alias using the notation
‘Name/Arity as Alias/Arity’ or, in alternative, the notation
‘Name/Arity::Alias/Arity’.  Aliases may be used to avoid conflicts
between predicates specified in ‘use_module/2’ and ‘uses/2’ directives,
for giving more meaningful names considering the calling context of the
predicates, and to change the order of the predicate arguments when
calling the predicate.  For predicates, it is also possible to define
alias shorthands using the notation ‘Predicate as Alias’ or, in
alternative, the notation ‘Predicate::Alias’, where ‘Predicate’ and
‘Alias’ are callable terms where some or all arguments may be
instantiated.

To enable the use of *note static binding: 35, and thus optimal
message-sending performance, the objects should be loaded before
compiling the entities that call their predicates.

The object identifier argument can also be a *note parameter variable:
a1. when using the directive in a parametric object or a parametric
category defined in a source file (the common case).  In this case,
*note dynamic binding: 36. will be used for all listed predicates (and
non-terminals).  The parameter variable must be instantiated at runtime
when the messages are sent.


File: TheLogtalkHandbook-3.101.0.info,  Node: Template and modes<36>,  Next: Examples<44>,  Prev: Description<43>,  Up: uses/2

2.3.4.59 Template and modes
...........................

     uses(+object_identifier, +predicate_indicator_list)
     uses(+object_identifier, +predicate_indicator_alias_list)

     uses(+object_identifier, +predicate_template_alias_list)

     uses(+object_identifier, +non_terminal_indicator_list)
     uses(+object_identifier, +non_terminal_indicator_alias_list)

     uses(+object_identifier, +operator_list)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<44>,  Prev: Template and modes<36>,  Up: uses/2

2.3.4.60 Examples
.................

     :- uses(list,  [append/3, member/2]).
     :- uses(store, [data/2]).
     :- uses(user,  [table/4]).

     foo :-
         ...,
         % the same as findall(X, list::member(X, L), A)
         findall(X, member(X, L), A),
         % the same as list::append(A, B, C)
         append(A, B, C),
         % the same as store::assertz(data(X, C))
         assertz(data(X, C)),
         % call the table/4 predicate in "user"
         table(X, Y, Z, T),
         ...

Another example, using the extended notation that allows us to define
predicate aliases:

     :- uses(btrees, [new/1 as new_btree/1]).
     :- uses(queues, [new/1 as new_queue/1]).

     btree_to_queue :-
         ...,
         % the same as btrees::new(Tree)
         new_btree(Tree),
         % the same as queues::new(Queue)
         new_queue(Queue),
         ...

An example of defining a predicate alias that is also a shorthand:

     :- uses(logtalk, [
         print_message(debug, my_app, Message) as dbg(Message)
     ]).

Predicate aliases can also be used to change argument order:

     :- uses(meta, [
         fold_left(Closure,Accumulator,List,Result) as foldl(Closure,List,Accumulator,Result)
     ]).

An example of using a *note parameter variable: a1. in place of the
object identifier to allow using the same test set for checking multiple
implementations of the same protocol:

     :- object(tests(_HeapObject_),
         extends(lgtunit)).

         :- uses(_HeapObject_, [
             as_heap/2, as_list/2, valid/1, new/1,
             insert/4, insert_all/3, delete/4, merge/3,
             empty/1, size/2, top/3, top_next/5
         ]).

See also
........

*note uses/1: 4a, *note use_module/1: 4c, *note use_module/2: 4d, *note
alias/2: 165.

'directive'


File: TheLogtalkHandbook-3.101.0.info,  Node: use_module/2,  Prev: uses/2,  Up: Predicate directives<2>

2.3.4.61 ‘use_module/2’
.......................

* Menu:

* Description: Description<44>.
* Template and modes: Template and modes<37>.
* Examples: Examples<45>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<44>,  Next: Template and modes<37>,  Up: use_module/2

2.3.4.62 Description
....................

     use_module(Module, [Name/Arity, ...])
     use_module(Module, [Name/Arity as Alias/Arity, ...])

     use_module(Module, [Predicate as Alias, ...])

     use_module(Module, [Name//Arity, ...])
     use_module(Module, [Name//Arity as Alias//Arity, ...])

     use_module(Module, [op(Precedence,Associativity,Operator), ...])

This directive declares that all calls (made from predicates defined in
the category or object containing the directive) to the specified
predicates (or non-terminals) are to be interpreted as calls to
explicitly-qualified module predicates (or non-terminals).  Thus, this
directive may be used to simplify the writing of predicate definitions
by allowing the programmer to omit the ‘Module:’ prefix when using the
predicates listed in the directive (as long as the predicate calls do
not occur as arguments for non-standard Prolog meta-predicates not
declared on the adapter files).  It is also possible to include operator
declarations in the second argument.

This directive is also taken into account when compiling calls to the
*note database: 1af. and *note reflection: 1c4. built-in methods by
looking into these methods predicate arguments if bound at compile-time.

It is possible to specify a predicate alias using the notation
‘Name/Arity as Alias/Arity’ or, in alternative, the notation
‘Name/Arity:Alias/Arity’.  Aliases may be used either for avoiding
conflicts between predicates specified in ‘use_module/2’ and *note
uses/2: 4b. directives or for giving more meaningful names considering
the calling context of the predicates.  For predicates, it is also
possible to define alias shorthands using the notation ‘Predicate as
Alias’ or, in alternative, the notation ‘Predicate::Alias’, where
‘Predicate’ and ‘Alias’ are callable terms where some or all arguments
may be instantiated.

Note that this directive differs from the directive with the same name
found on some Prolog implementations by requiring the first argument to
be a module name (an atom) instead of a file specification.  In Logtalk,
there’s no mixing between 'loading' a resource and (declaring the)
'using' (of) a resource.  As a consequence, this directive doesn’t
automatically load the module.  Loading the module file is dependent on
the used *note backend Prolog compiler: 34. and must be done separately
(usually, using a source file directive such as ‘use_module/1’ or
‘use_module/2’ in the entity file or preferably in the application *note
loader file: 4f. file).  Also, note that the name of the module may
differ from the name of the module file.

     Warning: The modules 'must' be loaded prior to the compilation of
     entities that call the module predicates.  This is required in
     general to allow the compiler to check if the called module
     predicate is a meta-predicate and retrieve its meta-predicate
     template to ensure proper call compilation.

The module identifier argument can also be a *note parameter variable:
a1. when using the directive in a parametric object or a parametric
category defined in a source file (the common case).  In this case,
*note dynamic binding: 36. will be used for all listed predicates (and
non-terminals).  The parameter variable must be instantiated at runtime
when the calls are made.


File: TheLogtalkHandbook-3.101.0.info,  Node: Template and modes<37>,  Next: Examples<45>,  Prev: Description<44>,  Up: use_module/2

2.3.4.63 Template and modes
...........................

     use_module(+module_identifier, +predicate_indicator_list)
     use_module(+module_identifier, +module_predicate_indicator_alias_list)

     use_module(+module_identifier, +predicate_template_alias_list)

     use_module(+module_identifier, +non_terminal_indicator_list)
     use_module(+module_identifier, +module_non_terminal_indicator_alias_list)

     use_module(+module_identifier, +operator_list)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<45>,  Prev: Template and modes<37>,  Up: use_module/2

2.3.4.64 Examples
.................

     :- use_module(lists, [append/3, member/2]).
     :- use_module(store, [data/2]).
     :- use_module(user,  [foo/1 as bar/1]).

     foo :-
         ...,
         % same as findall(X, lists:member(X, L), A)
         findall(X, member(X, L), A),
         % same as lists:append(A, B, C)
         append(A, B, C),
         % same as assertz(store:data(X, C))
         assertz(data(X, C)),
         % same as retractall(user:foo(_))
         retractall(bar(_)),
         ...

Another example, using the extended notation that allows us to define
predicate aliases:

     :- use_module(ugraphs, [transpose_ugraph/2 as transpose/2]).

     convert_graph :-
         ...,
         % the same as ugraphs:transpose_ugraph(Graph0, Graph)
         transpose(Graph0, Graph),
         ...

An example of defining a predicate alias that is also a shorthand:

     :- use_module(pairs, [
         map_list_to_pairs(length, Lists, Pairs) as length_pairs(Lists, Pairs)
     ]).

An example of using a *note parameter variable: a1. in place of the
module identifier to delay to runtime the actual module to use:

     :- object(bar(_OptionsModule_)).

         :- use_module(_OptionsModule_, [
             set/2, get/2, reset/0
         ]).

See also
........

*note use_module/1: 4c, *note uses/2: 4b, *note uses/1: 4a, *note
alias/2: 165.


File: TheLogtalkHandbook-3.101.0.info,  Node: Built-in predicates,  Next: Built-in methods<2>,  Prev: Directives<2>,  Up: Reference Manual

2.4 Built-in predicates
=======================

* Menu:

* Enumerating objects, categories and protocols: Enumerating objects categories and protocols.
* Enumerating objects, categories and protocols properties: Enumerating objects categories and protocols properties.
* Creating new objects, categories and protocols: Creating new objects categories and protocols.
* Abolishing objects, categories and protocols: Abolishing objects categories and protocols.
* Objects, categories, and protocols relations: Objects categories and protocols relations.
* Event handling: Event handling<2>.
* Multi-threading::
* Multi-threading engines::
* Compiling and loading source files::
* Flags::
* Linter::


File: TheLogtalkHandbook-3.101.0.info,  Node: Enumerating objects categories and protocols,  Next: Enumerating objects categories and protocols properties,  Up: Built-in predicates

2.4.1 Enumerating objects, categories and protocols
---------------------------------------------------

'built-in predicate'

* Menu:

* current_category/1::
* current_object/1::
* current_protocol/1::


File: TheLogtalkHandbook-3.101.0.info,  Node: current_category/1,  Next: current_object/1,  Up: Enumerating objects categories and protocols

2.4.1.1 ‘current_category/1’
............................

* Menu:

* Description: Description<45>.
* Modes and number of proofs: Modes and number of proofs<8>.
* Errors: Errors<9>.
* Examples: Examples<46>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<45>,  Next: Modes and number of proofs<8>,  Up: current_category/1

2.4.1.2 Description
...................

     current_category(Category)

Enumerates, by backtracking, all currently defined categories.  All
categories are found, either static, dynamic, or built-in.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<8>,  Next: Errors<9>,  Prev: Description<45>,  Up: current_category/1

2.4.1.3 Modes and number of proofs
..................................

     current_category(?category_identifier) - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<9>,  Next: Examples<46>,  Prev: Modes and number of proofs<8>,  Up: current_category/1

2.4.1.4 Errors
..............

     ‘Category’ is neither a variable nor a valid category identifier:
          ‘type_error(category_identifier, Category)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<46>,  Prev: Errors<9>,  Up: current_category/1

2.4.1.5 Examples
................

     % enumerate the defined categories:
     | ?- current_category(Category).

     Category = core_messages ;
     ...

See also
........

*note abolish_category/1: f5, *note category_property/2: 12c, *note
create_category/4: 11a, *note complements_object/2: c3, *note
extends_category/2-3: 129, *note imports_category/2-3: c0.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: current_object/1,  Next: current_protocol/1,  Prev: current_category/1,  Up: Enumerating objects categories and protocols

2.4.1.6 ‘current_object/1’
..........................

* Menu:

* Description: Description<46>.
* Modes and number of proofs: Modes and number of proofs<9>.
* Errors: Errors<10>.
* Examples: Examples<47>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<46>,  Next: Modes and number of proofs<9>,  Up: current_object/1

2.4.1.7 Description
...................

     current_object(Object)

Enumerates, by backtracking, all currently defined objects.  All objects
are found, either static, dynamic or built-in.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<9>,  Next: Errors<10>,  Prev: Description<46>,  Up: current_object/1

2.4.1.8 Modes and number of proofs
..................................

     current_object(?object_identifier) - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<10>,  Next: Examples<47>,  Prev: Modes and number of proofs<9>,  Up: current_object/1

2.4.1.9 Errors
..............

     ‘Object’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Object)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<47>,  Prev: Errors<10>,  Up: current_object/1

2.4.1.10 Examples
.................

     % enumerate the defined objects:
     | ?- current_object(Object).

     Object = user ;
     Object = logtalk ;
     ...

See also
........

*note abolish_object/1: 64, *note create_object/4: 62, *note
object_property/2: c6, *note extends_object/2-3: bf, *note
instantiates_class/2-3: bd, *note specializes_class/2-3: be, *note
complements_object/2: c3.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: current_protocol/1,  Prev: current_object/1,  Up: Enumerating objects categories and protocols

2.4.1.11 ‘current_protocol/1’
.............................

* Menu:

* Description: Description<47>.
* Modes and number of proofs: Modes and number of proofs<10>.
* Errors: Errors<11>.
* Examples: Examples<48>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<47>,  Next: Modes and number of proofs<10>,  Up: current_protocol/1

2.4.1.12 Description
....................

     current_protocol(Protocol)

Enumerates, by backtracking, all currently defined protocols.  All
protocols are found, either static, dynamic, or built-in.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<10>,  Next: Errors<11>,  Prev: Description<47>,  Up: current_protocol/1

2.4.1.13 Modes and number of proofs
...................................

     current_protocol(?protocol_identifier) - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<11>,  Next: Examples<48>,  Prev: Modes and number of proofs<10>,  Up: current_protocol/1

2.4.1.14 Errors
...............

     ‘Protocol’ is neither a variable nor a valid protocol identifier:
          ‘type_error(protocol_identifier, Protocol)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<48>,  Prev: Errors<11>,  Up: current_protocol/1

2.4.1.15 Examples
.................

     % enumerate the defined protocols:
     | ?- current_protocol(Protocol).

     Protocol = expanding ;
     Protocol = monitoring ;
     Protocol = forwarding ;
     ...

See also
........

*note abolish_protocol/1: e6, *note create_protocol/3: e3, *note
protocol_property/2: f4, *note conforms_to_protocol/2-3: c2, *note
extends_protocol/2-3: f0, *note implements_protocol/2-3: c1.


File: TheLogtalkHandbook-3.101.0.info,  Node: Enumerating objects categories and protocols properties,  Next: Creating new objects categories and protocols,  Prev: Enumerating objects categories and protocols,  Up: Built-in predicates

2.4.2 Enumerating objects, categories and protocols properties
--------------------------------------------------------------

'built-in predicate'

* Menu:

* category_property/2::
* object_property/2::
* protocol_property/2::


File: TheLogtalkHandbook-3.101.0.info,  Node: category_property/2,  Next: object_property/2,  Up: Enumerating objects categories and protocols properties

2.4.2.1 ‘category_property/2’
.............................

* Menu:

* Description: Description<48>.
* Modes and number of proofs: Modes and number of proofs<11>.
* Errors: Errors<12>.
* Examples: Examples<49>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<48>,  Next: Modes and number of proofs<11>,  Up: category_property/2

2.4.2.2 Description
...................

     category_property(Category, Property)

Enumerates, by backtracking, the properties associated with the defined
categories.  The valid properties are listed in the language grammar
section on *note entity properties: c8. and described in the User Manual
section on *note category properties: 12a.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<11>,  Next: Errors<12>,  Prev: Description<48>,  Up: category_property/2

2.4.2.3 Modes and number of proofs
..................................

     category_property(?category_identifier, ?category_property) - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<12>,  Next: Examples<49>,  Prev: Modes and number of proofs<11>,  Up: category_property/2

2.4.2.4 Errors
..............

     ‘Category’ is neither a variable nor a valid category identifier:
          ‘type_error(category_identifier, Category)’
          
     ‘Property’ is neither a variable nor a callable term:
          ‘type_error(callable, Property)’
     ‘Property’ is a callable term but not a valid category property:
          ‘domain_error(category_property, Property)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<49>,  Prev: Errors<12>,  Up: category_property/2

2.4.2.5 Examples
................

     % enumerate the properties of the core_messages built-in category:
     | ?- category_property(core_messages, Property).

     Property = source_data ;
     Property = static ;
     Property = built_in ;
     ...

See also
........

*note abolish_category/1: f5, *note create_category/4: 11a, *note
current_category/1: f1, *note complements_object/2: c3, *note
extends_category/2-3: 129, *note imports_category/2-3: c0.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: object_property/2,  Next: protocol_property/2,  Prev: category_property/2,  Up: Enumerating objects categories and protocols properties

2.4.2.6 ‘object_property/2’
...........................

* Menu:

* Description: Description<49>.
* Modes and number of proofs: Modes and number of proofs<12>.
* Errors: Errors<13>.
* Examples: Examples<50>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<49>,  Next: Modes and number of proofs<12>,  Up: object_property/2

2.4.2.7 Description
...................

     object_property(Object, Property)

Enumerates, by backtracking, the properties associated with the defined
objects.  The valid properties are listed in the language grammar
section on *note entity properties: c8. and described in the User Manual
section on *note object properties: c5.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<12>,  Next: Errors<13>,  Prev: Description<49>,  Up: object_property/2

2.4.2.8 Modes and number of proofs
..................................

     object_property(?object_identifier, ?object_property) - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<13>,  Next: Examples<50>,  Prev: Modes and number of proofs<12>,  Up: object_property/2

2.4.2.9 Errors
..............

     ‘Object’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Object)’
     ‘Property’ is neither a variable nor a callable term:
          ‘type_error(callable, Property)’
     ‘Property’ is a callable term but not a valid object property:
          ‘domain_error(object_property, Property)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<50>,  Prev: Errors<13>,  Up: object_property/2

2.4.2.10 Examples
.................

     % enumerate the properties of the logtalk built-in object:
     | ?- object_property(logtalk, Property).

     Property = context_switching_calls ;
     Property = source_data ;
     Property = threaded ;
     Property = static ;
     Property = built_in ;
     ...

See also
........

*note abolish_object/1: 64, *note create_object/4: 62, *note
current_object/1: a6, *note extends_object/2-3: bf, *note
instantiates_class/2-3: bd, *note specializes_class/2-3: be, *note
complements_object/2: c3.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: protocol_property/2,  Prev: object_property/2,  Up: Enumerating objects categories and protocols properties

2.4.2.11 ‘protocol_property/2’
..............................

* Menu:

* Description: Description<50>.
* Modes and number of proofs: Modes and number of proofs<13>.
* Errors: Errors<14>.
* Examples: Examples<51>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<50>,  Next: Modes and number of proofs<13>,  Up: protocol_property/2

2.4.2.12 Description
....................

     protocol_property(Protocol, Property)

Enumerates, by backtracking, the properties associated with the
currently defined protocols.  The valid properties are listed in the
language grammar section on *note entity properties: c8. and described
in the User Manual section on *note protocol properties: f3.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<13>,  Next: Errors<14>,  Prev: Description<50>,  Up: protocol_property/2

2.4.2.13 Modes and number of proofs
...................................

     protocol_property(?protocol_identifier, ?protocol_property) - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<14>,  Next: Examples<51>,  Prev: Modes and number of proofs<13>,  Up: protocol_property/2

2.4.2.14 Errors
...............

     ‘Protocol’ is neither a variable nor a valid protocol identifier:
          ‘type_error(protocol_identifier, Protocol)’
     ‘Property’ is neither a variable nor a callable term:
          ‘type_error(callable, Property)’
     ‘Property’ is a callable term but not a valid protocol property:
          ‘domain_error(protocol_property, Property)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<51>,  Prev: Errors<14>,  Up: protocol_property/2

2.4.2.15 Examples
.................

     % enumerate the properties of the monitoring built-in protocol:
     | ?- protocol_property(monitoring, Property).

     Property = source_data ;
     Property = static ;
     Property = built_in ;
     ...

See also
........

*note abolish_protocol/1: e6, *note create_protocol/3: e3, *note
current_protocol/1: e0, *note conforms_to_protocol/2-3: c2, *note
extends_protocol/2-3: f0, *note implements_protocol/2-3: c1.


File: TheLogtalkHandbook-3.101.0.info,  Node: Creating new objects categories and protocols,  Next: Abolishing objects categories and protocols,  Prev: Enumerating objects categories and protocols properties,  Up: Built-in predicates

2.4.3 Creating new objects, categories and protocols
----------------------------------------------------

'built-in predicate'

* Menu:

* create_category/4::
* create_object/4::
* create_protocol/3::


File: TheLogtalkHandbook-3.101.0.info,  Node: create_category/4,  Next: create_object/4,  Up: Creating new objects categories and protocols

2.4.3.1 ‘create_category/4’
...........................

* Menu:

* Description: Description<51>.
* Modes and number of proofs: Modes and number of proofs<14>.
* Errors: Errors<15>.
* Examples: Examples<52>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<51>,  Next: Modes and number of proofs<14>,  Up: create_category/4

2.4.3.2 Description
...................

     create_category(Identifier, Relations, Directives, Clauses)

Creates a new, dynamic category.  This predicate is often used as a
primitive to implement high-level category creation methods.

Note that, when opting for runtime generated category identifiers, it’s
possible to run out of identifiers when using a *note backend Prolog
compiler: 34. with bounded integer support.  The portable solution, when
creating a large number of dynamic categories in long-running
applications, is to recycle, whenever possible, the identifiers.

When creating a new dynamic parametric category, access to the object
parameters must use the *note parameter/2: a2. built-in execution
context method.

When using Logtalk multi-threading features, predicates calling this
built-in predicate may need to be declared synchronized in order to
avoid race conditions.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<14>,  Next: Errors<15>,  Prev: Description<51>,  Up: create_category/4

2.4.3.3 Modes and number of proofs
..................................

     create_category(?category_identifier, @list(category_relation), @list(category_directive), @list(clause)) - one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<15>,  Next: Examples<52>,  Prev: Modes and number of proofs<14>,  Up: create_category/4

2.4.3.4 Errors
..............

     ‘Relations’, ‘Directives’, or ‘Clauses’ is a variable:
          ‘instantiation_error’
     ‘Identifier’ is neither a variable nor a valid category identifier:
          ‘type_error(category_identifier, Identifier)’
     ‘Identifier’ is a valid object identifier but one of its arguments, ‘Parameter’, is not a variable:
          ‘type_error(variable, Parameter)’
     ‘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.101.0.info,  Node: Examples<52>,  Prev: Errors<15>,  Up: create_category/4

2.4.3.5 Examples
................

     | ?- create_category(
             tolerances,
             [implements(comparing)],
             [],
             [epsilon(1e-15), (equal(X, Y) :- epsilon(E), abs(X-Y) =< E)]
          ).

See also
........

*note abolish_category/1: f5, *note category_property/2: 12c, *note
current_category/1: f1, *note complements_object/2: c3, *note
extends_category/2-3: 129, *note imports_category/2-3: c0.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: create_object/4,  Next: create_protocol/3,  Prev: create_category/4,  Up: Creating new objects categories and protocols

2.4.3.6 ‘create_object/4’
.........................

* Menu:

* Description: Description<52>.
* Modes and number of proofs: Modes and number of proofs<15>.
* Errors: Errors<16>.
* Examples: Examples<53>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<52>,  Next: Modes and number of proofs<15>,  Up: create_object/4

2.4.3.7 Description
...................

     create_object(Identifier, Relations, Directives, Clauses)

Creates a new, dynamic object.  The word *note object: 534. is used here
as a generic term.  This predicate can be used to create new prototypes,
instances, and classes.  This predicate is often used as a primitive to
implement high-level object creation methods.

Note that, when opting for runtime generated object identifiers, it’s
possible to run out of identifiers when using a *note backend Prolog
compiler: 34. with bounded integer support.  The portable solution, when
creating a large number of dynamic objects in long-running applications,
is to recycle, whenever possible, the identifiers.

When creating a new dynamic parametric object, access to the object
parameters must use the *note parameter/2: a2. built-in execution
context method.

Declared predicates (using scope directives in the ‘Directives’
argument) are implicitly declared also as dynamic.

When using Logtalk multi-threading features, predicates calling this
built-in predicate may need to be declared synchronized in order to
avoid race conditions.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<15>,  Next: Errors<16>,  Prev: Description<52>,  Up: create_object/4

2.4.3.8 Modes and number of proofs
..................................

     create_object(?object_identifier, @list(object_relation), @list(object_directive), @list(clause)) - one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<16>,  Next: Examples<53>,  Prev: Modes and number of proofs<15>,  Up: create_object/4

2.4.3.9 Errors
..............

     ‘Relations’, ‘Directives’, or ‘Clauses’ is a variable:
          ‘instantiation_error’
     ‘Identifier’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Identifier)’
     ‘Identifier’ is a valid object identifier but one of its arguments, ‘Parameter’, is not a variable:
          ‘type_error(variable, Parameter)’
     ‘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.101.0.info,  Node: Examples<53>,  Prev: Errors<16>,  Up: create_object/4

2.4.3.10 Examples
.................

     % create a stand-alone object (a prototype):
     | ?- create_object(
              translator,
              [],
              [public(int/2)],
              [int(0, zero)]
          ).

     % create a prototype derived from a parent prototype:
     | ?- create_object(
              mickey,
              [extends(mouse)],
              [public(alias/1)],
              [alias(mortimer)]
          ).

     % create a class instance:
     | ?- create_object(
              p1,
              [instantiates(person)],
              [],
              [name('Paulo Moura'), age(42)]
          ).

     % create a subclass:
     | ?- create_object(
              hovercraft,
              [specializes(vehicle)],
              [public([propeller/2, fan/2])],
              []
          ).

     % create an object with an initialization goal:
     | ?- create_object(
              runner,
              [instantiates(runners)],
              [initialization(::start)],
              [length(22), time(60)]
          ).

     % create an object supporting dynamic predicate declarations:
     | ?- create_object(
              database,
              [],
              [set_logtalk_flag(dynamic_declarations, allow)],
              []
          ).

See also
........

*note abolish_object/1: 64, *note current_object/1: a6, *note
object_property/2: c6, *note extends_object/2-3: bf, *note
instantiates_class/2-3: bd, *note specializes_class/2-3: be, *note
complements_object/2: c3.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: create_protocol/3,  Prev: create_object/4,  Up: Creating new objects categories and protocols

2.4.3.11 ‘create_protocol/3’
............................

* Menu:

* Description: Description<53>.
* Modes and number of proofs: Modes and number of proofs<16>.
* Errors: Errors<17>.
* Examples: Examples<54>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<53>,  Next: Modes and number of proofs<16>,  Up: create_protocol/3

2.4.3.12 Description
....................

     create_protocol(Identifier, Relations, Directives)

Creates a new, dynamic, protocol.  This predicate is often used as a
primitive to implement high-level protocol creation methods.

Note that, when opting for runtime generated protocol identifiers, it’s
possible to run out of identifiers when using a *note backend Prolog
compiler: 34. with bounded integer support.  The portable solution, when
creating a large number of dynamic protocols in long-running
applications, is to recycle, whenever possible, the identifiers.

When using Logtalk multi-threading features, predicates calling this
built-in predicate may need to be declared synchronized in order to
avoid race conditions.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<16>,  Next: Errors<17>,  Prev: Description<53>,  Up: create_protocol/3

2.4.3.13 Modes and number of proofs
...................................

     create_protocol(?protocol_identifier, @list(protocol_relation), @list(protocol_directive)) - one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<17>,  Next: Examples<54>,  Prev: Modes and number of proofs<16>,  Up: create_protocol/3

2.4.3.14 Errors
...............

     Either ‘Relations’ or ‘Directives’ is a variable:
          ‘instantiation_error’
     ‘Identifier’ is neither a variable nor a valid protocol identifier:
          ‘type_error(protocol_identifier, Identifier)’
     ‘Identifier’ is already in use:
          ‘permission_error(modify, category, Identifier)’
          ‘permission_error(modify, object, Identifier)’
          ‘permission_error(modify, protocol, Identifier)’
     ‘Relations’ is neither a variable nor a proper list:
          ‘type_error(list, Relations)’
     Repeated entity relation clause:
          ‘permission_error(repeat, entity_relation, extends/1)’
     ‘Directives’ is neither a variable nor a proper list:
          ‘type_error(list, Directives)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<54>,  Prev: Errors<17>,  Up: create_protocol/3

2.4.3.15 Examples
.................

     | ?- create_protocol(
             logging,
             [extends(monitoring)],
             [public([log_file/1, log_on/0, log_off/0])]
          ).

See also
........

*note abolish_protocol/1: e6, *note current_protocol/1: e0, *note
protocol_property/2: f4, *note conforms_to_protocol/2-3: c2, *note
extends_protocol/2-3: f0, *note implements_protocol/2-3: c1.


File: TheLogtalkHandbook-3.101.0.info,  Node: Abolishing objects categories and protocols,  Next: Objects categories and protocols relations,  Prev: Creating new objects categories and protocols,  Up: Built-in predicates

2.4.4 Abolishing objects, categories and protocols
--------------------------------------------------

'built-in predicate'

* Menu:

* abolish_category/1::
* abolish_object/1::
* abolish_protocol/1::


File: TheLogtalkHandbook-3.101.0.info,  Node: abolish_category/1,  Next: abolish_object/1,  Up: Abolishing objects categories and protocols

2.4.4.1 ‘abolish_category/1’
............................

* Menu:

* Description: Description<54>.
* Modes and number of proofs: Modes and number of proofs<17>.
* Errors: Errors<18>.
* Examples: Examples<55>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<54>,  Next: Modes and number of proofs<17>,  Up: abolish_category/1

2.4.4.2 Description
...................

     abolish_category(Category)

Abolishes a dynamic category.  The category identifier can then be
reused when creating a new category.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<17>,  Next: Errors<18>,  Prev: Description<54>,  Up: abolish_category/1

2.4.4.3 Modes and number of proofs
..................................

     abolish_category(+category_identifier) - one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<18>,  Next: Examples<55>,  Prev: Modes and number of proofs<17>,  Up: abolish_category/1

2.4.4.4 Errors
..............

     ‘Category’ is a variable:
          ‘instantiation_error’
     ‘Category’ is neither a variable nor a valid category identifier:
          ‘type_error(category_identifier, Category)’
     ‘Category’ is an identifier of a static category:
          ‘permission_error(modify, static_category, Category)’
     ‘Category’ does not exist:
          ‘existence_error(category, Category)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<55>,  Prev: Errors<18>,  Up: abolish_category/1

2.4.4.5 Examples
................

     | ?- abolish_category(monitoring).

See also
........

*note category_property/2: 12c, *note create_category/4: 11a, *note
current_category/1: f1. *note complements_object/2: c3, *note
extends_category/2-3: 129, *note imports_category/2-3: c0.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: abolish_object/1,  Next: abolish_protocol/1,  Prev: abolish_category/1,  Up: Abolishing objects categories and protocols

2.4.4.6 ‘abolish_object/1’
..........................

* Menu:

* Description: Description<55>.
* Modes and number of proofs: Modes and number of proofs<18>.
* Errors: Errors<19>.
* Examples: Examples<56>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<55>,  Next: Modes and number of proofs<18>,  Up: abolish_object/1

2.4.4.7 Description
...................

     abolish_object(Object)

Abolishes a dynamic object.  The object identifier can then be reused
when creating a new object.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<18>,  Next: Errors<19>,  Prev: Description<55>,  Up: abolish_object/1

2.4.4.8 Modes and number of proofs
..................................

     abolish_object(+object_identifier) - one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<19>,  Next: Examples<56>,  Prev: Modes and number of proofs<18>,  Up: abolish_object/1

2.4.4.9 Errors
..............

     ‘Object’ is a variable:
          ‘instantiation_error’
     ‘Object’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Object)’
     ‘Object’ is an identifier of a static object:
          ‘permission_error(modify, static_object, Object)’
     ‘Object’ does not exist:
          ‘existence_error(object, Object)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<56>,  Prev: Errors<19>,  Up: abolish_object/1

2.4.4.10 Examples
.................

     | ?- abolish_object(list).

See also
........

*note create_object/4: 62, *note current_object/1: a6, *note
object_property/2: c6, *note extends_object/2-3: bf, *note
instantiates_class/2-3: bd, *note specializes_class/2-3: be, *note
complements_object/2: c3.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: abolish_protocol/1,  Prev: abolish_object/1,  Up: Abolishing objects categories and protocols

2.4.4.11 ‘abolish_protocol/1’
.............................

* Menu:

* Description: Description<56>.
* Modes and number of proofs: Modes and number of proofs<19>.
* Errors: Errors<20>.
* Examples: Examples<57>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<56>,  Next: Modes and number of proofs<19>,  Up: abolish_protocol/1

2.4.4.12 Description
....................

     abolish_protocol(Protocol)

Abolishes a dynamic protocol.  The protocol identifier can then be
reused when creating a new protocol.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<19>,  Next: Errors<20>,  Prev: Description<56>,  Up: abolish_protocol/1

2.4.4.13 Modes and number of proofs
...................................

     abolish_protocol(@protocol_identifier) - one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<20>,  Next: Examples<57>,  Prev: Modes and number of proofs<19>,  Up: abolish_protocol/1

2.4.4.14 Errors
...............

     ‘Protocol’ is a variable:
          ‘instantiation_error’
     ‘Protocol’ is neither a variable nor a valid protocol identifier:
          ‘type_error(protocol_identifier, Protocol)’
     ‘Protocol’ is an identifier of a static protocol:
          ‘permission_error(modify, static_protocol, Protocol)’
     ‘Protocol’ does not exist:
          ‘existence_error(protocol, Protocol)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<57>,  Prev: Errors<20>,  Up: abolish_protocol/1

2.4.4.15 Examples
.................

     | ?- abolish_protocol(listp).

See also
........

*note create_protocol/3: e3, *note current_protocol/1: e0, *note
protocol_property/2: f4, *note conforms_to_protocol/2-3: c2, *note
extends_protocol/2-3: f0, *note implements_protocol/2-3: c1.


File: TheLogtalkHandbook-3.101.0.info,  Node: Objects categories and protocols relations,  Next: Event handling<2>,  Prev: Abolishing objects categories and protocols,  Up: Built-in predicates

2.4.5 Objects, categories, and protocols relations
--------------------------------------------------

'built-in predicate'

* Menu:

* extends_object/2-3::
* extends_protocol/2-3::
* extends_category/2-3::
* implements_protocol/2-3::
* conforms_to_protocol/2-3::
* complements_object/2::
* imports_category/2-3::
* instantiates_class/2-3::
* specializes_class/2-3::


File: TheLogtalkHandbook-3.101.0.info,  Node: extends_object/2-3,  Next: extends_protocol/2-3,  Up: Objects categories and protocols relations

2.4.5.1 ‘extends_object/2-3’
............................

* Menu:

* Description: Description<57>.
* Modes and number of proofs: Modes and number of proofs<20>.
* Errors: Errors<21>.
* Examples: Examples<58>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<57>,  Next: Modes and number of proofs<20>,  Up: extends_object/2-3

2.4.5.2 Description
...................

     extends_object(Prototype, Parent)
     extends_object(Prototype, Parent, Scope)

Enumerates, by backtracking, all pairs of objects such that the first
one extends the second.  The relation scope is represented by the atoms
‘public’, ‘protected’, and ‘private’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<20>,  Next: Errors<21>,  Prev: Description<57>,  Up: extends_object/2-3

2.4.5.3 Modes and number of proofs
..................................

     extends_object(?object_identifier, ?object_identifier) - zero_or_more
     extends_object(?object_identifier, ?object_identifier, ?scope) - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<21>,  Next: Examples<58>,  Prev: Modes and number of proofs<20>,  Up: extends_object/2-3

2.4.5.4 Errors
..............

     ‘Prototype’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Prototype)’
     ‘Parent’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Parent)’
     ‘Scope’ is neither a variable nor an atom:
          ‘type_error(atom, Scope)’
     ‘Scope’ is an atom but an invalid entity scope:
          ‘domain_error(scope, Scope)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<58>,  Prev: Errors<21>,  Up: extends_object/2-3

2.4.5.5 Examples
................

     % enumerate objects derived from the state_space prototype:
     | ?- extends_object(Object, state_space).

     % enumerate objects publicly derived from the list prototype:
     | ?- extends_object(Object, list, public).

See also
........

*note current_object/1: a6, *note instantiates_class/2-3: bd, *note
specializes_class/2-3: be.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: extends_protocol/2-3,  Next: extends_category/2-3,  Prev: extends_object/2-3,  Up: Objects categories and protocols relations

2.4.5.6 ‘extends_protocol/2-3’
..............................

* Menu:

* Description: Description<58>.
* Modes and number of proofs: Modes and number of proofs<21>.
* Errors: Errors<22>.
* Examples: Examples<59>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<58>,  Next: Modes and number of proofs<21>,  Up: extends_protocol/2-3

2.4.5.7 Description
...................

     extends_protocol(Protocol, ParentProtocol)
     extends_protocol(Protocol, ParentProtocol, Scope)

Enumerates, by backtracking, all pairs of protocols such that the first
one extends the second.  The relation scope is represented by the atoms
‘public’, ‘protected’, and ‘private’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<21>,  Next: Errors<22>,  Prev: Description<58>,  Up: extends_protocol/2-3

2.4.5.8 Modes and number of proofs
..................................

     extends_protocol(?protocol_identifier, ?protocol_identifier) - zero_or_more
     extends_protocol(?protocol_identifier, ?protocol_identifier, ?scope) - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<22>,  Next: Examples<59>,  Prev: Modes and number of proofs<21>,  Up: extends_protocol/2-3

2.4.5.9 Errors
..............

     ‘Protocol’ is neither a variable nor a valid protocol identifier:
          ‘type_error(protocol_identifier, Protocol)’
     ‘ParentProtocol’ is neither a variable nor a valid protocol identifier:
          ‘type_error(protocol_identifier, ParentProtocol)’
     ‘Scope’ is neither a variable nor an atom:
          ‘type_error(atom, Scope)’
     ‘Scope’ is an atom but an invalid entity scope:
          ‘domain_error(scope, Scope)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<59>,  Prev: Errors<22>,  Up: extends_protocol/2-3

2.4.5.10 Examples
.................

     % enumerate the protocols extended by the listp protocol:
     | ?- extends_protocol(listp, Protocol).

     % enumerate protocols that privately extend the termp protocol:
     | ?- extends_protocol(Protocol, termp, private).

See also
........

*note current_protocol/1: e0, *note implements_protocol/2-3: c1, *note
conforms_to_protocol/2-3: c2.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: extends_category/2-3,  Next: implements_protocol/2-3,  Prev: extends_protocol/2-3,  Up: Objects categories and protocols relations

2.4.5.11 ‘extends_category/2-3’
...............................

* Menu:

* Description: Description<59>.
* Modes and number of proofs: Modes and number of proofs<22>.
* Errors: Errors<23>.
* Examples: Examples<60>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<59>,  Next: Modes and number of proofs<22>,  Up: extends_category/2-3

2.4.5.12 Description
....................

     extends_category(Category, ParentCategory)
     extends_category(Category, ParentCategory, Scope)

Enumerates, by backtracking, all pairs of categories such that the first
one extends the second.  The relation scope is represented by the atoms
‘public’, ‘protected’, and ‘private’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<22>,  Next: Errors<23>,  Prev: Description<59>,  Up: extends_category/2-3

2.4.5.13 Modes and number of proofs
...................................

     extends_category(?category_identifier, ?category_identifier) - zero_or_more
     extends_category(?category_identifier, ?category_identifier, ?scope) - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<23>,  Next: Examples<60>,  Prev: Modes and number of proofs<22>,  Up: extends_category/2-3

2.4.5.14 Errors
...............

     ‘Category’ is neither a variable nor a valid protocol identifier:
          ‘type_error(category_identifier, Category)’
     ‘ParentCategory’ is neither a variable nor a valid protocol identifier:
          ‘type_error(category_identifier, ParentCategory)’
     ‘Scope’ is neither a variable nor an atom:
          ‘type_error(atom, Scope)’
     ‘Scope’ is an atom but an invalid entity scope:
          ‘domain_error(scope, Scope)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<60>,  Prev: Errors<23>,  Up: extends_category/2-3

2.4.5.15 Examples
.................

     % enumerate the categories extended by the derailleur category:
     | ?- extends_category(derailleur, Category).

     % enumerate categories that privately extend the basics category:
     | ?- extends_category(Category, basics, private).

See also
........

*note current_category/1: f1, *note complements_object/2: c3, *note
imports_category/2-3: c0.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: implements_protocol/2-3,  Next: conforms_to_protocol/2-3,  Prev: extends_category/2-3,  Up: Objects categories and protocols relations

2.4.5.16 ‘implements_protocol/2-3’
..................................

* Menu:

* Description: Description<60>.
* Modes and number of proofs: Modes and number of proofs<23>.
* Errors: Errors<24>.
* Examples: Examples<61>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<60>,  Next: Modes and number of proofs<23>,  Up: implements_protocol/2-3

2.4.5.17 Description
....................

     implements_protocol(Object, Protocol)
     implements_protocol(Category, Protocol)

     implements_protocol(Object, Protocol, Scope)
     implements_protocol(Category, Protocol, Scope)

Enumerates, by backtracking, all pairs of entities such that an object
or a category implements a protocol.  The relation scope is represented
by the atoms ‘public’, ‘protected’, and ‘private’.  This predicate only
returns direct implementation relations.  For a transitive closure, see
the *note conforms_to_protocol/2-3: c2. predicate.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<23>,  Next: Errors<24>,  Prev: Description<60>,  Up: implements_protocol/2-3

2.4.5.18 Modes and number of proofs
...................................

     implements_protocol(?object_identifier, ?protocol_identifier) - zero_or_more
     implements_protocol(?category_identifier, ?protocol_identifier) - zero_or_more

     implements_protocol(?object_identifier, ?protocol_identifier, ?scope) - zero_or_more
     implements_protocol(?category_identifier, ?protocol_identifier, ?scope) - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<24>,  Next: Examples<61>,  Prev: Modes and number of proofs<23>,  Up: implements_protocol/2-3

2.4.5.19 Errors
...............

     ‘Object’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Object)’
     ‘Category’ is neither a variable nor a valid category identifier:
          ‘type_error(category_identifier, Category)’
     ‘Protocol’ is neither a variable nor a valid protocol identifier:
          ‘type_error(protocol_identifier, Protocol)’
     ‘Scope’ is neither a variable nor an atom:
          ‘type_error(atom, Scope)’
     ‘Scope’ is an atom but an invalid entity scope:
          ‘domain_error(scope, Scope)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<61>,  Prev: Errors<24>,  Up: implements_protocol/2-3

2.4.5.20 Examples
.................

     % check that the list object implements the listp protocol:
     | ?- implements_protocol(list, listp).

     % check that the list object publicly implements the listp protocol:
     | ?- implements_protocol(list, listp, public).

     % enumerate only objects that implement the listp protocol:
     | ?- current_object(Object), implements_protocol(Object, listp).

     % enumerate only categories that implement the serialization protocol:
     | ?- current_category(Category), implements_protocol(Category, serialization).

See also
........

*note current_object/1: a6, *note current_protocol/1: e0, *note
current_category/1: f1, *note conforms_to_protocol/2-3: c2.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: conforms_to_protocol/2-3,  Next: complements_object/2,  Prev: implements_protocol/2-3,  Up: Objects categories and protocols relations

2.4.5.21 ‘conforms_to_protocol/2-3’
...................................

* Menu:

* Description: Description<61>.
* Modes and number of proofs: Modes and number of proofs<24>.
* Errors: Errors<25>.
* Examples: Examples<62>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<61>,  Next: Modes and number of proofs<24>,  Up: conforms_to_protocol/2-3

2.4.5.22 Description
....................

     conforms_to_protocol(Object, Protocol)
     conforms_to_protocol(Category, Protocol)

     conforms_to_protocol(Object, Protocol, Scope)
     conforms_to_protocol(Category, Protocol, Scope)

Enumerates, by backtracking, all pairs of entities such that an object
or a category conforms to a protocol.  The relation scope is represented
by the atoms ‘public’, ‘protected’, and ‘private’.  This predicate
implements a transitive closure for the protocol implementation
relation.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<24>,  Next: Errors<25>,  Prev: Description<61>,  Up: conforms_to_protocol/2-3

2.4.5.23 Modes and number of proofs
...................................

     conforms_to_protocol(?object_identifier, ?protocol_identifier) - zero_or_more
     conforms_to_protocol(?category_identifier, ?protocol_identifier) - zero_or_more

     conforms_to_protocol(?object_identifier, ?protocol_identifier, ?scope) - zero_or_more
     conforms_to_protocol(?category_identifier, ?protocol_identifier, ?scope) - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<25>,  Next: Examples<62>,  Prev: Modes and number of proofs<24>,  Up: conforms_to_protocol/2-3

2.4.5.24 Errors
...............

     ‘Object’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Object)’
     ‘Category’ is neither a variable nor a valid category identifier:
          ‘type_error(category_identifier, Category)’
     ‘Protocol’ is neither a variable nor a valid protocol identifier:
          ‘type_error(protocol_identifier, Protocol)’
     ‘Scope’ is neither a variable nor an atom:
          ‘type_error(atom, Scope)’
     ‘Scope’ is an atom but an invalid entity scope:
          ‘domain_error(scope, Scope)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<62>,  Prev: Errors<25>,  Up: conforms_to_protocol/2-3

2.4.5.25 Examples
.................

     % enumerate objects and categories that conform to the listp protocol:
     | ?- conforms_to_protocol(Object, listp).

     % enumerate objects and categories that privately conform to the listp protocol:
     | ?- conforms_to_protocol(Object, listp, private).

     % enumerate only objects that conform to the listp protocol:
     | ?- current_object(Object), conforms_to_protocol(Object, listp).

     % enumerate only categories that conform to the serialization protocol:
     | ?- current_category(Category), conforms_to_protocol(Category, serialization).

See also
........

*note current_object/1: a6, *note current_protocol/1: e0, *note
current_category/1: f1, *note implements_protocol/2-3: c1.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: complements_object/2,  Next: imports_category/2-3,  Prev: conforms_to_protocol/2-3,  Up: Objects categories and protocols relations

2.4.5.26 ‘complements_object/2’
...............................

* Menu:

* Description: Description<62>.
* Modes and number of proofs: Modes and number of proofs<25>.
* Errors: Errors<26>.
* Examples: Examples<63>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<62>,  Next: Modes and number of proofs<25>,  Up: complements_object/2

2.4.5.27 Description
....................

     complements_object(Category, Object)

Enumerates, by backtracking, all category–object pairs such that the
category explicitly complements the object.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<25>,  Next: Errors<26>,  Prev: Description<62>,  Up: complements_object/2

2.4.5.28 Modes and number of proofs
...................................

     complements_object(?category_identifier, ?object_identifier) - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<26>,  Next: Examples<63>,  Prev: Modes and number of proofs<25>,  Up: complements_object/2

2.4.5.29 Errors
...............

     ‘Category’ is neither a variable nor a valid category identifier:
          ‘type_error(category_identifier, Prototype)’
     ‘Object’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Parent)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<63>,  Prev: Errors<26>,  Up: complements_object/2

2.4.5.30 Examples
.................

     % check that the logging category complements the employee object:
     | ?- complements_object(logging, employee).

See also
........

*note current_category/1: f1, *note imports_category/2-3: c0.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: imports_category/2-3,  Next: instantiates_class/2-3,  Prev: complements_object/2,  Up: Objects categories and protocols relations

2.4.5.31 ‘imports_category/2-3’
...............................

* Menu:

* Description: Description<63>.
* Modes and number of proofs: Modes and number of proofs<26>.
* Errors: Errors<27>.
* Examples: Examples<64>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<63>,  Next: Modes and number of proofs<26>,  Up: imports_category/2-3

2.4.5.32 Description
....................

     imports_category(Object, Category)

     imports_category(Object, Category, Scope)

Enumerates, by backtracking, importation relations between objects and
categories.  The relation scope is represented by the atoms ‘public’,
‘protected’, and ‘private’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<26>,  Next: Errors<27>,  Prev: Description<63>,  Up: imports_category/2-3

2.4.5.33 Modes and number of proofs
...................................

     imports_category(?object_identifier, ?category_identifier) - zero_or_more
     imports_category(?object_identifier, ?category_identifier, ?scope) - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<27>,  Next: Examples<64>,  Prev: Modes and number of proofs<26>,  Up: imports_category/2-3

2.4.5.34 Errors
...............

     ‘Object’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Object)’
     ‘Category’ is neither a variable nor a valid category identifier:
          ‘type_error(category_identifier, Category)’
     ‘Scope’ is neither a variable nor an atom:
          ‘type_error(atom, Scope)’
     ‘Scope’ is an atom but an invalid entity scope:
          ‘domain_error(scope, Scope)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<64>,  Prev: Errors<27>,  Up: imports_category/2-3

2.4.5.35 Examples
.................

     % check that the xref_diagram object imports the diagram category:
     | ?- imports_category(xref_diagram, diagram).

     % enumerate the objects that privately import the diagram category:
     | ?- imports_category(Object, diagram, private).

See also
........

*note current_category/1: f1, *note complements_object/2: c3.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: instantiates_class/2-3,  Next: specializes_class/2-3,  Prev: imports_category/2-3,  Up: Objects categories and protocols relations

2.4.5.36 ‘instantiates_class/2-3’
.................................

* Menu:

* Description: Description<64>.
* Modes and number of proofs: Modes and number of proofs<27>.
* Errors: Errors<28>.
* Examples: Examples<65>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<64>,  Next: Modes and number of proofs<27>,  Up: instantiates_class/2-3

2.4.5.37 Description
....................

     instantiates_class(Instance, Class)
     instantiates_class(Instance, Class, Scope)

Enumerates, by backtracking, all pairs of objects such that the first
one instantiates the second.  The relation scope is represented by the
atoms ‘public’, ‘protected’, and ‘private’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<27>,  Next: Errors<28>,  Prev: Description<64>,  Up: instantiates_class/2-3

2.4.5.38 Modes and number of proofs
...................................

     instantiates_class(?object_identifier, ?object_identifier) - zero_or_more
     instantiates_class(?object_identifier, ?object_identifier, ?scope) - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<28>,  Next: Examples<65>,  Prev: Modes and number of proofs<27>,  Up: instantiates_class/2-3

2.4.5.39 Errors
...............

     ‘Instance’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Instance)’
     ‘Class’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Class)’
     ‘Scope’ is neither a variable nor an atom:
          ‘type_error(atom, Scope)’
     ‘Scope’ is an atom but an invalid entity scope:
          ‘domain_error(scope, Scope)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<65>,  Prev: Errors<28>,  Up: instantiates_class/2-3

2.4.5.40 Examples
.................

     % check that the water_jug is an instante of state_space:
     | ?- instantiates_class(water_jug, state_space).

     % enumerate the state_space instances where the
     % instantiation relation is public:
     | ?- instantiates_class(Space, state_space, public).

See also
........

*note current_object/1: a6, *note extends_object/2-3: bf, *note
specializes_class/2-3: be.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: specializes_class/2-3,  Prev: instantiates_class/2-3,  Up: Objects categories and protocols relations

2.4.5.41 ‘specializes_class/2-3’
................................

* Menu:

* Description: Description<65>.
* Modes and number of proofs: Modes and number of proofs<28>.
* Errors: Errors<29>.
* Examples: Examples<66>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<65>,  Next: Modes and number of proofs<28>,  Up: specializes_class/2-3

2.4.5.42 Description
....................

     specializes_class(Class, Superclass)
     specializes_class(Class, Superclass, Scope)

Enumerates, by backtracking, all pairs of objects such that the first
one specializes the second.  The relation scope is represented by the
atoms ‘public’, ‘protected’, and ‘private’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<28>,  Next: Errors<29>,  Prev: Description<65>,  Up: specializes_class/2-3

2.4.5.43 Modes and number of proofs
...................................

     specializes_class(?object_identifier, ?object_identifier) - zero_or_more
     specializes_class(?object_identifier, ?object_identifier, ?scope) - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<29>,  Next: Examples<66>,  Prev: Modes and number of proofs<28>,  Up: specializes_class/2-3

2.4.5.44 Errors
...............

     ‘Class’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Class)’
     ‘Superclass’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Superclass)’
     ‘Scope’ is neither a variable nor an atom:
          ‘type_error(atom, Scope)’
     ‘Scope’ is an atom but an invalid entity scope:
          ‘domain_error(scope, Scope)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<66>,  Prev: Errors<29>,  Up: specializes_class/2-3

2.4.5.45 Examples
.................

     % enumerate the state_space subclasses:
     | ?- specializes_class(Subclass, state_space).

     % enumerate the state_space subclasses where the
     % specialization relation is public:
     | ?- specializes_class(Subclass, state_space, public).

See also
........

*note current_object/1: a6, *note extends_object/2-3: bf, *note
instantiates_class/2-3: bd.


File: TheLogtalkHandbook-3.101.0.info,  Node: Event handling<2>,  Next: Multi-threading,  Prev: Objects categories and protocols relations,  Up: Built-in predicates

2.4.6 Event handling
--------------------

'built-in predicate'

* Menu:

* abolish_events/5::
* current_event/5::
* define_events/5::


File: TheLogtalkHandbook-3.101.0.info,  Node: abolish_events/5,  Next: current_event/5,  Up: Event handling<2>

2.4.6.1 ‘abolish_events/5’
..........................

* Menu:

* Description: Description<66>.
* Modes and number of proofs: Modes and number of proofs<29>.
* Errors: Errors<30>.
* Examples: Examples<67>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<66>,  Next: Modes and number of proofs<29>,  Up: abolish_events/5

2.4.6.2 Description
...................

     abolish_events(Event, Object, Message, Sender, Monitor)

Abolishes all matching events.  The two types of events are represented
by the atoms ‘before’ and ‘after’.  When the predicate is called with
the first argument unbound, both types of events are abolished.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<29>,  Next: Errors<30>,  Prev: Description<66>,  Up: abolish_events/5

2.4.6.3 Modes and number of proofs
..................................

     abolish_events(@term, @term, @term, @term, @term) - one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<30>,  Next: Examples<67>,  Prev: Modes and number of proofs<29>,  Up: abolish_events/5

2.4.6.4 Errors
..............

     ‘Event’ is neither a variable nor a valid event identifier:
          ‘type_error(event, Event)’
     ‘Object’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Object)’
     ‘Message’ is neither a variable nor a callable term:
          ‘type_error(callable, Message)’
     ‘Sender’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Sender)’
     ‘Monitor’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Monitor)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<67>,  Prev: Errors<30>,  Up: abolish_events/5

2.4.6.5 Examples
................

     % abolish all events for messages sent to the "list"
     % object being monitored by the "debugger" object:
     | ?- abolish_events(_, list, _, _, debugger).

See also
........

*note current_event/5: 21e, *note define_events/5: 218, *note before/3:
101, *note after/3: 102.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: current_event/5,  Next: define_events/5,  Prev: abolish_events/5,  Up: Event handling<2>

2.4.6.6 ‘current_event/5’
.........................

* Menu:

* Description: Description<67>.
* Modes and number of proofs: Modes and number of proofs<30>.
* Errors: Errors<31>.
* Examples: Examples<68>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<67>,  Next: Modes and number of proofs<30>,  Up: current_event/5

2.4.6.7 Description
...................

     current_event(Event, Object, Message, Sender, Monitor)

Enumerates, by backtracking, all defined events.  The two types of
events are represented by the atoms ‘before’ and ‘after’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<30>,  Next: Errors<31>,  Prev: Description<67>,  Up: current_event/5

2.4.6.8 Modes and number of proofs
..................................

     current_event(?event, ?term, ?term, ?term, ?object_identifier) - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<31>,  Next: Examples<68>,  Prev: Modes and number of proofs<30>,  Up: current_event/5

2.4.6.9 Errors
..............

     ‘Event’ is neither a variable nor a valid event identifier:
          ‘type_error(event, Event)’
     ‘Object’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Object)’
     ‘Message’ is neither a variable nor a callable term:
          ‘type_error(callable, Message)’
     ‘Sender’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Sender)’
     ‘Monitor’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Monitor)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<68>,  Prev: Errors<31>,  Up: current_event/5

2.4.6.10 Examples
.................

     % enumerate all events monitored by the "debugger" object:
     | ?- current_event(Event, Object, Message, Sender, debugger).

See also
........

*note abolish_events/5: 21b, *note define_events/5: 218, *note before/3:
101, *note after/3: 102.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: define_events/5,  Prev: current_event/5,  Up: Event handling<2>

2.4.6.11 ‘define_events/5’
..........................

* Menu:

* Description: Description<68>.
* Modes and number of proofs: Modes and number of proofs<31>.
* Errors: Errors<32>.
* Examples: Examples<69>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<68>,  Next: Modes and number of proofs<31>,  Up: define_events/5

2.4.6.12 Description
....................

     define_events(Event, Object, Message, Sender, Monitor)

Defines a new set of events.  The two types of events are represented by
the atoms ‘before’ and ‘after’.  When the predicate is called with the
first argument unbound, both types of events are defined.  The object
‘Monitor’ must define the event handler methods required by the ‘Event’
argument.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<31>,  Next: Errors<32>,  Prev: Description<68>,  Up: define_events/5

2.4.6.13 Modes and number of proofs
...................................

     define_events(@term, @term, @term, @term, +object_identifier) - one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<32>,  Next: Examples<69>,  Prev: Modes and number of proofs<31>,  Up: define_events/5

2.4.6.14 Errors
...............

     ‘Event’ is neither a variable nor a valid event identifier:
          ‘type_error(event, Event)’
     ‘Object’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Object)’
     ‘Message’ is neither a variable nor a callable term:
          ‘type_error(callable, Message)’
     ‘Sender’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Sender)’
     ‘Monitor’ is a variable:
          ‘instantiation_error’
     ‘Monitor’ is neither a variable nor a valid object identifier:
          ‘type_error(object_identifier, Monitor)’
     ‘Monitor’ does not define the required ‘before/3’ method:
          ‘existence_error(procedure, before/3)’
     ‘Monitor’ does not define the required ‘after/3’ method:
          ‘existence_error(procedure, after/3)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<69>,  Prev: Errors<32>,  Up: define_events/5

2.4.6.15 Examples
.................

     % define "debugger" as a monitor for member/2 messages
     % sent to the "list" object:
     | ?- define_events(_, list, member(_, _), _ , debugger).

See also
........

*note abolish_events/5: 21b, *note current_event/5: 21e, *note before/3:
101, *note after/3: 102.


File: TheLogtalkHandbook-3.101.0.info,  Node: Multi-threading,  Next: Multi-threading engines,  Prev: Event handling<2>,  Up: Built-in predicates

2.4.7 Multi-threading
---------------------

'built-in predicate'

* Menu:

* threaded/1::
* threaded_call/1-2::
* threaded_once/1-2::
* threaded_ignore/1::
* threaded_exit/1-2::
* threaded_peek/1-2::
* threaded_cancel/1::
* threaded_wait/1::
* threaded_notify/1::


File: TheLogtalkHandbook-3.101.0.info,  Node: threaded/1,  Next: threaded_call/1-2,  Up: Multi-threading

2.4.7.1 ‘threaded/1’
....................

* Menu:

* Description: Description<69>.
* Meta-predicate template::
* Modes and number of proofs: Modes and number of proofs<32>.
* Errors: Errors<33>.
* Examples: Examples<70>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<69>,  Next: Meta-predicate template,  Up: threaded/1

2.4.7.2 Description
...................

     threaded(Conjunction)
     threaded(Disjunction)

Proves each goal in a conjunction or a disjunction of goals in its own
thread.  This meta-predicate is deterministic and opaque to cuts.  The
predicate argument is 'not' flattened.

When the argument is a conjunction of goals, a call to this predicate
blocks until either all goals succeed, one of the goals fail, or one of
the goals generate an exception; the failure of one of the goals or an
exception on the execution of one of the goals results in the
termination of the remaining threads.  The predicate call is true 'iff'
all goals are true.  The predicate call fails if all goals fail.  When
one of the goals throws an exception, the predicate call re-throws that
exception.

When the argument is a disjunction of goals, a call to this predicate
blocks until either one of the goals succeeds or all the goals fail or
throw exceptions; the success of one of the goals results in the
termination of the remaining threads.  The predicate call is true 'iff'
one of the goals is true.  The predicate call fails if all goals fails.
When no goal succeeds and one of the goals throws an exception, the
predicate call re-throws that exception.

When the predicate argument is neither a conjunction nor a disjunction
of goals, no threads are used.  In this case, the predicate call is
equivalent to a ‘once/1’ predicate call.

A dedicated message queue is used per call of this predicate to collect
the individual goal results.

     Note: This predicate requires a *note backend Prolog compiler: 34.
     providing compatible multi-threading primitives.  The value of the
     read-only *note threads: 225. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.101.0.info,  Node: Meta-predicate template,  Next: Modes and number of proofs<32>,  Prev: Description<69>,  Up: threaded/1

2.4.7.3 Meta-predicate template
...............................

     threaded(0)


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<32>,  Next: Errors<33>,  Prev: Meta-predicate template,  Up: threaded/1

2.4.7.4 Modes and number of proofs
..................................

     threaded(+callable) - zero_or_one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<33>,  Next: Examples<70>,  Prev: Modes and number of proofs<32>,  Up: threaded/1

2.4.7.5 Errors
..............

     ‘Goals’ is a variable:
          ‘instantiation_error’
     A goal in ‘Goals’ is a variable:
          ‘instantiation_error’
     ‘Goals’ is neither a variable nor a callable term:
          ‘type_error(callable, Goals)’
     A goal ‘Goal’ in ‘Goals’ is neither a variable nor a callable term:
          ‘type_error(callable, Goal)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<70>,  Prev: Errors<33>,  Up: threaded/1

2.4.7.6 Examples
................

     Prove a conjunction of goals, each one in its own thread:
          ‘threaded((Goal, Goals))’
     Prove a disjunction of goals, each one in its own thread:
          ‘threaded((Goal; Goals))’

See also
........

*note threaded_call/1-2: 230, *note threaded_once/1-2: 232, *note
threaded_ignore/1: 237, *note synchronized/1: 74.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: threaded_call/1-2,  Next: threaded_once/1-2,  Prev: threaded/1,  Up: Multi-threading

2.4.7.7 ‘threaded_call/1-2’
...........................

* Menu:

* Description: Description<70>.
* Meta-predicate template: Meta-predicate template<2>.
* Modes and number of proofs: Modes and number of proofs<33>.
* Errors: Errors<34>.
* Examples: Examples<71>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<70>,  Next: Meta-predicate template<2>,  Up: threaded_call/1-2

2.4.7.8 Description
...................

     threaded_call(Goal)
     threaded_call(Goal, Tag)

Proves ‘Goal’ asynchronously using a new thread.  The argument can be a
message-sending goal.  Calls to this predicate always succeed and return
immediately.  The results (success, failure, or exception) are sent back
to the message queue of the object containing the call (*note this:
114.) and can be retrieved by calling the *note threaded_exit/1: 231.
predicate.

The ‘threaded_call/2’ variant returns a threaded call identifier tag
that can be used with the *note threaded_exit/2: 231. and *note
threaded_cancel/1: 234. predicates.  Tags shall be regarded as opaque
terms; users shall not rely on their type.

     Note: This predicate requires a *note backend Prolog compiler: 34.
     providing compatible multi-threading primitives.  The value of the
     read-only *note threads: 225. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.101.0.info,  Node: Meta-predicate template<2>,  Next: Modes and number of proofs<33>,  Prev: Description<70>,  Up: threaded_call/1-2

2.4.7.9 Meta-predicate template
...............................

     threaded_call(0)
     threaded_call(0, *)


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<33>,  Next: Errors<34>,  Prev: Meta-predicate template<2>,  Up: threaded_call/1-2

2.4.7.10 Modes and number of proofs
...................................

     threaded_call(@callable) - one
     threaded_call(@callable, --nonvar) - one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<34>,  Next: Examples<71>,  Prev: Modes and number of proofs<33>,  Up: threaded_call/1-2

2.4.7.11 Errors
...............

     ‘Goal’ is a variable:
          ‘instantiation_error’
     ‘Goal’ is neither a variable nor a callable term:
          ‘type_error(callable, Goal)’
     ‘Tag’ is not a variable:
          ‘uninstantiation_error(Tag)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<71>,  Prev: Errors<34>,  Up: threaded_call/1-2

2.4.7.12 Examples
.................

     Prove ‘Goal’ asynchronously in a new thread:
          ‘threaded_call(Goal)’
     Prove ‘::Message’ asynchronously in a new thread:
          ‘threaded_call(::Message)’
     Prove ‘Object::Message’ asynchronously in a new thread:
          ‘threaded_call(Object::Message)’

See also
........

*note threaded_exit/1-2: 231, *note threaded_ignore/1: 237, *note
threaded_once/1-2: 232, *note threaded_peek/1-2: 233, *note
threaded_cancel/1: 234, *note threaded/1: 22b, *note synchronized/1: 74.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: threaded_once/1-2,  Next: threaded_ignore/1,  Prev: threaded_call/1-2,  Up: Multi-threading

2.4.7.13 ‘threaded_once/1-2’
............................

* Menu:

* Description: Description<71>.
* Meta-predicate template: Meta-predicate template<3>.
* Modes and number of proofs: Modes and number of proofs<34>.
* Errors: Errors<35>.
* Examples: Examples<72>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<71>,  Next: Meta-predicate template<3>,  Up: threaded_once/1-2

2.4.7.14 Description
....................

     threaded_once(Goal)
     threaded_once(Goal, Tag)

Proves ‘Goal’ asynchronously using a new thread.  Only the first goal
solution is found.  The argument can be a message-sending goal.  This
call always succeeds.  The result (success, failure, or exception) is
sent back to the message queue of the object containing the call (*note
this: 114.).

The ‘threaded_once/2’ variant returns a threaded call identifier tag
that can be used with the *note threaded_exit/2: 231. and *note
threaded_cancel/1: 234. predicates.  Tags shall be regarded as opaque
terms; users shall not rely on their type.

     Note: This predicate requires a *note backend Prolog compiler: 34.
     providing compatible multi-threading primitives.  The value of the
     read-only *note threads: 225. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.101.0.info,  Node: Meta-predicate template<3>,  Next: Modes and number of proofs<34>,  Prev: Description<71>,  Up: threaded_once/1-2

2.4.7.15 Meta-predicate template
................................

     threaded_once(0)
     threaded_once(0, *)


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<34>,  Next: Errors<35>,  Prev: Meta-predicate template<3>,  Up: threaded_once/1-2

2.4.7.16 Modes and number of proofs
...................................

     threaded_once(@callable) - one
     threaded_once(@callable, --nonvar) - one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<35>,  Next: Examples<72>,  Prev: Modes and number of proofs<34>,  Up: threaded_once/1-2

2.4.7.17 Errors
...............

     Goal is a variable:
          ‘instantiation_error’
     Goal is neither a variable nor a callable term:
          ‘type_error(callable, Goal)’
     Tag is not a variable:
          ‘uninstantiation_error(Tag)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<72>,  Prev: Errors<35>,  Up: threaded_once/1-2

2.4.7.18 Examples
.................

     Prove ‘Goal’ asynchronously in a new thread:
          ‘threaded_once(Goal)’
     Prove ‘::Message’ asynchronously in a new thread:
          ‘threaded_once(::Message)’
     Prove ‘Object::Message’ asynchronously in a new thread:
          ‘threaded_once(Object::Message)’

See also
........

*note threaded_call/1-2: 230, *note threaded_exit/1-2: 231, *note
threaded_ignore/1: 237, *note threaded_peek/1-2: 233, *note
threaded_cancel/1: 234, *note threaded/1: 22b, *note synchronized/1: 74.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: threaded_ignore/1,  Next: threaded_exit/1-2,  Prev: threaded_once/1-2,  Up: Multi-threading

2.4.7.19 ‘threaded_ignore/1’
............................

* Menu:

* Description: Description<72>.
* Meta-predicate template: Meta-predicate template<4>.
* Modes and number of proofs: Modes and number of proofs<35>.
* Errors: Errors<36>.
* Examples: Examples<73>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<72>,  Next: Meta-predicate template<4>,  Up: threaded_ignore/1

2.4.7.20 Description
....................

     threaded_ignore(Goal)

Proves ‘Goal’ asynchronously using a new thread.  Only the first goal
solution is found.  The argument can be a message-sending goal.  This
call always succeeds, independently of the result (success, failure, or
exception), which is simply discarded instead of being sent back to the
message queue of the object containing the call (*note this: 114.).

     Note: This predicate requires a *note backend Prolog compiler: 34.
     providing compatible multi-threading primitives.  The value of the
     read-only *note threads: 225. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.101.0.info,  Node: Meta-predicate template<4>,  Next: Modes and number of proofs<35>,  Prev: Description<72>,  Up: threaded_ignore/1

2.4.7.21 Meta-predicate template
................................

     threaded_ignore(0)


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<35>,  Next: Errors<36>,  Prev: Meta-predicate template<4>,  Up: threaded_ignore/1

2.4.7.22 Modes and number of proofs
...................................

     threaded_ignore(@callable) - one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<36>,  Next: Examples<73>,  Prev: Modes and number of proofs<35>,  Up: threaded_ignore/1

2.4.7.23 Errors
...............

     ‘Goal’ is a variable:
          ‘instantiation_error’
     ‘Goal’ is neither a variable nor a callable term:
          ‘type_error(callable, Goal)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<73>,  Prev: Errors<36>,  Up: threaded_ignore/1

2.4.7.24 Examples
.................

     Prove ‘Goal’ asynchronously in a new thread:
          ‘threaded_ignore(Goal)’
     Prove ‘::Message’ asynchronously in a new thread:
          ‘threaded_ignore(::Message)’
     Prove ‘Object::Message’ asynchronously in a new thread:
          ‘threaded_ignore(Object::Message)’

See also
........

*note threaded_call/1-2: 230, *note threaded_exit/1-2: 231, *note
threaded_once/1-2: 232, *note threaded_peek/1-2: 233, *note threaded/1:
22b, *note synchronized/1: 74.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: threaded_exit/1-2,  Next: threaded_peek/1-2,  Prev: threaded_ignore/1,  Up: Multi-threading

2.4.7.25 ‘threaded_exit/1-2’
............................

* Menu:

* Description: Description<73>.
* Modes and number of proofs: Modes and number of proofs<36>.
* Errors: Errors<37>.
* Examples: Examples<74>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<73>,  Next: Modes and number of proofs<36>,  Up: threaded_exit/1-2

2.4.7.26 Description
....................

     threaded_exit(Goal)
     threaded_exit(Goal, Tag)

Retrieves the result of proving ‘Goal’ in a new thread.  This predicate
blocks execution until the reply is sent to the *note this: 114. message
queue by the thread executing the goal.  When there is no thread proving
the goal, the predicate generates an exception.  This predicate is
non-deterministic, providing access to any alternative solutions of its
argument.

The argument of this predicate should be a 'variant' of the argument of
the corresponding *note threaded_call/1: 230. or *note threaded_once/1:
232. call.  When the predicate argument is subsumed by the
‘threaded_call/1’ or ‘threaded_once/1’ call argument, the
‘threaded_exit/1’ call will succeed iff its argument is a solution of
the (more general) goal.

The ‘threaded_exit/2’ variant accepts a threaded call identifier tag
generated by the calls to the *note threaded_call/2: 230. and *note
threaded_once/2: 232. predicates.  Tags shall be regarded as an opaque
term; users shall not rely on their type.

     Note: This predicate requires a *note backend Prolog compiler: 34.
     providing compatible multi-threading primitives.  The value of the
     read-only *note threads: 225. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<36>,  Next: Errors<37>,  Prev: Description<73>,  Up: threaded_exit/1-2

2.4.7.27 Modes and number of proofs
...................................

     threaded_exit(+callable) - zero_or_more
     threaded_exit(+callable, +nonvar) - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<37>,  Next: Examples<74>,  Prev: Modes and number of proofs<36>,  Up: threaded_exit/1-2

2.4.7.28 Errors
...............

     ‘Goal’ is a variable:
          ‘instantiation_error’
     ‘Goal’ is neither a variable nor a callable term:
          ‘type_error(callable, Goal)’
     No thread is running for proving ‘Goal’ in the ‘Object’ calling context:
          ‘existence_error(thread, Object)’
     ‘Tag’ is a variable:
          ‘instantiation_error’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<74>,  Prev: Errors<37>,  Up: threaded_exit/1-2

2.4.7.29 Examples
.................

     To retrieve an asynchronous goal proof result:
          ‘threaded_exit(Goal)’
     To retrieve an asynchronous message to 'self' result:
          ‘threaded_exit(::Goal)’
     To retrieve an asynchronous message result:
          ‘threaded_exit(Object::Goal)’

See also
........

*note threaded_call/1-2: 230, *note threaded_ignore/1: 237, *note
threaded_once/1-2: 232, *note threaded_peek/1-2: 233, *note
threaded_cancel/1: 234, *note threaded/1: 22b.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: threaded_peek/1-2,  Next: threaded_cancel/1,  Prev: threaded_exit/1-2,  Up: Multi-threading

2.4.7.30 ‘threaded_peek/1-2’
............................

* Menu:

* Description: Description<74>.
* Modes and number of proofs: Modes and number of proofs<37>.
* Errors: Errors<38>.
* Examples: Examples<75>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<74>,  Next: Modes and number of proofs<37>,  Up: threaded_peek/1-2

2.4.7.31 Description
....................

     threaded_peek(Goal)
     threaded_peek(Goal, Tag)

Checks if the result of proving ‘Goal’ in a new thread is already
available.  This call succeeds or fails without blocking execution
waiting for a reply to be available.  When there is no thread proving
the goal, the predicate generates an exception.

The argument of this predicate should be a 'variant' of the argument of
the corresponding *note threaded_call/1: 230. or *note threaded_once/1:
232. call.  When the predicate argument is subsumed by the
‘threaded_call/1’ or ‘threaded_once/1’ call argument, the
‘threaded_peek/1’ call will succeed iff its argument unifies with an
already available solution of the (more general) goal.

The ‘threaded_peek/2’ variant accepts a threaded call identifier tag
generated by the calls to the *note threaded_call/2: 230. and *note
threaded_once/2: 232. predicates.  Tags shall be regarded as an opaque
term; users shall not rely on their type.

     Note: This predicate requires a *note backend Prolog compiler: 34.
     providing compatible multi-threading primitives.  The value of the
     read-only *note threads: 225. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<37>,  Next: Errors<38>,  Prev: Description<74>,  Up: threaded_peek/1-2

2.4.7.32 Modes and number of proofs
...................................

     threaded_peek(+callable) - zero_or_one
     threaded_peek(+callable, +nonvar) - zero_or_one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<38>,  Next: Examples<75>,  Prev: Modes and number of proofs<37>,  Up: threaded_peek/1-2

2.4.7.33 Errors
...............

     ‘Goal’ is a variable:
          ‘instantiation_error’
     ‘Goal’ is neither a variable nor a callable term:
          ‘type_error(callable, Goal)’
     No thread is running for proving ‘Goal’ in the ‘Object’ calling context:
          ‘existence_error(thread, Object)’
     ‘Tag’ is a variable:
          ‘instantiation_error’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<75>,  Prev: Errors<38>,  Up: threaded_peek/1-2

2.4.7.34 Examples
.................

     To check for an asynchronous goal proof result:
          ‘threaded_peek(Goal)’
     To check for an asynchronous message to 'self' result:
          ‘threaded_peek(::Goal)’
     To check for an asynchronous message result:
          ‘threaded_peek(Object::Goal)’

See also
........

*note threaded_call/1-2: 230, *note threaded_exit/1-2: 231, *note
threaded_ignore/1: 237, *note threaded_once/1-2: 232, *note
threaded_cancel/1: 234, *note threaded/1: 22b.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: threaded_cancel/1,  Next: threaded_wait/1,  Prev: threaded_peek/1-2,  Up: Multi-threading

2.4.7.35 ‘threaded_cancel/1’
............................

* Menu:

* Description: Description<75>.
* Modes and number of proofs: Modes and number of proofs<38>.
* Errors: Errors<39>.
* Examples: Examples<76>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<75>,  Next: Modes and number of proofs<38>,  Up: threaded_cancel/1

2.4.7.36 Description
....................

     threaded_cancel(Tag)

Cancels a tagged threaded call.  When there is no asynchronous call with
the given tag, calling this predicate succeeds assuming the asynchronous
call has already terminated or canceled.  The threaded call identifier
tag is generated by calls to the *note threaded_call/2: 230. and *note
threaded_once/2: 232. predicates.  Tags shall be regarded as an opaque
term; users shall not rely on their type.

     Note: This predicate requires a *note backend Prolog compiler: 34.
     providing compatible multi-threading primitives.  The value of the
     read-only *note threads: 225. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<38>,  Next: Errors<39>,  Prev: Description<75>,  Up: threaded_cancel/1

2.4.7.37 Modes and number of proofs
...................................

     threaded_cancel(+nonvar) - one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<39>,  Next: Examples<76>,  Prev: Modes and number of proofs<38>,  Up: threaded_cancel/1

2.4.7.38 Errors
...............

     ‘Tag’ is a variable:
          ‘instantiation_error’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<76>,  Prev: Errors<39>,  Up: threaded_cancel/1

2.4.7.39 Examples
.................

(none)

See also
........

*note threaded_call/1-2: 230, *note threaded_exit/1-2: 231, *note
threaded_ignore/1: 237, *note threaded_once/1-2: 232, *note threaded/1:
22b.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: threaded_wait/1,  Next: threaded_notify/1,  Prev: threaded_cancel/1,  Up: Multi-threading

2.4.7.40 ‘threaded_wait/1’
..........................

* Menu:

* Description: Description<76>.
* Modes and number of proofs: Modes and number of proofs<39>.
* Errors: Errors<40>.
* Examples: Examples<77>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<76>,  Next: Modes and number of proofs<39>,  Up: threaded_wait/1

2.4.7.41 Description
....................

     threaded_wait(Term)
     threaded_wait([Term| Terms])

Suspends the thread making the call until a notification is received
that unifies with ‘Term’.  The call must be made within the same object
(*note this: 114.) containing the calls to the *note threaded_notify/1:
23c. predicate that will eventually send the notification.  The argument
may also be a list of notifications, ‘[Term| Terms]’.  In this case, the
thread making the call will suspend until all notifications in the list
are received.

     Note: This predicate requires a *note backend Prolog compiler: 34.
     providing compatible multi-threading primitives.  The value of the
     read-only *note threads: 225. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<39>,  Next: Errors<40>,  Prev: Description<76>,  Up: threaded_wait/1

2.4.7.42 Modes and number of proofs
...................................

     threaded_wait(?term) - one
     threaded_wait(+list(term)) - one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<40>,  Next: Examples<77>,  Prev: Modes and number of proofs<39>,  Up: threaded_wait/1

2.4.7.43 Errors
...............

(none)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<77>,  Prev: Errors<40>,  Up: threaded_wait/1

2.4.7.44 Examples
.................

     % wait until the "data_available" notification is received:
     ..., threaded_wait(data_available), ...

See also
........

*note threaded_notify/1: 23c.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: threaded_notify/1,  Prev: threaded_wait/1,  Up: Multi-threading

2.4.7.45 ‘threaded_notify/1’
............................

* Menu:

* Description: Description<77>.
* Modes and number of proofs: Modes and number of proofs<40>.
* Errors: Errors<41>.
* Examples: Examples<78>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<77>,  Next: Modes and number of proofs<40>,  Up: threaded_notify/1

2.4.7.46 Description
....................

     threaded_notify(Term)
     threaded_notify([Term| Terms])

Sends ‘Term’ as a notification to any thread suspended waiting for it in
order to proceed.  The call must be made within the same object (*note
this: 114.) containing the calls to the *note threaded_wait/1: 23b.
predicate waiting for the notification.  The argument may also be a list
of notifications, ‘[Term| Terms]’.  In this case, all notifications in
the list will be sent to any threads suspended waiting for them in order
to proceed.

     Note: This predicate requires a *note backend Prolog compiler: 34.
     providing compatible multi-threading primitives.  The value of the
     read-only *note threads: 225. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<40>,  Next: Errors<41>,  Prev: Description<77>,  Up: threaded_notify/1

2.4.7.47 Modes and number of proofs
...................................

     threaded_notify(@term) - one
     threaded_notify(@list(term)) - one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<41>,  Next: Examples<78>,  Prev: Modes and number of proofs<40>,  Up: threaded_notify/1

2.4.7.48 Errors
...............

(none)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<78>,  Prev: Errors<41>,  Up: threaded_notify/1

2.4.7.49 Examples
.................

     % send a "data_available" notification:
     ..., threaded_notify(data_available), ...

See also
........

*note threaded_wait/1: 23b.


File: TheLogtalkHandbook-3.101.0.info,  Node: Multi-threading engines,  Next: Compiling and loading source files,  Prev: Multi-threading,  Up: Built-in predicates

2.4.8 Multi-threading engines
-----------------------------

'built-in predicate'

* Menu:

* threaded_engine_create/3::
* threaded_engine_destroy/1::
* threaded_engine/1::
* threaded_engine_self/1::
* threaded_engine_next/2::
* threaded_engine_next_reified/2::
* threaded_engine_yield/1::
* threaded_engine_post/2::
* threaded_engine_fetch/1::


File: TheLogtalkHandbook-3.101.0.info,  Node: threaded_engine_create/3,  Next: threaded_engine_destroy/1,  Up: Multi-threading engines

2.4.8.1 ‘threaded_engine_create/3’
..................................

* Menu:

* Description: Description<78>.
* Meta-predicate template: Meta-predicate template<5>.
* Modes and number of proofs: Modes and number of proofs<41>.
* Errors: Errors<42>.
* Examples: Examples<79>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<78>,  Next: Meta-predicate template<5>,  Up: threaded_engine_create/3

2.4.8.2 Description
...................

     threaded_engine_create(AnswerTemplate, Goal, Engine)

Creates a new engine for proving the given goal and defines an answer
template for retrieving the goal solution bindings.  A message queue for
passing arbitrary terms to the engine is also created.  If the name for
the engine is not given, a unique name is generated and returned.
Engine names shall be regarded as opaque terms; users shall not rely on
its type.

     Note: This predicate requires a *note backend Prolog compiler: 34.
     providing compatible multi-threading primitives.  The value of the
     read-only *note engines: 2ba. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.101.0.info,  Node: Meta-predicate template<5>,  Next: Modes and number of proofs<41>,  Prev: Description<78>,  Up: threaded_engine_create/3

2.4.8.3 Meta-predicate template
...............................

     threaded_engine_create(*, 0, *)


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<41>,  Next: Errors<42>,  Prev: Meta-predicate template<5>,  Up: threaded_engine_create/3

2.4.8.4 Modes and number of proofs
..................................

     threaded_engine_create(@term, @callable, @nonvar) - one
     threaded_engine_create(@term, @callable, --nonvar) - one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<42>,  Next: Examples<79>,  Prev: Modes and number of proofs<41>,  Up: threaded_engine_create/3

2.4.8.5 Errors
..............

     ‘Goal’ is a variable:
          ‘instantiation_error’
     ‘Goal’ is neither a variable nor a callable term:
          ‘type_error(callable, Goal)’
     ‘Engine’ is the name of an existing engine:
          ‘permission_error(create, engine, Engine)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<79>,  Prev: Errors<42>,  Up: threaded_engine_create/3

2.4.8.6 Examples
................

     % create a new engine to enumerate list elements:
     | ?- threaded_engine_create(X, member(X, [1,2,3]), worker_1).

See also
........

*note threaded_engine_destroy/1: 242, *note threaded_engine_self/1: 5e6,
*note threaded_engine/1: 5e7, *note threaded_engine_next/2: 240, *note
threaded_engine_next_reified/2: 241.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: threaded_engine_destroy/1,  Next: threaded_engine/1,  Prev: threaded_engine_create/3,  Up: Multi-threading engines

2.4.8.7 ‘threaded_engine_destroy/1’
...................................

* Menu:

* Description: Description<79>.
* Modes and number of proofs: Modes and number of proofs<42>.
* Errors: Errors<43>.
* Examples: Examples<80>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<79>,  Next: Modes and number of proofs<42>,  Up: threaded_engine_destroy/1

2.4.8.8 Description
...................

     threaded_engine_destroy(Engine)

Stops and destroys an engine.

     Note: This predicate requires a *note backend Prolog compiler: 34.
     providing compatible multi-threading primitives.  The value of the
     read-only *note engines: 2ba. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<42>,  Next: Errors<43>,  Prev: Description<79>,  Up: threaded_engine_destroy/1

2.4.8.9 Modes and number of proofs
..................................

     threaded_engine_destroy(@nonvar) - one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<43>,  Next: Examples<80>,  Prev: Modes and number of proofs<42>,  Up: threaded_engine_destroy/1

2.4.8.10 Errors
...............

     ‘Engine’ is a variable:
          ‘instantiation_error’
     ‘Engine’ is neither a variable nor the name of an existing engine:
          ‘existence_error(engine, Engine)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<80>,  Prev: Errors<43>,  Up: threaded_engine_destroy/1

2.4.8.11 Examples
.................

     % stop the worker_1 engine:
     | ?- threaded_engine_destroy(worker_1).

     % stop all engines:
     | ?- forall(
              threaded_engine(Engine),
              threaded_engine_destroy(Engine)
          ).

See also
........

*note threaded_engine_create/3: 23f, *note threaded_engine_self/1: 5e6,
*note threaded_engine/1: 5e7.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: threaded_engine/1,  Next: threaded_engine_self/1,  Prev: threaded_engine_destroy/1,  Up: Multi-threading engines

2.4.8.12 ‘threaded_engine/1’
............................

* Menu:

* Description: Description<80>.
* Modes and number of proofs: Modes and number of proofs<43>.
* Errors: Errors<44>.
* Examples: Examples<81>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<80>,  Next: Modes and number of proofs<43>,  Up: threaded_engine/1

2.4.8.13 Description
....................

     threaded_engine(Engine)

Enumerates, by backtracking, all existing engines.  Engine names shall
be regarded as opaque terms; users shall not rely on their type.

     Note: This predicate requires a *note backend Prolog compiler: 34.
     providing compatible multi-threading primitives.  The value of the
     read-only *note engines: 2ba. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<43>,  Next: Errors<44>,  Prev: Description<80>,  Up: threaded_engine/1

2.4.8.14 Modes and number of proofs
...................................

     threaded_engine(?nonvar) - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<44>,  Next: Examples<81>,  Prev: Modes and number of proofs<43>,  Up: threaded_engine/1

2.4.8.15 Errors
...............

(none)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<81>,  Prev: Errors<44>,  Up: threaded_engine/1

2.4.8.16 Examples
.................

     % check that the worker_1 engine exists:
     | ?- threaded_engine(worker_1).

     % write the names of all existing engines:
     | ?- forall(
              threaded_engine(Engine),
              (writeq(Engine), nl)
          ).

See also
........

*note threaded_engine_create/3: 23f, *note threaded_engine_self/1: 5e6,
*note threaded_engine_destroy/1: 242.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: threaded_engine_self/1,  Next: threaded_engine_next/2,  Prev: threaded_engine/1,  Up: Multi-threading engines

2.4.8.17 ‘threaded_engine_self/1’
.................................

* Menu:

* Description: Description<81>.
* Modes and number of proofs: Modes and number of proofs<44>.
* Errors: Errors<45>.
* Examples: Examples<82>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<81>,  Next: Modes and number of proofs<44>,  Up: threaded_engine_self/1

2.4.8.18 Description
....................

     threaded_engine_self(Engine)

Queries the name of engine calling the predicate.  Fails if not called
from within an engine or if the argument doesn’t unify with the engine
name.

     Note: This predicate requires a *note backend Prolog compiler: 34.
     providing compatible multi-threading primitives.  The value of the
     read-only *note engines: 2ba. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<44>,  Next: Errors<45>,  Prev: Description<81>,  Up: threaded_engine_self/1

2.4.8.19 Modes and number of proofs
...................................

     threaded_engine_self(?nonvar) - zero_or_one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<45>,  Next: Examples<82>,  Prev: Modes and number of proofs<44>,  Up: threaded_engine_self/1

2.4.8.20 Errors
...............

(none)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<82>,  Prev: Errors<45>,  Up: threaded_engine_self/1

2.4.8.21 Examples
.................

     % find the name of the engine making the query:
     ..., threaded_engine_self(Engine), ...

     % check if the the engine making the query is worker_1:
     ..., threaded_engine_self(worker_1), ...

See also
........

*note threaded_engine_create/3: 23f, *note threaded_engine_destroy/1:
242, *note threaded_engine/1: 5e7.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: threaded_engine_next/2,  Next: threaded_engine_next_reified/2,  Prev: threaded_engine_self/1,  Up: Multi-threading engines

2.4.8.22 ‘threaded_engine_next/2’
.................................

* Menu:

* Description: Description<82>.
* Modes and number of proofs: Modes and number of proofs<45>.
* Errors: Errors<46>.
* Examples: Examples<83>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<82>,  Next: Modes and number of proofs<45>,  Up: threaded_engine_next/2

2.4.8.23 Description
....................

     threaded_engine_next(Engine, Answer)

Retrieves an answer from an engine and signals it to start computing the
next answer.  This predicate blocks until an answer becomes available.
The predicate fails when there are no more solutions to the engine goal.
If the engine goal throws an exception, calling this predicate will
re-throw the exception and subsequent calls will fail.

     Note: This predicate requires a *note backend Prolog compiler: 34.
     providing compatible multi-threading primitives.  The value of the
     read-only *note engines: 2ba. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<45>,  Next: Errors<46>,  Prev: Description<82>,  Up: threaded_engine_next/2

2.4.8.24 Modes and number of proofs
...................................

     threaded_engine_next(@nonvar, ?term) - zero_or_one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<46>,  Next: Examples<83>,  Prev: Modes and number of proofs<45>,  Up: threaded_engine_next/2

2.4.8.25 Errors
...............

     ‘Engine’ is a variable:
          ‘instantiation_error’
     ‘Engine’ is neither a variable nor the name of an existing engine:
          ‘existence_error(engine, Engine)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<83>,  Prev: Errors<46>,  Up: threaded_engine_next/2

2.4.8.26 Examples
.................

     % get the next answer from the worker_1 engine:
     | ?- threaded_engine_next(worker_1, Answer).

See also
........

*note threaded_engine_create/3: 23f, *note
threaded_engine_next_reified/2: 241, *note threaded_engine_yield/1: 245.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: threaded_engine_next_reified/2,  Next: threaded_engine_yield/1,  Prev: threaded_engine_next/2,  Up: Multi-threading engines

2.4.8.27 ‘threaded_engine_next_reified/2’
.........................................

* Menu:

* Description: Description<83>.
* Modes and number of proofs: Modes and number of proofs<46>.
* Errors: Errors<47>.
* Examples: Examples<84>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<83>,  Next: Modes and number of proofs<46>,  Up: threaded_engine_next_reified/2

2.4.8.28 Description
....................

     threaded_engine_next_reified(Engine, Answer)

Retrieves an answer from an engine and signals it to start computing the
next answer.  This predicate always succeeds and blocks until an answer
becomes available.  Answers are returned using the terms ‘the(Answer)’,
‘no’, and ‘exception(Error)’.

     Note: This predicate requires a *note backend Prolog compiler: 34.
     providing compatible multi-threading primitives.  The value of the
     read-only *note engines: 2ba. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<46>,  Next: Errors<47>,  Prev: Description<83>,  Up: threaded_engine_next_reified/2

2.4.8.29 Modes and number of proofs
...................................

     threaded_engine_next_reified(@nonvar, ?nonvar) - one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<47>,  Next: Examples<84>,  Prev: Modes and number of proofs<46>,  Up: threaded_engine_next_reified/2

2.4.8.30 Errors
...............

     ‘Engine’ is a variable:
          ‘instantiation_error’
     ‘Engine’ is neither a variable nor the name of an existing engine:
          ‘existence_error(engine, Engine)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<84>,  Prev: Errors<47>,  Up: threaded_engine_next_reified/2

2.4.8.31 Examples
.................

     % get the next reified answer from the worker_1 engine:
     | ?- threaded_engine_next_reified(worker_1, Answer).

See also
........

*note threaded_engine_create/3: 23f, *note threaded_engine_next/2: 240,
*note threaded_engine_yield/1: 245.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: threaded_engine_yield/1,  Next: threaded_engine_post/2,  Prev: threaded_engine_next_reified/2,  Up: Multi-threading engines

2.4.8.32 ‘threaded_engine_yield/1’
..................................

* Menu:

* Description: Description<84>.
* Modes and number of proofs: Modes and number of proofs<47>.
* Errors: Errors<48>.
* Examples: Examples<85>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<84>,  Next: Modes and number of proofs<47>,  Up: threaded_engine_yield/1

2.4.8.33 Description
....................

     threaded_engine_yield(Answer)

Returns an answer independent of the solutions of the engine goal.
Fails if not called from within an engine.  This predicate is usually
used when the engine goal is a call to a recursive predicate processing
terms from the engine term queue.

This predicate blocks until the returned answer is consumed.

Note that this predicate should not be called as the last element of a
conjunction resulting in an engine goal solution as, in this case, an
answer will always be returned.  For example, instead of
‘(threaded_engine_yield(ready); member(X,[1,2,3]))’ use ‘(X=ready;
member(X,[1,2,3]))’.

     Note: This predicate requires a *note backend Prolog compiler: 34.
     providing compatible multi-threading primitives.  The value of the
     read-only *note engines: 2ba. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<47>,  Next: Errors<48>,  Prev: Description<84>,  Up: threaded_engine_yield/1

2.4.8.34 Modes and number of proofs
...................................

     threaded_engine_yield(@term) - zero_or_one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<48>,  Next: Examples<85>,  Prev: Modes and number of proofs<47>,  Up: threaded_engine_yield/1

2.4.8.35 Errors
...............

(none)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<85>,  Prev: Errors<48>,  Up: threaded_engine_yield/1

2.4.8.36 Examples
.................

     % returns the atom "ready" as an engine answer:
     ..., threaded_engine_yield(ready), ...

See also
........

*note threaded_engine_create/3: 23f, *note threaded_engine_next/2: 240,
*note threaded_engine_next_reified/2: 241.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: threaded_engine_post/2,  Next: threaded_engine_fetch/1,  Prev: threaded_engine_yield/1,  Up: Multi-threading engines

2.4.8.37 ‘threaded_engine_post/2’
.................................

* Menu:

* Description: Description<85>.
* Modes and number of proofs: Modes and number of proofs<48>.
* Errors: Errors<49>.
* Examples: Examples<86>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<85>,  Next: Modes and number of proofs<48>,  Up: threaded_engine_post/2

2.4.8.38 Description
....................

     threaded_engine_post(Engine, Term)

Posts a term to the engine term queue.

     Note: This predicate requires a *note backend Prolog compiler: 34.
     providing compatible multi-threading primitives.  The value of the
     read-only *note engines: 2ba. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<48>,  Next: Errors<49>,  Prev: Description<85>,  Up: threaded_engine_post/2

2.4.8.39 Modes and number of proofs
...................................

     threaded_engine_post(@nonvar, @term) - one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<49>,  Next: Examples<86>,  Prev: Modes and number of proofs<48>,  Up: threaded_engine_post/2

2.4.8.40 Errors
...............

     ‘Engine’ is a variable:
          ‘instantiation_error’
     ‘Engine’ is neither a variable nor the name of an existing engine:
          ‘existence_error(engine, Engine)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<86>,  Prev: Errors<49>,  Up: threaded_engine_post/2

2.4.8.41 Examples
.................

     % post the atom "ready" to the worker_1 engine queue:
     | ?- threaded_engine_post(worker_1, ready).

See also
........

*note threaded_engine_fetch/1: 243.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: threaded_engine_fetch/1,  Prev: threaded_engine_post/2,  Up: Multi-threading engines

2.4.8.42 ‘threaded_engine_fetch/1’
..................................

* Menu:

* Description: Description<86>.
* Modes and number of proofs: Modes and number of proofs<49>.
* Errors: Errors<50>.
* Examples: Examples<87>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<86>,  Next: Modes and number of proofs<49>,  Up: threaded_engine_fetch/1

2.4.8.43 Description
....................

     threaded_engine_fetch(Term)

Fetches a term from the engine term queue.  Blocks until a term is
available.  Fails if not called from within an engine.

     Note: This predicate requires a *note backend Prolog compiler: 34.
     providing compatible multi-threading primitives.  The value of the
     read-only *note engines: 2ba. flag is set to ‘supported’ when that
     is the case.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<49>,  Next: Errors<50>,  Prev: Description<86>,  Up: threaded_engine_fetch/1

2.4.8.44 Modes and number of proofs
...................................

     threaded_engine_fetch(?term) - zero_or_one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<50>,  Next: Examples<87>,  Prev: Modes and number of proofs<49>,  Up: threaded_engine_fetch/1

2.4.8.45 Errors
...............

(none)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<87>,  Prev: Errors<50>,  Up: threaded_engine_fetch/1

2.4.8.46 Examples
.................

     % fetch a term from the engine term queue:
     ..., threaded_engine_fetch(Term), ...

See also
........

*note threaded_engine_post/2: 244.


File: TheLogtalkHandbook-3.101.0.info,  Node: Compiling and loading source files,  Next: Flags,  Prev: Multi-threading engines,  Up: Built-in predicates

2.4.9 Compiling and loading source files
----------------------------------------

'built-in predicate'

* Menu:

* logtalk_compile/1::
* logtalk_compile/2::
* logtalk_load/1::
* logtalk_load/2::
* logtalk_make/0::
* logtalk_make/1::
* logtalk_make_target_action/1::
* logtalk_library_path/2::
* logtalk_load_context/2::


File: TheLogtalkHandbook-3.101.0.info,  Node: logtalk_compile/1,  Next: logtalk_compile/2,  Up: Compiling and loading source files

2.4.9.1 ‘logtalk_compile/1’
...........................

* Menu:

* Description: Description<87>.
* Modes and number of proofs: Modes and number of proofs<50>.
* Errors: Errors<51>.
* Examples: Examples<88>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<87>,  Next: Modes and number of proofs<50>,  Up: logtalk_compile/1

2.4.9.2 Description
...................

     logtalk_compile(File)
     logtalk_compile(Files)

Compiles to disk a *note source file: 61d. or a list of source files
using the default compiler flag values.  The Logtalk source file name
extension (by default, ‘.lgt’) can be omitted.  Source file paths can be
absolute, relative to the current directory, or use *note library
notation: 2a8.  This predicate can also be used to compile Prolog source
files as Logtalk source code.  When no recognized Logtalk or Prolog
extension is specified, the compiler tries first to append a Logtalk
source file extension and then a Prolog source file extension.  If that
fails, the compiler tries to use the file name as-is.  The recognized
Logtalk and Prolog file extensions are defined in the *note backend
adapter files: 154.

     Note: This predicate does not load into memory the compiled source
     file.  If you want to both compile and load a source file, use
     instead the *note logtalk_load/1: 46. built-in predicate.

When this predicate is called from the top-level interpreter, relative
source file paths are resolved using the current working directory.
When the calls are made from a source file, relative source file paths
are resolved using the source file directory.

Note that only the errors related to problems in the predicate argument
are listed below.  This predicate fails on the first error found during
compilation of a source file.  In this case, no file with the compiled
code is written to disk.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<50>,  Next: Errors<51>,  Prev: Description<87>,  Up: logtalk_compile/1

2.4.9.3 Modes and number of proofs
..................................

     logtalk_compile(@source_file_name) - zero_or_one
     logtalk_compile(@list(source_file_name)) - zero_or_one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<51>,  Next: Examples<88>,  Prev: Modes and number of proofs<50>,  Up: logtalk_compile/1

2.4.9.4 Errors
..............

     ‘File’ is a variable:
          ‘instantiation_error’
     ‘Files’ is a variable or a list with an element which is a variable:
          ‘instantiation_error’
     ‘File’, or an element ‘File’ of the ‘Files’ list, is neither a variable nor a source file name:
          ‘type_error(source_file_name, File)’
     ‘File’, or an element ‘File’ of the ‘Files’ list, uses library notation but the library does not exist:
          ‘existence_error(library, Library)’
     ‘File’ or an element ‘File’ of the ‘Files’ list does not exist:
          ‘existence_error(file, File)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<88>,  Prev: Errors<51>,  Up: logtalk_compile/1

2.4.9.5 Examples
................

     % compile to disk the "set" source file in the
     % current directory:
     | ?- logtalk_compile(set).

     % compile to disk the "tree" source file in the
     % "types" library directory:
     | ?- logtalk_load(types(tree)).

     % compile to disk the "listp" and "list" source
     % files in the current directory:
     | ?- logtalk_compile([listp, list]).

See also
........

*note logtalk_compile/2: 2b2, *note logtalk_load/1: 46, *note
logtalk_load/2: 4e, *note logtalk_make/0: 29f, *note logtalk_make/1:
2a0, *note logtalk_library_path/2: 2a7.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: logtalk_compile/2,  Next: logtalk_load/1,  Prev: logtalk_compile/1,  Up: Compiling and loading source files

2.4.9.6 ‘logtalk_compile/2’
...........................

* Menu:

* Description: Description<88>.
* Modes and number of proofs: Modes and number of proofs<51>.
* Errors: Errors<52>.
* Examples: Examples<89>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<88>,  Next: Modes and number of proofs<51>,  Up: logtalk_compile/2

2.4.9.7 Description
...................

     logtalk_compile(File, Flags)
     logtalk_compile(Files, Flags)

Compiles to disk a *note source file: 61d. or a list of source files
using a list of compiler flags.  The Logtalk source file name extension
(by default, ‘.lgt’) can be omitted.  Source file paths can be absolute,
relative to the current directory, or use *note library notation: 2a8.
This predicate can also be used to compile Prolog source files as
Logtalk source code.  When no recognized Logtalk or Prolog extension is
specified, the compiler tries first to append a Logtalk source file
extension and then a Prolog source file extension.  If that fails, the
compiler tries to use the file name as-is.  Compiler flags are
represented as 'flag(value)'.  For a description of the available
compiler flags, please see the *note Compiler flags: 251. section in the
User Manual.  The recognized Logtalk and Prolog file extensions are
defined in the *note backend adapter files: 154.

     Note: This predicate does not load into memory the compiled source
     file.  If you want to both compile and load a source file, use
     instead the *note logtalk_load/2: 4e. built-in predicate.

When this predicate is called from the top-level interpreter, relative
source file paths are resolved using the current working directory.
When the calls are made from a source file, relative source file paths
are resolved by default using the source file directory (unless a *note
relative_to: 2e5. flag is passed).

Note that only the errors related to problems in the predicate argument
are listed below.  This predicate fails on the first error found during
compilation of a source file.  In this case, no file with the compiled
code is written to disk.

     Warning: The compiler flags specified in the second argument only
     apply to the files listed in the first argument.  Notably, if you
     are compiling a *note loader file: 4f, the flags only apply to the
     loader file itself.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<51>,  Next: Errors<52>,  Prev: Description<88>,  Up: logtalk_compile/2

2.4.9.8 Modes and number of proofs
..................................

     logtalk_compile(@source_file_name, @list(compiler_flag)) - zero_or_one
     logtalk_compile(@list(source_file_name), @list(compiler_flag)) - zero_or_one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<52>,  Next: Examples<89>,  Prev: Modes and number of proofs<51>,  Up: logtalk_compile/2

2.4.9.9 Errors
..............

     ‘File’ is a variable:
          ‘instantiation_error’
     ‘Files’ is a variable or a list with an element which is a variable:
          ‘instantiation_error’
     ‘File’, or an element ‘File’ of the ‘Files’ list, is neither a variable nor a source file name:
          ‘type_error(source_file_name, File)’
     ‘File’, or an element ‘File’ of the ‘Files’ list, uses library notation but the library does not exist:
          ‘existence_error(library, Library)’
     ‘File’ or an element ‘File’ of the ‘Files’ list, does not exist:
          ‘existence_error(file, File)’
          
     ‘Flags’ is a variable or a list with an element which is a variable:
          ‘instantiation_error’
     ‘Flags’ is neither a variable nor a proper list:
          ‘type_error(list, Flags)’
     An element ‘Flag’ of the ‘Flags’ list is not a valid compiler flag:
          ‘type_error(compiler_flag, Flag)’
     An element ‘Flag’ of the ‘Flags’ list defines a value for a read-only compiler flag:
          ‘permission_error(modify, flag, Flag)’
     An element ‘Flag’ of the ‘Flags’ list defines an invalid value for a flag:
          ‘domain_error(flag_value, Flag+Value)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<89>,  Prev: Errors<52>,  Up: logtalk_compile/2

2.4.9.10 Examples
.................

     % compile to disk the "list" source file in the
     % current directory using default compiler flags:
     | ?- logtalk_compile(list, []).

     % compile to disk the "tree" source file in the "types"
     % library directory with the source_data flag turned on:
     | ?- logtalk_compile(types(tree), [source_data(on)]).

     % compile to disk the "file_system" source file in the
     % current directory with portability warnings suppressed:
     | ?- logtalk_compile(file_system, [portability(silent)]).

See also
........

*note logtalk_compile/1: 29e, *note logtalk_load/1: 46, *note
logtalk_load/2: 4e, *note logtalk_make/0: 29f, *note logtalk_make/1:
2a0, *note logtalk_library_path/2: 2a7.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: logtalk_load/1,  Next: logtalk_load/2,  Prev: logtalk_compile/2,  Up: Compiling and loading source files

2.4.9.11 ‘logtalk_load/1’
.........................

* Menu:

* Description: Description<89>.
* Modes and number of proofs: Modes and number of proofs<52>.
* Errors: Errors<53>.
* Examples: Examples<90>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<89>,  Next: Modes and number of proofs<52>,  Up: logtalk_load/1

2.4.9.12 Description
....................

     logtalk_load(File)
     logtalk_load(Files)

Compiles to disk and then loads to memory a *note source file: 61d. or a
list of source files using the default compiler flag values.  The
Logtalk source file name extension (by default, ‘.lgt’) can be omitted.
Source file paths can be absolute, relative to the current directory, or
use *note library notation: 2a8.  This predicate can also be used to
compile Prolog source files as Logtalk source code.  When no recognized
Logtalk or Prolog extension is specified, the compiler tries first to
append a Logtalk source file extension and then a Prolog source file
extension.  If that fails, the compiler tries to use the file name
as-is.  The recognized Logtalk and Prolog file extensions are defined in
the *note backend adapter files: 154.

When this predicate is called from the top-level interpreter, relative
source file paths are resolved using the current working directory.
When the calls are made from a source file, relative source file paths
are resolved using the source file directory.

Note that only the errors related to problems in the predicate argument
are listed below.  This predicate fails on the first error found during
compilation of a source file.  In this case, the source file contents is
not loaded.

Depending on the *note backend Prolog compiler: 34, the shortcuts
‘{File}’ or ‘{File1, File2, ...}’ may be used as an alternative.  Check
the adapter files for the availability of these shortcuts as they are
not part of the language (and thus should only be used at the top-level
interpreter).


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<52>,  Next: Errors<53>,  Prev: Description<89>,  Up: logtalk_load/1

2.4.9.13 Modes and number of proofs
...................................

     logtalk_load(@source_file_name) - zero_or_one
     logtalk_load(@list(source_file_name)) - zero_or_one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<53>,  Next: Examples<90>,  Prev: Modes and number of proofs<52>,  Up: logtalk_load/1

2.4.9.14 Errors
...............

     ‘File’ is a variable:
          ‘instantiation_error’
     ‘Files’ is a variable or a list with an element which is a variable:
          ‘instantiation_error’
     ‘File’, or an element ‘File’ of the ‘Files’ list, is neither a variable nor a source file name:
          ‘type_error(source_file_name, File)’
     ‘File’, or an element ‘File’ of the ‘Files’ list, uses library notation but the library does not exist:
          ‘existence_error(library, Library)’
     ‘File’ or an element ‘File’ of the ‘Files’ list, does not exist:
          ‘existence_error(file, File)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<90>,  Prev: Errors<53>,  Up: logtalk_load/1

2.4.9.15 Examples
.................

     % compile and load the "set" source file in the
     % current directory:
     | ?- logtalk_load(set).

     % compile and load the "tree" source file in the
     % "types" library directory:
     | ?- logtalk_load(types(tree)).

     % compile and load the "listp" and "list" source
     % files in the current directory:
     | ?- logtalk_load([listp, list]).

See also
........

*note logtalk_compile/1: 29e, *note logtalk_compile/2: 2b2, *note
logtalk_load/2: 4e, *note logtalk_make/0: 29f, *note logtalk_make/1:
2a0, *note logtalk_library_path/2: 2a7.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: logtalk_load/2,  Next: logtalk_make/0,  Prev: logtalk_load/1,  Up: Compiling and loading source files

2.4.9.16 ‘logtalk_load/2’
.........................

* Menu:

* Description: Description<90>.
* Modes and number of proofs: Modes and number of proofs<53>.
* Errors: Errors<54>.
* Examples: Examples<91>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<90>,  Next: Modes and number of proofs<53>,  Up: logtalk_load/2

2.4.9.17 Description
....................

     logtalk_load(File, Flags)
     logtalk_load(Files, Flags)

Compiles to disk and then loads to memory a *note source file: 61d. or a
list of source files using a list of compiler flags.  The Logtalk source
file name extension (by default, ‘.lgt’) can be omitted.  Source file
paths can be absolute, relative to the current directory, or use *note
library notation: 2a8.  Compiler flags are represented as 'flag(value)'.
This predicate can also be used to compile Prolog source files as
Logtalk source code.  When no recognized Logtalk or Prolog extension is
specified, the compiler tries first to append a Logtalk source file
extension and then a Prolog source file extension.  If that fails, the
compiler tries to use the file name as-is.  For a description of the
available compiler flags, please see the *note Compiler flags: 251.
section in the User Manual.  The recognized Logtalk and Prolog file
extensions are defined in the *note backend adapter files: 154.  The
recognized Logtalk and Prolog file extensions are defined in the *note
backend adapter files: 154.

When this predicate is called from the top-level interpreter, relative
source file paths are resolved using the current working directory.
When the calls are made from a source file, relative source file paths
are resolved by default using the source file directory (unless a *note
relative_to: 2e5. flag is passed).

Note that only the errors related to problems in the predicate argument
are listed below.  This predicate fails on the first error found during
compilation of a source file.  In this case, the source file contents is
not loaded.

     Warning: The compiler flags specified in the second argument only
     apply to the files listed in the first argument and not to any
     files that those files may load or compile.  Notably, if you are
     loading a *note loader file: 4f, the flags only apply to the loader
     file itself and not to the files loaded by it.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<53>,  Next: Errors<54>,  Prev: Description<90>,  Up: logtalk_load/2

2.4.9.18 Modes and number of proofs
...................................

     logtalk_load(@source_file_name, @list(compiler_flag)) - zero_or_one
     logtalk_load(@list(source_file_name), @list(compiler_flag)) - zero_or_one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<54>,  Next: Examples<91>,  Prev: Modes and number of proofs<53>,  Up: logtalk_load/2

2.4.9.19 Errors
...............

     ‘File’ is a variable:
          ‘instantiation_error’
     ‘Files’ is a variable or a list with an element which is a variable:
          ‘instantiation_error’
     ‘File’, or an element ‘File’ of the ‘Files’ list, is neither a variable nor a source file name:
          ‘type_error(source_file_name, File)’
     ‘File’, or an element ‘File’ of the ‘Files’ list, uses library notation but the library does not exist:
          ‘existence_error(library, Library)’
     ‘File’ or an element ‘File’ of the ‘Files’ list, does not exist:
          ‘existence_error(file, File)’
     ‘Flags’ is a variable or a list with an element which is a variable:
          ‘instantiation_error’
     ‘Flags’ is neither a variable nor a proper list:
          ‘type_error(list, Flags)’
     An element ‘Flag’ of the ‘Flags’ list is not a valid compiler flag:
          ‘type_error(compiler_flag, Flag)’
     An element ‘Flag’ of the ‘Flags’ list defines a value for a read-only compiler flag:
          ‘permission_error(modify, flag, Flag)’
     An element ‘Flag’ of the ‘Flags’ list defines an invalid value for a flag:
          ‘domain_error(flag_value, Flag+Value)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<91>,  Prev: Errors<54>,  Up: logtalk_load/2

2.4.9.20 Examples
.................

     % compile and load the "list" source file in the
     % current directory using default compiler flags:
     | ?- logtalk_load(list, []).

     % compile and load the "tree" source file in the "types"
     % library directory with the source_data flag turned on:
     | ?- logtalk_load(types(tree)).

     % compile and load the "file_system" source file in the
     % current directory with portability warnings suppressed:
     | ?- logtalk_load(file_system, [portability(silent)]).

See also
........

*note logtalk_compile/1: 29e, *note logtalk_compile/2: 2b2, *note
logtalk_load/1: 46, *note logtalk_make/0: 29f, *note logtalk_make/1:
2a0, *note logtalk_library_path/2: 2a7.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: logtalk_make/0,  Next: logtalk_make/1,  Prev: logtalk_load/2,  Up: Compiling and loading source files

2.4.9.21 ‘logtalk_make/0’
.........................

* Menu:

* Description: Description<91>.
* Modes and number of proofs: Modes and number of proofs<54>.
* Errors: Errors<55>.
* Examples: Examples<92>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<91>,  Next: Modes and number of proofs<54>,  Up: logtalk_make/0

2.4.9.22 Description
....................

     logtalk_make

Reloads all Logtalk source files that have been modified since the time
they were last loaded.  Only source files loaded using the *note
logtalk_load/1: 46. and *note logtalk_load/2: 4e. predicates are
reloaded.  Non-modified files will also be reloaded when a previous
attempt to load them failed or when there is a change to the compilation
mode (i.e., when the files were loaded without explicit *note debug:
2e3. or *note optimize: 8c. flags and the default values of these flags
changed after loading; no check is made, however, for other implicit
compiler flags that may have changed since loading).  When an included
file is modified, this predicate reloads its main file (i.e., the file
that contains the *note include/1: b8. directive).

Depending on the *note backend Prolog compiler: 34, the shortcut ‘{*}’
may be used as an alternative.  Check the *note adapter files: 154. for
the availability of the shortcut as it is not part of the language.

     Warning: Only use the ‘{*}’ shortcut at the top-level interpreter
     and never in source files.

This predicate can be extended by the user by defining clauses for the
*note logtalk_make_target_action/1: 636. multifile and dynamic hook
predicate using the argument ‘all’.  The additional user defined actions
are run after the default one.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<54>,  Next: Errors<55>,  Prev: Description<91>,  Up: logtalk_make/0

2.4.9.23 Modes and number of proofs
...................................

     logtalk_make - one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<55>,  Next: Examples<92>,  Prev: Modes and number of proofs<54>,  Up: logtalk_make/0

2.4.9.24 Errors
...............

(none)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<92>,  Prev: Errors<55>,  Up: logtalk_make/0

2.4.9.25 Examples
.................

     % reload all files modified since last loaded:
     | ?- logtalk_make.

See also
........

*note logtalk_compile/1: 29e, *note logtalk_compile/2: 2b2, *note
logtalk_load/1: 46, *note logtalk_load/2: 4e, *note logtalk_make/1: 2a0,
*note logtalk_make_target_action/1: 636.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: logtalk_make/1,  Next: logtalk_make_target_action/1,  Prev: logtalk_make/0,  Up: Compiling and loading source files

2.4.9.26 ‘logtalk_make/1’
.........................

* Menu:

* Description: Description<92>.
* Modes and number of proofs: Modes and number of proofs<55>.
* Errors: Errors<56>.
* Examples: Examples<93>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<92>,  Next: Modes and number of proofs<55>,  Up: logtalk_make/1

2.4.9.27 Description
....................

     logtalk_make(Target)

Runs a make target.  Prints a warning message and fails when the target
is not valid.

Allows reloading all Logtalk source files that have been modified since
last loaded when called with the target ‘all’, deleting all intermediate
files generated by the compilation of Logtalk source files when called
with the target ‘clean’, checking for code issues when called with the
target ‘check’, listing of circular dependencies between pairs or trios
of objects when called with the target ‘circular’, generating
documentation when called with the target ‘documentation’, and deleting
the *note dynamic binding: 36. caches with the target ‘caches’.

There are also four variants of the ‘all’ target: ‘debug’, ‘normal’,
‘optimal’, and ‘force’.  The first three targets change the compilation
mode (by changing the default value of the *note debug: 2e3. and *note
optimize: 8c. flags) and reload all affected files (i.e., all files
loaded without an explicit ‘debug/1’ or ‘optimize/1’ compiler option).
The ‘force’ traget forces reloading of all files that were loaded
without an explicit ‘reload/1’ compiler option.  This target is
typically used after changing some compiler linter flag (e.g., the
‘portability’ flag).

When using the ‘all’ target, only source files loaded using the *note
logtalk_load/1: 46. and *note logtalk_load/2: 4e. predicates are
reloaded.  Non-modified files will also be reloaded when a previous
attempt to load them failed or when there is a change to the compilation
mode (i.e., when the files were loaded without explicit *note debug:
2e3. or *note optimize: 8c. flags and the default values of these flags
changed after loading; no check is made, however, for other implicit
compiler flags that may have changed since loading).  When an included
file is modified, this target reloads its main file (i.e., the file that
contains the *note include/1: b8. directive).

When using the ‘check’ or ‘circular’ targets, be sure to compile your
source files with the *note source_data: cc. flag turned on for complete
and detailed reports.

The ‘check’ target scans for missing entities (objects, protocols,
categories, and modules), missing entity predicates, and duplicated
library aliases.  Predicates for messages sent to objects that implement
the forwarding(1) built-in protocol are not reported.  While this
usually avoids only false positives, it may also result in failure to
report true missing predicates in some cases.

When using the ‘circular’ target, be prepared for a lengthy computation
time for applications with a large combined number of objects and
message calls.  Only mutual and triangular dependencies are checked due
to the computational cost.  Circular dependencies occur when an object
sends a message to a second object that, in turn, sends a message to the
first object.  These circular dependencies are often a consequence of
lack of separation of concerns.  But, when they cannot be fixed, the
only practical consequence is a small performance cost as some of the
messages would be forced to use dynamic binding.

The ‘documentation’ target requires the ‘doclet’ tool and a single *note
doclet object: 63d. to be loaded.  See the ‘doclet’ tool documentation
for more details.

Depending on the *note backend Prolog compiler: 34, the following
top-level shortcuts are usually defined:

   * ‘{*}’ - ‘logtalk_make(all)’

   * ‘{!}’ - ‘logtalk_make(clean)’

   * ‘{?}’ - ‘logtalk_make(check)’

   * ‘{@}’ - ‘logtalk_make(circular)’

   * ‘{#}’ - ‘logtalk_make(documentation)’

   * ‘{$}’ - ‘logtalk_make(caches)’

   * ‘{+d}’ - ‘logtalk_make(debug)’

   * ‘{+n}’ - ‘logtalk_make(normal)’

   * ‘{+o}’ - ‘logtalk_make(optimal)’

   * ‘{+f}’ - ‘logtalk_make(force)’

Check the *note adapter files: 154. for the availability of these
shortcuts as they are not part of the language.

     Warning: Only use the shortcuts at the top-level interpreter and
     never in source files.

The target actions can be extended by defining clauses for the multifile
and dynamic hook predicate *note logtalk_make_target_action(Target):
636. where ‘Target’ is one of the targets listed above.  The additional
user-defined actions are run after the default ones.

   ---------- Footnotes ----------

   (1) ../../../apis/forwarding_0.html#forwarding-0


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<55>,  Next: Errors<56>,  Prev: Description<92>,  Up: logtalk_make/1

2.4.9.28 Modes and number of proofs
...................................

     logtalk_make(+atom) - zero_or_one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<56>,  Next: Examples<93>,  Prev: Modes and number of proofs<55>,  Up: logtalk_make/1

2.4.9.29 Errors
...............

(none)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<93>,  Prev: Errors<56>,  Up: logtalk_make/1

2.4.9.30 Examples
.................

     % reload loaded source files in debug mode:
     | ?- logtalk_make(debug).

     % check for code issues in the loaded source files:
     | ?- logtalk_make(check).

     % delete all intermediate files generated by
     % the compilation of Logtalk source files:
     | ?- logtalk_make(clean).

See also
........

*note logtalk_compile/1: 29e, *note logtalk_compile/2: 2b2, *note
logtalk_load/1: 46, *note logtalk_load/2: 4e, *note logtalk_make/0: 29f,
*note logtalk_make_target_action/1: 636.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: logtalk_make_target_action/1,  Next: logtalk_library_path/2,  Prev: logtalk_make/1,  Up: Compiling and loading source files

2.4.9.31 ‘logtalk_make_target_action/1’
.......................................

* Menu:

* Description: Description<93>.
* Modes and number of proofs: Modes and number of proofs<56>.
* Errors: Errors<57>.
* Examples: Examples<94>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<93>,  Next: Modes and number of proofs<56>,  Up: logtalk_make_target_action/1

2.4.9.32 Description
....................

     logtalk_make_target_action(Target)

Multifile and dynamic hook predicate that allows defining user actions
for the *note logtalk_make/1: 2a0. targets.  The user defined actions
are run after the default ones using a failure driven loop.  This loop
does not catch any exceptions thrown when calling the user-defined
actions.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<56>,  Next: Errors<57>,  Prev: Description<93>,  Up: logtalk_make_target_action/1

2.4.9.33 Modes and number of proofs
...................................

     logtalk_make_target_action(+atom) - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<57>,  Next: Examples<94>,  Prev: Modes and number of proofs<56>,  Up: logtalk_make_target_action/1

2.4.9.34 Errors
...............

(none)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<94>,  Prev: Errors<57>,  Up: logtalk_make_target_action/1

2.4.9.35 Examples
.................

     % integrate the dead_code_scanner tool with logtalk_make/1

     :- multifile(logtalk_make_target_action/1).
     :- dynamic(logtalk_make_target_action/1).

     logtalk_make_target_action(check) :-
         dead_code_scanner::all.

See also
........

*note logtalk_make/1: 2a0, *note logtalk_make/0: 29f.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: logtalk_library_path/2,  Next: logtalk_load_context/2,  Prev: logtalk_make_target_action/1,  Up: Compiling and loading source files

2.4.9.36 ‘logtalk_library_path/2’
.................................

* Menu:

* Description: Description<94>.
* Modes and number of proofs: Modes and number of proofs<57>.
* Errors: Errors<58>.
* Examples: Examples<95>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<94>,  Next: Modes and number of proofs<57>,  Up: logtalk_library_path/2

2.4.9.37 Description
....................

     logtalk_library_path(Library, Path)

Dynamic and multifile user-defined predicate, allowing the declaration
of aliases to *note library: 6e. paths.  Library aliases may also be
used in the second argument (using the notation 'alias(path)').  Paths
must always end with the path directory separator character (‘'/'’).

     Warning: Library aliases should be unique.  The *note
     logtalk_make/1: 2a0. built-in predicate can be used to detect and
     report duplicated library aliases using the ‘check’ target.

Clauses for this predicate should preferably be facts.  Defining rules
to dynamically compute at runtime both library alias names and their
paths, although sometimes handy, can inadvertently result in endless
loops when those rules also attempt to expand library paths.  When
asserting facts for this predicate, use preferably ‘asserta/1’ instead
of ‘assertz/1’ to help ensure the facts will be used before any rules.

Relative paths (e.g., ‘'../'’ or ‘'./'’) should only be used within the
'alias(path)') notation so that library paths can always be expanded to
absolute paths independently of the (usually unpredictable) current
directory at the time the ‘logtalk_library_path/2’ predicate is called.

When working with a relocatable application, the actual application
installation directory can be retrieved by calling the *note
logtalk_load_context/2: 318. predicate with the ‘directory’ key and
using the returned value to define the ‘logtalk_library_path/2’
predicate.  On a *note settings file: 49. file or a *note loader file:
4f. file, simply use an *note initialization/1: 42. directive to wrap
the call to the ‘logtalk_load_context/2’ predicate and the assert of the
‘logtalk_library_path/2’ fact.

This predicate may be used to override the default *note scratch
directory: 293. by defining the library alias ‘scratch_directory’ in a
backend Prolog initialization file (assumed to be loaded prior to
Logtalk loading).  This allows e.g.  Logtalk to be installed in a
read-only directory by setting this alias to the operating-system
directory for temporary files.  It also allows several Logtalk instances
to run concurrently without conflict by using a unique scratch directory
per instance (e.g., using a process ID or a UUID generator).

This predicate may be used to override the default location used by the
*note packs: 64a. tool to store registries and packs by defining the
‘logtalk_packs’ library alias in settings file or in a backend Prolog
initialization file (assumed to be loaded prior to Logtalk loading).

The *note logtalk: d1. built-in object provides an
expand_library_path/2(1) predicate that can be used to expand library
aliases and files expressed using library notation.

   ---------- Footnotes ----------

   (1) ../../../apis/logtalk_0.html#logtalk-0-expand-library-path-2


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<57>,  Next: Errors<58>,  Prev: Description<94>,  Up: logtalk_library_path/2

2.4.9.38 Modes and number of proofs
...................................

     logtalk_library_path(?atom, -atom) - zero_or_more
     logtalk_library_path(?atom, -compound) - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<58>,  Next: Examples<95>,  Prev: Modes and number of proofs<57>,  Up: logtalk_library_path/2

2.4.9.39 Errors
...............

(none)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<95>,  Prev: Errors<58>,  Up: logtalk_library_path/2

2.4.9.40 Examples
.................

     :- initialization((
        logtalk_load_context(directory, Directory),
        asserta(logtalk_library_path(my_application_root, Directory))
     )).

     | ?- logtalk_library_path(viewpoints, Path).

     Path = examples('viewpoints/')
     yes

     | ?- logtalk_library_path(Library, Path).

     Library = home,
     Path = '$HOME/' ;

     Library = logtalk_home,
     Path = '$LOGTALKHOME/' ;

     Library = logtalk_user
     Path = '$LOGTALKUSER/' ;

     Library = examples
     Path = logtalk_user('examples/') ;

     Library = library
     Path = logtalk_user('library/') ;

     Library = viewpoints
     Path = examples('viewpoints/')
     yes

     | ?- logtalk::expand_library_path(viewpoints, Path).

     Path = '/Users/pmoura/logtalk/examples/viewpoints/'.
     yes

     | ?- logtalk::expand_library_path(viewpoints('loader.lgt'), Path).

     Path = '/Users/pmoura/logtalk/examples/viewpoints/loader.lgt'.
     yes

See also
........

*note logtalk_compile/1: 29e, *note logtalk_compile/2: 2b2, *note
logtalk_load/1: 46, *note logtalk_load/2: 4e.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: logtalk_load_context/2,  Prev: logtalk_library_path/2,  Up: Compiling and loading source files

2.4.9.41 ‘logtalk_load_context/2’
.................................

* Menu:

* Description: Description<95>.
* Modes and number of proofs: Modes and number of proofs<58>.
* Errors: Errors<59>.
* Examples: Examples<96>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<95>,  Next: Modes and number of proofs<58>,  Up: logtalk_load_context/2

2.4.9.42 Description
....................

     logtalk_load_context(Key, Value)

Provides access to the Logtalk compilation/loading context.  The
following keys are currently supported:

   * ‘entity_identifier’ - identifier of the entity being compiled if
     any

   * ‘entity_prefix’ - internal prefix for the entity compiled code

   * ‘entity_type’ - returns the value ‘module’ when compiling a module
     as an object

   * ‘entity_relation’ - returns the entity relations as declared in the
     entity opening directive

   * ‘source’ - full path of the source file being compiled

   * ‘file’ - the actual file being compiled, different from ‘source’
     only when processing an ‘include/1’ directive

   * ‘basename’ - source file basename

   * ‘directory’ - source file directory

   * ‘stream’ - input stream being used to read source file terms

   * ‘target’ - the full path of the intermediate Prolog file

   * ‘flags’ - the list of the explicit flags used for the compilation
     of the source file

   * ‘term’ - the source file term being compiled

   * ‘term_position’ - the position of the term being compiled
     (‘StartLine-EndLine’)

   * ‘term_position(Term)’ - the position of the term being compiled
     (‘StartLine-EndLine’)

   * ‘variables’ - the variables of the term being compiled
     (‘[Variable1, ...]’)

   * ‘variable_names’ - the variable names of the term being compiled
     (‘[Name1=Variable1, ...]’)

   * ‘variable_names(Term)’ - the variable names of the term being
     compiled (‘[Name1=Variable1, ...]’)

   * ‘singletons’ - the singleton variables of the term being compiled
     (‘[Name1=Variable1, ...]’)

   * ‘singletons(Term)’ - the singleton variables of the term being
     compiled (‘[Name1=Variable1, ...]’)

   * ‘parameter_variables’ - list of parameter variable names and
     positions (‘[Name1-Position1, ...]’)

For the ‘entity_relation’ key, the possible values are:

   * ‘extends_protocol(Protocol, ParentProtocol, Scope)’

   * ‘implements_protocol(ObjectOrCategory, Protocol, Scope)’

   * ‘extends_category(Category, ParentCategory, Scope)’

   * ‘imports_category(Object, Category, Scope)’

   * ‘extends_object(Prototype, Parent, Scope)’

   * ‘instantiates_class(Instance, Class, Scope)’

   * ‘specializes_class(Class, Superclass, Scope)’

   * ‘complements_object(Category, Object)’

Calling this predicate with the ‘parameter_variables’ key only succeeds
when compiling a parametric entity containing parameter variables.

This predicate is usually called by the *note term_expansion/2: fc. and
*note goal_expansion/2: fd. methods.  It can also be called directly
from *note initialization/1: 42. directives in a source file.  Note that
the entity keys are only available when compiling an entity term or from
an object ‘initialization/1’ directive.

     Warning: The ‘term_position’ key is only supported in *note backend
     Prolog compilers: 34. that provide access to the start and end
     lines of a read term.  When such support is not available, the
     value ‘-1’ is returned for both the start and the end lines.

     Variables in the values of the ‘term’, ‘variables’,
     ‘variable_names’, and ‘singletons’ keys are not shared with,
     respectively, the term and goal arguments of the ‘term_expansion/2’
     and ‘goal_expansion/2’ methods.  Use instead the
     ‘variable_names(Term)’ and ‘singletons(Term)’ keys when possible.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<58>,  Next: Errors<59>,  Prev: Description<95>,  Up: logtalk_load_context/2

2.4.9.43 Modes and number of proofs
...................................

     logtalk_load_context(?callable, -nonvar) - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<59>,  Next: Examples<96>,  Prev: Modes and number of proofs<58>,  Up: logtalk_load_context/2

2.4.9.44 Errors
...............

     ‘Key’ is neither a variable nor a callable term:
          ‘type_error(callable, Key)’
     ‘Key’ is a callable term but not a valid key:
          ‘domain_error(logtalk_load_context_key, Key)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<96>,  Prev: Errors<59>,  Up: logtalk_load_context/2

2.4.9.45 Examples
.................

     % expand source file terms only if they are entity terms
     term_expansion(Term, ExpandedTerms) :-
         logtalk_load_context(entity_identifier, _),
         ....

     % expand source file term while accessing its variable names
     term_expansion(Term, ExpandedTerms) :-
         logtalk_load_context(variable_names(Term), VariableNames),
         ....

     % define a library alias based on the source directory
     :- initialization((
         logtalk_load_context(directory, Directory),
         assertz(logtalk_library_path(my_app, Directory))
     )).

See also
........

*note term_expansion/2: fc, *note goal_expansion/2: fd, *note
initialization/1: 42.


File: TheLogtalkHandbook-3.101.0.info,  Node: Flags,  Next: Linter,  Prev: Compiling and loading source files,  Up: Built-in predicates

2.4.10 Flags
------------

'built-in predicate'

* Menu:

* current_logtalk_flag/2::
* set_logtalk_flag/2: set_logtalk_flag/2<2>.
* create_logtalk_flag/3::


File: TheLogtalkHandbook-3.101.0.info,  Node: current_logtalk_flag/2,  Next: set_logtalk_flag/2<2>,  Up: Flags

2.4.10.1 ‘current_logtalk_flag/2’
.................................

* Menu:

* Description: Description<96>.
* Modes and number of proofs: Modes and number of proofs<59>.
* Errors: Errors<60>.
* Examples: Examples<97>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<96>,  Next: Modes and number of proofs<59>,  Up: current_logtalk_flag/2

2.4.10.2 Description
....................

     current_logtalk_flag(Flag, Value)

Enumerates, by backtracking, the current Logtalk flag values.  For a
description of the predefined compiler flags, please see the *note
Compiler flags: 251. section in the User Manual.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<59>,  Next: Errors<60>,  Prev: Description<96>,  Up: current_logtalk_flag/2

2.4.10.3 Modes and number of proofs
...................................

     current_logtalk_flag(?atom, ?atom) - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<60>,  Next: Examples<97>,  Prev: Modes and number of proofs<59>,  Up: current_logtalk_flag/2

2.4.10.4 Errors
...............

     ‘Flag’ is neither a variable nor an atom:
          ‘type_error(atom, Flag)’
     ‘Flag’ is an atom but an invalid flag:
          ‘domain_error(flag, Value)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<97>,  Prev: Errors<60>,  Up: current_logtalk_flag/2

2.4.10.5 Examples
.................

     % get the current value of the source_data flag:
     | ?- current_logtalk_flag(source_data, Value).

See also
........

*note create_logtalk_flag/3: 2e7, *note set_logtalk_flag/2: 51.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: set_logtalk_flag/2<2>,  Next: create_logtalk_flag/3,  Prev: current_logtalk_flag/2,  Up: Flags

2.4.10.6 ‘set_logtalk_flag/2’
.............................

* Menu:

* Description: Description<97>.
* Modes and number of proofs: Modes and number of proofs<60>.
* Errors: Errors<61>.
* Examples: Examples<98>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<97>,  Next: Modes and number of proofs<60>,  Up: set_logtalk_flag/2<2>

2.4.10.7 Description
....................

     set_logtalk_flag(Flag, Value)

Sets global, default, flag values.  For local flag scope, use the
corresponding *note set_logtalk_flag/2: 50. directive.  To set a global
flag value when compiling and loading a source file, wrap the calls to
this built-in predicate with an *note initialization/1: 42. directive.
For a description of the predefined compiler flags, please see the *note
Compiler flags: 251. section in the User Manual.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<60>,  Next: Errors<61>,  Prev: Description<97>,  Up: set_logtalk_flag/2<2>

2.4.10.8 Modes and number of proofs
...................................

     set_logtalk_flag(+atom, +nonvar) - one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<61>,  Next: Examples<98>,  Prev: Modes and number of proofs<60>,  Up: set_logtalk_flag/2<2>

2.4.10.9 Errors
...............

     ‘Flag’ is a variable:
          ‘instantiation_error’
     ‘Value’ is a variable:
          ‘instantiation_error’
     ‘Flag’ is neither a variable nor an atom:
          ‘type_error(atom, Flag)’
     ‘Flag’ is an atom but an invalid flag:
          ‘domain_error(flag, Flag)’
     ‘Value’ is not a valid value for flag ‘Flag’:
          ‘domain_error(flag_value, Flag + Value)’
     ‘Flag’ is a read-only flag:
          ‘permission_error(modify, flag, Flag)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<98>,  Prev: Errors<61>,  Up: set_logtalk_flag/2<2>

2.4.10.10 Examples
..................

     % turn off globally and by default the compiler
     % unknown entities warnings:
     | ?- set_logtalk_flag(unknown_entities, silent).

See also
........

*note create_logtalk_flag/3: 2e7, *note current_logtalk_flag/2: 2b3.

'built-in predicate'


File: TheLogtalkHandbook-3.101.0.info,  Node: create_logtalk_flag/3,  Prev: set_logtalk_flag/2<2>,  Up: Flags

2.4.10.11 ‘create_logtalk_flag/3’
.................................

* Menu:

* Description: Description<98>.
* Modes and number of proofs: Modes and number of proofs<61>.
* Errors: Errors<62>.
* Examples: Examples<99>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<98>,  Next: Modes and number of proofs<61>,  Up: create_logtalk_flag/3

2.4.10.12 Description
.....................

     create_logtalk_flag(Flag, Value, Options)

Creates a new Logtalk flag and sets its default value.  User-defined
flags can be queried and set in the same way as predefined flags by
using, respectively, the *note current_logtalk_flag/2: 2b3. and *note
set_logtalk_flag/2: 51. built-in predicates.  For a description of the
predefined compiler flags, please see the *note Compiler flags: 251.
section in the User Manual.

This predicate is based on the specification of the SWI-Prolog
‘create_prolog_flag/3’ built-in predicate and supports the same options:
‘access(Access)’, where ‘Access’ can be either ‘read_write’ (the
default) or ‘read_only’; ‘keep(Keep)’, where ‘Keep’ can be either
‘false’ (the default) or ‘true’, for deciding if an existing definition
of the flag should be kept or replaced by the new one; and ‘type(Type)’
for specifying the type of the flag, which can be ‘boolean’, ‘atom’,
‘integer’, ‘float’, or ‘term’ (which only restricts the flag value to
ground terms).  When the ‘type/1’ option is not specified, the type of
the flag is inferred from its initial value.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<61>,  Next: Errors<62>,  Prev: Description<98>,  Up: create_logtalk_flag/3

2.4.10.13 Modes and number of proofs
....................................

     create_logtalk_flag(+atom, +ground, +list(ground)) - one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<62>,  Next: Examples<99>,  Prev: Modes and number of proofs<61>,  Up: create_logtalk_flag/3

2.4.10.14 Errors
................

     ‘Flag’ is a variable:
          ‘instantiation_error’
     ‘Value’ is not a ground term:
          ‘instantiation_error’
     ‘Options’ is not a ground term:
          ‘instantiation_error’
     ‘Flag’ is neither a variable nor an atom:
          ‘type_error(atom, Flag)’
     ‘Options’ is neither a variable nor a list:
          ‘type_error(atom, Flag)’
     ‘Value’ is not a valid value for flag Flag:
          ‘domain_error(flag_value, Flag + Value)’
     ‘Flag’ is a system-defined flag:
          ‘permission_error(modify, flag, Flag)’
     An element ‘Option’ of the list ‘Options’ is not a valid option
          domain_error(flag_option,Option)
     The list ‘Options’ contains a ‘type(Type)’ option and ‘Value’ is not of type ‘Type’
          type_error(Type, Value)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<99>,  Prev: Errors<62>,  Up: create_logtalk_flag/3

2.4.10.15 Examples
..................

     % create a new boolean flag with default value set to false:
     | ?- create_logtalk_flag(pretty_print_blobs, false, []).

See also
........

*note current_logtalk_flag/2: 2b3, *note set_logtalk_flag/2: 51.


File: TheLogtalkHandbook-3.101.0.info,  Node: Linter,  Prev: Flags,  Up: Built-in predicates

2.4.11 Linter
-------------

'built-in predicate'

* Menu:

* logtalk_linter_hook/7::


File: TheLogtalkHandbook-3.101.0.info,  Node: logtalk_linter_hook/7,  Up: Linter

2.4.11.1 ‘logtalk_linter_hook/7’
................................

* Menu:

* Description: Description<99>.
* Modes and number of proofs: Modes and number of proofs<62>.
* Errors: Errors<63>.
* Examples: Examples<100>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<99>,  Next: Modes and number of proofs<62>,  Up: logtalk_linter_hook/7

2.4.11.2 Description
....................

     logtalk_linter_hook(Goal, Flag, File, Lines, Type, Entity, Warning)

Multifile user-defined predicate, supporting the definition of custom
linter warnings.  Experimental.  The ‘Goal’ argument can be a
message-sending goal, ‘Object::Message’, a call to a Prolog built-in
predicate, or a call to a module predicate, ‘Module:Predicate’.  The
‘Flag’ argument must be a supported linter flag.  The ‘Warning’ argument
must be a valid ‘core’ message term.  For a given ‘Goal’, only the first
successful call to this predicate is considered.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<62>,  Next: Errors<63>,  Prev: Description<99>,  Up: logtalk_linter_hook/7

2.4.11.3 Modes and number of proofs
...................................

     logtalk_linter_hook(@callable, +atom, +atom, +pair(integer), +atom, @object_identifier, --callable) - zero_or_one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<63>,  Next: Examples<100>,  Prev: Modes and number of proofs<62>,  Up: logtalk_linter_hook/7

2.4.11.4 Errors
...............

(none)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<100>,  Prev: Errors<63>,  Up: logtalk_linter_hook/7

2.4.11.5 Examples
.................

     :- multifile(user::logtalk_linter_hook/7).
     % warn about using list::append/3 to construct a list from an head and a tail
     user::logtalk_linter_hook(
         list::append(L1,L2,L), suspicious_calls,
         File, Lines, Type, Entity,
         suspicious_call(File, Lines, Type, Entity, list::append(L1,L2,L), [L=[Head|L2]])
     ) :-
         nonvar(L1),
         L1 = [Head].


File: TheLogtalkHandbook-3.101.0.info,  Node: Built-in methods<2>,  Prev: Built-in predicates,  Up: Reference Manual

2.5 Built-in methods
====================

* Menu:

* Logic and control::
* Execution context::
* Reflection: Reflection<2>.
* Database::
* Meta-calls::
* Error handling: Error handling<2>.
* All solutions::
* Event handling: Event handling<3>.
* Message forwarding::
* Definite clause grammar rules: Definite clause grammar rules<2>.
* Term and goal expansion: Term and goal expansion<2>.
* Coinduction hooks::
* Message printing::
* Question asking::


File: TheLogtalkHandbook-3.101.0.info,  Node: Logic and control,  Next: Execution context,  Up: Built-in methods<2>

2.5.1 Logic and control
-----------------------

'built-in method'

* Menu:

* !/0::
* true/0::
* fail/0::
* false/0::
* repeat/0::


File: TheLogtalkHandbook-3.101.0.info,  Node: !/0,  Next: true/0,  Up: Logic and control

2.5.1.1 ‘!/0’
.............

* Menu:

* Description: Description<100>.
* Modes and number of proofs: Modes and number of proofs<63>.
* Errors: Errors<64>.
* Examples: Examples<101>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<100>,  Next: Modes and number of proofs<63>,  Up: !/0

2.5.1.2 Description
...................

     !

Always succeeds with the side-effect of discarding choice-points.  See
also the ISO Prolog standard definition.  This built-in method is
declared as a public method and can be used as a message to an object.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<63>,  Next: Errors<64>,  Prev: Description<100>,  Up: !/0

2.5.1.3 Modes and number of proofs
..................................

     ! - one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<64>,  Next: Examples<101>,  Prev: Modes and number of proofs<63>,  Up: !/0

2.5.1.4 Errors
..............

(none)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<101>,  Prev: Errors<64>,  Up: !/0

2.5.1.5 Examples
................

(none)

See also
........

*note true/0: 197, *note fail/0: 198, *note false/0: 199, *note
repeat/0: 19a.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: true/0,  Next: fail/0,  Prev: !/0,  Up: Logic and control

2.5.1.6 ‘true/0’
................

* Menu:

* Description: Description<101>.
* Modes and number of proofs: Modes and number of proofs<64>.
* Errors: Errors<65>.
* Examples: Examples<102>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<101>,  Next: Modes and number of proofs<64>,  Up: true/0

2.5.1.7 Description
...................

     true

Always succeeds.  See also the ISO Prolog standard definition.  This
built-in method is declared as a public method and can be used as a
message to an object.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<64>,  Next: Errors<65>,  Prev: Description<101>,  Up: true/0

2.5.1.8 Modes and number of proofs
..................................

     true - one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<65>,  Next: Examples<102>,  Prev: Modes and number of proofs<64>,  Up: true/0

2.5.1.9 Errors
..............

(none)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<102>,  Prev: Errors<65>,  Up: true/0

2.5.1.10 Examples
.................

(none)

See also
........

*note !/0: 196, *note fail/0: 198, *note false/0: 199, *note repeat/0:
19a.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: fail/0,  Next: false/0,  Prev: true/0,  Up: Logic and control

2.5.1.11 ‘fail/0’
.................

* Menu:

* Description: Description<102>.
* Modes and number of proofs: Modes and number of proofs<65>.
* Errors: Errors<66>.
* Examples: Examples<103>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<102>,  Next: Modes and number of proofs<65>,  Up: fail/0

2.5.1.12 Description
....................

     fail

Always fails.  See also the ISO Prolog standard definition.  This
built-in method is declared as a public method and can be used as a
message to an object.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<65>,  Next: Errors<66>,  Prev: Description<102>,  Up: fail/0

2.5.1.13 Modes and number of proofs
...................................

     fail - one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<66>,  Next: Examples<103>,  Prev: Modes and number of proofs<65>,  Up: fail/0

2.5.1.14 Errors
...............

(none)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<103>,  Prev: Errors<66>,  Up: fail/0

2.5.1.15 Examples
.................

(none)

See also
........

*note !/0: 196, *note true/0: 197, *note false/0: 199, *note repeat/0:
19a.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: false/0,  Next: repeat/0,  Prev: fail/0,  Up: Logic and control

2.5.1.16 ‘false/0’
..................

* Menu:

* Description: Description<103>.
* Modes and number of proofs: Modes and number of proofs<66>.
* Errors: Errors<67>.
* Examples: Examples<104>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<103>,  Next: Modes and number of proofs<66>,  Up: false/0

2.5.1.17 Description
....................

     false

Always fails.  See also the ISO Prolog standard definition.  This
built-in method is declared as a public method and can be used as a
message to an object.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<66>,  Next: Errors<67>,  Prev: Description<103>,  Up: false/0

2.5.1.18 Modes and number of proofs
...................................

     false - one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<67>,  Next: Examples<104>,  Prev: Modes and number of proofs<66>,  Up: false/0

2.5.1.19 Errors
...............

(none)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<104>,  Prev: Errors<67>,  Up: false/0

2.5.1.20 Examples
.................

(none)

See also
........

*note !/0: 196, *note true/0: 197, *note fail/0: 198, *note repeat/0:
19a.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: repeat/0,  Prev: false/0,  Up: Logic and control

2.5.1.21 ‘repeat/0’
...................

* Menu:

* Description: Description<104>.
* Modes and number of proofs: Modes and number of proofs<67>.
* Errors: Errors<68>.
* Examples: Examples<105>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<104>,  Next: Modes and number of proofs<67>,  Up: repeat/0

2.5.1.22 Description
....................

     repeat

Always succeeds when called and when backtracking into its call with an
infinite number of choice-points.  See also the ISO Prolog standard
definition.  This built-in method is declared as a public method and can
be used as a message to an object.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<67>,  Next: Errors<68>,  Prev: Description<104>,  Up: repeat/0

2.5.1.23 Modes and number of proofs
...................................

     repeat - one_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<68>,  Next: Examples<105>,  Prev: Modes and number of proofs<67>,  Up: repeat/0

2.5.1.24 Errors
...............

(none)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<105>,  Prev: Errors<68>,  Up: repeat/0

2.5.1.25 Examples
.................

(none)

See also
........

*note !/0: 196, *note true/0: 197, *note fail/0: 198, *note false/0:
199.


File: TheLogtalkHandbook-3.101.0.info,  Node: Execution context,  Next: Reflection<2>,  Prev: Logic and control,  Up: Built-in methods<2>

2.5.2 Execution context
-----------------------

'built-in method'

* Menu:

* context/1::
* parameter/2::
* self/1::
* sender/1::
* this/1::


File: TheLogtalkHandbook-3.101.0.info,  Node: context/1,  Next: parameter/2,  Up: Execution context

2.5.2.1 ‘context/1’
...................

* Menu:

* Description: Description<105>.
* Modes and number of proofs: Modes and number of proofs<68>.
* Errors: Errors<69>.
* Examples: Examples<106>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<105>,  Next: Modes and number of proofs<68>,  Up: context/1

2.5.2.2 Description
...................

     context(Context)

Returns the execution context for a predicate clause using the term
‘logtalk(Head,ExecutionContext)’ where ‘Head’ is the head of the clause
containing the call.  This private predicate is mainly used for
providing an error context when type-checking predicate arguments.  The
‘ExecutionContext’ term should be regarded as an opaque term, which can
be decoded using the logtalk::execution_context/7(1) predicate.  Calls
to this predicate are inlined at compilation time.

     Warning: As the execution context term includes the clause head,
     the head of the clause calling the ‘context(Context)’ method cannot
     contain the ‘Context’ variable as that would result in the creation
     of a cyclic term.  The compiler detects and reports any offending
     clauses by throwing a ‘representation_error(acyclic_term)’ error.

   ---------- Footnotes ----------

   (1) ../../../apis/logtalk_0.html#logtalk-0-execution-context-7


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<68>,  Next: Errors<69>,  Prev: Description<105>,  Up: context/1

2.5.2.3 Modes and number of proofs
..................................

     context(--callable) - one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<69>,  Next: Examples<106>,  Prev: Modes and number of proofs<68>,  Up: context/1

2.5.2.4 Errors
..............

(none)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<106>,  Prev: Errors<69>,  Up: context/1

2.5.2.5 Examples
................

     foo(A, N) :-
         % type-check arguments
         context(Context),
         type::check(atom, A, Context),
         type::check(integer, N, Context),
         % arguments are fine; go ahead
         ... .

See also
........

*note parameter/2: a2, *note self/1: 67, *note sender/1: 19d, *note
this/1: 68.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: parameter/2,  Next: self/1,  Prev: context/1,  Up: Execution context

2.5.2.6 ‘parameter/2’
.....................

* Menu:

* Description: Description<106>.
* Modes and number of proofs: Modes and number of proofs<69>.
* Errors: Errors<70>.
* Examples: Examples<107>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<106>,  Next: Modes and number of proofs<69>,  Up: parameter/2

2.5.2.7 Description
...................

     parameter(Number, Term)

Used in *note parametric objects: 6a1. (and parametric categories), this
private method provides runtime access to the parameter values of the
entity that contains the predicate clause whose body is being executed
by using the argument number in the entity identifier.  This predicate
is implemented as a unification between its second argument and the
corresponding implicit execution-context argument in the predicate
clause making the call.  This unification occurs at the clause head when
the second argument is not instantiated (the most common case).  When
the second argument is instantiated, the unification must be delayed to
runtime and thus occurs at the clause body.

Entity parameters can also be accessed using 'parameter variables',
which use the syntax ‘_VariableName_’.  The compiler recognizes
occurrences of these variables in directives and clauses.  Parameter
variables allow us to abstract parameter positions, thus simplifying
code maintenance.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<69>,  Next: Errors<70>,  Prev: Description<106>,  Up: parameter/2

2.5.2.8 Modes and number of proofs
..................................

     parameter(+integer, ?term) - zero_or_one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<70>,  Next: Examples<107>,  Prev: Modes and number of proofs<69>,  Up: parameter/2

2.5.2.9 Errors
..............

     ‘Number’ is a variable:
          ‘instantiation_error’
     ‘Number’ is neither a variable nor an integer value:
          ‘type_error(integer, Number)’
     ‘Number’ is smaller than one or greater than the parametric entity identifier arity:
          ‘domain_error(out_of_range, Number)’
     ‘Entity’ identifier is not a compound term:
          ‘type_error(compound, Entity)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<107>,  Prev: Errors<70>,  Up: parameter/2

2.5.2.10 Examples
.................

     :- object(box(_Color, _Weight)).

         ...

         % this clause is translated into
         % a fact upon compilation
         color(Color) :-
             parameter(1, Color).

         % upon compilation, the >/2 call will be
         % the single goal in the clause body
         heavy :-
             parameter(2, Weight),
             Weight > 10.
         ...

The same example using 'parameter variables':

     :- object(box(_Color_, _Weight_)).

         ...

         color(_Color_).

         heavy :-
             _Weight_ > 10.

         ...

See also
........

*note context/1: 19e, *note self/1: 67, *note sender/1: 19d, *note
this/1: 68.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: self/1,  Next: sender/1,  Prev: parameter/2,  Up: Execution context

2.5.2.11 ‘self/1’
.................

* Menu:

* Description: Description<107>.
* Modes and number of proofs: Modes and number of proofs<70>.
* Errors: Errors<71>.
* Examples: Examples<108>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<107>,  Next: Modes and number of proofs<70>,  Up: self/1

2.5.2.12 Description
....................

     self(Self)

Unifies its argument with the object that received the message under
processing.

This private method is compiled into a unification between its argument
and the corresponding implicit context argument in the predicate clause
making the call.  This unification occurs at the clause head when the
argument is not bound at compile-time (the most common case).


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<70>,  Next: Errors<71>,  Prev: Description<107>,  Up: self/1

2.5.2.13 Modes and number of proofs
...................................

     self(?object_identifier) - zero_or_one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<71>,  Next: Examples<108>,  Prev: Modes and number of proofs<70>,  Up: self/1

2.5.2.14 Errors
...............

(none)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<108>,  Prev: Errors<71>,  Up: self/1

2.5.2.15 Examples
.................

     % upon compilation, the write/1 call will be
     % the first goal in the clause body
     test :-
         self(Self),
         write('executing a method in behalf of '),
         writeq(Self), nl.

See also
........

*note context/1: 19e, *note parameter/2: a2, *note sender/1: 19d, *note
this/1: 68.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: sender/1,  Next: this/1,  Prev: self/1,  Up: Execution context

2.5.2.16 ‘sender/1’
...................

* Menu:

* Description: Description<108>.
* Modes and number of proofs: Modes and number of proofs<71>.
* Errors: Errors<72>.
* Examples: Examples<109>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<108>,  Next: Modes and number of proofs<71>,  Up: sender/1

2.5.2.17 Description
....................

     sender(Sender)

Unifies its argument with the object that sent the message under
processing.

This private method is translated into a unification between its
argument and the corresponding implicit context argument in the
predicate clause making the call.  This unification occurs at the clause
head when the argument is not bound at compile-time (the most common
case).


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<71>,  Next: Errors<72>,  Prev: Description<108>,  Up: sender/1

2.5.2.18 Modes and number of proofs
...................................

     sender(?object_identifier) - zero_or_one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<72>,  Next: Examples<109>,  Prev: Modes and number of proofs<71>,  Up: sender/1

2.5.2.19 Errors
...............

(none)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<109>,  Prev: Errors<72>,  Up: sender/1

2.5.2.20 Examples
.................

     % after compilation, the write/1 call will
     % be the first goal in the clause body
     test :-
         sender(Sender),
         write('executing a method to answer a message sent by '),
         writeq(Sender), nl.

See also
........

*note context/1: 19e, *note parameter/2: a2, *note self/1: 67, *note
this/1: 68.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: this/1,  Prev: sender/1,  Up: Execution context

2.5.2.21 ‘this/1’
.................

* Menu:

* Description: Description<109>.
* Modes and number of proofs: Modes and number of proofs<72>.
* Errors: Errors<73>.
* Examples: Examples<110>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<109>,  Next: Modes and number of proofs<72>,  Up: this/1

2.5.2.22 Description
....................

     this(This)

Unifies its argument with the identifier of the object calling this
method.  When this method is called from a category, the argument is
unified with the object importing the category on whose behalf the
clause containing the call is being used to prove the current goal.

This private method is implemented as a unification between its argument
and the corresponding implicit execution-context argument in the
predicate clause making the call.  This unification occurs at the clause
head when the argument is not bound at compile-time (the most common
case).

This method is useful for avoiding hard-coding references to an object
identifier or for retrieving all object parameters with a single call
when using parametric objects.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<72>,  Next: Errors<73>,  Prev: Description<109>,  Up: this/1

2.5.2.23 Modes and number of proofs
...................................

     this(?object_identifier) - zero_or_one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<73>,  Next: Examples<110>,  Prev: Modes and number of proofs<72>,  Up: this/1

2.5.2.24 Errors
...............

(none)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<110>,  Prev: Errors<73>,  Up: this/1

2.5.2.25 Examples
.................

     % after compilation, the write/1 call will
     % be the first goal in the clause body
     test :-
         this(This),
         write('Using a predicate clause contained in '),
         writeq(This), nl.

See also
........

*note context/1: 19e, *note parameter/2: a2, *note self/1: 67, *note
sender/1: 19d.


File: TheLogtalkHandbook-3.101.0.info,  Node: Reflection<2>,  Next: Database,  Prev: Execution context,  Up: Built-in methods<2>

2.5.3 Reflection
----------------

'built-in method'

* Menu:

* current_op/3::
* current_predicate/1::
* predicate_property/2::


File: TheLogtalkHandbook-3.101.0.info,  Node: current_op/3,  Next: current_predicate/1,  Up: Reflection<2>

2.5.3.1 ‘current_op/3’
......................

* Menu:

* Description: Description<110>.
* Modes and number of proofs: Modes and number of proofs<73>.
* Errors: Errors<74>.
* Examples: Examples<111>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<110>,  Next: Modes and number of proofs<73>,  Up: current_op/3

2.5.3.2 Description
...................

     current_op(Priority, Specifier, Operator)

Enumerates, by backtracking, the visible operators declared for an
object.  Operators not declared using a scope directive are not
enumerated.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<73>,  Next: Errors<74>,  Prev: Description<110>,  Up: current_op/3

2.5.3.3 Modes and number of proofs
..................................

     current_op(?operator_priority, ?operator_specifier, ?atom) - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<74>,  Next: Examples<111>,  Prev: Modes and number of proofs<73>,  Up: current_op/3

2.5.3.4 Errors
..............

     ‘Priority’ is neither a variable nor an integer:
          ‘type_error(integer, Priority)’
     ‘Priority’ is an integer but not a valid operator priority:
          ‘domain_error(operator_priority, Priority)’
     ‘Specifier’ is neither a variable nor an atom:
          ‘type_error(atom, Specifier)’
     ‘Specifier’ is an atom but not a valid operator specifier:
          ‘domain_error(operator_specifier, Specifier)’
     ‘Operator’ is neither a variable nor an atom:
          ‘type_error(atom, Operator)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<111>,  Prev: Errors<74>,  Up: current_op/3

2.5.3.5 Examples
................

     To enumerate, by backtracking, the local operators or the operators visible in *note this: 114.:
          ‘current_op(Priority, Specifier, Operator)’
     To enumerate, by backtracking, the public and protected operators visible in *note self: 69.:
          ‘::current_op(Priority, Specifier, Operator)’
     To enumerate, by backtracking, the public operators visible for an explicit object:
          ‘Object::current_op(Priority, Specifier, Operator)’

See also
........

*note current_predicate/1: 141, *note predicate_property/2: 142, *note
op/3: 15d.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: current_predicate/1,  Next: predicate_property/2,  Prev: current_op/3,  Up: Reflection<2>

2.5.3.6 ‘current_predicate/1’
.............................

* Menu:

* Description: Description<111>.
* Modes and number of proofs: Modes and number of proofs<74>.
* Errors: Errors<75>.
* Examples: Examples<112>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<111>,  Next: Modes and number of proofs<74>,  Up: current_predicate/1

2.5.3.7 Description
...................

     current_predicate(Predicate)

Enumerates, by backtracking, visible, user-defined, object predicates.
Built-in predicates and predicates not declared using a scope directive
are not enumerated.

This predicate also succeeds for any predicates listed in *note uses/2:
4b. and *note use_module/2: 4d. directives.

When ‘Predicate’ is bound at compile-time to a ‘(:)/2’ term, this
predicate enumerates module predicates (assuming that the *note backend
Prolog compiler: 34. supports modules).


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<74>,  Next: Errors<75>,  Prev: Description<111>,  Up: current_predicate/1

2.5.3.8 Modes and number of proofs
..................................

     current_predicate(?predicate_indicator) - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<75>,  Next: Examples<112>,  Prev: Modes and number of proofs<74>,  Up: current_predicate/1

2.5.3.9 Errors
..............

     ‘Predicate’ is neither a variable nor a valid predicate indicator:
          ‘type_error(predicate_indicator, Predicate)’
     ‘Predicate’ is a ‘Name/Arity’ term but ‘Functor’ is neither a variable nor an atom:
          ‘type_error(atom, Name)’
     ‘Predicate’ is a ‘Name/Arity’ term but ‘Arity’ is neither a variable nor an integer:
          ‘type_error(integer, Arity)’
     ‘Predicate’ is a ‘Name/Arity’ term but ‘Arity’ is a negative integer:
          ‘domain_error(not_less_than_zero, Arity)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<112>,  Prev: Errors<75>,  Up: current_predicate/1

2.5.3.10 Examples
.................

     To enumerate, by backtracking, the locally visible user predicates or the user predicates visible in *note this: 114.:
          ‘current_predicate(Predicate)’
     To enumerate, by backtracking, the public and protected user predicates visible in *note self: 69.:
          ‘::current_predicate(Predicate)’
     To enumerate, by backtracking, the public user predicates visible for an explicit object:
          ‘Object::current_predicate(Predicate)’

An example of enumerating locally visible object predicates.  These
include predicates listed using *note uses/2: 4b. and *note
use_module/2: 4d. directives:

     :- object(foo).

         :- uses(bar, [
             baz/1, quux/2
         ]).

         :- public(pred/1).
         pred(X) :-
            current_predicate(X).

     :- end_object.

     | ?- foo::pred(X).
     X = pred/1 ;
     X = baz/1 ;
     X = quux/2 ;
     no

See also
........

*note current_op/3: 15e, *note predicate_property/2: 142, *note uses/2:
4b, *note use_module/2: 4d.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: predicate_property/2,  Prev: current_predicate/1,  Up: Reflection<2>

2.5.3.11 ‘predicate_property/2’
...............................

* Menu:

* Description: Description<112>.
* Modes and number of proofs: Modes and number of proofs<75>.
* Errors: Errors<76>.
* Examples: Examples<113>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<112>,  Next: Modes and number of proofs<75>,  Up: predicate_property/2

2.5.3.12 Description
....................

     predicate_property(Predicate, Property)

Enumerates, by backtracking, the properties of a visible object
predicate.  Properties for predicates not declared using a scope
directive are not enumerated.  The valid predicate properties are listed
in the language grammar section on *note predicate properties: 3ef. and
described in the User Manual section on *note predicate properties: 1cc.

When ‘Predicate’ is listed in a *note uses/2: 4b. or *note use_module/2:
4d. directive, properties are enumerated for the referenced object or
module predicate.

When ‘Predicate’ is bound at compile-time to a ‘(:)/2’ term, this
predicate enumerates properties for module predicates (assuming that the
*note backend Prolog compiler: 34. supports modules).


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<75>,  Next: Errors<76>,  Prev: Description<112>,  Up: predicate_property/2

2.5.3.13 Modes and number of proofs
...................................

     predicate_property(+callable, ?predicate_property) - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<76>,  Next: Examples<113>,  Prev: Modes and number of proofs<75>,  Up: predicate_property/2

2.5.3.14 Errors
...............

     ‘Predicate’ is a variable:
          ‘instantiation_error’
     ‘Predicate’ is neither a variable nor a callable term:
          ‘type_error(callable, Predicate)’
     ‘Property’ is neither a variable nor a valid predicate property:
          ‘domain_error(predicate_property, Property)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<113>,  Prev: Errors<76>,  Up: predicate_property/2

2.5.3.15 Examples
.................

     To enumerate, by backtracking, the properties of a locally visible user predicate or a user predicate visible in *note this: 114.:
          ‘predicate_property(Predicate, Property)’
     To enumerate, by backtracking, the properties of a public or protected predicate visible in *note self: 69.:
          ‘::predicate_property(Predicate, Property)’
     To enumerate, by backtracking, the properties of a public predicate visible in an explicit object:
          ‘Object::predicate_property(Predicate, Property)’

An example of enumerating properties for locally visible object
predicates.  These include predicates listed using *note uses/2: 4b. and
*note use_module/2: 4d. directives:

     :- object(foo).

         :- uses(bar, [
             baz/1, quux/2
         ]).

         :- public(pred/1).
         pred_prop(Pred, Prop) :-
            predicate_property(Pred, Prop).

     :- end_object.

     | ?- foo::pred(baz(_), Prop).
     Prop = logtalk ;
     Prop = scope(public) ;
     Prop = public ;
     Prop = declared_in(bar) ;
     ...

See also
........

*note current_op/3: 15e, *note current_predicate/1: 141, *note uses/2:
4b, *note use_module/2: 4d.


File: TheLogtalkHandbook-3.101.0.info,  Node: Database,  Next: Meta-calls,  Prev: Reflection<2>,  Up: Built-in methods<2>

2.5.4 Database
--------------

'built-in method'

* Menu:

* abolish/1::
* asserta/1::
* assertz/1::
* clause/2::
* retract/1::
* retractall/1::


File: TheLogtalkHandbook-3.101.0.info,  Node: abolish/1,  Next: asserta/1,  Up: Database

2.5.4.1 ‘abolish/1’
...................

* Menu:

* Description: Description<113>.
* Modes and number of proofs: Modes and number of proofs<76>.
* Errors: Errors<77>.
* Examples: Examples<114>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<113>,  Next: Modes and number of proofs<76>,  Up: abolish/1

2.5.4.2 Description
...................

     abolish(Predicate)

Abolishes a runtime declared object dynamic predicate or an object local
dynamic predicate.  Only predicates that are dynamically declared at
runtime (using a call to the *note asserta/1: 1b2. or *note assertz/1:
1b3. built-in methods) can be abolished.

When the predicate indicator is declared in a *note uses/2: 4b. or *note
use_module/2: 4d. directive, the predicate is abolished in the
referenced object or module.  When the backend Prolog compiler supports
a module system, the predicate argument can also be module qualified.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<76>,  Next: Errors<77>,  Prev: Description<113>,  Up: abolish/1

2.5.4.3 Modes and number of proofs
..................................

     abolish(@predicate_indicator) - one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<77>,  Next: Examples<114>,  Prev: Modes and number of proofs<76>,  Up: abolish/1

2.5.4.4 Errors
..............

     ‘Predicate’ is a variable:
          ‘instantiation_error’
     ‘Functor’ is a variable:
          ‘instantiation_error’
     ‘Arity’ is a variable:
          ‘instantiation_error’
     ‘Predicate’ is neither a variable nor a valid predicate indicator:
          ‘type_error(predicate_indicator, Predicate)’
     ‘Functor’ is neither a variable nor an atom:
          ‘type_error(atom, Functor)’
     ‘Arity’ is neither a variable nor an integer:
          ‘type_error(integer, Arity)’
     ‘Predicate’ is statically declared:
          ‘permission_error(modify, predicate_declaration, Name/Arity)’
     ‘Predicate’ is a private predicate:
          ‘permission_error(modify, private_predicate, Name/Arity)’
     ‘Predicate’ is a protected predicate:
          ‘permission_error(modify, protected_predicate, Name/Arity)’
     ‘Predicate’ is a static predicate:
          ‘permission_error(modify, static_predicate, Name/Arity)’
     ‘Predicate’ is not declared for the object receiving the message:
          ‘existence_error(predicate_declaration, Name/Arity)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<114>,  Prev: Errors<77>,  Up: abolish/1

2.5.4.5 Examples
................

     To abolish a local dynamic predicate or a dynamic predicate in *note this: 114.:
          ‘abolish(Predicate)’
     To abolish a public or protected dynamic predicate in *note self: 69.:
          ‘::abolish(Predicate)’
     To abolish a public dynamic predicate in an explicit object:
          ‘Object::abolish(Predicate)’

See also
........

*note asserta/1: 1b2, *note assertz/1: 1b3, *note clause/2: 1b4, *note
retract/1: 1b5, *note retractall/1: 1b6. *note dynamic/0: b1, *note
dynamic/1: 15a, *note uses/2: 4b, *note use_module/2: 4d.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: asserta/1,  Next: assertz/1,  Prev: abolish/1,  Up: Database

2.5.4.6 ‘asserta/1’
...................

* Menu:

* Description: Description<114>.
* Modes and number of proofs: Modes and number of proofs<77>.
* Errors: Errors<78>.
* Examples: Examples<115>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<114>,  Next: Modes and number of proofs<77>,  Up: asserta/1

2.5.4.7 Description
...................

     asserta(Head)
     asserta((Head:-Body))

Asserts a clause as the first one for an object dynamic predicate.

When the predicate was not previously declared (using a scope
directive), a dynamic predicate declaration is added to the object.  In
this case, the predicate scope depends on how this method is called:

‘asserta(Clause)’

     The predicate is dynamically declared as *note private: 55.

‘::asserta(Clause)’

     The predicate is dynamically declared as *note protected: 54.

‘Object::asserta(Clause)’

     The predicate is dynamically declared as *note public: 53.

Note, however, that dynamically declaring a new predicate requires
either a local assert or the *note dynamic_declarations: 2d9. compiler
flag set to ‘allow’ when the object was created or compiled.

When the predicate indicator for ‘Head’ is declared in a *note uses/2:
4b. or *note use_module/2: 4d. directive, the clause is asserted in the
referenced object or module.  When the backend Prolog compiler supports
a module system, the predicate argument can also be module qualified.

This method may be used to assert clauses for predicates that are not
declared dynamic for dynamic objects provided that the predicates are
declared in *note this: 114.  This allows easy initialization of
dynamically created objects when writing constructors.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<77>,  Next: Errors<78>,  Prev: Description<114>,  Up: asserta/1

2.5.4.8 Modes and number of proofs
..................................

     asserta(+clause) - one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<78>,  Next: Examples<115>,  Prev: Modes and number of proofs<77>,  Up: asserta/1

2.5.4.9 Errors
..............

     ‘Head’ is a variable:
          ‘instantiation_error’
     ‘Head’ is neither a variable nor a callable term:
          ‘type_error(callable, Head)’
     ‘Body’ cannot be converted to a goal:
          ‘type_error(callable, Body)’
     The predicate indicator of ‘Head’, ‘Name/Arity’, is that of a private predicate:
          ‘permission_error(modify, private_predicate, Name/Arity)’
     The predicate indicator of ‘Head’, ‘Name/Arity’, is that of a protected predicate:
          ‘permission_error(modify, protected_predicate, Name/Arity)’
     The predicate indicator of ‘Head’, ‘Name/Arity’, is that of a static predicate:
          ‘permission_error(modify, static_predicate, Name/Arity)’
     The predicate indicator of ‘Head’, ‘Name/Arity’, does not match a declared predicate and the target object was created or compiled with support for dynamic declaration of predicates turned off:
          ‘permission_error(create, predicate_declaration, Name/Arity)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<115>,  Prev: Errors<78>,  Up: asserta/1

2.5.4.10 Examples
.................

     To assert a clause as the first one for a local dynamic predicate or a dynamic predicate in *note this: 114.:
          ‘asserta(Clause)’
     To assert a clause as the first one for any public or protected dynamic predicate in *note self: 69.:
          ‘::asserta(Clause)’
     To assert a clause as the first one for any public dynamic predicate in an explicit object:
          ‘Object::asserta(Clause)’

An example of asserting clauses in *note this: 114. and in *note self:
69. from a category:

     :- category(attributes,
         implements(attributes_protocol)).

         :- private(attr_/1).
         :- dynamic(attr_/1).

         set_in_this(A, X) :-
            asserta(attr_(A, X)).

         set_in_self(A, X) :-
            ::asserta(attr_(A, X)).

         ...

An example of asserting clauses into another object with the predicates
listed using a *note uses/2: 4b. directive (similar when using a *note
use_module/2: 4d. directive):

     :- object(reasoner(_KnowledgeBase_)).

         :- uses(_KnowledgeBase_, [
             foo/1, bar/1
         ]).

         baz(X) :-
            % compiled as _KnowledgeBase_::assertz(foo(X))
            asserta(foo(X)).

        foobar(Name, Argument) :-
           Clause =.. [Name, Argument],
           % runtime resolved to _KnowledgeBase_::assertz(Clause)
           % when Name is either foo or bar
           asserta(Clause).

         ...

See also
........

*note abolish/1: 1b1, *note assertz/1: 1b3, *note clause/2: 1b4, *note
retract/1: 1b5, *note retractall/1: 1b6. *note dynamic/0: b1, *note
dynamic/1: 15a, *note uses/2: 4b, *note use_module/2: 4d.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: assertz/1,  Next: clause/2,  Prev: asserta/1,  Up: Database

2.5.4.11 ‘assertz/1’
....................

* Menu:

* Description: Description<115>.
* Modes and number of proofs: Modes and number of proofs<78>.
* Errors: Errors<79>.
* Examples: Examples<116>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<115>,  Next: Modes and number of proofs<78>,  Up: assertz/1

2.5.4.12 Description
....................

     assertz(Head)
     assertz((Head:-Body))

Asserts a clause as the last one for a dynamic predicate.

When the predicate was not previously declared (using a scope
directive), a dynamic predicate declaration is added to the object.  In
this case, the predicate scope depends on how this method is called:

‘assertz(Clause)’

     The predicate is dynamically declared as *note private: 55.

‘::assertz(Clause)’

     The predicate is dynamically declared as *note protected: 54.

‘Object::assertz(Clause)’

     The predicate is dynamically declared as *note public: 53.

Note, however, that dynamically declaring a new predicate requires
either a local assert or the *note dynamic_declarations: 2d9. compiler
flag set to ‘allow’ when the object was created or compiled.

When the predicate indicator for ‘Head’ is declared in a *note uses/2:
4b. or *note use_module/2: 4d. directive, the clause is asserted in the
referenced object or module.  When the backend Prolog compiler supports
a module system, the predicate argument can also be module qualified.

This method may be used to assert clauses for predicates that are not
declared dynamic for dynamic objects provided that the predicates are
declared in *note this: 114.  This allows easy initialization of
dynamically created objects when writing constructors.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<78>,  Next: Errors<79>,  Prev: Description<115>,  Up: assertz/1

2.5.4.13 Modes and number of proofs
...................................

     assertz(+clause) - one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<79>,  Next: Examples<116>,  Prev: Modes and number of proofs<78>,  Up: assertz/1

2.5.4.14 Errors
...............

     ‘Head’ is a variable:
          ‘instantiation_error’
     ‘Head’ is neither a variable nor a callable term:
          ‘type_error(callable, Head)’
     ‘Body’ cannot be converted to a goal:
          ‘type_error(callable, Body)’
     The predicate indicator of ‘Head’, ‘Name/Arity’, is that of a private predicate:
          ‘permission_error(modify, private_predicate, Name/Arity)’
     The predicate indicator of ‘Head’, ‘Name/Arity’, is that of a protected predicate:
          ‘permission_error(modify, protected_predicate, Name/Arity)’
     The predicate indicator of ‘Head’, ‘Name/Arity’, is that of a static predicate:
          ‘permission_error(modify, static_predicate, Name/Arity)’
     The predicate indicator of ‘Head’, ‘Name/Arity’, does not match a declared predicate and the target object was created/compiled with support for dynamic declaration of predicates turned off:
          ‘permission_error(create, predicate_declaration, Name/Arity)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<116>,  Prev: Errors<79>,  Up: assertz/1

2.5.4.15 Examples
.................

     To assert a clause as the last one for a local dynamic predicate or a dynamic predicate in *note this: 114.:
          ‘assertz(Clause)’
     To assert a clause as the last one for any public or protected dynamic predicate in *note self: 69.:
          ‘::assertz(Clause)’
     To assert a clause as the last one for any public dynamic predicate in an explicit object:
          ‘Object::assertz(Clause)’

An example of asserting clauses in *note this: 114. and in *note self:
69. from a category:

     :- category(attributes,
         implements(attributes_protocol)).

         :- private(attr_/1).
         :- dynamic(attr_/1).

         set_in_this(A, X) :-
            assertz(attr_(A, X)).

         set_in_self(A, X) :-
            ::assertz(attr_(A, X)).

         ...

An example of asserting clauses into another object with the predicates
listed using a *note uses/2: 4b. directive (similar when using a *note
use_module/2: 4d. directive):

     :- object(reasoner(_KnowledgeBase_)).

         :- uses(_KnowledgeBase_, [
             foo/1, bar/1
         ]).

         baz(X) :-
            % compiled as _KnowledgeBase_::assertz(foo(X))
            assertz(foo(X)).

        foobar(Name, Argument) :-
           Clause =.. [Name, Argument],
           % runtime resolved to _KnowledgeBase_::assertz(Clause)
           % when Name is either foo or bar
           assertz(Clause).

         ...

See also
........

*note abolish/1: 1b1, *note asserta/1: 1b2, *note clause/2: 1b4, *note
retract/1: 1b5, *note retractall/1: 1b6. *note dynamic/0: b1, *note
dynamic/1: 15a, *note uses/2: 4b, *note use_module/2: 4d.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: clause/2,  Next: retract/1,  Prev: assertz/1,  Up: Database

2.5.4.16 ‘clause/2’
...................

* Menu:

* Description: Description<116>.
* Modes and number of proofs: Modes and number of proofs<79>.
* Errors: Errors<80>.
* Examples: Examples<117>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<116>,  Next: Modes and number of proofs<79>,  Up: clause/2

2.5.4.17 Description
....................

     clause(Head, Body)

Enumerates, by backtracking, the clauses of a dynamic predicate.

When the predicate indicator for ‘Head’ is declared in a *note uses/2:
4b. or *note use_module/2: 4d. directive, the predicate enumerates the
clauses in the referenced object or module.  When the backend Prolog
compiler supports a module system, the head argument can also be module
qualified.

This method may be used to enumerate clauses for predicates that are not
declared dynamic for dynamic objects provided that the predicates are
declared in *note this: 114.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<79>,  Next: Errors<80>,  Prev: Description<116>,  Up: clause/2

2.5.4.18 Modes and number of proofs
...................................

     clause(+callable, ?body) - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<80>,  Next: Examples<117>,  Prev: Modes and number of proofs<79>,  Up: clause/2

2.5.4.19 Errors
...............

     ‘Head’ is a variable:
          ‘instantiation_error’
     ‘Head’ is neither a variable nor a callable term:
          ‘type_error(callable, Head)’
     ‘Body’ is neither a variable nor a callable term:
          ‘type_error(callable, Body)’
     The predicate indicator of ‘Head’, ‘Name/Arity’, is that of a private predicate:
          ‘permission_error(access, private_predicate, Name/Arity)’
     The predicate indicator of ‘Head’, ‘Name/Arity’, is that of a protected predicate:
          ‘permission_error(access, protected_predicate, Name/Arity)’
     The predicate indicator of ‘Head’, ‘Name/Arity’, is that of a static predicate:
          ‘permission_error(access, static_predicate, Name/Arity)’
     ‘Head’ is not a declared predicate:
          ‘existence_error(predicate_declaration, Name/Arity)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<117>,  Prev: Errors<80>,  Up: clause/2

2.5.4.20 Examples
.................

     To retrieve a matching clause of a local dynamic predicate or a dynamic predicate in *note this: 114.:
          ‘clause(Head, Body)’
     To retrieve a matching clause of a public or protected dynamic predicate in *note self: 69.:
          ‘::clause(Head, Body)’
     To retrieve a matching clause of a public dynamic predicate in an explicit object:
          ‘Object::clause(Head, Body)’

See also
........

*note abolish/1: 1b1, *note asserta/1: 1b2, *note assertz/1: 1b3, *note
retract/1: 1b5, *note retractall/1: 1b6. *note dynamic/0: b1, *note
dynamic/1: 15a, *note uses/2: 4b, *note use_module/2: 4d.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: retract/1,  Next: retractall/1,  Prev: clause/2,  Up: Database

2.5.4.21 ‘retract/1’
....................

* Menu:

* Description: Description<117>.
* Modes and number of proofs: Modes and number of proofs<80>.
* Errors: Errors<81>.
* Examples: Examples<118>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<117>,  Next: Modes and number of proofs<80>,  Up: retract/1

2.5.4.22 Description
....................

     retract(Head)
     retract((Head:-Body))

Retracts a clause for an object dynamic predicate.  On backtracking, the
predicate retracts the next matching clause.

When the predicate indicator for ‘Head’ is declared in a *note uses/2:
4b. or *note use_module/2: 4d. directive, the clause is retracted in the
referenced object or module.  When the backend Prolog compiler supports
a module system, the predicate argument can also be module qualified.

This method may be used to retract clauses for predicates that are not
declared dynamic for dynamic objects provided that the predicates are
declared in *note this: 114.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<80>,  Next: Errors<81>,  Prev: Description<117>,  Up: retract/1

2.5.4.23 Modes and number of proofs
...................................

     retract(+clause) - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<81>,  Next: Examples<118>,  Prev: Modes and number of proofs<80>,  Up: retract/1

2.5.4.24 Errors
...............

     ‘Head’ is a variable:
          ‘instantiation_error’
     ‘Head’ is neither a variable nor a callable term:
          ‘type_error(callable, Head)’
     The predicate indicator of ‘Head’, ‘Name/Arity’, is that of a private predicate:
          ‘permission_error(modify, private_predicate, Name/Arity)’
     The predicate indicator of ‘Head’, ‘Name/Arity’, is that of a protected predicate:
          ‘permission_error(modify, protected_predicate, Name/Arity)’
     The predicate indicator of ‘Head’, ‘Name/Arity’, is that of a static predicate:
          ‘permission_error(modify, static_predicate, Name/Arity)’
     The predicate indicator of ‘Head’, ‘Name/Arity’, is not declared:
          ‘existence_error(predicate_declaration, Name/Arity)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<118>,  Prev: Errors<81>,  Up: retract/1

2.5.4.25 Examples
.................

     To retract a matching clause of a dynamic predicate in *note this: 114.:
          ‘retract(Clause)’
     To retract a matching clause of a public or protected dynamic predicate in *note self: 69.:
          ‘::retract(Clause)’
     To retract a matching clause of a public dynamic predicate in an explicit object:
          ‘Object::retract(Clause)’

See also
........

*note abolish/1: 1b1, *note asserta/1: 1b2, *note assertz/1: 1b3, *note
clause/2: 1b4, *note retractall/1: 1b6, *note dynamic/0: b1, *note
dynamic/1: 15a, *note uses/2: 4b, *note use_module/2: 4d.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: retractall/1,  Prev: retract/1,  Up: Database

2.5.4.26 ‘retractall/1’
.......................

* Menu:

* Description: Description<118>.
* Modes and number of proofs: Modes and number of proofs<81>.
* Errors: Errors<82>.
* Examples: Examples<119>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<118>,  Next: Modes and number of proofs<81>,  Up: retractall/1

2.5.4.27 Description
....................

     retractall(Head)

Retracts all clauses with a matching head for an object dynamic
predicate.

When the predicate indicator for ‘Head’ is declared in a *note uses/2:
4b. or *note use_module/2: 4d. directive, the clauses are retracted in
the referenced object or module.  When the backend Prolog compiler
supports a module system, the predicate argument can also be module
qualified.

This method may be used to retract clauses for predicates that are not
declared dynamic for dynamic objects provided that the predicates are
declared in *note this: 114.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<81>,  Next: Errors<82>,  Prev: Description<118>,  Up: retractall/1

2.5.4.28 Modes and number of proofs
...................................

     retractall(@callable) - one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<82>,  Next: Examples<119>,  Prev: Modes and number of proofs<81>,  Up: retractall/1

2.5.4.29 Errors
...............

     ‘Head’ is a variable:
          ‘instantiation_error’
     ‘Head’ is neither a variable nor a callable term:
          ‘type_error(callable, Head)’
     The predicate indicator of ‘Head’, ‘Name/Arity’, is that of a private predicate:
          ‘permission_error(modify, private_predicate, Name/Arity)’
     The predicate indicator of ‘Head’, ‘Name/Arity’, is that of a protected predicate:
          ‘permission_error(modify, protected_predicate, Name/Arity)’
     The predicate indicator of ‘Head’, ‘Name/Arity’, is that of a static predicate:
          ‘permission_error(modify, static_predicate, Name/Arity)’
     The predicate indicator of ‘Head’, ‘Name/Arity’, is not declared:
          ‘existence_error(predicate_declaration, Name/Arity)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<119>,  Prev: Errors<82>,  Up: retractall/1

2.5.4.30 Examples
.................

     To retract all clauses with a matching head of a dynamic predicate in *note this: 114.:
          ‘retractall(Head)’
     To retract all clauses with a matching head of a public or protected dynamic predicate in *note self: 69.:
          ‘::retractall(Head)’
     To retract all clauses with a matching head of a public dynamic predicate in an explicit object:
          ‘Object::retractall(Head)’

See also
........

*note abolish/1: 1b1, *note asserta/1: 1b2, *note assertz/1: 1b3, *note
clause/2: 1b4, *note retract/1: 1b5, *note dynamic/0: b1, *note
dynamic/1: 15a, *note uses/2: 4b, *note use_module/2: 4d.


File: TheLogtalkHandbook-3.101.0.info,  Node: Meta-calls,  Next: Error handling<2>,  Prev: Database,  Up: Built-in methods<2>

2.5.5 Meta-calls
----------------

'built-in method'

* Menu:

* call/1-N::
* ignore/1::
* once/1::
* (\+)/1: \+ /1.


File: TheLogtalkHandbook-3.101.0.info,  Node: call/1-N,  Next: ignore/1,  Up: Meta-calls

2.5.5.1 ‘call/1-N’
..................

* Menu:

* Description: Description<119>.
* Meta-predicate template: Meta-predicate template<6>.
* Modes and number of proofs: Modes and number of proofs<82>.
* Errors: Errors<83>.
* Examples: Examples<120>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<119>,  Next: Meta-predicate template<6>,  Up: call/1-N

2.5.5.2 Description
...................

     call(Goal)
     call(Closure, Arg1, ...)

Calls a goal constructed by appending additional arguments to a *note
closure: 14f.  The upper limit for ‘N’ depends on the upper limit for
the arity of a compound term of the *note backend Prolog compiler: 34.
This built-in meta-predicate is declared as a private method and thus
cannot be used as a message to an object.  The ‘Closure’ argument can
also be a lambda expression or a Logtalk control construct.  When using
a backend Prolog compiler supporting a module system, calls in the
format ‘call(Module:Closure, Arg1, ...)’ may also be used.

This meta-predicate is opaque to cuts in its arguments.


File: TheLogtalkHandbook-3.101.0.info,  Node: Meta-predicate template<6>,  Next: Modes and number of proofs<82>,  Prev: Description<119>,  Up: call/1-N

2.5.5.3 Meta-predicate template
...............................

     call(0)
     call(1, *)
     call(2, *, *)
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<82>,  Next: Errors<83>,  Prev: Meta-predicate template<6>,  Up: call/1-N

2.5.5.4 Modes and number of proofs
..................................

     call(+callable) - zero_or_more
     call(+callable, ?term) - zero_or_more
     call(+callable, ?term, ?term) - zero_or_more
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<83>,  Next: Examples<120>,  Prev: Modes and number of proofs<82>,  Up: call/1-N

2.5.5.5 Errors
..............

     ‘Goal’ is a variable:
          ‘instantiation_error’
     ‘Goal’ is neither a variable nor a callable term:
          ‘type_error(callable, Goal)’
     ‘Closure’ is a variable:
          ‘instantiation_error’
     ‘Closure’ is neither a variable nor a callable term:
          ‘type_error(callable, Closure)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<120>,  Prev: Errors<83>,  Up: call/1-N

2.5.5.6 Examples
................

     Call a goal, constructed by appending additional arguments to a closure, in the context of the object or category containing the call:
          ‘call(Closure, Arg1, Arg2, ...)’
     To send a goal, constructed by appending additional arguments to a closure, as a message to *note self: 69.:
          ‘call(::Closure, Arg1, Arg2, ...)’
     To send a goal, constructed by appending additional arguments to a closure, as a message to an explicit object:
          ‘call(Object::Closure, Arg1, Arg2, ...)’

See also
........

*note ignore/1: 180, *note once/1: 1bb, *note (\+)/1: 1bc.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: ignore/1,  Next: once/1,  Prev: call/1-N,  Up: Meta-calls

2.5.5.7 ‘ignore/1’
..................

* Menu:

* Description: Description<120>.
* Meta-predicate template: Meta-predicate template<7>.
* Modes and number of proofs: Modes and number of proofs<83>.
* Errors: Errors<84>.
* Examples: Examples<121>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<120>,  Next: Meta-predicate template<7>,  Up: ignore/1

2.5.5.8 Description
...................

     ignore(Goal)

This predicate succeeds whether its argument succeeds or fails and it is
not re-executable.  This built-in meta-predicate is declared as a
private method and thus cannot be used as a message to an object.

This meta-predicate is opaque to cuts in its argument.


File: TheLogtalkHandbook-3.101.0.info,  Node: Meta-predicate template<7>,  Next: Modes and number of proofs<83>,  Prev: Description<120>,  Up: ignore/1

2.5.5.9 Meta-predicate template
...............................

     ignore(0)


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<83>,  Next: Errors<84>,  Prev: Meta-predicate template<7>,  Up: ignore/1

2.5.5.10 Modes and number of proofs
...................................

     ignore(+callable) - one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<84>,  Next: Examples<121>,  Prev: Modes and number of proofs<83>,  Up: ignore/1

2.5.5.11 Errors
...............

     ‘Goal’ is a variable:
          ‘instantiation_error’
     ‘Goal’ is neither a variable nor a callable term:
          ‘type_error(callable, Goal)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<121>,  Prev: Errors<84>,  Up: ignore/1

2.5.5.12 Examples
.................

     Call a goal and succeeding even if it fails:
          ‘ignore(Goal)’
     To send a message succeeding even if it fails to *note self: 69.:
          ‘ignore(::Goal)’
     To send a message succeeding even if it fails to an explicit object:
          ‘ignore(Object::Goal)’

See also
........

*note call/1-N: 181, *note once/1: 1bb, *note (\+)/1: 1bc.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: once/1,  Next: \+ /1,  Prev: ignore/1,  Up: Meta-calls

2.5.5.13 ‘once/1’
.................

* Menu:

* Description: Description<121>.
* Meta-predicate template: Meta-predicate template<8>.
* Modes and number of proofs: Modes and number of proofs<84>.
* Errors: Errors<85>.
* Examples: Examples<122>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<121>,  Next: Meta-predicate template<8>,  Up: once/1

2.5.5.14 Description
....................

     once(Goal)

This predicate behaves as ‘call(Goal)’ but it is not re-executable.
This built-in meta-predicate is declared as a private method and thus
cannot be used as a message to an object.

This meta-predicate is opaque to cuts in its argument.


File: TheLogtalkHandbook-3.101.0.info,  Node: Meta-predicate template<8>,  Next: Modes and number of proofs<84>,  Prev: Description<121>,  Up: once/1

2.5.5.15 Meta-predicate template
................................

     once(0)


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<84>,  Next: Errors<85>,  Prev: Meta-predicate template<8>,  Up: once/1

2.5.5.16 Modes and number of proofs
...................................

     once(+callable) - zero_or_one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<85>,  Next: Examples<122>,  Prev: Modes and number of proofs<84>,  Up: once/1

2.5.5.17 Errors
...............

     ‘Goal’ is a variable:
          ‘instantiation_error’
     ‘Goal’ is neither a variable nor a callable term:
          ‘type_error(callable, Goal)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<122>,  Prev: Errors<85>,  Up: once/1

2.5.5.18 Examples
.................

     Call a goal deterministically in the context of the object or category containing the call:
          ‘once(Goal)’
     To send a goal as a non-backtracable message to *note self: 69.:
          ‘once(::Goal)’
     To send a goal as a non-backtracable message to an explicit object:
          ‘once(Object::Goal)’

See also
........

*note call/1-N: 181, *note ignore/1: 180, *note (\+)/1: 1bc.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: \+ /1,  Prev: once/1,  Up: Meta-calls

2.5.5.19 ‘(\+)/1’
.................

* Menu:

* Description: Description<122>.
* Meta-predicate template: Meta-predicate template<9>.
* Modes and number of proofs: Modes and number of proofs<85>.
* Errors: Errors<86>.
* Examples: Examples<123>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<122>,  Next: Meta-predicate template<9>,  Up: \+ /1

2.5.5.20 Description
....................

     \+ Goal

Not-provable meta-predicate.  True iff ‘call(Goal)’ is false.  This
built-in meta-predicate is declared as a private method and thus cannot
be used as a message to an object.

     Warning: The argument is always compiled (for improved
     performance).  As a consequence, when the argument is a control
     construct (e.g., a conjunction), any meta-variables will be wrapped
     with the equivalent to the ‘call/1’ control construct.  Note that
     these semantics differ from the ISO Prolog Core standard
     specification for the ‘(\+)/1’ built-in predicate.  For example,
     assuming a conforming system:

          | ?- X = !, \+ (member(Y,[1,2,3]), X, write(Y), fail).
          1

          X = !

     But in Logtalk ‘X’ is compiled into a meta-call, which is not
     cut-transparent:

          yes
          | ?- logtalk << (X = !, \+ (member(Y,[1,2,3]), X, write(Y), fail)).
          123

          X = !

     Note that the ISO Prolog Core standard doesn’t specify a
     cut-transparent alternative to the ‘call/1’ control construct.


File: TheLogtalkHandbook-3.101.0.info,  Node: Meta-predicate template<9>,  Next: Modes and number of proofs<85>,  Prev: Description<122>,  Up: \+ /1

2.5.5.21 Meta-predicate template
................................

     \+ 0


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<85>,  Next: Errors<86>,  Prev: Meta-predicate template<9>,  Up: \+ /1

2.5.5.22 Modes and number of proofs
...................................

     \+ +callable - zero_or_one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<86>,  Next: Examples<123>,  Prev: Modes and number of proofs<85>,  Up: \+ /1

2.5.5.23 Errors
...............

     ‘Goal’ is a variable:
          ‘instantiation_error’
     ‘Goal’ is neither a variable nor a callable term:
          ‘type_error(callable, Goal)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<123>,  Prev: Errors<86>,  Up: \+ /1

2.5.5.24 Examples
.................

     Not-provable goal in the context of the object or category containing the call:
          ‘\+ Goal’
     Not-provable goal sent as a message to *note self: 69.:
          ‘\+ ::Goal’
     Not-provable goal sent as a message to an explicit object:
          ‘\+ Object::Goal’

See also
........

*note call/1-N: 181, *note ignore/1: 180, *note once/1: 1bb.


File: TheLogtalkHandbook-3.101.0.info,  Node: Error handling<2>,  Next: All solutions,  Prev: Meta-calls,  Up: Built-in methods<2>

2.5.6 Error handling
--------------------

'built-in method'

* Menu:

* catch/3::
* throw/1::
* instantiation_error/0::
* uninstantiation_error/1::
* type_error/2::
* domain_error/2::
* consistency_error/3::
* existence_error/2::
* permission_error/3::
* representation_error/1::
* evaluation_error/1::
* resource_error/1::
* syntax_error/1::
* system_error/0::


File: TheLogtalkHandbook-3.101.0.info,  Node: catch/3,  Next: throw/1,  Up: Error handling<2>

2.5.6.1 ‘catch/3’
.................

* Menu:

* Description: Description<123>.
* Modes and number of proofs: Modes and number of proofs<86>.
* Errors: Errors<87>.
* Examples: Examples<124>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<123>,  Next: Modes and number of proofs<86>,  Up: catch/3

2.5.6.2 Description
...................

     catch(Goal, Catcher, Recovery)

Catches exceptions thrown by a goal.  See also the ISO Prolog standard
definition.  This built-in meta-predicate is declared as a private
method and thus cannot be used as a message to an object.

This method can also be used in grammar rules.  In this case, the
meta-arguments are interpreted as grammar rule bodies.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<86>,  Next: Errors<87>,  Prev: Description<123>,  Up: catch/3

2.5.6.3 Modes and number of proofs
..................................

     catch(?callable, ?term, ?callable) - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<87>,  Next: Examples<124>,  Prev: Modes and number of proofs<86>,  Up: catch/3

2.5.6.4 Errors
..............

(none)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<124>,  Prev: Errors<87>,  Up: catch/3

2.5.6.5 Examples
................

(none)

See also
........

*note throw/1: 1a2, *note context/1: 19e, *note instantiation_error/0:
1a3, *note uninstantiation_error/1: 1a4, *note type_error/2: 1a5, *note
domain_error/2: 1a6, *note consistency_error/3: 719, *note
existence_error/2: 1a7, *note permission_error/3: 1a8, *note
evaluation_error/1: 1aa, *note representation_error/1: 1a9. *note
resource_error/1: 1ab, *note syntax_error/1: 1ac, *note system_error/0:
1ad.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: throw/1,  Next: instantiation_error/0,  Prev: catch/3,  Up: Error handling<2>

2.5.6.6 ‘throw/1’
.................

* Menu:

* Description: Description<124>.
* Modes and number of proofs: Modes and number of proofs<87>.
* Errors: Errors<88>.
* Examples: Examples<125>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<124>,  Next: Modes and number of proofs<87>,  Up: throw/1

2.5.6.7 Description
...................

     throw(Exception)

Throws an exception.  See also the ISO Prolog standard definition.  This
built-in method is declared private and thus cannot be used as a message
to an object.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<87>,  Next: Errors<88>,  Prev: Description<124>,  Up: throw/1

2.5.6.8 Modes and number of proofs
..................................

     throw(+nonvar) - error


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<88>,  Next: Examples<125>,  Prev: Modes and number of proofs<87>,  Up: throw/1

2.5.6.9 Errors
..............

     ‘Exception’ is a variable:
          ‘instantiation_error’
     ‘Exception’ does not unify with the second argument of any call of *note catch/3: 1a1.:
          ‘system_error’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<125>,  Prev: Errors<88>,  Up: throw/1

2.5.6.10 Examples
.................

(none)

See also
........

*note catch/3: 1a1, *note context/1: 19e, *note instantiation_error/0:
1a3, *note uninstantiation_error/1: 1a4, *note type_error/2: 1a5, *note
domain_error/2: 1a6, *note consistency_error/3: 719, *note
existence_error/2: 1a7, *note permission_error/3: 1a8, *note
evaluation_error/1: 1aa, *note representation_error/1: 1a9. *note
resource_error/1: 1ab, *note syntax_error/1: 1ac, *note system_error/0:
1ad.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: instantiation_error/0,  Next: uninstantiation_error/1,  Prev: throw/1,  Up: Error handling<2>

2.5.6.11 ‘instantiation_error/0’
................................

* Menu:

* Description: Description<125>.
* Modes and number of proofs: Modes and number of proofs<88>.
* Errors: Errors<89>.
* Examples: Examples<126>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<125>,  Next: Modes and number of proofs<88>,  Up: instantiation_error/0

2.5.6.12 Description
....................

     instantiation_error

Throws an instantiation error.  Used when an argument or one of its
sub-arguments is a variable but a non-variable term is required.  For
example, trying to open a file with a variable for the input/output
mode.

This built-in method is declared private and thus cannot be used as a
message to an object.  Calling this predicate is equivalent to the
following sequence of calls:

     ...,
     context(Context),
     throw(error(instantiation_error, Context)).

This allows the user to generate errors in the same format used by the
runtime.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<88>,  Next: Errors<89>,  Prev: Description<125>,  Up: instantiation_error/0

2.5.6.13 Modes and number of proofs
...................................

     instantiation_error - error


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<89>,  Next: Examples<126>,  Prev: Modes and number of proofs<88>,  Up: instantiation_error/0

2.5.6.14 Errors
...............

     When called:
          ‘instantiation_error’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<126>,  Prev: Errors<89>,  Up: instantiation_error/0

2.5.6.15 Examples
.................

     ...,
     var(Handler),
     instantiation_error.

See also
........

*note catch/3: 1a1, *note throw/1: 1a2, *note context/1: 19e, *note
uninstantiation_error/1: 1a4, *note type_error/2: 1a5, *note
domain_error/2: 1a6, *note consistency_error/3: 719, *note
existence_error/2: 1a7, *note permission_error/3: 1a8, *note
representation_error/1: 1a9, *note evaluation_error/1: 1aa, *note
resource_error/1: 1ab, *note syntax_error/1: 1ac, *note system_error/0:
1ad.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: uninstantiation_error/1,  Next: type_error/2,  Prev: instantiation_error/0,  Up: Error handling<2>

2.5.6.16 ‘uninstantiation_error/1’
..................................

* Menu:

* Description: Description<126>.
* Modes and number of proofs: Modes and number of proofs<89>.
* Errors: Errors<90>.
* Examples: Examples<127>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<126>,  Next: Modes and number of proofs<89>,  Up: uninstantiation_error/1

2.5.6.17 Description
....................

     uninstantiation_error(Culprit)

Throws an uninstantiation error.  Used when an argument or one of its
sub-arguments is bound but a variable is required.  For example, trying
to open a file with a stream argument bound.

This built-in method is declared private and thus cannot be used as a
message to an object.  Calling this predicate is equivalent to the
following sequence of calls:

     ...,
     context(Context),
     throw(error(uninstantiation_error(Culprit), Context)).

This allows the user to generate errors in the same format used by the
runtime.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<89>,  Next: Errors<90>,  Prev: Description<126>,  Up: uninstantiation_error/1

2.5.6.18 Modes and number of proofs
...................................

     uninstantiation_error(@nonvar) - error


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<90>,  Next: Examples<127>,  Prev: Modes and number of proofs<89>,  Up: uninstantiation_error/1

2.5.6.19 Errors
...............

     When called:
          ‘uninstantiation_error(Culprit)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<127>,  Prev: Errors<90>,  Up: uninstantiation_error/1

2.5.6.20 Examples
.................

     ...,
     var(Handler),
     uninstantiation_error(my_stream).

See also
........

*note catch/3: 1a1, *note throw/1: 1a2, *note context/1: 19e, *note
instantiation_error/0: 1a3, *note type_error/2: 1a5, *note
domain_error/2: 1a6, *note consistency_error/3: 719, *note
existence_error/2: 1a7, *note permission_error/3: 1a8, *note
representation_error/1: 1a9, *note evaluation_error/1: 1aa, *note
resource_error/1: 1ab, *note syntax_error/1: 1ac, *note system_error/0:
1ad.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: type_error/2,  Next: domain_error/2,  Prev: uninstantiation_error/1,  Up: Error handling<2>

2.5.6.21 ‘type_error/2’
.......................

* Menu:

* Description: Description<127>.
* Modes and number of proofs: Modes and number of proofs<90>.
* Errors: Errors<91>.
* Examples: Examples<128>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<127>,  Next: Modes and number of proofs<90>,  Up: type_error/2

2.5.6.22 Description
....................

     type_error(Type, Culprit)

Throws a type error.  Used when the type of an argument is incorrect.
For example, trying to use a non-callable term as a message.  This
built-in method is declared private and thus cannot be used as a message
to an object.  Calling this predicate is equivalent to the following
sequence of goals:

     ...,
     context(Context),
     throw(error(type_error(Type,Culprit), Context)).

This allows the user to generate errors in the same format used by the
runtime.

Possible values for ‘Type’ include all the types defined by the ‘type’
library object and by other libraries such as ‘os’, ‘expecteds’, and
‘optionals’.  The value of ‘Culprit’ is the argument or one of its
sub-terms that caused the error.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<90>,  Next: Errors<91>,  Prev: Description<127>,  Up: type_error/2

2.5.6.23 Modes and number of proofs
...................................

     type_error(@nonvar, @term) - error


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<91>,  Next: Examples<128>,  Prev: Modes and number of proofs<90>,  Up: type_error/2

2.5.6.24 Errors
...............

     When called:
          ‘type_error(Type, Culprit)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<128>,  Prev: Errors<91>,  Up: type_error/2

2.5.6.25 Examples
.................

     ...,
     \+ atom(Name),
     type_error(atom, Name).

See also
........

*note catch/3: 1a1, *note throw/1: 1a2, *note context/1: 19e, *note
instantiation_error/0: 1a3, *note uninstantiation_error/1: 1a4, *note
domain_error/2: 1a6, *note consistency_error/3: 719, *note
existence_error/2: 1a7, *note permission_error/3: 1a8, *note
representation_error/1: 1a9. *note evaluation_error/1: 1aa, *note
resource_error/1: 1ab, *note syntax_error/1: 1ac, *note system_error/0:
1ad,

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: domain_error/2,  Next: consistency_error/3,  Prev: type_error/2,  Up: Error handling<2>

2.5.6.26 ‘domain_error/2’
.........................

* Menu:

* Description: Description<128>.
* Modes and number of proofs: Modes and number of proofs<91>.
* Errors: Errors<92>.
* Examples: Examples<129>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<128>,  Next: Modes and number of proofs<91>,  Up: domain_error/2

2.5.6.27 Description
....................

     domain_error(Domain, Culprit)

Throws a domain error.  Used when an argument is of the correct type but
outside the valid domain.  For example, trying to use an atom as an
operator specifier that is not a valid specifier.  This built-in method
is declared private and thus cannot be used as a message to an object.
Calling this predicate is equivalent to the following sequence of goals:

     ...,
     context(Context),
     throw(error(domain_error(Domain,Culprit), Context)).

This allows the user to generate errors in the same format used by the
runtime.

Possible values for ‘Domain’ include:

   - ‘character_code_list’

   - ‘close_option’

   - ‘flag_option’

   - ‘flag_value’

   - ‘compiler_flag’

   - ‘flag’

   - ‘prolog_flag’

   - ‘io_mode’

   - ‘non_empty_list’

   - ‘not_less_than_zero’

   - ‘operator_priority’

   - ‘operator_specifier’

   - ‘read_option’

   - ‘source_sink’

   - ‘stream’

   - ‘stream_option’

   - ‘stream_or_alias’

   - ‘stream_position’

   - ‘stream_property’

   - ‘write_option’

   - ‘character_code_list’

   - ‘text_encoding’

   - ‘directive’

   - ‘object_directive’

   - ‘protocol_directive’

   - ‘category_directive’

   - ‘object_relation’

   - ‘protocol_relation’

   - ‘category_relation’

   - ‘object_property’

   - ‘protocol_property’

   - ‘category_property’

   - ‘predicate_property’

   - ‘meta_argument_specifier’

   - ‘meta_directive_template’

   - ‘closure’

   - ‘allocation’

   - ‘redefinition’

   - ‘message_sending_goal’

   - ‘class’

   - ‘prototype’

   - ‘scope’

   - ‘boolean’

The value of ‘Culprit’ is the argument or one of its sub-terms that
caused the error.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<91>,  Next: Errors<92>,  Prev: Description<128>,  Up: domain_error/2

2.5.6.28 Modes and number of proofs
...................................

     domain_error(+atom, @nonvar) - error


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<92>,  Next: Examples<129>,  Prev: Modes and number of proofs<91>,  Up: domain_error/2

2.5.6.29 Errors
...............

     When called:
          ‘domain_error(Domain, Culprit)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<129>,  Prev: Errors<92>,  Up: domain_error/2

2.5.6.30 Examples
.................

     ...,
     atom(Color),
     \+ color(Color),
     domain_error(color, Color).

See also
........

*note catch/3: 1a1, *note throw/1: 1a2, *note context/1: 19e, *note
instantiation_error/0: 1a3, *note uninstantiation_error/1: 1a4, *note
type_error/2: 1a5, *note consistency_error/3: 719, *note
existence_error/2: 1a7, *note permission_error/3: 1a8, *note
representation_error/1: 1a9, *note evaluation_error/1: 1aa, *note
resource_error/1: 1ab, *note syntax_error/1: 1ac, *note system_error/0:
1ad.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: consistency_error/3,  Next: existence_error/2,  Prev: domain_error/2,  Up: Error handling<2>

2.5.6.31 ‘consistency_error/3’
..............................

* Menu:

* Description: Description<129>.
* Modes and number of proofs: Modes and number of proofs<92>.
* Errors: Errors<93>.
* Examples: Examples<130>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<129>,  Next: Modes and number of proofs<92>,  Up: consistency_error/3

2.5.6.32 Description
....................

     consistency_error(Consistency, Argument1, Argument2)

Throws a consistency error.  Used when two directives or predicate
arguments are individually correct but together are not consistent.  For
example, a predicate and its alias having different arity in a ‘uses/2’
directive.  This built-in method is declared private and thus cannot be
used as a message to an object.  Calling this predicate is equivalent to
the following sequence of goals:

     ...,
     context(Context),
     throw(error(consistency_error(Consistency,Argument1,Argument2), Context)).

This allows the user to generate errors in the same format used by the
runtime.

Possible values representing ‘Consistency’ checks include:

   - ‘same_arity’

   - ‘same_number_of_parameters’

   - ‘same_number_of_arguments’

   - ‘same_closure_specification’


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<92>,  Next: Errors<93>,  Prev: Description<129>,  Up: consistency_error/3

2.5.6.33 Modes and number of proofs
...................................

     consistency_error(+atom, @nonvar, @nonvar) - error


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<93>,  Next: Examples<130>,  Prev: Modes and number of proofs<92>,  Up: consistency_error/3

2.5.6.34 Errors
...............

     When called:
          ‘consistency_error(Consistency, Argument1, Argument2)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<130>,  Prev: Errors<93>,  Up: consistency_error/3

2.5.6.35 Examples
.................

     % code that will trigger consistency errors when compiled:

     % predicates (and non-terminals) aliases must have the same
     % arity as the original predicates (and non-terminals)
     :- uses(list, [
         member/2 as in/1
     ]).

     % meta-predicate templates should be consistent with how closures
     % are used regarding the number of additional arguments
     :- public(p/2).
     :- meta_predicate(p(1, *)).

     p(G, A) :-
         call(G, A, 2).

See also
........

*note catch/3: 1a1, *note throw/1: 1a2, *note context/1: 19e, *note
instantiation_error/0: 1a3, *note uninstantiation_error/1: 1a4, *note
type_error/2: 1a5, *note domain_error/2: 1a6, *note existence_error/2:
1a7, *note permission_error/3: 1a8, *note representation_error/1: 1a9,
*note evaluation_error/1: 1aa, *note resource_error/1: 1ab, *note
syntax_error/1: 1ac, *note system_error/0: 1ad.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: existence_error/2,  Next: permission_error/3,  Prev: consistency_error/3,  Up: Error handling<2>

2.5.6.36 ‘existence_error/2’
............................

* Menu:

* Description: Description<130>.
* Modes and number of proofs: Modes and number of proofs<93>.
* Errors: Errors<94>.
* Examples: Examples<131>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<130>,  Next: Modes and number of proofs<93>,  Up: existence_error/2

2.5.6.37 Description
....................

     existence_error(Thing, Culprit)

Throws an existence error.  Used when the subject of an operation does
not exist.  This built-in method is declared private and thus cannot be
used as a message to an object.  Calling this predicate is equivalent to
the following sequence of goals:

     ...,
     context(Context),
     throw(error(existence_error(Thing,Culprit), Context)).

This allows the user to generate errors in the same format used by the
runtime.

Possible values for ‘Thing’ include:

   - ‘predicate’

   - ‘non_terminal’

   - ‘predicate_declaration’

   - ‘procedure’

   - ‘source_sink’

   - ‘stream’

   - ‘object’

   - ‘protocol’

   - ‘category’

   - ‘module’

   - ‘ancestor’

   - ‘library’

   - ‘file’

   - ‘directive’

   - ‘engine’

   - ‘thread’

   - ‘goal_thread’

The value of ‘Culprit’ is the argument or one of its sub-terms that
caused the error.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<93>,  Next: Errors<94>,  Prev: Description<130>,  Up: existence_error/2

2.5.6.38 Modes and number of proofs
...................................

     existence_error(@nonvar, @nonvar) - error


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<94>,  Next: Examples<131>,  Prev: Modes and number of proofs<93>,  Up: existence_error/2

2.5.6.39 Errors
...............

     When called:
          ‘existence_error(Thing, Culprit)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<131>,  Prev: Errors<94>,  Up: existence_error/2

2.5.6.40 Examples
.................

     ...,
     \+ current_object(payroll),
     existence_error(object, payroll).

See also
........

*note catch/3: 1a1, *note throw/1: 1a2, *note context/1: 19e, *note
instantiation_error/0: 1a3, *note uninstantiation_error/1: 1a4, *note
type_error/2: 1a5, *note domain_error/2: 1a6, *note consistency_error/3:
719, *note evaluation_error/1: 1aa, *note permission_error/3: 1a8, *note
representation_error/1: 1a9, *note resource_error/1: 1ab, *note
syntax_error/1: 1ac, *note system_error/0: 1ad.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: permission_error/3,  Next: representation_error/1,  Prev: existence_error/2,  Up: Error handling<2>

2.5.6.41 ‘permission_error/3’
.............................

* Menu:

* Description: Description<131>.
* Modes and number of proofs: Modes and number of proofs<94>.
* Errors: Errors<95>.
* Examples: Examples<132>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<131>,  Next: Modes and number of proofs<94>,  Up: permission_error/3

2.5.6.42 Description
....................

     permission_error(Operation, PermissionType, Culprit)

Throws a permission error.  Used when an operation is not allowed.  For
example, sending a message for a predicate that is not within the scope
of the sender.  This built-in method is declared private and thus cannot
be used as a message to an object.  Calling this predicate is equivalent
to the following sequence of goals:

     ...,
     context(Context),
     throw(error(permission_error(Operation,PermissionType,Culprit), Context)).

This allows the user to generate errors in the same format used by the
runtime.

Possible values for ‘Operation’ include:

   - ‘access’

   - ‘create’

   - ‘declare’

   - ‘define’

   - ‘modify’

   - ‘open’

   - ‘input’

   - ‘output’

   - ‘reposition’

   - ‘repeat’

Possible values for ‘PermissionType’ include:

   - ‘predicate_declaration’

   - ‘protected_predicate’

   - ‘private_predicate’

   - ‘static_predicate’

   - ‘dynamic_predicate’

   - ‘predicate’

   - ‘non_terminal’

   - ‘database’

   - ‘object’

   - ‘static_object’

   - ‘static_protocol’

   - ‘static_category’

   - ‘entity_relation’

   - ‘operator’

   - ‘flag’

   - ‘engine’

   - ‘binary_stream’

   - ‘text_stream’

   - ‘source_sink’

   - ‘stream’

   - ‘past_end_of_stream’

The value of ‘Culprit’ is the argument or one of its sub-terms that
caused the error.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<94>,  Next: Errors<95>,  Prev: Description<131>,  Up: permission_error/3

2.5.6.43 Modes and number of proofs
...................................

     permission_error(@nonvar, @nonvar, @nonvar) - error


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<95>,  Next: Examples<132>,  Prev: Modes and number of proofs<94>,  Up: permission_error/3

2.5.6.44 Errors
...............

     When called:
          ‘permission_error(Operation, PermissionType, Culprit)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<132>,  Prev: Errors<95>,  Up: permission_error/3

2.5.6.45 Examples
.................

     ...,
     \+ writable(File),
     permission_error(modify, file, File).

See also
........

*note catch/3: 1a1, *note throw/1: 1a2, *note context/1: 19e, *note
instantiation_error/0: 1a3, *note uninstantiation_error/1: 1a4, *note
type_error/2: 1a5, *note domain_error/2: 1a6, *note consistency_error/3:
719, *note existence_error/2: 1a7, *note representation_error/1: 1a9,
*note evaluation_error/1: 1aa, *note resource_error/1: 1ab, *note
syntax_error/1: 1ac, *note system_error/0: 1ad.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: representation_error/1,  Next: evaluation_error/1,  Prev: permission_error/3,  Up: Error handling<2>

2.5.6.46 ‘representation_error/1’
.................................

* Menu:

* Description: Description<132>.
* Modes and number of proofs: Modes and number of proofs<95>.
* Errors: Errors<96>.
* Examples: Examples<133>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<132>,  Next: Modes and number of proofs<95>,  Up: representation_error/1

2.5.6.47 Description
....................

     representation_error(Flag)

Throws a representation error.  Used when some representation limit is
exceeded.  For example, trying to construct a compound term that exceeds
the maximum arity supported by the backend Prolog system.  This built-in
method is declared private and thus cannot be used as a message to an
object.  Calling this predicate is equivalent to the following sequence
of goals:

     ...,
     context(Context),
     throw(error(representation_error(Flag), Context)).

This allows the user to generate errors in the same format used by the
runtime.

Possible values for ‘Flag’ include:

   - ‘character’

   - ‘character_code’

   - ‘in_character_code’

   - ‘max_arity’

   - ‘max_integer’

   - ‘min_integer’

   - ‘acyclic_term’

   - ‘lambda_parameters’

   - ‘entity_prefix’


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<95>,  Next: Errors<96>,  Prev: Description<132>,  Up: representation_error/1

2.5.6.48 Modes and number of proofs
...................................

     representation_error(+atom) - error


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<96>,  Next: Examples<133>,  Prev: Modes and number of proofs<95>,  Up: representation_error/1

2.5.6.49 Errors
...............

     When called:
          ‘representation_error(Flag)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<133>,  Prev: Errors<96>,  Up: representation_error/1

2.5.6.50 Examples
.................

     ...,
     Code > 127,
     representation_error(character_code).

See also
........

*note catch/3: 1a1, *note throw/1: 1a2, *note context/1: 19e, *note
instantiation_error/0: 1a3, *note uninstantiation_error/1: 1a4, *note
type_error/2: 1a5, *note domain_error/2: 1a6, *note consistency_error/3:
719, *note existence_error/2: 1a7, *note permission_error/3: 1a8, *note
evaluation_error/1: 1aa, *note resource_error/1: 1ab, *note
syntax_error/1: 1ac, *note system_error/0: 1ad.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: evaluation_error/1,  Next: resource_error/1,  Prev: representation_error/1,  Up: Error handling<2>

2.5.6.51 ‘evaluation_error/1’
.............................

* Menu:

* Description: Description<133>.
* Modes and number of proofs: Modes and number of proofs<96>.
* Errors: Errors<97>.
* Examples: Examples<134>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<133>,  Next: Modes and number of proofs<96>,  Up: evaluation_error/1

2.5.6.52 Description
....................

     evaluation_error(Error)

Throws an evaluation error.  Used when evaluating an arithmetic
expression generates an exception.  This built-in method is declared
private and thus cannot be used as a message to an object.  Calling this
predicate is equivalent to the following sequence of goals:

     ...,
     context(Context),
     throw(error(evaluation_error(Error), Context)).

This allows the user to generate errors in the same format used by the
runtime.

Possible values for ‘Error’ include:

   - ‘float_overflow’

   - ‘int_overflow’

   - ‘undefined’

   - ‘underflow’

   - ‘zero_divisor’


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<96>,  Next: Errors<97>,  Prev: Description<133>,  Up: evaluation_error/1

2.5.6.53 Modes and number of proofs
...................................

     evaluation_error(@nonvar) - error


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<97>,  Next: Examples<134>,  Prev: Modes and number of proofs<96>,  Up: evaluation_error/1

2.5.6.54 Errors
...............

     When called:
          ‘evaluation_error(Exception)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<134>,  Prev: Errors<97>,  Up: evaluation_error/1

2.5.6.55 Examples
.................

     ...,
     Divisor =:= 0,
     evaluation_error(zero_divisor).

See also
........

*note catch/3: 1a1, *note throw/1: 1a2, *note context/1: 19e, *note
instantiation_error/0: 1a3, *note uninstantiation_error/1: 1a4, *note
type_error/2: 1a5, *note domain_error/2: 1a6, *note consistency_error/3:
719, *note existence_error/2: 1a7, *note permission_error/3: 1a8, *note
representation_error/1: 1a9, *note resource_error/1: 1ab, *note
syntax_error/1: 1ac, *note system_error/0: 1ad.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: resource_error/1,  Next: syntax_error/1,  Prev: evaluation_error/1,  Up: Error handling<2>

2.5.6.56 ‘resource_error/1’
...........................

* Menu:

* Description: Description<134>.
* Modes and number of proofs: Modes and number of proofs<97>.
* Errors: Errors<98>.
* Examples: Examples<135>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<134>,  Next: Modes and number of proofs<97>,  Up: resource_error/1

2.5.6.57 Description
....................

     resource_error(Resource)

Throws a resource error.  Used when a required resource (e.g., memory or
disk space) to complete execution is not available.  This built-in
method is declared private and thus cannot be used as a message to an
object.  Calling this predicate is equivalent to the following sequence
of goals:

     ...,
     context(Context),
     throw(error(resource_error(Resource), Context)).

This allows the user to generate errors in the same format used by the
runtime.

Possible values for ‘Resource’ include:

   - ‘engines’

   - ‘threads’

   - ‘coinduction’

   - ‘soft_cut_support’

   - ‘text_encoding_support’


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<97>,  Next: Errors<98>,  Prev: Description<134>,  Up: resource_error/1

2.5.6.58 Modes and number of proofs
...................................

     resource_error(@nonvar) - error


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<98>,  Next: Examples<135>,  Prev: Modes and number of proofs<97>,  Up: resource_error/1

2.5.6.59 Errors
...............

     When called:
          ‘resource_error(Resource)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<135>,  Prev: Errors<98>,  Up: resource_error/1

2.5.6.60 Examples
.................

     ...,
     empty(Tank),
     resource_error(gas).

See also
........

*note catch/3: 1a1, *note throw/1: 1a2, *note context/1: 19e, *note
instantiation_error/0: 1a3, *note uninstantiation_error/1: 1a4, *note
type_error/2: 1a5, *note domain_error/2: 1a6, *note consistency_error/3:
719, *note existence_error/2: 1a7, *note permission_error/3: 1a8, *note
representation_error/1: 1a9, *note syntax_error/1: 1ac, *note
system_error/0: 1ad.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: syntax_error/1,  Next: system_error/0,  Prev: resource_error/1,  Up: Error handling<2>

2.5.6.61 ‘syntax_error/1’
.........................

* Menu:

* Description: Description<135>.
* Modes and number of proofs: Modes and number of proofs<98>.
* Errors: Errors<99>.
* Examples: Examples<136>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<135>,  Next: Modes and number of proofs<98>,  Up: syntax_error/1

2.5.6.62 Description
....................

     syntax_error(Description)

Throws a syntax error.  Used when the sequence of characters being read
are not syntactically valid.  This built-in method is declared private
and thus cannot be used as a message to an object.  Calling this
predicate is equivalent to the following sequence of goals:

     ...,
     context(Context),
     throw(error(syntax_error(Description), Context)).

This allows the user to generate errors in the same format used by the
runtime.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<98>,  Next: Errors<99>,  Prev: Description<135>,  Up: syntax_error/1

2.5.6.63 Modes and number of proofs
...................................

     syntax_error(@nonvar) - error


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<99>,  Next: Examples<136>,  Prev: Modes and number of proofs<98>,  Up: syntax_error/1

2.5.6.64 Errors
...............

     When called:
          ‘syntax_error(Description)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<136>,  Prev: Errors<99>,  Up: syntax_error/1

2.5.6.65 Examples
.................

(none)

See also
........

*note catch/3: 1a1, *note throw/1: 1a2, *note context/1: 19e, *note
instantiation_error/0: 1a3, *note uninstantiation_error/1: 1a4, *note
type_error/2: 1a5, *note domain_error/2: 1a6, *note consistency_error/3:
719, *note existence_error/2: 1a7, *note permission_error/3: 1a8, *note
representation_error/1: 1a9, *note system_error/0: 1ad. *note
resource_error/1: 1ab.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: system_error/0,  Prev: syntax_error/1,  Up: Error handling<2>

2.5.6.66 ‘system_error/0’
.........................

* Menu:

* Description: Description<136>.
* Modes and number of proofs: Modes and number of proofs<99>.
* Errors: Errors<100>.
* Examples: Examples<137>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<136>,  Next: Modes and number of proofs<99>,  Up: system_error/0

2.5.6.67 Description
....................

     system_error

Throws a system error.  Used when runtime execution can no longer
proceed.  For example, an exception is thrown without an active catcher.
This built-in method is declared private and thus cannot be used as a
message to an object.  Calling this predicate is equivalent to the
following sequence of goals:

     ...,
     context(Context),
     throw(error(system_error, Context)).

This allows the user to generate errors in the same format used by the
runtime.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<99>,  Next: Errors<100>,  Prev: Description<136>,  Up: system_error/0

2.5.6.68 Modes and number of proofs
...................................

     system_error - error


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<100>,  Next: Examples<137>,  Prev: Modes and number of proofs<99>,  Up: system_error/0

2.5.6.69 Errors
...............

     When called:
          ‘system_error’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<137>,  Prev: Errors<100>,  Up: system_error/0

2.5.6.70 Examples
.................

(none)

See also
........

*note catch/3: 1a1, *note throw/1: 1a2, *note context/1: 19e, *note
instantiation_error/0: 1a3, *note uninstantiation_error/1: 1a4, *note
type_error/2: 1a5, *note domain_error/2: 1a6, *note consistency_error/3:
719, *note existence_error/2: 1a7, *note permission_error/3: 1a8, *note
representation_error/1: 1a9. *note evaluation_error/1: 1aa, *note
resource_error/1: 1ab, *note syntax_error/1: 1ac,


File: TheLogtalkHandbook-3.101.0.info,  Node: All solutions,  Next: Event handling<3>,  Prev: Error handling<2>,  Up: Built-in methods<2>

2.5.7 All solutions
-------------------

'built-in method'

* Menu:

* bagof/3::
* findall/3::
* findall/4::
* forall/2::
* setof/3::


File: TheLogtalkHandbook-3.101.0.info,  Node: bagof/3,  Next: findall/3,  Up: All solutions

2.5.7.1 ‘bagof/3’
.................

* Menu:

* Description: Description<137>.
* Meta-predicate template: Meta-predicate template<10>.
* Modes and number of proofs: Modes and number of proofs<100>.
* Errors: Errors<101>.
* Examples: Examples<138>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<137>,  Next: Meta-predicate template<10>,  Up: bagof/3

2.5.7.2 Description
...................

     bagof(Template, Goal, List)

Collects a bag of solutions for the goal for each set of instantiations
of the free variables in the goal.  The order of the elements in the bag
follows the order of the goal solutions.  The free variables in the goal
are the variables that occur in the goal but not in the template.  Free
variables can be ignored, however, by using the ‘^/2’ existential
qualifier.  For example, if ‘T’ is term containing all the free
variables that we want to ignore, we can write ‘T^Goal’.  Note that the
term ‘T’ can be written as ‘V1^V2^...’.

When there are free variables, this method is re-executable on
backtracking.  This method fails when there are no solutions, never
returning an empty list.

This built-in meta-predicate is declared as a private method and thus
cannot be used as a message to an object.


File: TheLogtalkHandbook-3.101.0.info,  Node: Meta-predicate template<10>,  Next: Modes and number of proofs<100>,  Prev: Description<137>,  Up: bagof/3

2.5.7.3 Meta-predicate template
...............................

     bagof(*, ^, *)


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<100>,  Next: Errors<101>,  Prev: Meta-predicate template<10>,  Up: bagof/3

2.5.7.4 Modes and number of proofs
..................................

     bagof(@term, +callable, -list) - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<101>,  Next: Examples<138>,  Prev: Modes and number of proofs<100>,  Up: bagof/3

2.5.7.5 Errors
..............

     ‘Goal’ is a variable:
          ‘instantiation_error’
     ‘Goal’ is neither a variable nor a callable term:
          ‘type_error(callable, Goal)’
     ‘Goal’ is a call to a non-existing predicate:
          ‘existence_error(procedure, Predicate)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<138>,  Prev: Errors<101>,  Up: bagof/3

2.5.7.6 Examples
................

     To find a bag of solutions in the context of the object or category containing the call:
          ‘bagof(Template, Goal, List)’
     To find a bag of solutions of sending a message to *note self: 69.:
          ‘bagof(Template, ::Message, List)’
     To find a bag of solutions of sending a message to an explicit object:
          ‘bagof(Template, Object::Message, List)’

See also
........

*note findall/3: 1c0, *note findall/4: 1c1, *note forall/2: 1c3, *note
setof/3: 1c2.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: findall/3,  Next: findall/4,  Prev: bagof/3,  Up: All solutions

2.5.7.7 ‘findall/3’
...................

* Menu:

* Description: Description<138>.
* Meta-predicate template: Meta-predicate template<11>.
* Modes and number of proofs: Modes and number of proofs<101>.
* Errors: Errors<102>.
* Examples: Examples<139>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<138>,  Next: Meta-predicate template<11>,  Up: findall/3

2.5.7.8 Description
...................

     findall(Template, Goal, List)

Collects a list of solutions for the goal.  The order of the elements in
the list follows the order of the goal solutions.  It succeeds returning
an empty list when the goal has no solutions.

This built-in meta-predicate is declared as a private method and thus
cannot be used as a message to an object.


File: TheLogtalkHandbook-3.101.0.info,  Node: Meta-predicate template<11>,  Next: Modes and number of proofs<101>,  Prev: Description<138>,  Up: findall/3

2.5.7.9 Meta-predicate template
...............................

     findall(*, 0, *)


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<101>,  Next: Errors<102>,  Prev: Meta-predicate template<11>,  Up: findall/3

2.5.7.10 Modes and number of proofs
...................................

     findall(?term, +callable, ?list) - zero_or_one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<102>,  Next: Examples<139>,  Prev: Modes and number of proofs<101>,  Up: findall/3

2.5.7.11 Errors
...............

     ‘Goal’ is a variable:
          ‘instantiation_error’
     ‘Goal’ is neither a variable nor a callable term:
          ‘type_error(callable, Goal)’
     ‘Goal’ is a call to a non-existing predicate:
          ‘existence_error(procedure, Predicate)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<139>,  Prev: Errors<102>,  Up: findall/3

2.5.7.12 Examples
.................

     To find all solutions in the context of the object or category containing the call:
          ‘findall(Template, Goal, List)’
     To find all solutions of sending a message to *note self: 69.:
          ‘findall(Template, ::Message, List)’
     To find all solutions of sending a message to an explicit object:
          ‘findall(Template, Object::Message, List)’

See also
........

*note bagof/3: 1bf, *note findall/4: 1c1, *note forall/2: 1c3, *note
setof/3: 1c2.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: findall/4,  Next: forall/2,  Prev: findall/3,  Up: All solutions

2.5.7.13 ‘findall/4’
....................

* Menu:

* Description: Description<139>.
* Meta-predicate template: Meta-predicate template<12>.
* Modes and number of proofs: Modes and number of proofs<102>.
* Errors: Errors<103>.
* Examples: Examples<140>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<139>,  Next: Meta-predicate template<12>,  Up: findall/4

2.5.7.14 Description
....................

     findall(Template, Goal, List, Tail)

Variant of the *note findall/3: 1c0. method that allows passing the tail
of the results list.  It succeeds returning the tail argument when the
goal has no solutions.

This built-in meta-predicate is declared as a private method and thus
cannot be used as a message to an object.


File: TheLogtalkHandbook-3.101.0.info,  Node: Meta-predicate template<12>,  Next: Modes and number of proofs<102>,  Prev: Description<139>,  Up: findall/4

2.5.7.15 Meta-predicate template
................................

     findall(*, 0, *, *)


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<102>,  Next: Errors<103>,  Prev: Meta-predicate template<12>,  Up: findall/4

2.5.7.16 Modes and number of proofs
...................................

     findall(?term, +callable, ?list, ?term) - zero_or_one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<103>,  Next: Examples<140>,  Prev: Modes and number of proofs<102>,  Up: findall/4

2.5.7.17 Errors
...............

     ‘Goal’ is a variable:
          ‘instantiation_error’
     ‘Goal’ is neither a variable nor a callable term:
          ‘type_error(callable, Goal)’
     ‘Goal’ is a call to a non-existing predicate:
          ‘existence_error(procedure, Predicate)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<140>,  Prev: Errors<103>,  Up: findall/4

2.5.7.18 Examples
.................

     To find all solutions in the context of the object or category containing the call:
          ‘findall(Template, Goal, List, Tail)’
     To find all solutions of sending a message to *note self: 69.:
          ‘findall(Template, ::Message, List, Tail)’
     To find all solutions of sending a message to an explicit object:
          ‘findall(Template, Object::Message, List, Tail)’

See also
........

*note bagof/3: 1bf, *note findall/3: 1c0, *note forall/2: 1c3, *note
setof/3: 1c2.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: forall/2,  Next: setof/3,  Prev: findall/4,  Up: All solutions

2.5.7.19 ‘forall/2’
...................

* Menu:

* Description: Description<140>.
* Meta-predicate template: Meta-predicate template<13>.
* Modes and number of proofs: Modes and number of proofs<103>.
* Errors: Errors<104>.
* Examples: Examples<141>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<140>,  Next: Meta-predicate template<13>,  Up: forall/2

2.5.7.20 Description
....................

     forall(Generator, Test)

For all solutions of ‘Generator’, ‘Test’ is true.  This meta-predicate
implements a 'generate-and-test' loop using a definition equivalent to
‘\+ (Generator, \+ Test)’.  As a consequence, no variables in the
arguments are bound by a call to this predicate.  This predicate often
provides a better alternative to a 'failure-driven loop' as an
unexpected ‘Test’ failure will not be ignored as it will make the
‘forall/2’ call fail.

This built-in meta-predicate is declared as a private method and thus
cannot be used as a message to an object.


File: TheLogtalkHandbook-3.101.0.info,  Node: Meta-predicate template<13>,  Next: Modes and number of proofs<103>,  Prev: Description<140>,  Up: forall/2

2.5.7.21 Meta-predicate template
................................

     forall(0, 0)


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<103>,  Next: Errors<104>,  Prev: Meta-predicate template<13>,  Up: forall/2

2.5.7.22 Modes and number of proofs
...................................

     forall(@callable, @callable) - zero_or_one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<104>,  Next: Examples<141>,  Prev: Modes and number of proofs<103>,  Up: forall/2

2.5.7.23 Errors
...............

     Either ‘Generator’ or ‘Test’ is a variable:
          ‘instantiation_error’
     ‘Generator’ is neither a variable nor a callable term:
          ‘type_error(callable, Generator)’
     ‘Test’ is neither a variable nor a callable term:
          ‘type_error(callable, Test)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<141>,  Prev: Errors<104>,  Up: forall/2

2.5.7.24 Examples
.................

     To call both goals in the context of the object or category containing the call:
          ‘forall(Generator, Test)’
     To send both goals as messages to *note self: 69.:
          ‘forall(::Generator, ::Test)’
     To send both goals as messages to explicit objects:
          ‘forall(Object1::Generator, Object2::Test)’

See also
........

*note bagof/3: 1bf, *note findall/3: 1c0, *note findall/4: 1c1, *note
setof/3: 1c2.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: setof/3,  Prev: forall/2,  Up: All solutions

2.5.7.25 ‘setof/3’
..................

* Menu:

* Description: Description<141>.
* Meta-predicate template: Meta-predicate template<14>.
* Modes and number of proofs: Modes and number of proofs<104>.
* Errors: Errors<105>.
* Examples: Examples<142>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<141>,  Next: Meta-predicate template<14>,  Up: setof/3

2.5.7.26 Description
....................

     setof(Template, Goal, List)

Collects a set of solutions for the goal for each set of instantiations
of the free variables in the goal.  The solutions are sorted using
standard term order.  The free variables in the goal are the variables
that occur in the goal but not in the template.  Free variables can be
ignored, however, by using the ‘^/2’ existential qualifier.  For
example, if ‘T’ is term containing all the free variables that we want
to ignore, we can write ‘T^Goal’.  Note that the term ‘T’ can be written
as ‘V1^V2^...’.

When there are free variables, this method is re-executable on
backtracking.  This method fails when there are no solutions, never
returning an empty list.

This built-in meta-predicate is declared as a private method and thus
cannot be used as a message to an object.


File: TheLogtalkHandbook-3.101.0.info,  Node: Meta-predicate template<14>,  Next: Modes and number of proofs<104>,  Prev: Description<141>,  Up: setof/3

2.5.7.27 Meta-predicate template
................................

     setof(*, ^, *)


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<104>,  Next: Errors<105>,  Prev: Meta-predicate template<14>,  Up: setof/3

2.5.7.28 Modes and number of proofs
...................................

     setof(@term, +callable, -list) - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<105>,  Next: Examples<142>,  Prev: Modes and number of proofs<104>,  Up: setof/3

2.5.7.29 Errors
...............

     ‘Goal’ is a variable:
          ‘instantiation_error’
     ‘Goal’ is neither a variable nor a callable term:
          ‘type_error(callable, Goal)’
     ‘Goal’ is a call to a non-existing predicate:
          ‘existence_error(procedure, Predicate)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<142>,  Prev: Errors<105>,  Up: setof/3

2.5.7.30 Examples
.................

     To find a set of solutions in the context of the object or category containing the call:
          ‘setof(Template, Goal, List)’
     To find a set of solutions of sending a message to *note self: 69.:
          ‘setof(Template, ::Message, List)’
     To find a set of solutions of sending a message to an explicit object:
          ‘setof(Template, Object::Message, List)’

See also
........

*note bagof/3: 1bf, *note findall/3: 1c0, *note findall/4: 1c1, *note
forall/2: 1c3.


File: TheLogtalkHandbook-3.101.0.info,  Node: Event handling<3>,  Next: Message forwarding,  Prev: All solutions,  Up: Built-in methods<2>

2.5.8 Event handling
--------------------

'built-in method'

* Menu:

* before/3::
* after/3::


File: TheLogtalkHandbook-3.101.0.info,  Node: before/3,  Next: after/3,  Up: Event handling<3>

2.5.8.1 ‘before/3’
..................

* Menu:

* Description: Description<142>.
* Modes and number of proofs: Modes and number of proofs<105>.
* Errors: Errors<106>.
* Examples: Examples<143>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<142>,  Next: Modes and number of proofs<105>,  Up: before/3

2.5.8.2 Description
...................

     before(Object, Message, Sender)

User-defined method for handling *note before events: 205.  This method
is declared in the monitoring(1) built-in protocol as a public predicate
and is automatically called by the runtime for messages sent using the
*note (;;)/2: 7e. control construct from within objects compiled with
the *note events: 89. flag set to ‘allow’.

Note that you can make this predicate scope protected or private by
using, respectively, *note protected or private implementation: 9e. of
the ‘monitoring’ protocol.

   ---------- Footnotes ----------

   (1) ../../../apis/monitoring_0.html#monitoring-0


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<105>,  Next: Errors<106>,  Prev: Description<142>,  Up: before/3

2.5.8.3 Modes and number of proofs
..................................

     before(?object_identifier, ?callable, ?object_identifier) - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<106>,  Next: Examples<143>,  Prev: Modes and number of proofs<105>,  Up: before/3

2.5.8.4 Errors
..............

(none)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<143>,  Prev: Errors<106>,  Up: before/3

2.5.8.5 Examples
................

     :- object(...,
         implements(monitoring),
         ...).

         % write a log message when a message is sent:
         before(Object, Message, Sender) :-
             writeq(Object), write('::'), writeq(Message),
             write(' from '), writeq(Sender), nl.

See also
........

*note after/3: 102, *note abolish_events/5: 21b, *note current_event/5:
21e, *note define_events/5: 218.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: after/3,  Prev: before/3,  Up: Event handling<3>

2.5.8.6 ‘after/3’
.................

* Menu:

* Description: Description<143>.
* Modes and number of proofs: Modes and number of proofs<106>.
* Errors: Errors<107>.
* Examples: Examples<144>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<143>,  Next: Modes and number of proofs<106>,  Up: after/3

2.5.8.7 Description
...................

     after(Object, Message, Sender)

User-defined method for handling *note after events: 205.  This method
is declared in the monitoring(1) built-in protocol as a public predicate
and is automatically called by the runtime for messages sent using the
*note (;;)/2: 7e. control construct from within objects compiled with
the *note events: 89. flag set to ‘allow’.

Note that you can make this predicate scope protected or private by
using, respectively, *note protected or private implementation: 9e. of
the ‘monitoring’ protocol.

   ---------- Footnotes ----------

   (1) ../../../apis/monitoring_0.html#monitoring-0


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<106>,  Next: Errors<107>,  Prev: Description<143>,  Up: after/3

2.5.8.8 Modes and number of proofs
..................................

     after(?object_identifier, ?callable, ?object_identifier) - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<107>,  Next: Examples<144>,  Prev: Modes and number of proofs<106>,  Up: after/3

2.5.8.9 Errors
..............

(none)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<144>,  Prev: Errors<107>,  Up: after/3

2.5.8.10 Examples
.................

     :- object(...,
         implements(monitoring),
         ...).

         % write a log message when a message is successful:
         after(Object, Message, Sender) :-
             writeq(Object), write('::'), writeq(Message),
             write(' from '), writeq(Sender), nl.

See also
........

*note before/3: 101, *note abolish_events/5: 21b, *note current_event/5:
21e, *note define_events/5: 218.


File: TheLogtalkHandbook-3.101.0.info,  Node: Message forwarding,  Next: Definite clause grammar rules<2>,  Prev: Event handling<3>,  Up: Built-in methods<2>

2.5.9 Message forwarding
------------------------

'built-in method'

* Menu:

* forward/1::


File: TheLogtalkHandbook-3.101.0.info,  Node: forward/1,  Up: Message forwarding

2.5.9.1 ‘forward/1’
...................

* Menu:

* Description: Description<144>.
* Modes and number of proofs: Modes and number of proofs<107>.
* Errors: Errors<108>.
* Examples: Examples<145>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<144>,  Next: Modes and number of proofs<107>,  Up: forward/1

2.5.9.2 Description
...................

     forward(Message)

User-defined method for forwarding unknown messages sent to an object
(using the *note (;;)/2: 7e. control construct), automatically called by
the runtime when defined.  This method is declared in the forwarding(1)
built-in protocol as a *note public: 143. predicate.  Note that you can
make its scope protected or private by using, respectively, *note
protected or private implementation: 9e. of the ‘forwarding’ protocol.

   ---------- Footnotes ----------

   (1) ../../../apis/forwarding_0.html#forwarding-0


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<107>,  Next: Errors<108>,  Prev: Description<144>,  Up: forward/1

2.5.9.3 Modes and number of proofs
..................................

     forward(+callable) - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<108>,  Next: Examples<145>,  Prev: Modes and number of proofs<107>,  Up: forward/1

2.5.9.4 Errors
..............

(none)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<145>,  Prev: Errors<108>,  Up: forward/1

2.5.9.5 Examples
................

     :- object(proxy,
         implements(forwarding),
         ...).

         forward(Message) :-
             % delegate unknown messages to the "real" object
             [real::Message].

See also
........

*note []/1: 81.


File: TheLogtalkHandbook-3.101.0.info,  Node: Definite clause grammar rules<2>,  Next: Term and goal expansion<2>,  Prev: Message forwarding,  Up: Built-in methods<2>

2.5.10 Definite clause grammar rules
------------------------------------

'built-in method'

* Menu:

* call//1-N::
* eos//0::
* phrase//1::
* phrase/2::
* phrase/3::


File: TheLogtalkHandbook-3.101.0.info,  Node: call//1-N,  Next: eos//0,  Up: Definite clause grammar rules<2>

2.5.10.1 ‘call//1-N’
....................

* Menu:

* Description: Description<145>.
* Meta-non-terminal template::
* Modes and number of proofs: Modes and number of proofs<108>.
* Errors: Errors<109>.
* Examples: Examples<146>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<145>,  Next: Meta-non-terminal template,  Up: call//1-N

2.5.10.2 Description
....................

     call(Closure)
     call(Closure, Arg1, ...)
     call(Object::Closure, Arg1, ...)
     call(::Closure, Arg1, ...)
     call(^^Closure, Arg1, ...)
     ...

This non-terminal takes a *note closure: 14f. and is processed by
appending the two implicit grammar rule arguments to the arguments of
the closure.  This built-in non-terminal is interpreted as a private
non-terminal and thus cannot be used as a message to an object.

Using this non-terminal is recommended when calling a predicate whose
last two arguments are the two implicit grammar rule arguments to avoid
hard-coding assumptions about how grammar rules are compiled into
clauses.  Note that the compiler ensures zero overhead when using this
non-terminal with a bound argument at compile-time.  To call a predicate
with a different argument order, use a *note lambda expression: 182. or
define a *note predicate alias: ca.  For example:

     square -->
         call([Number, Double]>>(Double is Number*Number)).

When using a *note backend Prolog compiler: 34. supporting a module
system, calls in the format ‘call(Module:Closure)’ may also be used.


File: TheLogtalkHandbook-3.101.0.info,  Node: Meta-non-terminal template,  Next: Modes and number of proofs<108>,  Prev: Description<145>,  Up: call//1-N

2.5.10.3 Meta-non-terminal template
...................................

     call(0)
     call(1, *)
     call(2, *, *)
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<108>,  Next: Errors<109>,  Prev: Meta-non-terminal template,  Up: call//1-N

2.5.10.4 Modes and number of proofs
...................................

     call(+callable) - zero_or_more
     call(+callable, ?term) - zero_or_more
     call(+callable, ?term, ?term) - zero_or_more
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<109>,  Next: Examples<146>,  Prev: Modes and number of proofs<108>,  Up: call//1-N

2.5.10.5 Errors
...............

     ‘Closure’ is a variable:
          ‘instantiation_error’
     ‘Closure’ is neither a variable nor a callable term:
          ‘type_error(callable, Closure)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<146>,  Prev: Errors<109>,  Up: call//1-N

2.5.10.6 Examples
.................

     Calls a goal, constructed by appending the two implicit grammar rule arguments to the closure, in in the context of the object or category containing the call:
          ‘call(Closure)’
     To make a 'super' call, constructed by appending the two implicit grammar rule arguments to the closure:
          ‘call(^^Closure)’
     To send a goal, constructed by appending the two implicit grammar rule arguments to the closure, as a message to *note self: 69.:
          ‘call(::Closure)’
     To send a goal, constructed by appending the two implicit grammar rule arguments to the closure, as a message to an explicit object:
          ‘call(Object::Closure)’

See also
........

*note eos//0: 1ca, *note phrase//1: 1c8, *note phrase/2: 18e, *note
phrase/3: 18f.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: eos//0,  Next: phrase//1,  Prev: call//1-N,  Up: Definite clause grammar rules<2>

2.5.10.7 ‘eos//0’
.................

* Menu:

* Description: Description<146>.
* Modes and number of proofs: Modes and number of proofs<109>.
* Errors: Errors<110>.
* Examples: Examples<147>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<146>,  Next: Modes and number of proofs<109>,  Up: eos//0

2.5.10.8 Description
....................

     eos

This non-terminal matches the end-of-input.  It is implemented by
checking that the implicit difference list unifies with ‘[]-[]’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<109>,  Next: Errors<110>,  Prev: Description<146>,  Up: eos//0

2.5.10.9 Modes and number of proofs
...................................

     eos - zero_or_one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<110>,  Next: Examples<147>,  Prev: Modes and number of proofs<109>,  Up: eos//0

2.5.10.10 Errors
................

(none)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<147>,  Prev: Errors<110>,  Up: eos//0

2.5.10.11 Examples
..................

     abc --> a, b, c, eos.

See also
........

*note call//1-N: 1c9, *note phrase//1: 1c8, *note phrase/2: 18e, *note
phrase/3: 18f.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: phrase//1,  Next: phrase/2,  Prev: eos//0,  Up: Definite clause grammar rules<2>

2.5.10.12 ‘phrase//1’
.....................

* Menu:

* Description: Description<147>.
* Meta-non-terminal template: Meta-non-terminal template<2>.
* Modes and number of proofs: Modes and number of proofs<110>.
* Errors: Errors<111>.
* Examples: Examples<148>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<147>,  Next: Meta-non-terminal template<2>,  Up: phrase//1

2.5.10.13 Description
.....................

     phrase(GrammarRuleBody)

This non-terminal takes a grammar rule body and parses it using the two
implicit grammar rule arguments.  A common use is to wrap what otherwise
would be a *note naked meta-variable: 7b9. in a grammar rule body when
defining a meta non-terminal.


File: TheLogtalkHandbook-3.101.0.info,  Node: Meta-non-terminal template<2>,  Next: Modes and number of proofs<110>,  Prev: Description<147>,  Up: phrase//1

2.5.10.14 Meta-non-terminal template
....................................

     phrase(0)


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<110>,  Next: Errors<111>,  Prev: Meta-non-terminal template<2>,  Up: phrase//1

2.5.10.15 Modes and number of proofs
....................................

     phrase(+callable) - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<111>,  Next: Examples<148>,  Prev: Modes and number of proofs<110>,  Up: phrase//1

2.5.10.16 Errors
................

     ‘GrammarRuleBody’ is a variable:
          ‘instantiation_error’
     ‘GrammarRuleBody’ is neither a variable nor a callable term:
          ‘type_error(callable, GrammarRuleBody)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<148>,  Prev: Errors<111>,  Up: phrase//1

2.5.10.17 Examples
..................

     (none)

See also
........

*note call//1-N: 1c9, *note phrase/2: 18e, *note phrase/3: 18f.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: phrase/2,  Next: phrase/3,  Prev: phrase//1,  Up: Definite clause grammar rules<2>

2.5.10.18 ‘phrase/2’
....................

* Menu:

* Description: Description<148>.
* Meta-predicate template: Meta-predicate template<15>.
* Modes and number of proofs: Modes and number of proofs<111>.
* Errors: Errors<112>.
* Examples: Examples<149>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<148>,  Next: Meta-predicate template<15>,  Up: phrase/2

2.5.10.19 Description
.....................

     phrase(GrammarRuleBody, Input)
     phrase(::GrammarRuleBody, Input)
     phrase(Object::GrammarRuleBody, Input)

True when the ‘GrammarRuleBody’ grammar rule body can be applied to the
‘Input’ list of tokens.  In the most common case, ‘GrammarRuleBody’ is a
non-terminal defined by a grammar rule.  This built-in method is
declared private and thus cannot be used as a message to an object.
When using a *note backend Prolog compiler: 34. supporting a module
system, calls in the format ‘phrase(Module:GrammarRuleBody, Input)’ may
also be used.

This method is opaque to cuts in the first argument.  When the first
argument is sufficiently instantiated at compile-time, the method call
is compiled in order to eliminate the implicit overheads of converting
the grammar rule body into a goal and meta-calling it.  For performance
reasons, the second argument is only type-checked at compile-time.


File: TheLogtalkHandbook-3.101.0.info,  Node: Meta-predicate template<15>,  Next: Modes and number of proofs<111>,  Prev: Description<148>,  Up: phrase/2

2.5.10.20 Meta-predicate template
.................................

     phrase(2, *)


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<111>,  Next: Errors<112>,  Prev: Meta-predicate template<15>,  Up: phrase/2

2.5.10.21 Modes and number of proofs
....................................

     phrase(+callable, ?list) - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<112>,  Next: Examples<149>,  Prev: Modes and number of proofs<111>,  Up: phrase/2

2.5.10.22 Errors
................

     ‘GrammarRuleBody’ is a variable:
          ‘instantiation_error’
     ‘GrammarRuleBody’ is neither a variable nor a callable term:
          ‘type_error(callable, GrammarRuleBody)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<149>,  Prev: Errors<112>,  Up: phrase/2

2.5.10.23 Examples
..................

     To parse a list of tokens using a local non-terminal:
          ‘phrase(NonTerminal, Input)’
     To parse a list of tokens using a non-terminal within the scope of *note self: 69.:
          ‘phrase(::NonTerminal, Input)’
     To parse a list of tokens using a public non-terminal of an explicit object:
          ‘phrase(Object::NonTerminal, Input)’

See also
........

*note call//1-N: 1c9, *note phrase//1: 1c8, *note phrase/3: 18f.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: phrase/3,  Prev: phrase/2,  Up: Definite clause grammar rules<2>

2.5.10.24 ‘phrase/3’
....................

* Menu:

* Description: Description<149>.
* Meta-predicate template: Meta-predicate template<16>.
* Modes and number of proofs: Modes and number of proofs<112>.
* Errors: Errors<113>.
* Examples: Examples<150>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<149>,  Next: Meta-predicate template<16>,  Up: phrase/3

2.5.10.25 Description
.....................

     phrase(GrammarRuleBody, Input, Rest)
     phrase(::GrammarRuleBody, Input, Rest)
     phrase(Object::GrammarRuleBody, Input, Rest)

True when the ‘GrammarRuleBody’ grammar rule body can be applied to the
‘Input-Rest’ difference list of tokens.  In the most common case,
‘GrammarRuleBody’ is a non-terminal defined by a grammar rule.  This
built-in method is declared private and thus cannot be used as a message
to an object.  When using a *note backend Prolog compiler: 34.
supporting a module system, calls in the format
‘phrase(Module:GrammarRuleBody, Input, Rest)’ may also be used.

This method is opaque to cuts in the first argument.  When the first
argument is sufficiently instantiated at compile-time, the method call
is compiled in order to eliminate the implicit overheads of converting
the grammar rule body into a goal and meta-calling it.  For performance
reasons, the second and third arguments are only type-checked at compile
time.


File: TheLogtalkHandbook-3.101.0.info,  Node: Meta-predicate template<16>,  Next: Modes and number of proofs<112>,  Prev: Description<149>,  Up: phrase/3

2.5.10.26 Meta-predicate template
.................................

     phrase(2, *, *)


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<112>,  Next: Errors<113>,  Prev: Meta-predicate template<16>,  Up: phrase/3

2.5.10.27 Modes and number of proofs
....................................

     phrase(+callable, ?list, ?list) - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<113>,  Next: Examples<150>,  Prev: Modes and number of proofs<112>,  Up: phrase/3

2.5.10.28 Errors
................

     ‘GrammarRuleBody’ is a variable:
          ‘instantiation_error’
     ‘GrammarRuleBody’ is neither a variable nor a callable term:
          ‘type_error(callable, GrammarRuleBody)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<150>,  Prev: Errors<113>,  Up: phrase/3

2.5.10.29 Examples
..................

     To parse a list of tokens using a local non-terminal:
          ‘phrase(NonTerminal, Input, Rest)’
     To parse a list of tokens using a non-terminal within the scope of *note self: 69.:
          ‘phrase(::NonTerminal, Input, Rest)’
     To parse a list of tokens using a public non-terminal of an explicit object:
          ‘phrase(Object::NonTerminal, Input, Rest)’

See also
........

*note call//1-N: 1c9, *note phrase/2: 18e, *note phrase/3: 18f.


File: TheLogtalkHandbook-3.101.0.info,  Node: Term and goal expansion<2>,  Next: Coinduction hooks,  Prev: Definite clause grammar rules<2>,  Up: Built-in methods<2>

2.5.11 Term and goal expansion
------------------------------

'built-in method'

* Menu:

* expand_term/2::
* term_expansion/2::
* expand_goal/2::
* goal_expansion/2::


File: TheLogtalkHandbook-3.101.0.info,  Node: expand_term/2,  Next: term_expansion/2,  Up: Term and goal expansion<2>

2.5.11.1 ‘expand_term/2’
........................

* Menu:

* Description: Description<150>.
* Modes and number of proofs: Modes and number of proofs<113>.
* Errors: Errors<114>.
* Examples: Examples<151>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<150>,  Next: Modes and number of proofs<113>,  Up: expand_term/2

2.5.11.2 Description
....................

     expand_term(Term, Expansion)

Expands a term.  The most common use is to expand a grammar rule into a
clause.  Users may override the default Logtalk grammar rule translator
by defining clauses for the *note term_expansion/2: fc. hook predicate.

The expansion works as follows: if the first argument is a variable,
then it is unified with the second argument; if the first argument is
not a variable and there are local or inherited clauses for the
‘term_expansion/2’ hook predicate within scope, then this predicate is
called to provide an expansion that is then unified with the second
argument; if the ‘term_expansion/2’ predicate is not used and the first
argument is a compound term with functor ‘(-->)/2’ then the default
Logtalk grammar rule translator is used, with the resulting clause being
unified with the second argument; when the translator is not used, the
two arguments are unified.  The ‘expand_term/2’ predicate may return a
single term or a list of terms.

This built-in method may be used to expand a grammar rule into a clause
for use with the built-in database methods.

Automatic term expansion is only performed at compile-time (to expand
terms read from a source file) when using a *note hook object: 39f.
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.101.0.info,  Node: Modes and number of proofs<113>,  Next: Errors<114>,  Prev: Description<150>,  Up: expand_term/2

2.5.11.3 Modes and number of proofs
...................................

     expand_term(?term, ?term) - one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<114>,  Next: Examples<151>,  Prev: Modes and number of proofs<113>,  Up: expand_term/2

2.5.11.4 Errors
...............

(none)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<151>,  Prev: Errors<114>,  Up: expand_term/2

2.5.11.5 Examples
.................

(none)

See also
........

*note expand_goal/2: 313, *note goal_expansion/2: fd, *note
term_expansion/2: fc.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: term_expansion/2,  Next: expand_goal/2,  Prev: expand_term/2,  Up: Term and goal expansion<2>

2.5.11.6 ‘term_expansion/2’
...........................

* Menu:

* Description: Description<151>.
* Modes and number of proofs: Modes and number of proofs<114>.
* Errors: Errors<115>.
* Examples: Examples<152>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<151>,  Next: Modes and number of proofs<114>,  Up: term_expansion/2

2.5.11.7 Description
....................

     term_expansion(Term, Expansion)

Defines an expansion for a term.  This predicate, when defined and
within scope, is automatically called by the *note expand_term/2: 1b7.
method.  When that is not the case, the ‘expand_term/2’ method only uses
the default expansions.  Use of this predicate by the ‘expand_term/2’
method may be restricted by changing its default public scope.

The ‘term_expansion/2’ predicate may return a list of terms.  Returning
an empty list effectively suppresses the term.

Term expansion may also be applied when compiling source files by
defining the object providing access to the ‘term_expansion/2’ clauses
as a *note hook object: 39f.  Clauses for the ‘term_expansion/2’
predicate defined within an object or a category are 'never' used in the
compilation of the object or the category itself.  Moreover, in this
context, terms wrapped using the *note {}/1: 191. compiler bypass
control construct are not expanded and any expanded term wrapped in this
control construct will not be further expanded.

Objects and categories implementing this predicate should declare that
they implement the expanding(1) protocol if no ancestor already declares
it.  This protocol implementation relation can be declared as either
*note protected or private: 9e. to restrict the scope of this predicate.

   ---------- Footnotes ----------

   (1) ../../../apis/expanding_0.html#expanding-0


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<114>,  Next: Errors<115>,  Prev: Description<151>,  Up: term_expansion/2

2.5.11.8 Modes and number of proofs
...................................

     term_expansion(+nonvar, -nonvar) - zero_or_one
     term_expansion(+nonvar, -list(nonvar)) - zero_or_one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<115>,  Next: Examples<152>,  Prev: Modes and number of proofs<114>,  Up: term_expansion/2

2.5.11.9 Errors
...............

(none)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<152>,  Prev: Errors<115>,  Up: term_expansion/2

2.5.11.10 Examples
..................

     term_expansion((:- license(default)), (:- license(gplv3))).
     term_expansion(data(Millimeters), data(Meters)) :- Meters is Millimeters / 1000.

See also
........

*note expand_goal/2: 313, *note expand_term/2: 1b7, *note
goal_expansion/2: fd, *note logtalk_load_context/2: 318.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: expand_goal/2,  Next: goal_expansion/2,  Prev: term_expansion/2,  Up: Term and goal expansion<2>

2.5.11.11 ‘expand_goal/2’
.........................

* Menu:

* Description: Description<152>.
* Modes and number of proofs: Modes and number of proofs<115>.
* Errors: Errors<116>.
* Examples: Examples<153>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<152>,  Next: Modes and number of proofs<115>,  Up: expand_goal/2

2.5.11.12 Description
.....................

     expand_goal(Goal, ExpandedGoal)

Expands a goal.  The expansion works as follows: if the first argument
is a variable, then it is unified with the second argument; if the first
argument is not a variable and there are local or inherited clauses for
the ‘goal_expansion/2’ hook predicate within scope, then this predicate
is recursively called until a fixed-point is reached to provide an
expansion that is then unified with the second argument; if the
‘goal_expansion/2’ predicate is not within scope, the two arguments are
unified.

Automatic goal expansion is only performed at compile-time (to expand
the body of clauses and meta-directives read from a source file) when
using *note hook objects: 39f.  This predicate can be used by the user
to manually perform goal expansion at runtime (for example, before
asserting a clause).


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<115>,  Next: Errors<116>,  Prev: Description<152>,  Up: expand_goal/2

2.5.11.13 Modes and number of proofs
....................................

     expand_goal(?term, ?term) - one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<116>,  Next: Examples<153>,  Prev: Modes and number of proofs<115>,  Up: expand_goal/2

2.5.11.14 Errors
................

(none)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<153>,  Prev: Errors<116>,  Up: expand_goal/2

2.5.11.15 Examples
..................

(none)

See also
........

*note expand_term/2: 1b7, *note goal_expansion/2: fd, *note
term_expansion/2: fc.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: goal_expansion/2,  Prev: expand_goal/2,  Up: Term and goal expansion<2>

2.5.11.16 ‘goal_expansion/2’
............................

* Menu:

* Description: Description<153>.
* Modes and number of proofs: Modes and number of proofs<116>.
* Errors: Errors<117>.
* Examples: Examples<154>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<153>,  Next: Modes and number of proofs<116>,  Up: goal_expansion/2

2.5.11.17 Description
.....................

     goal_expansion(Goal, ExpandedGoal)

Defines an expansion for a goal.  The first argument is the goal to be
expanded.  The expanded goal is returned in the second argument.  This
predicate is called recursively on the expanded goal until a fixed point
is reached.  Thus, care must be taken to avoid compilation loops.  This
predicate, when defined and within scope, is automatically called by the
*note expand_goal/2: 313. method.  Use of this predicate by the
‘expand_goal/2’ method may be restricted by changing its default public
scope.

Goal expansion may also be applied when compiling source files by
defining the object providing access to the ‘goal_expansion/2’ clauses
as a *note hook object: 39f.  Clauses for the ‘goal_expansion/2’
predicate defined within an object or a category are 'never' used in the
compilation of the object or the category itself.  Moreover, in this
context, goals wrapped using the *note {}/1: 191. compiler bypass
control construct are not expanded and any expanded goal wrapped in this
control construct will not be further expanded.

Objects and categories implementing this predicate should declare that
they implement the expanding(1) built-in protocol if no ancestor already
declares it.  This protocol implementation relation can be declared as
either *note protected or private: 9e. to restrict the scope of this
predicate.

   ---------- Footnotes ----------

   (1) ../../../apis/expanding_0.html#expanding-0


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<116>,  Next: Errors<117>,  Prev: Description<153>,  Up: goal_expansion/2

2.5.11.18 Modes and number of proofs
....................................

     goal_expansion(+callable, -callable) - zero_or_one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<117>,  Next: Examples<154>,  Prev: Modes and number of proofs<116>,  Up: goal_expansion/2

2.5.11.19 Errors
................

(none)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<154>,  Prev: Errors<117>,  Up: goal_expansion/2

2.5.11.20 Examples
..................

     goal_expansion(write(Term), (write_term(Term, []), nl)).
     goal_expansion(read(Term), (write('Input: '), {read(Term)})).

See also
........

*note expand_goal/2: 313, *note expand_term/2: 1b7, *note
term_expansion/2: fc, *note logtalk_load_context/2: 318.


File: TheLogtalkHandbook-3.101.0.info,  Node: Coinduction hooks,  Next: Message printing,  Prev: Term and goal expansion<2>,  Up: Built-in methods<2>

2.5.12 Coinduction hooks
------------------------

'built-in method'

* Menu:

* coinductive_success_hook/1-2::


File: TheLogtalkHandbook-3.101.0.info,  Node: coinductive_success_hook/1-2,  Up: Coinduction hooks

2.5.12.1 ‘coinductive_success_hook/1-2’
.......................................

* Menu:

* Description: Description<154>.
* Modes and number of proofs: Modes and number of proofs<117>.
* Errors: Errors<118>.
* Examples: Examples<155>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<154>,  Next: Modes and number of proofs<117>,  Up: coinductive_success_hook/1-2

2.5.12.2 Description
....................

     coinductive_success_hook(Head, Hypothesis)
     coinductive_success_hook(Head)

User-defined hook predicates that are automatically called in case of
coinductive success when proving a query for a coinductive predicates.
The hook predicates are called with the head of the coinductive
predicate on coinductive success and, optionally, with the hypothesis
that has used to reach coinductive success.

When both hook predicates are defined, the ‘coinductive_success_hook/1’
clauses are only used if no ‘coinductive_success_hook/2’ clause applies.
The compiler ensures zero performance penalties when defining
coinductive predicates without a corresponding definition for the
coinductive success hook predicates.

The compiler assumes that these hook predicates are defined as static
predicates in order to optimize their use.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<117>,  Next: Errors<118>,  Prev: Description<154>,  Up: coinductive_success_hook/1-2

2.5.12.3 Modes and number of proofs
...................................

     coinductive_success_hook(+callable, +callable) - zero_or_one
     coinductive_success_hook(+callable) - zero_or_one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<118>,  Next: Examples<155>,  Prev: Modes and number of proofs<117>,  Up: coinductive_success_hook/1-2

2.5.12.4 Errors
...............

(none)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<155>,  Prev: Errors<118>,  Up: coinductive_success_hook/1-2

2.5.12.5 Examples
.................

     % Are there "occurrences" of arg1 in arg2?
     :- public(member/2).
     :- coinductive(member/2).

     member(X, [X| _]).
     member(X, [_| T]) :-
         member(X, T).

     % Are there infinitely many "occurrences" of arg1 in arg2?
     :- public(comember/2).
     :- coinductive(comember/2).
     comember(X, [_| T]) :-
         comember(X, T).

     coinductive_success_hook(member(_, _)) :-
         fail.
     coinductive_success_hook(comember(X, L)) :-
         member(X, L).

See also
........

*note coinductive/1: 171.


File: TheLogtalkHandbook-3.101.0.info,  Node: Message printing,  Next: Question asking,  Prev: Coinduction hooks,  Up: Built-in methods<2>

2.5.13 Message printing
-----------------------

'built-in method'

* Menu:

* print_message/3::
* message_tokens//2::
* message_hook/4::
* message_prefix_stream/4::
* message_prefix_file/6::
* print_message_tokens/3::
* print_message_token/4::


File: TheLogtalkHandbook-3.101.0.info,  Node: print_message/3,  Next: message_tokens//2,  Up: Message printing

2.5.13.1 ‘print_message/3’
..........................

* Menu:

* Description: Description<155>.
* Modes and number of proofs: Modes and number of proofs<118>.
* Errors: Errors<119>.
* Examples: Examples<156>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<155>,  Next: Modes and number of proofs<118>,  Up: print_message/3

2.5.13.2 Description
....................

     print_message(Kind, Component, Term)

Built-in method for printing a message represented by a term, which is
converted to the message text using the *note
logtalk;;message_tokens(Term, Component): 301. 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): 305.
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): 307. hook predicate.  If this predicate succeeds, the
‘print_message/3’ predicate assumes that the message has been
successfully printed.

By default: messages of kind ‘debug’ or ‘debug(_)’ are only printed when
the ‘debug’ flag is turned on; messages of kind ‘banner’, ‘comment’, or
‘comment(_)’ are only printed when the ‘report’ flag is set to ‘on’;
messages of kind ‘warning’ and ‘warning(_)’ are not printed when the
‘report’ flag is set to ‘off’; messages of kind ‘silent’ and ‘silent()’
are not printed (but can be intercepted).

   ---------- Footnotes ----------

   (1) ../../../apis/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<118>,  Next: Errors<119>,  Prev: Description<155>,  Up: print_message/3

2.5.13.3 Modes and number of proofs
...................................

     print_message(+nonvar, +nonvar, +nonvar) - one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<119>,  Next: Examples<156>,  Prev: Modes and number of proofs<118>,  Up: print_message/3

2.5.13.4 Errors
...............

(none)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<156>,  Prev: Errors<119>,  Up: print_message/3

2.5.13.5 Examples
.................

     ..., logtalk::print_message(information, core, redefining_entity(object, foo)), ...

See also
........

*note message_hook/4: 307, *note message_prefix_stream/4: 305, *note
message_tokens//2: 301, *note print_message_tokens/3: 7f9, *note
print_message_token/4: 7fa, *note ask_question/5: 30c, *note
question_hook/6: 30e, *note question_prompt_stream/4: 7fb.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: message_tokens//2,  Next: message_hook/4,  Prev: print_message/3,  Up: Message printing

2.5.13.6 ‘message_tokens//2’
............................

* Menu:

* Description: Description<156>.
* Modes and number of proofs: Modes and number of proofs<119>.
* Errors: Errors<120>.
* Examples: Examples<157>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<156>,  Next: Modes and number of proofs<119>,  Up: message_tokens//2

2.5.13.7 Description
....................

     message_tokens(Message, Component)

User-defined non-terminal hook used to rewrite a message term into a
list of tokens and declared in the logtalk(1) built-in object as a
public, multifile, and dynamic non-terminal.  The list of tokens can be
printed by calling the *note print_message_tokens/3: 7f9. method.  This
non-terminal hook is automatically called by the *note print_message/3:
2ff. method.

   ---------- Footnotes ----------

   (1) ../../../apis/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<119>,  Next: Errors<120>,  Prev: Description<156>,  Up: message_tokens//2

2.5.13.8 Modes and number of proofs
...................................

     message_tokens(+nonvar, +nonvar) - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<120>,  Next: Examples<157>,  Prev: Modes and number of proofs<119>,  Up: message_tokens//2

2.5.13.9 Errors
...............

(none)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<157>,  Prev: Errors<120>,  Up: message_tokens//2

2.5.13.10 Examples
..................

     :- multifile(logtalk::message_tokens//2).
     :- dynamic(logtalk::message_tokens//2).

     logtalk::message_tokens(redefining_entity(Type, Entity), core) -->
         ['Redefining ~w ~q'-[Type, Entity], nl].

See also
........

*note message_hook/4: 307, *note message_prefix_stream/4: 305, *note
print_message/3: 2ff, *note print_message_tokens/3: 7f9, *note
print_message_token/4: 7fa, *note ask_question/5: 30c, *note
question_hook/6: 30e, *note question_prompt_stream/4: 7fb.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: message_hook/4,  Next: message_prefix_stream/4,  Prev: message_tokens//2,  Up: Message printing

2.5.13.11 ‘message_hook/4’
..........................

* Menu:

* Description: Description<157>.
* Modes and number of proofs: Modes and number of proofs<120>.
* Errors: Errors<121>.
* Examples: Examples<158>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<157>,  Next: Modes and number of proofs<120>,  Up: message_hook/4

2.5.13.12 Description
.....................

     message_hook(Message, Kind, Component, Tokens)

User-defined hook method for intercepting printing of a message,
declared in the logtalk(1) built-in object as a public, multifile, and
dynamic predicate.  This hook method is automatically called by the
*note print_message/3: 2ff. method.  When the call succeeds, the
‘print_message/3’ method assumes that the message has been successfully
printed.

   ---------- Footnotes ----------

   (1) ../../../apis/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<120>,  Next: Errors<121>,  Prev: Description<157>,  Up: message_hook/4

2.5.13.13 Modes and number of proofs
....................................

     message_hook(@nonvar, @nonvar, @nonvar, @list(nonvar)) - zero_or_one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<121>,  Next: Examples<158>,  Prev: Modes and number of proofs<120>,  Up: message_hook/4

2.5.13.14 Errors
................

(none)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<158>,  Prev: Errors<121>,  Up: message_hook/4

2.5.13.15 Examples
..................

     :- multifile(logtalk::message_hook/4).
     :- dynamic(logtalk::message_hook/4).

     % print silent messages instead of discarding them as default
     logtalk::message_hook(_, silent, core, Tokens) :-
         logtalk::message_prefix_stream(silent, core, Prefix, Stream),
         logtalk::print_message_tokens(Stream, Prefix, Tokens).

See also
........

*note message_prefix_stream/4: 305, *note message_tokens//2: 301, *note
print_message/3: 2ff, *note print_message_tokens/3: 7f9, *note
print_message_token/4: 7fa, *note ask_question/5: 30c, *note
question_hook/6: 30e, *note question_prompt_stream/4: 7fb.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: message_prefix_stream/4,  Next: message_prefix_file/6,  Prev: message_hook/4,  Up: Message printing

2.5.13.16 ‘message_prefix_stream/4’
...................................

* Menu:

* Description: Description<158>.
* Modes and number of proofs: Modes and number of proofs<121>.
* Errors: Errors<122>.
* Examples: Examples<159>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<158>,  Next: Modes and number of proofs<121>,  Up: message_prefix_stream/4

2.5.13.17 Description
.....................

     message_prefix_stream(Kind, Component, Prefix, Stream)

User-defined hook method for specifying the default prefix and stream
for printing a message for a given kind and *note component: 354.  This
method is declared in the logtalk(1) built-in object as a public,
multifile, and dynamic predicate.

The prefix is printed for each line in the list of tokens generated by
the message tokenization (new lines are specified using the ‘nl’ token;
see the documentation of the logtalk(2) built-in object for details).

   ---------- Footnotes ----------

   (1) ../../../apis/logtalk_0.html#logtalk-0

   (2) ../../../apis/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<121>,  Next: Errors<122>,  Prev: Description<158>,  Up: message_prefix_stream/4

2.5.13.18 Modes and number of proofs
....................................

     message_prefix_stream(?nonvar, ?nonvar, ?atom, ?stream_or_alias) - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<122>,  Next: Examples<159>,  Prev: Modes and number of proofs<121>,  Up: message_prefix_stream/4

2.5.13.19 Errors
................

(none)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<159>,  Prev: Errors<122>,  Up: message_prefix_stream/4

2.5.13.20 Examples
..................

     :- multifile(logtalk::message_prefix_stream/4).
     :- dynamic(logtalk::message_prefix_stream/4).

     logtalk::message_prefix_stream(information, core, '% ', user_output).

See also
........

*note message_prefix_file/6: 308, *note message_hook/4: 307, *note
message_tokens//2: 301, *note print_message/3: 2ff, *note
print_message_tokens/3: 7f9, *note print_message_token/4: 7fa, *note
ask_question/5: 30c, *note question_hook/6: 30e, *note
question_prompt_stream/4: 7fb.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: message_prefix_file/6,  Next: print_message_tokens/3,  Prev: message_prefix_stream/4,  Up: Message printing

2.5.13.21 ‘message_prefix_file/6’
.................................

* Menu:

* Description: Description<159>.
* Modes and number of proofs: Modes and number of proofs<122>.
* Errors: Errors<123>.
* Examples: Examples<160>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<159>,  Next: Modes and number of proofs<122>,  Up: message_prefix_file/6

2.5.13.22 Description
.....................

     message_prefix_file(Kind, Component, Prefix, File, Mode, Options)

Experimental user-defined hook method for specifying the prefix and file
for copying messages for a given kind and *note component: 354.  This
method is declared in the logtalk(1) built-in object as a public,
multifile, and dynamic predicate.  The valid values for ‘Mode’ are
‘write’ and ‘append’.  The valid options are the same as the standard
‘open/4’ predicate.

The prefix is printed for each line in the list of tokens generated by
the message tokenization (new lines are specified using the ‘nl’ token;
see the documentation of the logtalk(2) built-in object for details).

   ---------- Footnotes ----------

   (1) ../../../apis/logtalk_0.html#logtalk-0

   (2) ../../../apis/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<122>,  Next: Errors<123>,  Prev: Description<159>,  Up: message_prefix_file/6

2.5.13.23 Modes and number of proofs
....................................

     message_prefix_file(?nonvar, ?nonvar, ?atom, ?atom, ?atom, ?list(compound)) - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<123>,  Next: Examples<160>,  Prev: Modes and number of proofs<122>,  Up: message_prefix_file/6

2.5.13.24 Errors
................

(none)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<160>,  Prev: Errors<123>,  Up: message_prefix_file/6

2.5.13.25 Examples
..................

     :- multifile(logtalk::message_prefix_file/6).
     :- dynamic(logtalk::message_prefix_file/6).

     logtalk::message_prefix_file(comment, app, '% ', 'comments.txt', append, []).

See also
........

*note message_prefix_stream/4: 305, *note message_hook/4: 307, *note
message_tokens//2: 301, *note print_message/3: 2ff, *note
print_message_tokens/3: 7f9, *note print_message_token/4: 7fa, *note
ask_question/5: 30c, *note question_hook/6: 30e, *note
question_prompt_stream/4: 7fb.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: print_message_tokens/3,  Next: print_message_token/4,  Prev: message_prefix_file/6,  Up: Message printing

2.5.13.26 ‘print_message_tokens/3’
..................................

* Menu:

* Description: Description<160>.
* Modes and number of proofs: Modes and number of proofs<123>.
* Errors: Errors<124>.
* Examples: Examples<161>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<160>,  Next: Modes and number of proofs<123>,  Up: print_message_tokens/3

2.5.13.27 Description
.....................

     print_message_tokens(Stream, Prefix, Tokens)

Built-in method for printing a list of message tokens, declared in the
logtalk(1) built-in object as a public predicate.  This method is
automatically called by the *note print_message/3: 2ff. method (assuming
that the message was not intercepted by a *note message_hook/4: 307.
definition) and calls the user-defined hook predicate *note
print_message_token/4: 7fa. for each token.  When a call to this hook
predicate succeeds, the ‘print_message_tokens/3’ predicate assumes that
the token has been printed.  When the call fails, the
‘print_message_tokens/3’ predicate uses a default printing procedure for
the token.

   ---------- Footnotes ----------

   (1) ../../../apis/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<123>,  Next: Errors<124>,  Prev: Description<160>,  Up: print_message_tokens/3

2.5.13.28 Modes and number of proofs
....................................

     print_message_tokens(@stream_or_alias, +atom, @list(nonvar)) - zero_or_one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<124>,  Next: Examples<161>,  Prev: Modes and number of proofs<123>,  Up: print_message_tokens/3

2.5.13.29 Errors
................

(none)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<161>,  Prev: Errors<124>,  Up: print_message_tokens/3

2.5.13.30 Examples
..................

     ...,
     logtalk::print_message_tokens(user_error, '% ', ['Redefining ~w ~q'-[object,foo], nl]),
     ...

See also
........

*note message_hook/4: 307, *note message_prefix_stream/4: 305, *note
message_tokens//2: 301, *note print_message/3: 2ff, *note
print_message_token/4: 7fa, *note ask_question/5: 30c, *note
question_hook/6: 30e, *note question_prompt_stream/4: 7fb.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: print_message_token/4,  Prev: print_message_tokens/3,  Up: Message printing

2.5.13.31 ‘print_message_token/4’
.................................

* Menu:

* Description: Description<161>.
* Modes and number of proofs: Modes and number of proofs<124>.
* Errors: Errors<125>.
* Examples: Examples<162>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<161>,  Next: Modes and number of proofs<124>,  Up: print_message_token/4

2.5.13.32 Description
.....................

     print_message_token(Stream, Prefix, Token, Tokens)

User-defined hook method for printing a message token, declared in the
logtalk(1) built-in object as a public, multifile, and dynamic
predicate.  It allows the user to intercept the printing of a message
token.  This hook method is automatically called by the *note
print_message_tokens/3: 7f9. built-in method for each token.

   ---------- Footnotes ----------

   (1) ../../../apis/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<124>,  Next: Errors<125>,  Prev: Description<161>,  Up: print_message_token/4

2.5.13.33 Modes and number of proofs
....................................

     print_message_token(@stream_or_alias, @atom, @nonvar, @list(nonvar)) - zero_or_one


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<125>,  Next: Examples<162>,  Prev: Modes and number of proofs<124>,  Up: print_message_token/4

2.5.13.34 Errors
................

(none)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<162>,  Prev: Errors<125>,  Up: print_message_token/4

2.5.13.35 Examples
..................

     :- multifile(logtalk::print_message_token/4).
     :- dynamic(logtalk::print_message_token/4).

     % ignore all flush tokens
     logtalk::print_message_token(_Stream, _Prefix, flush, _Tokens).

See also
........

*note message_hook/4: 307, *note message_prefix_stream/4: 305, *note
message_tokens//2: 301, *note print_message/3: 2ff, *note
print_message_tokens/3: 7f9, *note ask_question/5: 30c, *note
question_hook/6: 30e, *note question_prompt_stream/4: 7fb.


File: TheLogtalkHandbook-3.101.0.info,  Node: Question asking,  Prev: Message printing,  Up: Built-in methods<2>

2.5.14 Question asking
----------------------

'built-in method'

* Menu:

* ask_question/5::
* question_hook/6::
* question_prompt_stream/4::


File: TheLogtalkHandbook-3.101.0.info,  Node: ask_question/5,  Next: question_hook/6,  Up: Question asking

2.5.14.1 ‘ask_question/5’
.........................

* Menu:

* Description: Description<162>.
* Modes and number of proofs: Modes and number of proofs<125>.
* Meta-predicate template: Meta-predicate template<17>.
* Errors: Errors<126>.
* Examples: Examples<163>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<162>,  Next: Modes and number of proofs<125>,  Up: ask_question/5

2.5.14.2 Description
....................

     ask_question(Kind, Component, Question, Check, Answer)

Built-in method for asking a question represented by a term, ‘Question’,
which is converted to the question text using the *note
logtalk;;message_tokens(Question, Component): 301. 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): 7fb.
hook predicate.  The ‘Check’ argument is a *note closure: 14f. that is
converted into a checking goal by extending it with the user supplied
answer.  This predicate implements a read-loop that terminates when the
check goal succeeds.

This predicate starts by calling the *note
logtalk;;question_hook(Question, Kind, Component, Tokens, Check,
Answer): 30e. hook predicate.  If this predicate succeeds, the
‘ask_question/5’ predicate assumes that the question have been
successfully asked and replied.


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<125>,  Next: Meta-predicate template<17>,  Prev: Description<162>,  Up: ask_question/5

2.5.14.3 Modes and number of proofs
...................................

     ask_question(+nonvar, +nonvar, +nonvar, +callable, -term) - one


File: TheLogtalkHandbook-3.101.0.info,  Node: Meta-predicate template<17>,  Next: Errors<126>,  Prev: Modes and number of proofs<125>,  Up: ask_question/5

2.5.14.4 Meta-predicate template
................................

     ask_question(*, *, *, 1, *)


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<126>,  Next: Examples<163>,  Prev: Meta-predicate template<17>,  Up: ask_question/5

2.5.14.5 Errors
...............

(none)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<163>,  Prev: Errors<126>,  Up: ask_question/5

2.5.14.6 Examples
.................

     ...,
     logtalk::ask_question(enter_age, question, my_app, integer, Age),
     ...

See also
........

*note question_hook/6: 30e, *note question_prompt_stream/4: 7fb, *note
message_hook/4: 307, *note message_prefix_stream/4: 305, *note
message_tokens//2: 301, *note print_message/3: 2ff, *note
print_message_tokens/3: 7f9, *note print_message_token/4: 7fa.

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: question_hook/6,  Next: question_prompt_stream/4,  Prev: ask_question/5,  Up: Question asking

2.5.14.7 ‘question_hook/6’
..........................

* Menu:

* Description: Description<163>.
* Modes and number of proofs: Modes and number of proofs<126>.
* Meta-predicate template: Meta-predicate template<18>.
* Errors: Errors<127>.
* Examples: Examples<164>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<163>,  Next: Modes and number of proofs<126>,  Up: question_hook/6

2.5.14.8 Description
....................

     question_hook(Question, Kind, Component, Tokens, Check, Answer)

User-defined hook method for intercepting asking a question, declared in
the logtalk(1) built-in object as a public, multifile, and dynamic
predicate.  This hook method is automatically called by the *note
ask_question/5: 30c. method.  When the call succeeds, the
‘ask_question/5’ method assumes that the question have been successfully
asked and replied.

   ---------- Footnotes ----------

   (1) ../../../apis/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<126>,  Next: Meta-predicate template<18>,  Prev: Description<163>,  Up: question_hook/6

2.5.14.9 Modes and number of proofs
...................................

     question_hook(+nonvar, +nonvar, +nonvar, +list(nonvar), +callable, -term) - zero_or_one


File: TheLogtalkHandbook-3.101.0.info,  Node: Meta-predicate template<18>,  Next: Errors<127>,  Prev: Modes and number of proofs<126>,  Up: question_hook/6

2.5.14.10 Meta-predicate template
.................................

     question_hook(*, *, *, *, 1, *)


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<127>,  Next: Examples<164>,  Prev: Meta-predicate template<18>,  Up: question_hook/6

2.5.14.11 Errors
................

(none)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<164>,  Prev: Errors<127>,  Up: question_hook/6

2.5.14.12 Examples
..................

     :- multifile(logtalk::question_hook/6).
     :- dynamic(logtalk::question_hook/6).

     % use a pre-defined answer instead of asking the user
     logtalk::question_hook(upper_limit, question, my_app, _, _, 3.7).

See also
........

*note ask_question/5: 30c, *note question_prompt_stream/4: 7fb. *note
message_hook/4: 307, *note message_prefix_stream/4: 305, *note
message_tokens//2: 301, *note print_message/3: 2ff, *note
print_message_tokens/3: 7f9, *note print_message_token/4: 7fa,

'built-in method'


File: TheLogtalkHandbook-3.101.0.info,  Node: question_prompt_stream/4,  Prev: question_hook/6,  Up: Question asking

2.5.14.13 ‘question_prompt_stream/4’
....................................

* Menu:

* Description: Description<164>.
* Modes and number of proofs: Modes and number of proofs<127>.
* Errors: Errors<128>.
* Examples: Examples<165>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<164>,  Next: Modes and number of proofs<127>,  Up: question_prompt_stream/4

2.5.14.14 Description
.....................

     question_prompt_stream(Kind, Component, Prompt, Stream)

User-defined hook method for specifying the default prompt and input
stream for asking a question for a given kind and *note component: 354.
This method is declared in the logtalk(1) built-in object as a public,
multifile, and dynamic predicate.

   ---------- Footnotes ----------

   (1) ../../../apis/logtalk_0.html#logtalk-0


File: TheLogtalkHandbook-3.101.0.info,  Node: Modes and number of proofs<127>,  Next: Errors<128>,  Prev: Description<164>,  Up: question_prompt_stream/4

2.5.14.15 Modes and number of proofs
....................................

     question_prompt_stream(?nonvar, ?nonvar, ?atom, ?stream_or_alias) - zero_or_more


File: TheLogtalkHandbook-3.101.0.info,  Node: Errors<128>,  Next: Examples<165>,  Prev: Modes and number of proofs<127>,  Up: question_prompt_stream/4

2.5.14.16 Errors
................

(none)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<165>,  Prev: Errors<128>,  Up: question_prompt_stream/4

2.5.14.17 Examples
..................

     :- multifile(logtalk::question_prompt_stream/4).
     :- dynamic(logtalk::question_prompt_stream/4).

     logtalk::question_prompt_stream(question, debugger, '    > ', user_input).

See also
........

*note ask_question/5: 30c, *note question_hook/6: 30e, *note
message_hook/4: 307, *note message_prefix_stream/4: 305, *note
message_tokens//2: 301, *note print_message/3: 2ff, *note
print_message_tokens/3: 7f9, *note print_message_token/4: 7fa.


File: TheLogtalkHandbook-3.101.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.101.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.101.0.info,  Node: Defining a list object,  Next: Defining a list protocol,  Up: List predicates

3.1.1 Defining a list object
----------------------------

We will start by defining an object, ‘list’, containing predicate
definitions for some common list predicates like ‘append/3’, ‘length/2’,
and ‘member/2’:

     :- object(list).

         :- public([
             append/3, length/2, member/2
         ]).

         append([], List, List).
         append([Head| Tail], List, [Head| Tail2]) :-
             append(Tail, List, Tail2).

         length(List, Length) :-
             length(List, 0, Length).

         length([], Length, Length).
         length([_| Tail], Acc, Length) :-
             Acc2 is Acc + 1,
             length(Tail, Acc2, Length).

         member(Element, [Element| _]).
         member(Element, [_| List]) :-
             member(Element, List).

     :- end_object.

What is different here from a regular Prolog program?  The definitions
of the list predicates are the usual ones.  We have two new directives,
*note object/1-5: 9a. and *note end_object/0: 9b, that encapsulate the
object’s code.  In Logtalk, by default, all object predicates are
private; therefore, we have to explicitly declare all predicates that we
want to be public, that is, that we want to call from outside the
object.  This is done using the *note public/1: 143. scope directive.

After we copy the object code to a text file and saved it under the name
‘list.lgt’, we need to change the Prolog working directory to the one
used to save our file (consult your Prolog compiler reference manual).
Then, after starting Logtalk (see the *note Installing and running
Logtalk: 371. section on the User Manual), we can compile and load the
object using the *note logtalk_load/1: 46. Logtalk built-in predicate:

     | ?- logtalk_load(list).

     object list loaded
     yes

We can now try goals like:

     | ?- list::member(X, [1, 2, 3]).

     X = 1;
     X = 2;
     X = 3;
     no

or:

     | ?- list::length([1, 2, 3], L).

     L = 3
     yes

The infix operator *note (;;)/2: 7e. is used in Logtalk to send a
message to an object.  The message must match a public object predicate.
If we try to call a non-public predicate such as the ‘length/3’
auxiliary predicate an exception will be generated:

     | ?- list::length([1, 2, 3], 0, L).

     uncaught exception:
         error(
             existence_error(predicate_declaration, length/3),
             logtalk(list::length([1,2,3],0,_), ...)
         )

The exception term describes the type of error and the context where the
error occurred.


File: TheLogtalkHandbook-3.101.0.info,  Node: Defining a list protocol,  Next: Summary,  Prev: Defining a list object,  Up: List predicates

3.1.2 Defining a list protocol
------------------------------

As we saw in the above example, a Logtalk object may contain predicate
directives and predicate definitions (clauses).  The set of predicate
directives defines what we call the object’s 'protocol' or interface.
An interface may have several implementations.  For instance, we may
want to define a new object that implements the list predicates using
difference lists.  However, we do not want to repeat the predicate
directives in the new object.  Therefore, what we need is to split the
object’s protocol from the object’s implementation by defining a new
Logtalk entity known as a protocol.  Logtalk protocols are compilation
units, at the same level as objects and categories.  That said, let us
define a ‘listp’ protocol:

     :- protocol(listp).

         :- public([
             append/3, length/2, member/2
         ]).

     :- end_protocol.

Similar to what we have done for objects, we use the *note protocol/1-2:
dc. and *note end_protocol/0: dd. directives to encapsulate the
predicate directives.  We can improve this protocol by documenting the
call/return modes and the number of proofs of each predicate using the
*note mode/2: 149. directive:

     :- protocol(listp).

         :- public(append/3).
         :- mode(append(?list, ?list, ?list), zero_or_more).

         :- public(length/2).
         :- mode(length(?list, ?integer), zero_or_more).

         :- public(member/2).
         :- mode(member(?term, ?list), zero_or_more).

     :- end_protocol.

We now need to change our definition of the ‘list’ object by removing
the predicate directives and by declaring that the object implements the
‘listp’ protocol:

     :- object(list,
         implements(listp)).

         append([], List, List).
         append([Head| Tail], List, [Head| Tail2]) :-
             append(Tail, List, Tail2).
         ...

     :- end_object.

The protocol declared in ‘listp’ may now be alternatively implemented
using difference lists by defining a new object, ‘difflist’:

     :- object(difflist,
         implements(listp).

         append(L1-X, X-L2, L1-L2).
         ...

     :- end_object.


File: TheLogtalkHandbook-3.101.0.info,  Node: Summary,  Prev: Defining a list protocol,  Up: List predicates

3.1.3 Summary
-------------

   * It is easy to define a simple object: just write your Prolog code
     inside starting and ending object directives and add the necessary
     scope directives.  The object will be self-defining and ready to
     use.

   * Define a protocol when you may want to provide or enable several
     alternative definitions to a given set of predicates.  This way we
     avoid needless repetition of predicate directives.


File: TheLogtalkHandbook-3.101.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.101.0.info,  Node: Defining a category,  Next: Importing the category,  Up: Dynamic object attributes

3.2.1 Defining a category
-------------------------

We want to define a set of predicates to handle dynamic object
attributes.  We need public predicates to set, get, and delete
attributes, and a private dynamic predicate to store the attribute
values.  Let us name these predicates ‘set_attribute/2’ and
‘get_attribute/2’, for getting and setting an attribute value,
‘del_attribute/2’ and ‘del_attributes/2’, for deleting attributes, and
‘attribute_/2’, for storing the attributes values.

But we do not want to encapsulate these predicates in an object.  Why?
Because they are a set of useful, closely related, predicates that may
be used by several, unrelated, objects.  If defined at an object level,
we would be constrained to use inheritance in order to have the
predicates available to other objects.  Furthermore, this could force us
to use multi-inheritance or to have some kind of generic root object
containing all kinds of possible useful predicates.

For this kind of situation, Logtalk enables the programmer to
encapsulate the predicates in a 'category', so that they can be used in
any object.  A category is a Logtalk entity, at the same level as
objects and protocols.  It can contain predicate directives and
predicate definitions.  Category predicates can be imported by any
object, without code duplication and without resorting to inheritance.

When defining category predicates, we need to remember that a category
can be imported by more than one object.  Thus, calls to the built-in
methods that handle the private dynamic predicate (such as *note
assertz/1: 1b3. or *note retract/1: 1b5.) must be made either in the
context of 'self', using the 'message to self' control structure, *note
(;;)/1: 5c, or in the context of 'this' (i.e., in the context of the
object importing the category).  This way, we ensure that when we call
one of the attribute predicates on an object, the intended object own
definition of ‘attribute_/2’ will be used.  The predicate definitions
are straightforward.  For example, if opting to store the attributes in
'self':

     :- category(attributes).

         :- public(set_attribute/2).
         :- mode(set_attribute(+nonvar, +nonvar), one).

         :- public(get_attribute/2).
         :- mode(get_attribute(?nonvar, ?nonvar), zero_or_more).

         :- public(del_attribute/2).
         :- mode(del_attribute(?nonvar, ?nonvar), zero_or_more).

         :- public(del_attributes/2).
         :- mode(del_attributes(@term, @term), one).

         :- private(attribute_/2).
         :- mode(attribute_(?nonvar, ?nonvar), zero_or_more).
         :- dynamic(attribute_/2).

         set_attribute(Attribute, Value):-
             ::retractall(attribute_(Attribute, _)),
             ::assertz(attribute_(Attribute, Value)).

         get_attribute(Attribute, Value):-
             ::attribute_(Attribute, Value).

         del_attribute(Attribute, Value):-
             ::retract(attribute_(Attribute, Value)).

         del_attributes(Attribute, Value):-
             ::retractall(attribute_(Attribute, Value)).

     :- end_category.

The alternative, opting to store the attributes on 'this', is similar:
just delete the ‘(::)/1’ operator from the code above.

We have two new directives, *note category/1-4: 10e. and *note
end_category/0: 10f, that encapsulate the category code.  If needed, we
can put the predicate directives inside a protocol that will be
implemented by the category:

     :- category(attributes,
         implements(attributes_protocol)).

         ...

     :- end_category.

Any protocol can be implemented by either an object, a category, or
both.


File: TheLogtalkHandbook-3.101.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.101.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.101.0.info,  Node: A reflective class-based system,  Next: Profiling programs,  Prev: Dynamic object attributes,  Up: Tutorial

3.3 A reflective class-based system
===================================

When compiling an object, Logtalk distinguishes prototypes from
instances or classes by examining the object relations.  If an object
instantiates and/or specializes another object, then it is compiled as
an instance or class, otherwise it is compiled as a prototype.  A
consequence of this is that, in order to work with instance or classes,
we always have to define root objects for the instantiation and
specialization hierarchies (however, we are not restricted to a single
hierarchy).  The best solution is often to define a reflective
class-based system *note [Maes87]: 14, where every class is also an
object and, as such, an instance of some class.

In this example, we are going to define the basis for a reflective
class-based system, based on an extension of the ideas presented in
*note [Cointe87]: 9c.  This extension provides, along with root objects
for the instantiation and specialization hierarchies, explicit support
for abstract classes *note [Moura94]: 9d.

* Menu:

* Defining the base classes::
* Summary: Summary<3>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Defining the base classes,  Next: Summary<3>,  Up: A reflective class-based system

3.3.1 Defining the base classes
-------------------------------

We will start by defining three classes: ‘object’, ‘abstract_class’, and
‘class’.  The class ‘object’ will contain all predicates common to all
objects.  It will be the root of the inheritance graph:

     :- object(object,
         instantiates(class)).

         % predicates common to all objects

     :- end_object.

The class ‘abstract_class’ specializes ‘object’ by adding predicates
common to all classes.  It will be the default meta-class for abstract
classes:

     :- object(abstract_class,
         instantiates(class),
         specializes(object)).

         % predicates common to all classes

     :- end_object.

The class ‘class’ specializes ‘abstract_class’ by adding predicates
common to all instantiable classes.  It will be the root of the
instantiation graph and the default meta-class for instantiable classes:

     :- object(class,
         instantiates(class),
         specializes(abstract_class)).

         % predicates common to all instantiable classes

     :- end_object.

Note that all three objects are instances of class ‘class’.  The
instantiation and specialization relationships are chosen so that each
object may use the predicates defined in itself and in the other two
objects, with no danger of *note message lookup: 37. endless loops.


File: TheLogtalkHandbook-3.101.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.101.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.101.0.info,  Node: Messages as events,  Next: Profilers as monitors,  Up: Profiling programs

3.4.1 Messages as events
------------------------

In a pure object-oriented system, all computations start by sending
messages to objects.  We can thus define an 'event' as the sending of a
message to an object.  An event can then be specified by the tuple
‘(Object, Message, Sender)’.  This definition can be refined by
interpreting the sending of a message and the return of the control to
the object that has sent the message as two distinct events.  We call
these events respectively ‘before’ and ‘after’.  Therefore, we end up by
representing an event by the tuple ‘(Event, Object, Message, Sender)’.
For instance, if we send the message:

     | ?- foo::bar(X).

     X = 1
     yes

the two corresponding events will be:

     (before, foo, bar(X), user)
     (after, foo, bar(1), user)

Note that the second event is only generated if the message succeeds.
If the message as a goal has multiple solutions, then an ‘after’ event
will be generated for each solution.

Events are automatically generated by the message-sending mechanisms for
each public message sent using the *note (;;)/2: 7e. operator.


File: TheLogtalkHandbook-3.101.0.info,  Node: Profilers as monitors,  Next: Summary<4>,  Prev: Messages as events,  Up: Profiling programs

3.4.2 Profilers as monitors
---------------------------

A monitor is an object that reacts whenever a spied event occurs.  The
monitor actions are defined by two event handlers: *note before/3: 101.
for ‘before’ events and *note after/3: 102. for ‘after’ events.  These
predicates are automatically called by the message-sending mechanisms
when an event registered for the monitor occurs.  These event handlers
are declared as public predicates in the ‘monitoring’ built-in protocol.

In our example, we need a way to get the current time before and after
we process a message.  We will assume that we have a ‘time’ object
implementing a ‘cpu_time/1’ predicate that returns the current CPU time
for the Prolog session:

     :- object(time).

         :- public(cpu_time/1).
         :- mode(cpu_time(-number), one).
         ...

     :- end_object.

Our profiler will be named ‘stop_watch’.  It must define event handlers
for the ‘before’ and ‘after’ events that will print the event
description (object, message, and sender) and the current time:

     :- object(stop_watch,
         % event handler predicates protocol
         implements(monitoring)).

         :- uses(time, [cpu_time/1]).

         before(Object, Message, Sender) :-
             write(Object), write(' <-- '), writeq(Message),
             write(' from '), write(Sender), nl, write('STARTING at '),
             cpu_time(Seconds), write(Seconds), write(' seconds'), nl.

         after(Object, Message, Sender) :-
             write(Object), write(' <-- '), writeq(Message),
             write(' from '), write(Sender), nl, write('ENDING at '),
             cpu_time(Seconds), write(Seconds), write(' seconds'), nl.

     :- end_object.

After compiling and loading the ‘stop_watch’ object (and the objects
that we want to profile), we can use the *note define_events/5: 218.
built-in predicate to set up our profiler.  For example, to profile all
messages that are sent to the object ‘foo’, we need to call the goal:

     | ?- define_events(_, foo, _, _, stop_watch).

     yes

This call will register ‘stop_watch’ as a monitor to all messages sent
to object ‘foo’, for both ‘before’ and ‘after’ events.  Note that we say
“as a monitor”, not “the monitor”: we can have any number of monitors
over the same events.

From now on, every time we sent a message to ‘foo’, the ‘stop_watch’
monitor will print the starting and ending times for the message
execution.  For instance:

     | ?- foo::bar(X).

     foo <-- bar(X) from user
     STARTING at 12.87415 seconds
     foo <-- bar(1) from user
     ENDING at 12.87419 seconds

     X = 1
     yes

To stop profiling the messages sent to ‘foo’ we use the *note
abolish_events/5: 21b. built-in predicate:

     | ?- abolish_events(_, foo, _, _, stop_watch).

     yes

This call will abolish all events defined over the object ‘foo’ assigned
to the ‘stop_watch’ monitor.


File: TheLogtalkHandbook-3.101.0.info,  Node: Summary<4>,  Prev: Profilers as monitors,  Up: Profiling programs

3.4.3 Summary
-------------

   - An event is defined as the sending of a (public) message to an
     object.

   - There are two kinds of events: ‘before’ events, generated before a
     message is processed, and ‘after’ events, generated after the
     message processing has completed successfully.

   - Any object can be declared as a monitor to any event.  A monitor
     shall reference the ‘monitoring’ built-in protocol in the object
     opening directive.

   - A monitor defines event handlers, the predicates *note before/3:
     101. and *note after/3: 102, that are automatically called by the
     runtime engine when a spied event occurs.

   - Three built-in predicates, *note define_events/5: 218, *note
     current_event/5: 21e, and *note abolish_events/5: 21b, enables us
     to define, query, and abolish both events and monitors.


File: TheLogtalkHandbook-3.101.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.101.0.info,  Node: General,  Next: Compatibility,  Up: FAQ

4.1 General
===========

   * *note Why are all versions of Logtalk numbered 2.x or 3.x?: 858.

   * *note Why do I need a Prolog compiler to use Logtalk?: 859.

   * *note Is the Logtalk implementation based on Prolog modules?: 85a.

   * *note Does the Logtalk implementation use term-expansion?: 85b.

* 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.101.0.info,  Node: Why are all versions of Logtalk numbered 2 x or 3 x?,  Next: Why do I need a Prolog compiler to use Logtalk?,  Up: General

4.1.1 Why are all versions of Logtalk numbered 2.x or 3.x?
----------------------------------------------------------

The numbers “2” and “3” in the Logtalk version string refer to,
respectively, the second and the third generations of the Logtalk
language.  Development of Logtalk 2 started in January 1998, with the
first alpha release for registered users in July and the first public
beta on October.  The first stable version of Logtalk 2 was released in
February 9, 1999.  Development of Logtalk 3 started in April 2012, with
the first public alpha released in August 21, 2012.  The first stable
version of Logtalk 3 was released in January 7, 2015.


File: TheLogtalkHandbook-3.101.0.info,  Node: Why do I need a Prolog compiler to use Logtalk?,  Next: Is the Logtalk implementation based on Prolog modules?,  Prev: Why are all versions of Logtalk numbered 2 x or 3 x?,  Up: General

4.1.2 Why do I need a Prolog compiler to use Logtalk?
-----------------------------------------------------

Currently, the Logtalk language is implemented as a 'trans-compiler' to
Prolog instead of as a standalone compiler.  Compilation of Logtalk
source files is performed in two steps.  First, the Logtalk compiler
converts a source file to a Prolog file.  Second, the chosen Prolog
compiler is called by Logtalk to compile the intermediate Prolog file
generated on the first step.  The implementation of Logtalk as a
trans-compiler allows users to use Logtalk together with features only
available on specific Prolog compilers.


File: TheLogtalkHandbook-3.101.0.info,  Node: Is the Logtalk implementation based on Prolog modules?,  Next: Does the Logtalk implementation use term-expansion?,  Prev: Why do I need a Prolog compiler to use Logtalk?,  Up: General

4.1.3 Is the Logtalk implementation based on Prolog modules?
------------------------------------------------------------

No.  Logtalk is (currently) implemented in plain Prolog code.  Only a
few Prolog compilers include a module system, with several compatibility
problems between them.  Moreover, the current ISO Prolog standard for
modules is next to worthless and is ignored by most of the Prolog
community.  Nevertheless, the Logtalk compiler is able to compile simple
modules (using a common subset of module directives) as objects for
backward-compatibility with existing code (see the *note Prolog
integration and migration: 38a. for details).


File: TheLogtalkHandbook-3.101.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.101.0.info,  Node: Compatibility,  Next: Installation,  Prev: General,  Up: FAQ

4.2 Compatibility
=================

   * *note What are the backend Prolog compiler requirements to run
     Logtalk?: 863.

   * *note Can I use constraint-based packages with Logtalk?: 864.

   * *note Can I use Logtalk objects and Prolog modules at the same
     time?: 865.

* 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.101.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.101.0.info,  Node: Can I use constraint-based packages with Logtalk?,  Next: Can I use Logtalk objects and Prolog modules at the same time?,  Prev: What are the backend Prolog compiler requirements to run Logtalk?,  Up: Compatibility

4.2.2 Can I use constraint-based packages with Logtalk?
-------------------------------------------------------

Usually, yes.  Some constraint-based packages may define operators which
clash with the ones defined by Logtalk.  In these cases, compatibility
with Logtalk depends on the constraint-based packages providing an
alternative for accessing the functionality provided by those operators.
When the constraint solver is encapsulated using a Prolog module, a
possible workaround is to use either explicit module qualification or
encapsulate the call using the *note {}/1: 191. control construct (thus
bypassing the Logtalk compiler).


File: TheLogtalkHandbook-3.101.0.info,  Node: Can I use Logtalk objects and Prolog modules at the same time?,  Prev: Can I use constraint-based packages with Logtalk?,  Up: Compatibility

4.2.3 Can I use Logtalk objects and Prolog modules at the same time?
--------------------------------------------------------------------

Yes.  In order to call a module predicate from within an object (or
category) you may use an *note use_module/2: 4d. directive or use
explicit module qualification (possibly wrapping the call using the
Logtalk control construct *note {}/1: 191. that allows bypassing of the
Logtalk compiler when compiling a predicate call).  Logtalk also allows
modules to be compiled as objects (see the *note Prolog integration and
migration: 38a. for details).


File: TheLogtalkHandbook-3.101.0.info,  Node: Installation,  Next: Portability,  Prev: Compatibility,  Up: FAQ

4.3 Installation
================

   * *note The integration scripts/shortcuts are not working!: 86c.

   * *note I get errors when starting up Logtalk after upgrading to the
     latest version!: 86d.

* Menu:

* The integration scripts/shortcuts are not working!::
* I get errors when starting up Logtalk after upgrading to the latest version!::


File: TheLogtalkHandbook-3.101.0.info,  Node: The integration scripts/shortcuts are not working!,  Next: I get errors when starting up Logtalk after upgrading to the latest version!,  Up: Installation

4.3.1 The integration scripts/shortcuts are not working!
--------------------------------------------------------

Check that the ‘LOGTALKHOME’ and ‘LOGTALKUSER’ environment variables are
defined, that the Logtalk user folder is available in the location
pointed by ‘LOGTALKUSER’ (you can create this folder by running the
‘logtalk_user_setup’ shell script), and that the Prolog compilers that
you want to use are supported and available from the system path.  If
the problem persists, run the shell script that creates the integration
script or shortcut manually and check for any error message or
additional instructions.  For some Prolog compilers such as XSB and
Ciao, the first call of the integration script or shortcut must be made
by an administrator user.  If you are using Windows, make sure that any
anti-virus or other security software that you might have installed is
not silently blocking some of the installer tasks.


File: TheLogtalkHandbook-3.101.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.101.0.info,  Node: Portability,  Next: Programming,  Prev: Installation,  Up: FAQ

4.4 Portability
===============

   * *note Are my Logtalk applications portable across Prolog
     compilers?: 873.

   * *note Are my Logtalk applications portable across operating
     systems?: 874.

* Menu:

* Are my Logtalk applications portable across Prolog compilers?::
* Are my Logtalk applications portable across operating systems?::


File: TheLogtalkHandbook-3.101.0.info,  Node: Are my Logtalk applications portable across Prolog compilers?,  Next: Are my Logtalk applications portable across operating systems?,  Up: Portability

4.4.1 Are my Logtalk applications portable across Prolog compilers?
-------------------------------------------------------------------

Yes, as long you don’t use built-in predicates or special features only
available on some Prolog compilers.  There is a *note portability: 1d1.
compiler flag that you can set to instruct Logtalk to print a warning
for each occurrence of non-ISO Prolog standard features such as
proprietary built-in predicates.  In addition, it is advisable that you
constrain, if possible, the use of platform or compiler dependent code
to a small number of objects with clearly defined protocols.  You may
also use Logtalk support for conditional compilation to compile
different entity or predicate definitions depending on the backend
Prolog compiler being used.


File: TheLogtalkHandbook-3.101.0.info,  Node: Are my Logtalk applications portable across operating systems?,  Prev: Are my Logtalk applications portable across Prolog compilers?,  Up: Portability

4.4.2 Are my Logtalk applications portable across operating systems?
--------------------------------------------------------------------

Yes, as long you don’t use built-in predicates or special features that
your chosen backend Prolog compiler only supports on some
operating-systems.  You may need to change the end-of-line characters of
your source files to match the ones on the target operating system and
the expectations of your Prolog compiler.  Some Prolog compilers
silently fail to compile source files with the wrong end-of-line
characters.


File: TheLogtalkHandbook-3.101.0.info,  Node: Programming,  Next: Troubleshooting,  Prev: Portability,  Up: FAQ

4.5 Programming
===============

   * *note Should I use prototypes or classes in my application?: 87a.

   * *note Can I use both classes and prototypes in the same
     application?: 87b.

   * *note Can I mix classes and prototypes in the same hierarchy?: 87c.

   * *note Can I use a protocol or a category with both prototypes and
     classes?: 87d.

   * *note What support is provided in Logtalk for defining and using
     components?: 87e.

   * *note What support is provided in Logtalk for reflective
     programming?: 87f.

* 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.101.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.101.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.101.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.101.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.101.0.info,  Node: What support is provided in Logtalk for defining and using components?,  Next: What support is provided in Logtalk for reflective programming?,  Prev: Can I use a protocol or a category with both prototypes and classes?,  Up: Programming

4.5.5 What support is provided in Logtalk for defining and using components?
----------------------------------------------------------------------------

Logtalk supports component-based programming (since its inception on
January 1998), by using 'categories' (which are first-class entities
like objects and protocols).  Logtalk categories can be used with both
classes and prototypes and are inspired by the Smalltalk-80
(documentation-only) concept of method categories and by Objective-C
categories, hence the name.  For more information, please consult the
*note Categories: 109. section and the examples provided with the
distribution.


File: TheLogtalkHandbook-3.101.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.101.0.info,  Node: Troubleshooting,  Next: Usability,  Prev: Programming,  Up: FAQ

4.6 Troubleshooting
===================

   * *note Using compiler options on calls to the Logtalk compiling and
     loading predicates does not work!: 889.

   * *note Gecko-based browsers (e.g., Firefox) show non-rendered HTML
     entities when browsing XML documenting files!: 88a.

   * *note Compiling a source file results in errors or warnings but the
     Logtalk compiler reports a successful compilation with zero errors
     and zero warnings!: 88b.

* Menu:

* Using compiler options on calls to the Logtalk compiling and loading predicates does not work!::
* Gecko-based browsers (e.g., Firefox) show non-rendered HTML entities when browsing XML documenting files!: Gecko-based browsers e g Firefox show non-rendered HTML entities when browsing XML documenting files!.
* Compiling a source file results in errors or warnings but the Logtalk compiler reports a successful compilation with zero errors and zero warnings!::


File: TheLogtalkHandbook-3.101.0.info,  Node: Using compiler options on calls to the Logtalk compiling and loading predicates does not work!,  Next: Gecko-based browsers e g Firefox show non-rendered HTML entities when browsing XML documenting files!,  Up: Troubleshooting

4.6.1 Using compiler options on calls to the Logtalk compiling and loading predicates does not work!
----------------------------------------------------------------------------------------------------

Using compiler options on calls to the Logtalk *note logtalk_compile/2:
2b2. and *note logtalk_load/2: 4e. built-in predicates only apply to the
file being compiled.  If the first argument is a *note loader file: 4f,
the compiler options will only be used in the compilation of the loader
file itself, not in the compilation of the files loaded by the loader
file.  The solution is to edit the loader file and add the compiler
options to the calls that compile/load the individual files.


File: TheLogtalkHandbook-3.101.0.info,  Node: Gecko-based browsers e g Firefox show non-rendered HTML entities when browsing XML documenting files!,  Next: Compiling a source file results in errors or warnings but the Logtalk compiler reports a successful compilation with zero errors and zero warnings!,  Prev: Using compiler options on calls to the Logtalk compiling and loading predicates does not work!,  Up: Troubleshooting

4.6.2 Gecko-based browsers (e.g., Firefox) show non-rendered HTML entities when browsing XML documenting files!
---------------------------------------------------------------------------------------------------------------

Using Gecko-based browsers (e.g., Firefox) show non-rendered HTML
entities (e.g., ‘&ndash;’) when browsing XML documenting files after
running the ‘lgt2xml’ shell script in the directory containing the XML
documenting files.  This is a consequence of the lack of support for the
‘disable-output-escaping’ attribute in the browser XSLT processor.  The
workaround is to use another browser (e.g., Safari or Opera) or to use
instead the ‘lgt2html’ shell script in the directory containing the XML
documenting files to convert them to (X)HTML files for browsing.


File: TheLogtalkHandbook-3.101.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.101.0.info,  Node: Usability,  Next: Deployment,  Prev: Troubleshooting,  Up: FAQ

4.7 Usability
=============

   * *note Is there a shortcut for compiling and loading source files?:
     892.

   * *note Is there an equivalent directive to the ensure_loaded/1
     Prolog directive?: 893.

   * *note Are there shortcuts for the make functionality?: 894.

* 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.101.0.info,  Node: Is there a shortcut for compiling and loading source files?,  Next: Is there an equivalent directive to the ensure_loaded/1 Prolog directive?,  Up: Usability

4.7.1 Is there a shortcut for compiling and loading source files?
-----------------------------------------------------------------

Yes.  With most backend Prolog compilers, you can use ‘{File}’ as a
shortcut for ‘logtalk_load(File)’.  For compiling and loading multiple
files simply use ‘{File1, File2, ...}’.  See the documentation of the
*note logtalk_load/1: 46. predicate for details.


File: TheLogtalkHandbook-3.101.0.info,  Node: Is there an equivalent directive to the ensure_loaded/1 Prolog directive?,  Next: Are there shortcuts for the make functionality?,  Prev: Is there a shortcut for compiling and loading source files?,  Up: Usability

4.7.2 Is there an equivalent directive to the ‘ensure_loaded/1’ Prolog directive?
---------------------------------------------------------------------------------

You can use the goal ‘logtalk_load(File, [reload(skip)])’ to ensure that
‘File’ it is only loaded once.  See the documentation of the *note
logtalk_load/2: 4e. predicate for details.


File: TheLogtalkHandbook-3.101.0.info,  Node: Are there shortcuts for the make functionality?,  Prev: Is there an equivalent directive to the ensure_loaded/1 Prolog directive?,  Up: Usability

4.7.3 Are there shortcuts for the make functionality?
-----------------------------------------------------

Yes.  With most backend Prolog compilers, you can use ‘{*}’ as a
shortcut for ‘logtalk_make(all)’ to reload all files modified since last
compiled and loaded, ‘{!}’ as a shortcut for ‘logtalk_make(clean)’ to
delete all intermediate Prolog files generated by the compilation of
Logtalk source files, ‘{?}’ as a shortcut for ‘logtalk_make(missing)’ to
list missing entities and predicates, and ‘{@}’ as a shortcut for
‘logtalk_make(circular)’ to list circular references.  See the
documentation of the *note logtalk_make/1: 2a0. predicate for details.


File: TheLogtalkHandbook-3.101.0.info,  Node: Deployment,  Next: Performance<3>,  Prev: Usability,  Up: FAQ

4.8 Deployment
==============

   * *note Can I create standalone applications with Logtalk?: 89b.

* Menu:

* Can I create standalone applications with Logtalk?::


File: TheLogtalkHandbook-3.101.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.101.0.info,  Node: Performance<3>,  Next: Licensing,  Prev: Deployment,  Up: FAQ

4.9 Performance
===============

   * *note Is Logtalk implemented as a meta-interpreter?: 8a0.

   * *note What kind of code Logtalk generates when compiling objects?
     Dynamic code?  Static code?: 8a1.

   * *note How about message-sending performance?  Does Logtalk use
     static binding or dynamic binding?: 8a2.

   * *note How does Logtalk performance compare with plain Prolog and
     with Prolog modules?: 8a3.

* 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.101.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.101.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.101.0.info,  Node: How about message-sending performance? Does Logtalk use static binding or dynamic binding?,  Next: Which Prolog-dependent factors are most crucial for good Logtalk performance?,  Prev: What kind of code Logtalk generates when compiling objects? Dynamic code? Static code?,  Up: Performance<3>

4.9.3 How about message-sending performance? Does Logtalk use static binding or dynamic binding?
------------------------------------------------------------------------------------------------

Logtalk supports both static binding and dynamic binding.  When static
binding is not possible, Logtalk uses dynamic binding coupled with a
caching mechanism that avoids repeated lookups of predicate declarations
and predicate definitions.  This is a solution common to other
programming languages supporting dynamic binding.  Message lookups are
automatically cached the first time a message is sent.  Cache entries
are automatically removed when loading entities or using Logtalk dynamic
features that invalidate the cached lookups.  Whenever static binding is
used, message-sending performance is essentially the same as a predicate
call in plain Prolog.  Performance of dynamic binding when lookups are
cached is close to the performance that would be achieved with static
binding.  See the User Manual section on *note performance: 38. for more
details.


File: TheLogtalkHandbook-3.101.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.101.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.101.0.info,  Node: Licensing,  Next: Support,  Prev: Performance<3>,  Up: FAQ

4.10 Licensing
==============

   * *note What’s the Logtalk distribution license?: 8ac.

   * *note Can Logtalk be used in commercial applications?: 8ad.

   * *note What’s the final license for a combination of Logtalk with a
     Prolog compiler?: 8ae.

* 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.101.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.101.0.info,  Node: Can Logtalk be used in commercial applications?,  Next: What’s the final license for a combination of Logtalk with a Prolog compiler?,  Prev: What’s the Logtalk distribution license?,  Up: Licensing

4.10.2 Can Logtalk be used in commercial applications?
------------------------------------------------------

Yes, the Apache License 2.0 allows commercial use.  See e.g.  the Apache
License and Distribution FAQ(1).

   ---------- Footnotes ----------

   (1) https://www.apache.org/foundation/license-faq.html


File: TheLogtalkHandbook-3.101.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.101.0.info,  Node: Support,  Prev: Licensing,  Up: FAQ

4.11 Support
============

   * *note Are there professional consulting, training and supporting
     services?: 8b5.

* Menu:

* Are there professional consulting, training and supporting services?: Are there professional consulting training and supporting services?.


File: TheLogtalkHandbook-3.101.0.info,  Node: Are there professional consulting training and supporting services?,  Up: Support

4.11.1 Are there professional consulting, training and supporting services?
---------------------------------------------------------------------------

Yes.  Please visit logtalk.pt(1) for professional consulting,
development, training, and other support services.

   ---------- Footnotes ----------

   (1) https://logtalk.org


File: TheLogtalkHandbook-3.101.0.info,  Node: Developer Tools,  Next: Libraries,  Prev: FAQ,  Up: Top

5 Developer Tools
*****************

The documentation of each developer tool can also be found in the tool
directory in the ‘NOTES.md’ file.

* Menu:

* Overview::
* asdf::
* assertions::
* code_metrics::
* dead_code_scanner::
* debug_messages::
* debugger::
* diagrams::
* doclet::
* help::
* issue_creator::
* lgtdoc::
* lgtunit::
* linter::
* linter_reporter::
* make::
* mutation_testing::
* packs::
* ports_profiler::
* profiler::
* sarif::
* sbom::
* tool_diagnostics::
* tutor::
* wrapper::


File: TheLogtalkHandbook-3.101.0.info,  Node: Overview,  Next: asdf,  Up: Developer Tools

5.1 Overview
============

The following developer tools are available, each one with its own
‘loader.lgt’ loader file (except for the built-in ‘linter’ and ‘make’
tools, which are integrated with the compiler/runtime) and ‘NOTES.md’
documentation files:

   - ‘asdf’

   - ‘assertions’

   - ‘code_metrics’

   - ‘dead_code_scanner’

   - ‘debug_messages’

   - ‘debugger’

   - ‘diagrams’

   - ‘doclet’

   - ‘help’

   - ‘issue_creator’

   - ‘lgtdoc’

   - ‘lgtunit’

   - ‘linter’

   - ‘linter_reporter’

   - ‘make’

   - ‘mutation_testing’

   - ‘packs’

   - ‘ports_profiler’

   - ‘profiler’

   - ‘sarif’

   - ‘sbom’

   - ‘tool_diagnostics’

   - ‘tutor’

   - ‘wrapper’

* Menu:

* Loading the developer tools::
* Tools documentation::
* Tools common flags::
* Tools requirements::


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading the developer tools,  Next: Tools documentation,  Up: Overview

5.1.1 Loading the developer tools
---------------------------------

To load the main developer tools, use the following goal:

     | ?- logtalk_load(tools(loader)).

The ‘linter_reporter’ and ‘sarif’ tools are not loaded by default as
they are mostly useful for CI/CD pipelines.

The ‘ports_profiler’ tool is not loaded by default; however, as it
conflicts with the ‘debugger’ tool as both provide a debug handler that
must be unique in a running session.

The ‘profiler’ tool is also not loaded by default, as it provides
integration with selected backend Prolog compiler profilers that are not
portable.

The ‘tutor’ tool is also not loaded by default, given its usefulness
mainly for new users that need help understanding compiler warning and
error messages.

The ‘wrapper’ tool is also not loaded by default, given its specialized
purpose and beta status.

The ‘sbom’ tool is also not loaded by default, given its specialized
purpose.

To load a specific tool, either change your Prolog working directory to
the tool folder and then compile and load the corresponding loader
utility file or simply use library notation as argument for the
compiling and loading predicates.  For example:

     | ?- logtalk_load(lgtunit(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Tools documentation,  Next: Tools common flags,  Prev: Loading the developer tools,  Up: Overview

5.1.2 Tools documentation
-------------------------

Specific notes about each tool can be found in the corresponding
‘NOTES.md’ files.  HTML documentation for each tool API can be found in
the ‘docs’ directory (open the ‘../docs/handbook/index.html’ file with
your web browser).


File: TheLogtalkHandbook-3.101.0.info,  Node: Tools common flags,  Next: Tools requirements,  Prev: Tools documentation,  Up: Overview

5.1.3 Tools common flags
------------------------

The ‘lgtdoc’, ‘lgtunit’, and ‘issue_creator’ tools share a
‘suppress_path_prefix’ flag that can be used to suppress a prefix when
printing file paths.  For example (after loading the tools):

     | ?- set_logtalk_flag(suppress_path_prefix, '/home/jdoe/').

This flag is mainly used to avoid user specific path prefixes appearing
in documentation, test logs, and bug reports.


File: TheLogtalkHandbook-3.101.0.info,  Node: Tools requirements,  Prev: Tools common flags,  Up: Overview

5.1.4 Tools requirements
------------------------

Some of the developer tools have third-party dependencies.  For example,
the ‘lgtdoc’ tool depends on XSLT processors to generate documentation
final formats and uses Sphinx for the preferred HTML final format.  Be
sure to consult the tools documentation details on those requirements
and possible alternatives.  For convenience, follows a global list of
the main tool requirements and suggestions for installing them per
operating-system.  If your operating-system or a dependency for it is
not listed, see the dependency websites for installation instructions.

* Menu:

* Tool dependencies for full functionality::
* Python dependencies (all operating-systems): Python dependencies all operating-systems.
* macOS - MacPorts::
* macOS - Homebrew::
* Ubuntu::
* RedHat::
* Windows - Chocolatey::
* Installers::
* Windows - PowerShell add-ons::


File: TheLogtalkHandbook-3.101.0.info,  Node: Tool dependencies for full functionality,  Next: Python dependencies all operating-systems,  Up: Tools requirements

5.1.4.1 Tool dependencies for full functionality
................................................

   - ‘code_metric’: ‘cloc’, ‘sed’

   - ‘diagrams’: d2, Graphviz

   - ‘help’: ‘lynx’ ‘info’

   - ‘issue_creator’: ‘gh’, ‘glab’

   - ‘lgtdoc’: Sphinx, ‘libxslt’, ‘fop’, ‘texlive’, ‘texinfo’, ‘pandoc’,
     ‘xsltproc’

   - ‘lgtunit’: Allure, ‘coreutils’, ‘gsed’

   - ‘packs’: ‘coreutils’, ‘libarchive’, ‘gnupg2’, ‘git’, ‘curl’,
     ‘wget’, ‘direnv’


File: TheLogtalkHandbook-3.101.0.info,  Node: Python dependencies all operating-systems,  Next: macOS - MacPorts,  Prev: Tool dependencies for full functionality,  Up: Tools requirements

5.1.4.2 Python dependencies (all operating-systems)
...................................................

     $ pip install --upgrade pygments
     $ pip install --upgrade sphinx
     $ pip install --upgrade sphinx_rtd_theme

In alternative, if your want to use the same versions used to build
release documentation:

     $ cd manuals/sources
     $ python3 -m pip install -r requirements.txt


File: TheLogtalkHandbook-3.101.0.info,  Node: macOS - MacPorts,  Next: macOS - Homebrew,  Prev: Python dependencies all operating-systems,  Up: Tools requirements

5.1.4.3 macOS - MacPorts
........................

     $ sudo port install cloc
     $ sudo port install d2 graphviz
     $ sudo port install lynx texinfo pandoc
     $ sudo port install libxslt fop texlive
     $ sudo port install gsed
     $ sudo port install coreutils gsed libarchive gnupg2 git curl wget direnv
     $ sudo port install gh glab


File: TheLogtalkHandbook-3.101.0.info,  Node: macOS - Homebrew,  Next: Ubuntu,  Prev: macOS - MacPorts,  Up: Tools requirements

5.1.4.4 macOS - Homebrew
........................

     $ brew install cloc
     $ brew install d2 graphviz
     $ brew install lynx texinfo pandoc
     $ brew install libxslt fop texlive
     $ brew install allure gsed
     $ brew install coreutils libarchive gnupg2 git curl wget direnv
     $ brew install gh glab


File: TheLogtalkHandbook-3.101.0.info,  Node: Ubuntu,  Next: RedHat,  Prev: macOS - Homebrew,  Up: Tools requirements

5.1.4.5 Ubuntu
..............

     $ sudo apt install cloc
     $ sudo apt install graphviz
     $ sudo apt install lynx texinfo pandoc
     $ sudo apt install xsltproc fop texlive-latex-extra tex-gyre latexmk
     $ sudo apt install coreutils libarchive-tools gnupg2 git curl wget direnv
     $ sudo apt install gh


File: TheLogtalkHandbook-3.101.0.info,  Node: RedHat,  Next: Windows - Chocolatey,  Prev: Ubuntu,  Up: Tools requirements

5.1.4.6 RedHat
..............

     $ sudo dnf install cloc
     $ sudo dnf install graphviz
     $ sudo dnf install lynx texinfo pandoc
     $ sudo dnf install libxslt fop
     $ sudo dnf install bsdtar gnupg2 git curl wget direnv


File: TheLogtalkHandbook-3.101.0.info,  Node: Windows - Chocolatey,  Next: Installers,  Prev: RedHat,  Up: Tools requirements

5.1.4.7 Windows - Chocolatey
............................

     > choco install cloc sed
     > choco install pandoc xsltproc
     > choco install d2 graphviz
     > choco install xsltproc apache-fop texlive
     > choco install gnupg git
     > choco install gh glab
     > choco install wget


File: TheLogtalkHandbook-3.101.0.info,  Node: Installers,  Next: Windows - PowerShell add-ons,  Prev: Windows - Chocolatey,  Up: Tools requirements

5.1.4.8 Installers
..................

   - ‘https://d2lang.com/tour/install’

   - ‘https://www.graphviz.org/download/’

   - ‘https://allurereport.org/docs/’

   - ‘https://www.gnupg.org/’

   - ‘https://gitforwindows.org’

   - ‘https://cli.github.com’

   - ‘https://glab.readthedocs.io’

   - ‘https://eternallybored.org/misc/wget/’


File: TheLogtalkHandbook-3.101.0.info,  Node: Windows - PowerShell add-ons,  Prev: Installers,  Up: Tools requirements

5.1.4.9 Windows - PowerShell add-ons
....................................

     PS> Install-Module -Name Set-PsEnv


File: TheLogtalkHandbook-3.101.0.info,  Node: asdf,  Next: assertions,  Prev: Overview,  Up: Developer Tools

5.2 ‘asdf’
==========

A Logtalk plugin for the asdf(1) extendable version manager is available
at:

‘https://github.com/LogtalkDotOrg/asdf-logtalk’

This plugin provides an alternative to the ‘logtalk_version_select’
script that can be useful to manage Logtalk versions when developing
solutions that use other languages and tools that can also be handled by
‘asdf’.

   ---------- Footnotes ----------

   (1) https://asdf-vm.com


File: TheLogtalkHandbook-3.101.0.info,  Node: assertions,  Next: code_metrics,  Prev: asdf,  Up: Developer Tools

5.3 ‘assertions’
================

The ‘assertions.lgt’ file contains definitions for two meta-predicates,
‘assertion/1-2’, which allows the use of assertions on your source code
to print warning and error messages (using the message printing
mechanism).  The ‘assertions_messages.lgt’ file defines the default
message translations generated when assertions succeed, fail, or throw
an exception.

* Menu:

* API documentation::
* Loading::
* Testing::
* Adding assertions to your source code::
* Automatically adding file and line context information to assertions::
* Suppressing assertion calls from source code::
* Redirecting assertion failure messages::
* Converting assertion failures into errors::


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation,  Next: Loading,  Up: assertions

5.3.1 API documentation
-----------------------

This tool API documentation is available at:

‘../../apis/library_index.html#assertions’


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading,  Next: Testing,  Prev: API documentation,  Up: assertions

5.3.2 Loading
-------------

This tool can be loaded using the query:

     | ?- logtalk_load(assertions(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing,  Next: Adding assertions to your source code,  Prev: Loading,  Up: assertions

5.3.3 Testing
-------------

To test this tool, load the ‘tester.lgt’ file:

     | ?- logtalk_load(assertions(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Adding assertions to your source code,  Next: Automatically adding file and line context information to assertions,  Prev: Testing,  Up: assertions

5.3.4 Adding assertions to your source code
-------------------------------------------

The ‘assertion/1’ predicate takes a goal as argument.  For example:

     foo(L) :-
         assertions::assertion(non_empty_list(L)),
         ...

The ‘assertion/2’ predicate takes as arguments a term for passing
context information and a goal.  Using again a unit test as an example:

     foo(L) :-
         assertions::assertion(foo_list_alerts, non_empty_list(L)),
         ...

When using a large number of assertions, you can use a lighter syntax by
adding a ‘uses/2’ directive.  For example:

     :- uses(assertions, [assertion/1, assertion/2]).


File: TheLogtalkHandbook-3.101.0.info,  Node: Automatically adding file and line context information to assertions,  Next: Suppressing assertion calls from source code,  Prev: Adding assertions to your source code,  Up: assertions

5.3.5 Automatically adding file and line context information to assertions
--------------------------------------------------------------------------

The ‘assertions/1’ parametric object can be used as a hook object to
automatically add file and line context information, represented by the
term ‘file_lines(File, BeginLine-EndLine)’, to calls to the
‘assertion/1’ predicate by goal-expanding it to calls to the
‘assertion/2’ predicate (the expansion assumes that a ‘uses/2’ directive
is being used in the code that will be expanded to direct ‘assertion/1’
calls to the ‘assertions’ object).  For example, assuming the file using
assertions is named ‘source’, it would be compiled and loaded using the
call:

     logtalk_load(source, [hook(assertions(debug))])


File: TheLogtalkHandbook-3.101.0.info,  Node: Suppressing assertion calls from source code,  Next: Redirecting assertion failure messages,  Prev: Automatically adding file and line context information to assertions,  Up: assertions

5.3.6 Suppressing assertion calls from source code
--------------------------------------------------

The ‘assertions/1’ parametric object can be used as a hook object to
suppress calls to the ‘assertion/1-2’ predicates using goal-expansion
(the expansion assumes ‘assertions::assertion/1-2’ messages).  For
example, assuming the file using assertions is named ‘source’, it would
be compiled and loaded using the call:

     logtalk_load(source, [hook(assertions(production))])


File: TheLogtalkHandbook-3.101.0.info,  Node: Redirecting assertion failure messages,  Next: Converting assertion failures into errors,  Prev: Suppressing assertion calls from source code,  Up: assertions

5.3.7 Redirecting assertion failure messages
--------------------------------------------

By default, assertion failures and errors are printed to the standard
output stream.  These messages, however, can be intercepted by defining
the ‘logtalk::message_hook/4’ multifile predicate.  For example:

     :- category(redirect_assertions_messages).

         :- multifile(logtalk::message_hook/4).
         :- dynamic(logtalk::message_hook/4).

         logtalk::message_hook(Message, error, assertions, _) :-
             writeq(my_log_file, Message), write(my_log_file, '.\n').

     :- end_category.


File: TheLogtalkHandbook-3.101.0.info,  Node: Converting assertion failures into errors,  Prev: Redirecting assertion failure messages,  Up: assertions

5.3.8 Converting assertion failures into errors
-----------------------------------------------

If you want an assertion failure to result in a failure or a runtime
error, you can intercept the assertion failure messages, optionally
still printing them, and throw an error.  For example:

     :- category(assertions_failures_to_errors).

         :- multifile(logtalk::message_hook/4).
         :- dynamic(logtalk::message_hook/4).

         logtalk::message_hook(Message, error, assertions, Tokens) :-
             % uncomment the next two lines to also print the default message
             % logtalk::message_prefix_stream(error, assertions, Prefix, Stream),
             % logtalk::print_message_tokens(Stream, Prefix, Tokens),
             throw(error(Message, _)).

     :- end_category.

In alternative, if you want assertions to always trigger an exception,
use instead the ‘lgtunit’ tool ‘assertions/1-2’ public predicates.


File: TheLogtalkHandbook-3.101.0.info,  Node: code_metrics,  Next: dead_code_scanner,  Prev: assertions,  Up: Developer Tools

5.4 ‘code_metrics’
==================

The purpose of this tool is to assess qualities of source code that may
predict negative aspects such as entity coupling, cohesion, complexity,
error-proneness, and overall maintainability.  It is meant to be
extensible via the addition of objects implementing new metrics.

This tool provides predicates for computing metrics for source files,
entities, libraries, files, and directories.  The actual availability of
a particular predicate depends on the specific metric.  A set of
predicates prints, by default, the computed metric values to the
standard output.  A second set of predicates computes and returns a
score (usually a compound term with the computed metric values as
arguments).

* Menu:

* API documentation: API documentation<2>.
* Loading: Loading<2>.
* Testing: Testing<2>.
* Available metrics::
* Coupling metrics::
* Lack of cohesion metric::
* WMC metric::
* RFC metric::
* Cognitive complexity metric::
* Lines metric::
* Maintainability index metric::
* Halstead metric::
* UPN metric::
* Cyclomatic complexity metric::
* Usage::
* Excluding code from analysis::
* Defining new metrics::
* Third-party tools::
* Applying metrics to Prolog modules::
* Applying metrics to plain Prolog code::


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<2>,  Next: Loading<2>,  Up: code_metrics

5.4.1 API documentation
-----------------------

This tool API documentation is available at:

‘../../apis/library_index.html#code-metrics’


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<2>,  Next: Testing<2>,  Prev: API documentation<2>,  Up: code_metrics

5.4.2 Loading
-------------

This tool can be loaded using the query:

     | ?- logtalk_load(code_metrics(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<2>,  Next: Available metrics,  Prev: Loading<2>,  Up: code_metrics

5.4.3 Testing
-------------

To test this tool, load the ‘tester.lgt’ file:

     | ?- logtalk_load(code_metrics(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Available metrics,  Next: Coupling metrics,  Prev: Testing<2>,  Up: code_metrics

5.4.4 Available metrics
-----------------------

Currently, the following metrics are provided:

   - Number of Clauses (‘noc_metric’)

   - Number of Rules (‘nor_metric’)

   - Unique Predicate Nodes (‘upn_metric’)

   - Cyclomatic Complexity (‘cc_metric’)

   - Depth of Inheritance (‘dit_metric’)

   - Efferent coupling, afferent coupling, instability, and abstractness
     (‘coupling_metric’)

   - Lack of cohesion of methods (‘lcom_metric’)

   - Weighted Methods per Class (‘wmc_metric’)

   - Response For a Class (‘rfc_metric’)

   - Cognitive complexity (‘cogc_metric’)

   - Documentation (‘doc_metric’)

   - Lines of code, comments, and blanks (‘lines_metric’)

   - Source code size (‘size_metric’)

   - Maintainability index (‘mi_metric’ and ‘mi_metric(Stroud)’)

   - Halstead complexity (‘halstead_metric’ and
     ‘halstead_metric(Stroud)’)

A helper object, ‘code_metrics’, is also provided, allowing running all
loaded individual metrics.  For code coverage metrics, see the ‘lgtunit’
tool documentation.


File: TheLogtalkHandbook-3.101.0.info,  Node: Coupling metrics,  Next: Lack of cohesion metric,  Prev: Available metrics,  Up: code_metrics

5.4.5 Coupling metrics
----------------------

   - Efferent coupling (‘Ce’): Number of entities that an entity depends
     on.  These include objects receiving messages from the entity, plus
     the implemented protocols, imported categories, and
     extended/instantiated/specialized objects.

   - Afferent coupling (‘Ca’): Number of entities that depend on an
     entity.  For a protocol, the number of protocols that extend it,
     plus the number of objects and categories that implement it.  For a
     category, the number of objects that import it.  For an object, the
     number of categories and objects that send messages to it plus the
     number of objects that extend/instantiate/specialize it.

   - Instability: Computed as ‘Ce / (Ce + Ca)’.  Measures an entity
     resilience to change.  Ranging from 0.0 to 1.0, with 0.0 indicating
     a maximally stable entity and 1.0 indicating a maximally unstable
     entity.  Ideally, an entity is either maximally stable or maximally
     unstable.

   - Abstractness: Computed as the ratio between the number of static
     predicates with scope directives without a local definition and the
     number of static predicates with scope directives.  Measures the
     rigidity of an entity.  Ranging from 0.0 to 1.0, with 0.0
     indicating a fully concrete entity and 1.0 indicating a fully
     abstract entity.

   - Distance from main sequence: Computed as ‘abs(A + I - 1)’.
     Measures how far an entity is from the idealized line ‘A + I = 1’
     (the “main sequence”).  Ranging from 0.0 to 1.0, with 0.0
     indicating the entity sits exactly on the main sequence and 1.0
     indicating maximum deviation.  Entities in the “zone of pain” (A =~
     0, I =~ 0: concrete and stable) are difficult to change; entities
     in the “zone of uselessness” (A =~ 1, I =~ 1: abstract and
     unstable) are not used.  Ideally, entities should have a distance
     close to 0.0.

The dependencies count includes direct entity relations plus predicate
calls or dynamic updates to predicates in external objects or
categories.

For more information on the interpretation of the coupling metric
scores, see, e.g., the original paper by Robert Martin:

     @inproceedings{citeulike:1579528,
         author = "Martin, Robert",
         booktitle = "Workshop Pragmatic and Theoretical Directions in Object-Oriented Software Metrics",
         citeulike-article-id = 1579528,
         citeulike-linkout-0 = "http://www.objectmentor.com/resources/articles/oodmetrc.pdf",
         keywords = "diplomarbeit",
         organization = "OOPSLA'94",
         posted-at = "2007-08-21 11:08:44",
         priority = 0,
         title = "OO Design Quality Metrics - An Analysis of Dependencies",
         url = "http://www.objectmentor.com/resources/articles/oodmetrc.pdf",
         year = 1994
     }

The coupling metric was also influenced by the metrics rating system in
Microsoft Visual Studio and aims to eventually emulate the functionality
of a maintainability index score.


File: TheLogtalkHandbook-3.101.0.info,  Node: Lack of cohesion metric,  Next: WMC metric,  Prev: Coupling metrics,  Up: code_metrics

5.4.6 Lack of cohesion metric
-----------------------------

The lack of cohesion of methods (LCOM4) metric is computed as the number
of connected components in the undirected graph whose nodes are the
locally defined (non-auxiliary) predicates of an object or category and
whose edges represent direct internal calls between those predicates.
The metric is reported as the compound term ‘lcom(Components,
Predicates)’ where ‘Components’ is the number of connected components
and ‘Predicates’ is the total number of locally defined predicates.

An ‘lcom(1, N)’ score indicates a fully cohesive entity: all predicates
are reachable from any other predicate via internal calls.  Higher
‘Components’ values suggest the entity may benefit from being split into
separate, more focused entities.  Entities with no predicates or a
single predicate always score ‘lcom(1, N)’.

Protocols are not scored by this metric (they never define predicate
clauses).  Only direct bare-predicate calls (as reported by the Logtalk
reflection API) are counted as internal edges; external message-sends
(‘Object::Predicate’) are excluded.

For more details on the LCOM4 variant, see:

     @inproceedings{Hitz:1995,
         author = "Hitz, M. and Montazeri, B.",
         title = "Measuring Coupling and Cohesion in Object-Oriented Systems",
         booktitle = "Proceedings of the International Symposium on Applied Corporate Computing",
         year = 1995
     }


File: TheLogtalkHandbook-3.101.0.info,  Node: WMC metric,  Next: RFC metric,  Prev: Lack of cohesion metric,  Up: code_metrics

5.4.7 WMC metric
----------------

The Weighted Methods per Class (WMC) metric counts the number of locally
defined (non-auxiliary) predicates in an object or category.  Unit
weights are used: each predicate contributes 1 to the score regardless
of its complexity.  Protocols are not scored as they cannot define
predicates.

A cyclomatic-complexity-weighted variant is not provided.  The Logtalk
reflection API exposes inter-predicate call edges but not intra-clause
branching structure (if-then-else, disjunction).  A CC-weighted WMC
would inherit the same approximation limitations already present in
‘cc_metric’ and would also be numerically equivalent to the number of
user clauses reported by ‘noc_metric’.

For more details on the WMC metric, see the original CK paper:

     @article{Chidamber:1994,
         author = "Chidamber, S. R. and Kemerer, C. F.",
         title = "A Metrics Suite for Object Oriented Design",
         journal = "IEEE Transactions on Software Engineering",
         volume = 20,
         number = 6,
         pages = "476--493",
         year = 1994
     }


File: TheLogtalkHandbook-3.101.0.info,  Node: RFC metric,  Next: Cognitive complexity metric,  Prev: WMC metric,  Up: code_metrics

5.4.8 RFC metric
----------------

The Response For a Class (RFC) metric is computed as the size of the
response set for an object or category.  The response set RS(E) for an
entity E is the union of its locally defined (non-auxiliary) predicates
and all distinct predicates directly called or updated by those
predicates.  RFC = |RS(E)|.

Internal calls (to predicates within the entity) are included in the
response set but are not double-counted: they are already part of the
locally defined predicates.  Only additional external callees increase
the score beyond the WMC score of the same entity.

When the receiver of a message is only bound at runtime (e.g.
‘Obj::foo/1’ where ‘Obj’ is a variable), all such calls for the same
predicate indicator are counted as one callee entry, regardless of how
many distinct call sites exist.

Calls to built-in predicates are never returned by the Logtalk
reflection API and therefore do not contribute to the score.

Protocols are not scored as they cannot define predicates.

Higher RFC scores indicate entities with larger potential execution
footprints, which increases testing effort.

For more details on the RFC metric, see the original CK paper:

     @article{Chidamber:1994,
         author = "Chidamber, S. R. and Kemerer, C. F.",
         title = "A Metrics Suite for Object Oriented Design",
         journal = "IEEE Transactions on Software Engineering",
         volume = 20,
         number = 6,
         pages = "476--493",
         year = 1994
     }


File: TheLogtalkHandbook-3.101.0.info,  Node: Cognitive complexity metric,  Next: Lines metric,  Prev: RFC metric,  Up: code_metrics

5.4.9 Cognitive complexity metric
---------------------------------

The cognitive complexity (‘cogc_metric’) metric is an approximation of
the Cognitive Complexity metric proposed by Campbell (2018).  For each
non-auxiliary predicate, the score contribution is the number of extra
clauses (number of clauses minus one, representing multi-clause
branching choices) plus one if the predicate is directly recursive (i.e.
calls itself within the same entity).  The entity score is the sum of
all predicate contributions.

A score of 0 means all predicates are single-clause and non-recursive.
Higher scores indicate entities with more branching and recursion, which
typically require more effort to understand and test.

'Approximation note': the Logtalk reflection API does not expose the use
of control constructs such as cuts, if-then-else, disjunction, or
‘catch/3’ in the predicate clause bodies.  Thus, these constructs cannot
contribute to the score, which should be interpreted as a lower bound
for the cognitive complexity of the entity.

Protocols are not scored as they cannot define predicates.


File: TheLogtalkHandbook-3.101.0.info,  Node: Lines metric,  Next: Maintainability index metric,  Prev: Cognitive complexity metric,  Up: code_metrics

5.4.10 Lines metric
-------------------

The lines metric (‘lines_metric’) computes the number of code lines,
comment lines, and blank lines, represented as the compound term
‘lines(Code, Comments, Blanks)’.

The implementation calls the external ‘cloc’ tool and parses its CSV
report.  For entity scores, it first obtains the entity source line
range from the reflection API using the ‘lines(BeginLine, EndLine)’
property, writes only that range to a temporary file, and runs ‘cloc’ on
that temporary file.

For file, directory, and library scores, the metric computes and sums
per-file ‘lines/3’ scores.

This metric requires the ‘cloc’ and ‘sed’ commands to be available in
the operating system path.


File: TheLogtalkHandbook-3.101.0.info,  Node: Maintainability index metric,  Next: Halstead metric,  Prev: Lines metric,  Up: code_metrics

5.4.11 Maintainability index metric
-----------------------------------

The maintainability index metric (‘mi_metric’) computes the original
maintainability index formula:

‘MI = 171 - 5.2 * ln(V) - 0.23 * C - 16.2 * ln(L)’

where ‘V’ is the Halstead volume, ‘C’ is cyclomatic complexity, and ‘L’
is the number of code lines.  The score is represented as ‘mi(Index)’.

The metric is available as ‘mi_metric’ (default Stroud coefficient 18)
and as ‘mi_metric(Stroud)’ for a user-defined Stroud coefficient passed
to the Halstead metric.

Protocols are not scored as they cannot define predicates.

This metric requires the lines metric and thus the ‘cloc’ and ‘sed’
commands to be available in the operating system path.


File: TheLogtalkHandbook-3.101.0.info,  Node: Halstead metric,  Next: UPN metric,  Prev: Maintainability index metric,  Up: code_metrics

5.4.12 Halstead metric
----------------------

Predicates declared, user-defined, and called are interpreted as
'operators'.  Built-in predicates and built-in control constructs are
ignored.  Predicate arguments are abstracted, assumed distinct, and
interpreted as 'operands'.  Note that this definition of operands is a
significant deviation from the original definition, which used syntactic
literals.  A computation closer to the original definition of the metric
would require switching to use the parser to collect information on
syntactic literals, which would imply a much larger computation cost.
The number of predicate calls doesn’t include calls to built-in
predicates and can underestimate recursive calls.

The computation of this metric is parameterized by the 'Stroud'
coefficient for computing the time required to program (default is 18).
The following individual measures are computed:

   - Number of distinct predicates (declared, defined, called, or
     updated; ‘Pn’).

   - Number of predicate arguments (assumed distinct; ‘PAn’).

   - Number of predicate calls/updates + number of clauses (‘Cn’).

   - Number of predicate call/update arguments + number of clause head
     arguments (‘CAn’).

   - Entity vocabulary (‘EV’).  Computed as ‘EV = Pn + PAn’.

   - Entity length (‘EL’).  Computed as ‘EL = Cn + CAn’.

   - Volume (‘V’).  Computed as ‘V = EL * log2(EV)’.

   - Difficulty (‘D’).  Computed as ‘D = (Pn/2) * (CAn/An)’.

   - Effort (‘E’).  Computed as ‘E = D * V’.

   - Time required to program (‘T’).  Computed as ‘T = E/k’ seconds
     (where ‘k’ is the Stroud number; defaults to 18).

   - Number of delivered bugs (‘B’).  Computed as ‘B = V/3000’.


File: TheLogtalkHandbook-3.101.0.info,  Node: UPN metric,  Next: Cyclomatic complexity metric,  Prev: Halstead metric,  Up: code_metrics

5.4.13 UPN metric
-----------------

The Unique Predicate Nodes (UPN) metric is described in the following
paper:

     @article{MOORES199845,
         title = "Applying Complexity Measures to Rule-Based Prolog Programs",
         journal = "Journal of Systems and Software",
         volume = "44",
         number = "1",
         pages = "45 - 52",
         year = "1998",
         issn = "0164-1212",
         doi = "https://doi.org/10.1016/S0164-1212(98)10042-0",
         url = "http://www.sciencedirect.com/science/article/pii/S0164121298100420",
         author = "Trevor T Moores"
     }

The nodes include called and updated predicates independently of where
they are defined.  It also includes multifile predicates contributed to
other entities.


File: TheLogtalkHandbook-3.101.0.info,  Node: Cyclomatic complexity metric,  Next: Usage,  Prev: UPN metric,  Up: code_metrics

5.4.14 Cyclomatic complexity metric
-----------------------------------

The cyclomatic complexity metric evaluates an entity code complexity by
measuring the number of linearly independent paths through the code.  In
its current implementation, all defined predicates that are not called
or updated are counted as graph-connected components (the reasoning
being that these predicates can be considered entry points).  The
implementation uses the same predicate abstraction as the UPN metric.
The defined predicates include multifile predicate definitions
contributed by the entity to other entities.

For more details on this metric, see the original paper by Thomas J.
McCabe:

     @inproceedings{McCabe:1976:CM:800253.807712,
         author = "McCabe, Thomas J.",
         title = "A Complexity Measure",
         booktitle = "Proceedings of the 2Nd International Conference on Software Engineering",
         series = "ICSE '76",
         year = 1976,
         location = "San Francisco, California, USA",
         pages = "407--",
         url = "http://dl.acm.org/citation.cfm?id=800253.807712",
         acmid = 807712,
         publisher = "IEEE Computer Society Press",
         address = "Los Alamitos, CA, USA",
         keywords = "Basis, Complexity measure, Control flow, Decomposition, Graph theory, Independence, Linear, Modularization, Programming, Reduction, Software, Testing",
     }


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage,  Next: Excluding code from analysis,  Prev: Cyclomatic complexity metric,  Up: code_metrics

5.4.15 Usage
------------

All metrics require the source code to be analyzed to be loaded with the
‘source_data’ flag turned on.  For usage examples, see the ‘SCRIPT.txt’
file in the tool directory.

Be sure to fully understand the metrics individual meanings and any
implementation limitations before using them to support any evaluation
or decision process.


File: TheLogtalkHandbook-3.101.0.info,  Node: Excluding code from analysis,  Next: Defining new metrics,  Prev: Usage,  Up: code_metrics

5.4.16 Excluding code from analysis
-----------------------------------

A set of options is available to specify code that should be excluded
when applying code metrics:

   - 
          ‘exclude_directories(Directories)’
          list of directories to exclude (default is ‘[]’); all sub-directories of the excluded directories are also excluded; directories may be listed by full or relative path

   - 
          ‘exclude_files(Files)’
          list of source files to exclude (default is ‘[]’); files may be listed by full path or basename, with or without extension

   - 
          ‘exclude_libraries(Libraries)’
          list of libraries to exclude (default is ‘[startup, scratch_directory]’)

   - 
          ‘exclude_entities(Entities)’
          list of entities to exclude (default is ‘[]’)


File: TheLogtalkHandbook-3.101.0.info,  Node: Defining new metrics,  Next: Third-party tools,  Prev: Excluding code from analysis,  Up: code_metrics

5.4.17 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.101.0.info,  Node: Third-party tools,  Next: Applying metrics to Prolog modules,  Prev: Defining new metrics,  Up: code_metrics

5.4.18 Third-party tools
------------------------

The following open-source command-line programs can count blank lines,
comment lines, and lines of source code in many programming languages,
including Logtalk:

   - ‘cloc’ - ‘https://github.com/AlDanial/cloc’

   - ‘ohcount’ - ‘https://github.com/blackducksoftware/ohcount’

   - ‘tokei’ - ‘https://github.com/XAMPPRocky/tokei’


File: TheLogtalkHandbook-3.101.0.info,  Node: Applying metrics to Prolog modules,  Next: Applying metrics to plain Prolog code,  Prev: Third-party tools,  Up: code_metrics

5.4.19 Applying metrics to Prolog modules
-----------------------------------------

Some of the metrics can also be applied to Prolog modules that Logtalk
is able to compile as objects.  For example, if the Prolog module file
is named ‘module.pl’, try:

     | ?- logtalk_load(module, [source_data(on)]).

Due to the lack of standardization of module systems and the abundance
of proprietary extensions, this solution is not expected to work for all
cases.


File: TheLogtalkHandbook-3.101.0.info,  Node: Applying metrics to plain Prolog code,  Prev: Applying metrics to Prolog modules,  Up: code_metrics

5.4.20 Applying metrics to plain Prolog code
--------------------------------------------

Some of the metrics can also be applied to plain Prolog code.  For
example, if the Prolog file is named ‘code.pl’, simply define an object
including its code:

     :- object(code).
         :- include('code.pl').
     :- end_object.

Save the object to an e.g.  ‘code.lgt’ file in the same directory as the
Prolog file and then load it in debug mode:

     | ?- logtalk_load(code, [source_data(on)]).

In alternative, use the ‘object_wrapper_hook’ provided by the
‘hook_objects’ library:

     | ?- logtalk_load(hook_objects(loader)).
     ...

     | ?- logtalk_load(code, [hook(object_wrapper_hook), source_data(on)]).

With either wrapping solution, pay special attention to any compilation
warnings that may signal issues that could prevent the plain Prolog code
from working when wrapped by an object.


File: TheLogtalkHandbook-3.101.0.info,  Node: dead_code_scanner,  Next: debug_messages,  Prev: code_metrics,  Up: Developer Tools

5.5 ‘dead_code_scanner’
=======================

This tool detects 'likely' dead code in Logtalk entities and in Prolog
modules compiled as objects.  Predicates (and non-terminals) are
classified as dead code when:

   - There is no scope directive for them, and they are not called,
     directly or indirectly, by any predicate with a (local or
     inherited) scope directive.

   - They are listed in ‘uses/2’ and ‘use_module/2’ directives but not
     called.

Besides dead code, this tool can also help detect other problems in the
code that often result in reporting false positives.  For example, typos
in ‘alias/2’ directives, missing scope directives, and missing
‘meta_non_terminal/1’ and ‘meta_predicate/1’ directives.

Given the possibility of false positives, care must be taken before
deleting reported dead code to ensure that it’s, in fact, code that is
not used.  A common cause of false positives is the use of conditional
compilation directives to provide implementations for predicates missing
in some systems or different predicate implementations per
operating-system.

The ‘dead_code_scanner.lgt’ source file implements the scanning
predicates for finding dead code in entities, libraries, and
directories.  The source file ‘dead_code_scanner_messages.lgt’ defines
the default translations for the messages printed when scanning for dead
code.  These messages can be intercepted to customize the output, e.g.,
to make it less verbose or for integration with, e.g., GUI IDEs and
continuous integration servers.

* Menu:

* API documentation: API documentation<3>.
* Loading: Loading<3>.
* Testing: Testing<3>.
* Usage: Usage<2>.
* Excluding code from analysis: Excluding code from analysis<2>.
* Machine-readable summaries::
* Machine-readable preflight warnings::
* Finding classes and confidence::
* SARIF reports::
* Integration with the make tool::
* Caveats::
* Scanning Prolog modules::
* Scanning plain Prolog files::
* Known issues::


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<3>,  Next: Loading<3>,  Up: dead_code_scanner

5.5.1 API documentation
-----------------------

This tool API documentation is available at:

‘../../apis/library_index.html#dead-code-scanner’

For sample queries, please see the ‘SCRIPT.txt’ file in the tool
directory.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<3>,  Next: Testing<3>,  Prev: API documentation<3>,  Up: dead_code_scanner

5.5.2 Loading
-------------

This tool can be loaded using the query:

     | ?- logtalk_load(dead_code_scanner(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<3>,  Next: Usage<2>,  Prev: Loading<3>,  Up: dead_code_scanner

5.5.3 Testing
-------------

To test this tool, load the ‘tester.lgt’ file:

     | ?- logtalk_load(dead_code_scanner(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<2>,  Next: Excluding code from analysis<2>,  Prev: Testing<3>,  Up: dead_code_scanner

5.5.4 Usage
-----------

This tool provides a set of predicates that allows scanning entities,
libraries, files, and directories.  See the tool API documentation for
details.  The source code to be analyzed should be loaded with the
‘source_data’ and ‘optimize’ flags turned on (possibly set from a loader
file).

For machine-readable integrations, the ‘diagnostics/2-3’,
‘diagnostic/2-3’, ‘diagnostics_summary/2-3’, and
‘diagnostics_preflight/2-3’ predicates can be used to collect dead-code
results and post-filter counts without relying on printed messages.
Diagnostics are returned as terms of the form:

   - ‘diagnostic(RuleId, Severity, Confidence, Message, Context, File,
     Lines, Properties)’

where:

   - ‘RuleId’ distinguishes local dead code from unused ‘uses/2’ and
     ‘use_module/2’ resources

   - ‘Severity’ is the reported diagnostic severity (‘error’, ‘warning’,
     or ‘note’)

   - ‘Confidence’ is a triage-oriented rating (‘high’, ‘medium’, or
     ‘low’)

   - ‘Context’ identifies the entity kind and entity where the
     diagnostic was found

   - ‘Properties’ contains additional structured metadata, including the
     analysis settings seen for the source file and any class-specific
     details needed to explain the finding

For machine-readable export integrations, the ‘export/3-4’ predicates
serialize scan results in SARIF format using the ‘json’ library.

As an example, assume that we want to scan an application with a library
alias ‘my_app’.  The following goals could be used:

     | ?- set_logtalk_flag(source_data, on),
          set_logtalk_flag(optimize, on).
     yes

     | ?- logtalk_load(my_app(loader)).
     ...
     yes

     | ?- dead_code_scanner::library(my_app).
     ...

For complex applications that make use of sub-libraries, there are also
‘rlibrary/1-2’ predicates that perform a recursive scan of a library and
all its sub-libraries.  Conversely, we may be interested in scanning a
single entity:

     | ?- dead_code_scanner::entity(some_object).
     ...

For other usage examples, see the ‘SCRIPT.txt’ file in the tool
directory.


File: TheLogtalkHandbook-3.101.0.info,  Node: Excluding code from analysis<2>,  Next: Machine-readable summaries,  Prev: Usage<2>,  Up: dead_code_scanner

5.5.5 Excluding code from analysis
----------------------------------

A set of options is available to specify code that should be excluded
when looking for unused predicates (and non-terminals):

   - 
          ‘exclude_directories(Directories)’
          list of directories to exclude (default is ‘[]’); all sub-directories of the excluded directories are also excluded; directories may be listed by full or relative path

   - 
          ‘exclude_files(Files)’
          list of source files to exclude (default is ‘[]’); files may be listed by full path or basename, with or without extension

   - 
          ‘exclude_libraries(Libraries)’
          list of libraries to exclude (default is ‘[startup, scratch_directory]’)

   - 
          ‘exclude_entities(Entities)’
          list of entities to exclude (default is ‘[]’)

   - 
          ‘exclude_predicates(Predicates)’
          list of predicate and non-terminal indicators to exclude from findings (default is ‘[]’); supports local indicators such as ‘foo/1’ and ‘bar//2’ plus qualified indicators such as ‘object::baz/2’ and ‘module:qux/3’

   - 
          ‘waive_findings(Findings)’
          list of finding patterns to suppress from the results (default is ‘[]’); intended for reusable CI baselines and supports partially instantiated structured finding terms such as ‘dead_predicate(local_dead_code, medium, _, object, some_object, helper/2, _, _)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Machine-readable summaries,  Next: Machine-readable preflight warnings,  Prev: Excluding code from analysis<2>,  Up: dead_code_scanner

5.5.6 Machine-readable summaries
--------------------------------

The ‘diagnostics_summary/2-3’ predicates return a term of the form:

   - ‘diagnostics_summary(Target, TotalContexts, TotalDiagnostics,
     Breakdown, ContextSummaries)’

where ‘Breakdown’ is a term of the form:

   - ‘diagnostic_breakdown(RuleCounts, SeverityCounts,
     ConfidenceCounts)’

with ‘RuleCounts’ containing ‘rule_count(RuleId, Count)’ terms,
‘SeverityCounts’ containing ‘severity_count(Severity, Count)’ terms, and
‘ConfidenceCounts’ containing ‘confidence_count(Confidence, Count)’
terms.

‘ContextSummaries’ is a list of terms of the form:

   - ‘context_summary(Context, DiagnosticsCount, Breakdown)’

The summary is computed after applying all exclusions and finding
waivers, making it suitable for CI thresholds and regression tracking.


File: TheLogtalkHandbook-3.101.0.info,  Node: Machine-readable preflight warnings,  Next: Finding classes and confidence,  Prev: Machine-readable summaries,  Up: dead_code_scanner

5.5.7 Machine-readable preflight warnings
-----------------------------------------

The ‘diagnostics_preflight/2-3’ predicates return an ordered set of
warnings describing analysis prerequisites that affect result quality
for a target.  Warning terms currently use the form:

   - ‘preflight_issue(missing_analysis_prerequisite, Severity, Message,
     Context, File, Lines, Properties)’

where ‘Prerequisite’ is currently one of:

   - ‘source_data’

   - ‘optimize’

This API is intended for CI and editor integrations that need to surface
analysis quality issues without scraping console messages.


File: TheLogtalkHandbook-3.101.0.info,  Node: Finding classes and confidence,  Next: SARIF reports,  Prev: Machine-readable preflight warnings,  Up: dead_code_scanner

5.5.8 Finding classes and confidence
------------------------------------

The current finding classes are:

   - ‘local_dead_code’

   - ‘unused_uses_resource’

   - ‘unused_use_module_resource’

Confidence is a triage-oriented rating attached to every finding.  The
JSON schema allows the values ‘high’, ‘medium’, and ‘low’, but the tool
currently emits only ‘high’ and ‘medium’:

   - ‘high’

     Used when the tool has stronger evidence that the reported code is
     really unused.

   - ‘medium’

     Used when the result is still useful, but can be affected by
     missing compilation information such as optimized call graph data.

   - ‘low’

     Reserved for future use.  It is accepted by the export schema but
     is not currently generated by the scanner.

For ‘local_dead_code’, the confidence depends on the effective
compilation mode of the analyzed file:

   - If the file was loaded in normal mode, or otherwise not loaded with
     ‘optimize(on)’, the confidence is ‘medium’.

   - If the file was loaded with ‘optimize(on)’, the confidence is
     upgraded to ‘high’ because the compiler can provide more complete
     call graph information, reducing the risk of false positives caused
     by missed meta-calls.

The effective mode is inferred from the loaded file itself, not from the
current scanner defaults.  Therefore, results reflect how the analyzed
code was actually compiled.

Unused ‘uses/2’ and ‘use_module/2’ resources are always reported with
‘high’ confidence because they are derived from the generated linking
clauses and the recorded call graph rather than from heuristic
reachability alone.

When scanning using the text-based predicates such as ‘entity/1-2’,
‘file/1-2’, and ‘all/0-1’, the tool now emits preflight warnings
whenever the analyzed files were not loaded with ‘source_data(on)’ or
‘optimize(on)’ so that potentially less reliable results can be triaged
more carefully.


File: TheLogtalkHandbook-3.101.0.info,  Node: SARIF reports,  Next: Integration with the make tool,  Prev: Finding classes and confidence,  Up: dead_code_scanner

5.5.9 SARIF reports
-------------------

This tool is a diagnostics producer.  To generate SARIF reports from its
diagnostics, load the standalone ‘sarif’ tool and call
‘sarif::generate(dead_code_scanner, Target, Sink, Options)’ where
‘Target’ and ‘Options’ are the same ones accepted by the diagnostics
predicates.

The generated report uses the SARIF ‘2.1.0’ JSON format and is suitable
for code scanning integrations that consume SARIF reports.  The shared
generator includes deterministic result fingerprints derived from the
canonical finding and preserves the rule descriptors and triage-oriented
severity mapping described below.

SARIF findings are exported using one rule descriptor per finding class:

   - ‘local_dead_code’

   - ‘unused_uses_resource’

   - ‘unused_use_module_resource’

Result severities are also triage-aware instead of using a single static
SARIF level for all findings:

   - ‘local_dead_code’ with ‘high’ confidence is exported as ‘warning’

   - ‘local_dead_code’ with ‘medium’ or ‘low’ confidence is exported as
     ‘note’

   - ‘unused_uses_resource’ with ‘high’ confidence is exported as
     ‘error’

   - ‘unused_use_module_resource’ with ‘high’ confidence is exported as
     ‘error’

This mapping allows CI consumers to distinguish advisory dead-code
findings from stronger unused-resource findings without reinterpreting
the custom ‘class’ and ‘confidence’ properties.

SARIF reports include the same preflight information as invocation-level
‘toolExecutionNotifications’, allowing consumers to distinguish
prerequisite warnings from dead code findings.  When the analyzed code
is inside a git repository, the shared generator also includes the
current branch and commit hash as optional run properties and a
‘versionControlProvenance’ entry when the repository URI can be derived.


File: TheLogtalkHandbook-3.101.0.info,  Node: Integration with the make tool,  Next: Caveats,  Prev: SARIF reports,  Up: dead_code_scanner

5.5.10 Integration with the ‘make’ tool
---------------------------------------

The ‘loader.lgt’ file sets a make target action that will call the
‘dead_code_scanner::all’ goal whenever the ‘logtalk_make(check)’ goal
(or its top-level abbreviation, ‘{?}’) is called.


File: TheLogtalkHandbook-3.101.0.info,  Node: Caveats,  Next: Scanning Prolog modules,  Prev: Integration with the make tool,  Up: dead_code_scanner

5.5.11 Caveats
--------------

Use of local meta-calls with goal arguments only known at runtime can
result in false positives.  When using library or user-defined
meta-predicates, compilation of the source files with the ‘optimize’
flag turned on may allow meta-calls to be resolved at compile-time and
thus allow calling information for the meta-arguments to be recorded,
avoiding false positives for predicates that are only meta-called.


File: TheLogtalkHandbook-3.101.0.info,  Node: Scanning Prolog modules,  Next: Scanning plain Prolog files,  Prev: Caveats,  Up: dead_code_scanner

5.5.12 Scanning Prolog modules
------------------------------

This tool can also be applied to Prolog modules that Logtalk is able to
compile as objects.  For example, if the Prolog module file is named
‘module.pl’, try:

     | ?- logtalk_load(module, [source_data(on)]).

Due to the lack of standardization of module systems and the abundance
of proprietary extensions, this solution is not expected to work for all
cases.


File: TheLogtalkHandbook-3.101.0.info,  Node: Scanning plain Prolog files,  Next: Known issues,  Prev: Scanning Prolog modules,  Up: dead_code_scanner

5.5.13 Scanning plain Prolog files
----------------------------------

This tool can also be applied to plain Prolog code.  For example, if the
Prolog file is named ‘code.pl’, simply define an object including its
code:

     :- object(code).
         :- include('code.pl').
     :- end_object.

Save the object to an e.g.  ‘code.lgt’ file in the same directory as the
Prolog file and then load it in debug mode:

     | ?- logtalk_load(code, [source_data(on), optimize(on)]).

In alternative, use the ‘object_wrapper_hook’ provided by the
‘hook_objects’ library:

     | ?- logtalk_load(hook_objects(loader)).
     ...

     | ?- logtalk_load(code, [hook(object_wrapper_hook), source_data(on), optimize(on)]).

With either wrapping solution, pay special attention to any compilation
warnings that may signal issues that could prevent the plain Prolog from
being fully analyzed when wrapped by an object.


File: TheLogtalkHandbook-3.101.0.info,  Node: Known issues,  Prev: Scanning plain Prolog files,  Up: dead_code_scanner

5.5.14 Known issues
-------------------

Some tests fail when using the ECLIPSe and Trealla Prolog backends due
to their implementation of the ‘multifile/1’ directive, specifically
when the multifile predicates are also dynamic with clauses defined in a
source file: reconsulting the file adds the new clauses to the old ones
instead of replacing them.


File: TheLogtalkHandbook-3.101.0.info,  Node: debug_messages,  Next: debugger,  Prev: dead_code_scanner,  Up: Developer Tools

5.6 ‘debug_messages’
====================

By default, ‘debug’ and ‘debug(Group)’ messages are only printed when
the ‘debug’ flag is turned on.  These messages are also suppressed when
compiling code with the ‘optimize’ flag turned on.  This tool supports
selective enabling of ‘debug’ and ‘debug(Group)’ messages in normal and
debug modes.

* Menu:

* API documentation: API documentation<4>.
* Loading: Loading<4>.
* Testing: Testing<4>.
* Usage: Usage<3>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<4>,  Next: Loading<4>,  Up: debug_messages

5.6.1 API documentation
-----------------------

This tool API documentation is available at:

‘../../apis/library_index.html#debug-messages’

For general information on debugging, open in a web browser the
following link and consult the debugging section of the User Manual:

‘../../handbook/userman/debugging.html’


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<4>,  Next: Testing<4>,  Prev: API documentation<4>,  Up: debug_messages

5.6.2 Loading
-------------

This tool can be loaded using the query:

     | ?- logtalk_load(debug_messages(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<4>,  Next: Usage<3>,  Prev: Loading<4>,  Up: debug_messages

5.6.3 Testing
-------------

To test this tool, load the ‘tester.lgt’ file:

     | ?- logtalk_load(debug_messages(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<3>,  Prev: Testing<4>,  Up: debug_messages

5.6.4 Usage
-----------

The tool provides two sets of predicates.  The first set allows enabling
and disabling of all ‘debug’ and ‘debug(Group)’ messages for a given
component.  The second set allows enabling and disabling of
‘debug(Group)’ messages for a given group and component for fine-grained
control.

Upon loading the tool, all debug messages are skipped.  The user is then
expected to use the tool API to selectively enable the messages that
will be printed.  As an example, consider the following object, part of
a ‘xyz’ component:

     :- object(foo).

         :- public([bar/0, baz/0]).
         :- uses(logtalk, [print_message/3]).

         bar :-
             print_message(debug(bar), xyz, @'bar/0 called').

         baz :-
             print_message(debug(baz), xyz, @'baz/0 called').

     :- end_object.

Assuming the object ‘foo’ is compiled and loaded in normal or debug
mode, after also loading this tool, ‘bar/0’ and ‘baz/0’ messages will
not print any debug messages:

     | ?- {debug_messages(loader), foo}.
     ...
     yes

     | ?- foo::(bar, baz).
     yes

We can then enable all debug messages for the ‘xyz’ component:

     | ?- debug_messages::enable(xyx).
     yes

     | ?- foo::(bar, baz).
     bar/0 called
     baz/0 called
     yes

Or we can selectively enable only debug messages for a specific group:

     | ?- debug_messages::disable(xyx).
     yes

     | ?- debug_messages::enable(xyx, bar).
     yes

     | ?- foo::(bar, baz).
     bar/0 called
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: debugger,  Next: diagrams,  Prev: debug_messages,  Up: Developer Tools

5.7 ‘debugger’
==============

This tool provides the default Logtalk command-line debugger.  Unlike
Prolog systems, the Logtalk debugger is a regular application, using a
public API. As a consequence, it must be explicitly loaded by the
programmer, either manually at the top-level interpreter or
automatically from a settings file.

* Menu:

* API documentation: API documentation<5>.
* Loading: Loading<5>.
* Testing: Testing<5>.
* Usage: Usage<4>.
* Alternative debugger tools::
* Known issues: Known issues<2>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<5>,  Next: Loading<5>,  Up: debugger

5.7.1 API documentation
-----------------------

This tool API documentation is available at:

‘../../apis/library_index.html#debugger’


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<5>,  Next: Testing<5>,  Prev: API documentation<5>,  Up: debugger

5.7.2 Loading
-------------

This tool can be loaded using the query:

     | ?- logtalk_load(debugger(loader)).

When the code to be debugged runs computationally expensive
initializations, loading this tool after the code may have a noticeable
impact on loading times.


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<5>,  Next: Usage<4>,  Prev: Loading<5>,  Up: debugger

5.7.3 Testing
-------------

To test this tool, load the ‘tester.lgt’ file:

     | ?- logtalk_load(debugger(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<4>,  Next: Alternative debugger tools,  Prev: Testing<5>,  Up: debugger

5.7.4 Usage
-----------

Debugging Logtalk source code (with this debugger) requires compiling
source files using the ‘debug(on)’ compiler flag.  For example:

     | ?- logtalk_load(my_buggy_code, [debug(on)]).

In alternative, you may also turn on the ‘debug’ flag globally by
typing:

     | ?- set_logtalk_flag(debug, on).

But note that loader files may override this flag setting (e.g., by
using ‘debug(off)’ or ‘optimize(on)’ options for loaded files).  If
that’s the case, you will need to either edit the loader files or write
customized loader files enabling debugging.  For detailed information on
using the debugger, consult the debugging section of the User Manual:

‘../../handbook/userman/debugging.html’

The ‘debugger_messages.lgt’ source file defines the default debugger
message translations.

The ‘dump_trace.lgt’ provides a simple solution for dumping a goal trace
to a file.  For example:

     | ?- dump_trace::start_redirect_to_file('trace.txt', some_goal),
          dump_trace::stop_redirect_to_file.

A full trace can also be obtained at the top-level by using the ‘S’
(Skip) command at the call port for the top-level goal when tracing it.


File: TheLogtalkHandbook-3.101.0.info,  Node: Alternative debugger tools,  Next: Known issues<2>,  Prev: Usage<4>,  Up: debugger

5.7.5 Alternative debugger tools
--------------------------------

Logtalk provides basic support for the SWI-Prolog graphical tracer.  The
'required' settings are described in the ‘samples/settings-sample.lgt’
file.  Logtalk queries can be traced using this tool by using the
‘gtrace/0-1’ predicates.  For example:

     | ?- gtrace(foo::bar).

Or alternatively:

     | ?- gtrace, foo::bar.

You can also use the ‘gspy/1’ predicate to spy on a Logtalk predicate
specified as ‘Entity::Functor/Arity’ when using the graphical tracer.
When using this tool, internal Logtalk compiler/runtime predicates and
compiled predicates that resulted from the term-expansion mechanism may
be exposed in some cases.  This issue is shared with Prolog code and
results from the non-availability of source code for the predicates
being traced.


File: TheLogtalkHandbook-3.101.0.info,  Node: Known issues<2>,  Prev: Alternative debugger tools,  Up: debugger

5.7.6 Known issues
------------------

Clause breakpoints require a Prolog backend compiler that supports
accessing read term starting line but only some backends (B-Prolog, GNU
Prolog, JIProlog, SICStus Prolog, SWI-Prolog, Trealla Prolog, XVM, and
YAP) provide accurate line numbers.  As a workaround, you can check the
start line number for an entity predicate definition using a query such
as:

     | ?- object_property(Entity, defines(Functor/Arity, Properties)).

Check the returned ‘line_count/1’ property to find if there’s any offset
to the source file number of the predicate clause that you want to
trace.  This issue, if present, usually only affects the first predicate
clause.

Clause breakpoints are currently not available when using XSB as this
backend doesn’t provide line information.

Using the port command ‘p’ (print) requires a backend supporting the
user-defined ‘portray/1’ hook predicate called via the ‘format/2-3’
predicates ‘~p’ control sequence.


File: TheLogtalkHandbook-3.101.0.info,  Node: diagrams,  Next: doclet,  Prev: debugger,  Up: Developer Tools

5.8 ‘diagrams’
==============

This tool generates 'library', 'directory', 'file', 'entity', and
'predicate' diagrams for source files and for libraries of source files
using the Logtalk reflection API to collect the relevant information and
a graph language for representing the diagrams.  Limited support is also
available for generating diagrams for Prolog module applications.  It’s
also possible in general to generate predicate cross-referencing
diagrams for plain Prolog files.

Linking 'library diagrams' to 'entity diagrams' to 'predicate
cross-referencing diagrams' and linking 'directory diagrams' to 'file
diagrams' is also supported when using SVG output.  This feature allows
using diagrams for understanding the architecture of applications by
navigating complex code and zooming into details.  SVG output can also
easily link to both source code repositories and API documentation.
This allows diagrams to be used for source code navigation.

Diagrams can also be used to uncover code issues.  For example,
comparing 'loading diagrams' with 'dependency diagrams' can reveal
implicit dependencies.  Loading diagrams can reveal circular
dependencies that may warrant code refactoring.  Entity diagrams can
provide a good overview of code coupling.  Predicate cross-referencing
diagrams can be used to visually access entity code complexity,
complementing the ‘code_metrics’ tool.

All diagrams support a comprehensive set of options, discussed below, to
customize the final contents and appearance.

Diagram generation can be easily automated using the ‘doclet’ tool and
the ‘logtalk_doclet’ scripts.  See the ‘doclet’ tool examples and
documentation for details.  See also the ‘diagrams’ tool own ‘lgt2svg’
Bash and PowerShell scripts.

* Menu:

* Requirements::
* API documentation: API documentation<6>.
* Loading: Loading<6>.
* Testing: Testing<6>.
* Supported diagrams::
* Graph elements::
* Supported graph languages::
* Customization::
* Linking diagrams::
* Creating diagrams for Prolog module applications::
* Creating diagrams for plain Prolog files::
* Other notes::


File: TheLogtalkHandbook-3.101.0.info,  Node: Requirements,  Next: API documentation<6>,  Up: diagrams

5.8.1 Requirements
------------------

Recent versions of d2 (0.6.9 or later) or Graphviz are required for
generating diagrams in the final formats:

   - ‘https://d2lang.com’

   - ‘https://www.graphviz.org/’

These can be installed using their own installers or using
operating-system package managers:

* Menu:

* macOS - MacPorts: macOS - MacPorts<2>.
* macOS - Homebrew: macOS - Homebrew<2>.
* Windows - Chocolatey: Windows - Chocolatey<2>.
* Installers: Installers<2>.


File: TheLogtalkHandbook-3.101.0.info,  Node: macOS - MacPorts<2>,  Next: macOS - Homebrew<2>,  Up: Requirements

5.8.1.1 macOS - MacPorts
........................

     $ sudo port install d2 graphviz


File: TheLogtalkHandbook-3.101.0.info,  Node: macOS - Homebrew<2>,  Next: Windows - Chocolatey<2>,  Prev: macOS - MacPorts<2>,  Up: Requirements

5.8.1.2 macOS - Homebrew
........................

     $ brew install d2 graphviz


File: TheLogtalkHandbook-3.101.0.info,  Node: Windows - Chocolatey<2>,  Next: Installers<2>,  Prev: macOS - Homebrew<2>,  Up: Requirements

5.8.1.3 Windows - Chocolatey
............................

     > choco install d2 graphviz


File: TheLogtalkHandbook-3.101.0.info,  Node: Installers<2>,  Prev: Windows - Chocolatey<2>,  Up: Requirements

5.8.1.4 Installers
..................

   - ‘https://d2lang.com/tour/install’

   - ‘https://www.graphviz.org/download/’


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<6>,  Next: Loading<6>,  Prev: Requirements,  Up: diagrams

5.8.2 API documentation
-----------------------

This tool API documentation is available at:

‘../../apis/library_index.html#diagrams’

For sample queries, please see the ‘SCRIPT.txt’ file in the tool
directory.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<6>,  Next: Testing<6>,  Prev: API documentation<6>,  Up: diagrams

5.8.3 Loading
-------------

This tool can be loaded using the query:

     | ?- logtalk_load(diagrams(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<6>,  Next: Supported diagrams,  Prev: Loading<6>,  Up: diagrams

5.8.4 Testing
-------------

To test this tool, load the ‘tester.lgt’ file:

     | ?- logtalk_load(diagrams(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Supported diagrams,  Next: Graph elements,  Prev: Testing<6>,  Up: diagrams

5.8.5 Supported diagrams
------------------------

The following entity diagrams are supported:

   - 'entity diagrams' showing entity public interfaces, entity
     inheritance relations, and entity predicate (or non-terminal)
     cross-reference relations

   - 'predicate/non-terminal cross-reference diagrams' (between entities
     or within an entity)

   - 'caller diagrams' showing direct and indirect callers of a given
     predicate (or non-terminal)

   - 'inheritance diagrams' showing entity inheritance relations

   - 'uses diagrams' showing which entities use resources from other
     entities

Entity nodes can optionally show a coupling metrics overlay.

The following library diagrams are supported:

   - 'library loading diagrams' showing which libraries load other
     libraries

   - 'library dependency diagrams' showing which libraries contain
     entities with references to entities defined in other libraries

The following file diagrams are supported:

   - 'file loading diagrams' showing which files load or include other
     files

   - 'file dependency diagrams' showing which files contain entities
     with references to entities defined in other files

File dependency diagrams are specially useful in revealing dependencies
that are not represented in file loading diagrams due to files being
loaded indirectly by files external to the libraries being documented.

The following directory diagrams are supported:

   - 'directory loading diagrams' showing which directories contain
     files that load files from other directories

   - 'directory dependency diagrams' showing which directories contain
     entities with references to entities defined in other directories

Comparing directory (or file) loading diagrams with directory (or file)
dependency diagrams allows comparing what is explicitly loaded with the
actual directory (or file) dependencies, which are inferred from the
source code.

Library and directory dependency diagrams are specially useful for large
applications where file diagrams would be too large and complex to be
useful, notably when combined with the 'zoom' option to link to,
respectively, entity and file diagrams.

A utility object, ‘diagrams’, is provided for generating all supported
diagrams in one step.  This object provides an interface common to all
diagrams, but note that some predicates that generate diagrams only make
sense for some types of diagrams.  For best results and fine-grained
customization of each diagram, the individual diagram objects should be
used with the intended set of options.


File: TheLogtalkHandbook-3.101.0.info,  Node: Graph elements,  Next: Supported graph languages,  Prev: Supported diagrams,  Up: diagrams

5.8.6 Graph elements
--------------------

Limitations in both the graph languages and UML force the invention of a
modeling language that can represent all kinds of Logtalk entities and
entity relations.  Currently we use the following Graphviz node shapes
(libraries, entities, predicates, and files) and arrowheads (entity,
predicate, and file relations):

   - 
          libraries
          ‘tab’ (lightsalmon)

   - 
          library loading and dependency relations
          ‘normal’ (arrow ending with a black triangle)

   - 
          objects (classes, instances, and prototypes)
          ‘box’ (rectangle, yellow for instances/classes and beige for prototypes)

   - 
          protocols
          ‘note’ (aqua marine rectangle with folded right-upper corners)

   - 
          categories
          ‘component’ (light cyan rectangle with two small rectangles intercepting the left side)

   - 
          modules
          ‘box’ (plum rectangle with small tab at top)

   - 
          public predicates
          ‘box’ (springgreen)

   - 
          public, multifile, predicates
          ‘box’ (skyblue)

   - 
          protected predicates
          ‘box’ (yellow)

   - 
          private predicates
          ‘box’ (indianred)

   - 
          external predicates
          ‘box’ (beige)

   - 
          exported module predicates
          ‘box’ (springgreen)

   - 
          directories
          ‘tab’ (lightsalmon)

   - 
          directory loading and dependency relations
          ‘normal’ (arrow ending with a black triangle)

   - 
          files
          ‘box’ (pale turquoise rectangle)

   - 
          file loading and dependency relations
          ‘normal’ (arrow ending with a black triangle)

   - 
          specialization relation
          ‘onormal’ (arrow ending with a white triangle)

   - 
          instantiation relation
          ‘normal’ (arrow ending with a black triangle)

   - 
          extends relation
          ‘vee’ (arrow ending with a “v”)

   - 
          implements relation
          ‘dot’ (arrow ending with a black circle)

   - 
          imports relation
          ‘box’ (arrow ending with a black square)

   - 
          complements relation
          ‘obox’ (arrow ending with a white square)

   - 
          uses and use module relations
          ‘rdiamond’ (arrow ending with a black half diamond)

   - 
          predicate calls
          ‘normal’ (arrow ending with a black triangle)

   - 
          dynamic predicate updates
          ‘diamond’ (arrow ending with a black diamond)

When using the d2 graph language, we use similar node shapes and
arrowheads when available.  As d2 evolves, we hope that these graph
elements will converge further.

The library, directory, file, entity, and predicate nodes that are not
part of the predicates, entities, files, or libraries for which we are
generating a diagram use a dashed border, a darker color, and are
described as external.

Note that all the elements above can have captions.  See below the
diagrams ‘node_type_captions/1’ and ‘relation_labels/1’ output options.


File: TheLogtalkHandbook-3.101.0.info,  Node: Supported graph languages,  Next: Customization,  Prev: Graph elements,  Up: diagrams

5.8.7 Supported graph languages
-------------------------------

Currently, both DOT and d2 graph languages support all the features of
the ‘diagrams’ tool.  There’s also preliminary support for Mermaid (its
current version lacks several required features for parity with d2 and
Graphviz, notably support for links on edges).

JSON output format is also supported for use with Cytoscape.  The
Cytoscape backend generates ‘.cx2’ files using the Cytoscape Exchange
Format version 2 (CX2), including core aspects such as
‘attributeDeclarations’, ‘networkAttributes’, ‘nodes’, ‘edges’,
‘visualProperties’, and ‘status’.  Node and edge styling is exported
using CX2 visual property mappings based on node and edge attributes.
The JSON backend includes optional metadata such as title, description,
generation timestamp, and Logtalk/Prolog version information.  A default
HTML viewer, ‘cytoscapejs_viewer.html’, is provided for convenience.
This viewer currently requires starting a local web server in the
generated diagrams directory and manually entering the server address.

PlantUML output is also supported.  The PlantUML backend generates
‘.puml’ files using custom stereotypes with spotted characters to
distinguish Logtalk entity kinds (O/blue for objects, P/green for
protocols, T/orange for categories).  All five Logtalk relationships
(implements, imports, extends, instantiates, specializes, complements)
are mapped to distinct labeled arrow styles.  A shared ‘logtalk.iuml’
include file defines all skinparam blocks, stereotype colors, and CSS
styles for consistent rendering.  PlantUML version 1.2024.0 or later is
recommended.  See ‘https://plantuml.com’ for installation instructions.

The diagrams ‘.d2’ and ‘.dot’ files are created by default in the
‘'./dot_dias'’ sub-directory of the current directory.  These files can
be easily converted into a printable format such as SVG, PDF, or
Postscript.  Sample helper scripts are provided for converting a
directory of ‘.d2’ or ‘.dot’ files to ‘.svg’ files:

   - ‘lgt2svg.sh’ for POSIX systems

   - ‘lgt2svg.ps1’ for Windows systems

The scripts assume that the d2 and Graphviz command-line executables are
available from the system path.  For Graphviz, the default is the ‘dot’
executable, but the scripts accept a command-line option to select in
alternative the ‘circo’, ‘fdp’, or ‘neato’ executables).  For d2, the
default layout engine is ‘elk’, but the scripts accept a command-line
option to select in alternative the ‘dagre’ or ‘tala’ layout engines.

The recommended output format is SVG, as it supports tooltips and URL
links, which can be used for showing, e.g., entity types, relation
types, file paths, and for navigating to files and directories of files
(libraries) or to API documentation.  See the relevant diagram options
below in order to take advantage of these features (see the discussion
below on “linking diagrams”).

To convert to formats other than SVG, you will need to use the d2 and
Graphviz executables directly.  For example, using the Graphviz ‘dot’
executable, we can generate a PDF with the command:

     dot -Tpdf diagram.dot > diagram.pdf

This usually works fine for entity and predicate call cross-referencing
diagrams.  For directory and file diagrams, the ‘fdp’ and ‘circo’
command-line executables may produce better results.  For example:

     fdp -Tsvg diagram.dot > diagram.svg
     circo -Tsvg diagram.dot > diagram.svg

It’s also worth experimenting with different layouts to find the one
that produces the best results (see the ‘layout/1’ option described
below).

When generating diagrams for multiple libraries or directories, it’s
possible to split a diagram with several disconnected library or
directory graphs using the ‘ccomps’ command-line executable.  For
example:

     ccomps -x -o subdiagram.dot diagram.dot

For more information on the DOT language and related tools, see:

     http://www.graphviz.org/

When using Windows, there are known issues with some Prolog compilers
due to the internal representation of paths.  If you encounter problems
with a specific backend Prolog compiler, try, if possible, to use
another supported backend Prolog compiler when generating diagrams.

For printing large diagrams, you will need to either use a tool to slice
the diagram into page-sized pieces or, preferably, use software capable
of tiled printing (e.g., Adobe Reader).  You can also hand-edit the
generated ‘.dot’ files and play with settings such as aspect ratio for
fine-tuning the diagrams layout.


File: TheLogtalkHandbook-3.101.0.info,  Node: Customization,  Next: Linking diagrams,  Prev: Supported graph languages,  Up: diagrams

5.8.8 Customization
-------------------

This tool provides parametric objects implementing the different types
of diagrams where the parameter is the export format: ‘dot’, ‘d2’,
‘cx2’, and ‘puml’.  The non-parametric versions of the diagram objects
default to ‘dot’.

A set of options is available to specify the details to include in the
generated diagrams.  For entity diagrams, the options are:

   - 
          ‘layout(Layout)’
          diagram layout (one of the atoms ‘{top_to_bottom,bottom_to_top,left_to_right,right_to_left}’; default is ‘bottom_to_top’)

   - 
          ‘title(Title)’
          diagram title (an atom; default is ‘''’)

   - 
          ‘date(Boolean)’
          print current date and time (‘true’ or ‘false’; default is ‘true’)

   - 
          ‘versions(Boolean)’
          print Logtalk and backend version data (‘true’ or ‘false’; default is ‘false’)

   - 
          ‘interface(Boolean)’
          print public predicates (‘true’ or ‘false’; default is ‘true’)

   - 
          ‘file_labels(Boolean)’
          print file labels (‘true’ or ‘false’; default is ‘true’)

   - 
          ‘file_extensions(Boolean)’
          print file name extensions (‘true’ or ‘false’; default is ‘true’)

   - 
          ‘relation_labels(Boolean)’
          print entity relation labels (‘true’ or ‘false’; default is ‘true’)

   - 
          ‘externals(Boolean)’
          print external nodes (‘true’ or ‘false’; default is ‘true’)

   - 
          ‘node_type_captions(Boolean)’
          print node type captions (‘true’ or ‘false’; default is ‘true’)

   - 
          ‘metrics_overlay(Boolean)’
          print coupling metrics overlay in entity nodes showing afferent coupling (Ca), efferent coupling (Ce), instability (I), abstractness (A), and distance from main sequence (D) values (‘true’ or ‘false’; default is ‘false’)

   - 
          ‘cycle_detection(Boolean)’
          highlight cyclic relations by coloring the edges red (‘true’ or ‘false’; default is ‘false’)

   - 
          ‘inheritance_relations(Boolean)’
          print inheritance relations (‘true’ or ‘false’; default is ‘true’ for entity inheritance diagrams and ‘false’ for other entity diagrams)

   - 
          ‘provide_relations(Boolean)’
          print provide relations (‘true’ or ‘false’; default is ‘false’)

   - 
          ‘xref_relations(Boolean)’
          print predicate call cross-reference relations (‘true’ or ‘false’; default depends on the specific diagram)

   - 
          ‘xref_calls(Boolean)’
          print predicate cross-reference calls (‘true’ or ‘false’; default depends on the specific diagram)

   - 
          ‘output_directory(Directory)’
          directory for the ‘.d2’ and ‘.dot’ files (an atom; default is ‘'./dot_dias'’)

   - 
          ‘exclude_directories(Directories)’
          list of directories to exclude except as external nodes (default is ‘[]’); all sub-directories of the excluded directories are also excluded; directories may be listed by full or relative path

   - 
          ‘exclude_files(Files)’
          list of source files to exclude except as external nodes (default is ‘[]’); files may be listed by full path or basename, with or without extension

   - 
          ‘exclude_libraries(Libraries)’
          list of libraries to exclude except as external nodes (default is ‘[startup, scratch_directory]’)

   - 
          ‘exclude_entities(Entities)’
          list of entities to exclude except as external nodes (default is ‘[]’)

   - 
          ‘path_url_prefixes(PathPrefix, CodeURLPrefix, DocURLPrefix)’
          code and documenting URL prefixes for a path prefix used when generating cluster, library, directory, file, and entity links (atoms; no default; can be specified multiple times)

   - 
          ‘url_prefixes(CodeURLPrefix, DocURLPrefix)’
          default URL code and documenting URL prefixes used when generating cluster, library, file, and entity links (atoms; no default)

   - 
          ‘entity_url_suffix_target(Suffix, Target)’
          extension for entity documenting URLs (an atom; default is ‘'.html'’) and target separating symbols (an atom; default is ‘'#'’)

   - 
          ‘omit_path_prefixes(Prefixes)’
          omit common path prefixes when printing directory paths and when constructing URLs (a list of atoms; default is a list with the user home directory)

   - 
          ‘zoom(Boolean)’
          generate sub-diagrams and add links and zoom icons to library and entity nodes (‘true’ or ‘false’; default is ‘false’)

   - 
          ‘zoom_url_suffix(Suffix)’
          extension for linked diagrams (an atom; default is ‘'.svg'’)

In the particular case of cross-referencing diagrams, there are also the
options:

   - 
          ‘recursive_relations(Boolean)’
          print recursive predicate relations (‘true’ or ‘false’; default is ‘false’)

   - 
          ‘url_line_references(Host)’
          syntax for the URL source file line part (an atom; possible values are ‘{github,gitlab,bitbucket}’; default is ‘github’); when using this option, the ‘CodeURLPrefix’ should be a permanent link (i.e., it should include the commit SHA1)

   - 
          ‘predicate_url_target_format(Generator)’
          documentation final format generator (an atom; possible values are ‘{sphinx,other}’; default is ‘sphinx’)

For directory and file diagrams, the options are:

   - 
          ‘layout(Layout)’
          diagram layout (one of the atoms ‘{top_to_bottom,bottom_to_top,left_to_right,right_to_left}’; default is ‘top_to_bottom’)

   - 
          ‘title(Title)’
          diagram title (an atom; default is ‘''’)

   - 
          ‘date(Boolean)’
          print current date and time (‘true’ or ‘false’; default is ‘true’)

   - 
          ‘versions(Boolean)’
          print Logtalk and backend version data (‘true’ or ‘false’; default is ‘false’)

   - 
          ‘directory_paths(Boolean)’
          print file directory paths (‘true’ or ‘false’; default is ‘false’)

   - 
          ‘file_extensions(Boolean)’
          print file name extensions (‘true’ or ‘false’; default is ‘true’)

   - 
          ‘path_url_prefixes(PathPrefix, CodeURLPrefix, DocURLPrefix)’
          code and documenting URL prefixes for a path prefix used when generating cluster, directory, file, and entity links (atoms; no default; can be specified multiple times)

   - 
          ‘url_prefixes(CodeURLPrefix, DocURLPrefix)’
          default URL code and documenting URL prefixes used when generating cluster, library, file, and entity links (atoms; no default)

   - 
          ‘omit_path_prefixes(Prefixes)’
          omit common path prefixes when printing directory paths and when constructing URLs (a list of atoms; default is a list with the user home directory)

   - 
          ‘relation_labels(Boolean)’
          print entity relation labels (‘true’ or ‘false’; default is ‘false’)

   - 
          ‘externals(Boolean)’
          print external nodes (‘true’ or ‘false’; default is ‘true’)

   - 
          ‘node_type_captions(Boolean)’
          print node type captions (‘true’ or ‘false’; default is ‘false’)

   - 
          ‘output_directory(Directory)’
          directory for the ‘.d2’ and ‘.dot’ files (an atom; default is ‘'./dot_dias'’)

   - 
          ‘exclude_directories(Directories)’
          list of directories to exclude except as external nodes (default is ‘[]’)

   - 
          ‘exclude_files(Files)’
          list of source files to exclude except as external nodes (default is ‘[]’)

   - 
          ‘zoom(Boolean)’
          generate sub-diagrams and add links and zoom icons to library and entity nodes (‘true’ or ‘false’; default is ‘false’)

   - 
          ‘zoom_url_suffix(Suffix)’
          extension for linked diagrams (an atom; default is ‘'.svg'’)

For directory dependency diagrams, there is also the option:

   - ‘cycle_detection(Boolean)’ highlight cyclic relations by coloring
     the edges red (‘true’ or ‘false’; default is ‘false’)

For library diagrams, the options are:

   - 
          ‘layout(Layout)’
          diagram layout (one of the atoms ‘{top_to_bottom,bottom_to_top,left_to_right,right_to_left}’; default is ‘top_to_bottom’)

   - 
          ‘title(Title)’
          diagram title (an atom; default is ‘''’)

   - 
          ‘date(Boolean)’
          print current date and time (‘true’ or ‘false’; default is ‘true’)

   - 
          ‘versions(Boolean)’
          print Logtalk and backend version data (‘true’ or ‘false’; default is ‘false’)

   - 
          ‘directory_paths(Boolean)’
          print file directory paths (‘true’ or ‘false’; default is ‘false’)

   - 
          ‘path_url_prefixes(PathPrefix, CodeURLPrefix, DocURLPrefix)’
          code and documenting URL prefixes for a path prefix used when generating cluster, library, file, and entity links (atoms; no default; can be specified multiple times)

   - 
          ‘url_prefixes(CodeURLPrefix, DocURLPrefix)’
          default URL code and documenting URL prefixes used when generating cluster, library, file, and entity links (atoms; no default)

   - 
          ‘omit_path_prefixes(Prefixes)’
          omit common path prefixes when printing directory paths and when constructing URLs (a list of atoms; default is a list with the user home directory)

   - 
          ‘relation_labels(Boolean)’
          print entity relation labels (‘true’ or ‘false’; default is ‘false’)

   - 
          ‘externals(Boolean)’
          print external nodes (‘true’ or ‘false’; default is ‘true’)

   - 
          ‘node_type_captions(Boolean)’
          print node type captions (‘true’ or ‘false’; default is ‘false’)

   - 
          ‘output_directory(Directory)’
          directory for the ‘.d2’ and ‘.dot’ files (an atom; default is ‘'./dot_dias'’)

   - 
          ‘exclude_directories(Directories)’
          list of directories to exclude except as external nodes (default is ‘[]’)

   - 
          ‘exclude_files(Files)’
          list of source files to exclude except as external nodes (default is ‘[]’)

   - 
          ‘exclude_libraries(Libraries)’
          list of libraries to exclude except as external nodes (default is ‘[startup, scratch_directory]’)

   - 
          ‘zoom(Boolean)’
          generate sub-diagrams and add links and zoom icons to library and entity nodes (‘true’ or ‘false’; default is ‘false’)

   - 
          ‘zoom_url_suffix(Suffix)’
          extension for linked diagrams (an atom; default is ‘'.svg'’)

For library dependency diagrams, there is also the option:

   - ‘cycle_detection(Boolean)’ highlight cyclic relations by coloring
     the edges red (‘true’ or ‘false’; default is ‘false’)

When using the ‘zoom(true)’ option, the ‘layout(Layout)’ option applies
only to the top diagram; sub-diagrams will use their own layout default.

The option ‘omit_path_prefixes(Prefixes)’ with a non-empty list of
prefixes should preferably be used together with the option
‘directory_paths(true)’ when generating library or file diagrams that
reference external libraries or files.  To confirm the exact default
options used by each type of diagram, send the ‘default_options/1’
message to the diagram object.

Be sure to set the ‘source_data’ flag ‘on’ before compiling the
libraries or files for which you want to generate diagrams.

Support for displaying Prolog modules and Prolog module files in
diagrams of Logtalk applications:

   - 
          ECLiPSe
          file diagrams don’t display module files

   - 
          SICStus Prolog
          file diagrams don’t display module files

   - 
          SWI-Prolog
          full support (uses the SWI-Prolog ‘prolog_xref’ library)

   - 
          YAP
          full support (uses the YAP ‘prolog_xref’ library)


File: TheLogtalkHandbook-3.101.0.info,  Node: Linking diagrams,  Next: Creating diagrams for Prolog module applications,  Prev: Customization,  Up: diagrams

5.8.9 Linking diagrams
----------------------

When using SVG output, it’s possible to generate diagrams that link to
other diagrams, to API documentation, to local files and directories,
and to source code repositories.

For generating links between diagrams, use the ‘zoom(true)’ option.
This option allows (1) linking library diagrams to entity diagrams to
predicate cross-referencing diagrams and (2) linking directory diagrams
to file diagrams to entity diagrams to predicate cross-referencing
diagrams.  The sub-diagrams are automatically generated.  For example,
using the predicates that generate library diagrams will also
automatically generate the entity and predicate cross-referencing
diagrams.

To generate local links for opening directories, files, and file
locations in selected text editors, set the URL code prefix:

   - VSCode: ‘url_prefixes('vscode://file/', DocPrefix)’

   - VSCodium: ‘url_prefixes('vscodium://file/', DocPrefix)’

   - Cursor: ‘url_prefixes('cursor://file/', DocPrefix)’

   - PearAI: ‘url_prefixes('pearai://file/', DocPrefix)’

   - Windsurf: ‘url_prefixes('windsurf://file/', DocPrefix)’

   - Zed: ‘url_prefixes('zed://file/', DocPrefix)’

   - BBEdit: ‘url_prefixes('x-bbedit://open?url=file://', DocPrefix)’

   - MacVim: ‘url_prefixes('mvim://open?url=file://', DocPrefix)’

   - TextMate: ‘url_prefixes('txmt://open?url=file://', DocPrefix)’

   - IDEA: ‘url_prefixes('idea://open?file=', DocPrefix)’

   - PyCharm: ‘url_prefixes('pycharm://open?file=', DocPrefix)’

In this case, the ‘DocPrefix’ argument should be the path to the
directory containing the HTML version of the application APIs.

As most of the text editor URL scheme handlers require local links to
use absolute paths, the ‘omit_path_prefixes/1’ option is ignored.  Note
that local links require text editor support for URL schemes that can
handle both file and directory links.

To generate links to API documentation and source code repositories, use
the options ‘path_url_prefixes/3’ (or ‘url_prefixes/2’ for simpler
cases) and ‘omit_path_prefixes/1’.  The idea is that the
‘omit_path_prefixes/1’ option specifies local file prefixes that will be
cut and replaced by the URL prefixes (which can be path prefix specific
when addressing multiple code repositories).  To generate local file
system URLs, define the empty atom, ‘''’, as a prefix.  As an example,
consider the Logtalk library.  Its source code is available from a
GitHub repository, and its documentation is published on the Logtalk
website.  The relevant URLs in this case are:

   - ‘https://github.com/LogtalkDotOrg/logtalk3/’ (source code)

   - ‘https://logtalk.org/library/’ (API documentation)

Git source code URLs should include the commit SHA1 to ensure that
entity and predicate file line information in the URLs remain valid if
the code changes in later commits.  Assuming a ‘GitHub’ variable bound
to the SHA1 commit URL we want to reference, an inheritance diagram can
be generated using the goal:

     | ?- GitHub  = 'https://github.com/LogtalkDotOrg/logtalk3/commit/eb156d46e135ac47ef23adcc5d20d49dd8b66abb',
          APIDocs = 'https://logtalk.org/library/',
          logtalk_load(diagrams(loader)),
          set_logtalk_flag(source_data, on),
          logtalk_load(library(all_loader)),
          inheritance_diagram::rlibrary(library, [
              title('Logtalk library'),
              node_type_captions(true),
              zoom(true),
              path_url_prefixes('$LOGTALKUSER/', GitHub, APIDocs),
              path_url_prefixes('$LOGTALKHOME/', GitHub, APIDocs),
              omit_path_prefixes(['$LOGTALKUSER/', '$LOGTALKHOME/', '$HOME/'])
          ]).

The two ‘path_url_prefixes/3’ options take care of source code and API
documentation for entities loaded either from the Logtalk installation
directory (whose location is given by the ‘LOGTALKHOME’ environment
variable) or from the Logtalk user directory (whose location is given by
the ‘LOGTALKUSER’ environment variable).  As we also don’t want any
local operating-system paths to be exposed in the diagram, we use the
‘omit_path_prefixes/1’ option to suppress those path prefixes.  Note
that all the paths and URLs must end with a slash for proper handling.
The ‘git’ library may be useful to retrieve the commit SHA1 from a local
repo directory.

For both ‘path_url_prefixes/3’ and ‘omit_path_prefixes/1’ options, when
a path prefix is itself a prefix of another path, the shorter path must
come last to ensure correct links.

See the ‘SCRIPT.txt’ file in the tool directory for additional examples.
To avoid retyping such complex goals when updating diagrams, use the
‘doclet’ tool to save and reapply them easily (e.g., by using the ‘make’
tool with the ‘documentation’ target).


File: TheLogtalkHandbook-3.101.0.info,  Node: Creating diagrams for Prolog module applications,  Next: Creating diagrams for plain Prolog files,  Prev: Linking diagrams,  Up: diagrams

5.8.10 Creating diagrams for Prolog module applications
-------------------------------------------------------

Currently limited to SWI-Prolog and YAP Prolog module applications due
to the lack of a comprehensive reflection API in other Prolog systems.

Simply load your Prolog module application and its dependencies and then
use diagram entity, directory, or file predicates.  Library diagram
predicates are not supported.  See the ‘SCRIPT.txt’ file in the tool
directory for some usage examples.  Note that support for diagrams with
links to API documentation is quite limited, however, due to the lack of
Prolog standards.


File: TheLogtalkHandbook-3.101.0.info,  Node: Creating diagrams for plain Prolog files,  Next: Other notes,  Prev: Creating diagrams for Prolog module applications,  Up: diagrams

5.8.11 Creating diagrams for plain Prolog files
-----------------------------------------------

This tool can also be used to create predicate cross-referencing
diagrams for plain Prolog files.  For example, if the Prolog file is
named ‘code.pl’, simply define an object including its code:

     :- object(code).
         :- include('code.pl').
     :- end_object.

Save the object to an e.g.  ‘code.lgt’ file in the same directory as the
Prolog file and then load it and create the diagram:

     | ?- logtalk_load(code),
          xref_diagram::entity(code).

An alternative is to use the ‘object_wrapper_hook’ provided by the
‘hook_objects’ library:

     | ?- logtalk_load(hook_objects(loader)).
     ...

     | ?- logtalk_load(code, [hook(object_wrapper_hook)]),
          xref_diagram::entity(code).


File: TheLogtalkHandbook-3.101.0.info,  Node: Other notes,  Prev: Creating diagrams for plain Prolog files,  Up: diagrams

5.8.12 Other notes
------------------

Caller graph diagrams can be generated for a specific predicate using
the ‘caller_diagram’ object.  For example, to generate a caller graph
for the ‘list::member/2’ predicate:

     | ?- caller_diagram::predicate(list::member/2).

Non-terminal indicators can also be used.  For example:

     | ?- caller_diagram::predicate(number_grammars(chars)::digit//1).

Generating complete diagrams requires that all referenced entities are
loaded.  When that is not the case, notably when generating
cross-referencing diagrams, missing entities can result in incomplete
diagrams.

For complex applications, diagrams can often be made simpler and more
readable by omitting external nodes (see the ‘externals/1’ option)
and/or using one of the alternatives to ‘dot’ provided by Graphviz
depending on the type of the diagram (see the section above on supported
graph languages for more details).

When generating entity predicate call cross-reference diagrams, caller
nodes are not created for auxiliary predicates.  For example, if the
‘meta_compiler’ library is used to optimize meta-predicate calls, the
diagrams may show predicates that are not apparently called by any other
predicate when the callers are from the optimized meta-predicate goals
(which are called via library generated auxiliary predicates).  A
workaround in this case would be creating a dedicated loader file that
doesn’t load (and apply) the ‘meta_compiler’ library when generating the
diagrams.

When generating diagrams in SVG format, a copy of the ‘diagrams.css’
file must exist in any directory used for publishing diagrams using it.
The ‘lgt2svg’ scripts also take care of copying this file.

The Graphviz command-line utilities, e.g., ‘dot’, are notorious for
random crashes (segmentation faults usually), often requiring retrying
conversions from ‘.dot’ files to other formats.  A possible workaround
is to repeat the command until it completes without error.  See, for
example, the ‘lgt2svg.sh’ script.

The conversion by the ‘d2’ command-line executable of ‘.d2’ files to
‘.svg’ files can be quite slow (as of its 0.6.8 version) with the
default ‘elk’ layout engine.  The ‘dagre’ layout engine is much faster
but doesn’t support a node referencing itself (notably, a node
representing a metaclass that instantiates itself).

Using the default d2 layout engine (‘elk’) works fine with graphs with a
relatively small number of nodes and edges.  When that’s not the case,
it’s a good idea to experiment with other layout engines.


File: TheLogtalkHandbook-3.101.0.info,  Node: doclet,  Next: help,  Prev: diagrams,  Up: Developer Tools

5.9 ‘doclet’
============

This folder provides a simple tool for (re)generating documentation for
a project.  The tool defines a ‘doclet’ object that is expected to be
extended by the user to specify a sequence of goals and a sequence of
shell commands that load the application and (re)generate its
documentation.

Doclet source files are preferably named ‘doclet.lgt’ (or
‘doclet.logtalk’) and the doclet objects are usually named after the
application or library to be documented with a ‘_doclet’ suffix.  By
using an ‘initialization/1’ directive to automatically send the
‘update/0’ message that generates the documentation upon doclet loading,
we can abstract the name of the doclet object.  The usual query to load
and run a doclet is therefore:

     | ?- logtalk_load([doclet(loader), doclet]).

For usage examples, see the ‘sample_doclet.lgt’, ‘doclet1.lgt’,
‘zoom_doclet.lgt’, and ‘tools_doclet.lgt’ source files.

* Menu:

* API documentation: API documentation<7>.
* Loading: Loading<7>.
* Automating running doclets::
* Integration with the make tool: Integration with the make tool<2>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<7>,  Next: Loading<7>,  Up: doclet

5.9.1 API documentation
-----------------------

This tool API documentation is available at:

‘../../apis/library_index.html#doclet’

For sample queries, please see the ‘SCRIPT.txt’ file in the tool
directory.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<7>,  Next: Automating running doclets,  Prev: API documentation<7>,  Up: doclet

5.9.2 Loading
-------------

This tool can be loaded using the query:

     | ?- logtalk_load(doclet(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Automating running doclets,  Next: Integration with the make tool<2>,  Prev: Loading<7>,  Up: doclet

5.9.3 Automating running doclets
--------------------------------

You can use the ‘scripts/logtalk_doclet.sh’ Bash shell script for
automating running doclets.  The script expects the doclet source files
to be named either ‘doclet.lgt’ or ‘doclet.logtalk’.  See the
‘scripts/NOTES.md’ file or the script man page for details.


File: TheLogtalkHandbook-3.101.0.info,  Node: Integration with the make tool<2>,  Prev: Automating running doclets,  Up: doclet

5.9.4 Integration with the make tool
------------------------------------

Loading this tool adds a definition for the
‘logtalk_make_target_action/1’ hook predicate for the target
‘documentation’.  The hook definition sends an ‘update/0’ message to
each loaded doclet.


File: TheLogtalkHandbook-3.101.0.info,  Node: help,  Next: issue_creator,  Prev: doclet,  Up: Developer Tools

5.10 ‘help’
===========

This tool provides help for Logtalk features and libraries when running
in most operating-systems.  For help on the Logtalk compiler error and
warning messages, see the ‘tutor’ tool.

* Menu:

* Requirements: Requirements<2>.
* Customization: Customization<2>.
* API documentation: API documentation<8>.
* Loading: Loading<8>.
* Testing: Testing<7>.
* Supported operating-systems::
* Usage: Usage<5>.
* Known issues: Known issues<3>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Requirements<2>,  Next: Customization<2>,  Up: help

5.10.1 Requirements
-------------------

On Windows, the ‘start’ command must be available.  On Linux, the
‘xdg-open’ command must be available.  On macOS, the command ‘open’ is
used.  On POSIX systems ‘bsdtar’ is also required.

Browsing the Handbook and APIs documentation at the top-level requires a
POSIX system and one of the following terminal-based browsers installed:

   - ‘https://invisible-island.net/lynx/’

   - ‘https://w3m.sourceforge.net/’

   - ‘http://links.twibright.com/’

   - ‘https://sr.ht/~bptato/chawan/’

On macOS, these browsers and ‘bsdtar’ can be installed with either
MacPorts:

     $ sudo port install lynx
     $ sudo port install w3m
     $ sudo port install links
     $ sudo port install libarchive

Or using Homebrew:

     $ brew install lynx
     $ brew install w3m
     $ brew install links
     $ brew install chawan
     $ brew install libarchive

On Linux systems, use the distribution’s own package manager to install
the browsers and ‘bsdtar’.  For example, in Ubuntu systems:

     $ sudo apt install lynx
     $ sudo apt install w3m
     $ sudo apt install links2
     $ sudo apt install libarchive-tools

For RedHat systems:

     $ sudo dnf install lynx
     $ sudo dnf install w3m
     $ sudo dnf install links2
     $ sudo dnf install bsdtar

If you’re running Logtalk from a git clone of its repo, you will need to
run the ‘docs/apis/sources/build.sh’ or ‘docs/apis/sources/build.ps1’
scripts to generate APIs documentation HTML files and also run the
‘docs/handbook/sources/build.sh’ or ‘docs/handbook/sources/build.ps1’
scripts to generate the Handbook HTML files.  Alternatively, you can
download the documentation for the latest stable release from the
Logtalk website and save them to the ‘docs’ directories.


File: TheLogtalkHandbook-3.101.0.info,  Node: Customization<2>,  Next: API documentation<8>,  Prev: Requirements<2>,  Up: help

5.10.2 Customization
--------------------

The preferred browser can be set in a ‘settings.lgt’ file by defining
the ‘help_default_browser’ user-defined flag as follows:

     :- initialization(
         create_logtalk_flag(help_default_browser, Browser, [type(atom), keep(true)])
     ).

The valid values for ‘Browser’ are: ‘lynx’ (default value), ‘w3m’,
‘links’, ‘cha’, and ‘default’ (‘default’ means use the operating-system
default browser instead of one of the terminal-based browsers).

We can also select between browsing the HTML files generated by Sphinx
for web browsing or the XHTML files generated by Sphinx for the ePub
version of the documentation by defining the ‘help_default_files’
user-defined flag as follows:

     :- initialization(
         create_logtalk_flag(help_default_files, Format, [type(atom), keep(true)])
     ).

The valid values for ‘Format’ are ‘html’ (default value) or ‘xhtml’.

The ‘samples/settings-sample.lgt’ file contains commented out code for
defining these flags.

On POSIX systems, one of the supported terminal-based browsers must be
installed unless you prefer using the default browser.  By default, the
tool checks first for ‘lynx’, second for ‘w3m’, third for ‘links’, and
finally for ‘chawan’.  When none of these terminal-based browsers is
available in their default installation paths, the documentation is open
in the operating-system default browser.

On Windows systems, the documentation is open in the operating-system
default browser.

When using the terminal-based browsers, after finishing consulting the
documentation and quitting the process, you will be back to the
top-level prompt (if you find that the top-level have scrolled from its
last position, try to set your terminal terminfo to ‘xterm-256colour’).


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<8>,  Next: Loading<8>,  Prev: Customization<2>,  Up: help

5.10.3 API documentation
------------------------

This tool API documentation is available at:

‘../../apis/library_index.html#help’


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<8>,  Next: Testing<7>,  Prev: API documentation<8>,  Up: help

5.10.4 Loading
--------------

     | ?- logtalk_load(help(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<7>,  Next: Supported operating-systems,  Prev: Loading<8>,  Up: help

5.10.5 Testing
--------------

To test this tool, load the ‘tester.lgt’ file:

     | ?- logtalk_load(help(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Supported operating-systems,  Next: Usage<5>,  Prev: Testing<7>,  Up: help

5.10.6 Supported operating-systems
----------------------------------

Currently, support is limited to Linux, macOS, and Windows.

This tool relies on the library portable operating-system access
abstraction.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<5>,  Next: Known issues<3>,  Prev: Supported operating-systems,  Up: help

5.10.7 Usage
------------

After loading the tool, use the query ‘help::help’ to get started:

     | ?- logtalk_load(help(loader)).
     ...

     | ?- help::help.
     ...

When using ECLiPSe, you will need to write the object name, ‘help’,
between parentheses to avoid a clash with the ‘help’ built-in operator:

     | ?- (help)::help.
     ...

Same sample help queries:

     % get et on-line help for the `logtalk_load/2` built-in predicate:

     | ?- help::logtalk_load/2.
     ...

     % get on-line help for the `eos//0` built-in non-terminal:

     | ?- help::eos//0.
     ...

     % consult the Handbook:

     | ?- help::handbook.
     ...

     % consult the APIs documentation:

     | ?- help::apis.
     ...

     % consult the APIs documentation about a library predicate:

     | ?- help::apis(member/2).
     ...

     % consult the APIs documentation about a library non-terminal:

     | ?- help::apis(one_or_more//0).
     ...

     % consult the documentation of a library:

     | ?- help::library(random).
     ...

     % consult the documentation of an entity:

     | ?- help::entity(logtalk).
     ...

     % consult the developer tools documentation:

     | ?- help::tools.
     ...

     % consult the documentation of the lgtunit tool:

     | ?- help::tool(lgtunit).
     ...

     % consult the documentation of the logtalk_tester script:

     | ?- help::man(logtalk_tester).
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Known issues<3>,  Prev: Usage<5>,  Up: help

5.10.8 Known issues
-------------------

When using the ‘lynx’ terminal-based browser, the ‘help_default_files’
flag setting is ignored as this browser doesn’t support XHTML.

When using the terminal-based browsers, the Handbook and APIs search
boxes are not usable as they require JavaScript support.  Use instead
the indexes.

Some CSS support is only provided by the Chawan terminal-based browser.
This results in formatting issues when browsing the Logtalk
documentation.  Some of these issues can be avoided by setting the
‘help_default_files’ flag to ‘xhtml’.

The open commands used to open documentation URLs in the default browser
drop the fragment part, thus preventing navigation to the specified
position on the documentation page.

ECLiPSe defines a ‘help’ prefix operator that forces wrapping this atom
between parentheses when sending messages to the tool.  E.g.  use
‘(help)::help’ instead of ‘help::help’.


File: TheLogtalkHandbook-3.101.0.info,  Node: issue_creator,  Next: lgtdoc,  Prev: help,  Up: Developer Tools

5.11 ‘issue_creator’
====================

This is a complementary tool for the ‘lgtunit’ tool for automatically
creating bug report issues for failed tests in GitHub or GitLab servers.

* Menu:

* Requirements: Requirements<3>.
* Loading: Loading<9>.
* Usage: Usage<6>.
* Known issues: Known issues<4>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Requirements<3>,  Next: Loading<9>,  Up: issue_creator

5.11.1 Requirements
-------------------

This tool requires that the GitHub ‘gh’ and GitLab ‘glab’ CLIs be
installed.  For the installation instructions see:

   - GitHub: ‘https://cli.github.com’

   - GitLab: ‘https://glab.readthedocs.io’


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<9>,  Next: Usage<6>,  Prev: Requirements<3>,  Up: issue_creator

5.11.2 Loading
--------------

This tool can be loaded using the query:

     | ?- logtalk_load(issue_creator(loader)).

But, in the most common usage scenario, this tool is automatically
loaded by the ‘logtalk_tester’ automation script.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<6>,  Next: Known issues<4>,  Prev: Loading<9>,  Up: issue_creator

5.11.3 Usage
------------

The ‘logtalk_tester’ automation script accepts a ‘-b’ option for
automatically using this tool (see the script man page for details).  In
the most simple case, this option possible values are ‘github’ and
‘gitlab’.  For example:

     $ logtalk_tester \
         -p gnu \
         -b github \
         -s "/home/jdoe/foo/" \
         -u https://github.com/jdoe/foo/tree/55aa900775befa135e0d5b48ea63098df8b97f5c/

The ‘logtalk_tester’ script 'must' be called from a git repo directory
or one of its sub-directories, which is a common setup in CI/CD
pipelines.  Moreover, prior to running the tests, the CLI must be used,
if required, to authenticate and login to the server where the bug
report issues will be created:

   - GitHub: ‘gh auth login --hostname <string> --with-token <
     token.txt’

   - GitLab: ‘glab auth login --hostname <string> --token <string>’

The access token must have the necessary scopes that allow bug reports
to be created.  See the CLIs documentation for details.  Typically, the
‘auth’ command is called from the CI/CD pipeline definition scripts.
However, depending on the CI/CD workflow, the authentication may be done
implicitly.

The bug reports are created using by default the label ‘bug’ and
assigned to the author of the latest commit of the git repo.  The ‘-b’
option can also be used to override the label with a comma separated set
of labels.  For example, to use both ‘bug’ and ‘auto’ labels:

     $ logtalk_tester \
         -p gnu \
         -b github:bug,auto \
         -s "/home/jdoe/foo/" \
         -u https://github.com/jdoe/foo/tree/55aa900775befa135e0d5b48ea63098df8b97f5c/

Note that the labels 'must' be predefined in the issue tracker server
for the bug report to be successfully created.  The ‘auto’ label can be
used to simplify filtering of auto-generated bug reports when browsing
the issue tracker.

The bug reports use Markdown formatting, which is the default in GitHub
and GitLab issue trackers.

But reports are only created for non-flaky tests.  The bug report title
and labels are used to prevent creating duplicated bug reports.
Therefore, the title should not be manually edited and the same labels
should be used for multiple runs of the same tests and preserved when
editing the bug reports.

There are cases where we may want to postpone or temporarily disable the
automatic creation of bug reports.  E.g.  a WIP branch that’s known to
break multiple tests.  A solution is to define a pull/merge request
label, e.g.  ‘NO_AUTO_BUG_REPORTS’, that can then be checked by the
CI/CD workflow.  For example, we can test the presence of that label to
set a ‘AUTO_BUG_REPORTS’ environment variable to either an empty string
or a ‘-b’ option and use:

     logtalk_tester.sh $AUTO_BUG_REPORTS -p ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Known issues<4>,  Prev: Usage<6>,  Up: issue_creator

5.11.4 Known issues
-------------------

GitLab creates CI/CD pipelines in a detached HEAD state by default.  As
a consequence, the git branch would be reported as HEAD. To workaround
this issue, this tool uses the value of the GitLab CI/CD pipeline
variable ‘CI_COMMIT_REF_NAME’ when defined as the branch name.

This tool is in a beta stage of development.  Your feedback is most
appreciated.


File: TheLogtalkHandbook-3.101.0.info,  Node: lgtdoc,  Next: lgtunit,  Prev: issue_creator,  Up: Developer Tools

5.12 ‘lgtdoc’
=============

This is the default Logtalk documenting tool for generating API
documentation for libraries and applications.  It uses the structural
reflection API to extract and output in XML format relevant
documentation about a source file, a library or directory of source
files, or all loaded source files.  The tool predicates accept several
options for generating the XML files, including the output directory.

The ‘lgtdoc/xml’ directory contains several ready-to-use Bash and
PowerShell scripts for converting the XML documenting files into final
formats, including XHTML 1.1, HTML 4.01, HTML 5, PDF, Markdown, and
reStructuredText (for use with Sphinx), and plain text files.  The
scripts are described in their ‘man’ pages and made available in the
system path by default.

* Menu:

* Requirements: Requirements<4>.
* API documentation: API documentation<9>.
* Loading: Loading<10>.
* Testing: Testing<8>.
* Documenting source code::
* Generating documentation::
* Documentation linter checks::


File: TheLogtalkHandbook-3.101.0.info,  Node: Requirements<4>,  Next: API documentation<9>,  Up: lgtdoc

5.12.1 Requirements
-------------------

This tool requirements for converting the XML files it generates to a
final format are as follows:

  1. Converting XML files to (X)HTML, reStructuredText, Markdown, or
     plain text files requires a XSLT processor.  The supported XSLT
     processors for Bash conversion scripts are:

   - xsltproc: ‘https://gitlab.gnome.org/GNOME/libxslt/-/wikis/home’

   - Xalan: ‘https://xml.apache.org/xalan-c/index.html’

   - Saxon: ‘https://www.saxonica.com’

On Windows, the PowerShell scripts use the .Net XSLT classes.

The reStructuredText files output is usually used as an intermediate
step to generate Sphinx HTML, PDF, ePub, and Texinfo files.  The
additional requirements are:

   - Sphinx: ‘https://www.sphinx-doc.org/’

   - Pygments: ‘https://pygments.org/’

   - Read the Docs theme:
     ‘https://github.com/readthedocs/sphinx_rtd_theme’

  2. Converting XML files to PDF files require a XSL-FO processor.  The
     supported XSL-FO processors for Bash and PowerShell conversion
     scripts are:

   - Apache FOP processor: ‘https://xmlgraphics.apache.org/fop/’

   - RenderX XEP processor: ‘https://www.renderx.com/’

For additional details, including compatible dependency versions and
available conversion scripts, see the ‘xml/NOTES.md’ file.  See the
‘tools/NOTES.md’ file for per operating-system installation instructions
for the above dependencies.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<9>,  Next: Loading<10>,  Prev: Requirements<4>,  Up: lgtdoc

5.12.2 API documentation
------------------------

This tool API documentation is available at:

‘../../apis/library_index.html#lgtdoc’


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<10>,  Next: Testing<8>,  Prev: API documentation<9>,  Up: lgtdoc

5.12.3 Loading
--------------

This tool can be loaded using the query:

     | ?- logtalk_load(lgtdoc(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<8>,  Next: Documenting source code,  Prev: Loading<10>,  Up: lgtdoc

5.12.4 Testing
--------------

To test this tool, load the ‘tester.lgt’ file:

     | ?- logtalk_load(lgtdoc(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Documenting source code,  Next: Generating documentation,  Prev: Testing<8>,  Up: lgtdoc

5.12.5 Documenting source code
------------------------------

For information on documenting your source code, notably on documenting
directives, consult the documenting section of the User Manual:

‘../../handbook/userman/documenting.html’

Extracting documenting information from your source code using this tool
requires compiling the source files using the ‘source_data(on)’ compiler
flag.  For example:

     | ?- logtalk_load(source_file, [source_data(on)]).

Usually, this flag is set for all application source files in the
corresponding loader file.  In alternative, you may also turn on the
‘source_data’ flag globally by typing:

     | ?- set_logtalk_flag(source_data, on).

The tool API allows generating documentation for libraries, directories,
and files, complemented with library, directory, entity, and predicate
indexes.  Note that the source files to be documented 'must' be loaded
prior to using this tool predicates to generate the documentation.


File: TheLogtalkHandbook-3.101.0.info,  Node: Generating documentation,  Next: Documentation linter checks,  Prev: Documenting source code,  Up: lgtdoc

5.12.6 Generating documentation
-------------------------------

For a simple application, assuming a library alias is defined for it
(e.g.  ‘my_app’), and at the top-level interpreter, we can generate the
application documentation by typing:

     | ?- {my_app(loader)}.
     ...

     | ?- {lgtdoc(loader)}.
     ...

     | ?- lgtdoc::library(my_app).
     ...

By default, the documenting XML files are created in a ‘xml_docs’
directory in the current working directory.  But usually all documenting
files are collected for both the application and the libraries it uses
in a common directory so that all documentation links resolved properly.
The ‘lgtdoc’ predicates can take a list of options to customize the
generated XML documenting files.  See the remarks section in the
lgtdocp(1) protocol documentation for details on the available options.

After generating the XML documenting files, these can be easily
converted into final formats using the provided scripts.  For example,
assuming that we want to generate HTML documentation:

     $ cd xml_docs
     $ lgt2html -t "My app"

To generate the documentation in Sphinx format instead (as used by
Logtalk itself for its APIs):

     $ cd xml_docs
     $ lgt2rst -s -- -q -p "Application name" -a "Author name" -v "Version X.YZ.P"
     $ make html

In this case, the generated documentation will be in the
‘xml_docs/_build/html/’ directory.  See the scripts man pages or call
them using the ‘-h’ option to learn more about their supported options.

For more complex applications, you can use the ‘doclet’ tool to define a
'doclet' to automate all the steps required to generate documentation.
The 'doclet' message that triggers the process can also be sent
automatically when the ‘make’ tool is used with the ‘documentation’
target.

   ---------- Footnotes ----------

   (1) ../../docs/apis/library_index.html#lgtdoc


File: TheLogtalkHandbook-3.101.0.info,  Node: Documentation linter checks,  Prev: Generating documentation,  Up: lgtdoc

5.12.7 Documentation linter checks
----------------------------------

When the ‘lgtdoc_missing_directives’ flag is set to ‘warning’ (its usual
default value), the ‘lgtdoc’ tool prints warnings on missing entity
‘info/1’ directives and missing predicate ‘info/2’ and ‘mode/2’
directives.

When the ‘lgtdoc_missing_info_key’ flag is set to ‘warning’ (its usual
default value), the ‘lgtdoc’ tool prints warnings on entity ‘info/1’
directive and predicate ‘info/2’ directive missing de facto required
keys (e.g., ‘comment’, ‘parameters’ or ‘parnames’ for parametric
entities, ‘arguments’ or ‘argnames’ for predicates/non-terminals with
arguments).

When the ‘lgtdoc_invalid_dates’ flag is set to ‘warning’ (its usual
default value), the ‘lgtdoc’ tool prints warnings on invalid dates
(including dates in the future) in ‘info/1’ directives.

When the ‘lgtdoc_non_standard_exceptions’ flag is set to ‘warning’ (its
usual default value), the ‘lgtdoc’ tool prints warnings on non-standard
exceptions.  This linter check is particularly effective in detecting
typos when specifying standard exceptions.

When the ‘lgtdoc_missing_punctuation’ flag is set to ‘warning’ (its
usual default value), the ‘lgtdoc’ tool prints warnings on missing
ending periods (full stops), exclamation marks, or question marks in
‘info/1-2’ directives (in comments, remarks, parameter descriptions, and
argument descriptions).

Set a flag value to ‘silent’ to turn off the corresponding linter
warnings.


File: TheLogtalkHandbook-3.101.0.info,  Node: lgtunit,  Next: linter,  Prev: lgtdoc,  Up: Developer Tools

5.13 ‘lgtunit’
==============

The ‘lgtunit’ tool provides testing support for Logtalk.  It can also be
used for testing plain Prolog code and Prolog module code.

This tool is inspired by the xUnit frameworks architecture and by the
works of Joachim Schimpf (ECLiPSe library ‘test_util’) and Jan
Wielemaker (SWI-Prolog ‘plunit’ package).

Tests are defined in objects, which represent a 'test set' or 'test
suite'.  In simple cases, we usually define a single object containing
the tests.  But it is also possible to use parametric test objects or
multiple objects defining parametrizable tests or test subsets for
testing more complex units and facilitating tests maintenance.
Parametric test objects are specially useful to test multiple
implementations of the same protocol using a single set of tests by
passing the implementation object as a parameter value.

* Menu:

* Main files::
* API documentation: API documentation<10>.
* Loading: Loading<11>.
* Testing: Testing<9>.
* Writing and running tests::
* Automating running tests::
* Parametric test objects::
* Test dialects::
* User-defined test dialects::
* QuickCheck::
* Skipping tests::
* Selecting tests::
* Checking test goal results::
* Testing local predicates::
* Testing non-deterministic predicates::
* Testing generators::
* Testing input/output predicates::
* Suppressing tested predicates output::
* Tests with timeout limits::
* Setup and cleanup goals::
* Test annotations::
* Test execution times and memory usage::
* Working with test data files::
* Flaky tests::
* Mocking::
* Debugging messages in tests::
* Debugging failed tests::
* Code coverage::
* Utility predicates::
* Exporting test results::
* Generating Allure reports::
* Exporting code coverage results::
* Automatically creating bug reports at issue trackers::
* Minimizing test results output::
* Help with warnings::
* Known issues: Known issues<5>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Main files,  Next: API documentation<10>,  Up: lgtunit

5.13.1 Main files
-----------------

The ‘lgtunit.lgt’ source file implements a framework for defining and
running unit tests in Logtalk.  The ‘lgtunit_messages.lgt’ source file
defines the default translations for the messages printed when running
unit tests.  These messages can be intercepted to customize the output,
e.g.  to make it less verbose or for integration with e.g.  GUI IDEs and
continuous integration servers.

Other files that are part of this tool provide support for alternative
output formats of test results and are discussed below.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<10>,  Next: Loading<11>,  Prev: Main files,  Up: lgtunit

5.13.2 API documentation
------------------------

This tool API documentation is available at:

‘../../apis/library_index.html#lgtunit’


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<11>,  Next: Testing<9>,  Prev: API documentation<10>,  Up: lgtunit

5.13.3 Loading
--------------

This tool can be loaded using the query:

     | ?- logtalk_load(lgtunit(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<9>,  Next: Writing and running tests,  Prev: Loading<11>,  Up: lgtunit

5.13.4 Testing
--------------

To test this tool, load the ‘tester.lgt’ file:

     | ?- logtalk_load(lgtunit(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Writing and running tests,  Next: Automating running tests,  Prev: Testing<9>,  Up: lgtunit

5.13.5 Writing and running tests
--------------------------------

In order to write your own unit tests, define objects extending the
‘lgtunit’ object.  You may start by copying the
‘samples/tests-sample.lgt’ file (at the root of the Logtalk
distribution) to a ‘tests.lgt’ file in your project directory and
editing it to add your tests:

     :- object(tests,
         extends(lgtunit)).

         % test definitions
         ...

     :- end_object.

The section on *note test dialects: 945. below describes in detail how
to write tests.  See the ‘tests’ top directory for examples of actual
unit tests.  Other sources of examples are the ‘library’ and ‘examples’
directories.

The tests must be term-expanded by the ‘lgtunit’ object by compiling the
source files defining the test objects using the option ‘hook(lgtunit)’.
For example:

     | ?- logtalk_load(lgtunit(loader)),
          logtalk_load(tests, [hook(lgtunit)]).

As the term-expansion mechanism applies to all the contents of a source
file, the source files defining the test objects should preferably not
contain entities other than the test objects.  Additional code necessary
for the tests should go to separate files.  In general, the tests
themselves can be compiled in 'optimized' mode.  Assuming that’s the
case, also use the ‘optimize(on)’ compiler option for faster execution.

The term-expansion performed by the ‘lgtunit’ object sets the test
object ‘source_data’ flag to ‘on’ and the ‘context_switching_calls’ flag
to ‘allow’ for code coverage and debugging support.  But these settings
can always be overridden in the test objects.

The ‘samples/tester-sample.lgt’ file (at the root of the Logtalk
distribution) exemplifies how to compile and load ‘lgtunit’ tool, the
source code under testing, the unit tests, and how to automatically run
all the tests after loading:

     :- initialization((
         % minimize compilation reports to the essential ones (errors and warnings)
         set_logtalk_flag(report, warnings),
         % load any necessary library files for your application; for example
         logtalk_load(basic_types(loader)),
         % load the unit test tool
         logtalk_load(lgtunit(loader)),
         % load your application files (e.g., "source.lgt") enabling support for
         % code coverage, which requires compilation in debug mode and collecting
         % source data information; if code coverage is not required, remove the
         % "debug(on)" option for faster execution
         logtalk_load(source, [source_data(on), debug(on)]),
         % compile the unit tests file expanding it using "lgtunit" as the hook
         % object to preprocess the tests; if you have failing tests, add the
         % option debug(on) to debug them (see "tools/lgtunit/NOTES.md" for
         % debugging advice); tests should be loaded after the code being tested
         % is loaded to avoid warnings such as references to unknown entities
         logtalk_load(tests, [hook(lgtunit)]),
         % run all the unit tests; assuming your tests object is named "tests"
         tests::run
     )).

You may copy this sample file to a ‘tester.lgt’ file in your project
directory and edit it to load your project and test files.  The
‘logtalk_tester’ testing automation script defaults to looking for test
driver files named ‘tester.lgt’ or ‘tester.logtalk’ (if you have
work-in-progress test sets that you don’t want to run by default, simply
use a different file name such as ‘tester_wip.lgt’; you can still run
them automated by using ‘logtalk_tester -n tester_wip’).

Debugged test sets should preferably be compiled in optimal mode,
specially when containing deterministic tests and when using the utility
benchmarking predicates.

Assuming a ‘tester.lgt’ driver file as exemplified above, the tests can
be run by simply loading this file:

     | ?- logtalk_load(tester).

Assuming your test object is named ‘tests’, you can re-run the tests by
typing:

     | ?- tests::run.

You can also re-run a single test (or a list of tests) using the ‘run/1’
predicate:

     | ?- tests::run(test_identifier).

When testing complex 'units', it is often desirable to split the tests
between several test objects or use parametric test objects to be able
to run the same tests using different parameters (e.g., different data
sets or alternative implementations of the same protocol).  In this
case, you can run all test subsets using the goal:

     | ?- lgtunit::run_test_sets([test_set_1, test_set_2, ...]).

where the ‘run_test_sets/1’ predicate argument is a list of two or more
test object identifiers.  This predicate makes it possible to get a
single code coverage report that takes into account all the tests.

It’s also possible to automatically run loaded tests when using the
‘make’ tool by calling the goal that runs the tests from a definition of
the hook predicate ‘logtalk_make_target_action/1’.  For example, by
adding to the tests ‘tester.lgt’ driver file the following code:

     % integrate the tests with logtalk_make/1
     :- multifile(logtalk_make_target_action/1).
     :- dynamic(logtalk_make_target_action/1).

     logtalk_make_target_action(check) :-
         tests::run.

Alternatively, you can define the predicate ‘make/1’ inside the test set
object.  For example:

     :- object(tests, extends(lgtunit)).

         make(check).
         ...

     :- end_object.

This clause will cause all tests to be run when calling the
‘logtalk_make/1’ predicate with the target ‘check’ (or its top-level
shortcut, ‘{?}’).  The other possible target is ‘all’ (with top-level
shortcut ‘{*}’).

Note that you can have multiple test driver files.  For example, one
driver file that runs the tests collecting code coverage data and a
quicker driver file that skips code coverage and compiles the code to be
tested in optimized mode.


File: TheLogtalkHandbook-3.101.0.info,  Node: Automating running tests,  Next: Parametric test objects,  Prev: Writing and running tests,  Up: lgtunit

5.13.6 Automating running tests
-------------------------------

You can use the ‘scripts/logtalk_tester.sh’ Bash shell script or the
‘scripts/logtalk_tester.ps1’ PowerShell script for automating running
unit tests (e.g., from a CI/CD pipeline).  When using one of the Logtalk
installers, the ‘.sh’ extension can usually be omitted.  For example,
assuming your current directory (or sub-directories) contains one or
more ‘tester.lgt’ files:

     $ logtalk_tester -p gnu

The only required argument is the identifier of the backend Prolog
system.  For other options, see the ‘scripts/NOTES.md’ file or type:

     $ logtalk_tester -h

On POSIX systems, you can also access extended documentation by
consulting the script man page:

     $ man logtalk_tester

The scripts support the same set of options.  But the option for passing
additional arguments to the tests uses different syntax.  For example:

     $ logtalk_tester -p gnu -- foo bar baz

     PS> logtalk_tester -p gnu -a foo,bar,baz

On POSIX systems, assuming Logtalk was installed using one of the
provided installers or installation scripts, there is also a ‘man’ page
for the script:

     $ man logtalk_tester

Alternatively, an HTML version of this man page can be found at:

‘https://logtalk.org/man/logtalk_tester.html’

On POSIX systems, the ‘logtalk_tester.sh’ Bash script timeout option
requires either a ‘timeout’ or a ‘gtimeout’ command (provided by the GNU
coreutils package).  The ‘logtalk_tester.ps1’ PowerShell script timeout
option requires that Git for Windows is also installed, as it requires
the GNU timeout command bundled with it.

In addition to using the ‘logtalk_tester.ps1’ PowerShell script, the
Bash shell version of the automation script can also be used in Windows
operating-systems with selected backends by using the Bash shell
included in the Git for Windows installer.  That requires defining a
‘.profile’ file setting the paths to the Logtalk scripts and the Prolog
backend executables.  For example:

     $ cat ~/.profile
     # YAP
     export PATH="/C/Program Files/Yap64/bin":$PATH
     # GNU Prolog
     export PATH="/C/GNU-Prolog/bin":$PATH
     # SWI/Prolog
     export PATH="/C/Program Files/swipl/bin":$PATH
     # ECLiPSe
     export PATH="/C/Program Files/ECLiPSe 7.0/lib/x86_64_nt":$PATH
     # SICStus Prolog
     export PATH="/C/Program Files/SICStus Prolog VC16 4.6.0/bin":$PATH
     # Logtalk
     export PATH="$LOGTALKHOME/scripts":"$LOGTALKHOME/integration":$PATH

The Git for Windows installer also includes GNU ‘coreutils’ and its
‘timeout’ command, which is used by the ‘logtalk_tester’ script ‘-t’
option.

Note that some tests may give different results when run from within the
Bash shell compared with running the tests manually using a Windows GUI
version of the Prolog backend.  Some backends may also not be usable for
automated testing due to the way they are made available as Windows
applications.

Additional advice on testing and on automating testing using continuous
integration servers can be found at:

‘https://logtalk.org/testing.html’


File: TheLogtalkHandbook-3.101.0.info,  Node: Parametric test objects,  Next: Test dialects,  Prev: Automating running tests,  Up: lgtunit

5.13.7 Parametric test objects
------------------------------

Parameterized unit tests can be easily defined by using parametric test
objects.  A typical example is testing multiple implementations of the
same protocol.  In this case, we can use a parameter to pass the
specific implementation being tested.  For example, assume that we want
to run the same set of tests for the library ‘random_protocol’ protocol.
We can write:

     :- object(tests(_RandomObject_),
         extends(lgtunit)).

         :- uses(_RandomObject_, [
             random/1, between/3, member/2,
             ...
         ]).

         test(between_3_in_interval) :-
             between(1, 10, Random),
             1 =< Random, Random =< 10.

         ...

     :- end_object.

We can then test a specific implementation by instantiating the
parameter.  For example:

     | ?- tests(fast_random)::run.

Or use the ‘lgtunit::run_test_sets/1’ predicate to test all the
implementations:

     | ?- lgtunit::run_test_sets([
             tests(backend_random),
             tests(fast_random),
             tests(random)
          ]).


File: TheLogtalkHandbook-3.101.0.info,  Node: Test dialects,  Next: User-defined test dialects,  Prev: Parametric test objects,  Up: lgtunit

5.13.8 Test dialects
--------------------

Multiple test 'dialects' are supported by default.  See the next section
on how to define your own test dialects.  In all dialects, a 'ground
callable term', usually an atom, is used to uniquely identify a test.
This simplifies reporting failed tests and running tests selectively.
An error message is printed if invalid or duplicated test identifiers
are found.  These errors must be corrected; otherwise the reported test
results can be misleading.  Ideally, tests should have descriptive names
that clearly state the purpose of the test and what is being tested.

Unit tests can be written using any of the following predefined
dialects:

     test(Test) :- Goal.

This is the most simple dialect, allowing the specification of tests
that are expected to succeed.  The argument of the ‘test/1’ predicate is
the test identifier, which must be unique.  A more versatile dialect is:

     succeeds(Test) :- Goal.
     deterministic(Test) :- Goal.
     fails(Test) :- Goal.
     throws(Test, Ball) :- Goal.
     throws(Test, Balls) :- Goal.

This is a straightforward dialect.  For ‘succeeds/1’ tests, ‘Goal’ is
expected to succeed.  For ‘deterministic/1’ tests, ‘Goal’ is expected to
succeed once without leaving a choice-point.  For ‘fails/1’ tests,
‘Goal’ is expected to fail.  For ‘throws/2’ tests, ‘Goal’ is expected to
throw the exception term ‘Ball’ or one of the exception terms in the
list ‘Balls’.  The specified exception must subsume the actual exception
for the test to succeed.

An alternative test dialect that can be used with more expressive power
is:

     test(Test, Outcome) :- Goal.

The possible values of the outcome argument are:

   - 
          ‘true’
          The test is expected to succeed.

   - 
          ‘true(Assertion)’
          The test is expected to succeed and satisfy the ‘Assertion’ goal.

   - 
          ‘deterministic’
          The test is expected to succeed once without leaving a choice-point.

   - 
          ‘deterministic(Assertion)’
          The test is expected to succeed once without leaving a choice-point and satisfy the ‘Assertion’ goal.

   - 
          ‘subsumes(Expected, Result)’
          The test is expected to succeed by binding ‘Result’ to a term that is subsumed by the ‘Expected’ term.

   - 
          ‘variant(Term1, Term2)’
          The test is expected to succeed by binding ‘Term1’ to a term that is a variant of the ‘Term2’ term.

   - 
          ‘exists(Assertion)’
          A solution exists for the test goal that satisfies the ‘Assertion’ goal.

   - 
          ‘all(Assertion)’
          All test goal solutions satisfy the ‘Assertion’ goal.

   - 
          ‘fail’
          The test is expected to fail.

   - 
          ‘false’
          The test is expected to fail.

   - 
          ‘error(Error)’
          The test is expected to throw the exception term ‘error(ActualError, _)’ where ‘ActualError’ is subsumed ‘Error’.

   - 
          ‘errors(Errors)’
          The test is expected to throw an exception term ‘error(ActualError, _)’ where ‘ActualError’ is subsumed by an element of the list ‘Errors’.

   - 
          ‘ball(Ball)’
          The test is expected to throw the exception term ‘ActualBall’ where ‘ActualBall’ is subsumed ‘Ball’.

   - 
          ‘balls(Balls)’
          The test is expected to throw an exception term ‘ActualBall’ where ‘ActualBall’ is subsumed by an element of the list ‘Balls’.

In the case of the ‘true(Assertion)’, ‘deterministic(Assertion)’, and
‘all(Assertion)’ outcomes, a message that includes the assertion goal is
printed for assertion failures and errors to help to debug failed unit
tests.  Same for the ‘subsumes(Expected, Result)’ and ‘variant(Term1,
Term2)’ assertions.  Note that this message is only printed when the
test goal succeeds, as its failure will prevent the assertion goal from
being called.  This allows distinguishing between test goal failure and
assertion failure.

Note that the ‘all(Assertion)’ outcome simplifies pinpointing which test
goal solution failed the assertion.  See also the section below on
testing non-deterministic predicates.

The ‘fail’ and ‘false’ outcomes are better reserved for cases where
there is a single test goal.  With multiple test goals, the test will
succeed when 'any' of those goals fail.

Some tests may require individual condition, setup, or cleanup goals.
In this case, the following alternative test dialect can be used:

     test(Test, Outcome, Options) :- Goal.

The currently supported options are (non-recognized options are
ignored):

   - 
          ‘condition(Goal)’
          Condition for deciding if the test should be run or skipped (default goal is ‘true’).

   - 
          ‘setup(Goal)’
          Setup goal for the test (default goal is ‘true’).

   - 
          ‘cleanup(Goal)’
          Cleanup goal for the test (default goal is ‘true’).

   - 
          ‘flaky’
          Declare the test as a flaky test.

   - 
          ‘note(Term)’
          Annotation to print (between parentheses by default) after the test result (default is ‘''’); the annotation term can share variables with the test goal, which can be used to pass additional information about the test result.

Also supported is QuickCheck testing, where random tests are
automatically generated and run given a predicate mode template with
type information for each argument (see the section below for more
details):

     quick_check(Test, Template, Options).
     quick_check(Test, Template).

The valid options are the same as for the ‘test/3’ dialect plus all the
supported QuickCheck specific options (see the QuickCheck section below
for details).

For examples of how to write unit tests, check the ‘tests’ folder or the
‘testing’ example in the ‘examples’ folder in the Logtalk distribution.
Most of the provided examples also include unit tests, some of them with
code coverage.


File: TheLogtalkHandbook-3.101.0.info,  Node: User-defined test dialects,  Next: QuickCheck,  Prev: Test dialects,  Up: lgtunit

5.13.9 User-defined test dialects
---------------------------------

Additional test dialects can be easily defined by extending the
‘lgtunit’ object and by term-expanding the new dialect into one of the
default dialects.  As an example, suppose that you want a dialect where
you can simply write a file with tests defined by clauses using the
format:

     test_identifier :-
         test_goal.

First, we define an expansion for this file into a test object:

     :- object(simple_dialect,
         implements(expanding)).

         term_expansion(begin_of_file, [(:- object(tests,extends(lgtunit)))]).
         term_expansion((Head :- Body), [test(Head) :- Body]).
         term_expansion(end_of_file, [(:- end_object)]).

     :- end_object.

Then we can use this hook object to expand and run tests written in this
dialect by using a ‘tester.lgt’ driver file with contents such as:

     :- initialization((
         set_logtalk_flag(report, warnings),
         logtalk_load(lgtunit(loader)),
         logtalk_load(hook_flows(loader)),
         logtalk_load(simple_dialect),
         logtalk_load(tests, [hook(hook_pipeline([simple_dialect,lgtunit]))]),
         tests::run
     )).

The hook pipeline first applies our ‘simple_dialect’ expansion, followed
by the default ‘lgtunit’ expansion.  This solution allows other hook
objects (e.g., required by the code being tested) to also be used by
updating the pipeline.


File: TheLogtalkHandbook-3.101.0.info,  Node: QuickCheck,  Next: Skipping tests,  Prev: User-defined test dialects,  Up: lgtunit

5.13.10 QuickCheck
------------------

QuickCheck was originally developed for Haskell.  Implementations for
several other programming languages soon followed.  QuickCheck provides
support for 'property-based testing'.  The idea is to express properties
that predicates must comply with and automatically generate tests for
those properties.  The ‘lgtunit’ tool supports both ‘quick_check/2-3’
test dialects, as described above, and ‘quick_check/1-3’ public
predicates for interactive use:

     quick_check(Template, Result, Options).
     quick_check(Template, Options).
     quick_check(Template).

The following options are supported:

   - ‘n/1’: number of random tests that will be generated and run
     (default is 100).

   - ‘s/1’: maximum number of shrink operations when a counter-example
     is found (default is 64).

   - ‘ec/1’: boolean option deciding if type edge cases are tested
     before generating random tests (default is ‘true’).

   - ‘rs/1’: starting seed to be used when generating the random tests
     (no default).

   - ‘pc/1’: pre-condition closure for generated tests (extended with
     the test arguments; no default).

   - ‘l/1’: label closure for classifying the generated tests (extended
     with the test arguments plus the label argument; no default).

   - ‘v/1’: boolean option for verbose reporting of generated random
     tests (default is ‘false’).

   - ‘pb/2’: progress bar option for executed random tests when the
     verbose option is false (first argument is a boolean, default is
     ‘false’; second argument is the tick number, a positive integer).

The ‘quick_check/1’ predicate uses the default option values.  The
‘quick_check/1-2’ predicates print the test results and are thus better
reserved for testing at the top-level interpreter.  The ‘quick_check/3’
predicate returns results in reified form:

   - ‘passed(SequenceSeed, Discarded, Labels)’

   - ‘failed(Goal, SequenceSeed, TestSeed)’

   - ‘error(Error, Goal, SequenceSeed, TestSeed)’

   - ‘broken(Why, Culprit)’

The ‘broken(Why, Culprit)’ result only occurs when the user-defined
testing setup is broken.  For example, a non-callable template (e.g., a
non-existing predicate), an invalid option, a problem with the
pre-condition closure or with the label closure (e.g., a pre-condition
that always fails or a label that fails to classify a generated test),
or errors/failures when generating tests (e.g., due to an unknown type
being used in the template or a broken custom type arbitrary value
generator).

The ‘Goal’ argument is the random test that failed.

The ‘SequenceSeed’ argument is the starting seed used to generate the
sequence of random tests.  The ‘TestSeed’ is the seed used to generate
the test that failed.  Both seeds should be regarded as opaque terms.
When the test seed is equal to the sequence seed, this means that the
failure or error occurred while using only type edge cases.  See below
how to use the seeds when testing bug fixes.

The ‘Discarded’ argument returns the number of generated tests that were
discarded for failing to comply with a pre-condition specified using the
‘pc/1’ option.  This option is specially useful when constraining or
enforcing a relation between the generated arguments and is often used
as an alternative to define a custom type.  For example, if we define
the following predicate:

     condition(I) :-
         between(0, 127, I).

We can then use it to filter the generated tests:

     | ?- lgtunit::quick_check(integer(+byte), [pc(condition)]).
     % 100 random tests passed, 94 discarded
     % starting seed: seed(416,18610,17023)
     yes

The ‘Labels’ argument returns a list of pairs ‘Label-N’ where ‘N’ is the
number of generated tests that are classified as ‘Label’ by a closure
specified using the ‘l/1’ option.  For example, assuming the following
predicate definition:

     label(I, Label) :-
         (   I mod 2 =:= 0 ->
             Label = even
         ;   Label = odd
         ).

We can try:

     | ?- lgtunit::quick_check(integer(+byte), [l(label), n(10000)]).
     % 10000 random tests passed, 0 discarded
     % starting seed: seed(25513,20881,16407)
     % even: 5037/10000 (50.370000%)
     % odd: 4963/10000 (49.630000%)
     yes

The label statistics are key to verifying that the generated tests
provide the necessary coverage.  The labeling predicates can return a
single test label or a list of test labels.  Labels should be ground and
are typically atoms.  To examine the generated tests themselves, you can
use the verbose option, ‘v/1’.  For example:

     | ?- lgtunit::quick_check(integer(+integer), [v(true), n(7), pc([I]>>(I>5))]).
     % Discarded: integer(0)
     % Passed:    integer(786)
     % Passed:    integer(590)
     % Passed:    integer(165)
     % Discarded: integer(-412)
     % Passed:    integer(440)
     % Discarded: integer(-199)
     % Passed:    integer(588)
     % Discarded: integer(-852)
     % Discarded: integer(-214)
     % Passed:    integer(196)
     % Passed:    integer(353)
     % 7 random tests passed, 5 discarded
     % starting seed: seed(23671,3853,29824)
     yes

When a counter-example is found, the verbose option also prints the
shrink steps.  For example:

     | ?- lgtunit::quick_check(atom(+atomic), [v(true), ec(false)]).
     % Passed:    atom('dyO=Xv_MX-3b/U4KH U')
     *     Failure:   atom(-198)
     *     Shrinked:  atom(-99)
     *     Shrinked:  atom(-49)
     *     Shrinked:  atom(-24)
     *     Shrinked:  atom(-12)
     *     Shrinked:  atom(-6)
     *     Shrinked:  atom(-3)
     *     Shrinked:  atom(-1)
     *     Shrinked:  atom(0)
     *     quick check test failure (at test 2 after 8 shrinks):
     *       atom(0)
     *     starting seed: seed(3172,9814,20125)
     *     test seed:     seed(7035,19506,18186)
     no

The template can be a ‘(::)/2’, ‘(<<)/2’, or ‘(:)/2’ qualified callable
term.  When the template is an unqualified callable term, it will be
used to construct a goal to be called in the context of the 'sender'
using the ‘(<<)/2’ debugging control construct.  Another simple example
is passing a template that will trigger a failed test (as the
‘random::random/1’ predicate always returns non-negative floats):

     | ?- lgtunit::quick_check(random::random(-negative_float)).
     *     quick check test failure (at test 1 after 0 shrinks):
     *       random::random(0.09230089279334841)
     *     starting seed: seed(3172,9814,20125)
     *     test seed:     seed(3172,9814,20125)
     no

When QuickCheck exposes a bug in the tested code, we can use the
reported counter-example to help diagnose it and fix it.  As tests are
randomly generated, we can use the starting seed reported with the
counter-example to confirm the bug fix by calling the ‘quick_check/2-3’
predicates with the ‘rs(Seed)’ option.  For example, assume the
following broken predicate definition:

     every_other([], []).
     every_other([_, X| L], [X | R]) :-
         every_other(L, R).

The predicate is supposed to construct a list by taking every other
element of an input list.  Cursory testing may fail to notice the bug:

     | ?- every_other([1,2,3,4,5,6], List).
     List = [2, 4, 6]
     yes

But QuickCheck will report a bug with lists with an odd number of
elements with a simple property that verifies that the predicate always
succeeds and returns a list of integers:

     | ?- lgtunit::quick_check(every_other(+list(integer), -list(integer))).
     *     quick check test failure (at test 2 after 0 shrinks):
     *       every_other([0],A)
     *     starting seed: seed(3172,9814,20125)
     *     test seed:     seed(3172,9814,20125)
     no

We could fix this particular bug by rewriting the predicate:

     every_other([], []).
     every_other([H| T], L) :-
         every_other(T, H, L).

     every_other([], X, [X]).
     every_other([_| T], X, [X| L]) :-
         every_other(T, L).

By retesting with the same test seed that uncovered the bug, the same
random test that found the bug will be generated and run again:

     | ?- lgtunit::quick_check(
             every_other(+list(integer), -list(integer)),
             [rs(seed(3172,9814,20125))]
          ).
     % 100 random tests passed, 0 discarded
     % starting seed: seed(3172,9814,20125)
     yes

Still, after verifying the bug fix, is also a good idea to re-run the
tests using the sequence seed instead, as bug fixes sometimes cause
regressions elsewhere.

When retesting using the ‘logtalk_tester’ automation script, the
starting seed can be set using the ‘-r’ option.  For example:

     $ logtalk_tester -r "seed(3172,9814,20125)"

We could now move to other properties that the predicate should comply
with (e.g., all elements in the output list being present in the input
list).  Often, both traditional unit tests and QuickCheck tests are
used, complementing each other to ensure the required code coverage.

Another example using a Prolog module predicate:

     | ?- lgtunit::quick_check(
             pairs:pairs_keys_values(
                 +list(pair(atom,integer)),
                 -list(atom),
                 -list(integer)
             )
          ).
     % 100 random tests passed, 0 discarded
     % starting seed: seed(3172,9814,20125)
     yes

As illustrated by the examples above, properties are expressed using
predicates.  In the most simple cases, that can be the predicate that we
are testing itself.  But, in general, it will be an auxiliary predicate
calling the predicate or predicates being tested and checking properties
that the results must comply with.

The QuickCheck test dialects and predicates take as argument the mode
template for a property, generate random values for each input argument
based on the type information, and check each output argument.  For
common types, the implementation tries first (by default) common edge
cases (e.g., empty atom, empty list, or zero) before generating
arbitrary values.  When the output arguments check fails, the QuickCheck
implementation tries (by default) up to 64 shrink operations of the
counter-example to report a simpler case to help debugging the failed
test.  Edge cases, generating arbitrary terms, and shrinking terms make
use of the library ‘arbitrary’ category via the ‘type’ object (both
entities can be extended by the user by defining clauses for multifile
predicates).

The mode template syntax is the same as that used in the ‘info/2’
predicate directives with an additional notation, ‘{}/1’, for passing
argument values as-is instead of generating random values for these
arguments.  For example, assume that we want to verify the
‘type::valid/2’ predicate, which takes as its first argument a type.
Randomly generating random types would be cumbersome at best but the
main problem is that we need to generate random values for the second
argument according to the first argument.  Using the ‘{}/1’ notation, we
can solve this problem for any specific type, e.g.  integer, by writing:

     | ?- lgtunit::quick_check(type::valid({integer}, +integer)).

We can also test all (ground, i.e.  non-parametric) types with arbitrary
value generators by writing:

     | ?- forall(
             (type::type(Type), ground(Type), type::arbitrary(Type)),
             lgtunit::quick_check(type::valid({Type}, +Type))
          ).

You can find the list of the basic supported types for use in the
template in the API documentation for the library entities ‘type’ and
‘arbitrary’.  Note that other library entities, including third-party or
your own, can contribute with additional type definitions, as both
‘type’ and ‘arbitrary’ entities are user-extensible by defining clauses
for their multifile predicates.

The user can define new types to use in the property mode templates to
use with its QuickCheck tests by defining clauses for the ‘type’ library
object and the ‘arbitrary’ library category multifile predicates.
QuickCheck will use the later to generate arbitrary input arguments and
the former to verify output arguments.  As a toy example, assume that
the property mode template has an argument of type ‘bit’ with possible
values ‘0’ and ‘1’.  We would then need to define:

     :- multifile(type::type/1).
     type::type(bit).

     :- multifile(type::check/2).
     type::check(bit, Term) :-
         once((Term == 0; Term == 1)).

     :- multifile(arbitrary::arbitrary/1).
     arbitrary::arbitrary(bit).

     :- multifile(arbitrary::arbitrary/2).
     arbitrary::arbitrary(bit, Arbitrary) :-
         random::member(Arbitrary, [0, 1]).


File: TheLogtalkHandbook-3.101.0.info,  Node: Skipping tests,  Next: Selecting tests,  Prev: QuickCheck,  Up: lgtunit

5.13.11 Skipping tests
----------------------

A test object can define the ‘condition/0’ predicate (which defaults to
‘true’) to test if some necessary condition for running the tests holds.
The tests are skipped if the call to this predicate fails or generates
an error.

Individual tests that for some reason should be unconditionally skipped
can have the test clause head prefixed with the ‘(-)/1’ operator.  For
example:

     - test(not_yet_ready) :-
         ...

In this case, it’s a good idea to use the ‘test/3’ dialect with a
‘note/1’ option that briefly explains why the test is being skipped.
For example:

     - test(xyz_reset, true, [note('Feature xyz reset not yet implemented')]) :-
         ...

The number of skipped tests is reported together with the numbers of
passed and failed tests.  To skip a test depending on some condition,
use the ‘test/3’ dialect and the ‘condition/1’ option.  For example:

     test(test_id, true, [condition(current_prolog_flag(bounded,true))) :-
         ...

The test is skipped if the condition goal fails or generates an error.
The conditional compilation directives can also be used in alternative,
but note that in this case there will be no report on the number of
skipped tests.


File: TheLogtalkHandbook-3.101.0.info,  Node: Selecting tests,  Next: Checking test goal results,  Prev: Skipping tests,  Up: lgtunit

5.13.12 Selecting tests
-----------------------

While debugging an application, we often want to temporarily run just a
selection of relevant tests.  This is specially useful when running all
the tests slows down and distracts from testing fixes for a specific
issue.  This can be accomplished by prefixing the clause heads of the
selected tests with the ‘(+)/1’ operator.  For example:

     :- object(tests,
         extends(lgtunit)).

         cover(ack).

         test(ack_1, true(Result == 11)) :-
             ack::ack(2, 4, Result).

         + test(ack_2, true(Result == 61)) :-
             ack::ack(3, 3, Result).

         test(ack_3, true(Result == 125)) :-
             ack::ack(3, 4, Result).

     :- end_object.

In this case, only the ‘ack_2’ would run.  Just be careful to remove all
‘(+)/1’ test prefixes when done debugging the issue that prompted you to
run just the selected tests.  After, be sure to run all the tests to
ensure there are no regressions introduced by your fixes.


File: TheLogtalkHandbook-3.101.0.info,  Node: Checking test goal results,  Next: Testing local predicates,  Prev: Selecting tests,  Up: lgtunit

5.13.13 Checking test goal results
----------------------------------

Checking test goal results can be performed using the ‘test/2-3’
supported outcomes such as ‘true(Assertion)’ and
‘deterministic(Assertion)’.  For example:

     test(compare_3_order_less, deterministic(Order == (<))) :-
         compare(Order, 1, 2).

For the other test dialects, checking test goal results can be performed
by calling the ‘assertion/1-2’ utility predicates or by writing the
checking goals directly in the test body.  For example:

     test(compare_3_order_less) :-
         compare(Order, 1, 2),
         ^^assertion(Order == (<)).

or:

     succeeds(compare_3_order_less) :-
         compare(Order, 1, 2),
         Order == (<).

Using assertions is, however, preferable to directly checking test
results in the test body as it facilitates debugging by printing the
unexpected results when the assertions fail.

The ‘assertion/1-2’ utility predicates are also useful for the
‘test/2-3’ dialects when we want to check multiple assertions in the
same test.  For example:

     test(dictionary_clone_4_01, true) :-
         as_dictionary([], Dictionary),
         clone(Dictionary, DictionaryPairs, Clone, ClonePairs),
         empty(Clone),
         ^^assertion(original_pairs, DictionaryPairs == []),
         ^^assertion(clone_pairs, ClonePairs == []).

Ground results can be compared using the standard ‘==/2’ term equality
built-in predicate.  Non-ground results can be compared using the
‘variant/2’ predicate provided by ‘lgtunit’.  The standard
‘subsumes_term/2’ built-in predicate can be used when testing a compound
term structure while abstracting some of its arguments.  Floating-point
numbers can be compared using the ‘=~=/2’, ‘approximately_equal/3’,
‘essentially_equal/3’, and ‘tolerance_equal/4’ predicates provided by
‘lgtunit’.  Using the ‘=/2’ term unification built-in predicate is
almost always an error, as it would mask test goals failing to bind
output arguments.  The ‘lgtunit’ tool implements a linter check for the
use of unification goals in test outcome assertions.  In the rare cases
that a unification goal is intended, wrapping the ‘(=)/2’ goal using the
‘{}/1’ control construct avoids the linter warning.

When the meta-argument of the ‘assertion/1-2’ predicates is call to a
local predicate (in the tests object), you need to call them using the
‘(::)/2’ message-sending control construct instead of the ‘(^^)/2’
'super' call control construct.  This is necessary as 'super' calls
preserve the 'sender', and the tests are implicitly run by the ‘lgtunit’
object sending a message to the tests object.  For example:

     :- uses(lgtunit, [
         assertion/1
     ]).

     test(my_test_id, true) :-
         foo(X, Y),
         assertion(consistent(X, Y)).

     consistent(X, Y) :-
         ...

In this case, the 'sender' is the tests object, and the ‘assertion/1’
meta-predicate will call the local ‘consistent/2’ predicate in the
expected context.


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing local predicates,  Next: Testing non-deterministic predicates,  Prev: Checking test goal results,  Up: lgtunit

5.13.14 Testing local predicates
--------------------------------

The ‘(<<)/2’ debugging control construct can be used to access and test
object local predicates (i.e., predicates without a scope directive).
In this case, make sure that the ‘context_switching_calls’ compiler flag
is set to ‘allow’ for those objects.  This is seldom required, however,
as local predicates are usually auxiliary predicates called by public
predicates and thus tested when testing those public predicates.  The
code coverage support can pinpoint any local predicate clause that is
not being exercised by the tests.


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing non-deterministic predicates,  Next: Testing generators,  Prev: Testing local predicates,  Up: lgtunit

5.13.15 Testing non-deterministic predicates
--------------------------------------------

For testing non-deterministic predicates (with a finite and manageable
number of solutions), you can wrap the test goal using the standard
‘findall/3’ predicate to collect all solutions and check against the
list of expected solutions.  When the expected solutions are a set, use
in alternative the standard ‘setof/3’ predicate.

If you want to check that all solutions of a non-deterministic predicate
satisfy an assertion, use the ‘test/2’ or ‘test/3’ test dialect with the
‘all(Assertion)’ outcome.  For example:

     test(atom_list, all(atom(Item))) :-
         member(Item, [a, b, c]).

See also the next section on testing 'generators'.

If you want to check that a solution exists for a non-deterministic
predicate that satisfies an assertion, use the ‘test/2’ or ‘test/3’ test
dialect with the ‘exists(Assertion)’ outcome.  For example:

     test(at_least_one_atom, exists(atom(Item))) :-
         member(Item, [1, foo(2), 3.14, abc, 42]).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing generators,  Next: Testing input/output predicates,  Prev: Testing non-deterministic predicates,  Up: lgtunit

5.13.16 Testing generators
--------------------------

To test all solutions of a predicate that acts as a 'generator', we can
use either the ‘all/1’ outcome or the ‘forall/2’ predicate as the test
goal with the ‘assertion/2’ predicate called to report details on any
solution that fails the test.  For example:

     test(test_solution_generator, all(test(X,Y,Z))) :-
         generator(X, Y, Z).

or:

     :- uses(lgtunit, [assertion/2]).
     ...

     test(test_solution_generator_2) :-
         forall(
             generator(X, Y, Z),
             assertion(generator(X), test(X,Y,Z))
         ).

While using the ‘all/1’ outcome results in a more compact test
definition, using the ‘forall/2’ predicate allows customizing the
assertion description.  In the example above, we use the ‘generator(X)’
description instead of the ‘test(X,Y,Z)’ description implicit when we
use the ‘all/1’ outcome.


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing input/output predicates,  Next: Suppressing tested predicates output,  Prev: Testing generators,  Up: lgtunit

5.13.17 Testing input/output predicates
---------------------------------------

Extensive support for testing input/output predicates is provided, based
on similar support found on the Prolog conformance testing framework
written by Péter Szabó and Péter Szeredi.

Two sets of predicates are provided, one for testing text input/output
and one for testing binary input/output.  In both cases, temporary files
(possibly referenced by a user-defined alias) are used.  The predicates
allow setting, checking, and cleaning text/binary input/output.  These
predicates are declared as protected and thus called using the ‘(^^/1)’
control construct.

As an example of testing an input predicate, consider the standard
‘get_char/1’ predicate.  This predicate reads a single character (atom)
from the current input stream.  Some test for basic functionality could
be:

     test(get_char_1_01, true(Char == 'q')) :-
         ^^set_text_input('qwerty'),
         get_char(Char).

     test(get_char_1_02, true(Assertion)) :-
         ^^set_text_input('qwerty'),
         get_char(_Char),
         ^^text_input_assertion('werty', Assertion).

As you can see in the above example, the testing pattern consists on
setting the input for the predicate being tested, calling it, and then
checking the results.  It is also possible to work with streams other
than the current input/output streams by using the ‘lgtunit’ predicate
variants that take a stream alias as argument.  For example, when
testing the standard ‘get_char/2’ predicate, we could write:

     test(get_char_2_01, true(Char == 'q')) :-
         ^^set_text_input(in, 'qwerty'),
         get_char(in, Char).

     test(get_char_2_02, true(Assertion)) :-
         ^^set_text_input(in, 'qwerty'),
         get_char(in, _Char),
         ^^text_input_assertion(in, 'werty', Assertion).

Testing output predicates follows a similar pattern by using instead the
‘set_text_output/1-2’ and ‘text_output_assertion/2-3’ predicates.  For
example:

     test(put_char_2_02, true(Assertion)) :-
         ^^set_text_output(out, 'qwert'),
         put_char(out, y),
         ^^text_output_assertion(out, 'qwerty', Assertion).

The ‘set_text_output/1’ predicate diverts only the standard output
stream (to a temporary file) using the standard ‘set_output/1’
predicate.  Most backend Prolog systems also support writing to the de
facto standard error stream.  But there’s no standard solution to divert
this stream.  However, several systems provide a ‘set_stream/2’ or
similar predicate that can be used for stream redirection.  For example,
assume that you wanted to test a backend Prolog system warning when an
‘initialization/1’ directive fails that is written to ‘user_error’.  An
hypothetical test could be:

     test(singletons_warning, true(Assertion)) :-
         ^^set_text_output(''),
         current_output(Stream),
         set_stream(Stream, alias(user_error)),
         consult(broken_file),
         ^^text_output_assertion('WARNING: initialization/1 directive failed', Assertion).

For testing binary input/output predicates, equivalent testing
predicates are provided.  There is also a small set of helper predicates
for dealing with stream handles and stream positions.  For testing with
files instead of streams, testing predicates are provided that allow
creating text and binary files with given contents and check text and
binary files for expected contents.

For more practical examples, check the included tests for Prolog
standard conformance of built-in input/output predicates.


File: TheLogtalkHandbook-3.101.0.info,  Node: Suppressing tested predicates output,  Next: Tests with timeout limits,  Prev: Testing input/output predicates,  Up: lgtunit

5.13.18 Suppressing tested predicates output
--------------------------------------------

Sometimes predicates being tested output text or binary data that, at
best, clutters testing logs and, at worst, can interfere with parsing of
test logs.  If that output itself is not under testing, you can suppress
it by using the goals ‘^^suppress_text_output’ or
‘^^suppress_binary_output’ at the beginning of the tests.  For example:

     test(proxies_04, true(Color == yellow)) :-
         ^^suppress_text_output,
         {circle('#2', Color)}::print.

The ‘suppress_text_output/0’ and ‘suppress_binary_output/0’ predicates
work by redirecting standard output to the operating-system null device.
But the application may also output to e.g.  ‘user_error’ and other
streams.  If this output must also be suppressed, several alternatives
are described next.

Output of expected warnings can be suppressed by turning off the
corresponding linter flags.  In this case, it is advisable to restrict
the scope of the flag value changes as much as possible.

Output of expected compiler errors can be suppressed by defining
suitable clauses for the ‘logtalk::message_hook/4’ hook predicate.  For
example:

     :- multifile(logtalk::message_hook/4).
     :- dynamic(logtalk::message_hook/4).

     % ignore expected domain error
     logtalk::message_hook(compiler_error(_,_,error(domain_error(foo,bar),_)), error, core, _).

In this case, it is advisable to restrict the scope of the clauses as
much as possible to exact exception terms.  For the exact message terms,
see the ‘core_messages’ category source file.  Defining this hook
predicate can also be used to suppress all messages from a given
component.  For example:

     :- multifile(logtalk::message_hook/4).
     :- dynamic(logtalk::message_hook/4).

     logtalk::message_hook(_Message, _Kind, code_metrics, _Tokens).

Note that there’s no portable solution to suppress 'all' output.
However, several systems provide a ‘set_stream/2’ or similar predicate
that can be used for stream redirection.  Check the documentation of the
backend Prolog systems you’re using for details.


File: TheLogtalkHandbook-3.101.0.info,  Node: Tests with timeout limits,  Next: Setup and cleanup goals,  Prev: Suppressing tested predicates output,  Up: lgtunit

5.13.19 Tests with timeout limits
---------------------------------

There’s no portable way to call a goal with a timeout limit.  However,
some backend Prolog compilers provide this functionality:

   - B-Prolog: ‘time_out/3’ built-in predicate

   - ECLiPSe: ‘timeout/3’ and ‘timeout/7’ library predicates

   - XVM: ‘call_with_timeout/2-3’ built-in predicates

   - SICStus Prolog: ‘time_out/3’ library predicate

   - SWI-Prolog: ‘call_with_time_limit/2’ library predicate

   - Trealla Prolog: ‘call_with_time_limit/2’ and ‘time_out/3’ library
     predicates

   - XSB: ‘timed_call/2’ built-in predicate

   - YAP: ‘time_out/3’ library predicate

Logtalk provides a ‘timeout’ portability library implementing a simple
abstraction for those backend Prolog compilers.

The ‘logtalk_tester’ automation script accepts a timeout option that can
be used to set a limit per-test set.


File: TheLogtalkHandbook-3.101.0.info,  Node: Setup and cleanup goals,  Next: Test annotations,  Prev: Tests with timeout limits,  Up: lgtunit

5.13.20 Setup and cleanup goals
-------------------------------

A test object can define ‘setup/0’ and ‘cleanup/0’ goals.  The ‘setup/0’
predicate is called, when defined, before running the object unit tests.
The ‘cleanup/0’ predicate is called, when defined, after running all the
object unit tests.  The tests are skipped when the setup goal fails or
throws an error.  For example:

     cleanup :-
         this(This),
         object_property(This, file(_,Directory)),
         atom_concat(Directory, serialized_objects, File),
         catch(ignore(os::delete_file(File)), _, true).

Per test setup and cleanup goals can be defined using the ‘test/3’
dialect and the ‘setup/1’ and ‘cleanup/1’ options.  The test is skipped
when the setup goal fails or throws an error.  Note that a broken test
cleanup goal doesn’t affect the test but may adversely affect any
following tests.  Variables in the setup and cleanup goals are shared
with the test body.


File: TheLogtalkHandbook-3.101.0.info,  Node: Test annotations,  Next: Test execution times and memory usage,  Prev: Setup and cleanup goals,  Up: lgtunit

5.13.21 Test annotations
------------------------

It’s possible to define per-unit and per-test annotations to be printed
after the test results or when tests are skipped.  This is particularly
useful when some units or some unit tests may be run while still being
developed.  Annotations can be used to pass additional information to a
user reviewing test results.  By intercepting the unit test framework
message printing calls (using the ‘message_hook/4’ hook predicate), test
automation scripts and integrating tools can also access these
annotations.

Units can define a global annotation using the predicate ‘note/1’.  To
define per-test annotations, use the ‘test/3’ dialect and the ‘note/1’
option.  For example, you can inform why a test is being skipped by
writing:

     - test(foo_1, true, [note('Waiting for Deep Thought answer')]) :-
         ...

Another common use is to return the execution time of one of the test
sub-goals.  For example:

     test(foobar, true, [note(bar(seconds-Time))]) :-
         foo(...),
         benchmark(bar(...), Time).

Annotations are written, by default, between parentheses after and in
the same line as the test results.


File: TheLogtalkHandbook-3.101.0.info,  Node: Test execution times and memory usage,  Next: Working with test data files,  Prev: Test annotations,  Up: lgtunit

5.13.22 Test execution times and memory usage
---------------------------------------------

Individual test CPU and wall execution times (in seconds) are reported
by default when running the tests.  Total CPU and wall execution times
for passed and failed tests are reported after the tests complete.
Starting and ending date and time when running a set of tests is also
reported by default.  The ‘lgtunit’ object also provides several public
benchmarking predicates that can be useful for e.g.  reporting test
sub-goals execution times using either CPU or wall clocks.  When running
multi-threaded code, the CPU time may or may not include all threads CPU
time depending on the backend.

Be aware that the accuracy of CPU and wall time depends of the backend.
Accuracy can also be different between CPU and wall time (e.g.  CPU time
can have nanosecond accuracy with wall time only having millisecond
accuracy).

Test memory usage is not reported by default due to the lack of a
portable solution to access memory data.  However, several backend
Prolog systems provide a ‘statistics/2’ or similar predicate that can be
used for a custom solution.  Depending on the system, individual keys
may be provided for each memory area (heap, trail, atom table, …).
Aggregating keys may also be provided.  As a hypothetical example,
assume you’re running Logtalk with a backend providing a ‘statistics/2’
predicate with a ‘memory_used’ key:

     test(ack_3, true(Result == 125), [note(memory-Memory)]) :-
         statistics(memory_used, Memory0),
         ack::ack(3, 4, Result),
         statistics(memory_used, Memory1),
         Memory is Memory1 - Memory0.

Consult the documentation of the backend Prolog systems for actual
details.


File: TheLogtalkHandbook-3.101.0.info,  Node: Working with test data files,  Next: Flaky tests,  Prev: Test execution times and memory usage,  Up: lgtunit

5.13.23 Working with test data files
------------------------------------

Frequently, tests make use of test data files that are usually stored in
the test set directory or in sub-directories.  These data files are
referenced using their relative paths.  But to allow the tests to run
independently of the Logtalk process current directory, the relative
paths often must be expanded into an absolute path before being passed
to the predicates being tested.  The ‘file_path/2’ protected predicate
can be used in the test definitions to expand the relative paths.  For
example:

     % check that the encoding/1 option is accepted
     test(lgt_unicode_open_4_01, true) :-
         ^^file_path(sample_utf_8, Path),
         open(Path, write, Stream, [encoding('UTF-8')]),
         close(Stream).

The absolute path is computed relative to the path of 'self', i.e.
relative to the path of the test object that received the message that
runs the tests.

It’s also common for tests to create temporary files and directories
that should be deleted after the tests completion.  The ‘clean_file/1’
and ‘clean_directory/1’ protected predicates can be used for this
purpose.  For example, assuming that the tests create a ‘foo.txt’ text
file and a ‘tmp’ directory in the same directory as the tests object:

     cleanup :-
         ^^clean_file('foo.txt'),
         ^^clean_directory('tmp').

Similar to the ‘file_path/2’ predicate, relative paths are interpreted
as relative to the path of the test object.  This predicate also closes
any open stream connected to the file before deleting it.


File: TheLogtalkHandbook-3.101.0.info,  Node: Flaky tests,  Next: Mocking,  Prev: Working with test data files,  Up: lgtunit

5.13.24 Flaky tests
-------------------

Flaky tests are tests that pass or fail non-deterministically, usually
due to external conditions (e.g., computer or network load).  Thus,
flaky tests often don’t result from bugs in the code being tested itself
but from test execution conditions that are not predictable.  The
‘flaky/0’ test option declares a test to be flaky.  For example:

     test(foo, true, [flaky]) :-
         ...

For backwards compatibility, the ‘note/1’ annotation can also be used to
alert that a test failure is for a flaky test when its argument is an
atom containing the sub-atom ‘flaky’.

The testing automation support outputs the text ‘[flaky]’ when reporting
failed flaky tests.  Moreover, the ‘logtalk_tester’ automation script
will ignore failed flaky tests when setting its exit status.


File: TheLogtalkHandbook-3.101.0.info,  Node: Mocking,  Next: Debugging messages in tests,  Prev: Flaky tests,  Up: lgtunit

5.13.25 Mocking
---------------

Sometimes the code being tested performs complex tasks that are not
feasible or desirable when running tests.  For example, the code may
perform a login operation requiring the user to provide a username and a
password using some GUI widget.  In this case, the tests may require the
login operation to still be performed but using canned data (also
simplifying testing automation).  I.e.  we want to 'mock' (as in
'imitate') the login procedure.  Ideally, this should be accomplished
without requiring any changes to the code being tested.  Logtalk
provides two solutions that can be used for mocking: 'term-expansion'
and 'hot patching'.  A third solution is possible if the code we want to
mock uses the 'message printing mechanism'.

Using the term-expansion mechanism, we would define a 'hook object' that
expands the login predicate into a fact:

     :- object(mock_login,
         implements(expanding)).

         term_expansion((login(_, _) :- _), login(jdoe, test123)).

     :- end_object.

The tests driver file would then load the application object responsible
for user management using this hook object:

     :- initialization((
         ...,
         logtalk_load(mock_login),
         logtalk_load(user_management, [hook(mock_login)]),
         ...
     )).

Using hot patching, we would define a 'complementing category' patching
the object that defines the login predicate:

     :- category(mock_login,
         complements(user_management)).

         login(jdoe, test123).

     :- end_category.

The tests driver file would then set the ‘complements’ flag to ‘allow’
and load the patch after loading application code:

     :- initialization((
         ...,
         set_logtalk_flag(complements, allow),
         logtalk_load(application),
         logtalk_load(mock_login),
         ...
     )).

There are pros and cons for each solution.  Term-expansion works by
defining hook objects that are used at compile-time, while hot patching
happens at runtime.  Complementing categories can also be dynamically
created, stacked, and abolished.  Hot patching disables static binding
optimizations, but that’s usually not a problem as the code being tested
is often compiled in debug mode to collect code coverage data.  Two
advantages of the term-expansion solution are that it allows defining
conditions for expanding terms and goals and can replace both predicate
definitions and predicate calls.  Limitations in the current Prolog
standards prevent patching callers to local predicates being patched.
But often both solutions can be used, with the choice depending on code
clarity and user preference.  See the Handbook sections on
term-expansion and hot patching for more details on these mechanisms.

In those cases where the code we want to mock uses the message printing
mechanism, the solution is to intercept and rewrite the messages being
printed and/or the questions being asked using the
‘logtalk::message_hook/4’ and ‘logtalk::question_hook/6’ hook
predicates.


File: TheLogtalkHandbook-3.101.0.info,  Node: Debugging messages in tests,  Next: Debugging failed tests,  Prev: Mocking,  Up: lgtunit

5.13.26 Debugging messages in tests
-----------------------------------

Sometimes it is useful to write debugging or logging messages from tests
when running them manually.  But those messages are better suppressed
when running the tests automated.  A common solution is to use debug
'meta-messages'.  For example:

     :- uses(logtalk, [
         print_message(debug, my_app, Message) as dbg(Message)
     ]).

     test(some_test_id, ...) :-
         ...,
         dbg('Some intermediate value'-Value),
         ...,
         dbg([Stream]>>custom_print_goal(Stream, ...)),
         ...

The messages are only printed (and the user-defined printing goals are
only called) when the ‘debug’ flag is turned on.  Note that this doesn’t
require compiling the tests in debug mode: you simply toggle the flag to
toggle the debug messages.  Also note that the ‘print_message/3’ goals
are suppressed by the compiler when compiling with the ‘optimize’ flag
turned on.


File: TheLogtalkHandbook-3.101.0.info,  Node: Debugging failed tests,  Next: Code coverage,  Prev: Debugging messages in tests,  Up: lgtunit

5.13.27 Debugging failed tests
------------------------------

Debugging of failed unit tests is simplified by using test assertions as
the reason for the assertion failures is printed out.  Thus, use
preferably the ‘test/2-3’ dialects with ‘true(Assertion)’,
‘deterministic(Assertion)’, ‘subsumes(Expected, Result)’, or
‘variant(Term1, Term2)’ outcomes.  If a test checks multiple assertions,
you can use the predicate ‘assertion/2’ in the test body.  In the case
of QuickCheck tests, the ‘v(true)’ verbose option can be used to print
the generated test case that failed if necessary.

If the assertion failures don’t provide enough information, you can use
the ‘debugger’ tool to debug failed unit tests.  Start by compiling the
unit test objects and the code being tested in debug mode.  Load the
debugger and trace the test that you want to debug.  For example,
assuming your tests are defined in a ‘tests’ object and that the
identifier of the test to be debugged is ‘test_foo’:

     | ?- logtalk_load(debugger(loader)).
     ...

     | ?- debugger::trace.
     ...

     | ?- tests::run(test_foo).
     ...

You can also compile the code and the tests in debug mode but without
using the ‘hook/1’ compiler option for the tests compilation.  Assuming
that the ‘context_switching_calls’ flag is set to ‘allow’, you can then
use the ‘(<<)/2’ debugging control construct to debug the tests.  For
example, assuming that the identifier of the test to be debugged is
‘test_foo’ and that you used the ‘test/1’ dialect:

     | ?- logtalk_load(debugger(loader)).
     ...

     | ?- debugger::trace.
     ...

     | ?- tests<<test(test_foo).
     ...

In the more complicated cases, it may be worth defining
‘loader_debug.lgt’ and ‘tester_debug.lgt’ driver files that load code
and tests in debug mode and also load the debugger.

When using the ‘logtalk_tester’ automation script, some test sets can be
reported as broken or crashed.  The script creates a logs directory, by
default named ‘logtalk_tester_logs’, in the same directory where the
script was called.  The log files, notably the ‘*.errors’ files, often
contain valuable information for debugging broken and crashed test sets.


File: TheLogtalkHandbook-3.101.0.info,  Node: Code coverage,  Next: Utility predicates,  Prev: Debugging failed tests,  Up: lgtunit

5.13.28 Code coverage
---------------------

If you want entity predicate clause coverage information to be collected
and printed, you will need to compile the entities that you’re testing
using the flags ‘debug(on)’ and ‘source_data(on)’.  Be aware, however,
that compiling in debug mode results in a performance penalty.

A single test object may include tests for one or more entities
(objects, protocols, and categories).  The entities being tested by a
unit test object for which code coverage information should be collected
must be declared using the ‘cover/1’ predicate.  For example, to collect
code coverage data for the objects ‘foo’ and ‘bar’ include in the tests
object the two clauses:

     cover(foo).
     cover(bar).

Code coverage is listed using the predicates clause indexes (counting
from one).  For example, using the ‘points’ example in the Logtalk
distribution:

     % point: default_init_option/1 - 2/2 - (all)
     % point: instance_base_name/1 - 1/1 - (all)
     % point: move/2 - 1/1 - (all)
     % point: position/2 - 1/1 - (all)
     % point: print/0 - 1/1 - (all)
     % point: process_init_option/1 - 1/2 - [1]
     % point: position_/2 - 0/0 - (all)
     % point: 7 out of 8 clauses covered, 87.500000% coverage

The numbers after the predicate indicators represent the clauses covered
and the total number of clauses.  E.g.  for the ‘process_init_option/1’
predicate, the tests cover 1 out of 2 clauses.  After these numbers, we
either get ‘(all)’ telling us that all clauses are covered or a list of
indexes for the covered clauses.  E.g.  only the first clause for the
‘process_init_option/1’ predicate, ‘[1]’.  Summary clause coverage
numbers are also printed for entities and for clauses across all
entities.

In the printed predicate clause coverage information, you may get a
total number of clauses smaller than the covered clauses.  This results
from the use of dynamic predicates with clauses asserted at runtime.
You may easily identify dynamic predicates in the results as their
clauses often have an initial count equal to zero.

The list of indexes of the covered predicate clauses can be quite long.
Some backend Prolog compilers provide a flag or a predicate to control
the depth of printed terms that can be useful:

   - CxProlog: ‘write_depth/2’ predicate

   - ECLiPSe: ‘print_depth’ flag

   - SICStus Prolog: ‘toplevel_print_options’ flag

   - SWI-Prolog 7.1.10 or earlier: ‘toplevel_print_options’ flag

   - SWI-Prolog 7.1.11 or later: ‘answer_write_options’ flag

   - Trealla Prolog: ‘answer_write_options’ flag

   - XSB: ‘set_file_write_depth/1’ predicate

   - XVM 3.2.0 or later: ‘answer_write_options’ flag

   - YAP: ‘write_depth/2-3’ predicates

Code coverage is only available when testing Logtalk code.  But Prolog
modules can often be compiled as Logtalk objects and plain Prolog code
may be wrapped in a Logtalk object.  For example, assuming a ‘module.pl’
module file, we can compile and load the module as an object by simply
calling:

     | ?- logtalk_load(module).
     ...

The module exported predicates become object public predicates.  For a
plain Prolog file, say ‘plain.pl’, we can define a Logtalk object that
wraps the code using an ‘include/1’ directive:

     :- object(plain).

         :- include('plain.pl').

     :- end_object.

The object can also declare as public the top Prolog predicates to
simplify writing the tests.  In alternative, we can use the
‘object_wrapper_hook’ provided by the ‘hook_objects’ library:

     | ?- logtalk_load(hook_objects(loader)).
     ...

     | ?- logtalk_load(plain, [hook(object_wrapper_hook)]).
     ...

These workarounds may thus allow generating code coverage data also for
Prolog code by defining tests that use the ‘(<<)/2’ debugging control
construct to call the Prolog predicates.

See also the section below on exporting code coverage results to XML
files, which can be easily converted and published as e.g.  HTML
reports.


File: TheLogtalkHandbook-3.101.0.info,  Node: Utility predicates,  Next: Exporting test results,  Prev: Code coverage,  Up: lgtunit

5.13.29 Utility predicates
--------------------------

The ‘lgtunit’ tool provides several public utility predicates to
simplify writing unit tests and for general use:

   - 
          ‘variant(Term1, Term2)’
          To check when two terms are a variant of each other (e.g., to check expected test results against actual results when they contain variables).

   - 
          ‘assertion(Goal)’
          To generate an exception in case the goal argument fails or throws an error.

   - 
          ‘assertion(Description, Goal)’
          To generate an exception in case the goal argument fails or throws an error (the first argument allows assertion failures to be distinguished when using multiple assertions).

   - 
          ‘approximately_equal(Number1, Number2)’
          For number approximate equality using the ‘epsilon’ arithmetic constant value.

   - 
          ‘approximately_equal(Number1, Number2, Epsilon)’
          For number approximate equality. Weaker equality than essential equality.

   - 
          ‘essentially_equal(Number1, Number2, Epsilon)’
          For number essential equality. Stronger equality than approximate equality.

   - 
          ‘tolerance_equal(Number1, Number2, RelativeTolerance, AbsoluteTolerance)’
          For number equality within tolerances.

   - 
          ‘Number1 =~= Number2’
          For number (or list of numbers) close equality (usually floating-point numbers).

   - 
          ‘benchmark(Goal, Time)’
          For timing a goal.

   - 
          ‘benchmark_reified(Goal, Time, Result)’
          Reified version of ‘benchmark/2’.

   - 
          ‘benchmark(Goal, Repetitions, Time)’
          For finding the average time to prove a goal.

   - 
          ‘benchmark(Goal, Repetitions, Clock, Time)’
          For finding the average time to prove a goal using a ‘cpu’ or a ‘wall’ clock.

   - 
          ‘deterministic(Goal)’
          For checking that a predicate succeeds without leaving a choice-point.

   - 
          ‘deterministic(Goal, Deterministic)’
          Reified version of the ‘deterministic/1’ predicate.

The ‘assertion/1-2’ predicates can be used in the body of tests where
using two or more assertions is convenient or in the body of tests
written using the ‘test/1’, ‘succeeds/1’, and ‘deterministic/1’ dialects
to help differentiate between the test goal and checking the test goal
results and to provide more informative test failure messages.

When the assertion, benchmarking, and deterministic meta-predicates call
a local predicate of the tests object, you must call them using an
implicit or explicit message instead of using a 'super' call.  For
example, to use an implicit message to call the ‘assertion/1-2’
meta-predicates, add the following directive to the tests object:

     :- uses(lgtunit, [assertion/1, assertion/2]).

The reason this is required is that meta-predicates goals arguments are
always called in the context of the 'sender', which would be the
‘lgtunit’ object in the case of a ‘(^^)/2’ call (as it preserves both
'self' and 'sender' and the tests are internally run by a message sent
from the ‘lgtunit’ object to the tests object).

As the ‘benchmark/2-4’ predicates are meta-predicates, turning on the
‘optimize’ compiler flag is advised to avoid runtime compilation of the
meta-argument, which would add an overhead to the timing results.  But
this advice conflicts with collecting code coverage data, which requires
compilation in debug mode.  The solution is to use separate test objects
for benchmarking and for code coverage.  Note that the CPU and wall
execution times (in seconds) for each individual test are reported by
default when running the tests.

The ‘(=~=)/2’ predicate is typically used by adding the following
directive to the object (or category) calling it:

     :- uses(lgtunit, [
         op(700, xfx, =~=), (=~=)/2
     ]).

Consult the ‘lgtunit’ object API documentation for more details on these
predicates.


File: TheLogtalkHandbook-3.101.0.info,  Node: Exporting test results,  Next: Generating Allure reports,  Prev: Utility predicates,  Up: lgtunit

5.13.30 Exporting test results
------------------------------

* Menu:

* xUnit XML format::
* TAP output format::
* CTRF JSON format::
* Subunit formats::


File: TheLogtalkHandbook-3.101.0.info,  Node: xUnit XML format,  Next: TAP output format,  Up: Exporting test results

5.13.30.1 xUnit XML format
..........................

To output test results in the xUnit XML format (from JUnit; see e.g.
‘https://github.com/windyroad/JUnit-Schema’ or
‘https://llg.cubic.org/docs/junit/’), simply load the ‘xunit_output.lgt’
file before running the tests.  This file defines an object,
‘xunit_output’, that intercepts and rewrites unit test execution
messages, converting them to the xUnit XML format.

To export the test results to a file using the xUnit XML format, simply
load the ‘xunit_report.lgt’ file before running the tests.  A file named
‘xunit_report.xml’ will be created in the same directory as the object
defining the tests.  When running a set of test suites as a single
unified suite (using the ‘run_test_sets/1’ predicate), the single xUnit
report is created in the directory of the first test suite object in the
set.

To use the xUnit.net v2 XML format
(‘https://xunit.net/docs/format-xml-v2’), load either the
‘xunit_net_v2_output.lgt’ file or the ‘xunit_net_v2_report.lgt’ file.

When using the ‘logtalk_tester’ automation script, use either the ‘-f
xunit’ option or the ‘-f xunit_net_v2’ option to generate the
‘xunit_report.xml’ files in the test set directories.

There are several third-party xUnit report converters that can generate
HTML files for easy browsing.  For example:

   - ‘https://allurereport.org/docs/’ (supports multiple reports)

   - ‘https://github.com/Zir0-93/xunit-to-html’ (supports multiple test
     sets in a single report)

   - ‘https://www.npmjs.com/package/xunit-viewer’

   - ‘https://github.com/JatechUK/NUnit-HTML-Report-Generator’

   - ‘https://plugins.jenkins.io/xunit’


File: TheLogtalkHandbook-3.101.0.info,  Node: TAP output format,  Next: CTRF JSON format,  Prev: xUnit XML format,  Up: Exporting test results

5.13.30.2 TAP output format
...........................

To output test results in the TAP (Test Anything Protocol) format,
simply load the ‘tap_output.lgt’ file before running the tests.  This
file defines an object, ‘tap_output’, that intercepts and rewrites unit
test execution messages, converting them to the TAP output format.

To export the test results to a file using the TAP (Test Anything
Protocol) output format, load instead the ‘tap_report.lgt’ file before
running the tests.  A file named ‘tap_report.txt’ will be created in the
same directory as the object defining the tests.

When using the ‘logtalk_tester’ automation script, use the ‘-f tap’
option to generate the ‘tap_report.xml’ files in the test set
directories.

When using the ‘test/3’ dialect with the TAP format, a ‘note/1’ option
whose argument is an atom starting with a ‘TODO’ or ‘todo’ word results
in a test report with a TAP TODO directive.

When running a set of test suites as a single unified suite, the single
TAP report is created in the directory of the first test suite object in
the set.

There are several third-party TAP report converters that can generate
HTML files for easy browsing.  For example:

   - ‘https://github.com/Quobject/tap-to-html’

   - ‘https://plugins.jenkins.io/tap/’


File: TheLogtalkHandbook-3.101.0.info,  Node: CTRF JSON format,  Next: Subunit formats,  Prev: TAP output format,  Up: Exporting test results

5.13.30.3 CTRF JSON format
..........................

To output test results in the CTRF (Common Test Report Format) JSON
format, simply load the ‘ctrf_output.lgt’ file before running the tests.
This file defines an object, ‘ctrf_output’, that intercepts and rewrites
unit test execution messages, converting them to the CTRF JSON format.

To export the test results to a file using the CTRF JSON format, load
instead the ‘ctrf_report.lgt’ file before running the tests.  A file
named ‘ctrf_report.json’ will be created in the same directory as the
object defining the tests.

When using the ‘logtalk_tester’ automation script, use the ‘-f ctrf’
option to generate the ‘ctrf_report.json’ files in the test set
directories.

When running a set of test suites as a single unified suite, the single
CTRF report is created in the directory of the first test suite object
in the set.


File: TheLogtalkHandbook-3.101.0.info,  Node: Subunit formats,  Prev: CTRF JSON format,  Up: Exporting test results

5.13.30.4 Subunit formats
.........................

To output test results in the Subunit v1 text streaming format, simply
load the ‘subunit_v1_output.lgt’ file before running the tests.  This
file defines an object, ‘subunit_v1_output’, that intercepts and
rewrites unit test execution messages, converting them to a Subunit text
stream.

To output test results in the Subunit v2 binary streaming format, load
the ‘subunit_v2_output.lgt’ file before running the tests.  This file
defines an object, ‘subunit_v2_output’, that intercepts and rewrites
unit test execution messages, converting them to Subunit v2 binary
packets.

These adapters write directly to the current output stream and are
intended for piping test execution output to tools that parse Subunit
streams.

To export test results to files using Subunit streaming formats, load
instead the ‘subunit_v1_report.lgt’ file (Subunit text stream) or the
‘subunit_v2_report.lgt’ file (Subunit v2 binary stream) before running
the tests.  Files named ‘subunit_v1_report.txt’ and
‘subunit_v2_report.bin’ are created in the same directory as the object
defining the tests.


File: TheLogtalkHandbook-3.101.0.info,  Node: Generating Allure reports,  Next: Exporting code coverage results,  Prev: Exporting test results,  Up: lgtunit

5.13.31 Generating Allure reports
---------------------------------

A ‘logtalk_allure_report.pl’ Bash shell script and a
‘logtalk_allure_report.ps1’ PowerShell script are provided for
generating Allure reports(1) (version 2.26.0 or later required).  This
requires exporting test results in xUnit XML format.  A simple usage
example (assuming a current directory containing tests):

     $ logtalk_tester -p gnu -f xunit
     $ logtalk_allure_report
     $ allure open

The ‘allure open’ command accepts ‘--host’ and ‘--port’ arguments in
case their default values are not suitable (e.g., when running Logtalk
in a remote host over a SSH connection).

The ‘logtalk_allure_report’ script supports command-line options to pass
the tests directory (i.e., the directory where the ‘logtalk_tester’
script was run), the directory where to collect all the xUnit report
files for generating the report, the directory where the report is to be
saved, and the report title (see the script man page or type
‘logtalk_allure_report -h’).  The script also supports saving the
history of past test runs.  In this case, a persistent location for both
the results and report directories must be used.

It’s also possible to use the script just to collect the xUnit report
files generated by ‘lgtunit’ and delegate the actual generation of the
report to e.g.  an Allure Docker container or to a Jenkins plug-in.  Two
examples are:

   - ‘https://github.com/fescobar/allure-docker-service’

   - ‘https://plugins.jenkins.io/allure-jenkins-plugin/’

In this case, we would use the ‘logtalk_allure_report’ script option to
only perform the preprocessing step:

     $ logtalk_allure_report -p

The script also supports passing 'environment pairs', which are
displayed in the generated Allure reports in the environment pane.  This
feature can be used to pass e.g.  the backend name and the backend
version or git commit hash.  The option syntax differs, however, between
the two scripts.  For example, using the Bash script:

     $ logtalk_allure_report -- Backend='GNU Prolog' Version=1.5.0

Or:

     $ logtalk_allure_report -- Project='Deep Thought' Commit=`git rev-parse --short HEAD`

In the case of the PowerShell script, the pairs are passed comma
separated inside a string:

     PS> logtalk_allure_report -e "Backend='GNU Prolog',Version=1.5.0"

Or:

     PS> logtalk_allure_report -e "Project='Deep Thought',Commit=bf166b6"

To show test run trends in the report (e.g., when running the tests for
each application source code commit), save the processed test results
and the report data to permanent directories.  For example:

     $ logtalk_allure_report \
       -i "$HOME/my_project/allure-results" \
       -o "$HOME/my_project/allure-report"
     $ allure open "$HOME/my_project/allure-report"

Note that (in Allure 2.x) the single file option is not compatible with
run trends.

The generated reports can include links to the tests source code.  This
requires using the ‘logtalk_tester’ shell script option that allows
passing the base URL for those links.  This option needs to be used
together with the option to suppress the tests directory prefix so that
the links can be constructed by appending the tests file relative path
to the base URL. For example, assuming that you want to generate a
report for the tests included in the Logtalk distribution when using the
GNU Prolog backend:

     $ cd $LOGTALKUSER
     $ logtalk_tester \
       -p gnu \
       -f xunit \
       -s "$LOGTALKUSER" \
       -u "https://github.com/LogtalkDotOrg/logtalk3/tree/3e4ea295986fb09d0d4aade1f3b4968e29ef594e"

The use of a git hash in the base URL ensures that the generated links
will always show the exact versions of the tests that were run.  The
links include the line number for the tests in the test files (assuming
that the git repo is stored in a BitBucket, GitHub, or GitLab server).
But note that not all supported backends provide accurate line numbers.

It’s also possible to generate single-file reports.  For example:

     $ logtalk_allure_report -s -t "My Amazing Tests Report"

There are some caveats when generating Allure reports that users must be
aware of.  First, Allure expects test names to be unique across
different tests sets.  If there are two tests with the same name in two
different test sets, only one of them will be reported.  Second, when
using the ‘xunit’ format, dates are reported as MM/DD/YYYY. Finally,
when using the ‘xunit_net_v2’ format, tests are reported in a random
order instead of their run order, and dates are displayed as “unknown”
in the overview page.

   ---------- Footnotes ----------

   (1) https://allurereport.org/docs/


File: TheLogtalkHandbook-3.101.0.info,  Node: Exporting code coverage results,  Next: Automatically creating bug reports at issue trackers,  Prev: Generating Allure reports,  Up: lgtunit

5.13.32 Exporting code coverage results
---------------------------------------

The ‘lgtunit’ tool can export code coverage stats in three formats by
loading the corresponding report object before running tests:

   - ‘coverage_report.lgt’ for a simple XML report
     (‘coverage_report.xml’)

   - ‘cobertura_report.lgt’ for a Cobertura XML report (‘cobertura.xml’)

   - ‘lcov_report.lgt’ for an LCOV report (‘lcov.info’)

When using the ‘logtalk_tester’ automation scripts, select the report
format using the ‘-c’ option with one of the values ‘xml’, ‘cobertura’,
or ‘lcov’ (or ‘none’ to disable code coverage reports).

* Menu:

* Simple XML format::
* Cobertura XML format::
* LCOV format::


File: TheLogtalkHandbook-3.101.0.info,  Node: Simple XML format,  Next: Cobertura XML format,  Up: Exporting code coverage results

5.13.32.1 Simple XML format
...........................

To export code coverage results in simple XML format, load the
‘coverage_report.lgt’ file before running the tests.  A file named
‘coverage_report.xml’ will be created in the same directory as the
object defining the tests.

The XML file can be opened in most web browsers (with the notorious
exception of Google Chrome) by copying to the same directory the
‘coverage_report.dtd’ and ‘coverage_report.xsl’ files found in the
‘tools/lgtunit’ directory (when using the ‘logtalk_tester’ script, these
two files are copied automatically).  In alternative, an XSLT processor
can be used to generate an XHTML file instead of relying on a web
browser for the transformation.  For example, using the popular
‘xsltproc’ processor:

     $ xsltproc -o coverage_report.html coverage_report.xml

On Windows operating-systems, this processor can be installed using e.g.
Chocolatey.  On a POSIX operating-systems (e.g., Linux, macOS, …) use
the system package manager to install it if necessary.

The coverage report can include links to the source code when hosted on
Bitbucket, GitHub, or GitLab.  This requires passing the base URL as the
value for the ‘url’ XSLT parameter.  The exact syntax depends on the
XSLT processor, however.  For example:

     $ xsltproc \
       --stringparam url https://github.com/LogtalkDotOrg/logtalk3/blob/master \
       -o coverage_report.html coverage_report.xml

Note that the base URL should preferably be a permanent link (i.e., it
should include the commit SHA1) so that the links to source code files
and lines remain valid if the source code is later updated.  It’s also
necessary to suppress the local path prefix in the generated
‘coverage_report.xml’ file.  For example:

     $ logtalk_tester -c xml -s $HOME/logtalk/

Alternatively, you can pass the local path prefix to be suppressed to
the XSLT processor (note that the ‘logtalk_tester’ script suppresses the
‘$HOME’ prefix by default):

     $ xsltproc \
       --stringparam prefix logtalk/ \
       --stringparam url https://github.com/LogtalkDotOrg/logtalk3/blob/master \
       -o coverage_report.html coverage_report.xml

If you are using Bitbucket, GitHub, or GitLab hosted on your own
servers, the ‘url’ parameter may not contain a ‘bitbucket’, ‘github’, or
‘gitlab’ string.  In this case, you can use the XSLT parameter ‘host’ to
indicate which service you are running.


File: TheLogtalkHandbook-3.101.0.info,  Node: Cobertura XML format,  Next: LCOV format,  Prev: Simple XML format,  Up: Exporting code coverage results

5.13.32.2 Cobertura XML format
..............................

To export code coverage results in Cobertura XML format, load the
‘cobertura_report.lgt’ file before running the tests.  A file named
‘cobertura.xml’ will be created in the same directory as the object
defining the tests.

When using the ‘logtalk_tester’ automation scripts, use the option:

     $ logtalk_tester -c cobertura


File: TheLogtalkHandbook-3.101.0.info,  Node: LCOV format,  Prev: Cobertura XML format,  Up: Exporting code coverage results

5.13.32.3 LCOV format
.....................

To export code coverage results in LCOV format, load the
‘lcov_report.lgt’ file before running the tests.  A file named
‘lcov.info’ will be created in the same directory as the object defining
the tests.

When using the ‘logtalk_tester’ automation scripts, use the option:

     $ logtalk_tester -c lcov


File: TheLogtalkHandbook-3.101.0.info,  Node: Automatically creating bug reports at issue trackers,  Next: Minimizing test results output,  Prev: Exporting code coverage results,  Up: lgtunit

5.13.33 Automatically creating bug reports at issue trackers
------------------------------------------------------------

To automatically create bug report issues for failed tests in GitHub or
GitLab servers, see the ‘issue_creator’ tool.


File: TheLogtalkHandbook-3.101.0.info,  Node: Minimizing test results output,  Next: Help with warnings,  Prev: Automatically creating bug reports at issue trackers,  Up: lgtunit

5.13.34 Minimizing test results output
--------------------------------------

To minimize the test results output, simply load the
‘minimal_output.lgt’ file before running the tests.  This file defines
an object, ‘minimal_output’, that intercepts and summarizes the unit
test execution messages.


File: TheLogtalkHandbook-3.101.0.info,  Node: Help with warnings,  Next: Known issues<5>,  Prev: Minimizing test results output,  Up: lgtunit

5.13.35 Help with warnings
--------------------------

Load the ‘tutor’ tool to get help with selected warnings printed by the
‘lgtunit’ tool.


File: TheLogtalkHandbook-3.101.0.info,  Node: Known issues<5>,  Prev: Help with warnings,  Up: lgtunit

5.13.36 Known issues
--------------------

Deterministic unit tests are currently not available when using Quintus
Prolog as it lacks built-in support that cannot be sensibly defined in
Prolog.

Parameter variables (‘_VariableName_’) cannot currently be used in the
definition of the ‘condition/1’, ‘setup/1’, and ‘cleanup/1’ test options
when using the ‘test/3’ dialect.  For example, the following condition
will not work:

     test(some_id, true, [condition(_ParVar_ == 42)]) :-
         ...

The workaround is to define an auxiliary predicate called from those
options.  For example:

     test(check_xyz, true, [condition(xyz_condition)]) :-
         ...

     xyz_condition :-
         _ParVar_ == 42.


File: TheLogtalkHandbook-3.101.0.info,  Node: linter,  Next: linter_reporter,  Prev: lgtunit,  Up: Developer Tools

5.14 ‘linter’
=============

Logtalk provides a built-in linter tool that runs automatically when
compiling and loading source files.  The lint warnings are controlled by
a set of flags(1).  The default values for these flags are defined in
the backend Prolog compiler adapter files and can be overridden from a
settings file, from a source file (e.g., a loader file), or from an
entity.  These flags can be set globally using the set_logtalk_flag/2(2)
built-in predicate.  For (source file or entity) local scope, use
instead the set_logtalk_flag/2(3) directive.

The linter flags can be managed as a group using the linter(4)
meta-flag.  See the documentation for details.

Some lint checks are turned off by default, specially when
computationally expensive.  Still, it’s a good idea to turn them on to
check your code on a regular basis (e.g., in CI/CD pipelines).

Note that, in some cases, the linter may generate false warnings due to
source code analysis limitations or special cases that, while valid when
intended, usually result from programming issues.  When a code rewrite
is not a sensible solution to avoid the warning, the workaround is to
turn off as locally as possible the flag that controls the warning.

* Menu:

* Main linter checks::
* Help on linter warnings::
* Extending the linter::
* Linting Prolog modules::
* Linting plain Prolog files::

   ---------- Footnotes ----------

   (1) ../userman/programming.html#programming-flags-lint

   (2) ../refman/predicates/set_logtalk_flag_2.html

   (3) ../refman/directives/set_logtalk_flag_2.html

   (4) ../userman/programming.html#flag-linter


File: TheLogtalkHandbook-3.101.0.info,  Node: Main linter checks,  Next: Help on linter warnings,  Up: linter

5.14.1 Main linter checks
-------------------------

Lint checks include:

   - Missing directives (including scope, meta-predicate, dynamic,
     discontiguous, and multifile directives)

   - Duplicated directives, clauses, and grammar rules

   - Missing predicates (unknown messages plus calls to non-declared and
     non-defined predicates)

   - Calls to declared but not defined static predicates

   - Non-terminals called as predicates (instead of via the ‘phrase/2-3’
     built-in methods)

   - Predicates called as non-terminals (instead of via the ‘call//1’
     built-in method)

   - Non-portable predicate calls, predicate options, arithmetic
     function calls, directives, flags, and flag values

   - Missing arithmetic functions (with selected backends)

   - Suspicious calls (syntactically valid calls that are likely
     semantic errors; e.g.  float comparisons using the standard
     arithmetic comparison operators or comparing numbers using
     unification)

   - Deprecated directives, predicates, arithmetic functions, control
     constructs, and flags

   - References to unknown entities (objects, protocols, categories, or
     modules)

   - Top-level shortcuts used as directives

   - Unification goals that will succeed without binding any variables

   - Unification goals that will succeed by creating a cyclic term

   - Goals that are always true or always false

   - Trivial goal failures (due to no matching predicate clause)

   - Redefined built-in predicates

   - Redefined standard operators

   - Lambda expression unclassified variables and mixed up variables

   - Lambda expression with parameter variables used elsewhere in a
     clause

   - Singleton variables

   - If-then-else and soft cut control constructs without an else part

   - If-then-else and soft cut control constructs where the test is a
     unification between a variable and a ground term

   - Missing parentheses around if-then-else and disjunction control
     constructs in the presence of cuts in the first argument

   - Cuts in clauses for multifile predicates

   - Missing cut in repeat loops

   - Possible non-steadfast predicate definitions

   - Non-tail recursive predicate definitions

   - Redundant calls to control constructs and built-in predicates

   - Calls to all-solutions predicates with existentially qualified
     variables not occurring in the qualified goal

   - Calls to all-solutions predicates with no shared variables between
     template and goal

   - Calls to ‘bagof/3’ and ‘setof/3’ where the goal argument contains
     singleton variables

   - Calls to ‘findall/3’ used to backtrack over all solutions of a goal
     without collecting them

   - Calls to ‘catch/3’ that catch all exceptions

   - Calls to standard predicates that have more efficient alternatives

   - Unsound calls in grammar rules

   - File, entity, predicate, and variable names not following official
     coding guidelines

   - Variable names that differ only on case

   - Clauses whose body is a disjunction (and that can be rewritten as
     multiple clauses per coding guidelines)

   - Naked meta-variables in cut-transparent control constructs

   - Left-recursion in clauses and grammar rules

Additional lint checks are provided by the ‘lgtunit’, ‘lgtdoc’, ‘make’,
and ‘dead_code_scanner’ tools.  For large projects, the data generated
by the ‘code_metrics’ tool may also be relevant in accessing code
quality and suggesting code refactoring candidates.


File: TheLogtalkHandbook-3.101.0.info,  Node: Help on linter warnings,  Next: Extending the linter,  Prev: Main linter checks,  Up: linter

5.14.2 Help on linter warnings
------------------------------

By loading the ‘tutor’ tool, most lint warnings are expanded with
explanations and suggestions on how to fix the reported issues.  See
also the coding guidelines(1) for additional explanations.

   ---------- Footnotes ----------

   (1) https://logtalk.org/coding_style_guidelines.html


File: TheLogtalkHandbook-3.101.0.info,  Node: Extending the linter,  Next: Linting Prolog modules,  Prev: Help on linter warnings,  Up: linter

5.14.3 Extending the linter
---------------------------

Experimental support for extending the linter with user-defined warnings
is available using the logtalk_linter_hook/7(1) multifile hook
predicate.  For example, the ‘format’ and ‘list’ library objects define
this hook predicate to lint calls to the ‘format/2-3’ and ‘append/3’
predicates for common errors and misuses.

   ---------- Footnotes ----------

   (1) ../refman/predicates/logtalk_linter_hook_7.html


File: TheLogtalkHandbook-3.101.0.info,  Node: Linting Prolog modules,  Next: Linting plain Prolog files,  Prev: Extending the linter,  Up: linter

5.14.4 Linting Prolog modules
-----------------------------

This tool can also be applied to Prolog modules that Logtalk is able to
compile as objects.  For example, if the Prolog module file is named
‘module.pl’, try:

     | ?- logtalk_load(module, [source_data(on)]).

Due to the lack of standardization of module systems and the abundance
of proprietary extensions, this solution is not expected to work for all
cases.


File: TheLogtalkHandbook-3.101.0.info,  Node: Linting plain Prolog files,  Prev: Linting Prolog modules,  Up: linter

5.14.5 Linting plain Prolog files
---------------------------------

This tool can also be applied to plain Prolog code.  For example, if the
Prolog file is named ‘code.pl’, simply define an object including its
code:

     :- object(code).
         :- include('code.pl').
     :- end_object.

Save the object to an e.g.  ‘code.lgt’ file in the same directory as the
Prolog file and then load it:

     | ?- logtalk_load(code, [source_data(on)]).

In alternative, use the ‘object_wrapper_hook’ provided by the
‘hook_objects’ library:

     | ?- logtalk_load(hook_objects(loader)).
     ...

     | ?- logtalk_load(code, [hook(object_wrapper_hook), source_data(on)]).

With either wrapping solution, pay special attention to any compilation
warnings that may signal issues that could prevent the plain Prolog from
being fully checked when wrapped by an object.


File: TheLogtalkHandbook-3.101.0.info,  Node: linter_reporter,  Next: make,  Prev: linter,  Up: Developer Tools

5.15 ‘linter_reporter’
======================

This tool intercepts compiler linter warnings and caches them as
machine-readable diagnostics.  These diagnostics can be queried directly
or serialized as a SARIF report using the standalone ‘sarif’ tool.

* Menu:

* API documentation: API documentation<11>.
* Loading: Loading<12>.
* Testing: Testing<10>.
* Usage: Usage<7>.
* Options::


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<11>,  Next: Loading<12>,  Up: linter_reporter

5.15.1 API documentation
------------------------

This tool API documentation is available at:

‘../../apis/library_index.html#linter_reporter’


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<12>,  Next: Testing<10>,  Prev: API documentation<11>,  Up: linter_reporter

5.15.2 Loading
--------------

Load the tool using:

     | ?- logtalk_load(linter_reporter(loader)).
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<10>,  Next: Usage<7>,  Prev: Loading<12>,  Up: linter_reporter

5.15.3 Testing
--------------

To test this tool, load the ‘tester.lgt’ file:

     | ?- logtalk_load(linter_reporter(tester)).

The test suite reuses ‘errors’ example files to exercise representative
built-in linter warnings and validates both the diagnostics API and
standalone SARIF generation in explanation-disabled and
explanation-enabled configurations.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<7>,  Next: Options,  Prev: Testing<10>,  Up: linter_reporter

5.15.4 Usage
------------

After loading the tool, enable collecting linter warnings data using
default options:

     | ?- linter_reporter::enable.
     true.

Or using explicit options:

     | ?- linter_reporter::enable([explanations(true)]).
     true.

Load the code for which you want diagnostics collected:

     | ?- logtalk_load(my_application(loader)).
     ...

Disable further collecting of linter warnings:

     | ?- linter_reporter::disable.
     true.

Query the cached diagnostics directly:

     | ?- linter_reporter::diagnostics(all, Diagnostics).
     ...

Warnings originating in an included file are not always file-scoped.
When the ‘include/1’ directive appears inside an entity, the diagnostic
context can be that entity; otherwise the context is typically the
included file.

Or generate a SARIF report using the standalone ‘sarif’ tool:

     | ?- logtalk_load(sarif(loader)).
     ...

     | ?- sarif::generate(linter_reporter, all, file('./linter_warnings.sarif'), []).
     true.

See the ‘sarif’ tool documentation for more details.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options,  Prev: Usage<7>,  Up: linter_reporter

5.15.5 Options
--------------

   - ‘explanations(Boolean)’ Boolean option accepted by ‘enable/1’.
     When set to ‘true’ (default is ‘false’), the tool enriches warnings
     with explanations from the ‘tutor_explanations’ category provided
     by the ‘tutor’ tool.


File: TheLogtalkHandbook-3.101.0.info,  Node: make,  Next: mutation_testing,  Prev: linter_reporter,  Up: Developer Tools

5.16 ‘make’
===========

Logtalk provides a make tool supporting several targets using the
‘logtalk_make/0-1’ built-in predicates.  Top-level shortcuts for the
targets are also provided.

* Menu:

* API documentation: API documentation<12>.
* Help with warnings: Help with warnings<2>.
* Known issues: Known issues<6>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<12>,  Next: Help with warnings<2>,  Up: make

5.16.1 API documentation
------------------------

To consult the documentation of the ‘logtalk_make/0-1’ built-in
predicates, open in a web browser the links:

   - ‘../refman/predicates/logtalk_make_0.html’

   - ‘../refman/predicates/logtalk_make_1.html’

There is also a user-defined hook predicate that supports defining
additional actions for the make targets (e.g., running tests
automatically on make check or regenerating API documentation on make
documentation):

   - ‘../refman/predicates/logtalk_make_target_action_1.html’


File: TheLogtalkHandbook-3.101.0.info,  Node: Help with warnings<2>,  Next: Known issues<6>,  Prev: API documentation<12>,  Up: make

5.16.2 Help with warnings
-------------------------

Load the ‘tutor’ tool to get help with selected warnings printed by the
‘make’ tool.


File: TheLogtalkHandbook-3.101.0.info,  Node: Known issues<6>,  Prev: Help with warnings<2>,  Up: make

5.16.3 Known issues
-------------------

The implementation of the ‘logtalk_make/0-1’ predicates for the target
‘all’ tries to avoid or minimize compilation warnings due to
out-of-order loading of modified source files by performing a file
topological sort based on the dependencies in the previous versions of
the files.  But it’s always possible that the new versions of the files
bring changes to those dependencies and thus result in compilation
warnings that could possibly be avoided with a different loading order.


File: TheLogtalkHandbook-3.101.0.info,  Node: mutation_testing,  Next: packs,  Prev: make,  Up: Developer Tools

5.17 ‘mutation_testing’
=======================

This tool provides mutation testing support for loaded Logtalk entities.
It’s still under development and breaking changes should be expected.

* Menu:

* API documentation: API documentation<13>.
* Loading: Loading<13>.
* Testing: Testing<11>.
* Features::
* Default mutators::
* Usage: Usage<8>.
* Limitations::
* Options: Options<2>.
* Sampling semantics::
* Defining new mutators::


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<13>,  Next: Loading<13>,  Up: mutation_testing

5.17.1 API documentation
------------------------

This tool API documentation is available at:

‘../../apis/library_index.html#mutation-testing’


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<13>,  Next: Testing<11>,  Prev: API documentation<13>,  Up: mutation_testing

5.17.2 Loading
--------------

This tool can be loaded using the query:

     | ?- logtalk_load(mutation_testing(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<11>,  Next: Features,  Prev: Loading<13>,  Up: mutation_testing

5.17.3 Testing
--------------

To test this tool, load the ‘tester.lgt’ file:

     | ?- logtalk_load(mutation_testing(tester)).

Some tests depend on the availability of the
‘test_files/mutation-testing-report-schema.json’ file.  This file can be
downloaded from:

‘https://github.com/stryker-mutator/mutation-testing-elements’


File: TheLogtalkHandbook-3.101.0.info,  Node: Features,  Next: Default mutators,  Prev: Testing<11>,  Up: mutation_testing

5.17.4 Features
---------------

   - Deterministic mutant discovery per entity predicate directive,
     predicate/non-terminal clause/rule, and mutator.

   - Configurable mutator sets and campaign size limits.

   - Deterministic sampled execution (‘sampling(all|count(N)|rate(R))’
     plus ‘seed/1’).

   - Mutation score computation (killed versus survived mutants).

   - Mutation generation guided by code coverage stats.

   - Threshold gating suitable for CI/CD checks.

   - Exporting of mutation campaign reports in plain text and JSON
     formats.


File: TheLogtalkHandbook-3.101.0.info,  Node: Default mutators,  Next: Usage<8>,  Prev: Features,  Up: mutation_testing

5.17.5 Default mutators
-----------------------

The default mutators are:

   - 
          ‘fail_insertion’
          Inserts failure in the selected predicate/non-terminal rule bodies.

   - 
          ‘body_goal_negation’
          Negates the selected predicate/non-terminal clause behavior.

   - 
          ‘relational_operator_replacement’
          Replaces a relational operator (e.g. ‘>’, ‘<’, ‘@=<’, ‘==’) with a complementary alternative.

   - 
          ‘arithmetic_operator_replacement’
          Replaces an arithmetic operator in selected expressions.

   - 
          ‘truth_literal_flip’
          Flips truth literals (‘true’ <-> ‘fail’) in selected goals.

   - 
          ‘head_arguments_mutation’
          Mutates one compile-time bound head argument using ‘type::mutation/3’.

   - 
          ‘head_arguments_reordering’
          Reorders head arguments (swapping the first two arguments).

   - 
          ‘clauses_reordering’
          Reorders predicate/non-terminal clauses/rules by swapping a clause with its successor.

   - 
          ‘scope_directive_replacement’
          Replaces a matching predicate/non-terminal scope directive visibility with an alternative visibility.

   - 
          ‘predicate_directive_suppression’
          Suppresses a matching predicate/non-terminal directive.

   - 
          ‘uses_directive_resource_deletion’
          Deletes one matching resource from a ‘uses/2’ directive.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<8>,  Next: Limitations,  Prev: Default mutators,  Up: mutation_testing

5.17.6 Usage
------------

Mutation testing 'requires' an existing set of tests for the code being
mutated.  These tests are used to verify if they are able to kill the
generated mutants or if they are too weak allowing the mutants to
survive.

By default, the tool looks for the tests driver file (usually,
‘tester.lgt’) in the directory of the entity, library, or directory
being tested.  If the tests driver file is not found there, the tool
looks into the startup directory of the Logtalk process.

Both the name of the tests driver file and its directory can be set
using the ‘tester_file_name/1’ and ‘tester_directory/1’ options if the
defaults don’t work in your particular case.

In this tool documentation, 'campaign predicates' refers to the
following public predicates:

   - ‘entity/1-2’

   - ‘predicate/2-3’

   - ‘library/1-2’

   - ‘directory/1-2’

These predicates run mutants and report results in one step.

Run mutation testing for one entity using defaults:

     | ?- mutation_testing::entity(my_object).

List generated mutants for one entity:

     | ?- mutation_testing::entity_mutants(my_object, Mutants).

Run with custom options:

     | ?- mutation_testing::entity(my_object, [
         mutators([fail_insertion, body_goal_negation]),
         max_mutations_per_mutator(5),
         sampling(count(100)),
         seed(20260303),
         max_mutators(100),
         threshold(60.0),
         verbose(true),
         print_mutation(true)
     ]).

Run campaigns for all loaded entities from a specific library:

     | ?- mutation_testing::library(core).

Run campaigns for all loaded entities from a specific directory:

     | ?- mutation_testing::directory('/path/to/sources').

Pretty-print a report term using the default text format:

     | ?- mutation_testing::report_entity(my_object, Report, []),
          mutation_testing::format_report(Report).

Suppress report formatting output for campaign predicates:

     | ?- mutation_testing::entity(my_object, [format(none)]).

Execution uses ‘lgtunit’ test sets only.  When using ‘timeout(Timeout)’,
timeout handling is best-effort.

When running mutation campaigns inside another ‘lgtunit’ test run,
per-mutant ‘killed’ versus ‘survived’ classification may be affected by
nested test-run message and event handling.  Campaign summary accounting
remains deterministic.


File: TheLogtalkHandbook-3.101.0.info,  Node: Limitations,  Next: Options<2>,  Prev: Usage<8>,  Up: mutation_testing

5.17.7 Limitations
------------------

   - Mutation points are currently mostly clause-level (one occurrence
     per clause per mutator), except ‘head_arguments_mutation’ which
     creates one occurrence per compile-time bound head argument with
     supported type; internal expression-level candidate enumeration is
     not implemented.

   - Equivalent mutant detection and duplicate mutant pruning are not
     implemented.

   - Built-in mutation apply/revert currently targets loaded source
     entities (objects/categories), not protocols.

   - Nested ‘lgtunit’ runs may affect per-mutant ‘killed’ vs ‘survived’
     status classification.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<2>,  Next: Sampling semantics,  Prev: Limitations,  Up: mutation_testing

5.17.8 Options
--------------

   - 
          ‘exclude_entities(Entities)’
          List of loaded entities to exclude (default ‘[]’).

   - 
          ‘include_entities(Entities)’
          List of loaded entities to include (default ‘[]’ meaning all).

   - 
          ‘max_mutators(Max)’
          Maximum number of discovered mutators to use when ‘mutators/1’ is not explicitly provided (‘all’ or positive integer; default ‘all’).

   - 
          ‘max_mutations_per_mutator(Max)’
          Maximum number of mutations generated per mutator and predicate/non-terminal (‘all’ or positive integer; default ‘5’).

   - 
          ‘mutators(Mutators)’
          Names of the mutators to use. When set to ‘[]’ (default), mutators are auto-discovered and optionally limited by ‘max_mutators/1’.

   - 
          ‘sampling(Sampling)’
          Mutant selection strategy (‘all’, ‘count(N)’, or ‘rate(R)’ where ‘0.0 =< R =< 1.0’; default ‘all’). See below for full details.

   - 
          ‘seed(Seed)’
          Pseudo-random generator seed for reproducible sampling (default ‘123456789’; ignored when ‘sampling(all)’).

   - 
          ‘timeout(Timeout)’
          Maximum time in seconds for each mutant execution (positive number; default ‘300’). Timeout handling is best-effort.

   - 
          ‘threshold(Threshold)’
          Minimum mutation score in range ‘0.0..100.0’ (default ‘0.0’).

   - 
          ‘print_mutation(Boolean)’
          When ‘true’, prints original and mutated terms with source location for mutators (default ‘false’).

   - 
          ‘verbose(Boolean)’
          Print per-mutant test results (default ‘false’).

   - ‘format(Format)’ Controls report formatting output (‘none’, ‘text’,
     or ‘json’; default ‘text’).  When set to ‘text’ or ‘json’, a report
     file is generated automatically for campaign predicates.  The
     ‘json’ format implements the Stryker Mutation Testing Framework
     report format: ‘https://stryker-mutator.io/’

   - ‘report_file_name(FileName)’ Report output file base name or path
     without extension (atom; default ‘mutation_test_report’).  The
     extension is inferred from ‘format/1’ (‘text’ -> ‘.txt’, ‘json’ ->
     ‘.json’).  When not absolute, the file is saved in the tests driver
     directory.

   - 
          ‘tester_file_name(Tester)’
          Name of the tests driver file for the code being tested (default ‘tester.lgt’).

   - 
          ‘tester_directory(Directory)’
          Full path to the directory containing the tests driver file for the code being tested (no default).

   - 
          ‘tester_options(Options)’
          Additional options for the calls to the ‘logtalk_tester’ script that are used to check mutations. Note that the most common options are already covered by explicit options (e.g., ‘timeout/1’). Options without arguments are specified using the corresponding character. Options that take a value are specified using a compound term whose name is the option character and whose single argument is the option value (default ‘[o(quiet)]’). Invalid options are ignored.


File: TheLogtalkHandbook-3.101.0.info,  Node: Sampling semantics,  Next: Defining new mutators,  Prev: Options<2>,  Up: mutation_testing

5.17.9 Sampling semantics
-------------------------

The ‘sampling(Sampling)’ option controls 'which generated mutants are
actually executed' in a mutation campaign.  It is a post-generation
selection step:

  1. Generate candidate mutants for the selected
     entities/predicates/mutators.

  2. Apply ‘sampling(...)’ to select a subset (or all).

  3. Execute only the selected mutants.

Because of this design, ‘sampling(...)’ affects campaign predicates
(‘entity/2’, ‘predicate/3’, ‘library/2’, ‘directory/2’).

The ‘format(Format)’ option affects only campaign predicates that
execute and report in one step (‘entity/2’, ‘predicate/3’, ‘library/2’,
‘directory/2’).  It does not affect the ‘*_mutants’ predicates or the
‘report_*’ predicates, which only compute and return terms.

For campaign predicates, a report file is written automatically unless
‘format(none)’ is used.

For ‘report_library/3’ and ‘report_directory/3’, call
‘format_report/2-3’ explicitly if you want to persist the computed
report term.  A single ‘format_report(..., Report)’ call always
generates a single output document (including JSON).

The ‘mutants/2-3’ predicates are still useful for inspecting the
generated deterministic mutant list itself; they are not
execution/reporting predicates.

* Menu:

* Sampling modes::
* Sampling usage in practice::


File: TheLogtalkHandbook-3.101.0.info,  Node: Sampling modes,  Next: Sampling usage in practice,  Up: Sampling semantics

5.17.9.1 Sampling modes
.......................

   - ‘sampling(all)’ Execute all generated mutants.

   - ‘sampling(count(N))’ Shuffle the generated mutant list and execute
     up to ‘N’ mutants.  If ‘N’ is greater than the total number of
     generated mutants, all mutants are executed.

   - ‘sampling(rate(R))’ Compute ‘round(R * TotalGeneratedMutants)’,
     shuffle the mutant list, and execute that many mutants.  If the
     computed value is greater than the total number of generated
     mutants, all mutants are executed.

The randomization used by ‘count/1’ and ‘rate/1’ is controlled by the
‘seed/1’ option, allowing reproducible selection.


File: TheLogtalkHandbook-3.101.0.info,  Node: Sampling usage in practice,  Prev: Sampling modes,  Up: Sampling semantics

5.17.9.2 Sampling usage in practice
...................................

   - 'Control campaign cost' Run a representative subset when the full
     mutant set is large.

   - 'Trade off speed vs.  confidence' Use smaller samples for quick
     feedback and larger/full runs for stronger confidence before
     release.

   - 'Enable reproducible sampling' With a fixed ‘seed/1’, repeated runs
     with the same generated mutant set and same sampling options select
     the same subset.  When all mutants are executed, (using
     ‘sampling(all)’) changing the seed has no effect on selection.

   - 'Complement other limits' ‘max_mutators/1’ and
     ‘max_mutations_per_mutator/1’ constrain mutant generation;
     ‘sampling/1’ controls execution selection after generation.


File: TheLogtalkHandbook-3.101.0.info,  Node: Defining new mutators,  Prev: Sampling semantics,  Up: mutation_testing

5.17.10 Defining new mutators
-----------------------------

Define a new mutator as parametric object implementing the ‘expanding’
protocol, either the ‘clause_mutator_protocol’ or the
‘directive_mutator_protocol’ marker protocol, and importing the
‘mutator_common’ category:

     :- object(my_mutator(_Entity_, _Predicate_, _TargetIndex_, _Occurrence_, _PrintMutation_),
         implements((expanding, clause_mutator_protocol)),
         imports(mutator_common)).

         % mutate code when loading it using this object as a hook object
         term_expansion(Term, Mutation) :-
             ...

         % compute a term mutation; generate multiple mutations by backtracking
         mutation(Term, Mutation) :-
             ...

         % reset any required internal state
         reset :-
             ...

     :- end_object.

New mutators are found by dynamically looking for objects that conform
to either the ‘clause_mutator_protocol’ or the
‘directive_mutator_protocol’ marker protocols.

For implementation examples, see the default mutators:

   - ‘mutators/fail_insertion.lgt’

   - ‘mutators/body_goal_negation.lgt’

   - ‘mutators/relational_operator_replacement.lgt’

   - ‘mutators/arithmetic_operator_replacement.lgt’

   - ‘mutators/truth_literal_flip.lgt’

   - ‘mutators/head_arguments_mutation.lgt’

   - ‘mutators/head_arguments_reordering.lgt’

   - ‘mutators/clauses_reordering.lgt’

   - ‘mutators/scope_directive_replacement.lgt’


File: TheLogtalkHandbook-3.101.0.info,  Node: packs,  Next: ports_profiler,  Prev: mutation_testing,  Up: Developer Tools

5.18 ‘packs’
============

This tool provides predicates for downloading, installing, upgrading,
and uninstalling third-party libraries and applications, generically
known as 'packs'.  Collections of pack specifications are made available
using 'registries'.  Registries can be local to a system, publicly
shared, or private to a company (e.g., only available in a VPN). There
is no concept of a central registry.  Users can decide which registries
they trust and want to use and add them using their published URLs.  The
tool supports both pack checksums and signatures and takes several steps
to sanitize registry and pack specifications.  As with other Logtalk
developer tools, portability is a main goal.  This tool can be used with
any supported Prolog backend and run on both POSIX and Windows systems.
Moreover, this tool can be used not only for handling Logtalk packs but
also for Prolog only packs, thus providing a solution for sharing
portable resources between multiple systems.

A list of public Logtalk and Prolog pack registries is available at:

‘https://github.com/LogtalkDotOrg/pack-registries’

This tool is in the beta stage of development.  Feedback is most
welcome.

* Menu:

* Requirements: Requirements<5>.
* API documentation: API documentation<14>.
* Loading: Loading<14>.
* Testing: Testing<12>.
* Usage: Usage<9>.
* Programmatic query API::
* Registries and packs storage::
* Virtual environments::
* Lock files::
* Registry specification::
* Registry handling::
* Registry development::
* Pack specification::
* Encrypted packs::
* Signed packs::
* Pack URLs and Single Sign-On::
* Multiple pack versions::
* Pack dependencies::
* Pack portability::
* Pack development::
* Pack handling::
* Pack documentation::
* Pinning registries and packs::
* Testing packs::
* Security considerations::
* Best practices::
* Installing Prolog packs::
* Help with warnings: Help with warnings<3>.
* Known issues: Known issues<7>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Requirements<5>,  Next: API documentation<14>,  Up: packs

5.18.1 Requirements
-------------------

On POSIX systems (Linux, macOS, …), the following shell commands are
required:

   - ‘sha256sum’ (provided by GNU ‘coreutils’)

   - ‘curl’ (default file downloader)

   - ‘wget’ (alternative file downloader)

   - ‘bsdtar’ (provided by ‘libarchive’ or ‘libarchive-tools’)

   - ‘gpg’ (provided by ‘gnupg2’)

   - ‘git’

   - ‘direnv’ (when using virtual environments)

The tool uses ‘bsdtar’ instead of GNU ‘tar’ so that it can uncompress
‘.zip’ archives (‘unzip’ doesn’t provide the desired options that allow
a simple and reliable solution for ignoring the non-predictable name of
the wrapper directory).

On Windows systems, the following shell commands are required:

   - ‘certutil.exe’

   - ‘curl.exe’ (default file downloader)

   - ‘wget.exe’ (alternative file downloader)

   - ‘tar.exe’

   - ‘gpg.exe’

   - ‘git.exe’

   - ‘Set-PsEnv’ (when using virtual environments)

In recent Windows 10 builds, only ‘wget’, ‘gpg’, ‘git’, and ‘Set-PsEnv’
should require installation.  You can download the GnuPG software from:

‘https://www.gnupg.org/’

You can download Git from:

‘https://gitforwindows.org’

You can download Wget from:

‘https://eternallybored.org/misc/wget/’

You can also use Chocolatey to install the commands above:

     > choco install gnupg git wget

To install Set-PsEnv(1) from the PowerShell Gallery:

     PS> Install-Module -Name Set-PsEnv

On macOS systems, Apple bundles both ‘curl’ and BSD ‘tar’ (under the
name ‘tar’; you can simply create a ‘bsdtar’ alias or install a more
recent version).  The required commands can be easily installed using
MacPorts:

     $ sudo port install coreutils wget libarchive gnupg2 git direnv

Or using Homebrew:

     $ brew install coreutils wget libarchive gnupg2 git direnv

On Linux systems, use the distribution’s own package manager to install
any missing command.  For example, in recent Ubuntu versions:

     $ sudo apt update
     $ sudo apt install coreutils curl wget libarchive-tools gnupg2 git direnv

   ---------- Footnotes ----------

   (1) https://github.com/rajivharris/Set-PsEnv


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<14>,  Next: Loading<14>,  Prev: Requirements<5>,  Up: packs

5.18.2 API documentation
------------------------

This tool API documentation is available at:

‘../../apis/library_index.html#packs’


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<14>,  Next: Testing<12>,  Prev: API documentation<14>,  Up: packs

5.18.3 Loading
--------------

This tool can be loaded using the query:

     | ?- logtalk_load(packs(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<12>,  Next: Usage<9>,  Prev: Loading<14>,  Up: packs

5.18.4 Testing
--------------

To run the tool tests, use the query:

     | ?- logtalk_load(packs(tester)).

The tests can be run without interfering with the user packs setup.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<9>,  Next: Programmatic query API,  Prev: Testing<12>,  Up: packs

5.18.5 Usage
------------

The ‘packs’ tool loads at startup all the currently defined registry and
pack specifications (from the registries/packs storage directory; see
below).  When no registry/pack setup exists, a new one is automatically
created.

The tool provides two main objects, ‘registries’ and ‘packs’, for
handling, respectively, registries and packs.  Both objects accept a
‘help/0’ message that describes the most common queries.


File: TheLogtalkHandbook-3.101.0.info,  Node: Programmatic query API,  Next: Registries and packs storage,  Prev: Usage<9>,  Up: packs

5.18.6 Programmatic query API
-----------------------------

Besides the user-facing predicates that print information (e.g.,
‘describe/1-2’), the ‘packs’ object also provides a query API intended
for programmatic use by tools and tests.  This API exposes resolved
installed-pack metadata and current-session load participation as data
instead of formatted text.

The main predicates are:

   - ‘pack_metadata/4’

   - ‘pack_property/4’

   - ‘pack_object/3’

   - ‘loaded_pack/3’

   - ‘loaded_pack_file/4’

   - ‘pack_dependency/6’

   - ‘loaded_pack_dependency/6’

The ‘pack_metadata/4’ predicate enumerates installed packs and returns a
resolved metadata term with the shape:

     metadata(Name, Description, License, Home, SourceURL, Checksum, Dependencies, Portability, Directory, Pinned, Installed, Loaded)

The term combines metadata declared by the pack specification object
with the metadata selected from the installed version.  Missing optional
metadata is normalized to ‘none’.  The ‘Installed’ field is always
‘true’ on success.  The ‘Loaded’ field reports if the installed pack
contributed at least one currently loaded file to the session.

For example:

     | ?- packs::pack_metadata(Registry, Pack, Version, Metadata).
     ...

The ‘pack_property/4’ predicate provides selective access to resolved
metadata using property terms.  Supported properties are:

   - ‘name(Name)’

   - ‘description(Description)’

   - ‘license(License)’

   - ‘home(Home)’

   - ‘source_url(URL)’

   - ‘checksum(Checksum)’

   - ‘dependencies(Dependencies)’

   - ‘portability(Portability)’

   - ‘directory(Directory)’

   - ‘pinned(Boolean)’

   - ‘installed(Boolean)’

   - ‘loaded(Boolean)’

For example:

     | ?- packs::pack_property(local_1_d, foo, Version, license(License)).
     License = 'Apache-2.0'.

The ‘pack_object/3’ predicate is a low-level bridge that returns the
pack specification object implementing the ‘pack_protocol’ for a given
registry and pack.  Most clients should prefer ‘pack_metadata/4’ or
‘pack_property/4’ unless direct access to the pack object is required.

For example:

     | ?- packs::pack_object(local_1_d, foo, PackObject).
     PackObject = foo_pack.

The ‘loaded_pack/3’ and ‘loaded_pack_file/4’ predicates expose
current-session pack participation.  A pack is considered loaded iff at
least one currently loaded file belongs to its installation directory.
The first predicate is the high-level query, while the second predicate
can be used to inspect the files that justify that status.

For example:

     | ?- packs::loaded_pack(Registry, Pack, Version).
     ...

     | ?- packs::loaded_pack_file(Registry, Pack, Version, File).
     ...

The ‘pack_dependency/6’ predicate enumerates resolved direct
pack-to-pack dependencies for installed pack versions using the same
version comparison and dependency selection semantics used by the
installation logic.  Version ranges, alternatives, and conjunctions are
resolved canonically.  Non-pack dependencies on Logtalk, Prolog
backends, and operating systems are ignored by this predicate.

For example:

     | ?- packs::pack_dependency(local_1_d, foo, 2:0:0, DependencyRegistry, DependencyPack, DependencyVersion).
     DependencyRegistry = local_2_d,
     DependencyPack = baz,
     DependencyVersion = 1:0:0.

The ‘loaded_pack_dependency/6’ predicate is the loaded-session
counterpart of ‘pack_dependency/6’.  It only succeeds when both the
source pack and the dependency pack contributed loaded files to the
current session.

For example:

     | ?- packs::loaded_pack_dependency(Registry, Pack, Version, DependencyRegistry, DependencyPack, DependencyVersion).
     ...

These predicates are especially useful for tools such as ‘sbom’, which
need to query resolved pack metadata, determine which installed packs
contributed code to the current session, and enumerate relationships
between those packs without reconstructing that information manually.


File: TheLogtalkHandbook-3.101.0.info,  Node: Registries and packs storage,  Next: Virtual environments,  Prev: Programmatic query API,  Up: packs

5.18.7 Registries and packs storage
-----------------------------------

The tool uses a directory specified using the ‘logtalk_packs’ library
alias when defined (in a settings file or in a backend Prolog
initialization file).  When this library alias is not defined, the tool
uses the value of the ‘LOGTALKPACKS’ environment variable when defined.
Otherwise, it defaults to the ‘~/logtalk_packs’ directory.  The actual
directory can be retrieved by the query:

     | ?- packs::logtalk_packs(Directory).
     ...

This directory holds sub-directories for registries, packs, and
archives.  These sub-directories are automatically created when loading
the ‘packs’ tool if they don’t exist.  Users should not manually modify
the contents of these directories.  Multiple and independent
registry/pack setups are possible using 'virtual environments' as
explained next.

Your registries and packs setup can be saved and restored (e.g., in a
different system) by using the ‘packs::save/1-2’ and
‘packs::restore/1-2’ predicates, as explained in the next section about
virtual environments.  If necessary, before restoring, the
‘packs::reset/0’ predicate can be called to delete any defined
registries and installed packs.


File: TheLogtalkHandbook-3.101.0.info,  Node: Virtual environments,  Next: Lock files,  Prev: Registries and packs storage,  Up: packs

5.18.8 Virtual environments
---------------------------

An application may require specific pack versions.  These requirements
may differ between applications.  Different applications may also have
conflicting requirements.  Therefore, a 'virtual environment' where an
application requirements are fulfilled may be required to develop and/or
run it.  A virtual environment is essentially a registries/packs storage
directory.

Defining the ‘logtalk_packs’ library alias in a settings file or
defining the ‘LOGTALKPACKS’ environment variable before starting Logtalk
allows easy creation and switching between virtual environments.  By
using a per-application settings file (or a per-application environment
variable definition), each application can thus use its own virtual
environment.  The ‘settings.lgt’ file can define the ‘logtalk_packs’
library alias using code such as:

     :- initialization((
         logtalk_load_context(directory, Directory),
         assertz(logtalk_library_path(logtalk_packs, Directory))
     )).

The definition of the ‘logtalk_packs’ library alias 'must' always be an
atom and thus never use library notation (i.e., it must never depend on
other library aliases).

When a virtual environment also requires a specific Logtalk version
(e.g., the version used to test and certify it), this can be installed
as a pack from the official talkshow(1) registry and used by
(re)defining the ‘LOGTALKHOME’ and ‘LOGTALKUSER’ environment variables
to point to its pack directory (which can be queried by using the
‘packs::directory/2’ message).

Experimental ‘lgtenv.sh’ and ‘lgtenv.ps1’ scripts are included to
simplify creating virtual environments.  For example:

     $ lgtenv -d ~/my_venv -c -p logtalk_packs
     $ cd ~/my_venv
     direnv: loading ~/my_venv/.envrc
     direnv: export +LOGTALKPACKS

Type ‘lgtenv -h’ for details on the script options.

These scripts require, respectively, direnv(2) and Set-PsEnv(3) to be
installed.  These utilities load and unload environment variables when
changing the current directory.  On Windows systems, when using the
‘lgtenv.ps1’ script, you also need to redefine the PowerShell prompt in
a profile file (e.g., ‘$HOME\Documents\PowerShell\Profile.ps1’) to mimic
the functionality of ‘direnv’ of automatically loading an existing
‘.env’ file when changing to its directory.  For example:

     function prompt {
         Set-PsEnv
         'PS ' + $(Get-Location) + '> '
     }

A virtual environment setup (i.e., the currently defined registries and
installed packs) can be saved into a file (e.g., ‘requirements.lgt’)
using the ‘packs::save/1-2’ predicates.  For example:

     | ?- packs::save('requirements.lgt').
     ...

This query saves a listing of all the installed packs and their
registries.  Using the saved file, the virtual environment setup can
then be restored using the ‘packs::restore/1-2’ predicates.  The file
uses a simple format with ‘registry/2’, ‘pack/3’, ‘pinned_registry/1’,
and ‘pinned_pack/1’ facts (in this order) and can be manually created or
edited if necessary.  For example:

     registry(talkshow, 'https://github.com/LogtalkDotOrg/talkshow.git').
     pack(talkshow, logtalk, 3:45:0).
     pack(talkshow, lflat, 2:1:0).

These files can be distributed with applications so that users can
easily fulfill application requirements by running the query once:

     | ?- packs::restore('requirements.lgt').

Subsequently, the application ‘loader.lgt’ file can then load the
required packs using their loader files:

     :- initialization((
         % load required packs
         logtalk_load(foo(loader)),
         logtalk_load(bar(loader)),
         ...
         % load application files
         ...
     )).

Note that restoring encrypted registries or encrypted packs requires
entering the required passphrases.  Although the ‘restore/2’ predicate
accepts a list of options that include the ‘gpg/1’ option, this only
allows specifying a single and common passphrase when interactive
entering of passphrases is not convenient or possible.

   ---------- Footnotes ----------

   (1) https://github.com/LogtalkDotOrg/talkshow

   (2) https://github.com/direnv/direnv

   (3) https://github.com/rajivharris/Set-PsEnv


File: TheLogtalkHandbook-3.101.0.info,  Node: Lock files,  Next: Registry specification,  Prev: Virtual environments,  Up: packs

5.18.9 Lock files
-----------------

For deterministic installs and CI/CD reproducibility when working with
virtual environments, the ‘save/2’ and ‘restore/2’ predicates support a
‘lock(true)’ option.  Saving with this option writes lock extension
facts in addition to the requirements facts:

     lockfile_version(1).
     lock_registry_commit(talkshow, '0123456789abcdef0123456789abcdef01234567').
     lock_integrity(talkshow, lflat, 2:1:0, sha256, '8774b3863efc03bb6c85dcf34f69f1156d2496a3').

The ‘lock_registry_commit/2’ facts are generated only for registries
defined from git URLs.  Restoring with ‘lock(true)’ enforces lock
extension facts, including exact pack versions, integrity hashes, and
git registry commits.


File: TheLogtalkHandbook-3.101.0.info,  Node: Registry specification,  Next: Registry handling,  Prev: Lock files,  Up: packs

5.18.10 Registry specification
------------------------------

A registry is a git remote repo that can be cloned, a downloadable or
local archive, or a local directory containing a Logtalk loader file
that loads source files defining the registry itself and the packs it
provides.  The registry name is ideally a valid unquoted atom.  The
registry directory must contain at least two Logtalk source files:

   - A file defining an object named after the registry with a
     ‘_registry’ suffix, implementing the ‘registry_protocol’.  This
     naming convention helps prevent name conflicts.

   - A loader file (named ‘loader.lgt’ or ‘loader.logtalk’) that loads
     the registry object file and all pack object files.

An example of a registry specification object would be:

     :- object(jdoe_awesome_packs_registry,
         implements(registry_protocol)).

         :- info([
             version is 1:0:0,
             author is 'John Doe',
             date is 2021-10-18,
             comment is 'John Doe awesome packs registry spec.'
         ]).

         name(jdoe_awesome_packs).

         description('John Doe awesome packs').

         home('https://example.com/jdoe_awesome_packs').

         clone('https://github.com/jdoe/jdoe_awesome_packs.git').

         archive('https://github.com/jdoe/jdoe_awesome_packs/archive/main.zip').

     :- end_object.

Optionally, the registry object can also define a ‘note(Action, Note)’
predicate.  The ‘Action’ argument is an atom: ‘add’, ‘update’, or
‘delete’.  The ‘Note’ argument is also an atom.  The tool will print any
available notes when executing one of the registry actions.  See the
‘registry_protocol’ documentation for more details.

The registry directory should also contain ‘LICENSE’ and ‘README.md’
files (individual packs can use a different license, however).  The path
to the ‘README.md’ file is printed when the registry is added.  It can
also be queried using the ‘registries::directory/2’ predicate.  The
‘NOTES.md’ file name can also be used in alternative to the recommended
‘README.md’ file name.

Summarizing the required directory structure using the above example
(note that the registry and pack specification files are named after the
objects):

     jdoe_awesome_packs
         LICENSE
         README.md
         jdoe_awesome_packs_registry.lgt
         loader.lgt
         foo_pack.lgt
         bar_pack.lgt
         ...

With the contents of the ‘loader.lgt’ file being:

     :- initialization((
         logtalk_load(jdoe_awesome_packs_registry),
         logtalk_load(foo_pack),
         logtalk_load(bar_pack),
         ...
     )).

It would be, of course, possible to have all objects in a single source
file.  But having a file per-object and a loader file helps maintenance,
and it’s also a tool requirement for applying safety procedures to the
source file contents and thus successfully loading the registry and pack
specs.

As registries are git repos in the most common case, and thus adding
them performs a git repo cloning, they should only contain the strictly
required files.


File: TheLogtalkHandbook-3.101.0.info,  Node: Registry handling,  Next: Registry development,  Prev: Registry specification,  Up: packs

5.18.11 Registry handling
-------------------------

Registries can be added using the ‘registries::add/1-3’ predicates,
which take a registry URL. Using the example above:

     | ?- registries::add('https://github.com/jdoe/jdoe_awesome_packs.git').

HTTPS URLs must end with either a ‘.git’ extension or an archive
extension (same valid extensions as for pack archives, including ‘gpg’
encrypted).  Git cloning URLs are preferred as they simplify updating
registries.  But a registry can also be made available via a local
directory (using a ‘file://’ URL) or a downloadable archive (using a
‘https://’ URL).

For registries made available using an archive, the
‘registries::add/2-3’ predicates 'must' be used as the registry name
cannot in general be inferred from the URL basename or from the archived
directory name.  The registry argument must also be the declared
registry name in the registry specification object.  For example:

     | ?- registries::add(
             jdoe_awesome_packs,
             'https://github.com/jdoe/jdoe_awesome_packs/archive/main.zip'
          ).

When a registry may be already defined, you can use the ‘update(true)’
option to ensure that the registry will be updated to its latest
definition:

     | ?- registries::add(
             jdoe_awesome_packs,
             'https://github.com/jdoe/jdoe_awesome_packs/archive/main.zip',
             [update(true)]
          ).

The added registries can be listed using the ‘registries::list/0’
predicate:

     | ?- registries::list.

     % Defined registries:
     %   jdoe_awesome_packs (git)
     %   ...

The ‘registries::describe/1’ predicate can be used to print the details
of a registry:

     | ?- registries::describe(jdoe_awesome_packs).

     % Registry:    jdoe_awesome_packs
     % Description: John Doe awesome packs
     % Home:        https://example.com/jdoe_awesome_packs
     % Cloning URL: https://github.com/jdoe/jdoe_awesome_packs.git
     % Archive URL: https://github.com/jdoe/jdoe_awesome_packs/archive/main.zip

To update all registries, use the ‘registries::update/0’ predicate.  To
update a single registry, use the ‘registries::update/1-2’ predicates.
After updating, you can use the ‘packs::outdated/0-1’ predicates to list
any outdated packs.

Registries can also be deleted using the ‘registries::delete/1-2’
predicate.  By default, any registries with installed packs cannot be
deleted.  If you force deletion (by using the ‘force(true)’ option), you
can use the ‘packs::orphaned/0’ predicate to list any orphaned packs
that are installed.

See the tool API documentation on the registries(1) object for other
useful predicates.

   ---------- Footnotes ----------

   (1) ../../docs/registries_0.html


File: TheLogtalkHandbook-3.101.0.info,  Node: Registry development,  Next: Pack specification,  Prev: Registry handling,  Up: packs

5.18.12 Registry development
----------------------------

To simplify registry development and testing, use a local directory and
a ‘file://’ URL when calling the ‘registries::add/1’ predicate.  For
example:

     | ?- registries::add('file:///home/jdoe/work/my_pack_collection').

If the directory is a git repo, the tool will clone it when adding it.
Otherwise, the files in the directory are copied to the registry
definition directory.  This allows the registry to be added and deleted
without consequences for the original registry source files.

The ‘registries::add/3’ and ‘registries::update/2’ predicates also
accept a ‘commit(Hash)’ option.  This option checks out a git registry
at an exact commit hash.  Using this option with non-git registries
fails with an error message.

To check your registry specifications, use the ‘registries::lint/0-1’
predicates after adding the registry.


File: TheLogtalkHandbook-3.101.0.info,  Node: Pack specification,  Next: Encrypted packs,  Prev: Registry development,  Up: packs

5.18.13 Pack specification
--------------------------

A pack is specified using a Logtalk source file defining an object that
implements the ‘pack_protocol’.  The source file should be named after
the pack with a ‘_pack’ suffix.  This naming convention helps prevent
name conflicts, notably with the pack’s own objects.  The file must be
available from a declared pack registry (by having the registry loader
file loading it).  The pack name is preferably a valid unquoted atom.
An example of a pack specification object would be:

     :- object(lflat_pack,
         implements(pack_protocol)).

         :- info([
             version is 1:0:0,
             author is 'Paulo Moura',
             date is 2021-10-18,
             comment is 'L-FLAT - Logtalk Formal Language and Automata Toolkit pack spec.'
         ]).

         name(lflat).

         description('L-FLAT - Logtalk Formal Language and Automata Toolkit').

         license('MIT').

         home('https://github.com/l-flat/lflat').

         version(
             2:1:0,
             stable,
             'https://github.com/l-flat/lflat/archive/refs/tags/v2.1.0.tar.gz',
             sha256 - '9c298c2a08c4e2a1972c14720ef1498e7f116c7cd8bf7702c8d22d8ff549b6a1',
             [logtalk @>= 3:42:0],
             all
         ).

         version(
             2:0:2,
             stable,
             'https://github.com/l-flat/lflat/archive/refs/tags/v2.0.2.tar.gz',
             sha256 - '8774b3863efc03bb6c284935885dcf34f69f115656d2496a33a446b6199f3e19',
             [logtalk @>= 3:36:0],
             all
         ).

     :- end_object.

The ‘license/1’ argument must be an atom and should, whenever possible,
be a license identifier as specified in the SPDX standard(1).

Optionally, the pack object can also define a ‘note(Action, Version,
Note)’ predicate.  The ‘Action’ argument is an atom: ‘install’,
‘update’, or ‘uninstall’.  The ‘Note’ argument is also an atom.  The
tool will print any available notes when executing one of the registry
actions.  See the ‘pack_protocol’ documentation for more details.

The pack sources must be available either as a local directory (when
using a ‘file://’ URL) or for downloading as a supported archive.  The
checksum for the archive must use the SHA-256 hash algorithm (‘sha256’).
The pack may optionally be signed.  Supported archive formats and
extensions are:

   - ‘.zip’

   - ‘.tgz’, ‘.tar.gz’

   - ‘.tbz2’, ‘.tar.bz2’

Also, for encrypted packs, all the extensions above with a ‘.gpg’ suffix
(e.g., ‘.zip.gpg’).

The pack sources should contain ‘LICENSE’, ‘README.md’ (or ‘NOTES.md’),
and ‘loader.lgt’ (or ‘loader.logtalk’) files.  Ideally, it should also
contain a ‘tester.lgt’ (‘tester.logtalk’) file.  The path to the
‘README.md’ file is printed when the pack is installed or updated.  It
can also be queried using the ‘packs::directory/2’ predicate.

   ---------- Footnotes ----------

   (1) https://spdx.org/licenses/


File: TheLogtalkHandbook-3.101.0.info,  Node: Encrypted packs,  Next: Signed packs,  Prev: Pack specification,  Up: packs

5.18.14 Encrypted packs
-----------------------

Packs can be ‘gpg’ encrypted, with a choice of passphrase-based
encryption, key-based encryption, or both.  Encrypted pack archives must
always have a ‘.gpg’ extension.  For example, to encrypt a pack archive
with a symmetric cipher using a passphrase:

     $ tar -cvzf - my_pack | gpg -c --cipher-algo AES256 > v1.2.1.tar.gz.gpg

In this case, the passphrase would need to be securely communicated to
any users installing or updating the pack.

See the ‘gpg’ documentation for full details on encrypting and
decrypting archives.  If you get a “gpg: problem with the agent:
Inappropriate ioctl for device” error message with the command above,
try:

     $ export GPG_TTY=$(tty)


File: TheLogtalkHandbook-3.101.0.info,  Node: Signed packs,  Next: Pack URLs and Single Sign-On,  Prev: Encrypted packs,  Up: packs

5.18.15 Signed packs
--------------------

Packs can be ‘gpg’ signed.  Detached signature files are assumed and
expected to share the name of the archive and use ‘.asc’ or ‘.sig’
extensions.  For example, if the pack archive name is ‘v1.0.0.tar.gz’,
the signature file must be named ‘v1.0.0.tar.gz.asc’ or
‘v1.0.0.tar.gz.sig’.  When the ‘checksig(true)’ option is used, the
signature file is automatically downloaded using a URL constructed from
the pack archive URL. When both ‘.asc’ and ‘.sig’ files exist, the
‘.asc’ file is used.  An example of signing a pack and creating the
‘.asc’ file (assuming the default signing key) is:

     $ gpg --armor --detach-sign v1.0.0.tar.gz

To create instead a ‘.sig’ file:

     $ gpg --detach-sign v1.0.0.tar.gz

See the ‘gpg’ documentation for full details on signing archives and
sharing the public keys required to verify the signatures.


File: TheLogtalkHandbook-3.101.0.info,  Node: Pack URLs and Single Sign-On,  Next: Multiple pack versions,  Prev: Signed packs,  Up: packs

5.18.16 Pack URLs and Single Sign-On
------------------------------------

Typically, pack archive download URLs are HTTPS URLs and handled using
‘curl’.  It’s also possible to use ‘git archive’ to download pack
archives, provided that the server supports it (as of this writing,
Bitbucket and GitLab public hosting services support it but not GitHub).
Using ‘git archive’ is specially useful when the packs registry is
hosted on a server using Single Sign-On (SSO) for authentication.  In
this case, HTTPS URLs can only be handled by ‘curl’ by passing a token
(see below for an example).  When the user has setup SSH keys to
authenticate to the packs registry server, ‘git archive’ simplifies pack
installation, providing a better user experience.  For example:

     version(
         1:0:1,
         stable,
         'git@gitlab.com:me/foo.git/v1.0.1.zip',
         sha256 - '0894c7cdb8968b6bbcf00e3673c1c16cfa98232573af30ceddda207b20a7a207',
         [logtalk @>= 3:36:0],
         all
     ).

The pseudo-URL must be the concatenation of the SSH repo cloning URL
with the archive name.  The archive name must be the concatenation of a
valid tag with a supported archive extension.  SSH repo cloning URLs use
the format:

     git@<hostname>:path/to/project.git

They can usually be easily copied from the hosting service repo webpage.
To compute the checksum, you must first download the archive.  For
example:

     $ git archive --output=foo-v1.0.1.zip --remote=git@gitlab.com:me/foo.git v1.0.1
     $ openssl sha256 foo-v1.0.1.zip

Be sure to use a format that is supported by both the ‘packs’ tool and
the ‘git archive’ command (the format is inferred from the ‘--output’
option).  Do not download the archive from the web interface of the git
hosting service in order to compute the checksum.  Different
implementations of the archiving and compressing algorithms may be used,
resulting in mismatched checksums.

Users installing packs available using ‘git archive’ URLs are advised to
run a SSH agent to avoid being prompted for passwords when installing or
updating packs.  They must also upload their SSH public keys to the pack
provider hosts.


File: TheLogtalkHandbook-3.101.0.info,  Node: Multiple pack versions,  Next: Pack dependencies,  Prev: Pack URLs and Single Sign-On,  Up: packs

5.18.17 Multiple pack versions
------------------------------

A pack may specify multiple versions.  Each version is described using a
‘version/6’ predicate clause as illustrated in the example above.  The
versions must be listed in order from newest to oldest.  For details,
see the ‘pack_protocol’ API documentation.

Listing multiple versions allows the pack specification to be updated
(by updating its registry) without forcing existing users into
installing (or updating to) the latest version of the pack.  It allows
different applications depending on different pack versions to continue
to be built and deployed.

The pack version is complemented by the pack status.  Valid values are
‘stable’, ‘rc’, ‘beta’, ‘alpha’, ‘experimental’, and ‘deprecated’.
Packs with a ‘experimental’ or ‘deprecated’ status are 'never' installed
by default when using the install and update predicates unless their
version is explicitly specified.  When updating packs, we can restrict
the valid status of the updates using the ‘status/1’ option.  For
example, we can ensure that we only update to new stable pack versions
by using the option ‘status([stable])’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Pack dependencies,  Next: Pack portability,  Prev: Multiple pack versions,  Up: packs

5.18.18 Pack dependencies
-------------------------

Pack dependencies on other packs can be specified using a list of
‘Registry::Pack Operator Version’ terms where ‘Operator’ is a standard
term comparison operator:

   - ‘Registry::Pack @>= Version’ - the pack requires a dependency with
     a version equal or above the specified one.  For example, ‘logtalk
     @>= 3:36:0’ means that the pack requires Logtalk 3.36.0 or a later
     version.

   - ‘Registry::Pack @=< Version’ - the pack requires a dependency with
     a version up to the specified one.  For example, ‘common::bits @=<
     2:1’ means that the pack requires a ‘common::bits’ pack up to 2.1.
     This includes all previous versions and also all patches for
     version 2.1 (e.g., 2.1.7, 2.1.8, …) but not version 2.2 or newer.

   - ‘Registry::Pack @< Version’ - the pack requires a dependency with
     version older than the specified one.  For example, ‘common::bits
     @< 3’ means that the pack requires a ‘common::bits’ 2.x or older
     version.

   - ‘Registry::Pack @> Version’ - the pack requires a dependency with
     version newer than the specified one.  For example, ‘common::bits
     @> 2:4’ means that the pack requires a ‘common::bits’ 2.5 or newer
     version.

   - ‘Registry::Pack == Version’ - the pack requires a dependency with a
     specific version.  For example, ‘common::bits == 2:1’ means that
     the pack requires a ‘common::bits’ pack version 2.1.x (thus, from
     version 2.1.0 to the latest patch for version 2.1).

   - ‘Registry::Pack \== Version’ - the pack requires a dependency with
     any version other than the one specified.  For example,
     ‘common::bits \== 2.1’ means that the pack requires a
     ‘common::bits’ pack version other than any 2.1.x version.

To specify 'range' dependencies by using two consecutive elements with
the lower bound followed by the upper bound.  For example, ‘common::bits
@>= 2, common::bits @< 3’ means all ‘common::bits’ 2.x versions but not
older or newer major versions.

It’s also possible to specify 'alternative' dependencies using the
‘(;)/2’ operator.  For example, ‘(common::bits == 1:9; common::bits @>=
2:3)’ means either ‘common::bits’ 1.9.x versions or 2.3.x and later
versions.  Alternatives should be listed in decreasing order of
preference.

When a pack also depends on a Logtalk or backend version, the name
‘logtalk’ or the backend identifier atom can be used in place of
‘Registry::Pack’ (see below for the table of backend specifiers).  For
example, ‘logtalk @>= 3.36.0’.

When a pack also depends on an operating-system version (e.g., a pack
containing shared libraries with executable code), the
‘os(Name,Machine)’ compound term can also be used in place of
‘Registry::Pack’.  For example, ‘os('Darwin',x86_64) @>= '23.0.0'’.
Note that, in this case, the release is an atom.  The operating-system
data (name, machine, and release) is queried using the corresponding
‘os’ library predicates (see the library documentation for details).


File: TheLogtalkHandbook-3.101.0.info,  Node: Pack portability,  Next: Pack development,  Prev: Pack dependencies,  Up: packs

5.18.19 Pack portability
------------------------

Ideally, packs are fully portable and can be used with all
Logtalk-supported Prolog backends.  This can be declared by using the
atom ‘all’ in the last argument of the ‘version/6’ predicate (see
example above).

When a pack can only be used with a subset of the Prolog backends, the
last argument of the ‘version/6’ predicate is a list of backend
identifiers (atoms):

   - B-Prolog: ‘b’

   - Ciao Prolog: ‘ciao’

   - CxProlog: ‘cx’

   - ECLiPSe: ‘eclipse’

   - GNU Prolog: ‘gnu’

   - JIProlog: ‘ji’

   - Quintus Prolog: ‘quintus’

   - SICStus Prolog: ‘sicstus’

   - SWI-Prolog: ‘swi’

   - Tau Prolog: ‘tau’

   - Trealla Prolog: ‘trealla’

   - XSB: ‘xsb’

   - XVM: ‘xvm’

   - YAP: ‘yap’


File: TheLogtalkHandbook-3.101.0.info,  Node: Pack development,  Next: Pack handling,  Prev: Pack portability,  Up: packs

5.18.20 Pack development
------------------------

To simplify pack development and testing, define a local registry and
add to it a pack specification with the development version available
from a local directory.  For example:

     version(
         0:11:0,
         beta,
         'file:///home/jdoe/work/my_awesome_library',
         none,
         [],
         all
     ).

If the directory is a git repo, the tool will clone it when installing
the pack.  Otherwise, the files in the directory are copied to the pack
installation directory.  This allows the pack to be installed, updated,
and uninstalled without consequences for the pack source files.

You can also use a local archive instead of a directory.  For example:

     version(
         1:0:0,
         stable,
         'file:///home/jdoe/work/my_awesome_library/v1.0.0.tar.gz',
         sha256 - '1944773afba1908cc6194297ff6b5ac649a844ef69a69b2bcdf267cfa8bfce1e',
         [],
         all
     ).

Packs that are expected to be fully portable should always be checked by
loading them with the ‘portability’ flag set to ‘warning’.

To check your pack manifest files, use the ‘packs::lint/0-2’ predicates
after adding the registry that provides the packs.


File: TheLogtalkHandbook-3.101.0.info,  Node: Pack handling,  Next: Pack documentation,  Prev: Pack development,  Up: packs

5.18.21 Pack handling
---------------------

Packs must be available from a defined registry.  To list all packs that
are available for installation, use the ‘packs::available/0’ predicate:

     | ?- packs::available.

To list all installed packs, call the ‘packs::installed/0’ predicate:

     | ?- packs::installed.

To list only the installed packs from a specific registry, call instead
the ‘packs::installed/1’ predicate.  For example:

     | ?- packs::installed(talkshow).

To know more about a specific pack, use the ‘packs::describe/1-2’
predicates.  For example:

     | ?- packs::describe(bar).

The ‘packs::describe/2’ predicate can be used when two or more
registries provide packs with the same name.  For example:

     | ?- packs::describe(reg, bar).

To install the latest version of a pack, we can use the
‘packs::install/1-4’ predicates.  In the most simple case, when a pack
name is unique among registries, we can use the ‘packs::install/1’
predicate.  For example:

     | ?- packs::install(bar).

Any pack dependencies are also checked and installed or updated if
necessary.  Other install predicates are available to disambiguate
between registries and to install a specific pack version.

Packs become available for loading immediately after successful
installation (no restarting of the Logtalk session is required).  For
example, after the pack ‘bar’ is installed, you can load it at the
top-level by typing:

     | ?- {bar(loader)}.

or load it from a loader file using the goal
‘logtalk_load(bar(loader))’.

After updating the defined registries, outdated packs can be listed
using the ‘packs::outdated/0’ predicate.  You can update all outdated
packs by calling the ‘packs::update/0’ predicate or update a single pack
using the ‘packs::update/1-2’ predicates.  For example:

     | ?- packs::update(bar).

By default, updating a pack fails if it would break any dependent pack
(the ‘force(true)’ option, described below, can be used to force
updating in this case).

The tool provides versions of the pack install, update, and uninstall
predicates that accept a list of options:

   - ‘verbose(Boolean)’ (default is ‘false’)

   - ‘clean(Boolean)’ (default is ‘false’)

   - ‘update(Boolean)’ (default is ‘false’)

   - ‘force(Boolean)’ (default is ‘false’)

   - ‘compatible(Boolean)’ (default is ‘true’)

   - ‘checksum(Boolean)’ (default is ‘true’)

   - ‘checksig(Boolean)’ (default is ‘false’)

   - ‘git(Atom)’ (extra command-line options; default is ‘''’)

   - ‘downloader(Atom)’ (downloader utility; default is ‘curl’)

   - ‘curl(Atom)’ (extra command-line options; default is ‘''’)

   - ‘wget(Atom)’ (extra command-line options; default is ‘''’)

   - ‘gpg(Atom)’ (extra command-line options; default is ‘''’)

   - ‘tar(Atom)’ (extra command-line options; default is ‘''’)

Note that, by default, only compatible packs can be installed.  To
install a pack that is incompatible with the current Logtalk version,
backend version, or operating-system version, use the ‘install/4’ or
‘update/3’ predicates with the option ‘compatible(false)’.

When installing large packs over unreliable network conditions, you may
try switching the default downloader utility from ‘curl’ to ‘wget’.

When a pack may already be installed, you can use the ‘update(true)’
option to ensure that the installation will be updated to the specified
version:

     | ?- packs::install(reg, bar, 1:1:2, [update(true)]).

When using a ‘checksig(true)’ option to check a pack signature, it is
strongly advised that you also use the ‘verbose(true)’ option.  For
example:

     | ?- packs::install(reg, bar, 1:1:2, [verbose(true), checksig(true)]).

Note that the public key used to sign the pack archive must already be
present in your local system.

Downloading pack archives may require passing extra command-line options
to ‘curl’ for authentication.  A common solution is to use a personal
access token.  The details depend on the server software.  An example
when using GitHub:

     | ?- packs::install(reg, bar, 1:1:2, [curl('--header "Authorization: token foo42"')]).

Another example when using GitLab:

     | ?- packs::install(reg, bar, 1:1:2, [curl('--header "PRIVATE-TOKEN: foo42"')]).

Pack archives may be ‘gpg’ encrypted.  Encryption can be
passphrase-based, key-based, or both.  When using only passphrase-based
encryption, the archive passphrase must be entered (if not cached) when
installing or updating a pack.  In this case, the passphrase can be
entered interactively or using the ‘gpg/1’ option.  For example:

     | ?- packs::install(reg, bar, 1:1:2, [gpg('--batch --passphrase test123')]).

See the ‘gpg’ documentation for details.  When using the ‘gpg/1’ option,
you should be careful to not leak passphrases in, e.g., the query
history.

To uninstall a pack that you no longer need, use the
‘packs::uninstall/1-2’ predicates.  By default, only packs with no
dependent packs can be uninstalled.  You can print or get a list of the
packs that depend on a given pack by using the ‘packs::dependents/1-3’
predicates.  For example:

     | ?- packs::dependents(reg, bar, Dependents).

See the tool API documentation on the packs(1) object for other useful
predicates.

   ---------- Footnotes ----------

   (1) ../../docs/packs_0.html


File: TheLogtalkHandbook-3.101.0.info,  Node: Pack documentation,  Next: Pinning registries and packs,  Prev: Pack handling,  Up: packs

5.18.22 Pack documentation
--------------------------

The path to the pack ‘README.md’ file is printed when the pack is
installed or updated.  It can also be retrieved at any time by using the
‘readme/2’ predicate.  For example:

     | ?- packs::readme(lflat, Path).

Additional documentation may also be available from the pack home page,
which can be printed by using the ‘describe/1-2’ predicates.  For
example:

     | ?- packs::describe(lflat).

     % Registry:    ...
     % Pack:        lflat
     % Description: L-FLAT - Logtalk Formal Language and Automata Toolkit
     % License:     MIT
     % Home:        https://github.com/l-flat/lflat
     % Versions:
     ...

The pack API documentation can be generated using the ‘lgtdoc’ tool
library and directory predicates (depending on the pack source files
organization).  For example:

     | ?- {lflat(loader)},
          {lgtdoc(loader)},
          logtalk::expand_library_path(lflat, Path),
          lgtdoc::rdirectory(Path).
     ...

This query creates a ‘xml_docs’ directory in the current directory.  The
XML documentation files can then be converted into a final format, e.g.,
HTML, using one of the scripts provided by the ‘lgtdoc’ tool.  For
example:

     $ cd xml_docs
     $ lgt2html

For more details and alternatives, see the ‘lgtdoc’ tool documentation.

It is also possible to add API documentation and diagrams for all the
installed packs to the Logtalk distribution API documentation and
diagrams by calling the ‘build’ and ‘update_svg_diagrams’ scripts in the
‘docs/apis/sources’ directory with the ‘-i’ option.  See the scripts
documentation for more details.


File: TheLogtalkHandbook-3.101.0.info,  Node: Pinning registries and packs,  Next: Testing packs,  Prev: Pack documentation,  Up: packs

5.18.23 Pinning registries and packs
------------------------------------

Registries and packs can be 'pinned' after installation to prevent
accidental updating or deleting, e.g., when using the batch ‘update/0’
predicate.  This is useful when your application requires a specific
version or for security considerations (see below).  For example, if we
want the ‘bar’ pack to stay at its current installed version:

     | ?- packs::pin(bar).
     yes

After, any attempt to update or uninstall the pack will fail with an
error message:

     | ?- packs::update(bar).
     !     Cannot update pinned pack: bar
     no

     | ?- packs::uninstall(bar).
     !     Cannot uninstall pinned pack: bar
     no

To enable the pack to be updated or uninstalled, the pack must first be
unpinned.  Alternatively, the ‘force(true)’ option can be used.  Note
that if you force update a pinned pack, the new version will be
unpinned.

It’s also possible to pin (or unpin) all defined registries or installed
packs at once by using the ‘pin/0’ (or ‘unpin/0’) predicates.  But note
that registries added after or packs installed after will not be
automatically pinned.


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing packs,  Next: Security considerations,  Prev: Pinning registries and packs,  Up: packs

5.18.24 Testing packs
---------------------

Logtalk packs (as most Logtalk libraries, tools, and examples) are
expected to have a ‘tester.lgt’ or ‘tester.logtalk’ tests driver file at
the root of their directory, which can be used for both automated and
manual testing.  For example, after installing the ‘foo’ pack:

     | ?- {foo(tester)}.

To test all installed packs, you can use the ‘logtalk_tester’ automation
script from the installed packs directory, which you can query using the
goal:

     | ?- packs::prefix(Directory).

Note that running the packs tests, like simply loading the pack, can
result in calling arbitrary code, which can potentially harm your
system.  Always take into account the security considerations discussed
below.


File: TheLogtalkHandbook-3.101.0.info,  Node: Security considerations,  Next: Best practices,  Prev: Testing packs,  Up: packs

5.18.25 Security considerations
-------------------------------

New pack registries should be examined before being added, specially if
public and from a previously unknown source.  The same precautions
should be taken when adding or updating a pack.  Note that a registry
can always index third-party packs.

Pack checksums are checked by default.  But pack signatures are only
checked if requested, as packs are often unsigned.  Care should be taken
when adding public keys for pack signers to your local system.

Registry and pack spec files, plus the registry loader file, are
compiled by term-expanding them so that only expected terms are actually
loaded and only expected ‘logtalk_load/2’ goals with expected relative
file paths are allowed.  Predicates defining URLs are discarded if the
URLs are neither ‘https://’ nor ‘file://’ URLs or if they contain
non-allowed characters (currently, only alpha-numeric ASCII characters
plus the ASCII ‘/’, ‘.’, ‘-’, and ‘_’ characters are accepted).  But
note that this tool makes no attempt to audit pack source files
themselves.

Registries and packs can always be pinned so that they are not
accidentally updated to a version that you may not have had the chance
to audit.


File: TheLogtalkHandbook-3.101.0.info,  Node: Best practices,  Next: Installing Prolog packs,  Prev: Security considerations,  Up: packs

5.18.26 Best practices
----------------------

   - Make available a new pack registry as a git repo.  This simplifies
     updating the registry and rolling back to a previous version.

   - Use registry and pack names that are valid unquoted atoms, thus
     simplifying usage.  Use descriptive names with underscores if
     necessary to link words.

   - Name the registry and pack specification objects after their names
     with a ‘_registry’ or ‘_pack’ suffix.  Save the objects in files
     named after the objects.

   - Create new pack versions from git tags.

   - If the sources of a pack are available from a git repo, consider
     using signed commits and signed tags for increased security.

   - When a new pack version breaks backwards compatibility, list both
     the old and the new versions on the pack specification file.

   - Pin registries and packs when specific versions are critical for
     your work so that you can still easily batch update the remaining
     packs and registries.

   - Include the ‘$LOGTALKPACKS’ directory (or the default
     ‘~/logtalk_packs’ directory) on your regular backups.


File: TheLogtalkHandbook-3.101.0.info,  Node: Installing Prolog packs,  Next: Help with warnings<3>,  Prev: Best practices,  Up: packs

5.18.27 Installing Prolog packs
-------------------------------

This tool can also be used to install Prolog packs that don’t use
Logtalk.  After installing a ‘pl_pack’ Prolog pack from a ‘pl_reg’
registry, it can be found in the ‘$LOGTALKPACKS/packs/pl_reg/pl_pack’
directory.  When the ‘LOGTALKPACKS’ environment variable is not defined,
the pack directory is by default ‘~/logtalk_packs/packs/pl_reg/pl_pack’.

Different Prolog systems provide different solutions for locating Prolog
code.  For example, several Prolog systems adopted the Quintus Prolog
‘file_search_path/2’ hook predicate.  For these systems, a solution
could be to add a fact to this predicate for each installed Prolog pack.
For example, assuming a ‘pl_pack’ Prolog pack:

     :- multifile(file_search_path/2).
     :- dynamic(file_search_path/2).

     file_search_path(library, '$LOGTALKPACKS/packs/pl_pack').

If the Prolog system also supports reading an initialization file at
startup, the above definition could be added there.


File: TheLogtalkHandbook-3.101.0.info,  Node: Help with warnings<3>,  Next: Known issues<7>,  Prev: Installing Prolog packs,  Up: packs

5.18.28 Help with warnings
--------------------------

Load the ‘tutor’ tool to get help with selected warnings printed by the
‘packs’ tool.


File: TheLogtalkHandbook-3.101.0.info,  Node: Known issues<7>,  Prev: Help with warnings<3>,  Up: packs

5.18.29 Known issues
--------------------

Using the ‘verbose(true)’ option on Windows systems may not provide the
shell commands output depending on the backend.

On Windows systems, the reset, delete, and uninstall predicates may fail
to delete all affected folders and files due to a operating-system bug.
Depending on the backend, this bug may cause some of the tests to fail.
For details on this bug, see:

‘https://github.com/microsoft/terminal/issues/309’

The workaround is to use the Windows File Explorer to delete the
leftover folders and files.

When using Ciao Prolog 1.20.0, a workaround is used for this system
non-standard support for multifile predicates.

When using GNU Prolog 1.5.0 as the backend on Windows, you may get an
error on ‘directory_files/2’ calls.  For details and a workaround, see:

‘https://github.com/didoudiaz/gprolog/issues/4’

This issue is fixed in the latest GNU Prolog git version.

Using SICStus Prolog as the backend on Windows doesn’t currently work in
version 4.7.0 and earlier versions.  The underlying issues are fixed in
the SICStus Prolog 4.7.1 version.

XSB has an odd bug (likely in its parser) when reading files that may
cause a pack installed version to be reported as the ‘end_of_file’ atom.

Some tests fail on Windows when using ECLiPSe or XSB due to file path
representation issues.


File: TheLogtalkHandbook-3.101.0.info,  Node: ports_profiler,  Next: profiler,  Prev: packs,  Up: Developer Tools

5.19 ‘ports_profiler’
=====================

This tool counts and reports the number of times each port in the
'procedure box model' is traversed during the execution of queries.  It
can also report the number of times each clause (or grammar rule) is
used.  It is inspired by the ECLiPSe ‘port_profiler’ tool.

The procedure box model is the same as the one used in the debugger
tool.  This is an extended version of the original Byrd’s four-port
model.  Besides the standard ‘call’, ‘exit’, ‘fail’, and ‘redo’ ports,
Logtalk also defines two post-unification ports, ‘fact’ and ‘rule’, and
an ‘exception’ port.  This tool can also distinguish between
deterministic exits (reported in the ‘exit’ column in the profiling
result tables) and exits that leave choice-points (reported in the
‘*exit’ column).

* Menu:

* API documentation: API documentation<15>.
* Loading: Loading<15>.
* Testing: Testing<13>.
* Compiling source files for port profiling::
* Generating profiling data::
* Printing profiling data reports::
* Interpreting profiling data::
* Profiling Prolog modules::
* Profiling plain Prolog code::
* Known issues: Known issues<8>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<15>,  Next: Loading<15>,  Up: ports_profiler

5.19.1 API documentation
------------------------

This tool API documentation is available at:

‘../../apis/library_index.html#ports-profiler’

For sample queries, please see the ‘SCRIPT.txt’ file in the tool
directory.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<15>,  Next: Testing<13>,  Prev: API documentation<15>,  Up: ports_profiler

5.19.2 Loading
--------------

     | ?- logtalk_load(ports_profiler(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<13>,  Next: Compiling source files for port profiling,  Prev: Loading<15>,  Up: ports_profiler

5.19.3 Testing
--------------

To test this tool, load the ‘tester.lgt’ file:

     | ?- logtalk_load(ports_profiler(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Compiling source files for port profiling,  Next: Generating profiling data,  Prev: Testing<13>,  Up: ports_profiler

5.19.4 Compiling source files for port profiling
------------------------------------------------

To compile source files for port profiling, simply compile them in debug
mode and with the ‘source_data’ flag turned on.  For example:

     | ?- logtalk_load(my_source_file, [debug(on), source_data(on)]).

Alternatively, you can also simply turn on the ‘debug’ and ‘source_data’
flags globally before compiling your source files:

     | ?- set_logtalk_flag(debug, on), set_logtalk_flag(source_data, on).

Be aware, however, that loader files (e.g., library loader files) may
override the default flag values, and thus the loaded files may not be
compiled in debug mode.  In this case, you will need to modify the
loader files themselves.


File: TheLogtalkHandbook-3.101.0.info,  Node: Generating profiling data,  Next: Printing profiling data reports,  Prev: Compiling source files for port profiling,  Up: ports_profiler

5.19.5 Generating profiling data
--------------------------------

After loading this tool and compiling the source files that you want to
profile in debug mode, simply call the ‘ports_profiler::start’ goal
followed by the goals to be profiled.  Use the ‘ports_profiler::stop’
goal to stop profiling.

Note that the ‘ports_profiler::start/0’ predicate implicitly selects the
‘ports_profiler’ tool as the active debug handler.  If you have
additional debug handlers loaded (e.g., the ‘debugger’ tool), those
would no longer be active (there can be only one active debug handler at
any given time).


File: TheLogtalkHandbook-3.101.0.info,  Node: Printing profiling data reports,  Next: Interpreting profiling data,  Prev: Generating profiling data,  Up: ports_profiler

5.19.6 Printing profiling data reports
--------------------------------------

After calling the goals that you want to profile, you can print a table
with all profile data by typing:

     | ?- ports_profiler::data.

To print a table with data for a single entity, use the query:

     | ?- ports_profiler::data(Entity).

To print a table with data for a single entity predicate, use the query:

     | ?- ports_profiler::data(Entity, Predicate).

In this case, the second argument must be either a predicate indicator,
‘Name/Arity’, or a non-terminal indicator, ‘Name//Arity’.

The profiling data can be reset using the query:

     | ?- ports_profiler::reset.

To reset only the data for a specific entity, use the query:

     | ?- ports_profiler::reset(Entity).

To illustrate the tool output, consider the ‘family’ example in the
Logtalk distribution:

     | ?- {ports_profiler(loader)}.
     ...
     yes

     | ?- set_logtalk_flag(debug, on).
     yes

     | ?- logtalk_load(family(loader)).
     ...
     yes

     | ?- ports_profiler::start.
     yes

     | ?- addams::sister(Sister, Sibling).
     Sister = wednesday,
     Sibling = pubert ;
     Sister = wednesday,
     Sibling = pugsley ;
     Sister = wednesday,
     Sibling = pubert ;
     Sister = wednesday,
     Sibling = pugsley ;
     no

     | ?- ports_profiler::data.
     ----------------------------------------------------------------------
     Entity     Predicate    Fact  Rule  Call  Exit *Exit  Fail  Redo Error
     ----------------------------------------------------------------------
     addams     female/1        2     0     1     1     1     0     1     0
     addams     parent/2        8     0     4     3     5     1     5     0
     relations  sister/2        0     1     1     0     4     1     4     0
     ----------------------------------------------------------------------
     yes

     | ?- ports_profiler::data(addams).
     -----------------------------------------------------------
     Predicate    Fact  Rule  Call  Exit *Exit  Fail  Redo Error
     -----------------------------------------------------------
     female/1        2     0     1     1     1     0     1     0
     parent/2        8     0     4     3     5     1     5     0
     -----------------------------------------------------------
     yes

     | ?- ports_profiler::data(addams, parent/2).
     -------------
     Clause  Count
     -------------
          1      1
          2      1
          3      2
          4      1
          5      1
          6      2
     -------------
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: Interpreting profiling data,  Next: Profiling Prolog modules,  Prev: Printing profiling data reports,  Up: ports_profiler

5.19.7 Interpreting profiling data
----------------------------------

Some useful information that can be inferred from the profiling data
include:

   - which predicates are called more often (from the ‘call’ port)

   - unexpected failures (from the ‘fail’ port)

   - unwanted non-determinism (from the ‘*exit’ port)

   - performance issues due to backtracking (from the ‘*exit’ and ‘redo’
     ports)

   - predicates acting like a generator of possible solutions (from the
     ‘*exit’ and ‘redo’ ports)

   - inefficient indexing of predicate clauses (from the ‘fact’, ‘rule’,
     and ‘call’ ports)

   - clauses that are never used or seldom used

The profiling data should be analyzed by taking into account the
expected behavior for the profiled predicates.


File: TheLogtalkHandbook-3.101.0.info,  Node: Profiling Prolog modules,  Next: Profiling plain Prolog code,  Prev: Interpreting profiling data,  Up: ports_profiler

5.19.8 Profiling Prolog modules
-------------------------------

This tool can also be applied to Prolog modules that Logtalk is able to
compile as objects.  For example, if the Prolog module file is named
‘module.pl’, try:

     | ?- logtalk_load(module, [debug(on), source_data(on)]).

Due to the lack of standardization of module systems and the abundance
of proprietary extensions, this solution is not expected to work for all
cases.


File: TheLogtalkHandbook-3.101.0.info,  Node: Profiling plain Prolog code,  Next: Known issues<8>,  Prev: Profiling Prolog modules,  Up: ports_profiler

5.19.9 Profiling plain Prolog code
----------------------------------

This tool can also be applied to plain Prolog code.  For example, if the
Prolog file is named ‘code.pl’, simply define an object including its
code and declaring as public any predicates that you want to use as
messages to the object.  For example:

     :- object(code).

         :- public(foo/2).
         :- include('code.pl').

     :- end_object.

Save the object to an e.g.  ‘code.lgt’ file in the same directory as the
Prolog file and then load it in debug mode:

     | ?- logtalk_load(code, [debug(on), source_data(on)]).

In alternative, use the ‘object_wrapper_hook’ provided by the
‘hook_objects’ library:

     | ?- logtalk_load(hook_objects(loader)).
     ...

     | ?- logtalk_load(
              code,
              [hook(object_wrapper_hook), debug(on),
               source_data(on), context_switching_calls(allow)]
          ).

In this second alternative, you can then use the ‘(<<)/2’ context switch
control construct to call the wrapped predicates.  E.g.

     | ?- code<<foo(X, Y).

With either wrapping solution, pay special attention to any compilation
warnings that may signal issues that could prevent the plain Prolog code
from working as-is when wrapped by an object.  Often any required
changes are straightforward (e.g., adding ‘use_module/2’ directives for
called module library predicates).


File: TheLogtalkHandbook-3.101.0.info,  Node: Known issues<8>,  Prev: Profiling plain Prolog code,  Up: ports_profiler

5.19.10 Known issues
--------------------

Determinism information is currently not available when using Quintus
Prolog as the backend compiler.


File: TheLogtalkHandbook-3.101.0.info,  Node: profiler,  Next: sarif,  Prev: ports_profiler,  Up: Developer Tools

5.20 ‘profiler’
===============

This tool contains simple wrappers for selected Prolog profiler tools.

* Menu:

* Loading: Loading<16>.
* Testing: Testing<14>.
* Supported backend Prolog compilers::
* Compiling source code for profiling::


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<16>,  Next: Testing<14>,  Up: profiler

5.20.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.101.0.info,  Node: Testing<14>,  Next: Supported backend Prolog compilers,  Prev: Loading<16>,  Up: profiler

5.20.2 Testing
--------------

To test this tool, load the ‘tester.lgt’ file:

     | ?- logtalk_load(profiler(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Supported backend Prolog compilers,  Next: Compiling source code for profiling,  Prev: Testing<14>,  Up: profiler

5.20.3 Supported backend Prolog compilers
-----------------------------------------

Currently, this tool supports the profilers provided with SICStus Prolog
4, SWI-Prolog, and YAP. The tool includes two files:

   - 
          ‘yap_profiler.lgt’
          simple wrapper for the YAP count profiler

   - 
          ‘sicstus_profiler.lgt’
          simple wrapper for the SICStus Prolog 4 profiler

Logtalk also supports the YAP tick profiler (using the latest YAP
development version) and the SWI-Prolog XPCE profiler.  When using the
XPCE profiler, you can avoid profiling the Logtalk compiler (which is
invoked, e.g., when you use the ‘(::)/2’ message-sending operator at the
top-level interpreter) by compiling your code with the ‘optimize’ flag
turned on:

     ?- set_logtalk_flag(optimize, on).
     true.

     ?- use_module(library(statistics)).
     true.

     ?- profile(... :: ...).
     ...

Given that ‘prolog_statistics:profile/1’ is a meta-predicate, Logtalk
will compile its argument before calling it thanks to the
‘goal_expansion/2’ hook predicate definitions in the adapter file.
Without this hook definition, you would need to use instead (to avoid
profiling the compiler itself):

     ?- logtalk << (prolog_statistics:profile(... :: ...)).
     ...

In either case, don’t forget, however, to load the ‘prolog_statistics’
module 'before' using or compiling calls to the ‘profile/1’ to allow the
Logtalk compiler to access its meta-predicate template.

The profiler support attempts to conceal internal Logtalk
compiler/runtime predicates and the generated entity predicates that
implement predicate inheritance.  Calls to internal compiler and runtime
predicates have functors starting with ‘$lgt_’.  Calls to predicates
with functors such as ‘_def’, ‘_dcl’, or ‘_super’, used to implement
inheritance, may still be listed in a few cases.  Note that the time and
the number of calls/redos of concealed predicates are added to the
caller predicates.


File: TheLogtalkHandbook-3.101.0.info,  Node: Compiling source code for profiling,  Prev: Supported backend Prolog compilers,  Up: profiler

5.20.4 Compiling source code for profiling
------------------------------------------

To get the user-level object and predicate names instead of the
compiler-generated internal names when using the SWI-Prolog and YAP
profilers, you must set ‘code_prefix’ flag to a character other than the
default ‘$’ before compiling your source code.  For example:

     ?- set_logtalk_flag(code_prefix, '.').

See also the ‘samples/settings-sample.lgt’ file for automating the
necessary setup at Logtalk startup.


File: TheLogtalkHandbook-3.101.0.info,  Node: sarif,  Next: sbom,  Prev: profiler,  Up: Developer Tools

5.21 ‘sarif’
============

The ‘sarif’ tool serializes diagnostics produced by tools implementing
the ‘tool_diagnostics_protocol’ protocol into SARIF 2.1.0 reports:

‘https://sarifweb.azurewebsites.net/’

* Menu:

* API documentation: API documentation<16>.
* Loading: Loading<17>.
* Testing: Testing<15>.
* Usage: Usage<10>.
* Diagnostics producers::
* Report visualization::


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<16>,  Next: Loading<17>,  Up: sarif

5.21.1 API documentation
------------------------

This tool API documentation is available at:

‘../../apis/library_index.html#sarif’


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<17>,  Next: Testing<15>,  Prev: API documentation<16>,  Up: sarif

5.21.2 Loading
--------------

Load the tool using:

     | ?- logtalk_load(sarif(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<15>,  Next: Usage<10>,  Prev: Loading<17>,  Up: sarif

5.21.3 Testing
--------------

To test this tool, load the ‘tester.lgt’ file:

     | ?- logtalk_load(sarif(tester)).

The test suite validates SARIF generation for single diagnostics
producers and explicit aggregate reports, including JSON Schema
validation against the SARIF 2.1.0 schema.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<10>,  Next: Diagnostics producers,  Prev: Testing<15>,  Up: sarif

5.21.4 Usage
------------

Use the ‘term/4’ and ‘generate/4’ predicates to generate a report for a
single diagnostics producer, target, and options combination.  These
predicates generate a SARIF document with a single run.

For example:

     | ?- sarif::generate(dead_code_scanner, entity(my_object), file('./report.sarif'), []).
     true.

Use the ‘term/2’ and ‘generate/2’ predicates to generate an explicit
aggregate report from a list of specifications.  Each specification must
be a ‘tool_spec(Tool, Target, Options)’ term and produces a single SARIF
run.  Runs are emitted in the same order as the specifications list.

For example:

     | ?- sarif::generate([
              tool_spec(linter_reporter, all, []),
              tool_spec(dead_code_scanner, entity(my_object), [])
          ], file('./aggregate.sarif')).
     true.

Each specification uses the same target and options accepted by the
corresponding diagnostics producer.  The aggregate API is explicit: the
‘sarif’ tool does not infer producers or merge options across
specifications.


File: TheLogtalkHandbook-3.101.0.info,  Node: Diagnostics producers,  Next: Report visualization,  Prev: Usage<10>,  Up: sarif

5.21.5 Diagnostics producers
----------------------------

The following tools produce diagnostics compatible with the ‘sarif’
tool:

   - ‘dead_code_scanner’

   - ‘lgtdoc’

   - ‘lgtunit’

   - ‘linter_reporter’

See the individual tools documentation for details on how to generate
diagnostics.


File: TheLogtalkHandbook-3.101.0.info,  Node: Report visualization,  Prev: Diagnostics producers,  Up: sarif

5.21.6 Report visualization
---------------------------

SARIF reports can be visualized using e.g.  VSCode extensions or online
viewers.  SARIF reports are also supported in e.g.  GitHub, GitLab, and
BitBucket.


File: TheLogtalkHandbook-3.101.0.info,  Node: sbom,  Next: tool_diagnostics,  Prev: sarif,  Up: Developer Tools

5.22 ‘sbom’
===========

This tool generates a Software Bill of Materials (SBOM) for an
application, exported as a JSON file in either the ISO/IEC 5962:2021
standard SPDX 2.3 JSON format or the CycloneDX 1.6 JSON format:

‘https://www.iso.org/standard/81870.html’

‘https://cyclonedx.org/specification/overview/’

* Menu:

* API documentation: API documentation<17>.
* Loading: Loading<18>.
* Testing: Testing<16>.
* Usage: Usage<11>.
* Known issues: Known issues<9>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<17>,  Next: Loading<18>,  Up: sbom

5.22.1 API documentation
------------------------

This tool API documentation is available at:

‘../../apis/library_index.html#sbom’


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<18>,  Next: Testing<16>,  Prev: API documentation<17>,  Up: sbom

5.22.2 Loading
--------------

This tool can be loaded using the query:

     | ?- logtalk_load(sbom(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<16>,  Next: Usage<11>,  Prev: Loading<18>,  Up: sbom

5.22.3 Testing
--------------

To run the tool tests, use the query:

     | ?- logtalk_load(sbom(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<11>,  Next: Known issues<9>,  Prev: Testing<16>,  Up: sbom

5.22.4 Usage
------------

The tool inspects the current Logtalk session and generates a JSON SBOM
document describing:

   - the loaded application

   - the Logtalk version

   - the backend Prolog system and version

   - the installed packs that contributed loaded files to the current
     session

When exactly one loaded object conforms to the ‘application_protocol’
protocol from the ‘application’ library, the tool also uses that object
as the default source for application metadata.  If no conforming object
exists, or if multiple conforming objects are loaded, the tool falls
back to the explicit ‘sbom’ options and built-in defaults.

For single-value application metadata such as ‘name/1’, ‘version/1’,
‘license/1’, ‘built_date/1’, ‘release_date/1’, ‘valid_until_date/1’,
‘supplier/1’, and ‘originator/1’, explicit ‘sbom’ options override the
values declared by the application object.  For ‘creators/1’, explicit
‘creators/1’ options override the application object creators list.
Application external references declared by the object are combined with
any ‘application_external_reference/2’ options.

For CycloneDX exports, the generated BOM also includes a ‘serialNumber’
and records the Logtalk ‘sbom’ generator itself under
‘metadata.tools.components’.  The BOM document license is exported as
‘metadata.licenses’ with the SPDX identifier ‘CC0-1.0’.  The CycloneDX
BOM itself also exports top-level ‘externalReferences’ for the Logtalk
website and the Logtalk git repository.

   - ‘bom_external_reference(Type, URL)’ Adds a top-level CycloneDX
     ‘externalReferences’ entry to the generated BOM. This option is
     ignored for SPDX exports.  It can be repeated to export multiple
     references.  The built-in Logtalk website and git repository
     references are still exported by default.  Runtime components are
     exported with explicit CycloneDX ‘scope’ ‘required’, while the
     ‘sbom’ generator listed under ‘metadata.tools.components’ is
     exported with ‘scope’ ‘excluded’.  When available from existing
     metadata, CycloneDX components also export ‘externalReferences’:
     Logtalk and the ‘sbom’ tool export a website reference, the backend
     component exports a website reference from the bundled backend
     table, and loaded packs export their ‘home/1’ and version source
     URL values as website and distribution references.  For SPDX
     exports, the default ‘creationInfo.creators’ entry is a versioned
     tool identifier derived from the ‘sbom’ tool version.  When URL
     metadata is available, SPDX packages also export ‘externalRefs’:
     the Logtalk and backend packages export website references, loaded
     packs export website and distribution references, and
     ‘application_external_reference/2’ options are mapped to SPDX
     package external references for the application package.

The public predicates are:

   - ‘document/1’

   - ‘document/2’

   - ‘export/1’

   - ‘export/2’

The ‘document/1-2’ predicates return a JSON term.  The ‘export/1-2’
predicates write the JSON document to any sink accepted by the
‘json::generate/2’ predicate, including ‘atom(Atom)’ and ‘file(Path)’.
Follows the list of supported options.

Global/application options:

   - ‘name(Name)’ Sets the application name.  Exported as the SPDX
     application package name and as the CycloneDX
     ‘metadata.component.name’.  When exactly one object conforming to
     ‘application_protocol’ is loaded and declares ‘name/1’, that value
     is used by default.  Otherwise, the default is
     ‘loaded-application’.

   - ‘format(Format)’ Selects the export format.  Possible values are
     ‘spdx’ and ‘cyclonedx’.  Default is ‘spdx’.

   - ‘version(Version)’ Sets the application version.  Exported as the
     SPDX application package ‘versionInfo’ and as the CycloneDX
     ‘metadata.component.version’.  When exactly one object conforming
     to ‘application_protocol’ is loaded and declares ‘version/1’, that
     value is used by default.  Otherwise, the default is ‘0.0.0’.

   - ‘application_license(License)’ Sets the application license.
     Exported as the SPDX application package ‘licenseConcluded’ and
     ‘licenseDeclared’ fields and, unless the value is ‘NOASSERTION’, as
     the CycloneDX ‘metadata.component.licenses’ entry, using
     ‘license.id’ for SPDX license identifiers, ‘expression’ for SPDX
     license expressions, and ‘license.name’ otherwise.  When exactly
     one object conforming to ‘application_protocol’ is loaded and
     declares ‘license/1’, that value is used by default.  Otherwise,
     the default is ‘NOASSERTION’.

   - ‘application_built_date(Date)’ Sets the application build date.
     Exported as the SPDX application package ‘builtDate’ field and as
     the CycloneDX custom property ‘logtalk:sbom:built_date’.  When
     exactly one object conforming to ‘application_protocol’ is loaded
     and declares ‘built_date/1’, that value is used by default.
     Otherwise, the default is not exporting this information.

   - ‘application_release_date(Date)’ Sets the application release date.
     Exported as the SPDX application package ‘releaseDate’ field and as
     the CycloneDX custom property ‘logtalk:sbom:release_date’.  When
     exactly one object conforming to ‘application_protocol’ is loaded
     and declares ‘release_date/1’, that value is used by default.
     Otherwise, the default is not exporting this information.

   - ‘application_valid_until_date(Date)’ Sets the application validity
     limit date.  Exported as the SPDX application package
     ‘validUntilDate’ field and as the CycloneDX custom property
     ‘logtalk:sbom:valid_until_date’.  When exactly one object
     conforming to ‘application_protocol’ is loaded and declares
     ‘valid_until_date/1’, that value is used by default.  Otherwise,
     the default is not exporting this information.

   - ‘application_supplier(Supplier)’ Sets the application supplier.
     Exported as the SPDX application package ‘supplier’ field.  For
     CycloneDX, exported as ‘metadata.component.supplier’ when using the
     ‘Organization: Name’ convention and also as the custom property
     ‘logtalk:sbom:supplier’.  When exactly one object conforming to
     ‘application_protocol’ is loaded and declares ‘supplier/1’, that
     value is used by default.  Otherwise, the default is not exporting
     this information.

   - ‘application_originator(Originator)’ Sets the application
     originator.  Exported as the SPDX application package ‘originator’
     field.  For CycloneDX, exported as
     ‘metadata.component.manufacturer’ when using the ‘Organization:
     Name’ convention, or as ‘metadata.component.authors’ when using the
     ‘Person: Name’ convention, and also as the custom property
     ‘logtalk:sbom:originator’.  When exactly one object conforming to
     ‘application_protocol’ is loaded and declares ‘originator/1’, that
     value is used by default.  Otherwise, the default is not exporting
     this information.

   - ‘application_external_reference(Type, Locator)’ Adds application
     reference metadata.  For SPDX exports, this becomes an application
     package ‘externalRefs’ entry.  For CycloneDX exports, URL-based
     references are exported under
     ‘metadata.component.externalReferences’, while package and
     provenance identifiers use the dedicated component identity fields.
     This option can be repeated to export multiple references.  When
     exactly one object conforming to ‘application_protocol’ is loaded,
     its declared ‘external_reference/2’ metadata is also exported.  The
     ‘homepage/1’, ‘distribution/1’, ‘package/1’, ‘repository/1’,
     ‘git_object_identifier/1’, and ‘software_heritage_identifier/1’
     predicates are mapped to ‘website’, ‘distribution’, ‘purl’, ‘vcs’,
     ‘gitoid’, and ‘swh’ SBOM reference types, respectively.  SPDX
     categories are inferred from the reference type, with ‘purl’
     exported under ‘PACKAGE-MANAGER’ and ‘gitoid’ and ‘swh’ exported
     under ‘PERSISTENT-ID’.  For CycloneDX exports, ‘purl’ is written to
     ‘metadata.component.purl’, ‘gitoid’ values to
     ‘metadata.component.omniborId’, and ‘swh’ values to
     ‘metadata.component.swhid’.

   - ‘namespace(Namespace)’ Sets the base document namespace URI. A
     process and timestamp suffix is added automatically to guarantee
     uniqueness.  This option only applies to SPDX exports
     (‘documentNamespace’) and is ignored for CycloneDX exports.
     Default is ‘https://logtalk.org/spdxdocs/logtalk-sbom’.

   - ‘creators(Creators)’ Adds all atoms in the list ‘Creators’ to the
     SPDX ‘creationInfo.creators’ list and the CycloneDX
     ‘metadata.authors’ list.  When no creator option is provided, and
     exactly one object conforming to ‘application_protocol’ is loaded
     with a declared ‘creators/1’ predicate, that list is used.
     Otherwise, the default for SPDX exports is the versioned tool
     identifier ‘Tool: Logtalk SBOM generator-<version>’ and the default
     for CycloneDX exports is ‘Logtalk SBOM generator’.

   - ‘validate_export(Boolean)’ When ‘true’, validates the generated
     document against the bundled schema for the selected format before
     exporting it.  Default is ‘false’.

Logtalk options:

   - ‘logtalk_license(License)’ Sets the Logtalk component license.
     Exported as the SPDX Logtalk package ‘licenseConcluded’ and
     ‘licenseDeclared’ fields and, unless the value is ‘NOASSERTION’, as
     the CycloneDX component ‘licenses’ entry, using ‘license.id’ for
     SPDX license identifiers, ‘expression’ for SPDX license
     expressions, and ‘license.name’ otherwise.  Default is
     ‘Apache-2.0’.

   - ‘logtalk_built_date(Date)’ Sets the Logtalk build date.  Exported
     as the SPDX Logtalk package ‘builtDate’ field and as the CycloneDX
     custom property ‘logtalk:sbom:built_date’.  Default is not
     exporting this information.

   - ‘logtalk_release_date(Date)’ Sets the Logtalk release date.
     Exported as the SPDX Logtalk package ‘releaseDate’ field and as the
     CycloneDX custom property ‘logtalk:sbom:release_date’.  Default is
     not exporting this information.

   - ‘logtalk_valid_until_date(Date)’ Sets the Logtalk validity limit
     date.  Exported as the SPDX Logtalk package ‘validUntilDate’ field
     and as the CycloneDX custom property
     ‘logtalk:sbom:valid_until_date’.  Default is not exporting this
     information.

   - ‘logtalk_supplier(Supplier)’ Sets the Logtalk supplier.  Exported
     as the SPDX Logtalk package ‘supplier’ field.  For CycloneDX,
     exported as the component ‘supplier’ when using the ‘Organization:
     Name’ convention and also as the custom property
     ‘logtalk:sbom:supplier’.  Default is not exporting this
     information.

   - ‘logtalk_originator(Originator)’ Sets the Logtalk originator.
     Exported as the SPDX Logtalk package ‘originator’ field.  For
     CycloneDX, exported as the component ‘manufacturer’ or ‘authors’
     entry, depending on the value convention, and also as the custom
     property ‘logtalk:sbom:originator’.  Default is not exporting this
     information.

Backend options:

   - ‘backend_license(License)’ Sets the backend component license.
     Exported as the SPDX backend package ‘licenseConcluded’ and
     ‘licenseDeclared’ fields and, unless the value is ‘NOASSERTION’, as
     the CycloneDX component ‘licenses’ entry, using ‘license.id’ for
     SPDX license identifiers, ‘expression’ for SPDX license
     expressions, and ‘license.name’ otherwise.  Default is the license
     specified in the ‘backend/3’ table.

   - ‘backend_built_date(Date)’ Sets the backend build date.  Exported
     as the SPDX backend package ‘builtDate’ field and as the CycloneDX
     custom property ‘logtalk:sbom:built_date’.  Default is not
     exporting this information.

   - ‘backend_release_date(Date)’ Sets the backend release date.
     Exported as the SPDX backend package ‘releaseDate’ field and as the
     CycloneDX custom property ‘logtalk:sbom:release_date’.  Default is
     not exporting this information.

   - ‘backend_valid_until_date(Date)’ Sets the backend validity limit
     date.  Exported as the SPDX backend package ‘validUntilDate’ field
     and as the CycloneDX custom property
     ‘logtalk:sbom:valid_until_date’.  Default is not exporting this
     information.

   - ‘backend_supplier(Supplier)’ Sets the backend supplier.  Exported
     as the SPDX backend package ‘supplier’ field.  For CycloneDX,
     exported as the component ‘supplier’ when using the ‘Organization:
     Name’ convention and also as the custom property
     ‘logtalk:sbom:supplier’.  Default is not exporting this
     information.

   - ‘backend_originator(Originator)’ Sets the backend originator.
     Exported as the SPDX backend package ‘originator’ field.  For
     CycloneDX, exported as the component ‘manufacturer’ or ‘authors’
     entry, depending on the value convention, and also as the custom
     property ‘logtalk:sbom:originator’.  Default is not exporting this
     information.

Pack options:

   - ‘pack_license(Pack, License)’ Sets the license for a loaded pack
     named ‘Pack’.  Exported as the SPDX pack package ‘licenseConcluded’
     and ‘licenseDeclared’ fields and, unless the value is
     ‘NOASSERTION’, as the CycloneDX component ‘licenses’ entry, using
     ‘license.id’ for SPDX license identifiers, ‘expression’ for SPDX
     license expressions, and ‘license.name’ otherwise.  Default for
     packs without an explicit option is the result of sending the pack
     specification object the message ‘license(License)’, falling back
     to ‘NOASSERTION’ when no license is available.  Loaded packs also
     export a SPDX package ‘downloadLocation’ from the pack
     specification ‘version/6’ third argument and, when available, a
     SPDX ‘homepage’ from the pack specification ‘home/1’ predicate.
     Pack ‘home/1’ and ‘version/6’ URLs are also exported as SPDX
     package ‘externalRefs’ with ‘website’ and ‘distribution’
     ‘referenceType’ values.  Pack checksums are exported as SPDX
     package checksums and CycloneDX component hashes when the pack
     specification defines them in the ‘version/6’ predicate fourth
     argument.

   - ‘pack_built_date(Pack, Date)’ Sets the build date for the loaded
     pack named ‘Pack’.  Exported as the SPDX pack package ‘builtDate’
     field and as the CycloneDX custom property
     ‘logtalk:sbom:built_date’.  Default is not exporting this
     information.

   - ‘pack_release_date(Pack, Date)’ Sets the release date for the
     loaded pack named ‘Pack’.  Exported as the SPDX pack package
     ‘releaseDate’ field and as the CycloneDX custom property
     ‘logtalk:sbom:release_date’.  Default is not exporting this
     information.

   - ‘pack_valid_until_date(Pack, Date)’ Sets the validity limit date
     for the loaded pack named ‘Pack’.  Exported as the SPDX pack
     package ‘validUntilDate’ field and as the CycloneDX custom property
     ‘logtalk:sbom:valid_until_date’.  Default is not exporting this
     information.

   - ‘pack_supplier(Pack, Supplier)’ Sets the supplier for the loaded
     pack named ‘Pack’.  Exported as the SPDX pack package ‘supplier’
     field.  For CycloneDX, exported as the component ‘supplier’ when
     using the ‘Organization: Name’ convention and also as the custom
     property ‘logtalk:sbom:supplier’.  Default is not exporting this
     information.

   - ‘pack_originator(Pack, Originator)’ Sets the originator for the
     loaded pack named ‘Pack’.  Exported as the SPDX pack package
     ‘originator’ field.  For CycloneDX, exported as the component
     ‘manufacturer’ or ‘authors’ entry, depending on the value
     convention, and also as the custom property
     ‘logtalk:sbom:originator’.  Default is not exporting this
     information.

Examples:

     | ?- sbom::document(Document).

     | ?- sbom::document(Document, [name(my_app), version('1.2.3')]).

     | ?- sbom::export(file('sbom.spdx.json')).

     | ?- sbom::export(file('sbom.cdx.json'), [format(cdx)]).

     | ?- sbom::export(atom(Atom), [
             format(cdx),
             name(my_app),
             version('1.2.3'),
             application_license('MIT'),
             logtalk_license('Apache-2.0'),
             backend_license('BSD-2-Clause'),
             application_built_date('2026-03-23T00:00:00Z'),
             application_release_date('2026-03-23T00:00:00Z'),
             application_valid_until_date('2027-03-23T00:00:00Z'),
             application_supplier('Organization: Example Application'),
             application_originator('Person: Application Maintainer'),
             bom_external_reference(documentation, 'https://example.com/my_app/sbom'),
             application_external_reference(website, 'https://example.com/my_app'),
             application_external_reference(vcs, 'https://example.com/my_app.git'),
             logtalk_supplier('Organization: Logtalk.org'),
             backend_supplier('Organization: Backend Vendor'),
             pack_license(my_pack, 'MIT'),
             pack_supplier(my_pack, 'Organization: Pack Maintainer'),
             creators(['Tool: My build pipeline', 'Person: Release Manager', 'Organization: Example, Inc.']),
             validate_export(true)
          ]).

Use the ‘.spdx.json’ extension for SPDX exports and the ‘.cdx.json’
extension for CycloneDX exports.

See the ‘sbom-example.spdx.json’ file for a representative SPDX export.
See the ‘sbom-example.cdx.json’ file for a representative CycloneDX
export.


File: TheLogtalkHandbook-3.101.0.info,  Node: Known issues<9>,  Prev: Usage<11>,  Up: sbom

5.22.5 Known issues
-------------------

The ECLiPSe and GNU Prolog backends fail several ‘sbom’ tests and cannot
be used for CycloneDX exports.  The root cause is that both backends are
limited to the US-ASCII charset, which prevents processing the
SPDX/CycloneDX schema data required for CycloneDX license validation and
export validation.


File: TheLogtalkHandbook-3.101.0.info,  Node: tool_diagnostics,  Next: tutor,  Prev: sbom,  Up: Developer Tools

5.23 ‘tool_diagnostics’
=======================

This tool provides the shared ‘tool_diagnostics_protocol’ protocol and
the ‘tool_diagnostics_common’ category used by developer tools such as
‘dead_code_scanner’, ‘lgtdoc’, ‘lgtunit’, and ‘linter_reporter’ to
expose machine-readable diagnostics.

The protocol is designed so that producer tools can keep their own
internal semantics while still providing a common interface for querying
diagnostics directly or for generating SARIF reports using the ‘sarif’
tool.

* Menu:

* API documentation: API documentation<18>.
* Loading: Loading<19>.
* Protocol overview::
* Term conventions::
* Usage: Usage<12>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<18>,  Next: Loading<19>,  Up: tool_diagnostics

5.23.1 API documentation
------------------------

This tool API documentation is available at:

‘../../apis/library_index.html#tool_diagnostics_protocol’


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<19>,  Next: Protocol overview,  Prev: API documentation<18>,  Up: tool_diagnostics

5.23.2 Loading
--------------

Load the protocol and common category definitions using:

     | ?- logtalk_load(tool_diagnostics(loader)).
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Protocol overview,  Next: Term conventions,  Prev: Loading<19>,  Up: tool_diagnostics

5.23.3 Protocol overview
------------------------

The protocol defines predicates for reporting:

   - tool metadata using ‘diagnostics_tool/5’

   - supported target patterns using ‘diagnostic_target/1’

   - rule descriptors using ‘diagnostic_rule/5’ and ‘diagnostic_rules/1’

   - diagnostics using ‘diagnostic/2-3’ and ‘diagnostics/2-3’

   - summaries using ‘diagnostics_summary/2-3’

   - preflight issues using ‘diagnostics_preflight/2-3’

Common target terms include ‘all’, ‘file(File)’, ‘directory(Directory)’,
‘rdirectory(Directory)’, ‘library(Library)’, ‘rlibrary(Library)’,
‘entity(Entity)’, and ‘tests(Object)’.

Predicates taking an ‘Options’ argument must accept the common option
‘explanations(Boolean)’.  Tools may use it to include
‘explanation(Text)’ properties when available, but implementations that
do not provide additional explanation text must still accept the option
as a no-op.


File: TheLogtalkHandbook-3.101.0.info,  Node: Term conventions,  Next: Usage<12>,  Prev: Protocol overview,  Up: tool_diagnostics

5.23.4 Term conventions
-----------------------

Tool metadata uses terms of the form:

     diagnostics_tool(Id, Name, Version, InformationURI, Properties)

The ‘Id’ and ‘Name’ arguments identify the tool.  The ‘Version’ argument
should be derived reflectively from the implementing object ‘info/1’
metadata using ‘object_property/2’ instead of being hardcoded.  The
‘InformationURI’ argument is a stable tool home or documentation URI and
is exported by the ‘sarif’ tool as the SARIF
‘tool.driver.informationUri’ value.

The ‘Properties’ list is intended for exporter and post-processing
hints.  The current ‘sarif’ tool interprets the following entries:

   - ‘guid(Guid)’ sets the SARIF ‘tool.driver.guid’ value when present.

   - ‘fingerprint_algorithm(Algorithm)’ sets the exported run
     ‘fingerprintAlgorithm’ property and selects the canonical result
     fingerprint key.  The current implementation distinguishes
     ‘canonical_finding_v1’ from the default warning-oriented path and
     computes result identities from normalized relative locations
     instead of raw absolute file paths.

   - ‘automation_id(target)’ requests that the SARIF
     ‘run.automationDetails.id’ value be derived from the queried target
     term, allowing different targets of the same tool to produce
     distinct run identities.

   - ‘automation_id(tool)’ denotes a tool-scoped automation identifier.
     In the current ‘sarif’ implementation this is redundant because
     omitting ‘automation_id(target)’ already falls back to the tool
     identifier.

   - ‘include_invocations(true)’ requests a SARIF ‘invocations’ section,
     including ‘toolExecutionNotifications’ when preflight issues exist.

   - ‘include_git_metadata(true)’ requests SARIF ‘gitBranch’ and
     ‘gitCommitHash’ run properties when a stable Git context can be
     inferred.  When this succeeds, the ‘sarif’ tool also normalizes
     artifact locations and fingerprint inputs relative to the
     repository root.  The ‘gitBranch’ value is descriptive metadata;
     the ‘gitCommitHash’ value provides the stable revision identity
     used to disambiguate repository-relative paths.

   - ‘include_version_control_provenance(true)’ requests SARIF
     ‘versionControlProvenance’ data when repository details can be
     inferred from diagnostic file paths.

   - ‘count_key(Key)’ selects the property name used for the exported
     count, e.g.  ‘diagnosticsCount’ or ‘totalWarnings’.

When ‘include_git_metadata(true)’ is not present or a stable Git context
cannot be inferred, the ‘sarif’ tool falls back to
application-root-relative artifact locations and fingerprint inputs
instead.

Rule descriptors use terms of the form:

     diagnostic_rule(RuleId, ShortDescription, FullDescription, DefaultSeverity, Properties)

The ‘diagnostic_rules/1’ predicate should return these descriptors in a
stable order.  Rule descriptor properties may contain terms such as
‘guid(Guid)’, ‘help(Text)’, ‘help_uri(URI)’, ‘tags(Tags)’, and
‘precision(Precision)’.

Diagnostics use terms of the form:

     diagnostic(RuleId, Severity, Confidence, Message, Context, File, Lines, Properties)

The ‘Context’ argument is represented using the term ‘context(Kind,
Identifier)’ where ‘Kind’ is a tool-defined atom such as ‘file’,
‘object’, ‘category’, ‘protocol’, or ‘test_set’.  For file-scoped
diagnostics, ‘Identifier’ is the source file path when available and the
empty atom otherwise.  Diagnostics originating in an included file may
still use an entity context when the ‘include/1’ directive appears
inside that entity; otherwise they are file-scoped.

The ‘File’ argument is a source file path or the empty atom when
unavailable.  The ‘Lines’ argument uses the ‘Start-End’ notation.  The
value ‘0-0’ means that no precise line information is available.

Supported severity values are ‘error’, ‘warning’, and ‘note’.  Supported
confidence values are ‘high’, ‘medium’, ‘low’, and ‘not_applicable’.

The ‘Properties’ argument should include stable structured metadata such
as ‘raw_term(Term)’, ‘explanation(Text)’, ‘flag(Flag)’,
‘directive(Directive)’, ‘indicator(Indicator)’, ‘key(Key)’,
‘test(Test)’, ‘option(Option)’, and any other tool-specific facts useful
for post-processing.

Preflight issues use terms of the form:

     preflight_issue(Id, Severity, Message, Context, File, Lines, Properties)

Preflight issues describe prerequisites or analysis quality issues
instead of findings.

Summaries use terms of the form:

     diagnostics_summary(Target, TotalContexts, TotalDiagnostics, Breakdown, ContextSummaries)

The ‘Breakdown’ argument uses a ‘diagnostic_breakdown(RuleCounts,
SeverityCounts, ConfidenceCounts)’ term and ‘ContextSummaries’ is a list
of ‘context_summary(Context, DiagnosticsCount, Breakdown)’ terms.

Rule counts use ‘rule_count(RuleId, Count)’ terms, severity counts use
‘severity_count(Severity, Count)’ terms, and confidence counts use
‘confidence_count(Confidence, Count)’ terms.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<12>,  Prev: Term conventions,  Up: tool_diagnostics

5.23.5 Usage
------------

Tools implementing this protocol can be queried directly for diagnostics
after compiling code that results in the production of diagnostics.  For
example:

     | ?- logtalk_load(dead_code_scanner(loader)).
     ...

     | ?- logtalk_load(my_library(loader)).
     ...

     | ?- dead_code_scanner::diagnostics(library(my_library), Diagnostics).
     ...

To serialize diagnostics as SARIF, load the standalone ‘sarif’ tool and
generate a report from a diagnostics producer:

     | ?- logtalk_load(sarif(loader)).
     ...

     | ?- sarif::generate(dead_code_scanner, entity(my_object), file('./report.sarif'), []).
     true.

To generate an explicit aggregate SARIF report with multiple diagnostics
producers, pass a list of ‘tool_spec(Tool, Target, Options)’ terms:

     | ?- sarif::generate([
     |        tool_spec(linter_reporter, all, []),
     |        tool_spec(dead_code_scanner, entity(my_object), [])
     |    ], file('./aggregate.sarif')).
     true.


File: TheLogtalkHandbook-3.101.0.info,  Node: tutor,  Next: wrapper,  Prev: tool_diagnostics,  Up: Developer Tools

5.24 ‘tutor’
============

This tool adds explanations and suggestions for selected warning and
error messages from the compiler/runtime and the developer tools.  It’s
specially useful for new users not yet familiar with the warning and
error messages and looking for advice on how to solve the reported
issues.

* Menu:

* API documentation: API documentation<19>.
* Loading: Loading<20>.
* Usage: Usage<13>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<19>,  Next: Loading<20>,  Up: tutor

5.24.1 API documentation
------------------------

This tool API documentation is available at:

‘../../apis/library_index.html#tutor’


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<20>,  Next: Usage<13>,  Prev: API documentation<19>,  Up: tutor

5.24.2 Loading
--------------

This tool can be loaded using the query:

     | ?- logtalk_load(tutor(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<13>,  Prev: Loading<20>,  Up: tutor

5.24.3 Usage
------------

Simply load the tool at startup (e.g., from a settings file).  As an
example, with this tool loaded, instead of terse compiler warnings such
as:

     *     No matching clause for goal: baz(a)
     *       while compiling object main_include_compiler_warning
     *       in file logtalk/examples/errors/include_compiler_warning.lgt between lines 37-38
     *
     *     Duplicated clause: b(one)
     *       first found at or above line 45
     *       while compiling object main_include_compiler_warning
     *       in file logtalk/examples/errors/include_compiler_warning.lgt at or above line 48

the user will get:

     *     No matching clause for goal: baz(a)
     *       while compiling object main_include_compiler_warning
     *       in file logtalk/examples/errors/include_compiler_warning.lgt between lines 37-38
     *     Calls to locally defined predicates without a clause with a matching head
     *     fail. Typo in a predicate argument? Predicate definition incomplete?
     *
     *     Duplicated clause: b(one)
     *       first found at or above line 45
     *       while compiling object main_include_compiler_warning
     *       in file logtalk/examples/errors/include_compiler_warning.lgt at or above line 48
     *     Duplicated clauses are usually a source code editing error and can
     *     result in spurious choice-points, degrading performance. Delete or
     *     correct the duplicated clause to fix this warning.


File: TheLogtalkHandbook-3.101.0.info,  Node: wrapper,  Prev: tutor,  Up: Developer Tools

5.25 ‘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<20>.
* Loading: Loading<21>.
* Workflows::
* Customization: Customization<3>.
* Current limitations::


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<20>,  Next: Loading<21>,  Up: wrapper

5.25.1 API documentation
------------------------

This tool API documentation is available at:

‘../../apis/library_index.html#wrapper’


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<21>,  Next: Workflows,  Prev: API documentation<20>,  Up: wrapper

5.25.2 Loading
--------------

This tool can be loaded using the query:

     | ?- logtalk_load(wrapper(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Workflows,  Next: Customization<3>,  Prev: Loading<21>,  Up: wrapper

5.25.3 Workflows
----------------

The typical porting workflow is:

     | ?- wrapper::rdirectory(root_directory_of_prolog_code).
     ...
     | ?- wrapper::save.
     ...

See the next section on how to customize the API calls for more flexible
processing.


File: TheLogtalkHandbook-3.101.0.info,  Node: Customization<3>,  Next: Current limitations,  Prev: Workflows,  Up: wrapper

5.25.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(Directories)’
          list of sub-directories to exclude (default is ‘[]’)

   - 
          ‘include_wrapped_files(Boolean)’
          generate ‘include/1’ directives for the wrapped Prolog source files (default is ‘true’)

The use, by default, of ‘include/1’ directives to wrap the code in
Prolog source files facilitates running in parallel the Logtalk port and
the original Prolog code.  This is specially useful when the Prolog code
being ported lacks a comprehensive set of tests that could be adapted to
verify the Logtalk port.  The generated Logtalk files can also take
advantage of ‘uses/2’ directives, including predicate aliases and
predicate shorthands to minimize the changes to the original Prolog code
and help verify if replacement calls to Logtalk library predicates
provide the same semantics as the original calls.


File: TheLogtalkHandbook-3.101.0.info,  Node: Current limitations,  Prev: Customization<3>,  Up: wrapper

5.25.5 Current limitations
--------------------------

   - The tool cannot deal with syntax errors in the Prolog files.  These
     errors usually occur when using a backend Prolog system different
     from the one used to compile the original plain Prolog code.  A
     common cause of syntax errors is operator definitions.  These can
     often be solved by defining those operators for the Prolog backend
     used to run Logtalk and this tool.  An alternative is to preload
     the Prolog files where those operators are declared.  Preloading
     the plain Prolog application can also help in wrapping it by
     ensuring that its dependencies are also loaded.

   - The tool assumes that all files to be wrapped have different names
     (even if found in different directories).  If that is not the case,
     the name conflicts must be manually solved before using the tool.

   - There’s only preliminary support for dealing with meta-predicates
     and advise on missing meta-predicate directives.


File: TheLogtalkHandbook-3.101.0.info,  Node: Libraries,  Next: Ports,  Prev: Developer Tools,  Up: Top

6 Libraries
***********

The documentation of each library can also be found in the library
directory in the ‘NOTES.md’ file.

* Menu:

* Overview: Overview<2>.
* adaptive_boosting_classifier::
* agglomerative_clusterer::
* amqp::
* anomaly_detection_protocols::
* application::
* apriori_pattern_miner::
* arbitrary::
* arrangements::
* assignvars::
* avro::
* base32::
* base58::
* base64::
* base85::
* basic_types::
* bayesian_ridge_regression::
* borda_ranker::
* bradley_terry_ranker::
* c45_classifier::
* cartesian_products::
* cbor::
* character_sets::
* ccsds_frames::
* ccsds_link_profiles::
* ccsds_packet_services::
* ccsds_packetization::
* ccsds_packets::
* ccsds_tc_services::
* ccsds_time_codes::
* ccsds_time_fields::
* classification_protocols::
* clo_span_pattern_miner::
* clustering_protocols::
* colley_ranker::
* combinations::
* command_line_options::
* core::
* copeland_ranker::
* coroutining::
* crypto::
* crs_projections::
* csv::
* cuid2::
* cusum_anomaly_detector::
* datalog::
* dates::
* dates_tz::
* dbscan_clusterer::
* dependents::
* deques::
* derangements::
* dictionaries::
* dif::
* dimension_reduction_protocols::
* eclat_pattern_miner::
* edcg::
* elastic_net_regression::
* elo_ranker::
* events::
* ewma_anomaly_detector::
* expand_library_alias_paths::
* expecteds::
* format::
* fp_growth_pattern_miner::
* frequent_pattern_mining_protocols::
* gaussian_mixture_clusterer::
* gaussian_process_regression::
* genint::
* gensym::
* geojson::
* geospatial::
* git::
* glicko2_ranker::
* glicko2_periodic_ranker::
* gradient_boosting_classifier::
* gradient_boosting_regression::
* grammars::
* graphs::
* gravatar::
* gsp_pattern_miner::
* hashes::
* hdbscan_clusterer::
* heaps::
* hierarchical_clustering::
* hierarchies::
* hmac::
* hodge_rank::
* hook_flows::
* hook_objects::
* html::
* http_authenticate::
* http_client::
* http_client_core::
* http_cookies::
* http_core::
* http_cors::
* http_digest::
* http_directory_listing::
* http_htmx::
* http_multipart::
* http_parameters::
* http_router::
* http_server::
* http_server_core::
* http_session::
* http_socket_transport::
* http_process_transport::
* http_static_files::
* http_websocket::
* http_websocket_frames::
* http_websocket_handshake::
* http_websocket_messages::
* http_websocket_service::
* http_websocket_session::
* ica_projection::
* ids::
* ieee_754::
* intervals::
* iqr_anomaly_detector::
* iso_639::
* iso_3166::
* iso_4217::
* iso_9362::
* iso_13616::
* isolation_forest_anomaly_detector::
* java::
* json::
* json_graph::
* json_ld::
* json_lines::
* json_patch::
* json_path::
* json_pointer::
* json_rpc::
* json_schema::
* jwt::
* kcenters_clusterer::
* kemeny_young_ranker::
* kernel_svm_classifier::
* kernel_pca_projection::
* kmeans_clusterer::
* kmedians_clusterer::
* kmedoids_clusterer::
* kmodes_clusterer::
* knn_classifier::
* knn_distance_anomaly_detector::
* knn_regression::
* kprototypes_clusterer::
* ksuid::
* lasso_regression::
* lda_classifier::
* lda_projection::
* linda::
* linear_algebra::
* linear_regression::
* linear_svm_classifier::
* listing::
* lof_anomaly_detector::
* logging::
* logistic_regression_classifier::
* loops::
* massey_ranker::
* mcp_server::
* memcached::
* message_pack::
* meta::
* meta_compiler::
* mime_types::
* modified_z_score_anomaly_detector::
* mutations::
* multisets::
* nanoid::
* naive_bayes_classifier::
* nearest_centroid_classifier::
* nested_dictionaries::
* nmea::
* nmf_projection::
* open_api::
* open_ai::
* open_id::
* optics_clusterer::
* optionals::
* options::
* os::
* otp::
* partitions::
* pattern_mining_protocols::
* pca_projection::
* permutations::
* plackett_luce_ranker::
* plackett_luce_last_ranker::
* pls_projection::
* prefix_span_pattern_miner::
* probabilistic_pca_projection::
* process::
* protobuf::
* qda_classifier::
* queues::
* random::
* random_forest_classifier::
* random_forest_regression::
* random_projection::
* rank_centrality::
* ranked_pairs::
* ranking_protocols::
* reader::
* recorded_database::
* redis::
* regression_protocols::
* regression_tree::
* regularized_bradley_terry_ranker::
* rest::
* ridge_regression::
* s3::
* schulze_ranker::
* sequential_pattern_mining_protocols::
* sets::
* sgd_classifier::
* snowflakeid::
* sockets::
* spade_pattern_miner::
* simulated_annealing::
* statistics::
* stemming::
* stomp::
* string_distance::
* strings::
* subsequences::
* term_io::
* thurstone_mosteller_ranker::
* time_scales::
* timeout::
* tle_orbits::
* toml::
* toon::
* truncated_svd_projection::
* tsv::
* types::
* tzif::
* ulid::
* unicode_data::
* union_find::
* url::
* uuid::
* validations::
* wkt_wkb::
* yaml::
* z_score_anomaly_detector::
* zippers::


File: TheLogtalkHandbook-3.101.0.info,  Node: Overview<2>,  Next: adaptive_boosting_classifier,  Up: Libraries

6.1 Overview
============

This folder contains libraries of useful objects, categories, and
protocols.  The currently available libraries can be grouped by theme as
follows (note that some libraries naturally span multiple themes):

* Menu:

* Library groups::
* Library documentation::
* Loading libraries::
* Testing libraries::
* Credits::
* Other notes: Other notes<2>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Library groups,  Next: Library documentation,  Up: Overview<2>

6.1.1 Library groups
--------------------

   - Application metadata, configuration, and logging: ‘application’,
     ‘expand_library_alias_paths’, ‘command_line_options’, ‘logging’,
     and ‘options’.

   - Types, collections and generic data processing: ‘basic_types’,
     ‘types’, ‘assignvars’, ‘deques’, ‘dictionaries’,
     ‘nested_dictionaries’, ‘graphs’, ‘heaps’, ‘hierarchies’,
     ‘intervals’, ‘queues’, ‘sets’, ‘subsequences’, ‘union_find’, and
     ‘zippers’.

   - Combinatorics: ‘arrangements’, ‘cartesian_products’,
     ‘combinations’, ‘derangements’, ‘multisets’, ‘partitions’, and
     ‘permutations’.

   - Meta-programming: ‘meta’ and ‘meta_compiler’

   - Monoid implementations: ‘expecteds’, ‘optionals’, and
     ‘validations’.

   - Control, state, and developer support: ‘dependents’, ‘edcg’,
     ‘events’, ‘listing’, ‘reader’, and ‘term_io’.

   - Term- and goal-expansion: ‘hook_flows’ and ‘hook_objects’.

   - Portability: ‘coroutining’, ‘dif’, ‘format’, ‘process’,
     ‘recorded_database’, and ‘timeout’.

   - Dates and time: ‘dates’, ‘dates_tz’, ‘time_scales’, and ‘tzif’.

   - Geospatial data: ‘crs_projections’, ‘geojson’, ‘geohash’,
     ‘geospatial’, ‘nmea’, ‘tle_orbits’, and ‘wkt_wkb’

   - Space communications and telemetry: ‘ccsds_frames’,
     ‘ccsds_link_profiles’, ‘ccsds_packet_services’,
     ‘ccsds_packetization’, ‘ccsds_packets’, ‘ccsds_tc_services’,
     ‘ccsds_time_codes’, ‘ccsds_time_fields’,

   - Text and NLP: ‘character_sets’, ‘grammars’, ‘stemming’,
     ‘string_distance’, and ‘strings’.

   - Web and HTTP APIs:

        - High-level libraries: ‘html’, ‘mime_types’, ‘url’,
          ‘http_client’, ‘http_server’, ‘http_websocket’, ‘gravatar’,
          ‘open_api’, ‘open_ai’, ‘open_id’, ‘rest’, and ‘s3’.

        - Supporting libraries: ‘http_core’, ‘http_authenticate’,
          ‘http_client_core’, ‘http_cookies’, ‘http_cors’,
          ‘http_digest’, ‘http_directory_listing’, ‘http_htmx’,
          ‘http_multipart’, ‘http_parameters’, ‘http_router’,
          ‘http_server_core’, ‘http_session’, ‘http_socket_transport’,
          ‘http_process_transport’, ‘http_static_files’,
          ‘http_websocket_messages’, ‘http_websocket_service’,
          ‘http_websocket_session’.

   - Identifiers: ‘cuid2’, ‘genint’, ‘gensym’, ‘ids’, ‘ksuid’, ‘nanoid’,
     ‘snowflakeid’, ‘ulid’, and ‘uuid’.

   - Interchange formats and wire protocols: ‘amqp’, ‘avro’, ‘base32’,
     ‘base58’, ‘base64’, ‘base85’, ‘cbor’, ‘csv’, ‘json’, ‘json_graph’,
     ‘json_ld’, ‘json_lines’, ‘json_patch’, ‘json_path’, ‘json_pointer’,
     ‘json_rpc’, ‘json_schema’, ‘message_pack’, ‘mcp_server’,
     ‘protobuf’, ‘stomp’, ‘toml’, ‘toon’, ‘tsv’, and ‘yaml’.

   - Coordination and data stores: ‘linda’, ‘memcached’, and ‘redis’.

   - System and external integration: ‘git’, ‘java’, ‘os’, and
     ‘sockets’.

   - Logic and symbolic computing: ‘datalog’.

   - Security and integrity: ‘crypto’, ‘hashes’, ‘hmac’, ‘otp’, and
     ‘jwt’.

   - Randomness: ‘arbitrary’, ‘mutations’, and ‘random’.

   - Mathematics, statistics, and optimization: ‘ieee_754’,
     ‘linear_algebra’, ‘simulated_annealing’, and ‘statistics’.

   - Machine learning:

        - Classification: ‘classification_protocols’,
          ‘adaptive_boosting_classifier’, ‘c45_classifier’,
          ‘gradient_boosting_classifier’, ‘kernel_svm_classifier’,
          ‘knn_classifier’, ‘lda_classifier’, ‘linear_svm_classifier’,
          ‘logistic_regression_classifier’, ‘naive_bayes_classifier’,
          ‘nearest_centroid_classifier’, ‘qda_classifier’,
          ‘random_forest_classifier’, and ‘sgd_classifier’.

        - Anomaly detection: ‘anomaly_detection_protocols’,
          ‘cusum_anomaly_detector’, ‘ewma_anomaly_detector’,
          ‘iqr_anomaly_detector’, ‘isolation_forest_anomaly_detector’,
          ‘knn_distance_anomaly_detector’, ‘lof_anomaly_detector’,
          ‘modified_z_score_anomaly_detector’, and
          ‘z_score_anomaly_detector’.

        - Regression: ‘regression_protocols’,
          ‘bayesian_ridge_regression’, ‘elastic_net_regression’,
          ‘gradient_boosting_regression’, ‘gaussian_process_regression’,
          ‘knn_regression’, ‘lasso_regression’, ‘linear_regression’,
          ‘random_forest_regression’, ‘regression_tree’, and
          ‘ridge_regression’.

        - Ranking: ‘ranking_protocols’, ‘borda_ranker’,
          ‘bradley_terry_ranker’, ‘colley_ranker’, ‘copeland_ranker’,
          ‘elo_ranker’, ‘glicko2_ranker’, ‘glicko2_periodic_ranker’,
          ‘hodge_rank’, ‘kemeny_young_ranker’, ‘massey_ranker’,
          ‘plackett_luce_ranker’, ‘plackett_luce_last_ranker’,
          ‘rank_centrality’, ‘ranked_pairs’,
          ‘regularized_bradley_terry_ranker’, ‘schulze_ranker’, and
          ‘thurstone_mosteller_ranker’.

        - Clustering: ‘clustering_protocols’, ‘agglomerative_clusterer’,
          ‘dbscan_clusterer’, ‘gaussian_mixture_clusterer’,
          ‘hdbscan_clusterer’, ‘hierarchical_clustering’,
          ‘kcenters_clusterer’, ‘kmeans_clusterer’,
          ‘kmedians_clusterer’, ‘kmedoids_clusterer’,
          ‘kmodes_clusterer’, ‘kprototypes_clusterer’, and
          ‘optics_clusterer’.

        - Dimension reduction: ‘dimension_reduction_protocols’,
          ‘ica_projection’, ‘kernel_pca_projection’, ‘lda_projection’,
          ‘nmf_projection’, ‘pca_projection’, ‘pls_projection’,
          ‘probabilistic_pca_projection’, and ‘random_projection’.

        - Pattern mining: ‘pattern_mining_protocols’,
          ‘frequent_pattern_mining_protocols’,
          ‘sequential_pattern_mining_protocols’,
          ‘apriori_pattern_miner’, ‘clo_span_pattern_miner’,
          ‘eclat_pattern_miner’, ‘fp_growth_pattern_miner’,
          ‘gsp_pattern_miner’, ‘prefix_span_pattern_miner’, and
          ‘spade_pattern_miner’.

In addition to the loader-based libraries, this directory also contains
a small number of standalone reusable entities, namely ‘attributes’,
‘cloning’, ‘counters’, and ‘streamvars’.

Specific notes about individual libraries can be found in the
corresponding library directory ‘NOTES.md’ files.

A plain Prolog version of the Unicode 6.2 standard is also included in
the ‘unicode_data’ folder.  See its ‘README.md’ file for details.

A ‘parallel_logtalk_processes_setup.pl’ Prolog file is also provided
with sample code for selected backend Prolog compilers for initializing
Logtalk processes such that each process uses a unique scratch
directory, therefore allowing parallel process execution (e.g., for
usage at continuous integration servers).  Starting with Logtalk 3.48.0,
this setup is only required in general when running with the ‘clean’
flag turned off.  See the comments in the file itself for usage
instructions.


File: TheLogtalkHandbook-3.101.0.info,  Node: Library documentation,  Next: Loading libraries,  Prev: Library groups,  Up: Overview<2>

6.1.2 Library documentation
---------------------------

Specific notes about each library can be found in the corresponding
‘NOTES.md’ files.  HTML documentation for each library API can be found
on the ‘docs’ directory (open the ‘../docs/handbook/index.html’ file
with your web browser).


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading libraries,  Next: Testing libraries,  Prev: Library documentation,  Up: Overview<2>

6.1.3 Loading libraries
-----------------------

All the individual libraries can be loaded using the ‘<library
name>(loader)’ notation as argument for the compiling and loading
predicates.  For example:

     | ?- logtalk_load(random(loader)).

There is also a file named ‘all_loader.lgt’ that will load all
libraries.  Simply type the goal:

     | ?- logtalk_load(library(all_loader)).

As a general rule, always use the corresponding loader file to load a
library.  Most library entities are part of small hierarchies or depend
on other libraries and thus cannot be loaded and compiled separately
(e.g., the ‘list’ object implements the ‘listp’ protocol and is part of
a basic types hierarchy).  Using the loader files takes care of all
dependencies and also ensures compilation in optimized mode.


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing libraries,  Next: Credits,  Prev: Loading libraries,  Up: Overview<2>

6.1.4 Testing libraries
-----------------------

Most of the libraries include unit tests in their directory, together
with a ‘tester.lgt’ file for running them.  For example, to run the
tests for the ‘random’ library, we can use the goal:

     | ?- logtalk_load(random(tester)).

To run all library tests, we can use the ‘logtalk_tester’ automation
script from the ‘library’ directory at the root of the Logtalk
distribution.  For example, assuming the Logtalk user directory is
‘~/logtalk’ and that we want to run the tests using ECLiPSe as the
backend Prolog compiler:

     $ cd ~/logtalk/library
     $ logtalk_tester -p eclipse


File: TheLogtalkHandbook-3.101.0.info,  Node: Credits,  Next: Other notes<2>,  Prev: Testing libraries,  Up: Overview<2>

6.1.5 Credits
-------------

Some code in this library is based on public domain Prolog code, in
particular, code adopted from the Edinburgh Prolog library.  The
definition of the predicate ‘reverse/2’ in the ‘list’ object is from
Richard O’Keefe and can be found in its book “The Craft of Prolog”.

Some elements of this library are inspired by Richard O’Keefe library
proposal available at:

‘http://www.cs.otago.ac.nz/staffpriv/ok/pllib.htm’

Some libraries, or parts of libraries, are either ports of Prolog system
libraries or inspired by Prolog system libraries.  See the individual
library notes for details.  See also the ‘NOTICE.txt’ file at the root
of the Logtalk distribution for copyright information on third-party
source code.


File: TheLogtalkHandbook-3.101.0.info,  Node: Other notes<2>,  Prev: Credits,  Up: Overview<2>

6.1.6 Other notes
-----------------

Some files contained in this directory represent work in progress and
are not loaded by default by any loader utility file.


File: TheLogtalkHandbook-3.101.0.info,  Node: adaptive_boosting_classifier,  Next: agglomerative_clusterer,  Prev: Overview<2>,  Up: Libraries

6.2 ‘adaptive_boosting_classifier’
==================================

Adaptive Boosting (aka AdaBoost) classifier using C4.5 decision trees as
base learners.  Implements the SAMME (Stagewise Additive Modeling using
a Multi-class Exponential loss function) variant, which supports
multi-class classification by adjusting the weight update formula to
account for the number of classes.  Builds an ensemble of weighted
decision trees where each subsequent tree focuses on the examples
misclassified by previous trees: after each iteration, the weights of
misclassified examples are increased so that subsequent learners focus
more on difficult cases.

The library implements the ‘classifier_protocol’ defined in the
‘classification_protocols’ library.  It provides predicates for learning
an ensemble classifier from a dataset, using it to make predictions
(with class probabilities), and exporting it as a list of predicate
clauses or to a file.

Datasets are represented as objects implementing the ‘dataset_protocol’
protocol from the ‘classification_protocols’ library.  See ‘test_files’
directory for examples.

* Menu:

* API documentation: API documentation<21>.
* Loading: Loading<22>.
* Testing: Testing<17>.
* Features: Features<2>.
* Options: Options<3>.
* Classifier representation::
* References::
* Usage: Usage<14>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<21>,  Next: Loading<22>,  Up: adaptive_boosting_classifier

6.2.1 API documentation
-----------------------

Open the ‘../../docs/library_index.html#adaptive_boosting_classifier’
link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<22>,  Next: Testing<17>,  Prev: API documentation<21>,  Up: adaptive_boosting_classifier

6.2.2 Loading
-------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(adaptive_boosting_classifier(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<17>,  Next: Features<2>,  Prev: Loading<22>,  Up: adaptive_boosting_classifier

6.2.3 Testing
-------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(adaptive_boosting_classifier(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<2>,  Next: Options<3>,  Prev: Testing<17>,  Up: adaptive_boosting_classifier

6.2.4 Features
--------------

   - 'Adaptive Boosting': Iteratively trains weighted decision trees,
     focusing on misclassified examples

   - 'SAMME Algorithm': Supports multi-class classification via the
     SAMME variant of AdaBoost

   - 'C4.5 Base Learners': Uses C4.5 decision trees as weak learners for
     each boosting round

   - 'Weighted Voting': Final predictions determined by weighted voting
     where more accurate learners have higher weight

   - 'Probability Estimation': Provides confidence scores based on
     weighted vote proportions

   - 'Early Stopping': Training stops early if a perfect classifier is
     found or if a base learner is worse than random

   - 'Configurable Options': Number of estimators (boosting rounds)
     configurable via predicate options

   - 'Classifier Export': Learned classifiers can be exported as
     predicate clauses


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<3>,  Next: Classifier representation,  Prev: Features<2>,  Up: adaptive_boosting_classifier

6.2.5 Options
-------------

The following options can be passed to the ‘learn/3’ predicate:

   - ‘number_of_estimators(N)’: Number of boosting rounds / weak
     learners (default: 10)


File: TheLogtalkHandbook-3.101.0.info,  Node: Classifier representation,  Next: References,  Prev: Options<3>,  Up: adaptive_boosting_classifier

6.2.6 Classifier representation
-------------------------------

The learned classifier is represented as a compound term:

     ab_classifier(WeightedTrees, ClassValues, Options)

Where:

   - ‘WeightedTrees’: List of ‘weighted_tree(Alpha, C45Tree,
     AttributeNames)’ elements

   - ‘ClassValues’: List of possible class values

   - ‘Options’: List of options used during learning

When exported using ‘export_to_clauses/4’ or ‘export_to_file/4’, this
classifier term is serialized directly as the single argument of the
generated predicate clause so that the exported model can be loaded and
reused as-is.


File: TheLogtalkHandbook-3.101.0.info,  Node: References,  Next: Usage<14>,  Prev: Classifier representation,  Up: adaptive_boosting_classifier

6.2.7 References
----------------

  1. Freund, Y. and Schapire, R.E. (1997).  “A Decision-Theoretic
     Generalization of On-Line Learning and an Application to Boosting”.
     Journal of Computer and System Sciences, 55(1), 119-139.

  2. Zhu, J., Zou, H., Rosset, S., and Hastie, T. (2009).  “Multi-class
     AdaBoost”.  Statistics and Its Interface, 2(3), 349-360.

  3. Quinlan, J.R. (1993).  “C4.5: Programs for Machine Learning”.
     Morgan Kaufmann.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<14>,  Prev: References,  Up: adaptive_boosting_classifier

6.2.8 Usage
-----------

* Menu:

* Learning a Classifier::
* Making Predictions::
* Exporting the Classifier::
* Using a Saved Classifier::
* Printing the Classifier::


File: TheLogtalkHandbook-3.101.0.info,  Node: Learning a Classifier,  Next: Making Predictions,  Up: Usage<14>

6.2.8.1 Learning a Classifier
.............................

     % Learn an AdaBoost classifier with default options (10 estimators)
     | ?- adaptive_boosting_classifier::learn(play_tennis, Classifier).
     ...

     % Learn with custom options
     | ?- adaptive_boosting_classifier::learn(play_tennis, Classifier, [number_of_estimators(20)]).
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Making Predictions,  Next: Exporting the Classifier,  Prev: Learning a Classifier,  Up: Usage<14>

6.2.8.2 Making Predictions
..........................

     % Predict class for a new instance
     | ?- adaptive_boosting_classifier::learn(play_tennis, Classifier),
          adaptive_boosting_classifier::predict(Classifier, [outlook-sunny, temperature-hot, humidity-high, wind-weak], Class).
     Class = no
     ...

     % Get probability distribution from weighted voting
     | ?- adaptive_boosting_classifier::learn(play_tennis, Classifier),
          adaptive_boosting_classifier::predict_probabilities(Classifier, [outlook-overcast, temperature-mild, humidity-normal, wind-weak], Probabilities).
     Probabilities = [yes-0.9, no-0.1]
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Exporting the Classifier,  Next: Using a Saved Classifier,  Prev: Making Predictions,  Up: Usage<14>

6.2.8.3 Exporting the Classifier
................................

     % Export as predicate clauses
     | ?- adaptive_boosting_classifier::learn(play_tennis, Classifier),
          adaptive_boosting_classifier::export_to_clauses(play_tennis, Classifier, my_boost, Clauses).
     ...

     % Export to a file
     | ?- adaptive_boosting_classifier::learn(play_tennis, Classifier),
          adaptive_boosting_classifier::export_to_file(play_tennis, Classifier, my_boost, 'boost.pl').
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Using a Saved Classifier,  Next: Printing the Classifier,  Prev: Exporting the Classifier,  Up: Usage<14>

6.2.8.4 Using a Saved Classifier
................................

     % Load and use a previously saved classifier
     | ?- logtalk_load('boost.pl'),
          my_boost(Classifier),
          adaptive_boosting_classifier::predict(Classifier, [outlook-sunny, temperature-cool, humidity-normal, wind-weak], Class).
     Class = yes
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Printing the Classifier,  Prev: Using a Saved Classifier,  Up: Usage<14>

6.2.8.5 Printing the Classifier
...............................

     % Print a summary of the AdaBoost classifier
     | ?- adaptive_boosting_classifier::learn(play_tennis, Classifier),
          adaptive_boosting_classifier::print_classifier(Classifier).

     AdaBoost Classifier
     ===================

     Learning options: [number_of_estimators(10)]

     Class values: [yes,no]
     Number of estimators: 10

     Weighted trees:
       Estimator 1 (alpha=1.2345, features: [outlook,temperature,humidity,wind]):
         -> tree rooted at outlook
       ...
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: agglomerative_clusterer,  Next: amqp,  Prev: adaptive_boosting_classifier,  Up: Libraries

6.3 ‘agglomerative_clusterer’
=============================

Agglomerative clusterer.

The library implements the ‘clusterer_protocol’ defined in the
‘clustering_protocols’ library.  It provides predicates for learning a
clusterer from a dataset, assigning new instances to clusters, and
exporting the learned clusterer as a list of predicate clauses or to a
file.

Datasets are represented as objects implementing the
‘clustering_dataset_protocol’ protocol from the ‘clustering_protocols’
library.

* Menu:

* API documentation: API documentation<22>.
* Loading: Loading<23>.
* Testing: Testing<18>.
* Features: Features<3>.
* Options: Options<4>.
* Clusterer representation::
* Diagnostics::


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<22>,  Next: Loading<23>,  Up: agglomerative_clusterer

6.3.1 API documentation
-----------------------

Open the ‘../../apis/library_index.html#agglomerative_clusterer’ link in
a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<23>,  Next: Testing<18>,  Prev: API documentation<22>,  Up: agglomerative_clusterer

6.3.2 Loading
-------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(agglomerative_clusterer(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<18>,  Next: Features<3>,  Prev: Loading<23>,  Up: agglomerative_clusterer

6.3.3 Testing
-------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(agglomerative_clusterer(tester)).

To run the performance benchmark suite, load the
‘tester_performance.lgt’ file:

     | ?- logtalk_load(agglomerative_clusterer(tester_performance)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<3>,  Next: Options<4>,  Prev: Testing<18>,  Up: agglomerative_clusterer

6.3.4 Features
--------------

   - 'Bottom-Up Clustering': Uses deterministic bottom-up
     agglomerative_clusterer clustering and stops when the requested
     number of clusters is reached.

   - 'Continuous Datasets': Accepts datasets containing only continuous
     attributes.

   - 'Linkage Strategies': Supports ‘single’, ‘complete’, and ‘average’
     linkage.

   - 'Distance Metrics': Supports ‘euclidean’ and ‘manhattan’ distances.

   - 'Optional Feature Scaling': Continuous attributes can be
     standardized using z-score scaling.

   - 'Linkage-Aware Prediction': New instances are assigned to the
     nearest learned cluster using the selected linkage strategy and
     distance metric applied to the learned cluster members.

   - 'Deterministic Ordering': Equal-distance merges are broken using
     node-id order and final clusters are ordered by minimum training
     example id so equivalent dataset permutations keep the same cluster
     ids.

   - 'Cached Distances': Inter-cluster distances are cached and
     incrementally updated after each merge instead of being fully
     recomputed from cluster members at every iteration.

   - 'Priority-Queue Merge Selection': Candidate merges are tracked in a
     min-heap keyed by distance and node-id order, allowing stale
     entries to be discarded lazily while keeping merge selection
     deterministic.

   - 'Rich Diagnostics': Diagnostics report the training example count,
     performed merge count, initial pair count, maximum heap size,
     stale-pair discard count, deterministic pair-selection strategy,
     and linkage-aware prediction strategy.

   - 'Fail-Fast Consistency Checks': Internal heap, active-node, and
     cached-distance inconsistencies raise explicit
     ‘agglomerative_error/2’ exceptions instead of failing silently.

   - 'Portable Export': Learned clusterers can be exported as clauses or
     files and reused later.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<4>,  Next: Clusterer representation,  Prev: Features<3>,  Up: agglomerative_clusterer

6.3.5 Options
-------------

The following options can be passed to the ‘learn/3’ predicate:

   - ‘k(K)’: Number of clusters to retain after merging.  Default is
     ‘2’.

   - ‘linkage(Linkage)’: Linkage strategy to use.  Options: ‘single’,
     ‘complete’, or ‘average’ (default).

   - ‘distance_metric(Metric)’: Distance metric to use.  Options:
     ‘euclidean’ (default) or ‘manhattan’.

   - ‘feature_scaling(FeatureScaling)’: Whether to standardize
     continuous attributes before clustering.  Options: ‘on’ (default)
     or ‘off’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Clusterer representation,  Next: Diagnostics,  Prev: Options<4>,  Up: agglomerative_clusterer

6.3.6 Clusterer representation
------------------------------

The learned clusterer is represented as a compound term with the functor
chosen by the user when exporting the clusterer and arity 4.  For
example:

     agglomerative_clusterer(Encoders, Clusters, Prototypes, Options, Diagnostics)

Where:

   - ‘Encoders’: List of continuous attribute encoders storing attribute
     name, mean, and scale.

   - ‘Clusters’: List of ‘cluster(Id, Points)’ terms in cluster-id
     order.

   - ‘Prototypes’: List of average vectors used for display,
     diagnostics, and export metadata.

   - ‘Options’: Effective training options used to learn the clusterer.

   - ‘Diagnostics’: Training metadata including heap and prediction
     details.


File: TheLogtalkHandbook-3.101.0.info,  Node: Diagnostics,  Prev: Clusterer representation,  Up: agglomerative_clusterer

6.3.7 Diagnostics
-----------------

The ‘diagnostics/2’ predicate returns metadata including:

   - ‘training_example_count/1’

   - ‘merge_count/1’

   - ‘initial_pair_count/1’

   - ‘maximum_heap_size/1’

   - ‘stale_pair_discard_count/1’

   - ‘pair_selection(priority_queue)’

   - ‘prediction_strategy(cluster_member_linkage_distance)’

   - ‘tie_breaking(node_id_order)’

   - ‘options/1’


File: TheLogtalkHandbook-3.101.0.info,  Node: amqp,  Next: anomaly_detection_protocols,  Prev: agglomerative_clusterer,  Up: Libraries

6.4 ‘amqp’
==========

Portable AMQP 0-9-1 (Advanced Message Queuing Protocol) client
implementation.  This library uses the ‘sockets’ library and supports
all backend Prolog systems supported by that library: ECLiPSe, GNU
Prolog, SICStus Prolog, SWI-Prolog, Trealla Prolog, and XVM.

‘https://www.rabbitmq.com/amqp-0-9-1-reference.html’

AMQP 0-9-1 is a binary wire-level protocol for message-oriented
middleware.  It is the de facto standard for message broker
interoperability and is supported by RabbitMQ, Apache Qpid, Apache
ActiveMQ, and other brokers.

* Menu:

* API documentation: API documentation<23>.
* Loading: Loading<24>.
* Testing: Testing<19>.
* Features: Features<4>.
* Usage: Usage<15>.
* Connection Pooling::
* Binary Frame Encoding::
* Data Types::
* Float/Double Encoding/Decoding::
* Error Handling::
* Comparison with STOMP::
* Future Work::
* Known Limitations and Issues::
* AMQP 1.0 vs AMQP 0-9-1: AMQP 1 0 vs AMQP 0-9-1.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<23>,  Next: Loading<24>,  Up: amqp

6.4.1 API documentation
-----------------------

Open the ‘../../apis/library_index.html#amqp’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<24>,  Next: Testing<19>,  Prev: API documentation<23>,  Up: amqp

6.4.2 Loading
-------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(amqp(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<19>,  Next: Features<4>,  Prev: Loading<24>,  Up: amqp

6.4.3 Testing
-------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(amqp(tester)).

Note: Integration tests require a running AMQP 0-9-1 server (e.g.,
RabbitMQ). RabbitMQ AMQP listens on port 5672 by default with
guest/guest credentials.

For example, on macOS using Homebrew, uou can setup a server using the
commands:

     $ brew install rabbitmq
     $ rabbitmq-plugins enable rabbitmq_amqp1_0
     $ brew services restart rabbitmq


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<4>,  Next: Usage<15>,  Prev: Testing<19>,  Up: amqp

6.4.4 Features
--------------

   - Full AMQP 0-9-1 protocol support with binary frame
     encoding/decoding

   - Connection management with heartbeat negotiation

   - Automatic reconnection with configurable retry attempts and delays

   - Connection pooling with automatic connection management

   - Multiple concurrent channels over a single connection

   - Exchange operations: declare, delete, bind, unbind

   - Queue operations: declare, delete, bind, unbind, purge

   - Basic messaging: publish, consume, get, ack, nack, reject

   - Quality of service (QoS) with prefetch settings

   - Transaction support: tx.select, tx.commit, tx.rollback

   - Publisher confirms (RabbitMQ extension)

   - SASL PLAIN authentication

   - Custom message properties and headers

   - Content properties: content-type, delivery-mode, priority, etc.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<15>,  Next: Connection Pooling,  Prev: Features<4>,  Up: amqp

6.4.5 Usage
-----------

* Menu:

* Connecting to an AMQP server::
* Opening a channel::
* Declaring exchanges and queues::
* Publishing messages::
* Consuming messages::
* Synchronous get::
* Quality of Service::
* Transactions::
* Publisher Confirms (RabbitMQ extension): Publisher Confirms RabbitMQ extension.
* Closing connections::


File: TheLogtalkHandbook-3.101.0.info,  Node: Connecting to an AMQP server,  Next: Opening a channel,  Up: Usage<15>

6.4.5.1 Connecting to an AMQP server
....................................

Basic connection to RabbitMQ with default settings:

     ?- amqp::connect(localhost, 5672, Connection, []).

Connection with custom credentials and virtual host:

     ?- amqp::connect(localhost, 5672, Connection, [
         username('myuser'),
         password('mypassword'),
         virtual_host('/myvhost'),
         heartbeat(30)
     ]).

Connection with automatic reconnection enabled:

     ?- amqp::connect(localhost, 5672, Connection, [
         reconnect(true),
         reconnect_attempts(5),
         reconnect_delay(2)
     ]).

This will attempt to connect up to 5 times with a 2 second delay between
attempts.  If all attempts fail, an ‘amqp_error(reconnect_failed)’ error
is thrown.  The reconnection options are:

   - ‘reconnect(Boolean)’ - Enable automatic reconnection (default:
     ‘false’)

   - ‘reconnect_attempts(N)’ - Maximum number of connection attempts
     (default: ‘3’)

   - ‘reconnect_delay(Seconds)’ - Delay between attempts in seconds
     (default: ‘1’)


File: TheLogtalkHandbook-3.101.0.info,  Node: Opening a channel,  Next: Declaring exchanges and queues,  Prev: Connecting to an AMQP server,  Up: Usage<15>

6.4.5.2 Opening a channel
.........................

AMQP operations require a channel.  Open one on the connection:

     ?- amqp::channel_open(Connection, 1, Channel).

You can open multiple channels (with different numbers) on a single
connection.


File: TheLogtalkHandbook-3.101.0.info,  Node: Declaring exchanges and queues,  Next: Publishing messages,  Prev: Opening a channel,  Up: Usage<15>

6.4.5.3 Declaring exchanges and queues
......................................

Declare a direct exchange:

     ?- amqp::exchange_declare(Channel, 'my.exchange', [
         type(direct),
         durable(true)
     ]).

Declare a queue:

     ?- amqp::queue_declare(Channel, 'my.queue', [
         durable(true),
         auto_delete(false)
     ]).

Declare a queue with server-generated name:

     ?- amqp::queue_declare(Channel, Queue, [exclusive(true)]).
     % Queue will be unified with the generated name

Bind a queue to an exchange:

     ?- amqp::queue_bind(Channel, 'my.queue', 'my.exchange', [
         routing_key('my.routing.key')
     ]).


File: TheLogtalkHandbook-3.101.0.info,  Node: Publishing messages,  Next: Consuming messages,  Prev: Declaring exchanges and queues,  Up: Usage<15>

6.4.5.4 Publishing messages
...........................

Publish a simple message:

     ?- amqp::basic_publish(Channel, 'my.exchange', 'Hello, World!', [
         routing_key('my.routing.key')
     ]).

Publish with properties:

     ?- amqp::basic_publish(Channel, 'my.exchange', '{"data": "json"}', [
         routing_key('my.routing.key'),
         content_type('application/json'),
         delivery_mode(2),  % persistent
         correlation_id('abc123'),
         reply_to('reply.queue')
     ]).

Publish with custom headers:

     ?- amqp::basic_publish(Channel, 'my.exchange', 'Message', [
         routing_key('my.key'),
         headers([
             'x-custom-header'-longstr('value'),
             'x-priority'-int(5)
         ])
     ]).


File: TheLogtalkHandbook-3.101.0.info,  Node: Consuming messages,  Next: Synchronous get,  Prev: Publishing messages,  Up: Usage<15>

6.4.5.5 Consuming messages
..........................

Start a consumer:

     ?- amqp::basic_consume(Channel, 'my.queue', [
         consumer_tag('my-consumer'),
         no_ack(false)
     ]).

Receive messages:

     ?- amqp::receive(Channel, Message, [timeout(5000)]).

Extract message data:

     ?- amqp::message_body(Message, Body),
        amqp::message_delivery_tag(Message, DeliveryTag),
        amqp::message_property(Message, content_type, ContentType).

Acknowledge a message:

     ?- amqp::basic_ack(Channel, DeliveryTag, []).

Reject a message:

     ?- amqp::basic_reject(Channel, DeliveryTag, [requeue(true)]).


File: TheLogtalkHandbook-3.101.0.info,  Node: Synchronous get,  Next: Quality of Service,  Prev: Consuming messages,  Up: Usage<15>

6.4.5.6 Synchronous get
.......................

Get a single message synchronously:

     ?- amqp::basic_get(Channel, 'my.queue', [no_ack(false)]).


File: TheLogtalkHandbook-3.101.0.info,  Node: Quality of Service,  Next: Transactions,  Prev: Synchronous get,  Up: Usage<15>

6.4.5.7 Quality of Service
..........................

Set prefetch count to limit unacknowledged messages:

     ?- amqp::basic_qos(Channel, [prefetch_count(10)]).


File: TheLogtalkHandbook-3.101.0.info,  Node: Transactions,  Next: Publisher Confirms RabbitMQ extension,  Prev: Quality of Service,  Up: Usage<15>

6.4.5.8 Transactions
....................

Enable transactions on a channel:

     ?- amqp::tx_select(Channel).

Publish messages within a transaction:

     ?- amqp::basic_publish(Channel, 'exchange', 'Msg1', [routing_key('key')]),
        amqp::basic_publish(Channel, 'exchange', 'Msg2', [routing_key('key')]),
        amqp::tx_commit(Channel).

Rollback a transaction:

     ?- amqp::tx_rollback(Channel).


File: TheLogtalkHandbook-3.101.0.info,  Node: Publisher Confirms RabbitMQ extension,  Next: Closing connections,  Prev: Transactions,  Up: Usage<15>

6.4.5.9 Publisher Confirms (RabbitMQ extension)
...............................................

Enable publisher confirms:

     ?- amqp::confirm_select(Channel).


File: TheLogtalkHandbook-3.101.0.info,  Node: Closing connections,  Prev: Publisher Confirms RabbitMQ extension,  Up: Usage<15>

6.4.5.10 Closing connections
............................

Close a channel:

     ?- amqp::channel_close(Channel).

Close the connection:

     ?- amqp::close(Connection).


File: TheLogtalkHandbook-3.101.0.info,  Node: Connection Pooling,  Next: Binary Frame Encoding,  Prev: Usage<15>,  Up: amqp

6.4.6 Connection Pooling
------------------------

The library provides connection pooling through the ‘amqp_pool’
category.  To create a connection pool, define an object that imports
this category:

* Menu:

* Defining a pool::
* Initializing the pool::
* Acquiring and releasing connections::
* Using with_connection/1::
* Pool statistics::
* Resizing the pool::
* Destroying the pool::
* Creating pools dynamically::


File: TheLogtalkHandbook-3.101.0.info,  Node: Defining a pool,  Next: Initializing the pool,  Up: Connection Pooling

6.4.6.1 Defining a pool
.......................

     :- object(my_pool,
         imports(amqp_pool)).
     :- end_object.


File: TheLogtalkHandbook-3.101.0.info,  Node: Initializing the pool,  Next: Acquiring and releasing connections,  Prev: Defining a pool,  Up: Connection Pooling

6.4.6.2 Initializing the pool
.............................

Initialize the pool with configuration options:

     ?- my_pool::initialize([
         host(localhost),
         port(5672),
         min_size(2),
         max_size(10),
         connection_options([
             username('guest'),
             password('guest'),
             virtual_host('/')
         ])
     ]).

Pool configuration options:

   - ‘host(Host)’ - AMQP server hostname (default: ‘localhost’)

   - ‘port(Port)’ - AMQP server port (default: ‘5672’)

   - ‘min_size(N)’ - Minimum connections to maintain (default: ‘1’)

   - ‘max_size(N)’ - Maximum connections allowed (default: ‘10’)

   - ‘connection_options(Options)’ - Options passed to ‘amqp::connect/4’
     (default: ‘[]’)


File: TheLogtalkHandbook-3.101.0.info,  Node: Acquiring and releasing connections,  Next: Using with_connection/1,  Prev: Initializing the pool,  Up: Connection Pooling

6.4.6.3 Acquiring and releasing connections
...........................................

Manually acquire and release connections:

     ?- my_pool::acquire(Connection),
        amqp::channel_open(Connection, 1, Channel),
        % ... use the channel ...
        amqp::channel_close(Channel),
        my_pool::release(Connection).


File: TheLogtalkHandbook-3.101.0.info,  Node: Using with_connection/1,  Next: Pool statistics,  Prev: Acquiring and releasing connections,  Up: Connection Pooling

6.4.6.4 Using with_connection/1
...............................

Use ‘with_connection/1’ for automatic connection management:

     ?- my_pool::with_connection(do_work).

     do_work(Connection) :-
         amqp::channel_open(Connection, 1, Channel),
         amqp::basic_publish(Channel, '', 'Hello!', [routing_key('my.queue')]),
         amqp::channel_close(Channel).

The connection is automatically released even if the goal fails or
throws an exception.


File: TheLogtalkHandbook-3.101.0.info,  Node: Pool statistics,  Next: Resizing the pool,  Prev: Using with_connection/1,  Up: Connection Pooling

6.4.6.5 Pool statistics
.......................

Get pool statistics:

     ?- my_pool::stats(stats(Available, InUse, Total, MinSize, MaxSize)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Resizing the pool,  Next: Destroying the pool,  Prev: Pool statistics,  Up: Connection Pooling

6.4.6.6 Resizing the pool
.........................

Resize the pool at runtime:

     ?- my_pool::resize(5, 20).


File: TheLogtalkHandbook-3.101.0.info,  Node: Destroying the pool,  Next: Creating pools dynamically,  Prev: Resizing the pool,  Up: Connection Pooling

6.4.6.7 Destroying the pool
...........................

Close all connections and clear pool state:

     ?- my_pool::destroy.


File: TheLogtalkHandbook-3.101.0.info,  Node: Creating pools dynamically,  Prev: Destroying the pool,  Up: Connection Pooling

6.4.6.8 Creating pools dynamically
..................................

Pools can also be created at runtime using ‘create_object/4’:

     ?- create_object(dynamic_pool, [imports(amqp_pool)], [], []),
        dynamic_pool::initialize([host(localhost), port(5672)]).


File: TheLogtalkHandbook-3.101.0.info,  Node: Binary Frame Encoding,  Next: Data Types,  Prev: Connection Pooling,  Up: amqp

6.4.7 Binary Frame Encoding
---------------------------

AMQP 0-9-1 is a binary protocol.  The library provides low-level
encoding and decoding predicates for working with raw frames:

* Menu:

* Frame structure::
* Encoding/decoding frames::


File: TheLogtalkHandbook-3.101.0.info,  Node: Frame structure,  Next: Encoding/decoding frames,  Up: Binary Frame Encoding

6.4.7.1 Frame structure
.......................

An AMQP frame consists of:

   - Type (1 byte): 1=method, 2=header, 3=body, 8=heartbeat

   - Channel (2 bytes): Channel number (0 for connection frames)

   - Size (4 bytes): Payload size

   - Payload (Size bytes): Frame-specific data

   - Frame end (1 byte): 0xCE marker


File: TheLogtalkHandbook-3.101.0.info,  Node: Encoding/decoding frames,  Prev: Frame structure,  Up: Binary Frame Encoding

6.4.7.2 Encoding/decoding frames
................................

Encode a frame to bytes:

     ?- amqp::encode_frame(Frame, Bytes).

Decode bytes to a frame:

     ?- amqp::decode_frame(Bytes, Frame).


File: TheLogtalkHandbook-3.101.0.info,  Node: Data Types,  Next: Float/Double Encoding/Decoding,  Prev: Binary Frame Encoding,  Up: amqp

6.4.8 Data Types
----------------

The library handles AMQP data types automatically:

   - 'octet': 8-bit unsigned integer

   - 'short': 16-bit unsigned integer (big-endian)

   - 'long': 32-bit unsigned integer (big-endian)

   - 'longlong': 64-bit unsigned integer (big-endian)

   - 'shortstr': Short string (length <= 255)

   - 'longstr': Long string

   - 'table': Field table (key-value pairs)

   - 'array': Field array

Field values in tables use type tags:

   - ‘bool(true/false)’ - Boolean

   - ‘byte(V)’ - Signed 8-bit

   - ‘short(V)’ - Signed 16-bit

   - ‘int(V)’ - Signed 32-bit

   - ‘long(V)’ - Signed 64-bit

   - ‘float(V)’ - 32-bit float

   - ‘double(V)’ - 64-bit float

   - ‘longstr(V)’ - Long string

   - ‘table(Pairs)’ - Nested table

   - ‘array(Values)’ - Array

   - ‘timestamp(V)’ - Timestamp

   - ‘void’ - No value


File: TheLogtalkHandbook-3.101.0.info,  Node: Float/Double Encoding/Decoding,  Next: Error Handling,  Prev: Data Types,  Up: amqp

6.4.9 Float/Double Encoding/Decoding
------------------------------------

The library implements proper IEEE 754 encoding and decoding for
floating-point values:

'Float (32-bit IEEE 754 single precision):'

   - Format: 1 sign bit + 8 exponent bits (bias 127) + 23 mantissa bits

   - Encoded as 4 bytes in big-endian order

   - Used for ‘float(Value)’ field values

'Double (64-bit IEEE 754 double precision):'

   - Format: 1 sign bit + 11 exponent bits (bias 1023) + 52 mantissa
     bits

   - Encoded as 8 bytes in big-endian order

   - Used for ‘double(Value)’ field values

'Special values representation:'

The library represents IEEE 754 special values using Prolog compound
terms:

   - ‘@infinity’ - Positive infinity

   - ‘@negative_infinity’ - Negative infinity

   - ‘@not_a_number’ - NaN (Not a Number)

These special values are automatically encoded to and decoded from their
standard IEEE 754 binary representations.

'Known limitation:'

Most Prolog backends cannot distinguish between ‘-0.0’ and ‘0.0’ when
comparing floating-point values.  While the library correctly encodes
and decodes both positive and negative zero according to IEEE 754, these
values will typically compare as equal in Prolog arithmetic operations.
This limitation is unlikely to affect typical AMQP messaging
applications.


File: TheLogtalkHandbook-3.101.0.info,  Node: Error Handling,  Next: Comparison with STOMP,  Prev: Float/Double Encoding/Decoding,  Up: amqp

6.4.10 Error Handling
---------------------

The library throws structured errors:

   - ‘amqp_error(connection_failed)’ - TCP connection failed

   - ‘amqp_error(auth_failed)’ - Authentication failed

   - ‘amqp_error(protocol_error(Msg))’ - Protocol violation

   - ‘amqp_error(channel_error(Msg))’ - Channel-level error

   - ‘amqp_error(exchange_error(Msg))’ - Exchange operation failed

   - ‘amqp_error(queue_error(Msg))’ - Queue operation failed

   - ‘amqp_error(basic_error(Msg))’ - Basic operation failed

   - ‘amqp_error(tx_error(Msg))’ - Transaction error


File: TheLogtalkHandbook-3.101.0.info,  Node: Comparison with STOMP,  Next: Future Work,  Prev: Error Handling,  Up: amqp

6.4.11 Comparison with STOMP
----------------------------

AMQP 0-9-1 and STOMP are both messaging protocols, but differ
significantly:

Feature            AMQP 0-9-1          STOMP
                                       
------------------------------------------------------------
Protocol type      Binary              Text
                                       
Complexity         High                Low
                                       
Exchange types     Multiple            Broker-dependent
                                       
Routing            Flexible            Simple
                                       
Transactions       Native              Native
                                       
QoS                Native prefetch     Limited
                                       
Performance        Higher              Lower
                                       

Use AMQP when you need:

   - Fine-grained routing control

   - High performance

   - Advanced message patterns

   - Exchange-based routing

Use STOMP when you need:

   - Simple text-based protocol

   - Easy debugging

   - Protocol simplicity


File: TheLogtalkHandbook-3.101.0.info,  Node: Future Work,  Next: Known Limitations and Issues,  Prev: Comparison with STOMP,  Up: amqp

6.4.12 Future Work
------------------

   - Logtalk protocols for messaging patterns (request/reply, pub/sub,
     etc.)

   - Categories for common message transformations

   - Async message handlers


File: TheLogtalkHandbook-3.101.0.info,  Node: Known Limitations and Issues,  Next: AMQP 1 0 vs AMQP 0-9-1,  Prev: Future Work,  Up: amqp

6.4.13 Known Limitations and Issues
-----------------------------------

   - SSL/TLS connections not yet supported (use stunnel or similar)

   - Heartbeat sending must be done manually via ‘send_heartbeat/1’

   - Most Prolog backends cannot distinguish between ‘-0.0’ and ‘0.0’
     (see the “Float/Double Encoding/Decoding” section above for
     details)

   - GNU Prolog support is partial as it doesn’t currently support null
     characters in atoms


File: TheLogtalkHandbook-3.101.0.info,  Node: AMQP 1 0 vs AMQP 0-9-1,  Prev: Known Limitations and Issues,  Up: amqp

6.4.14 AMQP 1.0 vs AMQP 0-9-1
-----------------------------

This library implements AMQP 0-9-1 only.  Despite the similar name,
'AMQP 1.0 is a fundamentally different protocol' and is not supported by
this library.  The two versions are not wire-compatible and have
different conceptual models:

Aspect              AMQP 0-9-1                AMQP 1.0
                                              
------------------------------------------------------------------------
Design              Broker-centric            Peer-to-peer
                                              
Routing             Exchanges + queues        Link-based addressing
                                              
Frame structure     Custom binary framing     Layered performatives
                                              
Data encoding       Custom type system        CBOR-like encoding
                                              

'Key differences:'

   - AMQP 0-9-1 uses exchanges, bindings, and queues as core protocol
     concepts

   - AMQP 1.0 abstracts these as broker-specific “nodes” and uses links

   - Frame encoding, handshake, and message format are completely
     different

   - Minimal code could be shared between the two implementations

AMQP 1.0 support would require a separate library with its own distinct
API reflecting the link-based model, rather than the exchange/queue
model of AMQP 0-9-1.

'Practical note:' RabbitMQ and most message brokers continue to
primarily use AMQP 0-9-1, making this library suitable for the vast
majority of use cases.


File: TheLogtalkHandbook-3.101.0.info,  Node: anomaly_detection_protocols,  Next: application,  Prev: amqp,  Up: Libraries

6.5 ‘anomaly_detection_protocols’
=================================

This library provides protocols used in the implementation of machine
learning anomaly-detection algorithms.  Datasets are represented as
objects implementing the ‘anomaly_dataset_protocol’ protocol.  Anomaly
detectors are represented as objects importing the
‘anomaly_detector_common’ category which imports the
‘anomaly_detector_protocol’ protocol.  The category provides shared
‘learn/2’, ‘predict/3-4’, ‘diagnostics/2’, ‘diagnostic/2’,
‘anomaly_detector_options/2’, file export, baseline training-selection
helpers, and dataset helper predicates.  It keeps threshold-based
prediction and export behavior separate from the algorithm-specific
learning, scoring, clause export, pretty-printing, and diagnostics
metadata code.

The shared category also provides reusable protected predicates for
baseline-only training workflows.  Libraries can use the
‘baseline_class_values/1’ and ‘baseline_selection_policy/1’ options via
a single helper instead of reimplementing class-label validation and
baseline-example filtering or rejection logic locally.

Learned detector terms can be validated explicitly using the shared
‘check_anomaly_detector/1’ and ‘valid_anomaly_detector/1’ predicates.
This validation API is never called implicitly by scoring, prediction,
printing, or export predicates.

This library also provides a reusable shared category, anomaly benchmark
datasets, and a small family smoke-test suite.

* Menu:

* Export header format::
* API documentation: API documentation<24>.
* Loading: Loading<25>.
* Testing: Testing<20>.
* Test datasets::


File: TheLogtalkHandbook-3.101.0.info,  Node: Export header format,  Next: API documentation<24>,  Up: anomaly_detection_protocols

6.5.1 Export header format
--------------------------

The shared exporter in the ‘anomaly_detector_common’ category writes a
header before the exported clauses in the following format:

     % exported anomaly detector predicate: Functor/Arity
     % training dataset: Dataset
     % options: Options
     % Functor(Detector)
     Functor(Detector)

The exported clauses serialize the learned detector term as a single
predicate argument so that loading the file gives a detector term that
can be passed directly to the ‘predict/3-4’ and ‘score_all/3’
predicates.

When exporting a serialized detector term, using a noun such as
‘detector/1’ or ‘model/1’ is recommended.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<24>,  Next: Loading<25>,  Prev: Export header format,  Up: anomaly_detection_protocols

6.5.2 API documentation
-----------------------

Open the ‘../../apis/library_index.html#anomaly-detection-protocols’
link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<25>,  Next: Testing<20>,  Prev: API documentation<24>,  Up: anomaly_detection_protocols

6.5.3 Loading
-------------

To load all entities in this library, load the ‘loader.lgt’ file:

| ?- logtalk_load(anomaly_detection_protocols(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<20>,  Next: Test datasets,  Prev: Loading<25>,  Up: anomaly_detection_protocols

6.5.4 Testing
-------------

To run the library smoke tests, shared category tests, and dataset
checks, load the ‘tester.lgt’ file:

| ?- logtalk_load(anomaly_detection_protocols(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Test datasets,  Prev: Testing<20>,  Up: anomaly_detection_protocols

6.5.5 Test datasets
-------------------

Several sample datasets are included in the ‘test_datasets’ directory:

   - ‘gaussian_anomalies.lgt’ — A synthetic 2D anomaly detection dataset
     with 48 examples and 2 continuous attributes (x, y).  Normal points
     are sampled from a standard normal distribution centered at the
     origin.  Anomalous points are placed far from the cluster center.
     Inspired by the canonical test case used in the Extended Isolation
     Forest paper by Hariri et al.  (2019).

   - ‘malformed_anomalies.lgt’ — A negative fixture with invalid class
     labels for testing family-level dataset validation.

   - ‘mixed_anomalies.lgt’ — A small mixed-feature anomaly dataset with
     16 examples, 2 continuous attributes (age, income), and 2
     categorical attributes (student, credit_rating).  Includes missing
     values and uncommon feature combinations to exercise
     anomaly-detection code on heterogeneous data.

   - ‘mixed_distance_behaviors.lgt’ — A compact mixed-feature anomaly
     fixture with 8 examples, 2 continuous attributes (size, weight),
     and 2 categorical attributes (color, shape).  Intended for
     smoke-testing continuous plus categorical distance behavior and
     basic mixed-data handling.

   - ‘sensor_anomalies.lgt’ — A synthetic industrial sensor anomaly
     dataset with 40 examples and 3 continuous attributes (temperature,
     pressure, vibration).  Contains missing values (14 examples with
     missing values, represented using anonymous variables).  Normal
     readings cluster around typical operating ranges.  Anomalous
     readings show extreme values indicating equipment malfunction.

   - ‘shuttle_anomalies.lgt’ — A subset of the Statlog Shuttle dataset
     with 50 examples and 9 continuous attributes representing sensor
     readings from the NASA Space Shuttle.  Class 1 (Rad Flow) is the
     majority class (normal), while all other classes are treated as
     anomalies.  Originally from Catlett, J. (1991).  Available from the
     UCI Machine Learning Repository:
     ‘https://archive.ics.uci.edu/dataset/148/statlog+shuttle’

   - ‘water_potability.lgt’ — A water potability dataset with 48
     examples and 9 continuous attributes (pH, hardness, solids,
     chloramines, sulfate, conductivity, organic carbon,
     trihalomethanes, turbidity).  Normal instances represent potable
     water samples within acceptable ranges.  Anomalous instances
     represent water samples with hazardous contamination levels.  Based
     on the publicly available Water Quality dataset (Kadiwal, A., 2020,
     Kaggle).


File: TheLogtalkHandbook-3.101.0.info,  Node: application,  Next: apriori_pattern_miner,  Prev: anomaly_detection_protocols,  Up: Libraries

6.6 ‘application’
=================

This library provides the ‘application_common’ category and the
‘application_protocol’ protocol for declaring application metadata,
including optional git-related facts such as repository URL, branch,
commit, author, and commit message, plus optional package and archive
identifiers.  Application metadata is typically consumed by tools such
as ‘sbom’.

The library distinguishes two kinds of information:

   - release metadata, such as name, version, description, license,
     distribution location, package identifier, release date, and
     validity date

   - optional source provenance metadata, such as repository URL,
     branch, commit, commit date, author, commit message, and archive
     identifiers

Source provenance predicates are explicit facts declared by the
application.  They are not a reflection of the current status of a local
git checkout and should not be assumed to identify a released artifact
unless the application author chooses to state them for that purpose.

* Menu:

* API documentation: API documentation<25>.
* Loading: Loading<26>.
* Testing: Testing<21>.
* Usage: Usage<16>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<25>,  Next: Loading<26>,  Up: application

6.6.1 API documentation
-----------------------

Open the ‘../../apis/library_index.html#application’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<26>,  Next: Testing<21>,  Prev: API documentation<25>,  Up: application

6.6.2 Loading
-------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(application(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<21>,  Next: Usage<16>,  Prev: Loading<26>,  Up: application

6.6.3 Testing
-------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(application(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<16>,  Prev: Testing<21>,  Up: application

6.6.4 Usage
-----------

Define an application metadata object importing the ‘application_common’
category and declaring the metadata that is known explicitly.  For
example:

     :- object(my_application,
         imports(application_common)).

         name(my_application).
         version('1.2.3').
         description('Example application metadata object').
         license('Apache-2.0').
         homepage('https://example.com/my_application').
         distribution('https://example.com/my_application/releases/download/v1.2.3/my_application.tgz').
         package('pkg:generic/my_application@1.2.3').
         creators(['Tool: Build pipeline', 'Person: Alice']).
         supplier('Organization: Example Application').
         originator('Organization: Upstream Project').
         repository('https://example.com/my_application.git').
         repository_branch(main).
         repository_commit('0123456789abcdef0123456789abcdef01234567').
         git_object_identifier('gitoid:commit:sha1:0123456789abcdef0123456789abcdef01234567').
         software_heritage_identifier('swh:1:rev:0123456789abcdef0123456789abcdef01234567').
         repository_commit_author('Alice').

     :- end_object.

The library distinguishes between creators and originator using two
predicates:

   - ‘creators/1’ identifies the people, organizations, or tools
     credited with creating the application or preparing its release
     metadata

   - ‘originator/1’ identifies the original source of the software when
     that is relevant and distinct from the creators

For example, an internal application might use the same party for both
‘creators/1’ and ‘originator/1’.  A packaged or redistributed
application may use ‘creators/1’ for the team or toolchain preparing the
release metadata and ‘originator/1’ for the original upstream source.

The imported category provides a default definition for the
‘loader_file/1’ predicate and derived external references that use the
same vocabulary as the corresponding first-class predicates:

   - ‘external_reference(homepage, URL)’ from ‘homepage/1’

   - ‘external_reference(distribution, URL)’ from ‘distribution/1’

   - ‘external_reference(package, Identifier)’ from ‘package/1’

   - ‘external_reference(repository, URL)’ from ‘repository/1’

   - ‘external_reference(git_object_identifier, Identifier)’ from
     ‘git_object_identifier/1’

   - ‘external_reference(software_heritage_identifier, Identifier)’ from
     ‘software_heritage_identifier/1’

The following predicates are intended to help tools such as ‘sbom’
export stronger standardized references:

   - ‘package/1’ Stores an application package identifier as a PURL.
     This is distinct from ‘distribution/1’, which stores a download
     location URL. Tools such as ‘sbom’ can use ‘package/1’ to export a
     package identity reference instead of only a release download
     location.  Example: ‘package('pkg:generic/my_application@1.2.3')’.

   - ‘git_object_identifier/1’ Stores a standardized Git object
     identifier as a gitoid.  This is distinct from
     ‘repository_commit/1’, which stores the raw commit hash as
     provenance metadata.  Tools such as ‘sbom’ can use
     ‘git_object_identifier/1’ to export a stronger provenance
     reference.  Example:
     ‘git_object_identifier('gitoid:commit:sha1:0123456789abcdef0123456789abcdef01234567')’.

   - ‘software_heritage_identifier/1’ Stores a Software Heritage
     identifier (SWHID) for an archived release or revision.  Tools such
     as ‘sbom’ can use it to export a stable archived source provenance
     reference when one is known.  Example:
     ‘software_heritage_identifier('swh:1:rev:0123456789abcdef0123456789abcdef01234567')’.

Git-related predicates are optional source provenance facts, not
reflection over the current state of a local repository checkout.

Release-oriented metadata typically includes:

   - ‘name/1’

   - ‘version/1’

   - ‘description/1’

   - ‘license/1’

   - ‘homepage/1’

   - ‘distribution/1’

   - ‘package/1’

   - ‘creators/1’

   - ‘supplier/1’

   - ‘originator/1’

   - ‘built_date/1’

   - ‘release_date/1’

   - ‘valid_until_date/1’

   - ‘external_reference/2’

Optional source provenance metadata typically includes:

   - ‘repository/1’

   - ‘repository_branch/1’

   - ‘repository_commit/1’

   - ‘repository_commit_abbreviated/1’

   - ‘repository_commit_date/1’

   - ‘repository_commit_author/1’

   - ‘repository_commit_message/1’

   - ‘git_object_identifier/1’

   - ‘software_heritage_identifier/1’


File: TheLogtalkHandbook-3.101.0.info,  Node: apriori_pattern_miner,  Next: arbitrary,  Prev: application,  Up: Libraries

6.7 ‘apriori_pattern_miner’
===========================

Apriori frequent itemset miner for transaction datasets.  The library
depends on the ‘frequent_pattern_mining_protocols’ support library,
implements the generic ‘pattern_miner_protocol’ defined in the
‘pattern_mining_protocols’ core library, and mines frequent itemsets
using deterministic level-wise candidate generation and anti-monotone
pruning with one transaction rescan per candidate level using a
candidate hash tree backed by keyed bucket dictionaries.  Requires a
dataset implementing ‘transaction_dataset_protocol’ with transactions
represented as canonical sorted lists of unique declared items.

* Menu:

* API documentation: API documentation<26>.
* Loading: Loading<27>.
* Testing: Testing<22>.
* Features: Features<5>.
* Options: Options<5>.
* Pattern miner representation::
* References: References<2>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<26>,  Next: Loading<27>,  Up: apriori_pattern_miner

6.7.1 API documentation
-----------------------

Open the ‘../../apis/library_index.html#apriori_pattern_miner’ link in a
web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<27>,  Next: Testing<22>,  Prev: API documentation<26>,  Up: apriori_pattern_miner

6.7.2 Loading
-------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(apriori_pattern_miner(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<22>,  Next: Features<5>,  Prev: Loading<27>,  Up: apriori_pattern_miner

6.7.3 Testing
-------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(apriori_pattern_miner(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<5>,  Next: Options<5>,  Prev: Testing<22>,  Up: apriori_pattern_miner

6.7.4 Features
--------------

   - 'Deterministic Level-Wise Mining': Builds frequent itemsets level
     by level by generating deterministic candidate combinations,
     pruning candidates whose subsets are infrequent, and rescanning
     transactions once per level to compute support counts for all
     candidates using a candidate hash tree.

   - 'Candidate Hash Tree Counting': Counts supports for an entire
     candidate level by traversing a hash tree with keyed bucket and
     item dictionaries instead of linearly scanning bucket lists for
     every transaction.

   - 'Library Hashing': Uses the ‘hashes’ library ‘fnv1a_32’ object to
     hash candidate items instead of relying on an ad hoc local hash
     function.

   - 'Apriori Join Step': Generates level candidates by pairwise joins
     of the previous frequent itemsets with shared prefixes.

   - 'Apriori Pruning': Rejects candidate itemsets whose immediate
     subsets are not all frequent using ordered subset checks over the
     previous level.

   - 'Canonical Transactions': Validates that transactions are sorted,
     duplicate-free, and restricted to declared items.

   - 'Flexible Support Thresholds': Supports relative minimum support
     and absolute minimum support count.

   - 'Model Export': Mined pattern collections can be exported as
     predicate clauses or written to a file.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<5>,  Next: Pattern miner representation,  Prev: Features<5>,  Up: apriori_pattern_miner

6.7.5 Options
-------------

The ‘mine/3’ predicate accepts the following options:

   - ‘minimum_support/1’: Relative minimum support threshold in the
     interval ‘]0.0, 1.0]’.  The default is ‘0.5’.

   - ‘minimum_support_count/1’: Absolute minimum support count.  When
     both support options are provided, this option takes precedence.

   - ‘maximum_pattern_length/1’: Maximum itemset length to mine.  The
     default is ‘1000’, which is effectively capped by the longest
     transaction in the dataset.

   - ‘minimum_pattern_length/1’: Minimum itemset length retained in the
     mined result.  The default is ‘1’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Pattern miner representation,  Next: References<2>,  Prev: Options<5>,  Up: apriori_pattern_miner

6.7.6 Pattern miner representation
----------------------------------

The mined pattern miner result is represented by a compound term with
the functor chosen by the implementation and arity 3.  For example:

     apriori_pattern_miner(ItemDomain, Patterns, Options)

Where:

   - ‘ItemDomain’: Canonical sorted list of declared dataset items.

   - ‘Patterns’: List of ‘itemset(Items, SupportCount)’ terms ordered
     first by pattern length and then lexicographically.

   - ‘Options’: Effective mining options used to mine the frequent
     itemsets.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<2>,  Prev: Pattern miner representation,  Up: apriori_pattern_miner

6.7.7 References
----------------

  1. Agrawal, R. and Srikant, R. (1994) - “Fast algorithms for mining
     association rules in large databases”.


File: TheLogtalkHandbook-3.101.0.info,  Node: arbitrary,  Next: arrangements,  Prev: apriori_pattern_miner,  Up: Libraries

6.8 ‘arbitrary’
===============

The ‘arbitrary’ library defines an ‘arbitrary’ category providing
predicates for generating random values for selected types to the ‘type’
object, complementing its type checking predicates.  Both the object and
the category predicates can be extended by the user with definitions for
new types by defining clauses for multifile predicates.  This library is
notably used in the QuickCheck implementation by the ‘lgtunit’ tool.
See also the documentation of the ‘mutations’ library for related
functionality.

* Menu:

* API documentation: API documentation<27>.
* Loading: Loading<28>.
* Testing: Testing<23>.
* Pre-defined types::
* Usage: Usage<17>.
* Defining new generators and shrinkers::
* Scoped generators and shrinkers::
* Reproducing sequences of arbitrary terms::
* Default size of generated terms::
* Known issues: Known issues<10>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<27>,  Next: Loading<28>,  Up: arbitrary

6.8.1 API documentation
-----------------------

Open the ‘../../apis/library_index.html#arbitrary’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<28>,  Next: Testing<23>,  Prev: API documentation<27>,  Up: arbitrary

6.8.2 Loading
-------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(arbitrary(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<23>,  Next: Pre-defined types,  Prev: Loading<28>,  Up: arbitrary

6.8.3 Testing
-------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(arbitrary(tester)).

Several of the provided tests are generic and verify the correct
behavior of all pre-defined and loaded user-defined generators and
shrinkers for all ground types.


File: TheLogtalkHandbook-3.101.0.info,  Node: Pre-defined types,  Next: Usage<17>,  Prev: Testing<23>,  Up: arbitrary

6.8.4 Pre-defined types
-----------------------

This library defines random generators for the most common Logtalk and
Prolog types.  See the API documentation(1) for a listing of all the
pre-defined types.

   ---------- Footnotes ----------

   (1) ../../apis/library_index.html#arbitrary


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<17>,  Next: Defining new generators and shrinkers,  Prev: Pre-defined types,  Up: arbitrary

6.8.5 Usage
-----------

The ‘arbitrary’ category complements the ‘type’ object and thus its
predicates are accessed via this object.  For example:

     | ?- type::arbitrary(integer, Arbitrary).
     Arbitrary = -816
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: Defining new generators and shrinkers,  Next: Scoped generators and shrinkers,  Prev: Usage<17>,  Up: arbitrary

6.8.6 Defining new generators and shrinkers
-------------------------------------------

To define a generator of arbitrary values for a type, define a clause
for the ‘arbitrary::arbitrary/1’ multifile predicate specifying the type
and a clause for the ‘arbitrary::arbitrary/2’ multifile predicate
generating an arbitrary term of the specified type.  As a simple
example, assume that we want to define an “odd integer type”.  We start
by defining both the type checker and the arbitrary generator:

     :- multifile(type::type/1).
     type::type(odd).

     :- multifile(type::check/2).
     type::check(odd, Term) :-
         (   var(Term) ->
             throw(instantiation_error)
         ;   integer(Term),
             Term mod 2 =:= 1 ->
             true
         ;   throw(type_error(odd, Term))
         ).

     :- multifile(arbitrary::arbitrary/1).
     arbitrary::arbitrary(odd).

     :- multifile(arbitrary::arbitrary/2).
     arbitrary::arbitrary(odd, Arbitrary) :-
         type::arbitrary(integer, Arbitrary0),
         (   Arbitrary0 mod 2 =:= 1 ->
             Arbitrary = Arbitrary0
         ;   Arbitrary is Arbitrary0 + 1
         ).

The ‘arbitrary’ library also provides 'meta-types' that can simplify the
definition of new generators.  For example, the ‘odd’ type above can
also be defined using the ‘constrain/2’ meta-type to only generate
values that satisfy a closure:

     arbitrary::arbitrary(odd, Arbitrary) :-
         arbitrary(constrain(integer, [Arbitrary]>>(Arbitrary mod 2 =:= 1)), Arbitrary).

Another example is using the ‘transform/2’ meta-type to transform
generated values for a base type using a closure.  Assuming that we want
to generate a sorted list of random integers, we can write:

     arbitrary::arbitrary(sorted_integer_list, Arbitrary) :-
         arbitrary(transform(list(integer), sort), Arbitrary).

We can also define a clause for the ‘arbitrary::shrinker/1’ multifile
predicate to declare a new shrinker and a ‘arbitrary::shrink/3’
multifile predicate for shrinking arbitrary values for QuickCheck usage:

     :- multifile(arbitrary::shrinker/1).
     arbitrary::shrinker(odd).

     :- multifile(arbitrary::shrink/3).
     arbitrary::shrink(odd, Large, Small) :-
         integer(Large),
         (   Large < -1 ->
             Small is Large + 2
         ;   Large > 1,
             Small is Large - 2
         ).

Definitions for the ‘shrink/3’ predicate should either succeed or fail
but never throw an exception.  The ‘shrink_sequence/3’ predicate can be
used to help test that shrinking a value results in a finite sequence of
values.

It is also possible to define edge cases for a given type for use with
QuickCheck implementations.  For example:

     :- multifile(arbitrary::edge_case/2).
     arbitrary::edge_case(odd,  1).
     arbitrary::edge_case(odd, -1).

Edge cases are tried before resorting to generating arbitrary values for
a type.

A more complex example is generating arbitrary values for a recursive
type.  A simple example of a recursive type is a binary tree.  Assuming
that we are working with a binary tree holding integers where each node
is represented by a ‘node(Left, Right)’ compound term, we can define a
‘node(Depth)’ type where ‘Depth’ is the maximum depth of the tree.  This
argument allows us to prevent excessively deep trees:

     :- category(binary_tree).

         :- multifile(type::type/1).
         type::type(node(_)).

         :- multifile(type::check/2).
         type::check(node(_), Term) :-
             (   check(Term) ->
                 true
             ;   var(Term) ->
                 throw(instantiation_error)
             ;   throw(type_error(node(_), Term))
             ).

         check(Term) :-
             (   integer(Term) ->
                 true
             ;   compound(Term),
                 Term = node(Left, Right),
                 check(Left),
                 check(Right)
             ).

         :- multifile(arbitrary::arbitrary/1).
         arbitrary::arbitrary(node(_)).

         :- multifile(arbitrary::arbitrary/2).
         arbitrary::arbitrary(node(Depth), Arbitrary) :-
         (   Depth > 1 ->
             NewDepth is Depth - 1,
             type::arbitrary(
                 types_frequency([
                     integer - 1,
                     compound(
                         node,
                         [
                             types([node(NewDepth), integer]),
                             types([node(NewDepth), integer])
                         ]
                     ) - 3
                 ]),
                 Arbitrary
             )
         ;   type::arbitrary(
         integer, Arbitrary)
         ).

     :- end_category.

In this second example, we use some of the pre-defined types provided by
the library.  The ‘types_frequency(Pairs)’ type supports generating
random terms for a type in the ‘Type-Frequency’ pairs list where the
type is randomly chosen after the types relative frequency.  The
‘compound(Name, Types)’ type supports generating compound terms with a
given name and random arguments after the given types:

     | ?- type::arbitrary(node(4), Arbitrary).
     Arbitrary = 907
     yes

     | ?- type::arbitrary(node(4), Arbitrary).
     Arbitrary = node(node(node(522, 509), node(83, 453)), node(454, -197))
     yes

     | ?- type::arbitrary(node(4), Arbitrary).
     Arbitrary = node(node(-875, -866), -254)
     yes

     | ?- type::arbitrary(node(4), Arbitrary).
     Arbitrary = node(-133, -831)
     yes

The source code of these examples can be found in the ‘test_files’
directory.  Other examples of arbitrary term generators can be found in
the implementation of the ‘optionals’ and ‘expecteds’ libraries.


File: TheLogtalkHandbook-3.101.0.info,  Node: Scoped generators and shrinkers,  Next: Reproducing sequences of arbitrary terms,  Prev: Defining new generators and shrinkers,  Up: arbitrary

6.8.7 Scoped generators and shrinkers
-------------------------------------

Declaring a new generator and possibly a shrinker for a custom type
raises the possibility of a conflict with third-party-defined generators
and shrinkers.  An alternative is to use the ‘(::)/2’ meta-type to
define scoped generators and shrinkers.  For example:

     :- object(scoped).

         % the same predicate is used for both generating and validating
         :- public(custom/1).
         custom(Term) :-
             (   var(Term) ->
                 % assume predicate used as a generator
                 random::random(Term)
             ;   % assume predicate used as a validator
                 float(Term)
             ).

         % a predicate with the same name is used for shrinking
         :- public(custom/2).
         custom(Larger, Small) :-
             Small is Larger / 2.

     :- end_object.

Some sample calls:

     | ?- type::arbitrary(scoped::custom, Arbitrary).
     Arbitrary = 0.5788130906607927
     yes

     | ?- type::valid(scoped::custom, foo).
     no

     | ?- type::check(scoped::custom, _).
     ERROR: type_error(instantiation_error)

     | ?- type::check(scoped::custom, foo).
     ERROR: type_error(scoped::custom, foo)

     | ?- type::shrink(scoped::custom, 0.42, Smaller).
     Smaller = 0.21
     yes

The source code of this example can be found in the ‘test_files’
directory.


File: TheLogtalkHandbook-3.101.0.info,  Node: Reproducing sequences of arbitrary terms,  Next: Default size of generated terms,  Prev: Scoped generators and shrinkers,  Up: arbitrary

6.8.8 Reproducing sequences of arbitrary terms
----------------------------------------------

The ‘arbitrary’ category provides access to the pseudo-random generator
it uses via the ‘get_seed/1’ and ‘set_seed/1’.  This allows sequences of
arbitrary values to be reproduced.  For example:

     | ?- type::get_seed(Seed).
     Seed = seed(3172, 9814, 20125)
     yes

     | ?- type::arbitrary(integer, Arbitrary).
     Arbitrary = -816
     yes

     | ?- type::arbitrary(integer, Arbitrary).
     Arbitrary = -113
     yes

     | ?- type::arbitrary(integer, Arbitrary).
     Arbitrary = 446

     | ?- type::set_seed(seed(3172, 9814, 20125)).
     yes

     | ?- type::arbitrary(integer, Arbitrary).
     Arbitrary = -816
     yes

     | ?- type::arbitrary(integer, Arbitrary).
     Arbitrary = -113
     yes

     | ?- type::arbitrary(integer, Arbitrary).
     Arbitrary = 446
     yes

The seed should be regarded as an opaque term and handled using the
‘get_seed/1’ and ‘set_seed/1’ predicates.  These predicates are notably
used in the QuickCheck implementation provided by the ‘lgtunit’ tool.


File: TheLogtalkHandbook-3.101.0.info,  Node: Default size of generated terms,  Next: Known issues<10>,  Prev: Reproducing sequences of arbitrary terms,  Up: arbitrary

6.8.9 Default size of generated terms
-------------------------------------

The library uses the value 42 for the default size of generated terms
for types where size is meaningful and implicit.  To override this
default value, define a clause for the ‘arbitrary::max_size/1’ multifile
predicate.  The new default size must be a positive integer.  For
example:

     :- multifile(arbitrary::max_size/1).
     arbitrary::max_size(7).

When multiple definitions exist, the first valid one found is used.
When no definition is valid, the default value of 42 is used.


File: TheLogtalkHandbook-3.101.0.info,  Node: Known issues<10>,  Prev: Default size of generated terms,  Up: arbitrary

6.8.10 Known issues
-------------------

Some Prolog systems either don’t support the null character or provide
buggy results when calling ‘char_code/2’ with a code of zero.  When
that’s the case, the null character is excluded when generating
arbitrary characters or character codes.

Generating arbitrary Unicode characters (instead of Unicode codepoints)
is inherently problematic as the process first generates codepoints and
then tries to use the standard ‘char_code/2’ to convert them to
characters.  But, depending on the backend Prolog system and its
internal (if any) Unicode normalization, it may not be possible to
convert a codepoint to a single character.


File: TheLogtalkHandbook-3.101.0.info,  Node: arrangements,  Next: assignvars,  Prev: arbitrary,  Up: Libraries

6.9 ‘arrangements’
==================

This library provides predicates for generating and querying
arrangements over lists.  Arrangements are ordered selections of a given
length with element repetition allowed.  The following categories of
predicates are provided:

   - 'Generation operations' - Predicates for generating arrangements.

   - 'Ordering variants' - Predicates that support an additional order
     argument (‘default’ or ‘lexicographic’) for controlling output
     order.

   - 'Distinct-value generation' - Predicates for generating
     arrangements while deduplicating equal-valued results.

   - 'Indexed access' - Predicates for direct access to arrangements at
     specific positions, including distinct arrangements.

   - 'Lexicographic stepping' - Predicates for navigating arrangements
     in lexicographic order.

   - 'Counting operations' - Predicates for counting arrangements and
     distinct arrangements.

   - 'Random selection' - Predicates for randomly selecting and sampling
     arrangements and distinct arrangements.

Dedicated ‘cartesian_products’, ‘permutations’, ‘combinations’,
‘multisets’, ‘derangements’, ‘partitions’, and ‘subsequences’ libraries
are also available for focused APIs on related operations.

* Menu:

* API documentation: API documentation<28>.
* Loading: Loading<29>.
* Testing: Testing<24>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<28>,  Next: Loading<29>,  Up: arrangements

6.9.1 API documentation
-----------------------

Open the ‘../../apis/library_index.html#arrangements’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<29>,  Next: Testing<24>,  Prev: API documentation<28>,  Up: arrangements

6.9.2 Loading
-------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(arrangements(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<24>,  Prev: Loading<29>,  Up: arrangements

6.9.3 Testing
-------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(arrangements(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: assignvars,  Next: avro,  Prev: arrangements,  Up: Libraries

6.10 ‘assignvars’
=================

The ‘assignvarsp’ protocol declares the predicates used for logical
assignment of Prolog terms developed by Nobukuni Kino.

The ‘assignvars’ object provides a declarative implementation of the
‘assignvarsp’ protocol.  It can be used with any backend Prolog
compiler.

The ‘nd_assignvars’ object provides a non-declarative but faster
implementation of the ‘assignvarsp’ protocol.  It can be used with the
following backend Prolog compilers: B-Prolog, CxProlog, ECLiPSe, GNU
Prolog, SICStus Prolog, SWI-Prolog, and YAP.

For more information on assignvars, please consult the URL:

‘https://web.archive.org/web/20160818050049/http://www.kprolog.com/en/logical_assignment/’

The representation of assignable terms should be regarded as an opaque
term and only accessed using the library predicates.

* Menu:

* API documentation: API documentation<29>.
* Loading: Loading<30>.
* Testing: Testing<25>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<29>,  Next: Loading<30>,  Up: assignvars

6.10.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#assignvars’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<30>,  Next: Testing<25>,  Prev: API documentation<29>,  Up: assignvars

6.10.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(assignvars(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<25>,  Prev: Loading<30>,  Up: assignvars

6.10.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(assignvars(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: avro,  Next: base32,  Prev: assignvars,  Up: Libraries

6.11 ‘avro’
===========

The ‘avro’ library implements predicates for reading (parsing) and
writing (generating) data in the Apache Avro binary format:

   - ‘https://avro.apache.org/docs/current/specification/’

'This library requires a backend supporting unbounded integer
arithmetic.'

* Menu:

* API documentation: API documentation<30>.
* Loading: Loading<31>.
* Testing: Testing<26>.
* Schema representation::
* Data representation::
* Schema Examples::
* Encoding::
* Decoding::


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<30>,  Next: Loading<31>,  Up: avro

6.11.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#avro’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<31>,  Next: Testing<26>,  Prev: API documentation<30>,  Up: avro

6.11.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(avro(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<26>,  Next: Schema representation,  Prev: Loading<31>,  Up: avro

6.11.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(avro(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Schema representation,  Next: Data representation,  Prev: Testing<26>,  Up: avro

6.11.4 Schema representation
----------------------------

Schema files use the ‘.avsc’ extension and their contents are always
valid JSON values.  They can be parsed using the ‘json(curly,dash,atom)’
library object.


File: TheLogtalkHandbook-3.101.0.info,  Node: Data representation,  Next: Schema Examples,  Prev: Schema representation,  Up: avro

6.11.5 Data representation
--------------------------

Data to be serialized to Avro binary format files can be represented in
the JSON Lines format (using the ‘.jsonl’ extension) and parsed using
the ‘json_lines(curly, dash, atom)’ library object.


File: TheLogtalkHandbook-3.101.0.info,  Node: Schema Examples,  Next: Encoding,  Prev: Data representation,  Up: avro

6.11.6 Schema Examples
----------------------

Primitive type schemas:

   - ‘null’

   - ‘boolean’

   - ‘int’

   - ‘long’

   - ‘float’

   - ‘double’

   - ‘bytes’

   - ‘string’

Array schema example represented as a JSON term:

     {type-array, items-int}


File: TheLogtalkHandbook-3.101.0.info,  Node: Encoding,  Next: Decoding,  Prev: Schema Examples,  Up: avro

6.11.7 Encoding
---------------

Encoding is accomplished using the ‘generate/3’ or ‘generate/4’
predicates.  For example, assuming the schema is just ‘int’:

     | ?- avro::generate(bytes(Bytes), int, 42).
     Bytes = [84]
     yes

Or an array of ‘int’:

     | ?- avro::generate(bytes(Bytes), {type-array,items-int}, [42,37,13,17]).
     Bytes = [8,84,74,26,34,0]
     yes

To include the schema in the output (as an Avro Object Container File),
use the ‘generate/4’ predicate with the second argument set to ‘true’.
For example:

     | ?- avro::generate(file('output.avro'), true, {type-array,items-int}, [42,37,13,17]).
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: Decoding,  Prev: Encoding,  Up: avro

6.11.8 Decoding
---------------

Decoding is accomplished using the ‘parse/2’ or ‘parse/3’ predicates.

When parsing a file that includes a schema (Avro Object Container File),
use ‘parse/2’ which returns a ‘Schema-Data’ pair.  For example:

     | ?- avro::parse(file('input.avro'), Schema-Data).

When the schema is not present in the file, ‘Schema’ is unified with
‘false’.

When parsing with a known schema, use instead the ‘parse/3’ predicate.
For example:

     | ?- avro::parse(bytes([84]), int, Data).
     Data = 42
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: base32,  Next: base58,  Prev: avro,  Up: Libraries

6.12 ‘base32’
=============

The ‘base32’ library provides predicates for encoding and decoding data
in the Base32 format as per the specification found at:

‘https://www.rfc-editor.org/rfc/rfc4648’

* Menu:

* API documentation: API documentation<31>.
* Loading: Loading<32>.
* Testing: Testing<27>.
* Encoding: Encoding<2>.
* Decoding: Decoding<2>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<31>,  Next: Loading<32>,  Up: base32

6.12.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#base32’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<32>,  Next: Testing<27>,  Prev: API documentation<31>,  Up: base32

6.12.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ utility
file:

     | ?- logtalk_load(base32(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<27>,  Next: Encoding<2>,  Prev: Loading<32>,  Up: base32

6.12.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(base32(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Encoding<2>,  Next: Decoding<2>,  Prev: Testing<27>,  Up: base32

6.12.4 Encoding
---------------

Encoding a list of bytes in Base32 format is accomplished by the
‘base32::generate/2’ predicate.  For example:

     | ?- atom_codes('Hello!', Bytes),
          base32::generate(atom(Base32), Bytes).
     Base32 = 'JBSWY3DPEE======'
     Bytes = [72,101,108,108,111,33]
     yes

     | ?- atom_codes('Hello!', Bytes),
          base32::generate(codes(Base32), Bytes).
     Base32 = [74,66,83,87,89,51,68,80,69,69,61,61,61,61,61,61]
     Bytes = [72,101,108,108,111,33]
     yes

The Base32 result can also be represented using a list of chars, written
to a file or to a stream.  See the API documentation for details.


File: TheLogtalkHandbook-3.101.0.info,  Node: Decoding<2>,  Prev: Encoding<2>,  Up: base32

6.12.5 Decoding
---------------

Decoding of Base32 data is accomplished using the ‘base32::parse/2’
predicate.  For example:

     | ?- base32::parse(atom('JBSWY3DPEE======'), Bytes),
          atom_codes(Atom, Bytes).
     Atom = 'Hello!'
     Bytes = [72,101,108,108,111,33]
     yes

     | ?- base32::parse(chars(['J','B','S','W','Y','3','D','P','E','E','=','=','=','=','=','=']), Bytes),
          atom_codes(Atom, Bytes).
     Atom = 'Hello!'
     Bytes = [72,101,108,108,111,33]
     yes

The ‘base32::parse/2’ predicate accepts other input sources such as a
file or a stream.  See the API documentation for details.  Both
uppercase and lowercase letters are accepted when decoding.


File: TheLogtalkHandbook-3.101.0.info,  Node: base58,  Next: base64,  Prev: base32,  Up: Libraries

6.13 ‘base58’
=============

The ‘base58’ library provides predicates for encoding and decoding data
in the Base58 format using the Bitcoin alphabet variant.  Base58 is
commonly used in Bitcoin addresses and other cryptocurrency
applications.  The Bitcoin alphabet excludes visually ambiguous
characters:

   - ‘0’ (zero), ‘O’ (uppercase o)

   - ‘I’ (uppercase i), ‘l’ (lowercase L)

Alphabet: ‘123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz’

For more details, see for example:

‘https://bitcoinwiki.org/wiki/base58’

'This library requires a backend supporting unbounded integer
arithmetic.'

* Menu:

* API documentation: API documentation<32>.
* Loading: Loading<33>.
* Testing: Testing<28>.
* Encoding: Encoding<3>.
* Decoding: Decoding<3>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<32>,  Next: Loading<33>,  Up: base58

6.13.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#base58’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<33>,  Next: Testing<28>,  Prev: API documentation<32>,  Up: base58

6.13.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ utility
file:

     | ?- logtalk_load(base58(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<28>,  Next: Encoding<3>,  Prev: Loading<33>,  Up: base58

6.13.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(base58(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Encoding<3>,  Next: Decoding<3>,  Prev: Testing<28>,  Up: base58

6.13.4 Encoding
---------------

Encoding a list of bytes in Base58 format is accomplished by the
‘base58::generate/2’ predicate.  For example:

     | ?- atom_codes('Hello World', Bytes),
          base58::generate(atom(Base58), Bytes).
     Base58 = 'JxF12TrwUP45BMd'
     Bytes = [72,101,108,108,111,32,87,111,114,108,100]
     yes

Leading zero bytes are preserved and encoded as ‘1’ characters:

     | ?- base58::generate(atom(Base58), [0, 0, 0, 1, 2, 3]).
     Base58 = '111Ldp'
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: Decoding<3>,  Prev: Encoding<3>,  Up: base58

6.13.5 Decoding
---------------

Decoding of Base58 data is accomplished using the ‘base58::parse/2’
predicate.  For example:

     | ?- base58::parse(atom('JxF12TrwUP45BMd'), Bytes),
          atom_codes(Atom, Bytes).
     Atom = 'Hello World'
     Bytes = [72,101,108,108,111,32,87,111,114,108,100]
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: base64,  Next: base85,  Prev: base58,  Up: Libraries

6.14 ‘base64’
=============

The ‘base64’ library provides predicates for parsing and generating data
in the Base64 and Base64URL formats as per the specification found at:

‘https://www.rfc-editor.org/rfc/rfc4648’

* Menu:

* API documentation: API documentation<33>.
* Loading: Loading<34>.
* Testing: Testing<29>.
* Encoding: Encoding<4>.
* Decoding: Decoding<4>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<33>,  Next: Loading<34>,  Up: base64

6.14.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#base64’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<34>,  Next: Testing<29>,  Prev: API documentation<33>,  Up: base64

6.14.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ utility
file:

     | ?- logtalk_load(base64(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<29>,  Next: Encoding<4>,  Prev: Loading<34>,  Up: base64

6.14.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(base64(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Encoding<4>,  Next: Decoding<4>,  Prev: Testing<29>,  Up: base64

6.14.4 Encoding
---------------

Encoding a list of bytes in Base64 format is accomplished by the
‘base64::generate/2’ predicate.  For example:

     | ?- atom_codes('Hello world!', Bytes),
          base64::generate(atom(Base64), Bytes).
     Base64 = 'SGVsbG8gd29ybGQh'
     Bytes = [72,101,108,108,111,32,119,111,114,108,100,33]
     yes

     | ?- atom_codes('Hello world!', Bytes),
          base64::generate(codes(Base64), Bytes).
     Base64 = [83,71,86,115,98,71,56,103,100,50,57,121,98,71,81,104]
     Bytes = [72,101,108,108,111,32,119,111,114,108,100,33]
     yes

The Base64 result can also be represented using a list of chars, written
to a file or to a stream.  See the API documentation for details.

For safe encoding of URLs, use instead the Base64URL format.  For
example:

     | ?- base64url::generate(atom(Base64URL), 'https://logtalk.org').
     Base64URL == 'aHR0cHM6Ly9sb2d0YWxrLm9yZw=='
     yes

The Base64URL can also be represented using a list of chars or a list of
codes.  The input URL should be in the same format.  Use the
‘base64url_no_padding’ object when a specification explicitly omits
Base64URL padding, such as JOSE (JWT, JWS, and JWK) and PKCE.


File: TheLogtalkHandbook-3.101.0.info,  Node: Decoding<4>,  Prev: Encoding<4>,  Up: base64

6.14.5 Decoding
---------------

Decoding of Base64 data is accomplished using the ‘base64::parse/2’
predicate.  For example:

     | ?- base64::parse(atom('SGVsbG8gd29ybGQh'), Bytes),
          atom_codes(Atom, Bytes).
     Atom = 'Hello world!'
     Bytes = [72,101,108,108,111,32,119,111,114,108,100,33]
     yes

     | ?- base64::parse(chars(['S','G','V',s,b,'G','8',g,d,'2','9',y,b,'G','Q',h]), Bytes),
          atom_codes(Atom, Bytes).
     Atom = 'Hello world!'
     Bytes = [72,101,108,108,111,32,119,111,114,108,100,33]
     yes

The ‘base64::parse/2’ predicate accepts other input source such as a
file or a stream.  See the API documentation for details.

For decoding of URLs in the Base64URL format, use the
‘base64url::parse/2’ predicate.  For example:

     | ?- base64url::parse(atom('aHR0cHM6Ly9sb2d0YWxrLm9yZw=='), URL).
     URL == 'https://logtalk.org'
     yes

The ‘base64url::parse/2’ predicate also accepts a list of chars or a
list of codes as input.  See the API documentation for details.


File: TheLogtalkHandbook-3.101.0.info,  Node: base85,  Next: basic_types,  Prev: base64,  Up: Libraries

6.15 ‘base85’
=============

The ‘base85’ library provides predicates for encoding and decoding data
in the Base85 (Ascii85) format.  Ascii85 is used in PostScript and PDF
files.  The encoding uses printable ASCII characters from ‘!’ (33) to
‘u’ (117).  A special shortcut ‘z’ represents four zero bytes.  For more
details, see for example:

‘https://en.wikipedia.org/wiki/Ascii85’

* Menu:

* API documentation: API documentation<34>.
* Loading: Loading<35>.
* Testing: Testing<30>.
* Encoding: Encoding<5>.
* Decoding: Decoding<5>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<34>,  Next: Loading<35>,  Up: base85

6.15.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#base85’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<35>,  Next: Testing<30>,  Prev: API documentation<34>,  Up: base85

6.15.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ utility
file:

     | ?- logtalk_load(base85(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<30>,  Next: Encoding<5>,  Prev: Loading<35>,  Up: base85

6.15.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(base85(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Encoding<5>,  Next: Decoding<5>,  Prev: Testing<30>,  Up: base85

6.15.4 Encoding
---------------

Encoding a list of bytes in Base85 format is accomplished by the
‘base85::generate/2’ predicate.  For example:

     | ?- atom_codes('Man ', Bytes),
          base85::generate(atom(Base85), Bytes).
     Base85 = '9jqo^'
     Bytes = [77,97,110,32]
     yes

Four zero bytes are encoded as the special character ‘z’:

     | ?- base85::generate(atom(Base85), [0, 0, 0, 0]).
     Base85 = 'z'
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: Decoding<5>,  Prev: Encoding<5>,  Up: base85

6.15.5 Decoding
---------------

Decoding of Base85 data is accomplished using the ‘base85::parse/2’
predicate.  For example:

     | ?- base85::parse(atom('9jqo^'), Bytes),
          atom_codes(Atom, Bytes).
     Atom = 'Man '
     Bytes = [77,97,110,32]
     yes

The parser also accepts input with optional ‘<~’ and ‘~>’ delimiters:

     | ?- base85::parse(atom('<~9jqo^~>'), Bytes),
          atom_codes(Atom, Bytes).
     Atom = 'Man '
     Bytes = [77,97,110,32]
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: basic_types,  Next: bayesian_ridge_regression,  Prev: base85,  Up: Libraries

6.16 ‘basic_types’
==================

The ‘basic_types’ library is a virtual library that loads only basic
types from the ‘types’ library:

   - ‘comparingp’

   - ‘termp’, ‘term’

   - ‘atomic’, ‘atom’, ‘number’, ‘float’, ‘integer’

   - ‘compound’, ‘listp’, ‘list’

   - ‘type’

* Menu:

* API documentation: API documentation<35>.
* Loading: Loading<36>.
* Testing: Testing<31>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<35>,  Next: Loading<36>,  Up: basic_types

6.16.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#types’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<36>,  Next: Testing<31>,  Prev: API documentation<35>,  Up: basic_types

6.16.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(basic_types(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<31>,  Prev: Loading<36>,  Up: basic_types

6.16.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file for the
‘types’ library:

     | ?- logtalk_load(types(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: bayesian_ridge_regression,  Next: borda_ranker,  Prev: basic_types,  Up: Libraries

6.17 ‘bayesian_ridge_regression’
================================

Bayesian ridge regression regressor supporting continuous and
mixed-feature datasets.  The library implements the ‘regressor_protocol’
defined in the ‘regression_protocols’ library and learns a Bayesian
linear model using evidence maximization for the global weight and noise
precisions together with Gamma hyperpriors over both precision terms.

* Menu:

* API documentation: API documentation<36>.
* Loading: Loading<37>.
* Testing: Testing<32>.
* Features: Features<6>.
* Regressor representation::
* Diagnostics syntax::
* Options: Options<6>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<36>,  Next: Loading<37>,  Up: bayesian_ridge_regression

6.17.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#bayesian_ridge_regression’ link
in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<37>,  Next: Testing<32>,  Prev: API documentation<36>,  Up: bayesian_ridge_regression

6.17.2 Loading
--------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(bayesian_ridge_regression(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<32>,  Next: Features<6>,  Prev: Loading<37>,  Up: bayesian_ridge_regression

6.17.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(bayesian_ridge_regression(tester)).

To run the performance benchmark suite, load the
‘tester_performance.lgt’ file:

     | ?- logtalk_load(bayesian_ridge_regression(tester_performance)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<6>,  Next: Regressor representation,  Prev: Testing<32>,  Up: bayesian_ridge_regression

6.17.4 Features
---------------

   - 'Continuous and Mixed Features': Supports continuous attributes and
     categorical attributes encoded using reference-level dummy coding
     from the declared dataset attribute values.

   - 'Automatic Hyperparameter Tuning': Learns the global coefficient
     precision and observation-noise precision using MacKay-style
     evidence maximization with configurable Gamma hyperpriors instead
     of a user-supplied ridge penalty.

   - 'Posterior Uncertainty': Exposes predictive Gaussian distributions
     using coefficient posterior uncertainty plus observation noise,
     matching the usual scikit-learn BayesianRidge treatment where the
     intercept is not probabilistic.  Posterior coefficient variances
     are also exposed.

   - 'Feature Scaling': Continuous attributes can be standardized using
     z-score scaling before fitting and prediction.

   - 'Stable Posterior Solves': Evidence-maximization updates clamp the
     learned weight and noise precisions to configurable
     ‘precision_bounds(Min, Max)’ to avoid degenerate zero or infinite
     precision estimates.  Posterior solves use Cholesky factorization
     of positive-definite precision matrices, diagnostics report any
     diagonal jitter applied when factorization retries are needed, and
     the evidence-maximization loop computes the effective degrees of
     freedom from a one-time eigenspectrum of the centered Gram
     surrogate while still switching to a sample-space solve when the
     active encoded feature count exceeds the number of training rows.

   - 'Missing Values': Missing numeric and categorical values
     represented using anonymous variables are encoded using explicit
     missing-value indicator features.

   - 'Unknown Values': Prediction requests containing categorical values
     that are not declared by the dataset raise a domain error.

   - 'Zero-Variance Features': Encoded columns with zero variance are
     excluded from posterior updates and assigned zero mean and zero
     posterior variance.

   - 'Diagnostics Metadata': Learned regressors record model name,
     target, training example count, Cholesky stabilization attempts and
     applied jitter, Gamma hyperpriors for both precision terms,
     effective precision bounds, learned precisions, learned noise
     variance, final log evidence, the full log-evidence score trace,
     active feature count, posterior variances, intercept treatment,
     convergence metric and status, encoded feature count, and effective
     options.

   - 'Model Export': Learned regressors can be exported as predicate
     clauses or written to a file.


File: TheLogtalkHandbook-3.101.0.info,  Node: Regressor representation,  Next: Diagnostics syntax,  Prev: Features<6>,  Up: bayesian_ridge_regression

6.17.5 Regressor representation
-------------------------------

The learned regressor is represented by default as:

   - ‘bayesian_ridge_regressor(Encoders, Bias, Weights, ActiveFlags,
     PosteriorCovariance, NoiseVariance, Diagnostics)’

The exported predicate clauses therefore use the shape:

   - ‘Functor(Encoders, Bias, Weights, ActiveFlags, PosteriorCovariance,
     NoiseVariance, Diagnostics)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Diagnostics syntax,  Next: Options<6>,  Prev: Regressor representation,  Up: bayesian_ridge_regression

6.17.6 Diagnostics syntax
-------------------------

The ‘diagnostics/2’ predicate returns a list of metadata terms with the
form:

     [
         model(bayesian_ridge_regression),
         target(Target),
         training_example_count(TrainingExampleCount),
         options(Options),
         solver(cholesky_factorization),
         stabilization_attempts(StabilizationAttempts),
         stabilization_jitter(StabilizationJitter),
         precision_bounds(MinimumPrecision, MaximumPrecision),
         weight_precision_hyperprior(gamma(LambdaShape, LambdaRate)),
         noise_precision_hyperprior(gamma(AlphaShape, AlphaRate)),
         weight_precision(Alpha),
         noise_precision(Beta),
         noise_variance(NoiseVariance),
         log_evidence(LogEvidence),
         scores(Scores),
         active_feature_count(ActiveFeatureCount),
         weight_prior(isotropic_zero_mean_gaussian),
         intercept_treatment(non_probabilistic),
         bias_variance(BiasVariance),
         weight_variances(WeightVariances),
         convergence_metric(coefficient_l1),
         convergence(Convergence),
         iterations(Iterations),
         final_delta(FinalDelta),
         encoded_feature_count(FeatureCount)
     ]

The ‘scores/1’ diagnostic is analogous to scikit-learn ‘scores_’: it
stores the log marginal likelihood at the initial hyperparameters
followed by the value after each evidence-maximization update.  The
final element is identical to ‘log_evidence/1’.

The ‘bias_variance/1’ diagnostic is always ‘0.0’ because the intercept
is treated as a deterministic centering adjustment rather than as a
probabilistic parameter.

Use the ‘regression_protocols’ ‘diagnostic/2’ and ‘regressor_options/2’
helper predicates when you only need a single metadata term or the
effective options.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<6>,  Prev: Diagnostics syntax,  Up: bayesian_ridge_regression

6.17.7 Options
--------------

The ‘learn/3’ predicate accepts the following options:

   - ‘maximum_iterations/1’: Maximum number of evidence-maximization
     updates.  The default is ‘300’.

   - ‘tolerance/1’: Convergence tolerance on the L1 change between
     consecutive active coefficient vectors across evidence-maximization
     updates.  The default is ‘1.0e-6’.

   - ‘initial_weight_precision/1’: Positive initial value for the shared
     coefficient precision.  The default is ‘1.0’.

   - ‘initial_noise_precision/1’: Positive initial value for the
     observation-noise precision or ‘auto’ to derive it from the target
     variance.  The default is ‘auto’.

   - ‘alpha_1/1’: Non-negative shape hyperparameter of the Gamma prior
     over the learned observation-noise precision.  The default is
     ‘1.0e-6’.

   - ‘alpha_2/1’: Non-negative rate hyperparameter of the Gamma prior
     over the learned observation-noise precision.  The default is
     ‘1.0e-6’.

   - ‘lambda_1/1’: Non-negative shape hyperparameter of the Gamma prior
     over the learned coefficient precision.  The default is ‘1.0e-6’.

   - ‘lambda_2/1’: Non-negative rate hyperparameter of the Gamma prior
     over the learned coefficient precision.  The default is ‘1.0e-6’.

   - ‘feature_scaling/1’: Controls z-score standardization of continuous
     attributes before training and prediction.  Accepted values are
     ‘true’ and ‘false’.  The default is ‘true’.

   - ‘precision_bounds/2’: Lower and upper positive bounds used to clamp
     the learned weight and noise precisions during evidence
     maximization for numerical stability.  The default is
     ‘precision_bounds(1.0e-12, 1.0e12)’.


File: TheLogtalkHandbook-3.101.0.info,  Node: borda_ranker,  Next: bradley_terry_ranker,  Prev: bayesian_ridge_regression,  Up: Libraries

6.18 ‘borda_ranker’
===================

Borda grouped-ranking ranker.  Ranks each item by summing, across
groups, the number of same-group items with strictly lower relevance.

The library implements the ‘ranker_protocol’ defined in the
‘ranking_protocols’ library.  It provides predicates for learning a
ranker from grouped relevance judgments, using it to order candidate
items, and exporting it as a list of predicate clauses or to a file.

Datasets are represented as objects implementing the
‘ranking_dataset_protocol’ protocol from the ‘ranking_protocols’
library.  See the ‘test_datasets’ directory for examples.  ‘The training
dataset must declare each group once, use only declared groups and items
in relevance judgments, and assign non-negative integer relevance
values.

* Menu:

* API documentation: API documentation<37>.
* Loading: Loading<38>.
* Testing: Testing<33>.
* Features: Features<7>.
* Scoring semantics::
* Usage: Usage<18>.
* Diagnostics syntax: Diagnostics syntax<2>.
* Options: Options<7>.
* Ranker representation::
* References: References<3>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<37>,  Next: Loading<38>,  Up: borda_ranker

6.18.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#borda_ranker’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<38>,  Next: Testing<33>,  Prev: API documentation<37>,  Up: borda_ranker

6.18.2 Loading
--------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(borda_ranker(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<33>,  Next: Features<7>,  Prev: Loading<38>,  Up: borda_ranker

6.18.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(borda_ranker(tester)).

To run the performance benchmark suite, load the
‘tester_performance.lgt’ file:

     | ?- logtalk_load(borda_ranker(tester_performance)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<7>,  Next: Scoring semantics,  Prev: Testing<33>,  Up: borda_ranker

6.18.4 Features
---------------

   - 'Grouped Relevance Learning': Learns one deterministic item score
     from grouped ranking or relevance-judgment datasets.

   - 'Portable Borda Scoring': Computes scores using only non-negative
     integer grouped relevance judgments and standard Logtalk library
     predicates.  Within each group, an item receives one point for
     every same-group item with strictly lower relevance when using
     ‘tie_scoring(standard)’ and the average of the minimum and maximum
     tied positions when using ‘tie_scoring(fractional)’.

   - 'Deterministic Ranking': Orders candidate items by learned score
     with deterministic tie-breaking.  Ranking ties are broken
     deterministically using the standard term order of the item
     identifiers after sorting by descending score.

   - 'Missing relevance semantics': Missing relevance facts are treated
     as zero by default using the ‘missing_relevance(zero)’ option and
     can be rejected using ‘missing_relevance(error)’.

   - 'Strict Dataset Validation': Rejects duplicate groups, duplicate
     items within a group, undeclared groups or items in relevance
     judgments, and non-integer or negative relevance values.

   - 'Explicit Semantics Options': The ‘learn/3’ predicate exposes the
     current tie and missing-relevance policies using the
     ‘tie_scoring/1’ and ‘missing_relevance/1’ options.

   - 'Benchmark Coverage': Includes a dedicated performance suite for a
     large grouped dataset benchmark.

   - 'Training Diagnostics': Learned rankers include dataset summary
     metadata that can be accessed using the ‘diagnostics/2’ predicate.

   - 'Ranker Export': Learned rankers can be exported as self-contained
     terms.

   - 'Shared Ranking Infrastructure': Uses the common
     ‘ranking_protocols’ helper predicates for option processing,
     dataset validation, diagnostics, export, and candidate ranking.


File: TheLogtalkHandbook-3.101.0.info,  Node: Scoring semantics,  Next: Usage<18>,  Prev: Features<7>,  Up: borda_ranker

6.18.5 Scoring semantics
------------------------

This implementation uses a grouped Borda count variant over the declared
items of each group.  With the default ‘tie_scoring(standard)’ option,
an item receives one point for every same-group item with strictly lower
relevance.  Tied items therefore receive the same per-group
contribution, because equal relevance values do not add or subtract
points.

With the ‘tie_scoring(fractional)’ option, each tied relevance class
receives the average of the minimum and maximum per-group Borda points
available to that tie block.  For example, when two items tie above a
single lower-ranked item, both tied items receive ‘1.5’ points instead
of the ‘1’ point assigned by the default policy.

Missing relevance facts are treated as relevance ‘0’ only for items that
are declared in the group when using the default
‘missing_relevance(zero)’ option.  This allows grouped datasets to omit
explicit zero judgments while keeping the score computation
deterministic.  Use ‘missing_relevance(error)’ to reject grouped
datasets that omit a declared item relevance.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<18>,  Next: Diagnostics syntax<2>,  Prev: Scoring semantics,  Up: borda_ranker

6.18.6 Usage
------------

* Menu:

* Learning a ranker::
* Inspecting diagnostics::
* Ranking candidate items::
* Exporting the ranker::


File: TheLogtalkHandbook-3.101.0.info,  Node: Learning a ranker,  Next: Inspecting diagnostics,  Up: Usage<18>

6.18.6.1 Learning a ranker
..........................

     % Learn from a grouped ranking dataset object
     | ?- borda_ranker::learn(my_dataset, Ranker).
     ...

     % Learn with an explicit empty options list
     | ?- borda_ranker::learn(my_dataset, Ranker, []).
     ...

     % Learn while requiring every declared group item to have a relevance fact
     | ?- borda_ranker::learn(my_dataset, Ranker, [missing_relevance(error)]).
     ...

     % Learn using fractional tie scoring for tied relevance levels
     | ?- borda_ranker::learn(my_dataset, Ranker, [tie_scoring(fractional)]).
     ...

The current implementation accepts the ‘missing_relevance/1’ and
‘tie_scoring/1’ options described below.


File: TheLogtalkHandbook-3.101.0.info,  Node: Inspecting diagnostics,  Next: Ranking candidate items,  Prev: Learning a ranker,  Up: Usage<18>

6.18.6.2 Inspecting diagnostics
...............................

     % Inspect model and dataset summary metadata
     | ?- borda_ranker::learn(my_dataset, Ranker),
          borda_ranker::diagnostics(Ranker, Diagnostics).
     Diagnostics = [...]
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Ranking candidate items,  Next: Exporting the ranker,  Prev: Inspecting diagnostics,  Up: Usage<18>

6.18.6.3 Ranking candidate items
................................

     % Rank a candidate set from most preferred to least preferred
     | ?- borda_ranker::learn(my_dataset, Ranker),
          borda_ranker::rank(Ranker, [item_a, item_b, item_c], Ranking).
     Ranking = [...]
     ...

Candidate lists must be proper lists of unique, ground items declared by
the training dataset.  Invalid ranker terms, duplicate candidates, and
candidates containing variables are rejected with errors instead of
being silently accepted.


File: TheLogtalkHandbook-3.101.0.info,  Node: Exporting the ranker,  Prev: Ranking candidate items,  Up: Usage<18>

6.18.6.4 Exporting the ranker
.............................

Learned rankers can be exported as a list of clauses or to a file for
later use.

     % Export as predicate clauses
     | ?- borda_ranker::learn(my_dataset, Ranker),
          borda_ranker::export_to_clauses(my_dataset, Ranker, my_ranker, Clauses).
     Clauses = [my_ranker(borda_ranker(...))]
     ...

     % Export to a file
     | ?- borda_ranker::learn(my_dataset, Ranker),
          borda_ranker::export_to_file(my_dataset, Ranker, my_ranker, 'ranker.pl').
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Diagnostics syntax<2>,  Next: Options<7>,  Prev: Usage<18>,  Up: borda_ranker

6.18.7 Diagnostics syntax
-------------------------

The ‘diagnostics/2’ predicate returns a list of metadata terms with the
form:

     [
         model(borda_ranker),
         options(Options),
         dataset_summary(DatasetSummary)
     ]

Where:

   - ‘model(borda_ranker)’ identifies the learning algorithm that
     produced the ranker.

   - ‘options(Options)’ stores the effective learning options after
     merging the user options with the library defaults.

   - ‘dataset_summary(DatasetSummary)’ stores a summary list describing
     the validated training dataset.

The current ‘dataset_summary/1’ payload has the form:

     [
         groups(NumberOfGroups),
         items(NumberOfItems),
         relevance_judgments(NumberOfJudgments)
     ]

Use the ‘ranking_protocols’ ‘diagnostic/2’ and ‘ranker_options/2’ helper
predicates when you only need a single metadata term or the effective
options.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<7>,  Next: Ranker representation,  Prev: Diagnostics syntax<2>,  Up: borda_ranker

6.18.8 Options
--------------

The following options can be passed to the ‘learn/3’ predicate:

   - ‘missing_relevance(Policy)’: Controls how declared group items
     without an explicit relevance fact are handled.  The supported
     values are ‘zero’ (default) and ‘error’.

   - ‘tie_scoring(Policy)’: Controls the grouped Borda tie semantics.
     The current implementation supports ‘standard’ (minimum tied-block
     score) and ‘fractional’ (average tied-block score).


File: TheLogtalkHandbook-3.101.0.info,  Node: Ranker representation,  Next: References<3>,  Prev: Options<7>,  Up: borda_ranker

6.18.9 Ranker representation
----------------------------

The learned ranker is represented by a compound term of the form:

     borda_ranker(Items, Scores, Diagnostics)

Where:

   - ‘Items’: List of ranked items.

   - ‘Scores’: List of ‘Item-Score’ pairs.

   - ‘Diagnostics’: List of metadata terms, including the effective
     options and dataset summary.

When exported using ‘export_to_clauses/4’ or ‘export_to_file/4’, this
ranker term is serialized directly as the single argument of the
generated predicate clause so that the exported model can be loaded and
reused as-is.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<3>,  Prev: Ranker representation,  Up: borda_ranker

6.18.10 References
------------------

  1. de Borda, J.-C. (1781).  Mémoire sur les élections au scrutin.
     'Histoire de l’Académie Royale des Sciences'.


File: TheLogtalkHandbook-3.101.0.info,  Node: bradley_terry_ranker,  Next: c45_classifier,  Prev: borda_ranker,  Up: Libraries

6.19 ‘bradley_terry_ranker’
===========================

Bradley-Terry pairwise preference ranker.  Uses a deterministic
minorization-maximization update to estimate one relative strength
parameter per item from weighted pairwise wins and losses.

The library implements the ‘ranker_protocol’ defined in the
‘ranking_protocols’ library.  It provides predicates for learning a
ranker from pairwise preferences, using it to order candidate items, and
exporting it as a list of predicate clauses or to a file.

Datasets are represented as objects implementing the
‘pairwise_ranking_dataset_protocol’ protocol from the
‘ranking_protocols’ library.  See the ‘test_datasets’ directory for
examples.  The training dataset must declare each ranked item once,
enumerate positive-weight pairwise preferences between distinct declared
items, induce a connected undirected comparison graph, and induce a
strongly connected directed win graph so that a finite Bradley-Terry
maximum-likelihood estimate exists.

* Menu:

* API documentation: API documentation<38>.
* Loading: Loading<39>.
* Testing: Testing<34>.
* Features: Features<8>.
* Dataset requirements::
* Usage: Usage<19>.
* Diagnostics syntax: Diagnostics syntax<3>.
* Options: Options<8>.
* Ranker representation: Ranker representation<2>.
* References: References<4>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<38>,  Next: Loading<39>,  Up: bradley_terry_ranker

6.19.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#bradley_terry_ranker’ link in a
web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<39>,  Next: Testing<34>,  Prev: API documentation<38>,  Up: bradley_terry_ranker

6.19.2 Loading
--------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(bradley_terry_ranker(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<34>,  Next: Features<8>,  Prev: Loading<39>,  Up: bradley_terry_ranker

6.19.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(bradley_terry_ranker(tester)).

To run the performance benchmark suite, load the
‘tester_performance.lgt’ file:

     | ?- logtalk_load(bradley_terry_ranker(tester_performance)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<8>,  Next: Dataset requirements,  Prev: Testing<34>,  Up: bradley_terry_ranker

6.19.4 Features
---------------

   - 'Pairwise Preference Learning': Learns relative item strengths from
     weighted head-to-head outcomes.

   - 'Original MM Fidelity': Rejects datasets without a finite
     Bradley-Terry maximum-likelihood estimate instead of masking them
     with implicit strength flooring or other hidden regularization.

   - 'Deterministic Ranking': Orders candidate items by learned strength
     with deterministic tie-breaking.

   - 'Strict Dataset Validation': Rejects duplicate items, undeclared
     items, self-preferences, non-positive weights, disconnected
     comparison graphs, and pairwise datasets that do not admit a finite
     Bradley-Terry maximum- likelihood estimate.

   - 'Training Diagnostics': Learned rankers include convergence and
     dataset summary metadata that can be accessed using the
     ‘diagnostics/2’ predicate.

   - 'Ranker Export': Learned rankers can be exported as self-contained
     terms.

   - 'Sparse Comparison Processing': Training aggregates weighted
     comparisons into sparse adjacency lists so iteration cost scales
     with observed pairwise comparisons instead of the full dense item
     cross-product.


File: TheLogtalkHandbook-3.101.0.info,  Node: Dataset requirements,  Next: Usage<19>,  Prev: Features<8>,  Up: bradley_terry_ranker

6.19.5 Dataset requirements
---------------------------

This implementation requires more than undirected connectedness.  In
order to admit a finite Bradley-Terry maximum-likelihood estimate, the
directed win graph induced by the preferences must be strongly
connected.  Datasets that leave one or more items isolated, split the
undirected comparison graph into multiple components, or create
dominance partitions with no directed path back to stronger items are
rejected instead of producing degenerate strengths.

For a related MAP formulation that keeps the same pairwise-preference
setting but uses an explicit Gamma prior to admit connected datasets
whose directed win graph is not strongly connected, see the
‘regularized_bradley_terry_ranker’ library.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<19>,  Next: Diagnostics syntax<3>,  Prev: Dataset requirements,  Up: bradley_terry_ranker

6.19.6 Usage
------------

* Menu:

* Learning a ranker: Learning a ranker<2>.
* Inspecting diagnostics: Inspecting diagnostics<2>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Learning a ranker<2>,  Next: Inspecting diagnostics<2>,  Up: Usage<19>

6.19.6.1 Learning a ranker
..........................

     % Learn from a pairwise ranking dataset object
     | ?- bradley_terry_ranker::learn(my_dataset, Ranker).
     ...

     % Learn with custom iteration and convergence options
     | ?- bradley_terry_ranker::learn(my_dataset, Ranker, [maximum_iterations(500), tolerance(1.0e-7)]).
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Inspecting diagnostics<2>,  Prev: Learning a ranker<2>,  Up: Usage<19>

6.19.6.2 Inspecting diagnostics
...............................

     % Inspect convergence and dataset summary metadata
     | ?- bradley_terry_ranker::learn(my_dataset, Ranker),
          bradley_terry_ranker::diagnostics(Ranker, Diagnostics).
     Diagnostics = [...]
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Diagnostics syntax<3>,  Next: Options<8>,  Prev: Usage<19>,  Up: bradley_terry_ranker

6.19.7 Diagnostics syntax
-------------------------

The ‘diagnostics/2’ predicate returns a list of metadata terms with the
form:

     [
         model(bradley_terry_ranker),
         options(Options),
         convergence(Status),
         iterations(Iterations),
         final_delta(FinalDelta),
         dataset_summary(DatasetSummary)
     ]

Where:

   - ‘model(bradley_terry_ranker)’ identifies the learning algorithm
     that produced the ranker.

   - ‘options(Options)’ stores the effective learning options after
     merging the user options with the library defaults.

   - ‘convergence(Status)’ records the training stop condition.  The
     current values are ‘converged’ and ‘maximum_iterations_exhausted’.

   - ‘iterations(Iterations)’ stores the number of update iterations
     that were executed.

   - ‘final_delta(FinalDelta)’ stores the maximum absolute strength
     update in the last iteration.

   - ‘dataset_summary(DatasetSummary)’ stores a summary list describing
     the validated training dataset.

The current ‘dataset_summary/1’ payload has the form:

     [
         items(NumberOfItems),
         preferences(NumberOfPreferences),
         connected_components(NumberOfComponents),
         isolated_items(IsolatedItems)
     ]

Where ‘IsolatedItems’ is the list of declared items that have no
comparisons.  For valid Bradley-Terry training datasets this list is
expected to be empty, because disconnected datasets are rejected.

For example, learning from the ‘head_to_head’ test dataset currently
returns diagnostics with the structure:

     [
         model(bradley_terry_ranker),
         options([maximum_iterations(5000), tolerance(1.0e-6)]),
         convergence(converged),
         iterations(...),
         final_delta(...),
         dataset_summary([
             items(4),
             preferences(6),
             connected_components(1),
             isolated_items([])
         ])
     ]

Use the ‘ranking_protocols’ ‘diagnostic/2’ and ‘ranker_options/2’ helper
predicates when you only need a single metadata term or the effective
options.

* Menu:

* Ranking candidate items: Ranking candidate items<2>.
* Exporting the ranker: Exporting the ranker<2>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Ranking candidate items<2>,  Next: Exporting the ranker<2>,  Up: Diagnostics syntax<3>

6.19.7.1 Ranking candidate items
................................

     % Rank a candidate set from most preferred to least preferred
     | ?- bradley_terry_ranker::learn(my_dataset, Ranker),
          bradley_terry_ranker::rank(Ranker, [item_a, item_b, item_c], Ranking).
     Ranking = [...]
     ...

Candidate lists must be proper lists of unique, ground items declared by
the training dataset.  Invalid ranker terms, duplicate candidates, and
candidates containing variables are rejected with errors instead of
being silently accepted.


File: TheLogtalkHandbook-3.101.0.info,  Node: Exporting the ranker<2>,  Prev: Ranking candidate items<2>,  Up: Diagnostics syntax<3>

6.19.7.2 Exporting the ranker
.............................

Learned rankers can be exported as a list of clauses or to a file for
later use.

     % Export as predicate clauses
     | ?- bradley_terry_ranker::learn(my_dataset, Ranker),
          bradley_terry_ranker::export_to_clauses(my_dataset, Ranker, my_ranker, Clauses).
     Clauses = [my_ranker(bt_ranker(...))]
     ...

     % Export to a file
     | ?- bradley_terry_ranker::learn(my_dataset, Ranker),
          bradley_terry_ranker::export_to_file(my_dataset, Ranker, my_ranker, 'ranker.pl').
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<8>,  Next: Ranker representation<2>,  Prev: Diagnostics syntax<3>,  Up: bradley_terry_ranker

6.19.8 Options
--------------

The following options can be passed to the ‘learn/3’ predicate:

   - ‘maximum_iterations(MaximumIterations)’: Positive integer iteration
     bound.

   - ‘tolerance(Tolerance)’: Positive convergence tolerance.


File: TheLogtalkHandbook-3.101.0.info,  Node: Ranker representation<2>,  Next: References<4>,  Prev: Options<8>,  Up: bradley_terry_ranker

6.19.9 Ranker representation
----------------------------

The learned ranker is represented by a compound term of the form:

     bt_ranker(Items, Strengths, Diagnostics)

Where:

   - ‘Items’: List of ranked items.

   - ‘Scores’: List of ‘Item-Strength’ pairs.

   - ‘Diagnostics’: List of metadata terms, including the effective
     options, convergence status, iteration count, final update delta,
     and dataset summary.

When exported using ‘export_to_clauses/4’ or ‘export_to_file/4’, this
ranker term is serialized directly as the single argument of the
generated predicate clause so that the exported model can be loaded and
reused as-is.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<4>,  Prev: Ranker representation<2>,  Up: bradley_terry_ranker

6.19.10 References
------------------

  1. Bradley, R. A. and Terry, M. E. (1952).  Rank analysis of
     incomplete block designs: I. The method of paired comparisons.
     'Biometrika', 39(3/4), 324-345.

  2. Hunter, D. R. (2004).  MM algorithms for generalized Bradley-Terry
     models.  'The Annals of Statistics', 32(1), 384-406.


File: TheLogtalkHandbook-3.101.0.info,  Node: c45_classifier,  Next: cartesian_products,  Prev: bradley_terry_ranker,  Up: Libraries

6.20 ‘c45_classifier’
=====================

This library implements the C4.5 decision tree learning algorithm.  C4.5
is an extension of the ID3 algorithm that uses information gain ratio
instead of information gain for attribute selection, which avoids bias
towards attributes with many values (see below for implementation
details).

The library implements the ‘classifier_protocol’ defined in the
‘classification_protocols’ library.  It provides predicates for learning
a decision tree from a dataset, optionally prune it, using it to make
predictions, and exporting it as a list of predicate clauses or to a
file.

Datasets are represented as objects implementing the ‘dataset_protocol’
protocol from the ‘classification_protocols’ library.  See ‘test_files’
directory for examples.

* Menu:

* API documentation: API documentation<39>.
* Loading: Loading<40>.
* Testing: Testing<35>.
* Implemented features::
* Learned tree representation::
* Limitations: Limitations<2>.
* References: References<5>.
* Usage: Usage<20>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<39>,  Next: Loading<40>,  Up: c45_classifier

6.20.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#c45_classifier’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<40>,  Next: Testing<35>,  Prev: API documentation<39>,  Up: c45_classifier

6.20.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(c45_classifier(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<35>,  Next: Implemented features,  Prev: Loading<40>,  Up: c45_classifier

6.20.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(c45_classifier(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Implemented features,  Next: Learned tree representation,  Prev: Testing<35>,  Up: c45_classifier

6.20.4 Implemented features
---------------------------

   - Information gain ratio for attribute selection (avoids bias towards
     attributes with many values)

   - Handling of discrete (categorical) attributes with multi-way splits

   - Handling of continuous (numeric) attributes with binary threshold
     splits (selects the threshold with the highest gain ratio from
     midpoints between consecutive sorted values)

   - Handling of missing attribute values (represented using anonymous
     variables): examples with missing values for an attribute are
     distributed to all branches during tree construction; gain ratio
     computation uses only examples with known values for the attribute
     being evaluated; prediction with missing values uses majority
     voting by exploring all possible branches and selecting the most
     common class

   - Tree pruning using pessimistic error pruning (PEP): estimates error
     rates using the upper confidence bound of the binomial distribution
     (Wilson score interval) with a configurable confidence factor
     (default 0.25) and minimum instances per leaf (default 2); replaces
     subtrees with leaf nodes when doing so would not increase the
     estimated error; helps reduce overfitting and improve
     generalization

   - Export of learned decision trees as predicate clauses

   - Pretty-printing of learned decision trees


File: TheLogtalkHandbook-3.101.0.info,  Node: Learned tree representation,  Next: Limitations<2>,  Prev: Implemented features,  Up: c45_classifier

6.20.5 Learned tree representation
----------------------------------

For discrete attributes, the learned decision tree is represented as
‘leaf(Class)’ for leaf nodes and ‘tree(Attribute, Subtrees)’ for
internal nodes with discrete attributes, where ‘Subtrees’ is a list of
‘Value-Subtree’ pairs.

For continuous (numeric) attributes, the tree uses binary threshold
splits represented as ‘tree(Attribute, threshold(Threshold),
LeftSubtree, RightSubtree)’ where ‘LeftSubtree’ corresponds to values
‘=< Threshold’ and ‘RightSubtree’ to values ‘> Threshold’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Limitations<2>,  Next: References<5>,  Prev: Learned tree representation,  Up: c45_classifier

6.20.6 Limitations
------------------

   - No incremental learning (the tree must be rebuilt from scratch when
     new examples are added)


File: TheLogtalkHandbook-3.101.0.info,  Node: References<5>,  Next: Usage<20>,  Prev: Limitations<2>,  Up: c45_classifier

6.20.7 References
-----------------

   - Quinlan, J.R. (1986).  Induction of Decision Trees.  'Machine
     Learning', 1(1), 81-106.  ‘https://doi.org/10.1007/BF00116251’

   - Quinlan, J.R. (1993).  'C4.5: Programs for Machine Learning'.
     Morgan Kaufmann Publishers.
     ‘https://doi.org/10.1016/C2009-0-27846-9’

   - Mitchell, T.M. (1997).  'Machine Learning'.  McGraw-Hill.  Chapter
     3: Decision Tree Learning.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<20>,  Prev: References<5>,  Up: c45_classifier

6.20.8 Usage
------------

To learn a decision tree from a dataset:

     | ?- c45_classifier::learn(play_tennis, Tree).

To prune a learned tree with the default parameters (confidence factor
0.25, minimum instances per leaf 2):

     | ?- c45_classifier::learn(breast_cancer, Tree),
          c45_classifier::prune(breast_cancer, Tree, PrunedTree).

To prune a learned tree with both custom confidence factor and minimum
instances per leaf:

     | ?- c45_classifier::learn(breast_cancer, Tree),
          c45_classifier::prune(breast_cancer, Tree, 0.1, 3, PrunedTree).

To export the tree as a list of predicate clauses:

     | ?- c45_classifier::learn(play_tennis, Tree),
          c45_classifier::tree_to_clauses(play_tennis, Tree, classify, Clauses).

To export the tree to a file:

     | ?- c45_classifier::learn(play_tennis, Tree),
          c45_classifier::tree_to_file(play_tennis, Tree, classify, 'tree.pl').

To print the tree to the current output:

     | ?- c45_classifier::learn(play_tennis, Tree),
          c45_classifier::print_tree(Tree).

To predict the class for a new instance (as a list of attribute-value
pairs):

     | ?- c45_classifier::learn(play_tennis, Tree),
          c45_classifier::predict(Tree, [outlook-sunny, temperature-hot, humidity-high, wind-weak], Class).


File: TheLogtalkHandbook-3.101.0.info,  Node: cartesian_products,  Next: cbor,  Prev: c45_classifier,  Up: Libraries

6.21 ‘cartesian_products’
=========================

This library provides predicates for generating and querying Cartesian
products over lists.  The following categories of predicates are
provided:

   - 'Generation operations' - Predicates for generating Cartesian
     products and tuples.

   - 'Ordering variants' - Predicates that support an additional order
     argument (‘default’ or ‘lexicographic’) for controlling output
     order.

   - 'Distinct-value generation' - Predicates for generating tuples
     while deduplicating repeated values in factor lists.

   - 'Indexed access' - Predicates for direct access to tuples at
     specific positions.

   - 'Lexicographic stepping' - Predicates for navigating tuples in
     lexicographic order.

   - 'Counting operations' - Predicates for counting tuples without
     generating them.

   - 'Random selection' - Predicates for randomly selecting and sampling
     tuples.

Dedicated ‘arrangements’, ‘permutations’, ‘combinations’, ‘multisets’,
‘derangements’, ‘partitions’, and ‘subsequences’ libraries are also
available for focused APIs on related operations.

* Menu:

* API documentation: API documentation<40>.
* Loading: Loading<41>.
* Testing: Testing<36>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<40>,  Next: Loading<41>,  Up: cartesian_products

6.21.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#cartesian_products’ link in a
web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<41>,  Next: Testing<36>,  Prev: API documentation<40>,  Up: cartesian_products

6.21.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(cartesian_products(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<36>,  Prev: Loading<41>,  Up: cartesian_products

6.21.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(cartesian_products(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: cbor,  Next: character_sets,  Prev: cartesian_products,  Up: Libraries

6.22 ‘cbor’
===========

The ‘cbor’ library implements predicates for importing and exporting
data in the Concise Binary Object Representation (CBOR) format:

   - ‘https://www.rfc-editor.org/rfc/rfc8949.html’

   - ‘http://cbor.io/’

This library is a work-in-progress.  Currently it requires a backend
supporting unbounded integer arithmetic.

* Menu:

* Representation::
* Encoding: Encoding<6>.
* Decoding: Decoding<6>.
* API documentation: API documentation<41>.
* Loading: Loading<42>.
* Testing: Testing<37>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Representation,  Next: Encoding<6>,  Up: cbor

6.22.1 Representation
---------------------

   - Maps are represented using curly-bracketed terms, ‘{Pairs}’, where
     each pair uses the representation ‘Key-Value’.

   - Arrays are represented using lists.

   - Byte strings uses ‘bytes(List)’ compound terms.

   - Text strings can be represented as atoms, ‘chars(List)’, or
     ‘codes(List)’.  The default when decoding is to use atoms when
     using the ‘cbor’ object.  To decode text strings into lists of
     chars or code, use the ‘cbor/1’ with the parameter bound to ‘chars’
     or ‘codes’.  For example:

          | ?- cbor::parse([0x65,0x68,0x65,0x6c,0x6c,0x6f], Term).
          Term = hello
          yes

          | ?- cbor(atom)::parse([0x65,0x68,0x65,0x6c,0x6c,0x6f], Term).
          Term = hello
          yes

          | ?- cbor(chars)::parse([0x65,0x68,0x65,0x6c,0x6c,0x6f], Term).
          Term = chars([h,e,l,l,o])
          yes

          | ?- cbor(codes)::parse([0x65,0x68,0x65,0x6c,0x6c,0x6f], Term).
          Term = codes([104,101,108,108,111])
          yes

   - Tagged data uses ‘tag(Tag, Data)’ compound terms.

   - Simple values can be represented using ‘simple(Simple)’ compound
     terms.

   - The CBOR elements ‘false’, ‘true’, ‘null’, and ‘undefined’ are
     represented by, respectively, the ‘@false’, ‘@true’, ‘@null’, and
     ‘@undefined’ compound terms.

   - The compound terms ‘@infinity’, ‘@negative_infinity’, and
     ‘@not_a_number’ are used to represent the corresponding CBOR
     elements.

   - Only some backends distinguish between positive zero and negative
     zero.  The compound terms ‘@zero’ and ‘@negative_zero’ can be used
     as an alternative for encoding.  The decoder, however, produces the
     ‘0.0’ and ‘-0.0’ floats.


File: TheLogtalkHandbook-3.101.0.info,  Node: Encoding<6>,  Next: Decoding<6>,  Prev: Representation,  Up: cbor

6.22.2 Encoding
---------------

Encoding is accomplished using the ‘generate/2’ predicate.  For example:

     | ?- cbor::generate([a,{b-c}], Encoding).
     Encoding = [0x9f,0x61,0x61,0xbf,0x61,0x62,0x61,0x63,0xff,0xff]
     yes

The encoding of arrays and maps uses indefinite-length encoding.  All
floats are currently encoded using decimal fractions.  Encoding
indicators and big floats are not currently supported.


File: TheLogtalkHandbook-3.101.0.info,  Node: Decoding<6>,  Next: API documentation<41>,  Prev: Encoding<6>,  Up: cbor

6.22.3 Decoding
---------------

Decoding is accomplished using the ‘parse/2’ predicate.  For example:

     | ?- cbor::parse([0x9f,0x61,0x61,0xbf,0x61,0x62,0x61,0x63,0xff,0xff], Term).
     Term = [a,{b-c}]
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<41>,  Next: Loading<42>,  Prev: Decoding<6>,  Up: cbor

6.22.4 API documentation
------------------------

Open the ‘../../apis/library_index.html#cbor’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<42>,  Next: Testing<37>,  Prev: API documentation<41>,  Up: cbor

6.22.5 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(cbor(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<37>,  Prev: Loading<42>,  Up: cbor

6.22.6 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(cbor(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: character_sets,  Next: ccsds_frames,  Prev: cbor,  Up: Libraries

6.23 ‘character_sets’
=====================

This library provides a ‘character_set_protocol’ protocol plus concrete
objects for converting between lists of character codes and lists of
bytes.  It also provides metadata predicates ‘preferred_mime_name/1’,
‘name/1’, ‘alias/1’, and ‘mibenum/1’ based on the IANA character set
registry:

‘https://www.iana.org/assignments/character-sets/character-sets.xhtml’

The currently provided objects are:

   - ‘us_ascii’

   - ‘iso_8859_1’

   - ‘iso_8859_2’

   - ‘iso_8859_3’

   - ‘iso_8859_4’

   - ‘iso_8859_9’

   - ‘iso_8859_10’

   - ‘iso_8859_13’

   - ‘iso_8859_14’

   - ‘iso_8859_15’

   - ‘iso_8859_16’

   - ‘windows_1250’

   - ‘windows_1251’

   - ‘windows_1252’

   - ‘windows_1253’

   - ‘windows_1254’

   - ‘windows_1257’

   - ‘utf_8’

   - ‘utf_16le’

   - ‘utf_16be’

   - ‘utf_32le’

   - ‘utf_32be’

Object names are derived from the preferred IANA MIME names by
lowercasing them and replacing hyphens with underscores.  When a
registry entry has no distinct preferred MIME alias, the registered IANA
name is used instead.  A compatibility alias object named ‘utf16be’ is
also provided for ‘utf_16be’.

The Unicode character set objects work with Unicode scalar values and do
not emit or consume a byte order mark (BOM).

This library intentionally does not currently provide ‘Shift_JIS’ or
‘GB18030’ objects because portable mapping tables for those multibyte
encodings are not yet included.

No input validation is performed when converting between character codes
and bytes.  When necessary, use the ‘types’ library validation and
checking predicates before calling the ‘codes_to_bytes/2’ and
‘bytes_to_codes/2’ predicates.

* Menu:

* API documentation: API documentation<42>.
* Loading: Loading<43>.
* Testing: Testing<38>.
* Usage: Usage<21>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<42>,  Next: Loading<43>,  Up: character_sets

6.23.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#character_sets’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<43>,  Next: Testing<38>,  Prev: API documentation<42>,  Up: character_sets

6.23.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(character_sets(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<38>,  Next: Usage<21>,  Prev: Loading<43>,  Up: character_sets

6.23.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(character_sets(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<21>,  Prev: Testing<38>,  Up: character_sets

6.23.4 Usage
------------

The UTF, ISO 8859, and Windows character set objects are grouped in
three main files:

   - ‘utf_character_sets.lgt’

   - ‘iso_8859_character_sets.lgt’

   - ‘windows_character_sets.lgt’

This allows some customization of the character set objects loaded by
your application.  Note that the ‘character_set_protocol.lgt’ and
‘character_sets.lgt’ base files must always be loaded (they include the
‘us_ascii’ character set, which is thus always loaded).


File: TheLogtalkHandbook-3.101.0.info,  Node: ccsds_frames,  Next: ccsds_link_profiles,  Prev: character_sets,  Up: Libraries

6.24 ‘ccsds_frames’
===================

The ‘ccsds_frames’ library provides support for CCSDS transfer frames.
The current implementation includes CCSDS telemetry transfer frames and
CCSDS telecommand transfer frames, plus CCSDS advanced orbiting systems
transfer frames, all using fixed frame lengths and optional
mission-profile fields configured at the object level.

* Menu:

* API documentation: API documentation<43>.
* Loading: Loading<44>.
* Testing: Testing<39>.
* Available entities::
* Representation: Representation<2>.
* Parsing and generating::
* Types::
* Facade helpers::


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<43>,  Next: Loading<44>,  Up: ccsds_frames

6.24.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#ccsds_frames’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<44>,  Next: Testing<39>,  Prev: API documentation<43>,  Up: ccsds_frames

6.24.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(ccsds_frames(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<39>,  Next: Available entities,  Prev: Loading<44>,  Up: ccsds_frames

6.24.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(ccsds_frames(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Available entities,  Next: Representation<2>,  Prev: Testing<39>,  Up: ccsds_frames

6.24.4 Available entities
-------------------------

   - ‘ccsds_frame_protocol’ Common protocol for transfer frame format
     objects.

   - ‘ccsds_frames’ Facade object for introspecting frame terms and
     bridging raw frame data fields with CCSDS space packets.

   - ‘ccsds_tm_frames(FrameLength, SecondaryHeaderLength, HasFECF)’
     Parametric object implementing parsing, generation, and accessors
     for CCSDS telemetry transfer frames.

   - ‘ccsds_tc_frames(FrameLength, SegmentHeaderLength, HasFECF)’
     Parametric object implementing parsing, generation, and accessors
     for CCSDS telecommand transfer frames.

   - ‘ccsds_aos_frames(FrameLength, InsertZoneLength, HasOCF, HasFECF)’
     Parametric object implementing parsing, generation, and accessors
     for CCSDS advanced orbiting systems transfer frames.

   - ‘ccsds_frames_types’ Type definitions for TM, TC, and AOS transfer
     frame byte encodings and terms.


File: TheLogtalkHandbook-3.101.0.info,  Node: Representation<2>,  Next: Parsing and generating,  Prev: Available entities,  Up: ccsds_frames

6.24.5 Representation
---------------------

Telemetry transfer frames are represented using the compound term:

     tm_transfer_frame(
         Version,
         SpacecraftId,
         VirtualChannelId,
         OCFFlag,
         MasterChannelFrameCount,
         VirtualChannelFrameCount,
         SecondaryHeaderFlag,
         SynchronizationFlag,
         PacketOrderFlag,
         SegmentLengthIdentifier,
         FirstHeaderPointer,
         SecondaryHeader,
         DataField,
         OCF,
         FECF
     )

Where:

   - ‘SecondaryHeader’ is either ‘none’ or ‘secondary_header(Bytes)’

   - ‘OCF’ is either ‘none’ or ‘ocf(Bytes)’

   - ‘FECF’ is either ‘none’ or ‘fecf(Bytes)’

Telecommand transfer frames are represented using the compound term:

tc_transfer_frame( Version, BypassFlag, ControlCommandFlag,
SpacecraftId, VirtualChannelId, SequenceNumber, SegmentHeader,
DataField, FECF )

Where:

   - ‘SegmentHeader’ is either ‘none’ or ‘segment_header(Bytes)’

   - ‘FECF’ is either ‘none’ or ‘fecf(Bytes)’

Advanced orbiting systems transfer frames are represented using the
compound term:

aos_transfer_frame( Version, SpacecraftId, VirtualChannelId,
VirtualChannelFrameCount, SignalingField, InsertZone, DataField, OCF,
FECF )

Where:

   - ‘SignalingField’ is ‘signaling_field(ReplayFlag,
     FrameCountUsageFlag, SpacecraftIdExtension, FrameCountCycle)’

   - ‘InsertZone’ is either ‘none’ or ‘insert_zone(Bytes)’

   - ‘OCF’ is either ‘none’ or ‘ocf(Bytes)’

   - ‘FECF’ is either ‘none’ or ‘fecf(Bytes)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Parsing and generating,  Next: Types,  Prev: Representation<2>,  Up: ccsds_frames

6.24.6 Parsing and generating
-----------------------------

To parse a fixed 16-octet telemetry transfer frame without a telemetry
transfer frame secondary header and without a frame error control field:

     | ?- ccsds_tm_frames(16, 0, false)::parse(bytes([0x02, 0xA7, 0x10, 0x20, 0x18, 0x00, 1, 2, 3, 4, 5, 6, 0xDE, 0xAD, 0xBE, 0xEF]), Frames).

To generate the original byte sequence from the parsed term:

     | ?- ccsds_tm_frames(16, 0, false)::generate(bytes(Bytes), Frames).

To parse a fixed 10-octet telecommand transfer frame without a segment
header:

| ?- ccsds_tc_frames(10, 0, true)::parse(bytes([0x20, 0x2A, 0x0C, 0x09,
0x07, 1, 2, 3, 0x44, 0x6D]), Frames).

To generate the original byte sequence from the parsed term:

| ?- ccsds_tc_frames(10, 0, true)::generate(bytes(Bytes), Frames).

When FECF support is enabled for a frame object, parsing verifies the
incoming FECF, ‘valid/1’ checks that it matches the remaining frame
fields, and ‘generate/2-3’ recomputes it from the remaining frame
content.  The parametric frame objects also provide ‘update_fecf/2’ and
‘verify_fecf/1’ for explicit integrity handling:

| ?- ccsds_tc_frames(10, 0, true)::update_fecf(tc_transfer_frame(0, 1,
0, 42, 3, 7, none, [1,2,3], none), Frame).

| ?- ccsds_tc_frames(10, 0, true)::verify_fecf(Frame).

To parse a fixed 12-octet AOS transfer frame without an insert zone,
OCF, or FECF:

| ?- ccsds_aos_frames(12, 0, false, false)::parse(bytes([0x4A, 0x83,
0x12, 0x34, 0x56, 0x80, 1, 2, 3, 4, 5, 6]), Frames).

To generate the original byte sequence from the parsed term:

| ?- ccsds_aos_frames(12, 0, false, false)::generate(bytes(Bytes),
Frames).


File: TheLogtalkHandbook-3.101.0.info,  Node: Types,  Next: Facade helpers,  Prev: Parsing and generating,  Up: ccsds_frames

6.24.7 Types
------------

The ‘ccsds_frames_types’ category defines the following types:

   - ‘ccsds_tm_frame(FrameLength, SecondaryHeaderLength, HasFECF)’ for
     byte encodings

   - ‘ccsds_tm_frame_term(FrameLength, SecondaryHeaderLength, HasFECF)’
     for frame terms

   - ‘ccsds_tc_frame(FrameLength, SegmentHeaderLength, HasFECF)’ for
     byte encodings

   - ‘ccsds_tc_frame_term(FrameLength, SegmentHeaderLength, HasFECF)’
     for frame terms

   - ‘ccsds_aos_frame(FrameLength, InsertZoneLength, HasOCF, HasFECF)’
     for byte encodings

   - ‘ccsds_aos_frame_term(FrameLength, InsertZoneLength, HasOCF,
     HasFECF)’ for frame terms

For example:

     | ?- type::check(ccsds_tm_frame(16, 0, false), [0x02, 0xA7, 0x10, 0x20, 0x18, 0x00, 1, 2, 3, 4, 5, 6, 0xDE, 0xAD, 0xBE, 0xEF]).

     | ?- type::check(ccsds_tm_frame_term(16, 0, false), tm_transfer_frame(0, 42, 3, 1, 16, 32, 0, 0, 0, 3, 0, none, [1,2,3,4,5,6], ocf([0xDE,0xAD,0xBE,0xEF]), none)).

     | ?- type::check(ccsds_tc_frame(10, 0, true), [0x20, 0x2A, 0x0C, 0x09, 0x07, 1, 2, 3, 0x44, 0x6D]).

     | ?- type::check(ccsds_tc_frame_term(10, 0, true), tc_transfer_frame(0, 1, 0, 42, 3, 7, none, [1,2,3], fecf([0x44,0x6D]))).

     | ?- type::check(ccsds_aos_frame(12, 0, false, false), [0x4A, 0x83, 0x12, 0x34, 0x56, 0x80, 1, 2, 3, 4, 5, 6]).

     | ?- type::check(ccsds_aos_frame_term(12, 0, false, false), aos_transfer_frame(1, 42, 3, 0x123456, signaling_field(1, 0, 0, 0), none, [1,2,3,4,5,6], none, none)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Facade helpers,  Prev: Types,  Up: ccsds_frames

6.24.8 Facade helpers
---------------------

The ‘ccsds_frames’ facade object provides generic accessors that work
across TM, TC, and AOS frame terms:

   - ‘frame_type/2’

   - ‘version/2’

   - ‘spacecraft_id/2’

   - ‘virtual_channel_id/2’

   - ‘data_field/2’

   - ‘ocf/2’

   - ‘fecf/2’

   - ‘update_fecf/2’

   - ‘verify_fecf/1’

It also provides raw payload bridge helpers for CCSDS space packets:

   - ‘extract_packets(Frame, SecondaryHeaderLength, Packets)’ parses the
     frame data field bytes using
     ‘ccsds_packets(SecondaryHeaderLength)’.

   - ‘insert_packets(Packets, SecondaryHeaderLength, Frame,
     UpdatedFrame)’ generates packet bytes using
     ‘ccsds_packets(SecondaryHeaderLength)’ and replaces the frame data
     field while leaving the remaining frame fields unchanged.

For example:

     | ?- ccsds_frames::extract_packets(tm_transfer_frame(0, 42, 3, 0, 16, 32, 0, 0, 0, 3, 0, none, [0x08,0x01,0xC0,0x00,0x00,0x03,0xDE,0xAD,0xBE,0xEF], none, none), 0, Packets).

     | ?- ccsds_frames::insert_packets([ccsds_packet(0, 0, 1, 1, 3, 0, none, [0xDE,0xAD,0xBE,0xEF])], 0, tm_transfer_frame(0, 42, 3, 0, 16, 32, 0, 0, 0, 3, 0, none, [], none, none), UpdatedFrame).

| ?- ccsds_frames::update_fecf(tc_transfer_frame(0, 1, 0, 42, 3, 7,
none, [1,2,3], fecf([0x00,0x00])), UpdatedFrame).

| ?- ccsds_frames::verify_fecf(UpdatedFrame).


File: TheLogtalkHandbook-3.101.0.info,  Node: ccsds_link_profiles,  Next: ccsds_packet_services,  Prev: ccsds_frames,  Up: Libraries

6.25 ‘ccsds_link_profiles’
==========================

The ‘ccsds_link_profiles’ library provides an ergonomic wrapper layer
over the existing parametric CCSDS frame objects.

Instead of selecting one of the raw ‘ccsds_tm_frames(...)’,
‘ccsds_tc_frames(...)’, or ‘ccsds_aos_frames(...)’ objects directly at
each call site, callers can work with explicit profile terms and generic
wrapper predicates.

* Menu:

* API documentation: API documentation<44>.
* Loading: Loading<45>.
* Testing: Testing<40>.
* Representation: Representation<3>.
* Public API::
* Parsing and generating: Parsing and generating<2>.
* Packet helpers::


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<44>,  Next: Loading<45>,  Up: ccsds_link_profiles

6.25.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#ccsds_link_profiles’ link in a
web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<45>,  Next: Testing<40>,  Prev: API documentation<44>,  Up: ccsds_link_profiles

6.25.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(ccsds_link_profiles(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<40>,  Next: Representation<3>,  Prev: Loading<45>,  Up: ccsds_link_profiles

6.25.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(ccsds_link_profiles(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Representation<3>,  Next: Public API,  Prev: Testing<40>,  Up: ccsds_link_profiles

6.25.4 Representation
---------------------

Link profiles are represented using the compound terms:

     tm_profile(FrameLength, SecondaryHeaderLength, HasFECF)
     tc_profile(FrameLength, SegmentHeaderLength, HasFECF)
     aos_profile(FrameLength, InsertZoneLength, HasOCF, HasFECF)

Where:

   - ‘FrameLength’ is the fixed frame length in octets

   - ‘SecondaryHeaderLength’, ‘SegmentHeaderLength’, and
     ‘InsertZoneLength’ are the mission-profile field lengths in octets

   - ‘HasOCF’ and ‘HasFECF’ are the atoms ‘true’ or ‘false’


File: TheLogtalkHandbook-3.101.0.info,  Node: Public API,  Next: Parsing and generating<2>,  Prev: Representation<3>,  Up: ccsds_link_profiles

6.25.5 Public API
-----------------

The current implementation provides the predicates:

   - ‘valid_profile/1’

   - ‘parse_frame/3’

   - ‘parse_frames/3’

   - ‘generate_frame/3’

   - ‘generate_frames/3’

   - ‘valid_reassembly_state/1’

   - ‘initial_reassembly_state/1’

   - ‘pending_fragments/2’

   - ‘valid_discontinuity_policy/1’

   - ‘extract_packets/4’

   - ‘insert_packets/5’

   - ‘reassemble_packets/6-8’

   - ‘reassemble_frames/6-8’


File: TheLogtalkHandbook-3.101.0.info,  Node: Parsing and generating<2>,  Next: Packet helpers,  Prev: Public API,  Up: ccsds_link_profiles

6.25.6 Parsing and generating
-----------------------------

To parse exactly one telemetry transfer frame using a profile term:

     | ?- ccsds_link_profiles::parse_frame(bytes([0x02, 0xA7, 0x10, 0x20, 0x18, 0x00, 1, 2, 3, 4, 5, 6, 0xDE, 0xAD, 0xBE, 0xEF]), tm_profile(16, 0, false), Frame).

To generate a telecommand transfer frame using a profile term:

     | ?- ccsds_link_profiles::generate_frame(bytes(Bytes), tc_profile(10, 0, true), tc_transfer_frame(0, 1, 0, 42, 3, 7, none, [1,2,3], fecf([0x44,0x6D]))).

‘parse_frame/3’ expects the source to contain exactly one frame.  If the
source contains zero frames or more than one frame, the predicate throws
a ‘domain_error(ccsds_single_frame_source, Source)’ exception.

Parsing and generation inherit FECF verification and regeneration from
the underlying TM, TC, and AOS frame objects selected by the profile.

To parse or generate multi-frame sources and sinks, use ‘parse_frames/3’
and ‘generate_frames/3’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Packet helpers,  Prev: Parsing and generating<2>,  Up: ccsds_link_profiles

6.25.7 Packet helpers
---------------------

Packet extraction and insertion are provided for TM and AOS profiles
using the high-level packet-zone semantics from ‘ccsds_packet_services’:

     | ?- ccsds_link_profiles::extract_packets(tm_profile(18, 0, false), 0, tm_transfer_frame(0, 42, 3, 0, 16, 32, 0, 0, 0, 3, 2, none, [0xAA,0xBB,0x08,0x01,0xC0,0x00,0x00,0x03,0xDE,0xAD,0xBE,0xEF], none, none), PacketZone).

     | ?- ccsds_link_profiles::insert_packets(aos_profile(20, 0, false, false), 0, packet_zone([0xAA,0xBB], [ccsds_packet(0, 0, 1, 1, 3, 0, none, [0xDE,0xAD,0xBE,0xEF])], []), aos_transfer_frame(1, 42, 3, 0x123456, signaling_field(1, 0, 0, 0), none, [0,0,0,0,0,0,0,0,0,0,0,0,0,0], none, none), UpdatedFrame).

For cross-frame TM and AOS packet reconstruction, initialize a
reassembly state and call the generic profile wrapper predicates:

     | ?- ccsds_link_profiles::initial_reassembly_state(State), ccsds_link_profiles::reassemble_frames(tm_profile(16, 0, false), 0, Frames, resynchronize, State, Packets, UpdatedState).

Telecommand profiles are intentionally rejected by ‘extract_packets/4’
and ‘insert_packets/5’, ‘reassemble_packets/6-8’, and
‘reassemble_frames/6-8’, which throw a
‘domain_error(ccsds_packet_link_profile, tc_profile(...))’ exception.


File: TheLogtalkHandbook-3.101.0.info,  Node: ccsds_packet_services,  Next: ccsds_packetization,  Prev: ccsds_link_profiles,  Up: Libraries

6.26 ‘ccsds_packet_services’
============================

The ‘ccsds_packet_services’ library provides service-aware helpers that
sit above the raw ‘ccsds_packets’ and ‘ccsds_frames’ codec libraries.

The current implementation supports telemetry and advanced orbiting
systems packet-zone handling above the raw ‘ccsds_frames’ payload
bridge:

   - splitting a packet-zone byte sequence using a TM transfer frame
     first header pointer

   - parsing the complete packets that start in that zone

   - preserving any leading continuation bytes and trailing incomplete
     bytes

   - rebuilding a packet zone and reinserting it into a TM transfer
     frame

   - splitting an AOS M_PDU packet-service data field into its
     first-header-pointer header and packet zone

   - representing AOS idle-only packet zones distinctly from AOS
     no-start packet zones using the same ‘packet_zone/3’ term

   - rebuilding an AOS M_PDU packet-service data field and reinserting
     it into an AOS transfer frame

   - carrying trailing packet fragments across multiple TM or AOS frames
     using an explicit packet reassembly state term

   - reassembling complete packets across frame sequences while
     preserving any still-incomplete trailing fragment for the next
     batch

   - tracking TM and AOS reassembly state per frame type, spacecraft
     identifier, and virtual channel identifier

   - detecting dropped or out-of-order TM and AOS frames by checking the
     expected virtual-channel frame counts during reassembly

   - applying configurable discontinuity recovery policies at the frame
     level, choosing between throwing an error, dropping the
     discontinuous frame, or resynchronizing on the current frame

   - returning explicit recovery event streams from the richer frame
     reassembly predicates so callers can observe dropped fragments,
     skipped frames, and resynchronization points

* Menu:

* API documentation: API documentation<45>.
* Loading: Loading<46>.
* Testing: Testing<41>.
* Representation: Representation<4>.
* Packet-zone helpers::
* Telemetry transfer frame helpers::
* Advanced orbiting systems helpers::
* Cross-frame packet reassembly::
* Scope::


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<45>,  Next: Loading<46>,  Up: ccsds_packet_services

6.26.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#ccsds_packet_services’ link in a
web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<46>,  Next: Testing<41>,  Prev: API documentation<45>,  Up: ccsds_packet_services

6.26.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(ccsds_packet_services(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<41>,  Next: Representation<4>,  Prev: Loading<46>,  Up: ccsds_packet_services

6.26.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(ccsds_packet_services(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Representation<4>,  Next: Packet-zone helpers,  Prev: Testing<41>,  Up: ccsds_packet_services

6.26.4 Representation
---------------------

Packet zones are represented using the compound term:

     packet_zone(PrefixData, Packets, SuffixData)

Where:

   - ‘PrefixData’ is a list of bytes preceding the first complete packet

   - ‘Packets’ is a list of complete ‘ccsds_packet(...)’ terms

   - ‘SuffixData’ is a list of bytes trailing the last complete packet

When a telemetry transfer frame first header pointer indicates that no
packet starts in the frame data field, the full data field is
represented as:

     packet_zone(DataField, [], [])

For AOS packet service data fields, the same term is used after decoding
the two-octet M_PDU first header pointer:

   - ‘packet_zone(PrefixData, [], [])’ corresponds to first header
     pointer ‘2047’ and means that no packet starts in this frame packet
     zone

   - ‘packet_zone([], [], SuffixData)’ corresponds to first header
     pointer ‘2046’ and means that the packet zone contains idle data
     only

Cross-frame packet reassembly state is represented using the compound
term:

     packet_reassembly_state(PendingData)

Where ‘PendingData’ is a list of bytes belonging to an incomplete packet
whose header started in an earlier frame and whose remaining bytes are
expected in a later frame.

Frame-channel reassembly state is represented using the compound term:

     channel_reassembly_state(Channels)

Where ‘Channels’ is a list of terms of the form:

     reassembly_channel(FrameType, SpacecraftId, VirtualChannelId, CounterModulus, ExpectedFrameCount, PendingData)

The ‘FrameType’ argument is either ‘tm’ or ‘aos’.  The keyed state is
used by the frame-level reassembly predicates so that interleaved
virtual channels and TM versus AOS streams do not collide.

Discontinuity recovery policies are represented by the atoms:

     throw
     drop
     resynchronize

The policies have the following meaning when a frame-count discontinuity
is detected for a keyed channel:

   - ‘throw’: raise a ‘domain_error/2’ exception and leave recovery to
     the caller

   - ‘drop’: discard any buffered fragment for that keyed channel and
     skip the discontinuous frame payload entirely

   - ‘resynchronize’: discard any buffered fragment for that keyed
     channel but still process the current frame, ignoring any
     pre-pointer continuation bytes

Recovery event streams are returned by the seven-argument TM and AOS
frame reassembly predicates as lists of terms of the form:

     dropped_fragment(FrameType, SpacecraftId, VirtualChannelId, Reason, PendingData)
     skipped_frame(FrameType, SpacecraftId, VirtualChannelId, Discontinuity)
     resynchronized(FrameType, SpacecraftId, VirtualChannelId, Discontinuity)

Where ‘Reason’ is either:

   - ‘discontinuity(StoredCounterModulus, CounterModulus,
     ExpectedFrameCount, VirtualChannelFrameCount)’

   - ‘idle_only(VirtualChannelFrameCount)’ for AOS idle-only M_PDUs that
     clear a buffered fragment


File: TheLogtalkHandbook-3.101.0.info,  Node: Packet-zone helpers,  Next: Telemetry transfer frame helpers,  Prev: Representation<4>,  Up: ccsds_packet_services

6.26.5 Packet-zone helpers
--------------------------

To split a packet zone using a first header pointer and parse the
complete packets that start there:

     | ?- ccsds_packet_services::split_packet_zone([0xAA,0xBB,0x00,0x00,0xC0,0x00,0x00,0x00,0x42,0xCC], 2, 0, PacketZone).

To rebuild a packet zone and recover the corresponding first header
pointer:

     | ?- ccsds_packet_services::join_packet_zone(packet_zone([0xAA,0xBB], [ccsds_packet(0,0,0,0,3,0,none,[0x42])], [0xCC]), 0, Bytes, FirstHeaderPointer).


File: TheLogtalkHandbook-3.101.0.info,  Node: Telemetry transfer frame helpers,  Next: Advanced orbiting systems helpers,  Prev: Packet-zone helpers,  Up: ccsds_packet_services

6.26.6 Telemetry transfer frame helpers
---------------------------------------

To extract a packet zone from a telemetry transfer frame term:

     | ?- ccsds_packet_services::extract_tm_packets(tm_transfer_frame(0, 42, 3, 0, 16, 32, 0, 0, 0, 3, 2, none, [0xAA,0xBB,0x00,0x00,0xC0,0x00,0x00,0x00,0x42,0xCC], none, none), 0, PacketZone).

To update a telemetry transfer frame from a packet zone term:

     | ?- ccsds_packet_services::insert_tm_packets(packet_zone([0xAA,0xBB], [ccsds_packet(0,0,0,0,3,0,none,[0x42])], [0xCC]), 0, tm_transfer_frame(0, 42, 3, 0, 16, 32, 0, 0, 0, 3, 0, none, [], none, none), UpdatedFrame).

If the input TM frame already carries a ‘fecf/1’ term,
‘insert_tm_packets/4’ refreshes it from the updated frame bytes.  Frames
with ‘none’ keep ‘none’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Advanced orbiting systems helpers,  Next: Cross-frame packet reassembly,  Prev: Telemetry transfer frame helpers,  Up: ccsds_packet_services

6.26.7 Advanced orbiting systems helpers
----------------------------------------

To split an AOS M_PDU packet-service data field:

     | ?- ccsds_packet_services::split_aos_packet_zone([0x00,0x02,0xAA,0xBB,0x00,0x00,0xC0,0x00,0x00,0x00,0x42,0xCC], 0, PacketZone).

To rebuild an AOS M_PDU packet-service data field from a packet zone
term:

     | ?- ccsds_packet_services::join_aos_packet_zone(packet_zone([0xAA,0xBB], [ccsds_packet(0,0,0,0,3,0,none,[0x42])], [0xCC]), 0, Bytes).

To extract a packet zone from an AOS transfer frame term:

     | ?- ccsds_packet_services::extract_aos_packets(aos_transfer_frame(1, 42, 3, 16, signaling_field(0,0,0,0), none, [0x00,0x02,0xAA,0xBB,0x00,0x00,0xC0,0x00,0x00,0x00,0x42,0xCC], none, none), 0, PacketZone).

To update an AOS transfer frame from a packet zone term:

     | ?- ccsds_packet_services::insert_aos_packets(packet_zone([0xAA,0xBB], [ccsds_packet(0,0,0,0,3,0,none,[0x42])], [0xCC]), 0, aos_transfer_frame(1, 42, 3, 16, signaling_field(0,0,0,0), none, [], none, none), UpdatedFrame).

If the input AOS frame already carries a ‘fecf/1’ term,
‘insert_aos_packets/4’ refreshes it from the updated frame bytes.
Frames with ‘none’ keep ‘none’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Cross-frame packet reassembly,  Next: Scope,  Prev: Advanced orbiting systems helpers,  Up: ccsds_packet_services

6.26.8 Cross-frame packet reassembly
------------------------------------

To get the initial low-level packet reassembly state:

     | ?- ccsds_packet_services::initial_reassembly_state(State).

To get the initial keyed frame-channel reassembly state:

     | ?- ccsds_packet_services::initial_channel_reassembly_state(State).

To reassemble a packet zone against a prior trailing fragment:

     | ?- ccsds_packet_services::reassemble_packet_zone(packet_zone([0x00,0x00,0x42], [ccsds_packet(0,0,0,0,3,1,none,[0x43])], []), 0, packet_reassembly_state([0x00,0x00,0xC0,0x00]), Packets, UpdatedState).

To reassemble complete packets across a sequence of telemetry transfer
frames:

     | ?- ccsds_packet_services::reassemble_tm_frames([tm_transfer_frame(0, 42, 3, 0, 16, 32, 0, 0, 0, 3, 0, none, [0x00,0x00,0xC0,0x00], none, none), tm_transfer_frame(0, 42, 3, 0, 16, 33, 0, 0, 0, 3, 3, none, [0x00,0x00,0x42,0x00,0x00,0xC0,0x01,0x00,0x00,0x43], none, none)], 0, channel_reassembly_state([]), Packets, UpdatedState).

To reassemble telemetry transfer frames while resynchronizing
automatically on a detected discontinuity:

     | ?- ccsds_packet_services::reassemble_tm_packets(tm_transfer_frame(0, 42, 3, 0, 16, 34, 0, 0, 0, 3, 3, none, [0x00,0x00,0x42,0x00,0x00,0xC0,0x02,0x00,0x00,0x44], none, none), 0, resynchronize, channel_reassembly_state([reassembly_channel(tm,42,3,256,33,[0x00,0x00,0xC0,0x00])]), Packets, UpdatedState).

To reassemble a telemetry transfer frame and also receive explicit
recovery events:

     | ?- ccsds_packet_services::reassemble_tm_packets(tm_transfer_frame(0, 42, 3, 0, 16, 34, 0, 0, 0, 3, 3, none, [0x00,0x00,0x42,0x00,0x00,0xC0,0x02,0x00,0x00,0x44], none, none), 0, resynchronize, channel_reassembly_state([reassembly_channel(tm,42,3,256,33,[0x00,0x00,0xC0,0x00])]), Packets, UpdatedState, Events).

To reassemble complete packets across a sequence of AOS transfer frames:

     | ?- ccsds_packet_services::reassemble_aos_frames([aos_transfer_frame(1, 42, 3, 16, signaling_field(0,0,0,0), none, [0x00,0x00,0x00,0x00,0xC0,0x00], none, none), aos_transfer_frame(1, 42, 3, 17, signaling_field(0,0,0,0), none, [0x00,0x03,0x00,0x00,0x42,0x00,0x00,0xC0,0x01,0x00,0x00,0x43], none, none)], 0, channel_reassembly_state([]), Packets, UpdatedState).

To reassemble AOS transfer frames while dropping a discontinuous frame
and resetting the keyed buffered fragment:

     | ?- ccsds_packet_services::reassemble_aos_packets(aos_transfer_frame(1, 42, 3, 18, signaling_field(0,0,0,0), none, [0x00,0x03,0x00,0x00,0x42,0x00,0x00,0xC0,0x02,0x00,0x00,0x44], none, none), 0, drop, channel_reassembly_state([reassembly_channel(aos,42,3,16777216,17,[0x00,0x00,0xC0,0x00])]), Packets, UpdatedState).

To reassemble AOS transfer frames and receive explicit recovery events
across a frame sequence:

     | ?- ccsds_packet_services::reassemble_aos_frames([aos_transfer_frame(1, 42, 3, 16, signaling_field(0,0,0,0), none, [0x00,0x00,0x00,0x00,0xC0,0x00], none, none), aos_transfer_frame(1, 42, 3, 18, signaling_field(0,0,0,0), none, [0x00,0x03,0x00,0x00,0x42,0x00,0x00,0xC0,0x02,0x00,0x00,0x44], none, none)], 0, drop, channel_reassembly_state([]), Packets, UpdatedState, Events).

To inspect the currently buffered keyed pending fragments:

     | ?- ccsds_packet_services::pending_fragments(channel_reassembly_state([reassembly_channel(tm,42,3,256,33,[0x00,0x00,0xC0,0x00])]), PendingFragments).

For AOS packet service, idle-only M_PDUs clear any pending fragment
state.  This matches the packet-zone interpretation where first header
pointer ‘2046’ denotes idle data rather than continuation bytes.

If a TM or AOS frame arrives with a virtual-channel frame count
different from the keyed state expected count, the frame-level
reassembly predicates apply the selected discontinuity recovery policy.
The five-argument variants default to the ‘throw’ policy.  The
seven-argument variants additionally report the recovery decisions as an
explicit event stream.


File: TheLogtalkHandbook-3.101.0.info,  Node: Scope,  Prev: Cross-frame packet reassembly,  Up: ccsds_packet_services

6.26.9 Scope
------------

This milestone covers TM transfer frame packet zones, AOS packet-service
M_PDUs, low-level packet-fragment stitching, and keyed TM/AOS
cross-frame packet reassembly with continuity checks and configurable
discontinuity recovery.  Future milestones can extend the same library
with segmentation policies, idle packet generation, richer per-channel
recovery controls, and higher level packetization policies.


File: TheLogtalkHandbook-3.101.0.info,  Node: ccsds_packetization,  Next: ccsds_packets,  Prev: ccsds_packet_services,  Up: Libraries

6.27 ‘ccsds_packetization’
==========================

The ‘ccsds_packetization’ library provides the inverse service-layer
helpers to the existing ‘ccsds_packet_services’ library.

The current implementation covers:

   - fitting packet streams into TM and AOS packet-service regions

   - preserving partially emitted packet bytes across frame boundaries

   - tracking queued packets per frame type, spacecraft identifier, and
     virtual channel identifier

   - generating idle packets deliberately when there is remaining frame
     capacity

   - reporting explicit packetization events for buffered fragments and
     generated idle packets

* Menu:

* API documentation: API documentation<46>.
* Loading: Loading<47>.
* Testing: Testing<42>.
* Representation: Representation<5>.
* Packetization::
* Events::
* Idle packets::


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<46>,  Next: Loading<47>,  Up: ccsds_packetization

6.27.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#ccsds_packetization’ link in a
web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<47>,  Next: Testing<42>,  Prev: API documentation<46>,  Up: ccsds_packetization

6.27.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(ccsds_packetization(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<42>,  Next: Representation<5>,  Prev: Loading<47>,  Up: ccsds_packetization

6.27.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(ccsds_packetization(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Representation<5>,  Next: Packetization,  Prev: Testing<42>,  Up: ccsds_packetization

6.27.4 Representation
---------------------

Packetizer state is represented using the compound term:

     packetizer_state(Channels)

Where ‘Channels’ is a list of terms of the form:

     packetizer_channel(FrameType, SpacecraftId, VirtualChannelId, PendingBytes, QueuedPackets)

Where:

   - ‘FrameType’ is either ‘tm’ or ‘aos’

   - ‘SpacecraftId’ is the keyed spacecraft identifier

   - ‘VirtualChannelId’ is the keyed virtual channel identifier

   - ‘PendingBytes’ is a list of packet bytes already started in an
     earlier frame but not yet fully emitted

   - ‘QueuedPackets’ is a list of complete ‘ccsds_packet(...)’ terms
     waiting to be packetized for that keyed channel

Idle packets are generated as telemetry packets using APID ‘2047’,
standalone sequence flags, the requested sequence count, a zero-filled
secondary header of the requested length, and zero-filled user data.


File: TheLogtalkHandbook-3.101.0.info,  Node: Packetization,  Next: Events,  Prev: Representation<5>,  Up: ccsds_packetization

6.27.5 Packetization
--------------------

To get the initial packetizer state:

     | ?- ccsds_packetization::initial_state(State).

To inspect the currently buffered pending bytes and queued packets:

     | ?- ccsds_packetization::pending_packets(packetizer_state([packetizer_channel(tm, 42, 3, [0x22,0x33], [ccsds_packet(0,0,0,1,3,7,none,[0x44])])]), PendingPackets).

To packetize packets into a TM transfer frame:

     | ?- ccsds_packetization::packetize_tm_packets(tm_transfer_frame(0, 42, 3, 0, 16, 32, 0, 0, 0, 3, 2047, none, [0,0,0,0,0,0,0], none, none), 0, packetizer_state([]), [ccsds_packet(0, 0, 0, 0, 3, 0, none, [0x42])], UpdatedFrame, UpdatedState).

When the input TM frame already carries a ‘fecf/1’ term,
‘packetize_tm_packets/6-7’ refresh it from the updated frame bytes.
Frames with ‘none’ keep ‘none’.

To packetize packets into an AOS transfer frame:

     | ?- ccsds_packetization::packetize_aos_packets(aos_transfer_frame(1, 42, 3, 16, signaling_field(0,0,0,0), none, [0,0,0,0,0,0,0,0,0], none, none), 0, packetizer_state([]), [ccsds_packet(0, 0, 0, 0, 3, 0, none, [0x42])], UpdatedFrame, UpdatedState).

When the input AOS frame already carries a ‘fecf/1’ term,
‘packetize_aos_packets/6-7’ refresh it from the updated frame bytes.
Frames with ‘none’ keep ‘none’.

To packetize packets across a sequence of TM transfer frames:

     | ?- ccsds_packetization::packetize_tm_frames([Frame1, Frame2], 0, packetizer_state([]), Packets, UpdatedFrames, RemainingPackets, UpdatedState).


File: TheLogtalkHandbook-3.101.0.info,  Node: Events,  Next: Idle packets,  Prev: Packetization,  Up: ccsds_packetization

6.27.6 Events
-------------

The richer single-frame and multi-frame packetization predicates return
event lists using the terms:

     buffered_packet_fragment(FrameType, SpacecraftId, VirtualChannelId, PendingBytes)
     generated_idle_packet(FrameType, SpacecraftId, VirtualChannelId, Packet)

Where:

   - ‘buffered_packet_fragment/4’ reports trailing packet bytes buffered
     for the next frame

   - ‘generated_idle_packet/4’ reports an idle packet synthesized to
     consume remaining frame capacity


File: TheLogtalkHandbook-3.101.0.info,  Node: Idle packets,  Prev: Events,  Up: ccsds_packetization

6.27.7 Idle packets
-------------------

To generate a telemetry idle packet with APID ‘2047’:

     | ?- ccsds_packetization::generate_idle_packet(0, 7, 2, Packet).


File: TheLogtalkHandbook-3.101.0.info,  Node: ccsds_packets,  Next: ccsds_tc_services,  Prev: ccsds_packetization,  Up: Libraries

6.28 ‘ccsds_packets’
====================

The ‘ccsds_packets’ library implements predicates for parsing and
generating CCSDS (Consultative Committee for Space Data Systems) Space
Packets following the CCSDS 133.0-B-2 standard (Space Packet Protocol):

   - ‘https://public.ccsds.org/Pubs/133x0b2e1.pdf’

   - 
     ‘https://jastoolbox.sandia.gov/topic/communication-specification/jas-packets/ccsds-telecommand-and-telemetry-format-packet-standard/’

* Menu:

* API documentation: API documentation<47>.
* Loading: Loading<48>.
* Testing: Testing<43>.
* Packet Structure::
* Representation: Representation<6>.
* Parsing::
* Generating::
* Accessor Predicates::
* Types and arbitrary generators::


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<47>,  Next: Loading<48>,  Up: ccsds_packets

6.28.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#ccsds_packets’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<48>,  Next: Testing<43>,  Prev: API documentation<47>,  Up: ccsds_packets

6.28.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(ccsds_packets(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<43>,  Next: Packet Structure,  Prev: Loading<48>,  Up: ccsds_packets

6.28.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(ccsds_packets(tester)).

To test the performance of the library parsing predicates, load the
‘tester_performance.lgt’ file:

     | ?- logtalk_load(ccsds_packets(tester_performance)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Packet Structure,  Next: Representation<6>,  Prev: Testing<43>,  Up: ccsds_packets

6.28.4 Packet Structure
-----------------------

A CCSDS Space Packet consists of:

  1. 'Primary Header (6 bytes)':

        - Version Number (3 bits) - Always 000 for Space Packets

        - Packet Type (1 bit) - 0=Telemetry, 1=Telecommand

        - Secondary Header Flag (1 bit) - 0=absent, 1=present

        - Application Process ID (APID) (11 bits) - 0-2047

        - Sequence Flags (2 bits) - 00=continuation, 01=first, 10=last,
          11=standalone

        - Packet Sequence Count (14 bits) - 0-16383

        - Packet Data Length (16 bits) - Number of octets in data field
          minus 1

  2. 'User Data Field' - Variable length payload


File: TheLogtalkHandbook-3.101.0.info,  Node: Representation<6>,  Next: Parsing,  Prev: Packet Structure,  Up: ccsds_packets

6.28.5 Representation
---------------------

Packets are represented using the compound term:

     ccsds_packet(Version, Type, SecHeaderFlag, APID, SeqFlags, SeqCount, SecHeader, UserData)

Where:

   - ‘Version’ is an integer (0-7, typically 0)

   - ‘Type’ is an integer (0=telemetry, 1=telecommand)

   - ‘SecHeaderFlag’ is an integer (0 or 1)

   - ‘APID’ is an integer (0-2047)

   - ‘SeqFlags’ is an integer (0-3)

   - ‘SeqCount’ is an integer (0-16383)

   - ‘SecHeader’ is either ‘none’ or ‘secondary_header(Bytes)’ where
     ‘Bytes’ is a list of bytes

   - ‘UserData’ is a list of bytes

Note that the ‘DataLength’ field from the wire format is not stored in
the term representation as it can be computed from ‘SecHeader’ and
‘UserData’.  The ‘data_length/2’ accessor predicate computes and returns
this value when needed.


File: TheLogtalkHandbook-3.101.0.info,  Node: Parsing,  Next: Generating,  Prev: Representation<6>,  Up: ccsds_packets

6.28.6 Parsing
--------------

The ‘parse/2’ predicate accepts a source term as its first argument.
The source can be ‘file(File)’, ‘stream(Stream)’, or ‘bytes(Bytes)’.
All source types return a list of packets for uniformity.

To parse packets from a list of bytes:

     | ?- ccsds_packets::parse(bytes([0x08, 0x01, 0xC0, 0x00, 0x00, 0x03, 0xDE, 0xAD, 0xBE, 0xEF]), Packets).
     Packets = [ccsds_packet(0, 0, 1, 1, 3, 0, none, [222, 173, 190, 239])]
     yes

To parse packets from a binary file:

     | ?- ccsds_packets::parse(file('telemetry.bin'), Packets).

To parse packets from a binary stream:

     | ?- ccsds_packets::parse(stream(Stream), Packets).

When the packets include a secondary header, the secondary header length
must be known.  In this case, use the
‘ccsds_packets(SecondaryHeaderLength)’ object instead of the
‘ccsds_packets’ object.  For example, to parse packets with a secondary
header of 6 bytes:

     | ?- ccsds_packets(6)::parse(bytes([0x08, 0x01, 0xC0, 0x00, 0x00, 0x07, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0xAA, 0xBB]), Packets).


File: TheLogtalkHandbook-3.101.0.info,  Node: Generating,  Next: Accessor Predicates,  Prev: Parsing,  Up: ccsds_packets

6.28.7 Generating
-----------------

The ‘generate/2’ predicate accepts a sink term as its first argument and
a list of packet terms as the second argument.  The sink can be
‘file(File)’, ‘stream(Stream)’, or ‘bytes(Bytes)’.

To generate bytes from a list of packet terms:

     | ?- ccsds_packets::generate(bytes(Bytes), [ccsds_packet(0, 0, 1, 1, 3, 0, none, [0xDE, 0xAD, 0xBE, 0xEF])]).
     Bytes = [8, 1, 192, 0, 0, 3, 222, 173, 190, 239]
     yes

To write the bytes generated from a list of packet terms to a binary
file:

     | ?- ccsds_packets::generate(file('output.bin'), Packets).

To write the bytes generated from a list of packet terms to a binary
stream:

     | ?- ccsds_packets::generate(stream(Stream), Packets).


File: TheLogtalkHandbook-3.101.0.info,  Node: Accessor Predicates,  Next: Types and arbitrary generators,  Prev: Generating,  Up: ccsds_packets

6.28.8 Accessor Predicates
--------------------------

The library provides convenient accessor predicates for extracting
packet fields:

     | ?- ccsds_packets::apid(Packet, APID).

     % Returns telemetry or telecommand
     | ?- ccsds_packets::type(Packet, Type).

     % Returns continuation, first, last, or standalone
     | ?- ccsds_packets::sequence_flags(Packet, Flags).

     % Returns the secondary header as a list of bytes or none
     | ?- ccsds_packets::secondary_header(Packet, SecHeader).

     % Parses a self-describing secondary-header time field when Descriptor is a variable.
     | ?- ccsds_packets(7)::secondary_header_time(Packet, Descriptor, Time).

     % Parses raw secondary-header T-field bytes using an explicit descriptor term.
     | ?- ccsds_packets(10)::secondary_header_time(Packet, cuc_descriptor(5, 5, ccsds_epoch), Time).

     | ?- ccsds_packets::user_data(Packet, Data).

     % Returns the packet data length (computed from secondary header and user data)
     | ?- ccsds_packets::data_length(Packet, Length).


File: TheLogtalkHandbook-3.101.0.info,  Node: Types and arbitrary generators,  Prev: Accessor Predicates,  Up: ccsds_packets

6.28.9 Types and arbitrary generators
-------------------------------------

The library includes a ‘ccsds_packets_types’ category that provides
‘ccsds_packet’ and ‘ccsds_packet(SecondaryHeaderLength)’ types and
arbitrary generators for CCSDS packets.  For example:

     | ?- type::check(ccsds_packet, Bytes).

     | ?- type::arbitrary(ccsds_packet(42), Bytes).

It also provides a ‘ccsds_packets(N)’ and
‘ccsds_packets(SecondaryHeaderLength, N)’ types for generating a list
with ‘N’ packets.  For example:

     | ?- type::arbitrary(ccsds_packets(10), Bytes).

     | ?- type::check(ccsds_packets(42, 10), Bytes).

For a term representation of a packet, use the ‘ccsds_packet_term’ and
‘ccsds_packet_term(SecondaryHeaderLength)’ types and arbitrary
generators.  For example:

     | ?- type::check(ccsds_packet_term, Packet).

     | ?- type::arbitrary(ccsds_packet_term(42), Packet).


File: TheLogtalkHandbook-3.101.0.info,  Node: ccsds_tc_services,  Next: ccsds_time_codes,  Prev: ccsds_packets,  Up: Libraries

6.29 ‘ccsds_tc_services’
========================

The ‘ccsds_tc_services’ library provides service-aware helpers that sit
above raw ‘ccsds_frames’ telecommand transfer frame terms.

The current implementation covers:

   - extracting telecommand segments from CCSDS telecommand transfer
     frames

   - encoding telecommand segments back into telecommand transfer frames

   - tracking segmented telecommand reassembly state per spacecraft
     identifier and virtual channel identifier

   - keeping pending segmented data separately per MAP identifier inside
     each virtual channel

   - detecting telecommand frame-sequence discontinuities during
     reassembly

   - applying configurable discontinuity recovery policies during
     reassembly

   - returning explicit recovery event streams from the richer frame
     reassembly predicates

   - returning provenance-aware reassembled service-unit terms that
     preserve the ordered per-frame mission-specific segment-header
     suffixes contributing to a complete telecommand service unit

   - grouping complete telecommand service units into MAP-aware dispatch
     buckets so callers can route them by MAP identifier without
     rebuilding that bookkeeping

* Menu:

* API documentation: API documentation<48>.
* Loading: Loading<49>.
* Testing: Testing<44>.
* Representation: Representation<7>.
* Scope: Scope<2>.
* Examples: Examples<166>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<48>,  Next: Loading<49>,  Up: ccsds_tc_services

6.29.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#ccsds_tc_services’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<49>,  Next: Testing<44>,  Prev: API documentation<48>,  Up: ccsds_tc_services

6.29.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(ccsds_tc_services(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<44>,  Next: Representation<7>,  Prev: Loading<49>,  Up: ccsds_tc_services

6.29.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(ccsds_tc_services(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Representation<7>,  Next: Scope<2>,  Prev: Testing<44>,  Up: ccsds_tc_services

6.29.4 Representation
---------------------

Telecommand segments extracted by this library are represented using the
compound term:

     tc_segment(SequenceFlags, MapId, HeaderSuffix, Data)

Where:

   - ‘SequenceFlags’ is one of ‘continuation’, ‘first’, ‘last’, or
     ‘unsegmented’

   - ‘MapId’ is the multiplexer access point identifier in the range
     0-63

   - ‘HeaderSuffix’ is the list of mission-specific segment-header
     octets that follow the standard first octet

   - ‘Data’ is the segment data as a list of bytes

The compact term ‘tc_segment(SequenceFlags, MapId, Data)’ is also
accepted by predicates such as ‘valid_segment/1’ and
‘insert_tc_segment/3’ as shorthand for an empty header suffix.

Reassembled service units that are reconstructed from multiple transfer
frames use the empty list as ‘HeaderSuffix’, as there is no single
mission-specific suffix value that unambiguously represents the merged
result.

When callers need that provenance instead of the compact compatibility
view, the companion reassembly predicates return terms of the form:

     tc_reassembled_segment(MapId, HeaderSuffixes, Data)

Where ‘HeaderSuffixes’ is the ordered list of the per-frame
mission-specific segment-header suffixes that contributed to the
complete service unit.

MAP-aware dispatch helpers group complete telecommand service units into
terms of the form:

     map_dispatch(MapId, ServiceUnits)

Where ‘ServiceUnits’ is a list of complete telecommand service-unit
terms for a single ‘MapId’, preserving the original service-unit order
inside each bucket and the first-seen order of the MAP buckets.

Telecommand reassembly state is represented using the compound term:

     tc_reassembly_state(Channels)

Where ‘Channels’ is a list of terms of the form:

     tc_reassembly_channel(SpacecraftId, VirtualChannelId, ExpectedSequenceNumber, PendingSegments)

The ‘PendingSegments’ list stores the currently buffered segmented data
by MAP identifier using terms of the form:

     tc_pending_segment(MapId, PendingData)

Pending buffered fragments can be queried using ‘pending_fragments/2’,
which returns flattened terms of the form:

     pending_fragment(SpacecraftId, VirtualChannelId, MapId, PendingData)

Discontinuity recovery policies are represented by the atoms:

     throw
     drop
     resynchronize

The policies have the following meaning when a frame sequence
discontinuity is found for a telecommand virtual channel:

   - ‘throw’: raise a ‘domain_error/2’ exception

   - ‘drop’: discard all pending MAP fragments for that virtual channel
     and skip the discontinuous frame payload

   - ‘resynchronize’: discard all pending MAP fragments for that virtual
     channel and still process the current frame payload

Recovery event streams are returned by ‘reassemble_tc_frame/6’ and
‘reassemble_tc_frames/6’ as lists of terms of the form:

     dropped_fragment(SpacecraftId, VirtualChannelId, MapId, Reason, PendingData)
     skipped_frame(SpacecraftId, VirtualChannelId, Discontinuity)
     resynchronized(SpacecraftId, VirtualChannelId, Discontinuity)

Where ‘Discontinuity’ is represented by:

     discontinuity(ExpectedSequenceNumber, SequenceNumber)

Provenance-aware reassembly is provided by the companion predicates
‘reassemble_tc_frame_with_provenance/5-6’ and
‘reassemble_tc_frames_with_provenance/5-6’.

MAP-aware dispatch is provided by ‘dispatch_service_units_by_map/2-3’,
which accept both compact telecommand segment terms and provenance-aware
reassembled telecommand service-unit terms.


File: TheLogtalkHandbook-3.101.0.info,  Node: Scope<2>,  Next: Examples<166>,  Prev: Representation<7>,  Up: ccsds_tc_services

6.29.5 Scope
------------

This first milestone interprets the standard telecommand MAP and
sequence semantics from the first segment-header octet, where the high
two bits encode the sequence flags and the low six bits encode the MAP
identifier.  Transfer frames with longer mission-specific segment
headers are also supported: additional segment-header octets are exposed
in extracted segment terms as the ‘HeaderSuffix’ component and are
preserved when updating frames.


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<166>,  Prev: Scope<2>,  Up: ccsds_tc_services

6.29.6 Examples
---------------

To extract a telecommand segment from a telecommand transfer frame term:

     | ?- ccsds_tc_services::extract_tc_segment(tc_transfer_frame(0, 1, 0, 42, 3, 7, segment_header([0xC5]), [1,2,3], none), Segment).

To update a telecommand transfer frame from a telecommand segment term:

     | ?- ccsds_tc_services::insert_tc_segment(tc_segment(first, 42, [1,2,3]), tc_transfer_frame(0, 1, 0, 42, 3, 7, none, [], none), UpdatedFrame).

To inspect the mission-specific segment-header suffix from an extracted
telecommand segment term:

     | ?- ccsds_tc_services::segment_header_suffix(tc_segment(first, 5, [0xAA,0xBB], [1,2,3]), HeaderSuffix).

Mission-specific segment-header suffix octets are preserved when present
in the input frame term:

     | ?- ccsds_tc_services::insert_tc_segment(tc_segment(first, 42, [1,2,3]), tc_transfer_frame(0, 1, 0, 42, 3, 7, segment_header([0x00,0xAA,0xBB]), [], none), UpdatedFrame).

To reassemble a segmented telecommand service unit across a sequence of
frames:

     | ?- ccsds_tc_services::reassemble_tc_frames([tc_transfer_frame(0, 1, 0, 42, 3, 7, segment_header([0x45]), [1,2], none), tc_transfer_frame(0, 1, 0, 42, 3, 8, segment_header([0x85]), [3,4], none)], tc_reassembly_state([]), Segments, UpdatedState).

To reassemble a segmented telecommand service unit across a sequence of
frames and preserve the ordered per-frame mission-specific header-suffix
provenance:

     | ?- ccsds_tc_services::reassemble_tc_frames_with_provenance([tc_transfer_frame(0, 1, 0, 42, 3, 7, segment_header([0x45,0xAA]), [1,2], none), tc_transfer_frame(0, 1, 0, 42, 3, 8, segment_header([0x85,0xBB]), [3,4], none)], tc_reassembly_state([]), ReassembledSegments, UpdatedState, Events).

To group complete telecommand service units into MAP-aware dispatch
buckets:

     | ?- ccsds_tc_services::dispatch_service_units_by_map([tc_segment(unsegmented, 7, [], [0x01]), tc_reassembled_segment(6, [[0xBB]], [0x03]), tc_reassembled_segment(7, [[0xAA]], [0x02])], Dispatches).

To resynchronize on a discontinuous telecommand frame while receiving
explicit recovery events:

     | ?- ccsds_tc_services::reassemble_tc_frame(tc_transfer_frame(0, 1, 0, 42, 3, 9, segment_header([0xC6]), [9], none), resynchronize, tc_reassembly_state([tc_reassembly_channel(42, 3, 8, [tc_pending_segment(5, [1])])]), Segments, UpdatedState, Events).


File: TheLogtalkHandbook-3.101.0.info,  Node: ccsds_time_codes,  Next: ccsds_time_fields,  Prev: ccsds_tc_services,  Up: Libraries

6.30 ‘ccsds_time_codes’
=======================

The ‘ccsds_time_codes’ library provides support for CCSDS time codes.
The current implementation includes CCSDS Unsegmented Time Code (CUC)
and CCSDS Day Segmented Time Code (CDS), and CCSDS Calendar Segmented
Time Code (CCS), keeping the package small and reusable by the existing
‘ccsds_packets’ packet library and by future frame-level libraries.

* Menu:

* API documentation: API documentation<49>.
* Loading: Loading<50>.
* Testing: Testing<45>.
* Available entities: Available entities<2>.
* Representation: Representation<8>.
* Parsing and generating: Parsing and generating<3>.
* Unix time conversion::
* Types and arbitrary generators: Types and arbitrary generators<2>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<49>,  Next: Loading<50>,  Up: ccsds_time_codes

6.30.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#ccsds_time_codes’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<50>,  Next: Testing<45>,  Prev: API documentation<49>,  Up: ccsds_time_codes

6.30.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(ccsds_time_codes(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<45>,  Next: Available entities<2>,  Prev: Loading<50>,  Up: ccsds_time_codes

6.30.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(ccsds_time_codes(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Available entities<2>,  Next: Representation<8>,  Prev: Testing<45>,  Up: ccsds_time_codes

6.30.4 Available entities
-------------------------

   - ‘ccsds_time_code_protocol’ Common protocol for time code format
     objects.

   - ‘ccsds_time_codes’ Facade object for introspecting time code terms.

   - ‘ccsds_cuc(CoarseOctets, FineOctets, Epoch)’ Parametric object
     implementing parsing, generation, and conversion for CUC time
     codes.

   - ‘ccsds_cds(DaySegmentOctets, SubmillisecondOctets, Epoch)’
     Parametric object implementing parsing, generation, and conversion
     for CDS time codes.

   - ‘ccsds_ccs(CalendarVariant, FractionOctets)’ Parametric object
     implementing parsing, generation, and conversion for CCS time
     codes.

   - ‘ccsds_time_codes_types’ Type definitions and arbitrary generators
     for CUC terms and byte encodings.


File: TheLogtalkHandbook-3.101.0.info,  Node: Representation<8>,  Next: Parsing and generating<3>,  Prev: Available entities<2>,  Up: ccsds_time_codes

6.30.5 Representation
---------------------

CUC values are represented using the compound term:

     cuc_time(Coarse, Fine)

Where:

   - ‘Coarse’ is the integer value stored in the coarse time octets

   - ‘Fine’ is the integer value stored in the fine time octets

The number of octets used for each field is selected by the parametric
object.

CDS values are represented using the compound terms:

     cds_time(Days, Milliseconds)
     cds_time(Days, Milliseconds, Submilliseconds)

Where:

   - ‘Days’ is the integer value stored in the day segment

   - ‘Milliseconds’ is the millisecond-of-day value

   - ‘Submilliseconds’ is the optional submillisecond value when the
     object uses a submillisecond segment; 2-octet objects store
     microseconds and 4-octet objects store picoseconds within the
     millisecond

CCS values are represented using the compound terms:

     ccs_calendar_time(Year, Month, Day, Hour, Minute, Second, Fraction)
     ccs_ordinal_time(Year, DayOfYear, Hour, Minute, Second, Fraction)

Where:

   - ‘Year’ is the four-digit BCD year

   - ‘Month’ and ‘Day’ are used by the ‘calendar’ variant

   - ‘DayOfYear’ is used by the ‘day_of_year’ variant

   - ‘Fraction’ stores the optional BCD fractional digits encoded by the
     object


File: TheLogtalkHandbook-3.101.0.info,  Node: Parsing and generating<3>,  Next: Unix time conversion,  Prev: Representation<8>,  Up: ccsds_time_codes

6.30.6 Parsing and generating
-----------------------------

To parse a 4-octet coarse and 2-octet fine CUC value using the CCSDS
epoch:

     | ?- ccsds_cuc(4, 2, ccsds_epoch)::parse(bytes([0x00, 0x00, 0x01, 0x00, 0x00, 0x80]), TimeCode).
     TimeCode = cuc_time(256, 128)
     yes

To generate the corresponding byte sequence:

     | ?- ccsds_cuc(4, 2, ccsds_epoch)::generate(bytes(Bytes), cuc_time(256, 128)).
     Bytes = [0, 0, 1, 0, 0, 128]
     yes

To parse a 16-bit day-segment CDS value without the optional
submillisecond segment:

     | ?- ccsds_cds(2, 0, ccsds_epoch)::parse(bytes([0x00, 0x01, 0x00, 0x00, 0x07, 0xD0]), TimeCode).
     TimeCode = cds_time(1, 2000)
     yes

To parse a CDS value with a 16-bit submillisecond segment:

     | ?- ccsds_cds(2, 2, unix_epoch)::parse(bytes([0x00, 0x01, 0x00, 0x00, 0x07, 0xD0, 0x01, 0xF4]), TimeCode).
     TimeCode = cds_time(1, 2000, 500)
     yes

To parse a CDS value with a 32-bit submillisecond segment:

     | ?- ccsds_cds(3, 4, unix_epoch)::parse(bytes([0x00, 0x00, 0x01, 0x00, 0x00, 0x07, 0xD0, 0x1D, 0xCD, 0x65, 0x00]), TimeCode).
     TimeCode = cds_time(1, 2000, 500000000)
     yes

To parse a CCS calendar-segmented value without fractional digits:

     | ?- ccsds_ccs(calendar, 0)::parse(bytes([0x20, 0x26, 0x05, 0x08, 0x14, 0x30, 0x45]), TimeCode).
     TimeCode = ccs_calendar_time(2026, 5, 8, 14, 30, 45, 0)
     yes

To parse an ordinal CCS value with one fractional BCD octet:

     | ?- ccsds_ccs(day_of_year, 1)::parse(bytes([0x20, 0x26, 0x01, 0x28, 0x14, 0x30, 0x45, 0x67]), TimeCode).
     TimeCode = ccs_ordinal_time(2026, 128, 14, 30, 45, 67)
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: Unix time conversion,  Next: Types and arbitrary generators<2>,  Prev: Parsing and generating<3>,  Up: ccsds_time_codes

6.30.7 Unix time conversion
---------------------------

To convert a CUC value that uses the Unix epoch into Unix seconds:

     | ?- ccsds_cuc(4, 2, unix_epoch)::unix_seconds(cuc_time(1, 32768), Seconds).
     Seconds = 1.5
     yes

To convert Unix seconds back into a CUC value:

     | ?- ccsds_cuc(4, 2, unix_epoch)::from_unix_seconds(1.5, TimeCode).
     TimeCode = cuc_time(1, 32768)
     yes

To convert a CDS value that uses the Unix epoch into Unix seconds:

     | ?- ccsds_cds(2, 2, unix_epoch)::unix_seconds(cds_time(1, 2000, 500), Seconds).
     Seconds = 86402.0005
     yes

To convert Unix seconds back into a CDS value:

     | ?- ccsds_cds(2, 2, unix_epoch)::from_unix_seconds(86402.0005, TimeCode).
     TimeCode = cds_time(1, 2000, 500)
     yes

To convert a CCS calendar value into Unix seconds:

     | ?- ccsds_ccs(calendar, 0)::unix_seconds(ccs_calendar_time(1970, 1, 1, 0, 0, 0, 0), Seconds).
     Seconds = 0
     yes

To convert Unix seconds back into an ordinal CCS value:

     | ?- ccsds_ccs(day_of_year, 1)::from_unix_seconds(1.5, TimeCode).
     TimeCode = ccs_ordinal_time(1970, 1, 0, 0, 1, 50)
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: Types and arbitrary generators<2>,  Prev: Unix time conversion,  Up: ccsds_time_codes

6.30.8 Types and arbitrary generators
-------------------------------------

The ‘ccsds_time_codes_types’ category defines the following types:

   - ‘ccsds_cuc(CoarseOctets, FineOctets, Epoch)’ for byte encodings

   - ‘ccsds_cuc_time(CoarseOctets, FineOctets)’ for ‘cuc_time/2’ terms

   - ‘ccsds_cds(DaySegmentOctets, SubmillisecondOctets, Epoch)’ for byte
     encodings

   - ‘ccsds_cds_time(DaySegmentOctets, SubmillisecondOctets)’ for CDS
     terms

   - ‘ccsds_ccs(CalendarVariant, FractionOctets)’ for byte encodings

   - ‘ccsds_ccs_time(CalendarVariant, FractionOctets)’ for CCS terms

For example:

     | ?- type::check(ccsds_cuc(4, 2, ccsds_epoch), [0, 0, 1, 0, 0, 128]).

     | ?- type::check(ccsds_cuc_time(4, 2), cuc_time(256, 128)).

     | ?- type::check(ccsds_cds(2, 0, ccsds_epoch), [0, 1, 0, 0, 7, 208]).

     | ?- type::check(ccsds_cds_time(2, 2), cds_time(1, 2000, 500)).

     | ?- type::check(ccsds_ccs(calendar, 0), [0x20, 0x26, 0x05, 0x08, 0x14, 0x30, 0x45]).

     | ?- type::check(ccsds_ccs_time(day_of_year, 1), ccs_ordinal_time(2026, 128, 14, 30, 45, 67)).


File: TheLogtalkHandbook-3.101.0.info,  Node: ccsds_time_fields,  Next: classification_protocols,  Prev: ccsds_time_codes,  Up: Libraries

6.31 ‘ccsds_time_fields’
========================

The ‘ccsds_time_fields’ library adds the self-describing time-field
layer that is missing between raw embedded time bytes and the
format-specific objects in ‘ccsds_time_codes’.

This library covers CCSDS binary P-fields for:

   - CUC time fields using 1 to 7 coarse octets and 0 to 10 fine octets,
     including the two-octet extended P-field encoding

   - CDS time fields using 16-bit or 24-bit day segments and either no
     submillisecond segment, a 16-bit microsecond segment, or a 32-bit
     picosecond segment

   - CCS time fields using either calendar or day-of-year encoding and
     up to 6 BCD fraction octets

* Menu:

* API documentation: API documentation<50>.
* Loading: Loading<51>.
* Testing: Testing<46>.
* Representation: Representation<9>.
* Parsing and generating: Parsing and generating<4>.
* Descriptor helpers::


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<50>,  Next: Loading<51>,  Up: ccsds_time_fields

6.31.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#ccsds_time_fields’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<51>,  Next: Testing<46>,  Prev: API documentation<50>,  Up: ccsds_time_fields

6.31.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(ccsds_time_fields(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<46>,  Next: Representation<9>,  Prev: Loading<51>,  Up: ccsds_time_fields

6.31.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(ccsds_time_fields(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Representation<9>,  Next: Parsing and generating<4>,  Prev: Testing<46>,  Up: ccsds_time_fields

6.31.4 Representation
---------------------

Descriptors are represented using the compound terms:

     cuc_descriptor(CoarseOctets, FineOctets, Epoch)
     cds_descriptor(DaySegmentOctets, SubmillisecondOctets, Epoch)
     ccs_descriptor(CalendarVariant, FractionOctets)

Where:

   - ‘Epoch’ is either ‘ccsds_epoch’ or ‘unix_epoch’

   - ‘CalendarVariant’ is either ‘calendar’ or ‘day_of_year’

This library uses the existing ‘ccsds_time_codes’ objects to parse and
generate the T-field bytes once the descriptor has been decoded.

For the current scope, the agency-defined epoch bit in CUC and CDS
descriptors is mapped to the existing ‘unix_epoch’ atom so callers can
keep using the same time-code objects and terms already provided by
‘ccsds_time_codes’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Parsing and generating<4>,  Next: Descriptor helpers,  Prev: Representation<9>,  Up: ccsds_time_fields

6.31.5 Parsing and generating
-----------------------------

To parse a self-describing CUC time field:

     | ?- ccsds_time_fields::parse(bytes([0x1E, 0x00, 0x00, 0x01, 0x00, 0x00, 0x80]), Descriptor, TimeCode).

To parse a self-describing extended CUC time field:

     | ?- ccsds_time_fields::parse(bytes([0x9F, 0x28, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x80]), Descriptor, TimeCode).

To generate the same time field from a descriptor and a time-code term:

     | ?- ccsds_time_fields::generate(bytes(Bytes), cuc_descriptor(4, 2, ccsds_epoch), cuc_time(256, 128)).

To parse a self-describing CDS time field:

     | ?- ccsds_time_fields::parse(bytes([0x40, 0x00, 0x01, 0x00, 0x00, 0x07, 0xD0]), Descriptor, TimeCode).

To parse a self-describing CDS time field with a 32-bit submillisecond
segment:

     | ?- ccsds_time_fields::parse(bytes([0x4E, 0x00, 0x00, 0x01, 0x00, 0x00, 0x07, 0xD0, 0x1D, 0xCD, 0x65, 0x00]), Descriptor, TimeCode).

To generate a self-describing CCS day-of-year time field:

     | ?- ccsds_time_fields::generate(bytes(Bytes), ccs_descriptor(day_of_year, 1), ccs_ordinal_time(2026, 128, 14, 30, 45, 67)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Descriptor helpers,  Prev: Parsing and generating<4>,  Up: ccsds_time_fields

6.31.6 Descriptor helpers
-------------------------

The library also provides helper predicates for descriptor
introspection:

   - ‘valid_descriptor/1’

   - ‘format/2’

   - ‘epoch/2’

For example:

     | ?- ccsds_time_fields::format(cds_descriptor(3, 4, unix_epoch), Format).

     | ?- ccsds_time_fields::epoch(ccs_descriptor(calendar, 1), Epoch).


File: TheLogtalkHandbook-3.101.0.info,  Node: classification_protocols,  Next: clo_span_pattern_miner,  Prev: ccsds_time_fields,  Up: Libraries

6.32 ‘classification_protocols’
===============================

This library provides protocols used in the implementation of machine
learning classifier algorithms.  Datasets are represented as objects
implementing the ‘dataset_protocol’ protocol.  Classifiers are
represented as objects implementing the ‘classifier_protocol’ protocol.

This library also provides reusable shared categories, smoke tests, and
test datasets.  See below for details.

Logtalk currently provides several classifiers including
‘c45_classifier’, ‘knn_classifier’, ‘linear_svm_classifier’,
‘logistic_regression_classifier’, ‘naive_bayes_classifier’,
‘nearest_centroid_classifier’, and ‘random_forest_classifier’.  See
these libraries documentation for details.

* Menu:

* Shared category::
* Diagnostics: Diagnostics<2>.
* Export header format: Export header format<2>.
* API documentation: API documentation<51>.
* Loading: Loading<52>.
* Testing: Testing<47>.
* Test datasets: Test datasets<2>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Shared category,  Next: Diagnostics<2>,  Up: classification_protocols

6.32.1 Shared category
----------------------

The library includes one reusable category intended to be imported by
classifier algorithm implementations:

   - ‘classifier_common’ — shared diagnostics accessors and classifier
     export helpers.

This category keeps diagnostics access and file export behavior separate
from the algorithm-specific learning, prediction, and pretty-printing
code.


File: TheLogtalkHandbook-3.101.0.info,  Node: Diagnostics<2>,  Next: Export header format<2>,  Prev: Shared category,  Up: classification_protocols

6.32.2 Diagnostics
------------------

The ‘classifier_common’ category provides shared accessor predicates
such as ‘diagnostics/2’, ‘diagnostic/2’, and ‘classifier_options/2’.
These predicates make it possible to inspect learned-classifier metadata
without depending on the exact term representation used by a particular
classifier implementation.

The detailed contents of the diagnostics data are classifier-dependent.
For example, some classifiers report effective training options, while
others report structural metadata such as attribute names, feature
types, or the number of training examples or models.


File: TheLogtalkHandbook-3.101.0.info,  Node: Export header format<2>,  Next: API documentation<51>,  Prev: Diagnostics<2>,  Up: classification_protocols

6.32.3 Export header format
---------------------------

The shared classifier exporter in the ‘classifier_common’ category
writes a header before the exported clauses in the following format:

     % exported classifier predicate: Functor/Arity
     % training dataset: Dataset
     % dataset prediction schema: Functor(Attribute1, ..., AttributeN, Class)
     % diagnostics: Diagnostics
     % Functor(Classifier)
     Functor(Classifier)

The ‘dataset prediction schema’ line always uses an ASCII-only title
case conversion for the attribute names and class.  This line documents
the dataset-level prediction interface for readability, even when the
exported clauses serialize a model term instead of an executable
predictor relation.

When exporting a serialized classifier term, using a noun such as
‘classifier/1’ or ‘model/1’ is recommended.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<51>,  Next: Loading<52>,  Prev: Export header format<2>,  Up: classification_protocols

6.32.4 API documentation
------------------------

Open the ‘../../apis/library_index.html#classification_protocols’ link
in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<52>,  Next: Testing<47>,  Prev: API documentation<51>,  Up: classification_protocols

6.32.5 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

| ?- logtalk_load(classification_protocols(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<47>,  Next: Test datasets<2>,  Prev: Loading<52>,  Up: classification_protocols

6.32.6 Testing
--------------

To test this library predicates, shared categories, and datasets, load
the ‘tester.lgt’ file:

| ?- logtalk_load(classification_protocols(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Test datasets<2>,  Prev: Testing<47>,  Up: classification_protocols

6.32.7 Test datasets
--------------------

Several sample datasets are included in the ‘test_datasets’ directory:

   - ‘play_tennis.lgt’ — The classic weather/tennis dataset with 14
     examples and 4 discrete attributes (outlook, temperature, humidity,
     wind).  Originally from Quinlan (1986) and widely used in machine
     learning textbooks including Mitchell (1997).  Also available from
     the UCI Machine Learning Repository:
     ‘https://archive.ics.uci.edu/dataset/349/tennis+major+tournament+match+statistics’

   - ‘contact_lenses.lgt’ — A dataset with 24 examples and 4 discrete
     attributes (age, spectacle prescription, astigmatism, tear
     production rate) for deciding the type of contact lenses to
     prescribe.  Originally from Cendrowska, J. (1987).  PRISM: An
     algorithm for inducing modular rules.  'International Journal of
     Man-Machine Studies', 27(4), 349-370.  Available from the UCI
     Machine Learning Repository:
     ‘https://archive.ics.uci.edu/dataset/58/lenses’

   - ‘iris.lgt’ — The classic Iris flower dataset with 150 examples and
     4 continuous attributes (sepal length, sepal width, petal length,
     petal width) for classifying iris species (setosa, versicolor,
     virginica).  Originally from Fisher, R.A. (1936).  The use of
     multiple measurements in taxonomic problems.  'Annals of Eugenics',
     7(2), 179-188.  Available from the UCI Machine Learning Repository:
     ‘https://archive.ics.uci.edu/dataset/53/iris’

   - ‘breast_cancer.lgt’ — A dataset with 286 examples and 9 discrete
     attributes (age, menopause, tumor size, inv-nodes, node-caps,
     degree of malignancy, breast, breast quadrant, irradiation) for
     predicting breast cancer recurrence events.  Contains missing
     values (9 examples with missing values in the node-caps and
     breast-quad attributes, represented using anonymous variables).
     Originally from the Institute of Oncology, University Medical
     Centre, Ljubljana, Yugoslavia.  Donors: Ming Tan and Jeff
     Schlimmer.  Available from the UCI Machine Learning Repository:
     ‘https://archive.ics.uci.edu/dataset/14/breast+cancer’


File: TheLogtalkHandbook-3.101.0.info,  Node: clo_span_pattern_miner,  Next: clustering_protocols,  Prev: classification_protocols,  Up: Libraries

6.33 ‘clo_span_pattern_miner’
=============================

CloSpan closed sequential pattern miner for sequence datasets.  The
library depends on the ‘sequential_pattern_mining_protocols’ support
library, implements the generic ‘pattern_miner_protocol’ defined in the
‘pattern_mining_protocols’ core library, and mines closed frequent
sequential patterns directly using closure-aware projected-database
search with explicit projected-database-equivalence backward pruning
that skips equivalent branches before recursion, together with a
same-support closed frontier that merges branch results during the
search without a final post-filter.

Requires a dataset implementing ‘sequence_dataset_protocol’ with
sequences represented as ordered lists of canonical sorted itemsets over
a declared item domain.

* Menu:

* API documentation: API documentation<52>.
* Loading: Loading<53>.
* Testing: Testing<48>.
* Features: Features<9>.
* Options: Options<9>.
* Pattern miner representation: Pattern miner representation<2>.
* References: References<6>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<52>,  Next: Loading<53>,  Up: clo_span_pattern_miner

6.33.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#clo_span_pattern_miner’ link in
a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<53>,  Next: Testing<48>,  Prev: API documentation<52>,  Up: clo_span_pattern_miner

6.33.2 Loading
--------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(clo_span_pattern_miner(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<48>,  Next: Features<9>,  Prev: Loading<53>,  Up: clo_span_pattern_miner

6.33.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(clo_span_pattern_miner(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<9>,  Next: Options<9>,  Prev: Testing<48>,  Up: clo_span_pattern_miner

6.33.4 Features
---------------

   - 'Closed Pattern Mining': Retains only frequent sequential patterns
     that have no superpattern with the same support.

   - 'Backward and Closure Pruning': Uses projected-database equivalence
     to skip equivalent backward-growth branches before recursion, then
     maintains a same-support closed frontier to suppress dominated
     patterns during the search instead of post-filtering another miner
     output.

   - 'Canonical Sequences': Uses the shared sequential validation logic
     from the support library.

   - 'Flexible Support Thresholds': Supports relative minimum support
     and absolute minimum support count.  When both are given, the
     absolute-count threshold takes precedence.

   - 'Model Export': Closed pattern collections can be exported as
     predicate clauses or written to a file.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<9>,  Next: Pattern miner representation<2>,  Prev: Features<9>,  Up: clo_span_pattern_miner

6.33.5 Options
--------------

The ‘mine/3’ predicate accepts the following options:

   - ‘minimum_support/1’: Relative minimum support threshold in the
     interval ‘]0.0, 1.0]’.  The default is ‘0.5’.

   - ‘minimum_support_count/1’: Absolute minimum support count.  When
     both support options are provided, this option takes precedence.

   - ‘maximum_pattern_length/1’: Maximum total number of items in a
     mined sequential pattern.  The default is ‘1000’, effectively
     capped by the longest sequence in the dataset.

   - ‘minimum_pattern_length/1’: Minimum total number of items retained
     in the mined result.  The default is ‘1’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Pattern miner representation<2>,  Next: References<6>,  Prev: Options<9>,  Up: clo_span_pattern_miner

6.33.6 Pattern miner representation
-----------------------------------

The mined pattern miner result is represented by a compound term with
the functor chosen by the implementation and arity 3.  For example:

     clo_span_pattern_miner(ItemDomain, Patterns, Options)

Where:

   - ‘ItemDomain’: Canonical sorted list of declared dataset items.

   - ‘Patterns’: List of ‘sequence_pattern(Pattern, SupportCount)’ terms
     ordered first by total item count and then lexicographically.

   - ‘Options’: Effective mining options used to mine the closed
     sequential patterns.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<6>,  Prev: Pattern miner representation<2>,  Up: clo_span_pattern_miner

6.33.7 References
-----------------

  1. Yan, X., Han, J., and Afshar, R. (2003) - “CloSpan: Mining closed
     sequential patterns in large datasets”.


File: TheLogtalkHandbook-3.101.0.info,  Node: clustering_protocols,  Next: colley_ranker,  Prev: clo_span_pattern_miner,  Up: Libraries

6.34 ‘clustering_protocols’
===========================

This library provides protocols used in the implementation of machine
learning clustering algorithms.  Datasets are represented as objects
implementing the ‘clustering_dataset_protocol’ protocol.  Clusterers are
represented as objects implementing the ‘clusterer_protocol’ protocol.

This library also provides test datasets and a small smoke-test suite.
The shared test suite also includes cross-library comparison tests for
clusterers that implement the same protocols, allowing common datasets
and validation failures to be checked in one place.

Concrete clustering algorithms are intentionally out of scope for this
package.  The goal is to provide a portable foundation for future
libraries such as ‘kmeans_clusterer’.

* Menu:

* API documentation: API documentation<53>.
* Loading: Loading<54>.
* Testing: Testing<49>.
* Test datasets: Test datasets<3>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<53>,  Next: Loading<54>,  Up: clustering_protocols

6.34.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#clustering_protocols’ link in a
web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<54>,  Next: Testing<49>,  Prev: API documentation<53>,  Up: clustering_protocols

6.34.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(clustering_protocols(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<49>,  Next: Test datasets<3>,  Prev: Loading<54>,  Up: clustering_protocols

6.34.3 Testing
--------------

To run the library smoke tests and shared comparison tests, load the
‘tester.lgt’ file:

     | ?- logtalk_load(clustering_protocols(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Test datasets<3>,  Prev: Testing<49>,  Up: clustering_protocols

6.34.4 Test datasets
--------------------

Several sample datasets are included in the ‘test_datasets’ directory:

   - ‘all_noise.lgt’ — A synthetic 2D continuous dataset with 4 examples
     and 2 continuous attributes (‘x’, ‘y’).  The examples are well
     separated, making the dataset useful for all-noise tests where a
     density-based clusterer should reject every point under a small
     epsilon radius.

   - ‘bridge_noise.lgt’ — A synthetic 2D continuous dataset with 10
     examples and 2 continuous attributes (‘x’, ‘y’).  The examples form
     two dense blobs connected by two sparse bridge points, making the
     dataset suitable for testing density-based algorithms that should
     keep the blobs separate while treating the bridge as noise.

   - ‘dead_component_blobs.lgt’ — A synthetic 2D continuous dataset with
     6 examples and 2 continuous attributes (‘x’, ‘y’).  The examples
     form two tiny ordered blobs sized so an over-specified Gaussian
     mixture with ‘first_k’ initialization can drive one component fully
     dead, making the dataset useful for dead-component policy
     regression tests.

   - ‘duplicate_points.lgt’ — A synthetic 2D continuous dataset with 6
     examples and 2 continuous attributes (‘x’, ‘y’).  The examples
     include repeated coordinates forming a dense local cluster plus one
     isolated outlier, making the dataset useful for duplicate-point and
     density-threshold tests.

   - ‘imbalanced_three_modes.lgt’ — A synthetic 2D continuous dataset
     with 9 examples and 2 continuous attributes (‘x’, ‘y’).  The
     examples form one dense blob plus two much sparser distant modes,
     making the dataset useful for imbalanced-cluster and Gaussian
     mixture stress tests.

   - ‘iris_unlabeled.lgt’ — A compact Iris-derived dataset with 9
     examples and 4 continuous attributes (‘sepal_length’,
     ‘sepal_width’, ‘petal_length’, ‘petal_width’).  It is derived from
     the classic Iris dataset but intentionally omits species labels so
     it can be used with unsupervised algorithms.

   - ‘large_two_blobs.lgt’ — A synthetic 2D continuous dataset with 100
     examples and 2 continuous attributes (‘x’, ‘y’).  The examples form
     two dense 5x10 grids that are well separated, making the dataset
     useful for performance benchmarks that need a larger deterministic
     density-based clustering workload than the small smoke-test
     datasets.

   - ‘mixed_profiles.lgt’ — A mixed-feature dataset with 6 examples, 2
     continuous attributes (‘age’, ‘income’), and 2 discrete attributes
     (‘channel’, ‘region’).  This dataset is intended for clustering
     algorithms that support both numeric and categorical features.

   - ‘scaling_bands.lgt’ — A synthetic 2D continuous dataset with 6
     examples and 2 continuous attributes (‘x’, ‘y’).  The examples form
     two horizontal bands with large variation along ‘x’, making the
     dataset useful for tests that compare clustering behavior with
     feature scaling turned on versus off.

   - ‘shopping_profiles.lgt’ — A categorical dataset with 6 examples and
     4 discrete attributes (‘channel’, ‘region’, ‘loyalty’, ‘device’).
     The examples form two clear shopping-profile segments suitable for
     categorical clustering smoke tests.

   - ‘single_blob.lgt’ — A synthetic 2D continuous dataset with 6
     examples and 2 continuous attributes (‘x’, ‘y’).  The examples form
     a single compact blob suitable for one-cluster smoke tests.

   - ‘two_blobs.lgt’ — A synthetic 2D continuous dataset with 8 examples
     and 2 continuous attributes (‘x’, ‘y’).  The examples form two
     compact, well-separated blobs suitable for deterministic clustering
     smoke tests.


File: TheLogtalkHandbook-3.101.0.info,  Node: colley_ranker,  Next: combinations,  Prev: clustering_protocols,  Up: Libraries

6.35 ‘colley_ranker’
====================

Colley pairwise preference ranker.

The library implements the ‘ranker_protocol’ defined in the
‘ranking_protocols’ library.  It provides predicates for learning a
ranker from pairwise preferences, using it to order candidate items, and
exporting it as a list of predicate clauses or to a file.

Datasets are represented as objects implementing the
‘pairwise_ranking_dataset_protocol’ protocol from the
‘ranking_protocols’ library.  See the ‘test_datasets’ directory for
examples.  Requires well-formed connected pairwise datasets so that the
learned rankings remain globally comparable across all ranked items.

* Menu:

* API documentation: API documentation<54>.
* Loading: Loading<55>.
* Testing: Testing<50>.
* Features: Features<10>.
* Scoring semantics: Scoring semantics<2>.
* Usage: Usage<22>.
* Diagnostics syntax: Diagnostics syntax<4>.
* Ranker representation: Ranker representation<3>.
* References: References<7>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<54>,  Next: Loading<55>,  Up: colley_ranker

6.35.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#colley_ranker’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<55>,  Next: Testing<50>,  Prev: API documentation<54>,  Up: colley_ranker

6.35.2 Loading
--------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(colley_ranker(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<50>,  Next: Features<10>,  Prev: Loading<55>,  Up: colley_ranker

6.35.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(colley_ranker(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<10>,  Next: Scoring semantics<2>,  Prev: Testing<50>,  Up: colley_ranker

6.35.4 Features
---------------

   - 'Pairwise Preference Learning': Learns one deterministic rating per
     item from aggregated pairwise outcomes.

   - 'Colley Matrix Fidelity': Solves the standard Colley linear system
     with diagonal regularization ‘2 + games_i’ and off-diagonal entries
     ‘-games_ij’.

   - 'Numerically Hardened Solver': Uses Gaussian elimination with
     partial pivoting plus residual checks before accepting the learned
     ratings.

   - 'Conservative Ratings': Produces ratings in the interval ‘[0,1]’
     with the neutral prior centered at ‘0.5’.

   - 'Deterministic Ranking': Orders candidate items by learned rating
     with deterministic tie-breaking.

   - 'Strict Dataset Validation': Rejects duplicate items, undeclared
     items, self-preferences, non-positive weights, and disconnected
     comparison graphs.

   - 'Ranker Export': Learned rankers can be exported as self-contained
     terms.

   - 'Shared Ranking Infrastructure': Reuses the ‘ranking_protocols’
     helpers for dataset validation, diagnostics, export, and candidate
     ranking.


File: TheLogtalkHandbook-3.101.0.info,  Node: Scoring semantics<2>,  Next: Usage<22>,  Prev: Features<10>,  Up: colley_ranker

6.35.5 Scoring semantics
------------------------

This implementation aggregates pairwise preferences into matchup totals
and then solves the Colley system

     C r = b

where ‘C_ii = 2 + games_i’, ‘C_ij = -games_ij’ for ‘i \= j’, and ‘b_i =
1 + (wins_i - losses_i) / 2’.

The linear system is solved using deterministic Gaussian elimination
with partial pivoting.  The implementation also verifies that the
recovered solution has a small residual and only clamps negligible
floating-point boundary noise at ‘0.0’ or ‘1.0’; materially invalid
out-of-range values are rejected instead of being silently accepted.

The resulting ratings remain close to ‘0.5’ when evidence is weak and
move toward ‘1.0’ or ‘0.0’ only when repeated pairwise results justify
doing so.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<22>,  Next: Diagnostics syntax<4>,  Prev: Scoring semantics<2>,  Up: colley_ranker

6.35.6 Usage
------------

* Menu:

* Learning a ranker: Learning a ranker<3>.
* Inspecting diagnostics: Inspecting diagnostics<3>.
* Ranking candidate items: Ranking candidate items<3>.
* Exporting the ranker: Exporting the ranker<3>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Learning a ranker<3>,  Next: Inspecting diagnostics<3>,  Up: Usage<22>

6.35.6.1 Learning a ranker
..........................

     % Learn from a pairwise ranking dataset object
     | ?- colley_ranker::learn(my_dataset, Ranker).
     ...

     % Learn with an explicit empty options list
     | ?- colley_ranker::learn(my_dataset, Ranker, []).
     ...

The current implementation accepts only the empty options list ‘[]’.
Any non-empty options list is rejected.


File: TheLogtalkHandbook-3.101.0.info,  Node: Inspecting diagnostics<3>,  Next: Ranking candidate items<3>,  Prev: Learning a ranker<3>,  Up: Usage<22>

6.35.6.2 Inspecting diagnostics
...............................

     % Inspect model and dataset summary metadata
     | ?- colley_ranker::learn(my_dataset, Ranker),
          colley_ranker::diagnostics(Ranker, Diagnostics).
     Diagnostics = [...]
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Ranking candidate items<3>,  Next: Exporting the ranker<3>,  Prev: Inspecting diagnostics<3>,  Up: Usage<22>

6.35.6.3 Ranking candidate items
................................

     % Rank a candidate set from most preferred to least preferred
     | ?- colley_ranker::learn(my_dataset, Ranker),
          colley_ranker::rank(Ranker, [item_a, item_b, item_c], Ranking).
     Ranking = [...]
     ...

Candidate lists must be proper lists of unique, ground items declared by
the training dataset.  Invalid ranker terms, duplicate candidates, and
candidates containing variables are rejected with errors instead of
being silently accepted.


File: TheLogtalkHandbook-3.101.0.info,  Node: Exporting the ranker<3>,  Prev: Ranking candidate items<3>,  Up: Usage<22>

6.35.6.4 Exporting the ranker
.............................

Learned rankers can be exported as a list of clauses or to a file for
later use.

     % Export as predicate clauses
     | ?- colley_ranker::learn(my_dataset, Ranker),
          colley_ranker::export_to_clauses(my_dataset, Ranker, my_ranker, Clauses).
     Clauses = [my_ranker(colley_ranker(...))]
     ...

     % Export to a file
     | ?- colley_ranker::learn(my_dataset, Ranker),
          colley_ranker::export_to_file(my_dataset, Ranker, my_ranker, 'ranker.pl').
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Diagnostics syntax<4>,  Next: Ranker representation<3>,  Prev: Usage<22>,  Up: colley_ranker

6.35.7 Diagnostics syntax
-------------------------

The ‘diagnostics/2’ predicate returns a list of metadata terms with the
form:

     [
         model(colley_ranker),
         options(Options),
         dataset_summary(DatasetSummary)
     ]


File: TheLogtalkHandbook-3.101.0.info,  Node: Ranker representation<3>,  Next: References<7>,  Prev: Diagnostics syntax<4>,  Up: colley_ranker

6.35.8 Ranker representation
----------------------------

The learned ranker is represented by a compound term of the form:

     colley_ranker(Items, Ratings, Diagnostics)

Where:

   - ‘Items’: List of ranked items.

   - ‘Scores’: List of ‘Item-Rating’ pairs.

   - ‘Diagnostics’: List of metadata terms, including the effective
     options and dataset summary.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<7>,  Prev: Ranker representation<3>,  Up: colley_ranker

6.35.9 References
-----------------

  1. Colley, W. N. (2002).  'Colley’s bias free college football ranking
     method: The Colley Matrix explained'.


File: TheLogtalkHandbook-3.101.0.info,  Node: combinations,  Next: command_line_options,  Prev: colley_ranker,  Up: Libraries

6.36 ‘combinations’
===================

This library provides predicates for generating and querying
combinations over lists.  The following categories of predicates are
provided:

   - 'Generation operations' - Predicates for generating combinations.

   - 'Ordering variants' - Predicates that support an additional order
     argument (‘default’, ‘lexicographic’, or ‘shortlex’) for
     controlling output order.

   - 'Distinct-value generation' - Predicates for generating
     combinations while deduplicating equal-valued results.

   - 'Indexed access' - Predicates for direct access to combinations at
     specific positions, including distinct combinations.

   - 'Counting operations' - Predicates for counting combinations and
     distinct combinations.

   - 'Random selection' - Predicates for randomly selecting and sampling
     combinations and distinct combinations.

   - 'Stepping operations' - Predicates for moving to the next or
     previous combination in lexicographic order.

Dedicated ‘arrangements’, ‘cartesian_products’, ‘multisets’,
‘permutations’, ‘derangements’, ‘partitions’, and ‘subsequences’
libraries are also available for focused APIs on related operations.
The ‘multisets’ library is the repetition-allowed counterpart to this
library.

* Menu:

* API documentation: API documentation<55>.
* Loading: Loading<56>.
* Testing: Testing<51>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<55>,  Next: Loading<56>,  Up: combinations

6.36.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#combinations’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<56>,  Next: Testing<51>,  Prev: API documentation<55>,  Up: combinations

6.36.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(combinations(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<51>,  Prev: Loading<56>,  Up: combinations

6.36.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(combinations(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: command_line_options,  Next: core,  Prev: combinations,  Up: Libraries

6.37 ‘command_line_options’
===========================

This library provides command-line parsing predicates where command-line
options are defined as objects that import the ‘command_line_option’
category.  Predicates are also provided for generating help text.

Parsed options are returned by default as a list of ‘Name(Value)’ terms.
A parser option, ‘output_functor(Functor)’, allows returning options as
‘Functor(Key, Value)’ terms instead.

Adapted with significant changes from the SWI-Prolog ‘optparse’ library
by Marcus Uneson.  Most documentation, parsing options, and help options
retained from the original library.  Command line options specification
changed to an object-based representation.  Parsing simplified, no
longer using DCGs.  Comprehensive set of tests added, based on
documentation examples.  Full portability to all supported backends.

* Menu:

* API documentation: API documentation<56>.
* Loading: Loading<57>.
* Testing: Testing<52>.
* Terminology::
* Defining option objects::
* Validating option definitions::
* Example option objects::
* Parsing command-line arguments::
* Generating help text::
* Help options::
* Parse options::
* Notes and tips::


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<56>,  Next: Loading<57>,  Up: command_line_options

6.37.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#command_line_options’ file in a
web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<57>,  Next: Testing<52>,  Prev: API documentation<56>,  Up: command_line_options

6.37.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ utility
file:

     | ?- logtalk_load(command_line_options(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<52>,  Next: Terminology,  Prev: Loading<57>,  Up: command_line_options

6.37.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(command_line_options(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Terminology,  Next: Defining option objects,  Prev: Testing<52>,  Up: command_line_options

6.37.4 Terminology
------------------

The terminology is partly borrowed from Python (see
‘http://docs.python.org/library/optparse.html#terminology’).
'Arguments' are what you provide on the command line and for many Prolog
systems show up as a list of atoms ‘Args’ in ‘current_prolog_flag(argv,
Args)’.  They can be divided into:

   - 'Runtime arguments', which control the Prolog runtime;
     conventionally terminated by ‘--’.

   - 'Options', which are key-value pairs (with a boolean value possibly
     implicit) intended to control your program.

   - 'Positional arguments', which are what remains after all runtime
     arguments and options have been removed (with implicit arguments
     ‘true’/‘false’ for booleans filled in).

Positional arguments are used for mandatory arguments without sensible
defaults (e.g., input file names).  Options offer flexibility by letting
you change a default setting.  This library has no notion of mandatory
or required options.


File: TheLogtalkHandbook-3.101.0.info,  Node: Defining option objects,  Next: Validating option definitions,  Prev: Terminology,  Up: command_line_options

6.37.5 Defining option objects
------------------------------

Define command-line options by creating objects that import the
‘command_line_option’ category.  Each object represents one command-line
option and overrides the predicates to specify its properties.

Create an object that imports ‘command_line_option’ and override the
following predicates:

   - ‘key/1’: The key used to identify this option in the result.  This
     predicate must be overridden.

   - ‘short_flags/1’: List of single-character short flags (e.g., ‘[v]’
     for ‘-v’).  Default: ‘[]’.

   - ‘long_flags/1’: List of long flags (e.g., ‘[verbose]’ for
     ‘--verbose’).  Default: ‘[]’.

   - ‘type/1’: Option value type.  One of ‘boolean’, ‘atom’, ‘integer’,
     ‘float’, or ‘term’.  Default: ‘term’.

   - ‘default/1’: Default value.  Optional.

   - ‘meta/1’: Metasyntactic variable name for help text.  Default:
     ‘''’.

   - ‘help/1’: Help text (atom or list of atoms for pre-broken lines).
     Default: ‘''’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Validating option definitions,  Next: Example option objects,  Prev: Defining option objects,  Up: command_line_options

6.37.6 Validating option definitions
------------------------------------

Option objects provide two predicates for validating their definitions:

   - ‘check/0’: Validates the option definition, throwing an error if
     invalid.  The validation checks:

        - The ‘key/1’ predicate is defined (not just using the default).

        - All short flags are single characters.

        - The type is a known type (supported by the ‘type’ library).

        - If a default value is defined and the type is not ‘term’, the
          default value matches the declared type.

   - ‘valid/0’: Succeeds deterministically if the option definition is
     valid, fails otherwise.  This is useful when you want to check
     validity without handling exceptions.

The ‘parse/4-5’ and ‘help/2-3’ predicates automatically call ‘check/0’
on all option objects before processing, ensuring invalid definitions
are caught early with clear error messages.

Example:

     | ?- verbose_option::check.
     yes

     | ?- verbose_option::valid.
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: Example option objects,  Next: Parsing command-line arguments,  Prev: Validating option definitions,  Up: command_line_options

6.37.7 Example option objects
-----------------------------

     :- object(verbose_option,
         imports(command_line_option)).

         key(verbose).
         short_flags([v]).
         long_flags([verbosity]).
         type(integer).
         default(2).
         meta('V').
         help('verbosity level, 1 <= V <= 3').

     :- end_object.


     :- object(mode_option,
         imports(command_line_option)).

         key(mode).
         short_flags([m]).
         long_flags([mode]).
         type(atom).
         default('SCAN').
         help(['data gathering mode, one of',
               '  SCAN: do this',
               '  READ: do that',
               '  MAKE: fabricate numbers',
               '  WAIT: do nothing']).

     :- end_object.


     :- object(cache_option,
         imports(command_line_option)).

         key(cache).
         short_flags([r]).
         long_flags(['rebuild-cache']).
         type(boolean).
         default(true).
         help('rebuild cache in each iteration').

     :- end_object.


     :- object(outfile_option,
         imports(command_line_option)).

         key(outfile).
         short_flags([o]).
         long_flags(['output-file']).
         type(atom).
         meta('FILE').
         help('write output to FILE').

     :- end_object.


     % Configuration parameter without command-line flags
     :- object(path_option,
         imports(command_line_option)).

         key(path).
         default('/some/file/path/').

     :- end_object.


File: TheLogtalkHandbook-3.101.0.info,  Node: Parsing command-line arguments,  Next: Generating help text,  Prev: Example option objects,  Up: command_line_options

6.37.8 Parsing command-line arguments
-------------------------------------

Use the ‘command_line_options’ object ‘parse/4-5’ predicates:

     | ?- command_line_options::parse(
              [verbose_option, mode_option, cache_option, outfile_option],
              ['-v', '5', '-m', 'READ', '-ooutput.txt', 'input.txt'],
              Options,
              PositionalArguments
          ).

     Options = [verbose(5), mode('READ'), cache(true), outfile('output.txt')],
     PositionalArguments = ['input.txt'].


File: TheLogtalkHandbook-3.101.0.info,  Node: Generating help text,  Next: Help options,  Prev: Parsing command-line arguments,  Up: command_line_options

6.37.9 Generating help text
---------------------------

Use the ‘command_line_options::help/2’ predicate for default formatting:

     | ?- command_line_options::help([verbose_option, mode_option, cache_option], Help).

Or use ‘command_line_options::help/3’ with custom help options:

     | ?- command_line_options::help([verbose_option, mode_option], Help, [line_width(100)]).


File: TheLogtalkHandbook-3.101.0.info,  Node: Help options,  Next: Parse options,  Prev: Generating help text,  Up: command_line_options

6.37.10 Help options
--------------------

The ‘help/3’ predicate supports the following help options:

   - ‘line_width(Width)’: Maximum line width for help text.  Default:
     ‘80’.

   - ‘min_help_width(Width)’: Minimum width for help text column.
     Default: ‘40’.

   - ‘break_long_flags(Boolean)’: If ‘true’, break long flags across
     multiple lines.  Default: ‘false’.

   - ‘suppress_empty_meta(Boolean)’: If ‘true’ (default), suppress empty
     metasyntactic variables in help output.


File: TheLogtalkHandbook-3.101.0.info,  Node: Parse options,  Next: Notes and tips,  Prev: Help options,  Up: command_line_options

6.37.11 Parse options
---------------------

The ‘parse/5’ predicate supports the following parse options:

   - ‘output_functor(Functor)’: When defined, options are returned as
     ‘Functor(Key, Value)’ terms instead of ‘Key(Value)’ terms.  No
     default.

   - ‘duplicated_flags(Keep)’: How to handle duplicate options.  One of
     ‘keepfirst’, ‘keeplast’, ‘keepall’.  Default: ‘keeplast’.

   - ‘allow_empty_flag_spec(Boolean)’: If ‘true’ (default), options
     without flags are allowed (useful for configuration parameters).
     Set to ‘false’ to raise errors on empty flags.


File: TheLogtalkHandbook-3.101.0.info,  Node: Notes and tips,  Prev: Parse options,  Up: command_line_options

6.37.12 Notes and tips
----------------------

   - The default type is ‘term’, which subsumes ‘integer’, ‘float’, and
     ‘atom’.  However, always specifying types is recommended for
     reliable parsing and clear error messages.

   - ‘-sbar’ is taken as ‘-s bar’, not as ‘-s -b -a -r’ (no clustering).

   - ‘-s=foo’ is disallowed.

   - Duplicate flags default to ‘keeplast’ (controllable via the
     ‘duplicated_flags’ parse option).

   - Unknown flags (not in the specification) will raise errors.


File: TheLogtalkHandbook-3.101.0.info,  Node: core,  Next: copeland_ranker,  Prev: command_line_options,  Up: Libraries

6.38 ‘core’
===========

This library consists of built-in entities.

* Menu:

* API documentation: API documentation<57>.
* Loading: Loading<58>.
* Testing: Testing<53>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<57>,  Next: Loading<58>,  Up: core

6.38.1 API documentation
------------------------

See this Handbook “Objects”, “Protocols”, and “Categories” sections.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<58>,  Next: Testing<53>,  Prev: API documentation<57>,  Up: core

6.38.2 Loading
--------------

All entities in this library are automatically loaded at Logtalk
startup.


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<53>,  Prev: Loading<58>,  Up: core

6.38.3 Testing
--------------

Tests for this library can be found in the ‘tests/logtalk/entities’
directory.


File: TheLogtalkHandbook-3.101.0.info,  Node: copeland_ranker,  Next: coroutining,  Prev: core,  Up: Libraries

6.39 ‘copeland_ranker’
======================

Copeland pairwise preference ranker.  Ranks each item by its number of
matchup wins minus losses after aggregating weighted pairwise
preferences per observed opponent pair.

The library implements the ‘ranker_protocol’ defined in the
‘ranking_protocols’ library.  It provides predicates for learning a
ranker from pairwise preference judgments, using it to order candidate
items, and exporting it as a list of predicate clauses or to a file.

Datasets are represented as objects implementing the
‘pairwise_ranking_dataset_protocol’ protocol from the
‘ranking_protocols’ library.  See the ‘test_datasets’ directory for
examples.  The training dataset must declare each ranked item once, use
only declared items in preferences, assign positive weights to
preferences between distinct items, and induce a connected undirected
comparison graph.

* Menu:

* API documentation: API documentation<58>.
* Loading: Loading<59>.
* Testing: Testing<54>.
* Features: Features<11>.
* Scoring semantics: Scoring semantics<3>.
* Usage: Usage<23>.
* Diagnostics syntax: Diagnostics syntax<5>.
* Options: Options<10>.
* Ranker representation: Ranker representation<4>.
* References: References<8>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<58>,  Next: Loading<59>,  Up: copeland_ranker

6.39.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#copeland_ranker’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<59>,  Next: Testing<54>,  Prev: API documentation<58>,  Up: copeland_ranker

6.39.2 Loading
--------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(copeland_ranker(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<54>,  Next: Features<11>,  Prev: Loading<59>,  Up: copeland_ranker

6.39.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(copeland_ranker(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<11>,  Next: Scoring semantics<3>,  Prev: Testing<54>,  Up: copeland_ranker

6.39.4 Features
---------------

   - 'Pairwise Preference Learning': Learns one deterministic score per
     item from pairwise preference datasets.

   - 'Portable Copeland Scoring': Computes Copeland scores from
     aggregated head-to-head outcomes using only standard Logtalk
     library predicates.

   - 'Integer Score Semantics': Learned scores are restricted to
     integers, because each observed aggregated matchup contributes
     exactly ‘+1’, ‘-1’, or ‘0’ to an item’s total score.

   - 'Deterministic Ranking': Orders candidate items by learned score
     with deterministic tie-breaking using the standard term order of
     the item identifiers after sorting by descending score.

   - 'Strict Dataset Validation': Rejects duplicate items, undeclared
     items in preferences, self-preferences, non-positive weights, and
     disconnected comparison graphs.

   - 'Training Diagnostics': Learned rankers include dataset summary
     metadata that can be accessed using the ‘diagnostics/2’ predicate.

   - 'Ranker Export': Learned rankers can be exported as self-contained
     terms.

   - 'Shared Ranking Infrastructure': Uses the common
     ‘ranking_protocols’ helper predicates for option processing,
     dataset validation, diagnostics, export, and candidate ranking.


File: TheLogtalkHandbook-3.101.0.info,  Node: Scoring semantics<3>,  Next: Usage<23>,  Prev: Features<11>,  Up: copeland_ranker

6.39.5 Scoring semantics
------------------------

This implementation uses a Copeland score defined over aggregated
observed matchups.  For each unordered pair of observed opponents, the
preference data is aggregated into total wins for the left and right
item.  The item with the higher aggregated total receives ‘+1’ for that
matchup, the item with the lower total receives ‘-1’, and both receive
‘0’ when the aggregated totals tie.

Only observed opponent pairs contribute to the learned scores.
Unobserved pairs are ignored rather than treated as implicit ties.  This
makes the implementation a sparse-data Copeland variant suitable for
incomplete pairwise datasets.

Because each observed matchup contributes only ‘+1’, ‘-1’, or ‘0’, every
learned Copeland score is an integer.  The ranker validation logic
enforces this invariant when consuming serialized or exported ranker
terms so that malformed non-integer score payloads are rejected instead
of silently accepted.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<23>,  Next: Diagnostics syntax<5>,  Prev: Scoring semantics<3>,  Up: copeland_ranker

6.39.6 Usage
------------

* Menu:

* Learning a ranker: Learning a ranker<4>.
* Inspecting diagnostics: Inspecting diagnostics<4>.
* Ranking candidate items: Ranking candidate items<4>.
* Exporting the ranker: Exporting the ranker<4>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Learning a ranker<4>,  Next: Inspecting diagnostics<4>,  Up: Usage<23>

6.39.6.1 Learning a ranker
..........................

     % Learn from a pairwise ranking dataset object
     | ?- copeland_ranker::learn(my_dataset, Ranker).
     ...

     % Learn with an explicit empty options list
     | ?- copeland_ranker::learn(my_dataset, Ranker, []).
     ...

The current implementation accepts only the empty options list ‘[]’.
Any non-empty options list is rejected.


File: TheLogtalkHandbook-3.101.0.info,  Node: Inspecting diagnostics<4>,  Next: Ranking candidate items<4>,  Prev: Learning a ranker<4>,  Up: Usage<23>

6.39.6.2 Inspecting diagnostics
...............................

     % Inspect model and dataset summary metadata
     | ?- copeland_ranker::learn(my_dataset, Ranker),
          copeland_ranker::diagnostics(Ranker, Diagnostics).
     Diagnostics = [...]
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Ranking candidate items<4>,  Next: Exporting the ranker<4>,  Prev: Inspecting diagnostics<4>,  Up: Usage<23>

6.39.6.3 Ranking candidate items
................................

     % Rank a candidate set from most preferred to least preferred
     | ?- copeland_ranker::learn(my_dataset, Ranker),
          copeland_ranker::rank(Ranker, [item_a, item_b, item_c], Ranking).
     Ranking = [...]
     ...

Candidate lists must be proper lists of unique, ground items declared by
the training dataset.  Invalid ranker terms, duplicate candidates, and
candidates containing variables are rejected with errors instead of
being silently accepted.


File: TheLogtalkHandbook-3.101.0.info,  Node: Exporting the ranker<4>,  Prev: Ranking candidate items<4>,  Up: Usage<23>

6.39.6.4 Exporting the ranker
.............................

Learned rankers can be exported as a list of clauses or to a file for
later use.

     % Export as predicate clauses
     | ?- copeland_ranker::learn(my_dataset, Ranker),
          copeland_ranker::export_to_clauses(my_dataset, Ranker, my_ranker, Clauses).
     Clauses = [my_ranker(copeland_ranker(...))]
     ...

     % Export to a file
     | ?- copeland_ranker::learn(my_dataset, Ranker),
          copeland_ranker::export_to_file(my_dataset, Ranker, my_ranker, 'ranker.pl').
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Diagnostics syntax<5>,  Next: Options<10>,  Prev: Usage<23>,  Up: copeland_ranker

6.39.7 Diagnostics syntax
-------------------------

The ‘diagnostics/2’ predicate returns a list of metadata terms with the
form:

     [
         model(copeland_ranker),
         options(Options),
         dataset_summary(DatasetSummary)
     ]

Where:

   - ‘model(copeland_ranker)’ identifies the learning algorithm that
     produced the ranker.

   - ‘options(Options)’ stores the effective learning options after
     merging the user options with the library defaults.

   - ‘dataset_summary(DatasetSummary)’ stores a summary list describing
     the validated training dataset.

The current ‘dataset_summary/1’ payload has the form:

     [
         items(NumberOfItems),
         preferences(NumberOfPreferences),
         connected_components(NumberOfComponents),
         isolated_items(IsolatedItems)
     ]

Use the ‘ranking_protocols’ ‘diagnostic/2’ and ‘ranker_options/2’ helper
predicates when you only need a single metadata term or the effective
options.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<10>,  Next: Ranker representation<4>,  Prev: Diagnostics syntax<5>,  Up: copeland_ranker

6.39.8 Options
--------------

The current ‘learn/3’ implementation does not define any user options
beyond the default empty list.  Non-empty options lists are rejected.


File: TheLogtalkHandbook-3.101.0.info,  Node: Ranker representation<4>,  Next: References<8>,  Prev: Options<10>,  Up: copeland_ranker

6.39.9 Ranker representation
----------------------------

The learned ranker is represented by a compound term of the form:

     copeland_ranker(Items, Scores, Diagnostics)

Where:

   - ‘Items’: List of ranked items.

   - ‘Scores’: List of ‘Item-Score’ pairs.

   - ‘Diagnostics’: List of metadata terms, including the effective
     options and dataset summary.

The ‘Scores’ payload is expected to contain integer Copeland scores
only.  This restriction is not just an implementation preference but a
direct consequence of the scoring semantics: each observed aggregated
matchup changes an item’s score by one of the three integer values ‘+1’,
‘-1’, or ‘0’.

When exported using ‘export_to_clauses/4’ or ‘export_to_file/4’, this
ranker term is serialized directly as the single argument of the
generated predicate clause so that the exported model can be loaded and
reused as-is.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<8>,  Prev: Ranker representation<4>,  Up: copeland_ranker

6.39.10 References
------------------

  1. Copeland, A. H. (1951).  A reasonable social welfare function.
     'Seminar on Mathematics in the Social Sciences, University of
     Michigan'.


File: TheLogtalkHandbook-3.101.0.info,  Node: coroutining,  Next: crypto,  Prev: copeland_ranker,  Up: Libraries

6.40 ‘coroutining’
==================

The ‘coroutining’ object provides a portable abstraction over how common
coroutining predicates are made available by the supported backend
Prolog systems (ECLiPSe, SICStus Prolog, SWI-Prolog, Trealla Prolog,
XVM, and YAP) that provide them.  Partial support for XSB is provided
(the predicate ‘frozen/2’ is not available and calls to it fail).

Calls to the library predicates are inlined when compiled with the
‘optimize’ flag turned on.  In this case, there is no overhead compared
with calling the abstracted predicates directly.

See also the ‘dif’ library.

* Menu:

* API documentation: API documentation<59>.
* Loading: Loading<60>.
* Testing: Testing<55>.
* Usage: Usage<24>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<59>,  Next: Loading<60>,  Up: coroutining

6.40.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#coroutining’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<60>,  Next: Testing<55>,  Prev: API documentation<59>,  Up: coroutining

6.40.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(coroutining(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<55>,  Next: Usage<24>,  Prev: Loading<60>,  Up: coroutining

6.40.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(coroutining(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<24>,  Prev: Testing<55>,  Up: coroutining

6.40.4 Usage
------------

Load this library from your application loader file.  To call the
coroutining predicates using implicit message-sending, add the following
directive to any object or category calling the predicates (adjust the
list to the predicates actually called):

     :- uses(coroutining, [
         dif/2, dif/1, freeze/2, frozen/2, when/2
     ]).


File: TheLogtalkHandbook-3.101.0.info,  Node: crypto,  Next: crs_projections,  Prev: coroutining,  Up: Libraries

6.41 ‘crypto’
=============

This library provides transport-neutral cryptographic predicates.  It
currently exports the ‘crypto’ object with the predicates:

   - ‘random_below/2’

   - ‘random_bytes/2’

   - ‘hex_bytes/2’

   - ‘token_hex/2’

   - ‘token_urlsafe/2’

   - ‘secure_compare/2’

   - ‘hkdf/5’

   - ‘pbkdf2/6’

   - ‘apr1/3’

   - ‘password_hash/4’

   - ‘password_hash_needs_rehash/3’

   - ‘verify_password_hash/2’

The ‘random_below/2’ predicate returns a uniformly distributed random
integer greater than or equal to zero and less than the given exclusive
upper bound.

The ‘random_bytes/2’ predicate returns a list with the requested number
of random bytes.  It tries to read bytes from ‘/dev/urandom’ first and
falls back to a pseudo-random generator when that source is unavailable.

The ‘hex_bytes/2’ predicate relates hexadecimal atoms with lists of
bytes.

The ‘token_hex/2’ and ‘token_urlsafe/2’ predicates return either a
lowercase hexadecimal token or a unpadded Base64URL token generated from
the requested number of random bytes.

The ‘secure_compare/2’ predicate provides constant-time comparison for
byte sequences represented either as byte lists or atoms.

The ‘hkdf/5’ and ‘pbkdf2/6’ predicates provide portable key derivation
implemented on top of the existing ‘hashes’ and ‘hmac’ libraries.

The ‘apr1/3’ predicate computes Apache APR1 encoded checksums for
password and salt byte sequences using a portable MD5-based
implementation.

The ‘password_hash/4’ predicate builds on top of ‘pbkdf2/6’ to generate
structured password-hash terms.  The ‘password_hash_needs_rehash/3’
predicate checks stored password-hash terms against the current PBKDF2
policy.  The ‘verify_password_hash/2’ predicate verifies ‘pbkdf2(Hash,
Iterations, Salt, DerivedKey)’, ‘digest(Hash, StoredDigest)’, and
‘apr1(Salt, Checksum)’ terms.

* Menu:

* API documentation: API documentation<60>.
* Loading: Loading<61>.
* Testing: Testing<56>.
* Examples: Examples<167>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<60>,  Next: Loading<61>,  Up: crypto

6.41.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#crypto’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<61>,  Next: Testing<56>,  Prev: API documentation<60>,  Up: crypto

6.41.2 Loading
--------------

To load the library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(crypto(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<56>,  Next: Examples<167>,  Prev: Loading<61>,  Up: crypto

6.41.3 Testing
--------------

To test this library, load the ‘tester.lgt’ file:

     | ?- logtalk_load(crypto(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<167>,  Prev: Testing<56>,  Up: crypto

6.41.4 Examples
---------------

Generate sixteen random bytes:

     | ?- crypto::random_bytes(16, Bytes).
     Bytes = [42,17,203,91,16,88,121,4,238,75,63,142,7,210,119,55]
     yes

Convert bytes to a hexadecimal atom:

     | ?- crypto::hex_bytes(Hex, [80,26,206]).
     Hex = '501ace'
     yes

Derive 32 bytes using HKDF-SHA-256:

     | ?- crypto::hkdf(sha256, [1,2,3,4], 32, Bytes, [salt([5,6,7,8]),info([9,10])]).
     Bytes = [...]
     yes

Compute an Apache APR1 checksum:

     | ?- crypto::apr1([112,97,115,115,119,111,114,100], [112,111,114,116,97,98,108,101], Checksum).
     Checksum = [107,117,110,70,78,90,57,114,48,81,57,54,51,88,98,115,116,101,79,79,87,46]
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: crs_projections,  Next: csv,  Prev: crypto,  Up: Libraries

6.42 ‘crs_projections’
======================

This library provides a ‘crs_projections_protocol’ protocol and a
‘crs_projections’ object for working with a small set of common
coordinate reference systems and transforming coordinates between them.

Both 2D and explicit 3D WGS84 geodetic coordinates are supported.

* Menu:

* API documentation: API documentation<61>.
* Loading: Loading<62>.
* Testing: Testing<57>.
* Supported coordinate reference systems::
* Usage: Usage<25>.
* Notes::


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<61>,  Next: Loading<62>,  Up: crs_projections

6.42.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#crs_projections’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<62>,  Next: Testing<57>,  Prev: API documentation<61>,  Up: crs_projections

6.42.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(crs_projections(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<57>,  Next: Supported coordinate reference systems,  Prev: Loading<62>,  Up: crs_projections

6.42.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(crs_projections(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Supported coordinate reference systems,  Next: Usage<25>,  Prev: Testing<57>,  Up: crs_projections

6.42.4 Supported coordinate reference systems
---------------------------------------------

The library currently supports:

   - ‘wgs84’ geographic coordinates represented as
     ‘geographic(Latitude,Longitude)’ in degrees

   - ‘wgs84_3d’ geographic coordinates represented as
     ‘geographic(Latitude,Longitude,EllipsoidalHeight)’ in degrees and
     meters

   - ‘web_mercator’ projected coordinates represented as
     ‘projected(X,Y)’ in meters

   - ‘world_mercator’ projected coordinates represented as
     ‘projected(X,Y)’ in meters

   - ‘ecef’ geocentric coordinates represented as ‘ecef(X,Y,Z)’ in
     meters

   - ‘enu(OriginCoordinate)’ local tangent-plane coordinates represented
     as ‘enu(East,North,Up)’ in meters

   - ‘lambert_azimuthal_equal_area(OriginCoordinate)’ equal-area
     projected coordinates represented as ‘projected(X,Y)’ in meters

   - ‘utm(Zone,Hemisphere)’ projected coordinates represented as
     ‘grid(Easting,Northing)’ in meters

EPSG helpers are available for these reference systems:

   - ‘4326’ for ‘wgs84’

   - ‘4979’ for ‘wgs84_3d’

   - ‘3857’ for ‘web_mercator’

   - ‘3395’ for ‘world_mercator’

   - ‘4978’ for ‘ecef’

   - ‘32601’-‘32660’ for northern-hemisphere UTM zones

   - ‘32701’-‘32760’ for southern-hemisphere UTM zones

Additional metadata helpers are provided for querying CRS names, kinds,
coordinate units, and dimensions.

Additional projection helpers are provided for working directly with
local ENU tangent-plane coordinates and Lambert azimuthal equal-area
coordinates.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<25>,  Next: Notes,  Prev: Supported coordinate reference systems,  Up: crs_projections

6.42.5 Usage
------------

Load the library:

     | ?- logtalk_load(crs_projections(loader)).

Validate CRS terms and look up EPSG codes:

     | ?- crs_projections::valid_crs(utm(29, north)).
     | ?- crs_projections::crs_name(wgs84_3d, Name).
     | ?- crs_projections::crs_name(ecef, Name).
     | ?- crs_projections::crs_kind(world_mercator, Kind).
     | ?- crs_projections::crs_units(wgs84, Units).
     | ?- crs_projections::crs_units(wgs84_3d, Units).
     | ?- crs_projections::crs_dimensions(ecef, Dimensions).
     | ?- crs_projections::crs_dimensions(wgs84_3d, Dimensions).
     | ?- crs_projections::crs_epsg(web_mercator, EPSG).
     | ?- crs_projections::crs_epsg(wgs84_3d, EPSG).
     | ?- crs_projections::epsg_crs(32629, CRS).
     | ?- crs_projections::epsg_crs(4979, CRS).
     | ?- crs_projections::valid_crs(enu(geographic(38.7223, -9.1393))).
     | ?- crs_projections::valid_crs(lambert_azimuthal_equal_area(geographic(38.7223, -9.1393))).

Infer the native UTM CRS for a WGS84 coordinate:

     | ?- crs_projections::utm_zone(geographic(38.7223, -9.1393), Zone).
     | ?- crs_projections::utm_crs(geographic(38.7223, -9.1393), CRS).

Transform WGS84 coordinates to projected systems and back:

     | ?- crs_projections::transform(wgs84, web_mercator, geographic(38.7223, -9.1393), Projected).
     | ?- crs_projections::transform(wgs84, wgs84_3d, geographic(38.7223, -9.1393), Geodetic3D).
     | ?- crs_projections::transform(wgs84_3d, ecef, geographic(38.7223, -9.1393, 123.45), Geocentric3D).
     | ?- crs_projections::transform(ecef, wgs84_3d, Geocentric3D, Geodetic3D).
     | ?- crs_projections::transform(web_mercator, wgs84, Projected, Coordinate).
     | ?- crs_projections::transform(wgs84, world_mercator, geographic(38.7223, -9.1393), Mercator).
     | ?- crs_projections::transform(wgs84, ecef, geographic(38.7223, -9.1393), Geocentric).
     | ?- crs_projections::transform(wgs84_3d, enu(geographic(38.7223, -9.1393, 100.0)), geographic(38.7223, -9.1393, 125.0), Local3D).
     | ?- crs_projections::transform(enu(geographic(38.7223, -9.1393, 100.0)), wgs84_3d, Local3D, Geodetic3D).
     | ?- crs_projections::transform(wgs84, enu(geographic(38.7223, -9.1393)), geographic(38.7233, -9.1383), Local).
     | ?- crs_projections::transform(wgs84, lambert_azimuthal_equal_area(geographic(38.7223, -9.1393)), geographic(38.7233, -9.1383), EqualArea).
     | ?- crs_projections::transform(wgs84, utm(29, north), geographic(38.7223, -9.1393), UTM).
     | ?- crs_projections::transform(utm(29, north), wgs84, UTM, Coordinate).

Use direct helper predicates for local tangent-plane and equal-area
workflows:

     | ?- crs_projections::local_tangent_plane(geographic(38.7223, -9.1393), geographic(38.7233, -9.1383), Local).
     | ?- crs_projections::local_tangent_plane_inverse(geographic(38.7223, -9.1393), Local, Coordinate).
     | ?- crs_projections::lambert_azimuthal_equal_area(geographic(38.7223, -9.1393), geographic(38.7233, -9.1383), EqualArea).
     | ?- crs_projections::lambert_azimuthal_equal_area_inverse(geographic(38.7223, -9.1393), EqualArea, Coordinate).


File: TheLogtalkHandbook-3.101.0.info,  Node: Notes,  Prev: Usage<25>,  Up: crs_projections

6.42.6 Notes
------------

The ‘utm_zone/2’, ‘utm_crs/2’, and UTM transformation predicates only
succeed for latitudes in the ‘[-80.0,84.0[’ range, matching the standard
UTM coverage.

Transformations between projected coordinate reference systems are
implemented by converting through ‘wgs84’.

When converting from ‘wgs84’ to ‘wgs84_3d’, the ellipsoidal height
defaults to ‘0.0’.  When converting from 2D projected or geographic
coordinate reference systems to ‘wgs84_3d’, the resulting ellipsoidal
height is also ‘0.0’ because the source coordinate reference system does
not carry height information.

Transforms between ‘ecef’ and projected coordinate reference systems are
also implemented through ‘wgs84’.

Transforms involving ‘enu(OriginCoordinate)’ preserve the local ‘Up’
component when converting directly to or from ‘ecef’ and ‘wgs84_3d’.


File: TheLogtalkHandbook-3.101.0.info,  Node: csv,  Next: cuid2,  Prev: crs_projections,  Up: Libraries

6.43 ‘csv’
==========

The ‘csv’ library provides predicates for reading and writing CSV files
and streams:

‘https://www.rfc-editor.org/rfc/rfc4180.txt’

The main object, ‘csv/4’, is a parametric object allowing passing
options for the handling of the header of the file, the fields
separator, the handling of double-quoted fields, and comments handling.
When comments handling is ‘true’, lines starting with the ‘#’ character
are skipped when reading files and streams.

The ‘csv/3’ parametric object is kept for backward compatibility and
extends ‘csv/4’ by setting the comments option to ‘false’.  The ‘csv’
object extends the ‘csv/4’ parametric object using default option
values.

The library also includes predicates to guess the separator and guess
the number of columns in a given CSV file.

Files and streams can be read into a list of rows (with each row being
represented by a list of fields) or asserted using a user-defined
dynamic predicate.  Reading can be done by first loading the whole file
(using the ‘read_file/2-3’ predicates) into memory or line by line
(using the ‘read_file_by_line/2-3’ predicates).  Reading line by line is
usually the best option for parsing large CSV files.

Data can be saved to a CSV file or stream by providing the object and
predicate for accessing the data plus the name of the destination file
or the stream handle or alias.

* Menu:

* API documentation: API documentation<62>.
* Loading: Loading<63>.
* Testing: Testing<58>.
* Usage: Usage<26>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<62>,  Next: Loading<63>,  Up: csv

6.43.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#csv’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<63>,  Next: Testing<58>,  Prev: API documentation<62>,  Up: csv

6.43.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(csv(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<58>,  Next: Usage<26>,  Prev: Loading<63>,  Up: csv

6.43.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(csv(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<26>,  Prev: Testing<58>,  Up: csv

6.43.4 Usage
------------

The ‘csv(Header, Separator, IgnoreQuotes, Comments)’ parametric object
allows passing the following options:

  1. ‘Header’: possible values are ‘missing’, ‘skip’, and ‘keep’.

  2. ‘Separator’: possible values are ‘comma’, ‘tab’, ‘semicolon’, and
     ‘colon’.

  3. ‘IgnoreQuotes’: possible values are ‘true’ to ignore double quotes
     surrounding field data and ‘false’ to preserve the double quotes.

  4. ‘Comments’: possible values are ‘false’ (default) and ‘true’ to
     skip lines starting with ‘#’.

The ‘csv’ object uses the default values ‘keep’, ‘comma’, ‘false’, and
‘false’.

When writing CSV files or streams, set the quoted fields option to
‘false’ to write all non-numeric fields double-quoted (i.e., escaped).

The library objects can also be used to guess the separator used in a
CSV file if necessary.  For example:

     | ?- csv::guess_separator('test_files/crlf_ending.csv', Separator).
     Is this the proper reading of a line of this file (y/n)? [aaa,bb,ccc]
     |> y.

     Separator = comma ?

This information can then be used to read the CSV file returning a list
of rows:

     | ?- csv(keep, comma, true)::read_file('test_files/crlf_ending.csv', Rows).

     Rows = [[aaa,bbb,ccc],[zzz,yyy,xxx]] ?

     | ?- csv(keep, comma, true, true)::read_file('test_files/comments.csv', Rows).

     Rows = [[aaa,bbb,ccc],[zzz,yyy,xxx]] ?

Alternatively, the CSV data can be saved using a public and dynamic
object predicate (that must be previously declared).  For example:

     | ?- assertz(p(_,_,_)), retractall(p(_,_,_)).
     yes

     | ?- csv(keep, comma, true)::read_file('test_files/crlf_ending.csv', user, p/3).
     yes

     | ?-  p(A,B,C).

     A = aaa
     B = bbb
     C = ccc ? ;

     A = zzz
     B = yyy
     C = xxx

Given a predicate representing a table, the predicate data can be
written to a file or stream.  For example:

     | ?- csv(keep, comma, true)::write_file('output.csv', user, p/3).
     yes

leaving the content just as the original file thanks to the use of
‘true’ for the ‘IgnoreQuotes’ option:

     aaa,bbb,ccc
     zzz,yyy,xxx

Otherwise:

     | ?- csv(keep, comma, false)::write_file('output.csv', user, p/3).
     yes

results in the following file content:

     "aaa","bbb","ccc"
     "zzz","yyy","xxx"

The ‘guess_arity/2’ method, to identify the arity, i.  e.  the number of
fields or columns per record in a given CSV file, for example:

     | ?- csv(keep, comma, false)::guess_arity('test_files/crlf_ending.csv', Arity).
     Is this the proper reading of a line of this file (y/n)? [aaa,bbb,ccc]
     |> y.

     Arity = 3


File: TheLogtalkHandbook-3.101.0.info,  Node: cuid2,  Next: cusum_anomaly_detector,  Prev: csv,  Up: Libraries

6.44 ‘cuid2’
============

This library generates random Cuid2 identifiers:

‘https://github.com/paralleldrive/cuid2’

By default, identifiers are represented as atoms with 24 symbols and use
a lowercase alphanumeric alphabet:

     abcdefghijklmnopqrstuvwxyz0123456789

Custom size, alphabet, and representation (atoms, lists of characters,
or lists of character codes) are supported using a parametric object.

The generation of random identifiers uses the ‘/dev/urandom’ random
number generator when available.  This includes macOS, Linux, *BSD, and
other POSIX operating systems.  On Windows, a pseudo-random generator is
used, randomized using the current wall time.

See also the ‘ids’, ‘nanoid’, ‘ksuid’, ‘snowflakeid’, ‘uuid’, and ‘ulid’
libraries.

* Menu:

* API documentation: API documentation<63>.
* Loading: Loading<64>.
* Testing: Testing<59>.
* Usage: Usage<27>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<63>,  Next: Loading<64>,  Up: cuid2

6.44.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#cuid2’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<64>,  Next: Testing<59>,  Prev: API documentation<63>,  Up: cuid2

6.44.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(cuid2(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<59>,  Next: Usage<27>,  Prev: Loading<64>,  Up: cuid2

6.44.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(cuid2(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<27>,  Prev: Testing<59>,  Up: cuid2

6.44.4 Usage
------------

To generate an identifier using the default configuration:

     | ?- cuid2::generate(Cuid2).
     Cuid2 = 'k4f9mdd51t2r9y53i8h4j1bz'
     yes

To generate a 10-symbol identifier represented as a list of characters:

     | ?- cuid2(chars, 10, 'abcdef012345')::generate(Cuid2).
     Cuid2 = ['a','2','f','e','5','c','1','d','0','b']
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: cusum_anomaly_detector,  Next: datalog,  Prev: cuid2,  Up: Libraries

6.45 ‘cusum_anomaly_detector’
=============================

CUSUM (Cumulative Sum Control Chart) anomaly detector for continuous
sequence-like datasets.  This is a statistical anomaly-detection method
based on a two-sided CUSUM control chart.  Declared continuous
attributes are interpreted as ordered monitoring steps.

The library implements the ‘anomaly_detector_protocol’ defined in the
‘anomaly_detection_protocols’ library.  It learns a detector from a
continuous dataset, computes anomaly scores for new instances, predicts
‘normal’ or ‘anomaly’, and exports learned detectors as clauses or
files.

Datasets are represented as objects implementing the
‘anomaly_dataset_protocol’ protocol from the
‘anomaly_detection_protocols’ library.  Declared continuous attributes
are interpreted as ordered monitoring steps in a sequence.  See the
‘cusum_anomaly_detector/tests.lgt’ file for example datasets.

* Menu:

* API documentation: API documentation<64>.
* Loading: Loading<65>.
* Testing: Testing<60>.
* Features: Features<12>.
* Options: Options<11>.
* Detector representation::
* Notes: Notes<2>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<64>,  Next: Loading<65>,  Up: cusum_anomaly_detector

6.45.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#cusum_anomaly_detector’ link in
a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<65>,  Next: Testing<60>,  Prev: API documentation<64>,  Up: cusum_anomaly_detector

6.45.2 Loading
--------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(cusum_anomaly_detector(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<60>,  Next: Features<12>,  Prev: Loading<65>,  Up: cusum_anomaly_detector

6.45.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(cusum_anomaly_detector(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<12>,  Next: Options<11>,  Prev: Testing<60>,  Up: cusum_anomaly_detector

6.45.4 Features
---------------

   - 'Statistical method': implements anomaly detection based on a
     two-sided CUSUM control chart, using learned per-step population
     means and standard deviations for continuous attributes.

   - 'Ordered sequence interpretation': declared continuous attributes
     are treated as ordered monitoring steps.  For each known step value
     ‘x_t’, the library computes ‘z_t = (x_t - mu_t) / sigma_t’ and
     updates the positive and negative CUSUM recurrences along that
     attribute order.  The learned detector stores a precomputed
     attribute schema so that this ordering does not need to be rebuilt
     for every scoring call.

   - 'CUSUM recurrences': the positive and negative cumulative sums are
     updated as ‘C+_t = max(0, C+_(t-1) + z_t - k)’ and ‘C-_t = max(0,
     C-_(t-1) - z_t - k)’, where ‘k’ is the learn-time allowance.  The
     raw anomaly score is the maximum excursion over all positive and
     negative cumulative sums.

   - 'Continuous features only': accepts datasets whose declared
     attributes are all ‘continuous’.

   - 'Baseline training selection': supports learn-time
     ‘baseline_class_values(ClassValues)’ and
     ‘baseline_selection_policy(Policy)’ options.  The default baseline
     class values are ‘[normal]’.  The default ‘reject’ policy throws an
     error if any non-baseline training example is found.  The ‘filter’
     policy removes non-baseline examples before fitting the baseline
     statistics.

   - 'Missing-value tolerant': ignores missing values when fitting
     per-step statistics and skips them during scoring.  Queries must
     still provide at least one known value.

   - 'Bounded scoring': maps the raw CUSUM excursion to ‘[0.0, 1.0)’
     using ‘Score = Raw / (1 + Raw)’.

   - 'CUSUM control parameters': supports learn-time ‘allowance/1’ and
     ‘decision_interval/1’ options.  The default ‘allowance(0.5)’ and
     ‘decision_interval(5.0)’ correspond to a common standardized CUSUM
     setup.

   - 'Default threshold': the default
     ‘anomaly_threshold(0.8333333333333334)’ corresponds to the default
     raw decision interval ‘5.0’.  If a custom ‘decision_interval/1’ is
     passed to ‘learn/3’ without an explicit ‘anomaly_threshold/1’, the
     stored anomaly threshold is derived automatically as ‘H / (1 + H)’.

   - 'Learn-time control parameters': ‘allowance/1’ and
     ‘decision_interval/1’ are recorded in the learned detector and
     reused for subsequent scoring and prediction.  Passing them to
     ‘predict/4’ does not override the learned values.  Only
     ‘anomaly_threshold/1’ can be overridden at predict time.

   - 'All-missing queries rejected': scoring and prediction throw a
     ‘domain_error(non_empty_known_values, AttributeNames)’ exception
     when every declared step is missing in the query.

   - 'Featureless datasets rejected': datasets must declare at least one
     continuous feature; otherwise ‘learn/2-3’ throws a
     ‘domain_error(non_empty_features, Dataset)’ exception.

   - 'Detector export': learned detectors can be exported as predicate
     clauses.

   - 'Explicit validation and diagnostics': supports the shared
     ‘check_anomaly_detector/1’, ‘valid_anomaly_detector/1’,
     ‘diagnostics/2’, ‘diagnostic/2’, and ‘anomaly_detector_options/2’
     predicates.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<11>,  Next: Detector representation,  Prev: Features<12>,  Up: cusum_anomaly_detector

6.45.5 Options
--------------

The following options are supported by the public API:

   - ‘anomaly_threshold(Threshold)’: Threshold for ‘predict/3-4’
     (default: ‘0.8333333333333334’)

   - ‘allowance(Allowance)’: Learn-time CUSUM allowance ‘k’ (default:
     ‘0.5’)

   - ‘baseline_class_values(ClassValues)’: Learn-time class labels that
     are admissible for baseline fitting (default: ‘[normal]’)

   - ‘baseline_selection_policy(Policy)’: Learn-time handling of
     examples whose class is not listed in ‘baseline_class_values/1’.
     Supported values are ‘reject’ and ‘filter’ (default: ‘reject’)

   - ‘decision_interval(DecisionInterval)’: Learn-time raw decision
     interval ‘H’ (default: ‘5.0’).  If no explicit
     ‘anomaly_threshold/1’ is passed to ‘learn/3’, the stored threshold
     is derived from this value as ‘H / (1 + H)’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Detector representation,  Next: Notes<2>,  Prev: Options<11>,  Up: cusum_anomaly_detector

6.45.6 Detector representation
------------------------------

The learned detector is represented by default as:

     cusum_detector(TrainingDataset, AttributeSchema, Encoders, Diagnostics)

Where:

   - ‘TrainingDataset’: training dataset object identifier

   - ‘AttributeSchema’: precomputed attribute ordering metadata used to
     validate and reorder query step values efficiently during scoring

   - ‘Encoders’: list of ‘cusum_encoder(Attribute, Mean, Scale)’ records

   - ‘Diagnostics’: learned metadata terms including ‘model/1’,
     ‘training_dataset/1’, ‘attribute_names/1’, ‘feature_count/1’,
     ‘example_count/1’, and ‘options/1’.  The ‘example_count/1’ value is
     the effective number of training examples after applying the
     selected baseline selection policy.

When exported using ‘export_to_clauses/4’ or ‘export_to_file/4’, this
detector term is serialized directly as the single argument of the
generated predicate clause so that the exported model can be loaded and
reused as-is.


File: TheLogtalkHandbook-3.101.0.info,  Node: Notes<2>,  Prev: Detector representation,  Up: cusum_anomaly_detector

6.45.7 Notes
------------

Scoring has three stages.  First, the detector computes one standardized
deviation ‘z_t = (x_t - mu_t) / sigma_t’ for each known monitoring step.
Second, those deviations are processed sequentially using the positive
and negative CUSUM recurrences with the learned ‘allowance/1’ value.
Third, the maximum raw excursion is mapped to the interval ‘[0.0, 1.0)’
using ‘Score = Raw / (1 + Raw)’.

The ‘allowance/1’ option changes the CUSUM update rule itself by
controlling how much drift must accumulate before the chart grows.
Larger values make the detector less sensitive to small shifts.  The
‘decision_interval/1’ option does not change scoring; it only affects
the default threshold stored when learning a detector.

The ‘baseline_class_values/1’ option declares which dataset class labels
are admissible for baseline fitting.  The ‘baseline_selection_policy/1’
option then controls what happens when other labels are present in the
training data.  The default ‘reject’ policy raises a
‘domain_error(baseline_only_training_data, Dataset)’ exception when any
non-baseline example is found.  The ‘filter’ policy removes non-baseline
examples before fitting and raises a
‘domain_error(non_empty_baseline_training_data, Dataset)’ exception if
no training examples remain after filtering.

Attributes with zero observed dispersion are assigned a fallback scale
of ‘1.0’.  This keeps the detector well-defined for singleton datasets
or constant steps while still yielding zero score for matching values
and positive scores for deviating values.


File: TheLogtalkHandbook-3.101.0.info,  Node: datalog,  Next: dates,  Prev: cusum_anomaly_detector,  Up: Libraries

6.46 ‘datalog’
==============

This library provides a portable Datalog and incremental rule engine for
educational purposes and non-demanding applications.  This library is
work-in-progress and changes, possibly breaking backwards compatibility,
are to be expected.

* Menu:

* API documentation: API documentation<65>.
* Loading: Loading<66>.
* Testing: Testing<61>.
* Scope: Scope<3>.
* Public API overview::
* Basic usage::
* Limitations: Limitations<3>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<65>,  Next: Loading<66>,  Up: datalog

6.46.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#datalog’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<66>,  Next: Testing<61>,  Prev: API documentation<65>,  Up: datalog

6.46.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(datalog(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<61>,  Next: Scope<3>,  Prev: Loading<66>,  Up: datalog

6.46.3 Testing
--------------

To run the library unit tests, load the ‘tester.lgt’ file:

     | ?- logtalk_load(datalog(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Scope<3>,  Next: Public API overview,  Prev: Testing<61>,  Up: datalog

6.46.4 Scope
------------

   - positive and stratified negation rules (‘neg/1’ body literals)

   - conservative aggregates (‘agg(Op, Template, Goals, Result)’) with
     lower-strata dependencies (‘Op’ in ‘count’, ‘sum’, ‘min’, ‘max’)

   - safe rules (‘Head’ and negated literal variables must appear in
     positive ‘Body’ literals)

   - fixpoint materialization

   - incremental updates using support-count based propagation

   - simple explanations for derived facts

   - rule management (‘add_rule/3’, ‘remove_rule/1’)

   - transaction support (‘begin/0’, ‘commit/0’, ‘rollback/0’)

   - stratum introspection (‘predicate_stratum/3’, ‘strata/1’)

   - rule body normalization (positive ground literals first, then
     positive non-ground, then aggregates, then negation)


File: TheLogtalkHandbook-3.101.0.info,  Node: Public API overview,  Next: Basic usage,  Prev: Scope<3>,  Up: datalog

6.46.5 Public API overview
--------------------------

   - lifecycle: ‘clear/0’, ‘load_program/1’, ‘materialize/0’

   - rule management: ‘add_rule/3’, ‘remove_rule/1’, ‘rules/1’

   - fact management: ‘assert_fact/1’, ‘retract_fact/1’, ‘facts/1’

   - querying and explanations: ‘query/1’, ‘query/2’, ‘explain/2’

   - updates: ‘update/3’

   - transactions: ‘begin/0’, ‘commit/0’, ‘rollback/0’

   - stratification introspection: ‘predicate_stratum/3’, ‘strata/1’

Rules and facts are represented as terms:

   - ‘rule(Id, Head, Body)’ where ‘Body’ is a list of ‘Literal’ terms:

        - positive literal: ‘Term’

        - negative literal: ‘neg(Term)’

        - aggregate literal: ‘agg(Op, Template, Goals, Result)’ where
          ‘Op’ is one of ‘count’, ‘sum’, ‘min’, ‘max’

   - ‘fact(Fact)’ for extensional database (EDB) facts

Aggregate notes:

   - Aggregate dependencies are required to be in lower strata.

   - ‘min’ and ‘max’ require at least one matching value; otherwise no
     fact is derived.

   - Incremental updates involving negation or aggregates currently
     fallback to full rematerialization for correctness.


File: TheLogtalkHandbook-3.101.0.info,  Node: Basic usage,  Next: Limitations<3>,  Prev: Public API overview,  Up: datalog

6.46.6 Basic usage
------------------

     | ?- logtalk_load(datalog(loader)).
     ...

     | ?- Program = [
             rule(path_base, path(X,Y), [edge(X,Y)]),
             rule(path_rec, path(X,Z), [edge(X,Y), path(Y,Z)]),
             fact(edge(a,b)),
             fact(edge(b,c))
         ],
         datalog::load_program(Program),
         datalog::query(path(a,c)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Limitations<3>,  Prev: Basic usage,  Up: datalog

6.46.7 Limitations
------------------

This first version intentionally keeps the implementation simple and
portable.  Negation support is currently limited to stratified programs.
Aggregates and cost-based optimization are planned future enhancements.
Aggregate support is currently limited to ‘count’, ‘sum’, ‘min’, and
‘max’.


File: TheLogtalkHandbook-3.101.0.info,  Node: dates,  Next: dates_tz,  Prev: datalog,  Up: Libraries

6.47 ‘dates’
============

The ‘date’ object implements some useful calendar date predicates.

It also provides portable predicates for date-time handling, including:

   - Unix epoch conversions (‘date_time_to_unix/2’,
     ‘unix_to_date_time/2’)

   - date-time arithmetic with durations (‘add_duration/3’,
     ‘subtract_duration/3’, ‘duration_between/3’)

   - UTC/local conversion using explicit offsets (‘utc_to_local/3’,
     ‘local_to_utc/3’)

   - date-time formatting with explicit offsets (‘format_date_time/4’)

   - calendar utilities (‘day_of_year/2’, ‘week_of_year_iso/2’,
     ‘weekday/2’)

   - reverse and positional calendar utilities (‘day_of_year_date/3’,
     ‘month_weekday_date/5’)

   - date-time normalization and validation (‘normalize_date_time/2’,
     ‘valid_date_time/1’)

   - date-time comparison (‘before/2’, ‘after/2’, ‘same_instant/2’,
     ‘compare_date_time/3’)

The duration predicates accept two duration representations:

   - ‘duration(Days, Hours, Minutes, Seconds)’ — a fixed-length duration
     converted to seconds

   - ‘duration(Years, Months, Days, Hours, Minutes, Seconds)’ — a
     calendar-aware period where the year and month delta is applied
     first using calendar arithmetic, clamping the day to the last valid
     day of the resulting month when necessary (e.g.  adding one month
     to January 31 gives February 28 or 29 depending on the year), with
     the remaining day and time delta applied via fixed-length
     arithmetic.  The ‘duration_between/3’ predicate returns this form
     when called with a 6-arity skeleton such as ‘duration(Yr, Mo, Da,
     Hr, Mi, Se)’.

Date-time values are represented using the ‘date_time/6’ compound term:

   - ‘date_time(Year, Month, Day, Hours, Minutes, Seconds)’

The ‘format_date_time/4’ predicate currently supports the named formats
‘rfc3339’, ‘iso8601’, ‘atom’, ‘rfc2822’, ‘rfc5322’, ‘rss’, ‘http_date’,
‘rfc1123’, ‘unix_date’, ‘common_log’, ‘date_short’, ‘date_medium’,
‘date_long’, ‘date_full’, ‘time_short’, ‘time_medium’, ‘time_long’,
‘time_full’, ‘date_time_short’, ‘date_time_medium’, ‘date_time_long’,
and ‘date_time_full’.

The explicit offset argument is given in seconds.  Formats that include
numeric offsets require offsets representable in whole minutes.  The
‘http_date’ and ‘rfc1123’ formats always normalize the output to ‘GMT’.

The style presets are currently English-only presentation formats:

   - ‘date_short’ -> ‘2026-04-08’

   - ‘date_medium’ -> ‘8 Apr 2026’

   - ‘date_long’ -> ‘April 8, 2026’

   - ‘date_full’ -> ‘Tuesday, April 8, 2026’

   - ‘time_short’ -> ‘13:45’

   - ‘time_medium’ -> ‘13:45:30’

   - ‘time_long’ -> ‘13:45:30 +01:00’

   - ‘time_full’ -> ‘1:45:30 PM +01:00’

   - ‘date_time_short’ -> ‘2026-04-08 13:45’

   - ‘date_time_medium’ -> ‘8 Apr 2026 13:45:30’

   - ‘date_time_long’ -> ‘April 8, 2026 1:45:30 PM +01:00’

   - ‘date_time_full’ -> ‘Tuesday, April 8, 2026 1:45:30 PM +01:00’

The ‘time’ object implements some useful time predicates.

Please note that the functionality of these objects depends on the
chosen Prolog support for accessing the operating system time and date.

* Menu:

* API documentation: API documentation<66>.
* Loading: Loading<67>.
* Testing: Testing<62>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<66>,  Next: Loading<67>,  Up: dates

6.47.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#dates’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<67>,  Next: Testing<62>,  Prev: API documentation<66>,  Up: dates

6.47.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ utility
file:

     | ?- logtalk_load(dates(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<62>,  Prev: Loading<67>,  Up: dates

6.47.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(dates(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: dates_tz,  Next: dbscan_clusterer,  Prev: dates,  Up: Libraries

6.48 ‘dates_tz’
===============

Bridge library linking the ‘dates’ and ‘tzif’ libraries for zone-aware
date-time conversions.  Provides predicates that convert UTC date-times
to civil local date-times and vice-versa, handling DST transitions
including ambiguous (fold) and non-existent (gap) times.  Also provides
cross-zone conversion that routes through UTC as an intermediate
representation.

This library requires unbounded integer arithmetic support from the
backend Prolog compiler (as does the ‘tzif’ library it depends on).  It
is not available on backends where the ‘bounded’ Prolog flag is ‘true’.

* Menu:

* API documentation: API documentation<67>.
* Loading: Loading<68>.
* Testing: Testing<63>.
* Usage: Usage<28>.
* Examples: Examples<168>.
* Notes: Notes<3>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<67>,  Next: Loading<68>,  Up: dates_tz

6.48.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#dates_tz’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<68>,  Next: Testing<63>,  Prev: API documentation<67>,  Up: dates_tz

6.48.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ utility
file:

     | ?- logtalk_load(dates_tz(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<63>,  Next: Usage<28>,  Prev: Loading<68>,  Up: dates_tz

6.48.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(dates_tz(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<28>,  Next: Examples<168>,  Prev: Testing<63>,  Up: dates_tz

6.48.4 Usage
------------

Zone data must be loaded separately into the ‘tzif’ cache before calling
any ‘dates_tz’ predicates.  For example:

     :- initialization((
         logtalk_load(dates_tz(loader)),
         tzif::load(file('/usr/share/zoneinfo/America/New_York', 'America/New_York')),
         tzif::load(directory('/usr/share/zoneinfo'))
     )).


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<168>,  Next: Notes<3>,  Prev: Usage<28>,  Up: dates_tz

6.48.5 Examples
---------------

Convert a UTC ‘date_time/6’ compound to the civil local date-time in the
named IANA zone.  The UTC instant always has exactly one local
representation.

     |?- dates_tz::utc_to_local_tz(date_time(2024,1,15,12,0,0), 'America/New_York', Local).
     Local = date_time(2024,1,15,7,0,0).

Convert a civil local ‘date_time/6’ compound in the named zone to UTC
using strict interpretation.  Fails silently if the local time falls in
a DST gap (non-existent) or a DST fold (ambiguous).  Throws an error if
the zone is not cached.

     | ?- dates_tz::local_to_utc_tz(date_time(2024,1,15,7,0,0), 'America/New_York', UTC).
     UTC = date_time(2024,1,15,12,0,0).

Convert a civil local date-time to UTC with an explicit resolution mode.
The mode can be:

   - ‘strict’ — fail unless exactly one interpretation exists

   - ‘first’ — prefer the earliest valid interpretation (earliest UTC
     instant)

   - ‘second’ — prefer the latest valid interpretation (latest UTC
     instant)

   - ‘all’ — enumerate all valid interpretations in chronological order
     (non-deterministic)

Fall-back fold in New York: 2024-11-03 01:30 occurs twice:

     | ?- dates_tz::local_to_utc_tz_with_resolution(
          date_time(2024,11,3,1,30,0), 'America/New_York', first, UTC).
     UTC = date_time(2024,11,3,5,30,0).  % EDT interpretation

     | ?- dates_tz::local_to_utc_tz_with_resolution(
          date_time(2024,11,3,1,30,0), 'America/New_York', second, UTC).
     UTC = date_time(2024,11,3,6,30,0).  % EST interpretation

Convert a civil local date-time from one IANA zone to another, routing
through UTC. Uses strict interpretation for the source zone: fails if
the source local time is ambiguous or non-existent.  Requires both zones
to be cached.

     | ?- dates_tz::convert_zones(
          date_time(2024,1,15,7,0,0), 'America/New_York', 'Asia/Kathmandu', Result).
     Result = date_time(2024,1,15,17,45,0).

Convert a civil local date-time between zones with an explicit
resolution mode applied to the source zone.  Useful when the source
local time may be ambiguous due to a DST transition.

     | ?- dates_tz::convert_zones_with_resolution(
          date_time(2024,11,3,1,30,0), 'America/New_York', first, 'Asia/Kathmandu', Result).
     Result = date_time(2024,11,3,11,15,0).


File: TheLogtalkHandbook-3.101.0.info,  Node: Notes<3>,  Prev: Examples<168>,  Up: dates_tz

6.48.6 Notes
------------

   - Date-time values are represented as ‘date_time(Year, Month, Day,
     Hour, Minute, Second)’ compounds, consistent with the ‘dates’
     library.

   - UTC offset arithmetic is performed via integer seconds using
     ‘date::add_duration/3’ and ‘date::subtract_duration/3’.

   - This library does not provide a system clock or current-time
     predicate.  Use the ‘dates’ library’s ‘date::now/6’ or equivalent
     for the current time.

   - For performance when converting many instants in the same zone,
     load all required zones once at startup and keep them in the ‘tzif’
     cache.


File: TheLogtalkHandbook-3.101.0.info,  Node: dbscan_clusterer,  Next: dependents,  Prev: dates_tz,  Up: Libraries

6.49 ‘dbscan_clusterer’
=======================

DBSCAN clusterer.  Uses deterministic density-based clustering based on
epsilon neighborhoods and minimum point counts.  Supports continuous
attributes only.

The library implements the ‘clusterer_protocol’ defined in the
‘clustering_protocols’ library.  It provides predicates for learning a
clusterer from a dataset, assigning new instances to clusters, and
exporting the learned clusterer as a list of predicate clauses or to a
file.

Datasets are represented as objects implementing the
‘clustering_dataset_protocol’ protocol from the ‘clustering_protocols’
library.

* Menu:

* API documentation: API documentation<68>.
* Loading: Loading<69>.
* Testing: Testing<64>.
* Features: Features<13>.
* Options: Options<12>.
* Clusterer representation: Clusterer representation<2>.
* References: References<9>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<68>,  Next: Loading<69>,  Up: dbscan_clusterer

6.49.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#dbscan_clusterer’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<69>,  Next: Testing<64>,  Prev: API documentation<68>,  Up: dbscan_clusterer

6.49.2 Loading
--------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(dbscan_clusterer(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<64>,  Next: Features<13>,  Prev: Loading<69>,  Up: dbscan_clusterer

6.49.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(dbscan_clusterer(tester)).

To run the performance benchmark suite, load the
‘tester_performance.lgt’ file:

     | ?- logtalk_load(dbscan_clusterer(tester_performance)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<13>,  Next: Options<12>,  Prev: Testing<64>,  Up: dbscan_clusterer

6.49.4 Features
---------------

   - 'Density-Based Clustering': Learns density-connected clusters using
     epsilon neighborhoods and minimum point counts.

   - 'Adaptive Neighborhood Indexing': Builds a low-dimensional
     epsilon-grid index when it is likely to be cheaper and otherwise
     falls back to a deterministic metric tree.  The metric-tree path
     uses adaptive leaf sizing, balanced tie-aware subtree splits,
     selectable exact or heuristic pivot scoring, and lower-allocation
     range-query traversal.

   - 'Continuous Datasets': Accepts datasets containing only continuous
     attributes.

   - 'Distance Metrics': Supports ‘euclidean’ and ‘manhattan’ distances.

   - 'Optional Feature Scaling': Continuous attributes can be
     standardized using z-score scaling.

   - 'Reachable-Core Prediction': New instances are assigned to the
     cluster of the nearest reachable core point within the learned
     epsilon radius; otherwise the atom ‘noise’ is returned.

   - 'Portable Export': Learned clusterers can be exported as clauses or
     files and reused later.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<12>,  Next: Clusterer representation<2>,  Prev: Features<13>,  Up: dbscan_clusterer

6.49.5 Options
--------------

The following options can be passed to the ‘learn/3’ predicate:

   - ‘epsilon(Epsilon)’: Neighborhood radius used to determine density
     connectivity.  Default is ‘1.0’.

   - ‘minimum_points(MinimumPoints)’: Minimum number of points in an
     epsilon neighborhood for a core point.  Default is ‘2’.

   - ‘distance_metric(Metric)’: Distance metric to use.  Options:
     ‘euclidean’ (default) or ‘manhattan’.

   - ‘feature_scaling(FeatureScaling)’: Whether to standardize
     continuous attributes before clustering.  Options: ‘on’ (default)
     or ‘off’.

   - ‘pivot_scoring(PivotScoring)’: Metric-tree pivot scoring strategy.
     Options: ‘heuristic’ (default, single-pass dispersion scoring with
     one final sort) or ‘exact’ (more expensive gap-and-range scoring
     that sorts each candidate profile).


File: TheLogtalkHandbook-3.101.0.info,  Node: Clusterer representation<2>,  Next: References<9>,  Prev: Options<12>,  Up: dbscan_clusterer

6.49.6 Clusterer representation
-------------------------------

The learned clusterer is represented as a compound term with the functor
chosen by the user when exporting the clusterer and arity 4.  For
example:

     dbscan_clusterer(Encoders, Clusters, Noise, Options)

Where:

   - ‘Encoders’: List of continuous attribute encoders storing attribute
     name, mean, and scale.

   - ‘Clusters’: List of ‘cluster(Id, CorePoints, BorderPoints)’ terms
     in cluster-id order.

   - ‘Noise’: List of encoded training points classified as noise.

   - ‘Options’: Effective training options used to learn the clusterer.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<9>,  Prev: Clusterer representation<2>,  Up: dbscan_clusterer

6.49.7 References
-----------------

  1. Ester, Kriegel, Sander, and Xu (1996) - “A Density-Based Algorithm
     for Discovering Clusters in Large Spatial Databases with Noise”.
     KDD, 226-231.


File: TheLogtalkHandbook-3.101.0.info,  Node: dependents,  Next: deques,  Prev: dbscan_clusterer,  Up: Libraries

6.50 ‘dependents’
=================

The ‘observer’ and ‘subject’ categories implement the Smalltalk
dependents handling mechanism.  This mechanism can be used as an
alternative to Logtalk system-wide support for event-driven programming.

* Menu:

* API documentation: API documentation<69>.
* Loading: Loading<70>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<69>,  Next: Loading<70>,  Up: dependents

6.50.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#dependents’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<70>,  Prev: API documentation<69>,  Up: dependents

6.50.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ utility
file:

     | ?- logtalk_load(dependents(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: deques,  Next: derangements,  Prev: dependents,  Up: Libraries

6.51 ‘deques’
=============

This library implements double-ended queues, deques.  The queue
representation should be regarded as an opaque term and only accessed
using this library predicates.

* Menu:

* API documentation: API documentation<70>.
* Loading: Loading<71>.
* Testing: Testing<65>.
* Usage: Usage<29>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<70>,  Next: Loading<71>,  Up: deques

6.51.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#deques’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<71>,  Next: Testing<65>,  Prev: API documentation<70>,  Up: deques

6.51.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(deques(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<65>,  Next: Usage<29>,  Prev: Loading<71>,  Up: deques

6.51.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(deques(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<29>,  Prev: Testing<65>,  Up: deques

6.51.4 Usage
------------

To create a new deque, use the ‘new/1’ predicate:

     | ?- deque::new(Deque).
     Deque = ...
     yes

Elements can be added and removed both at the front and at the back of
the deque using the ‘push_front/3’, ‘push_back/3’, ‘pop_front/3’, and
‘pop_back/3’, predicates.  For example:

     | ?- deque::(as_deque([1,2,3], Deque0), push_front(0, Deque0, Deque)).
     Deque0 = ...,
     Deque = ...
     yes

We can also peek at the front and back of the deque using the
‘peek_front/2’ and ‘peek_back/2’ predicates.  For example:

     | ?- deque::(as_deque([1,2,3], Deque), peek_back(Deque, Element)).
     Deque = ...,
     Element = 3
     yes

Mapping a closure over all elements of a deque can be done using the
‘map/2’ and ‘map/3’ predicates.  For example:

     | ?- deque::(as_deque([1,2,3], Deque), map(write, Deque)).
     123
     Deque = ...
     yes

For details on these and other provided predicates, consult the library
API documentation.


File: TheLogtalkHandbook-3.101.0.info,  Node: derangements,  Next: dictionaries,  Prev: deques,  Up: Libraries

6.52 ‘derangements’
===================

This library provides predicates for generating and querying
derangements over lists.  Derangements are full-length permutations
where no result element is identical to the input element at the same
position.  The following categories of predicates are provided:

   - 'Generation operations' - Predicates for generating derangements.

   - 'Ordering variants' - Predicates that support an additional order
     argument (‘default’, ‘lexicographic’, or ‘shortlex’) for
     controlling output order.

   - 'Distinct-value generation' - Predicates for generating
     derangements while deduplicating equal-valued results.

   - 'Indexed access' - Predicates for direct access to derangements at
     specific positions, including distinct derangements.

   - 'Lexicographic stepping' - Predicates for navigating derangements
     in lexicographic order.

   - 'Counting operations' - Predicates for counting derangements and
     distinct derangements.

   - 'Random selection' - Predicates for randomly selecting and sampling
     derangements and distinct derangements.

Dedicated ‘permutations’, ‘arrangements’, ‘cartesian_products’,
‘combinations’, ‘multisets’, ‘partitions’, and ‘subsequences’ libraries
are also available for focused APIs on related operations.

* Menu:

* API documentation: API documentation<71>.
* Loading: Loading<72>.
* Testing: Testing<66>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<71>,  Next: Loading<72>,  Up: derangements

6.52.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#derangements’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<72>,  Next: Testing<66>,  Prev: API documentation<71>,  Up: derangements

6.52.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(derangements(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<66>,  Prev: Loading<72>,  Up: derangements

6.52.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(derangements(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: dictionaries,  Next: dif,  Prev: derangements,  Up: Libraries

6.53 ‘dictionaries’
===================

This library provides a dictionary (also known as associative array,
map, or symbol table) protocol and binary tree, AVL tree, Red–Black
tree, splay tree, ad 2-3 tree implementations.  The different
representations of a dictionary should be regarded as opaque terms and
only accessed using the library predicates.

* Menu:

* API documentation: API documentation<72>.
* Loading: Loading<73>.
* Testing: Testing<67>.
* Usage: Usage<30>.
* Credits: Credits<2>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<72>,  Next: Loading<73>,  Up: dictionaries

6.53.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#dictionaries’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<73>,  Next: Testing<67>,  Prev: API documentation<72>,  Up: dictionaries

6.53.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(dictionaries(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<67>,  Next: Usage<30>,  Prev: Loading<73>,  Up: dictionaries

6.53.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(dictionaries(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<30>,  Next: Credits<2>,  Prev: Testing<67>,  Up: dictionaries

6.53.4 Usage
------------

First, select the dictionary implementation that you want to use.  For
cases where the number of elements is relatively small and performance
is not critical, ‘bintree’ can be a good choice.  For other cases,
‘avltree’, ‘rbtree’, or ‘two3tree’ are likely better choices.  The
‘splaytree’ implementation can be a good choice when recently accessed
elements are likely to be accessed again, as it moves accessed elements
closer to the root.  If you want to compare the performance of the
implementations, either define an object alias or use a ‘uses/2’
directive so that you can switch between implementations by simply
changing the alias definition or the first argument of the directive.
Note that you can switch between implementations at runtime without code
changes by using a parameter variable in the first argument of a
‘uses/2’ directive.

Dictionary keys should preferably be ground terms.  If the keys contain
variables, the user must ensure that any instantiation of those
variables when calling this library predicates will not affect the key
ordering.

To create a new dictionary, you can use the ‘new/1’ predicate.  For
example:

     | ?- avltree::new(Dictionary).
     Dictionary = ...
     yes

You can also create a new dictionary from a list of key-value pairs by
using the ‘as_dictionary/2’ predicate.  For example:

     | ?- avltree::as_dictionary([a-1,c-3,b-2], Dictionary).
     Dictionary = ...
     yes

Several predicates are provided for inserting key-value pairs, lookup
key-value pairs updating the value associated with a key, and deleting
key-value pairs.  For example:

     | ?- avltree::(
             new(Dictionary0),
             insert(Dictionary0, a, 1, Dictionary1),
             update(Dictionary1, a, 2, Dictionary2),
             lookup(a, Value, Dictionary2)
         ).
     Dictionary0 = ...,
     Dictionary1 = ...,
     Dictionary2 = ...,
     Value = 2
     yes

For details on these and other provided predicates, consult the library
API documentation.


File: TheLogtalkHandbook-3.101.0.info,  Node: Credits<2>,  Prev: Usage<30>,  Up: dictionaries

6.53.5 Credits
--------------

The AVL tree implementation is an adaptation to Logtalk of the ‘assoc’
SWI-Prolog library authored by R.A.O’Keefe, L.Damas, V.S.Costa, Glenn
Burgess, Jiri Spitz, and Jan Wielemaker.  Additional predicates authored
by Paulo Moura.

The Red–Black tree implementation is an adaptation to Logtalk of the
‘rbtrees’ Prolog library authored by Vitor Santos Costa.

The 2-3 tree implementation is a contribution by Michael T. Richter.


File: TheLogtalkHandbook-3.101.0.info,  Node: dif,  Next: dimension_reduction_protocols,  Prev: dictionaries,  Up: Libraries

6.54 ‘dif’
==========

The ‘dif’ object provides a portable abstraction over how the ‘dif/2’
predicate is made available by the supported backend Prolog systems that
implement it (B-Prolog, ECLiPSe, SICStus Prolog, SWI-Prolog, Trealla
Prolog, XSB, XVM, and YAP).

Calls to the library predicates are inlined when compiled with the
‘optimize’ flag turned on.  In this case, there is no overhead compared
with calling the abstracted predicate directly.

See also the ‘coroutining’ library.

* Menu:

* API documentation: API documentation<73>.
* Loading: Loading<74>.
* Testing: Testing<68>.
* Usage: Usage<31>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<73>,  Next: Loading<74>,  Up: dif

6.54.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#dif’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<74>,  Next: Testing<68>,  Prev: API documentation<73>,  Up: dif

6.54.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(dif(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<68>,  Next: Usage<31>,  Prev: Loading<74>,  Up: dif

6.54.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(dif(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<31>,  Prev: Testing<68>,  Up: dif

6.54.4 Usage
------------

Load this library from your application loader file.  To call the
‘dif/1-2’ predicates using implicit message-sending, add the following
directive to any object or category calling the predicates:

     :- uses(dif, [
         dif/2, dif/1
     ]).


File: TheLogtalkHandbook-3.101.0.info,  Node: dimension_reduction_protocols,  Next: eclat_pattern_miner,  Prev: dif,  Up: Libraries

6.55 ‘dimension_reduction_protocols’
====================================

This library provides protocols and reusable support predicates used in
the implementation of machine learning dimension reduction algorithms.
Unsupervised datasets are represented as objects implementing the
‘dimension_reduction_dataset_protocol’ protocol.  Labeled datasets for
supervised reducers such as Linear Discriminant Analysis are represented
as objects implementing the
‘supervised_dimension_reduction_dataset_protocol’ protocol.
Target-valued datasets for reducers such as partial least squares
projections are represented as objects implementing the
‘target_supervised_dimension_reduction_dataset_protocol’ protocol.
Dimension reducers are represented as objects importing the
‘dimension_reducer_common’ category.

This library also provides reusable test datasets and a small smoke-test
suite.

Concrete dimension reduction algorithms are intentionally out of scope
for this package.  The goal is to provide a portable foundation for
libraries such as ‘pca_projection’, ‘truncated_svd_projection’,
‘random_projection’, ‘nmf_projection’, ‘lda_projection’, and
‘pls_projection’, including shared reducer helpers for common tasks such
as feature encoding, projection, reducer validation, diagnostics,
export, and pretty-printing.

Exported reducers are serialized protocol-wide as single-argument
predicates such as ‘reducer(Reducer)’, allowing the saved reducer term
to be loaded and passed directly to ‘transform/3’.

All reducers importing the shared category are also expected to record a
diagnostics list containing at least ‘model/1’ and ‘options/1’ terms.
The shared protocol surface exposes this metadata using the
‘diagnostics/2’, ‘diagnostic/2’, and ‘dimension_reducer_options/2’
predicates and validates serialized reducers using
‘check_dimension_reducer/1’.

* Menu:

* API documentation: API documentation<74>.
* Loading: Loading<75>.
* Common options::
* Testing: Testing<69>.
* Test datasets: Test datasets<4>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<74>,  Next: Loading<75>,  Up: dimension_reduction_protocols

6.55.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#dimension_reduction_protocols’
link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<75>,  Next: Common options,  Prev: API documentation<74>,  Up: dimension_reduction_protocols

6.55.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(dimension_reduction_protocols(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Common options,  Next: Testing<69>,  Prev: Loading<75>,  Up: dimension_reduction_protocols

6.55.3 Common options
---------------------

The ‘dimension_reducer_common’ category supports the ‘feature_scaling/1’
option used by importing reducers to control continuous feature
normalization before projection:

   - ‘feature_scaling(true)’ standardizes each continuous attribute
     using its training-set mean and standard deviation.

   - ‘feature_scaling(false)’ only centers each continuous attribute
     using its training-set mean.

The current ‘pca_projection’, ‘random_projection’, ‘lda_projection’, and
‘pls_projection’ libraries all define ‘feature_scaling(true)’ as their
default.

Reducers can also specialize preprocessing behavior.  For example, the
‘nmf_projection’ library only supports ‘center(false)’ because the
learned feature representation must remain non-negative.


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<69>,  Next: Test datasets<4>,  Prev: Common options,  Up: dimension_reduction_protocols

6.55.4 Testing
--------------

To run the library smoke tests, load the ‘tester.lgt’ file:

     | ?- logtalk_load(dimension_reduction_protocols(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Test datasets<4>,  Prev: Testing<69>,  Up: dimension_reduction_protocols

6.55.5 Test datasets
--------------------

Several sample datasets are included in the ‘test_datasets’ directory:

   - ‘correlated_plane.lgt’ — A compact continuous dataset with 8
     examples and 3 continuous attributes (‘x’, ‘y’, ‘z’) where the
     features are strongly correlated.  It is intended for PCA and
     projection smoke tests.

   - ‘high_dimensional_measurements.lgt’ — A small continuous dataset
     with 10 examples and 6 continuous attributes (‘f1’ through ‘f6’).
     It is intended for testing projected dimensionality and reducer
     output shape.

   - ‘low_rank_rectangular.lgt’ — A compact continuous dataset with 4
     examples and 3 continuous attributes whose third feature is the sum
     of the first two.  It is intended for testing matrix-rank
     truncation and singular-value-based reducers such as
     ‘truncated_svd_projection’.

   - ‘labeled_measurements.lgt’ — A compact labeled continuous dataset
     with 9 examples, 4 continuous attributes (‘length’, ‘width’,
     ‘height’, ‘weight’), and 3 class labels (‘alpha’, ‘beta’, ‘gamma’).
     It is intended for testing supervised reducers such as
     ‘lda_projection’.

   - ‘parts_based_measurements.lgt’ — A compact non-negative continuous
     dataset with 5 examples and 4 continuous attributes (‘f1’ through
     ‘f4’) built from two latent additive parts.  It is intended for
     testing parts-based reducers such as ‘nmf_projection’.

   - ‘target_latent_measurements.lgt’ — A compact target-valued
     continuous dataset with 6 examples, 4 continuous attributes (‘f1’
     through ‘f4’), and a numeric target attribute (‘score’) influenced
     by two latent directions.  It is intended for testing
     target-supervised reducers such as ‘pls_projection’.

   - Target-supervised smoke coverage is currently provided by the
     ‘target_measurements’ object in the library smoke tests, which
     exercises the
     ‘target_supervised_dimension_reduction_dataset_protocol’ contract.


File: TheLogtalkHandbook-3.101.0.info,  Node: eclat_pattern_miner,  Next: edcg,  Prev: dimension_reduction_protocols,  Up: Libraries

6.56 ‘eclat_pattern_miner’
==========================

Eclat frequent itemset miner for transaction datasets.  Normalizes
dataset transaction identifiers to internal ascending ordinals, builds
vertical tidsets for frequent singleton items, and recursively extends
them by lexicographic suffix joins and tidset intersections.

This library depends on the ‘frequent_pattern_mining_protocols’ support
library, implements the generic ‘pattern_miner_protocol’ defined in the
‘pattern_mining_protocols’ core library.

Requires a dataset implementing ‘transaction_dataset_protocol’ with
transactions represented as canonical sorted lists of unique declared
items.  External transaction identifiers are treated as opaque metadata
and normalized to internal ordinals before tidset construction.

* Menu:

* API documentation: API documentation<75>.
* Loading: Loading<76>.
* Testing: Testing<70>.
* Features: Features<14>.
* Options: Options<13>.
* Pattern miner representation: Pattern miner representation<3>.
* References: References<10>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<75>,  Next: Loading<76>,  Up: eclat_pattern_miner

6.56.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#eclat_pattern_miner’ link in a
web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<76>,  Next: Testing<70>,  Prev: API documentation<75>,  Up: eclat_pattern_miner

6.56.2 Loading
--------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(eclat_pattern_miner(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<70>,  Next: Features<14>,  Prev: Loading<76>,  Up: eclat_pattern_miner

6.56.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(eclat_pattern_miner(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<14>,  Next: Options<13>,  Prev: Testing<70>,  Up: eclat_pattern_miner

6.56.4 Features
---------------

   - 'Vertical Tidsets': Represents each frequent extension by the
     sorted list of transaction identifiers containing it.

   - 'Transaction Ordinal Normalization': Treats external transaction
     identifiers as opaque metadata and normalizes them to internal
     ascending ordinals before building vertical tidsets.

   - 'Depth-First Mining': Extends frequent prefixes recursively using
     tidset intersections.

   - 'Canonical Transactions': Validates that transactions are sorted,
     duplicate-free, and restricted to declared items.

   - 'Flexible Support Thresholds': Supports relative minimum support
     and absolute minimum support count.  When both are given, the
     absolute-count threshold takes precedence.

   - 'Model Export': Mined pattern collections can be exported as
     predicate clauses or written to a file.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<13>,  Next: Pattern miner representation<3>,  Prev: Features<14>,  Up: eclat_pattern_miner

6.56.5 Options
--------------

The ‘mine/3’ predicate accepts the following options:

   - ‘minimum_support/1’: Relative minimum support threshold in the
     interval ‘]0.0, 1.0]’.  The default is ‘0.5’.

   - ‘minimum_support_count/1’: Absolute minimum support count.  When
     both support options are provided, this option takes precedence.

   - ‘maximum_pattern_length/1’: Maximum itemset length to mine.  The
     default is ‘1000’, which is effectively capped by the longest
     transaction in the dataset.

   - ‘minimum_pattern_length/1’: Minimum itemset length retained in the
     mined result.  The default is ‘1’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Pattern miner representation<3>,  Next: References<10>,  Prev: Options<13>,  Up: eclat_pattern_miner

6.56.6 Pattern miner representation
-----------------------------------

The mined pattern miner result is represented by a compound term with
the functor chosen by the implementation and arity 3.  For example:

     eclat_pattern_miner(ItemDomain, Patterns, Options)

Where:

   - ‘ItemDomain’: Canonical sorted list of declared dataset items.

   - ‘Patterns’: List of ‘itemset(Items, SupportCount)’ terms ordered
     first by pattern length and then lexicographically.

   - ‘Options’: Effective mining options used to mine the frequent
     itemsets.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<10>,  Prev: Pattern miner representation<3>,  Up: eclat_pattern_miner

6.56.7 References
-----------------

  1. Zaki, M. J. (2000) - “Scalable algorithms for association mining”.


File: TheLogtalkHandbook-3.101.0.info,  Node: edcg,  Next: elastic_net_regression,  Prev: eclat_pattern_miner,  Up: Libraries

6.57 ‘edcg’
===========

This library provides a Logtalk port of Peter Van Roy’s extended DCG
implementation.  For full documentation on EDCGs, see:

‘https://webperso.info.ucl.ac.be/~pvr/edcg.html’

This Logtalk version defines a hook object, ‘edcg’.  Source files
defining EDCGs must be compiled using the compiler option ‘hook(edcg)’:

     | ?- logtalk_load(source, [hook(edcg)]).

Alternatively, the following directive can be added at the beginning of
the source file containing the EDCGs:

     :- set_logtalk_flag(hook, edcg).

The hook object automatically adds the EDCGs ‘-->>’ infix operator
scoped to the source file.

This port has simplified by copying and then modifying Michael
Hendricks’s ‘edcg’ repo at:

‘https://github.com/mndrix/edcg’

A notable difference is that Michael’s version declares Peter’s original
predicates for declaring accumulators and predicates using the hidden
arguments as multifile predicates.  But this is risky as two independent
EDCGs may use e.g.  the same accumulator names and introduce conflicts.
The Logtalk version uses instead the ‘edcg’ hook object internal state
to temporarily save those predicates in order to parse the corresponding
EDCGs.

* Menu:

* API documentation: API documentation<76>.
* Loading: Loading<77>.
* Testing: Testing<71>.
* Usage: Usage<32>.
* Introduction::
* Syntax::
* Declaration of Predicates::
* Declaration of Accumulators::
* Declaration of Passed Arguments::
* Additional documentation::


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<76>,  Next: Loading<77>,  Up: edcg

6.57.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#edcg’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<77>,  Next: Testing<71>,  Prev: API documentation<76>,  Up: edcg

6.57.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ utility
file:

     | ?- logtalk_load(edcg(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<71>,  Next: Usage<32>,  Prev: Loading<77>,  Up: edcg

6.57.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file of the
‘edcgs’ example:

     | ?- logtalk_load(edcgs(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<32>,  Next: Introduction,  Prev: Testing<71>,  Up: edcg

6.57.4 Usage
------------

Follows the usage documentation written by Michael Hendricks (with a
contribution from Peter Ludemann), used here with permission, with the
necessary changes for the Logtalk port.

     % declare accumulators
     acc_info(adder, X, In, Out, integer::plus(X,In,Out)).

     % declare predicates using these hidden arguments
     pred_info(len,0,[adder,dcg]).
     pred_info(increment,0,[adder]).

     increment -->>
         % add one to the accumulator
         [1]:adder.


     len(Xs,N) :-
         len(0,N,Xs,[]).

     len -->>
         % 'dcg' accumulator has an element
         [_],
         !,
         % increment the 'adder' accumulator
         increment,
         len.
     len -->>
         [].


File: TheLogtalkHandbook-3.101.0.info,  Node: Introduction,  Next: Syntax,  Prev: Usage<32>,  Up: edcg

6.57.5 Introduction
-------------------

DCG notation gives us a single, hidden accumulator.  Extended DCG
notation (implemented by this library) lets predicates have arbitrarily
many hidden accumulators.  As demonstrated by the synopsis above, those
accumulators can be implemented with arbitrary goals (like
‘integer::plus/3’).

Benefits of this library:

   - avoid tedium and errors from manually threading accumulators
     through your predicates

   - add or remove accumulators with a single declaration

   - change the accumulator implementation with a single declaration
     (ex, switching from ordsets to rbtrees)


File: TheLogtalkHandbook-3.101.0.info,  Node: Syntax,  Next: Declaration of Predicates,  Prev: Introduction,  Up: edcg

6.57.6 Syntax
-------------

Extended DCG syntax is very similar to DCG notation.  An EDCG is created
with clauses whose neck is the ‘-->>’ operator.  The following syntax is
supported inside an EDCG clause:

   - ‘{Goal}’ - don’t expand any hidden arguments of ‘Goal’

   - ‘Goal’ - expand all hidden arguments of Goal that are also in the
     head.  Those hidden arguments not in the head are given default
     values.

   - ‘Goal:L’ - If ‘Goal’ has no hidden arguments then force the
     expansion of all arguments in ‘L’ in the order given.  If ‘Goal’
     has hidden arguments then expand all of them, using the contents of
     ‘L’ to override the expansion.  ‘L’ is either a term of the form
     ‘Acc’, ‘Acc(Left,Right)’, ‘Pass’, ‘Pass(Value)’, or a list of such
     terms.  When present, the arguments ‘Left’, ‘Right’, and ‘Value’
     override the default values of arguments not in the head.

   - ‘List:Acc’ - Accumulate a list of terms in the accumulator ‘Acc’

   - ‘List’ - Accumulate a list of terms in the accumulator ‘dcg’

   - ‘X/Acc’ - Unify ‘X’ with the left term for the accumulator ‘Acc’

   - ‘Acc/X’ - Unify ‘X’ with the right term for the accumulator ‘Acc’

   - ‘X/Acc/Y’ - Unify ‘X’ with the left and ‘Y’ with the right term for
     the accumulator ‘Acc’

   - ‘insert(X,Y):Acc’ - Insert the arguments ‘X’ and ‘Y’ into the chain
     implementing the accumulator ‘Acc’.  This is useful when the value
     of the accumulator changes radically because ‘X’ and ‘Y’ may be the
     arguments of an arbitrary relation

   - ‘insert(X,Y)’ - Insert the arguments ‘X’ and ‘Y’ into the chain
     implementing the accumulator ‘dcg’.  This inserts the difference
     list X-Y into the accumulated list


File: TheLogtalkHandbook-3.101.0.info,  Node: Declaration of Predicates,  Next: Declaration of Accumulators,  Prev: Syntax,  Up: edcg

6.57.7 Declaration of Predicates
--------------------------------

Predicates are declared with facts of the following form:

     pred_info(Name, Arity, List).

The predicate ‘Name/Arity’ has the hidden parameters given in ‘List’.
The parameters are added in the order given by ‘List’ and their names
must be atoms.


File: TheLogtalkHandbook-3.101.0.info,  Node: Declaration of Accumulators,  Next: Declaration of Passed Arguments,  Prev: Declaration of Predicates,  Up: edcg

6.57.8 Declaration of Accumulators
----------------------------------

Accumulators are declared with facts in one of two forms.  The short
form is:

     acc_info(Acc, Term, Left, Right, Joiner).

The long form is:

     acc_info(Acc, Term, Left, Right, Joiner, LStart, RStart).

In most cases the short form gives sufficient information.  It declares
the accumulator ‘Acc’, which must be an atom, along with the
accumulating function, ‘Joiner’, and its arguments ‘Term’, the term to
be accumulated, and ‘Left’ & ‘Right’, the variables used in chaining.

The long form of ‘acc_info’ is useful in more complex programs.  It
contains two additional arguments, ‘LStart’ and ‘RStart’, that are used
to give default starting values for an accumulator occurring in a body
goal that does not occur in the head.  The starting values are given to
the unused accumulator to ensure that it will execute correctly even
though its value is not used.  Care is needed to give correct values for
‘LStart’ and ‘RStart’.  For DCG-like list accumulation both may remain
unbound.

Two conventions are used for the two variables used in chaining
depending on which direction the accumulation is done.  For forward
accumulation, ‘Left’ is the input and ‘Right’ is the output.  For
reverse accumulation, ‘Right’ is the input and ‘Left’ is the output.


File: TheLogtalkHandbook-3.101.0.info,  Node: Declaration of Passed Arguments,  Next: Additional documentation,  Prev: Declaration of Accumulators,  Up: edcg

6.57.9 Declaration of Passed Arguments
--------------------------------------

Passed arguments are conceptually the same as accumulators with ‘=/2’ as
the joiner function.  Passed arguments are declared as facts in one of
two forms.  The short form is:

     pass_info(Pass).

The long form is:

     pass_info(Pass, PStart).

In most cases the short form is sufficient.  It declares a passed
argument ‘Pass’, that must be an atom.  The long form also contains the
starting value ‘PStart’ that is used to give a default value for a
passed argument in a body goal that does not occur in the head.  Most of
the time this situation does not occur.


File: TheLogtalkHandbook-3.101.0.info,  Node: Additional documentation,  Prev: Declaration of Passed Arguments,  Up: edcg

6.57.10 Additional documentation
--------------------------------

Peter Van Roy’s page: Declarative Programming with State(1)

Technical Report UCB/CSD-90-583 Extended DCG Notation: A Tool for
Applicative Programming in Prolog(2) by Peter Van Roy

   - The Tech Report’s PDF is here(3)

A short Wikipedia article(4) on DCGs and extensions.

   ---------- Footnotes ----------

   (1) https://webperso.info.ucl.ac.be/~pvr/edcg.html

   (2) https://www2.eecs.berkeley.edu/Pubs/TechRpts/1990/5471.html

   (3) https://www2.eecs.berkeley.edu/Pubs/TechRpts/1990/CSD-90-583.pdf

   (4) https://en.wikipedia.org/wiki/Definite_clause_grammar#Extensions


File: TheLogtalkHandbook-3.101.0.info,  Node: elastic_net_regression,  Next: elo_ranker,  Prev: edcg,  Up: Libraries

6.58 ‘elastic_net_regression’
=============================

Elastic net regression regressor supporting continuous and mixed-feature
datasets.  The library implements the ‘regressor_protocol’ defined in
the ‘regression_protocols’ library and learns a linear model using
cyclic coordinate descent with coefficient-wise soft-thresholding
updates and an additional L2 term in order to minimize mean squared
error plus a standard elastic net penalty.

* Menu:

* API documentation: API documentation<77>.
* Loading: Loading<78>.
* Testing: Testing<72>.
* Features: Features<15>.
* Regressor representation: Regressor representation<2>.
* Diagnostics syntax: Diagnostics syntax<6>.
* Options: Options<14>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<77>,  Next: Loading<78>,  Up: elastic_net_regression

6.58.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#elastic_net_regression’ link in
a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<78>,  Next: Testing<72>,  Prev: API documentation<77>,  Up: elastic_net_regression

6.58.2 Loading
--------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(elastic_net_regression(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<72>,  Next: Features<15>,  Prev: Loading<78>,  Up: elastic_net_regression

6.58.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(elastic_net_regression(tester)).

The unit test suite covers the default mixed-penalty behavior together
with the boundary cases ‘l1_ratio(0.0)’ and ‘l1_ratio(1.0)’.

To run the performance benchmark suite, load the
‘tester_performance.lgt’ file:

     | ?- logtalk_load(elastic_net_regression(tester_performance)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<15>,  Next: Regressor representation<2>,  Prev: Testing<72>,  Up: elastic_net_regression

6.58.4 Features
---------------

   - 'Continuous and Mixed Features': Supports continuous attributes and
     categorical attributes.

   - 'Feature Scaling': Continuous attributes can be standardized using
     z-score scaling.

   - 'Missing Values': Missing numeric and categorical values
     represented using anonymous variables are encoded using explicit
     missing-value indicator features.

   - 'Unknown Values': Prediction requests containing categorical values
     that are not declared by the dataset raise a domain error.

   - 'Mixed Penalty': Combines coefficient-wise L1 shrinkage with an L2
     penalty controlled by the ‘regularization/1’ and ‘l1_ratio/1’
     options, including the ridge-like ‘l1_ratio(0.0)’ and lasso-like
     ‘l1_ratio(1.0)’ endpoints.

   - 'Standard Encoding Semantics': Categorical attributes are encoded
     using reference-level dummy coding derived from the declared
     dataset attribute values, with a trailing missing-value indicator
     feature, and each encoded coefficient is regularized independently.

   - 'Diagnostics Metadata': Learned regressors record model name,
     target, training example count, optimization stop reason, completed
     iterations, final parameter delta, encoded feature count, and
     effective options, accessible using the shared regression
     diagnostics predicates.

   - 'Model Export': Learned regressors can be exported as predicate
     clauses or written to a file.

   - 'Reference Benchmarks': Includes a dedicated performance suite
     reporting training time, RMSE, and MAE for both zero-penalty
     baselines and explicit elastic-net runs on sparse, mixed,
     categorical, and wide mixed datasets.


File: TheLogtalkHandbook-3.101.0.info,  Node: Regressor representation<2>,  Next: Diagnostics syntax<6>,  Prev: Features<15>,  Up: elastic_net_regression

6.58.5 Regressor representation
-------------------------------

The learned regressor is represented by default as:

   - ‘elastic_net_regressor(Encoders, Bias, Weights, Diagnostics)’

The exported predicate clauses therefore use the shape:

   - ‘Functor(Encoders, Bias, Weights, Diagnostics)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Diagnostics syntax<6>,  Next: Options<14>,  Prev: Regressor representation<2>,  Up: elastic_net_regression

6.58.6 Diagnostics syntax
-------------------------

The ‘diagnostics/2’ predicate returns a list of metadata terms with the
form:

     [
         model(elastic_net_regression),
         target(Target),
         training_example_count(TrainingExampleCount),
         options(Options),
         convergence(Status),
         iterations(Iterations),
         final_delta(FinalDelta),
         encoded_feature_count(FeatureCount)
     ]

Where:

   - ‘model(elastic_net_regression)’ identifies the learning algorithm
     that produced the regressor.

   - ‘target(Target)’ stores the target attribute name declared by the
     training dataset.

   - ‘training_example_count(TrainingExampleCount)’ stores the number of
     examples used during training.

   - ‘options(Options)’ stores the effective learning options after
     merging the user options with the library defaults.

   - ‘convergence(Status)’ records the optimization stop condition.  The
     current values are ‘tolerance’ when the maximum Karush-Kuhn-Tucker
     optimality violation across the intercept and all encoded features
     is within the configured tolerance and
     ‘maximum_iterations_exhausted’ when training stops because the
     iteration cap is reached.

   - ‘iterations(Iterations)’ stores the number of coordinate-descent
     sweeps completed during training.

   - ‘final_delta(FinalDelta)’ stores the maximum Karush-Kuhn-Tucker
     optimality violation measured during the final optimization check.

   - ‘encoded_feature_count(FeatureCount)’ stores the number of numeric
     features induced by the encoder list, including missing-value
     indicator features.

Use the ‘regression_protocols’ ‘diagnostic/2’ and ‘regressor_options/2’
helper predicates when you only need a single metadata term or the
effective options.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<14>,  Prev: Diagnostics syntax<6>,  Up: elastic_net_regression

6.58.7 Options
--------------

The ‘learn/3’ predicate accepts the following options:

   - ‘maximum_iterations/1’: Maximum number of coordinate-descent sweeps
     to run before stopping even if the tolerance criterion has not been
     met.  The default is ‘2000’.

   - ‘tolerance/1’: Convergence threshold for the maximum
     Karush-Kuhn-Tucker optimality violation in a full
     coordinate-descent sweep.  Training stops early when both the
     intercept condition and all encoded-feature subgradient conditions
     are satisfied within this value.  The default is ‘1.0e-7’.

   - ‘regularization/1’: Overall penalty coefficient applied during
     optimization.  Higher values increase shrinkage and can reduce
     overfitting.  The default is ‘0.01’.

   - ‘l1_ratio/1’: Fraction of the overall penalty assigned to the L1
     part of the elastic net penalty.  The remaining fraction is
     assigned to the L2 part.  Accepted values are floats in the
     interval ‘[0.0, 1.0]’, where ‘0.0’ gives the ridge endpoint and
     ‘1.0’ gives the lasso endpoint.  The default is ‘0.5’.

   - ‘feature_scaling/1’: Controls z-score standardization of continuous
     attributes before training and prediction.  Accepted values are
     ‘true’ and ‘false’.  The default is ‘true’.


File: TheLogtalkHandbook-3.101.0.info,  Node: elo_ranker,  Next: events,  Prev: elastic_net_regression,  Up: Libraries

6.59 ‘elo_ranker’
=================

Elo pairwise preference ranker.  Processes the pairwise preference
stream in dataset enumeration order using the standard Elo
expected-score formula and symmetric rating updates after each observed
result.

The library implements the ‘ranker_protocol’ defined in the
‘ranking_protocols’ library.  It provides predicates for learning a
ranker from pairwise preferences, using it to order candidate items, and
exporting it as a list of predicate clauses or to a file.

Datasets are represented as objects implementing the
‘pairwise_ranking_dataset_protocol’ protocol from the
‘ranking_protocols’ library.  See the ‘test_datasets’ directory for
examples.  The current implementation requires a well-formed connected
pairwise dataset so that learned ratings remain globally comparable
across all ranked items.

* Menu:

* API documentation: API documentation<78>.
* Loading: Loading<79>.
* Testing: Testing<73>.
* Features: Features<16>.
* Rating semantics::
* Usage: Usage<33>.
* Options: Options<15>.
* Ranker representation: Ranker representation<5>.
* References: References<11>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<78>,  Next: Loading<79>,  Up: elo_ranker

6.59.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#elo_ranker’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<79>,  Next: Testing<73>,  Prev: API documentation<78>,  Up: elo_ranker

6.59.2 Loading
--------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(elo_ranker(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<73>,  Next: Features<16>,  Prev: Loading<79>,  Up: elo_ranker

6.59.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(elo_ranker(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<16>,  Next: Rating semantics,  Prev: Testing<73>,  Up: elo_ranker

6.59.4 Features
---------------

   - 'Pairwise Preference Learning': Learns one deterministic rating per
     item from pairwise outcomes.

   - 'Deterministic Batch Elo Semantics': Replays the dataset preference
     stream in enumeration order using the standard Elo expected-score
     formula.  Because the current pairwise dataset protocol does not
     record historical timestamps, the implementation is a deterministic
     batch interpretation of that enumeration order rather than a
     reconstruction of a literal chronological competition log.

   - 'Configurable Rating Parameters': Exposes the initial rating,
     K-factor, and rating scale as user options.

   - 'Integer Weight Fidelity': Preference weights must be positive
     integers and are replayed as repeated unit outcomes in dataset
     enumeration order.

   - 'Deterministic Ranking': Orders candidate items by learned rating
     with deterministic tie-breaking.

   - 'Strict Dataset Validation': Rejects duplicate items, undeclared
     items, self-preferences, non-positive weights, and disconnected
     comparison graphs.

   - 'Ranker Export': Learned rankers can be exported as self-contained
     terms.

   - 'Shared Ranking Infrastructure': Reuses the ‘ranking_protocols’
     helpers for option processing, dataset validation, diagnostics,
     export, and candidate ranking.


File: TheLogtalkHandbook-3.101.0.info,  Node: Rating semantics,  Next: Usage<33>,  Prev: Features<16>,  Up: elo_ranker

6.59.5 Rating semantics
-----------------------

This implementation uses a deterministic batch Elo interpretation over
the pairwise preference stream.  Each preference is processed in dataset
enumeration order.  For a winner with rating ‘R_w’ and a loser with
rating ‘R_l’, the expected winner score is computed as

     1 / (1 + 10^((R_l - R_w)/Scale))

and the winner receives a rating update of

     K * (1 - ExpectedWinnerScore)

with the loser receiving the symmetric negative update.

Because the current pairwise dataset protocol does not encode
timestamps, this is a deterministic batch Elo variant rather than a
literal historical competition-log replay.

Positive integer preference weights are replayed as repeated unit
outcomes.  Datasets using non-integer preference weights are rejected
because they do not map cleanly to standard Elo update semantics.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<33>,  Next: Options<15>,  Prev: Rating semantics,  Up: elo_ranker

6.59.6 Usage
------------

* Menu:

* Learning a ranker: Learning a ranker<5>.
* Inspecting diagnostics: Inspecting diagnostics<5>.
* Ranking candidate items: Ranking candidate items<5>.
* Exporting the ranker: Exporting the ranker<5>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Learning a ranker<5>,  Next: Inspecting diagnostics<5>,  Up: Usage<33>

6.59.6.1 Learning a ranker
..........................

     % Learn from a pairwise ranking dataset object
     | ?- elo_ranker::learn(my_dataset, Ranker).
     ...

     % Learn with custom Elo parameters
     | ?- elo_ranker::learn(my_dataset, Ranker, [initial_rating(1400.0), k_factor(24.0), rating_scale(200.0)]).
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Inspecting diagnostics<5>,  Next: Ranking candidate items<5>,  Prev: Learning a ranker<5>,  Up: Usage<33>

6.59.6.2 Inspecting diagnostics
...............................

     % Inspect model, options, and dataset summary metadata
     | ?- elo_ranker::learn(my_dataset, Ranker),
          elo_ranker::diagnostics(Ranker, Diagnostics).
     Diagnostics = [...]
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Ranking candidate items<5>,  Next: Exporting the ranker<5>,  Prev: Inspecting diagnostics<5>,  Up: Usage<33>

6.59.6.3 Ranking candidate items
................................

     % Rank a candidate set from most preferred to least preferred
     | ?- elo_ranker::learn(my_dataset, Ranker),
          elo_ranker::rank(Ranker, [item_a, item_b, item_c], Ranking).
     Ranking = [...]
     ...

Candidate lists must be proper lists of unique, ground items declared by
the training dataset.  Invalid ranker terms, duplicate candidates, and
candidates containing variables are rejected with errors instead of
being silently accepted.


File: TheLogtalkHandbook-3.101.0.info,  Node: Exporting the ranker<5>,  Prev: Ranking candidate items<5>,  Up: Usage<33>

6.59.6.4 Exporting the ranker
.............................

Learned rankers can be exported as a list of clauses or to a file for
later use.

     % Export as predicate clauses
     | ?- elo_ranker::learn(my_dataset, Ranker),
          elo_ranker::export_to_clauses(my_dataset, Ranker, my_ranker, Clauses).
     Clauses = [my_ranker(elo_ranker(...))]
     ...

     % Export to a file
     | ?- elo_ranker::learn(my_dataset, Ranker),
          elo_ranker::export_to_file(my_dataset, Ranker, my_ranker, 'ranker.pl').
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<15>,  Next: Ranker representation<5>,  Prev: Usage<33>,  Up: elo_ranker

6.59.7 Options
--------------

The following options can be passed to the ‘learn/3’ predicate:

   - ‘initial_rating(Rating)’: Initial rating assigned to every item.

   - ‘k_factor(KFactor)’: Positive Elo K-factor.

   - ‘rating_scale(Scale)’: Positive rating-scale denominator used in
     the expected-score formula.

Datasets supplied to the ranker must use positive integer preference
weights.  Non-integer weights are rejected.


File: TheLogtalkHandbook-3.101.0.info,  Node: Ranker representation<5>,  Next: References<11>,  Prev: Options<15>,  Up: elo_ranker

6.59.8 Ranker representation
----------------------------

The learned ranker is represented by a compound term of the form:

     elo_ranker(Items, Ratings, Diagnostics)

Where:

   - ‘Items’: List of ranked items.

   - ‘Scores’: List of ‘Item-Rating’ pairs.

   - ‘Diagnostics’: List of metadata terms, including the effective
     options and dataset summary.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<11>,  Prev: Ranker representation<5>,  Up: elo_ranker

6.59.9 References
-----------------

  1. Elo, A. E. (1978).  'The Rating of Chessplayers, Past and Present'.
     Arco.


File: TheLogtalkHandbook-3.101.0.info,  Node: events,  Next: ewma_anomaly_detector,  Prev: elo_ranker,  Up: Libraries

6.60 ‘events’
=============

The objects ‘event_registry’, ‘before_event_registry’, and
‘after_event_registry’ implement convenient predicates for registering
before and after events.

The code makes use of the ‘monitoring’ built-in protocol, which declares
the two basic event handler predicates (‘before/3’ and ‘after/3’).  You
will need to refer to this protocol in your objects if you want to use
the super control structure ‘(^^/1)’ with these predicates.

The ‘monitor’ object implements more sophisticated event handling
predicates.

* Menu:

* API documentation: API documentation<79>.
* Loading: Loading<80>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<79>,  Next: Loading<80>,  Up: events

6.60.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#events’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<80>,  Prev: API documentation<79>,  Up: events

6.60.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ loader file:

     | ?- logtalk_load(events(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: ewma_anomaly_detector,  Next: expand_library_alias_paths,  Prev: events,  Up: Libraries

6.61 ‘ewma_anomaly_detector’
============================

EWMA (Exponentially Weighted Moving Average) anomaly detector for
continuous sequence-like datasets.  It is a statistical
anomaly-detection method based on a two-sided EWMA control chart: for
each known step value ‘x_t’, it computes a standardized deviation,
updates the EWMA statistic ‘E_t’, and uses the maximum normalized
excursion ‘|E_t| / (L*c_t)’ as the raw anomaly score, so a score of
‘1.0’ corresponds exactly to reaching the chosen EWMA control limit.

The library implements the ‘anomaly_detector_protocol’ defined in the
‘anomaly_detection_protocols’ library.  It learns a detector from a
continuous dataset, computes anomaly scores for new instances, predicts
‘normal’ or ‘anomaly’, and exports learned detectors as clauses or
files.

Datasets are represented as objects implementing the
‘anomaly_dataset_protocol’ protocol from the
‘anomaly_detection_protocols’ library.  Declared continuous attributes
are interpreted as ordered monitoring steps in a sequence.  See the
‘ewma_anomaly_detector/tests.lgt’ file for example datasets.

* Menu:

* API documentation: API documentation<80>.
* Loading: Loading<81>.
* Testing: Testing<74>.
* Features: Features<17>.
* Options: Options<16>.
* Detector representation: Detector representation<2>.
* Notes: Notes<4>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<80>,  Next: Loading<81>,  Up: ewma_anomaly_detector

6.61.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#ewma_anomaly_detector’ link in a
web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<81>,  Next: Testing<74>,  Prev: API documentation<80>,  Up: ewma_anomaly_detector

6.61.2 Loading
--------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(ewma_anomaly_detector(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<74>,  Next: Features<17>,  Prev: Loading<81>,  Up: ewma_anomaly_detector

6.61.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(ewma_anomaly_detector(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<17>,  Next: Options<16>,  Prev: Testing<74>,  Up: ewma_anomaly_detector

6.61.4 Features
---------------

   - 'Statistical method': implements anomaly detection based on a
     two-sided EWMA control chart, using learned per-step population
     means and standard deviations for continuous attributes.

   - 'Ordered sequence interpretation': declared continuous attributes
     are treated as ordered monitoring steps.  For each known step value
     ‘x_t’, the library computes ‘z_t = (x_t - mu_t) / sigma_t’ and
     updates the EWMA recurrence ‘E_t = lambda*z_t + (1 -
     lambda)*E_(t-1)’ with ‘E_0 = 0’.

   - 'EWMA control limits': the raw anomaly score is the maximum
     normalized excursion ‘|E_t| / (L*c_t)’, where ‘L’ is the learn-time
     ‘control_limit_multiplier/1’ option and ‘c_t =
     sqrt(lambda/(2-lambda) * (1 - (1-lambda)^(2*t)))’ is the classical
     EWMA control-limit factor after ‘t’ EWMA updates.  The learned
     detector stores a precomputed attribute schema so that query values
     can be reordered efficiently during scoring.

   - 'Continuous features only': accepts datasets whose declared
     attributes are all ‘continuous’.

   - 'Baseline training selection': supports learn-time
     ‘baseline_class_values(ClassValues)’ and
     ‘baseline_selection_policy(Policy)’ options.  The default baseline
     class values are ‘[normal]’.  The default ‘reject’ policy throws an
     error if any non-baseline training example is found.  The ‘filter’
     policy removes non-baseline examples before fitting the baseline
     statistics.

   - 'Missing-value tolerant': ignores missing values when fitting
     per-step statistics.  During scoring, missing step values do not
     update the EWMA state or advance the EWMA update count.  Queries
     must still provide at least one known value.

   - 'Bounded scoring': maps the raw EWMA excursion to ‘[0.0, 1.0)’
     using ‘Score = Raw / (1 + Raw)’.

   - 'EWMA control parameters': supports learn-time
     ‘control_limit_multiplier/1’ and ‘smoothing_factor/1’ options.  The
     default ‘control_limit_multiplier(3.0)’ and ‘smoothing_factor(0.2)’
     correspond to a common EWMA monitoring setup.

   - 'Default threshold': the default ‘anomaly_threshold(0.5)’
     corresponds to the chosen EWMA control limit after score
     normalization.  Because the raw score is already normalized by the
     learned control limit, this threshold remains the same for any
     learned ‘control_limit_multiplier/1’ value.

   - 'Learn-time control parameters': ‘control_limit_multiplier/1’ and
     ‘smoothing_factor/1’ are recorded in the learned detector and
     reused for subsequent scoring and prediction.  Passing them to
     ‘predict/4’ does not override the learned values.  Only
     ‘anomaly_threshold/1’ can be overridden at predict time.

   - 'All-missing queries rejected': scoring and prediction throw a
     ‘domain_error(non_empty_known_values, AttributeNames)’ exception
     when every declared step is missing in the query.

   - 'Featureless datasets rejected': datasets must declare at least one
     continuous feature; otherwise ‘learn/2-3’ throws a
     ‘domain_error(non_empty_features, Dataset)’ exception.

   - 'Detector export': learned detectors can be exported as predicate
     clauses.

   - 'Explicit validation and diagnostics': supports the shared
     ‘check_anomaly_detector/1’, ‘valid_anomaly_detector/1’,
     ‘diagnostics/2’, ‘diagnostic/2’, and ‘anomaly_detector_options/2’
     predicates.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<16>,  Next: Detector representation<2>,  Prev: Features<17>,  Up: ewma_anomaly_detector

6.61.5 Options
--------------

The following options are supported by the public API:

   - ‘anomaly_threshold(Threshold)’: Threshold for ‘predict/3-4’
     (default: ‘0.5’)

   - ‘baseline_class_values(ClassValues)’: Learn-time class labels that
     are admissible for baseline fitting (default: ‘[normal]’)

   - ‘baseline_selection_policy(Policy)’: Learn-time handling of
     examples whose class is not listed in ‘baseline_class_values/1’.
     Supported values are ‘reject’ and ‘filter’ (default: ‘reject’)

   - ‘control_limit_multiplier(ControlLimitMultiplier)’: Learn-time EWMA
     control-limit multiplier ‘L’ (default: ‘3.0’)

   - ‘smoothing_factor(SmoothingFactor)’: Learn-time EWMA smoothing
     factor ‘lambda’ (default: ‘0.2’)


File: TheLogtalkHandbook-3.101.0.info,  Node: Detector representation<2>,  Next: Notes<4>,  Prev: Options<16>,  Up: ewma_anomaly_detector

6.61.6 Detector representation
------------------------------

The learned detector is represented by default as:

     ewma_detector(TrainingDataset, AttributeSchema, Encoders, Diagnostics)

Where:

   - ‘TrainingDataset’: training dataset object identifier

   - ‘AttributeSchema’: precomputed attribute ordering metadata used to
     validate and reorder query step values efficiently during scoring

   - ‘Encoders’: list of ‘ewma_encoder(Attribute, Mean, Scale)’ records

   - ‘Diagnostics’: learned metadata terms including ‘model/1’,
     ‘training_dataset/1’, ‘attribute_names/1’, ‘feature_count/1’,
     ‘example_count/1’, and ‘options/1’.  The ‘example_count/1’ value is
     the effective number of training examples after applying the
     selected baseline selection policy.

When exported using ‘export_to_clauses/4’ or ‘export_to_file/4’, this
detector term is serialized directly as the single argument of the
generated predicate clause so that the exported model can be loaded and
reused as-is.


File: TheLogtalkHandbook-3.101.0.info,  Node: Notes<4>,  Prev: Detector representation<2>,  Up: ewma_anomaly_detector

6.61.7 Notes
------------

Scoring has three stages.  First, the detector computes one standardized
deviation ‘z_t = (x_t - mu_t) / sigma_t’ for each known monitoring step.
Second, those deviations are processed sequentially using the EWMA
recurrence ‘E_t = lambda*z_t + (1 - lambda)*E_(t-1)’ with the learned
‘smoothing_factor/1’ value.  Third, the maximum normalized excursion
‘|E_t| / (L*c_t)’ is mapped to the interval ‘[0.0, 1.0)’ using ‘Score =
Raw / (1 + Raw)’.

The control-limit factor ‘c_t’ is computed from the number of actual
EWMA updates, not from the declared attribute position.  Accordingly,
leading or intermediate missing step values neither update the EWMA
state nor widen the control limits.

The ‘smoothing_factor/1’ option changes the EWMA update rule itself.
Smaller values make the detector retain longer-term history while larger
values react more strongly to recent deviations.  The
‘control_limit_multiplier/1’ option scales the control limits directly
in the score path.  Larger values therefore make the detector less
sensitive by requiring larger EWMA excursions before the raw score
reaches ‘1.0’.

The ‘baseline_class_values/1’ option declares which dataset class labels
are admissible for baseline fitting.  The ‘baseline_selection_policy/1’
option then controls what happens when other labels are present in the
training data.  The default ‘reject’ policy raises a
‘domain_error(baseline_only_training_data, Dataset)’ exception when any
non-baseline example is found.  The ‘filter’ policy removes non-baseline
examples before fitting and raises a
‘domain_error(non_empty_baseline_training_data, Dataset)’ exception if
no training examples remain after filtering.

Attributes with zero observed dispersion are assigned a fallback scale
of ‘1.0’.  This keeps the detector well-defined for singleton datasets
or constant steps while still yielding zero score for matching values
and positive scores for deviating values.


File: TheLogtalkHandbook-3.101.0.info,  Node: expand_library_alias_paths,  Next: expecteds,  Prev: ewma_anomaly_detector,  Up: Libraries

6.62 ‘expand_library_alias_paths’
=================================

This library provides provides a hook object,
‘expand_library_alias_paths’, for expanding library alias paths in
‘logtalk_library_path/2 facts’ in source files.  It is mainly used when
embedding Logtalk and Logtalk applications.

* Menu:

* API documentation: API documentation<81>.
* Loading: Loading<82>.
* Usage: Usage<34>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<81>,  Next: Loading<82>,  Up: expand_library_alias_paths

6.62.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#expand-library-alias-paths’ link
in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<82>,  Next: Usage<34>,  Prev: API documentation<81>,  Up: expand_library_alias_paths

6.62.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ utility
file:

     | ?- logtalk_load(expand_library_alias_paths(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<34>,  Prev: Loading<82>,  Up: expand_library_alias_paths

6.62.3 Usage
------------

Use the ‘hook/1’ option when compiling a source file:

     | ?- logtalk_load(my_source_file, [hook(expand_library_alias_paths)]).
     ...

Alternatively, assuming it is the only hook object you are using, you
can set it as thew default hook object:

     | ?- set_logtalk_flag(hook, expand_library_alias_paths).
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: expecteds,  Next: format,  Prev: expand_library_alias_paths,  Up: Libraries

6.63 ‘expecteds’
================

This library provides an implementation of 'expected terms' with an API
that is inspired by the ‘optional’ library and C++ standardization
proposals for an ‘Expected<T>’ type.  An expected term is an opaque
compound term that either contains an expected value or an error
informing why the expected value is not present.  Expected terms provide
an alternative to generating an exception (or a failure) when something
unexpected happens when asking for a value.  This allows, e.g.,
separating the code that constructs expected terms from the code that
processes them, which is then free to deal if necessary and at its
convenience with any unexpected events.

* Menu:

* API documentation: API documentation<82>.
* Loading: Loading<83>.
* Testing: Testing<75>.
* Usage: Usage<35>.
* See also::


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<82>,  Next: Loading<83>,  Up: expecteds

6.63.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#expecteds’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<83>,  Next: Testing<75>,  Prev: API documentation<82>,  Up: expecteds

6.63.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(expecteds(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<75>,  Next: Usage<35>,  Prev: Loading<83>,  Up: expecteds

6.63.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(expecteds(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<35>,  Next: See also,  Prev: Testing<75>,  Up: expecteds

6.63.4 Usage
------------

The ‘expected’ object provides constructors for expected terms.  For
example:

     | ?- expected::of_expected(1, Expected).
     ...

The created expected terms can then be passed as parameters to the
‘expected/1’ parametric object.  For example:

     | ?- expected::of_expected(1, Expected), expected(Expected)::or_else(Value, 0).
     Expected = expected(1),
     Value = 1
     yes

     | ?- expected::of_unexpected(-1, Expected), expected(Expected)::or_else(Value, 0).
     Expected = unexpected(-1),
     Value = 0
     yes

The ‘either’ object provides types and predicates for extended
type-checking and predicates for handling lists of expected terms,
including ‘sequence/2’ and ‘traverse/3’.

The ‘expected/1’ parametric object provides ‘filter/3’ for conditionally
rejecting values, converting them to unexpected terms with a given
error:

     | ?- expected::of_expected(1, Expected),
          expected(Expected)::filter(integer, not_integer, NewExpected).
     NewExpected = expected(1)
     yes

     | ?- expected::of_expected(a, Expected),
          expected(Expected)::filter(integer, not_integer, NewExpected).
     NewExpected = unexpected(not_integer)
     yes

The ‘map_or_else/3’ predicate applies a closure to the value if present,
returning a default value otherwise (symmetric with the optionals
library):

     | ?- expected::of_expected(a, Expected),
          expected(Expected)::map_or_else(char_code, 0, Value).
     Value = 97
     yes

     | ?- expected::of_unexpected(-1, Expected),
          expected(Expected)::map_or_else(char_code, 0, Value).
     Value = 0
     yes

The ‘or/2’ predicate chains expected terms, returning the current term
if it holds a value, or calling a closure to produce an alternative
otherwise:

     | ?- expected::of_expected(1, Expected),
          expected(Expected)::or(NewExpected, expected::of_expected(2)).
     NewExpected = expected(1)
     yes

     | ?- expected::of_unexpected(-1, Expected),
          expected(Expected)::or(NewExpected, expected::of_expected(2)).
     NewExpected = expected(2)
     yes

The ‘zip/3’ predicate combines two expected terms using a closure when
both hold values, returning the first error otherwise:

     | ?- expected::of_expected(1, E1), expected::of_expected(3, E2),
          expected(E1)::zip([X,Y,Z]>>(Z is X+Y), E2, NewExpected).
     NewExpected = expected(4)
     yes

     | ?- expected::of_unexpected(-1, E1), expected::of_expected(3, E2),
          expected(E1)::zip([X,Y,Z]>>(Z is X+Y), E2, NewExpected).
     NewExpected = unexpected(-1)
     yes

The ‘map_unexpected/2’ predicate transforms the error held by an
expected term:

     | ?- expected::of_unexpected(-1, Expected),
          expected(Expected)::map_unexpected([X,Y]>>(Y is abs(X)), NewExpected).
     NewExpected = unexpected(1)
     yes

The ‘map_catching/2’ predicate applies a closure that may throw an
error, catching it and wrapping it as an unexpected term:

     | ?- expected::of_expected(a, Expected),
          expected(Expected)::map_catching(char_code, NewExpected).
     NewExpected = expected(97)
     yes

     | ?- expected::of_expected(1, Expected),
          expected(Expected)::map_catching(char_code, NewExpected),
          expected(NewExpected)::is_unexpected.
     yes

The ‘map_both/3’ predicate is a bifunctor map that transforms both the
expected value and unexpected error using separate closures:

     | ?- expected::of_expected(1, Expected),
          expected(Expected)::map_both([X,Y]>>(Y is X+1), [X,Y]>>(Y is abs(X)), NewExpected).
     NewExpected = expected(2)
     yes

The ‘swap/1’ predicate swaps expected and unexpected terms:

     | ?- expected::of_expected(1, Expected),
          expected(Expected)::swap(NewExpected).
     NewExpected = unexpected(1)
     yes

     | ?- expected::of_unexpected(error, Expected),
          expected(Expected)::swap(NewExpected).
     NewExpected = expected(error)
     yes

The ‘flatten/1’ predicate unwraps a nested expected term:

     | ?- expected::of_expected(1, Inner), expected::of_expected(Inner, Outer),
          expected(Outer)::flatten(NewExpected).
     NewExpected = expected(1)
     yes

     | ?- expected::of_unexpected(oops, Inner), expected::of_expected(Inner, Outer),
          expected(Outer)::flatten(NewExpected).
     NewExpected = unexpected(oops)
     yes

Conversion between expected and optional terms is provided by the
‘to_optional/1’, ‘from_optional/3’, and ‘optional/1::to_expected/2’
predicates:

     | ?- expected::of_expected(1, Expected),
          expected(Expected)::to_optional(Optional).
     Optional = optional(1)
     yes

     | ?- expected::of_unexpected(error, Expected),
          expected(Expected)::to_optional(Optional).
     Optional = empty
     yes

     | ?- optional::of(1, Optional),
          expected::from_optional(Optional, missing, Expected).
     Expected = expected(1)
     yes

     | ?- optional::empty(Optional),
          expected::from_optional(Optional, missing, Expected).
     Expected = unexpected(missing)
     yes

Examples:

     | ?- expected::of_expected(1, E1), expected::of_expected(2, E2),
          either::sequence([E1, E2], Expected).
     Expected = expected([1,2])
     yes

     | ?- either::traverse({expected}/[X,E]>>expected::of_expected(X, E), [1,2], Expected).
     Expected = expected([1,2])
     yes

     | ?- either::traverse({expected}/[X,E]>>(
            integer(X) -> expected::of_expected(X, E)
          ; expected::of_unexpected(not_integer(X), E)
          ), [1,a,2], Expected).
     Expected = unexpected(not_integer(a))
     yes

     | ?- expected::of_expected(1, E1), expected::of_unexpected(e, E2),
          either::sequence([E1, E2], Expected).
     Expected = unexpected(e)
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: See also,  Prev: Usage<35>,  Up: expecteds

6.63.5 See also
---------------

The ‘optionals’ and ‘validations’ libraries.


File: TheLogtalkHandbook-3.101.0.info,  Node: format,  Next: fp_growth_pattern_miner,  Prev: expecteds,  Up: Libraries

6.64 ‘format’
=============

The ‘format’ object provides a portable abstraction over how the de
facto standard ‘format/2-3’ predicates are made available by the
supported backend Prolog systems.  Some systems provide these predicates
as built-in predicates, while others make them available using a library
that must be explicitly loaded.

Calls to the library predicates are inlined when compiled with the
‘optimize’ flag turned on for most of the backends.  When that’s the
case, there is no overhead compared with calling the abstracted
predicates directly.

This library provides linter checks for calls to the ‘format/2-3’
predicates.  Given the differences between the implementations of these
predicates among Prolog systems, the linter checks focus on detecting
common errors such as missing arguments and too many arguments.  The
linter warnings are printed when the ‘suspicious_calls’ flag is set to
‘warning’ (its usual default).

* Menu:

* API documentation: API documentation<83>.
* Loading: Loading<84>.
* Testing: Testing<76>.
* Usage: Usage<36>.
* Portability: Portability<2>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<83>,  Next: Loading<84>,  Up: format

6.64.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#format’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<84>,  Next: Testing<76>,  Prev: API documentation<83>,  Up: format

6.64.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(format(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<76>,  Next: Usage<36>,  Prev: Loading<84>,  Up: format

6.64.3 Testing
--------------

Minimal tests for this library predicates can be run by loading the
‘tester.lgt’ file:

     | ?- logtalk_load(format(tester)).

Detailed tests for the ‘format/2-3’ predicates are available in the
‘tests/prolog/predicates’ directory as part of the Prolog standards
conformance test suite.  Use those tests to confirm the portability of
the format specifiers that you want to use.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<36>,  Next: Portability<2>,  Prev: Testing<76>,  Up: format

6.64.4 Usage
------------

Load this library from your application loader file.  To call the
‘format/2-3’ predicates using implicit message-sending, add the
following directive to any object or category calling the predicates:

     :- uses(format, [
         format/2, format/3
     ]).


File: TheLogtalkHandbook-3.101.0.info,  Node: Portability<2>,  Prev: Usage<36>,  Up: format

6.64.5 Portability
------------------

Some Prolog systems provide only a subset of the expected format
specifiers.  Notably, table-related format specifiers are only fully
supported by a few systems.  See the section below on testing.

Only some of the supported Prolog backends provide implementations of
the ‘format/2-3’ predicates that allow using not only an atom or a list
of character codes for the format string (as de facto standard) but also
using a list of characters.  These currently include ECLiPSe, GNU
Prolog, SICStus Prolog, SWI-Prolog, Trealla Prolog, XVM, and YAP.
Therefore, when wide portability is sought, atoms must be used for the
format specifier argument as they bypass any dependency on the
‘double_quotes’ standard Prolog flag.  Some systems, like Tau Prolog,
only accept a list of characters for the format string.  In this case,
this library will convert the atom format string before calling these
systems native implementations.


File: TheLogtalkHandbook-3.101.0.info,  Node: fp_growth_pattern_miner,  Next: frequent_pattern_mining_protocols,  Prev: format,  Up: Libraries

6.65 ‘fp_growth_pattern_miner’
==============================

FP-growth frequent itemset miner for transaction datasets.  The library
depends on the ‘frequent_pattern_mining_protocols’ support library,
implements the generic ‘pattern_miner_protocol’ defined in the
‘pattern_mining_protocols’ core library, and mines frequent itemsets
using recursive conditional pattern-base projection over a compact
FP-tree whose nodes store parent links directly, plus header-table node
chains derived from the final tree for direct conditional-base
reconstruction, without candidate generation.

Requires a dataset implementing ‘transaction_dataset_protocol’ with
transactions represented as canonical sorted lists of unique declared
items.

* Menu:

* API documentation: API documentation<84>.
* Loading: Loading<85>.
* Testing: Testing<77>.
* Features: Features<18>.
* Options: Options<17>.
* Pattern miner representation: Pattern miner representation<4>.
* References: References<12>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<84>,  Next: Loading<85>,  Up: fp_growth_pattern_miner

6.65.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#fp_growth_pattern_miner’ link in
a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<85>,  Next: Testing<77>,  Prev: API documentation<84>,  Up: fp_growth_pattern_miner

6.65.2 Loading
--------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(fp_growth_pattern_miner(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<77>,  Next: Features<18>,  Prev: Loading<85>,  Up: fp_growth_pattern_miner

6.65.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(fp_growth_pattern_miner(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<18>,  Next: Options<17>,  Prev: Testing<77>,  Up: fp_growth_pattern_miner

6.65.4 Features
---------------

   - 'FP-tree Construction': Builds a compact prefix tree from frequent
     items ordered by global support.

   - 'Header and Parent Links': Stores parent links directly in tree
     nodes and derives header-table node chains from the final tree so
     conditional pattern bases are reconstructed by walking parent links
     instead of using a separate node index.

   - 'Pattern Growth': Mines frequent itemsets recursively from
     conditional pattern bases without candidate generation.

   - 'Canonical Transactions': Validates that transactions are sorted,
     duplicate-free, and restricted to declared items.

   - 'Flexible Support Thresholds': Supports relative minimum support
     and absolute minimum support count.

   - 'Model Export': Mined pattern collections can be exported as
     predicate clauses or written to a file.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<17>,  Next: Pattern miner representation<4>,  Prev: Features<18>,  Up: fp_growth_pattern_miner

6.65.5 Options
--------------

The ‘mine/3’ predicate accepts the following options:

   - ‘minimum_support/1’: Relative minimum support threshold in the
     interval ‘]0.0, 1.0]’.  The default is ‘0.5’.

   - ‘minimum_support_count/1’: Absolute minimum support count.  When
     both support options are provided, this option takes precedence.

   - ‘maximum_pattern_length/1’: Maximum itemset length to mine.  The
     default is ‘1000’, which is effectively capped by the longest
     transaction in the dataset.

   - ‘minimum_pattern_length/1’: Minimum itemset length retained in the
     mined result.  The default is ‘1’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Pattern miner representation<4>,  Next: References<12>,  Prev: Options<17>,  Up: fp_growth_pattern_miner

6.65.6 Pattern miner representation
-----------------------------------

The mined pattern miner result is represented by a compound term with
the functor chosen by the implementation and arity 3.  For example:

     fp_growth_pattern_miner(ItemDomain, Patterns, Options)

Where:

   - ‘ItemDomain’: Canonical sorted list of declared dataset items.

   - ‘Patterns’: List of ‘itemset(Items, SupportCount)’ terms ordered
     first by pattern length and then lexicographically.

   - ‘Options’: Effective mining options used to mine the frequent
     itemsets.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<12>,  Prev: Pattern miner representation<4>,  Up: fp_growth_pattern_miner

6.65.7 References
-----------------

  1. Han, J., Pei, J., and Yin, Y. (2000) - “Mining frequent patterns
     without candidate generation”.


File: TheLogtalkHandbook-3.101.0.info,  Node: frequent_pattern_mining_protocols,  Next: gaussian_mixture_clusterer,  Prev: fp_growth_pattern_miner,  Up: Libraries

6.66 ‘frequent_pattern_mining_protocols’
========================================

This library provides support entities for frequent itemset mining
algorithms.  Transactional datasets are represented as objects
implementing the ‘transaction_dataset_protocol’ protocol.  The generic
‘pattern_miner_protocol’ protocol and the ‘pattern_miner_common’
category used by concrete miners are loaded from the
‘pattern_mining_protocols’ core library.

The ‘frequent_pattern_mining_common’ category builds on that generic
core with frequent-itemset-specific helpers for dataset validation,
support accumulation, and itemset ordering/filtering.

This library also provides reusable transaction smoke-test datasets and
a small smoke-test suite.

* Menu:

* API documentation: API documentation<85>.
* Loading: Loading<86>.
* Testing: Testing<78>.
* Test datasets: Test datasets<5>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<85>,  Next: Loading<86>,  Up: frequent_pattern_mining_protocols

6.66.1 API documentation
------------------------

Open the
‘../../apis/library_index.html#frequent_pattern_mining_protocols’ link
in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<86>,  Next: Testing<78>,  Prev: API documentation<85>,  Up: frequent_pattern_mining_protocols

6.66.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(frequent_pattern_mining_protocols(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<78>,  Next: Test datasets<5>,  Prev: Loading<86>,  Up: frequent_pattern_mining_protocols

6.66.3 Testing
--------------

To run the library smoke tests, load the ‘tester.lgt’ file:

     | ?- logtalk_load(frequent_pattern_mining_protocols(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Test datasets<5>,  Prev: Testing<78>,  Up: frequent_pattern_mining_protocols

6.66.4 Test datasets
--------------------

Several sample transaction datasets are included in the ‘test_datasets’
directory:

   - ‘market_basket_basics.lgt’: A compact transaction dataset with 6
     transactions and 5 items intended for frequent-itemset smoke tests.

   - ‘layered_baskets.lgt’: A transaction dataset with overlapping
     co-occurrence layers intended for support-count and
     candidate-pruning tests.

   - ‘deep_intersection_baskets.lgt’: A compact transaction dataset with
     one frequent length-4 itemset and multiple overlapping length-3
     itemsets intended to stress deeper vertical tidset intersections.

The directory also includes invalid fixtures useful for validation and
error-handling tests:

   - ‘invalid_undeclared_item_baskets.lgt’: Uses an item not listed in
     the declared item domain.

   - ‘invalid_unsorted_transaction_baskets.lgt’: Uses a transaction
     whose items are not in canonical sorted order.

   - ‘invalid_duplicate_item_baskets.lgt’: Uses a transaction with a
     duplicate item.

   - ‘invalid_empty_baskets.lgt’: Declares an item domain but no
     transactions.

   - ‘invalid_item_domain_baskets.lgt’: Declares a non-canonical item
     domain with duplicate items.


File: TheLogtalkHandbook-3.101.0.info,  Node: gaussian_mixture_clusterer,  Next: gaussian_process_regression,  Prev: frequent_pattern_mining_protocols,  Up: Libraries

6.67 ‘gaussian_mixture_clusterer’
=================================

Gaussian mixture model clusterer.  It uses deterministic
expectation-maximization with diagonal covariance matrices.  Supports
continuous attributes only.

The library implements the ‘clusterer_protocol’ defined in the
‘clustering_protocols’ library.  It provides predicates for learning a
clusterer from a dataset, assigning new instances to clusters, returning
Gaussian-mixture posterior component probabilities for new instances,
and exporting the learned clusterer as a list of predicate clauses or to
a file.

Datasets are represented as objects implementing the
‘clustering_dataset_protocol’ protocol from the ‘clustering_protocols’
library.

* Menu:

* API documentation: API documentation<86>.
* Loading: Loading<87>.
* Testing: Testing<79>.
* Features: Features<19>.
* Gaussian-Mixture-Specific Prediction API::
* Options: Options<18>.
* Clusterer representation: Clusterer representation<3>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<86>,  Next: Loading<87>,  Up: gaussian_mixture_clusterer

6.67.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#gaussian_mixture_clusterer’ link
in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<87>,  Next: Testing<79>,  Prev: API documentation<86>,  Up: gaussian_mixture_clusterer

6.67.2 Loading
--------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(gaussian_mixture_clusterer(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<79>,  Next: Features<19>,  Prev: Loading<87>,  Up: gaussian_mixture_clusterer

6.67.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(gaussian_mixture_clusterer(tester)).

To run the performance benchmark suite, load the
‘tester_performance.lgt’ file:

     | ?- logtalk_load(gaussian_mixture_clusterer(tester_performance)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<19>,  Next: Gaussian-Mixture-Specific Prediction API,  Prev: Testing<79>,  Up: gaussian_mixture_clusterer

6.67.4 Features
---------------

   - 'Expectation-Maximization': Learns diagonal Gaussian components
     using deterministic EM updates.

   - 'Continuous Datasets': Accepts datasets containing only continuous
     attributes.

   - 'Configurable Dead-Component Handling': Dead components can either
     be preserved with zero weight or deterministically reseeded to the
     least-confident training row.

   - 'Deterministic Initialization': Supports ‘first_k’ and
     deterministic ‘spread’ initialization for component means.  The
     ‘spread’ strategy uses a canonical first seed and canonical
     tie-breaking so equivalent row permutations produce the same
     initialization.

   - 'Optional Feature Scaling': Continuous attributes can be
     standardized using z-score scaling.

   - 'Posterior Prediction': New instances are assigned to the component
     with the highest posterior score, and ‘cluster_probabilities/3’ can
     return the full posterior distribution over components.

   - 'Training Diagnostics': Learned clusterers record convergence
     reason, iteration count, average log-likelihood, final delta, and
     effective options.

   - 'Portable Export': Learned clusterers can be exported as clauses or
     files and reused later.


File: TheLogtalkHandbook-3.101.0.info,  Node: Gaussian-Mixture-Specific Prediction API,  Next: Options<18>,  Prev: Features<19>,  Up: gaussian_mixture_clusterer

6.67.5 Gaussian-Mixture-Specific Prediction API
-----------------------------------------------

In addition to the shared ‘cluster/3’ predicate from the clustering
protocols library, this package provides a Gaussian-mixture-specific
predicate:

   - ‘cluster_probabilities(Clusterer, Instance, Probabilities)’:
     Returns posterior component probabilities for ‘Instance’ as
     ‘Cluster-Probability’ pairs in component-id order.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<18>,  Next: Clusterer representation<3>,  Prev: Gaussian-Mixture-Specific Prediction API,  Up: gaussian_mixture_clusterer

6.67.6 Options
--------------

The following options can be passed to the ‘learn/3’ predicate:

   - ‘k(K)’: Number of mixture components.  Default is ‘2’.

   - ‘initialization(Initialization)’: Mean initialization strategy.
     Options: ‘spread’ (default) or ‘first_k’.

   - ‘feature_scaling(FeatureScaling)’: Whether to standardize
     continuous attributes before clustering.  Options: ‘on’ (default)
     or ‘off’.

   - ‘maximum_iterations(MaximumIterations)’: Maximum number of EM
     iterations.  Default is ‘100’.

   - ‘tolerance(Tolerance)’: Per-example average log-likelihood
     convergence tolerance.  Default is ‘0.0001’.

   - ‘covariance_regularization(Regularization)’: Positive diagonal
     covariance regularization constant.  Default is ‘0.001’.

   - ‘dead_component_policy(Policy)’: Handling for components whose
     total responsibility collapses below the dead-component threshold.
     Options: ‘zero_weight’ (default) keeps the previous component with
     zero weight; ‘reseed’ relocates the component to the
     least-confident training row and gives it one-example prior weight.


File: TheLogtalkHandbook-3.101.0.info,  Node: Clusterer representation<3>,  Prev: Options<18>,  Up: gaussian_mixture_clusterer

6.67.7 Clusterer representation
-------------------------------

The learned clusterer is represented as a compound term with the functor
chosen by the user when exporting the clusterer and arity 5.  For
example:

     gaussian_mixture_clusterer(Encoders, Components, Weights, Options, Diagnostics)

Where:

   - ‘Encoders’: List of continuous attribute encoders storing attribute
     name, mean, and scale.

   - ‘Components’: List of ‘component(Mean, Variances)’ terms in
     component-id order.

   - ‘Weights’: List of mixture weights in component-id order.

   - ‘Options’: Effective training options used to learn the clusterer.

   - ‘Diagnostics’: Training diagnostics including convergence status,
     iteration count, average log-likelihood, final delta, and options.


File: TheLogtalkHandbook-3.101.0.info,  Node: gaussian_process_regression,  Next: genint,  Prev: gaussian_mixture_clusterer,  Up: Libraries

6.68 ‘gaussian_process_regression’
==================================

Gaussian process regression regressor supporting continuous and
mixed-feature datasets.  Uses exact Gaussian process regression with a
mixed covariance kernel: an automatic-relevance-determination
squared-exponential component over continuous encoded features and a
field-wise categorical overlap component over categorical attributes.
Hyperparameters are selected by maximizing the log marginal likelihood
using a deterministic coordinate search in log space.

The library implements the ‘regressor_protocol’ defined in the
‘regression_protocols’ library and learns an exact mixed gaussian
process using an automatic-relevance-determination squared-exponential
kernel for continuous encoded features together with a categorical
overlap kernel for categorical attributes.  Hyperparameters are selected
by maximizing the log marginal likelihood using a deterministic
coordinate search in log space.

* Menu:

* API documentation: API documentation<87>.
* Loading: Loading<88>.
* Testing: Testing<80>.
* Features: Features<20>.
* Regressor representation: Regressor representation<3>.
* Prediction API::
* Diagnostics syntax: Diagnostics syntax<7>.
* Options: Options<19>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<87>,  Next: Loading<88>,  Up: gaussian_process_regression

6.68.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#gaussian_process_regression’
link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<88>,  Next: Testing<80>,  Prev: API documentation<87>,  Up: gaussian_process_regression

6.68.2 Loading
--------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(gaussian_process_regression(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<80>,  Next: Features<20>,  Prev: Loading<88>,  Up: gaussian_process_regression

6.68.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(gaussian_process_regression(tester)).

To run the performance benchmark suite, load the
‘tester_performance.lgt’ file:

     | ?- logtalk_load(gaussian_process_regression(tester_performance)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<20>,  Next: Regressor representation<3>,  Prev: Testing<80>,  Up: gaussian_process_regression

6.68.4 Features
---------------

   - 'Continuous and Mixed Features': Supports continuous attributes and
     categorical attributes encoded using reference-level dummy coding.

   - 'Feature Scaling': Continuous attributes can be standardized using
     z-score scaling.

   - 'Missing Values': Missing numeric and categorical values are
     encoded using explicit missing-value indicator features.

   - 'Unknown Values': Prediction requests containing categorical values
     that are not declared by the dataset raise a domain error.

   - 'Exact Bayesian Regression': Uses exact Gaussian process regression
     with a mixed covariance kernel combining an
     automatic-relevance-determination squared-exponential component for
     continuous encoded features and a field-wise categorical overlap
     component for categorical attributes.

   - 'Automatic Hyperparameter Selection': By default performs
     deterministic log-marginal-likelihood optimization of the
     continuous-feature length scales, categorical mismatch penalties,
     signal variance, and noise variance.  The ‘length_scale/1’,
     ‘categorical_penalty/1’, ‘signal_variance/1’, and
     ‘noise_variance/1’ options also accept ‘auto’ when optimization is
     disabled.

   - 'Uncertainty Quantification': Exposes posterior predictive Gaussian
     distributions for new instances (including observation noise
     variance) using the ‘predict_distribution/3’ predicate.  Small
     negative posterior variances caused by floating-point roundoff are
     clipped to zero while larger negative values raise an error.

   - 'Adaptive Stabilization': Retries covariance factorization with
     progressively larger jitter values and records the effective retry
     count in the learned diagnostics.

   - 'Memory-Based Representation': Stores the encoded training rows and
     cached Cholesky factor required for exact posterior prediction plus
     the dual coefficients required for exact posterior prediction.

   - 'Model Export': Learned regressors can be exported as predicate
     clauses or written to a file.

   - 'Reference Benchmarks': Includes a dedicated performance suite
     reporting training time, RMSE, and MAE for representative
     regression datasets.


File: TheLogtalkHandbook-3.101.0.info,  Node: Regressor representation<3>,  Next: Prediction API,  Prev: Features<20>,  Up: gaussian_process_regression

6.68.5 Regressor representation
-------------------------------

The learned regressor is represented by default as:

   - ‘gaussian_process_regressor(Encoders, TrainingFeatures, TargetMean,
     Alpha, CholeskyFactor, Kernel, Diagnostics)’

The exported predicate clauses therefore use the shape:

   - ‘Functor(Encoders, TrainingFeatures, TargetMean, Alpha,
     CholeskyFactor, Kernel, Diagnostics)’

In this representation, ‘Encoders’ stores feature encoding metadata,
‘TrainingFeatures’ stores the encoded training rows, ‘TargetMean’ stores
the centered-mean offset, ‘Alpha’ stores the cached dual coefficients,
‘CholeskyFactor’ stores the lower-triangular covariance factor, ‘Kernel’
stores the learned mixed-kernel hyperparameters including one continuous
length scale per encoded continuous feature and one categorical penalty
per categorical attribute, and ‘Diagnostics’ stores training metadata
including the effective options and learned hyperparameters.


File: TheLogtalkHandbook-3.101.0.info,  Node: Prediction API,  Next: Diagnostics syntax<7>,  Prev: Regressor representation<3>,  Up: gaussian_process_regression

6.68.6 Prediction API
---------------------

The standard ‘predict/3’ predicate returns the posterior predictive
mean.

The ‘predict_distribution/3’ predicate returns a term with the form:

   - ‘gaussian(Mean, Variance)’

where ‘Variance’ is the posterior predictive variance for observed
targets, including the learned observation noise variance.  Tiny
negative values caused by floating-point roundoff are clipped to zero;
larger negative values raise a domain error.


File: TheLogtalkHandbook-3.101.0.info,  Node: Diagnostics syntax<7>,  Next: Options<19>,  Prev: Prediction API,  Up: gaussian_process_regression

6.68.7 Diagnostics syntax
-------------------------

The ‘diagnostics/2’ predicate returns a list of metadata terms with the
form:

     [
         model(gaussian_process_regression),
         target(Target),
         training_example_count(TrainingExampleCount),
         options(Options),
         kernel(squared_exponential),
         length_scales(LengthScales),
         categorical_penalties(CategoricalPenalties),
         signal_variance(SignalVariance),
         noise_variance(NoiseVariance),
         jitter(Jitter),
         continuous_feature_count(ContinuousFeatureCount),
         categorical_feature_count(CategoricalFeatureCount),
         jitter_attempts(JitterAttempts),
         log_marginal_likelihood(LogMarginalLikelihood),
         convergence(Convergence),
         iterations(Iterations),
         final_delta(FinalDelta),
         encoded_feature_count(FeatureCount)
     ]

Where:

   - ‘model(gaussian_process_regression)’ identifies the learning
     algorithm that produced the regressor.

   - ‘target(Target)’ stores the target attribute name declared by the
     training dataset.

   - ‘training_example_count(TrainingExampleCount)’ stores the number of
     examples used during training.

   - ‘options(Options)’ stores the effective learning options after
     merging the user options with the library defaults.

   - ‘kernel(squared_exponential)’ records the covariance-kernel family
     used by the learned model.

   - ‘length_scales(LengthScales)’ stores the learned per-feature
     squared-exponential length scales for the continuous encoded
     feature dimensions.

   - ‘categorical_penalties(CategoricalPenalties)’ stores the learned
     mismatch penalties for the categorical attributes.

   - ‘signal_variance(SignalVariance)’ stores the learned latent-process
     marginal variance.

   - ‘noise_variance(NoiseVariance)’ stores the learned observation
     noise variance.

   - ‘jitter(Jitter)’ stores the effective diagonal jitter used to
     stabilize the covariance factorization.

   - ‘continuous_feature_count(ContinuousFeatureCount)’ stores the
     number of continuous encoded feature dimensions used by the
     squared-exponential kernel.

   - ‘categorical_feature_count(CategoricalFeatureCount)’ stores the
     number of categorical attributes handled by the overlap-kernel
     component.

   - ‘jitter_attempts(JitterAttempts)’ stores the number of adaptive
     jitter retries required by the final covariance factorization.

   - ‘log_marginal_likelihood(LogMarginalLikelihood)’ stores the final
     training log marginal likelihood.

   - ‘convergence(Convergence)’ records the hyperparameter-search stop
     reason.

   - ‘iterations(Iterations)’ stores the number of hyperparameter-search
     sweeps performed.

   - ‘final_delta(FinalDelta)’ stores the last log-marginal-likelihood
     improvement magnitude.

   - ‘encoded_feature_count(FeatureCount)’ stores the number of numeric
     features induced by the encoder list, including missing-value
     indicator features.

Use the ‘regression_protocols’ ‘diagnostic/2’ and ‘regressor_options/2’
helper predicates when you only need a single metadata term or the
effective options.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<19>,  Prev: Diagnostics syntax<7>,  Up: gaussian_process_regression

6.68.8 Options
--------------

The ‘learn/3’ predicate accepts the following options:

   - ‘kernel/1’: Kernel family.  The current accepted value is
     ‘squared_exponential’.  The default is ‘squared_exponential’.

   - ‘feature_scaling/1’: Controls z-score standardization of continuous
     attributes before training and prediction.  Accepted values are
     ‘true’ and ‘false’.  The default is ‘true’.

   - ‘optimize_hyperparameters/1’: Controls deterministic
     log-marginal-likelihood optimization of the kernel hyperparameters.
     Accepted values are ‘true’ and ‘false’.  The default is ‘true’.

   - ‘length_scale/1’: Initial or fixed squared-exponential length-scale
     specification for the continuous encoded feature dimensions.
     Accepted values are ‘auto’, a positive float that is broadcast to
     every continuous encoded feature, or a list of positive floats with
     one value per continuous encoded feature.  The default is ‘auto’.

   - ‘categorical_penalty/1’: Initial or fixed categorical
     mismatch-penalty specification.  Accepted values are ‘auto’, a
     positive float that is broadcast to every categorical attribute, or
     a list of positive floats with one value per categorical attribute.
     The default is ‘auto’.

   - ‘signal_variance/1’: Initial or fixed latent-process variance.
     Accepted values are ‘auto’ or a positive float.  The default is
     ‘auto’.

   - ‘noise_variance/1’: Initial or fixed observation noise variance.
     Accepted values are ‘auto’ or a non-negative float.  The default is
     ‘auto’.

   - ‘jitter/1’: Positive diagonal stabilization jitter added to the
     covariance matrix before factorization.  When factorization fails,
     the implementation retries with progressively larger jitter values
     until it succeeds or exhausts the retry budget.  The default is
     ‘1.0e-8’.

   - ‘maximum_iterations/1’: Maximum number of hyperparameter-search
     sweeps when optimization is enabled.  The default is ‘12’.

   - ‘tolerance/1’: Minimum log-marginal-likelihood improvement floor
     required to continue hyperparameter optimization.  The default
     floor is ‘1.0e-6’.

   - ‘relative_improvement_factor/1’: Relative log-marginal-likelihood
     improvement factor used together with ‘tolerance/1’ to stop
     hyperparameter optimization when only numerically insignificant
     gains remain.  The default is ‘1.0e-4’.

   - ‘hyperparameter_minimum/1’: Lower bound used when proposing scaled
     hyperparameter candidates during coordinate search.  The default is
     ‘1.0e-6’.

   - ‘maximum_continuous_length_scale/1’: Upper bound used when
     proposing scaled continuous length-scale candidates during
     coordinate search.  The default is ‘32.0’.

   - ‘maximum_categorical_penalty/1’: Upper bound used when proposing
     scaled categorical mismatch-penalty candidates during coordinate
     search.  The default is ‘32.0’.

   - ‘max_factorization_attempts/1’: Maximum number of
     covariance-factorization retries performed with progressively
     increased jitter before training raises a positive-definiteness
     error.  The default is ‘32’.

   - ‘jitter_scale_factor/1’: Multiplicative factor used to increase the
     diagonal jitter on each covariance-factorization retry.  The
     default is ‘2.0’.


File: TheLogtalkHandbook-3.101.0.info,  Node: genint,  Next: gensym,  Prev: gaussian_process_regression,  Up: Libraries

6.69 ‘genint’
=============

The ‘genint’ library implements predicates for generating positive
integers in increasing order.  The public predicates are declared
synchronized to prevent race conditions when using a backend Prolog
compiler with multi-threading support.

* Menu:

* API documentation: API documentation<88>.
* Loading: Loading<89>.
* Testing: Testing<81>.
* Usage: Usage<37>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<88>,  Next: Loading<89>,  Up: genint

6.69.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#genint’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<89>,  Next: Testing<81>,  Prev: API documentation<88>,  Up: genint

6.69.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(genint(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<81>,  Next: Usage<37>,  Prev: Loading<89>,  Up: genint

6.69.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(genint(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<37>,  Prev: Testing<81>,  Up: genint

6.69.4 Usage
------------

The ‘genint_core’ category implements the library predicates.  This
category is imported by the default ‘genint’ object to provide
application global named counters.  To make the counters local and thus
minimize the potential for counter name clashes, the category can be
imported by one or more application objects.  Use protected or private
import to restrict the scope of the library predicates.


File: TheLogtalkHandbook-3.101.0.info,  Node: gensym,  Next: geojson,  Prev: genint,  Up: Libraries

6.70 ‘gensym’
=============

The ‘gensym’ library implements predicates for generating unique atoms.
The public predicates are declared synchronized to prevent race
conditions when using a backend Prolog compiler with multi-threading
support.

* Menu:

* API documentation: API documentation<89>.
* Loading: Loading<90>.
* Testing: Testing<82>.
* Usage: Usage<38>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<89>,  Next: Loading<90>,  Up: gensym

6.70.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#gensym’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<90>,  Next: Testing<82>,  Prev: API documentation<89>,  Up: gensym

6.70.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(gensym(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<82>,  Next: Usage<38>,  Prev: Loading<90>,  Up: gensym

6.70.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(gensym(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<38>,  Prev: Testing<82>,  Up: gensym

6.70.4 Usage
------------

The ‘gensym_core’ category implements the library predicates.  This
category is imported by the default ‘gensym’ object to provide
application global generators.  To make the generators local and thus
minimize the potential for generator name clashes, the category can be
imported by one or more application objects.  Use protected or private
import to restrict the scope of the library predicates.  For example:

     :- object(foo,
         imports(private::gensym_core)).

         bar :-
             ^^gensym(p, S),
             ...

     :- end_object.


File: TheLogtalkHandbook-3.101.0.info,  Node: geojson,  Next: geospatial,  Prev: gensym,  Up: Libraries

6.71 ‘geojson’
==============

The ‘geojson’ library provides predicates for parsing, generating, and
validating GeoJSON documents as specified by RFC 7946:

   - ‘https://www.rfc-editor.org/rfc/rfc7946’

It builds on top of the ‘json’ library for JSON parsing and generation
and complements the ‘geospatial’ library by providing a standard
interchange format for geometry, features, and feature collections.

* Menu:

* API documentation: API documentation<90>.
* Loading: Loading<91>.
* Testing: Testing<83>.
* Representation: Representation<10>.
* Examples: Examples<169>.
* Notes: Notes<5>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<90>,  Next: Loading<91>,  Up: geojson

6.71.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#geojson’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<91>,  Next: Testing<83>,  Prev: API documentation<90>,  Up: geojson

6.71.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(geojson(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<83>,  Next: Representation<10>,  Prev: Loading<91>,  Up: geojson

6.71.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(geojson(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Representation<10>,  Next: Examples<169>,  Prev: Testing<83>,  Up: geojson

6.71.4 Representation
---------------------

The library parses GeoJSON documents into native terms using the
following representation:

   - ‘point(Position)’ or ‘point(Position, Options)’

   - ‘multi_point(Positions)’ or ‘multi_point(Positions, Options)’

   - ‘line_string(Positions)’ or ‘line_string(Positions, Options)’

   - ‘multi_line_string(LineStrings)’ or ‘multi_line_string(LineStrings,
     Options)’

   - ‘polygon(Rings)’ or ‘polygon(Rings, Options)’

   - ‘multi_polygon(Polygons)’ or ‘multi_polygon(Polygons, Options)’

   - ‘geometry_collection(Geometries)’ or
     ‘geometry_collection(Geometries, Options)’

   - ‘feature(Geometry, Properties)’ or ‘feature(Geometry, Properties,
     Options)’

   - ‘feature_collection(Features)’ or ‘feature_collection(Features,
     Options)’

Positions follow the GeoJSON order and are represented as lists of
numbers, e.g.  ‘[Longitude, Latitude]’ or ‘[Longitude, Latitude,
Altitude]’.  Validation also checks longitude and latitude values
against the RFC 7946 geographic ranges.

The ‘Options’ lists may contain:

   - ‘bbox(BBox)’ for the optional bounding box member

   - ‘id(Id)’ for feature identifiers

   - ‘foreign_members(ForeignMembers)’ for additional non-reserved
     members, represented either as a list of pairs or as an embedded
     JSON object term using the selected object representation

Feature geometries and properties may be ‘@null’ to represent GeoJSON
‘null’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<169>,  Next: Notes<5>,  Prev: Representation<10>,  Up: geojson

6.71.5 Examples
---------------

Parse a point document:

     | ?- geojson::parse(atom('{"type":"Point","coordinates":[100.0,0.0]}'), GeoJSON).
     GeoJSON = point([100.0, 0.0])
     yes

Generate a GeoJSON feature collection:

     | ?- geojson::generate(atom(JSON), feature_collection([
         feature(point([102.0, 0.5]), {prop0-value0}),
         feature(@null, @null)
     ], [bbox([100.0, 0.0, 105.0, 1.0])])).

Validate a native GeoJSON term:

     | ?- geojson::validate(polygon([[[100.0,0.0],[101.0,0.0],[101.0,1.0],[100.0,1.0],[100.0,0.0]]])).

Inspect validation errors:

     | ?- geojson::validate(polygon([[[100.0,0.0],[101.0,0.0],[101.0,1.0],[100.0,1.0]]]), Errors).
     Errors = [ring_not_closed([coordinates,0])]
     yes

Convert between JSON terms and native GeoJSON terms:

     | ?- geojson::json_to_geojson({type-'Point', coordinates-[1,2]}, GeoJSON).
     GeoJSON = point([1,2])
     yes

     | ?- geojson::geojson_to_json(feature(@null, @null, [id(1)]), JSON).
     JSON = {type-'Feature', geometry-@null, properties-@null, id-1}
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: Notes<5>,  Prev: Examples<169>,  Up: geojson

6.71.6 Notes
------------

   - The library validates the RFC 7946 structural rules for geometry,
     features, feature collections, linear rings, bounding boxes, and
     prohibited ‘crs’ members.

   - Bounding boxes are represented as plain lists of numbers with
     either four or six elements.  Longitude values must stay within
     ‘[-180,180]’, latitude values within ‘[-90,90]’, south must not
     exceed north, and three-dimensional boxes also require minimum
     altitude not to exceed maximum altitude.  Bounding box
     dimensionality must match the represented geometry dimensionality,
     so two-dimensional geometries use four-element boxes while
     geometries with altitude use six-element boxes.  Mixed
     two-dimensional and three-dimensional geometry or feature
     collections are treated as three-dimensional for bounding-box
     validation.  Antimeridian-crossing boxes are accepted, so west may
     still be greater than east.

   - Parsing rejects duplicate reserved GeoJSON members instead of
     silently normalizing them.

   - Properties and foreign member values are recursively validated as
     JSON values compatible with the selected embedded object
     representation.

   - When using the ‘chars’ or ‘codes’ string representations, string
     terms are validated as proper character or character-code lists.

   - Foreign members are preserved but reserved GeoJSON member names are
     rejected when used as foreign member keys, regardless of whether
     the foreign members are supplied as pair lists or embedded object
     terms.

   - The ‘geojson/3’ parametric object mirrors the ‘json/3’
     customization parameters for embedded object, pair, and string
     representations.


File: TheLogtalkHandbook-3.101.0.info,  Node: geospatial,  Next: git,  Prev: geojson,  Up: Libraries

6.72 ‘geospatial’
=================

This library provides a ‘geospatial_protocol’ protocol and a
‘geospatial’ object for common geographic computations over coordinates
represented as ‘geographic(Latitude,Longitude)’.  By default, distances
are returned in kilometers.

* Menu:

* API documentation: API documentation<91>.
* Loading: Loading<92>.
* Testing: Testing<84>.
* Available predicates::
* Notes: Notes<6>.
* Usage: Usage<39>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<91>,  Next: Loading<92>,  Up: geospatial

6.72.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#geospatial’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<92>,  Next: Testing<84>,  Prev: API documentation<91>,  Up: geospatial

6.72.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(geospatial(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<84>,  Next: Available predicates,  Prev: Loading<92>,  Up: geospatial

6.72.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(geospatial(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Available predicates,  Next: Notes<6>,  Prev: Testing<84>,  Up: geospatial

6.72.4 Available predicates
---------------------------

The library currently includes predicates for:

   - Coordinate validation

   - Coordinate normalization

   - Point-to-point distances (‘haversine’ and ‘vincenty’)

   - Rhumb-line distance, bearing, and destination predicates

   - Rhumb-line interpolation and midpoint

   - Generic distance dispatch (‘distance/4’ and ‘distance/5’)

   - Initial and final bearings

   - Midpoint and destination point computations

   - Great-circle interpolation and track-distance

   - Proximity checks and nearest coordinate search

   - Mean center and coordinates bounding boxes

   - Minimum enclosing circle

   - Coordinates-to-bounding-box conversion

   - Equirectangular projection and inverse

   - Point-in-polygon checks

   - Polygon area, polygon centroid, and polygon bounding boxes

   - Polygon closure and orientation

   - Polygon orientation normalization

   - Polygon validity checks

   - Bounding-box utilities

   - Strict bounding-box overlap checks

   - Bounding-box and polygon/polyline relation

   - Nearest-point and point-to-polyline distance

   - Polyline length and polygon perimeter

   - Polyline simplification by tolerance

   - Polyline split and resampling

   - Polygon intersection checks

   - Spherical bounding boxes

   - Route distance accumulation (‘route_distance/2’,
     ‘route_distance/3’, and ‘route_distance/4’)

For explicit units, predicates ‘distance/5’ and ‘route_distance/4’
support ‘kilometers’, ‘meters’, ‘miles’, and ‘nautical_miles’.

Generic metric dispatch accepts ‘rhumb’ (and alias ‘loxodrome’) in
addition to existing spherical and ellipsoidal metrics.


File: TheLogtalkHandbook-3.101.0.info,  Node: Notes<6>,  Next: Usage<39>,  Prev: Available predicates,  Up: geospatial

6.72.5 Notes
------------

The generic vector distance predicates already available in the ‘types’
library (notably in the ‘listp’ and ‘numberlistp’ protocols) remain the
recommended choice for non-geographic n-dimensional data.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<39>,  Prev: Notes<6>,  Up: geospatial

6.72.6 Usage
------------

Load the library:

     | ?- logtalk_load(geospatial(loader)).

Validate a coordinate:

     | ?- geospatial::valid_coordinate(geographic(38.7223, -9.1393)).

Normalize coordinates and convert to/from local planar coordinates:

     | ?- geospatial::normalize_coordinate(geographic(95.0, 10.0), Normalized).
     | ?- geospatial::equirectangular_projection(geographic(38.7223, -9.1393), 38.0, X, Y).
     | ?- geospatial::equirectangular_inverse(X, Y, 38.0, Coordinate).

Compute default distance in kilometers (Haversine):

     | ?- geospatial::distance(geographic(38.7223, -9.1393), geographic(41.1579, -8.6291), haversine, Distance).
     | ?- geospatial::rhumb_distance(geographic(38.7223, -9.1393), geographic(41.1579, -8.6291), Distance).
     | ?- geospatial::rhumb_bearing(geographic(38.7223, -9.1393), geographic(41.1579, -8.6291), Bearing).
     | ?- geospatial::rhumb_destination_point(geographic(38.7223, -9.1393), 45.0, 50.0, Destination).
     | ?- geospatial::interpolate_rhumb(geographic(38.7223, -9.1393), geographic(41.1579, -8.6291), 0.5, Intermediate).
     | ?- geospatial::rhumb_midpoint(geographic(38.7223, -9.1393), geographic(41.1579, -8.6291), Midpoint).

Compute distance with explicit unit (‘meters’, ‘miles’, or
‘nautical_miles’):

     | ?- geospatial::distance(geographic(38.7223, -9.1393), geographic(41.1579, -8.6291), vincenty, miles, Distance).

Compute route distance using the default metric (‘haversine’) in
kilometers:

     | ?- geospatial::route_distance([geographic(38.7223, -9.1393), geographic(39.7440, -8.8070), geographic(41.1579, -8.6291)], Distance).

Compute route distance with explicit metric and unit:

     | ?- geospatial::route_distance([geographic(38.7223, -9.1393), geographic(39.7440, -8.8070), geographic(41.1579, -8.6291)], vincenty, nautical_miles, Distance).

Compute midpoint and destination point:

     | ?- geospatial::midpoint(geographic(38.7223, -9.1393), geographic(41.1579, -8.6291), Midpoint).
     | ?- geospatial::destination_point(geographic(38.7223, -9.1393), 45.0, 50.0, Destination).
     | ?- geospatial::interpolate_great_circle(geographic(38.7223, -9.1393), geographic(41.1579, -8.6291), 0.5, Intermediate).
     | ?- geospatial::cross_track_distance(geographic(40.0, -9.0), geographic(38.7223, -9.1393), geographic(41.1579, -8.6291), CrossTrackKm).
     | ?- geospatial::along_track_distance(geographic(40.0, -9.0), geographic(38.7223, -9.1393), geographic(41.1579, -8.6291), AlongTrackKm).

Compute final bearing and proximity checks:

     | ?- geospatial::final_bearing(geographic(38.7223, -9.1393), geographic(41.1579, -8.6291), Bearing).
     | ?- geospatial::within_distance(geographic(38.7223, -9.1393), geographic(41.1579, -8.6291), 300.0, haversine).

Find the nearest coordinate from a list:

     | ?- geospatial::nearest_coordinate(geographic(38.7223, -9.1393), [geographic(37.7749, -122.4194), geographic(41.1579, -8.6291), geographic(40.4168, -3.7038)], vincenty, Nearest, Distance).

Compute center and coordinate-list bounding boxes:

     | ?- geospatial::mean_center([geographic(38.7223, -9.1393), geographic(41.1579, -8.6291), geographic(40.4168, -3.7038)], Center).
     | ?- geospatial::minimum_enclosing_circle([geographic(38.7223, -9.1393), geographic(41.1579, -8.6291), geographic(40.4168, -3.7038)], Center, Radius).
     | ?- geospatial::coordinates_bounding_box([geographic(38.7223, -9.1393), geographic(41.1579, -8.6291), geographic(40.4168, -3.7038)], BoundingBox).
     | ?- geospatial::bbox_from_coordinates([geographic(38.7223, -9.1393), geographic(41.1579, -8.6291), geographic(40.4168, -3.7038)], BoundingBox).

Work with polygons:

     | ?- geospatial::point_in_polygon(geographic(0.5, 0.5), [geographic(0.0, 0.0), geographic(0.0, 1.0), geographic(1.0, 1.0), geographic(1.0, 0.0)]).
     | ?- geospatial::polygon_area([geographic(0.0, 0.0), geographic(0.0, 1.0), geographic(1.0, 1.0), geographic(1.0, 0.0)], Area).
     | ?- geospatial::polygon_centroid([geographic(0.0, 0.0), geographic(0.0, 1.0), geographic(1.0, 1.0), geographic(1.0, 0.0)], Centroid).
     | ?- geospatial::polygon_bounding_box([geographic(1.0, -2.0), geographic(0.0, 1.0), geographic(-1.0, -1.0)], BoundingBox).
     | ?- geospatial::close_polygon([geographic(0.0, 0.0), geographic(0.0, 1.0), geographic(1.0, 0.0)], ClosedPolygon).
     | ?- geospatial::polygon_orientation([geographic(0.0, 0.0), geographic(1.0, 0.0), geographic(1.0, 1.0), geographic(0.0, 1.0)], Orientation).
     | ?- geospatial::is_clockwise_polygon([geographic(0.0, 0.0), geographic(1.0, 0.0), geographic(1.0, 1.0), geographic(0.0, 1.0)]).
     | ?- geospatial::normalize_polygon_orientation([geographic(0.0, 0.0), geographic(0.0, 1.0), geographic(1.0, 1.0), geographic(1.0, 0.0)], clockwise, Oriented).
     | ?- geospatial::clockwise_polygon([geographic(0.0, 0.0), geographic(0.0, 1.0), geographic(1.0, 1.0), geographic(1.0, 0.0)], Clockwise).
     | ?- geospatial::counterclockwise_polygon([geographic(0.0, 0.0), geographic(1.0, 0.0), geographic(1.0, 1.0), geographic(0.0, 1.0)], Counterclockwise).
     | ?- geospatial::is_valid_polygon([geographic(0.0, 0.0), geographic(0.0, 1.0), geographic(1.0, 0.0)]).

Work with bounding boxes:

     | ?- geospatial::bbox_contains(bbox(geographic(-1.0, -1.0), geographic(1.0, 1.0)), geographic(0.5, 0.5)).
     | ?- geospatial::bbox_contains(bbox(geographic(-1.0, 170.0), geographic(1.0, -170.0)), bbox(geographic(-0.5, 175.0), geographic(0.5, -175.0))).
     | ?- geospatial::bbox_intersects(bbox(geographic(0.0, 0.0), geographic(1.0, 1.0)), bbox(geographic(0.5, 0.5), geographic(2.0, 2.0))).
     | ?- geospatial::bbox_overlaps(bbox(geographic(0.0, 0.0), geographic(1.0, 1.0)), bbox(geographic(0.5, 0.5), geographic(2.0, 2.0))).
     | ?- geospatial::bbox_intersects_polygon(bbox(geographic(0.0, 0.0), geographic(1.0, 1.0)), [geographic(0.5, 0.5), geographic(0.5, 1.5), geographic(1.5, 1.5), geographic(1.5, 0.5)]).
     | ?- geospatial::bbox_contains_polygon(bbox(geographic(0.0, 0.0), geographic(2.0, 2.0)), [geographic(0.5, 0.5), geographic(0.5, 1.5), geographic(1.5, 1.5), geographic(1.5, 0.5)]).
     | ?- geospatial::bbox_intersects_polyline(bbox(geographic(0.0, 0.0), geographic(1.0, 1.0)), [geographic(-1.0, 0.5), geographic(2.0, 0.5)]).
     | ?- geospatial::bbox_union(bbox(geographic(0.0, 0.0), geographic(1.0, 1.0)), bbox(geographic(-1.0, 0.5), geographic(0.5, 2.0)), BoundingBox).
     | ?- geospatial::bbox_expand(bbox(geographic(0.0, 0.0), geographic(0.0, 0.0)), 111.195, ExpandedBoundingBox).

Compute nearest points and distances to paths:

     | ?- geospatial::nearest_point_on_segment(geographic(1.0, 1.0), geographic(0.0, 0.0), geographic(0.0, 2.0), Nearest).
     | ?- geospatial::nearest_point_on_polyline(geographic(1.0, 1.0), [geographic(0.0, 0.0), geographic(0.0, 2.0), geographic(2.0, 2.0)], Nearest, Distance).
     | ?- geospatial::point_to_polyline_distance(geographic(1.0, 1.0), [geographic(0.0, 0.0), geographic(0.0, 2.0)], Distance).

Compute polyline and polygon lengths:

     | ?- geospatial::polyline_length([geographic(0.0, 0.0), geographic(0.0, 1.0), geographic(0.0, 2.0)], Length).
     | ?- geospatial::polyline_length([geographic(0.0, 0.0), geographic(0.0, 1.0)], vincenty, Length).
     | ?- geospatial::polyline_simplify([geographic(0.0, 0.0), geographic(0.5, 0.1), geographic(1.0, 0.0)], 20.0, Simplified).
     | ?- geospatial::polyline_split_at_distance([geographic(0.0, 0.0), geographic(0.0, 1.0), geographic(0.0, 2.0)], 111.195, Left, Right).
     | ?- geospatial::polyline_resample([geographic(0.0, 0.0), geographic(0.0, 1.0), geographic(0.0, 2.0)], 50.0, Resampled).
     | ?- geospatial::polygon_perimeter([geographic(0.0, 0.0), geographic(0.0, 1.0), geographic(1.0, 1.0), geographic(1.0, 0.0)], Perimeter).

Check polygon intersections:

     | ?- geospatial::polygons_intersect([geographic(0.0, 0.0), geographic(0.0, 2.0), geographic(2.0, 2.0), geographic(2.0, 0.0)], [geographic(1.0, 1.0), geographic(1.0, 3.0), geographic(3.0, 3.0), geographic(3.0, 1.0)]).


File: TheLogtalkHandbook-3.101.0.info,  Node: git,  Next: glicko2_ranker,  Prev: geospatial,  Up: Libraries

6.73 ‘git’
==========

This library provides access to a git project current branch and latest
commit data (e.g., commit hash).  Support for using this library on
Windows operating-systems is experimental and may or may not work
depending on the used Prolog backend.

* Menu:

* API documentation: API documentation<92>.
* Loading: Loading<93>.
* Testing: Testing<85>.
* Usage: Usage<40>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<92>,  Next: Loading<93>,  Up: git

6.73.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#git’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<93>,  Next: Testing<85>,  Prev: API documentation<92>,  Up: git

6.73.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(git(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<85>,  Next: Usage<40>,  Prev: Loading<93>,  Up: git

6.73.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(git(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<40>,  Prev: Testing<85>,  Up: git

6.73.4 Usage
------------

All predicates take as first argument a directory, which should be
either a git repository directory or a sub-directory of a git repository
directory.  The main predicate is ‘commit_log/3’.  It provides access to
the ‘git log’ command when called with the ‘--oneline -n 1
--pretty=format:’ options.  By passing as second argument the desired
format, it returns an atom with the formatted output.  For example:

     | ?- git::commit_log('/Users/pmoura/logtalk3', '%h%n%B', Output),
          write(Output), nl.

     eccaa1a2a
     Update SVG diagrams

     Output = 'eccaa1a2a\nUpdate SVG diagrams\n'
     yes

See e.g.  the official documentation on ‘git log’ pretty formats for
details:

‘https://git-scm.com/docs/pretty-formats’

Convenient predicates are also provided for commonly used formats such
as the commit author and the commit hash.  For example:

     | ?- git::commit_author('/Users/pmoura/Documents/Logtalk/logtalk3', Author).

     Author = 'Paulo Moura'
     yes

     | ?- git::commit_hash('/Users/pmoura/Documents/Logtalk/logtalk3', Hash).

     Hash = eccaa1a2a9495fef441915bbace84e0a4b0394a2
     yes

It’s also possible to get the name of the current local branch.  For
example:

     | ?- git::branch('/Users/pmoura/Documents/Logtalk/logtalk3', Branch).

     Branch = master
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: glicko2_ranker,  Next: glicko2_periodic_ranker,  Prev: git,  Up: Libraries

6.74 ‘glicko2_ranker’
=====================

Glicko-2 pairwise preference ranker.  It applies the standard Glicko-2
rating, rating-deviation, and volatility update equations over a single
synthetic rating period built from the aggregated pairwise outcomes of
the dataset.

The library implements the ‘ranker_protocol’ defined in the
‘ranking_protocols’ library.  It provides predicates for learning a
ranker from pairwise preferences, using it to order candidate items, and
exporting it as a list of predicate clauses or to a file.

Datasets are represented as objects implementing the
‘pairwise_ranking_dataset_protocol’ protocol from the
‘ranking_protocols’ library.  See the ‘test_datasets’ directory for
examples.  The current implementation requires a well-formed connected
pairwise dataset so that learned ratings remain globally comparable
across all ranked items.

* Menu:

* API documentation: API documentation<93>.
* Loading: Loading<94>.
* Testing: Testing<86>.
* Features: Features<21>.
* Rating semantics: Rating semantics<2>.
* Usage: Usage<41>.
* Options: Options<20>.
* Diagnostics syntax: Diagnostics syntax<8>.
* Ranker representation: Ranker representation<6>.
* References: References<13>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<93>,  Next: Loading<94>,  Up: glicko2_ranker

6.74.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#glicko2_ranker’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<94>,  Next: Testing<86>,  Prev: API documentation<93>,  Up: glicko2_ranker

6.74.2 Loading
--------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(glicko2_ranker(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<86>,  Next: Features<21>,  Prev: Loading<94>,  Up: glicko2_ranker

6.74.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(glicko2_ranker(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<21>,  Next: Rating semantics<2>,  Prev: Testing<86>,  Up: glicko2_ranker

6.74.4 Features
---------------

   - 'Pairwise Preference Learning': Learns one deterministic rating per
     item from pairwise outcomes.

   - 'Deterministic Single-Period Glicko-2 Semantics': Applies the
     standard Glicko-2 rating-period update equations over one synthetic
     rating period built from the aggregated pairwise results.

   - 'Configurable Rating Parameters': Exposes the initial rating,
     initial rating deviation, initial volatility, volatility constraint
     parameter, and volatility-solver tolerance as user options.

   - 'Integer Weight Fidelity': Preference weights must be positive
     integers and are interpreted as repeated unit outcomes inside the
     same rating period.

   - 'Deterministic Ranking': Orders candidate items by learned rating
     with deterministic tie-breaking.

   - 'Strict Dataset Validation': Rejects duplicate items, undeclared
     items, self-preferences, non-positive weights, and disconnected
     comparison graphs.

   - 'Extended Diagnostics': Preserves per-item rating deviations and
     volatilities in the learned ranker diagnostics.

   - 'Ranker Export': Learned rankers can be exported as self-contained
     terms.

   - 'Shared Ranking Infrastructure': Reuses the ‘ranking_protocols’
     helpers for option processing, dataset validation, diagnostics
     access, export, and candidate ranking.


File: TheLogtalkHandbook-3.101.0.info,  Node: Rating semantics<2>,  Next: Usage<41>,  Prev: Features<21>,  Up: glicko2_ranker

6.74.5 Rating semantics
-----------------------

This implementation uses a deterministic batch interpretation of
Glicko-2.  The whole dataset is treated as a single synthetic rating
period because the current pairwise dataset protocol does not encode
timestamps or rating-period boundaries.

The implementation converts ratings and rating deviations to the
internal Glicko-2 scale, applies the standard opponent-scaling factor
‘g(phi)’, expected-score function, variance term ‘v’, improvement
estimate ‘delta’, and volatility update iteration, and then converts the
updated ratings and deviations back to the conventional Glicko scale.

Positive integer preference weights are replayed as repeated unit
outcomes.  Datasets using non-integer preference weights are rejected
because they do not map cleanly to standard Glicko-2 update semantics.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<41>,  Next: Options<20>,  Prev: Rating semantics<2>,  Up: glicko2_ranker

6.74.6 Usage
------------

* Menu:

* Learning a ranker: Learning a ranker<6>.
* Inspecting diagnostics: Inspecting diagnostics<6>.
* Ranking candidate items: Ranking candidate items<6>.
* Exporting the ranker: Exporting the ranker<6>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Learning a ranker<6>,  Next: Inspecting diagnostics<6>,  Up: Usage<41>

6.74.6.1 Learning a ranker
..........................

     % Learn from a pairwise ranking dataset object
     | ?- glicko2_ranker::learn(my_dataset, Ranker).
     ...

     % Learn with custom Glicko-2 parameters
     | ?- glicko2_ranker::learn(my_dataset, Ranker, [initial_rating(1400.0), initial_deviation(300.0), initial_volatility(0.07), tau(0.4)]).
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Inspecting diagnostics<6>,  Next: Ranking candidate items<6>,  Prev: Learning a ranker<6>,  Up: Usage<41>

6.74.6.2 Inspecting diagnostics
...............................

     % Inspect model, options, deviations, volatilities, and dataset metadata
     | ?- glicko2_ranker::learn(my_dataset, Ranker),
          glicko2_ranker::diagnostics(Ranker, Diagnostics).
     Diagnostics = [...]
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Ranking candidate items<6>,  Next: Exporting the ranker<6>,  Prev: Inspecting diagnostics<6>,  Up: Usage<41>

6.74.6.3 Ranking candidate items
................................

     % Rank a candidate set from most preferred to least preferred
     | ?- glicko2_ranker::learn(my_dataset, Ranker),
          glicko2_ranker::rank(Ranker, [item_a, item_b, item_c], Ranking).
     Ranking = [...]
     ...

Candidate lists must be proper lists of unique, ground items declared by
the training dataset.  Invalid ranker terms, duplicate candidates, and
candidates containing variables are rejected with errors instead of
being silently accepted.


File: TheLogtalkHandbook-3.101.0.info,  Node: Exporting the ranker<6>,  Prev: Ranking candidate items<6>,  Up: Usage<41>

6.74.6.4 Exporting the ranker
.............................

Learned rankers can be exported as a list of clauses or to a file for
later use.

     % Export as predicate clauses
     | ?- glicko2_ranker::learn(my_dataset, Ranker),
          glicko2_ranker::export_to_clauses(my_dataset, Ranker, my_ranker, Clauses).
     Clauses = [my_ranker(glicko2_ranker(...))]
     ...

     % Export to a file
     | ?- glicko2_ranker::learn(my_dataset, Ranker),
          glicko2_ranker::export_to_file(my_dataset, Ranker, my_ranker, 'ranker.pl').
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<20>,  Next: Diagnostics syntax<8>,  Prev: Usage<41>,  Up: glicko2_ranker

6.74.7 Options
--------------

The following options can be passed to the ‘learn/3’ predicate:

   - ‘initial_rating(Rating)’: Initial rating assigned to every item.

   - ‘initial_deviation(Deviation)’: Initial rating deviation assigned
     to every item.

   - ‘initial_volatility(Volatility)’: Initial volatility assigned to
     every item.

   - ‘tau(Tau)’: Positive volatility-constraint parameter used by the
     Glicko-2 update.

   - ‘volatility_tolerance(Tolerance)’: Positive stopping tolerance used
     by the volatility root-finding iteration.

Datasets supplied to the ranker must use positive integer preference
weights.  Non-integer weights are rejected.


File: TheLogtalkHandbook-3.101.0.info,  Node: Diagnostics syntax<8>,  Next: Ranker representation<6>,  Prev: Options<20>,  Up: glicko2_ranker

6.74.8 Diagnostics syntax
-------------------------

The ‘diagnostics/2’ predicate returns a list of metadata terms with the
form:

     [
         model(glicko2_ranker),
         options(Options),
         rating_deviations(Deviations),
         volatilities(Volatilities),
         dataset_summary(DatasetSummary)
     ]


File: TheLogtalkHandbook-3.101.0.info,  Node: Ranker representation<6>,  Next: References<13>,  Prev: Diagnostics syntax<8>,  Up: glicko2_ranker

6.74.9 Ranker representation
----------------------------

The learned ranker is represented by a compound term of the form:

     glicko2_ranker(Items, Ratings, Diagnostics)

Where:

   - ‘Items’: List of ranked items.

   - ‘Ratings’: List of ‘Item-Rating’ pairs.

   - ‘Diagnostics’: List of metadata terms, including the effective
     options, per-item rating deviations, per-item volatilities, and
     dataset summary.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<13>,  Prev: Ranker representation<6>,  Up: glicko2_ranker

6.74.10 References
------------------

  1. Glickman, M. E. (2012).  'Example of the Glicko-2 system'.


File: TheLogtalkHandbook-3.101.0.info,  Node: glicko2_periodic_ranker,  Next: gradient_boosting_classifier,  Prev: glicko2_ranker,  Up: Libraries

6.75 ‘glicko2_periodic_ranker’
==============================

Multi-period Glicko-2 ranker over temporal pairwise game datasets.
Applies the standard Glicko-2 rating, rating-deviation, and volatility
update equations period by period using simultaneous player updates
inside each declared rating period.

This library implements the ‘ranker_protocol’ defined in the
‘ranking_protocols’ library.  It learns one rating per item from
datasets implementing the ‘temporal_pairwise_ranking_dataset_protocol’
protocol, processing declared rating periods in order and applying
simultaneous Glicko-2 player updates inside each period using the
standard Glicko-2 rating, rating-deviation, and volatility update
equations.

Draws are represented directly using game scores on the set ‘{0.0, 0.5,
1.0}’.  Players who are inactive in a declared period keep their rating
and volatility while their rating deviation is inflated for that period.

Players are initialized when they first play instead of being forced to
appear in the first declared period.

The library provides predicates for learning a ranker from temporal
pairwise games, using it to order candidate items, and exporting it as a
list of predicate clauses or to a file.

Datasets are represented as objects implementing the
‘temporal_pairwise_ranking_dataset_protocol’ protocol from the
‘ranking_protocols’ library.  See the ‘test_datasets’ directory for
examples.

* Menu:

* API documentation: API documentation<94>.
* Loading: Loading<95>.
* Testing: Testing<87>.
* Features: Features<22>.
* Rating semantics: Rating semantics<3>.
* Usage: Usage<42>.
* Options: Options<21>.
* Diagnostics syntax: Diagnostics syntax<9>.
* Ranker representation: Ranker representation<7>.
* References: References<14>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<94>,  Next: Loading<95>,  Up: glicko2_periodic_ranker

6.75.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#glicko2_periodic_ranker’ link in
a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<95>,  Next: Testing<87>,  Prev: API documentation<94>,  Up: glicko2_periodic_ranker

6.75.2 Loading
--------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(glicko2_periodic_ranker(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<87>,  Next: Features<22>,  Prev: Loading<95>,  Up: glicko2_periodic_ranker

6.75.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(glicko2_periodic_ranker(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<22>,  Next: Rating semantics<3>,  Prev: Testing<87>,  Up: glicko2_periodic_ranker

6.75.4 Features
---------------

   - 'Temporal Pairwise Game Learning': Learns one deterministic rating
     per item from temporal pairwise game results.

   - 'Deterministic Multi-Period Glicko-2 Semantics': Processes the
     declared rating periods in order and applies simultaneous Glicko-2
     player updates within each period.

   - 'Direct Draw Support': Uses explicit game scores on the set ‘{0.0,
     0.5, 1.0}’, allowing wins, draws, and losses to be represented
     directly.

   - 'Inactive-Period Deviation Inflation': Players who do not play in a
     declared period keep their rating and volatility while their rating
     deviation is inflated for that period.

   - 'Late Player Initialization': Players are initialized when they
     first appear in the dataset instead of being forced to play in the
     first declared period.

   - 'Configurable Rating Parameters': Exposes the initial rating,
     initial rating deviation, initial volatility, volatility constraint
     parameter, and volatility-solver tolerance as user options.

   - 'Deterministic Ranking': Orders candidate items by learned rating
     with deterministic tie-breaking.

   - 'Strict Dataset Validation': Rejects duplicate periods, unknown
     periods, undeclared items, self-games, illegal scores, and
     disconnected comparison graphs.

   - 'Extended Diagnostics': Preserves per-item rating deviations,
     volatilities, processed period count, and final period metadata in
     the learned ranker diagnostics.

   - 'Ranker Export': Learned rankers can be exported as self-contained
     terms.

   - 'Shared Ranking Infrastructure': Reuses the ‘ranking_protocols’
     helpers for option processing, dataset validation, diagnostics
     access, export, and candidate ranking.


File: TheLogtalkHandbook-3.101.0.info,  Node: Rating semantics<3>,  Next: Usage<42>,  Prev: Features<22>,  Up: glicko2_periodic_ranker

6.75.5 Rating semantics
-----------------------

This implementation uses the standard Glicko-2 update equations over
explicit rating periods supplied by the dataset.  The declared periods
are processed in order, and all active players in a period are updated
simultaneously from the pre-period ratings, deviations, and
volatilities.

Game results are represented directly using scores in the set ‘{0.0,
0.5, 1.0}’.  A score of ‘0.5’ denotes a draw.  Players who are inactive
in a period keep their rating and volatility, but their rating deviation
is inflated for that period according to the Glicko-2 inactivity rule.

Players are initialized when they first appear in a game rather than
being required to occur in the first declared period.  Items declared by
the dataset but never seen in a game are initialized after training so
they remain present in the learned ranker with the configured initial
parameters.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<42>,  Next: Options<21>,  Prev: Rating semantics<3>,  Up: glicko2_periodic_ranker

6.75.6 Usage
------------

* Menu:

* Learning a ranker: Learning a ranker<7>.
* Inspecting diagnostics: Inspecting diagnostics<7>.
* Ranking candidate items: Ranking candidate items<7>.
* Exporting the ranker: Exporting the ranker<7>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Learning a ranker<7>,  Next: Inspecting diagnostics<7>,  Up: Usage<42>

6.75.6.1 Learning a ranker
..........................

     % Learn from a temporal pairwise ranking dataset object
     | ?- glicko2_periodic_ranker::learn(my_dataset, Ranker).
     ...

     % Learn with custom Glicko-2 parameters
     | ?- glicko2_periodic_ranker::learn(my_dataset, Ranker, [initial_rating(1400.0), initial_deviation(300.0), initial_volatility(0.07), tau(0.4)]).
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Inspecting diagnostics<7>,  Next: Ranking candidate items<7>,  Prev: Learning a ranker<7>,  Up: Usage<42>

6.75.6.2 Inspecting diagnostics
...............................

     % Inspect model, options, deviations, volatilities, and period metadata
     | ?- glicko2_periodic_ranker::learn(my_dataset, Ranker),
          glicko2_periodic_ranker::diagnostics(Ranker, Diagnostics).
     Diagnostics = [...]
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Ranking candidate items<7>,  Next: Exporting the ranker<7>,  Prev: Inspecting diagnostics<7>,  Up: Usage<42>

6.75.6.3 Ranking candidate items
................................

     % Rank a candidate set from most preferred to least preferred
     | ?- glicko2_periodic_ranker::learn(my_dataset, Ranker),
          glicko2_periodic_ranker::rank(Ranker, [item_a, item_b, item_c], Ranking).
     Ranking = [...]
     ...

Candidate lists must be proper lists of unique, ground items declared by
the training dataset.  Invalid ranker terms, duplicate candidates, and
candidates containing variables are rejected with errors instead of
being silently accepted.


File: TheLogtalkHandbook-3.101.0.info,  Node: Exporting the ranker<7>,  Prev: Ranking candidate items<7>,  Up: Usage<42>

6.75.6.4 Exporting the ranker
.............................

Learned rankers can be exported as a list of clauses or to a file for
later use.

     % Export as predicate clauses
     | ?- glicko2_periodic_ranker::learn(my_dataset, Ranker),
          glicko2_periodic_ranker::export_to_clauses(my_dataset, Ranker, my_ranker, Clauses).
     Clauses = [my_ranker(glicko2_periodic_ranker(...))]
     ...

     % Export to a file
     | ?- glicko2_periodic_ranker::learn(my_dataset, Ranker),
          glicko2_periodic_ranker::export_to_file(my_dataset, Ranker, my_ranker, 'ranker.pl').
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<21>,  Next: Diagnostics syntax<9>,  Prev: Usage<42>,  Up: glicko2_periodic_ranker

6.75.7 Options
--------------

The following options can be passed to the ‘learn/3’ predicate:

   - ‘initial_rating(Rating)’: Initial rating assigned to a player when
     it is first initialized.

   - ‘initial_deviation(Deviation)’: Initial rating deviation assigned
     to a player when it is first initialized.

   - ‘initial_volatility(Volatility)’: Initial volatility assigned to a
     player when it is first initialized.

   - ‘tau(Tau)’: Positive volatility-constraint parameter used by the
     Glicko-2 update.

   - ‘volatility_tolerance(Tolerance)’: Positive stopping tolerance used
     by the volatility root-finding iteration.

Datasets supplied to the ranker must use legal game scores from the set
‘{0.0, 0.5, 1.0}’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Diagnostics syntax<9>,  Next: Ranker representation<7>,  Prev: Options<21>,  Up: glicko2_periodic_ranker

6.75.8 Diagnostics syntax
-------------------------

The ‘diagnostics/2’ predicate returns a list of metadata terms with the
form:

     [
         model(glicko2_periodic_ranker),
         options(Options),
         rating_deviations(Deviations),
         volatilities(Volatilities),
         periods_processed(PeriodsProcessed),
         final_period(FinalPeriod),
         dataset_summary(DatasetSummary)
     ]


File: TheLogtalkHandbook-3.101.0.info,  Node: Ranker representation<7>,  Next: References<14>,  Prev: Diagnostics syntax<9>,  Up: glicko2_periodic_ranker

6.75.9 Ranker representation
----------------------------

The learned ranker is represented by a compound term of the form:

     glicko2_periodic_ranker(Items, Ratings, Diagnostics)

Where:

   - ‘Items’: List of ranked items.

   - ‘Ratings’: List of ‘Item-Rating’ pairs.

   - ‘Diagnostics’: List of metadata terms, including the effective
     options, per-item rating deviations, per-item volatilities,
     processed period count, final period, and dataset summary.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<14>,  Prev: Ranker representation<7>,  Up: glicko2_periodic_ranker

6.75.10 References
------------------

  1. Glickman, M. E. (2012).  'Example of the Glicko-2 system'.


File: TheLogtalkHandbook-3.101.0.info,  Node: gradient_boosting_classifier,  Next: gradient_boosting_regression,  Prev: glicko2_periodic_ranker,  Up: Libraries

6.76 ‘gradient_boosting_classifier’
===================================

Gradient boosting classifier for tabular datasets using multinomial
additive models fitted by regression trees to softmax residuals.  At
each boosting stage the implementation fits one regression tree per
class and updates additive class scores using the configured learning
rate.

The library implements the ‘classifier_protocol’ defined in the
‘classification_protocols’ library.  It provides predicates for learning
a classifier from a dataset, using it to make predictions, estimating
class probabilities, and exporting it as a list of predicate clauses or
to a file.

Datasets are represented as objects implementing the ‘dataset_protocol’
protocol from the ‘classification_protocols’ library.  Continuous,
categorical, and mixed-feature datasets are supported through the reused
‘regression_tree’ backend.

* Menu:

* API documentation: API documentation<95>.
* Loading: Loading<96>.
* Testing: Testing<88>.
* Features: Features<23>.
* Options: Options<22>.
* Usage: Usage<43>.
* Classifier representation: Classifier representation<2>.
* References: References<15>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<95>,  Next: Loading<96>,  Up: gradient_boosting_classifier

6.76.1 API documentation
------------------------

Open the ‘../../docs/library_index.html#gradient_boosting_classifier’
link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<96>,  Next: Testing<88>,  Prev: API documentation<95>,  Up: gradient_boosting_classifier

6.76.2 Loading
--------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(gradient_boosting_classifier(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<88>,  Next: Features<23>,  Prev: Loading<96>,  Up: gradient_boosting_classifier

6.76.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(gradient_boosting_classifier(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<23>,  Next: Options<22>,  Prev: Testing<88>,  Up: gradient_boosting_classifier

6.76.4 Features
---------------

   - 'Multiclass Boosting': Fits one additive score function per class
     and predicts using the highest boosted score.

   - 'Regression Tree Backend': Reuses the ‘regression_tree’ library to
     fit residual models at each boosting stage.

   - 'Probability Estimation': Provides class probabilities using a
     softmax over the final additive scores.

   - 'Configurable Tree Complexity': Exposes boosting-stage tree depth,
     minimum leaf size, and minimum variance reduction options.

   - 'Tabular Datasets': Supports continuous, categorical, and
     mixed-feature datasets.

   - 'Classifier Export': Learned classifiers can be exported as
     predicate clauses or written to a file.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<22>,  Next: Usage<43>,  Prev: Features<23>,  Up: gradient_boosting_classifier

6.76.5 Options
--------------

The ‘learn/3’ predicate supports these options:

   - ‘number_of_estimators/1’ - number of boosting stages to fit
     (default: ‘25’)

   - ‘learning_rate/1’ - shrinkage factor applied to each stage
     prediction (default: ‘0.1’)

   - ‘maximum_depth/1’ - maximum depth of each regression tree (default:
     ‘3’)

   - ‘minimum_samples_leaf/1’ - minimum number of examples in a leaf
     (default: ‘1’)

   - ‘minimum_variance_reduction/1’ - minimum variance reduction
     required for a split (default: ‘0.0’)

   - ‘feature_scaling/1’ - whether to scale continuous features in the
     regression-tree backend (default: ‘false’)


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<43>,  Next: Classifier representation<2>,  Prev: Options<22>,  Up: gradient_boosting_classifier

6.76.6 Usage
------------

* Menu:

* Learning a classifier::
* Making predictions::
* Exporting the classifier::


File: TheLogtalkHandbook-3.101.0.info,  Node: Learning a classifier,  Next: Making predictions,  Up: Usage<43>

6.76.6.1 Learning a classifier
..............................

     | ?- gradient_boosting_classifier::learn(weather, Classifier).

     | ?- gradient_boosting_classifier::learn(iris_small, Classifier, [number_of_estimators(50), learning_rate(0.05)]).


File: TheLogtalkHandbook-3.101.0.info,  Node: Making predictions,  Next: Exporting the classifier,  Prev: Learning a classifier,  Up: Usage<43>

6.76.6.2 Making predictions
...........................

     | ?- gradient_boosting_classifier::learn(weather, Classifier),
          gradient_boosting_classifier::predict(Classifier, [outlook-overcast, temperature-mild, humidity-high, windy-false], Class).

     | ?- gradient_boosting_classifier::learn(mixed, Classifier),
          gradient_boosting_classifier::predict_probabilities(Classifier, [age-40, income-60000, student-yes, credit_rating-fair], Probabilities).


File: TheLogtalkHandbook-3.101.0.info,  Node: Exporting the classifier,  Prev: Making predictions,  Up: Usage<43>

6.76.6.3 Exporting the classifier
.................................

     | ?- gradient_boosting_classifier::learn(weather, Classifier),
          gradient_boosting_classifier::export_to_clauses(weather, Classifier, classify, Clauses).

     | ?- gradient_boosting_classifier::learn(weather, Classifier),
          gradient_boosting_classifier::export_to_file(weather, Classifier, classify, 'classifier.pl').


File: TheLogtalkHandbook-3.101.0.info,  Node: Classifier representation<2>,  Next: References<15>,  Prev: Usage<43>,  Up: gradient_boosting_classifier

6.76.7 Classifier representation
--------------------------------

The learned classifier is represented as a compound term with the form:

     gradient_boosting_classifier(Classes, InitialScores, StageTrees, Options)

Where:

   - ‘Classes’: list of class labels

   - ‘InitialScores’: list of initial log-prior scores, one per class

   - ‘StageTrees’: list of ‘stage_trees(ClassTrees)’ terms, where each
     ‘ClassTrees’ value contains ‘class_tree(Class, LearningRate, Tree)’
     terms

   - ‘Options’: merged training options used to learn the classifier

When exported using ‘export_to_clauses/4’ or ‘export_to_file/4’, this
classifier term is serialized directly as the single argument of the
generated predicate clause so that the exported model can be loaded and
reused as-is.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<15>,  Prev: Classifier representation<2>,  Up: gradient_boosting_classifier

6.76.8 References
-----------------

  1. Friedman, J.H. (2001).  “Greedy Function Approximation: A Gradient
     Boosting Machine”.

  2. Hastie, T., Tibshirani, R. and Friedman, J. (2009).  “The Elements
     of Statistical Learning”.  Chapter 10.

  3. Bishop, C.M. (2006).  “Pattern Recognition and Machine Learning”.
     Section 14.4.


File: TheLogtalkHandbook-3.101.0.info,  Node: gradient_boosting_regression,  Next: grammars,  Prev: gradient_boosting_classifier,  Up: Libraries

6.77 ‘gradient_boosting_regression’
===================================

Gradient boosting regression supporting continuous and mixed-feature
datasets.  Builds an additive ensemble of regression trees by repeatedly
fitting the current residuals under squared-error loss.  Starts from the
arithmetic mean of the training targets and then adds a scaled tree
prediction at each boosting stage.

The library implements the ‘regressor_protocol’ defined in the
‘regression_protocols’ library and learns an additive ensemble of
regression trees by repeatedly fitting the current residuals under
squared-error loss.

* Menu:

* API documentation: API documentation<96>.
* Loading: Loading<97>.
* Testing: Testing<89>.
* Features: Features<24>.
* Regressor representation: Regressor representation<4>.
* Diagnostics syntax: Diagnostics syntax<10>.
* Options: Options<23>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<96>,  Next: Loading<97>,  Up: gradient_boosting_regression

6.77.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#gradient_boosting_regression’
link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<97>,  Next: Testing<89>,  Prev: API documentation<96>,  Up: gradient_boosting_regression

6.77.2 Loading
--------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(gradient_boosting_regression(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<89>,  Next: Features<24>,  Prev: Loading<97>,  Up: gradient_boosting_regression

6.77.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(gradient_boosting_regression(tester)).

To run the performance benchmark suite, load the
‘tester_performance.lgt’ file:

     | ?- logtalk_load(gradient_boosting_regression(tester_performance)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<24>,  Next: Regressor representation<4>,  Prev: Testing<89>,  Up: gradient_boosting_regression

6.77.4 Features
---------------

   - 'Residual Fitting': Fits each regression tree to the residuals of
     the current additive model under squared-error loss.

   - 'Shrinkage': Supports a fixed learning rate to scale stage
     contributions and reduce overfitting.

   - 'Continuous and Mixed Features': Supports continuous attributes and
     categorical attributes encoded by the underlying regression-tree
     learner.

   - 'Tree Configuration': Exposes the underlying regression-tree depth,
     minimum-leaf, variance-reduction, and scaling options.

   - 'Diagnostics Metadata': Learned regressors record model name,
     target, training example count, initial prediction, fitted stage
     count, and effective options, accessible using the shared
     regression diagnostics predicates.

   - 'Model Export': Learned regressors can be exported as predicate
     clauses or written to a file.

   - 'Reference Benchmarks': Includes a dedicated performance suite
     reporting training time, RMSE, and MAE for representative
     regression datasets.


File: TheLogtalkHandbook-3.101.0.info,  Node: Regressor representation<4>,  Next: Diagnostics syntax<10>,  Prev: Features<24>,  Up: gradient_boosting_regression

6.77.5 Regressor representation
-------------------------------

The learned regressor is represented by default as:

   - ‘gradient_boosting_regressor(InitialPrediction, WeightedTrees,
     Diagnostics)’

The exported predicate clauses therefore use the shape:

   - ‘Functor(InitialPrediction, WeightedTrees, Diagnostics)’

In this representation, ‘WeightedTrees’ contains
‘weighted_tree(LearningRate, Tree)’ terms and ‘Diagnostics’ stores
training metadata including the effective options.


File: TheLogtalkHandbook-3.101.0.info,  Node: Diagnostics syntax<10>,  Next: Options<23>,  Prev: Regressor representation<4>,  Up: gradient_boosting_regression

6.77.6 Diagnostics syntax
-------------------------

The ‘diagnostics/2’ predicate returns a list of metadata terms with the
form:

     [
         model(gradient_boosting_regression),
         target(Target),
         training_example_count(TrainingExampleCount),
         options(Options),
         initial_prediction(InitialPrediction),
         stage_count(StageCount)
     ]

Where:

   - ‘model(gradient_boosting_regression)’ identifies the learning
     algorithm that produced the regressor.

   - ‘target(Target)’ stores the target attribute name declared by the
     training dataset.

   - ‘training_example_count(TrainingExampleCount)’ stores the number of
     examples used during training.

   - ‘options(Options)’ stores the effective learning options after
     merging the user options with the library defaults.

   - ‘initial_prediction(InitialPrediction)’ stores the constant
     prediction used to initialize the additive model before fitting any
     trees.

   - ‘stage_count(StageCount)’ stores the number of boosting stages that
     were actually fitted.

Use the ‘regression_protocols’ ‘diagnostic/2’ and ‘regressor_options/2’
helper predicates when you only need a single metadata term or the
effective options.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<23>,  Prev: Diagnostics syntax<10>,  Up: gradient_boosting_regression

6.77.7 Options
--------------

The ‘learn/3’ predicate accepts the following options:

   - ‘number_of_estimators/1’: Maximum number of boosting stages to fit.
     Each stage adds one regression tree to the ensemble.  The default
     is ‘50’.  Training can stop before reaching this limit when the
     residual sum of squares becomes negligible.

   - ‘learning_rate/1’: Shrinkage factor applied to each stage
     prediction before it is added to the current model.  Smaller values
     usually require more stages but can improve generalization.  The
     default is ‘0.1’.

   - ‘maximum_depth/1’: Maximum depth allowed for each regression tree
     used as a base learner.  Lower values produce weaker, simpler
     trees; higher values allow each stage to model more complex
     residual structure.  The default is ‘3’.

   - ‘minimum_samples_leaf/1’: Minimum number of training examples
     required in each leaf of a base learner tree.  Increasing this
     value makes the fitted trees more conservative and can reduce
     overfitting.  The default is ‘1’.

   - ‘minimum_variance_reduction/1’: Minimum reduction in target
     variance required to accept a split when fitting a base learner
     tree.  Larger values make tree growth stricter by rejecting weak
     splits.  The default is ‘0.0’.

   - ‘feature_scaling/1’: Controls continuous-feature scaling in the
     underlying regression-tree learner.  The accepted values are ‘true’
     and ‘false’.  The default is ‘false’.


File: TheLogtalkHandbook-3.101.0.info,  Node: grammars,  Next: graphs,  Prev: gradient_boosting_regression,  Up: Libraries

6.78 ‘grammars’
===============

This library provides Definite Clause Grammars (DCGs) for common parsing
tasks.  The DCGs support parsing both lists of characters (aka chars)
and lists of character codes (aka codes).

Currently, four groups of DCGs are available, each defined in its own
file:

   - blanks (‘blank_grammars.lgt’)

   - numbers (‘number_grammars.lgt’)

   - sequences (‘sequence_grammars.lgt’)

   - IP addresses (‘ip_grammars.lgt’; depends on ‘number_grammars.lgt’)

* Menu:

* API documentation: API documentation<97>.
* Loading: Loading<98>.
* Testing: Testing<90>.
* Usage: Usage<44>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<97>,  Next: Loading<98>,  Up: grammars

6.78.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#grammars’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<98>,  Next: Testing<90>,  Prev: API documentation<97>,  Up: grammars

6.78.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(grammars(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<90>,  Next: Usage<44>,  Prev: Loading<98>,  Up: grammars

6.78.3 Testing
--------------

Minimal tests for this library predicates can be run by loading the
‘tester.lgt’ file:

     | ?- logtalk_load(grammars(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<44>,  Prev: Testing<90>,  Up: grammars

6.78.4 Usage
------------

The library uses (when necessary) parametric objects where the single
parameter can be either ‘chars’ or ‘codes’.  The parameter must be bound
when using the DCGs.  For example, when using implicit message-sending:

     :- uses(blank_grammars(chars), [
         white_spaces//0, new_lines//0
     ]).


File: TheLogtalkHandbook-3.101.0.info,  Node: graphs,  Next: gravatar,  Prev: grammars,  Up: Libraries

6.79 ‘graphs’
=============

The ‘graphs’ library implements predicates for handling
directed/undirected weighted/unweighted graphs.  Graphs are represented
using a dictionary where keys are vertices and values are sorted lists
of neighbors (vertex names for unweighted graphs, ‘Vertex-Weight’ pairs
for weighted graphs).

The four graph types are implemented as parametric objects where the
parameter specifies the dictionary implementation to use (e.g.,
‘avltree’, ‘rbtree’, ‘bintree’, or ‘splaytree’).  This allows for easy
experimentation (e.g., for performance analysis) with different
dictionary backends.  Non-parametric objects are also provided for each
graph type using the ‘avltree’ dictionary implementation.

The common protocol for all graph types is defined in ‘graph_protocol’.
There are also ‘directed_graph_protocol’ and ‘undirected_graph_protocol’
for protocols specific to directed and undirected graphs, respectively.
Additional predicates specific to each graph type (e.g., ‘transpose/2’,
‘topological_sort/2’, ‘min_path/5’, ‘min_tree/3’) are declared in the
individual graph objects.

* Menu:

* API documentation: API documentation<98>.
* Loading: Loading<99>.
* Testing: Testing<91>.
* Usage: Usage<45>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<98>,  Next: Loading<99>,  Up: graphs

6.79.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#graphs’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<99>,  Next: Testing<91>,  Prev: API documentation<98>,  Up: graphs

6.79.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(graphs(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<91>,  Next: Usage<45>,  Prev: Loading<99>,  Up: graphs

6.79.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(graphs(tester)).

This library provides also a ‘graph_types’ category for type-checking
and arbitrary generation of graph-related terms.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<45>,  Prev: Testing<91>,  Up: graphs

6.79.4 Usage
------------

* Menu:

* Graph types::
* Creating graphs::
* Querying graphs::
* Undirected graphs::


File: TheLogtalkHandbook-3.101.0.info,  Node: Graph types,  Next: Creating graphs,  Up: Usage<45>

6.79.4.1 Graph types
....................

   - ‘unweighted_directed_graph(Dictionary)’ - Unweighted directed graph

   - ‘unweighted_undirected_graph(Dictionary)’ - Unweighted undirected
     graph

   - ‘weighted_directed_graph(Dictionary)’ - Weighted directed graph

   - ‘weighted_undirected_graph(Dictionary)’ - Weighted undirected graph


File: TheLogtalkHandbook-3.101.0.info,  Node: Creating graphs,  Next: Querying graphs,  Prev: Graph types,  Up: Usage<45>

6.79.4.2 Creating graphs
........................

Create an empty graph:

     | ?- unweighted_directed_graph(avltree)::new(Graph).

Create a graph from a list of edges:

     | ?- unweighted_directed_graph(avltree)::new([1-2, 2-3, 3-1], Graph).

Create a graph from vertices and edges:

     | ?- unweighted_directed_graph(avltree)::new([1,2,3,4], [1-2, 2-3], Graph).

For weighted graphs, edges use the format ‘(V1-V2)-Weight’:

     | ?- weighted_directed_graph(avltree)::new([(a-b)-5, (b-c)-3], Graph).


File: TheLogtalkHandbook-3.101.0.info,  Node: Querying graphs,  Next: Undirected graphs,  Prev: Creating graphs,  Up: Usage<45>

6.79.4.3 Querying graphs
........................

     | ?- unweighted_directed_graph(avltree)::new([1-2, 2-3], Graph),
          unweighted_directed_graph(avltree)::vertices(Graph, Vertices),
          unweighted_directed_graph(avltree)::edges(Graph, Edges),
          unweighted_directed_graph(avltree)::neighbors(1, Graph, Neighbors).


File: TheLogtalkHandbook-3.101.0.info,  Node: Undirected graphs,  Prev: Querying graphs,  Up: Usage<45>

6.79.4.4 Undirected graphs
..........................

Undirected edges are stored internally as two directed edges.  The
‘edges/2’ predicate returns each undirected edge only once (with ‘V1 @=<
V2’).  For undirected graphs, ‘neighbors/3’ excludes self-loops.


File: TheLogtalkHandbook-3.101.0.info,  Node: gravatar,  Next: gsp_pattern_miner,  Prev: graphs,  Up: Libraries

6.80 ‘gravatar’
===============

The ‘gravatar’ library provides a portable client for retrieving
Gravatar profile information using the Gravatar REST API. It uses
‘http_client’ with the ‘http_process_transport’ transport for HTTPS
support and reuses the ‘crypto’, ‘options’, ‘os’, ‘json’, ‘url’, and
‘rest’ libraries.

This library can be used with backend Prolog systems that support
unbound integer arithmetic and the ‘sockets’ library: ECLiPSe, SICStus
Prolog, SWI-Prolog, Trealla Prolog, and XVM.

* Menu:

* API documentation: API documentation<99>.
* Loading: Loading<100>.
* Testing: Testing<92>.
* Basic usage: Basic usage<2>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<99>,  Next: Loading<100>,  Up: gravatar

6.80.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#gravatar’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<100>,  Next: Testing<92>,  Prev: API documentation<99>,  Up: gravatar

6.80.2 Loading
--------------

To load the library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(gravatar(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<92>,  Next: Basic usage<2>,  Prev: Loading<100>,  Up: gravatar

6.80.3 Testing
--------------

To test this library, load the ‘tester.lgt’ file:

     | ?- logtalk_load(gravatar(tester)).

To run the optional live tests against the public Gravatar API, define
the ‘LOGTALK_GRAVATAR_API_KEY’ environment variable and load the
‘tester_live.lgt’ file:

     | ?- logtalk_load(gravatar(tester_live)).

The live tests exercise the account profile for ‘pmoura@logtalk.org’ and
are skipped automatically when the API key environment variable is not
defined.


File: TheLogtalkHandbook-3.101.0.info,  Node: Basic usage<2>,  Prev: Testing<92>,  Up: gravatar

6.80.4 Basic usage
------------------

     | ?- gravatar::profile('user@example.com', Profile).
     ...

For authenticated requests, pass an API key explicitly:

     | ?- gravatar::profile('user@example.com', Profile, [api_key('...')]).
     ...

When the ‘api_key/1’ option is omitted, the client uses the
‘LOGTALK_GRAVATAR_API_KEY’ environment variable when it is defined.  If
neither source is available, the request is sent without authentication.
But this last resort is strongly discouraged.

The decoded profile is returned as a JSON term.  Convenience predicates
are available for common profile fields:

     | ?- gravatar::profile('user@example.com', Profile),
          gravatar::display_name(Profile, DisplayName),
          gravatar::avatar_url(Profile, AvatarURL).
     ...

The supported helpers are ‘hash/2’, ‘display_name/2’, ‘profile_url/2’,
‘avatar_url/2’, ‘avatar_alt_text/2’, ‘location/2’, ‘job_title/2’,
‘company/2’, ‘description/2’, ‘pronouns/2’, ‘verified_accounts/2’, and
‘section_visibility/2’.  The generic ‘field/3’ predicate can be used for
any top-level profile field.


File: TheLogtalkHandbook-3.101.0.info,  Node: gsp_pattern_miner,  Next: hashes,  Prev: gravatar,  Up: Libraries

6.81 ‘gsp_pattern_miner’
========================

GSP sequential pattern miner for sequence datasets.  The library depends
on the ‘sequential_pattern_mining_protocols’ support library, implements
the generic ‘pattern_miner_protocol’ defined in the
‘pattern_mining_protocols’ core library, and mines frequent sequential
patterns using prefix-indexed candidate joins, pruning candidates whose
immediate subpatterns are not all frequent, and counting singleton and
candidate supports in batched horizontal dataset scans.

Requires a dataset implementing ‘sequence_dataset_protocol’ with
sequences represented as ordered lists of canonical sorted itemsets over
a declared item domain.

* Menu:

* API documentation: API documentation<100>.
* Loading: Loading<101>.
* Testing: Testing<93>.
* Features: Features<25>.
* Options: Options<24>.
* Pattern miner representation: Pattern miner representation<5>.
* References: References<16>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<100>,  Next: Loading<101>,  Up: gsp_pattern_miner

6.81.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#gsp_pattern_miner’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<101>,  Next: Testing<93>,  Prev: API documentation<100>,  Up: gsp_pattern_miner

6.81.2 Loading
--------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(gsp_pattern_miner(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<93>,  Next: Features<25>,  Prev: Loading<101>,  Up: gsp_pattern_miner

6.81.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(gsp_pattern_miner(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<25>,  Next: Options<24>,  Prev: Testing<93>,  Up: gsp_pattern_miner

6.81.4 Features
---------------

   - 'Level-Wise Mining': Builds longer frequent sequences by extending
     the current frequent level.

   - 'Join-Based Candidates': Generates candidate sequences by joining
     compatible frequent patterns from the previous level.

   - 'Support-Pruned Candidates': Prunes candidates whose immediate
     subpatterns are not all frequent.

   - 'Batched Horizontal Support Counting': Counts singleton and
     candidate supports using horizontal scans over the sequence
     database at each level.

   - 'Canonical Sequences': Validates that itemsets are sorted,
     duplicate-free, non-empty, and restricted to declared items.

   - 'Flexible Support Thresholds': Supports relative minimum support
     and absolute minimum support count.

   - 'Model Export': Mined pattern collections can be exported as
     predicate clauses or written to a file.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<24>,  Next: Pattern miner representation<5>,  Prev: Features<25>,  Up: gsp_pattern_miner

6.81.5 Options
--------------

The ‘mine/3’ predicate accepts the following options:

   - ‘minimum_support/1’: Relative minimum support threshold in the
     interval ‘]0.0, 1.0]’.  The default is ‘0.5’.

   - ‘minimum_support_count/1’: Absolute minimum support count.  When
     both support options are provided, this option takes precedence.

   - ‘maximum_pattern_length/1’: Maximum total number of items in a
     mined sequential pattern.  The default is ‘1000’, effectively
     capped by the longest sequence in the dataset.

   - ‘minimum_pattern_length/1’: Minimum total number of items retained
     in the mined result.  The default is ‘1’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Pattern miner representation<5>,  Next: References<16>,  Prev: Options<24>,  Up: gsp_pattern_miner

6.81.6 Pattern miner representation
-----------------------------------

The mined pattern miner result is represented by a compound term with
the functor chosen by the implementation and arity 3.  For example:

     gsp_pattern_miner(ItemDomain, Patterns, Options)

Where:

   - ‘ItemDomain’: Canonical sorted list of declared dataset items.

   - ‘Patterns’: List of ‘sequence_pattern(Pattern, SupportCount)’ terms
     ordered first by total item count and then lexicographically.

   - ‘Options’: Effective mining options used to mine the frequent
     sequential patterns.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<16>,  Prev: Pattern miner representation<5>,  Up: gsp_pattern_miner

6.81.7 References
-----------------

  1. Srikant, R. and Agrawal, R. (1996) - “Mining sequential patterns:
     Generalizations and performance improvements”.


File: TheLogtalkHandbook-3.101.0.info,  Node: hashes,  Next: hdbscan_clusterer,  Prev: gsp_pattern_miner,  Up: Libraries

6.82 ‘hashes’
=============

The ‘hashes’ library provides portable implementations of several
commonly used hashing algorithms.  All hash objects implement the
‘hash_protocol’ protocol by providing a ‘hash/2’ predicate that takes a
list of bytes and returns the computed hash as a lowercase hexadecimal
atom.

* Menu:

* API documentation: API documentation<101>.
* Loading: Loading<102>.
* Testing: Testing<94>.
* Supported hash algorithms::
* HMAC compatibility::
* Segmented hashing::
* Examples: Examples<170>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<101>,  Next: Loading<102>,  Up: hashes

6.82.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#hashes’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<102>,  Next: Testing<94>,  Prev: API documentation<101>,  Up: hashes

6.82.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(hashes(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<94>,  Next: Supported hash algorithms,  Prev: Loading<102>,  Up: hashes

6.82.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(hashes(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Supported hash algorithms,  Next: HMAC compatibility,  Prev: Testing<94>,  Up: hashes

6.82.4 Supported hash algorithms
--------------------------------

The library implements the following hashing algorithms:

   - DJB2 32-bit (‘djb2_32’)

   - DJB2 64-bit (‘djb2_64’)

   - SDBM 32-bit (‘sdbm_32’)

   - SDBM 64-bit (‘sdbm_64’)

   - FNV-1a 32-bit (‘fnv1a_32’)

   - FNV-1a 64-bit (‘fnv1a_64’)

   - SipHash (‘siphash_2_4’)

   - CRC-32 parametric reflected implementation
     (‘crc32_reflected(Polynomial)’)

   - CRC-32 parametric non-reflected implementation
     (‘crc32_non_reflected(Polynomial, Initial, FinalXor,
     AppendLength)’)

   - CRC-32/ISO-HDLC (‘crc32b’)

   - CRC-32C/Castagnoli (‘crc32c’)

   - CRC-32/POSIX (‘crc32posix’)

   - CRC-32/MPEG-2 (‘crc32mpeg2’)

   - CRC-32/BZIP2 (‘crc32bzip2’)

   - CRC-32Q (aka CRC-32/AIXM) (‘crc32q’)

   - MurmurHash3 x86 32-bit (‘murmurhash3_x86_32’)

   - MurmurHash3 x86 128-bit (‘murmurhash3_x86_128’)

   - MurmurHash3 x64 128-bit (‘murmurhash3_x64_128’)

   - BLAKE2s (‘blake2s’)

   - SHA3-224 (‘sha3_224’)

   - SHA3-256 (‘sha3_256’)

   - SHA3-384 (‘sha3_384’)

   - SHA3-512 (‘sha3_512’)

   - SHAKE128 (‘shake128(OutputBytes)’)

   - SHAKE256 (‘shake256(OutputBytes)’)

   - MD5 (‘md5’)

   - SHA1 (‘sha1’)

   - SHA224 (‘sha224’)

   - SHA256 (‘sha256’)

   - BLAKE2b (‘blake2b’)

   - SHA-384 (‘sha384’)

   - SHA-512 (‘sha512’)

   - SHA-512/256 (‘sha512_256’)

The ‘djb2_64’, ‘sdbm_64’, ‘fnv1a_64’, ‘siphash_2_4’,
‘murmurhash3_x86_128’, ‘murmurhash3_x64_128’, ‘blake2b’, ‘sha3_224’,
‘sha3_256’, ‘sha3_384’, ‘sha3_512’, ‘shake128(OutputBytes)’,
‘shake256(OutputBytes)’, ‘sha1’, ‘sha224’, ‘sha256’, ‘sha384’, ‘sha512’,
and ‘sha512_256’ objects are only loaded on backend Prolog compilers
supporting unbounded integer arithmetic.

SHA-224 and SHA-384 are based on the same block processing as SHA-256
and SHA-512, respectively, differing only in their initial hash values
and in truncating the output to 224 or 384 bits.

The SHAKE objects are parametric extensible-output functions.  Pass the
number of output bytes to generate when constructing the object.

The ‘crc32_reflected(Polynomial)’ object implements a reflected CRC-32
family using initial value ‘0xFFFFFFFF’ and final xor value
‘0xFFFFFFFF’, where ‘Polynomial’ is the reflected CRC-32 polynomial.

The ‘crc32_non_reflected(Polynomial, Initial, FinalXor, AppendLength)’
object implements a non-reflected CRC-32 family using a canonical
polynomial, configurable initial and final xor values, and an
‘AppendLength’ flag that controls whether the message length is appended
as little-endian bytes.

The ‘crc32b’ object implements the CRC-32/ISO-HDLC variant, also widely
used by Ethernet, gzip, and PKZip.  It uses reflected input/output
processing, the reflected polynomial ‘0xEDB88320’ (equivalent to the
canonical polynomial ‘0x04C11DB7’), initial value ‘0xFFFFFFFF’, and
final xor value ‘0xFFFFFFFF’.

The ‘crc32c’ object implements the CRC-32C/Castagnoli variant using
reflected input/output processing, the reflected polynomial ‘0x82F63B78’
(equivalent to the canonical polynomial ‘0x1EDC6F41’), initial value
‘0xFFFFFFFF’, and final xor value ‘0xFFFFFFFF’.

The ‘crc32posix’ object implements the CRC-32/POSIX variant used by the
standard ‘cksum’ utility.  It is an instance of the non-reflected
‘crc32_non_reflected(Polynomial, Initial, FinalXor, AppendLength)’
family: it uses the canonical polynomial ‘0x04C11DB7’, initial value
‘0x00000000’, processes bits most-significant first, appends the message
length as little-endian bytes, and applies a final xor value of
‘0xFFFFFFFF’.

The ‘crc32mpeg2’ object implements the CRC-32/MPEG-2 variant using the
canonical polynomial ‘0x04C11DB7’, initial value ‘0xFFFFFFFF’, no
appended length bytes, and final xor value ‘0x00000000’.

The ‘crc32bzip2’ object implements the CRC-32/BZIP2 variant using the
canonical polynomial ‘0x04C11DB7’, initial value ‘0xFFFFFFFF’, no
appended length bytes, and final xor value ‘0xFFFFFFFF’.

The ‘crc32q’ object implements the CRC-32Q variant, also used by
AIXM-style formats, using the canonical polynomial ‘0x814141AB’, initial
value ‘0x00000000’, no appended length bytes, and final xor value
‘0x00000000’.

The ‘siphash_2_4’ object uses the standard reference key ‘00 01 02 ...
0f’.  For custom keys, use the parametric object ‘siphash_2_4(Key)’
where ‘Key’ is a list of 16 bytes.

The implementations of the hashing algorithms make no attempt to
validate that the input is a list of bytes.  When necessary, use the
‘types’ library ‘type::check(list(byte), Input)’ goal before calling the
‘hash/2’ predicate.


File: TheLogtalkHandbook-3.101.0.info,  Node: HMAC compatibility,  Next: Segmented hashing,  Prev: Supported hash algorithms,  Up: hashes

6.82.5 HMAC compatibility
-------------------------

The fixed-size cryptographic hash objects that can be safely used with
HMAC (‘blake2s’, ‘md5’, ‘sha1’, ‘sha224’, ‘sha256’, ‘blake2b’, ‘sha384’,
‘sha512’, ‘sha512_256’, ‘sha3_224’, ‘sha3_256’, ‘sha3_384’, and
‘sha3_512’) also implement the ‘hash_digest_protocol’ protocol.  This
protocol adds ‘digest/2’, ‘digest_size/1’, and ‘block_size/1’ predicates
so that libraries such as ‘hmac’ can compute keyed digests without
duplicating hash function internals.


File: TheLogtalkHandbook-3.101.0.info,  Node: Segmented hashing,  Next: Examples<170>,  Prev: HMAC compatibility,  Up: hashes

6.82.6 Segmented hashing
------------------------

Objects implementing the ‘hash_state_protocol’ protocol (which extends
‘hash_protocol’) additionally provide ‘new_hash_state/1’,
‘update_hash_state/3’, and ‘final_hash_state/2’ predicates for genuine
incremental hash computation.  Unlike computing a hash from a single,
fully materialized message, these predicates let the caller feed the
message to the hash function one chunk at a time (e.g.  as each chunk is
read from a file or a network stream), discarding each chunk as soon as
it has been folded into the state.  Only the current chunk and a small,
bounded amount of algorithm state (for block-padded and rate-limited
algorithms, a leftover buffer smaller than one block or rate) are ever
resident at once, regardless of the total message length.

All hashing algorithms in this library implement ‘hash_state_protocol’.

Example, hashing a message fed in three chunks:

     | ?- md5::new_hash_state(S0),
          md5::update_hash_state(S0, [84,104,101], S1),
          md5::update_hash_state(S1, [32,113,117,105,99,107], S2),
          md5::update_hash_state(S2, [32,98,114,111,119,110], S3),
          md5::final_hash_state(S3, Hash).
     Hash = '5aa207e85988921b8733912c4f526c80'
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<170>,  Prev: Segmented hashing,  Up: hashes

6.82.7 Examples
---------------

Compute the SHA-256 hash of a text message:

     | ?- atom_codes('The quick brown fox jumps over the lazy dog', Bytes),
          sha256::hash(Bytes, Hash).
     Bytes = [84,104,101,32,113,117,105,99,107,32,98,114,111,119,110,32,102,111,120,32,106,117,109,112,115,32,111,118,101,114,32,116,104,101,32,108,97,122,121,32,100,111,103],
     Hash = 'd7a8fbb307d7809469ca9abcb0082e4f8d5651e46d3cdb762d02d0bf37c9e592'
     yes

Compute a 32-byte SHAKE128 digest:

     | ?- atom_codes('The quick brown fox jumps over the lazy dog', Bytes),
          shake128(32)::hash(Bytes, Hash).
     Bytes = [84,104,101,32,113,117,105,99,107,32,98,114,111,119,110,32,102,111,120,32,106,117,109,112,115,32,111,118,101,114,32,116,104,101,32,108,97,122,121,32,100,111,103],
     Hash = 'f4202e3c5852f9182a0430fd8144f0a74b95e7417ecae17db0f8cfeed0e3e66e'
     yes

Compute the CRC-32/ISO-HDLC checksum for the standard ‘123456789’ test
vector:

     | ?- atom_codes('123456789', Bytes), crc32b::hash(Bytes, Hash).
     Bytes = [49,50,51,52,53,54,55,56,57],
     Hash = 'cbf43926'
     yes

Compute the CRC-32C/Castagnoli checksum for the standard ‘123456789’
test vector:

     | ?- atom_codes('123456789', Bytes), crc32c::hash(Bytes, Hash).
     Bytes = [49,50,51,52,53,54,55,56,57],
     Hash = 'e3069283'
     yes

Compute the CRC-32/POSIX checksum for the standard ‘123456789’ test
vector:

     | ?- atom_codes('123456789', Bytes), crc32posix::hash(Bytes, Hash).
     Bytes = [49,50,51,52,53,54,55,56,57],
     Hash = '377a6011'
     yes

Compute the CRC-32/MPEG-2 checksum for the standard ‘123456789’ test
vector:

     | ?- atom_codes('123456789', Bytes), crc32mpeg2::hash(Bytes, Hash).
     Bytes = [49,50,51,52,53,54,55,56,57],
     Hash = '0376e6e7'
     yes

Compute the CRC-32/BZIP2 checksum for the standard ‘123456789’ test
vector:

     | ?- atom_codes('123456789', Bytes), crc32bzip2::hash(Bytes, Hash).
     Bytes = [49,50,51,52,53,54,55,56,57],
     Hash = 'fc891918'
     yes

Compute the CRC-32Q checksum for the standard ‘123456789’ test vector:

     | ?- atom_codes('123456789', Bytes), crc32q::hash(Bytes, Hash).
     Bytes = [49,50,51,52,53,54,55,56,57],
     Hash = '3010bf7f'
     yes

Use SipHash-2-4 with a custom key on a backend supporting unbounded
integer arithmetic:

     | ?- siphash_2_4([0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15])::hash([0,1,2,3], Hash).
     Hash = 'cf2794e0277187b7'
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: hdbscan_clusterer,  Next: heaps,  Prev: hashes,  Up: Libraries

6.83 ‘hdbscan_clusterer’
========================

Simplified HDBSCAN-style clusterer.  It builds the mutual-reachability
graph, computes a minimum spanning tree, derives the single-linkage
hierarchy, condenses the hierarchy using ‘minimum_cluster_size’, and
selects clusters using ‘eom’ or ‘leaf’ selection.  Supports continuous
attributes only.

The library implements the ‘clusterer_protocol’ defined in the
‘clustering_protocols’ library.  It provides predicates for learning a
clusterer from a dataset, assigning new instances to clusters, and
exporting the learned clusterer as a list of predicate clauses or to a
file.

Datasets are represented as objects implementing the
‘clustering_dataset_protocol’ protocol from the ‘clustering_protocols’
library.

* Menu:

* API documentation: API documentation<102>.
* Loading: Loading<103>.
* Testing: Testing<95>.
* Features: Features<26>.
* Options: Options<25>.
* Clusterer representation: Clusterer representation<4>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<102>,  Next: Loading<103>,  Up: hdbscan_clusterer

6.83.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#hdbscan_clusterer’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<103>,  Next: Testing<95>,  Prev: API documentation<102>,  Up: hdbscan_clusterer

6.83.2 Loading
--------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(hdbscan_clusterer(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<95>,  Next: Features<26>,  Prev: Loading<103>,  Up: hdbscan_clusterer

6.83.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(hdbscan_clusterer(tester)).

To run the performance benchmark suite, load the
‘tester_performance.lgt’ file:

     | ?- logtalk_load(hdbscan_clusterer(tester_performance)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<26>,  Next: Options<25>,  Prev: Testing<95>,  Up: hdbscan_clusterer

6.83.4 Features
---------------

   - 'Hierarchical Density Clustering': Builds the mutual-reachability
     graph, computes a minimum spanning tree, derives the single-linkage
     hierarchy, condenses it using ‘minimum_cluster_size’, and selects
     clusters using ‘eom’ or ‘leaf’ selection.

   - 'Continuous Datasets': Accepts datasets containing only continuous
     attributes.

   - 'Cluster Selection Methods': Supports both ‘eom’ and ‘leaf’ cluster
     selection.

   - 'Distance Metrics': Supports Euclidean and Manhattan distances.

   - 'Optional Feature Scaling': Continuous attributes can be
     standardized using z-score scaling.

   - 'Reachability-Based Prediction': New instances are assigned to the
     selected cluster with the nearest training point when the distance
     is within the learned cluster reachability threshold; otherwise the
     atom ‘noise’ is returned.

   - 'Noise Detection': Points not assigned to any extracted cluster are
     retained as noise.

   - 'Portable Export': Learned clusterers can be exported as clauses or
     files and reused later.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<25>,  Next: Clusterer representation<4>,  Prev: Features<26>,  Up: hdbscan_clusterer

6.83.5 Options
--------------

The following options can be passed to the ‘learn/3’ predicate:

   - ‘minimum_points(MinimumPoints)’: Minimum neighborhood size used
     when computing core distances and mutual reachability.  Default is
     ‘2’.

   - ‘minimum_cluster_size(MinimumClusterSize)’: Minimum number of
     points required for an extracted cluster.  Default is ‘2’.

   - ‘cluster_selection_method(Method)’: Cluster extraction policy.
     Options: ‘eom’ (default) or ‘leaf’.

   - ‘distance_metric(Metric)’: Distance metric to use.  Options:
     ‘euclidean’ (default) or ‘manhattan’.

   - ‘feature_scaling(FeatureScaling)’: Whether to standardize
     continuous attributes before clustering.  Options: ‘on’ (default)
     or ‘off’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Clusterer representation<4>,  Prev: Options<25>,  Up: hdbscan_clusterer

6.83.6 Clusterer representation
-------------------------------

The learned clusterer is represented as a compound term with the functor
chosen by the user when exporting the clusterer and arity 4.  For
example:

     hdbscan_clusterer(Encoders, Clusters, Noise, Options)

Where:

   - ‘Encoders’: List of continuous attribute encoders storing attribute
     name, mean, and scale.

        - ‘Clusters’: List of ‘cluster(Id, Points, MaxCoreDistance,
          Stability)’ terms in cluster-id order.

   - ‘Noise’: List of encoded training points classified as noise.

   - ‘Options’: Effective training options used to learn the clusterer.


File: TheLogtalkHandbook-3.101.0.info,  Node: heaps,  Next: hierarchical_clustering,  Prev: hdbscan_clusterer,  Up: Libraries

6.84 ‘heaps’
============

This library defines a heap protocol and provides minimum and maximum
heaps using two different implementations: pairing heaps and binary
heaps.

The heap representations should be regarded as opaque terms, subjected
to be changed without notice, and only accessed using the library
predicates.

For backward-compatibility, the ‘legacy.lgt’ file defines the ‘heapp’
protocol extending the ‘heap_protocol’ protocol plus the ‘heap/1’,
‘minheap’, and ‘maxheap’ objects extending the ‘binary_heap/1’ object.
These legacy protocol and objects are deprecated and should not be used
in new code.

* Menu:

* API documentation: API documentation<103>.
* Loading: Loading<104>.
* Testing: Testing<96>.
* Usage: Usage<46>.
* Credits: Credits<3>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<103>,  Next: Loading<104>,  Up: heaps

6.84.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#heaps’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<104>,  Next: Testing<96>,  Prev: API documentation<103>,  Up: heaps

6.84.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(heaps(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<96>,  Next: Usage<46>,  Prev: Loading<104>,  Up: heaps

6.84.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(heaps(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<46>,  Next: Credits<3>,  Prev: Testing<96>,  Up: heaps

6.84.4 Usage
------------

Choose the heap implementation that best suits your needs.  The pairing
heap implementation is usually the best choice, specially if insertion
and merging operations dominate in your use case.  You can easily
benchmark and compare the two implementations using either a ‘uses/2’
directive with a parameter variable for the heap object and calling the
heap predicates using implicit message-sending goals or a ‘uses/1’
directive defining an object alias for the heap object and using the
alias with explicit message-sending goals.

The two main library objects are ‘binary_heap(Order)’ and
‘pairing_heap(Order)’, where ‘Order’ is either ‘<’ for a minimum heap or
‘>’ for a maximum heap.  For convenience, there are also
‘binary_heap_min’ and ‘pairing_heap_min’ objects for minimum heaps and
‘binary_heap_max’ and ‘pairing_heap_max’ objects for maximum heaps.


File: TheLogtalkHandbook-3.101.0.info,  Node: Credits<3>,  Prev: Usage<46>,  Up: heaps

6.84.5 Credits
--------------

Original binary heap code by Richard O’Keefe and adapted to Logtalk by
Paulo Moura and Victor Lagerkvist.


File: TheLogtalkHandbook-3.101.0.info,  Node: hierarchical_clustering,  Next: hierarchies,  Prev: heaps,  Up: Libraries

6.85 ‘hierarchical_clustering’
==============================

Hierarchical clusterer.  Supports continuous attributes only.  It builds
the full bottom-up agglomerative_clusterer hierarchy and derives the
requested partition by cutting the learned dendrogram at the largest
remaining merge distances.

The library implements the ‘clusterer_protocol’ defined in the
‘clustering_protocols’ library.  It provides predicates for learning a
full agglomerative_clusterer hierarchy from a dataset, deriving a
‘k’-cluster cut for prediction, and exporting the learned clusterer as a
list of predicate clauses or to a file.

Datasets are represented as objects implementing the
‘clustering_dataset_protocol’ protocol from the ‘clustering_protocols’
library.

* Menu:

* API documentation: API documentation<104>.
* Loading: Loading<105>.
* Testing: Testing<97>.
* Features: Features<27>.
* Options: Options<26>.
* Clusterer representation: Clusterer representation<5>.
* Additional API::
* Diagnostics: Diagnostics<3>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<104>,  Next: Loading<105>,  Up: hierarchical_clustering

6.85.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#hierarchical_clustering’ link in
a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<105>,  Next: Testing<97>,  Prev: API documentation<104>,  Up: hierarchical_clustering

6.85.2 Loading
--------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(hierarchical_clustering(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<97>,  Next: Features<27>,  Prev: Loading<105>,  Up: hierarchical_clustering

6.85.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(hierarchical_clustering(tester)).

To run the performance benchmark suite, load the
‘tester_performance.lgt’ file:

     | ?- logtalk_load(hierarchical_clustering(tester_performance)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<27>,  Next: Options<26>,  Prev: Testing<97>,  Up: hierarchical_clustering

6.85.4 Features
---------------

   - 'Full Hierarchy Learning': Builds the complete bottom-up merge
     hierarchy before deriving the requested cluster partition.

   - 'Deterministic Dendrogram Cutting': Produces the final ‘k’ clusters
     by repeatedly splitting the highest remaining merge.

   - 'Continuous Datasets': Accepts datasets containing only continuous
     attributes.

   - 'Linkage Strategies': Supports ‘single’, ‘complete’, and ‘average’
     linkage.

   - 'Distance Metrics': Supports Euclidean and Manhattan distances.

   - 'Optional Feature Scaling': Continuous attributes can be
     standardized using z-score scaling.

   - 'Linkage-Aware Prediction': New instances are assigned to the
     nearest learned cluster using the selected linkage strategy and
     distance metric rather than a prototype shortcut.

   - 'Incremental Distance Updates': Training caches singleton pair
     distances once and updates merge distances incrementally for
     ‘single’, ‘complete’, and ‘average’ linkage instead of recomputing
     all member-pair distances after every merge.

   - 'Heap-Based Merge Selection': Training uses a lazy min-heap of
     candidate cluster pairs and skips stale entries for merged-away
     nodes instead of rescanning all active pairs at every agglomeration
     step.

   - 'Reusable Hierarchy Cuts': Learned hierarchies can be re-cut to a
     different ‘k’ using ‘cut/3’ without retraining.

   - 'Rich Diagnostics': Learned clusterers record merge counts,
     dendrogram height, heap rebuilds, scan fallbacks, maximum heap
     size, and effective options.

   - 'Deterministic Tie-Breaking': Equal merge distances and equal split
     heights are resolved by preferring the smallest node-id pair.

   - 'Portable Export': Learned clusterers can be exported as clauses or
     files and reused later.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<26>,  Next: Clusterer representation<5>,  Prev: Features<27>,  Up: hierarchical_clustering

6.85.5 Options
--------------

The following options can be passed to the ‘learn/3’ predicate:

   - ‘k(K)’: Number of clusters to retain after cutting the learned
     hierarchy.  Default is ‘2’.

   - ‘linkage(Linkage)’: Linkage strategy to use.  Options: ‘single’,
     ‘complete’, or ‘average’ (default).

   - ‘distance_metric(Metric)’: Distance metric to use.  Options:
     ‘euclidean’ (default) or ‘manhattan’.

   - ‘feature_scaling(FeatureScaling)’: Whether to standardize
     continuous attributes before clustering.  Options: ‘on’ (default)
     or ‘off’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Clusterer representation<5>,  Next: Additional API,  Prev: Options<26>,  Up: hierarchical_clustering

6.85.6 Clusterer representation
-------------------------------

The learned clusterer is represented as a compound term with the functor
chosen by the user when exporting the clusterer and arity 5.  For
example:

     hierarchical_clustering_clusterer(Encoders, hierarchy(RootState, MergeRecords, Dendrogram), Clusters, Prototypes, Diagnostics)

Where:

   - ‘Encoders’: List of continuous attribute encoders storing attribute
     name, mean, and scale.

   - ‘hierarchy(RootState, MergeRecords, Dendrogram)’: Reusable
     hierarchy state.  ‘RootState’ and ‘MergeRecords’ are used
     internally by ‘cut/3’, and ‘Dendrogram’ is the learned merge tree
     represented with ‘leaf(Id)’ and ‘merge(Left, Right, Distance,
     Size)’ terms.

   - ‘Clusters’: List of ‘cluster(Id, Points)’ terms for the selected
     ‘k’-cluster cut.

   - ‘Prototypes’: List of average vectors kept for display and export
     metadata.

   - ‘Diagnostics’: Diagnostics metadata including the effective
     training options used to learn the clusterer.


File: TheLogtalkHandbook-3.101.0.info,  Node: Additional API,  Next: Diagnostics<3>,  Prev: Clusterer representation<5>,  Up: hierarchical_clustering

6.85.7 Additional API
---------------------

   - ‘cut(+Clusterer, +K, -RecutClusterer)’: Reuses the learned
     hierarchy to derive a new ‘K’-cluster cut without retraining.


File: TheLogtalkHandbook-3.101.0.info,  Node: Diagnostics<3>,  Prev: Additional API,  Up: hierarchical_clustering

6.85.8 Diagnostics
------------------

The ‘diagnostics/2’ predicate returns metadata terms including:

   - ‘model(hierarchical_clustering)’

   - ‘cluster_count(Count)’

   - ‘prototype_count(Count)’

   - ‘training_example_count(Count)’

   - ‘merge_count(Count)’

   - ‘dendrogram_height(Height)’

   - ‘heap_rebuild_count(Count)’

   - ‘scan_fallback_count(Count)’

   - ‘maximum_heap_size(Size)’

   - ‘tie_breaking(node_id_order)’

   - ‘options(Options)’


File: TheLogtalkHandbook-3.101.0.info,  Node: hierarchies,  Next: hmac,  Prev: hierarchical_clustering,  Up: Libraries

6.86 ‘hierarchies’
==================

This library provides categories implementing reflection predicates over
class and prototype hierarchies.  These categories can be imported by
any object that requires reasoning about hierarchies.

* Menu:

* API documentation: API documentation<105>.
* Loading: Loading<106>.
* Testing: Testing<98>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<105>,  Next: Loading<106>,  Up: hierarchies

6.86.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#hierarchies’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<106>,  Next: Testing<98>,  Prev: API documentation<105>,  Up: hierarchies

6.86.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(hierarchies(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<98>,  Prev: Loading<106>,  Up: hierarchies

6.86.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(hierarchies(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: hmac,  Next: hodge_rank,  Prev: hierarchies,  Up: Libraries

6.87 ‘hmac’
===========

The ‘hmac’ library provides a portable implementation of HMAC
(Keyed-Hashing for Message Authentication) as specified in RFC 2104:

‘https://datatracker.ietf.org/doc/html/rfc2104.html’

The library exports a single object, ‘hmac’, implementing the
‘hmac_protocol’ protocol with the predicates:

   - ‘digest/4’

   - ‘hex_digest/4’

   - ‘digest/5’

   - ‘hex_digest/5’

The first argument is a hash object implementing the
‘hash_digest_protocol’ protocol from the ‘hashes’ library.  Currently
supported hash objects are:

   - ‘md5’

   - ‘sha1’

   - ‘sha224’

   - ‘sha256’

   - ‘sha384’

   - ‘sha512’

   - ‘sha512_256’

   - ‘sha3_224’

   - ‘sha3_256’

   - ‘sha3_384’

   - ‘sha3_512’

On backend Prolog compilers supporting only bounded integer arithmetic,
only ‘md5’ is available.  On backends supporting unbounded integer
arithmetic, all the listed hash objects are available.

The ‘digest/5’ and ‘hex_digest/5’ predicates implement the truncation
rule described in RFC 2104 and RFC 2202 by returning the requested
number of leftmost digest bytes.

* Menu:

* API documentation: API documentation<106>.
* Loading: Loading<107>.
* Testing: Testing<99>.
* Examples: Examples<171>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<106>,  Next: Loading<107>,  Up: hmac

6.87.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#hmac’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<107>,  Next: Testing<99>,  Prev: API documentation<106>,  Up: hmac

6.87.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(hmac(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<99>,  Next: Examples<171>,  Prev: Loading<107>,  Up: hmac

6.87.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(hmac(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<171>,  Prev: Testing<99>,  Up: hmac

6.87.4 Examples
---------------

Compute the HMAC-SHA-256 digest for a text message and return it as a
hexadecimal atom:

     | ?- atom_codes('Jefe', Key),
          atom_codes('what do ya want for nothing?', Message),
          hmac::hex_digest(sha256, Key, Message, Digest).
     Key = [74,101,102,101],
     Message = [119,104,97,116,32,100,111,32,121,97,32,119,97,110,116,32,102,111,114,32,110,111,116,104,105,110,103,63],
     Digest = '5bdcc146bf60754e6a042426089575c75a003f089d2739839dec58b964ec3843'
     yes

Compute a truncated 16-byte HMAC-SHA-256 digest:

     | ?- atom_codes('Jefe', Key),
          atom_codes('what do ya want for nothing?', Message),
          hmac::hex_digest(sha256, Key, Message, 16, Digest).
     Key = [74,101,102,101],
     Message = [119,104,97,116,32,100,111,32,121,97,32,119,97,110,116,32,102,111,114,32,110,111,116,104,105,110,103,63],
     Digest = '5bdcc146bf60754e6a042426089575c7'
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: hodge_rank,  Next: hook_flows,  Prev: hmac,  Up: Libraries

6.88 ‘hodge_rank’
=================

HodgeRank pairwise measurement ranker.  It builds a weighted graph
Laplacian from the pairwise measurement support graph, solves the
anchored normal equations using deterministic Gaussian elimination with
partial pivoting and residual validation, and computes edge residuals
against the fitted score differences.

The library implements the ‘ranker_protocol’ defined in the
‘ranking_protocols’ library.  It provides predicates for learning a
ranker from weighted signed pairwise measurements, using it to order
candidate items, inspecting the resulting edge residuals, and exporting
it as a list of predicate clauses or to a file.

Datasets are represented as objects implementing the
‘pairwise_measurement_dataset_protocol’ protocol from the
‘ranking_protocols’ library.  See the ‘test_datasets’ directory for
examples.  The current implementation requires a well-formed connected
pairwise measurement dataset so that learned scores remain globally
comparable across all ranked items.

* Menu:

* API documentation: API documentation<107>.
* Loading: Loading<108>.
* Testing: Testing<100>.
* Features: Features<28>.
* Scoring semantics: Scoring semantics<4>.
* Residual semantics::
* Usage: Usage<47>.
* Diagnostics syntax: Diagnostics syntax<11>.
* Ranker representation: Ranker representation<8>.
* References: References<17>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<107>,  Next: Loading<108>,  Up: hodge_rank

6.88.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#hodge_rank’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<108>,  Next: Testing<100>,  Prev: API documentation<107>,  Up: hodge_rank

6.88.2 Loading
--------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(hodge_rank(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<100>,  Next: Features<28>,  Prev: Loading<108>,  Up: hodge_rank

6.88.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(hodge_rank(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<28>,  Next: Scoring semantics<4>,  Prev: Testing<100>,  Up: hodge_rank

6.88.4 Features
---------------

   - 'Weighted Measurement Learning': Learns one deterministic score per
     item from weighted signed pairwise measurements instead of
     winner/loser counts.

   - 'HodgeRank Global Component': Solves the weighted graph-Laplacian
     least- squares system with a zero-sum anchoring convention.

   - 'Residual Inspection': Exposes edge residuals through the
     ‘residuals/2’ predicate so the non-global residual edge flow can be
     inspected explicitly.

   - 'Numerically Hardened Solver': Uses Gaussian elimination with
     partial pivoting plus residual checks before accepting the learned
     scores.

   - 'Deterministic Ranking': Orders candidate items by learned score
     with deterministic tie-breaking.

   - 'Strict Dataset Validation': Rejects duplicate items, undeclared
     items, self-measurements, non-numeric values, non-positive weights,
     and disconnected support graphs.

   - 'Ranker Export': Learned rankers can be exported as self-contained
     terms.


File: TheLogtalkHandbook-3.101.0.info,  Node: Scoring semantics<4>,  Next: Residual semantics,  Prev: Features<28>,  Up: hodge_rank

6.88.5 Scoring semantics
------------------------

This implementation interprets each measurement fact

     measurement(Item1, Item2, Value, Weight)

as a weighted signed observation for the oriented edge ‘Item1 -> Item2’.
The learner fits a global zero-sum score vector ‘s’ by minimizing the
weighted least-squares objective

     sum_ij Weight_ij * (Value_ij - (s_i - s_j))^2

subject to ‘sum(scores) = 0’.  The resulting normal equations are a
weighted graph-Laplacian system with one anchoring row enforcing the
zero-sum gauge.

The learned scores are relative rather than probabilistic: only their
differences and ordering matter.  Larger positive values indicate items
whose fitted global potential is higher than average.  The ‘residuals/2’
predicate returns the unexplained part of each observed edge measurement
after removing the fitted score difference, i.e.  the non-global
residual edge flow left after fitting the global component.


File: TheLogtalkHandbook-3.101.0.info,  Node: Residual semantics,  Next: Usage<47>,  Prev: Scoring semantics<4>,  Up: hodge_rank

6.88.6 Residual semantics
-------------------------

Residuals capture the part of each observed edge measurement that is not
explained by the fitted global score difference, exposing the non-global
residual edge flow left after fitting the global component.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<47>,  Next: Diagnostics syntax<11>,  Prev: Residual semantics,  Up: hodge_rank

6.88.7 Usage
------------

* Menu:

* Learning a ranker: Learning a ranker<8>.
* Inspecting residuals::


File: TheLogtalkHandbook-3.101.0.info,  Node: Learning a ranker<8>,  Next: Inspecting residuals,  Up: Usage<47>

6.88.7.1 Learning a ranker
..........................

     % Learn from a pairwise measurement dataset object
     | ?- hodge_rank::learn(my_dataset, Ranker).
     ...

     % Learn with an explicit empty options list
     | ?- hodge_rank::learn(my_dataset, Ranker, []).
     ...

The current implementation accepts only the empty options list ‘[]’.
Any non-empty options list is rejected.


File: TheLogtalkHandbook-3.101.0.info,  Node: Inspecting residuals,  Prev: Learning a ranker<8>,  Up: Usage<47>

6.88.7.2 Inspecting residuals
.............................

     % Inspect edge residuals from the fitted global scores
     | ?- hodge_rank::learn(my_dataset, Ranker),
          hodge_rank::residuals(Ranker, Residuals).
     Residuals = [...]
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Diagnostics syntax<11>,  Next: Ranker representation<8>,  Prev: Usage<47>,  Up: hodge_rank

6.88.8 Diagnostics syntax
-------------------------

The ‘diagnostics/2’ predicate returns a list of metadata terms with the
form:

     [
         model(hodge_rank),
         options(Options),
         residuals(Residuals),
         residual_norm(ResidualNorm),
         dataset_summary(DatasetSummary)
     ]


File: TheLogtalkHandbook-3.101.0.info,  Node: Ranker representation<8>,  Next: References<17>,  Prev: Diagnostics syntax<11>,  Up: hodge_rank

6.88.9 Ranker representation
----------------------------

The learned ranker is represented by a compound term of the form:

     hodge_rank_ranker(Items, Scores, Diagnostics)

Where:

   - ‘Items’: List of ranked items.

   - ‘Scores’: List of ‘Item-Score’ pairs.

   - ‘Diagnostics’: List of metadata terms, including the residuals,
     residual norm, effective options, and dataset summary.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<17>,  Prev: Ranker representation<8>,  Up: hodge_rank

6.88.10 References
------------------

  1. Jiang, X., Lim, L.-H., Yao, Y., & Ye, Y. (2011).  'Statistical
     ranking and combinatorial Hodge theory'.


File: TheLogtalkHandbook-3.101.0.info,  Node: hook_flows,  Next: hook_objects,  Prev: hodge_rank,  Up: Libraries

6.89 ‘hook_flows’
=================

Hook objects (i.e., objects that define term- and goal-expansion rules)
can be combined to define expansion 'workflows'.  While in some cases
the expansions are independent and thus can be applied in any order, in
other cases a specific order is required.  The ‘hook_pipeline’ and
‘hook_set’ parametric objects in this library implement the two most
common scenarios of combining multiple hook objects for the expansion of
source files.  These parametric hook objects can be combined to define
workflows of any complexity (e.g., a pipeline where one of the steps is
set with an element that is a pipeline).  These two basic hook flows can
also be used as examples of how to construct your own custom expansion
workflows.

* Menu:

* API documentation: API documentation<108>.
* Loading: Loading<109>.
* Testing: Testing<101>.
* Usage: Usage<48>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<108>,  Next: Loading<109>,  Up: hook_flows

6.89.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#hook-flows’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<109>,  Next: Testing<101>,  Prev: API documentation<108>,  Up: hook_flows

6.89.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(hook_flows(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<101>,  Next: Usage<48>,  Prev: Loading<109>,  Up: hook_flows

6.89.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(hook_flows(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<48>,  Prev: Testing<101>,  Up: hook_flows

6.89.4 Usage
------------

Pre-processing a source file with a hook object can be accomplished by
either compiling the source file using the option ‘hook(HookObject)’ or
by adding to the top of the file the directive:

     :- set_logtalk_flag(hook, HookObject).

Note that ‘set_logtalk_flag/2’ directives are local to an entity or a
source file.

The ‘hook_pipeline(Pipeline)’ is a parametric object where the parameter
is a list of hook objects, interpreted as a pre-processing pipeline: the
results of a hook object are passed to the next hook object.  Terms and
goals that are not expanded by a hook object are passed as-is to the
next hook object.  This parametric object is used when a set of
expansions must be applied in a specific order.  It also allows
overriding the default compiler semantics where term-expansion rules are
tried in sequence only until one of them succeeds.

The ‘hook_set(Set)’ is a parametric object where the parameter is a list
of hook objects, interpreted as a set of hook objects.  The hook objects
are tried in sequence until one of them succeeds in expanding the
current term (goal) into a different term (goal).  This parametric
object is used when applying multiple independent expansions (i.e.,
expansions that don’t apply to the same terms or goals).

Both the ‘hook_pipeline(Pipeline)’ and ‘hook_set(Set)’ objects assume
that the individual hook objects publicly implement the ‘expanding’
protocol (this is the default) as they send ‘term_expansion/2’ and
‘goal_expansion/2’ messages to those objects.

When using a backend Prolog compiler that supports modules, it’s also
possible to use as parameter a list of hook modules as long as their
names do not coincide with the names of loaded objects.


File: TheLogtalkHandbook-3.101.0.info,  Node: hook_objects,  Next: html,  Prev: hook_flows,  Up: Libraries

6.90 ‘hook_objects’
===================

This library provides a set of convenient hook objects for defining
custom expansion workflows (using, e.g., the ‘hook_flows’ library) and
for debugging.  They are usable and useful as-is but should also be
regarded as term- and goal-expansion examples that you can learn from,
clone, and change to fit your application requirements.

* Menu:

* API documentation: API documentation<109>.
* Loading: Loading<110>.
* Testing: Testing<102>.
* Usage: Usage<49>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<109>,  Next: Loading<110>,  Up: hook_objects

6.90.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#hook-objects’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<110>,  Next: Testing<102>,  Prev: API documentation<109>,  Up: hook_objects

6.90.2 Loading
--------------

To load all hook objects in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(hook_objects(loader)).

To load a specific hook object, e.g., the ‘backend_adapter_hook’ object:

     | ?- logtalk_load(hook_objects(backend_adapter_hook)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<102>,  Next: Usage<49>,  Prev: Loading<110>,  Up: hook_objects

6.90.3 Testing
--------------

To test this library hook objects, load the ‘tester.lgt’ file:

     | ?- logtalk_load(hook_objects(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<49>,  Prev: Testing<102>,  Up: hook_objects

6.90.4 Usage
------------

The provided hook objects cover different expansion scenarios as
follows.

* Menu:

* Using the Prolog backend adapter file expansion rules::
* Restoring the default compiler expansion workflow::
* Preventing applying any (other) user-defined expansion rules: Preventing applying any other user-defined expansion rules.
* Expanding grammar rules into clauses independently of the compiler::
* Using the expansion rules defined in a Prolog module::
* Wrap the contents of a plain Prolog file as an object::
* Outputting term-expansion results to a stream or a file::
* Printing entity predicate goals before or after calling them::
* Suppressing goals::


File: TheLogtalkHandbook-3.101.0.info,  Node: Using the Prolog backend adapter file expansion rules,  Next: Restoring the default compiler expansion workflow,  Up: Usage<49>

6.90.4.1 Using the Prolog backend adapter file expansion rules
..............................................................

Useful when defining a custom expansion workflow.  This can be
accomplished by loading the ‘backend_adapter_hook.lgt’ file, which
defines a ‘backend_adapter_hook’ hook object that can be used as a
workflow step.


File: TheLogtalkHandbook-3.101.0.info,  Node: Restoring the default compiler expansion workflow,  Next: Preventing applying any other user-defined expansion rules,  Prev: Using the Prolog backend adapter file expansion rules,  Up: Usage<49>

6.90.4.2 Restoring the default compiler expansion workflow
..........................................................

In this case, load the ‘default_workflow_hook.lgt’ file, which defines a
‘default_workflow_hook’ hook object, and use the following 'goal' to set
the default hook object:

     | ?- set_logtalk_flag(hook, default_workflow_hook).


File: TheLogtalkHandbook-3.101.0.info,  Node: Preventing applying any other user-defined expansion rules,  Next: Expanding grammar rules into clauses independently of the compiler,  Prev: Restoring the default compiler expansion workflow,  Up: Usage<49>

6.90.4.3 Preventing applying any (other) user-defined expansion rules
.....................................................................

When compiling a source file, we sometimes want to prevent applying
expansion rules.  This can be accomplished by simply loading the
‘identity_hook.lgt’ file, which defines the ‘identity_hook’ hook object,
whose expansion rules simply succeed without changing the terms and
goals, and setting it as the file-specific hook object writing as the
first term in the file the 'directive':

     :- set_logtalk_flag(hook, identity_hook).

Note that the compiler will always convert any grammar rules defined in
the file into clauses.  Although this conversion can also be performed
as an expansion, grammar rules are part of the Logtalk language.  If you
want to preserve the grammar rules, use the hook objects described below
to write them to a stream.


File: TheLogtalkHandbook-3.101.0.info,  Node: Expanding grammar rules into clauses independently of the compiler,  Next: Using the expansion rules defined in a Prolog module,  Prev: Preventing applying any other user-defined expansion rules,  Up: Usage<49>

6.90.4.4 Expanding grammar rules into clauses independently of the compiler
...........................................................................

Load the ‘grammar_rules_hook.lgt’ and use the term-expansion rules in
the ‘grammar_rules_hook’ object.  For example:

     | ?- grammar_rules_hook::term_expansion((a --> [b],c), Clause).

     Clause = (a([b|T], C) :- c(T, C))
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: Using the expansion rules defined in a Prolog module,  Next: Wrap the contents of a plain Prolog file as an object,  Prev: Expanding grammar rules into clauses independently of the compiler,  Up: Usage<49>

6.90.4.5 Using the expansion rules defined in a Prolog module
.............................................................

Load the ‘prolog_module_hook.lgt’, which defines the parametric hook
object ‘prolog_module_hook(Module)’.  To use this hook object, you need
to instantiate the parameter to the name of the module.  For example:

     :- set_logtalk_flag(hook, prolog_module_hook(user)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Wrap the contents of a plain Prolog file as an object,  Next: Outputting term-expansion results to a stream or a file,  Prev: Using the expansion rules defined in a Prolog module,  Up: Usage<49>

6.90.4.6 Wrap the contents of a plain Prolog file as an object
..............................................................

Load the ‘object_wrapper_hook.lgt’, which defines the
‘object_wrapper_hook/0-2’ hook objects.  Use them to wrap the contents
of a plain Prolog file as an object named after the file (optionally
implementing a protocol) or an object with the given name and object
relations.  Can be used to apply Logtalk developer tools to plain Prolog
code or when porting a Prolog application to Logtalk.  For example:

     | ?- logtalk_load('plain.pl', [hook(object_wrapper_hook)]).
     ...

     | ?- current_object(plain).
     yes

Or:

     | ?- logtalk_load('world_1.pl', [hook(object_wrapper_hook(some_protocol))]).
     ...

     | ?- current_object(world_1).
     yes

     | ?- implements_protocol(world_1, Protocol).
     Protocol = some_protocol
     yes

Or:

     | ?- logtalk_load('foo.pl', [hook(object_wrapper_hook(bar,[imports(some_category))]).
     ...

     | ?- current_object(bar).
     yes

     | ?- imports_category(bar, Category).
     Category = some_category
     yes

The ‘object_wrapper_hook’ object sets the ‘context_switching_calls’ flag
to ‘allow’ for the generated object.  This enables calling the
predicates using the ‘(<<)/2’ context-switching control construct.  But
it’s usually better to define a protocol for the predicates being
encapsulated and use instead the ‘object_wrapper_hook/1-2’ objects.


File: TheLogtalkHandbook-3.101.0.info,  Node: Outputting term-expansion results to a stream or a file,  Next: Printing entity predicate goals before or after calling them,  Prev: Wrap the contents of a plain Prolog file as an object,  Up: Usage<49>

6.90.4.7 Outputting term-expansion results to a stream or a file
................................................................

Load the ‘write_to_stream_hook.lgt’ file and use the
‘write_to_stream_hook(Stream)’ or ‘write_to_stream_hook(Stream,
Options)’ hook objects.  Alternatively, you can load the
‘write_to_file_hook.lgt’ file and use the ‘write_to_file_hook(File)’ or
‘write_to_file_hook(File, Options)’ hook objects.  The terms are not
modified and thus these hook objects may be used at any point in an
expansion workflow.  The terms are written followed by a period and a
new line.

For example, assume that we want to expand all terms in a ‘input.pl’
source file, writing the resulting terms to a ‘output.pl’ file, using
the expansion rules defined in a ‘expansions’ hook object.  Taking
advantage of the ‘hook_flows’ library ‘hook_pipeline/1’ object, we can
write:

     | ?- logtalk_compile(
              'input.pl',
              [hook(hook_pipeline([
                  expansions,
                  write_to_file_hook('output.pl')
              ]))]
          ).


File: TheLogtalkHandbook-3.101.0.info,  Node: Printing entity predicate goals before or after calling them,  Next: Suppressing goals,  Prev: Outputting term-expansion results to a stream or a file,  Up: Usage<49>

6.90.4.8 Printing entity predicate goals before or after calling them
.....................................................................

This is helpful for quick debugging.  Load the ‘print_goal_hook.lgt’
file and use the ‘print_goal_hook’ hook object.  For example, we can set
this hook object as the default hook:

     | ?- set_logtalk_flag(hook, print_goal_hook).

Then, edit the entity source code to print selected goals:

     foo :-
         - bar,   % print goal before calling it
         + baz,   % print goal after calling it
         * quux.  % print goal before and after calling it


File: TheLogtalkHandbook-3.101.0.info,  Node: Suppressing goals,  Prev: Printing entity predicate goals before or after calling them,  Up: Usage<49>

6.90.4.9 Suppressing goals
..........................

The ‘suppress_goal_hook.lgt’ file provides the ‘suppress_goal_hook’ hook
object that supports suppressing a goal in a clause body by prefixing it
using the ‘--’ operator.  We can set this hook object as the default
hook using the goal:

     | ?- set_logtalk_flag(hook, suppress_goal_hook).

If the expansion is only to be used in a single file, use instead the
source file directive:

     :- set_logtalk_flag(hook, suppress_goal_hook).

Then, edit entity predicates to suppress goals.  For example:

     foo :-
         bar,
         -- baz,
         quux.

The suppressed goals are replaced by calls to ‘true/0’.


File: TheLogtalkHandbook-3.101.0.info,  Node: html,  Next: http_authenticate,  Prev: hook_objects,  Up: Libraries

6.91 ‘html’
===========

This library provides predicates for generating HTML content using
either HTML 5 or XHTML 1.1 formats from a term representation.  The
library performs minimal validation, checking only that all elements are
valid.  No attempt is made to generate nicely indented output.

Normal elements are represented using a compound term with one argument
(the element content) or two arguments (the element attributes
represented by a list of ‘Key=Value’ or ‘Key-Value’ pairs and the
element content).  The element content can be another element or a list
of elements.  For example:

     ol([type-a], [li(foo), li(bar), li(baz)])

The two exceptions are the ‘pre’ or ‘code’ elements whose content is
never interpreted as an element or a list of elements.  For example, the
fragment:

     pre([foo,bar,baz])

is translated to:

     <pre>
     [foo,bar,baz]
     </pre>

Void elements are represented using a compound term with one argument,
the (possibly empty) list of attributes represented by a list of
‘Key=Value’ or ‘Key-Value’ pairs.  For example:

     hr([class-separator])

Atomic arguments of the compound terms are interpreted as element
content.  Non-atomic element content can be represented as a quoted atom
or by using the ‘pre’ or ‘code’ elements as explained above.

This library is a work in progress.

* Menu:

* API documentation: API documentation<110>.
* Loading: Loading<111>.
* Testing: Testing<103>.
* Generating a HTML document::
* Generating a HTML fragment::
* Working with callbacks to generate content::
* Working with resource declarations::
* Aggregating and ordering resources::
* Working with custom elements::


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<110>,  Next: Loading<111>,  Up: html

6.91.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#html’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<111>,  Next: Testing<103>,  Prev: API documentation<110>,  Up: html

6.91.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(html(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<103>,  Next: Generating a HTML document,  Prev: Loading<111>,  Up: html

6.91.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(html(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Generating a HTML document,  Next: Generating a HTML fragment,  Prev: Testing<103>,  Up: html

6.91.4 Generating a HTML document
---------------------------------

HTML documents can be generated from a compound term representation and
written to a file or a stream.  For example, assuming we want to
generate a HTML 5 file:

     | ?- html5::generate(
              file('hello.html'),
              html([lang=en], [head(title('Hello world!')), body(p('Bye!'))])
          ).

When the second argument is a ‘html/1’ or ‘html/2’ compound term, a
'doctype' is automatically written.  If we prefer instead e.g.  a XHTML
1.1 document, we use the ‘xhtml11’ object:

     | ?- xhtml11::generate(
              file('hello.html'),
              html([lang=en], [head(title('Hello world!')), body(p('Bye!'))])
          ).


File: TheLogtalkHandbook-3.101.0.info,  Node: Generating a HTML fragment,  Next: Working with callbacks to generate content,  Prev: Generating a HTML document,  Up: html

6.91.5 Generating a HTML fragment
---------------------------------

It’s also possible to generate just a fragment of a (X)HTML document by
using a list of compound terms or a compound term for an element other
than ‘html’.  For example:

     | ?- current_output(Stream),
          html5::generate(stream(Stream), ul([li(foo), li(bar), li(baz)])).

     <ul>
     <li>
     foo</li>
     <li>
     bar</li>
     <li>
     baz</li>
     </ul>

     Stream = ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Working with callbacks to generate content,  Next: Working with resource declarations,  Prev: Generating a HTML fragment,  Up: html

6.91.6 Working with callbacks to generate content
-------------------------------------------------

Often we need to programmatically generate HTML content from queries.
In other cases, we may have fixed content that we don’t want to keep
repeating (e.g., a navigation bar).  The library supports a ‘(::)/2’
pseudo-element that sends a message to an object to retrieve content.
As an example, assume the following predicate definition in ‘user’:

     content(strong('Hello world!')).

This predicate can then be called from the HTML term representation.
For example:

     | ?- current_output(Stream),
          html5::generate(stream(Stream), span(user::content)).

     <span><strong>Hello world!</strong></span>

     Stream = ...

Note that the callback always takes the form ‘Object::Closure’ where
‘Closure’ is extended with a single argument (to be bound to the
generated content).  More complex callbacks are possible by using lambda
expressions.


File: TheLogtalkHandbook-3.101.0.info,  Node: Working with resource declarations,  Next: Aggregating and ordering resources,  Prev: Working with callbacks to generate content,  Up: html

6.91.7 Working with resource declarations
-----------------------------------------

The renderer accepts explicit resource declarations in addition to the
usual HTML elements.  The supported resource declarations are:

   - ‘resource(Type, Target)’

   - ‘resource(Type, Target, Attributes)’

   - ‘css(Href)’

   - ‘js(Src)’

   - ‘resources(Declarations)’

   - ‘dependency(Dependent, Required)’

Here, ‘Type’ is ‘css’ or ‘js’, ‘Target’ is the stylesheet or script
location, ‘Attributes’ is an optional list of HTML attributes added to
the generated ‘<link>’ or ‘<script>’ element, ‘Href’ and ‘Src’ are
shorthand forms for the corresponding stylesheet or script target,
‘Declarations’ is a list of resource specifications to aggregate, and
‘dependency(Dependent, Required)’ expresses that the resource
‘Dependent’ must be emitted after ‘Required’ when ordering the generated
output.

The atom ‘stylesheet’ can also be used as an alternative to ‘css’.  The
atoms ‘javascript’ and ‘script’ can also be used as an alternative to
‘js’.

For example, the following term renders standard stylesheet and
JavaScript links directly:

     | ?- current_output(Stream),
          html5::generate(stream(Stream),
              resources([
                  css('base.css'),
                  resource(js, 'app.js', [defer-true])
          ])).

This produces ‘<link rel="stylesheet" href="base.css" />’ and ‘<script
defer src="app.js"></script>’-style output.


File: TheLogtalkHandbook-3.101.0.info,  Node: Aggregating and ordering resources,  Next: Working with custom elements,  Prev: Working with resource declarations,  Up: html

6.91.8 Aggregating and ordering resources
-----------------------------------------

A list of resource declarations can be wrapped with ‘resources/1’ to
normalize and aggregate them into a deterministic output order.
Repeated entries are removed automatically, and ‘dependency(Dependent,
Required)’ can be used to force a resource to be emitted after its
prerequisite.

For example:

     | ?- current_output(Stream),
          html5::generate(stream(Stream),
              resources([
                  dependency(resource(css, 'theme.css'), resource(css, 'base.css')),
                  css('theme.css'),
                  css('base.css'),
                  css('theme.css')
          ])).

This renders the ‘base.css’ stylesheet before ‘theme.css’, while also
removing the duplicated ‘theme.css’ entry from the final output.


File: TheLogtalkHandbook-3.101.0.info,  Node: Working with custom elements,  Prev: Aggregating and ordering resources,  Up: html

6.91.9 Working with custom elements
-----------------------------------

The ‘html5’ and ‘xhtml11’ objects recognize the same set of standard
HTML 5 normal and void elements and generate an error for non-standard
elements.  If you need to generate HTML content containing custom
elements, define a new object that extends one of the library objects.
For example:

     :- object(html5custom,
         extends(html5)).

         normal_element(foo, inline).
         normal_element(bar, block).
         normal_element(Name, Display) :-
             ^^normal_element(Name, Display).

     :- end_object.


File: TheLogtalkHandbook-3.101.0.info,  Node: http_authenticate,  Next: http_client,  Prev: html,  Up: Libraries

6.92 ‘http_authenticate’
========================

This library provides HTTP Basic authentication helpers on top of the
normalized HTTP stack.

The library currently provides these public entities:

   - ‘http_authenticate_verifier_protocol’ server-side verifier protocol
     for checking plaintext credentials

   - ‘http_authenticate’ core Basic parsing, generation, request
     protection, and challenge helpers

   - ‘http_htpasswd_verifier(_)’ portable Apache ‘.htpasswd’ subset
     verifier supporting ‘{SHA}’ and ‘$apr1$’ entries

   - ‘http_server_core_basic_handler(_, _, _)’ portable handler wrapper
     that applies Basic protection around another object implementing
     ‘http_handler_protocol’

   - ‘http_router_basic_auth(_, _)’ router companion category that
     protects routes declaring ‘basic_auth/1’ metadata

* Menu:

* API documentation: API documentation<111>.
* Loading: Loading<112>.
* Testing: Testing<104>.
* Usage overview::
* Current scope::
* Option validation::
* Non-implemented features::


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<111>,  Next: Loading<112>,  Up: http_authenticate

6.92.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#http_authenticate’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<112>,  Next: Testing<104>,  Prev: API documentation<111>,  Up: http_authenticate

6.92.2 Loading
--------------

To load the library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(http_authenticate(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<104>,  Next: Usage overview,  Prev: Loading<112>,  Up: http_authenticate

6.92.3 Testing
--------------

To test this library, load the ‘tester.lgt’ file:

     | ?- logtalk_load(http_authenticate(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage overview,  Next: Current scope,  Prev: Testing<104>,  Up: http_authenticate

6.92.4 Usage overview
---------------------

Use ‘http_authenticate’ directly when you need explicit control over
Basic challenge parsing and request verification:

     | ?- http_authenticate::protect_request(Request, verifier, Action, [realm('private')]).

Wrap a normal handler with ‘http_server_core_basic_handler(_, _, _)’
when you want a portable middleware-style integration point for Basic
verification:

     | ?- Handler = http_server_core_basic_handler(verifier, app_handler, [realm('private')]).

Use ‘http_router_basic_auth(_, _)’ in router objects importing
‘http_router’ when you want per-route protection driven by normal route
metadata:

     authorize_routed_request(Request, Action) :-
         ^^authorize_basic_auth_request(Request, Action).

     route_metadata(show_secret, [basic_auth([])]).


File: TheLogtalkHandbook-3.101.0.info,  Node: Current scope,  Next: Option validation,  Prev: Usage overview,  Up: http_authenticate

6.92.5 Current scope
--------------------

   - deterministic Basic header parsing and generation for
     ‘Authorization’ and ‘WWW-Authenticate’

   - server-side request protection through explicit verifier objects
     with malformed or missing client credentials mapped to ‘401
     Unauthorized’ responses while verifier and configuration errors are
     rethrown

   - middleware-style handler wrapping for generic
     ‘http_handler_protocol’ objects

   - route-level protection through ‘http_router_basic_auth(_, _)’ and
     the ‘authorize_routed_request/2’ router hook

   - portable Apache ‘.htpasswd’ subset verification for ‘{SHA}’ and
     ‘$apr1$’ entries using expanded file paths and rejecting malformed
     supported hash entries


File: TheLogtalkHandbook-3.101.0.info,  Node: Option validation,  Next: Non-implemented features,  Prev: Current scope,  Up: http_authenticate

6.92.6 Option validation
------------------------

   - ‘protect_request/4’ and ‘unauthorized_response/3-4’ validate option
     values at the call boundary using the shared ‘options’ category
     support

   - ‘unauthorized_response/4’ only accepts overlay options for
     ‘status/1’, ‘headers/1’, ‘body/1’, and ‘properties/1’

   - unauthorized-response ‘status/1’ values remain limited to ‘401’,
     but the reason phrase follows the shared HTTP ‘text’ rules instead
     of requiring an atom representation

   - invalid response customization ‘headers/1’ and ‘body/1’ values are
     rejected before any normalized HTTP response term is constructed


File: TheLogtalkHandbook-3.101.0.info,  Node: Non-implemented features,  Prev: Option validation,  Up: http_authenticate

6.92.7 Non-implemented features
-------------------------------

   - client-side session helpers

   - automatic role or scope authorization metadata

   - portable verification of bcrypt (‘$2a$’, ‘$2b$’, ‘$2y$’) or
     traditional ‘crypt()’ ‘.htpasswd’ entries


File: TheLogtalkHandbook-3.101.0.info,  Node: http_client,  Next: http_client_core,  Prev: http_authenticate,  Up: Libraries

6.93 ‘http_client’
==================

The ‘http_client’ library provides a request-oriented client layer on
top of the ‘http_core’, ‘url’, and HTTP transport libraries.  It is the
request-oriented client-side entry point: it builds normalized requests
from absolute URLs plus options and delegates transport to the selected
‘http_transport_protocol’-compatible layer, such as
‘http_socket_transport’ or ‘http_process_transport’.

This library can be used with backend Prolog systems that support
unbound integer arithmetic and the ‘sockets’ library: ECLiPSe, SICStus
Prolog, SWI-Prolog, Trealla Prolog, and XVM.

By default, ‘transport(default)’ selects ‘http_socket_transport’ for
‘http://’ and ‘ws://’ URLs, and ‘http_process_transport’ for ‘https://’
and ‘wss://’ URLs.  Applications can select a transport explicitly with
the ‘transport/1’ option when they need lower-level control or a custom
transport object.

When the selected transport supports secure schemes, the
request-oriented facade defaults ‘https://’ and ‘wss://’ URLs without an
explicit port to port ‘443’ and adds ‘connection_transport(tls)’ to the
connection options automatically unless already specified explicitly.
This TLS-aware behavior applies notably to ‘http_process_transport’,
which provides transport support for secure schemes via the same
‘http_transport_protocol’ interface.

* Menu:

* API documentation: API documentation<112>.
* Loading: Loading<113>.
* Testing: Testing<105>.
* Usage examples::
* Current scope: Current scope<2>.
* Multipart workflow::
* WebSocket workflow::
* Current limitations: Current limitations<2>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<112>,  Next: Loading<113>,  Up: http_client

6.93.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#http_client’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<113>,  Next: Testing<105>,  Prev: API documentation<112>,  Up: http_client

6.93.2 Loading
--------------

To load the library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(http_client(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<105>,  Next: Usage examples,  Prev: Loading<113>,  Up: http_client

6.93.3 Testing
--------------

To test this library, load the ‘tester.lgt’ file:

     | ?- logtalk_load(http_client(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage examples,  Next: Current scope<2>,  Prev: Testing<105>,  Up: http_client

6.93.4 Usage examples
---------------------

The examples below are self-contained.  They use the high-level
‘http_server’ facade to start a local loopback server, so they can be
reproduced without any external service.  They assume that both
‘http_client(loader)’ and ‘http_server(loader)’ are loaded and that the
backend supports threads, as the ‘http_server::start/4-5’ and
‘http_server::stop/1’ helpers run the local server concurrently with the
client call.

Define a small echo handler once:

     :- object(notes_http_client_echo_handler,
         implements(http_handler_protocol)).

         handle(Request, Response) :-
             http_core::version(Request, Version),
             http_core::body(Request, Body),
             http_core::response(Version, status(200, 'OK'), [], Body, [], Response).

     :- end_object.

Start a local server, send a request, and inspect the normalized
response.  The unbound ‘Port’ argument is unified with the actual port
selected by the backend:

     | ?- http_server::start('127.0.0.1', Port, notes_http_client_echo_handler, Server, []),
          atomic_list_concat(['http://127.0.0.1:', Port, '/echo'], URL),
          http_client::post(URL, content('text/plain', text(hello)), Response, []),
          http_server::stop(Server).

     Response = response(http(1,1), status(200, 'OK'), _, content('text/plain', text(hello)), _).

The QUERY method uses the same body-carrying convenience shape as POST,
PUT, and PATCH:

     | ?- http_server::start('127.0.0.1', Port, notes_http_client_echo_handler, Server, []),
          atomic_list_concat(['http://127.0.0.1:', Port, '/contacts'], URL),
          http_client::query(URL, content('application/x-www-form-urlencoded', form([limit-'10'])), Response, []),
          http_server::stop(Server).

     Response = response(http(1,1), status(200, 'OK'), _, content('application/x-www-form-urlencoded', form([limit-'10'])), _).

For a multipart form-data request, define a handler that inspects the
normalized request body using ‘http_multipart’:

     :- object(notes_http_client_multipart_handler,
         implements(http_handler_protocol)).

         handle(Request, Response) :-
             http_core::version(Request, Version),
             http_core::body(Request, Body),
             http_multipart::fields(Body, [field(title, Title, _FieldParameters)]),
             http_multipart::files(Body, [file(upload, Filename, 'text/plain', text(hello), _FileParameters)]),
             atomic_list_concat(['title=', Title, '; upload=', Filename], Text),
             http_core::response(Version, status(200, 'OK'), [], content('text/plain', text(Text)), [], Response).

     :- end_object.

An example form-data request can then be:

     | ?- http_server::start('127.0.0.1', Port, notes_http_client_multipart_handler, Server, []),
          atomic_list_concat(['http://127.0.0.1:', Port, '/upload'], URL),
          http_client::post(
              URL,
              form_data([
                  field(title, 'Logtalk', []),
                  file(upload, 'notes.txt', 'text/plain', text(hello), [])
              ]),
              Response,
              []
          ),
          http_server::stop(Server).

     Response = response(http(1,1), status(200, 'OK'), _, content('text/plain', text('title=Logtalk; upload=notes.txt')), _).

For a WebSocket opening handshake, define a handler that accepts the
upgrade:

     :- object(notes_http_client_websocket_handler,
         implements(http_handler_protocol)).

         handle(Request, Response) :-
             http_server_core::accept_websocket(Request, Response, [protocol(chat)]).

     :- end_object.

An example opening handshake query can then be:

     | ?- http_server::start('127.0.0.1', Port, notes_http_client_websocket_handler, Server, []),
          atomic_list_concat(['ws://127.0.0.1:', Port, '/socket'], URL),
          http_client::open_websocket(URL, Connection, Response, [protocols([chat]), key('dGhlIHNhbXBsZSBub25jZQ==')]),
          http_socket_transport::close_connection(Connection),
          http_server::stop(Server).

     Response = response(http(1,1), status(101, 'Switching Protocols'), _, empty, _).

The ‘Connection’ term returned by ‘open_websocket/4’ remains open.
After the handshake, either close it explicitly with
‘http_socket_transport::close_connection/1’ or hand it to the
‘http_websocket’, ‘http_websocket_messages’, ‘http_websocket_session’,
or ‘http_websocket_service’ libraries.


File: TheLogtalkHandbook-3.101.0.info,  Node: Current scope<2>,  Next: Multipart workflow,  Prev: Usage examples,  Up: http_client

6.93.5 Current scope
--------------------

The initial request-oriented implementation provides:

   - ‘request/4’ for one-shot requests against absolute URLs supported
     by the selected transport.

   - ‘open_websocket/4’ for validated WebSocket opening handshakes
     against absolute WebSocket URLs supported by the selected
     transport, returning the upgraded reusable connection handle and
     the ‘101’ response.

   - ‘request/5’ for requests over an already open compatible reusable
     connection or connection pool handle, with endpoint validation
     against the supplied URL.

   - ‘get/3-4’, ‘head/3-4’, ‘delete/3-4’, ‘post/4-5’, ‘put/4-5’, and
     ‘patch/4-5’ convenience predicates.

When the same request-construction or WebSocket opening-handshake option
is given multiple times, the first occurrence is used.

Supported request options are:

   - ‘transport(Transport)’ to select the transport object.  Default:
     ‘default’, which selects the transport from the URL scheme.

   - ‘headers(Headers)’ to supply normalized request headers.

   - ‘body(Body)’ to supply a normalized request body.  The
     request-oriented facade also accepts ‘body(form_data(Items))’ as a
     convenience descriptor for multipart form-data requests; in that
     case it builds the multipart body via ‘http_multipart’ and injects
     a generated boundary property unless the caller already provided
     one in ‘properties/1’.

   - ‘query(Pairs)’ to append URL-encoded query pairs to the URL query
     string.

   - ‘version(Version)’ to override the default ‘http(1,1)’ version.

   - ‘properties(Properties)’ to supply additional normalized request
     properties.

   - ‘connection_options(Options)’ to pass transport-specific options
     through to the underlying ‘open_connection/4’ call for one-shot
     requests.  When the URL uses the ‘https://’ scheme,
     ‘connection_transport(tls)’ is added automatically unless ‘Options’
     already specify a transport explicitly.

Supported WebSocket opening-handshake options are:

   - ‘transport(Transport)’ to select the transport object.  Default:
     ‘default’, which selects the transport from the URL scheme.

   - ‘headers(Headers)’ to supply additional normalized handshake
     request headers other than the handshake-managed headers.

   - ‘query(Pairs)’ to append URL-encoded query pairs to the URL query
     string.

   - ‘version(Version)’ to override the default ‘http(1,1)’ version.
     The opening handshake requires HTTP/1.1 or later.

   - ‘protocols(Protocols)’ to request one or more subprotocol tokens.

   - ‘key(Key)’ to provide an explicit ‘Sec-WebSocket-Key’ value.  When
     omitted, a fresh key is generated automatically.

   - ‘connection_options(Options)’ to pass transport-specific options
     through to the selected transport ‘open_connection/4’ predicate.
     When the URL uses the ‘wss://’ scheme, ‘connection_transport(tls)’
     is added automatically unless ‘Options’ already specify a transport
     explicitly.

The stream-based primitives remain available from the ‘http_client_core’
object.


File: TheLogtalkHandbook-3.101.0.info,  Node: Multipart workflow,  Next: WebSocket workflow,  Prev: Current scope<2>,  Up: http_client

6.93.6 Multipart workflow
-------------------------

The current multipart workflow is intentionally small but practical:

   - For generic multipart bodies, callers can keep using normalized
     ‘content(MediaType, multipart(Parts))’ terms.

   - For common form-data requests, callers can use ‘form_data(Items)’
     through the existing body path, including ‘post/4-5’, ‘put/4-5’,
     and ‘patch/4-5’.

   - The ‘Items’ descriptors are the same ‘field(Name, Value,
     Parameters)’ and ‘file(Name, Filename, MediaType, Payload,
     Parameters)’ descriptors supported by the
     ‘http_multipart::form_data_body/2’ helper.

   - In both descriptor shapes, ‘Parameters’ is the ordered list of
     extra ‘Content-Disposition: form-data’ parameters to preserve or
     generate.

   - The reserved ‘name’ and ‘filename’ parameters stay explicit helper
     arguments and must not be repeated in the ‘Parameters’ list.

   - When using the convenience descriptor, the client facade adds a
     multipart boundary property automatically so the request can be
     generated on the wire without extra caller bookkeeping.

For example, callers can send extra disposition parameters explicitly:

     | ?- http_client::post(
          URL,
          form_data([
              field(title, 'Logtalk', [charset-utf8]),
              file(upload, 'notes.txt', 'text/plain', text(hello), [creation_date-'2026-06-08'])
          ]),
          Response,
          []
      ).


File: TheLogtalkHandbook-3.101.0.info,  Node: WebSocket workflow,  Next: Current limitations<2>,  Prev: Multipart workflow,  Up: http_client

6.93.7 WebSocket workflow
-------------------------

The current WebSocket workflow is intentionally limited to the opening
handshake:

   - Call ‘open_websocket/4’ with an absolute WebSocket URL supported by
     the selected transport.

   - The helper opens a dedicated reusable transport connection, sends a
     normalized opening-handshake request, and validates the server
     ‘101’ response including the ‘Sec-WebSocket-Accept’ value.

   - When the call succeeds, the returned connection handle remains open
     so a higher layer can take over the upgraded stream, typically by
     calling the selected transport ‘connection_streams/3’ predicate and
     then using the ‘http_websocket’ frame predicates, the
     ‘http_websocket_messages’ message predicates, or the stateful
     ‘http_websocket_session’ predicates with explicit close-state and
     automatic control-message handling, including the higher-level
     ‘http_websocket_service’ ‘run_session/3-4’ callback loop.

   - When client-side code wants one entry point for handshake plus
     session execution, the ‘http_websocket_client_service::open/4-5’
     predicates layer on top of ‘open_websocket/4’, can write optional
     initial outbound messages, and then run the callback-driven session
     loop.

   - Callers are responsible for eventually closing that connection
     using the selected transport ‘close_connection/1’ predicate if a
     later layer does not take ownership of it.  The
     ‘http_websocket_service::run_session/3-4’ predicates do take
     ownership of the upgraded connection and close it automatically
     when the session loop finishes, as do the higher-level
     ‘http_websocket_client_service::open/4-5’ predicates.


File: TheLogtalkHandbook-3.101.0.info,  Node: Current limitations<2>,  Prev: WebSocket workflow,  Up: http_client

6.93.8 Current limitations
--------------------------

   - The ‘open_websocket/4’ predicate is limited to opening-handshake
     validation.  See the dedicated WebSocket libraries for frame
     parsing, message reassembly, and related functionality.


File: TheLogtalkHandbook-3.101.0.info,  Node: http_client_core,  Next: http_cookies,  Prev: http_client,  Up: Libraries

6.94 ‘http_client_core’
=======================

The ‘http_client_core’ library provides low-level stream primitives that
are transport-neutral and used by ‘http_socket_transport’ the library.

This library can be used with backend Prolog systems that support
unbound integer arithmetic and the ‘sockets’ library: ECLiPSe, SICStus
Prolog, SWI-Prolog, Trealla Prolog, and XVM.

* Menu:

* API documentation: API documentation<113>.
* Loading: Loading<114>.
* Testing: Testing<106>.
* Current scope: Current scope<3>.
* Framing rules::
* Current limitations: Current limitations<3>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<113>,  Next: Loading<114>,  Up: http_client_core

6.94.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#http_client_core’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<114>,  Next: Testing<106>,  Prev: API documentation<113>,  Up: http_client_core

6.94.2 Loading
--------------

To load the library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(http_client_core(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<106>,  Next: Current scope<3>,  Prev: Loading<114>,  Up: http_client_core

6.94.3 Testing
--------------

To test this library, load the ‘tester.lgt’ file:

     | ?- logtalk_load(http_client_core(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Current scope<3>,  Next: Framing rules,  Prev: Testing<106>,  Up: http_client_core

6.94.4 Current scope
--------------------

The ‘http_client_core’ object provides the following stream-based
predicates:

   - ‘write_request/2’

   - ‘read_response/2’

   - ‘exchange/4’

   - ‘exchange_sequence/4’


File: TheLogtalkHandbook-3.101.0.info,  Node: Framing rules,  Next: Current limitations<3>,  Prev: Current scope<3>,  Up: http_client_core

6.94.5 Framing rules
--------------------

The ‘http_client_core’ object supports response framing for:

   - status codes that never carry a body (‘1xx’, ‘204’, ‘205’, and
     ‘304’)

   - fixed-length bodies via ‘Content-Length’

   - chunked bodies via ‘Transfer-Encoding: chunked’, including trailers

   - close-delimited bodies terminated by end-of-file

Request-aware exchanges performed by ‘http_client_core::exchange/4’ and
‘http_client_core::exchange_sequence/4’ also support ‘HEAD’ responses.
In that case the normalized response body is ‘empty’ and the response is
annotated with the metadata properties ‘body_omitted(head)’ and, when
applicable, ‘omitted_body_length(Length)’.

Close-delimited responses returned by
‘http_client_core::read_response/2’ and ‘http_client_core::exchange/4’
are annotated with the property ‘body_framing(close_delimited)’.
Sequential exchanges can only use a close-delimited response as the
final response in the sequence because the connection is consumed while
reading the body.


File: TheLogtalkHandbook-3.101.0.info,  Node: Current limitations<3>,  Prev: Framing rules,  Up: http_client_core

6.94.6 Current limitations
--------------------------

   - Only the transport coding sequence ‘[chunked]’ is recognized when
     reading streamed response bodies in ‘http_client_core’.

   - Close-delimited response bodies can only be used as the final
     response in an ‘http_client_core::exchange_sequence/4’ sequence.

   - The ‘http_client_core’ object assumes binary streams for both input
     and output.


File: TheLogtalkHandbook-3.101.0.info,  Node: http_cookies,  Next: http_core,  Prev: http_client_core,  Up: Libraries

6.95 ‘http_cookies’
===================

This library implements validation, parsing, and generation of HTTP
‘Cookie’ and ‘Set-Cookie’ header field values following RFC 6265 syntax.
Header values can be represented as atoms, character lists, or code
lists.

* Menu:

* API documentation: API documentation<114>.
* Loading: Loading<115>.
* Testing: Testing<107>.
* Usage: Usage<50>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<114>,  Next: Loading<115>,  Up: http_cookies

6.95.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#http_cookies’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<115>,  Next: Testing<107>,  Prev: API documentation<114>,  Up: http_cookies

6.95.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(http_cookies(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<107>,  Next: Usage<50>,  Prev: Loading<115>,  Up: http_cookies

6.95.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(http_cookies(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<50>,  Prev: Testing<107>,  Up: http_cookies

6.95.4 Usage
------------

The library predicates are defined in the
‘http_cookies(_Representation_)’ parametric object where
‘_Representation_’ can be one of:

   - ‘atom’ - cookie texts are represented as atoms

   - ‘chars’ - cookie texts are represented as lists of characters

   - ‘codes’ - cookie texts are represented as lists of character codes

The parameter must be bound when sending messages to the object.

‘Cookie’ header values are represented as lists of ‘Name-Value’ pairs.

‘Set-Cookie’ header values are represented by a cookie name, a cookie
value, and a list of attributes.

where ‘Attributes’ use ‘Key-Value’ notation and can contain:

   - ‘expires-date_time(Year, Month, Day, Hours, Minutes, Seconds)’

   - ‘max_age-Seconds’

   - ‘domain-Domain’

   - ‘path-Path’

   - ‘secure-true’

   - ‘http_only-true’

   - ‘same_site-lax|strict|none’

   - ‘partitioned-true’

   - ‘priority-low|medium|high’

   - ‘extension-Attribute’

Unknown Set-Cookie attributes are preserved as ‘extension-Attribute’
pairs so long as they do not reuse one of the reserved RFC 6265
attribute names.

The ‘Expires’ attribute is normalized to a ‘date_time/6’ term when
parsing and generated back using the canonical HTTP-date syntax.

For interoperability with LemonLDAP::NG-style cookies, the parser also
accepts boolean ‘Set-Cookie’ attributes encoded as ‘Name=1’ in addition
to the standard flag form.  This applies to the ‘Secure’, ‘HttpOnly’,
and ‘Partitioned’ attributes.

The library also provides pure helpers for working with canonical
attribute lists:

   - ‘normalize_cookie_attributes/2’

   - ‘cookie_attribute_present/2’

   - ‘cookie_attribute_value/3-4’

   - ‘cookie_expiry/2-3’

   - ‘cookie_deletion/3’


File: TheLogtalkHandbook-3.101.0.info,  Node: http_core,  Next: http_cors,  Prev: http_cookies,  Up: Libraries

6.96 ‘http_core’
================

This library provides the transport-independent core of the HTTP stack.
It currently covers normalized request and response terms, shared
protocols, wire parsing and generation for the message start-lines,
headers, and bodies, plus semantic normalization for a core set of
frequently used headers.

* Menu:

* API documentation: API documentation<115>.
* Loading: Loading<116>.
* Testing: Testing<108>.
* Layering::
* Current scope: Current scope<4>.
* Normalized terms::
* Current limitations: Current limitations<4>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<115>,  Next: Loading<116>,  Up: http_core

6.96.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#http_core’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<116>,  Next: Testing<108>,  Prev: API documentation<115>,  Up: http_core

6.96.2 Loading
--------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(http_core(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<108>,  Next: Layering,  Prev: Loading<116>,  Up: http_core

6.96.3 Testing
--------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(http_core(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Layering,  Next: Current scope<4>,  Prev: Testing<108>,  Up: http_core

6.96.4 Layering
---------------

Use the ‘http_core’ library as the base of the current HTTP and API
stack:

   - Start here when you need normalized ‘request/6’ and ‘response/5’
     terms, shared protocols, body codecs, or wire parsing and
     generation.

   - Add http_server_core(1) or http_client(2) when you need
     transport-side orchestration on top of those normalized messages.

   - Add http_router(3) when you want declarative path-template and
     method dispatch over handler objects implementing the
     ‘http_handler_protocol’ protocol.

   - Add rest(4) when you want a higher-level authoring layer on top of
     ‘http_router’.

   - Pair any of those layers with open_api(5) when you want OpenAPI
     document derivation or request and response contract validation.

   ---------- Footnotes ----------

   (1) ../http_server_core/NOTES.md

   (2) ../http_client/NOTES.md

   (3) ../http_router/NOTES.md

   (4) ../rest/NOTES.md

   (5) ../open_api/NOTES.md


File: TheLogtalkHandbook-3.101.0.info,  Node: Current scope<4>,  Next: Normalized terms,  Prev: Layering,  Up: http_core

6.96.5 Current scope
--------------------

   - Define core shared protocols for request objects, response objects,
     body codecs, and handlers

   - Construct normalized ‘request/6’ and ‘response/5’ terms using
     ‘request/7’ and ‘response/6’

   - Validate normalized methods, targets, versions, statuses, headers,
     bodies, and higher-layer properties

   - Provide generic accessors over normalized request and response
     terms

   - Parse and generate request lines, status lines, header blocks,
     bodies, full requests, and full responses

   - Generate effective response headers independently from the response
     body bytes using ‘generate_response_headers/2’ when higher layers
     need to stream file-backed bodies without materializing them in
     memory first

   - Decode and generate chunked transfer coding for full requests and
     responses, including normalized ‘trailers/1’ properties

   - Parse and generate multipart bodies at both the standalone body
     level and the full-message level when a boundary is available

   - Provide the normalized multipart body and part representation
     reused by the higher-level ‘http_multipart’ helpers and the current
     client and server integration tests

   - Normalize and generate the core WebSocket opening-handshake headers
     needed by the next client and server transport slices

   - Dispatch to concrete body codecs for ‘application/octet-stream’,
     ‘text/plain’, ‘application/json’, and
     ‘application/x-www-form-urlencoded’

   - Normalize semantic header values for ‘Content-Length’,
     ‘Content-Type’, ‘Accept-Query’, ‘Cookie’, ‘Set-Cookie’, ‘Host’,
     ‘Connection’, ‘Upgrade’, ‘Sec-WebSocket-Key’,
     ‘Sec-WebSocket-Version’, ‘Sec-WebSocket-Accept’,
     ‘Sec-WebSocket-Protocol’, and ‘Transfer-Encoding’

   - Derive and validate normalized properties such as ‘content_type/2’,
     ‘accept_query/1’, ‘content_length/1’, ‘host/1-2’, ‘cookies/1’,
     ‘set_cookies/1’, ‘query_pairs/1’, ‘path_segments/1’, ‘scheme/1’,
     ‘connection/1’, ‘upgrade/1’, ‘websocket_key/1’,
     ‘websocket_version/1’, ‘websocket_accept/1’,
     ‘websocket_protocol/1’, ‘transfer_encoding/1’, ‘trailers/1’, and
     ‘decoded_body/1’

   - Reuse ‘url’ for absolute-target validation and ‘http_cookies’ for
     ‘Cookie’ and ‘Set-Cookie’ header validation

   - Provide the internal ‘http_origin_site_helpers’ category reused by
     ‘http_cors’ and ‘http_session’ for absolute URL parsing, ‘Origin’
     parsing, normalized endpoint derivation, and schemeful same-site
     comparison using a bundled public suffix rule set with exact,
     wildcard, and exception cases


File: TheLogtalkHandbook-3.101.0.info,  Node: Normalized terms,  Next: Current limitations<4>,  Prev: Current scope<4>,  Up: http_core

6.96.6 Normalized terms
-----------------------

Requests use the fixed-arity term:

     request(Method, Target, Version, Headers, Body, Properties)

Responses use the fixed-arity term:

     response(Version, Status, Headers, Body, Properties)

Supported request method atoms include the core HTTP methods plus
‘query’ for the HTTP QUERY method defined by RFC 10008.  Method atoms
are normalized to lowercase internally and generated uppercase on the
wire.

Supported request targets are:

   - ‘asterisk’

   - ‘origin(Path)’

   - ‘origin(Path, Query)’

   - ‘absolute(URLComponents)’

   - ‘authority(Host)’

   - ‘authority(Host, Port)’

Supported body terms are:

   - ‘empty’

   - ‘content(MediaType, binary(Bytes))’

   - ‘content(MediaType, file(Path, Offset, Length))’

   - ‘content(MediaType, text(Text))’

   - ‘content(MediaType, json(Term))’

   - ‘content(MediaType, form(Pairs))’

   - ‘content(MediaType, multipart(Parts))’

Multipart parts use recursive normalized terms:

     part(Headers, Body, Properties)

The ‘Accept-Query’ response header can be represented directly as a
typed header value or as a response property:

accept_query-[media_range(MediaRange, Parameters), …]
accept_query([media_range(MediaRange, Parameters), …])

‘MediaRange’ is a lowercase media range atom such as
‘application/x-www-form-urlencoded’, ‘application/jsonpath’, ‘text/*’,
or ‘*/*’.  ‘Parameters’ is a list of ‘Name-Value’ pairs.


File: TheLogtalkHandbook-3.101.0.info,  Node: Current limitations<4>,  Prev: Normalized terms,  Up: http_core

6.96.7 Current limitations
--------------------------

   - Chunked transfer coding support is limited to the bare
     ‘Transfer-Encoding: chunked’ case; stacked transfer codings remain
     out of scope for now

   - Multipart wire parsing and generation require a boundary parameter
     in the effective ‘Content-Type’ metadata, or an explicit
     ‘boundary/1’ option when using ‘parse_body/4’ or ‘generate_body/3’

   - File-backed bodies are generated only; parsing normalizes incoming
     bodies to in-memory payload terms.  The declared ‘Offset’ and
     ‘Length’ determine the response ‘Content-Length’ metadata when the
     body is generated.

   - The body codec set is intentionally small and focused on a limited
     set of media types

   - Header normalization is selective; headers outside the supported
     set are preserved as validated raw ‘Name-Value’ pairs

   - The internal schemeful same-site helper uses bundled public suffix
     rules to tighten site classification for multi-label public
     suffixes and hosted domains, but automatic synchronization with the
     full Mozilla Public Suffix List remains out of scope

   - The WebSocket support in this layer is limited to HTTP
     opening-handshake metadata normalization.  ‘wss://’ and TLS-backed
     transport orchestration are currently not supported


File: TheLogtalkHandbook-3.101.0.info,  Node: http_cors,  Next: http_digest,  Prev: http_core,  Up: Libraries

6.97 ‘http_cors’
================

The ‘http_cors’ library provides a transport-neutral CORS layer on top
of the normalized ‘http_core’ library.  It classifies normalized
requests as CORS or preflight requests, builds direct preflight
responses from CORS policies, and decorates normalized responses with
the relevant ‘Access-Control-*’ headers.

This library reuses the ‘http_core’, ‘http_server_core’, and
‘http_router’.  It uses normalized request and response terms and can be
called directly from plain handlers or from router hooks and response
middleware.

* Menu:

* API documentation: API documentation<116>.
* Loading: Loading<117>.
* Testing: Testing<109>.
* Current scope: Current scope<5>.
* Route-level overrides::
* Router integration::
* Plain handler integration::
* Current limitations: Current limitations<5>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<116>,  Next: Loading<117>,  Up: http_cors

6.97.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#http_cors’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<117>,  Next: Testing<109>,  Prev: API documentation<116>,  Up: http_cors

6.97.2 Loading
--------------

To load the library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(http_cors(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<109>,  Next: Current scope<5>,  Prev: Loading<117>,  Up: http_cors

6.97.3 Testing
--------------

To test this library, load the ‘tester.lgt’ file:

     | ?- logtalk_load(http_cors(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Current scope<5>,  Next: Route-level overrides,  Prev: Testing<109>,  Up: http_cors

6.97.4 Current scope
--------------------

The current implementation provides one transport-neutral public object
with five public predicates:

   - ‘request_origin/2’

   - ‘is_cors_request/1’

   - ‘is_preflight_request/1’

   - ‘preflight_response/3’

   - ‘add_response_headers/4’

The option DSL follows the ‘options’ library conventions and supports:

   - ‘allowed_origins(any)’

   - ‘allowed_origins(Origins)’

   - ‘allowed_methods(any)’

   - ‘allowed_methods(Methods)’

   - ‘allowed_headers(any)’

   - ‘allowed_headers(requested)’

   - ‘allowed_headers(Headers)’

   - ‘expose_headers(any)’

   - ‘expose_headers(Headers)’

   - ‘allow_credentials(Boolean)’

   - ‘max_age(none)’

   - ‘max_age(Seconds)’

The default policy is:

   - ‘allowed_origins([])’

   - ‘allowed_methods([get])’

   - ‘allowed_headers(requested)’

   - ‘expose_headers([])’

   - ‘allow_credentials(false)’

   - ‘max_age(none)’

This library consumes the normalized HTTP terms provided by the
‘http_core’ library:

     request(Method, Target, Version, Headers, Body, Properties)
     response(Version, Status, Headers, Body, Properties)

It reads normalized request headers such as ‘origin’,
‘access_control_request_method’, and ‘access_control_request_headers’
and emits normalized response headers such as
‘access_control_allow_origin’, ‘access_control_allow_methods’,
‘access_control_allow_headers’, ‘access_control_expose_headers’, and
‘vary’.

When policy depends on a specific requesting origin, generated responses
add or preserve the appropriate ‘Vary’ metadata.  Existing ‘Vary: *’
headers are treated as absorbing and remain ‘*’ when CORS headers are
merged into a response.

Wildcard header policies can be expressed explicitly using
‘allowed_headers(any)’ and ‘expose_headers(any)’.  For compatibility,
exact ‘['*']’ option values are normalized to the same wildcard
behavior.  On non-credentialed requests these policies emit ‘*’ when
that has the intended CORS wildcard meaning.  On credentialed requests,
and for ‘Authorization’ preflight requests, the library materializes
explicit header-name lists instead because browsers otherwise treat ‘*’
as a literal header name.

Similarly, ‘allowed_origins(any)’ emits ‘*’ for non-credentialed
requests but reflects the concrete request origin for credentialed
requests and adds ‘Vary: Origin’ so caches keep those responses
partitioned correctly.

Wildcard origin policies can also be expressed using pattern atoms
inside ‘allowed_origins(Origins)’, for example
‘allowed_origins(['https://*.example.com'])’.  These patterns match
exactly one leftmost hostname label, require exact scheme matching, and
require exact port matching when the pattern includes an explicit port.
Matching pattern policies always emit the concrete request origin and
add or preserve ‘Vary: Origin’ because the response depends on the
requesting origin.

Wildcard method policies can be expressed using ‘allowed_methods(any)’.
For compatibility, exact ‘['*']’ values are normalized to the same
wildcard behavior.  Method wildcards expand from the request
‘effective_methods(Methods)’ property after removing ‘options’, so they
are intended for routed or otherwise annotated requests that provide
that metadata.  The generated ‘Access-Control-Allow-Methods’ header
still contains an explicit method list.


File: TheLogtalkHandbook-3.101.0.info,  Node: Route-level overrides,  Next: Router integration,  Prev: Current scope<5>,  Up: http_cors

6.97.5 Route-level overrides
----------------------------

When present, the request property ‘cors(Options)’ overrides the
caller-supplied default options.  This makes it possible to define
router-wide defaults and then refine them per route using
‘route_metadata/2’.

Example route metadata:

     route_metadata(show_page, [
         cors([
             allowed_origins(['https://app.example.com']),
             expose_headers([x_trace_id]),
             allow_credentials(true)
         ])
     ]).


File: TheLogtalkHandbook-3.101.0.info,  Node: Router integration,  Next: Plain handler integration,  Prev: Route-level overrides,  Up: http_cors

6.97.6 Router integration
-------------------------

For actual routed responses, use router response middleware:

     response_middleware(cors, add_cors_headers).

     add_cors_headers(Request, Response0, Response) :-
         Defaults = [
             allowed_origins([]),
             allowed_methods([get]),
             allowed_headers(requested),
             expose_headers([]),
             allow_credentials(false),
             max_age(none)
         ],
         http_cors::add_response_headers(Request, Response0, Response, Defaults).

For automatic router ‘OPTIONS’ responses, use
‘route_automatic_options_response/3’ when the router object wants to
build a direct preflight response:

     route_automatic_options_response(Request, _EffectiveMethods, Response) :-
         Defaults = [
             allowed_origins([]),
             allowed_methods([get, post]),
             allowed_headers(requested),
             expose_headers([]),
             allow_credentials(false),
             max_age(none)
         ],
         http_cors::preflight_response(Request, Response, Defaults).

The current ‘http_router’ implementation annotates synthetic automatic
‘OPTIONS’ requests with ‘automatic_options(true)’,
‘effective_methods(Methods)’, and route metadata when the match is
unique or the metadata is shared across same-path matches.  This allows
‘http_cors’ integrations to reuse those annotations directly.


File: TheLogtalkHandbook-3.101.0.info,  Node: Plain handler integration,  Next: Current limitations<5>,  Prev: Router integration,  Up: http_cors

6.97.7 Plain handler integration
--------------------------------

For plain handlers using ‘http_server_core’, the recommended pattern is:

  1. detect preflight requests with ‘is_preflight_request/1’

  2. build the direct preflight response with ‘preflight_response/3’

  3. otherwise build the application response and pass it through
     ‘add_response_headers/4’

When ‘add_response_headers/4’ denies a request, it does not add
permission headers but it may still preserve or add cache-relevant
‘Vary’ metadata.  Use ‘preflight_response/3’ when an explicit ‘403
Forbidden’ preflight response is required.


File: TheLogtalkHandbook-3.101.0.info,  Node: Current limitations<5>,  Prev: Plain handler integration,  Up: http_cors

6.97.8 Current limitations
--------------------------

   - Origin matching is exact and string-based

   - Dynamic callback policies are not supported


File: TheLogtalkHandbook-3.101.0.info,  Node: http_digest,  Next: http_directory_listing,  Prev: http_cors,  Up: Libraries

6.98 ‘http_digest’
==================

This library provides HTTP Digest authentication helpers on top of the
normalized HTTP stack.

This library can be used with backend Prolog systems that support
unbound integer arithmetic and the ‘sockets’ library: ECLiPSe, SICStus
Prolog, SWI-Prolog, Trealla Prolog, and XVM.

* Menu:

* API documentation: API documentation<117>.
* Loading: Loading<118>.
* Testing: Testing<110>.
* Usage overview: Usage overview<2>.
* Current scope: Current scope<6>.
* Non-implemented features: Non-implemented features<2>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<117>,  Next: Loading<118>,  Up: http_digest

6.98.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#http_digest’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<118>,  Next: Testing<110>,  Prev: API documentation<117>,  Up: http_digest

6.98.2 Loading
--------------

To load the library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(http_digest(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<110>,  Next: Usage overview<2>,  Prev: Loading<118>,  Up: http_digest

6.98.3 Testing
--------------

To test this library, load the ‘tester.lgt’ file:

     | ?- logtalk_load(http_digest(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage overview<2>,  Next: Current scope<6>,  Prev: Testing<110>,  Up: http_digest

6.98.4 Usage overview
---------------------

The library provides these public entities:

   - ‘http_digest_verifier_protocol’ server-side verifier protocol for
     looking up stored Digest HA1 values

   - ‘http_digest’ core Digest parsing, generation, request
     authorization, request protection, challenge building, and
     ‘Authentication-Info’ response decoration

   - ‘http_server_core_digest_handler(_, _, _, _)’ portable handler
     wrapper that applies Digest protection and response decoration
     around another object implementing ‘http_handler_protocol’

   - ‘http_router_digest_auth(_, _, _)’ router companion category that
     protects routes declaring ‘digest_auth/1’ metadata and decorates
     successful protected responses with ‘Authentication-Info’

   - ‘http_client_digest_session’ stateful client helper that preserves
     cookies and retries once when the server replies with a ‘401’
     Digest challenge

The library design keeps the Digest core object stateless and
deterministic.  State is kept only where it is operationally useful: in
verifier objects supplied by applications and in the optional
client-side session helper used for cookie storage.

The server-side entities are portable across the backends supported by
the normalized HTTP library.  The ‘http_client_digest_session’ helper
additionally depends on the socket-backed HTTP client stack and is
therefore available on the same backends supported by the ‘http_client’
and ‘http_socket_transport’ libraries.

Use ‘http_digest’ directly when you need explicit control over Digest
challenge parsing and request verification:

     | ?- http_digest::unauthorized_response(Challenge, Response, [realm('private'), nonce_secret('secret')]).

Wrap a normal handler with ‘http_server_core_digest_handler(_, _, _, _)’
when you want a portable middleware-style integration point for Digest
verification:

     | ?- Handler = http_server_core_digest_handler(verifier, app_handler, [realm('private'), nonce_secret('secret')], []).

Use ‘http_router_digest_auth(_, _, _)’ in router objects importing
‘http_router’ when you want per-route protection driven by normal route
metadata:

     authorize_routed_request(Request, Action) :-
         ^^authorize_digest_auth_request(Request, Action).

     response_middleware(digest_authentication_info, add_digest_authentication_info).

     route_metadata(show_secret, [digest_auth([])]).

Use ‘http_client_digest_session’ when you need cookie persistence plus
automatic retry after a ‘401’ Digest challenge:

     | ?- http_client_digest_session::open(Session, 'Mufasa', 'Circle Of Life'),
          http_client_digest_session::get(Session, 'http://127.0.0.1:8080/protected', Response, []),
          http_client_digest_session::close(Session).

The current client helper is reactive: it sends the initial request
without an ‘Authorization’ header and retries automatically only after
receiving a Digest challenge.  This keeps the helper small and avoids
maintaining speculative challenge caches inside the client session
state.

For ‘add_authentication_info/4’, the ‘nextnonce’ option accepts three
forms:

   - ‘nextnonce(false)’ omits the ‘nextnonce’ field

   - ‘nextnonce(true)’ generates a fresh nonce using ‘nonce_secret/1’

   - ‘nextnonce(Nonce)’ emits the explicit nonce atom verbatim


File: TheLogtalkHandbook-3.101.0.info,  Node: Current scope<6>,  Next: Non-implemented features<2>,  Prev: Usage overview<2>,  Up: http_digest

6.98.5 Current scope
--------------------

   - deterministic Digest header parsing and generation for challenges,
     authorizations, and ‘Authentication-Info’

   - ‘auth’ and ‘auth-int’ quality-of-protection request and response
     digest computation, with ‘auth-int’ hashing transfer-decoded
     entity-body bytes

   - server-side request protection through explicit verifier objects

   - middleware-style handler wrapping for server integration

   - route-level protection and successful-response
     ‘Authentication-Info’ decoration through
     ‘http_router_digest_auth(_, _, _)’ plus the
     ‘authorize_routed_request/2’ and ‘response_middleware/2’ router
     hooks

   - client-side Digest retry on top of the existing socket-backed
     transport and cookie-jar support, including ‘https://’ URLs when
     the selected transport parameterization supports secure schemes

   - MD5, SHA-256, and SHA-512-256 based Digest computations through the
     ‘hashes’ and ‘hmac’ libraries; when no algorithm option is
     provided, the default challenge algorithm remains ‘sha256’


File: TheLogtalkHandbook-3.101.0.info,  Node: Non-implemented features<2>,  Prev: Current scope<6>,  Up: http_digest

6.98.6 Non-implemented features
-------------------------------

   - proactive client-side challenge caching across requests

   - shared or persistent nonce replay stores


File: TheLogtalkHandbook-3.101.0.info,  Node: http_directory_listing,  Next: http_htmx,  Prev: http_digest,  Up: Libraries

6.99 ‘http_directory_listing’
=============================

The ‘http_directory_listing’ library provides a router-agnostic helper
for serving HTML directory listings from a configured document root
using normalized ‘http_core’ request and response terms.

This library resolves a relative request path against a document root,
canonicalizes the joined target path using ‘os::absolute_file_name/2’,
rejects canonicalized escapes with the same outward ‘404 Not Found’
response used for missing directories, and renders a simple HTML5
listing for existing directory targets.

* Menu:

* API documentation: API documentation<118>.
* Loading: Loading<119>.
* Testing: Testing<111>.
* Current scope: Current scope<7>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<118>,  Next: Loading<119>,  Up: http_directory_listing

6.99.1 API documentation
------------------------

Open the ‘../../apis/library_index.html#http_directory_listing’ link in
a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<119>,  Next: Testing<111>,  Prev: API documentation<118>,  Up: http_directory_listing

6.99.2 Loading
--------------

To load the library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(http_directory_listing(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<111>,  Next: Current scope<7>,  Prev: Loading<119>,  Up: http_directory_listing

6.99.3 Testing
--------------

To test this library, load the ‘tester.lgt’ file:

     | ?- logtalk_load(http_directory_listing(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Current scope<7>,  Prev: Testing<111>,  Up: http_directory_listing

6.99.4 Current scope
--------------------

The current version provides one public object with two public
predicates:

   - ‘serve/4’

   - ‘serve/5’

Supported options are:

   - ‘dot_files(Boolean)’

   - ‘directories_first(Boolean)’

   - ‘sort_by(SortBy)’

   - ‘sort_order(SortOrder)’

   - ‘columns(Columns)’

   - ‘type_display(TypeDisplay)’

   - ‘size_display(SizeDisplay)’

   - ‘title(Title)’

   - ‘theme(Theme)’

   - ‘stylesheets(Stylesheets)’

   - ‘exclude(Exclusions)’

   - ‘cache_control(Directives)’

   - ‘expires(Expires)’

Default options are:

   - ‘dot_files(false)’

   - ‘directories_first(true)’

   - ‘sort_by(name)’

   - ‘sort_order(ascending)’

   - ‘columns([name, type, size, modified])’

   - ‘type_display(simple)’

   - ‘size_display(bytes)’

   - ‘title('Directory listing')’

   - ‘theme(default)’

   - ‘stylesheets([])’

   - ‘exclude([])’

   - ‘cache_control([])’

   - ‘expires(none)’

Supported features:

   - ‘GET’ and ‘HEAD’

   - ‘200 OK’ HTML directory listings for existing directory targets

   - canonical docroot-prefix checks after path normalization

   - shared document-root path sandboxing with ‘http_static_files’

   - directory-first sorting by default, with configurable fallback to a
     single mixed ordering

   - sortable ‘Name’, ‘Type’, ‘Size’, and ‘Modified’ columns

   - query-driven ordering using ‘sort=name|type|size|modified’ and
     ‘order=ascending|descending’ for visible columns only

   - breadcrumb navigation for the current directory path

   - parent-directory navigation for non-root listings

   - relative links for directory and file entries

   - file metadata columns for entry type, file size, and file
     modification time

   - optional column selection while keeping the ‘Name’ column visible

   - MIME-based file-type display using ‘type_display(media)’

   - optional file-size display units using ‘size_display(kilobytes)’,
     ‘size_display(megabytes)’, ‘size_display(gigabytes)’, or
     ‘size_display(terabytes)’

   - theme-aware CSS hooks on the generated ‘<body>’, ‘<table>’, and
     entry rows

   - optional stylesheet ‘<link>’ generation for custom presentation
     themes

   - optional inclusion of dot files

   - configurable exclusion of entry names using exact names, prefixes,
     suffixes, or simple wildcard patterns

   - configurable ‘Cache-Control’ and ‘Expires’ response headers

   - ‘404 Not Found’ for missing, unsafe, or non-directory targets

   - ‘405 Method Not Allowed’ for other methods

Presentation customization uses these option values:

   - ‘columns(Columns)’ accepts an ordered subset of ‘[name, type, size,
     modified]’ that must include ‘name’; hidden columns are also
     removed from the accepted query ‘sort=’ values, with hidden or
     invalid sort keys falling back to the effective default visible
     column

   - ‘type_display(simple)’ keeps the existing ‘file’/‘directory’ labels
     while ‘type_display(media)’ renders MIME-based file type text such
     as ‘text/plain’

   - ‘size_display(bytes)’ renders file sizes as raw byte counts;
     ‘size_display(kilobytes)’, ‘size_display(megabytes)’,
     ‘size_display(gigabytes)’, and ‘size_display(terabytes)’ render
     sizes with one decimal digit using binary multiples and labels such
     as ‘1.2 KB’ or ‘4.8 MB’; size sorting continues to use the raw byte
     value

   - ‘theme(Theme)’ adds a ‘theme-Theme’ CSS class to the generated
     ‘<body>’ and ‘<table>’ elements

   - ‘stylesheets(Stylesheets)’ appends stylesheet links in the
     generated ‘<head>’

   - ‘exclude(Exclusions)’ removes matching entry names before metadata
     and sorting; entries can be excluded using ‘name(Name)’,
     ‘prefix(Prefix)’, ‘suffix(Suffix)’, ‘wildcard(Pattern)’, or an atom
     shortcut for a wildcard pattern such as ‘'.DS_Store'’ or ‘'*.tmp'’;
     in wildcard patterns, only ‘*’ has special meaning

Cache-policy configuration uses these option values:

   - ‘cache_control(Directives)’ where ‘Directives’ is a list containing
     any of ‘public’, ‘private’, ‘no_cache’, ‘no_store’, ‘no_transform’,
     ‘must_revalidate’, ‘proxy_revalidate’, ‘immutable’,
     ‘max_age(Seconds)’, ‘s_maxage(Seconds)’,
     ‘stale_while_revalidate(Seconds)’, ‘stale_if_error(Seconds)’, or
     ‘extension(Directive)’

   - ‘expires(none)’ to omit the header, ‘expires(Seconds)’ for a
     relative expiry from the current system time, or
     ‘expires(date_time(Year,Month,Day,Hour,Minute,Second))’ for an
     absolute expiry time

The generated HTML includes stable CSS hooks such as:

   - ‘body’ class ‘http-directory-listing theme-Theme’

   - ‘table’ class ‘directory-listing-table theme-Theme columns-...’

   - entry row classes ‘entry entry-directory’ and ‘entry entry-file’


File: TheLogtalkHandbook-3.101.0.info,  Node: http_htmx,  Next: http_multipart,  Prev: http_directory_listing,  Up: Libraries

6.100 ‘http_htmx’
=================

The ‘http_htmx’ library provides router-agnostic helpers for HTMX
request classification, HTML reply construction, and HTMX
response-header decoration using normalized ‘http_core’ request and
response terms.

Currently this library provides:

   - HTMX request detection helpers

   - ‘reply/3-4’ helpers for pre-rendered HTML atoms and ‘html’
     terms/lists

   - ‘page_fragment_reply/4-5’ helpers for full-page replies on
     ordinary, boosted, and history-restore HTMX requests and fragment
     replies on other HTMX requests

   - ‘add_response_headers/4’ for the common ‘HX-*’ response headers

   - the companion ‘http_router_htmx’ category for router middleware
     integration

* Menu:

* API documentation: API documentation<119>.
* Loading: Loading<120>.
* Testing: Testing<112>.
* Current scope: Current scope<8>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<119>,  Next: Loading<120>,  Up: http_htmx

6.100.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#http_htmx’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<120>,  Next: Testing<112>,  Prev: API documentation<119>,  Up: http_htmx

6.100.2 Loading
---------------

To load the library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(http_htmx(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<112>,  Next: Current scope<8>,  Prev: Loading<120>,  Up: http_htmx

6.100.3 Testing
---------------

To test this library, load the ‘tester.lgt’ file:

     | ?- logtalk_load(http_htmx(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Current scope<8>,  Prev: Testing<112>,  Up: http_htmx

6.100.4 Current scope
---------------------

The current library provides one public object and one companion
category:

   - object ‘http_htmx’

   - category ‘http_router_htmx’

The main public predicates are:

   - ‘is_htmx_request/1’

   - ‘is_boosted_request/1’

   - ‘is_history_restore_request/1’

   - ‘is_fragment_request/1’

   - ‘request_kind/2’

   - ‘current_url/2’

   - ‘current_url_abs_path/2’

   - ‘prompt/2’

   - ‘target/2’

   - ‘trigger/2’

   - ‘trigger_name/2’

   - ‘request_property/2’

   - ‘request_properties/2’

   - ‘reply/3’

   - ‘reply/4’

   - ‘page_fragment_reply/4’

   - ‘page_fragment_reply/5’

   - ‘add_response_headers/4’

The companion router category provides these middleware handler
predicates:

   - ‘annotate_htmx_request/2’

   - ‘add_htmx_response_headers/3’

For handlers that only need one HTMX request flag or value, prefer
‘request_property/2’.  Use ‘request_properties/2’ when you need the full
derived property list, for example when annotating a request with all
HTMX metadata.  The derived property set now also includes
‘htmx_request_kind(Kind)’, mirroring ‘request_kind/2’ for middleware and
other property-oriented consumers.

For handlers that need the same full-page versus fragment decision used
by ‘page_fragment_reply/4-5’, prefer ‘is_fragment_request/1’ instead of
repeating the ‘HX-Request’, ‘HX-Boosted’, and
‘HX-History-Restore-Request’ checks.

For handlers that need one mutually exclusive classification for control
flow or presentation, prefer ‘request_kind/2’ instead of open-coding
precedence between ordinary, fragment, boosted, and history-restore
requests.

For handlers that need a same-origin absolute-path form of
‘HX-Current-URL’, prefer ‘current_url_abs_path/2’.  It returns the path
plus optional query and fails when the current URL does not match the
request scheme and host information.

The supported response-header options are currently:

   - ‘redirect(URL)’

   - ‘refresh(Boolean)’

   - ‘vary_hx_request(Boolean)’

   - ‘location(Value)’

   - ‘push_url(Value)’

   - ‘replace_url(Value)’

   - ‘reswap(Value)’

   - ‘retarget(Value)’

   - ‘reselect(Value)’

   - ‘trigger(Value)’

   - ‘trigger_after_settle(Value)’

   - ‘trigger_after_swap(Value)’

HTMX response headers are only added for non-‘3xx’ responses.  When a
request is an HTMX request and the selected options would emit one or
more ‘HX-*’ response headers, attempting to combine those options with a
‘3xx’ response status raises an error instead of silently generating
headers that HTMX will ignore.  If you need a normal HTTP redirect, use
the standard response headers directly.

When an endpoint can return both a full-page reply and an HTMX fragment
for the same URL, set ‘vary_hx_request(true)’ so the helpers merge
‘Vary: HX-Request’ with any existing ‘Vary’ metadata.  Otherwise,
browser or intermediary caches can reuse the wrong representation.

History restore requests after an HTMX history-cache miss are expected
to return the full page.  The ‘page_fragment_reply/4-5’ helpers
therefore treat ‘HX-History-Restore-Request’ the same as ordinary or
boosted navigation.  If your application uses ‘HX-Request’ to select
between page and fragment representations, configure the client with
‘htmx.config.historyRestoreAsHxRequest’ set to ‘false’ so that history
restores do not also carry ‘HX-Request’.

Structured values for ‘location/1’ and the trigger options reuse the
repository JSON-term conventions through the shared HTTP JSON helpers,
with HTMX-specific validation of the top-level shape:

   - ‘location/1’ accepts either a URL atom or a JSON object with a
     required ‘path’ key and only the documented HTMX optional keys
     (‘source’, ‘event’, ‘handler’, ‘target’, ‘swap’, ‘values’,
     ‘headers’, ‘select’, ‘selectOOB’, ‘push’, and ‘replace’)

   - ‘trigger/1’, ‘trigger_after_settle/1’, and ‘trigger_after_swap/1’
     accept either a single event atom, a list of event atoms, or a JSON
     object whose top-level keys are event names

The router companion category expects HTMX response options to be
provided as ‘htmx_response_options(Options)’ request metadata or
response properties.


File: TheLogtalkHandbook-3.101.0.info,  Node: http_multipart,  Next: http_parameters,  Prev: http_htmx,  Up: Libraries

6.101 ‘http_multipart’
======================

This library provides a higher-level multipart helper layer on top of
the ‘http_core’ library.  It does not replace the low-level multipart
wire support already implemented in ‘http_core’; instead it wraps the
normalized multipart body and part terms, adds form-data field and file
helpers, and delegates raw parsing and generation to the existing
‘http_core’ predicates.

* Menu:

* API documentation: API documentation<120>.
* Loading: Loading<121>.
* Testing: Testing<113>.
* Current scope: Current scope<9>.
* Form-data descriptors::
* Normalized terms: Normalized terms<2>.
* Current workflow::
* Current limitations: Current limitations<6>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<120>,  Next: Loading<121>,  Up: http_multipart

6.101.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#http_multipart’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<121>,  Next: Testing<113>,  Prev: API documentation<120>,  Up: http_multipart

6.101.2 Loading
---------------

To load the library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(http_multipart(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<113>,  Next: Current scope<9>,  Prev: Loading<121>,  Up: http_multipart

6.101.3 Testing
---------------

To test this library, load the ‘tester.lgt’ file:

     | ?- logtalk_load(http_multipart(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Current scope<9>,  Next: Form-data descriptors,  Prev: Testing<113>,  Up: http_multipart

6.101.4 Current scope
---------------------

The current version provides:

   - ‘body/3’ for constructing validated normalized multipart body
     terms.

   - ‘part/4’ for constructing validated normalized multipart part
     terms.

   - ‘is_body/1’ and ‘is_part/1’ for testing normalized multipart body
     and part terms.

   - ‘media_type/2’ and ‘parts/2’ for inspecting multipart body terms.

   - ‘part_headers/2’, ‘part_body/2’, and ‘part_properties/2’ for
     inspecting multipart part terms.

   - ‘field/4’ and ‘fields/2’ for inspecting textual form-data field
     parts and multipart/form-data bodies.

   - ‘file/6’ and ‘files/2’ for inspecting form-data file parts and
     multipart/form-data bodies.

   - ‘field_part/4’ and ‘file_part/6’ for constructing outgoing
     form-data field and file parts.

   - ‘form_data_body/2’ for constructing a ‘multipart/form-data’ body
     from an ordered list of parameter-aware field and file descriptors.

   - ‘parse/4’ and ‘generate/3’ as multipart-specific wrappers around
     the existing ‘http_core::parse_body/4’ and
     ‘http_core::generate_body/3’ predicates.


File: TheLogtalkHandbook-3.101.0.info,  Node: Form-data descriptors,  Next: Normalized terms<2>,  Prev: Current scope<9>,  Up: http_multipart

6.101.5 Form-data descriptors
-----------------------------

The parameter-aware helper predicates use the following descriptor
shapes:

   - ‘field(Name, Value, Parameters)’

   - ‘file(Name, Filename, MediaType, Payload, Parameters)’

In both cases, ‘Parameters’ is an ordered list of extra
‘Content-Disposition: form-data’ parameters represented as ‘Name-Value’
pairs.  The reserved ‘name’ and ‘filename’ parameters remain explicit
helper arguments and must not be repeated in the ‘Parameters’ list.

Additional ‘Content-Disposition: form-data’ parameters are preserved as
ordered ‘Name-Value’ pairs.  Any special semantics for extended
parameters such as ‘filename*’ are intentionally left to callers.


File: TheLogtalkHandbook-3.101.0.info,  Node: Normalized terms<2>,  Next: Current workflow,  Prev: Form-data descriptors,  Up: http_multipart

6.101.6 Normalized terms
------------------------

Multipart bodies use the normalized ‘http_core’ body term:

     content(MediaType, multipart(Parts))

Multipart parts use the recursive normalized term:

     part(Headers, Body, Properties)


File: TheLogtalkHandbook-3.101.0.info,  Node: Current workflow,  Next: Current limitations<6>,  Prev: Normalized terms<2>,  Up: http_multipart

6.101.7 Current workflow
------------------------

   - Use ‘form_data_body/2’ when you want to assemble a normalized
     ‘multipart/form-data’ body explicitly.

   - Use the ‘field/4’, ‘fields/2’, ‘file/6’, and ‘files/2’ predicates
     when you want to inspect multipart form-data bodies after parsing.

   - The ‘http_client’ library can send common form-data requests
     directly from a ‘form_data(Items)’ descriptor.

   - The ‘http_server_core’ library keeps multipart request bodies in
     the normalized form expected by this library, so handlers can
     inspect incoming multipart requests without reparsing them.


File: TheLogtalkHandbook-3.101.0.info,  Node: Current limitations<6>,  Prev: Current workflow,  Up: http_multipart

6.101.8 Current limitations
---------------------------

   - The library is entirely in-memory.

   - Textual field helpers target simple text field payloads.  If a part
     has a non-text body or a more specialized encoding, callers should
     use the generic part accessors instead.

   - Multipart wire parsing and generation require a boundary parameter
     in the effective ‘Content-Type’ metadata or an explicit
     ‘boundary/1’ option, exactly as in the underlying ‘http_core’
     library.

   - The library does not provide streaming sinks, temp-file policies,
     or large-upload orchestration.


File: TheLogtalkHandbook-3.101.0.info,  Node: http_parameters,  Next: http_router,  Prev: http_multipart,  Up: Libraries

6.102 ‘http_parameters’
=======================

The ‘http_parameters’ library provides typed query, form, path, header,
and cookie parameter extraction helpers for normalized HTTP requests
together with an optional router companion category that reuses the same
declarations for OpenAPI metadata generation.

Currently this library provides:

   - object ‘http_parameters’

   - category ‘http_router_parameters’

* Menu:

* API documentation: API documentation<121>.
* Loading: Loading<122>.
* Testing: Testing<114>.
* Declarations::
* Error handling: Error handling<3>.
* Router integration: Router integration<2>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<121>,  Next: Loading<122>,  Up: http_parameters

6.102.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#http_parameters’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<122>,  Next: Testing<114>,  Prev: API documentation<121>,  Up: http_parameters

6.102.2 Loading
---------------

To load the library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(http_parameters(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<114>,  Next: Declarations,  Prev: Loading<122>,  Up: http_parameters

6.102.3 Testing
---------------

To test this library, load the ‘tester.lgt’ file:

     | ?- logtalk_load(http_parameters(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Declarations,  Next: Error handling<3>,  Prev: Testing<114>,  Up: http_parameters

6.102.4 Declarations
--------------------

Parameter declarations use the shape:

     parameter(Name, Source, Type, Options)

The currently supported source atoms are:

   - ‘query’

   - ‘form’

   - ‘path’

   - ‘header’

   - ‘cookie’

Header declarations match normalized request headers case-insensitively.
Cookie declarations read from the normalized ‘cookies(Pairs)’ request
property already exposed by the ‘http_core’ library.  Reserved OpenAPI
header names such as ‘accept’, ‘content_type’, and ‘authorization’
remain available for runtime extraction but are omitted from generated
OpenAPI parameter descriptors.

The currently supported scalar types are:

   - ‘string’

   - ‘text’

   - ‘atom’

   - ‘integer’

   - ‘number’

   - ‘boolean’

List-valued declarations use ‘list(ScalarType)’.

The currently supported options are:

   - ‘optional’

   - ‘default(Value)’

   - ‘description(Description)’

   - ‘schema(Schema)’

   - ‘enum(Values)’

   - ‘minimum(Value)’

   - ‘maximum(Value)’

   - ‘pattern(Pattern)’

The ‘enum/1’, ‘minimum/1’, and ‘maximum/1’ options are enforced at
runtime after type coercion.  For list-valued declarations they apply to
each extracted item.  Defaults are also checked against these
constraints when declarations are normalized.

The ‘minimum/1’ and ‘maximum/1’ options are only valid for ‘integer’ and
‘number’ declarations.  The ‘pattern/1’ option is only valid for
‘string’, ‘text’, and ‘atom’ declarations and is currently used only to
enrich the generated OpenAPI schema; it is not enforced at runtime.

Duplicate declaration pairs with the same ‘(Name, Source)’ are rejected.

Path declarations must remain scalar and cannot use ‘default/1’.  When
the library is used through ‘http_router_parameters’, any declared
‘path’ parameter must match a placeholder in the route path template.
Typed route placeholders remain authoritative for runtime type
compatibility:

   - ‘{name:integer}’ requires a declared runtime type of ‘integer’

   - ‘{name:number}’ requires a declared runtime type of ‘number’

   - ‘{name}’ allows declared runtime types ‘string’, ‘text’, or ‘atom’

Descriptions and custom ‘schema/1’ values can still refine the generated
OpenAPI descriptor for a matching path parameter, but they cannot rename
the placeholder or change its runtime type.


File: TheLogtalkHandbook-3.101.0.info,  Node: Error handling<3>,  Next: Router integration<2>,  Prev: Declarations,  Up: http_parameters

6.102.5 Error handling
----------------------

Client-input validation failures throw exceptions using the shape:

     error(http_parameter_validation(Errors), Context)

The ‘Errors’ list currently contains these structured terms:

   - ‘missing_parameter(Source, Name)’

   - ‘duplicate_parameter(Source, Name)’

   - ‘invalid_parameter_value(Source, Name, Value, Reason)’

The ‘Reason’ term is currently one of:

   - ‘expected(Type)’

   - ‘incompatible_type(Type)’

   - ‘not_in_enum(Values)’

   - ‘below_minimum(Minimum)’

   - ‘above_maximum(Maximum)’

   - ‘invalid_list_item(Index, ItemReason)’

Even though the public API currently fails fast, the list-shaped
contract keeps error detection and reporting decoupled and leaves room
for future accumulated validation without changing router integration.


File: TheLogtalkHandbook-3.101.0.info,  Node: Router integration<2>,  Prev: Error handling<3>,  Up: http_parameters

6.102.6 Router integration
--------------------------

The ‘http_router_parameters’ category extends ‘http_router’ and adds:

   - ‘route_parameters/2’

   - ‘route_parameter_declarations/2’

   - ‘route_parameter_request_body_description/2’

   - ‘route_parameter_extra_metadata/2’

The category generates OpenAPI parameter descriptors for ‘query’,
‘path’, ‘header’, and ‘cookie’ declarations,
‘application/x-www-form-urlencoded’ request bodies for ‘form’
declarations, and a default ‘400 Bad Request’ response descriptor.  When
a declaration uses ‘enum/1’, ‘minimum/1’, ‘maximum/1’, or ‘pattern/1’,
the generated parameter or form-property schema reflects those
constraints when the schema is generated by the library.

When ‘route_parameter_extra_metadata/2’ also defines ‘responses/1’, an
explicit ‘response(400, ...)’ replaces the generated validation
response.  A ‘response(default, ...)’ remains additive and does not
suppress the generated ‘400 Bad Request’ descriptor.


File: TheLogtalkHandbook-3.101.0.info,  Node: http_router,  Next: http_server,  Prev: http_parameters,  Up: Libraries

6.103 ‘http_router’
===================

The ‘http_router’ library provides the first declarative routing layer
on top of the ‘http_core’ library.  It is implemented as a category so
that router objects can import it and implement the
‘http_handler_protocol’ protocol directly while reusing common method
dispatch and path-template matching logic.

* Menu:

* API documentation: API documentation<122>.
* Loading: Loading<123>.
* Testing: Testing<115>.
* Layering: Layering<2>.
* Current scope: Current scope<10>.
* Route declarations::
* Path templates::
* Request annotations::
* Route metadata::
* Route authorization::
* Content negotiation::
* Middleware chaining::
* Response middleware::
* HEAD fallback::
* OPTIONS handling::
* Custom bad-request responses::
* Custom error responses::
* Custom negotiation failures::
* OpenAPI derivation::
* Current limitations: Current limitations<7>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<122>,  Next: Loading<123>,  Up: http_router

6.103.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#http_router’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<123>,  Next: Testing<115>,  Prev: API documentation<122>,  Up: http_router

6.103.2 Loading
---------------

To load the library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(http_router(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<115>,  Next: Layering<2>,  Prev: Loading<123>,  Up: http_router

6.103.3 Testing
---------------

To test this library, load the ‘tester.lgt’ file:

     | ?- logtalk_load(http_router(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Layering<2>,  Next: Current scope<10>,  Prev: Testing<115>,  Up: http_router

6.103.4 Layering
----------------

‘http_router’ sits between the normalized ‘http_core’ message layer and
higher-level API authoring helpers:

   - Use ‘http_server’ directly when you only need normalized messages,
     parsers, generators, or low-level handlers.

   - Use ‘http_router’ when you want the handler object to keep exposing
     ‘handle/2’ while route matching, metadata annotation, middleware,
     and content negotiation are derived from ‘route/4’ declarations.

   - Add ‘rest’ when ‘route/4’ is still too low-level and you prefer
     endpoint descriptors plus small normalized result terms.

   - Pair router objects with ‘open_api’ when you want the route
     declarations and metadata to derive OpenAPI operations
     automatically.

   - Add companion libraries such as ‘http_parameters’, ‘http_cors’,
     ‘http_htmx’, ‘http_session’, ‘http_static_files’, and
     ‘http_directory_listing’ when you need parameter extraction,
     middleware helpers, sessions, or static-file routing on the same
     dispatch layer.


File: TheLogtalkHandbook-3.101.0.info,  Node: Current scope<10>,  Next: Route declarations,  Prev: Layering<2>,  Up: http_router

6.103.5 Current scope
---------------------

The initial routing solution provides one public predicate through the
imported category:

   - ‘handle/2’ routes a normalized request using ‘route/4’ clauses
     defined by the importing object.

The remaining router behavior is organized in the sections below.


File: TheLogtalkHandbook-3.101.0.info,  Node: Route declarations,  Next: Path templates,  Prev: Current scope<10>,  Up: http_router

6.103.6 Route declarations
--------------------------

Importing router objects must define route descriptors using:

   - ‘route(Id, Method, PathTemplate, Handler)’

The ‘Method’ argument is a normalized lowercase HTTP method atom
accepted by ‘http_core’, including ‘query’ for RFC 10008 QUERY routes.
The ‘Handler’ argument is the name of a declared local predicate with
arity 2, typically a protected predicate.

When automatic ‘OPTIONS’ or ‘405 Method Not Allowed’ responses are
generated, QUERY routes are included in the ‘Allow’ header like other
route methods.


File: TheLogtalkHandbook-3.101.0.info,  Node: Path templates,  Next: Request annotations,  Prev: Route declarations,  Up: http_router

6.103.7 Path templates
----------------------

Path-template atoms support literal segments, anonymous ‘*’ wildcard
segments, plain ‘{name}’ placeholders, and typed placeholders such as
‘{id:integer}’ and ‘{score:number}’.  Example:

     route(show_user, get, '/users/{id}', show_user).


File: TheLogtalkHandbook-3.101.0.info,  Node: Request annotations,  Next: Route metadata,  Prev: Path templates,  Up: http_router

6.103.8 Request annotations
---------------------------

The router category calls the matched handler after annotating the
request with ‘route(Id)’, ‘path_params(Pairs)’, and any
‘route_metadata/2’ properties.  When ‘route_produces/2’ is defined and
the request ‘Accept’ header can be satisfied, it also adds the
negotiated ‘response_media_type(MediaType)’ property.  On the normal
routing path it scrubs stale internal synthetic properties such as
‘open_api_probe/1’, ‘automatic_options/1’, ‘effective_methods/1’, and
‘response_media_type/1’ before handler execution.


File: TheLogtalkHandbook-3.101.0.info,  Node: Route metadata,  Next: Route authorization,  Prev: Request annotations,  Up: http_router

6.103.9 Route metadata
----------------------

Importing router objects can optionally declare additional
route-specific metadata using:

   - ‘route_metadata(Id, Metadata)’

When defined, ‘Metadata’ must be a list of compound terms.  The router
removes any existing request properties with the same functors, prepends
the metadata to the matched request, and then adds the standard
‘route/1’ and ‘path_params/1’ annotations.  This keeps route metadata
available to both route handlers and response middleware and allows
metadata descriptors such as ‘summary/1’, ‘description/1’, ‘tags/1’, or
other application-specific terms.


File: TheLogtalkHandbook-3.101.0.info,  Node: Route authorization,  Next: Content negotiation,  Prev: Route metadata,  Up: http_router

6.103.10 Route authorization
----------------------------

Importing router objects can optionally authorize or decorate routed
requests after route matching and metadata annotation but before route
handler dispatch using:

   - ‘authorize_routed_request(Request, Action)’

The hook must return either ‘continue(Request)’ or ‘respond(Response)’.
Short-circuited responses still flow through response middleware and
keep the routed request annotations such as ‘route/1’, ‘path_params/1’,
and any route metadata properties.  This hook is the main place to
validate or decorate a routed request after route matching and metadata
annotation but before the route handler is dispatched.


File: TheLogtalkHandbook-3.101.0.info,  Node: Content negotiation,  Next: Middleware chaining,  Prev: Route authorization,  Up: http_router

6.103.11 Content negotiation
----------------------------

Importing router objects can optionally declare route response media
types using:

   - ‘route_produces(Id, MediaTypes)’

When defined, ‘MediaTypes’ must be a non-empty list of media type atoms.
The router negotiates the request ‘Accept’ header against that list,
annotates the matched request with ‘response_media_type(MediaType)’, and
returns a generic ‘406 Not Acceptable’ response when no produced media
type matches.

On the normal routing path, any stale incoming ‘response_media_type/1’
annotation is scrubbed before route dispatch and replaced only when the
matched route successfully negotiates one of its declared
‘route_produces/2’ media types.


File: TheLogtalkHandbook-3.101.0.info,  Node: Middleware chaining,  Next: Response middleware,  Prev: Content negotiation,  Up: http_router

6.103.12 Middleware chaining
----------------------------

Importing router objects can also optionally define ordered middleware
descriptors using:

   - ‘middleware(Id, Handler)’

The ‘Handler’ argument is the name of a declared local predicate with
arity 2 that receives the current request and returns either
‘continue(Request)’ or ‘respond(Response)’.  Middleware runs before
route matching, so it can rewrite requests before dispatch or
short-circuit processing with an immediate response.  Ordered middleware
descriptors are evaluated in declaration order.


File: TheLogtalkHandbook-3.101.0.info,  Node: Response middleware,  Next: HEAD fallback,  Prev: Middleware chaining,  Up: http_router

6.103.13 Response middleware
----------------------------

Importing router objects can also optionally define ordered response
middleware descriptors using:

   - ‘response_middleware(Id, Handler)’

The ‘Handler’ argument is the name of a declared local predicate with
arity 3 that receives the current request, the current response, and
returns the transformed response.  Response middleware runs after route
dispatch or short-circuit processing, so it can decorate or rewrite any
generated response.  It is the final place where a response can be
adjusted before it is returned to the caller.


File: TheLogtalkHandbook-3.101.0.info,  Node: HEAD fallback,  Next: OPTIONS handling,  Prev: Response middleware,  Up: http_router

6.103.14 HEAD fallback
----------------------

‘HEAD’ requests match exact ‘head’ routes first and otherwise fall back
to a matching ‘get’ route.


File: TheLogtalkHandbook-3.101.0.info,  Node: OPTIONS handling,  Next: Custom bad-request responses,  Prev: HEAD fallback,  Up: http_router

6.103.15 OPTIONS handling
-------------------------

‘OPTIONS’ requests match explicit ‘options’ routes first.  When no
explicit ‘options’ route exists for a matched path, the router returns
an automatic ‘200 OK’ response with the derived ‘Allow’ header and an
empty body.  The synthetic request used for this path is annotated with
‘automatic_options(true)’ and ‘effective_methods(Methods)’.  When the
router can identify exactly one matching non-‘options’ route template,
it also annotates that synthetic request with ‘route(Id)’,
‘path_params(Pairs)’, and that route ‘route_metadata/2’ properties
before response middleware runs.  When multiple non-‘options’ routes
match the same path, the synthetic request omits ‘route/1’, keeps
‘path_params/1’ only when all matches produce the same value, and
preserves only metadata properties that are identical across all matched
routes.  Automatic ‘OPTIONS’ can be customized using
‘route_automatic_options_response/3’ and still flows through response
middleware.


File: TheLogtalkHandbook-3.101.0.info,  Node: Custom bad-request responses,  Next: Custom error responses,  Prev: OPTIONS handling,  Up: http_router

6.103.16 Custom bad-request responses
-------------------------------------

Importing router objects can optionally define:

   - ‘route_bad_request_response(Request, Errors, Response)’

Dedicated route-handler exceptions matching
‘error(http_parameter_validation(Errors), Context)’ with a non-empty
‘Errors’ list are translated into ‘400 Bad Request’ responses before
response middleware runs.  The router uses the optional
‘route_bad_request_response/3’ hook when it is defined and otherwise
falls back to a default plain-text response.  The routed request
annotations remain available to the hook and to any later response
middleware.


File: TheLogtalkHandbook-3.101.0.info,  Node: Custom error responses,  Next: Custom negotiation failures,  Prev: Custom bad-request responses,  Up: http_router

6.103.17 Custom error responses
-------------------------------

Importing router objects can optionally customize other routing errors
by defining:

   - ‘route_not_found_response(Request, Response)’

   - ‘route_method_not_allowed_response(Request, AllowedMethods,
     Response)’

When a path matches but the request method does not, the router returns
a ‘405 Method Not Allowed’ response with an ‘Allow’ header derived from
the matching route descriptors.  A ‘get’ route implicitly contributes
both ‘GET’ and ‘HEAD’ to that header.  Automatic router support for
‘OPTIONS’ also contributes ‘OPTIONS’ to the header for matched paths.

The ‘AllowedMethods’ argument passed to the ‘405’ hook is the effective
method list as lowercase atoms and already includes implicit ‘head’
support for ‘get’ routes and automatic ‘options’ support.  The ‘Request’
passed to the ‘405’ hook and to response middleware is annotated with
‘matched_path(true)’ and ‘effective_methods(AllowedMethods)’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Custom negotiation failures,  Next: OpenAPI derivation,  Prev: Custom error responses,  Up: http_router

6.103.18 Custom negotiation failures
------------------------------------

Importing router objects can optionally define:

   - ‘route_not_acceptable_response(Request, ProducedMediaTypes,
     Response)’

The ‘ProducedMediaTypes’ argument passed to the ‘406’ hook is the
normalized list declared by ‘route_produces/2’ for the matched route.


File: TheLogtalkHandbook-3.101.0.info,  Node: OpenAPI derivation,  Next: Current limitations<7>,  Prev: Custom negotiation failures,  Up: http_router

6.103.19 OpenAPI derivation
---------------------------

When a router object also implements the ‘open_api_provider_protocol’
protocol, the imported category can automatically derive ‘operations/1’
from ‘route/4’, ‘route_metadata/2’, and ‘route_produces/2’.  Recognized
route-metadata terms for OpenAPI derivation are:

   - ‘summary(Summary)’

   - ‘description(Description)’

   - ‘tags(Tags)’

   - ‘deprecated(Boolean)’

   - ‘security(Requirements)’

   - ‘parameters(Parameters)’

   - ‘request_body(RequestBody)’

   - ‘responses(Responses)’

Path-template placeholders automatically derive default OpenAPI path
parameter descriptors using a string schema.  Metadata ‘parameters/1’
can override those defaults or add extra query, header, or cookie
parameters.  When ‘responses/1’ is not provided, the router first
attempts to infer a successful response by probing the route handler
with a synthetic annotated request and then falls back to a default
successful response.  When available, ‘route_produces/2’ guides both
response probing and the derived OpenAPI media types.

When ‘request_body/1’ metadata is not provided, the router also attempts
to infer a request body descriptor by probing the route handler with a
synthetic annotated request whose body is left open for the handler to
constrain.  The inferred request and response schemas are emitted inline
and are derived from the observed payload terms:

   - ‘json/1’ payloads infer JSON Schema types recursively from the
     observed JSON values.

   - ‘text/1’ and ‘binary/1’ payloads infer a string schema.

   - ‘form/1’ payloads infer an object schema from the observed
     key-value pairs.

Explicit ‘request_body/1’ or ‘responses/1’ metadata always takes
precedence over inferred descriptors.

The imported category also exposes top-level OpenAPI provider
predicates.  The default ‘api_info/1’ descriptor is derived from the
importing object identifier, ‘servers/1’ defaults to ‘[]’, and importing
objects can override or extend the provider surface with these hooks:

   - ‘open_api_info(Info)’

   - ‘open_api_servers(Servers)’

   - ‘open_api_security(Security)’

   - ‘open_api_schema(Name, Schema)’

   - ‘open_api_security_scheme(Name, SecurityScheme)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Current limitations<7>,  Prev: OpenAPI derivation,  Up: http_router

6.103.20 Current limitations
----------------------------

   - OpenAPI inference is best-effort.  Even with the optional
     ‘route_open_api_request_body_example/2’ and
     ‘route_open_api_response_example/2’ hooks, explicit metadata
     remains the right choice for reusable component schemas and for
     routes whose contracts should be stated directly instead of
     inferred.


File: TheLogtalkHandbook-3.101.0.info,  Node: http_server,  Next: http_server_core,  Prev: http_router,  Up: Libraries

6.104 ‘http_server’
===================

The ‘http_server’ library provides the user-facing facade for starting
and stopping HTTP and HTTPS servers.  It selects a default transport
from the ‘scheme/1’ option while still allowing explicit transport
selection when an application needs lower-level control.

By default, ‘scheme(http)’ uses ‘http_socket_transport’ and
‘scheme(https)’ uses ‘http_process_transport’ (selecting a TLS
listener).  Incompatible scheme, transport, and listener transport
combinations are rejected with a ‘consistency_error/3’ exception.

* Menu:

* API documentation: API documentation<123>.
* Loading: Loading<124>.
* Testing: Testing<116>.
* Bounded serving::
* Open-ended serving::
* HTTPS::
* Handling server requests::
* Options: Options<27>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<123>,  Next: Loading<124>,  Up: http_server

6.104.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#http_server’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<124>,  Next: Testing<116>,  Prev: API documentation<123>,  Up: http_server

6.104.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(http_server(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<116>,  Next: Bounded serving,  Prev: Loading<124>,  Up: http_server

6.104.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(http_server(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Bounded serving,  Next: Open-ended serving,  Prev: Testing<116>,  Up: http_server

6.104.4 Bounded serving
-----------------------

To serve a given number of connections, use the ‘serve/4’ predicate.
For example:

     | ?- http_server::serve(8080, my_handler, 10, [scheme(http)]).

To inspect or reuse a listener, open it explicitly and close it after
serving:

     | ?- http_server::open('127.0.0.1', Port, Server, []),
          http_server::serve(Server, my_handler, 1, ClientInfos),
          http_server::close(Server).


File: TheLogtalkHandbook-3.101.0.info,  Node: Open-ended serving,  Next: HTTPS,  Prev: Bounded serving,  Up: http_server

6.104.5 Open-ended serving
--------------------------

To serve any number of connections until shutdown, use the
‘serve_until_shutdown/5’ predicate.  For example:

     | ?- http_server::serve_until_shutdown('127.0.0.1', 8080, my_handler, control, []).
     ...

     | ?- http_server::request_shutdown(control).
     ...

When the Prolog backend supports threads, you can also use the
‘start/4-5’ and ‘stop/1’ predicates.  For example:

     | ?- http_server::start(8080, my_handler, Server, []),
          http_server::stop(Server).


File: TheLogtalkHandbook-3.101.0.info,  Node: HTTPS,  Next: Handling server requests,  Prev: Open-ended serving,  Up: http_server

6.104.6 HTTPS
-------------

For HTTPS, the server must have TLS credentials.  The facade selects
‘http_process_transport’ and a TLS listener when ‘scheme(https)’ is
used, but the transport still needs either explicit certificate and key
files or a request to create temporary credentials.

Use ‘tls_certificate_file/1’ and ‘tls_key_file/1’ for real deployments:

     | ?- http_server::serve(
             '127.0.0.1', 8443, my_handler, 10, _ClientInfos,
             [
                 scheme(https),
                 tls_certificate_file('/path/to/cert.pem'),
                 tls_key_file('/path/to/key.pem')
             ]
          ).

Use ‘temporary_tls_credentials/1’ for local examples and tests.  Its
argument is a file name prefix used for temporary certificate and key
files.  The temporary files are created by the process transport and
removed when the listener is closed:

     | ?- http_server::serve(
             '127.0.0.1', 8443, my_handler, 10, _ClientInfos,
             [scheme(https), temporary_tls_credentials('logtalk_http_server_')]
          ).

If ‘scheme(https)’ is used without either ‘temporary_tls_credentials/1’
or both ‘tls_certificate_file/1’ and ‘tls_key_file/1’, the process
transport rejects the listener options.


File: TheLogtalkHandbook-3.101.0.info,  Node: Handling server requests,  Next: Options<27>,  Prev: HTTPS,  Up: http_server

6.104.7 Handling server requests
--------------------------------

The handler argument in the examples above, ‘my_handler’, is the object
that implements ‘http_handler_protocol’ and receives each accepted HTTP
request, building the corresponding HTTP response.

For ordinary HTTP requests, the handler is expected to provide a
‘handle/2’ predicate compatible with the ‘http_server_core’
request/response pipeline.  For example, a minimal handler can
pattern-match the request and return a plain text response:

     :- object(my_handler,
         implements(http_handler_protocol)).

         :- uses(http_core, [
             response/6
         ]).

         handle(Request, Response) :-
             Request = request(_Method, _Target, Version, _Headers, _Body, _Properties),
             response(
                 Version, status(200, 'OK'), [],
                 content('text/plain', text('Hello!')), [], Response
             ).

     :- end_object.

When a server accepts a connection, the selected transport reads the
request, calls ‘my_handler::handle(Request, Response)’, writes the
response back to the client, and then follows the selected serving
policy.  Parametric objects can be used when the handler needs
configuration, e.g.  ‘static_site_handler(Root)’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<27>,  Prev: Handling server requests,  Up: http_server

6.104.8 Options
---------------

The predicates that open or start a listener accept the following facade
options:

   - ‘scheme(Scheme)’ controls the URL scheme served by the listener.
     Valid values: ‘http’ or ‘https’.  Default: ‘http’.

   - ‘transport(Transport)’ selects the transport object.  Valid values:
     ‘default’ or an object implementing ‘http_transport_protocol’.
     Default: ‘default’, which resolves to ‘http_socket_transport’ for
     ‘scheme(http)’ and to ‘http_process_transport’ for ‘scheme(https)’.

   - ‘listener_options(Options)’ passes additional listener options
     directly to the selected transport.  Default: ‘[]’.

   - ‘serve_options(Options)’ passes additional serving options directly
     to the selected transport.  Default: ‘[]’.

   - ‘control(Control)’ names the shutdown control used by ‘start/4-5’
     and open-ended serving.  Valid values: any non-variable term, or
     ‘default’ to create a fresh internal control term.  Default:
     ‘default’.

For convenience, selected listener and serving options can also be
written directly in the facade option list instead of wrapping them in
‘listener_options/1’ or ‘serve_options/1’:

   - Listener options: ‘backlog/1’, ‘type/1’, ‘listener_transport/1’,
     ‘listener_helper_executable/1’, ‘temporary_tls_credentials/1’,
     ‘tls_certificate_file/1’, and ‘tls_key_file/1’.

   - Serving options: ‘workers/1’ and ‘shutdown/1’.

The direct listener options accepted by the facade have the following
values: ‘backlog/1’ takes a positive integer, ‘type/1’ takes ‘binary’ or
‘text’, ‘listener_transport/1’ takes ‘tcp’ or ‘tls’,
‘listener_helper_executable/1’ takes ‘ncat’ or ‘socat’, and the TLS
credential options take file names or a temporary file name prefix as
atoms.

The direct serving options accepted by the facade are ‘workers(serial)’,
‘workers(per_connection)’, ‘workers(pool(Size))’, ‘workers(pool(Size,
rolling))’, ‘shutdown(keep_open)’, and ‘shutdown(close)’.

These direct options are pass-through options.  They are checked by the
facade for basic shape, but the selected transport still decides whether
a particular option is supported and what its transport-specific default
is.  For example, ‘listener_transport(tls)’,
‘listener_helper_executable/1’, and the TLS credential options are
options for the process transport.  With ‘scheme(https)’, the facade
adds ‘listener_transport(tls)’ automatically unless another listener
transport is explicitly specified.

When the process transport is selected, these listener defaults apply:
‘backlog(5)’, ‘type(binary)’, ‘listener_transport(tcp)’, and
‘listener_helper_executable(ncat)’.  The facade changes the effective
listener transport to ‘tls’ for ‘scheme(https)’.  The TLS credential
options have no default usable certificate:
‘temporary_tls_credentials/1’ must be requested explicitly, or both
‘tls_certificate_file/1’ and ‘tls_key_file/1’ must be provided when
opening a TLS listener.

Common serving defaults are inherited from the transports:
‘workers(serial)’ and ‘shutdown(keep_open)’.  The convenience predicates
that open and close a listener around a bounded request loop add
‘shutdown(close)’ while serving.


File: TheLogtalkHandbook-3.101.0.info,  Node: http_server_core,  Next: http_session,  Prev: http_server,  Up: Libraries

6.105 ‘http_server_core’
========================

The ‘http_server_core’ library provides a portable stream-oriented
server layer on top of the ‘http_core’ library.  It is designed for the
first orchestration step above the wire parser and generator: read
exactly one request from an existing binary stream, dispatch it to a
handler object implementing the ‘http_handler_protocol’ protocol, and
write exactly one response.

All stream predicates expect binary input and output streams.

This library can be used with backend Prolog systems that support
unbound integer arithmetic and the ‘sockets’ library: ECLiPSe, SICStus
Prolog, SWI-Prolog, Trealla Prolog, and XVM.

* Menu:

* API documentation: API documentation<124>.
* Loading: Loading<125>.
* Testing: Testing<117>.
* Usage examples: Usage examples<2>.
* Current scope: Current scope<11>.
* Framing rules: Framing rules<2>.
* Multipart workflow: Multipart workflow<2>.
* WebSocket handshake workflow::
* Current limitations: Current limitations<8>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<124>,  Next: Loading<125>,  Up: http_server_core

6.105.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#http_server_core’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<125>,  Next: Testing<117>,  Prev: API documentation<124>,  Up: http_server_core

6.105.2 Loading
---------------

To load the library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(http_server_core(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<117>,  Next: Usage examples<2>,  Prev: Loading<125>,  Up: http_server_core

6.105.3 Testing
---------------

To test this library, load the ‘tester.lgt’ file:

     | ?- logtalk_load(http_server_core(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage examples<2>,  Next: Current scope<11>,  Prev: Testing<117>,  Up: http_server_core

6.105.4 Usage examples
----------------------

The examples below use in-memory streams or local files so they can be
reproduced directly.

Define a simple handler object once:

     :- object(notes_http_server_core_echo_handler,
         implements(http_handler_protocol)).

         handle(Request, Response) :-
             http_core::version(Request, Version),
             http_core::body(Request, Body),
             http_core::response(Version, status(200, 'OK'), [], Body, [], Response).

     :- end_object.

To serve a single request from existing binary streams:

     | ?- Request = 'POST /echo HTTP/1.1\r\nhost: example.com\r\ncontent-type: text/plain\r\ncontent-length: 5\r\n\r\nhello',
          atom_codes(Request, RequestBytes),
          open('request.tmp', write, RequestStream, [type(binary)]),
          forall(member(RequestByte, RequestBytes), put_byte(RequestStream, RequestByte)),
          close(RequestStream),
          open('request.tmp', read, Input, [type(binary)]),
          open('response.tmp', write, Output, [type(binary)]),
          http_server_core::serve(Input, Output, notes_http_server_core_echo_handler),
          close(Input),
          close(Output),
          http_core::parse_response(file('response.tmp'), Response).

     Response = response(http(1,1), status(200, 'OK'), _, content('text/plain', text(hello)), _).

To keep serving requests on the same stream pair until persistence rules
say to stop, write several requests into the same input stream and call
‘serve_connection/3’ once:

     | ?- Requests = 'POST /echo HTTP/1.1\r\nhost: example.com\r\ncontent-type: text/plain\r\ncontent-length: 3\r\n\r\nonePOST /echo HTTP/1.1\r\nhost: example.com\r\ncontent-type: text/plain\r\ncontent-length: 3\r\n\r\ntwo',
          atom_codes(Requests, RequestBytes),
          open('requests.tmp', write, RequestStream, [type(binary)]),
          forall(member(RequestByte, RequestBytes), put_byte(RequestStream, RequestByte)),
          close(RequestStream),
          open('requests.tmp', read, Input, [type(binary)]),
          open('responses.tmp', write, Output, [type(binary)]),
          http_server_core::serve_connection(Input, Output, notes_http_server_core_echo_handler),
          close(Input),
          close(Output).

The generated ‘responses.tmp’ file contains two consecutive normalized
HTTP responses, one for ‘one’ and one for ‘two’.

For multipart request inspection, define a handler that uses
‘http_multipart’ on the normalized request body:

     :- object(notes_http_server_core_multipart_handler,
         implements(http_handler_protocol)).

         handle(Request, Response) :-
             http_core::version(Request, Version),
             http_core::body(Request, Body),
             http_multipart::fields(Body, [field(title, Title, _FieldParameters)]),
             http_multipart::files(Body, [file(upload, Filename, 'text/plain', text(hello), _FileParameters)]),
             atomic_list_concat(['title=', Title, '; upload=', Filename], Text),
             http_core::response(Version, status(200, 'OK'), [], content('text/plain', text(Text)), [], Response).

     :- end_object.

That handler can be used unchanged with ‘serve/3’ or
‘serve_connection/3’ because this library exposes multipart requests in
the same normalized form produced by ‘http_core::parse_request/2’.

The multipart helper predicates used by handlers return the
parameter-aware ‘field(Name, Value, Parameters)’ and ‘file(Name,
Filename, MediaType, Payload, Parameters)’ descriptors defined by the
‘http_multipart’ library.

In both descriptor shapes, ‘Parameters’ is the ordered list of extra
‘Content-Disposition: form-data’ parameters.  The reserved ‘name’ and
‘filename’ parameters stay explicit helper arguments and are not
repeated in that list.

For a WebSocket opening handshake, define a handler that delegates to
‘accept_websocket/3’:

     :- object(notes_http_server_core_websocket_handler,
         implements(http_handler_protocol)).

         handle(Request, Response) :-
             http_server_core::accept_websocket(Request, Response, [protocol(chat)]).

     :- end_object.

     | ?- Request = 'GET /socket HTTP/1.1\r\nhost: example.com\r\nconnection: Upgrade\r\nupgrade: websocket\r\nsec-websocket-key: dGhlIHNhbXBsZSBub25jZQ==\r\nsec-websocket-version: 13\r\nsec-websocket-protocol: chat\r\n\r\n',
          atom_codes(Request, RequestBytes),
          open('ws_request.tmp', write, RequestStream, [type(binary)]),
          forall(member(RequestByte, RequestBytes), put_byte(RequestStream, RequestByte)),
          close(RequestStream),
          open('ws_request.tmp', read, Input, [type(binary)]),
          open('ws_response.tmp', write, Output, [type(binary)]),
          http_server_core::serve_websocket(Input, Output, notes_http_server_core_websocket_handler, Outcome),
          close(Input),
          close(Output).

     Outcome = accepted(RequestTerm, Response),
     Response = response(http(1,1), status(101, 'Switching Protocols'), _, empty, _).

After ‘serve_websocket/4’ succeeds, higher layers must take ownership of
the underlying upgraded connection or streams.  This library stops at
the WebSocket HTTP opening handshake, independently of whether those
streams are plain or TLS-protected.


File: TheLogtalkHandbook-3.101.0.info,  Node: Current scope<11>,  Next: Framing rules<2>,  Prev: Usage examples<2>,  Up: http_server_core

6.105.5 Current scope
---------------------

The current implementation provides per-message primitives, a connection
loop, and WebSocket handshake helpers:

   - ‘read_request/2’ reads exactly one request from a binary stream
     without requiring end-of-file.

   - ‘write_response/2’ writes exactly one normalized response to a
     binary stream.

   - ‘write_response/2’ streams file-backed response bodies directly
     after writing the generated header block when the response does not
     use chunked transfer coding.

   - ‘dispatch/3’ calls a handler object and normalizes handler failures
     into ‘500 Internal Server Error’ responses.

   - ‘accept_websocket/3’ validates a normalized WebSocket
     opening-handshake request and builds the corresponding ‘101
     Switching Protocols’ response, including ‘Sec-WebSocket-Accept’ and
     optional subprotocol selection.

   - ‘serve_websocket/4’ reads one request, dispatches one response,
     writes it to the output stream, and reports whether the exchange
     completed with a valid WebSocket opening-handshake response.

   - ‘serve/3’ connects request reading, handler dispatch, and response
     writing, returning ‘400 Bad Request’ for malformed input.

   - ‘serve_connection/3’ repeatedly serves requests on the same stream
     pair using HTTP persistence rules and stops on end-of-file or
     ‘Connection: close’ semantics.

   - ‘serve/3’ and ‘serve_connection/3’ send the generated response
     headers for ‘HEAD’ requests but suppress the response body bytes,
     including for file-backed responses.

Because incoming request bodies are normalized by the ‘http_core’
library, handler objects can inspect ‘multipart/form-data’ requests
directly using the ‘http_multipart’ predicates after reading or serving
a request.

QUERY requests are read and dispatched like any other normalized
request.  A resource handler that implements RFC 10008 QUERY semantics
remains responsible for rejecting missing or unsupported query content
metadata, such as absent or unsupported ‘Content-Type’, with the
appropriate 4xx response.

This layer intentionally stays transport-neutral.  It does not accept
sockets, listen for connections, or manage concurrency.  Those concerns
belong to higher layers or backend-specific integration built on top of
this stream contract.


File: TheLogtalkHandbook-3.101.0.info,  Node: Framing rules<2>,  Next: Multipart workflow<2>,  Prev: Current scope<11>,  Up: http_server_core

6.105.6 Framing rules
---------------------

Request framing currently supports:

   - header termination using ‘CRLF CRLF’

   - fixed-length bodies via ‘Content-Length’

   - chunked request bodies via ‘Transfer-Encoding: chunked’, including
     trailers

When neither ‘Content-Length’ nor ‘Transfer-Encoding’ is present, the
request is read as having an empty body so that subsequent bytes remain
available for the next request on the stream.


File: TheLogtalkHandbook-3.101.0.info,  Node: Multipart workflow<2>,  Next: WebSocket handshake workflow,  Prev: Framing rules<2>,  Up: http_server_core

6.105.7 Multipart workflow
--------------------------

This library does not introduce a separate multipart server API.
Multipart requests are exposed to handlers as the same normalized
request bodies produced by ‘http_core::parse_request/2’, which means
handlers can use ‘http_multipart::fields/2’ and
‘http_multipart::files/2’ directly on the request body.


File: TheLogtalkHandbook-3.101.0.info,  Node: WebSocket handshake workflow,  Next: Current limitations<8>,  Prev: Multipart workflow<2>,  Up: http_server_core

6.105.8 WebSocket handshake workflow
------------------------------------

This layer now provides a focused helper for the HTTP opening handshake:

   - Handlers can call ‘accept_websocket/3’ to validate an incoming
     normalized handshake request and build the matching ‘101’ response.

   - Servers that need to stop after one opening handshake can call
     ‘serve_websocket/4’ and inspect whether it returned
     ‘accepted(Request, Response)’ or ‘rejected(Response)’.

   - The optional ‘protocol(Protocol)’ option selects one offered
     subprotocol.

   - The helper is intentionally transport-neutral: it handles the
     WebSocket HTTP opening handshake on existing binary streams,
     independently of whether those streams are plain or TLS-protected.

   - It does not take ownership of the upgraded stream or begin frame
     processing.  Higher layers that need to continue on the upgraded
     connection must stop at a single served message and then take over
     the underlying stream or socket.

   - Upgraded connection handles and frame/session loops are provided by
     higher layers such as ‘http_socket_transport’,
     ‘http_process_transport’, and ‘http_websocket_service’.

   - The ‘http_websocket_server_service::serve_once/6-7’ predicates
     build on top of this handshake helper when server-side code wants a
     single entry point for handshake plus callback-driven session
     execution.


File: TheLogtalkHandbook-3.101.0.info,  Node: Current limitations<8>,  Prev: WebSocket handshake workflow,  Up: http_server_core

6.105.9 Current limitations
---------------------------

   - Only the transport coding sequence ‘[chunked]’ is recognized when
     reading streamed request bodies.

   - The library does not provide socket accept loops, connection
     pooling, or concurrency management.


File: TheLogtalkHandbook-3.101.0.info,  Node: http_session,  Next: http_socket_transport,  Prev: http_server_core,  Up: Libraries

6.106 ‘http_session’
====================

This library provides explicit client-side and server-side HTTP session
support on top of the normalized HTTP stack.

The library provides these public entities:

   - ‘http_cookie_jar’ explicit in-memory cookie storage and request
     matching for client-side use

   - ‘http_client_session’ reusable HTTP client sessions that
     automatically replay and store cookies

   - ‘http_server_core_session’ server-side session manager over
     normalized request and response terms

   - ‘http_server_core_session_handler(_, _)’ portable handler wrapper
     that applies server-session begin and finish logic

   - ‘http_router_server_session(_)’ router middleware helpers for
     request annotation and response finalization

The design keeps the current ‘http_client’ API stateless.  Automatic
cookie persistence is scoped to explicit client-session handles, while
server-side session state stays in an explicit in-memory manager keyed
by opaque cookie identifiers.

By default, ‘http_client_session’ uses the ‘http_socket_transport’
transport through the default ‘http_client’ facade.  The parametric
‘http_client_session(_HTTPSocket_)’ object can also be parameterized
with alternative ‘http_transport_protocol’ implementations such as
‘http_process_transport’, which supports TLS-backed client transport.

This library can be used with backend Prolog systems that support
unbound integer arithmetic and the ‘sockets’ library: ECLiPSe, SICStus
Prolog, SWI-Prolog, Trealla Prolog, and XVM.

* Menu:

* API documentation: API documentation<125>.
* Loading: Loading<126>.
* Testing: Testing<118>.
* Usage overview: Usage overview<3>.
* Current scope: Current scope<12>.
* Current limitations: Current limitations<9>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<125>,  Next: Loading<126>,  Up: http_session

6.106.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#http_session’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<126>,  Next: Testing<118>,  Prev: API documentation<125>,  Up: http_session

6.106.2 Loading
---------------

To load the library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(http_session(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<118>,  Next: Usage overview<3>,  Prev: Loading<126>,  Up: http_session

6.106.3 Testing
---------------

To test this library, load the ‘tester.lgt’ file:

     | ?- logtalk_load(http_session(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage overview<3>,  Next: Current scope<12>,  Prev: Testing<118>,  Up: http_session

6.106.4 Usage overview
----------------------

Use ‘http_client’ for one-shot stateless calls:

     | ?- http_client::get('http://127.0.0.1:8080/resource', Response, []).

Use ‘http_client_session’ when you need cookie persistence across
requests:

     | ?- http_client_session::open(Session),
          http_client_session::get(Session, 'http://127.0.0.1:8080/visits', First, []),
          http_client_session::get(Session, 'http://127.0.0.1:8080/visits', Second, []),
          http_client_session::close(Session).

Per-request client-session options can also carry explicit SameSite
replay context when cookie replay depends on the request initiator or
whether the request is a top-level navigation:

     | ?- http_client_session::get(Session, 'http://app.example.com/data', Response,
          [source_origin('https://other.example.net'), top_level_navigation(true)]).

Sessions can also reopen a saved cookie jar directly:

     | ?- http_client_session::open(Session, [cookies_file('cookies.state')]),
          http_client_session::get(Session, 'http://127.0.0.1:8080/visits', Response, []),
          http_client_session::close(Session).

Use ‘http_server_core_session’ when you need explicit server-side
session state over normalized request and response terms:

     | ?- http_server_core_session::open(Manager),
          http_core::request(get, origin('/visits'), http(1, 1), [], empty, [], Request0),
          http_server_core_session::begin(Manager, Request0, Request),
          http_server_core_session::current(Request, Session),
          http_server_core_session::set(Session, visits, 1),
          http_core::response(http(1, 1), status(200, 'OK'), [], empty, [], Response0),
          http_server_core_session::finish(Request, Response0, Response),
          http_server_core_session::close(Manager).

You can also work directly with the cookie jar:

     | ?- http_cookie_jar::open(Jar),
          http_cookie_jar::store_set_cookies(Jar, 'http://example.com/login', [set_cookie(session, '1', [path-('/')])]),
          http_cookie_jar::request_cookies(Jar, 'http://example.com/dashboard', Cookies).

When you need explicit SameSite replay control, use the primary
context-bearing cookie-jar API:

     | ?- http_cookie_jar::request_cookies(Jar, 'https://app.example.com/data',
          request_context(get, source_url('https://other.example.net/start'), true), Cookies).

Cookie jars can also be explicitly saved and restored:

     | ?- http_cookie_jar::open(Jar),
          http_cookie_jar::store_set_cookies(Jar, 'http://example.com/login', [set_cookie(session, '1', [path-('/')])]),
          http_cookie_jar::save(Jar, 'cookies.state'),
          http_cookie_jar::close(Jar),
          http_cookie_jar::open(RestoredJar, [cookies_file('cookies.state')]).

When these SameSite request-context controls are omitted, both
‘http_client_session’ and ‘http_cookie_jar::request_cookies/3’ default
to ‘request_context(get, source_url(URL), false)’, modeling a same-site
direct request to the target URL. Use ‘source_url/1’ for a full
initiating URL and ‘source_origin/1’ for a bare ‘Origin’ header value.

The ‘cookies_file/1’ session option is a convenience for opening a fresh
owned cookie jar from disk.  It is mutually exclusive with the
‘cookie_jar/1’ session option.


File: TheLogtalkHandbook-3.101.0.info,  Node: Current scope<12>,  Next: Current limitations<9>,  Prev: Usage overview<3>,  Up: http_session

6.106.5 Current scope
---------------------

   - in-memory cookie storage with explicit save and load support

   - automatic cookie replay for explicit client-session handles

   - context-bearing cookie replay using ‘request_context(Method,
     Source, TopLevelNavigation)’ and the matching ‘http_client_session’
     request options ‘source_url/1’, ‘source_origin/1’, and
     ‘top_level_navigation/1’

   - in-memory server-side session storage keyed by opaque cookie
     identifiers

   - direct server-session request begin/finish operations plus
     plain-handler and router adapters

   - client-session transport via the existing parameterized
     ‘http_client’ facade; with the default ‘http_socket_transport’
     parameterization this means absolute ‘http://’ URLs, while
     parameterizations such as ‘http_process_transport’ also support
     ‘https://’ URLs; cookie storage and SameSite source parsing accept
     both ‘http://’ and ‘https://’ URLs plus bare ‘Origin’ values

   - core handling for host-only and domain cookies, default path
     computation, secure filtering, ‘Max-Age’, normalized ‘Expires’
     HTTP-date values, and ‘SameSite’ values

   - schemeful SameSite replay semantics using the shared origin/site
     helper in ‘http_core’, with cookies that omit ‘SameSite’ treated as
     Lax-by-default

   - server-session cookie emission with a default ‘same_site-lax’
     template and validation that explicit ‘same_site-none’ also
     requires ‘secure-true’


File: TheLogtalkHandbook-3.101.0.info,  Node: Current limitations<9>,  Prev: Current scope<12>,  Up: http_session

6.106.6 Current limitations
---------------------------

   - HTTPS transport is not available with the default
     ‘http_socket_transport’ parameterization; use a TLS-capable
     parameterization such as ‘http_process_transport’ when
     client-session transport must support ‘https://’

   - automatic synchronization with the full Mozilla Public Suffix List
     snapshot

   - browser-specific temporary Lax-allowing-unsafe grace windows

   - full browser document lifecycle semantics for cookie replay
     decisions

   - persistent or distributed server-session stores

   - session-owned connection-pool management


File: TheLogtalkHandbook-3.101.0.info,  Node: http_socket_transport,  Next: http_process_transport,  Prev: http_session,  Up: Libraries

6.107 ‘http_socket_transport’
=============================

The ‘http_socket_transport’ library is the first transport-aware layer
on top of the ‘http_client_core’, ‘http_server_core’, and ‘sockets’
libraries.  It uses TCP sockets for connection management while
delegating HTTP message framing and connection semantics to the existing
stream core and server layers.

This library can be used with backend Prolog systems that support
unbound integer arithmetic and the ‘sockets’ library: ECLiPSe, SICStus
Prolog, SWI-Prolog, Trealla Prolog, and XVM.

* Menu:

* API documentation: API documentation<126>.
* Loading: Loading<127>.
* Testing: Testing<119>.
* Current scope: Current scope<13>.
* WebSocket handshake workflow: WebSocket handshake workflow<2>.
* Current limitations: Current limitations<10>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<126>,  Next: Loading<127>,  Up: http_socket_transport

6.107.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#http_socket_transport’ link in a
web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<127>,  Next: Testing<119>,  Prev: API documentation<126>,  Up: http_socket_transport

6.107.2 Loading
---------------

To load the library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(http_socket_transport(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<119>,  Next: Current scope<13>,  Prev: Loading<127>,  Up: http_socket_transport

6.107.3 Testing
---------------

To test this library, load the ‘tester.lgt’ file:

     | ?- logtalk_load(http_socket_transport(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Current scope<13>,  Next: WebSocket handshake workflow<2>,  Prev: Testing<119>,  Up: http_socket_transport

6.107.4 Current scope
---------------------

The current implementation provides nineteen public predicates, grouped
by responsibility:

   - Listener lifecycle: ‘open_listener/4’, ‘close_listener/1’, and
     ‘request_listener_shutdown/1’.

   - Reusable client connections: ‘open_connection/4’,
     ‘close_connection/1’, ‘connection_streams/3’, ‘exchange/3’,
     ‘exchange_sequence/3’, ‘exchange/4’, and ‘exchange_sequence/4’.

   - Managed connection pools: ‘open_connection_pool/4’,
     ‘close_connection_pool/1’, and ‘connection_pool_stats/2’.

   - Server-side request serving: ‘serve_once/3’,
     ‘serve_websocket_once/5’, ‘serve_listener/4’, and
     ‘serve_listener/5’.

   - Open-ended serving control: ‘serve_until_shutdown/4’,
     ‘serve_until_shutdown/5’, and ‘request_shutdown/1’.

Although it exposes these transport-oriented helpers, the library stays
focused on socket-backed connection and listener management.  It
delegates HTTP message framing and connection semantics to
‘http_client_core’ and ‘http_server_core’, and delegates socket creation
and teardown to the ‘sockets’ library.

Reusable client connections are represented by ‘http_connection(Host,
Port, ...)’ handle terms that carry normalized endpoint metadata and can
be passed to ‘exchange/3’, ‘exchange_sequence/3’,
‘connection_streams/3’, and ‘close_connection/1’.

Accepted WebSocket upgrades are represented by
‘http_websocket_connection(ClientInfo, Input, Output)’ handle terms that
can be passed to ‘connection_streams/3’ and ‘close_connection/1’.

Managed connection pools are represented by ‘http_connection_pool(Host,
Port, ...)’ handle terms that carry normalized endpoint metadata and can
be passed to ‘exchange/3’, ‘exchange_sequence/3’,
‘close_connection_pool/1’, and ‘connection_pool_stats/2’.

Open-ended serving is controlled by a user-supplied control term.  A
control term is any fresh non-variable term chosen by the caller to
identify one active ‘serve_until_shutdown/4’ or ‘serve_until_shutdown/5’
loop.  The same term is later passed to ‘request_shutdown/1’ to stop
that specific serving loop, distinguishing it from any other listener
loops running at the same time.

The ‘open_connection_pool/4’ predicate supports the following options:

   - ‘min_size(N)’ pre-opens ‘N’ reusable connections when the pool is
     created.  The default is ‘0’.

   - ‘max_size(N)’ limits the pool to at most ‘N’ managed connections.
     The default is ‘10’.

   - ‘connection_options(Options)’ passes socket options through to
     ‘open_connection/4’ when creating pooled connections.

Pool exchanges fail immediately with
‘resource_error(http_socket_transport_connection_pool)’ when no pooled
connection is available and the pool is already at its maximum size.

The ‘serve_listener/5’ predicate supports the following option families:

Shutdown options:

   - ‘shutdown(keep_open)’ leaves the listener open after the bounded
     serving loop.  This is the default.

   - ‘shutdown(close)’ closes the listener when the bounded serving loop
     finishes or aborts.

Worker options:

   - ‘workers(serial)’ serves accepted connections sequentially in the
     caller thread.  This is the default.

   - ‘workers(per_connection)’ spawns one worker thread per accepted
     connection and waits for all workers before returning.

   - ‘workers(pool(N))’ serves accepted connections in batches of up to
     ‘N’ worker threads, waiting for each batch to finish before
     accepting the next batch.

   - ‘workers(pool(N, rolling))’ keeps up to ‘N’ worker threads active
     and accepts the next connection as soon as one worker finishes.

Calling ‘request_listener_shutdown/1’ for a listener with an active
bounded ‘serve_listener/5’ loop wakes any blocked accept call and lets
the loop return with the client information terms accepted before the
shutdown request.

The ‘serve_until_shutdown/4’ and ‘serve_until_shutdown/5’ predicates
support the ‘workers/1’ option family:

   - ‘workers(serial)’ serves accepted connections sequentially in the
     caller thread.  This is the default.

   - ‘workers(per_connection)’ spawns one worker thread per accepted
     connection and waits for active workers when shutdown is requested.

   - ‘workers(pool(N))’ serves accepted connections using at most ‘N’
     concurrent worker threads, waiting for worker completion
     notifications before accepting additional connections.

   - ‘workers(pool(N, rolling))’ is accepted as an explicit alias for
     the rolling fixed-size worker-pool policy used by
     ‘workers(pool(N))’.

Open-ended serving loops should use a fresh control term for each call
to ‘serve_until_shutdown/4’ or ‘serve_until_shutdown/5’.

When the same listener, serving, or pool-management option is given
multiple times, the first occurrence is used.


File: TheLogtalkHandbook-3.101.0.info,  Node: WebSocket handshake workflow<2>,  Next: Current limitations<10>,  Prev: Current scope<13>,  Up: http_socket_transport

6.107.5 WebSocket handshake workflow
------------------------------------

The current WebSocket transport workflow is intentionally limited to the
opening handshake handoff:

   - Client-side code can use ‘http_client::open_websocket/4’ to obtain
     a reusable upgraded connection handle.

   - Server-side code can use ‘serve_websocket_once/5’ with a handler
     that builds a valid ‘101 Switching Protocols’ response, typically
     via ‘http_server_core::accept_websocket/3’.

   - When the opening handshake succeeds, the returned upgraded
     connection remains open and its streams are available through
     ‘connection_streams/3’ for use with ‘http_websocket::read_frame/2’
     and ‘http_websocket::write_frame/2’ or, at the next abstraction
     level, with ‘http_websocket_messages::read_message/2’ and
     ‘http_websocket_messages::write_message/2’, or with the stateful
     ‘http_websocket_session’ layer when interleaved control frames and
     role-aware masking policies matter, including automatic close
     replies and optional automatic pong replies, or with the
     ‘http_websocket_service’ layer, which provides the higher-level
     ‘run_session/3-4’ callback loop that takes ownership of the
     upgraded connection and closes it automatically after the close
     handshake completes, the client-side
     ‘http_websocket_client_service::open/4-5’ convenience, and the
     server-side ‘http_websocket_server_service::serve_once/6-7’
     convenience.

   - Rejected or malformed handshakes are written to the peer and then
     reported as errors by ‘serve_websocket_once/5’; the accepted
     streams are closed in that case.


File: TheLogtalkHandbook-3.101.0.info,  Node: Current limitations<10>,  Prev: WebSocket handshake workflow<2>,  Up: http_socket_transport

6.107.6 Current limitations
---------------------------

   - Availability depends on the supported backends of the ‘sockets’
     library.

   - The library does not provide TLS or URL-based request helpers.

   - The WebSocket transport helper is limited to the opening handshake
     and upgraded connection handle management.  It does not provide
     frame parsing, message I/O, or higher-level session handling.

   - The ‘workers(per_connection)’ and ‘workers(pool(N))’ options depend
     on backend thread support.

   - Server-side helpers do not provide supervision trees.


File: TheLogtalkHandbook-3.101.0.info,  Node: http_process_transport,  Next: http_static_files,  Prev: http_socket_transport,  Up: Libraries

6.108 ‘http_process_transport’
==============================

The ‘http_process_transport’ library provides an alternative
implementation of the ‘http_transport_protocol’ protocol.  Based on the
‘process’ library and external commands, it provides TLS support for
HTTPS and WSS connections.  The current implementation uses ‘openssl
s_client’ to expose a reusable client-side byte stream suitable for the
existing ‘http_client_core’ predicates.  The current server-side
implementation defaults to ‘ncat’ to own the public listener socket and
expose accepted connections to the parent object using a loopback relay
listener plus peer metadata parsed from helper diagnostics.

This library requires backend support for the ‘process’ and ‘socket’
libraries.  Sequential client-side transport, including reusable
connections, one-shot client exchanges, and connection pools, depends on
binary process pipes.

When using a backend that doesn’t support threads, this library still
supports client-side reusable connections, sequential client pooling,
one-shot and reusable client exchanges, and serial single-connection
HTTPS and WSS serving.  Worker-based serving modes and shutdown control
still require backend thread support.

* Menu:

* Requirements: Requirements<6>.
* API documentation: API documentation<127>.
* Loading: Loading<128>.
* Testing: Testing<120>.
* Current scope: Current scope<14>.
* Current limitations: Current limitations<11>.
* Live smoke tests::


File: TheLogtalkHandbook-3.101.0.info,  Node: Requirements<6>,  Next: API documentation<127>,  Up: http_process_transport

6.108.1 Requirements
--------------------

The ‘openssl’ and ‘ncat’ commands must be available on the current
‘PATH’.

On macOS, both commands can be installed using e.g.  Homebrew:

     $ brew install openssl nmap

Or using MacPorts:

     $ sudo port install openssl nmap

On Ubuntu, both commands can be installed using:

     $ sudo apt install openssl ncat

On RedHat distributions (8.x and later):

     $ sudo dnf install openssl nmap-ncat

For older RedHat distributions:

     $ sudo yum install openssl nmap-ncat

On Windows, both commands can be installed using e.g.  Chocolatey:

     > choco install openssl
     > choco install nmap


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<127>,  Next: Loading<128>,  Prev: Requirements<6>,  Up: http_process_transport

6.108.2 API documentation
-------------------------

Open the ‘../../apis/library_index.html#http_process_transport’ link in
a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<128>,  Next: Testing<120>,  Prev: API documentation<127>,  Up: http_process_transport

6.108.3 Loading
---------------

To load the library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(http_process_transport(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<120>,  Next: Current scope<14>,  Prev: Loading<128>,  Up: http_process_transport

6.108.4 Testing
---------------

To test this library, load the ‘tester.lgt’ file:

     | ?- logtalk_load(http_process_transport(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Current scope<14>,  Next: Current limitations<11>,  Prev: Testing<120>,  Up: http_process_transport

6.108.5 Current scope
---------------------

   - reusable client connections (‘open_connection/4’,
     ‘close_connection/1’)

   - reusable client connection pools (‘open_connection_pool/4’,
     ‘close_connection_pool/1’)

   - reusable-connection and one-shot exchanges (‘exchange/3-4’,
     ‘exchange_sequence/3-4’)

   - helper-backed plain TCP listeners (‘open_listener/4’,
     ‘close_listener/1’)

   - helper-backed TLS listeners (‘open_listener/4’ with
     ‘listener_transport(tls)’)

   - server-side serving (‘serve_once/3’, ‘serve_websocket_once/5’,
     ‘serve_listener/4-5’, ‘serve_until_shutdown/4’,
     ‘request_shutdown/1’)

   - the same public connection and pool handle shapes used by
     ‘http_socket_transport’ to keep downstream endpoint validation
     compatible


File: TheLogtalkHandbook-3.101.0.info,  Node: Current limitations<11>,  Next: Live smoke tests,  Prev: Current scope<14>,  Up: http_process_transport

6.108.6 Current limitations
---------------------------

   - worker-based serving modes and shutdown control require backend
     thread support

   - the ‘openssl’ executable must be available on the ‘PATH’ unless
     overridden with the ‘openssl_executable/1’ option

   - server-side listeners require ‘ncat’ on the ‘PATH’ unless
     overridden with the ‘listener_helper_executable/1’ option to use
     ‘socat’ instead

   - the TLS listener implementation is limited to server-side stream
     exposure and handshake handling; advanced TLS options such as ALPN,
     client certificate verification, and protocol version tuning are
     not provided

Connection options accepted by ‘open_connection/4’:

   - ‘type(binary)’

   - ‘type(text)’

   - ‘connection_transport(tcp)’

   - ‘connection_transport(tls)’

   - ‘openssl_executable(Executable)’

   - ‘server_name(Name)’

   - ‘openssl_arguments(Arguments)’

Notes on those options:

   - ‘type(binary)’ and ‘type(text)’ match the shared
     ‘http_socket_transport’ client-side option surface; the selected
     value is applied to the client connection streams after the helper
     process is started

   - ‘connection_transport(tcp)’ is the default and uses ‘ncat’ as the
     helper process

   - ‘connection_transport(tls)’ uses ‘openssl s_client’ for the client
     connection helper process

   - the default ‘server_name(default)’ value maps to the requested host
     except for colon-containing hosts, where the SNI option is omitted
     by default when ‘connection_transport(tls)’ is selected

   - ‘openssl_arguments/1’ can be used to pass verification, CA, ALPN,
     or client certificate flags directly to ‘openssl s_client’ when
     ‘connection_transport(tls)’ is selected

Connection-pool options accepted by ‘open_connection_pool/4’:

   - ‘min_size(N)’

   - ‘max_size(N)’

   - ‘connection_options(Options)’

Listener options accepted by ‘open_listener/4’:

   - ‘backlog(N)’

   - ‘type(binary)’

   - ‘type(text)’

   - ‘listener_transport(tcp)’

   - ‘listener_transport(tls)’

   - ‘listener_helper_executable(Executable)’

   - ‘temporary_tls_credentials(Prefix)’

   - ‘tls_certificate_file(File)’

   - ‘tls_key_file(File)’

Notes on those listener options:

   - ‘type/1’ is accepted for drop-in compatibility with
     ‘http_socket_transport’ but does not change the internal relay
     socket type used by the listener implementation

   - ‘listener_helper_executable/1’ is a compatibility option name for
     selecting the helper executable used for the public listener and
     loopback relay

   - ‘temporary_tls_credentials(Prefix)’ generates a temporary
     self-signed certificate and key owned by the listener when
     ‘listener_transport(tls)’ is selected; both files are deleted by
     ‘close_listener/1’ and by the ‘serve_until_shutdown/4-5’
     finalization path

   - ‘tls_certificate_file/1’ and ‘tls_key_file/1’ are required together
     when ‘listener_transport(tls)’ is selected unless
     ‘temporary_tls_credentials/1’ is used instead

   - ‘temporary_tls_credentials/1’ is mutually exclusive with
     ‘tls_certificate_file/1’ and ‘tls_key_file/1’

Helper predicate:

   - ‘temporary_tls_credentials_files(Prefix, CertificateFile, KeyFile)’
     computes the temporary certificate and key file paths for a given
     prefix without creating those files; this is useful for client-side
     trust configuration when the listener itself owns certificate
     creation via ‘temporary_tls_credentials(Prefix)’

Serving options accepted by ‘serve_listener/5’:

   - ‘shutdown(keep_open)’

   - ‘shutdown(close)’

   - ‘workers(serial)’

   - ‘workers(per_connection)’

   - ‘workers(pool(Size))’

   - ‘workers(pool(Size, rolling))’

Serving options accepted by ‘serve_until_shutdown/4’:

   - ‘workers(serial)’

   - ‘workers(per_connection)’

   - ‘workers(pool(Size))’

   - ‘workers(pool(Size, rolling))’

Example:

     :- initialization((
         logtalk_load(http_process_transport(loader)),
         http_core::request(get, origin('/'), http(1,1), [host-host('example.com')], empty, [], Request),
         http_process_transport::exchange(
             'example.com',
             443,
             Request,
             Response
         ),
         writeq(Response), nl,
         halt
     )).

The one-shot exchange predicates add ‘Connection: close’ automatically
when the request does not already specify connection handling, mirroring
the existing ‘http_socket_transport’ behavior.

On the server side, a long-lived helper listener keeps ownership of the
public listener socket and relays each accepted connection into a local
loopback listener.  Peer addresses are recovered from helper
diagnostics, allowing the parent object to keep returning ‘ClientInfo’
terms while still exposing real binary streams to ‘http_server_core’ and
the existing WebSocket layers.  The same listener shape is used for both
plain TCP and TLS listeners, which allows the higher-level HTTP and
WebSocket layers to serve HTTPS and WSS requests without depending on
backend-specific SSL predicates.


File: TheLogtalkHandbook-3.101.0.info,  Node: Live smoke tests,  Prev: Current limitations<11>,  Up: http_process_transport

6.108.7 Live smoke tests
------------------------

The normal ‘tester.lgt’ driver only runs non-network tests.  Opt-in live
smoke tests are provided in ‘tests_live.lgt’ and can be run using
‘tester_live.lgt’:

     | ?- logtalk_load(http_process_transport(tester_live)).

The live smoke tests cover two parts:

   - external HTTPS client-side smoke tests against a configurable
     public endpoint

   - local loopback server-side smoke tests for plain HTTP, HTTPS, and
     WSS using the ‘http_process_transport’ listener path

The client-side live smoke tests default to the proven endpoint:

   - host: ‘httpbin.org’

   - port: ‘443’

   - path: ‘/’

The endpoint can be overridden using environment variables before
running the driver:

   - ‘LOGTALK_HTTP_SOCKET_PROCESS_LIVE_HOST’

   - ‘LOGTALK_HTTP_SOCKET_PROCESS_LIVE_PORT’

   - ‘LOGTALK_HTTP_SOCKET_PROCESS_LIVE_PATH’

These live tests exercise the one-shot exchange path, reusable
connections, sequential reuse on the same connection, and pooled reuse
while keeping the normal automated test suite free of external network
dependencies.

The server-side live smoke tests generate a temporary self-signed
certificate, open local loopback listeners, and then verify:

   - plain ‘serve_once/3’

   - TLS ‘serve_once/3’

   - WSS ‘serve_websocket_once/5’ plus a small frame round-trip on the
     upgraded streams


File: TheLogtalkHandbook-3.101.0.info,  Node: http_static_files,  Next: http_websocket,  Prev: http_process_transport,  Up: Libraries

6.109 ‘http_static_files’
=========================

The ‘http_static_files’ library provides a router-agnostic helper for
serving existing files from a configured document root using normalized
‘http_core’ request and response terms.

This library resolves a relative request path against a document root,
canonicalizes the joined target path using ‘os::absolute_file_name/2’,
rejects canonicalized escapes with the same outward ‘404 Not Found’
response used for missing files, falls back to configurable index files
for directory targets, guesses the response media type using
‘mime_types’, emits ‘ETag’, ‘Last-Modified’, and ‘Accept-Ranges’
metadata, and returns file-backed response bodies that
‘http_server_core’ can stream efficiently.

* Menu:

* API documentation: API documentation<128>.
* Loading: Loading<129>.
* Testing: Testing<121>.
* Current scope: Current scope<15>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<128>,  Next: Loading<129>,  Up: http_static_files

6.109.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#http_static_files’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<129>,  Next: Testing<121>,  Prev: API documentation<128>,  Up: http_static_files

6.109.2 Loading
---------------

To load the library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(http_static_files(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<121>,  Next: Current scope<15>,  Prev: Loading<129>,  Up: http_static_files

6.109.3 Testing
---------------

To test this library, load the ‘tester.lgt’ file:

     | ?- logtalk_load(http_static_files(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Current scope<15>,  Prev: Testing<121>,  Up: http_static_files

6.109.4 Current scope
---------------------

The current library provides one public object with two public
predicates:

   - ‘serve/4’

   - ‘serve/5’

Supported options are:

   - ‘index_files(IndexFiles)’

   - ‘mime_types_strict(Boolean)’

   - ‘mime_type_overrides(Overrides)’

   - ‘fallback_file(Fallback)’

   - ‘directory_listing(BooleanOrOptions)’

   - ‘cors(Policy)’

   - ‘cache_control(Directives)’

   - ‘expires(Expires)’

   - ‘content_disposition(Disposition)’

Default options are:

   - ‘index_files(['index.html', 'index.htm'])’

   - ‘mime_types_strict(false)’

   - ‘mime_type_overrides([])’

   - ‘fallback_file(none)’

   - ‘directory_listing(false)’

   - ‘cors([])’

   - ‘cache_control([])’

   - ‘expires(none)’

   - ‘content_disposition(none)’

Supported features:

   - ‘GET’, ‘HEAD’, and ‘OPTIONS’

   - ‘200 OK’ file responses

   - ‘204 No Content’ ‘OPTIONS’ responses with ‘Allow: GET, HEAD,
     OPTIONS’

   - canonical docroot-prefix checks after path normalization

   - weak ‘ETag’ and ‘Last-Modified’ validators derived from file size
     and modification time

   - ‘412 Precondition Failed’ responses for failing ‘If-Match’ and
     ‘If-Unmodified-Since’ request preconditions

   - ‘304 Not Modified’ responses for matching ‘If-None-Match’ and
     ‘If-Modified-Since’ requests, with ‘If-None-Match’ taking
     precedence

   - single ‘bytes=’ ranges with ‘206 Partial Content’

   - ‘416 Range Not Satisfiable’ for malformed, unsupported multi-range,
     and unsatisfiable range requests

   - ‘If-Range’ fallback to full ‘200 OK’ responses when the validator
     does not match or is only weakly equal

   - ‘406 Not Acceptable’ when ‘Accept-Encoding’ rejects the identity
     representation and no acceptable precompressed variant is available

   - ‘404 Not Found’ for missing or unsafe paths

   - custom fallback file responses for missing paths that resolve
     safely inside the document root

   - ‘405 Method Not Allowed’ for other methods with ‘Allow: GET, HEAD,
     OPTIONS’

   - ‘301 Moved Permanently’ trailing-slash redirects for directory
     targets

   - index-file lookup for directory targets

   - optional directory-listing fallback for directory targets without
     an index file, using the ‘http_directory_listing’ library

   - precompressed ‘.zst’, ‘.br’, and ‘.gz’ asset negotiation driven by
     ‘Accept-Encoding’

   - ‘Vary: Accept-Encoding’ responses when negotiated precompressed
     variants exist

   - MIME type and content-encoding guessing

   - per-extension and per-path MIME type overrides on top of
     ‘mime_types’

   - optional CORS response decoration using the ‘http_cors’ library

   - configurable ‘Cache-Control’ and ‘Expires’ response headers, also
     shared by ‘OPTIONS’ responses when configured

   - configurable ‘Content-Disposition’ response headers for inline or
     attachment file delivery

For directory listing, see the ‘http_directory_listing’ library.

Cache-policy configuration uses these option values:

   - ‘cache_control(Directives)’ where ‘Directives’ is a list containing
     any of ‘public’, ‘private’, ‘no_cache’, ‘no_store’, ‘no_transform’,
     ‘must_revalidate’, ‘proxy_revalidate’, ‘immutable’,
     ‘max_age(Seconds)’, ‘s_maxage(Seconds)’,
     ‘stale_while_revalidate(Seconds)’, ‘stale_if_error(Seconds)’, or
     ‘extension(Directive)’

   - ‘expires(none)’ to omit the header, ‘expires(Seconds)’ for a
     relative expiry from the current system time, or
     ‘expires(date_time(Year,Month,Day,Hour,Minute,Second))’ for an
     absolute expiry time

   - ‘mime_type_overrides(Overrides)’ where ‘Overrides’ is a list
     containing ‘extension(Extension, MediaType)’ or ‘path(Path,
     MediaType)’ terms; path overrides match the served document-root
     relative file path and take precedence over extension overrides

   - ‘fallback_file(none)’ to omit custom fallback handling,
     ‘fallback_file(not_found(Path))’ to serve a document-root relative
     file with ‘404 Not Found’ status for missing targets, or
     ‘fallback_file(spa(Path))’ to serve a document-root relative file
     with ‘200 OK’ status for SPA client-side routes; fallback files are
     only considered after the requested path has resolved safely inside
     the document root

   - ‘directory_listing(false)’ to omit directory-listing fallback,
     ‘directory_listing(true)’ to serve listings using the
     ‘http_directory_listing’ defaults, or ‘directory_listing(Options)’
     to pass options to ‘http_directory_listing::serve/5’; listing
     fallback is only used for existing directory targets after
     trailing-slash redirect checks and index-file lookup, and before
     generic ‘fallback_file/1’ handling

   - ‘cors([])’ to omit CORS response decoration, or ‘cors(Policy)’ to
     decorate generated responses using
     ‘http_cors::add_response_headers/4’; when the policy omits
     ‘allowed_methods/1’, static files provide the default CORS method
     policy ‘allowed_methods([get, head])’, and ‘allowed_methods(any)’
     expands from the effective methods ‘[get, head, options]’

   - ‘content_disposition(none)’ to omit the header,
     ‘content_disposition(inline)’ or ‘content_disposition(attachment)’
     for disposition-only values, and
     ‘content_disposition(inline(Filename))’ or
     ‘content_disposition(attachment(Filename))’ to include a quoted
     ‘filename’ parameter

Current validator and date handling is intentionally conservative:

   - ‘ETag’ values are weak validators of the form
     ‘W/"Size-ModifiedTime"’

   - HTTP-date formatting, date validation, and Unix-time conversion
     delegate to the ‘dates’ library; request parsing remains limited to
     the IMF-fixdate form generated for ‘Last-Modified’

   - ‘If-Match’ entity-tag evaluation uses strong comparison semantics,
     so the generated weak ‘ETag’ values only satisfy the wildcard ‘*’
     precondition

   - ‘If-Range’ entity-tag evaluation uses strong comparison semantics,
     so the generated weak ‘ETag’ values never authorize partial
     responses; matching ‘Last-Modified’ dates can still do so

   - ‘If-Range’ mismatches fall back to the full ‘200 OK’ response
     before range validation, so malformed or unsupported range syntax
     is ignored in that case

   - precompressed-asset negotiation currently recognizes ‘.zst’, ‘.br’,
     and ‘.gz’ sibling files and selects between them using
     ‘Accept-Encoding’ quality values, otherwise falling back to the
     identity representation when it remains acceptable

   - path sandboxing is based on canonicalized absolute-path prefix
     checks; no separate cross-backend symlink-policy layer has been
     added yet


File: TheLogtalkHandbook-3.101.0.info,  Node: http_websocket,  Next: http_websocket_frames,  Prev: http_static_files,  Up: Libraries

6.110 ‘http_websocket’
======================

This library provides high-level WebSocket predicates for opening and
closing connections, for exchanging messages, and for running common
client and server session loops.

By default, client predicates select a transport from the WebSocket URL
scheme: ‘ws://’ uses ‘http_socket_transport’ and ‘wss://’ uses
‘http_process_transport’.  Server predicates that accept an already open
listener default to ‘http_socket_transport’.  Applications can select a
transport explicitly with the ‘transport/1’ option when they need
lower-level control or a custom ‘http_transport_protocol’
implementation.

This library can be used with backend Prolog systems that support
unbound integer arithmetic and the ‘sockets’ library: ECLiPSe, SICStus
Prolog, SWI-Prolog, Trealla Prolog, and XVM.

* Menu:

* API documentation: API documentation<129>.
* Loading: Loading<130>.
* Testing: Testing<122>.
* Current scope: Current scope<16>.
* Current workflow: Current workflow<2>.
* Lower-level layers::


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<129>,  Next: Loading<130>,  Up: http_websocket

6.110.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#http_websocket’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<130>,  Next: Testing<122>,  Prev: API documentation<129>,  Up: http_websocket

6.110.2 Loading
---------------

To load the full library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(http_websocket(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<122>,  Next: Current scope<16>,  Prev: Loading<130>,  Up: http_websocket

6.110.3 Testing
---------------

To test this library, load the ‘tester.lgt’ file:

     | ?- logtalk_load(http_websocket(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Current scope<16>,  Next: Current workflow<2>,  Prev: Testing<122>,  Up: http_websocket

6.110.4 Current scope
---------------------

The current implementation provides the following predicates:

   - ‘open/2-3’ for opening client WebSocket connections and returning
     opaque handles.  The ‘transport/1’ option selects the transport;
     ‘transport(default)’ derives it from the URL scheme.

   - ‘accept/3-4’ for accepting one server-side WebSocket connection on
     an open listener and returning opaque handles.  The listener must
     be created by the selected transport.  Use ‘transport(Transport)’
     when accepting from a listener opened with a transport other than
     ‘http_socket_transport’.

   - ‘send/2-3’, ‘receive/2-3’, and ‘close/1-2’ for direct message
     exchange using those handles.

   - ‘property/2’ for inspecting handle properties such as the handshake
     response, selected subprotocol, or underlying upgraded connection.

   - ‘send_text/2’, ‘receive_text/2’, ‘send_binary/2’,
     ‘receive_binary/2’, ‘send_json/2’, ‘receive_json/2’, ‘send_term/2’,
     and ‘receive_term/2’ convenience predicates for common payload
     formats.

   - ‘open_session/4-5’ and ‘serve_once/5-6’ for callback-driven client
     and server sessions built on top of the ‘http_websocket_service’
     layer.

The test suite exercises both ‘http_socket_transport’ and
‘http_process_transport’ by passing the selected transport through the
‘transport/1’ option.


File: TheLogtalkHandbook-3.101.0.info,  Node: Current workflow<2>,  Next: Lower-level layers,  Prev: Current scope<16>,  Up: http_websocket

6.110.5 Current workflow
------------------------

For the common direct client case:

| ?- http_websocket::open(‘ws://127.0.0.1:8080/echo’, WebSocket,
[protocols([chat])]), http_websocket::send_text(WebSocket, hello),
http_websocket::receive_text(WebSocket, Reply),
http_websocket::close(WebSocket, status(1000, done)).

For the common direct server case:

| ?- http_socket_transport::open_listener(‘127.0.0.1’, 8080, Listener,
[]), http_websocket::accept(Listener, WebSocket, ClientInfo,
[transport(http_socket_transport), protocol(chat)]),
http_websocket::receive(WebSocket, Message),
http_websocket::send(WebSocket, Message).

To use the process-backed transport instead, pair the matching listener
and ‘transport/1’ option:

| ?- http_process_transport::open_listener(‘127.0.0.1’, 8080, Listener,
[]), http_websocket::accept(Listener, WebSocket, ClientInfo,
[transport(http_process_transport), protocol(chat)]),
http_websocket::receive(WebSocket, Message),
http_websocket::send(WebSocket, Message).

For callback-driven client sessions that should stay on the high-level
surface, use:

| ?- http_websocket::open_session(URL, Handler, Response, State,
[transport(default), protocols([chat]), initial_messages([message(text,
hello)])]).

For callback-driven server sessions that should stay on the high-level
surface, use:

| ?- http_websocket::serve_once(Listener, Handler, Response, State,
ClientInfo, [transport(http_socket_transport), protocol(chat)]).


File: TheLogtalkHandbook-3.101.0.info,  Node: Lower-level layers,  Prev: Current workflow<2>,  Up: http_websocket

6.110.6 Lower-level layers
--------------------------

The ‘http_websocket’ library now hides the most common plumbing, but the
lower-level libraries remain available when you need them:

   - Use ‘http_websocket_frames’ when working with raw frame parsing and
     generation.

   - Use ‘http_websocket_messages’ when you want transport-neutral
     message I/O without connection or session ownership.

   - Use ‘http_websocket_session’ when you need the stateful message
     layer with detailed close/ping state control but without callback
     loops or threads.

   - Use ‘http_websocket_service’ when you need the full callback-driven
     session layer or registry-backed broadcast helpers.


File: TheLogtalkHandbook-3.101.0.info,  Node: http_websocket_frames,  Next: http_websocket_handshake,  Prev: http_websocket,  Up: Libraries

6.111 ‘http_websocket_frames’
=============================

This library provides the transport-neutral WebSocket helpers shared by
the current HTTP stack.  It includes normalized frame terms and binary
frame parsing and generation in the ‘http_websocket_frames’ object.

This library can be used with backend Prolog systems that support
unbound integer arithmetic.

* Menu:

* API documentation: API documentation<130>.
* Loading: Loading<131>.
* Testing: Testing<123>.
* Current scope: Current scope<17>.
* Normalized terms: Normalized terms<3>.
* Valid properties::
* Current workflow: Current workflow<3>.
* Current limitations: Current limitations<12>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<130>,  Next: Loading<131>,  Up: http_websocket_frames

6.111.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#http_websocket_frames’ link in a
web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<131>,  Next: Testing<123>,  Prev: API documentation<130>,  Up: http_websocket_frames

6.111.2 Loading
---------------

To load the full library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(http_websocket_frames(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<123>,  Next: Current scope<17>,  Prev: Loading<131>,  Up: http_websocket_frames

6.111.3 Testing
---------------

To test this library, load the ‘tester.lgt’ file:

     | ?- logtalk_load(http_websocket_frames(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Current scope<17>,  Next: Normalized terms<3>,  Prev: Testing<123>,  Up: http_websocket_frames

6.111.4 Current scope
---------------------

The current implementation provides:

   - ‘frame/5’ for constructing validated normalized WebSocket frame
     terms.

   - ‘is_frame/1’ for testing normalized frame terms.

   - ‘final/2’, ‘opcode/2’, ‘payload/2’, ‘properties/2’, and
     ‘property/2’ for inspecting normalized frame terms.

   - ‘parse/2’ and ‘generate/2’ for binary source and sink terms.

   - ‘read_frame/2’ and ‘write_frame/2’ for incremental frame I/O on
     binary streams.


File: TheLogtalkHandbook-3.101.0.info,  Node: Normalized terms<3>,  Next: Valid properties,  Prev: Current scope<17>,  Up: http_websocket_frames

6.111.5 Normalized terms
------------------------

Frames use the normalized term:

     frame(Final, Opcode, Payload, Properties)

Where:

   - ‘Final’ is either ‘final’ or ‘more’.

   - ‘Opcode’ is one of ‘continuation’, ‘text’, ‘binary’, ‘close’,
     ‘ping’, or ‘pong’.

   - ‘Payload’ is a list of bytes.

   - ‘Properties’ currently recognizes:

        - ‘masking_key(Key)’ where ‘Key’ is a four-byte list.

        - ‘reserved_bits(Bits)’ where ‘Bits’ is an ordered subset of
          ‘[rsv1, rsv2, rsv3]’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Valid properties,  Next: Current workflow<3>,  Prev: Normalized terms<3>,  Up: http_websocket_frames

6.111.6 Valid properties
------------------------

The ‘Properties’ list accepted by ‘frame/5’, ‘generate/2’, and
‘write_frame/2’ can contain only the following properties:

   - ‘masking_key(Key)’

        - ‘Key’ must be a list of exactly four bytes.

        - Each byte must be an integer in the ‘0..255’ range.

   - ‘reserved_bits(Bits)’

        - ‘Bits’ must be a list containing any ordered subset of ‘[rsv1,
          rsv2, rsv3]’.

        - Duplicate reserved-bit atoms are invalid.

Each property can be given at most once.  When both properties are
present, the normalized property list is returned in the canonical order
‘[reserved_bits(Bits), masking_key(Key)]’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Current workflow<3>,  Next: Current limitations<12>,  Prev: Valid properties,  Up: http_websocket_frames

6.111.7 Current workflow
------------------------

   - Use ‘read_frame/2’ and ‘write_frame/2’ on those streams to exchange
     WebSocket frames.

   - Use the higher-level ‘http_websocket_messages’ library when you
     need continuation reassembly or UTF-8-aware text and close-reason
     handling.

   - Use the ‘http_websocket_session’ library when fragmented reads must
     preserve pending state across interleaved control frames or when
     outgoing writes should apply client or server masking policy
     automatically.

   - Use ‘parse/2’ and ‘generate/2’ when working with in-memory byte
     lists or binary files instead of live streams.


File: TheLogtalkHandbook-3.101.0.info,  Node: Current limitations<12>,  Prev: Current workflow<3>,  Up: http_websocket_frames

6.111.8 Current limitations
---------------------------

   - This library operates at the frame level only.  It does not provide
     application session loops.

   - This layer does not provide message reassembly or UTF-8-aware text
     and close-reason handling.

   - Client and server masking policy is not enforced by role in this
     frame layer.  The presence of a ‘masking_key/1’ property controls
     whether outgoing frames are masked.  Use the
     ‘http_websocket_session’ layer when you want role-aware writes and
     role-aware incoming masking validation.

   - Reserved bits are preserved structurally but no extension
     negotiation or extension semantics are implemented.


File: TheLogtalkHandbook-3.101.0.info,  Node: http_websocket_handshake,  Next: http_websocket_messages,  Prev: http_websocket_frames,  Up: Libraries

6.112 ‘http_websocket_handshake’
================================

This library provides lower-level opening-handshake predicates in the
‘http_websocket_handshake’ object that is used by other libraries.
Requires a backend supporting unbound integer arithmetic.

* Menu:

* API documentation: API documentation<131>.
* Loading: Loading<132>.
* Testing: Testing<124>.
* Current scope: Current scope<18>.
* Current workflow: Current workflow<4>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<131>,  Next: Loading<132>,  Up: http_websocket_handshake

6.112.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#http_websocket_handshake’ link
in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<132>,  Next: Testing<124>,  Prev: API documentation<131>,  Up: http_websocket_handshake

6.112.2 Loading
---------------

To load the full library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(http_websocket_handshake(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<124>,  Next: Current scope<18>,  Prev: Loading<132>,  Up: http_websocket_handshake

6.112.3 Testing
---------------

To test this library, load the ‘tester.lgt’ file:

     | ?- logtalk_load(http_websocket_handshake(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Current scope<18>,  Next: Current workflow<4>,  Prev: Testing<124>,  Up: http_websocket_handshake

6.112.4 Current scope
---------------------

The current implementation provides two predicates:

   - ‘websocket_opening_key/1’ for generating canonical base64-encoded
     opening keys.

   - ‘websocket_accept/2’ for computing canonical ‘Sec-WebSocket-Accept’
     values from valid opening keys.


File: TheLogtalkHandbook-3.101.0.info,  Node: Current workflow<4>,  Prev: Current scope<18>,  Up: http_websocket_handshake

6.112.5 Current workflow
------------------------

Use the ‘websocket_opening_key/1’ and ‘websocket_accept/2’ predicates
only when you need the raw opening-handshake values without opening a
connection.


File: TheLogtalkHandbook-3.101.0.info,  Node: http_websocket_messages,  Next: http_websocket_service,  Prev: http_websocket_handshake,  Up: Libraries

6.113 ‘http_websocket_messages’
===============================

This library provides the next transport-neutral WebSocket slice on top
of the ‘http_websocket’ frame library.  It reassembles continuation
sequences for text and binary messages, decodes and encodes UTF-8 text
payloads, and adds a normalized message term for text, binary, ping,
pong, and close messages.

This library can be used with backend Prolog systems that support
unbound integer arithmetic.

* Menu:

* API documentation: API documentation<132>.
* Loading: Loading<133>.
* Testing: Testing<125>.
* Current scope: Current scope<19>.
* Normalized terms: Normalized terms<4>.
* Current workflow: Current workflow<5>.
* Current limitations: Current limitations<13>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<132>,  Next: Loading<133>,  Up: http_websocket_messages

6.113.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#http_websocket_messages’ link in
a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<133>,  Next: Testing<125>,  Prev: API documentation<132>,  Up: http_websocket_messages

6.113.2 Loading
---------------

To load the library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(http_websocket_messages(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<125>,  Next: Current scope<19>,  Prev: Loading<133>,  Up: http_websocket_messages

6.113.3 Testing
---------------

To test this library, load the ‘tester.lgt’ file:

     | ?- logtalk_load(http_websocket_messages(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Current scope<19>,  Next: Normalized terms<4>,  Prev: Testing<125>,  Up: http_websocket_messages

6.113.4 Current scope
---------------------

The current implementation provides:

   - ‘message/3’ for constructing validated normalized WebSocket message
     terms.

   - ‘is_message/1’ for testing normalized message terms.

   - ‘type/2’ and ‘payload/2’ for inspecting normalized message terms.

   - ‘read_message/2’ for reading one WebSocket message from a binary
     stream, including continuation reassembly for text and binary
     messages.

   - ‘write_message/2’ for writing one WebSocket message as a single
     final frame.

This layer remains intentionally stateless.  The
‘http_websocket_session’ library builds on top of it when the caller
needs explicit session state, interleaved control-frame surfacing, or
role-aware outgoing fragmentation and masking.


File: TheLogtalkHandbook-3.101.0.info,  Node: Normalized terms<4>,  Next: Current workflow<5>,  Prev: Current scope<19>,  Up: http_websocket_messages

6.113.5 Normalized terms
------------------------

Messages use the normalized term:

     message(Type, Payload)

Where:

   - ‘Type’ is one of ‘text’, ‘binary’, ‘ping’, ‘pong’, or ‘close’.

   - For ‘text’, ‘Payload’ is text in the selected representation.

   - For ‘binary’, ‘ping’, and ‘pong’, ‘Payload’ is a list of bytes.

   - For ‘close’, ‘Payload’ is one of:

        - ‘empty’

        - ‘status(Code)’

        - ‘status(Code, Reason)’

The parameterized object ‘http_websocket_messages(TextRepresentation)’
accepts ‘atom’, ‘chars’, or ‘codes’.  The plain
‘http_websocket_messages’ object uses atoms.


File: TheLogtalkHandbook-3.101.0.info,  Node: Current workflow<5>,  Next: Current limitations<13>,  Prev: Normalized terms<4>,  Up: http_websocket_messages

6.113.6 Current workflow
------------------------

   - Complete the opening handshake with ‘http_client::open_websocket/4’
     or ‘http_socket_transport::serve_websocket_once/5’.

   - Obtain the upgraded binary streams with
     ‘http_socket_transport::connection_streams/3’.

   - Use ‘read_message/2’ and ‘write_message/2’ when you want
     UTF-8-aware text messages and continuation reassembly instead of
     raw frame access.

   - Use the higher-level ‘http_websocket_session’ library when
     fragmented data reads must coexist with interleaved control
     messages or when writes should apply client or server masking
     policy automatically.

   - Use the lower-level ‘http_websocket’ predicates directly when you
     need raw frame properties such as masking keys or reserved bits.


File: TheLogtalkHandbook-3.101.0.info,  Node: Current limitations<13>,  Prev: Current workflow<5>,  Up: http_websocket_messages

6.113.7 Current limitations
---------------------------

   - Outgoing messages are generated as a single final frame.  This
     layer does not provide outgoing fragmentation policies.

   - Fragmented text and binary messages are reassembled only when the
     following frames are plain continuation frames.  Use the
     ‘http_websocket_session’ library when interleaved control messages
     must be surfaced while the fragmented data remains pending.

   - Client and server masking policy is not enforced automatically by
     role in this stateless layer.  Use the ‘http_websocket_session’
     library when that policy should be applied automatically.

   - This layer does not provide application session loops.  For full
     close-handshake orchestration or automatic ping/pong policies, use
     the ‘http_websocket_session’ layer.


File: TheLogtalkHandbook-3.101.0.info,  Node: http_websocket_service,  Next: http_websocket_session,  Prev: http_websocket_messages,  Up: Libraries

6.114 ‘http_websocket_service’
==============================

This library provides higher-level callback-driven WebSocket session
loops on top of the ‘http_websocket_session’ state-machine library and
upgraded WebSocket connections provided by a selected
‘http_transport_protocol’ implementation.  It adds connection lifecycle
ownership, optional auto-pong, keepalive, and idle-timeout policies,
client- and server-side conveniences that collapse the opening handshake
and the session loop into a single call, and a registry-backed broadcast
helper for multi-session servers.

By default, the convenience objects use the ‘http_socket_transport’
transport.  The parametric ‘http_websocket_service(_HTTPSocket_, _Role_,
_TextRepresentation_)’, ‘http_websocket_client_service(_HTTPSocket_)’,
and ‘http_websocket_server_service(_HTTPSocket_)’ objects can also use
alternative ‘http_transport_protocol’ implementations such as
‘http_process_transport’.

This library can be used with backend Prolog systems that support
unbound integer arithmetic and the ‘sockets’ library: ECLiPSe, SICStus
Prolog, SWI-Prolog, Trealla Prolog, and XVM. On backends that don’t
support threads, only a subset of the library is usable; see the
“Backends without thread support” section below for the details.

* Menu:

* API documentation: API documentation<133>.
* Loading: Loading<134>.
* Testing: Testing<126>.
* Current scope: Current scope<20>.
* Higher-level session loop::
* Registry-backed server helper::
* Backends without thread support::
* Current workflow: Current workflow<6>.
* Current limitations: Current limitations<14>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<133>,  Next: Loading<134>,  Up: http_websocket_service

6.114.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#http_websocket_service’ link in
a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<134>,  Next: Testing<126>,  Prev: API documentation<133>,  Up: http_websocket_service

6.114.2 Loading
---------------

To load the library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(http_websocket_service(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<126>,  Next: Current scope<20>,  Prev: Loading<134>,  Up: http_websocket_service

6.114.3 Testing
---------------

To test this library, load the ‘tester.lgt’ file:

     | ?- logtalk_load(http_websocket_service(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Current scope<20>,  Next: Higher-level session loop,  Prev: Testing<126>,  Up: http_websocket_service

6.114.4 Current scope
---------------------

The current implementation provides:

   - ‘run_session/3-4’ for higher-level callback-driven loops over
     upgraded WebSocket connection handles produced by the selected
     transport parameterization that keep reading until the close
     handshake completes or the peer closes the stream and then close
     the upgraded connection automatically, with optional auto-pong,
     keepalive, idle-timeout, and maximum payload length policies.

   - ‘open/4-5’ in the ‘http_websocket_client_service’ object as a
     client-side convenience that combines
     ‘http_client::open_websocket/4’, optional initial outbound
     messages, and the higher-level session loop.  The accepted URL
     schemes depend on the selected transport parameterization, e.g.
     ‘ws://’ for ‘http_socket_transport’ and both ‘ws://’ and ‘wss://’
     for ‘http_process_transport’.

   - ‘serve_once/6-7’ in the ‘http_websocket_server_service’ object as a
     server-side convenience that combines the selected transport
     parameterization ‘serve_websocket_once/5’ predicate with the
     higher-level session loop.

   - ‘serve_until_shutdown/5-6’ and ‘request_shutdown/1’ in the
     ‘http_websocket_server_service’ object for registry-backed
     multi-session servers with queued broadcast delivery.

   - ‘open/1’, ‘close/1’, ‘register/2’, ‘unregister/2’, ‘send/3’,
     ‘broadcast/2’, ‘broadcast_except/3’, and ‘take_pending/3’ in the
     ‘http_websocket_service_registry’ object for managing active
     sessions and queued outbound messages.


File: TheLogtalkHandbook-3.101.0.info,  Node: Higher-level session loop,  Next: Registry-backed server helper,  Prev: Current scope<20>,  Up: http_websocket_service

6.114.5 Higher-level session loop
---------------------------------

The ‘run_session/3-4’ predicates accept an upgraded WebSocket connection
handle produced by the selected transport parameterization together with
a handler object that implements the
‘http_websocket_service_handler_protocol’ protocol:

     handle(Message, Replies)

For each received normalized message, the handler returns a list of
normalized reply messages to write before the next read.  The loop:

   - starts from the initial session state,

   - reuses the stateful session orchestration including automatic close
     replies and optional auto-pong policy,

   - writes the handler replies using the stateful session write
     predicates,

   - continues until the close handshake reaches ‘closed(SentPayload,
     ReceivedPayload)’ or the peer closes the stream, and

   - closes the upgraded connection automatically before returning.

The ‘run_session/4’ predicate accepts these loop options:

   - ‘auto_pong(on)’ or ‘auto_pong(off)’

   - ‘keepalive_interval(Seconds)’

   - ‘idle_timeout(Seconds)’

   - ‘max_payload_length(Bytes)’

When ‘keepalive_interval(Seconds)’ is used, the loop sends empty ping
messages after ‘Seconds’ of inbound silence.  When
‘idle_timeout(Seconds)’ is used, the loop sends ‘message(close,
status(1001, idle_timeout))’ after ‘Seconds’ of inbound silence and then
waits one more idle interval for the peer close reply.  These timed
options require backend thread support.  The keepalive and idle-timeout
policies are tracked using absolute wall-clock deadlines, making the
loop robust to scheduling jitter and slow reads.

A small server-side session handler can look like:

     :- object(chat_session_handler,
         implements(http_websocket_service_handler_protocol)).

         handle(message(text, ping), [message(text, pong)]) :-
             !.
         handle(message(text, Text), [message(text, Text)]) :-
             !.
         handle(message(close, _Payload), []) :-
             !.
         handle(_Message, []).

     :- end_object.

After a successful opening handshake returns an upgraded ‘Connection’
handle, run the loop with either:

     | ?- http_websocket_server_service::run_session(Connection, chat_session_handler, FinalState).

or:

     | ?- http_websocket_server_service::run_session(Connection, chat_session_handler, FinalState, [auto_pong(on)]).

or with timed loop policies:

     | ?- http_websocket_server_service::run_session(Connection, chat_session_handler, FinalState, [auto_pong(on), keepalive_interval(30), idle_timeout(120)]).

The ‘run_session/3-4’ predicates take ownership of the upgraded
connection, so no explicit transport ‘close_connection/1’ call is needed
afterwards.

For a client that wants to collapse the opening handshake and the
callback loop into a single call, the ‘http_websocket_client_service’
object provides:

     open(URL, SessionHandler, Response, FinalState)

or:

     open(URL, SessionHandler, Response, FinalState, [protocols([chat]), initial_messages([message(text, hello)]), auto_pong(on)])

The accepted WebSocket URL schemes depend on the selected transport
parameterization.  For example, the default
‘http_websocket_client_service’ object uses ‘http_socket_transport’ and
therefore accepts ‘ws://’ URLs, while
‘http_websocket_client_service(http_process_transport)’ also accepts
‘wss://’ URLs.

The ‘initial_messages(Messages)’ option writes the given list of
normalized outbound messages immediately after the handshake and before
the first session read.  The ‘open/4-5’ predicates also accept the
‘keepalive_interval/1’, ‘idle_timeout/1’, and ‘max_payload_length/1’
session-loop options.  They take ownership of the upgraded connection
and close it automatically when the session loop finishes.

For a server that wants to collapse the opening handshake and the
callback loop into a single call, the ‘http_websocket_server_service’
object provides:

     serve_once(Listener, HandshakeHandler, SessionHandler, Response, FinalState, ClientInfo)

or:

     serve_once(Listener, HandshakeHandler, SessionHandler, Response, FinalState, ClientInfo, [auto_pong(on)])

These predicates accept one incoming socket connection, serve one valid
opening handshake via the given HTTP handler, run the session loop via
the given session handler, and then close the upgraded connection
automatically.  They also accept the ‘keepalive_interval/1’,
‘idle_timeout/1’, and ‘max_payload_length/1’ session-loop options.

For server-side helpers, the ‘Listener’ must come from the same selected
transport parameterization as the service object, e.g.
‘http_websocket_server_service(http_process_transport)’ must be paired
with a listener opened by ‘http_process_transport::open_listener/4’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Registry-backed server helper,  Next: Backends without thread support,  Prev: Higher-level session loop,  Up: http_websocket_service

6.114.6 Registry-backed server helper
-------------------------------------

For multi-session servers that need queued outbound delivery and
broadcast, the ‘http_websocket_server_service’ object also provides:

     serve_until_shutdown(Listener, HandshakeHandler, SessionHandler, Registry, Control)

or:

     serve_until_shutdown(Listener, HandshakeHandler, SessionHandler, Registry, Control, [auto_pong(on), keepalive_interval(30), idle_timeout(120)])

This helper accepts opening handshakes until:

   - ‘http_websocket_server_service::request_shutdown(Control)’ is
     called, or

   - the listener is closed externally.

Each accepted upgraded connection is registered in ‘Registry’ and
handled in its own session worker.  The registry queues outbound
messages so that each worker only writes to its own connection.

When used with ‘serve_until_shutdown/5-6’, the session handler may still
return plain normalized reply messages, but it may also return these
action wrappers:

   - ‘reply(Message)’

   - ‘broadcast(Message)’

   - ‘broadcast_others(Message)’

For example, a simple chat-style broadcast handler can look like:

     :- object(chat_broadcast_handler,
         implements(http_websocket_service_handler_protocol)).

         handle(message(text, Text), [broadcast_others(message(text, Text))]) :-
             !.
         handle(message(close, _Payload), []) :-
             !.
         handle(_Message, []).

     :- end_object.

The ‘http_websocket_service_registry’ object provides the registry
handle and queue-management predicates used by this helper.  The
registry-backed server helper requires backend thread support.


File: TheLogtalkHandbook-3.101.0.info,  Node: Backends without thread support,  Next: Current workflow<6>,  Prev: Registry-backed server helper,  Up: http_websocket_service

6.114.7 Backends without thread support
---------------------------------------

The library loads on any backend that supports the ‘sockets’ library and
unbounded integer arithmetic, but the available functionality depends on
whether the backend supports threads.

Available without thread support:

   - The ‘run_session/3-4’, ‘http_websocket_client_service::open/4-5’,
     and ‘http_websocket_server_service::serve_once/6-7’ predicates when
     called without the ‘keepalive_interval/1’ and ‘idle_timeout/1’
     options.  In this case, the session loop reads from the connection
     using plain blocking reads and no background reader is required.

   - The ‘http_websocket_service_registry’ data predicates (‘open/1’,
     ‘close/1’, ‘register/2’, ‘unregister/2’, ‘send/3’, ‘broadcast/2’,
     ‘broadcast_except/3’, and ‘take_pending/3’), which are plain
     database operations.

Requiring thread support:

   - The ‘keepalive_interval/1’ and ‘idle_timeout/1’ loop options.
     These policies need a timed session loop that polls a background
     reader, which is implemented using threads.  When used on a backend
     without thread support, the loop predicates throw a
     ‘existence_error(http_websocket_service,timing)’ exception before
     reading or writing any frames.

   - Registry-driven session loops (i.e., sessions run on behalf of the
     registry-backed server helper).  These impose a polling interval so
     that messages and broadcasts queued by other sessions can be
     flushed promptly, which also requires the timed session loop and
     thus thread support.

   - The ‘serve_until_shutdown/5-6’ and ‘request_shutdown/1’ predicates,
     which run each accepted session in its own worker thread.  On
     backends without thread support, these predicates throw a
     ‘existence_error(http_websocket_server_service,registry)’
     exception.

In all cases, unsupported usage fails fast with a ‘existence_error/2’
exceptions at validation time instead of hanging or silently
misbehaving.


File: TheLogtalkHandbook-3.101.0.info,  Node: Current workflow<6>,  Next: Current limitations<14>,  Prev: Backends without thread support,  Up: http_websocket_service

6.114.8 Current workflow
------------------------

   - Use the ‘http_websocket_session’ library directly when you need
     stateful reads, close-state tracking, or role-aware writes on
     binary streams that you manage yourself.

   - When a single callback object should own the connection lifecycle,
     pass the upgraded handle to ‘run_session/3-4’ and let the service
     layer close it when the close handshake completes.

   - When client-side code should own the full upgraded connection
     lifecycle, call ‘http_websocket_client_service::open/4-5’ and let
     the service layer handle the opening handshake, any configured
     initial outbound messages, and the final connection close.

   - When the client transport must support secure ‘wss://’ URLs, use
     the a TLS-capable parameterization such as
     ‘http_process_transport’.

   - When server-side code already owns a listener and wants a single
     entry point for handshake plus session execution, call
     ‘http_websocket_server_service::serve_once/6-7’.

   - When server-side code uses a non-default transport such as
     ‘http_process_transport’, use the matching parametric service
     object and open the listener with that same transport
     parameterization.

   - When server-side code needs multiple active sessions plus queued
     broadcast delivery, create a registry with
     ‘http_websocket_service_registry::open/1’ and call
     ‘http_websocket_server_service::serve_until_shutdown/5-6’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Current limitations<14>,  Prev: Current workflow<6>,  Up: http_websocket_service

6.114.9 Current limitations
---------------------------

   - The ‘run_session/3-4’ and ‘serve_once/6-7’ helpers are synchronous,
     single-connection callback loops.

   - On backends without thread support, the timed loop options
     ‘keepalive_interval/1’ and ‘idle_timeout/1’, registry-driven
     session loops, and the ‘serve_until_shutdown/5-6’ helper are not
     available and throw ‘existence_error/2’ exceptions; see the
     “Backends without thread support” section above.


File: TheLogtalkHandbook-3.101.0.info,  Node: http_websocket_session,  Next: ica_projection,  Prev: http_websocket_service,  Up: Libraries

6.115 ‘http_websocket_session’
==============================

This library provides the next WebSocket slice on top of the
‘http_websocket_messages’ library.  It adds a state term for incremental
reads, surfaces interleaved control messages while a fragmented text or
binary message is still pending, applies role-aware client and server
masking when writing messages, and can automatically orchestrate close
replies and optional pong replies.

This library is a pure state-machine layer working on binary streams: it
does not create threads and does not depend on socket support.  The
higher-level callback-driven session loops, keepalive and idle-timeout
policies, and the registry-backed broadcast helpers for upgraded
‘http_socket_transport’ connections are provided by the
‘http_websocket_service’ library.

This library can be used with backend Prolog systems that support
unbound integer arithmetic.

* Menu:

* API documentation: API documentation<134>.
* Loading: Loading<135>.
* Testing: Testing<127>.
* Current scope: Current scope<21>.
* Role-aware objects::
* Stateful reads::
* Automatic control handling::
* Outgoing fragmentation::
* Current workflow: Current workflow<7>.
* Current limitations: Current limitations<15>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<134>,  Next: Loading<135>,  Up: http_websocket_session

6.115.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#http_websocket_session’ link in
a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<135>,  Next: Testing<127>,  Prev: API documentation<134>,  Up: http_websocket_session

6.115.2 Loading
---------------

To load the library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(http_websocket_session(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<127>,  Next: Current scope<21>,  Prev: Loading<135>,  Up: http_websocket_session

6.115.3 Testing
---------------

To test this library, load the ‘tester.lgt’ file:

     | ?- logtalk_load(http_websocket_session(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Current scope<21>,  Next: Role-aware objects,  Prev: Testing<127>,  Up: http_websocket_session

6.115.4 Current scope
---------------------

The current implementation provides:

   - ‘initial_state/1’ and ‘is_state/1’ for working with session state
     terms.

   - ‘read_message/4’ for stateful message reads that preserve pending
     fragmented data across interleaved control messages while tracking
     close-handshake state.

   - ‘read_message/5’ for stateful message reads plus automatic
     close-handshake replies.

   - ‘read_message/6’ for stateful message reads plus automatic
     close-handshake replies and optional auto-pong and maximum payload
     length policies.

   - ‘write_message/2-3’ as stateless convenience wrappers for
     role-aware writes.

   - ‘write_message/4-5’ for role-aware writes that also update the
     session state, including close-handshake transitions.


File: TheLogtalkHandbook-3.101.0.info,  Node: Role-aware objects,  Next: Stateful reads,  Prev: Current scope<21>,  Up: http_websocket_session

6.115.5 Role-aware objects
--------------------------

The parameterized object ‘http_websocket_session(Role,
TextRepresentation)’ accepts:

   - ‘Role’ equal to ‘client’ or ‘server’

   - ‘TextRepresentation’ equal to ‘atom’, ‘chars’, or ‘codes’

The library also provides two convenience objects using atom text:

   - ‘http_websocket_client_session’

   - ‘http_websocket_server_session’

Client sessions expect unmasked inbound frames and mask all outgoing
frames.  Server sessions expect masked inbound frames and leave outgoing
frames unmasked.


File: TheLogtalkHandbook-3.101.0.info,  Node: Stateful reads,  Next: Automatic control handling,  Prev: Role-aware objects,  Up: http_websocket_session

6.115.6 Stateful reads
----------------------

The ‘read_message/4’ predicate threads an explicit session state term:

     read_message(Stream, State0, State, Message)

When a fragmented text or binary message is in progress and a control
frame is received before the final continuation frame, the control frame
is returned as a normalized ‘message(Type, Payload)’ term and the
pending fragmented data is kept in ‘State’ for the next call.

Close-handshake state is tracked in the returned state.  Open states
keep the compact form ‘session_state(Pending)’.  Once a close message
has been sent or received, the state uses ‘session_state(Pending,
CloseStatus)’ where ‘CloseStatus’ is one of:

   - ‘close_sent(Payload)’

   - ‘close_received(Payload)’

   - ‘closed(SentPayload, ReceivedPayload)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Automatic control handling,  Next: Outgoing fragmentation,  Prev: Stateful reads,  Up: http_websocket_session

6.115.7 Automatic control handling
----------------------------------

The ‘read_message/5’ predicate automatically writes a matching close
reply when it reads a close message and the session state shows that no
close message has yet been sent.

The ‘read_message/6’ predicate adds the options:

   - ‘auto_pong(on)’ or ‘auto_pong(off)’

   - ‘max_payload_length(Bytes)’

When ‘auto_pong(on)’ is used, incoming ping messages are still returned
to the caller but a matching pong message is written automatically on
the output stream.  When ‘max_payload_length(Bytes)’ is used, inbound
frames whose declared payload length is greater than ‘Bytes’ are
rejected before allocating payload storage.


File: TheLogtalkHandbook-3.101.0.info,  Node: Outgoing fragmentation,  Next: Current workflow<7>,  Prev: Automatic control handling,  Up: http_websocket_session

6.115.8 Outgoing fragmentation
------------------------------

The ‘write_message/3’ predicate accepts the option:

   - ‘fragment_size(Size)’

For ‘text’ and ‘binary’ messages, this splits the payload into frames of
at most ‘Size’ bytes.  The first frame uses the original opcode and
continuation frames use the ‘continuation’ opcode.  Control messages
remain single final frames regardless of the option.


File: TheLogtalkHandbook-3.101.0.info,  Node: Current workflow<7>,  Next: Current limitations<15>,  Prev: Outgoing fragmentation,  Up: http_websocket_session

6.115.9 Current workflow
------------------------

   - Complete the opening handshake with ‘http_client::open_websocket/4’
     or ‘http_socket_transport::serve_websocket_once/5’.

   - Use the ‘http_websocket_messages’ layer when you only need
     stateless message normalization and simple reassembly.

   - Use the ‘http_websocket_session’ layer when you need stateful reads
     across interleaved control messages, close-state tracking,
     automatic close replies, optional auto-pong behavior, or role-aware
     outgoing fragmentation and masking.

   - Use the ‘http_websocket_service’ library when a callback object
     should own the connection lifecycle through higher-level session
     loops with optional keepalive, idle-timeout, and registry-backed
     broadcast policies.


File: TheLogtalkHandbook-3.101.0.info,  Node: Current limitations<15>,  Prev: Current workflow<7>,  Up: http_websocket_session

6.115.10 Current limitations
----------------------------

   - Fragmentation is controlled only by fixed payload chunk size.

   - Reserved-bit extension negotiation and extension semantics remain
     delegated to lower layers.


File: TheLogtalkHandbook-3.101.0.info,  Node: ica_projection,  Next: ids,  Prev: http_websocket_session,  Up: Libraries

6.116 ‘ica_projection’
======================

Independent Component Analysis reducer for continuous datasets (missing
or non-numeric values are rejected).  The library implements the
‘dimension_reducer_protocol’ defined in the
‘dimension_reduction_protocols’ library and learns a linear unmixing
projection by centering the training data, optionally standardizing
continuous attributes, whitening the covariance matrix using the shared
deterministic symmetric eigen-decomposition from ‘linear_algebra’, and
then extracting independent components using a deterministic cubic
FastICA fixed-point iteration with orthogonal deflation.

* Menu:

* API documentation: API documentation<135>.
* Loading: Loading<136>.
* Testing: Testing<128>.
* Features: Features<29>.
* Options: Options<28>.
* Usage: Usage<51>.
* Dimension reducer representation::
* References: References<18>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<135>,  Next: Loading<136>,  Up: ica_projection

6.116.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#ica_projection’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<136>,  Next: Testing<128>,  Prev: API documentation<135>,  Up: ica_projection

6.116.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(ica_projection(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<128>,  Next: Features<29>,  Prev: Loading<136>,  Up: ica_projection

6.116.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(ica_projection(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<29>,  Next: Options<28>,  Prev: Testing<128>,  Up: ica_projection

6.116.4 Features
----------------

   - 'Continuous Datasets': Accepts datasets containing only continuous
     attributes.

   - 'Shared Symmetric Whitening Plus Fixed-Point ICA': Whitens the
     training covariance matrix using the shared symmetric
     eigendecomposition from ‘linear_algebra’ and then extracts
     independent directions using deterministic cubic FastICA with
     orthogonal deflation.

   - 'Always Centered': Training and transform inputs are always
     centered using the training-set means before whitening and
     projection.

   - 'Optional Scaling': Can optionally standardize each continuous
     attribute before whitening.

   - 'Training Diagnostics': Records whitening eigenvalues plus
     per-component convergence reasons, iteration counts, and final
     deltas.

   - 'Projection API': Transforms a new instance into a list of
     ‘component_N-Value’ pairs.

   - 'Model Export': Learned reducers can be exported as predicate
     clauses or written to a file.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<28>,  Next: Usage<51>,  Prev: Features<29>,  Up: ica_projection

6.116.5 Options
---------------

The ‘learn/3’ predicate accepts the following options:

   - ‘n_components/1’: Number of independent components to extract.
     Because training data is always centered, requests that exceed
     ‘min(feature_count, sample_count - 1)’ raise
     ‘domain_error(component_count, Requested-Maximum)’.  Requests that
     still exceed the numerical rank of the whitened covariance matrix
     raise ‘domain_error(component_count, Requested-Extracted)’.  The
     default is ‘2’.

   - ‘feature_scaling/1’: Whether to divide each continuous attribute by
     its training-set standard deviation before whitening.  Options:
     ‘true’ or ‘false’ (default).

   - ‘maximum_iterations/1’: Maximum iteration bound used both by the
     whitening eigensolver and by the FastICA fixed-point steps for each
     independent component.  The default is ‘1000’.

   - ‘tolerance/1’: Positive convergence tolerance used both for
     whitening rank detection and for FastICA fixed-point stopping.  The
     default is ‘1.0e-8’.

The learned diagnostics also include:

   - ‘whitening_eigenvalues(Values)’: Eigenvalues used to build the
     whitening transform, aligned with the extracted components.

   - ‘convergence(Statuses)’: Per-component stop reasons, such as
     ‘tolerance’ or ‘maximum_iterations_exhausted’.

   - ‘iterations(Counts)’: Per-component iteration counts aligned with
     the extracted components.

   - ‘final_delta(Deltas)’: Per-component final update magnitudes
     aligned with the extracted components.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<51>,  Next: Dimension reducer representation,  Prev: Options<28>,  Up: ica_projection

6.116.6 Usage
-------------

The following examples use the sample dataset shipped with the
‘dimension_reduction_protocols’ library:

     | ?- logtalk_load(dimension_reduction_protocols('test_datasets/mixed_independent_sources')).

* Menu:

* Learning a reducer::
* Transforming new instances::
* Exporting and reusing the reducer::


File: TheLogtalkHandbook-3.101.0.info,  Node: Learning a reducer,  Next: Transforming new instances,  Up: Usage<51>

6.116.6.1 Learning a reducer
............................

     | ?- ica_projection::learn(mixed_independent_sources, DimensionReducer).

     | ?- ica_projection::learn(mixed_independent_sources, DimensionReducer, [n_components(2), feature_scaling(true), maximum_iterations(200), tolerance(1.0e-7)]).


File: TheLogtalkHandbook-3.101.0.info,  Node: Transforming new instances,  Next: Exporting and reusing the reducer,  Prev: Learning a reducer,  Up: Usage<51>

6.116.6.2 Transforming new instances
....................................

     | ?- ica_projection::learn(mixed_independent_sources, DimensionReducer),
          ica_projection::transform(DimensionReducer, [x1-(-5.0), x2-(-4.0), x3-(-4.0)], ReducedInstance).


File: TheLogtalkHandbook-3.101.0.info,  Node: Exporting and reusing the reducer,  Prev: Transforming new instances,  Up: Usage<51>

6.116.6.3 Exporting and reusing the reducer
...........................................

     | ?- ica_projection::learn(mixed_independent_sources, DimensionReducer, [n_components(2)]),
          ica_projection::export_to_file(mixed_independent_sources, DimensionReducer, reducer, 'ica_reducer.pl').

     | ?- logtalk_load('ica_reducer.pl'),
          reducer(Reducer),
          ica_projection::transform(Reducer, [x1-(-5.0), x2-(-4.0), x3-(-4.0)], ReducedInstance).


File: TheLogtalkHandbook-3.101.0.info,  Node: Dimension reducer representation,  Next: References<18>,  Prev: Usage<51>,  Up: ica_projection

6.116.7 Dimension reducer representation
----------------------------------------

The learned dimension reducer is represented by a compound term with the
functor chosen by the implementation and arity 3.  For example:

     ica_reducer(Encoders, Components, Diagnostics)

Where:

   - ‘Encoders’: List of continuous attribute encoders storing attribute
     name, centering offset, and scale factor.

   - ‘Components’: List of learned unmixing vectors in feature space.

   - ‘Diagnostics’: Learned reducer metadata including the effective
     training options, whitening eigenvalues, and per-component
     convergence information.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<18>,  Prev: Dimension reducer representation,  Up: ica_projection

6.116.8 References
------------------

  1. Hyvarinen, A. and Oja, E. (2000) - “Independent Component Analysis:
     Algorithms and Applications”.


File: TheLogtalkHandbook-3.101.0.info,  Node: ids,  Next: ieee_754,  Prev: ica_projection,  Up: Libraries

6.117 ‘ids’
===========

This library generates random identifiers given the number of bytes of
randomness.  The identifiers are Base64 encoded.  By default, 20 bytes
(160 bits) are used.

The generation of random identifiers uses the ‘/dev/urandom’ random
number generator when available.  This includes macOS, Linux, *BSD, and
other POSIX operating-systems.  On Windows, a pseudo-random generator is
used, but randomized using the current wall time.

Identifiers can be generated as atoms, lists of characters, or lists of
character codes.

See also the ‘cuid2’, ‘ksuid’, ‘nanoid’, ‘snowflakeid’, ‘uuid’, and
‘ulid’ libraries.

* Menu:

* API documentation: API documentation<136>.
* Loading: Loading<137>.
* Testing: Testing<129>.
* Usage: Usage<52>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<136>,  Next: Loading<137>,  Up: ids

6.117.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#ids’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<137>,  Next: Testing<129>,  Prev: API documentation<136>,  Up: ids

6.117.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(ids(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<129>,  Next: Usage<52>,  Prev: Loading<137>,  Up: ids

6.117.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(ids(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<52>,  Prev: Testing<129>,  Up: ids

6.117.4 Usage
-------------

To generate an identifier using the default 160 bits of randomness:

     | ?- ids::generate(Identifier).
     Identifier = '2gpMzqAFXBO5mYFIPX1qMkHxgGE='
     yes

To generate an identifier represented by an atom using 240 bits (30
bytes) of randomness:

     | ?- ids(atom, 30)::generate(Identifier).
     Identifier = 'ie/jYcLsqo8ZguCOF1ZNPFDRvJ03Ww5Qa9e0FxRB'
     yes

To generate an identifier represented by a list of characters using 64
bits (8 bytes) of randomness:

     | ?- ids(chars, 8)::generate(Identifier).
     Identifier = ['5','0','8','V',d,'S',c,y,n,o,'A',=]
     yes

To generate an identifier represented by a list of character codes using
64 bits (8 bytes) of randomness:

     | ?- ids(codes, 8)::generate(Identifier).
     Identifier = [111,81,86,55,99,79,70,77,65,74,103,61]
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: ieee_754,  Next: intervals,  Prev: ids,  Up: Libraries

6.118 ‘ieee_754’
================

The ‘ieee_754’ library is a support package for parsing and generating
IEEE 754 floating-point encodings shared by binary interchange libraries
such as ‘message_pack’, ‘avro’, ‘protobuf’, ‘cbor’, and ‘wkt_wkb’.

* Menu:

* Loading: Loading<138>.
* Testing: Testing<130>.
* Object model::
* Value representation::
* Public API: Public API<2>.
* Semantics::


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<138>,  Next: Testing<130>,  Up: ieee_754

6.118.1 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(ieee_754(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<130>,  Next: Object model,  Prev: Loading<138>,  Up: ieee_754

6.118.2 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(ieee_754(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Object model,  Next: Value representation,  Prev: Testing<130>,  Up: ieee_754

6.118.3 Object model
--------------------

The library provides two parameterized implementation objects:

     `ieee_754(Precision, ByteOrder, NaNRepresentation)`

‘ieee_754_fields(Precision, ByteOrder)’

with the following parameter values:

   - ‘Precision’: ‘half’, ‘single’, or ‘double’

   - ‘ByteOrder’: ‘big’ or ‘little’

   - ‘NaNRepresentation’: ‘canonical’ or ‘payloads’

The parameterization keeps format-specific policy out of the shared
core.  Advanced callers can use ‘ieee_754_fields’ to inspect exact sign,
exponent, mantissa, finite binary-rational decompositions, and NaN
payload bits without going through backend float values.


File: TheLogtalkHandbook-3.101.0.info,  Node: Value representation,  Next: Public API<2>,  Prev: Object model,  Up: ieee_754

6.118.4 Value representation
----------------------------

The intended term representation is:

   - finite values: backend Prolog floats

   - positive infinity: ‘@infinity’

   - negative infinity: ‘@negative_infinity’

   - canonical NaN: ‘@not_a_number’

   - payload-preserving NaN values: ‘not_a_number(Bytes)’

The ‘not_a_number(Bytes)’ representation is only intended to be accepted
and produced by objects configured with ‘NaNRepresentation = payloads’.

Under the ‘payloads’ policy, decoding a canonical quiet NaN should still
yield ‘@not_a_number’.  Non-canonical NaN encodings should decode to
‘not_a_number(Bytes)’ using canonical byte order for the selected
precision.

The high-level ‘ieee_754/3’ object API deliberately abstracts away the
IEEE 754 quiet-versus-signaling NaN distinction.  In ‘canonical’ mode,
all NaN encodings decode to ‘@not_a_number’.  In ‘payloads’ mode, the
designated canonical quiet NaN encoding decodes to ‘@not_a_number’ while
all other NaN encodings decode to ‘not_a_number(Bytes)’ for roundtrip
preservation.  Callers that need exact NaN inspection should use
‘ieee_754_fields/2’ object API.


File: TheLogtalkHandbook-3.101.0.info,  Node: Public API<2>,  Next: Semantics,  Prev: Value representation,  Up: ieee_754

6.118.5 Public API
------------------

The high-level value API is defined in ‘ieee_754_protocol.lgt’ and
consists of:

   - ‘parse/2’ Decodes ‘bytes(Bytes)’ or ‘bits(Bits)’ into a value term.

   - ‘generate/2’ Encodes a value term into ‘bytes(Bytes)’ or
     ‘bits(Bits)’.

   - ‘generate/3’ Encodes a value term to a byte list with an open tail
     for difference-list based binary generators.

   - ‘valid/1’ Checks whether a term is a valid value representation for
     the selected object.

   - ‘exactly_representable/1’ Checks whether a term can be encoded and
     decoded in the selected precision without loss of value
     information.

   - ‘precision/1’ Returns the selected precision.

   - ‘order/1’ Returns the selected byte order.

   - ‘nan_representation/1’ Returns the selected NaN representation
     policy.

   - ‘byte_count/1’ Returns the number of bytes used by the selected
     precision.

The low-level exact field API is defined in
‘ieee_754_fields_protocol.lgt’ and consists of:

   - ‘classify/2’ Classifies ‘bytes(Bytes)’ or ‘bits(Bits)’ as ‘zero’,
     ‘subnormal’, ‘normal’, ‘infinity’, or ‘not_a_number’.

   - ‘fields/5’ Extracts the exact sign bit, exponent bits, mantissa
     bits, and class.

   - ‘finite_binary_rational/4’ Extracts finite encodings as exact
     ‘(-1)^Sign * Significand * 2^Exponent’ terms.

   - ‘nan_payload/2’ Extracts the raw NaN mantissa payload bits.

   - ‘nan_kind/2’ Classifies a NaN encoding as ‘quiet’ or ‘signaling’.

   - ‘precision/1’ Returns the selected precision.

   - ‘order/1’ Returns the selected byte order.

   - ‘byte_count/1’ Returns the number of bytes used by the selected
     precision.


File: TheLogtalkHandbook-3.101.0.info,  Node: Semantics,  Prev: Public API<2>,  Up: ieee_754

6.118.6 Semantics
-----------------

The intended shared semantics are:

   - finite encoding rounds according to the selected IEEE 754 precision

   - ‘exactly_representable/1’ succeeds only when no value information
     is lost

   - signed zero is preserved when supported by the backend Prolog
     compiler

   - infinities and NaN values are represented independently from
     backend float syntax

   - subnormal values are supported for all selected precisions

   - payload-preserving NaN decoding is available when explicitly
     requested

   - the ‘ieee_754_fields’ API works from exact encodings and therefore
     does not depend on backend float decomposition behavior

   - exact quiet/signaling NaN inspection is exposed by
     ‘ieee_754_fields/2’ instead of the high-level value codec API


File: TheLogtalkHandbook-3.101.0.info,  Node: intervals,  Next: iqr_anomaly_detector,  Prev: ieee_754,  Up: Libraries

6.119 ‘intervals’
=================

This library provides:

   - an ‘interval_protocol’ protocol and an ‘interval’ object
     implementing the 13 Allen base interval relations plus interval
     pair classification using ‘relation/3’

   - an ‘interval_algebra_protocol’ protocol and an ‘interval_algebra’
     object implementing Allen relation algebra predicates over the 13
     base relation atoms

   - an ‘interval_relation_set_protocol’ protocol and an
     ‘interval_relation_set’ object implementing canonical relation-set
     operations over Allen base relation atoms

   - an ‘interval_constraint_network_protocol’ protocol and an
     ‘interval_constraint_network’ object implementing first interval
     constraint-network predicates over canonical relation sets,
     including batch refinement, explanation lists, and network
     inspection/comparison helpers

The ‘interval’ object works on interval terms represented as ‘i(Start,
End)’.  The ‘interval_algebra’ object works on relation atoms such as
‘before’, ‘overlaps’, and ‘contains’.  The ‘interval_relation_set’
object works on canonical ordered duplicate-free lists of relation
atoms.  The ‘interval_constraint_network’ object works on
‘network(Nodes, Constraints)’ terms whose pair constraints are relation
sets.  Internally, the ‘interval_constraint_network’ object compiles
that public representation to an a dense indexed form for propagation
and for most query operations, while still returning ordinary
‘network/2’ terms at the API boundary.

The ‘interval_algebra::compose/3’ predicate returns canonical ordered
duplicate-free lists of base relation atoms.

* Menu:

* Practical limits::
* API documentation: API documentation<137>.
* Loading: Loading<139>.
* Testing: Testing<131>.
* Examples: Examples<172>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Practical limits,  Next: API documentation<137>,  Up: intervals

6.119.1 Practical limits
------------------------

The ‘interval_constraint_network’ object is intended for small-to-medium
symbolic networks.  It uses a complete ‘network(Nodes, Constraints)’
representation, so the number of stored pair constraints grows
quadratically with the number of nodes.  Propagation is based on path
consistency and now uses an internal dense indexed representation with
direct pair access, a reverse node-to-index table, and scheduled-pair
tracking to avoid repeated linear worklist duplicate checks.  This
substantially reduces overhead relative to a purely list-based
implementation, but the representation is still dense and updates still
rebuild parts of the internal matrix before the result is decompiled
back to a public ‘network/2’ term.

In practice, the network predicates are suitable for moderate
qualitative temporal reasoning workloads, but they should not be treated
as a large-scale or latency-sensitive temporal CSP solver.  Exact limits
depend on the Prolog backend, network density, how often closure is
recomputed, and how often callers invoke single-step API operations that
must compile or decompile the public network representation.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<137>,  Next: Loading<139>,  Prev: Practical limits,  Up: intervals

6.119.2 API documentation
-------------------------

Open the ‘../../apis/library_index.html#intervals’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<139>,  Next: Testing<131>,  Prev: API documentation<137>,  Up: intervals

6.119.3 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(intervals(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<131>,  Next: Examples<172>,  Prev: Loading<139>,  Up: intervals

6.119.4 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(intervals(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<172>,  Prev: Testing<131>,  Up: intervals

6.119.5 Examples
----------------

Classify two valid intervals according to their unique Allen base
relation:

     | ?- interval::new(1, 3, I1), interval::new(3, 5, I2), interval::relation(I1, I2, Relation).
     Relation = meets.

Compose two Allen base relation atoms:

     | ?- interval_algebra::compose(meets, met_by, Relations).
     Relations = [finishes, finished_by, equal].

Normalize an Allen relation set:

     | ?- interval_relation_set::normalize([during, before, during], RelationSet).
     RelationSet = [before, during].

Propagate interval constraints across a small symbolic network:

     | ?- interval_constraint_network::new([a, b, c], Network0),
          interval_constraint_network::refine(Network0, a, b, [before], Network1),
          interval_constraint_network::refine(Network1, b, c, [before], Network2),
          interval_constraint_network::path_consistency(Network2, Network3),
          interval_constraint_network::relation(Network3, a, c, RelationSet).
     RelationSet = [before].

Check whether a query is entailed by the current symbolic constraints:

     | ?- interval_constraint_network::entails(Network3, a, c, [before, meets]).
     true.

Inspect a simple explanation for an entailed relation:

     | ?- interval_constraint_network::entails(Network3, a, c, [before], Explanation).
     Explanation = propagated(b, [before], [before], [before]).

Inspect a simple contradiction explanation after closure:

     | ?- interval_constraint_network::contradiction(Closure, Explanation).
     Explanation = contradiction(a, c, propagated(b, [before], [before], [before])).

Refine and propagate in a single operation that fails on contradiction:

     | ?- interval_constraint_network::new([a, b, c], Network0),
          interval_constraint_network::refine_propagate(Network0, a, b, [before], Network1).
     Network1 = ...

Post a batch of constraints and propagate them in one step:

     | ?- interval_constraint_network::refine_propagate(Network0, [constraint(a, b, [before]), constraint(b, c, [before])], Network1).
     Network1 = ...

Collect direct and propagated changes while propagating:

     | ?- interval_constraint_network::propagate(Network2, Network3, Changes).
     Changes = [...].

Query which node triples caused the propagated refinements:

     | ?- interval_constraint_network::propagation_triples(Changes, Triples).
     Triples = [triple(a, b, c)].

List all immediate explanations supporting an entailed query:

     | ?- interval_constraint_network::entailment_explanations(Network3, a, c, [before, meets], Explanations).
     Explanations = [propagated(b, [before], [before], [before])].

List all contradiction explanations currently present in an inconsistent
network:

     | ?- interval_constraint_network::contradiction_explanations(Closure, Explanations).
     Explanations = [...].

Inspect a closure and compare networks by generality or equivalence:

     | ?- interval_constraint_network::constraints(Network3, Constraints).
     Constraints = [constraint(a, b, [before]), constraint(a, c, [before]), constraint(b, c, [before])].

     | ?- interval_constraint_network::subsumes(Network0, Network3).
     true.

     | ?- interval_constraint_network::equivalent(Network3, Network5).
     true.


File: TheLogtalkHandbook-3.101.0.info,  Node: iqr_anomaly_detector,  Next: iso_639,  Prev: intervals,  Up: Libraries

6.120 ‘iqr_anomaly_detector’
============================

Statistical interquartile-range anomaly detector for continuous
datasets.  It is a statistical anomaly-detection method based on Tukey
interquartile fences: for each known continuous attribute value it
learns ‘Q1’ and ‘Q3’, computes the exceedance beyond ‘[Q1,Q3]’ in
interquartile-range units normalized by the learned
‘fence_multiplier/1’, and then aggregates the per-attribute normalized
deviations according to ‘score_mode/1’, so any value at or beyond ‘[Q1 -
k*IQR, Q3 + k*IQR]’ reaches the default anomaly boundary when using
‘fence_multiplier(k)’.

The library implements the ‘anomaly_detector_protocol’ defined in the
‘anomaly_detection_protocols’ library.  It learns a detector from a
continuous dataset, computes anomaly scores for new instances, predicts
‘normal’ or ‘anomaly’, and exports learned detectors as clauses or
files.

Datasets are represented as objects implementing the
‘anomaly_dataset_protocol’ protocol from the
‘anomaly_detection_protocols’ library.  See the
‘anomaly_detection_protocols/test_datasets’ directory for examples.

* Menu:

* API documentation: API documentation<138>.
* Loading: Loading<140>.
* Testing: Testing<132>.
* Features: Features<30>.
* Options: Options<29>.
* Detector representation: Detector representation<3>.
* Notes: Notes<7>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<138>,  Next: Loading<140>,  Up: iqr_anomaly_detector

6.120.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#iqr_anomaly_detector’ link in a
web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<140>,  Next: Testing<132>,  Prev: API documentation<138>,  Up: iqr_anomaly_detector

6.120.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(iqr_anomaly_detector(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<132>,  Next: Features<30>,  Prev: Loading<140>,  Up: iqr_anomaly_detector

6.120.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(iqr_anomaly_detector(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<30>,  Next: Options<29>,  Prev: Testing<132>,  Up: iqr_anomaly_detector

6.120.4 Features
----------------

   - 'Statistical method': implements anomaly detection based on
     interquartile-range fences, using per-attribute first and third
     quartiles to measure how far new observations deviate from the
     central baseline distribution.

   - 'Quartile-based scoring': for each known attribute value ‘x’, the
     library computes the positive exceedance of ‘x’ beyond the interval
     ‘[Q1, Q3]’ in interquartile-range units, where ‘Q1’ and ‘Q3’ are
     the learned sample quartiles.

   - 'Continuous features only': accepts datasets whose declared
     attributes are all ‘continuous’.

   - 'Robust statistics': reuses the ‘statistics’ library ‘sample’
     object ‘quartiles/4’ predicate to compute per-attribute quartiles.

   - 'Baseline training selection': supports learn-time
     ‘baseline_class_values(ClassValues)’ and
     ‘baseline_selection_policy(Policy)’ options.  The default baseline
     class values are ‘[normal]’.  The default ‘reject’ policy throws an
     error if non-baseline examples are present, while ‘filter’ removes
     them before fitting.

   - 'Missing-value tolerant': ignores missing values when fitting
     attribute statistics.  During scoring, queries must provide at
     least one known value.  In the default
     ‘score_mode(root_mean_square)’, the raw score is aggregated over
     attributes with positive normalized deviation so that neutral
     inlier attributes do not dilute fence anomalies.  The learned
     detector stores a precomputed attribute schema so that scoring
     reuses the same attribute ordering without rebuilding it on every
     call.

   - 'Configurable scoring semantics': supports both dense multivariate
     deviation scoring using ‘score_mode(root_mean_square)’ and sparse
     anomaly detection using ‘score_mode(any_feature_extreme)’.  The
     default root-mean-square mode reuses the ‘numberlist’ library
     Euclidean norm predicate as part of the computation.

   - 'Configurable Tukey fences': supports a learn-time
     ‘fence_multiplier/1’ option.  The default ‘1.5’ corresponds to the
     classical Tukey inner fence cutoff, and the learned multiplier is
     applied directly in the score path.

   - 'Bounded scoring': maps the raw multivariate IQR score to ‘[0.0,
     1.0)’ using ‘Score = Raw / (1 + Raw)’.

   - 'Default threshold': the default ‘anomaly_threshold(0.5)’
     corresponds to the learned Tukey fence cutoff after score scaling,
     while remaining overrideable in ‘learn/3’ and ‘predict/4’.

   - 'Learn-time options': ‘fence_multiplier/1’ and ‘score_mode/1’ are
     recorded in the learned detector and reused for subsequent scoring
     and prediction.  Passing either option to ‘predict/4’ does not
     override the learned value.

   - 'All-missing queries rejected': scoring and prediction throw a
     ‘domain_error(non_empty_known_values, AttributeNames)’ exception
     when every declared feature is missing in the query.

   - 'Featureless datasets rejected': datasets must declare at least one
     continuous feature; otherwise ‘learn/2-3’ throws a
     ‘domain_error(non_empty_features, Dataset)’ exception.

   - 'Detector export': learned detectors can be exported as predicate
     clauses.

   - 'Explicit validation and diagnostics': supports the shared
     ‘check_anomaly_detector/1’, ‘valid_anomaly_detector/1’,
     ‘diagnostics/2’, ‘diagnostic/2’, and ‘anomaly_detector_options/2’
     predicates.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<29>,  Next: Detector representation<3>,  Prev: Features<30>,  Up: iqr_anomaly_detector

6.120.5 Options
---------------

The following options are supported by the public API:

   - ‘anomaly_threshold(Threshold)’: Threshold for ‘predict/3-4’
     (default: ‘0.5’)

   - ‘baseline_class_values(ClassValues)’: Learn-time class labels that
     are admissible for baseline fitting (default: ‘[normal]’)

   - ‘baseline_selection_policy(Policy)’: Learn-time handling of
     examples whose class is not listed in ‘baseline_class_values/1’.
     Supported values are ‘filter’ and ‘reject’ (default: ‘reject’)

   - ‘fence_multiplier(Multiplier)’: Learn-time Tukey fence multiplier
     stored in the learned detector (default: ‘1.5’)

   - ‘score_mode(Mode)’: Learn-time score aggregation mode for
     ‘learn/3’.  Supported values are ‘root_mean_square’ and
     ‘any_feature_extreme’ (default: ‘root_mean_square’).  If passed to
     ‘predict/4’, it is ignored and the value stored in the learned
     detector is used.


File: TheLogtalkHandbook-3.101.0.info,  Node: Detector representation<3>,  Next: Notes<7>,  Prev: Options<29>,  Up: iqr_anomaly_detector

6.120.6 Detector representation
-------------------------------

The learned detector is represented by default as:

     iqr_detector(TrainingDataset, AttributeSchema, Encoders, Diagnostics)

Where:

   - ‘TrainingDataset’: training dataset object identifier

   - ‘AttributeSchema’: precomputed attribute ordering used for
     validation and scoring

   - ‘Encoders’: list of ‘iqr_anomaly_detector(Attribute, Q1, Q3,
     Scale)’ records

   - ‘Diagnostics’: learned metadata terms including ‘model/1’,
     ‘training_dataset/1’, ‘attribute_names/1’, ‘feature_count/1’,
     ‘example_count/1’, and ‘options/1’

When exported using ‘export_to_clauses/4’ or ‘export_to_file/4’, this
detector term is serialized directly as the single argument of the
generated predicate clause so that the exported model can be loaded and
reused as-is.


File: TheLogtalkHandbook-3.101.0.info,  Node: Notes<7>,  Prev: Detector representation<3>,  Up: iqr_anomaly_detector

6.120.7 Notes
-------------

Scoring has three stages.  First, the detector computes one
per-attribute IQR deviation score for each known attribute value using
its exceedance beyond the interval ‘[Q1, Q3]’ in interquartile-range
units.  Second, each per-attribute score is normalized by the learned
‘fence_multiplier/1’, so that it reaches ‘1.0’ exactly at the chosen
Tukey fence cutoff.  Third, those normalized per-attribute scores are
aggregated into a single raw deviation score according to the learned
‘score_mode/1’ option before being mapped to the interval ‘[0.0, 1.0)’
using ‘Score = Raw / (1 + Raw)’.

The ‘score_mode/1’ option does not change the per-attribute quartile
formula.  It only changes the aggregation step.  With
‘score_mode(root_mean_square)’, the raw score is the root mean square of
the positive normalized per-attribute deviations, computed over the
attributes with positive deviation so that inlier padding does not
dilute fence-reaching anomalies.  With
‘score_mode(any_feature_extreme)’, the raw score is the maximum
normalized per-attribute deviation.

The ‘fence_multiplier/1’ option defines the classical Tukey anomaly
cutoff and directly normalizes the per-attribute deviation scores.  With
any learned ‘fence_multiplier(K)’, a per-attribute score of ‘1.0’ means
the query has reached the chosen Tukey fence on that attribute, so the
default normalized threshold ‘0.5’ corresponds to that cutoff in both
supported aggregation modes.

The ‘baseline_class_values/1’ option declares which dataset class labels
are admissible for fitting the baseline quartiles and interquartile
ranges.  The ‘baseline_selection_policy/1’ option then controls what
happens when other labels are present in the training data.  The default
‘reject’ policy raises a ‘domain_error(baseline_only_training_data,
Dataset)’ exception when any non-baseline example is found.  The
‘filter’ policy removes non-baseline examples before fitting.

Attributes with zero observed interquartile range are assigned a
fallback scale of ‘1.0’.  This keeps the detector well-defined for
singleton datasets or constant columns while still yielding zero score
for matching values and positive scores for deviating values.

The root-mean-square aggregation keeps the default threshold stable
while avoiding dilution from missing or neutral inlier attributes.

Use ‘score_mode(any_feature_extreme)’ when a single extreme feature
should be sufficient to flag an anomaly in high-dimensional data.


File: TheLogtalkHandbook-3.101.0.info,  Node: iso_639,  Next: iso_3166,  Prev: iqr_anomaly_detector,  Up: Libraries

6.121 ‘iso_639’
===============

This library provides ISO 639 sets 1, 2, 3, and 5 lookups generated from
the Library of Congress and SIL maintenance-agency sources.  It requires
Unicode support from the backend Prolog compiler.

The set 1 and set 2 data are generated from the Library of Congress ISO
639-2 code list.  The set 3 data are generated from the SIL
tab-delimited code set download.  The set 5 data are generated from the
Library of Congress ISO 639-5 identifier list.

The refresh tooling lives in ‘library/iso_639/scripts/’ together with
the checked-in source snapshots used to regenerate the fact tables using
shell scripts only.

* Menu:

* API documentation: API documentation<139>.
* Loading: Loading<141>.
* Testing: Testing<133>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<139>,  Next: Loading<141>,  Up: iso_639

6.121.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#iso_639’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<141>,  Next: Testing<133>,  Prev: API documentation<139>,  Up: iso_639

6.121.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(iso_639(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<133>,  Prev: Loading<141>,  Up: iso_639

6.121.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(iso_639(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: iso_3166,  Next: iso_4217,  Prev: iso_639,  Up: Libraries

6.122 ‘iso_3166’
================

This library provides generated ISO 3166 country and subdivision code
lookups.  The current worktree includes a real ISO 3166-1 fact table
generated from the official United Nations M49 overview page, which
republishes ISO alpha-2 and alpha-3 country codes together with the M49
numeric codes used here.  It requires Unicode support from the backend
Prolog compiler.

ISO 3166-2 subdivision data is bundled in the public facade and
generated from the Debian ‘iso-codes’ machine-readable JSON snapshot.
Subdivision codes and country alpha-2 codes are stored as lowercase
atoms to match the conventions used by the generated ISO 3166-1 country
fact table, while names and categories preserve the source spelling.

To refresh the generated subdivision table, run:

     $ library/iso_3166/scripts/update_iso_3166_2.sh

* Menu:

* API documentation: API documentation<140>.
* Loading: Loading<142>.
* Testing: Testing<134>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<140>,  Next: Loading<142>,  Up: iso_3166

6.122.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#iso_3166’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<142>,  Next: Testing<134>,  Prev: API documentation<140>,  Up: iso_3166

6.122.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(iso_3166(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<134>,  Prev: Loading<142>,  Up: iso_3166

6.122.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(iso_3166(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: iso_4217,  Next: iso_9362,  Prev: iso_3166,  Up: Libraries

6.123 ‘iso_4217’
================

This library provides ISO 4217 active non-fund currency code lookups
generated from the authoritative SIX maintenance-agency XML list
together with active fund currency code lookups.  It requires Unicode
support from the backend Prolog compiler.

The generated fact table keeps one entry per XML row with a currency
code, therefore preserving entity-specific assignments for shared
currencies such as the Euro or the US Dollar.  Rows marked by SIX as
fund entries are exposed using the ‘fund_currency/5’ predicate while the
‘currency/5’ predicate remains scoped to non-fund entries.  Minor units
are represented either as integers or the atom ‘na’ when the source
lists ‘N.A.’.

* Menu:

* API documentation: API documentation<141>.
* Loading: Loading<143>.
* Testing: Testing<135>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<141>,  Next: Loading<143>,  Up: iso_4217

6.123.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#iso_4217’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<143>,  Next: Testing<135>,  Prev: API documentation<141>,  Up: iso_4217

6.123.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(iso_4217(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<135>,  Prev: Loading<143>,  Up: iso_4217

6.123.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(iso_4217(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: iso_9362,  Next: iso_13616,  Prev: iso_4217,  Up: Libraries

6.124 ‘iso_9362’
================

This library provides ISO 9362 Business Identifier Code (BIC) structure
parsing and normalization based on the public Swift and ISO 9362
documentation.  It requires Unicode support from the backend Prolog
compiler.

The current public implementation focuses on the normative structure
that Swift and ISO 9362 publish openly: a BIC consists of a 4-character
business party prefix, a 2-character ISO 3166-1 alpha-2 country code, a
2-character business party suffix, and an optional 3-character branch
identifier.  Eight-character primary-office BICs are normalized to the
branch code ‘XXX’.

This library does not currently ship the full ISO 9362 directory as
facts.  The public SwiftRef TXT directory download is available only
through a secure, time-limited email link, so it is not treated as an
automatable checked-in source snapshot in the same way as the ISO 4217
and ISO 639 libraries.

* Menu:

* API documentation: API documentation<142>.
* Loading: Loading<144>.
* Testing: Testing<136>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<142>,  Next: Loading<144>,  Up: iso_9362

6.124.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#iso_9362’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<144>,  Next: Testing<136>,  Prev: API documentation<142>,  Up: iso_9362

6.124.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(iso_9362(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<136>,  Prev: Loading<144>,  Up: iso_9362

6.124.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(iso_9362(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: iso_13616,  Next: isolation_forest_anomaly_detector,  Prev: iso_9362,  Up: Libraries

6.125 ‘iso_13616’
=================

This library provides ISO 13616 International Bank Account Number (IBAN)
structure parsing, checksum validation, and normalization based on the
public ISO 13616 and Swift IBAN registry documentation.  It requires
Unicode support from the backend Prolog compiler.

The current public implementation includes a checked-in snapshot of the
public SWIFT IBAN registry for all currently registered IBAN countries.
Validation therefore checks:

   - the ISO 3166-1 alpha-2 country code

   - the country-specific total IBAN length

   - the country-specific BBAN structure pattern

   - the standard MOD-97 checksum

The checked-in registry facts use a derived Prolog segment
representation for BBAN patterns, e.g.  ‘[a-4, n-6, n-8]’ instead of the
original SWIFT text syntax ‘4!a6!n8!n’.  This keeps the published
structure information while making validation code simpler and more
direct.

The public API remains structural.  The library validates the published
national IBAN formats but does not attempt to ship any bank directory or
account existence data beyond the public registry pattern definitions.

* Menu:

* API documentation: API documentation<143>.
* Loading: Loading<145>.
* Testing: Testing<137>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<143>,  Next: Loading<145>,  Up: iso_13616

6.125.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#iso_13616’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<145>,  Next: Testing<137>,  Prev: API documentation<143>,  Up: iso_13616

6.125.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(iso_13616(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<137>,  Prev: Loading<145>,  Up: iso_13616

6.125.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(iso_13616(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: isolation_forest_anomaly_detector,  Next: java,  Prev: iso_13616,  Up: Libraries

6.126 ‘isolation_forest_anomaly_detector’
=========================================

This library implements the Extended Isolation Forest (EIF) algorithm
for anomaly detection as described by Hariri et al.  (2019).  The
Extended Isolation Forest improves upon the original Isolation Forest
algorithm (Liu et al., 2008) by using random hyperplane cuts instead of
axis-aligned cuts, eliminating bias artifacts in anomaly scores along
coordinate axes.  Learning fits the forest from baseline training
examples selected from the dataset class labels.

The algorithm builds an ensemble of isolation trees (iTrees) by
recursively partitioning data using random hyperplanes.  Anomalous
points, being few and different from normal points, require fewer
partitions (shorter path lengths) to be isolated.  The anomaly score for
an instance is computed based on the average path length across all
trees in the forest.

Datasets are represented as objects implementing the
‘anomaly_dataset_protocol’ protocol from the
‘anomaly_detection_protocols’ library.  See the
‘anomaly_detection_protocols/test_datasets’ directory for examples.

* Menu:

* API documentation: API documentation<144>.
* Loading: Loading<146>.
* Testing: Testing<138>.
* Implemented features: Implemented features<2>.
* Options: Options<30>.
* Detector representation: Detector representation<4>.
* Limitations: Limitations<4>.
* References: References<19>.
* Usage: Usage<53>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<144>,  Next: Loading<146>,  Up: isolation_forest_anomaly_detector

6.126.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#isolation-forest’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<146>,  Next: Testing<138>,  Prev: API documentation<144>,  Up: isolation_forest_anomaly_detector

6.126.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(isolation_forest_anomaly_detector(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<138>,  Next: Implemented features<2>,  Prev: Loading<146>,  Up: isolation_forest_anomaly_detector

6.126.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(isolation_forest_anomaly_detector(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Implemented features<2>,  Next: Options<30>,  Prev: Testing<138>,  Up: isolation_forest_anomaly_detector

6.126.4 Implemented features
----------------------------

   - Extended Isolation Forest with random hyperplane cuts: splits are
     defined by random normal vectors and intercept points drawn from
     the data range, producing ‘(x - p) * n =< 0’ partitions that
     generalize to arbitrary orientations

   - Configurable extension level: level 0 corresponds to the original
     axis-aligned Isolation Forest; levels up to ‘d - 1’ (the default)
     use fully extended random hyperplanes where ‘d’ is the number of
     dimensions

   - Anomaly score computation following Liu et al.  (2008): ‘s(x) =
     2^(-E(h(x)) / c(psi))’ where ‘E(h(x))’ is the average path length
     across all trees, ‘c(psi)’ is the average path length of
     unsuccessful searches in a BST, and ‘psi’ is the subsample size

   - Handling of both continuous (numeric) and discrete (categorical)
     attributes: discrete attributes are mapped to numeric indices based
     on their position in the attribute value list declared by the
     dataset

   - Baseline training selection: ‘baseline_class_values/1’ declares
     which class labels are admissible for fitting the forest, while
     ‘baseline_selection_policy/1’ controls whether non-baseline
     examples are rejected (default) or filtered before training

   - Handling of missing attribute values (represented using anonymous
     variables): during tree construction, missing values are replaced
     with random values drawn from the observed range of the
     corresponding attribute; during scoring, each internal tree node
     stores its own feasible per-dimension bounds so that missing
     dimensions can be routed using subtree-local support instead of
     only the global training ranges

   - Scoring all dataset instances with results sorted by descending
     anomaly score for easy identification of top anomalies

   - Pretty-printing of learned models with tree depth and node count
     summaries

   - Learning rejects empty datasets with a
     ‘domain_error(non_empty_dataset, Dataset)’ exception


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<30>,  Next: Detector representation<4>,  Prev: Implemented features<2>,  Up: isolation_forest_anomaly_detector

6.126.5 Options
---------------

The following options can be passed to the ‘learn/3’ and ‘predict/4’
predicates:

   - ‘number_of_trees(N)’: number of isolation trees to build (default:
     ‘100’)

   - ‘subsample_size(N)’: subsample size used to build each isolation
     tree.  When omitted, the implementation uses ‘256’ or the number of
     training instances if smaller

   - ‘extension_level(N)’: controls the dimensionality of the random
     hyperplane cuts.  ‘0’ reproduces the original axis-aligned
     Isolation Forest; when omitted, the implementation uses ‘d - 1’,
     where ‘d’ is the number of dimensions

   - ‘anomaly_threshold(T)’: threshold used by ‘predict/3-4’ (default:
     ‘0.5’)

   - ‘baseline_class_values(Classes)’: learn-time list of admissible
     baseline class labels (default: ‘[normal]’)

   - ‘baseline_selection_policy(Policy)’: learn-time handling of
     non-baseline examples.  Supported values are ‘reject’ (default) and
     ‘filter’


File: TheLogtalkHandbook-3.101.0.info,  Node: Detector representation<4>,  Next: Limitations<4>,  Prev: Options<30>,  Up: isolation_forest_anomaly_detector

6.126.6 Detector representation
-------------------------------

The learned detector is represented by default as:

     if_model(Trees, Psi, AttributeNames, Attributes, Ranges, Diagnostics)

Where:

   - ‘Trees’: List of learned isolation trees

   - ‘Psi’: Effective subsample size used to build each tree

   - ‘AttributeNames’: List of attribute names in order

   - ‘Attributes’: List of ‘Attribute-Values’ declarations from the
     training dataset

   - ‘Ranges’: Observed numeric ranges used for imputing missing values
     during training

   - ‘Diagnostics’: Learned metadata terms including ‘model/1’,
     ‘tree_count/1’, ‘subsample_size/1’, ‘attribute_names/1’,
     ‘feature_count/1’, and ‘options/1’

Each internal tree node additionally stores node-local dimension bounds
used when resolving missing-value routing during scoring.

When exported using ‘export_to_clauses/4’ or ‘export_to_file/4’, this
detector term is serialized directly as the single argument of the
generated predicate clause so that the exported model can be loaded and
reused as-is.


File: TheLogtalkHandbook-3.101.0.info,  Node: Limitations<4>,  Next: References<19>,  Prev: Detector representation<4>,  Up: isolation_forest_anomaly_detector

6.126.7 Limitations
-------------------

   - No incremental learning (the forest must be rebuilt from scratch
     when new examples are added)

   - No streaming or online variant


File: TheLogtalkHandbook-3.101.0.info,  Node: References<19>,  Next: Usage<53>,  Prev: Limitations<4>,  Up: isolation_forest_anomaly_detector

6.126.8 References
------------------

   - Liu, F.T., Ting, K.M. and Zhou, Z.-H. (2008).  Isolation Forest.
     'Proceedings of the 2008 Eighth IEEE International Conference on
     Data Mining', 413-422.  ‘https://doi.org/10.1109/ICDM.2008.17’

   - Hariri, S., Kind, M.C. and Brunner, R.J. (2019).  Extended
     Isolation Forest.  'IEEE Transactions on Knowledge and Data
     Engineering', 33(4), 1479-1489.
     ‘https://doi.org/10.1109/TKDE.2019.2947676’


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<53>,  Prev: References<19>,  Up: isolation_forest_anomaly_detector

6.126.9 Usage
-------------

To learn an isolation forest model from a dataset with default options:

| ?- isolation_forest_anomaly_detector::learn(gaussian_anomalies, Model,
[baseline_selection_policy(filter)]).

To learn with custom options:

     | ?- isolation_forest_anomaly_detector::learn(gaussian_anomalies, Model, [
            baseline_selection_policy(filter),
              number_of_trees(200),
              subsample_size(128),
              extension_level(1),
              anomaly_threshold(0.6)
          ]).

To compute the anomaly score for a new instance:

| ?- isolation_forest_anomaly_detector::learn(gaussian_anomalies, Model,
[baseline_selection_policy(filter)]),
isolation_forest_anomaly_detector::score(Model, [x-0.12, y-0.34],
Score).

To predict whether an instance is an anomaly or normal:

| ?- isolation_forest_anomaly_detector::learn(gaussian_anomalies, Model,
[baseline_selection_policy(filter)]),
isolation_forest_anomaly_detector::predict(Model, [x-4.50, y-4.20],
Prediction).

To compute and rank anomaly scores for all instances in a dataset:

| ?- isolation_forest_anomaly_detector::learn(gaussian_anomalies, Model,
[baseline_selection_policy(filter)]),
isolation_forest_anomaly_detector::score_all(gaussian_anomalies, Model,
Scores).

The ‘Scores’ list contains ‘Id-Class-Score’ triples sorted by descending
anomaly score.  This makes it easy to inspect top anomalies:

| ?- isolation_forest_anomaly_detector::learn(gaussian_anomalies, Model,
[baseline_selection_policy(filter)]),
isolation_forest_anomaly_detector::score_all(gaussian_anomalies, Model,
[Top1, Top2, Top3| _]).

To print a summary of the learned model:

| ?- isolation_forest_anomaly_detector::learn(gaussian_anomalies, Model,
[baseline_selection_policy(filter)]),
isolation_forest_anomaly_detector::print_anomaly_detector(Model).

To use the original (non-extended) Isolation Forest, set the extension
level to 0:

| ?- isolation_forest_anomaly_detector::learn(gaussian_anomalies, Model,
[baseline_selection_policy(filter), extension_level(0)]).


File: TheLogtalkHandbook-3.101.0.info,  Node: java,  Next: json,  Prev: isolation_forest_anomaly_detector,  Up: Libraries

6.127 ‘java’
============

The library Java entities define a minimal abstraction for calling Java
from Logtalk.  This abstraction makes use of Logtalk parametric objects
and allows creating Java objects, accessing Java class fields, and
calling Java class and object methods using syntax closer to Logtalk.
It also gives access to some Java utility predicates.

This abstraction was developed primarily to work with XVM (with its
‘jni’ plug-in installed) or the JPL library bundled with SWI-Prolog and
YAP. However, it’s expected to be implementable with alternative Java
interfaces found in other backend Prolog compilers.  Currently, a
preliminary implementation is also available for JIProlog.

The main idea in this abstraction layer is to use parametric objects
where the first parameter holds the Java reference (usually to a class
or object) and an optional second parameter holds the return value.
Together with a forward message handler, this allows the use of Java
messages with the same functor and number of arguments as found in the
relevant JavaDocs.

* Menu:

* API documentation: API documentation<145>.
* Loading: Loading<147>.
* Testing: Testing<139>.
* Usage: Usage<54>.
* Known issues: Known issues<11>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<145>,  Next: Loading<147>,  Up: java

6.127.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#java’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<147>,  Next: Testing<139>,  Prev: API documentation<145>,  Up: java

6.127.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(java(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<139>,  Next: Usage<54>,  Prev: Loading<147>,  Up: java

6.127.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(java(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<54>,  Next: Known issues<11>,  Prev: Testing<139>,  Up: java

6.127.4 Usage
-------------

The two main objects in this library are ‘java(Reference, ReturnValue)’
and ‘java(Reference)’.  Use the latter if you want to ignore the return
value or when calling a void Java method.

The ‘java’ object implements utility predicates.  For some backend Java
interfaces such as JPL (available in SWI-Prolog, XVM, and YAP) there is
also a ‘java_hook’ hook object for removing any overhead when using this
library abstraction.

For usage examples and additional tests, see the ‘clustering’,
‘document_converter’, ‘jpl’, and ‘neo4j’ examples.


File: TheLogtalkHandbook-3.101.0.info,  Node: Known issues<11>,  Prev: Usage<54>,  Up: java

6.127.5 Known issues
--------------------

When running Java GUI examples on the macOS Terminal application, you
may get a Java error saying that the AWT cannot be started.  In
alternative, try to run the example from within the SWI-Prolog macOS
application instead of using the shell integration script.  This issue
is due to a macOS Java issue that’s orthogonal to both Prolog backends
and Logtalk.


File: TheLogtalkHandbook-3.101.0.info,  Node: json,  Next: json_graph,  Prev: java,  Up: Libraries

6.128 ‘json’
============

The ‘json’ library provides predicates for parsing and generating data
in the JSON format based on the specification and standard found at:

   - ‘https://www.rfc-editor.org/rfc/rfc8259’

   - 
     ‘https://ecma-international.org/publications-and-standards/standards/ecma-404/’

It includes parametric objects whose parameters allow selecting the
representation for parsed JSON objects (‘curly’ or ‘list’), JSON text
strings (‘atom’, ‘chars’, or ‘codes’) and JSON pairs (‘dash’, ‘equal’,
or ‘colon’).

* Menu:

* API documentation: API documentation<146>.
* Loading: Loading<148>.
* Testing: Testing<140>.
* Representation: Representation<11>.
* Encoding: Encoding<7>.
* Decoding: Decoding<7>.
* Known issues: Known issues<12>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<146>,  Next: Loading<148>,  Up: json

6.128.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#json’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<148>,  Next: Testing<140>,  Prev: API documentation<146>,  Up: json

6.128.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(json(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<140>,  Next: Representation<11>,  Prev: Loading<148>,  Up: json

6.128.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(json(tester)).

Some of the sample JSON test files are based on examples published at:

‘https://www.json.org/’


File: TheLogtalkHandbook-3.101.0.info,  Node: Representation<11>,  Next: Encoding<7>,  Prev: Testing<140>,  Up: json

6.128.4 Representation
----------------------

The following choices of syntax have been made to represent JSON
elements as terms:

   - By default, JSON objects are represented using curly-bracketed
     terms, ‘{Pairs}’, where each pair uses the representation
     ‘Key-Value’ (see below for alternative representations).

   - Arrays are represented using lists.

   - Text strings can be represented as atoms, ‘chars(List)’, or
     ‘codes(List)’.  The default when decoding is to use atoms when
     using the ‘json’ object.  To decode text strings into lists of
     chars or codes, use the ‘json/1’ with the parameter bound to
     ‘chars’ or ‘codes’.  For example:

          | ?- json::parse(codes([34,104,101,108,108,111,34]), Term).
          Term = hello
          yes

          | ?- json(atom)::parse(codes([34,104,101,108,108,111,34]), Term).
          Term = hello
          yes

          | ?- json(chars)::parse(codes([34,104,101,108,108,111,34]), Term).
          Term = chars([h,e,l,l,o])
          yes

          | ?- json(codes)::parse(codes([34,104,101,108,108,111,34]), Term).
          Term = codes([104,101,108,108,111])
          yes

   - The JSON values ‘false’, ‘true’ and ‘null’ are represented by,
     respectively, the ‘@false’, ‘@true’ and ‘@null’ compound terms.

The following table exemplifies the term equivalents of JSON elements
using default representations for objects, pairs, and strings:

JSON                          term
                              
------------------------------------------------------------
[1,2]                         [1,2]
                              
true                          @true
                              
false                         @false
                              
null                          @null
                              
-1                            -1
                              
[1.2345]                      [1.2345]
                              
[]                            []
                              
[2147483647]                  [2147483647]
                              
[0]                           [0]
                              
[1234567890123456789]         [1234567890123456789]
                              
[false]                       [@false]
                              
[-2147483648]                 [-2147483648]
                              
{“a”:null,”foo”:”bar”}        <{a-@null>, foo-bar}
                              
[2.225073858507201e-308]      [2.225073858507201e-308]
                              
[0,1]                         [0,1]
                              
[2.2250738585072014e-308]     [2.2250738585072014e-308]
                              
[1.7976931348623157e+308]     [1.7976931348623157e+308]
                              
[0.0]                         [0.0]
                              
[4294967295]                  [4294967295]
                              
[-1234567890123456789]        [-1234567890123456789]
                              
[“foo”]                       [foo]
                              
[1]                           [1]
                              
[null]                        [@null]
                              
[-1.2345]                     [-1.2345]
                              
[5.0e-324]                    [5.0e-324]
                              
[-1]                          [-1]
                              
[true]                        [@true]
                              
[9223372036854775807]         [9223372036854775807]
                              

For JSON objects that are two possible term representations:

JSON object               term (curly)
                          
----------------------------------------------
{“a”:1, “b”:2, “c”:3}     {a-1, b-2, c-3}
                          
{}                        {}
                          

and:

JSON object               term (list)
                          
----------------------------------------------------
{“a”:1, “b”:2, “c”:3}     json([a-1, b-2, c-3])
                          
{}                        json([])
                          

For JSON pairs that are three possible representations:

JSON object               term (dash)
                          
----------------------------------------------
{“a”:1, “b”:2, “c”:3}     {a-1, b-2, c-3}
                          

and:

JSON object               term (equal)
                          
----------------------------------------------
{“a”:1, “b”:2, “c”:3}     {a=1, b=2, c=3}
                          

and:

JSON object               term (colon)
                          
----------------------------------------------
{“a”:1, “b”:2, “c”:3}     {a:1, b:2, c:3}
                          

By default, the curly-term representation and the dash pair
representation are used.  The ‘json/3’ parametric object allows
selecting the desired representation choices.  For example:

     | ?- json(curly,dash,atom)::parse(atom('{"a":1, "b":2, "c":3}'), JSON).
     JSON = {a-1, b-2, c-3}
     yes

     | ?- json(list,equal,atom)::parse(atom('{"a":1, "b":2, "c":3}'), JSON).
     JSON = json([a=1, b=2, c=3])
     yes

     | ?- json(curly,colon,atom)::parse(atom('{"a":1, "b":2, "c":3}'), JSON).
     JSON = {a:1, b:2, c:3}
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: Encoding<7>,  Next: Decoding<7>,  Prev: Representation<11>,  Up: json

6.128.5 Encoding
----------------

Encoding is accomplished using the ‘generate/2’ predicate.  For example:

     | ?- json::generate(codes(Encoding), [a,{b-c}]).
     Encoding = [91,34,97,34,44,123,34,98,34,58,34,99,34,125,93]
     yes

Alternatively:

     | ?- json::generate(chars(Encoding), [a,{b-c}]).
     Encoding = ['[','"',a,'"',',','{','"',b,'"',:,'"',c,'"','}',']']
     Yes

     | ?- json::generate(atom(Encoding), [a,{b-c}]).
     Encoding = '["a",{"b":"c"}]'
     Yes

Notice that ‘generate/2’ takes, as second argument, a Prolog term that
corresponds to the JSON syntax in Prolog and produces the corresponding
JSON output in the format specified in the first argument:
(‘codes(Variable)’, ‘stream(Stream)’, ‘file(File)’, ‘chars(Variable)’ or
‘atom(Variable)’).


File: TheLogtalkHandbook-3.101.0.info,  Node: Decoding<7>,  Next: Known issues<12>,  Prev: Encoding<7>,  Up: json

6.128.6 Decoding
----------------

Decoding is accomplished using the ‘parse/2’ predicate.  For example, to
decode a given json file:

     | ?- json::parse(file('simple/roundtrip_array_obj_array.json'), Term).
     Term = [{a-[b]}]
     yes

The ‘parse/2’ predicate first argument must indicate the input source
(‘codes(Codes)’, ‘stream(Stream)’, ‘line(Stream)’, ‘file(Path)’,
‘chars(Chars)’ or ‘atom(Atom)’) containing a JSON payload to be decoded
into the Prolog term in the second argument.


File: TheLogtalkHandbook-3.101.0.info,  Node: Known issues<12>,  Prev: Decoding<7>,  Up: json

6.128.7 Known issues
--------------------

Some tests, notably ‘parse_simple_valid_files’ and
‘roundtrip_hexadecimals’, fail on backends such as ECLiPSe and GNU
Prolog that don’t support Unicode.


File: TheLogtalkHandbook-3.101.0.info,  Node: json_graph,  Next: json_ld,  Prev: json,  Up: Libraries

6.129 ‘json_graph’
==================

The ‘json_graph’ library provides predicates for parsing and generating
JSON Graph Format (JGF) version 2 graphs:

‘https://jsongraphformat.info’

The library main object, ‘json_graph’, converts between JGF JSON and a
canonical list of terms:

   - ‘graph(GraphId, Properties)’

   - ‘node(GraphId, NodeId, Properties)’

   - ‘edge(GraphId, EdgeId, Source, Target, Properties)’

   - ‘hyperedge(GraphId, HyperedgeId, Nodes, Properties)’

   - ‘hyperedge(GraphId, HyperedgeId, Sources, Targets, Properties)’

Canonical graph, node, source, target, and edge identifiers are always
atoms.  When the library needs to generate missing graph, edge, or
hyperedge identifiers while parsing JGF input, it uses atoms in the
‘gN’, ‘eN’, and ‘heN’ formats.  Node identifiers are not generated
because JGF nodes are stored as object members keyed by their
identifiers.

Undirected hyperedges use ‘hyperedge/4’ and require their graph to have
a ‘directed(false)’ property.  Directed hyperedges use ‘hyperedge/5’ and
preserve the JGF ‘source’ and ‘target’ node sets as separate lists.  A
graph uses either ordinary edges or hyperedges, matching the JGF schema
shape.

It also supports object-backed sources and sinks using the
‘json_graph_data_protocol’ protocol.  Objects used as sinks should
implement that protocol and locally declare the ‘graph/2’, ‘node/3’,
‘edge/5’, ‘hyperedge/4’, and ‘hyperedge/5’ predicates as dynamic.

* Menu:

* API documentation: API documentation<147>.
* Loading: Loading<149>.
* Testing: Testing<141>.
* Usage: Usage<55>.
* Roundtrip and fixture coverage::


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<147>,  Next: Loading<149>,  Up: json_graph

6.129.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#json_graph’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<149>,  Next: Testing<141>,  Prev: API documentation<147>,  Up: json_graph

6.129.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(json_graph(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<141>,  Next: Usage<55>,  Prev: Loading<149>,  Up: json_graph

6.129.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(json_graph(tester)).

To run the performance benchmark suite, load the
‘tester_performance.lgt’ file:

     | ?- logtalk_load(json_graph(tester_performance)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<55>,  Next: Roundtrip and fixture coverage,  Prev: Testing<141>,  Up: json_graph

6.129.4 Usage
-------------

A JSON graph can be parsed into a list of canonical terms:

     | ?- json_graph::parse(atom('{"graph":{"id":"g","label":"Example","nodes":{"n1":{"label":"one"}},"edges":[{"source":"n1","target":"n1"}]}}'), Terms).

An object-backed graph can be exported by implementing the
‘json_graph_data_protocol’ protocol and defining ‘graph/2’, ‘node/3’,
‘edge/5’, ‘hyperedge/4’, and ‘hyperedge/5’ predicates.


File: TheLogtalkHandbook-3.101.0.info,  Node: Roundtrip and fixture coverage,  Prev: Usage<55>,  Up: json_graph

6.129.5 Roundtrip and fixture coverage
--------------------------------------

The test suite includes roundtrip checks for generated single-graph and
multi-graph term representations, file sink roundtrips, and public JGF
example files saved under the ‘test_files/’ directory.

The bundled public fixtures are sourced from the upstream JGF
specification examples repository:

   - ‘test_files/car_graphs.json’

   - ‘test_files/empty_test.json’

   - ‘test_files/hyper-directed.json’

   - ‘test_files/hyper-undirected.json’

   - ‘test_files/les_miserables.json’

   - ‘test_files/test.network.json’

   - ‘test_files/usual_suspects.json’


File: TheLogtalkHandbook-3.101.0.info,  Node: json_ld,  Next: json_lines,  Prev: json_graph,  Up: Libraries

6.130 ‘json_ld’
===============

The ‘json_ld’ library provides predicates for parsing, generating,
expanding, compacting, flattening, and framing JSON-LD 1.1 (JSON-based
Serialization for Linked Data) documents based on the W3C Recommendation
found at:

‘https://www.w3.org/TR/json-ld11/’

This library builds on top of the ‘json’ library for JSON parsing and
generation, and uses the same representation choices for JSON data.  It
includes parametric objects whose parameters allow selecting the
representation for parsed JSON objects (‘curly’ or ‘list’), JSON text
strings (‘atom’, ‘chars’, or ‘codes’) and JSON pairs (‘dash’, ‘equal’,
or ‘colon’).

* Menu:

* API documentation: API documentation<148>.
* Loading: Loading<150>.
* Testing: Testing<142>.
* Parsing: Parsing<2>.
* Generating: Generating<2>.
* Expansion::
* Compaction::
* Flattening::
* Framing::
* Implemented Features::
* Known Limitations::
* Representation: Representation<12>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<148>,  Next: Loading<150>,  Up: json_ld

6.130.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#json_ld’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<150>,  Next: Testing<142>,  Prev: API documentation<148>,  Up: json_ld

6.130.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(json_ld(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<142>,  Next: Parsing<2>,  Prev: Loading<150>,  Up: json_ld

6.130.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(json_ld(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Parsing<2>,  Next: Generating<2>,  Prev: Testing<142>,  Up: json_ld

6.130.4 Parsing
---------------

JSON-LD documents can be parsed from various sources using the ‘parse/2’
predicate.  Since JSON-LD is a superset of JSON, any valid JSON-LD
document is also valid JSON:

     | ?- json_ld::parse(file('document.jsonld'), Term).

     | ?- json_ld::parse(atom('{"@context": {"name": "http://schema.org/name"}, "name": "Manu Sporny"}'), Term).


File: TheLogtalkHandbook-3.101.0.info,  Node: Generating<2>,  Next: Expansion,  Prev: Parsing<2>,  Up: json_ld

6.130.5 Generating
------------------

JSON-LD documents can be generated from Logtalk terms using the
‘generate/2’ predicate:

     | ?- json_ld::generate(atom(Atom), {'@context'-{name-'http://schema.org/name'}, name-'Manu Sporny'}).


File: TheLogtalkHandbook-3.101.0.info,  Node: Expansion,  Next: Compaction,  Prev: Generating<2>,  Up: json_ld

6.130.6 Expansion
-----------------

Expansion is the process of removing the context and representing all
properties and types as full IRIs.  This is useful for processing
JSON-LD data in a context-independent way:

     | ?- json_ld::parse(atom('{"@context": {"name": "http://schema.org/name"}, "name": "Manu Sporny"}'), Doc),
          json_ld::expand(Doc, Expanded).
     Doc = {'@context'-{name-'http://schema.org/name'}, name-'Manu Sporny'},
     Expanded = [{'http://schema.org/name'-[{'@value'-'Manu Sporny'}]}]
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: Compaction,  Next: Flattening,  Prev: Expansion,  Up: json_ld

6.130.7 Compaction
------------------

Compaction is the process of applying a context to shorten IRIs to terms
or compact IRIs.  The current implementation provides basic key and
value compaction but does not yet implement the full JSON-LD 1.1 inverse
context selection algorithm:

     | ?- json_ld::expand({'@context'-{name-'http://schema.org/name'}, name-'Manu Sporny'}, Expanded),
          json_ld::compact(Expanded, {'@context'-{name-'http://schema.org/name'}}, Compacted).


File: TheLogtalkHandbook-3.101.0.info,  Node: Flattening,  Next: Framing,  Prev: Compaction,  Up: json_ld

6.130.8 Flattening
------------------

Flattening uses node map generation to collect node objects into an
expanded flat array, with nested node objects replaced by references.
Blank node identifiers are generated for nodes that don’t have an ‘@id’
and existing blank node identifiers are relabeled consistently:

     | ?- json_ld::parse(atom('{"@context":{"knows":"http://xmlns.com/foaf/0.1/knows"},"@id":"http://example.org/john","knows":{"@id":"http://example.org/jane"}}'), Doc),
          json_ld::expand(Doc, Expanded),
          json_ld::flatten(Expanded, Flattened).


File: TheLogtalkHandbook-3.101.0.info,  Node: Framing,  Next: Implemented Features,  Prev: Flattening,  Up: json_ld

6.130.9 Framing
---------------

Framing selects and shapes nodes from a JSON-LD document using a frame.
The ‘frame/3’ predicate expands the input document and frame, generates
a node map, matches nodes by ‘@id’, ‘@type’, and framed properties, and
embeds referenced nodes according to the framing options.  When the
frame includes a context, the framed result is compacted using that
context:

| ?- json_ld::frame( {‘@context’-{name
<{'@context'-{name>-’‘http://schema.org/name'}’, ‘@id’-‘http
<'@id'-'http>://example.org/alice’, name-‘Alice’}, {‘@context’-{name
<{'@context'-{name>-’‘http://schema.org/name'}’, ‘@id
<'@id>’-’‘http://example.org/alice'}’, Framed).


File: TheLogtalkHandbook-3.101.0.info,  Node: Implemented Features,  Next: Known Limitations,  Prev: Framing,  Up: json_ld

6.130.10 Implemented Features
-----------------------------

The library currently implements the following JSON-LD 1.1 processing
features:

'Context processing:'

   - Inline context definitions (‘@context’)

   - Vocabulary mapping (‘@vocab’)

   - Base IRI (‘@base’)

   - Relative IRI resolution against ‘@base’, including common path,
     query, and fragment references

   - Default language (‘@language’) for string values

   - Validation of base direction (‘@direction’) values

   - Compact IRIs (prefix:suffix notation)

   - Term definitions with simple IRI mappings and expanded ‘@id’
     mappings

   - Type coercion for ‘@id’, ‘@vocab’, and typed literals in term
     definitions

   - Context arrays (multiple contexts)

   - Validation of ‘@version’, ‘@base’, ‘@vocab’, ‘@language’,
     ‘@direction’, ‘@propagate’, and ‘@protected’ context values

'Node objects:'

   - Node identifiers (‘@id’)

   - Node types (‘@type’)

   - Blank node identifiers (‘_:name’)

'Value objects:'

   - String, numeric, and boolean property values expanded as value
     objects

   - Typed values (‘@value’ with ‘@type’)

   - Language-tagged strings (‘@value’ with ‘@language’)

   - Direction-tagged value objects (‘@value’ with ‘@direction’)

   - Ordinary ‘null’ property values are dropped during expansion

'Graph support:'

   - Named graphs (‘@graph’)

   - Default graph

'Collections:'

   - Ordered lists (‘@list’)

   - Unordered sets (‘@set’)

   - ‘@list’ rejects nested arrays during expansion

'Other features:'

   - Reverse properties (‘@reverse’)

   - Included blocks (‘@included’)

   - Index preservation (‘@index’)

   - Nested property blocks (‘@nest’)

   - Basic compaction (‘compact/3’)

   - Node map based flattening (‘flatten/2’), including named graphs,
     reverse properties, included blocks, lists, duplicate suppression,
     type merging, conflicting index detection, and deterministic blank
     node relabeling

   - Framing (‘frame/3’) with ‘@id’ and ‘@type’ matching, nested frames,
     ‘@embed’, ‘@explicit’, ‘@requireAll’, ‘@omitDefault’, ‘@default’,
     ‘@reverse’, ‘@list’, cycle prevention, and context-based compaction
     of framed output


File: TheLogtalkHandbook-3.101.0.info,  Node: Known Limitations,  Next: Representation<12>,  Prev: Implemented Features,  Up: json_ld

6.130.11 Known Limitations
--------------------------

The implementation is intentionally portable and currently incomplete
with respect to full JSON-LD 1.1 API conformance.  Known limitations
include:

'Context processing:'

   - Remote contexts referenced by URL are not fetched.

   - ‘@import’ is rejected with a ‘domain_error(json_ld_context_import,
     Value)’ error; imported contexts are not loaded or merged.

   - ‘@protected’ and ‘@propagate’ values are validated but their full
     JSON-LD scoping and term redefinition semantics are not yet
     implemented.

   - ‘@container’, ‘@prefix’, scoped contexts, reverse properties in
     term definitions, index mappings, language maps, and graph
     containers are not yet implemented.

   - ‘@direction’ is preserved in explicit value objects and validated
     in contexts, but default direction is not yet applied to string
     values during expansion.

   - ‘@type: @json’ and ‘@type: @none’ coercion are not yet implemented.

'Expansion:'

   - Expansion implements common node, value, list, set, reverse,
     included, index, and nest cases but does not yet implement all
     validation rules from the JSON-LD 1.1 expansion algorithm.

   - Container expansion for ‘@language’, ‘@index’, ‘@id’, ‘@type’,
     ‘@graph’, ‘@list’, and ‘@set’ containers is not yet implemented.

   - Reverse property validation is partial.

   - Absolute IRI detection and compact IRI processing are sufficient
     for common ‘://’, ‘urn:’, and prefix:suffix cases but are not a
     complete RFC 3986/3987 implementation.

'Compaction:'

   - ‘compact/3’ performs basic key and value compaction but does not
     yet build or use the JSON-LD inverse context.

   - Term selection does not yet account for container, type, language,
     direction, reverse, or index preferences.

   - The result is a compacted term tree and does not yet implement the
     full JSON-LD compact API output shape, including context injection
     and all compact arrays rules.

'Flattening:'

   - ‘flatten/2’ returns expanded flattened output and does not
     implement a separate compacted flattening API variant with context
     injection.

   - The node map implementation covers common node, named graph,
     reverse, included, list, duplicate suppression, type merging, and
     blank node relabeling cases, but some edge-case validation from the
     full JSON-LD 1.1 algorithms is still partial.

'Framing:'

   - ‘frame/3’ implements portable JSON-LD framing for common expanded
     and compacted inputs, including nested embedding, reverse
     properties, lists, defaults, and cycle prevention.

   - Full JSON-LD 1.1 framing edge-case semantics are not yet
     implemented, including all ‘@embed’ modes beyond boolean behavior,
     all default object shapes, graph map framing details, ‘@included’
     framing details, and all validation/error cases from the
     Recommendation.

'Not currently supported:'

   - Remote context fetching (contexts referenced by URL)

   - Full JSON-LD 1.1 compaction algorithm

   - RDF conversion, normalization, or dataset processing


File: TheLogtalkHandbook-3.101.0.info,  Node: Representation<12>,  Prev: Known Limitations,  Up: json_ld

6.130.12 Representation
-----------------------

JSON-LD documents are represented using the same term conventions as the
‘json’ library.  The JSON-LD keywords (‘@context’, ‘@id’, ‘@type’, etc.)
are represented as atoms in the parsed terms.  For example:

JSON-LD                                                  term (default)
                                                         
-------------------------------------------------------------------------------------------------------------------------
{“@id”: “‘http://example.org/"}’                         {‘@id <{'@id>’-’‘http://example.org/'}’
                                                         
{“@type”: “Person”}                                      {‘@type’-‘Person <{'@type'-'Person>’}
                                                         
{“@value”: “hello”, “@language”: “en”}                   {‘@value’-hello <{'@value'-hello>, ‘@language’-en
                                                         <'@language'-en>}
                                                         
{“@list”: [1, 2, 3]}                                     {‘@list <{'@list>’-[1, 2, 3]}
                                                         
{“@graph”: […]}                                          {‘@graph <{'@graph>’-[…]}
                                                         

As with the ‘json’ library, objects can be represented using curly terms
(default) or list terms, and pairs can use dash, equal, or colon
notation.


File: TheLogtalkHandbook-3.101.0.info,  Node: json_lines,  Next: json_patch,  Prev: json_ld,  Up: Libraries

6.131 ‘json_lines’
==================

The ‘json_lines’ library provides predicates for parsing and generating
data in the JSON Lines format based on the proposal found at:

‘https://jsonlines.org’

It includes parametric objects whose parameters allow selecting the
representation for parsed JSON objects (‘curly’ or ‘list’), JSON text
strings (‘atom’, ‘chars’, or ‘codes’) and JSON pairs (‘dash’, ‘equal’,
or ‘colon’).

* Menu:

* API documentation: API documentation<149>.
* Loading: Loading<151>.
* Testing: Testing<143>.
* Representation: Representation<13>.
* Encoding: Encoding<8>.
* Decoding: Decoding<8>.
* Known issues: Known issues<13>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<149>,  Next: Loading<151>,  Up: json_lines

6.131.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#json_lines’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<151>,  Next: Testing<143>,  Prev: API documentation<149>,  Up: json_lines

6.131.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(json_lines(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<143>,  Next: Representation<13>,  Prev: Loading<151>,  Up: json_lines

6.131.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(json_lines(tester)).

Some of the sample JSON test files are based on examples published at:

‘https://jsonlines.org/’


File: TheLogtalkHandbook-3.101.0.info,  Node: Representation<13>,  Next: Encoding<8>,  Prev: Testing<143>,  Up: json_lines

6.131.4 Representation
----------------------

The following choices of syntax have been made to represent JSON
elements as terms:

   - By default, JSON objects are represented using curly-bracketed
     terms, ‘{Pairs}’, where each pair uses the representation
     ‘Key-Value’ (see below for alternative representations).

   - Arrays are represented using lists.

   - Text strings can be represented as atoms, ‘chars(List)’, or
     ‘codes(List)’.  The default when decoding is to use atoms when
     using the ‘json_lines’ object.  To decode text strings into lists
     of chars or codes, use the ‘json_lines/1’ object with the parameter
     bound to ‘chars’ or ‘codes’.  For example:

          | ?- json_lines::parse(codes([34,104,101,108,108,111,34]), Terms).
          Terms = [hello]
          yes

          | ?- json_lines(atom)::parse(codes([34,104,101,108,108,111,34]), Terms).
          Terms = [hello]
          yes

          | ?- json_lines(chars)::parse(codes([34,104,101,108,108,111,34]), Terms).
          Terms = [chars([h,e,l,l,o])]
          yes

          | ?- json_lines(codes)::parse(codes([34,104,101,108,108,111,34]), Terms).
          Terms = [codes([104,101,108,108,111])]
          yes

   - The JSON values ‘false’, ‘true’ and ‘null’ are represented by,
     respectively, the ‘@false’, ‘@true’ and ‘@null’ compound terms.

The following table exemplifies the term equivalents of JSON elements
using default representations for objects, pairs, and strings:

JSON                          term
                              
------------------------------------------------------------
[1,2]                         [1,2]
                              
true                          @true
                              
false                         @false
                              
null                          @null
                              
-1                            -1
                              
[1.2345]                      [1.2345]
                              
[]                            []
                              
[2147483647]                  [2147483647]
                              
[0]                           [0]
                              
[1234567890123456789]         [1234567890123456789]
                              
[false]                       [@false]
                              
[-2147483648]                 [-2147483648]
                              
{“a”:null,”foo”:”bar”}        <{a-@null>, foo-bar}
                              
[2.225073858507201e-308]      [2.225073858507201e-308]
                              
[0,1]                         [0,1]
                              
[2.2250738585072014e-308]     [2.2250738585072014e-308]
                              
[1.7976931348623157e+308]     [1.7976931348623157e+308]
                              
[0.0]                         [0.0]
                              
[4294967295]                  [4294967295]
                              
[-1234567890123456789]        [-1234567890123456789]
                              
[“foo”]                       [foo]
                              
[1]                           [1]
                              
[null]                        [@null]
                              
[-1.2345]                     [-1.2345]
                              
[5.0e-324]                    [5.0e-324]
                              
[-1]                          [-1]
                              
[true]                        [@true]
                              
[9223372036854775807]         [9223372036854775807]
                              

For JSON objects that are two possible term representations:

JSON object               term (curly)
                          
----------------------------------------------
{“a”:1, “b”:2, “c”:3}     {a-1, b-2, c-3}
                          
{}                        {}
                          

and:

JSON object               term (list)
                          
----------------------------------------------------
{“a”:1, “b”:2, “c”:3}     json([a-1, b-2, c-3])
                          
{}                        json([])
                          

For JSON pairs that are three possible representations:

JSON object               term (dash)
                          
----------------------------------------------
{“a”:1, “b”:2, “c”:3}     {a-1, b-2, c-3}
                          

and:

JSON object               term (equal)
                          
----------------------------------------------
{“a”:1, “b”:2, “c”:3}     {a=1, b=2, c=3}
                          

and:

JSON object               term (colon)
                          
----------------------------------------------
{“a”:1, “b”:2, “c”:3}     {a:1, b:2, c:3}
                          

By default, the curly-term representation and the dash pair
representation are used.  The ‘json/3’ parametric object allows
selecting the desired representation choices.  For example:

     | ?- json_lines(curly,dash,atom)::parse(atom('{"a":1, "b":2, "c":3}'), JSONL).
     JSONL = [{a-1, b-2, c-3}]
     yes

     | ?- json_lines(list,equal,atom)::parse(atom('{"a":1, "b":2, "c":3}'), JSONL).
     JSONL = [json([a=1, b=2, c=3])]
     yes

     | ?- json_lines(curly,colon,atom)::parse(atom('{"a":1, "b":2, "c":3}'), JSONL).
     JSONL = [{a:1, b:2, c:3}]
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: Encoding<8>,  Next: Decoding<8>,  Prev: Representation<13>,  Up: json_lines

6.131.5 Encoding
----------------

Encoding is accomplished using the ‘generate/2’ predicate.  For example:

     | ?- json_lines::generate(codes(Encoding), [a,{b-c}]).
     Encoding = [34,97,34,10,123,34,98,34,58,34,99,34,125,10]
     yes

Alternatively:

     | ?- json_lines::generate(chars(Encoding), [a,{b-c}]).
     Encoding = ['"',a,'"','\n','{','"',b,'"',:,'"',c,'"','}','\n']
     Yes

     | ?- json_lines::generate(atom(Encoding), [a,{b-c}]).
     Encoding = '"a"\n{"b":"c"}\n'
     Yes

Notice that ‘generate/2’ takes, as second argument, a Prolog term that
corresponds to the JSON syntax in Prolog and produces the corresponding
JSON output in the format specified in the first argument:
(‘codes(Variable)’, ‘stream(Stream)’, ‘file(File)’, ‘chars(Variable)’ or
‘atom(Variable)’).


File: TheLogtalkHandbook-3.101.0.info,  Node: Decoding<8>,  Next: Known issues<13>,  Prev: Encoding<8>,  Up: json_lines

6.131.6 Decoding
----------------

Decoding is accomplished using the ‘parse/2’ predicate.  For example, to
decode a given json file:

     | ?- json_lines::parse(file('simple/data.jsonl'), Terms).
     Term = [{a-[b]}]
     yes

The ‘parse/2’ predicate first argument must indicate the input source
(‘codes(Codes)’, ‘stream(Stream)’, ‘line(Stream)’, ‘file(Path)’,
‘chars(Chars)’ or ‘atom(Atom)’) containing a JSON payload to be decoded
into the Prolog term in the second argument.


File: TheLogtalkHandbook-3.101.0.info,  Node: Known issues<13>,  Prev: Decoding<8>,  Up: json_lines

6.131.7 Known issues
--------------------

Some tests may fail on backends such as ECLiPSe and GNU Prolog that
don’t support Unicode.


File: TheLogtalkHandbook-3.101.0.info,  Node: json_patch,  Next: json_path,  Prev: json_lines,  Up: Libraries

6.132 ‘json_patch’
==================

The ‘json_patch’ library provides predicates for applying JSON Patch
documents as specified by RFC 6902:

   - ‘https://www.rfc-editor.org/rfc/rfc6902’

Patch documents are represented as lists of JSON operation objects using
the repository native JSON term representation.

* Menu:

* API documentation: API documentation<150>.
* Loading: Loading<152>.
* Testing: Testing<144>.
* Representation: Representation<14>.
* Patch document structure::
* Valid operations::
* Path rules::
* Representation notes::
* Failure and errors::


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<150>,  Next: Loading<152>,  Up: json_patch

6.132.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#json_patch’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<152>,  Next: Testing<144>,  Prev: API documentation<150>,  Up: json_patch

6.132.2 Loading
---------------

To load all entities in this library from the repository checkout, load
the ‘loader.lgt’ file from this directory:

     | ?- logtalk_load(json_patch(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<144>,  Next: Representation<14>,  Prev: Loading<152>,  Up: json_patch

6.132.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(json_patch(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Representation<14>,  Next: Patch document structure,  Prev: Testing<144>,  Up: json_patch

6.132.4 Representation
----------------------

Patch documents are JSON arrays represented as Prolog lists.  Each
element in the list is a JSON object representing a patch operation.
The public predicate provided by this library is:

     | ?- json_patch::apply(Patch, OldJSON, NewJSON).

where ‘Patch’ is a list of operation objects, ‘OldJSON’ is the input
JSON term, and ‘NewJSON’ is the patched JSON term.


File: TheLogtalkHandbook-3.101.0.info,  Node: Patch document structure,  Next: Valid operations,  Prev: Representation<14>,  Up: json_patch

6.132.5 Patch document structure
--------------------------------

Each patch operation is encoded as a JSON object using any of the JSON
object representations supported by the repository JSON libraries:

   - Curly objects using dash pairs, e.g.  ‘{op-add, path-'/foo',
     value-1}’

   - List objects using ‘json([...])’, e.g.  ‘json([op=add, path='/foo',
     value=1])’

   - List objects using colon pairs, e.g.  ‘json([':'(op, add),
     ':'(path, '/foo')])’

The operation member names are always:

   - ‘op’

   - ‘path’

   - ‘from’

   - ‘value’

The ‘path’ and ‘from’ members are JSON Pointer strings parsed using the
‘json_pointer’ library.  They can be represented as:

   - atoms, e.g.  ‘'/items/0'’

   - ‘chars(List)’, e.g.  ‘chars(['/', i, t, e, m, s, '/', '0'])’

   - ‘codes(List)’, e.g.  ‘codes([0'/, 0'i, 0't, 0'e, 0'm, 0's, 0'/,
     0'0])’

For example:

     | ?- Patch = [{op-add, path-'/baz', value-1}],
          json_patch::apply(Patch, {foo-bar}, JSON).
     Patch = [{op-add,path-'/baz',value-1}]
     JSON = {foo-bar, baz-1}
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: Valid operations,  Next: Path rules,  Prev: Patch document structure,  Up: json_patch

6.132.6 Valid operations
------------------------

The library accepts the six RFC 6902 operations:

   - ‘add’ Required members: ‘op’, ‘path’, ‘value’ Adds a value at the
     target path.  When the target path is empty (‘''’), the whole
     document is replaced by the given value.

          | ?- Patch = [{op-add, path-'/items/-', value-b}],
               json_patch::apply(Patch, {items-[a]}, JSON).
          Patch = [{op-add,path-'/items/-',value-b}]
          JSON = {items-[a,b]}
          yes

   - ‘remove’ Required members: ‘op’, ‘path’ Removes the value at the
     target path.  The target must exist.  Removing the root document is
     not supported, so an empty path fails.

          | ?- Patch = [{op-remove, path-'/foo'}],
               json_patch::apply(Patch, {foo-bar}, JSON).
          Patch = [{op-remove,path-'/foo'}]
          JSON = {}
          yes

   - ‘replace’ Required members: ‘op’, ‘path’, ‘value’ Replaces the
     existing value at the target path.  When the target path is empty,
     the whole document is replaced.

          | ?- Patch = [{op-replace, path-'', value-[1,2]}],
               json_patch::apply(Patch, {foo-bar}, JSON).
          Patch = [{op-replace,path-'',value-[1,2]}]
          JSON = [1,2]
          yes

   - ‘move’ Required members: ‘op’, ‘from’, ‘path’ Reads the value
     identified by ‘from’, removes it from the source location, and then
     adds it at ‘path’.

          | ?- Patch = [{op-move, from-'/foo', path-'/baz'}],
               json_patch::apply(Patch, {foo-bar}, JSON).
          Patch = [{op-move,from-'/foo',path-'/baz'}]
          JSON = {baz-bar}
          yes

   - ‘copy’ Required members: ‘op’, ‘from’, ‘path’ Reads the value
     identified by ‘from’ and adds a copy of it at ‘path’.

          | ?- Patch = [{op-copy, from-'/foo', path-'/baz'}],
               json_patch::apply(Patch, {foo-bar}, JSON).
          Patch = [{op-copy,from-'/foo',path-'/baz'}]
          JSON = {foo-bar,baz-bar}
          yes

   - ‘test’ Required members: ‘op’, ‘path’, ‘value’ Succeeds only if the
     value at the target path is structurally equal to the given
     ‘value’.  On success, ‘NewJSON’ is unified with the original
     document.

          | ?- Patch = [{op-test, path-'/flag', value- @true}],
               json_patch::apply(Patch, {flag- @true}, JSON).
          Patch = [{op-test,path-'/flag',value- @true}]
          JSON = {flag- @true}
          yes


File: TheLogtalkHandbook-3.101.0.info,  Node: Path rules,  Next: Representation notes,  Prev: Valid operations,  Up: json_patch

6.132.7 Path rules
------------------

   - Paths use RFC 6901 JSON Pointer syntax.

   - The empty path (‘''’) addresses the whole JSON document.

   - Array insertion with ‘add’ supports the special ‘'-'’ token for
     appending to the end of an array.

   - Array indices must be decimal integers without leading zeros,
     except for the single digit ‘0’.

   - Intermediate containers must already exist.  Operations do not
     create missing parent objects or arrays.


File: TheLogtalkHandbook-3.101.0.info,  Node: Representation notes,  Next: Failure and errors,  Prev: Path rules,  Up: json_patch

6.132.8 Representation notes
----------------------------

This implementation reuses ‘json_pointer’ for parsing patch paths and
preserves the object representation found in the patched JSON term:

   - curly objects stay curly objects

   - ‘json([...])’ objects stay ‘json([...])’ objects

   - key text representation such as atoms, ‘chars(List)’, or
     ‘codes(List)’ is preserved when new members are added to an
     existing object

The implementation also accepts patch operation objects encoded using
curly or ‘json([...])’ object notation and pointer text represented as
atoms, ‘chars(List)’, or ‘codes(List)’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Failure and errors,  Prev: Representation notes,  Up: json_patch

6.132.9 Failure and errors
--------------------------

   - ‘apply/3’ throws an ‘instantiation_error’ when ‘Patch’ or ‘OldJSON’
     is a variable.

   - ‘apply/3’ throws ‘type_error(list, Patch)’ when the patch document
     is not a list.

   - ‘apply/3’ throws ‘domain_error(json_patch_operation, Operation)’
     when an operation object is malformed.

   - Operations fail when a required target value does not exist or when
     a ‘test’ comparison does not succeed.

Empty patch paths are supported for root replacement, copying to the
root, moving to the root, and testing the full document.


File: TheLogtalkHandbook-3.101.0.info,  Node: json_path,  Next: json_pointer,  Prev: json_patch,  Up: Libraries

6.133 ‘json_path’
=================

This library provides predicates for parsing, generating, and evaluating
JSONPath queries for native Logtalk JSON terms.

It is based on RFC 9535:

   - ‘https://www.rfc-editor.org/rfc/rfc9535’

* Menu:

* Current implementation status::
* API documentation: API documentation<151>.
* Loading: Loading<153>.
* Testing: Testing<145>.
* Representation: Representation<15>.
* Examples: Examples<173>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Current implementation status,  Next: API documentation<151>,  Up: json_path

6.133.1 Current implementation status
-------------------------------------

This implementation currently supports:

   - child segments

   - descendant segments

   - name selectors

   - wildcard selectors

   - index selectors, including negative indexes

   - slice selectors

   - filter selectors

   - existence tests

   - logical operators: ‘||’, ‘&&’, and ‘!’

   - comparisons using literals, singular queries, and supported
     function expressions

   - function expressions: ‘length()’, ‘count()’, ‘match()’, ‘search()’,
     and ‘value()’

   - local I-Regexp matching support for alternation, grouping, wildcard
     ‘.’, character classes, single-character escapes, and quantifiers
     (‘*’, ‘+’, ‘?’, ‘{m}’, ‘{m,}’, ‘{m,n}’)

   - Unicode general-category escapes ‘\p{...}’ and ‘\P{...}’ using
     backend ‘unicode_property/2’ support when available

   - additional local validation for malformed character classes and for
     unsafe explicit range quantifiers (nested explicit ranges and very
     large upper bounds/spans are rejected)

   - validation of index and slice integers against the RFC 9535 I-JSON
     exact-integer range

   - validation that queries supplied in ‘codes(...)’ representation
     contain only Unicode scalar values

   - normalized path reporting

Still pending:

   - the remaining RFC 9535 function-extension surface


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<151>,  Next: Loading<153>,  Prev: Current implementation status,  Up: json_path

6.133.2 API documentation
-------------------------

Open the ‘../../apis/library_index.html#json_path’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<153>,  Next: Testing<145>,  Prev: API documentation<151>,  Up: json_path

6.133.3 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(json_path(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<145>,  Next: Representation<15>,  Prev: Loading<153>,  Up: json_path

6.133.4 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(json_path(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Representation<15>,  Next: Examples<173>,  Prev: Testing<145>,  Up: json_path

6.133.5 Representation
----------------------

The library defines the ‘json_path(_Representation_)’ parametric object
where ‘_Representation_’ can be one of:

   - ‘atom’ - member names and normalized paths are represented as atoms

   - ‘chars’ - member names and normalized paths are represented as
     ‘chars(List)’

   - ‘codes’ - member names and normalized paths are represented as
     ‘codes(List)’

When using the default ‘json_path’ object, member names and normalized
paths are represented as atoms.


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<173>,  Prev: Representation<15>,  Up: json_path

6.133.6 Examples
----------------

Parse and evaluate a query:

     | ?- json_path::parse(atom('$.store.book[0].title'), Query),
          json_path::evaluate(Query, {store-{book-[{title-'Sayings of the Century'}]}}, Values).
     Query = json_path([child([name(store)]), child([name(book)]), child([index(0)]), child([name(title)])])
     Values = ['Sayings of the Century']
     yes

Filter books by price:

     | ?- JSON = {store-{book-[{title-'Sayings', price-8.95}, {title-'Honour', price-12.99}]}},
          json_path::query(atom('$.store.book[?@.price < 10].title'), JSON, Values).
     JSON = {store-{book-[{title-'Sayings', price-8.95}, {title-'Honour', price-12.99}]}}
     Values = ['Sayings']
     yes

Return normalized paths for the selected nodes:

     | ?- json_path::parse(atom('$..j'), Query),
          json_path::paths(Query, {o-{j-1}, a-[[{j-4}]]}, Paths).
     Paths = ['$[''o''][''j'']', '$[''a''][0][0][''j'']']
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: json_pointer,  Next: json_rpc,  Prev: json_path,  Up: Libraries

6.134 ‘json_pointer’
====================

The ‘json_pointer’ library provides predicates for parsing, generating,
and evaluating JSON Pointers as specified by RFC 6901, plus support for
Relative JSON Pointer:

   - ‘https://www.rfc-editor.org/rfc/rfc6901’

   - ‘https://json-schema.org/draft/2020-12/relative-json-pointer’

It supports both the plain string syntax and the URI fragment syntax for
absolute JSON Pointers.  Relative JSON Pointers use the plain string
syntax.  Reference tokens can be represented as atoms, ‘chars(List)’, or
‘codes(List)’.

* Menu:

* API documentation: API documentation<152>.
* Loading: Loading<154>.
* Testing: Testing<146>.
* Representation: Representation<16>.
* Examples: Examples<174>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<152>,  Next: Loading<154>,  Up: json_pointer

6.134.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#json_pointer’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<154>,  Next: Testing<146>,  Prev: API documentation<152>,  Up: json_pointer

6.134.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(json_pointer(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<146>,  Next: Representation<16>,  Prev: Loading<154>,  Up: json_pointer

6.134.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(json_pointer(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Representation<16>,  Next: Examples<174>,  Prev: Testing<146>,  Up: json_pointer

6.134.4 Representation
----------------------

The library defines the ‘json_pointer(_Representation_)’ parametric
object where ‘_Representation_’ can be one of:

   - ‘atom’ - reference tokens are represented as atoms

   - ‘chars’ - reference tokens are represented as ‘chars(List)’

   - ‘codes’ - reference tokens are represented as ‘codes(List)’

When using the default ‘json_pointer’ object, reference tokens are
represented as atoms.

Relative JSON Pointer values are represented as ‘relative(Up, Shift,
Suffix)’:

   - ‘Up’ is the number of ancestor steps

   - ‘Shift’ is the optional signed array index adjustment

   - ‘Suffix’ is either a list of reference tokens or the atom ‘'#'’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<174>,  Prev: Representation<16>,  Up: json_pointer

6.134.5 Examples
----------------

Parse and evaluate a pointer:

     | ?- json_pointer::parse(atom('/foo/0'), Pointer),
          json_pointer::evaluate(Pointer, {foo-[bar, baz]}, Value).
     Pointer = [foo, '0']
     Value = bar
     yes

Generate a URI fragment representation:

     | ?- json_pointer::generate_fragment(atom(Fragment), ['a b', 'c/d']).
     Fragment = '#/a%20b/c~1d'
     yes

Evaluate a Relative JSON Pointer from a known context path:

     | ?- json_pointer::evaluate_relative(relative(1, 0, ['0']), [foo, '1'], {foo-[bar, baz]}, Value).
     Value = bar
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: json_rpc,  Next: json_schema,  Prev: json_pointer,  Up: Libraries

6.135 ‘json_rpc’
================

JSON-RPC 2.0 protocol encoding and decoding library.  Provides
predicates for constructing, parsing, classifying, and inspecting
JSON-RPC 2.0 messages (requests, notifications, responses, and error
responses).  Also provides stream-based message I/O for implementing
JSON-RPC clients and servers, including Content-Length header framing as
used by the Language Server Protocol (LSP) and the Model Context
Protocol (MCP). Uses the ‘json’ library for JSON parsing and generation.

* Menu:

* API documentation: API documentation<153>.
* Loading: Loading<155>.
* Testing: Testing<147>.
* Usage: Usage<56>.
* API summary::


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<153>,  Next: Loading<155>,  Up: json_rpc

6.135.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#json_rpc’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<155>,  Next: Testing<147>,  Prev: API documentation<153>,  Up: json_rpc

6.135.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(json_rpc(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<147>,  Next: Usage<56>,  Prev: Loading<155>,  Up: json_rpc

6.135.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(json_rpc(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<56>,  Next: API summary,  Prev: Testing<147>,  Up: json_rpc

6.135.4 Usage
-------------

* Menu:

* Constructing JSON-RPC 2.0 messages: Constructing JSON-RPC 2 0 messages.
* Standard error constructors::
* Encoding and decoding::
* Message classification::
* Field extraction::
* Stream I/O (client and server API): Stream I/O client and server API.
* Content-Length framed I/O (LSP/MCP protocols): Content-Length framed I/O LSP/MCP protocols.


File: TheLogtalkHandbook-3.101.0.info,  Node: Constructing JSON-RPC 2 0 messages,  Next: Standard error constructors,  Up: Usage<56>

6.135.4.1 Constructing JSON-RPC 2.0 messages
............................................

Construct requests, notifications, responses, and error responses:

     | ?- json_rpc::request(subtract, [42,23], 1, Request).
     Request = {jsonrpc-'2.0', method-subtract, params-[42,23], id-1}.

     | ?- json_rpc::notification(update, [1,2,3], Notification).
     Notification = {jsonrpc-'2.0', method-update, params-[1,2,3]}.

     | ?- json_rpc::response(19, 1, Response).
     Response = {jsonrpc-'2.0', result-19, id-1}.

     | ?- json_rpc::error_response(-32601, 'Method not found', 1, ErrorResponse).


File: TheLogtalkHandbook-3.101.0.info,  Node: Standard error constructors,  Next: Encoding and decoding,  Prev: Constructing JSON-RPC 2 0 messages,  Up: Usage<56>

6.135.4.2 Standard error constructors
.....................................

     | ?- json_rpc::parse_error(Error).
     Error = ...

     | ?- json_rpc::invalid_request(Error).
     Error = ...

     | ?- json_rpc::method_not_found(1, Error).
     Error = ...

     | ?- json_rpc::invalid_params(1, Error).
     Error = ...

     | ?- json_rpc::internal_error(1, Error).
     Error = ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Encoding and decoding,  Next: Message classification,  Prev: Standard error constructors,  Up: Usage<56>

6.135.4.3 Encoding and decoding
...............................

     | ?- json_rpc::request(subtract, [42,23], 1, Request),
        json_rpc::encode(Request, JSON).
     JSON = '{"jsonrpc":"2.0","method":"subtract","params":[42,23],"id":1}'.

     | ?- json_rpc::decode('{"jsonrpc":"2.0","result":19,"id":1}', Term).


File: TheLogtalkHandbook-3.101.0.info,  Node: Message classification,  Next: Field extraction,  Prev: Encoding and decoding,  Up: Usage<56>

6.135.4.4 Message classification
................................

     | ?- json_rpc::is_request(Message).
     ...

     | ?- json_rpc::is_notification(Message).
     ...

     | ?- json_rpc::is_response(Message).
     ...

     | ?- json_rpc::is_error_response(Message).
     ...

     | ?- json_rpc::is_batch(Messages).
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Field extraction,  Next: Stream I/O client and server API,  Prev: Message classification,  Up: Usage<56>

6.135.4.5 Field extraction
..........................

     | ?- json_rpc::id(Message, Id).
     ...

     | ?- json_rpc::method(Message, Method).
     ...

     | ?- json_rpc::params(Message, Params).
     ...

     | ?- json_rpc::result(Message, Result).
     ...

     | ?- json_rpc::error_code(Message, Code).
     ...

     | ?- json_rpc::error_message(Message, ErrorMessage).
     ...

     | ?- json_rpc::error_data(Message, Data).
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Stream I/O client and server API,  Next: Content-Length framed I/O LSP/MCP protocols,  Prev: Field extraction,  Up: Usage<56>

6.135.4.6 Stream I/O (client and server API)
............................................

Write and read newline-delimited JSON-RPC messages over streams:

     | ?- json_rpc::write_message(Output, Message).
     ...

     | ?- json_rpc::read_message(Input, Message).
     ...

These predicates can be used with any stream, including socket streams
from the ‘sockets’ library, to implement JSON-RPC clients and servers.


File: TheLogtalkHandbook-3.101.0.info,  Node: Content-Length framed I/O LSP/MCP protocols,  Prev: Stream I/O client and server API,  Up: Usage<56>

6.135.4.7 Content-Length framed I/O (LSP/MCP protocols)
.......................................................

Write and read JSON-RPC messages using ‘Content-Length’ header framing
as defined by the Language Server Protocol (LSP) and the Model Context
Protocol (MCP). Each message is preceded by a ‘Content-Length:
N\r\n\r\n’ header where ‘N’ is the byte length of the JSON body:

     | ?- json_rpc::write_framed_message(Output, Message).
     ...

     | ?- json_rpc::read_framed_message(Input, Message).
     ...

‘read_framed_message/2’ fails at end of stream or if the header is
missing or malformed.


File: TheLogtalkHandbook-3.101.0.info,  Node: API summary,  Prev: Usage<56>,  Up: json_rpc

6.135.5 API summary
-------------------

* Menu:

* Message construction::
* Standard error responses::
* Encoding and decoding: Encoding and decoding<2>.
* Message classification: Message classification<2>.
* Field extraction: Field extraction<2>.
* Stream I/O::


File: TheLogtalkHandbook-3.101.0.info,  Node: Message construction,  Next: Standard error responses,  Up: API summary

6.135.5.1 Message construction
..............................

Predicates for building JSON-RPC 2.0 message terms.  Requests include an
‘id’ for matching responses; notifications do not.

   - ‘request(+Method, +Params, +Id, --Request)’ - Construct a request

   - ‘request(+Method, +Id, --Request)’ - Construct a request with no
     parameters

   - ‘notification(+Method, +Params, --Notification)’ - Construct a
     notification

   - ‘notification(+Method, --Notification)’ - Construct a notification
     with no parameters

   - ‘response(+Result, +Id, --Response)’ - Construct a successful
     response

   - ‘error_response(+Code, +Message, +Id, --ErrorResponse)’ - Construct
     an error response

   - ‘error_response(+Code, +Message, +Data, +Id, --ErrorResponse)’ -
     Construct an error response with data


File: TheLogtalkHandbook-3.101.0.info,  Node: Standard error responses,  Next: Encoding and decoding<2>,  Prev: Message construction,  Up: API summary

6.135.5.2 Standard error responses
..................................

Convenience predicates for the five standard JSON-RPC 2.0 error codes.

   - ‘parse_error(--ErrorResponse)’ - Parse error (-32700)

   - ‘invalid_request(--ErrorResponse)’ - Invalid request (-32600)

   - ‘method_not_found(+Id, --ErrorResponse)’ - Method not found
     (-32601)

   - ‘invalid_params(+Id, --ErrorResponse)’ - Invalid params (-32602)

   - ‘internal_error(+Id, --ErrorResponse)’ - Internal error (-32603)


File: TheLogtalkHandbook-3.101.0.info,  Node: Encoding and decoding<2>,  Next: Message classification<2>,  Prev: Standard error responses,  Up: API summary

6.135.5.3 Encoding and decoding
...............................

Convert between JSON-RPC message terms and JSON atoms (strings).

   - ‘encode(+Term, --JSON)’ - Encode a JSON-RPC term to a JSON atom

   - ‘decode(+JSON, --Term)’ - Decode a JSON atom to a JSON-RPC term


File: TheLogtalkHandbook-3.101.0.info,  Node: Message classification<2>,  Next: Field extraction<2>,  Prev: Encoding and decoding<2>,  Up: API summary

6.135.5.4 Message classification
................................

Test what kind of JSON-RPC message a term represents.

   - ‘is_request(+Term)’ - Test if a term is a request

   - ‘is_notification(+Term)’ - Test if a term is a notification

   - ‘is_response(+Term)’ - Test if a term is a successful response

   - ‘is_error_response(+Term)’ - Test if a term is an error response

   - ‘is_batch(+Term)’ - Test if a term is a batch (non-empty list)


File: TheLogtalkHandbook-3.101.0.info,  Node: Field extraction<2>,  Next: Stream I/O,  Prev: Message classification<2>,  Up: API summary

6.135.5.5 Field extraction
..........................

Extract individual fields from JSON-RPC message terms.

   - ‘id(+Message, --Id)’ - Extract the id field

   - ‘method(+Message, --Method)’ - Extract the method field

   - ‘params(+Message, --Params)’ - Extract the params field

   - ‘result(+Message, --Result)’ - Extract the result field

   - ‘error(+Message, --Error)’ - Extract the error object

   - ‘error_code(+Message, --Code)’ - Extract the error code

   - ‘error_message(+Message, --ErrorMessage)’ - Extract the error
     message

   - ‘error_data(+Message, --Data)’ - Extract the error data


File: TheLogtalkHandbook-3.101.0.info,  Node: Stream I/O,  Prev: Field extraction<2>,  Up: API summary

6.135.5.6 Stream I/O
....................

Read and write JSON-RPC messages over streams.  The newline-delimited
variants are suitable for socket-based communication.  The
Content-Length framed variants implement the header-based framing used
by the Language Server Protocol (LSP) and the Model Context Protocol
(MCP).

   - ‘write_message(+Output, +Message)’ - Write a newline-delimited
     message

   - ‘read_message(+Input, --Message)’ - Read a newline-delimited
     message

   - ‘write_framed_message(+Output, +Message)’ - Write a message with
     Content-Length framing

   - ‘read_framed_message(+Input, --Message)’ - Read a message with
     Content-Length framing


File: TheLogtalkHandbook-3.101.0.info,  Node: json_schema,  Next: jwt,  Prev: json_rpc,  Up: Libraries

6.136 ‘json_schema’
===================

The ‘json_schema’ library provides predicates for parsing JSON Schema
documents and validating JSON data against schemas.  It is based on the
JSON Schema specification found at:

   - ‘https://json-schema.org/’

This library builds on top of the ‘json’ library for JSON parsing and
uses the same representation choices for JSON data.

* Menu:

* API documentation: API documentation<154>.
* Loading: Loading<156>.
* Testing: Testing<148>.
* Schema Parsing::
* Validation::
* Supported Keywords::
* Known Limitations: Known Limitations<2>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<154>,  Next: Loading<156>,  Up: json_schema

6.136.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#json_schema’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<156>,  Next: Testing<148>,  Prev: API documentation<154>,  Up: json_schema

6.136.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(json_schema(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<148>,  Next: Schema Parsing,  Prev: Loading<156>,  Up: json_schema

6.136.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(json_schema(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Schema Parsing,  Next: Validation,  Prev: Testing<148>,  Up: json_schema

6.136.4 Schema Parsing
----------------------

Schemas can be parsed from various sources using the ‘parse/2’
predicate:

     | ?- json_schema::parse(file('schema.json'), Schema).

     | ?- json_schema::parse(atom('{"type": "string"}'), Schema).

     | ?- json_schema::parse(codes(Codes), Schema).


File: TheLogtalkHandbook-3.101.0.info,  Node: Validation,  Next: Supported Keywords,  Prev: Schema Parsing,  Up: json_schema

6.136.5 Validation
------------------

JSON data can be validated against a schema using the ‘validate/2’ or
‘validate/3’ predicates:

     % Success/failure validation
     | ?- json_schema::parse(atom('{"type": "string"}'), Schema),
          json_schema::validate(Schema, hello).
     yes

     | ?- json_schema::parse(atom('{"type": "string"}'), Schema),
          json_schema::validate(Schema, 42).
     no

     % Validation with error collection
     | ?- json_schema::parse(atom('{"type": "string"}'), Schema),
          json_schema::validate(Schema, 42, Errors).
     Errors = [error([], expected_type(string))]


File: TheLogtalkHandbook-3.101.0.info,  Node: Supported Keywords,  Next: Known Limitations<2>,  Prev: Validation,  Up: json_schema

6.136.6 Supported Keywords
--------------------------

The library supports the following JSON Schema keywords:

'Type validation:'

   - ‘type’ (string, number, integer, boolean, array, object, null)

   - Multiple types: ‘{"type": ["string", "number"]}’

'Generic validation:'

   - ‘enum’ - value must be one of the specified values

   - ‘const’ - value must be exactly the specified value

'String validation:'

   - ‘minLength’ - minimum string length

   - ‘maxLength’ - maximum string length

'Numeric validation:'

   - ‘minimum’ - minimum value (inclusive)

   - ‘maximum’ - maximum value (inclusive)

   - ‘exclusiveMinimum’ - minimum value (exclusive)

   - ‘exclusiveMaximum’ - maximum value (exclusive)

   - ‘multipleOf’ - value must be a multiple of this number

'Array validation:'

   - ‘items’ - schema for array items

   - ‘prefixItems’ - schemas for array items by position

   - ‘minItems’ - minimum number of items

   - ‘maxItems’ - maximum number of items

   - ‘uniqueItems’ - all items must be unique

   - ‘contains’ - at least one item must match the schema

'Object validation:'

   - ‘properties’ - schemas for object properties

   - ‘required’ - list of required property names

   - ‘minProperties’ - minimum number of properties

   - ‘maxProperties’ - maximum number of properties

   - ‘propertyNames’ - schema for property names

'Composition:'

   - ‘allOf’ - value must match all schemas

   - ‘anyOf’ - value must match at least one schema

   - ‘oneOf’ - value must match exactly one schema

   - ‘not’ - value must not match the schema

'Conditional:'

   - ‘if’/‘then’/‘else’ - conditional schema application

'Schema References:'

   - ‘$defs’/‘definitions’ - schema definitions

   - ‘$ref’ - local JSON Pointer references and local file references
     (e.g., ‘#/$defs/name’, ‘address.json’, ‘common.json#/$defs/name’)

'Format validation:'

The ‘format’ keyword validates string formats.  Non-string values pass
format validation.  Unknown formats are ignored per JSON Schema
specification.  Supported formats:

   - ‘email’ - basic email format (<local@domain>)

   - ‘date’ - ISO 8601 date (YYYY-MM-DD)

   - ‘time’ - ISO 8601 time (HH:MM:SS) with optional fractional seconds
     and timezone

   - ‘date-time’ - ISO 8601 combined date and time

   - ‘uri’ - URI with scheme (e.g., ‘http://example.com’)

   - ‘uri-reference’ - URI or relative reference

   - ‘hostname’ - RFC 1123 hostname

   - ‘ipv4’ - IPv4 address (dotted decimal notation)

   - ‘ipv6’ - IPv6 address (hex groups with colons, supports ::
     compression)

   - ‘uuid’ - UUID format (8-4-4-4-12 hex pattern)

   - ‘json-pointer’ - JSON Pointer (RFC 6901)

   - ‘relative-json-pointer’ - Relative JSON Pointer

'Boolean schemas:'

   - ‘true’ - accepts any value

   - ‘false’ - rejects all values


File: TheLogtalkHandbook-3.101.0.info,  Node: Known Limitations<2>,  Prev: Supported Keywords,  Up: json_schema

6.136.7 Known Limitations
-------------------------

The following JSON Schema features are not yet supported:

   - ‘pattern’ - regular expression validation (requires regex support)

   - ‘patternProperties’ - property matching by pattern

   - ‘format’ - formats not listed above (e.g., ‘regex’)

   - ‘$ref’ with remote URLs - external schema references require HTTP
     support


File: TheLogtalkHandbook-3.101.0.info,  Node: jwt,  Next: kcenters_clusterer,  Prev: json_schema,  Up: Libraries

6.137 ‘jwt’
===========

The ‘jwt’ library provides compact JWT parsing, JWS signing and
verification, JWK/JWKS key selection, and reusable registered-claim
validation predicates.

The current implementation supports native ‘HS256’ signing/verification
and OpenSSL-backed ‘RS256’/‘ES256’ verification.  ‘ES256’ signatures are
converted from JOSE raw ‘R || S’ encoding to DER before calling OpenSSL.

This library requires a Prolog backend supporting unbound integer
arithmetic.

* Menu:

* Requirements: Requirements<7>.
* API documentation: API documentation<155>.
* Loading: Loading<157>.
* Testing: Testing<149>.
* Options: Options<31>.
* Validation policy::
* Basic usage: Basic usage<3>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Requirements<7>,  Next: API documentation<155>,  Up: jwt

6.137.1 Requirements
--------------------

The ‘openssl’ command must be available on the current ‘PATH’.

On macOS, it can be installed using e.g.  Homebrew:

     $ brew install openssl

Or using MacPorts:

     $ sudo port install openssl

On Ubuntu, it can be installed using:

     $ sudo apt install openssl

On RedHat distributions (8.x and later):

     $ sudo dnf install openssl

For older RedHat distributions:

     $ sudo yum install openssl

On Windows, it can be installed using e.g.  Chocolatey:

     > choco install openssl


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<155>,  Next: Loading<157>,  Prev: Requirements<7>,  Up: jwt

6.137.2 API documentation
-------------------------

Open the ‘../../apis/library_index.html#jwt’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<157>,  Next: Testing<149>,  Prev: API documentation<155>,  Up: jwt

6.137.3 Loading
---------------

To load the library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(jwt(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<149>,  Next: Options<31>,  Prev: Loading<157>,  Up: jwt

6.137.4 Testing
---------------

To test this library, load the ‘tester.lgt’ file:

     | ?- logtalk_load(jwt(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<31>,  Next: Validation policy,  Prev: Testing<149>,  Up: jwt

6.137.5 Options
---------------

The facade predicates that take an options list validate the following
option terms.  Each option only affects predicates that perform the
corresponding operation.

Signature and algorithm options:

   - ‘allow_algorithms(Algorithms)’ - List of allowed JOSE ‘alg’ atom
     values for verification and signing.  The default is ‘['HS256',
     'RS256', 'ES256']’.

   - ‘algorithm(Algorithm)’ - Requires one exact JOSE ‘alg’ atom value.
     When used with ‘allow_algorithms/1’, both checks must pass.

   - ‘allow_none(Boolean)’ - Allows or rejects the unsecured ‘none’
     algorithm.  The default is ‘false’.

Claim validation options:

   - ‘allow_missing_exp(Boolean)’ - Allows tokens without an ‘exp’ claim
     when set to ‘true’.  The default is ‘false’.

   - ‘clock_skew(Seconds)’ - Non-negative numeric leeway, in seconds,
     for time claim validation.  The default is ‘60’.

   - ‘now(Timestamp)’ - Numeric timestamp to use instead of the current
     operating system time when validating time claims.

   - ‘max_age(Seconds)’ - Non-negative maximum age, in seconds, for
     policies that validate an ‘iat’ claim as ‘time(issued_at)’.

   - ‘required_claims(Names)’ - List of claim-name atoms that must be
     present when validating claims.  The default is ‘[]’.

   - ‘claim_policy(Policy)’ - Claim policy list applied by ‘verify/4’
     and ‘verify/5’ after signature verification.  When calling
     ‘validate_claims/3’ directly, pass the policy as the second
     argument instead.

OpenSSL options:

   - ‘openssl_executable(Executable)’ - Atom naming the OpenSSL
     executable or its path.  The default command name is ‘openssl’.

   - ‘openssl_arguments(Arguments)’ - List accepted by the option
     checker for OpenSSL command customization.  The current facade
     implementation does not add these arguments to the generated
     OpenSSL command.


File: TheLogtalkHandbook-3.101.0.info,  Node: Validation policy,  Next: Basic usage<3>,  Prev: Options<31>,  Up: jwt

6.137.6 Validation policy
-------------------------

The verification predicates apply a conservative JWT validation policy
in addition to signature verification:

   - JWT headers and claims must decode to JSON objects.  Objects with
     duplicate member names are rejected instead of using first-wins or
     last-wins semantics.

   - JWS ‘crit’ header parameters are rejected unless explicitly
     supported by the library.  The current implementation does not
     support extension header parameters that can be marked critical.

   - The ‘exp’ claim is required by default.  This is stricter than the
     base JWT specification, where registered claims are optional.  Use
     the option ‘allow_missing_exp(true)’ when verifying tokens whose
     issuer legitimately omits this claim.

   - Use ‘allow_algorithms/1’ to configure the allowed algorithm set.
     Use ‘algorithm/1’ when the caller expects one exact JOSE ‘alg’
     value.  When both options are present, both constraints must be
     satisfied.

   - When verifying with a JWK Set, all keys matching the token header
     ‘alg’ and optional ‘kid’ are tried in set order until a signature
     verifies.  Verification fails only after all matching candidate
     keys fail.

   - ‘HS256’ symmetric keys must contain at least 32 bytes of key
     material, matching the algorithm’s 256-bit security requirement.

   - RSA JWK ‘n’ and ‘e’ members must be minimally encoded positive
     Base64urlUInt values.  ‘RS256’ public moduli must be odd and at
     least 2048 bits, and public exponents must be odd integers greater
     than one and smaller than the modulus.

   - P-256 EC JWK coordinates must be 32-byte unsigned values in range
     and the point ‘(x,y)’ must lie on the P-256 curve.

   - Octet, RSA, and P-256 EC JWKs are validated before key material is
     used.  Malformed key objects raise JWT key-domain errors.

OpenSSL-backed ‘RS256’ and ‘ES256’ verification requires an ‘openssl’
command in the current command search path, unless overridden using
‘openssl_executable/1’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Basic usage<3>,  Prev: Validation policy,  Up: jwt

6.137.7 Basic usage
-------------------

Decode a compact JWT without verifying its signature:

     | ?- jwt::decode(Token, Header, Claims).

Inspect only selected header or claims data:

     | ?- jwt::peek_algorithm(Token, Algorithm).

     | ?- jwt::claim(Claims, sub, Subject).

Sign and verify a token using native ‘HS256’ support:

     | ?- Header = {alg-'HS256', typ-'JWT'},
          Claims = {sub-'123', exp-4102444800},
          jwt::sign(Header, Claims, '0123456789abcdef0123456789abcdef', Token, []),
          jwt::verify(Token, '0123456789abcdef0123456789abcdef', VerifiedClaims, []).

Validate claims independently from signature verification:

     | ?- Policy = [
              claim(iss, expected('https://issuer.example')),
              claim(aud, contains('client-id')),
              claim(exp, time(expiration))
          ],
          jwt::validate_claims(Claims, Policy, [now(1700000001)]).

Verify an asymmetric token using a JWK Set.  The library selects
matching keys using the JWT header ‘alg’ and optional ‘kid’ values:

     | ?- JWKSet = {keys-[PublicJWK]},
          jwt::verify(Token, JWKSet, Claims, [
              allow_algorithms(['RS256', 'ES256']),
              claim_policy([
                  claim(iss, expected('https://issuer.example')),
                  claim(aud, contains('client-id'))
              ])
          ]).

Use the ‘openssl_executable/1’ option when the OpenSSL command is not
named ‘openssl’ or is not found in the default command search path:

     | ?- jwt::verify(Token, JWKSet, Claims, [
              openssl_executable('/opt/local/bin/openssl')
          ]).


File: TheLogtalkHandbook-3.101.0.info,  Node: kcenters_clusterer,  Next: kemeny_young_ranker,  Prev: jwt,  Up: Libraries

6.138 ‘kcenters_clusterer’
==========================

k-Centers clusterer.  It uses a deterministic farthest-first center
selection heuristic.  Supports continuous attributes only.

The library implements the ‘clusterer_protocol’ defined in the
‘clustering_protocols’ library.  It provides predicates for learning a
clusterer from a dataset, assigning new instances to clusters, and
exporting the learned clusterer as a list of predicate clauses or to a
file.

Datasets are represented as objects implementing the
‘clustering_dataset_protocol’ protocol from the ‘clustering_protocols’
library.

* Menu:

* API documentation: API documentation<156>.
* Loading: Loading<158>.
* Testing: Testing<150>.
* Features: Features<31>.
* Options: Options<32>.
* Diagnostics: Diagnostics<4>.
* Clusterer representation: Clusterer representation<6>.
* References: References<20>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<156>,  Next: Loading<158>,  Up: kcenters_clusterer

6.138.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#kcenters_clusterer’ link in a
web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<158>,  Next: Testing<150>,  Prev: API documentation<156>,  Up: kcenters_clusterer

6.138.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(kcenters_clusterer(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<150>,  Next: Features<31>,  Prev: Loading<158>,  Up: kcenters_clusterer

6.138.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(kcenters_clusterer(tester)).

To run the performance benchmark suite, load the
‘tester_performance.lgt’ file:

     | ?- logtalk_load(kcenters_clusterer(tester_performance)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<31>,  Next: Options<32>,  Prev: Testing<150>,  Up: kcenters_clusterer

6.138.4 Features
----------------

   - 'Continuous Datasets': Accepts datasets containing only continuous
     attributes.

   - 'Farthest-First Center Selection': Uses a deterministic
     farthest-first heuristic to choose centers.

   - 'Deterministic Initialization': Supports ‘first_k’ and
     deterministic ‘spread’ initialization that repeatedly chooses the
     farthest example from the centers selected so far..

   - 'Distance Metrics': Supports Euclidean and Manhattan distances..

   - 'Optional Feature Scaling': Continuous attributes can be
     standardized using z-score scaling.

   - 'Rich Training Diagnostics': Learned clusterers report training
     example count, selected center count, and the center-selection
     strategy used during learning.

   - 'Portable Export': Learned clusterers can be exported as clauses or
     files and reused later.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<32>,  Next: Diagnostics<4>,  Prev: Features<31>,  Up: kcenters_clusterer

6.138.5 Options
---------------

The following options can be passed to the ‘learn/3’ predicate:

   - ‘k(K)’: Number of clusters to learn.  Default is ‘2’.

   - ‘initialization(Initialization)’: Center initialization strategy.
     Options: ‘spread’ (default) or ‘first_k’.

   - ‘distance_metric(Metric)’: Distance metric to use.  Options:
     ‘euclidean’ (default) or ‘manhattan’.

   - ‘feature_scaling(FeatureScaling)’: Whether to standardize
     continuous attributes before clustering.  Options: ‘on’ (default)
     or ‘off’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Diagnostics<4>,  Next: Clusterer representation<6>,  Prev: Options<32>,  Up: kcenters_clusterer

6.138.6 Diagnostics
-------------------

The ‘diagnostics/2’ predicate returns a list containing:

   - ‘model(kcenters_clusterer)’

   - ‘center_count(Count)’

   - ‘training_example_count(Count)’

   - ‘selection_strategy(Strategy)’

   - ‘options(Options)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Clusterer representation<6>,  Next: References<20>,  Prev: Diagnostics<4>,  Up: kcenters_clusterer

6.138.7 Clusterer representation
--------------------------------

The learned clusterer is represented as a compound term with the functor
chosen by the user when exporting the clusterer and arity 4.  For
example:

     kcenters_clusterer(Encoders, Centers, Options, Diagnostics)

Where:

   - ‘Encoders’: List of continuous attribute encoders storing attribute
     name, mean, and scale.

   - ‘Centers’: List of center vectors in cluster-id order.

   - ‘Options’: Effective training options used to learn the clusterer.

   - ‘Diagnostics’: Training diagnostics metadata returned by the
     ‘diagnostics/2’ predicate.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<20>,  Prev: Clusterer representation<6>,  Up: kcenters_clusterer

6.138.8 References
------------------

  1. Gonzalez (1985) - “Clustering to minimize the maximum intercluster
     distance”.  Theoretical Computer Science, 38, 293-306.


File: TheLogtalkHandbook-3.101.0.info,  Node: kemeny_young_ranker,  Next: kernel_svm_classifier,  Prev: kcenters_clusterer,  Up: Libraries

6.139 ‘kemeny_young_ranker’
===========================

Kemeny-Young pairwise preference ranker.  It aggregates head-to-head
preference weights, then performs an exact branch-and-bound search over
linear orders to maximize the total pairwise agreement score under the
Kemeny-Young criterion.

The library implements the ‘ranker_protocol’ defined in the
‘ranking_protocols’ library.  It provides predicates for learning an
exact consensus ranker from pairwise preferences, using it to order
candidate items, inspecting the learned consensus ranking and consensus
score, and exporting it as a list of predicate clauses or to a file.

Datasets are represented as objects implementing the
‘pairwise_ranking_dataset_protocol’ protocol from the
‘ranking_protocols’ library.  See the ‘test_datasets’ directory for
examples.  The current implementation requires a well-formed connected
pairwise dataset so that all ranked items remain part of a single
comparison graph.

* Menu:

* API documentation: API documentation<157>.
* Loading: Loading<159>.
* Testing: Testing<151>.
* Features: Features<32>.
* Usage: Usage<57>.
* Options: Options<33>.
* Scoring semantics: Scoring semantics<5>.
* Diagnostics syntax: Diagnostics syntax<12>.
* Ranker representation: Ranker representation<9>.
* Notes: Notes<8>.
* References: References<21>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<157>,  Next: Loading<159>,  Up: kemeny_young_ranker

6.139.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#kemeny_young_ranker’ link in a
web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<159>,  Next: Testing<151>,  Prev: API documentation<157>,  Up: kemeny_young_ranker

6.139.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(kemeny_young_ranker(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<151>,  Next: Features<32>,  Prev: Loading<159>,  Up: kemeny_young_ranker

6.139.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(kemeny_young_ranker(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<32>,  Next: Usage<57>,  Prev: Testing<151>,  Up: kemeny_young_ranker

6.139.4 Features
----------------

   - 'Exact Consensus Ranking': Learns one deterministic Kemeny-Young
     consensus order from aggregated pairwise outcomes.

   - 'Branch-and-Bound Search': Uses exact search with pruning over
     linear orders to maximize total pairwise agreement.

   - 'Deterministic Optimal Tie Breaking': Supports both standard
     term-order and dataset declaration-order selection when multiple
     optimal consensus rankings exist.

   - 'Consensus Access': Exposes the learned full-item consensus ranking
     and its maximum agreement score using the ‘consensus_ranking/2’ and
     ‘consensus_score/2’ predicates.

   - 'Deterministic Ranking': Orders candidate items by the selected
     consensus order with deterministic tie-breaking.  When multiple
     optimal Kemeny orders exist, the ‘tie_breaking/1’ option selects
     the deterministic search order used to choose one representative
     consensus ranking.

   - 'Strict Dataset Validation': Rejects duplicate items, undeclared
     items, self-preferences, non-positive weights, and disconnected
     comparison graphs.

   - 'Training Diagnostics': Learned rankers include dataset summary
     metadata, the effective tie-breaking mode, the selected consensus
     ranking, and the maximum agreement score.

   - 'Ranker Export': Learned rankers can be exported as self-contained
     terms.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<57>,  Next: Options<33>,  Prev: Features<32>,  Up: kemeny_young_ranker

6.139.5 Usage
-------------

* Menu:

* Learning a ranker: Learning a ranker<9>.
* Inspecting the learned consensus::
* Ranking candidate items: Ranking candidate items<8>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Learning a ranker<9>,  Next: Inspecting the learned consensus,  Up: Usage<57>

6.139.5.1 Learning a ranker
...........................

     % Learn from a pairwise ranking dataset object
     | ?- kemeny_young_ranker::learn(my_dataset, Ranker).
     ...

     % Learn with custom optimal-order tie breaking
     | ?- kemeny_young_ranker::learn(my_dataset, Ranker, [tie_breaking(declaration_order)]).
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Inspecting the learned consensus,  Next: Ranking candidate items<8>,  Prev: Learning a ranker<9>,  Up: Usage<57>

6.139.5.2 Inspecting the learned consensus
..........................................

     % Inspect the learned full-item consensus ranking
     | ?- kemeny_young_ranker::learn(my_dataset, Ranker),
          kemeny_young_ranker::consensus_ranking(Ranker, ConsensusRanking).
     ConsensusRanking = [...]
     ...

     % Inspect the maximum pairwise agreement score
     | ?- kemeny_young_ranker::learn(my_dataset, Ranker),
          kemeny_young_ranker::consensus_score(Ranker, ConsensusScore).
     ConsensusScore = ...
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Ranking candidate items<8>,  Prev: Inspecting the learned consensus,  Up: Usage<57>

6.139.5.3 Ranking candidate items
.................................

     % Rank a candidate set from most preferred to least preferred
     | ?- kemeny_young_ranker::learn(my_dataset, Ranker),
          kemeny_young_ranker::rank(Ranker, [item_a, item_b, item_c], Ranking).
     Ranking = [...]
     ...

Candidate lists must be proper lists of unique, ground items declared by
the training dataset.  Invalid ranker terms, duplicate candidates, and
candidates containing variables are rejected with errors instead of
being silently accepted.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<33>,  Next: Scoring semantics<5>,  Prev: Usage<57>,  Up: kemeny_young_ranker

6.139.6 Options
---------------

The following options can be passed to the ‘learn/3’ predicate:

   - ‘tie_breaking(term_order)’: Select the lexicographically earliest
     optimal consensus ranking using the standard term order of the item
     identifiers.

   - ‘tie_breaking(declaration_order)’: Select the earliest optimal
     consensus ranking using the dataset declaration order preserved by
     the pairwise dataset helpers.

The default is ‘tie_breaking(term_order)’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Scoring semantics<5>,  Next: Diagnostics syntax<12>,  Prev: Options<33>,  Up: kemeny_young_ranker

6.139.7 Scoring semantics
-------------------------

The learned ‘scores/2’ values are reverse consensus positions.  For a
learned consensus order with ‘N’ items, the first item receives score
‘N-1’ and the last item receives score ‘0’.

This positional encoding is a deterministic surrogate used to satisfy
the shared ‘ranker_protocol’ scoring interface.  The authoritative
Kemeny-Young output is the full ‘consensus_ranking/2’ order together
with its ‘consensus_score/2’ agreement value.


File: TheLogtalkHandbook-3.101.0.info,  Node: Diagnostics syntax<12>,  Next: Ranker representation<9>,  Prev: Scoring semantics<5>,  Up: kemeny_young_ranker

6.139.8 Diagnostics syntax
--------------------------

The ‘diagnostics/2’ predicate returns a list of metadata terms with the
form:

     [
         model(kemeny_young_ranker),
         options(Options),
         consensus_ranking(ConsensusRanking),
         consensus_score(ConsensusScore),
         dataset_summary(DatasetSummary)
     ]


File: TheLogtalkHandbook-3.101.0.info,  Node: Ranker representation<9>,  Next: Notes<8>,  Prev: Diagnostics syntax<12>,  Up: kemeny_young_ranker

6.139.9 Ranker representation
-----------------------------

The learned ranker is represented by a compound term of the form:

     kemeny_young_ranker(Items, Scores, Diagnostics)

Where:

   - ‘Items’: List of ranked items.

   - ‘Scores’: List of ‘Item-Score’ pairs.

   - ‘Diagnostics’: List of metadata terms, including the effective
     options, selected consensus ranking, maximum agreement score, and
     dataset summary.


File: TheLogtalkHandbook-3.101.0.info,  Node: Notes<8>,  Next: References<21>,  Prev: Ranker representation<9>,  Up: kemeny_young_ranker

6.139.10 Notes
--------------

Kemeny-Young optimization is NP-hard in general.  This implementation
uses an exact branch-and-bound search and is intended for small to
moderate item sets.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<21>,  Prev: Notes<8>,  Up: kemeny_young_ranker

6.139.11 References
-------------------

  1. Kemeny, J. G. (1959).  'Mathematics without numbers'.

  2. Young, H. P. (1988).  'Condorcet’s theory of voting'.


File: TheLogtalkHandbook-3.101.0.info,  Node: kernel_svm_classifier,  Next: kernel_pca_projection,  Prev: kemeny_young_ranker,  Up: Libraries

6.140 ‘kernel_svm_classifier’
=============================

Kernel support vector machine classifier using one-vs-rest dual margin
models with linear, polynomial, and radial basis function kernels.  The
implementation encodes tabular datasets using the shared linear encoder
pipeline so mixed continuous and categorical datasets are handled
consistently with the existing linear classifiers.

The library implements the ‘classifier_protocol’ defined in the
‘classification_protocols’ library.  It provides predicates for learning
a classifier from a dataset, using it to make predictions, estimating
class probabilities, and exporting it as a list of predicate clauses or
to a file.

Datasets are represented as objects implementing the ‘dataset_protocol’
protocol from the ‘classification_protocols’ library.  Continuous,
categorical, and mixed-feature datasets are supported.

* Menu:

* API documentation: API documentation<158>.
* Loading: Loading<160>.
* Testing: Testing<152>.
* Features: Features<33>.
* Options: Options<34>.
* Usage: Usage<58>.
* Classifier representation: Classifier representation<3>.
* References: References<22>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<158>,  Next: Loading<160>,  Up: kernel_svm_classifier

6.140.1 API documentation
-------------------------

Open the ‘../../docs/library_index.html#kernel_svm_classifier’ link in a
web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<160>,  Next: Testing<152>,  Prev: API documentation<158>,  Up: kernel_svm_classifier

6.140.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(kernel_svm_classifier(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<152>,  Next: Features<33>,  Prev: Loading<160>,  Up: kernel_svm_classifier

6.140.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(kernel_svm_classifier(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<33>,  Next: Options<34>,  Prev: Testing<152>,  Up: kernel_svm_classifier

6.140.4 Features
----------------

   - 'Binary and Multiclass Classification': Learns one-vs-rest dual
     models and predicts the class with the highest decision score.

   - 'Multiple Kernels': Supports ‘linear’, ‘polynomial(Degree, Gamma,
     Coef0)’, and ‘rbf(Gamma)’ kernels.

   - 'Mixed Features': Reuses the shared tabular encoders for continuous
     and categorical attributes, including missing-value indicators.

   - 'Probability Estimation': Provides class probabilities using a
     softmax over kernel decision scores.

   - 'Regularized Training': Supports configurable learning-rate
     scheduling, tolerance, and L2 regularization.

   - 'Classifier Export': Learned classifiers can be exported as
     predicate clauses or written to a file.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<34>,  Next: Usage<58>,  Prev: Features<33>,  Up: kernel_svm_classifier

6.140.5 Options
---------------

The ‘learn/3’ predicate supports these options:

   - ‘kernel/1’ - kernel function to use (default: ‘linear’)

   - ‘learning_rate/1’ - base learning rate for the dual optimization
     loop (default: ‘0.5’)

   - ‘learning_schedule/1’ - learning-rate schedule, either ‘constant’
     or ‘inverse_scaling(Power)’ (default: ‘constant’)

   - ‘maximum_iterations/1’ - maximum number of optimization epochs
     (default: ‘25’)

   - ‘tolerance/1’ - convergence threshold for the maximum parameter
     update (default: ‘1.0e-5’)

   - ‘l2_regularization/1’ - L2 penalty factor applied during
     optimization (default: ‘0.001’)

   - ‘feature_scaling/1’ - whether to standardize continuous attributes
     before encoding (default: ‘true’)


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<58>,  Next: Classifier representation<3>,  Prev: Options<34>,  Up: kernel_svm_classifier

6.140.6 Usage
-------------

* Menu:

* Learning a classifier: Learning a classifier<2>.
* Making predictions: Making predictions<2>.
* Exporting the classifier: Exporting the classifier<2>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Learning a classifier<2>,  Next: Making predictions<2>,  Up: Usage<58>

6.140.6.1 Learning a classifier
...............................

     | ?- kernel_svm_classifier::learn(weather, Classifier).

     | ?- kernel_svm_classifier::learn(mixed, Classifier, [kernel(rbf(0.5)), maximum_iterations(50)]).


File: TheLogtalkHandbook-3.101.0.info,  Node: Making predictions<2>,  Next: Exporting the classifier<2>,  Prev: Learning a classifier<2>,  Up: Usage<58>

6.140.6.2 Making predictions
............................

     | ?- kernel_svm_classifier::learn(mixed, Classifier),
          kernel_svm_classifier::predict(Classifier, [age-35, income-65000, student-yes, credit_rating-fair], Class).

     | ?- kernel_svm_classifier::learn(weather, Classifier),
          kernel_svm_classifier::predict_probabilities(Classifier, [outlook-sunny, temperature-hot, humidity-high, windy-false], Probabilities).


File: TheLogtalkHandbook-3.101.0.info,  Node: Exporting the classifier<2>,  Prev: Making predictions<2>,  Up: Usage<58>

6.140.6.3 Exporting the classifier
..................................

     | ?- kernel_svm_classifier::learn(weather, Classifier),
          kernel_svm_classifier::export_to_clauses(weather, Classifier, classify, Clauses).

     | ?- kernel_svm_classifier::learn(weather, Classifier),
          kernel_svm_classifier::export_to_file(weather, Classifier, classify, 'classifier.pl').


File: TheLogtalkHandbook-3.101.0.info,  Node: Classifier representation<3>,  Next: References<22>,  Prev: Usage<58>,  Up: kernel_svm_classifier

6.140.7 Classifier representation
---------------------------------

The learned classifier is represented as a compound term with the form:

     kernel_svm_classifier(Classes, Encoders, Kernel, TrainingRows, Models, Options)

Where:

   - ‘Classes’: list of class labels

   - ‘Encoders’: list of continuous scaling descriptors and categorical
     value encoders

   - ‘Kernel’: selected kernel specification

   - ‘TrainingRows’: encoded feature vectors for the training examples

   - ‘Models’: list of ‘class_model(Class, Bias, Coefficients)’ terms

   - ‘Options’: merged training options used to learn the classifier

When exported using ‘export_to_clauses/4’ or ‘export_to_file/4’, this
classifier term is serialized directly as the single argument of the
generated predicate clause so that the exported model can be loaded and
reused as-is.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<22>,  Prev: Classifier representation<3>,  Up: kernel_svm_classifier

6.140.8 References
------------------

  1. Cortes, C. and Vapnik, V. (1995).  “Support-Vector Networks”.

  2. Scholkopf, B. and Smola, A.J. (2002).  “Learning with Kernels”.

  3. Bishop, C.M. (2006).  “Pattern Recognition and Machine Learning”.
     Chapter 7.


File: TheLogtalkHandbook-3.101.0.info,  Node: kernel_pca_projection,  Next: kmeans_clusterer,  Prev: kernel_svm_classifier,  Up: Libraries

6.141 ‘kernel_pca_projection’
=============================

Kernel Principal Component Analysis reducer for continuous datasets.
The library implements the ‘dimension_reducer_protocol’ defined in the
‘dimension_reduction_protocols’ library and learns a nonlinear
projection by centering the training data, optionally standardizing
continuous attributes, building a centered kernel Gram matrix, and
extracting deterministic principal directions in sample space using
portable power iteration with deflation.

* Menu:

* API documentation: API documentation<159>.
* Loading: Loading<161>.
* Testing: Testing<153>.
* Features: Features<34>.
* Options: Options<35>.
* Usage: Usage<59>.
* Dimension reducer representation: Dimension reducer representation<2>.
* References: References<23>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<159>,  Next: Loading<161>,  Up: kernel_pca_projection

6.141.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#kernel_pca_projection’ link in a
web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<161>,  Next: Testing<153>,  Prev: API documentation<159>,  Up: kernel_pca_projection

6.141.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(kernel_pca_projection(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<153>,  Next: Features<34>,  Prev: Loading<161>,  Up: kernel_pca_projection

6.141.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(kernel_pca_projection(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<34>,  Next: Options<35>,  Prev: Testing<153>,  Up: kernel_pca_projection

6.141.4 Features
----------------

   - 'Continuous Datasets': Accepts datasets containing only continuous
     attributes.  Missing or nonnumeric values are rejected.

   - 'Centering and Optional Scaling': Centers all attributes and
     optionally standardizes them before evaluating kernels.

   - 'Configurable Shortfall Handling': Lets callers choose whether a
     component-extraction shortfall raises an error or truncates the
     learned reducer with explicit diagnostics.

   - 'Supported Kernels': Supports linear, polynomial with non-negative
     offset, and radial basis function kernels through the ‘kernel/1’
     option.

   - 'Shared Gram-Centering Helpers': Delegates training Gram-matrix
     centering and out-of-sample Gram-vector centering to the shared
     ‘linear_algebra’ library.

   - 'Portable Eigensolver': Uses deterministic power iteration with
     deflation instead of backend-specific linear algebra libraries.

   - 'Projection API': Transforms a new instance into a list of
     ‘component_N-Value’ pairs using centered kernel evaluations against
     the training rows.

   - 'Model Export': Learned reducers can be exported as predicate
     clauses or written to a file.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<35>,  Next: Usage<59>,  Prev: Features<34>,  Up: kernel_pca_projection

6.141.5 Options
---------------

The ‘learn/3’ predicate accepts the following options:

   - ‘n_components/1’: Number of kernel principal components to extract.
     Requests that exceed ‘SampleCount - 1’ raise
     ‘domain_error(component_count, Requested-Maximum)’.  The default is
     ‘2’.

   - ‘feature_scaling/1’: Whether to standardize continuous attributes
     before evaluating kernels.  Options: ‘true’ (default) or ‘false’.

   - ‘shortfall_policy/1’: Controls what happens when the centered
     kernel Gram matrix yields fewer numerically significant components
     than requested.  Options: ‘truncate’ (default), which returns a
     reducer with fewer components and records a
     ‘shortfall(truncated(Requested, Learned, ResidualEigenvalue,
     Tolerance))’ diagnostic, or ‘error’, which raises
     ‘domain_error(component_count, Requested-Learned)’.

   - ‘kernel/1’: Kernel specification.  Supported values are ‘linear’
     (default), ‘polynomial(Degree, Gamma, Coef0)’ with positive
     ‘Degree’, positive ‘Gamma’, and non-negative ‘Coef0’, and
     ‘rbf(Gamma)’ with positive ‘Gamma’.

   - ‘maximum_iterations/1’: Maximum number of power-iteration steps
     used when estimating each dual principal direction.  The default is
     ‘1000’.

   - ‘tolerance/1’: Positive convergence tolerance used both for
     power-iteration stopping and for deciding when deflated eigenvalues
     are negligible.  The default is ‘1.0e-8’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<59>,  Next: Dimension reducer representation<2>,  Prev: Options<35>,  Up: kernel_pca_projection

6.141.6 Usage
-------------

The following examples use the sample datasets shipped with the
‘dimension_reduction_protocols’ library:

     | ?- logtalk_load(dimension_reduction_protocols('test_datasets/correlated_plane')).

* Menu:

* Learning a reducer: Learning a reducer<2>.
* Transforming new instances: Transforming new instances<2>.
* Exporting and reusing the reducer: Exporting and reusing the reducer<2>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Learning a reducer<2>,  Next: Transforming new instances<2>,  Up: Usage<59>

6.141.6.1 Learning a reducer
............................

     | ?- kernel_pca_projection::learn(correlated_plane, DimensionReducer).

     | ?- kernel_pca_projection::learn(correlated_plane, DimensionReducer, [n_components(1), kernel(rbf(0.25))]).


File: TheLogtalkHandbook-3.101.0.info,  Node: Transforming new instances<2>,  Next: Exporting and reusing the reducer<2>,  Prev: Learning a reducer<2>,  Up: Usage<59>

6.141.6.2 Transforming new instances
....................................

     | ?- kernel_pca_projection::learn(correlated_plane, DimensionReducer, [n_components(2), kernel(rbf(0.25))]),
          kernel_pca_projection::transform(DimensionReducer, [x-2.0, y-4.0, z-6.0], ReducedInstance).


File: TheLogtalkHandbook-3.101.0.info,  Node: Exporting and reusing the reducer<2>,  Prev: Transforming new instances<2>,  Up: Usage<59>

6.141.6.3 Exporting and reusing the reducer
...........................................

     | ?- kernel_pca_projection::learn(correlated_plane, DimensionReducer, [n_components(1)]),
          kernel_pca_projection::export_to_file(correlated_plane, DimensionReducer, reducer, 'kernel_pca_reducer.pl').

     | ?- logtalk_load('kernel_pca_reducer.pl'),
          reducer(Reducer),
          kernel_pca_projection::transform(Reducer, [x-1.0, y-2.0, z-3.0], ReducedInstance).


File: TheLogtalkHandbook-3.101.0.info,  Node: Dimension reducer representation<2>,  Next: References<23>,  Prev: Usage<59>,  Up: kernel_pca_projection

6.141.7 Dimension reducer representation
----------------------------------------

The learned dimension reducer is represented by a compound term with the
functor chosen by the implementation and arity 7.  For example:

     kernel_pca_reducer(Encoders, TrainingRows, RowMeans, TotalMean, Components, ExplainedVariances, Diagnostics)

Where:

   - ‘Encoders’: List of continuous attribute encoders storing attribute
     name, mean, and scale.

   - ‘TrainingRows’: Encoded training rows used when evaluating kernels
     for new instances.

   - ‘RowMeans’: Per-training-row kernel means used for centering
     out-of-sample kernel vectors.

   - ‘TotalMean’: Global kernel mean used for centering both the
     training Gram matrix and new kernel vectors.

   - ‘Components’: List of normalized dual projection vectors in
     descending variance order.

   - ‘ExplainedVariances’: List of kernel Gram matrix eigenvalues
     matching the extracted components.

   - ‘Diagnostics’: Learned metadata including the effective training
     options, kernel preprocessing, sample count, explained variances,
     and optional truncate-mode shortfall details.

When exported using ‘export_to_clauses/4’ or ‘export_to_file/4’, this
reducer term is serialized directly as the single argument of the
generated predicate clause so that the exported model can be loaded and
reused as-is.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<23>,  Prev: Dimension reducer representation<2>,  Up: kernel_pca_projection

6.141.8 References
------------------

  1. Schölkopf, B., Smola, A., and Müller, K.-R. (1998) - “Nonlinear
     component analysis as a kernel eigenvalue problem”.

  2. Shawe-Taylor, J. and Cristianini, N. (2004) - “Kernel Methods for
     Pattern Analysis”.


File: TheLogtalkHandbook-3.101.0.info,  Node: kmeans_clusterer,  Next: kmedians_clusterer,  Prev: kernel_pca_projection,  Up: Libraries

6.142 ‘kmeans_clusterer’
========================

k-Means clusterer.  It uses Lloyd’s algorithm with deterministic
initialization.  Supports continuous attributes only.

The library implements the ‘clusterer_protocol’ defined in the
‘clustering_protocols’ library.  It provides predicates for learning a
clusterer from a dataset, assigning new instances to clusters, and
exporting the learned clusterer as a list of predicate clauses or to a
file.

Datasets are represented as objects implementing the
‘clustering_dataset_protocol’ protocol from the ‘clustering_protocols’
library.

* Menu:

* API documentation: API documentation<160>.
* Loading: Loading<162>.
* Testing: Testing<154>.
* Features: Features<35>.
* Options: Options<36>.
* Diagnostics: Diagnostics<5>.
* Clusterer representation: Clusterer representation<7>.
* References: References<24>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<160>,  Next: Loading<162>,  Up: kmeans_clusterer

6.142.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#kmeans_clusterer’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<162>,  Next: Testing<154>,  Prev: API documentation<160>,  Up: kmeans_clusterer

6.142.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(kmeans_clusterer(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<154>,  Next: Features<35>,  Prev: Loading<162>,  Up: kmeans_clusterer

6.142.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(kmeans_clusterer(tester)).

To run the performance benchmark suite, load the
‘tester_performance.lgt’ file:

     | ?- logtalk_load(kmeans_clusterer(tester_performance)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<35>,  Next: Options<36>,  Prev: Testing<154>,  Up: kmeans_clusterer

6.142.4 Features
----------------

   - 'Continuous Datasets': Accepts datasets containing only continuous
     attributes.

   - 'Deterministic Initialization': Supports ‘first_k’ and
     deterministic ‘spread’ initialization that repeatedly chooses the
     farthest example from the centroids selected so far.

   - 'Optional Feature Scaling': Continuous attributes can be
     standardized using z-score scaling.

   - 'Rich Training Diagnostics': Learned clusterers report training
     example count, convergence status, iteration count, and final
     centroid shift.

   - 'Portable Export': Learned clusterers can be exported as clauses or
     files and reused later.

   - 'Stable Empty-Cluster Handling': Empty clusters keep their previous
     centroids instead of failing.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<36>,  Next: Diagnostics<5>,  Prev: Features<35>,  Up: kmeans_clusterer

6.142.5 Options
---------------

The following options can be passed to the ‘learn/3’ predicate:

   - ‘k(K)’: Number of clusters to learn.  Default is ‘2’.

   - ‘maximum_iterations(Iterations)’: Maximum number of Lloyd
     iterations.  Default is ‘100’.

   - ‘tolerance(Tolerance)’: Maximum centroid shift threshold for
     convergence.  Default is ‘1.0e-6’.

   - ‘initialization(Initialization)’: Centroid initialization strategy.
     Options: ‘spread’ (default) or ‘first_k’.

   - ‘feature_scaling(FeatureScaling)’: Whether to standardize
     continuous attributes before clustering.  Options: ‘on’ (default)
     or ‘off’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Diagnostics<5>,  Next: Clusterer representation<7>,  Prev: Options<36>,  Up: kmeans_clusterer

6.142.6 Diagnostics
-------------------

The ‘diagnostics/2’ predicate returns a list containing:

   - ‘model(kmeans_clusterer)’

   - ‘centroid_count(Count)’

   - ‘training_example_count(Count)’

   - ‘convergence(Reason)’

   - ‘iterations(Count)’

   - ‘final_shift(Shift)’

   - ‘options(Options)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Clusterer representation<7>,  Next: References<24>,  Prev: Diagnostics<5>,  Up: kmeans_clusterer

6.142.7 Clusterer representation
--------------------------------

The learned clusterer is represented as a compound term with the functor
chosen by the user when exporting the clusterer and arity 4.  For
example:

     kmeans_clusterer(Encoders, Centroids, Options, Diagnostics)

Where:

   - ‘Encoders’: List of continuous attribute encoders storing attribute
     name, mean, and scale.

   - ‘Centroids’: List of centroid vectors in cluster-id order.

   - ‘Options’: Effective training options used to learn the clusterer.

   - ‘Diagnostics’: Training diagnostics metadata returned by the
     ‘diagnostics/2’ predicate.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<24>,  Prev: Clusterer representation<7>,  Up: kmeans_clusterer

6.142.8 References
------------------

  1. MacQueen (1967) - “Some Methods for Classification and Analysis of
     Multivariate Observations”.  Proceedings of the Fifth Berkeley
     Symposium on Mathematical Statistics and Probability.

  2. Lloyd (1982) - “Least Squares Quantization in PCM”.  IEEE
     Transactions on Information Theory, 28(2), 129-137.


File: TheLogtalkHandbook-3.101.0.info,  Node: kmedians_clusterer,  Next: kmedoids_clusterer,  Prev: kmeans_clusterer,  Up: Libraries

6.143 ‘kmedians_clusterer’
==========================

k-Medians clusterer.  It uses an iterative median-update algorithm with
deterministic initialization.  Supports continuous attributes only.

The library implements the ‘clusterer_protocol’ defined in the
‘clustering_protocols’ library.  It provides predicates for learning a
clusterer from a dataset, assigning new instances to clusters, and
exporting the learned clusterer as a list of predicate clauses or to a
file.

Datasets are represented as objects implementing the
‘clustering_dataset_protocol’ protocol from the ‘clustering_protocols’
library.

* Menu:

* API documentation: API documentation<161>.
* Loading: Loading<163>.
* Testing: Testing<155>.
* Features: Features<36>.
* Options: Options<37>.
* Diagnostics: Diagnostics<6>.
* Clusterer representation: Clusterer representation<8>.
* References: References<25>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<161>,  Next: Loading<163>,  Up: kmedians_clusterer

6.143.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#kmedians_clusterer’ link in a
web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<163>,  Next: Testing<155>,  Prev: API documentation<161>,  Up: kmedians_clusterer

6.143.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(kmedians_clusterer(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<155>,  Next: Features<36>,  Prev: Loading<163>,  Up: kmedians_clusterer

6.143.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(kmedians_clusterer(tester)).

To run the performance benchmark suite, load the
‘tester_performance.lgt’ file:

     | ?- logtalk_load(kmedians_clusterer(tester_performance)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<36>,  Next: Options<37>,  Prev: Testing<155>,  Up: kmedians_clusterer

6.143.4 Features
----------------

   - 'Continuous Datasets': Accepts datasets containing only continuous
     attributes.

   - 'Deterministic Initialization': Supports ‘first_k’ and
     deterministic ‘spread’ initialization that repeatedly chooses the
     farthest example from the medians selected so far.

   - 'Optional Feature Scaling': Continuous attributes can be
     standardized using z-score scaling.

   - 'Manhattan Distance': Uses Manhattan distance for cluster
     assignment and convergence checks.

   - 'Rich Training Diagnostics': Learned clusterers report training
     example count, convergence status, iteration count, and final
     median shift.

   - 'Portable Export': Learned clusterers can be exported as clauses or
     files and reused later.

   - 'Stable Empty-Cluster Handling': Empty clusters keep their previous
     medians instead of failing.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<37>,  Next: Diagnostics<6>,  Prev: Features<36>,  Up: kmedians_clusterer

6.143.5 Options
---------------

The following options can be passed to the ‘learn/3’ predicate:

   - ‘k(K)’: Number of clusters to learn.  Default is ‘2’.

   - ‘maximum_iterations(Iterations)’: Maximum number of median-update
     iterations.  Default is ‘100’.

   - ‘tolerance(Tolerance)’: Maximum median shift threshold for
     convergence.  Default is ‘1.0e-6’.

   - ‘initialization(Initialization)’: Median initialization strategy.
     Options: ‘spread’ (default) or ‘first_k’.

   - ‘feature_scaling(FeatureScaling)’: Whether to standardize
     continuous attributes before clustering.  Options: ‘on’ (default)
     or ‘off’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Diagnostics<6>,  Next: Clusterer representation<8>,  Prev: Options<37>,  Up: kmedians_clusterer

6.143.6 Diagnostics
-------------------

The ‘diagnostics/2’ predicate returns a list containing:

   - ‘model(kmedians_clusterer)’

   - ‘median_count(Count)’

   - ‘training_example_count(Count)’

   - ‘convergence(Reason)’

   - ‘iterations(Count)’

   - ‘final_shift(Shift)’

   - ‘options(Options)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Clusterer representation<8>,  Next: References<25>,  Prev: Diagnostics<6>,  Up: kmedians_clusterer

6.143.7 Clusterer representation
--------------------------------

The learned clusterer is represented as a compound term with the functor
chosen by the user when exporting the clusterer and arity 4.  For
example:

     kmedians_clusterer(Encoders, Medians, Options, Diagnostics)

Where:

   - ‘Encoders’: List of continuous attribute encoders storing attribute
     name, mean, and scale.

   - ‘Medians’: List of median vectors in cluster-id order.

   - ‘Options’: Effective training options used to learn the clusterer.

   - ‘Diagnostics’: Training diagnostics metadata returned by the
     ‘diagnostics/2’ predicate.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<25>,  Prev: Clusterer representation<8>,  Up: kmedians_clusterer

6.143.8 References
------------------

  1. MacQueen (1967) - “Some Methods for Classification and Analysis of
     Multivariate Observations”.  Proceedings of the Fifth Berkeley
     Symposium on Mathematical Statistics and Probability.

  2. Kaufman & Rousseeuw (1990) - “Finding Groups in Data: An
     Introduction to Cluster Analysis”.  Wiley.


File: TheLogtalkHandbook-3.101.0.info,  Node: kmedoids_clusterer,  Next: kmodes_clusterer,  Prev: kmedians_clusterer,  Up: Libraries

6.144 ‘kmedoids_clusterer’
==========================

k-Medoids clusterer.  It uses an iterative medoid-update algorithm with
deterministic initialization and deterministic cluster assignments.
Supports continuous attributes only.

The library implements the ‘clusterer_protocol’ defined in the
‘clustering_protocols’ library.  It provides predicates for learning a
clusterer from a dataset, assigning new instances to clusters, and
exporting the learned clusterer as a list of predicate clauses or to a
file.

Datasets are represented as objects implementing the
‘clustering_dataset_protocol’ protocol from the ‘clustering_protocols’
library.

* Menu:

* API documentation: API documentation<162>.
* Loading: Loading<164>.
* Testing: Testing<156>.
* Features: Features<37>.
* Options: Options<38>.
* Diagnostics: Diagnostics<7>.
* Clusterer representation: Clusterer representation<9>.
* References: References<26>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<162>,  Next: Loading<164>,  Up: kmedoids_clusterer

6.144.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#kmedoids_clusterer’ link in a
web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<164>,  Next: Testing<156>,  Prev: API documentation<162>,  Up: kmedoids_clusterer

6.144.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(kmedoids_clusterer(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<156>,  Next: Features<37>,  Prev: Loading<164>,  Up: kmedoids_clusterer

6.144.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(kmedoids_clusterer(tester)).

To run the performance benchmark suite, load the
‘tester_performance.lgt’ file:

     | ?- logtalk_load(kmedoids_clusterer(tester_performance)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<37>,  Next: Options<38>,  Prev: Testing<156>,  Up: kmedoids_clusterer

6.144.4 Features
----------------

   - 'Continuous Datasets': Accepts datasets containing only continuous
     attributes.

   - 'Distance Metrics': Supports Euclidean and Manhattan distances.

   - 'Deterministic Initialization': Supports ‘first_k’ and
     deterministic ‘spread’ initialization that repeatedly chooses the
     farthest example from the medoids selected so far.

   - 'Optional Feature Scaling': Continuous attributes can be
     standardized using z-score scaling.

   - 'Rich Training Diagnostics': Learned clusterers report training
     example count, convergence status, iteration count, and final
     medoid shift.

   - 'Portable Export': Learned clusterers can be exported as clauses or
     files and reused later.

   - 'Stable Empty-Cluster Handling': Empty clusters keep their previous
     medoids instead of failing.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<38>,  Next: Diagnostics<7>,  Prev: Features<37>,  Up: kmedoids_clusterer

6.144.5 Options
---------------

The following options can be passed to the ‘learn/3’ predicate:

   - ‘k(K)’: Number of clusters to learn.  Default is ‘2’.

   - ‘maximum_iterations(Iterations)’: Maximum number of medoid-update
     iterations.  Default is ‘100’.

   - ‘tolerance(Tolerance)’: Maximum medoid shift threshold for
     convergence.  Default is ‘1.0e-6’.

   - ‘initialization(Initialization)’: Medoid initialization strategy.
     Options: ‘spread’ (default) or ‘first_k’.

   - ‘distance_metric(Metric)’: Distance metric to use.  Options:
     ‘euclidean’ (default) or ‘manhattan’.

   - ‘feature_scaling(FeatureScaling)’: Whether to standardize
     continuous attributes before clustering.  Options: ‘on’ (default)
     or ‘off’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Diagnostics<7>,  Next: Clusterer representation<9>,  Prev: Options<38>,  Up: kmedoids_clusterer

6.144.6 Diagnostics
-------------------

The ‘diagnostics/2’ predicate returns a list containing:

   - ‘model(kmedoids_clusterer)’

   - ‘medoid_count(Count)’

   - ‘training_example_count(Count)’

   - ‘convergence(Reason)’

   - ‘iterations(Count)’

   - ‘final_shift(Shift)’

   - ‘options(Options)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Clusterer representation<9>,  Next: References<26>,  Prev: Diagnostics<7>,  Up: kmedoids_clusterer

6.144.7 Clusterer representation
--------------------------------

The learned clusterer is represented as a compound term with the functor
chosen by the user when exporting the clusterer and arity 4.  For
example:

     kmedoids_clusterer(Encoders, Medoids, Options, Diagnostics)

Where:

   - ‘Encoders’: List of continuous attribute encoders storing attribute
     name, mean, and scale.

   - ‘Medoids’: List of medoid vectors in cluster-id order.

   - ‘Options’: Effective training options used to learn the clusterer.

   - ‘Diagnostics’: Training diagnostics metadata returned by the
     ‘diagnostics/2’ predicate.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<26>,  Prev: Clusterer representation<9>,  Up: kmedoids_clusterer

6.144.8 References
------------------

  1. Kaufman & Rousseeuw (1987) - “Clustering by Means of Medoids”.  In
     Statistical Data Analysis Based on the L1-Norm and Related Methods.

  2. Kaufman & Rousseeuw (1990) - “Finding Groups in Data: An
     Introduction to Cluster Analysis”.  Wiley.


File: TheLogtalkHandbook-3.101.0.info,  Node: kmodes_clusterer,  Next: knn_classifier,  Prev: kmedoids_clusterer,  Up: Libraries

6.145 ‘kmodes_clusterer’
========================

k-Modes clusterer.  It uses an iterative mode-update algorithm with
deterministic initialization and deterministic cluster assignments.
Supports discrete attributes only.

The library implements the ‘clusterer_protocol’ defined in the
‘clustering_protocols’ library.  It provides predicates for learning a
clusterer from a dataset, assigning new instances to clusters, and
exporting the learned clusterer as a list of predicate clauses or to a
file.

Datasets are represented as objects implementing the
‘clustering_dataset_protocol’ protocol from the ‘clustering_protocols’
library.

* Menu:

* API documentation: API documentation<163>.
* Loading: Loading<165>.
* Testing: Testing<157>.
* Features: Features<38>.
* Options: Options<39>.
* Diagnostics: Diagnostics<8>.
* Clusterer representation: Clusterer representation<10>.
* References: References<27>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<163>,  Next: Loading<165>,  Up: kmodes_clusterer

6.145.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#kmodes_clusterer’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<165>,  Next: Testing<157>,  Prev: API documentation<163>,  Up: kmodes_clusterer

6.145.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(kmodes_clusterer(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<157>,  Next: Features<38>,  Prev: Loading<165>,  Up: kmodes_clusterer

6.145.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(kmodes_clusterer(tester)).

To run the performance benchmark suite, load the
‘tester_performance.lgt’ file:

     | ?- logtalk_load(kmodes_clusterer(tester_performance)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<38>,  Next: Options<39>,  Prev: Testing<157>,  Up: kmodes_clusterer

6.145.4 Features
----------------

   - 'Discrete Datasets': Accepts datasets containing only discrete
     attributes.

   - 'Deterministic Initialization': Supports ‘first_k’ and
     deterministic ‘spread’ initialization that repeatedly chooses the
     farthest example from the modes selected so far.

   - 'Rich Training Diagnostics': Learned clusterers report training
     example count, convergence status, iteration count, and final mode
     shift.

   - 'Portable Export': Learned clusterers can be exported as clauses or
     files and reused later.

   - 'Stable Empty-Cluster Handling': Empty clusters keep their previous
     modes instead of failing.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<39>,  Next: Diagnostics<8>,  Prev: Features<38>,  Up: kmodes_clusterer

6.145.5 Options
---------------

The following options can be passed to the ‘learn/3’ predicate:

   - ‘k(K)’: Number of clusters to learn.  Default is ‘2’.

   - ‘maximum_iterations(Iterations)’: Maximum number of mode-update
     iterations.  Default is ‘100’.

   - ‘tolerance(Tolerance)’: Maximum mode shift threshold for
     convergence.  Default is ‘0.0’.

   - ‘initialization(Initialization)’: Mode initialization strategy.
     Options: ‘spread’ (default) or ‘first_k’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Diagnostics<8>,  Next: Clusterer representation<10>,  Prev: Options<39>,  Up: kmodes_clusterer

6.145.6 Diagnostics
-------------------

The ‘diagnostics/2’ predicate returns a list containing:

   - ‘model(kmodes_clusterer)’

   - ‘mode_count(Count)’

   - ‘training_example_count(Count)’

   - ‘convergence(Reason)’

   - ‘iterations(Count)’

   - ‘final_shift(Shift)’

   - ‘options(Options)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Clusterer representation<10>,  Next: References<27>,  Prev: Diagnostics<8>,  Up: kmodes_clusterer

6.145.7 Clusterer representation
--------------------------------

The learned clusterer is represented as a compound term with the functor
chosen by the user when exporting the clusterer and arity 4.  For
example:

     kmodes_clusterer(Encoders, Modes, Options, Diagnostics)

Where:

   - ‘Encoders’: List of discrete attribute encoders.

   - ‘Modes’: List of learned categorical modes in cluster-id order.

   - ‘Options’: Effective training options used to learn the clusterer.

   - ‘Diagnostics’: Training diagnostics metadata returned by the
     ‘diagnostics/2’ predicate.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<27>,  Prev: Clusterer representation<10>,  Up: kmodes_clusterer

6.145.8 References
------------------

  1. Huang (1998) - “Extensions to the k-means algorithm for clustering
     large data sets with categorical values”.  Data Mining and
     Knowledge Discovery, 2, 283-304.


File: TheLogtalkHandbook-3.101.0.info,  Node: knn_classifier,  Next: knn_distance_anomaly_detector,  Prev: kmodes_clusterer,  Up: Libraries

6.146 ‘knn_classifier’
======================

k-Nearest Neighbors classifier supporting multiple distance metrics,
weighting schemes, and both categorical and continuous features.  This
is a lazy learning algorithm that classifies instances based on the
majority class among the k nearest training instances.

The library implements the ‘classifier_protocol’ defined in the
‘classification_protocols’ library.  It provides predicates for learning
a classifier from a dataset, using it to make predictions, and exporting
it as a list of predicate clauses or to a file.

Datasets are represented as objects implementing the ‘dataset_protocol’
protocol from the ‘classification_protocols’ library.  See ‘test_files’
directory for examples.

* Menu:

* API documentation: API documentation<164>.
* Loading: Loading<166>.
* Testing: Testing<158>.
* Features: Features<39>.
* Usage: Usage<60>.
* Options: Options<40>.
* Classifier representation: Classifier representation<4>.
* References: References<28>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<164>,  Next: Loading<166>,  Up: knn_classifier

6.146.1 API documentation
-------------------------

Open the ‘../../docs/library_index.html#knn_classifier’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<166>,  Next: Testing<158>,  Prev: API documentation<164>,  Up: knn_classifier

6.146.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(knn_classifier(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<158>,  Next: Features<39>,  Prev: Loading<166>,  Up: knn_classifier

6.146.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(knn_classifier(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<39>,  Next: Usage<60>,  Prev: Testing<158>,  Up: knn_classifier

6.146.4 Features
----------------

   - 'Multiple Distance Metrics': Euclidean, Manhattan, Chebyshev,
     Minkowski.

   - 'Flexible Weighting': Uniform, distance-based, and Gaussian
     weighting of neighbors.

   - 'Mixed Features': Automatically handles categorical and continuous
     features.

   - 'Configurable Options': k value, distance metric, and weighting
     scheme via predicate options.

   - 'Probability Estimation': Provides confidence scores for
     predictions.

   - 'Classifier Export': Learned classifiers can be exported as
     predicate clauses.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<60>,  Next: Options<40>,  Prev: Features<39>,  Up: knn_classifier

6.146.5 Usage
-------------

* Menu:

* Learning a Classifier: Learning a Classifier<2>.
* Making Predictions: Making Predictions<2>.
* Exporting the Classifier: Exporting the Classifier<2>.
* Using a learned classifier::


File: TheLogtalkHandbook-3.101.0.info,  Node: Learning a Classifier<2>,  Next: Making Predictions<2>,  Up: Usage<60>

6.146.5.1 Learning a Classifier
...............................

     % Learn from a dataset object with default options (k=3, euclidean, uniform)
     | ?- knn_classifier::learn(my_dataset, Classifier).
     ...

     % Learn with custom options
     | ?- knn_classifier::learn(my_dataset, Classifier, [k(5), distance_metric(manhattan)]).
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Making Predictions<2>,  Next: Exporting the Classifier<2>,  Prev: Learning a Classifier<2>,  Up: Usage<60>

6.146.5.2 Making Predictions
............................

     % Predict class for a new instance
     | ?- Instance = [attr1-value1, attr2-value2, ...],
          knn_classifier::learn(my_dataset, Classifier),
          knn_classifier::predict(Classifier, Instance, PredictedClass).
     PredictedClass = ...
     ...

     % Predict with custom options
     | ?- knn_classifier::predict(Classifier, Instance, PredictedClass, [k(5), weight_scheme(distance)]).
     ...

     % Get probability distribution
     | ?- knn_classifier::predict_probabilities(Classifier, Instance, Probabilities).
     Probabilities = [class1-0.67, class2-0.33]
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Exporting the Classifier<2>,  Next: Using a learned classifier,  Prev: Making Predictions<2>,  Up: Usage<60>

6.146.5.3 Exporting the Classifier
..................................

Learned classifiers can be exported as a list of clauses or to a file
for later use.

     % Export as predicate clauses
     | ?- knn_classifier::learn(my_dataset, Classifier),
          knn_classifier::export_to_clauses(my_dataset, Classifier, my_classifier, Clauses).
     Clauses = [my_classifier(...)]
     ...

     % Export to a file
     | ?- knn_classifier::learn(my_dataset, Classifier),
          knn_classifier::export_to_file(my_dataset, Classifier, my_classifier, 'classifier.pl').
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Using a learned classifier,  Prev: Exporting the Classifier<2>,  Up: Usage<60>

6.146.5.4 Using a learned classifier
....................................

Learned and saved classifiers can later be used for predictions without
needing to access the original training dataset.

     % Later, load the file and use the classifier
     | ?- consult('classifier.pl'),
          my_classifier(Classifier),
          Instance = [...],
          knn_classifier::predict(Classifier, Instance, Class).
     Class = ...
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<40>,  Next: Classifier representation<4>,  Prev: Usage<60>,  Up: knn_classifier

6.146.6 Options
---------------

The following options can be passed to the ‘predict/4’ and
‘predict_probabilities/4’ predicates:

   - ‘k(K)’: Number of neighbors to consider (default: 3)

   - ‘distance_metric(Metric)’: Distance metric to use.  Options:
     ‘euclidean’ (default), ‘manhattan’, ‘chebyshev’, ‘minkowski’

   - ‘weight_scheme(Scheme)’: Weighting scheme for neighbor votes.
     Options: ‘uniform’ (default), ‘distance’, ‘gaussian’


File: TheLogtalkHandbook-3.101.0.info,  Node: Classifier representation<4>,  Next: References<28>,  Prev: Options<40>,  Up: knn_classifier

6.146.7 Classifier representation
---------------------------------

The learned classifier is represented as a compound term:

     knn_classifier(AttributeNames, FeatureTypes, Instances)

Where:

   - ‘AttributeNames’: List of attribute names in order

   - ‘FeatureTypes’: List of types (‘numeric’ or ‘categorical’)

   - ‘Instances’: List of ‘Values-Class’ pairs (the training data in
     compact form)

When exported using ‘export_to_clauses/4’ or ‘export_to_file/4’, this
classifier term is serialized directly as the single argument of the
generated predicate clause so that the exported model can be loaded and
reused as-is.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<28>,  Prev: Classifier representation<4>,  Up: knn_classifier

6.146.8 References
------------------

  1. Cover, T. & Hart, P. (1967).  “Nearest neighbor pattern
     classification”.  IEEE Transactions on Information Theory.

  2. Hastie, T., Tibshirani, R., & Friedman, J. (2009).  “The Elements
     of Statistical Learning”.  Chapter 13.

  3. Mitchell, T. (1997).  “Machine Learning”.  Chapter 8:
     Instance-Based Learning.


File: TheLogtalkHandbook-3.101.0.info,  Node: knn_distance_anomaly_detector,  Next: knn_regression,  Prev: knn_classifier,  Up: Libraries

6.147 ‘knn_distance_anomaly_detector’
=====================================

k-nearest-neighbor distance anomaly detector supporting multiple
distance metrics, mixed continuous and categorical features, and missing
values.  The detector memorizes the training instances and computes an
anomaly score from normalized distances to the nearest neighbors.
Larger distances indicate more isolated and therefore more anomalous
instances.

The library implements the ‘anomaly_detector_protocol’ defined in the
‘anomaly_detection_protocols’ library.  It learns a compact detector
from a dataset by selecting baseline training examples from the declared
class labels, computes anomaly scores for new instances, predicts
‘normal’ or ‘anomaly’, and exports learned detectors as clauses or
files.

Datasets are represented as objects implementing the
‘anomaly_dataset_protocol’ protocol from the
‘anomaly_detection_protocols’ library.  See the
‘anomaly_detection_protocols/test_datasets’ directory for examples.

* Menu:

* API documentation: API documentation<165>.
* Loading: Loading<167>.
* Testing: Testing<159>.
* Features: Features<40>.
* Options: Options<41>.
* Detector representation: Detector representation<5>.
* References: References<29>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<165>,  Next: Loading<167>,  Up: knn_distance_anomaly_detector

6.147.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#knn_distance_anomaly_detector’
link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<167>,  Next: Testing<159>,  Prev: API documentation<165>,  Up: knn_distance_anomaly_detector

6.147.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(knn_distance_anomaly_detector(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<159>,  Next: Features<40>,  Prev: Loading<167>,  Up: knn_distance_anomaly_detector

6.147.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(knn_distance_anomaly_detector(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<40>,  Next: Options<41>,  Prev: Testing<159>,  Up: knn_distance_anomaly_detector

6.147.4 Features
----------------

   - 'Distance-based anomaly scoring': supports both distance to the
     k-th neighbor and average distance to the k nearest neighbors.

   - 'Mixed features': automatically handles continuous and categorical
     features declared by the dataset.

   - 'Missing values': ignores missing dimensions while normalizing
     distances (distances are normalized by the number of comparable
     dimensions).

   - 'Baseline training selection': ‘baseline_class_values/1’ declares
     which class labels are admissible for fitting the detector, while
     ‘baseline_selection_policy/1’ controls whether non-baseline
     examples are rejected (default) or filtered before training.

   - 'Multiple metrics': supports Euclidean, Manhattan, Chebyshev, and
     Minkowski distance metrics.

   - 'Detector export': learned detectors can be exported as predicate
     clauses.

   - 'Dataset validation': learning rejects empty datasets with a
     ‘domain_error(non_empty_dataset, Dataset)’ exception.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<41>,  Next: Detector representation<5>,  Prev: Features<40>,  Up: knn_distance_anomaly_detector

6.147.5 Options
---------------

The following options can be passed to the ‘learn/3’ and ‘predict/4’
predicates:

   - ‘k(K)’: Number of neighbors to consider (default: 5)

   - ‘distance_metric(Metric)’: Distance metric to use.  Options:
     ‘euclidean’ (default), ‘manhattan’, ‘chebyshev’, ‘minkowski’

   - ‘score_mode(Mode)’: Score computation mode.  Options:
     ‘kth_distance’ (default) and ‘mean_distance’

   - ‘anomaly_threshold(Threshold)’: Threshold for ‘predict/3-4’
     (default: ‘0.5’)

   - ‘baseline_class_values(Classes)’: Learn-time list of admissible
     baseline class labels (default: ‘[normal]’)

   - ‘baseline_selection_policy(Policy)’: Learn-time handling of
     non-baseline examples.  Supported values are ‘reject’ (default) and
     ‘filter’


File: TheLogtalkHandbook-3.101.0.info,  Node: Detector representation<5>,  Next: References<29>,  Prev: Options<41>,  Up: knn_distance_anomaly_detector

6.147.6 Detector representation
-------------------------------

The learned detector is represented by default as:

     knn_distance_detector(TrainingDataset, AttributeNames, FeatureTypes, AttributeScales, Instances, ReferenceScores, Diagnostics)

Where:

   - ‘AttributeNames’: List of attribute names in order

   - ‘FeatureTypes’: List of feature types (‘numeric’ or ‘categorical’)

   - ‘AttributeScales’: Normalization scales for numeric features

   - ‘Instances’: List of retained baseline training ‘Id-Class-Values’
     triples

   - ‘ReferenceScores’: Cached leave-one-out raw training scores for the
     retained baseline training instances

   - ‘Diagnostics’: Learned metadata terms including ‘model/1’,
     ‘training_dataset/1’, ‘attribute_names/1’, ‘feature_types/1’,
     ‘example_count/1’, ‘reference_score_count/1’, and ‘options/1’

The ‘score/3’ predicate always treats its input as a fresh query.  Only
‘score_all/3’ on the original training dataset with the ‘reject’
baseline selection policy reuses the cached leave-one-out
‘ReferenceScores’ for all examples.  With the ‘filter’ policy, retained
baseline training examples reuse the cached leave-one-out scores while
excluded examples are scored as fresh queries against the learned
baseline detector.

When exported using ‘export_to_clauses/4’ or ‘export_to_file/4’, this
detector term is serialized directly as the single argument of the
generated predicate clause so that the exported model can be loaded and
reused as-is.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<29>,  Prev: Detector representation<5>,  Up: knn_distance_anomaly_detector

6.147.7 References
------------------

  1. Angiulli, F. and Pizzuti, C. (2002).  “Fast outlier detection in
     high dimensional spaces”.  PKDD.

  2. Chandola, V., Banerjee, A., and Kumar, V. (2009).  “Anomaly
     detection: A survey”.  ACM Computing Surveys.


File: TheLogtalkHandbook-3.101.0.info,  Node: knn_regression,  Next: kprototypes_clusterer,  Prev: knn_distance_anomaly_detector,  Up: Libraries

6.148 ‘knn_regression’
======================

k-Nearest Neighbors regressor supporting continuous and mixed-feature
datasets.  Learns lazily by storing encoded training rows and predicts
targets as the weighted average of the k nearest neighbors.

The library implements the ‘regressor_protocol’ defined in the
‘regression_protocols’ library, learns lazily by storing encoded
training rows, and predicts numeric targets using the weighted average
of the nearest encoded neighbors.

* Menu:

* API documentation: API documentation<166>.
* Loading: Loading<168>.
* Testing: Testing<160>.
* Features: Features<41>.
* Regressor representation: Regressor representation<5>.
* Diagnostics syntax: Diagnostics syntax<13>.
* Options: Options<42>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<166>,  Next: Loading<168>,  Up: knn_regression

6.148.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#knn_regression’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<168>,  Next: Testing<160>,  Prev: API documentation<166>,  Up: knn_regression

6.148.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(knn_regression(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<160>,  Next: Features<41>,  Prev: Loading<168>,  Up: knn_regression

6.148.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(knn_regression(tester)).

To run the performance benchmark suite, load the
‘tester_performance.lgt’ file:

     | ?- logtalk_load(knn_regression(tester_performance)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<41>,  Next: Regressor representation<5>,  Prev: Testing<160>,  Up: knn_regression

6.148.4 Features
----------------

   - 'Distance-Based Regression': Predicts targets using the weighted
     average of the nearest neighbors.

   - 'Multiple Metrics': Supports Euclidean, Manhattan, Chebyshev, and
     Minkowski distance metrics over encoded numeric feature vectors.

   - 'Weighting Schemes': Supports uniform, inverse-distance, and
     Gaussian weighting of neighbors.

   - 'Continuous and Mixed Features': Supports continuous attributes and
     categorical attributes encoded using reference-level dummy coding
     derived from the declared dataset attribute values.

   - 'Optional Feature Scaling': Continuous attributes can be
     standardized using z-score scaling.

   - 'Missing Values': Missing numeric and categorical values
     represented using anonymous variables are encoded using explicit
     missing-value indicator features.

   - 'Diagnostics Metadata': Learned regressors record model name,
     target, training example count, encoded feature count, and
     effective options, accessible using the shared regression
     diagnostics predicates.

   - 'Model Export': Learned regressors can be exported as predicate
     clauses or written to a file.

   - 'Reference Benchmarks': Includes a dedicated performance suite
     reporting training time, RMSE, and MAE for representative
     regression datasets.


File: TheLogtalkHandbook-3.101.0.info,  Node: Regressor representation<5>,  Next: Diagnostics syntax<13>,  Prev: Features<41>,  Up: knn_regression

6.148.5 Regressor representation
--------------------------------

The learned regressor is represented by default as:

   - ‘knn_regressor(Encoders, Rows, Diagnostics)’

The exported predicate clauses therefore use the shape:

   - ‘Functor(Encoders, Rows, Diagnostics)’

In this representation, ‘Rows’ stores encoded feature vectors paired
with numeric targets and ‘Diagnostics’ stores training metadata
including the effective options.


File: TheLogtalkHandbook-3.101.0.info,  Node: Diagnostics syntax<13>,  Next: Options<42>,  Prev: Regressor representation<5>,  Up: knn_regression

6.148.6 Diagnostics syntax
--------------------------

The ‘diagnostics/2’ predicate returns a list of metadata terms with the
form:

     [
         model(knn_regression),
         target(Target),
         training_example_count(TrainingExampleCount),
         options(Options),
         encoded_feature_count(FeatureCount)
     ]

Where:

   - ‘model(knn_regression)’ identifies the learning algorithm that
     produced the regressor.

   - ‘target(Target)’ stores the target attribute name declared by the
     training dataset.

   - ‘training_example_count(TrainingExampleCount)’ stores the number of
     examples used during training.

   - ‘options(Options)’ stores the effective learning options after
     merging the user options with the library defaults.

   - ‘encoded_feature_count(FeatureCount)’ stores the number of numeric
     features induced by the encoder list, including missing-value
     indicator features.

Use the ‘regression_protocols’ ‘diagnostic/2’ and ‘regressor_options/2’
helper predicates when you only need a single metadata term or the
effective options.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<42>,  Prev: Diagnostics syntax<13>,  Up: knn_regression

6.148.7 Options
---------------

The ‘learn/3’ predicate accepts the following options:

   - ‘k/1’: Number of nearest neighbors considered for each prediction.
     Smaller values make predictions more local; larger values smooth
     them by averaging over more training rows.  The default is ‘3’.

   - ‘distance_metric/1’: Distance function used to compare encoded
     feature vectors.  Accepted values are ‘euclidean’, ‘manhattan’,
     ‘chebyshev’, and ‘minkowski’.  The default is ‘euclidean’.

   - ‘weight_scheme/1’: Neighbor weighting policy used when averaging
     targets.  Accepted values are ‘uniform’, ‘distance’, and
     ‘gaussian’.  The default is ‘uniform’.

   - ‘minkowski_power/1’: Exponent used when
     ‘distance_metric(minkowski)’ is selected.  Larger values increase
     the influence of larger coordinate differences.  The default is
     ‘3.0’.

   - ‘feature_scaling/1’: Controls z-score standardization of continuous
     attributes before storing rows and encoding prediction requests.
     Accepted values are ‘true’ and ‘false’.  The default is ‘true’.


File: TheLogtalkHandbook-3.101.0.info,  Node: kprototypes_clusterer,  Next: ksuid,  Prev: knn_regression,  Up: Libraries

6.149 ‘kprototypes_clusterer’
=============================

k-Prototypes clusterer.  It uses an iterative prototype-update algorithm
with deterministic initialization and deterministic cluster assignments.
Supports continuous and discrete attributes in the same dataset.

The library implements the ‘clusterer_protocol’ defined in the
‘clustering_protocols’ library.  It provides predicates for learning a
clusterer from a dataset, assigning new instances to clusters, and
exporting the learned clusterer as a list of predicate clauses or to a
file.

Datasets are represented as objects implementing the
‘clustering_dataset_protocol’ protocol from the ‘clustering_protocols’
library.

* Menu:

* API documentation: API documentation<167>.
* Loading: Loading<169>.
* Testing: Testing<161>.
* Features: Features<42>.
* Options: Options<43>.
* Distance Function::
* Clusterer representation: Clusterer representation<11>.
* References: References<30>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<167>,  Next: Loading<169>,  Up: kprototypes_clusterer

6.149.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#kprototypes_clusterer’ link in a
web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<169>,  Next: Testing<161>,  Prev: API documentation<167>,  Up: kprototypes_clusterer

6.149.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(kprototypes_clusterer(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<161>,  Next: Features<42>,  Prev: Loading<169>,  Up: kprototypes_clusterer

6.149.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(kprototypes_clusterer(tester)).

To run the performance benchmark suite, load the
‘tester_performance.lgt’ file:

     | ?- logtalk_load(kprototypes_clusterer(tester_performance)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<42>,  Next: Options<43>,  Prev: Testing<161>,  Up: kprototypes_clusterer

6.149.4 Features
----------------

   - 'Mixed Datasets': Accepts datasets with continuous, discrete, or
     mixed attributes.

   - 'Strict Attribute Validation': Training examples and prediction
     instances must contain each declared attribute exactly once and no
     undeclared attributes.

   - 'Deterministic Initialization': Supports ‘first_k’ and
     deterministic ‘spread’ initialization that repeatedly chooses the
     farthest example from the prototypes selected so far.

   - 'Optional Feature Scaling': Continuous attributes can be
     standardized using z-score scaling.

   - 'Categorical Weighting': Uses a ‘gamma’ mismatch penalty for
     discrete attributes in the mixed distance function.

   - 'Portable Export': Learned clusterers can be exported as clauses or
     files and reused later.

   - 'Stable Empty-Cluster Handling': Empty clusters keep their previous
     prototypes instead of failing.

   - 'Training Diagnostics': Exposes convergence metadata including
     training example count, iteration count, and final prototype shift.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<43>,  Next: Distance Function,  Prev: Features<42>,  Up: kprototypes_clusterer

6.149.5 Options
---------------

The following options can be passed to the ‘learn/3’ predicate:

   - ‘k(K)’: Number of clusters to learn.  Default is ‘2’.

   - ‘maximum_iterations(Iterations)’: Maximum number of
     prototype-update iterations.  Default is ‘100’.

   - ‘tolerance(Tolerance)’: Maximum prototype shift threshold for
     convergence.  Default is ‘1.0e-6’.

   - ‘initialization(Initialization)’: Prototype initialization
     strategy.  Options: ‘spread’ (default) or ‘first_k’.

   - ‘gamma(Gamma)’: Penalty added for each discrete-feature mismatch.
     Default is ‘1.0’.

   - ‘feature_scaling(FeatureScaling)’: Whether to standardize
     continuous attributes before clustering.  Options: ‘on’ (default)
     or ‘off’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Distance Function,  Next: Clusterer representation<11>,  Prev: Options<43>,  Up: kprototypes_clusterer

6.149.6 Distance Function
-------------------------

The mixed k-prototypes distance used for both assignment and prototype
spread initialization is:

     D(X, P) = Sum((x_i - p_i)^2) + gamma * M

where the sum is taken over all continuous attributes and ‘M’ is the
number of discrete-attribute mismatches between the instance ‘X’ and the
prototype ‘P’.

For discrete prototype updates, the selected value for each categorical
attribute is the most frequent value among the cluster members.  When
two or more values are tied, the implementation deterministically keeps
the first value in the declared attribute-values list.


File: TheLogtalkHandbook-3.101.0.info,  Node: Clusterer representation<11>,  Next: References<30>,  Prev: Distance Function,  Up: kprototypes_clusterer

6.149.7 Clusterer representation
--------------------------------

The learned clusterer is represented as a compound term with the functor
chosen by the user when exporting the clusterer and arity 4.  For
example:

     kprototypes_clusterer(Encoders, Prototypes, Options, Diagnostics)

Where:

   - ‘Encoders’: List of continuous and discrete attribute encoders.

   - ‘Prototypes’: List of learned mixed prototypes in cluster-id order.

   - ‘Options’: Effective training options used to learn the clusterer.

   - ‘Diagnostics’: Training metadata including convergence reason,
     iteration count, and final prototype shift.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<30>,  Prev: Clusterer representation<11>,  Up: kprototypes_clusterer

6.149.8 References
------------------

  1. Huang (1997) - “Clustering large data sets with mixed numeric and
     categorical values”.  Proceedings of the First Pacific-Asia
     Conference on Knowledge Discovery and Data Mining.

  2. Huang (1998) - “Extensions to the k-means algorithm for clustering
     large data sets with categorical values”.  Data Mining and
     Knowledge Discovery, 2, 283-304.


File: TheLogtalkHandbook-3.101.0.info,  Node: ksuid,  Next: lasso_regression,  Prev: kprototypes_clusterer,  Up: Libraries

6.150 ‘ksuid’
=============

This library generates random KSUID identifiers:

‘https://github.com/segmentio/ksuid’

'This library requires a backend supporting unbounded integer
arithmetic.'

By default, identifiers are represented as atoms and encoded using the
canonical Base62 alphabet:

     0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz

The generation of random identifiers uses the ‘/dev/urandom’ random
number generator when available.  This includes macOS, Linux, *BSD, and
other POSIX operating systems.  On Windows, a pseudo-random generator is
used, randomized using the current wall time.

Identifiers can be generated as atoms, lists of characters, or lists of
character codes.

See also the ‘cuid2’, ‘ids’, ‘nanoid’, ‘snowflakeid’, ‘uuid’, and ‘ulid’
libraries.

* Menu:

* API documentation: API documentation<168>.
* Loading: Loading<170>.
* Testing: Testing<162>.
* Usage: Usage<61>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<168>,  Next: Loading<170>,  Up: ksuid

6.150.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#ksuid’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<170>,  Next: Testing<162>,  Prev: API documentation<168>,  Up: ksuid

6.150.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(ksuid(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<162>,  Next: Usage<61>,  Prev: Loading<170>,  Up: ksuid

6.150.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(ksuid(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<61>,  Prev: Testing<162>,  Up: ksuid

6.150.4 Usage
-------------

To generate a KSUID using the default configuration:

     | ?- ksuid::generate(KSUID).
     KSUID = '2YBXxVf8R5A1x6Yx5Y1AL7bEmel'
     yes

To generate a KSUID represented as a list of characters:

     | ?- ksuid(chars, '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz')::generate(KSUID).
     KSUID = ['2','Y','B','X','x','V','f','8','R','5','A','1','x','6','Y','x','5','Y','1','A','L','7','b','E','m','e','l']
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: lasso_regression,  Next: lda_classifier,  Prev: ksuid,  Up: Libraries

6.151 ‘lasso_regression’
========================

Lasso regression regressor supporting continuous and mixed-feature
datasets.  Uses cyclic coordinate descent with soft-thresholding updates
for each encoded feature in order to minimize mean squared error plus an
L1 penalty on the encoded coefficient vector.

The library implements the ‘regressor_protocol’ defined in the
‘regression_protocols’ library and learns a linear model using cyclic
coordinate descent with L1 regularization and soft-thresholding updates
for each encoded feature in order to minimize mean squared error plus an
L1 penalty on the encoded coefficient vector.

* Menu:

* API documentation: API documentation<169>.
* Loading: Loading<171>.
* Testing: Testing<163>.
* Features: Features<43>.
* Regressor representation: Regressor representation<6>.
* Diagnostics syntax: Diagnostics syntax<14>.
* Options: Options<44>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<169>,  Next: Loading<171>,  Up: lasso_regression

6.151.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#lasso_regression’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<171>,  Next: Testing<163>,  Prev: API documentation<169>,  Up: lasso_regression

6.151.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(lasso_regression(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<163>,  Next: Features<43>,  Prev: Loading<171>,  Up: lasso_regression

6.151.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(lasso_regression(tester)).

To run the performance benchmark suite, load the
‘tester_performance.lgt’ file:

     | ?- logtalk_load(lasso_regression(tester_performance)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<43>,  Next: Regressor representation<6>,  Prev: Testing<163>,  Up: lasso_regression

6.151.4 Features
----------------

   - 'Continuous and Mixed Features': Supports continuous attributes and
     categorical attributes

   - 'Categorical Attributes Encoding': Uses reference-level dummy
     coding derived from the declared dataset attribute values, with a
     missing-value indicator, and the resulting encoded coefficients are
     regularized independently.

   - 'Feature Scaling': Continuous attributes can be standardized using
     z-score scaling.

   - 'Missing Values': Missing numeric and categorical values
     represented using anonymous variables are encoded using explicit
     missing-value indicator features.

   - 'Unknown Values': Prediction requests containing categorical values
     that are not declared by the dataset raise a domain error.

   - 'Coefficient-wise L1 Shrinkage': Applies soft-thresholding updates
     independently to every encoded feature, including categorical dummy
     and missing-indicator features.

   - 'Diagnostics Metadata': Learned regressors record model name,
     target, training example count, optimization stop reason, completed
     iterations, final parameter delta, encoded feature count, and
     effective options, accessible using the shared regression
     diagnostics predicates.

   - 'Model Export': Learned regressors can be exported as predicate
     clauses or written to a file.

   - 'Reference Benchmarks': Includes a dedicated performance suite
     reporting training time, RMSE, and MAE for representative
     regression datasets.


File: TheLogtalkHandbook-3.101.0.info,  Node: Regressor representation<6>,  Next: Diagnostics syntax<14>,  Prev: Features<43>,  Up: lasso_regression

6.151.5 Regressor representation
--------------------------------

The learned regressor is represented by default as:

   - ‘lasso_regressor(Encoders, Bias, Weights, Diagnostics)’

The exported predicate clauses therefore use the shape:

   - ‘Functor(Encoders, Bias, Weights, Diagnostics)’

In this representation, ‘Encoders’ stores the feature encoding metadata,
‘Bias’ stores the intercept, ‘Weights’ stores one coefficient per
encoded feature, and ‘Diagnostics’ stores training metadata including
the effective options.


File: TheLogtalkHandbook-3.101.0.info,  Node: Diagnostics syntax<14>,  Next: Options<44>,  Prev: Regressor representation<6>,  Up: lasso_regression

6.151.6 Diagnostics syntax
--------------------------

The ‘diagnostics/2’ predicate returns a list of metadata terms with the
form:

     [
         model(lasso_regression),
         target(Target),
         training_example_count(TrainingExampleCount),
         options(Options),
         convergence(Status),
         iterations(Iterations),
         final_delta(FinalDelta),
         encoded_feature_count(FeatureCount)
     ]

Where:

   - ‘model(lasso_regression)’ identifies the learning algorithm that
     produced the regressor.

   - ‘target(Target)’ stores the target attribute name declared by the
     training dataset.

   - ‘training_example_count(TrainingExampleCount)’ stores the number of
     examples used during training.

   - ‘options(Options)’ stores the effective learning options after
     merging the user options with the library defaults.

   - ‘convergence(Status)’ records the optimization stop condition.  The
     current values are ‘tolerance’ when the maximum Karush-Kuhn-Tucker
     optimality violation across the intercept and all encoded features
     is within the configured tolerance and
     ‘maximum_iterations_exhausted’ when training stops because the
     iteration cap is reached.

   - ‘iterations(Iterations)’ stores the number of coordinate-descent
     sweeps completed during training.

   - ‘final_delta(FinalDelta)’ stores the maximum Karush-Kuhn-Tucker
     optimality violation measured during the final optimization check.

   - ‘encoded_feature_count(FeatureCount)’ stores the number of numeric
     features induced by the encoder list, including missing-value
     indicator features.

Use the ‘regression_protocols’ ‘diagnostic/2’ and ‘regressor_options/2’
helper predicates when you only need a single metadata term or the
effective options.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<44>,  Prev: Diagnostics syntax<14>,  Up: lasso_regression

6.151.7 Options
---------------

The ‘learn/3’ predicate accepts the following options:

   - ‘maximum_iterations/1’: Maximum number of coordinate-descent sweeps
     to run before stopping even if the tolerance criterion has not been
     met.  The default is ‘2000’.

   - ‘tolerance/1’: Convergence threshold for the maximum
     Karush-Kuhn-Tucker optimality violation in a full
     coordinate-descent sweep.  Training stops early when both the
     intercept condition and all encoded-feature subgradient conditions
     are satisfied within this value.  The default is ‘1.0e-7’.

   - ‘regularization/1’: L1 penalty coefficient applied independently to
     every encoded feature during optimization.  Higher values increase
     shrinkage and can reduce overfitting.  The default is ‘0.01’.

   - ‘feature_scaling/1’: Controls z-score standardization of continuous
     attributes before training and prediction.  Accepted values are
     ‘true’ and ‘false’.  The default is ‘true’.


File: TheLogtalkHandbook-3.101.0.info,  Node: lda_classifier,  Next: lda_projection,  Prev: lasso_regression,  Up: Libraries

6.152 ‘lda_classifier’
======================

Linear Discriminant Analysis classifier for continuous datasets using a
shared pooled covariance estimate with diagonal regularization.  The
implementation learns one linear discriminant function per class and
predicts the class with the highest discriminant score.

The library implements the ‘classifier_protocol’ defined in the
‘classification_protocols’ library.  It provides predicates for learning
a classifier from a dataset, using it to make predictions, inspecting
class scores, and exporting it as a list of predicate clauses or to a
file.

Datasets are represented as objects implementing the ‘dataset_protocol’
protocol from the ‘classification_protocols’ library.  All dataset
attributes must be declared as ‘continuous’.

* Menu:

* API documentation: API documentation<170>.
* Loading: Loading<172>.
* Testing: Testing<164>.
* Features: Features<44>.
* Options: Options<45>.
* Usage: Usage<62>.
* Classifier representation: Classifier representation<5>.
* References: References<31>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<170>,  Next: Loading<172>,  Up: lda_classifier

6.152.1 API documentation
-------------------------

Open the ‘../../docs/library_index.html#lda_classifier’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<172>,  Next: Testing<164>,  Prev: API documentation<170>,  Up: lda_classifier

6.152.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(lda_classifier(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<164>,  Next: Features<44>,  Prev: Loading<172>,  Up: lda_classifier

6.152.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(lda_classifier(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<44>,  Next: Options<45>,  Prev: Testing<164>,  Up: lda_classifier

6.152.4 Features
----------------

   - 'Continuous Datasets': Accepts only datasets whose attributes are
     all declared as continuous.

   - 'Pooled Covariance Model': Learns a shared covariance matrix and
     class-specific means and priors.

   - 'Regularized Estimation': Applies configurable diagonal
     regularization to stabilize covariance inversion.

   - 'Feature Scaling': Supports optional z-score scaling of continuous
     features before fitting the model.

   - 'Score Inspection': Provides discriminant scores for all classes
     using ‘predict_scores/3’.

   - 'Classifier Export': Learned classifiers can be exported as
     predicate clauses or written to a file.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<45>,  Next: Usage<62>,  Prev: Features<44>,  Up: lda_classifier

6.152.5 Options
---------------

The ‘learn/3’ predicate supports these options:

   - ‘feature_scaling/1’ - whether to standardize continuous attributes
     before training (default: ‘true’)

   - ‘regularization/1’ - positive diagonal value added to the pooled
     covariance matrix before inversion (default: ‘1.0e-6’)


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<62>,  Next: Classifier representation<5>,  Prev: Options<45>,  Up: lda_classifier

6.152.6 Usage
-------------

* Menu:

* Learning a classifier: Learning a classifier<3>.
* Making predictions: Making predictions<3>.
* Exporting the classifier: Exporting the classifier<3>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Learning a classifier<3>,  Next: Making predictions<3>,  Up: Usage<62>

6.152.6.1 Learning a classifier
...............................

     | ?- lda_classifier::learn(iris_small, Classifier).

     | ?- lda_classifier::learn(iris_small, Classifier, [regularization(1.0e-5)]).


File: TheLogtalkHandbook-3.101.0.info,  Node: Making predictions<3>,  Next: Exporting the classifier<3>,  Prev: Learning a classifier<3>,  Up: Usage<62>

6.152.6.2 Making predictions
............................

     | ?- lda_classifier::learn(iris_small, Classifier),
          lda_classifier::predict(Classifier, [sepal_length-5.1, sepal_width-3.5, petal_length-1.4, petal_width-0.2], Class).

     | ?- lda_classifier::learn(iris_small, Classifier),
          lda_classifier::predict_scores(Classifier, [sepal_length-6.0, sepal_width-2.9, petal_length-4.5, petal_width-1.5], Scores).


File: TheLogtalkHandbook-3.101.0.info,  Node: Exporting the classifier<3>,  Prev: Making predictions<3>,  Up: Usage<62>

6.152.6.3 Exporting the classifier
..................................

     | ?- lda_classifier::learn(iris_small, Classifier),
          lda_classifier::export_to_clauses(iris_small, Classifier, classify, Clauses).

     | ?- lda_classifier::learn(iris_small, Classifier),
          lda_classifier::export_to_file(iris_small, Classifier, classify, 'classifier.pl').


File: TheLogtalkHandbook-3.101.0.info,  Node: Classifier representation<5>,  Next: References<31>,  Prev: Usage<62>,  Up: lda_classifier

6.152.7 Classifier representation
---------------------------------

The learned classifier is represented as a compound term with the form:

     lda_classifier(Encoders, Models, Options)

Where:

   - ‘Encoders’: list of continuous feature encoders with learned
     scaling parameters

   - ‘Models’: list of ‘class_model(Class, Prior, Mean, Weights,
     Offset)’ terms

   - ‘Options’: merged training options used to learn the classifier

When exported using ‘export_to_clauses/4’ or ‘export_to_file/4’, this
classifier term is serialized directly as the single argument of the
generated predicate clause so that the exported model can be loaded and
reused as-is.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<31>,  Prev: Classifier representation<5>,  Up: lda_classifier

6.152.8 References
------------------

  1. Fisher, R.A. (1936).  “The use of multiple measurements in
     taxonomic problems”.

  2. Hastie, T., Tibshirani, R. and Friedman, J. (2009).  “The Elements
     of Statistical Learning”.  Section 4.3.

  3. Bishop, C.M. (2006).  “Pattern Recognition and Machine Learning”.
     Section 4.1.


File: TheLogtalkHandbook-3.101.0.info,  Node: lda_projection,  Next: linda,  Prev: lda_classifier,  Up: Libraries

6.153 ‘lda_projection’
======================

Linear Discriminant Analysis projection for labeled continuous datasets.
Supports continuous attributes only.

The library implements the ‘dimension_reducer_protocol’ defined in the
‘dimension_reduction_protocols’ library and learns discriminant
directions by centering the training data, optionally standardizing
continuous attributes, building regularized within-class and
between-class scatter matrices, whitening the Fisher criterion using a
Cholesky factorization, and extracting discriminant directions using
deterministic power iteration with deflation.

Requires a dataset implementing
‘supervised_dimension_reduction_dataset_protocol’ and therefore uses
class labels during training.

* Menu:

* API documentation: API documentation<171>.
* Loading: Loading<173>.
* Testing: Testing<165>.
* Features: Features<45>.
* Options: Options<46>.
* Usage: Usage<63>.
* Dimension reducer representation: Dimension reducer representation<3>.
* References: References<32>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<171>,  Next: Loading<173>,  Up: lda_projection

6.153.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#lda_projection’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<173>,  Next: Testing<165>,  Prev: API documentation<171>,  Up: lda_projection

6.153.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(lda_projection(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<165>,  Next: Features<45>,  Prev: Loading<173>,  Up: lda_projection

6.153.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(lda_projection(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<45>,  Next: Options<46>,  Prev: Testing<165>,  Up: lda_projection

6.153.4 Features
----------------

   - 'Supervised Continuous Datasets': Accepts labeled datasets
     implementing ‘supervised_dimension_reduction_dataset_protocol’ and
     containing only continuous attributes.

   - 'Centering and Optional Scaling': Centers all attributes and
     optionally standardizes them before estimating class scatter
     matrices.

   - 'Portable Fisher Eigensolver': Uses regularized within-class
     scatter, Cholesky whitening, and deterministic power iteration
     instead of backend-specific linear algebra libraries.

   - 'Projection API': Transforms a new instance into a list of
     ‘component_N-Value’ pairs.

   - 'Model Export': Learned reducers can be exported as predicate
     clauses or written to a file.

   - 'Missing Values': Missing or nonnumeric values are rejected.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<46>,  Next: Usage<63>,  Prev: Features<45>,  Up: lda_projection

6.153.5 Options
---------------

The ‘learn/3’ predicate accepts the following options:

   - ‘n_components/1’: Maximum number of discriminant components to
     extract.  Requests that exceed the minimum of the number of
     features and ‘number_of_classes - 1’ raise
     ‘domain_error(component_count, Requested-Maximum)’.  The default is
     ‘2’.

   - ‘feature_scaling/1’: Whether to standardize continuous attributes
     before estimating scatter matrices.  Options: ‘true’ (default) or
     ‘false’.

   - ‘maximum_iterations/1’: Maximum number of power-iteration steps
     used when estimating each discriminant direction.  The default is
     ‘1000’.

   - ‘tolerance/1’: Positive convergence tolerance used both for
     power-iteration stopping and for deciding when additional
     discriminant directions are numerically negligible.  The default is
     ‘1.0e-8’.

   - ‘regularization/1’: Positive diagonal regularization added to the
     within-class scatter matrix before whitening.  The default is
     ‘1.0e-6’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<63>,  Next: Dimension reducer representation<3>,  Prev: Options<46>,  Up: lda_projection

6.153.6 Usage
-------------

The following examples use the sample labeled dataset shipped with the
‘dimension_reduction_protocols’ library:

     | ?- logtalk_load(dimension_reduction_protocols('test_datasets/labeled_measurements')).

* Menu:

* Learning a reducer: Learning a reducer<3>.
* Transforming new instances: Transforming new instances<3>.
* Exporting and reusing the reducer: Exporting and reusing the reducer<3>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Learning a reducer<3>,  Next: Transforming new instances<3>,  Up: Usage<63>

6.153.6.1 Learning a reducer
............................

     | ?- lda_projection::learn(labeled_measurements, DimensionReducer).

     | ?- lda_projection::learn(labeled_measurements, DimensionReducer, [n_components(1), feature_scaling(false), maximum_iterations(250), tolerance(1.0e-7), regularization(1.0e-5)]).


File: TheLogtalkHandbook-3.101.0.info,  Node: Transforming new instances<3>,  Next: Exporting and reusing the reducer<3>,  Prev: Learning a reducer<3>,  Up: Usage<63>

6.153.6.2 Transforming new instances
....................................

     | ?- lda_projection::learn(labeled_measurements, DimensionReducer),
          lda_projection::transform(DimensionReducer, [length-5.1, width-3.5, height-1.4, weight-0.2], ReducedInstance).

     | ?- lda_projection::learn(labeled_measurements, DimensionReducer, [n_components(1)]),
          lda_projection::transform(DimensionReducer, [length-6.2, width-3.4, height-5.4, weight-2.3], ReducedInstance).


File: TheLogtalkHandbook-3.101.0.info,  Node: Exporting and reusing the reducer<3>,  Prev: Transforming new instances<3>,  Up: Usage<63>

6.153.6.3 Exporting and reusing the reducer
...........................................

     | ?- lda_projection::learn(labeled_measurements, DimensionReducer, [n_components(1)]),
          lda_projection::export_to_file(labeled_measurements, DimensionReducer, reducer, 'lda_projection_reducer.pl').

     | ?- logtalk_load('lda_projection_reducer.pl'),
          reducer(Reducer),
          lda_projection::transform(Reducer, [length-5.1, width-3.5, height-1.4, weight-0.2], ReducedInstance).


File: TheLogtalkHandbook-3.101.0.info,  Node: Dimension reducer representation<3>,  Next: References<32>,  Prev: Usage<63>,  Up: lda_projection

6.153.7 Dimension reducer representation
----------------------------------------

The learned dimension reducer is represented by a compound term with the
functor chosen by the implementation and arity 4.  For example:

     lda_projection_reducer(Encoders, Components, ClassValues, Diagnostics)

Where:

   - ‘Encoders’: List of continuous attribute encoders storing attribute
     name, mean, and scale.

   - ‘Components’: List of learned discriminant vectors in component
     order.

   - ‘ClassValues’: Ordered list of class labels used during training.

   - ‘Diagnostics’: Learned reducer metadata including the effective
     training options and model details.

When exported using ‘export_to_clauses/4’ or ‘export_to_file/4’, this
reducer term is serialized directly as the single argument of the
generated predicate clause so that the exported model can be loaded and
reused as-is.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<32>,  Prev: Dimension reducer representation<3>,  Up: lda_projection

6.153.8 References
------------------

  1. Fisher, R. A. (1936) - “The use of multiple measurements in
     taxonomic problems”.

  2. Rao, C. R. (1948) - “The utilization of multiple measurements in
     problems of biological classification”.


File: TheLogtalkHandbook-3.101.0.info,  Node: linda,  Next: linear_algebra,  Prev: lda_projection,  Up: Libraries

6.154 ‘linda’
=============

Linda is a classic coordination model for process communication.  This
library provides a Linda tuple-space implementation.  Requires both
multi-threading and sockets support.  It supports SWI-Prolog, Trealla
Prolog, and XVM.

The tuple-space is a shared blackboard where processes can:

   - 'Write' tuples using the ‘out/1-2’ predicates

   - 'Read' tuples (without removing) using the ‘rd/1-2’ and
     ‘rd_noblock/1-2’ predicates

   - 'Remove' tuples using the ‘in/1-2’ and ‘in_noblock/1-2’ predicates

The blocking predicates (‘in/1-2’, ‘rd/1-2’) suspend the process until a
matching tuple becomes available.  The non-blocking variants
(‘in_noblock/1-2’, ‘rd_noblock/1-2’) fail immediately if no matching
tuple is found.  There are also additional predicates for list
operations.  Tuples are matched using unification.

* Menu:

* API documentation: API documentation<172>.
* Loading: Loading<174>.
* Testing: Testing<166>.
* Usage: Usage<64>.
* Examples: Examples<175>.
* API Summary::
* Known issues: Known issues<14>.
* See also: See also<2>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<172>,  Next: Loading<174>,  Up: linda

6.154.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#linda’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<174>,  Next: Testing<166>,  Prev: API documentation<172>,  Up: linda

6.154.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(linda(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<166>,  Next: Usage<64>,  Prev: Loading<174>,  Up: linda

6.154.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(linda(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<64>,  Next: Examples<175>,  Prev: Testing<166>,  Up: linda

6.154.4 Usage
-------------

The main library entities are the ‘linda_server’ and ‘linda_client’
categories.  These categories provide a clean separation between server
and client code.  For backward compatibility with the previous version
of this library, a ‘linda’ object importing both categories is also
provided.  The usage examples that follow use this object.  An object
importing the ‘linda_server’ category must use the ‘threaded/0’
directive.

* Menu:

* Starting a server::
* Connecting a client::
* Tuple operations::
* Disconnecting::
* Timeout control::


File: TheLogtalkHandbook-3.101.0.info,  Node: Starting a server,  Next: Connecting a client,  Up: Usage<64>

6.154.4.1 Starting a server
...........................

To start a Linda server that prints its address:

     | ?- linda::linda.
     % Server started at localhost:54321
     ...

To start a server with a callback when it starts:

     | ?- linda::linda([(Host:Port)-format('Server at ~w:~w~n', [Host, Port])]).

The server runs until all clients disconnect after a shutdown request.


File: TheLogtalkHandbook-3.101.0.info,  Node: Connecting a client,  Next: Tuple operations,  Prev: Starting a server,  Up: Usage<64>

6.154.4.2 Connecting a client
.............................

To connect to a server:

     | ?- linda::linda_client(localhost:54321).


File: TheLogtalkHandbook-3.101.0.info,  Node: Tuple operations,  Next: Disconnecting,  Prev: Connecting a client,  Up: Usage<64>

6.154.4.3 Tuple operations
..........................

Write a tuple:

     | ?- linda::out(message(hello, world)).

Read a tuple (blocking):

     | ?- linda::rd(message(X, Y)).
     X = hello,
     Y = world

Remove a tuple (blocking):

     | ?- linda::in(message(X, Y)).
     X = hello,
     Y = world

Non-blocking operations:

     | ?- linda::rd_noblock(message(X, Y)).
     no   % if no matching tuple exists

     | ?- linda::in_noblock(message(X, Y)).
     no   % if no matching tuple exists

Wait for one of several tuples:

     | ?- linda::in([task(1, X), task(2, X), done], Tuple).

Alternative syntax using ‘in_list/2’:

     | ?- linda::in_list([task(1, X), task(2, X), done], Tuple).

Similarly for reading:

     | ?- linda::rd_list([status(ready), status(waiting)], Status).

Collect all matching tuples atomically (read without removing):

     | ?- linda::findall_rd_noblock(N, counter(N), Counters).

Collect and remove all matching tuples atomically:

     | ?- linda::findall_in_noblock(X, item(X), Items).


File: TheLogtalkHandbook-3.101.0.info,  Node: Disconnecting,  Next: Timeout control,  Prev: Tuple operations,  Up: Usage<64>

6.154.4.4 Disconnecting
.......................

Close the client connection:

     | ?- linda::close_client.

Request server shutdown (server stops accepting new connections):

     | ?- linda::shutdown_server, linda::close_client.


File: TheLogtalkHandbook-3.101.0.info,  Node: Timeout control,  Prev: Disconnecting,  Up: Usage<64>

6.154.4.5 Timeout control
.........................

Set a timeout for blocking operations:

     | ?- linda::linda_timeout(Old, 5:0).  % 5 seconds timeout

Disable timeout (wait forever):

     | ?- linda::linda_timeout(_, off).


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<175>,  Next: API Summary,  Prev: Usage<64>,  Up: linda

6.154.5 Examples
----------------

* Menu:

* Producer-Consumer::
* Critical Region::
* Synchronization::


File: TheLogtalkHandbook-3.101.0.info,  Node: Producer-Consumer,  Next: Critical Region,  Up: Examples<175>

6.154.5.1 Producer-Consumer
...........................

Producer (client 1):

     producer :-
         produce(X),
         linda::out(item(X)),
         producer.

Consumer (client 2):

     consumer :-
         linda::in(item(X)),
         consume(X),
         consumer.


File: TheLogtalkHandbook-3.101.0.info,  Node: Critical Region,  Next: Synchronization,  Prev: Producer-Consumer,  Up: Examples<175>

6.154.5.2 Critical Region
.........................

     critical_section :-
         linda::in(mutex),  % acquire lock
         do_critical_work,
         linda::out(mutex). % release lock

Initialize the mutex:

     | ?- linda::out(mutex).


File: TheLogtalkHandbook-3.101.0.info,  Node: Synchronization,  Prev: Critical Region,  Up: Examples<175>

6.154.5.3 Synchronization
.........................

Wait for a signal:

     | ?- linda::in(ready).  % blocks until someone does out(ready)

Send a signal:

     | ?- linda::out(ready).


File: TheLogtalkHandbook-3.101.0.info,  Node: API Summary,  Next: Known issues<14>,  Prev: Examples<175>,  Up: linda

6.154.6 API Summary
-------------------

* Menu:

* Server predicates::
* Client predicates::
* Tuple predicates (single/default server): Tuple predicates single/default server.
* Tuple predicates (multiple servers): Tuple predicates multiple servers.


File: TheLogtalkHandbook-3.101.0.info,  Node: Server predicates,  Next: Client predicates,  Up: API Summary

6.154.6.1 Server predicates
...........................

   - ‘linda’ - Start server on automatic port

   - ‘linda(Options)’ - Start server with options


File: TheLogtalkHandbook-3.101.0.info,  Node: Client predicates,  Next: Tuple predicates single/default server,  Prev: Server predicates,  Up: API Summary

6.154.6.2 Client predicates
...........................

   - ‘linda_client(Address)’ - Connect to server at ‘Host:Port’

   - ‘close_client’ - Close connection

   - ‘shutdown_server’ - Request server shutdown

   - ‘linda_timeout(Old, New)’ - Get/set timeout


File: TheLogtalkHandbook-3.101.0.info,  Node: Tuple predicates single/default server,  Next: Tuple predicates multiple servers,  Prev: Client predicates,  Up: API Summary

6.154.6.3 Tuple predicates (single/default server)
..................................................

   - ‘out(Tuple)’ - Add tuple to space

   - ‘in(Tuple)’ - Remove matching tuple (blocking)

   - ‘in_noblock(Tuple)’ - Remove matching tuple (non-blocking)

   - ‘in(TupleList, Tuple)’ - Remove one of several tuples (blocking)

   - ‘in_list(TupleList, Tuple)’ - Remove one of several tuples
     (blocking)

   - ‘rd(Tuple)’ - Read matching tuple (blocking)

   - ‘rd_noblock(Tuple)’ - Read matching tuple (non-blocking)

   - ‘rd(TupleList, Tuple)’ - Read one of several tuples (blocking)

   - ‘rd_list(TupleList, Tuple)’ - Read one of several tuples (blocking)

   - ‘findall_rd_noblock(Template, Tuple, List)’ - Collect all matching
     tuples (atomic read)

   - ‘findall_in_noblock(Template, Tuple, List)’ - Collect and remove
     all matching tuples (atomic remove)


File: TheLogtalkHandbook-3.101.0.info,  Node: Tuple predicates multiple servers,  Prev: Tuple predicates single/default server,  Up: API Summary

6.154.6.4 Tuple predicates (multiple servers)
.............................................

Variants of the predicates above with an additional first argument for
the server address or the server alias (an atom; default is
‘blackboard’).


File: TheLogtalkHandbook-3.101.0.info,  Node: Known issues<14>,  Next: See also<2>,  Prev: API Summary,  Up: linda

6.154.7 Known issues
--------------------

Recent versions of macOS seem to disable the mapping of ‘localhost’ to
‘127.0.0.1’.  This issue may prevent some functionality from working.
This can be fixed either by editing the ‘/etc/hosts’ file or by using
‘'127.0.0.1'’ as the host argument instead of ‘localhost’.


File: TheLogtalkHandbook-3.101.0.info,  Node: See also<2>,  Prev: Known issues<14>,  Up: linda

6.154.8 See also
----------------

   - SICStus Prolog Linda documentation:
     ‘https://sicstus.sics.se/sicstus/docs/latest4/html/sicstus.html/lib_002dlinda.html’

   - Original Linda papers:

        - Carreiro, N. & Gelernter, D. (1989).  Linda in Context.

        - Carreiro, N. & Gelernter, D. (1989).  How to Write Parallel
          Programs: A Guide to the Perplexed.


File: TheLogtalkHandbook-3.101.0.info,  Node: linear_algebra,  Next: linear_regression,  Prev: linda,  Up: Libraries

6.155 ‘linear_algebra’
======================

This library provides predicates for numeric vectors and matrices,
including vector construction and scaling, general vector norms, matrix
construction and transformation, matrix-matrix products, row Gram
matrices and Gram-centering helpers, offset diagonal helpers,
triangular-part extraction, diagonal shifts, lower- and upper-triangular
matrix solves, direct row and column lookup, tolerance-aware vector
normalization and sign stabilization, generic dense square-system
solves, determinants, matrix inversion, thin QR decomposition, QR-backed
least-squares solving, tolerance-aware rank estimation, real symmetric
eigendecomposition, pseudo-inverse and null-space helpers, covariance
helpers, and Cholesky-based linear solves.

Vectors are represented as lists of numbers.  Matrices are represented
as lists of row lists, where each row is a numeric vector.

Predicates that index into vectors or matrices use one-based indices.
Matrix access predicates use one-based row and column indices.

Square-system predicates include ‘solve_linear_system/3’,
‘solve_linear_systems/3’, ‘determinant/2’, and ‘inverse_matrix/2’.
Rectangular-system predicates include ‘qr_decomposition/3’ and
‘least_squares/3’, ‘pseudo_inverse/2-3’, and ‘null_space/2-3’.
Row-matrix structural predicates include ‘gram_matrix/2’,
‘matrix_row_means/2’, ‘matrix_column_means/2’, ‘center_gram_matrix/4’,
and ‘center_gram_vector/4’.  Diagonal and triangular helpers include
‘matrix_diagonal/2-3’, ‘diagonal_matrix/2-4’,
‘upper_triangular_part/2-3’, and ‘lower_triangular_part/2-3’.  Norm
helpers include ‘vector_norm/3’ and ‘frobenius_norm/2’.  Real symmetric
spectral predicates include ‘symmetric_eigen/3-5’.  Tolerance-sensitive
numerical predicates include ‘normalize_vector/2-3’,
‘first_significant_component/2-3’, ‘stabilize_vector_sign/2-3’,
‘matrix_rank/2-3’, ‘symmetric_eigen/3-5’, ‘pseudo_inverse/2-3’, and
‘null_space/2-3’.

The ‘symmetric_eigen/5’ predicate can be used when callers need to
control the power-iteration budget explicitly instead of relying on the
default iteration bound.

* Menu:

* API documentation: API documentation<173>.
* Loading: Loading<175>.
* Testing: Testing<167>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<173>,  Next: Loading<175>,  Up: linear_algebra

6.155.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#linear_algebra’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<175>,  Next: Testing<167>,  Prev: API documentation<173>,  Up: linear_algebra

6.155.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(linear_algebra(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<167>,  Prev: Loading<175>,  Up: linear_algebra

6.155.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(linear_algebra(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: linear_regression,  Next: linear_svm_classifier,  Prev: linear_algebra,  Up: Libraries

6.156 ‘linear_regression’
=========================

Linear regression regressor supporting continuous and mixed-feature
datasets.  The library implements the ‘regressor_protocol’ defined in
the ‘regression_protocols’ library and learns a linear model using the
shared regression encoding core to build a row-oriented design matrix
with an explicit intercept column before delegating least-squares
solving and rank estimation to the ‘linear_algebra’ library.  The
intercept is always retained and encoded feature columns that are
numerically dependent on the design matrix are assigned zero
coefficients.

* Menu:

* API documentation: API documentation<174>.
* Loading: Loading<176>.
* Testing: Testing<168>.
* Features: Features<46>.
* Regressor representation: Regressor representation<7>.
* Diagnostics syntax: Diagnostics syntax<15>.
* Options: Options<47>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<174>,  Next: Loading<176>,  Up: linear_regression

6.156.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#linear_regression’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<176>,  Next: Testing<168>,  Prev: API documentation<174>,  Up: linear_regression

6.156.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(linear_regression(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<168>,  Next: Features<46>,  Prev: Loading<176>,  Up: linear_regression

6.156.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(linear_regression(tester)).

To run the performance benchmark suite, load the
‘tester_performance.lgt’ file:

     | ?- logtalk_load(linear_regression(tester_performance)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<46>,  Next: Regressor representation<7>,  Prev: Testing<168>,  Up: linear_regression

6.156.4 Features
----------------

   - 'Continuous and Mixed Features': Supports continuous attributes and
     categorical attributes.  -'Categorical Attributes Encoding': Uses
     reference-level dummy coding from the declared dataset attribute
     values.  Encoded columns with no independent signal after
     accounting for the intercept and previously selected features are
     assigned zero coefficients.

   - 'Feature Scaling': Continuous attributes can be standardized using
     z-score scaling.

   - 'Missing Values': Missing numeric and categorical values
     represented using anonymous variables are encoded using explicit
     missing-value indicator features.

   - 'Unknown Values': Prediction requests containing categorical values
     that are not declared by the dataset raise a domain error.

   - 'Rank Handling': Encoded columns that are numerically dependent on
     the intercept or on earlier selected columns are dropped from the
     direct solve and assigned zero coefficients.

   - 'Diagnostics Metadata': Learned regressors record model name,
     target, training example count, solver name, residual sum of
     squares, effective rank, active feature count, encoded feature
     count, and effective options, accessible using the shared
     regression diagnostics predicates.

   - 'Model Export': Learned regressors can be exported as predicate
     clauses or written to a file.

   - 'Reference Benchmarks': Includes a dedicated performance suite
     reporting training time, RMSE, and MAE for representative
     regression datasets.


File: TheLogtalkHandbook-3.101.0.info,  Node: Regressor representation<7>,  Next: Diagnostics syntax<15>,  Prev: Features<46>,  Up: linear_regression

6.156.5 Regressor representation
--------------------------------

The learned regressor is represented by default as:

   - ‘linear_regressor(Encoders, Bias, Weights, Diagnostics)’

The exported predicate clauses therefore use the shape:

   - ‘Functor(Encoders, Bias, Weights, Diagnostics)’

In this representation, ‘Encoders’ stores the feature encoding metadata,
‘Bias’ stores the intercept, ‘Weights’ stores one coefficient per
encoded feature, and ‘Diagnostics’ stores training metadata including
the effective options.


File: TheLogtalkHandbook-3.101.0.info,  Node: Diagnostics syntax<15>,  Next: Options<47>,  Prev: Regressor representation<7>,  Up: linear_regression

6.156.6 Diagnostics syntax
--------------------------

The ‘diagnostics/2’ predicate returns a list of metadata terms with the
form:

     [
         model(linear_regression),
         target(Target),
         training_example_count(TrainingExampleCount),
         options(Options),
         solver(Solver),
         residual_sum_of_squares(ResidualSumOfSquares),
         effective_rank(EffectiveRank),
         active_feature_count(ActiveFeatureCount),
         encoded_feature_count(FeatureCount)
     ]

Where:

   - ‘model(linear_regression)’ identifies the learning algorithm that
     produced the regressor.

   - ‘target(Target)’ stores the target attribute name declared by the
     training dataset.

   - ‘training_example_count(TrainingExampleCount)’ stores the number of
     examples used during training.

   - ‘options(Options)’ stores the effective learning options after
     merging the user options with the library defaults.

   - ‘solver(Solver)’ records the direct least-squares solver family
     used for the fit.  The current value is
     ‘modified_gram_schmidt_column_pivoting’, which is now reported by
     the shared regression core while delegating the actual solve to the
     ‘linear_algebra’ library.

   - ‘residual_sum_of_squares(ResidualSumOfSquares)’ stores the training
     residual sum of squares for the fitted regressor.

   - ‘effective_rank(EffectiveRank)’ stores the rank of the fitted
     row-oriented design matrix, including the intercept column.

   - ‘active_feature_count(ActiveFeatureCount)’ stores the number of
     encoded feature columns retained after subtracting the intercept
     contribution from the fitted design-matrix rank.

   - ‘encoded_feature_count(FeatureCount)’ stores the number of numeric
     features induced by the encoder list, including missing-value
     indicator features.

Use the ‘regression_protocols’ ‘diagnostic/2’ and ‘regressor_options/2’
helper predicates when you only need a single metadata term or the
effective options.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<47>,  Prev: Diagnostics syntax<15>,  Up: linear_regression

6.156.7 Options
---------------

The ‘learn/3’ predicate accepts the following options:

   - ‘feature_scaling/1’: Controls z-score standardization of continuous
     attributes before training and prediction.  Accepted values are
     ‘true’ and ‘false’.  The default is ‘true’.


File: TheLogtalkHandbook-3.101.0.info,  Node: linear_svm_classifier,  Next: listing,  Prev: linear_regression,  Up: Libraries

6.157 ‘linear_svm_classifier’
=============================

Linear support vector machine classifier supporting both binary and
multiclass classification.  Multiclass classification is implemented
using a one-vs-rest scheme with one linear margin model per class, and
training uses batch subgradient descent to fit each hinge-loss model.

The library implements the ‘classifier_protocol’ defined in the
‘classification_protocols’ library.  It provides predicates for learning
a classifier from a dataset object, using it to make predictions, and
exporting the learned model as a list of predicate clauses or to a file.

Datasets are represented as objects implementing the ‘dataset_protocol’
protocol from the ‘classification_protocols’ library.  Existing datasets
in ‘classification_protocols/test_datasets’ can be used for binary,
multiclass, continuous, categorical, and mixed-feature testing.

* Menu:

* API documentation: API documentation<175>.
* Loading: Loading<177>.
* Testing: Testing<169>.
* Features: Features<47>.
* Options: Options<48>.
* Usage: Usage<65>.
* Classifier representation: Classifier representation<6>.
* References: References<33>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<175>,  Next: Loading<177>,  Up: linear_svm_classifier

6.157.1 API documentation
-------------------------

Open the ‘../../docs/library_index.html#linear_svm_classifier’ link in a
web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<177>,  Next: Testing<169>,  Prev: API documentation<175>,  Up: linear_svm_classifier

6.157.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(linear_svm_classifier(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<169>,  Next: Features<47>,  Prev: Loading<177>,  Up: linear_svm_classifier

6.157.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(linear_svm_classifier(tester)).

To run the performance benchmark suite, load the
‘tester_performance.lgt’ file:

     | ?- logtalk_load(linear_svm_classifier(tester_performance)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<47>,  Next: Options<48>,  Prev: Testing<169>,  Up: linear_svm_classifier

6.157.4 Features
----------------

   - 'Binary and Multiclass Classification': Learns one-vs-rest linear
     margin models and predicts the class with the highest score.

   - 'Continuous Features': Standardizes numeric attributes using
     z-score scaling derived from the training data.

   - 'Categorical Features': Expands discrete attributes using one-hot
     encoding based on the declared dataset attribute values and rejects
     unseen values with a domain error.

   - 'Missing Values': Encodes missing numeric and categorical values
     represented using anonymous variables using explicit missing-value
     indicator features.

   - 'Unknown values': Prediction requests containing categorical values
     that are not declared by the dataset raise a domain error.

   - 'Classifier Export': Learned classifiers can be exported as
     predicate clauses or written to a file.

   - 'Pretty Printing': Prints a compact summary of classes, encoders,
     and learned weight vector sizes.

   - 'Reference Benchmarks': Includes a dedicated performance suite
     covering the ‘weather’, ‘mixed’, ‘iris_small’, ‘missing_mixed’, and
     ‘breast_cancer’ datasets with reported training time and training
     accuracy.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<48>,  Next: Usage<65>,  Prev: Features<47>,  Up: linear_svm_classifier

6.157.5 Options
---------------

The ‘learn/3’ predicate supports these options:

   - ‘learning_rate/1’ - base gradient descent learning rate (default:
     ‘0.1’)

   - ‘maximum_iterations/1’ - maximum number of optimization iterations
     (default: ‘1000’)

   - ‘tolerance/1’ - convergence threshold for the maximum parameter
     update (default: ‘1.0e-6’)

   - ‘l2_regularization/1’ - L2 penalty factor applied to weights
     (default: ‘0.01’)


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<65>,  Next: Classifier representation<6>,  Prev: Options<48>,  Up: linear_svm_classifier

6.157.6 Usage
-------------

* Menu:

* Learning a classifier: Learning a classifier<4>.
* Making predictions: Making predictions<4>.
* Exporting the classifier: Exporting the classifier<4>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Learning a classifier<4>,  Next: Making predictions<4>,  Up: Usage<65>

6.157.6.1 Learning a classifier
...............................

     | ?- linear_svm_classifier::learn(weather, Classifier).

     | ?- linear_svm_classifier::learn(iris_small, Classifier, [learning_rate(0.05), maximum_iterations(1500)]).


File: TheLogtalkHandbook-3.101.0.info,  Node: Making predictions<4>,  Next: Exporting the classifier<4>,  Prev: Learning a classifier<4>,  Up: Usage<65>

6.157.6.2 Making predictions
............................

     | ?- linear_svm_classifier::learn(mixed, Classifier),
          linear_svm_classifier::predict(Classifier, [age-45, income-75000, student-no, credit_rating-fair], Class).


File: TheLogtalkHandbook-3.101.0.info,  Node: Exporting the classifier<4>,  Prev: Making predictions<4>,  Up: Usage<65>

6.157.6.3 Exporting the classifier
..................................

     | ?- linear_svm_classifier::learn(weather, Classifier),
          linear_svm_classifier::export_to_clauses(weather, Classifier, classify, Clauses).

     | ?- linear_svm_classifier::learn(weather, Classifier),
          linear_svm_classifier::export_to_file(weather, Classifier, classify, 'classifier.pl').


File: TheLogtalkHandbook-3.101.0.info,  Node: Classifier representation<6>,  Next: References<33>,  Prev: Usage<65>,  Up: linear_svm_classifier

6.157.7 Classifier representation
---------------------------------

The learned classifier is represented as a compound term with the form:

     linear_svm_classifier(Classes, Encoders, Models, Options)

Where:

   - ‘Classes’: list of class labels

   - ‘Encoders’: list of continuous scaling descriptors and categorical
     value lists

   - ‘Models’: list of ‘class_model(Class, Bias, Weights)’ terms

   - ‘Options’: merged training options used to learn the model

When exported using ‘export_to_clauses/4’ or ‘export_to_file/4’, this
classifier term is serialized directly as the single argument of the
generated predicate clause so that the exported model can be loaded and
reused as-is.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<33>,  Prev: Classifier representation<6>,  Up: linear_svm_classifier

6.157.8 References
------------------

  1. Cortes, C. and Vapnik, V. (1995).  “Support-Vector Networks”.

  2. Bishop, C.M. (2006).  “Pattern Recognition and Machine Learning”.
     Section 7.1.

  3. Hastie, T., Tibshirani, R. and Friedman, J. (2009).  “The Elements
     of Statistical Learning”.  Section 12.3.


File: TheLogtalkHandbook-3.101.0.info,  Node: listing,  Next: lof_anomaly_detector,  Prev: linear_svm_classifier,  Up: Libraries

6.158 ‘listing’
===============

This library provides support for listing object dynamic predicate
clauses.  The predicates must (also) be declared using a scope directive
to make them visible to the listing predicates.

* Menu:

* API documentation: API documentation<176>.
* Loading: Loading<178>.
* Testing: Testing<170>.
* Usage: Usage<66>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<176>,  Next: Loading<178>,  Up: listing

6.158.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#listing’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<178>,  Next: Testing<170>,  Prev: API documentation<176>,  Up: listing

6.158.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ utility
file:

     | ?- logtalk_load(listing(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<170>,  Next: Usage<66>,  Prev: Loading<178>,  Up: listing

6.158.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(listing(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<66>,  Prev: Testing<170>,  Up: listing

6.158.4 Usage
-------------

This library provides a ‘listing’ category that can be imported by any
number of objects.  The main predicates are declared public.  If you
want to restrict their scope, use protected or private import.  For
example:

     :- object(data_store,
         imports(private::listing)).

         debug :-
             ^^listing(data/4).
         ...

     :- end_object.

The ‘listing’ category provides a bare-bones ‘portray_clause/1’
predicate implementation.  As this predicate is called (by the
‘listing/0-1’ predicates) using the ‘(::)/1’ control construct, the
object importing the category can easily override the inherited
definition with its own or with a call to the backend system native
implementation of the predicate.  For example, assuming a backend that
provides ‘portray_clause/1’ as a built-in predicate, we can write:

     :- object(thing,
         imports(listing)).

         :- uses(user, [portray_clause/1]).
         ...

     :- end_object.

The main predicate, ‘listing/1’, accepts as argument a predicate
indicator, a non-terminal indicator, or a clause head template (to list
only clauses with a matching head).

This library is often useful as a debugging helper.  For example,
assuming that we want to list dynamic predicate clauses for an object
‘data’ compiled (or created) with the ‘complements’ flag set to ‘allow’,
we can hot patch it to add the ‘listing’ category:

     | ?- create_category(patch, [extends(listing),complements(data)], [], []).
     yes

     | ?- data::listing.
     ...

Another example:

     | ?- create_category(
              patch,
              [extends(listing),complements(data)],
              [public(debug/1)],
              [(debug(Key) :- ::listing(p(Key,Datum)))]
          ).
     yes

     | ?- data::debug(k42).
     ...

Note that the semantics of complementing categories require that we use
the ‘(::)/2’ control construct instead of the ‘(^^)/2’ control construct
as a 'super' call would be interpreted as made from the complemented
object.


File: TheLogtalkHandbook-3.101.0.info,  Node: lof_anomaly_detector,  Next: logging,  Prev: listing,  Up: Libraries

6.159 ‘lof_anomaly_detector’
============================

Local Outlier Factor anomaly detector supporting multiple distance
metrics, mixed continuous and categorical features, and missing values.
The detector memorizes the training instances and computes Local Outlier
Factor values by comparing the local reachability density of a query to
the densities of its neighbors.

The library implements the ‘anomaly_detector_protocol’ defined in the
‘anomaly_detection_protocols’ library.  It learns a compact detector
from a dataset by selecting baseline training examples from the declared
class labels, computes normalized anomaly scores for new instances,
predicts ‘normal’ or ‘anomaly’, and exports learned detectors as clauses
or files.

Datasets are represented as objects implementing the
‘anomaly_dataset_protocol’ protocol from the
‘anomaly_detection_protocols’ library.  See the
‘anomaly_detection_protocols/test_datasets’ directory for examples.

* Menu:

* API documentation: API documentation<177>.
* Loading: Loading<179>.
* Testing: Testing<171>.
* Features: Features<48>.
* Options: Options<49>.
* Detector representation: Detector representation<6>.
* References: References<34>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<177>,  Next: Loading<179>,  Up: lof_anomaly_detector

6.159.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#lof_anomaly_detector’ link in a
web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<179>,  Next: Testing<171>,  Prev: API documentation<177>,  Up: lof_anomaly_detector

6.159.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(lof_anomaly_detector(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<171>,  Next: Features<48>,  Prev: Loading<179>,  Up: lof_anomaly_detector

6.159.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(lof_anomaly_detector(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<48>,  Next: Options<49>,  Prev: Testing<171>,  Up: lof_anomaly_detector

6.159.4 Features
----------------

   - 'Density-based anomaly scoring': computes Local Outlier Factor
     scores from local reachability densities.

   - 'Normalized scores': Raw LOF values are normalized to the interval
     ‘[0.0, 1.0]’ by mapping the ideal baseline value ‘1.0’ to ‘0.0’ and
     scaling larger values against the largest training raw score.

   - 'Mixed features': automatically handles continuous and categorical
     features declared by the dataset.

   - 'Missing values': ignores missing dimensions while normalizing
     distances (distances are normalized by the number of comparable
     dimensions).

   - 'Baseline training selection': ‘baseline_class_values/1’ declares
     which class labels are admissible for fitting the detector, while
     ‘baseline_selection_policy/1’ controls whether non-baseline
     examples are rejected (default) or filtered before training.

   - 'Multiple metrics': supports Euclidean, Manhattan, Chebyshev, and
     Minkowski distance metrics.

   - 'Detector export': learned detectors can be exported as predicate
     clauses.

   - 'Dataset validation': learning rejects empty datasets with a
     ‘domain_error(non_empty_dataset, Dataset)’ exception.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<49>,  Next: Detector representation<6>,  Prev: Features<48>,  Up: lof_anomaly_detector

6.159.5 Options
---------------

The following options can be passed to the ‘learn/3’ and ‘predict/4’
predicates:

   - ‘k(K)’: Number of neighbors to consider (default: 5)

   - ‘distance_metric(Metric)’: Distance metric to use.  Options:
     ‘euclidean’ (default), ‘manhattan’, ‘chebyshev’, ‘minkowski’

   - ‘anomaly_threshold(Threshold)’: Threshold for ‘predict/3-4’
     (default: ‘0.4’)

   - ‘baseline_class_values(Classes)’: Learn-time list of admissible
     baseline class labels (default: ‘[normal]’)

   - ‘baseline_selection_policy(Policy)’: Learn-time handling of
     non-baseline examples.  Supported values are ‘reject’ (default) and
     ‘filter’


File: TheLogtalkHandbook-3.101.0.info,  Node: Detector representation<6>,  Next: References<34>,  Prev: Options<49>,  Up: lof_anomaly_detector

6.159.6 Detector representation
-------------------------------

The learned detector is represented by default as:

     lof_detector(TrainingDataset, AttributeNames, FeatureTypes, AttributeScales, Instances, ReferenceScores, Diagnostics)

Where:

   - ‘AttributeNames’: List of attribute names in order

   - ‘FeatureTypes’: List of feature types (‘numeric’ or ‘categorical’)

   - ‘AttributeScales’: Normalization scales for numeric features

   - ‘Instances’: List of retained baseline training ‘Id-Class-Values’
     triples

   - ‘ReferenceScores’: Cached leave-one-out raw training scores for the
     retained baseline training instances

   - ‘Diagnostics’: Learned metadata terms including ‘model/1’,
     ‘training_dataset/1’, ‘attribute_names/1’, ‘feature_types/1’,
     ‘example_count/1’, ‘reference_score_count/1’, and ‘options/1’

The ‘score/3’ predicate always treats its input as a fresh query.  Only
‘score_all/3’ on the original training dataset with the ‘reject’
baseline selection policy reuses the cached leave-one-out
‘ReferenceScores’ for all examples.  With the ‘filter’ policy, retained
baseline training examples reuse the cached leave-one-out scores while
excluded examples are scored as fresh queries against the learned
baseline detector.

When exported using ‘export_to_clauses/4’ or ‘export_to_file/4’, this
detector term is serialized directly as the single argument of the
generated predicate clause so that the exported model can be loaded and
reused as-is.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<34>,  Prev: Detector representation<6>,  Up: lof_anomaly_detector

6.159.7 References
------------------

  1. Breunig, M. M., Kriegel, H.-P., Ng, R. T., and Sander, J. (2000).
     “LOF: Identifying density-based local outliers”.  SIGMOD.


File: TheLogtalkHandbook-3.101.0.info,  Node: logging,  Next: logistic_regression_classifier,  Prev: lof_anomaly_detector,  Up: Libraries

6.160 ‘logging’
===============

This library provides support for logging events to files.

* Menu:

* API documentation: API documentation<178>.
* Loading: Loading<180>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<178>,  Next: Loading<180>,  Up: logging

6.160.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#logging’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<180>,  Prev: API documentation<178>,  Up: logging

6.160.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ utility
file:

     | ?- logtalk_load(logging(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: logistic_regression_classifier,  Next: loops,  Prev: logging,  Up: Libraries

6.161 ‘logistic_regression_classifier’
======================================

Logistic regression classifier supporting both binary and multiclass
classification.  Multiclass classification is implemented using batch
gradient descent to train a single multiclass softmax model.  Binary
classification is treated as a two-class special case of the same
objective.

The library implements the ‘classifier_protocol’ defined in the
‘classification_protocols’ library.  It provides predicates for learning
a classifier from a dataset object, using it to make predictions,
returning class probabilities, and exporting the learned model as a list
of predicate clauses or to a file.

Datasets are represented as objects implementing the ‘dataset_protocol’
protocol from the ‘classification_protocols’ library.  Existing datasets
in ‘classification_protocols/test_datasets’ can be used for binary,
multiclass, continuous, categorical, and mixed-feature testing.

* Menu:

* API documentation: API documentation<179>.
* Loading: Loading<181>.
* Testing: Testing<172>.
* Features: Features<49>.
* Options: Options<50>.
* Usage: Usage<67>.
* Classifier representation: Classifier representation<7>.
* References: References<35>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<179>,  Next: Loading<181>,  Up: logistic_regression_classifier

6.161.1 API documentation
-------------------------

Open the ‘../../docs/library_index.html#logistic_regression_classifier’
link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<181>,  Next: Testing<172>,  Prev: API documentation<179>,  Up: logistic_regression_classifier

6.161.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(logistic_regression_classifier(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<172>,  Next: Features<49>,  Prev: Loading<181>,  Up: logistic_regression_classifier

6.161.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(logistic_regression_classifier(tester)).

To run the performance benchmark suite, load the
‘tester_performance.lgt’ file:

     | ?- logtalk_load(logistic_regression_classifier(tester_performance)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<49>,  Next: Options<50>,  Prev: Testing<172>,  Up: logistic_regression_classifier

6.161.4 Features
----------------

   - 'Binary and Multiclass Classification': Learns a joint softmax
     logistic model with one parameter vector per class.

   - 'Continuous Features': Standardizes numeric attributes using
     z-score scaling derived from the training data.

   - 'Categorical Features': Expands discrete attributes using one-hot
     encoding based on the declared dataset attribute values and rejects
     unseen values with a domain error.

   - 'Missing Values': Encodes missing numeric and categorical values
     represented using anonymous variables using explicit missing-value
     indicator features instead of being conflated with baseline feature
     values.

   - 'Unknown values': Prediction requests containing categorical values
     that are not declared by the dataset raise a domain error instead
     of being silently mapped into an existing feature bucket.

   - 'Probability Estimation': Provides class probability distributions
     in addition to class predictions.

   - 'Classifier Export': Learned classifiers can be exported as
     predicate clauses or written to a file.

   - 'Reference Benchmarks': Includes a dedicated performance suite
     covering the ‘weather’, ‘mixed’, ‘iris_small’, ‘missing_mixed’, and
     ‘breast_cancer’ datasets with reported training time, training
     accuracy, and mean log loss.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<50>,  Next: Usage<67>,  Prev: Features<49>,  Up: logistic_regression_classifier

6.161.5 Options
---------------

The ‘learn/3’ predicate supports these options:

   - ‘learning_rate/1’ - gradient descent learning rate (default: ‘0.1’)

   - ‘maximum_iterations/1’ - maximum number of optimization iterations
     (default: ‘1000’)

   - ‘tolerance/1’ - convergence threshold for the maximum parameter
     update (default: ‘1.0e-6’)

   - ‘l2_regularization/1’ - L2 penalty factor applied to weights
     (default: ‘0.0’)


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<67>,  Next: Classifier representation<7>,  Prev: Options<50>,  Up: logistic_regression_classifier

6.161.6 Usage
-------------

* Menu:

* Learning a classifier: Learning a classifier<5>.
* Making predictions: Making predictions<5>.
* Exporting the classifier: Exporting the classifier<5>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Learning a classifier<5>,  Next: Making predictions<5>,  Up: Usage<67>

6.161.6.1 Learning a classifier
...............................

     | ?- logistic_regression_classifier::learn(weather, Classifier).

     | ?- logistic_regression_classifier::learn(iris_small, Classifier, [learning_rate(0.05), maximum_iterations(1500)]).


File: TheLogtalkHandbook-3.101.0.info,  Node: Making predictions<5>,  Next: Exporting the classifier<5>,  Prev: Learning a classifier<5>,  Up: Usage<67>

6.161.6.2 Making predictions
............................

     | ?- logistic_regression_classifier::learn(mixed, Classifier),
          logistic_regression_classifier::predict(Classifier, [age-45, income-75000, student-no, credit_rating-fair], Class).

     | ?- logistic_regression_classifier::learn(iris_small, Classifier),
          logistic_regression_classifier::predict_probabilities(Classifier, [sepal_length-6.4, sepal_width-3.0, petal_length-5.8, petal_width-2.2], Probabilities).


File: TheLogtalkHandbook-3.101.0.info,  Node: Exporting the classifier<5>,  Prev: Making predictions<5>,  Up: Usage<67>

6.161.6.3 Exporting the classifier
..................................

     | ?- logistic_regression_classifier::learn(weather, Classifier),
          logistic_regression_classifier::export_to_clauses(weather, Classifier, classify, Clauses).

     | ?- logistic_regression_classifier::learn(weather, Classifier),
          logistic_regression_classifier::export_to_file(weather, Classifier, classify, 'classifier.pl').


File: TheLogtalkHandbook-3.101.0.info,  Node: Classifier representation<7>,  Next: References<35>,  Prev: Usage<67>,  Up: logistic_regression_classifier

6.161.7 Classifier representation
---------------------------------

The learned classifier is represented as a compound term with the form:

     lr_classifier(Classes, Encoders, Models, Options)

Where:

   - ‘Classes’: list of class labels

   - ‘Encoders’: list of continuous scaling descriptors and categorical
     value lists

   - ‘Models’: list of ‘class_model(Class, Bias, Weights)’ terms

   - ‘Options’: merged training options used to learn the model

When exported using ‘export_to_clauses/4’ or ‘export_to_file/4’, this
classifier term is serialized directly as the single argument of the
generated predicate clause so that the exported model can be loaded and
reused as-is.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<35>,  Prev: Classifier representation<7>,  Up: logistic_regression_classifier

6.161.8 References
------------------

  1. Hosmer, D.W., Lemeshow, S. and Sturdivant, R.X. (2013).  “Applied
     Logistic Regression”.

  2. Bishop, C.M. (2006).  “Pattern Recognition and Machine Learning”.
     Chapter 4.

  3. Hastie, T., Tibshirani, R. and Friedman, J. (2009).  “The Elements
     of Statistical Learning”.  Chapter 4.


File: TheLogtalkHandbook-3.101.0.info,  Node: loops,  Next: massey_ranker,  Prev: logistic_regression_classifier,  Up: Libraries

6.162 ‘loops’
=============

This library provides implementations of several kinds of loops typical
of imperative languages.

* Menu:

* API documentation: API documentation<180>.
* Loading: Loading<182>.
* Testing: Testing<173>.
* Usage: Usage<68>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<180>,  Next: Loading<182>,  Up: loops

6.162.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#loops’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<182>,  Next: Testing<173>,  Prev: API documentation<180>,  Up: loops

6.162.2 Loading
---------------

To load the main entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(loops(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<173>,  Next: Usage<68>,  Prev: Loading<182>,  Up: loops

6.162.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(loops(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<68>,  Prev: Testing<173>,  Up: loops

6.162.4 Usage
-------------

See e.g.  the ‘searching’ example.


File: TheLogtalkHandbook-3.101.0.info,  Node: massey_ranker,  Next: mcp_server,  Prev: loops,  Up: Libraries

6.163 ‘massey_ranker’
=====================

Massey pairwise preference ranker.  It builds the Massey coefficient
matrix with diagonal entries ‘games_i’, off-diagonal entries
‘-games_ij’, and a final ‘sum(ratings)=0’ anchoring row, then solves the
linear system using deterministic Gaussian elimination with partial
pivoting and residual validation.

The library implements the ‘ranker_protocol’ defined in the
‘ranking_protocols’ library.  It provides predicates for learning a
ranker from pairwise preferences, using it to order candidate items, and
exporting it as a list of predicate clauses or to a file.

Datasets are represented as objects implementing the
‘pairwise_ranking_dataset_protocol’ protocol from the
‘ranking_protocols’ library.  See the ‘test_datasets’ directory for
examples.  The current implementation requires a well-formed connected
pairwise dataset so that learned rankings remain globally comparable
across all ranked items.

* Menu:

* API documentation: API documentation<181>.
* Loading: Loading<183>.
* Testing: Testing<174>.
* Features: Features<50>.
* Scoring semantics: Scoring semantics<6>.
* Usage: Usage<69>.
* Diagnostics syntax: Diagnostics syntax<16>.
* Ranker representation: Ranker representation<10>.
* References: References<36>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<181>,  Next: Loading<183>,  Up: massey_ranker

6.163.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#massey_ranker’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<183>,  Next: Testing<174>,  Prev: API documentation<181>,  Up: massey_ranker

6.163.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(massey_ranker(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<174>,  Next: Features<50>,  Prev: Loading<183>,  Up: massey_ranker

6.163.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(massey_ranker(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<50>,  Next: Scoring semantics<6>,  Prev: Testing<174>,  Up: massey_ranker

6.163.4 Features
----------------

   - 'Pairwise Preference Learning': Learns one deterministic rating per
     item from aggregated pairwise outcomes.

   - 'Massey Matrix Fidelity': Solves the standard Massey linear system
     with diagonal entries ‘games_i’, off-diagonal entries ‘-games_ij’,
     and a final anchoring row enforcing ‘sum(ratings) = 0’.

   - 'Numerically Hardened Solver': Uses Gaussian elimination with
     partial pivoting plus residual checks before accepting the learned
     ratings.

   - 'Zero-Sum Ratings': Produces ratings centered at ‘0.0’, where
     positive values indicate above-average aggregate performance and
     negative values indicate below-average aggregate performance.

   - 'Deterministic Ranking': Orders candidate items by learned rating
     with deterministic tie-breaking.

   - 'Strict Dataset Validation': Rejects duplicate items, undeclared
     items, self-preferences, non-positive weights, and disconnected
     comparison graphs.

   - 'Ranker Export': Learned rankers can be exported as self-contained
     terms.

   - 'Shared Ranking Infrastructure': Reuses the ‘ranking_protocols’
     helpers for dataset validation, diagnostics, export, and candidate
     ranking.


File: TheLogtalkHandbook-3.101.0.info,  Node: Scoring semantics<6>,  Next: Usage<69>,  Prev: Features<50>,  Up: massey_ranker

6.163.5 Scoring semantics
-------------------------

This implementation aggregates pairwise preferences into matchup totals
and then solves the Massey system

     M r = p

where ‘M_ii = games_i’, ‘M_ij = -games_ij’ for ‘i \= j’, and the final
row of ‘M’ is replaced with ones so that the learned ratings satisfy
‘sum(ratings) = 0’.  The right-hand-side vector ‘p’ is the per-item
signed point-differential total ‘wins_i - losses_i’.

The linear system is solved using deterministic Gaussian elimination
with partial pivoting.  The implementation also verifies that the
recovered solution has a small residual and only clamps negligible
floating-point noise around ‘0.0’.

The resulting ratings are relative rather than probabilistic: only their
differences and ordering matter.  Larger positive values indicate
stronger aggregate pairwise performance against the field.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<69>,  Next: Diagnostics syntax<16>,  Prev: Scoring semantics<6>,  Up: massey_ranker

6.163.6 Usage
-------------

* Menu:

* Learning a ranker: Learning a ranker<10>.
* Inspecting diagnostics: Inspecting diagnostics<8>.
* Ranking candidate items: Ranking candidate items<9>.
* Exporting the ranker: Exporting the ranker<8>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Learning a ranker<10>,  Next: Inspecting diagnostics<8>,  Up: Usage<69>

6.163.6.1 Learning a ranker
...........................

     % Learn from a pairwise ranking dataset object
     | ?- massey_ranker::learn(my_dataset, Ranker).
     ...

     % Learn with an explicit empty options list
     | ?- massey_ranker::learn(my_dataset, Ranker, []).
     ...

The current implementation accepts only the empty options list ‘[]’.
Any non-empty options list is rejected.


File: TheLogtalkHandbook-3.101.0.info,  Node: Inspecting diagnostics<8>,  Next: Ranking candidate items<9>,  Prev: Learning a ranker<10>,  Up: Usage<69>

6.163.6.2 Inspecting diagnostics
................................

     % Inspect model and dataset summary metadata
     | ?- massey_ranker::learn(my_dataset, Ranker),
          massey_ranker::diagnostics(Ranker, Diagnostics).
     Diagnostics = [...]
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Ranking candidate items<9>,  Next: Exporting the ranker<8>,  Prev: Inspecting diagnostics<8>,  Up: Usage<69>

6.163.6.3 Ranking candidate items
.................................

     % Rank a candidate set from most preferred to least preferred
     | ?- massey_ranker::learn(my_dataset, Ranker),
          massey_ranker::rank(Ranker, [item_a, item_b, item_c], Ranking).
     Ranking = [...]
     ...

Candidate lists must be proper lists of unique, ground items declared by
the training dataset.  Invalid ranker terms, duplicate candidates, and
candidates containing variables are rejected with errors instead of
being silently accepted.


File: TheLogtalkHandbook-3.101.0.info,  Node: Exporting the ranker<8>,  Prev: Ranking candidate items<9>,  Up: Usage<69>

6.163.6.4 Exporting the ranker
..............................

Learned rankers can be exported as a list of clauses or to a file for
later use.

     % Export as predicate clauses
     | ?- massey_ranker::learn(my_dataset, Ranker),
          massey_ranker::export_to_clauses(my_dataset, Ranker, my_ranker, Clauses).
     Clauses = [my_ranker(massey_ranker(...))]
     ...

     % Export to a file
     | ?- massey_ranker::learn(my_dataset, Ranker),
          massey_ranker::export_to_file(my_dataset, Ranker, my_ranker, 'ranker.pl').
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Diagnostics syntax<16>,  Next: Ranker representation<10>,  Prev: Usage<69>,  Up: massey_ranker

6.163.7 Diagnostics syntax
--------------------------

The ‘diagnostics/2’ predicate returns a list of metadata terms with the
form:

     [
         model(massey_ranker),
         options(Options),
         dataset_summary(DatasetSummary)
     ]


File: TheLogtalkHandbook-3.101.0.info,  Node: Ranker representation<10>,  Next: References<36>,  Prev: Diagnostics syntax<16>,  Up: massey_ranker

6.163.8 Ranker representation
-----------------------------

The learned ranker is represented by a compound term of the form:

     massey_ranker(Items, Ratings, Diagnostics)

Where:

   - ‘Items’: List of ranked items.

   - ‘Ratings’: List of ‘Item-Rating’ pairs.

   - ‘Diagnostics’: List of metadata terms, including the effective
     options and dataset summary.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<36>,  Prev: Ranker representation<10>,  Up: massey_ranker

6.163.9 References
------------------

  1. Massey, K. (1997).  'Statistical models applied to the rating of
     sports teams'.


File: TheLogtalkHandbook-3.101.0.info,  Node: mcp_server,  Next: memcached,  Prev: massey_ranker,  Up: Libraries

6.164 ‘mcp_server’
==================

MCP (Model Context Protocol) server library for Logtalk applications.
Makes any Logtalk application available as a local MCP server using
stdio transport.  Implements the MCP 2025-06-18 specification (tools,
prompts, resources, elicitation, structured output, and resource links).
Supports version negotiation.

The library uses the ‘json_rpc’ library for JSON-RPC 2.0 message
handling as currently required by the MCP specification.

* Menu:

* API documentation: API documentation<182>.
* Loading: Loading<184>.
* Testing: Testing<175>.
* Usage: Usage<70>.
* Error handling: Error handling<4>.
* Protocol::
* Supported MCP methods::


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<182>,  Next: Loading<184>,  Up: mcp_server

6.164.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#mcp_server’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<184>,  Next: Testing<175>,  Prev: API documentation<182>,  Up: mcp_server

6.164.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(mcp_server(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<175>,  Next: Usage<70>,  Prev: Loading<184>,  Up: mcp_server

6.164.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(mcp_server(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<70>,  Next: Error handling<4>,  Prev: Testing<175>,  Up: mcp_server

6.164.4 Usage
-------------

* Menu:

* Implementing the tool protocol::
* Auto-dispatch vs. custom tool_call/3: Auto-dispatch vs custom tool_call/3.
* Output schemas (structured tool output): Output schemas structured tool output.
* Starting the server for debugging::
* MCP client configuration::
* Elicitation (interactive tools): Elicitation interactive tools.
* Prompts (prompt templates): Prompts prompt templates.
* Resources (data exposure): Resources data exposure.


File: TheLogtalkHandbook-3.101.0.info,  Node: Implementing the tool protocol,  Next: Auto-dispatch vs custom tool_call/3,  Up: Usage<70>

6.164.4.1 Implementing the tool protocol
........................................

To expose a Logtalk object as an MCP tool provider, implement the
‘mcp_tool_protocol’ protocol:

     :- object(my_tools,
         implements(mcp_tool_protocol)).

         :- public(factorial/2).
         :- mode(factorial(+integer, -integer), one).
         :- info(factorial/2, [
             comment is 'Computes the factorial of a non-negative integer.',
             argnames is ['N', 'F']
         ]).

         tools([
             tool(factorial, factorial, 2)
         ]).

         factorial(0, 1) :- !.
         factorial(N, F) :-
             N > 0,
             N1 is N - 1,
             factorial(N1, F1),
             F is N * F1.

     :- end_object.

The ‘tools/1’ predicate returns a list of ‘tool(Name, Functor, Arity)’
descriptors that declare which predicates are exposed as MCP tools:

   - ‘Name’ — the MCP tool name (an atom)

   - ‘Functor’ — the predicate functor

   - ‘Arity’ — the predicate arity

Tool descriptions and parameter schemas are automatically derived from
the ‘info/2’ and ‘mode/2’ directives.  This must be accurate to allow
correct derivation of inout and output arguments and types.

A ‘title’ key in the predicate’s ‘info/2’ directive provides a
human-friendly display name for the tool.  If omitted, the predicate
functor is used as the title.

The supported predicates types and their corresponding JSON types are:

Logtalk type     JSON type
                 
---------------------------------
‘integer’        ‘integer’
                 
‘float’          ‘number’
                 
‘number’         ‘number’
                 
‘atom’           ‘string’
                 
‘boolean’        ‘boolean’
                 
‘list’           ‘array’
                 
‘list(_)’        ‘array’
                 
‘compound’       ‘object’
                 
‘nonvar’         ‘string’
                 
‘term’           ‘string’
                 
‘chars’          ‘string’
                 
‘codes’          ‘string’
                 
(other)          ‘string’
                 


File: TheLogtalkHandbook-3.101.0.info,  Node: Auto-dispatch vs custom tool_call/3,  Next: Output schemas structured tool output,  Prev: Implementing the tool protocol,  Up: Usage<70>

6.164.4.2 Auto-dispatch vs. custom ‘tool_call/3’
................................................

By default, when an MCP client calls a tool, the server auto-dispatches:
it calls the corresponding predicate as a message to the application
object, collects output-mode arguments (‘-’ and ‘--’), and returns them
as text content.

For custom result formatting, implement ‘tool_call/3’:

     tool_call(factorial, Arguments, Result) :-
         member('N'-N, Arguments),
         factorial(N, F),
         number_codes(F, Codes),
         atom_codes(FAtom, Codes),
         atom_concat('The factorial is: ', FAtom, Text),
         Result = text(Text).

The ‘Result’ term can be:

   - ‘text(Atom)’ — a text result

   - ‘error(Atom)’ — a tool-level error (sets ‘isError: true’)

   - ‘results(List)’ — a list of content items (‘text(Atom)’,
     ‘error(Atom)’, ‘resource_link(URI, Name)’, or ‘resource_link(URI,
     Name, Description, MimeType)’)

   - ‘structured(StructuredContent)’ — a structured result (the server
     auto-generates a text representation for the ‘content’ field)

   - ‘structured(Items, StructuredContent)’ — a structured result with
     explicit content items for the ‘content’ field


File: TheLogtalkHandbook-3.101.0.info,  Node: Output schemas structured tool output,  Next: Starting the server for debugging,  Prev: Auto-dispatch vs custom tool_call/3,  Up: Usage<70>

6.164.4.3 Output schemas (structured tool output)
.................................................

Tools can declare an output schema by defining ‘output_schema/2’ in
their application object:

     output_schema(divide, {type-object, properties-{quotient-{type-number}}, required-[quotient]}).

When an output schema is declared, the tool descriptor includes an
‘outputSchema’ field.  The tool’s ‘tool_call/3’ can then return
‘structured(StructuredContent)’ or ‘structured(Items,
StructuredContent)’ results.  The ‘StructuredContent’ must be a
curly-term matching the schema.


File: TheLogtalkHandbook-3.101.0.info,  Node: Starting the server for debugging,  Next: MCP client configuration,  Prev: Output schemas structured tool output,  Up: Usage<70>

6.164.4.4 Starting the server for debugging
...........................................

Start the MCP server from a Logtalk top-level or script:

     | ?- mcp_server::start('my-server', my_tools).

With options:

     | ?- mcp_server::start('my-server', my_tools, [version('2.0.0'), server_title('My Server')]).

There should either be no output or only a Prolog backend term input
prompt.  Other than that, any spurious output will break the connection
between a MCP client and the MCP server.


File: TheLogtalkHandbook-3.101.0.info,  Node: MCP client configuration,  Next: Elicitation interactive tools,  Prev: Starting the server for debugging,  Up: Usage<70>

6.164.4.5 MCP client configuration
..................................

To use the server with an MCP client (e.g., VSCode or Claude Desktop),
configure it as a stdio server.  Example ‘claude_desktop_config.json’:

     {
         "mcpServers": {
             "my-server": {
                 "command": "swilgt",
                 "args": [
                     "-q",
                     "-g", "logtalk_load(my_mcp_server(loader))",
                     "-t", "halt"
                 ],
                 "env": {
                     "LOGTALKHOME": "/usr/local/share/logtalk",
                     "LOGTALKUSER": "/Users/jdoe/logtalk"
                 }
             }
         }
     }

The ‘env’ definition of the ‘LOGTALKHOME’ and ‘LOGTALKUSER’ environment
variables may or may not be required (it’s usually necessary on macOS).
When required, replace the values above with the actual values on your
Logtalk setup.

The actual arguments to the integration script (‘swilgt’ in the example
above) depend on the Prolog backend.  For example, XVM requires instead:

     {
         "mcpServers": {
             "my-server": {
                 "command": "xvmlgt",
                 "args": [
                     "-q",
                     "-g", "logtalk_load(my_mcp_server(loader)), halt.",
                 ],
                 "env": {
                     "LOGTALKHOME": "/usr/local/share/logtalk",
                     "LOGTALKUSER": "/Users/jdoe/logtalk"
                 }
             }
         }
     }


File: TheLogtalkHandbook-3.101.0.info,  Node: Elicitation interactive tools,  Next: Prompts prompt templates,  Prev: MCP client configuration,  Up: Usage<70>

6.164.4.6 Elicitation (interactive tools)
.........................................

Tools that need to ask the user questions during execution can use MCP
elicitation 'if' the MCP client supports it (tested and working with
VSCode Copilot).  The application declares the ‘elicitation’ capability
and implements ‘tool_call/4’ instead of ‘tool_call/3’:

     :- object(interactive_tools,
         implements(mcp_tool_protocol)).

         capabilities([elicitation]).

         tools([
             tool(ask_name, ask_name, 0)
         ]).

         :- public(ask_name/0).
         :- info(ask_name/0, [
             comment is 'Asks the user for their name and greets them.'
         ]).

         tool_call(ask_name, _Arguments, Elicit, Result) :-
             Schema = {
                 type-object,
                 properties-{name-{type-string}},
                 required-[name]
             },
             call(Elicit, 'What is your name?', Schema, Answer),
             (   Answer = accept(Content),
                 has_pair(Content, name, Name) ->
                 atom_concat('Hello, ', Name, Greeting),
                 atom_concat(Greeting, '!', Text),
                 Result = text(Text)
             ;   Result = text('No name provided.')
             ).

         has_pair({Pairs}, Key, Value) :-
             curly_member(Key-Value, Pairs).

         curly_member(Pair, (Pair, _)) :- !.
         curly_member(Pair, (_, Rest)) :-
             !, curly_member(Pair, Rest).
         curly_member(Pair, Pair).

     :- end_object.

The ‘Elicit’ closure is called as ‘call(Elicit, Message, Schema,
Answer)’ where:

   - ‘Message’ — an atom with the prompt text

   - ‘Schema’ — a curly-term JSON Schema for the requested input

   - ‘Answer’ — unified with ‘accept(Content)’, ‘decline’, or ‘cancel’

When ‘accept(Content)’ is returned, ‘Content’ is a curly-term with the
user’s response matching the requested schema.

See the ‘examples/birds_mcp/’ example for a complete demonstration of
elicitation with a bird identification expert system.


File: TheLogtalkHandbook-3.101.0.info,  Node: Prompts prompt templates,  Next: Resources data exposure,  Prev: Elicitation interactive tools,  Up: Usage<70>

6.164.4.7 Prompts (prompt templates)
....................................

MCP prompts are templates for structured LLM interactions.  They allow
an application to expose reusable prompt templates that MCP clients can
discover and use.  To add prompts, implement ‘mcp_prompt_protocol’ in
addition to ‘mcp_tool_protocol’, and declare ‘prompts’ in capabilities:

     :- object(my_prompts,
         implements([mcp_tool_protocol, mcp_prompt_protocol])).

         capabilities([prompts]).

         tools([]).

         prompts([
             prompt(code_review, 'Reviews code for potential issues', [
                 argument(code, 'The code to review', true),
                 argument(language, 'The programming language', false)
             ]),
             prompt(summarize, 'Summarizes a given text', [
                 argument(text, 'The text to summarize', true)
             ])
         ]).

         prompt_get(code_review, Arguments, Result) :-
             (   member(code-Code, Arguments) ->
                 atom_concat('Please review the following code for potential issues:\n\n', Code, Text)
             ;   Text = 'Please provide code to review.'
             ),
             Result = messages([message(user, text(Text))]).

         prompt_get(summarize, Arguments, Result) :-
             (   member(text-Text, Arguments) ->
                 atom_concat('Please summarize the following text:\n\n', Text, PromptText)
             ;   PromptText = 'Please provide text to summarize.'
             ),
             Result = messages([message(user, text(PromptText))]).

         :- uses(list, [member/2]).

     :- end_object.

The ‘prompts/1’ predicate returns a list of prompt descriptors:

   - ‘prompt(Name, Description, Arguments)’ — without title

   - ‘prompt(Name, Title, Description, Arguments)’ — with title

Where:

   - ‘Name’ — the MCP prompt name (an atom)

   - ‘Title’ — a human-friendly display name (an atom, optional)

   - ‘Description’ — a human-readable description (an atom)

   - ‘Arguments’ — a list of ‘argument(ArgName, ArgDescription,
     Required)’ terms where ‘Required’ is ‘true’ or ‘false’

The ‘prompt_get/3’ predicate handles prompt get requests.  Its result
term can be:

   - ‘messages(MessageList)’ — a list of prompt messages

   - ‘messages(Description, MessageList)’ — a list of messages with a
     description

Each message in the list is a ‘message(Role, Content)’ term where:

   - ‘Role’ — ‘user’ or ‘assistant’

   - ‘Content’ — ‘text(Text)’ where ‘Text’ is an atom

Multi-turn prompts can return multiple messages:

     prompt_get(debate, Arguments, Result) :-
         member(topic-Topic, Arguments),
         atom_concat('Let us debate: ', Topic, UserText),
         Result = messages([
             message(user, text(UserText)),
             message(assistant, text('I would be happy to debate that topic. What is your position?'))
         ]).


File: TheLogtalkHandbook-3.101.0.info,  Node: Resources data exposure,  Prev: Prompts prompt templates,  Up: Usage<70>

6.164.4.8 Resources (data exposure)
...................................

MCP resources expose data and content from the application that MCP
clients can access.  To add resources, implement ‘mcp_resource_protocol’
in addition to ‘mcp_tool_protocol’, and declare ‘resources’ in
capabilities:

     :- object(my_resources,
         implements([mcp_tool_protocol, mcp_resource_protocol])).

         capabilities([resources]).

         tools([]).

         resources([
             resource('logtalk://my-app/config', config, 'Application configuration', 'application/json'),
             resource('logtalk://my-app/readme', readme, 'Application readme', 'text/plain')
         ]).

         resource_read('logtalk://my-app/config', _Arguments, Result) :-
             Result = contents([
                 text_content('logtalk://my-app/config', 'application/json', '{"name": "my-app", "version": "1.0"}')
             ]).

         resource_read('logtalk://my-app/readme', _Arguments, Result) :-
             Result = contents([
                 text_content('logtalk://my-app/readme', 'text/plain', 'Welcome to my application.')
             ]).

     :- end_object.

The ‘resources/1’ predicate returns a list of resource descriptors:

   - ‘resource(URI, Name, Description, MimeType)’ — without title

   - ‘resource(URI, Name, Title, Description, MimeType)’ — with title

Where:

   - ‘URI’ — the resource identifier (an atom, typically a URI like
     ‘logtalk://my-app/data’)

   - ‘Name’ — a human-readable name (an atom)

   - ‘Title’ — a human-friendly display name (an atom, optional)

   - ‘Description’ — a human-readable description (an atom)

   - ‘MimeType’ — the MIME type of the resource content (an atom, e.g.
     ‘'text/plain'’, ‘'application/json'’)

The ‘resource_read/3’ predicate handles resource read requests.  Its
result term must be ‘contents(ContentList)’ where each content item is:

   - ‘text_content(URI, MimeType, Text)’ — for text resources

   - ‘blob_content(URI, MimeType, Base64Data)’ — for binary resources
     encoded as base64

A resource can return multiple content items:

     resource_read('logtalk://my-app/logs', _Arguments, Result) :-
         Result = contents([
             text_content('logtalk://my-app/logs', 'text/plain', 'Log entry 1'),
             text_content('logtalk://my-app/logs', 'text/plain', 'Log entry 2')
         ]).


File: TheLogtalkHandbook-3.101.0.info,  Node: Error handling<4>,  Next: Protocol,  Prev: Usage<70>,  Up: mcp_server

6.164.5 Error handling
----------------------

   - Predicate failures result in a tool-level error with ‘isError:
     true’.

   - Predicate exceptions result in a tool-level error with the
     exception term serialized as the error text.

   - Prompt execution failures result in a JSON-RPC error response.

   - Resource read failures result in a JSON-RPC error response.


File: TheLogtalkHandbook-3.101.0.info,  Node: Protocol,  Next: Supported MCP methods,  Prev: Error handling<4>,  Up: mcp_server

6.164.6 Protocol
----------------

The ‘mcp_tool_protocol’ protocol defines the following predicates:

   - ‘capabilities/1’ — returns the list of additional capabilities
     needed by the application (e.g.  ‘[elicitation]’, ‘[prompts]’,
     ‘[resources]’, or ‘[prompts, resources, elicitation]’); optional,
     defaults to ‘[]’

   - ‘tools/1’ — returns the list of tool descriptors

   - ‘tool_call/3’ — handles a tool call (optional; auto-dispatch is
     used when not defined)

   - ‘tool_call/4’ — handles a tool call with an elicitation closure
     (optional; requires ‘capabilities([elicitation])’ or
     ‘capabilities([..., elicitation])’)

   - ‘output_schema/2’ — declares a JSON Schema for structured tool
     output (optional; when defined, the tool descriptor includes
     ‘outputSchema’)

The ‘mcp_prompt_protocol’ protocol defines the following predicates:

   - ‘prompts/1’ — returns the list of prompt descriptors

   - ‘prompt_get/3’ — handles a prompt get request

The ‘mcp_resource_protocol’ protocol defines the following predicates:

   - ‘resources/1’ — returns the list of resource descriptors

   - ‘resource_read/3’ — handles a resource read request


File: TheLogtalkHandbook-3.101.0.info,  Node: Supported MCP methods,  Prev: Protocol,  Up: mcp_server

6.164.7 Supported MCP methods
-----------------------------

Method                     Type             Description
                                            
-------------------------------------------------------------------------------
‘initialize’               Request          MCP handshake
                                            
‘initialized’              Notification     Client acknowledgment
                                            
‘ping’                     Request          Server liveness check
                                            
‘tools/list’               Request          Lists available tools
                                            
‘tools/call’               Request          Calls a tool
                                            
‘prompts/list’             Request          Lists available prompts
                                            
‘prompts/get’              Request          Gets a prompt with arguments
                                            
‘resources/list’           Request          Lists available resources
                                            
‘resources/read’           Request          Reads a resource by URI
                                            
‘elicitation/create’       Request (=>)     Asks the client for user input
                                            


File: TheLogtalkHandbook-3.101.0.info,  Node: memcached,  Next: message_pack,  Prev: mcp_server,  Up: Libraries

6.165 ‘memcached’
=================

Portable Memcached client implementing the text (ASCII) protocol.  This
library uses the ‘sockets’ library and supports all backend Prolog
systems supported by that library: ECLiPSe, GNU Prolog, SICStus Prolog,
SWI-Prolog, Trealla Prolog, and XVM.

* Menu:

* API documentation: API documentation<183>.
* Loading: Loading<185>.
* Testing: Testing<176>.
* Protocol Version::
* Features: Features<51>.
* Usage: Usage<71>.
* API Summary: API Summary<2>.
* Error Handling: Error Handling<2>.
* Key Format::
* Expiration Times::


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<183>,  Next: Loading<185>,  Up: memcached

6.165.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#memcached’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<185>,  Next: Testing<176>,  Prev: API documentation<183>,  Up: memcached

6.165.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(memcached(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<176>,  Next: Protocol Version,  Prev: Loading<185>,  Up: memcached

6.165.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(memcached(tester)).

Note: Tests require a running Memcached server on ‘localhost’ port
‘11211’ (the default).  To install and start Memcached:

On macOS:

     $ brew install memcached
     $ memcached -d

On Linux (Debian/Ubuntu):

     $ sudo apt-get install memcached
     $ sudo systemctl start memcached

On Linux (RHEL/Fedora):

     $ sudo dnf install memcached
     $ sudo systemctl start memcached


File: TheLogtalkHandbook-3.101.0.info,  Node: Protocol Version,  Next: Features<51>,  Prev: Testing<176>,  Up: memcached

6.165.4 Protocol Version
------------------------

This library implements the Memcached text (ASCII) protocol as
documented in the official specification:

‘https://github.com/memcached/memcached/blob/master/doc/protocol.txt’

The text protocol is the standard protocol supported by all Memcached
clients and servers.  All commands use simple text lines terminated by
‘\r\n’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<51>,  Next: Usage<71>,  Prev: Protocol Version,  Up: memcached

6.165.5 Features
----------------

   - Full storage command support: ‘set’, ‘add’, ‘replace’, ‘append’,
     ‘prepend’, ‘cas’

   - Retrieval commands: ‘get’, ‘gets’ (with CAS token), multi-get,
     ‘gat’, ‘gats’

   - Key deletion with ‘delete’

   - Atomic increment/decrement with ‘incr’/‘decr’

   - Item expiration management with ‘touch’, ‘gat’, ‘gats’

   - Server management: ‘flush_all’, ‘version’, ‘stats’

   - Graceful disconnect with ‘quit’

   - Proper handling of all protocol response codes


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<71>,  Next: API Summary<2>,  Prev: Features<51>,  Up: memcached

6.165.6 Usage
-------------

* Menu:

* Connecting to a Memcached server::
* Storing data::
* Retrieving data::
* Check-and-Set (CAS): Check-and-Set CAS.
* Deleting data::
* Increment/Decrement::
* Touch and Get-and-Touch::
* Server management::
* Disconnecting: Disconnecting<2>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Connecting to a Memcached server,  Next: Storing data,  Up: Usage<71>

6.165.6.1 Connecting to a Memcached server
..........................................

Basic connection to localhost on the default port (11211):

     ?- memcached::connect(localhost, Connection).

Connection to a specific host and port:

     ?- memcached::connect('cache.example.com', 11211, Connection).


File: TheLogtalkHandbook-3.101.0.info,  Node: Storing data,  Next: Retrieving data,  Prev: Connecting to a Memcached server,  Up: Usage<71>

6.165.6.2 Storing data
......................

Store a value unconditionally:

     ?- memcached::set(Connection, my_key, 'Hello, World!').

Store with flags and expiration time (in seconds):

     ?- memcached::set(Connection, my_key, 'Hello!', 0, 3600).

Store only if the key does not exist:

     ?- memcached::add(Connection, new_key, 'New value', 0, 60).

Store only if the key already exists:

     ?- memcached::replace(Connection, existing_key, 'Updated', 0, 60).

Append data to an existing value:

     ?- memcached::append(Connection, my_key, ' World!').

Prepend data to an existing value:

     ?- memcached::prepend(Connection, my_key, 'Hello ').


File: TheLogtalkHandbook-3.101.0.info,  Node: Retrieving data,  Next: Check-and-Set CAS,  Prev: Storing data,  Up: Usage<71>

6.165.6.3 Retrieving data
.........................

Get a value by key:

     ?- memcached::get(Connection, my_key, Value).

Get a value with flags:

     ?- memcached::get(Connection, my_key, Value, Flags).

Get a value with CAS token (for optimistic locking):

     ?- memcached::gets(Connection, my_key, Value, CasUnique).

Get multiple keys at once:

     ?- memcached::mget(Connection, [key1, key2, key3], Items).


File: TheLogtalkHandbook-3.101.0.info,  Node: Check-and-Set CAS,  Next: Deleting data,  Prev: Retrieving data,  Up: Usage<71>

6.165.6.4 Check-and-Set (CAS)
.............................

CAS provides optimistic locking for cache updates:

     ?- memcached::gets(Connection, my_key, Value, CasUnique),
        % ... process value ...
        memcached::cas(Connection, my_key, 'New value', 0, 60, CasUnique).

If another client modifies the value between ‘gets’ and ‘cas’, the ‘cas’
command will throw ‘error(memcached_error(exists), _)’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Deleting data,  Next: Increment/Decrement,  Prev: Check-and-Set CAS,  Up: Usage<71>

6.165.6.5 Deleting data
.......................

Delete an item by key:

     ?- memcached::delete(Connection, my_key).

Fails if the key does not exist.


File: TheLogtalkHandbook-3.101.0.info,  Node: Increment/Decrement,  Next: Touch and Get-and-Touch,  Prev: Deleting data,  Up: Usage<71>

6.165.6.6 Increment/Decrement
.............................

Atomically increment a numeric value:

     ?- memcached::set(Connection, counter, '100'),
        memcached::incr(Connection, counter, 5, NewValue).
     % NewValue = 105

Atomically decrement a numeric value:

     ?- memcached::decr(Connection, counter, 3, NewValue).
     % NewValue = 102

Note: The item must already exist and contain a decimal representation
of a 64-bit unsigned integer.  Decrementing below 0 yields 0.


File: TheLogtalkHandbook-3.101.0.info,  Node: Touch and Get-and-Touch,  Next: Server management,  Prev: Increment/Decrement,  Up: Usage<71>

6.165.6.7 Touch and Get-and-Touch
.................................

Update expiration time without fetching:

     ?- memcached::touch(Connection, my_key, 3600).

Fetch and update expiration time in one operation:

     ?- memcached::gat(Connection, my_key, 3600, Value).

Fetch with CAS and update expiration:

     ?- memcached::gats(Connection, my_key, 3600, Value, CasUnique).


File: TheLogtalkHandbook-3.101.0.info,  Node: Server management,  Next: Disconnecting<2>,  Prev: Touch and Get-and-Touch,  Up: Usage<71>

6.165.6.8 Server management
...........................

Invalidate all items:

     ?- memcached::flush_all(Connection).

Invalidate all items after a delay (in seconds):

     ?- memcached::flush_all(Connection, 30).

Get server version:

     ?- memcached::version(Connection, Version).

Get server statistics:

     ?- memcached::stats(Connection, Stats).

Get specific statistics:

     ?- memcached::stats(Connection, items, Stats).


File: TheLogtalkHandbook-3.101.0.info,  Node: Disconnecting<2>,  Prev: Server management,  Up: Usage<71>

6.165.6.9 Disconnecting
.......................

     ?- memcached::disconnect(Connection).


File: TheLogtalkHandbook-3.101.0.info,  Node: API Summary<2>,  Next: Error Handling<2>,  Prev: Usage<71>,  Up: memcached

6.165.7 API Summary
-------------------

* Menu:

* Connection management::
* Storage commands::
* Retrieval commands::
* Deletion::
* Increment/Decrement: Increment/Decrement<2>.
* Touch::
* Server commands::


File: TheLogtalkHandbook-3.101.0.info,  Node: Connection management,  Next: Storage commands,  Up: API Summary<2>

6.165.7.1 Connection management
...............................

   - ‘connect(+Host, +Port, -Connection)’ - Connect to server

   - ‘connect(+Host, -Connection)’ - Connect to server on default port

   - ‘disconnect(+Connection)’ - Disconnect from server


File: TheLogtalkHandbook-3.101.0.info,  Node: Storage commands,  Next: Retrieval commands,  Prev: Connection management,  Up: API Summary<2>

6.165.7.2 Storage commands
..........................

   - ‘set(+Connection, +Key, +Value, +Flags, +ExpTime)’ - Store
     unconditionally

   - ‘set(+Connection, +Key, +Value)’ - Store with default flags and no
     expiration

   - ‘add(+Connection, +Key, +Value, +Flags, +ExpTime)’ - Store only if
     new

   - ‘replace(+Connection, +Key, +Value, +Flags, +ExpTime)’ - Store only
     if exists

   - ‘append(+Connection, +Key, +Value)’ - Append to existing value

   - ‘prepend(+Connection, +Key, +Value)’ - Prepend to existing value

   - ‘cas(+Connection, +Key, +Value, +Flags, +ExpTime, +CasUnique)’ -
     Check-and-set


File: TheLogtalkHandbook-3.101.0.info,  Node: Retrieval commands,  Next: Deletion,  Prev: Storage commands,  Up: API Summary<2>

6.165.7.3 Retrieval commands
............................

   - ‘get(+Connection, +Key, -Value)’ - Get value

   - ‘get(+Connection, +Key, -Value, -Flags)’ - Get value and flags

   - ‘gets(+Connection, +Key, -Value, -CasUnique)’ - Get with CAS token

   - ‘gets(+Connection, +Key, -Value, -Flags, -CasUnique)’ - Get with
     flags and CAS

   - ‘mget(+Connection, +Keys, -Items)’ - Multi-get


File: TheLogtalkHandbook-3.101.0.info,  Node: Deletion,  Next: Increment/Decrement<2>,  Prev: Retrieval commands,  Up: API Summary<2>

6.165.7.4 Deletion
..................

   - ‘delete(+Connection, +Key)’ - Delete item


File: TheLogtalkHandbook-3.101.0.info,  Node: Increment/Decrement<2>,  Next: Touch,  Prev: Deletion,  Up: API Summary<2>

6.165.7.5 Increment/Decrement
.............................

   - ‘incr(+Connection, +Key, +Amount, -NewValue)’ - Increment

   - ‘decr(+Connection, +Key, +Amount, -NewValue)’ - Decrement


File: TheLogtalkHandbook-3.101.0.info,  Node: Touch,  Next: Server commands,  Prev: Increment/Decrement<2>,  Up: API Summary<2>

6.165.7.6 Touch
...............

   - ‘touch(+Connection, +Key, +ExpTime)’ - Update expiration

   - ‘gat(+Connection, +Key, +ExpTime, -Value)’ - Get and touch

   - ‘gats(+Connection, +Key, +ExpTime, -Value, -CasUnique)’ -
     Get-and-touch with CAS


File: TheLogtalkHandbook-3.101.0.info,  Node: Server commands,  Prev: Touch,  Up: API Summary<2>

6.165.7.7 Server commands
.........................

   - ‘flush_all(+Connection)’ - Invalidate all items

   - ‘flush_all(+Connection, +Delay)’ - Invalidate all items after delay

   - ‘version(+Connection, -Version)’ - Get server version

   - ‘stats(+Connection, -Stats)’ - Get general statistics

   - ‘stats(+Connection, +Argument, -Stats)’ - Get specific statistics


File: TheLogtalkHandbook-3.101.0.info,  Node: Error Handling<2>,  Next: Key Format,  Prev: API Summary<2>,  Up: memcached

6.165.8 Error Handling
----------------------

Most predicates throw ‘error(memcached_error(Reason), Context)’ on
failure.  Common error reasons:

   - ‘connection_failed’ - Could not establish TCP connection

   - ‘not_stored’ - Storage condition not met (e.g.  ‘add’ on existing
     key)

   - ‘exists’ - CAS conflict (item was modified by another client)

   - ‘not_found’ - CAS on non-existent key

   - ‘server_error(Message)’ - Server returned an error

Retrieval predicates (‘get’, ‘gets’, ‘gat’, ‘gats’) fail (rather than
throw) when the requested key is not found.  The ‘delete’, ‘incr’,
‘decr’, and ‘touch’ predicates also fail when the key is not found.


File: TheLogtalkHandbook-3.101.0.info,  Node: Key Format,  Next: Expiration Times,  Prev: Error Handling<2>,  Up: memcached

6.165.9 Key Format
------------------

   - Keys are atoms up to 250 characters

   - Keys must not contain control characters or whitespace

   - Keys are case-sensitive


File: TheLogtalkHandbook-3.101.0.info,  Node: Expiration Times,  Prev: Key Format,  Up: memcached

6.165.10 Expiration Times
-------------------------

   - ‘0’ means the item never expires (may still be evicted by LRU)

   - Values up to 2592000 (30 days) are treated as relative seconds

   - Values over 2592000 are treated as absolute Unix timestamps

   - Negative values cause immediate expiration


File: TheLogtalkHandbook-3.101.0.info,  Node: message_pack,  Next: meta,  Prev: memcached,  Up: Libraries

6.166 ‘message_pack’
====================

The ‘message_pack’ library provides predicates for parsing and
generating data in the MessagePack(1) format based on the current
specification and reference documents found at:

   - ‘https://github.com/msgpack/msgpack/blob/master/spec.md’

   - ‘https://github.com/msgpack/msgpack/blob/master/spec-old.md’

It follows the representation conventions used by the existing binary
and JSON libraries whenever practical.

* Menu:

* API documentation: API documentation<184>.
* Loading: Loading<186>.
* Testing: Testing<177>.
* Representation: Representation<17>.
* Notes: Notes<9>.

   ---------- Footnotes ----------

   (1) https://msgpack.org/


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<184>,  Next: Loading<186>,  Up: message_pack

6.166.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#message_pack’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<186>,  Next: Testing<177>,  Prev: API documentation<184>,  Up: message_pack

6.166.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(message_pack(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<177>,  Next: Representation<17>,  Prev: Loading<186>,  Up: message_pack

6.166.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(message_pack(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Representation<17>,  Next: Notes<9>,  Prev: Testing<177>,  Up: message_pack

6.166.4 Representation
----------------------

The following choices of syntax have been made to represent MessagePack
elements as terms:

   - Maps are represented using curly-bracketed terms, ‘{Pairs}’, where
     each pair uses the representation ‘Key-Value’.

   - Arrays are represented using lists.

   - Strings can be represented as atoms, ‘chars(List)’, or
     ‘codes(List)’.  Use the ‘message_pack/1’ parameterized object with
     the parameter bound to ‘atom’, ‘chars’, or ‘codes’ to select the
     representation used when decoding strings.

   - MessagePack strings are validated using strict UTF-8 decoding and
     encoding.  Invalid UTF-8 byte sequences and invalid Unicode scalar
     values are rejected.

   - Binary data is represented by ‘bytes(List)’.

   - Extension values are represented by ‘ext(Type, bytes(Bytes))’,
     where ‘Type’ is the signed 8-bit extension type and ‘Bytes’ is the
     extension payload.

   - The MessagePack values ‘false’, ‘true’, and ‘nil’ are represented
     by, respectively, the ‘@false’, ‘@true’, and ‘@null’ compound
     terms.

   - IEEE 754 infinities and NaN values are represented by the
     ‘@infinity’, ‘@negative_infinity’, and ‘@not_a_number’ compound
     terms.

   - Only some backends distinguish between positive zero and negative
     zero.  The decoder produces the ‘0.0’ and ‘-0.0’ floats, but
     backends that normalize both values to ‘0.0’ cannot preserve the
     sign of zero when re-encoding.

The following table exemplifies the term equivalents of common
MessagePack elements when using ‘message_pack(atom)’:

MessagePack value     term
                      
--------------------------------------------------
nil                   @null
                      
false                 @false
                      
true                  @true
                      
“foo”                 foo
                      
[1,2,3]               [1,2,3]
                      
{“a”:1,”b”:true}      {a-1, <b-@true>}
                      
bin payload           bytes([…])
                      
extension payload     ext(Type, bytes([…]))
                      


File: TheLogtalkHandbook-3.101.0.info,  Node: Notes<9>,  Prev: Representation<17>,  Up: message_pack

6.166.5 Notes
-------------

   - Generated integers always use the smallest valid MessagePack
     integer format.

   - Generated floating point values use the single-precision format
     when it can exactly represent the input value; otherwise, the
     double-precision format is used.

   - Recommended string representation choice depends on the trust
     boundary of the input.  For trusted input, ‘message_pack(atom)’ is
     usually the most convenient choice when the rest of the application
     already works with atoms.  For untrusted input, prefer
     ‘message_pack(codes)’ or ‘message_pack(chars)’ to avoid interning
     arbitrary incoming strings as atoms.

   - For untrusted input, ‘message_pack(codes)’ is generally the best
     default choice.  It avoids atom creation while preserving the exact
     decoded Unicode code points.  ‘message_pack(chars)’ provides the
     same safety with a more readable but less compact representation.

   - The predefined timestamp extension is currently exposed using the
     generic ‘ext(-1, bytes(Bytes))’ representation.

   - The library requires a backend Prolog compiler with unbounded
     integer support, matching the requirements of the existing ‘cbor’,
     ‘avro’, and ‘protobuf’ libraries.


File: TheLogtalkHandbook-3.101.0.info,  Node: meta,  Next: meta_compiler,  Prev: message_pack,  Up: Libraries

6.167 ‘meta’
============

This library provides implementations of common meta-predicates.  The
‘meta’ object implements common meta-predicates like ‘map/3’ and
‘fold_left/4’.

See also the ‘meta_compiler’ library, which provides optimized
compilation of meta-predicate calls.

* Menu:

* API documentation: API documentation<185>.
* Loading: Loading<187>.
* Testing: Testing<178>.
* Usage: Usage<72>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<185>,  Next: Loading<187>,  Up: meta

6.167.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#meta’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<187>,  Next: Testing<178>,  Prev: API documentation<185>,  Up: meta

6.167.2 Loading
---------------

To load the main entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(meta(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<178>,  Next: Usage<72>,  Prev: Loading<187>,  Up: meta

6.167.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(meta(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<72>,  Prev: Testing<178>,  Up: meta

6.167.4 Usage
-------------

See e.g.  the ‘metapredicates’ example and unit tests.


File: TheLogtalkHandbook-3.101.0.info,  Node: meta_compiler,  Next: mime_types,  Prev: meta,  Up: Libraries

6.168 ‘meta_compiler’
=====================

This library supports implementations optimized compilation of
meta-calls for the predicates defined in the ‘meta’ library.

* Menu:

* API documentation: API documentation<186>.
* Loading: Loading<188>.
* Testing: Testing<179>.
* Usage: Usage<73>.
* Known issues: Known issues<15>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<186>,  Next: Loading<188>,  Up: meta_compiler

6.168.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#meta-compiler’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<188>,  Next: Testing<179>,  Prev: API documentation<186>,  Up: meta_compiler

6.168.2 Loading
---------------

To load the main entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(meta_compiler(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<179>,  Next: Usage<73>,  Prev: Loading<188>,  Up: meta_compiler

6.168.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(meta_compiler(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<73>,  Next: Known issues<15>,  Prev: Testing<179>,  Up: meta_compiler

6.168.4 Usage
-------------

If ‘meta_compiler’ is the only hook object you are using, you can set it
as the default hook object (but note that the optimizations are only
applied to entities compiled with the ‘optimize’ flag turned on):

     | ?- set_logtalk_flag(hook, meta_compiler).
     ...

Otherwise, use the ‘hook(meta_compiler)’ and ‘optimize(on)’ compiler
options when compiling and loading the code that you want to optimize.
For example:

     | ?- logtalk_load(my_source_file, [hook(meta_compiler), optimize(on)]).
     ...

See also the ‘metapredicates_compiled’ example and unit tests.


File: TheLogtalkHandbook-3.101.0.info,  Node: Known issues<15>,  Prev: Usage<73>,  Up: meta_compiler

6.168.5 Known issues
--------------------

Goals in clauses containing parameter variables are currently not
expanded by this library and thus not optimized.


File: TheLogtalkHandbook-3.101.0.info,  Node: mime_types,  Next: modified_z_score_anomaly_detector,  Prev: meta_compiler,  Up: Libraries

6.169 ‘mime_types’
==================

The ‘mime_types’ library provides convenience predicates for mapping
file extensions, file names, and URL-like resources to MIME media types
and content encodings.

The current implementation ships with a built-in registry containing a
practical set of common standard mappings plus a smaller set of de-facto
common mappings.  Additional mappings can be loaded at runtime from
‘mime.types’-style files.

Lookup is lenient by default.  The convenience predicates also accept a
boolean ‘Strict’ argument to restrict lookup to strict runtime overlays
plus the built-in standard registry.

The library uses the ‘os’ library ‘decompose_file_name/4’ predicate to
split paths, and recognizes common compound suffixes such as ‘.tgz’ and
‘.svgz’.

* Menu:

* API documentation: API documentation<187>.
* Loading: Loading<189>.
* Testing: Testing<180>.
* Usage: Usage<74>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<187>,  Next: Loading<189>,  Up: mime_types

6.169.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#mime_types’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<189>,  Next: Testing<180>,  Prev: API documentation<187>,  Up: mime_types

6.169.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(mime_types(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<180>,  Next: Usage<74>,  Prev: Loading<189>,  Up: mime_types

6.169.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(mime_types(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<74>,  Prev: Testing<180>,  Up: mime_types

6.169.4 Usage
-------------

Guess the MIME type and content encoding for a file name:

     | ?- mime_types::guess_file_type('archive.tgz', Type, Encoding).
     Type = 'application/x-tar',
     Encoding = gzip
     yes

Lookup a preferred extension for a MIME type:

     | ?- mime_types::guess_extension('application/json', Extension).
     Extension = '.json'
     yes

Read a ‘mime.types’-style file without mutating the runtime registry:

     | ?- mime_types::read_mime_types('mime.types', Pairs).

Load additional runtime mappings from a ‘mime.types’-style file:

     | ?- mime_types::load('mime.types').


File: TheLogtalkHandbook-3.101.0.info,  Node: modified_z_score_anomaly_detector,  Next: mutations,  Prev: mime_types,  Up: Libraries

6.170 ‘modified_z_score_anomaly_detector’
=========================================

Statistical modified Z-score anomaly detector for continuous datasets.
It is a statistical anomaly-detection method based on the modified
Z-score defined by Iglewicz and Hoaglin (1993): for each known
continuous attribute value ‘x’, the detector computes ‘0.6745 * (x -
median) / mad’, where ‘median’ is the learned sample median and ‘mad’ is
the learned median absolute deviation, and then aggregates the
per-attribute modified Z-scores using the selected learn-time
‘score_mode/1’ option.

The library implements the ‘anomaly_detector_protocol’ defined in the
‘anomaly_detection_protocols’ library.  It learns a detector from a
continuous dataset, computes anomaly scores for new instances, predicts
‘normal’ or ‘anomaly’, and exports learned detectors as clauses or
files.

Datasets are represented as objects implementing the
‘anomaly_dataset_protocol’ protocol from the
‘anomaly_detection_protocols’ library.  See the
‘anomaly_detection_protocols/test_datasets’ directory for examples.

* Menu:

* API documentation: API documentation<188>.
* Loading: Loading<190>.
* Testing: Testing<181>.
* Features: Features<52>.
* Options: Options<51>.
* Detector representation: Detector representation<7>.
* Notes: Notes<10>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<188>,  Next: Loading<190>,  Up: modified_z_score_anomaly_detector

6.170.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#modified-z-score’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<190>,  Next: Testing<181>,  Prev: API documentation<188>,  Up: modified_z_score_anomaly_detector

6.170.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(modified_z_score_anomaly_detector(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<181>,  Next: Features<52>,  Prev: Loading<190>,  Up: modified_z_score_anomaly_detector

6.170.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(modified_z_score_anomaly_detector(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<52>,  Next: Options<51>,  Prev: Testing<181>,  Up: modified_z_score_anomaly_detector

6.170.4 Features
----------------

   - 'Statistical method': implements robust anomaly detection based on
     the modified Z-score described by Iglewicz and Hoaglin (1993),
     using the sample median and median absolute deviation of each
     continuous attribute to measure how far new observations deviate
     from the training data distribution.

   - 'Classical per-attribute modified Z-score': for each known
     attribute value ‘x’, the library computes the standard robust score
     ‘0.6745 * (x - median) / mad’, where ‘median’ is the learned sample
     median for that attribute and ‘mad’ is the learned median absolute
     deviation.

   - 'Continuous features only': accepts datasets whose declared
     attributes are all ‘continuous’.

   - 'Robust statistics': reuses the ‘statistics’ library ‘sample’
     object to compute per-attribute medians and the median of absolute
     deviations.

   - 'Baseline training selection': supports learn-time
     ‘baseline_class_values(ClassValues)’ and
     ‘baseline_selection_policy(Policy)’ options.  The default baseline
     class values are ‘[normal]’.  The default ‘reject’ policy throws an
     error if non-baseline examples are present, while ‘filter’ removes
     them before fitting.

   - 'Missing-value tolerant': ignores missing values when fitting
     attribute statistics.  During scoring, queries must provide at
     least one known value.  In the default
     ‘score_mode(root_mean_square)’, the raw score is normalized by the
     number of known values so that scores remain comparable across
     different missing-value patterns.

   - 'Configurable scoring semantics': supports both dense multivariate
     deviation scoring using ‘score_mode(root_mean_square)’ and sparse
     anomaly detection using ‘score_mode(any_feature_extreme)’.  The
     default root-mean-square mode reuses the ‘numberlist’ library
     Euclidean norm predicate as part of the computation.  The
     ‘score_mode/1’ option only controls how the per-attribute modified
     Z-scores are aggregated into a single raw anomaly score.

   - 'Bounded scoring': maps the raw multivariate modified Z-score to
     ‘[0.0, 1.0)’ using ‘Score = Raw / (1 + Raw)’.

   - 'Default threshold': the default
     ‘anomaly_threshold(0.7777777777777778)’ corresponds to the
     classical raw modified Z-score cutoff ‘3.5’ recommended by Iglewicz
     and Hoaglin (1993), while remaining overrideable in ‘learn/3’ and
     ‘predict/4’.

   - 'Learn-time score mode': ‘score_mode/1’ is recorded in the learned
     detector and reused for subsequent scoring and prediction.  Passing
     a ‘score_mode/1’ option to ‘predict/4’ does not override the
     learned mode.

   - 'All-missing queries rejected': scoring and prediction throw a
     ‘domain_error(non_empty_known_values, AttributeNames)’ exception
     when every declared feature is missing in the query.

   - 'Featureless datasets rejected': datasets must declare at least one
     continuous feature; otherwise ‘learn/2-3’ throws a
     ‘domain_error(non_empty_features, Dataset)’ exception.

   - 'Detector export': learned detectors can be exported as predicate
     clauses.

   - 'Explicit validation and diagnostics': supports the shared
     ‘check_anomaly_detector/1’, ‘valid_anomaly_detector/1’,
     ‘diagnostics/2’, ‘diagnostic/2’, and ‘anomaly_detector_options/2’
     predicates.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<51>,  Next: Detector representation<7>,  Prev: Features<52>,  Up: modified_z_score_anomaly_detector

6.170.5 Options
---------------

The following options are supported by the public API:

   - ‘anomaly_threshold(Threshold)’: Threshold for ‘predict/3-4’
     (default: ‘0.7777777777777778’)

   - ‘baseline_class_values(ClassValues)’: Learn-time class labels that
     are admissible for baseline fitting (default: ‘[normal]’)

   - ‘baseline_selection_policy(Policy)’: Learn-time handling of
     examples whose class is not listed in ‘baseline_class_values/1’.
     Supported values are ‘filter’ and ‘reject’ (default: ‘reject’)

   - ‘score_mode(Mode)’: Learn-time score aggregation mode for
     ‘learn/3’.  Supported values are ‘root_mean_square’ and
     ‘any_feature_extreme’ (default: ‘root_mean_square’).  If passed to
     ‘predict/4’, it is ignored and the value stored in the learned
     detector is used.


File: TheLogtalkHandbook-3.101.0.info,  Node: Detector representation<7>,  Next: Notes<10>,  Prev: Options<51>,  Up: modified_z_score_anomaly_detector

6.170.6 Detector representation
-------------------------------

The learned detector is represented by default as:

     modified_z_score_detector(TrainingDataset, Encoders, Diagnostics)

Where:

   - ‘TrainingDataset’: training dataset object identifier

   - ‘Encoders’: list of ‘modified_zscore(Attribute, Median, Scale)’
     records

   - ‘Diagnostics’: learned metadata terms including ‘model/1’,
     ‘training_dataset/1’, ‘attribute_names/1’, ‘feature_count/1’,
     ‘example_count/1’, and ‘options/1’

When exported using ‘export_to_clauses/4’ or ‘export_to_file/4’, this
detector term is serialized directly as the single argument of the
generated predicate clause so that the exported model can be loaded and
reused as-is.


File: TheLogtalkHandbook-3.101.0.info,  Node: Notes<10>,  Prev: Detector representation<7>,  Up: modified_z_score_anomaly_detector

6.170.7 Notes
-------------

Scoring has three stages.  First, the detector computes one classical
per-attribute modified Z-score for each known attribute value using
‘0.6745 * (x - median) / mad’.  Second, those per-attribute modified
Z-scores are aggregated into a single raw anomaly score according to the
learned ‘score_mode/1’ option.  Third, the raw score is mapped to the
interval ‘[0.0, 1.0)’ using ‘Score = Raw / (1 + Raw)’.

The ‘score_mode/1’ option does not change the classical per-attribute
formula.  It only changes the aggregation step.  With
‘score_mode(root_mean_square)’, the raw score is the root mean square of
the per-attribute modified Z-scores.  With
‘score_mode(any_feature_extreme)’, the raw score is the maximum absolute
per-attribute modified Z-score.

The ‘baseline_class_values/1’ option declares which dataset class labels
are admissible for fitting the baseline medians and median absolute
deviations.  The ‘baseline_selection_policy/1’ option then controls what
happens when other labels are present in the training data.  The default
‘reject’ policy raises a ‘domain_error(baseline_only_training_data,
Dataset)’ exception when any non-baseline example is found.  The
‘filter’ policy removes non-baseline examples before fitting.

Attributes with zero observed median absolute deviation are assigned a
fallback scale of ‘1.0’.  This keeps the detector well-defined for
singleton datasets or constant columns while still yielding zero score
for matching values and positive scores for deviating values.

The root-mean-square aggregation keeps the default threshold stable as
the number of observed dimensions grows and avoids penalizing partially
observed queries solely for having fewer known attributes.

Use ‘score_mode(any_feature_extreme)’ when a single extreme feature
should be sufficient to flag an anomaly in high-dimensional data.


File: TheLogtalkHandbook-3.101.0.info,  Node: mutations,  Next: multisets,  Prev: modified_z_score_anomaly_detector,  Up: Libraries

6.171 ‘mutations’
=================

Experimental library.  Should not be used in production code.  Details
can be changed without advance notice.

The ‘mutations’ library provides support for generating random mutations
of selected types.  The library defines default mutation algorithms for
the following basic types:

   - ‘atom’

   - ‘integer’

   - ‘float’

   - ‘compound’

   - ‘list’

The user can add additional mutation algorithms for these or other types
by defining objects or categories providing clauses for the ‘mutation/3’
predicate and expanding the entity source files using the
‘mutations_store’ object as the hook object.

This library is expected to eventually be used to support mutation-based
'fuzz testing'.

By default, loading this library loads a set of default mutation
algorithms.  These can be overridden by defining alternative mutations
and a custom loader file.

* Menu:

* API documentation: API documentation<189>.
* Loading: Loading<191>.
* Testing: Testing<182>.
* Usage: Usage<75>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<189>,  Next: Loading<191>,  Up: mutations

6.171.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#mutations’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<191>,  Next: Testing<182>,  Prev: API documentation<189>,  Up: mutations

6.171.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(mutations(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<182>,  Next: Usage<75>,  Prev: Loading<191>,  Up: mutations

6.171.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(mutations(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<75>,  Prev: Testing<182>,  Up: mutations

6.171.4 Usage
-------------

The ‘mutations’ category complements the ‘type’ object and thus its
predicates are accessed via this object.  For example:

     | ?- type::mutation(integer, 123, M).
     M = 1293
     yes

     | type::mutation(integer, 123, M).
     M = 5123
     yes

     | type::mutation(integer, 123, M).
     M = -123
     yes

     | type::mutation(integer, 123, M).
     M = 23
     yes

When there are multiple mutation algorithms for a given type, the
predicate ‘type::mutation/3’ chooses one of them randomly.  We can query
the number of mutation algorithms available per type using the
‘mutations_store::counter/2’ predicate:

     | ?- mutations_store::counter(Type, Count).
     Type = atom,
     Count = 6 ;
     Type = integer,
     Count = 7 ;
     ...

Loading this library also loads the ‘arbitrary’ library, which provides
‘get_seed/1’ and ‘set_seed/1’ predicates that can be used to control the
pseudo-random number generator.


File: TheLogtalkHandbook-3.101.0.info,  Node: multisets,  Next: nanoid,  Prev: mutations,  Up: Libraries

6.172 ‘multisets’
=================

This library provides predicates for generating and querying multisets
over lists.  Multisets are unordered selections of a given length with
element repetition allowed.  The following categories of predicates are
provided:

   - 'Generation operations' - Predicates for generating multisets.

   - 'Ordering variants' - Predicates that support an additional order
     argument (‘default’ or ‘lexicographic’) for controlling output
     order.

   - 'Distinct-value generation' - Predicates for generating multisets
     while deduplicating equal-valued results.

   - 'Indexed access' - Predicates for direct access to multisets at
     specific positions, including order-aware access.

   - 'Counting operations' - Predicates for counting multisets and
     distinct multisets.

   - 'Random selection' - Predicates for randomly selecting and sampling
     multisets and distinct multisets.

   - 'Lexicographic stepping' - Predicates for stepping to the next or
     previous multiset in lexicographic order.

Dedicated ‘arrangements’, ‘cartesian_products’, ‘combinations’,
‘permutations’, ‘derangements’, ‘partitions’, and ‘subsequences’
libraries are also available for focused APIs on related operations.

* Menu:

* API documentation: API documentation<190>.
* Loading: Loading<192>.
* Testing: Testing<183>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<190>,  Next: Loading<192>,  Up: multisets

6.172.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#multisets’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<192>,  Next: Testing<183>,  Prev: API documentation<190>,  Up: multisets

6.172.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(multisets(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<183>,  Prev: Loading<192>,  Up: multisets

6.172.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(multisets(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: nanoid,  Next: naive_bayes_classifier,  Prev: multisets,  Up: Libraries

6.173 ‘nanoid’
==============

This library generates random NanoID identifiers:

‘https://github.com/ai/nanoid’

By default, identifiers are represented as atoms with 21 symbols and use
the standard URL-safe alphabet:

     _-0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ

Custom size, alphabet, and representation (atoms, lists of characters,
or lists of character codes) are supported using a parametric object.

The generation of random identifiers uses the ‘/dev/urandom’ random
number generator when available.  This includes macOS, Linux, *BSD, and
other POSIX operating systems.  On Windows, a pseudo-random generator is
used, randomized using the current wall time.

See also the ‘ids’, ‘uuid’, and ‘ulid’ libraries.

* Menu:

* API documentation: API documentation<191>.
* Loading: Loading<193>.
* Testing: Testing<184>.
* Usage: Usage<76>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<191>,  Next: Loading<193>,  Up: nanoid

6.173.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#nanoid’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<193>,  Next: Testing<184>,  Prev: API documentation<191>,  Up: nanoid

6.173.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(nanoid(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<184>,  Next: Usage<76>,  Prev: Loading<193>,  Up: nanoid

6.173.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(nanoid(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<76>,  Prev: Testing<184>,  Up: nanoid

6.173.4 Usage
-------------

To generate an identifier using the default configuration:

     | ?- nanoid::generate(NanoID).
     NanoID = 'V1StGXR8_Z5jdHi6B-myT'
     yes

To generate a 10-symbol identifier represented as a list of characters:

     | ?- nanoid(chars, 10, 'abcdef012345')::generate(NanoID).
     NanoID = ['4','b','d','f','a','0','3','2','1','e']
     yes

To generate a 32-symbol identifier represented as a list of character
codes:

     | ?- nanoid(codes, 32, [0'a,0'b,0'c,0'd,0'e,0'f,0'0,0'1,0'2,0'3])::generate(NanoID).
     NanoID = [49,97,99,100,48,102,98,101,50,51,48,101,99,102,49,50,98,100,49,97,48,51,101,98,100,99,49,102,48,97,50,100]
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: naive_bayes_classifier,  Next: nearest_centroid_classifier,  Prev: nanoid,  Up: Libraries

6.174 ‘naive_bayes_classifier’
==============================

Naive Bayes probabilistic classifier based on Bayes theorem with strong
(naive) independence assumptions between features and supporting both
categorical and continuous (Gaussian) features with Laplace smoothing.

The library implements the ‘classifier_protocol’ defined in the
‘classification_protocols’ library.  It provides predicates for learning
a classifier from a dataset, using it to make predications, and
exporting it as a list of predicate clauses or to a file.

Datasets are represented as objects implementing the ‘dataset_protocol’
protocol from the ‘classification_protocols’ library.  See ‘test_files’
directory for examples.

* Menu:

* API documentation: API documentation<192>.
* Loading: Loading<194>.
* Testing: Testing<185>.
* Features: Features<53>.
* Usage: Usage<77>.
* Classifier representation: Classifier representation<8>.
* References: References<37>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<192>,  Next: Loading<194>,  Up: naive_bayes_classifier

6.174.1 API documentation
-------------------------

Open the ‘../../docs/library_index.html#naive_bayes_classifier’ link in
a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<194>,  Next: Testing<185>,  Prev: API documentation<192>,  Up: naive_bayes_classifier

6.174.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(naive_bayes_classifier(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<185>,  Next: Features<53>,  Prev: Loading<194>,  Up: naive_bayes_classifier

6.174.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(naive_bayes_classifier(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<53>,  Next: Usage<77>,  Prev: Testing<185>,  Up: naive_bayes_classifier

6.174.4 Features
----------------

   - 'Categorical Features': Handles discrete-valued features with
     Laplace smoothing

   - 'Continuous Features': Uses Gaussian (normal) distribution for
     numeric features

   - 'Classifier Export': Learned classifiers can be exported as
     predicate clauses

   - 'Probability Estimation': Provides both class predictions and
     probability distributions


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<77>,  Next: Classifier representation<8>,  Prev: Features<53>,  Up: naive_bayes_classifier

6.174.5 Usage
-------------

* Menu:

* Learning a Classifier: Learning a Classifier<3>.
* Making Predictions: Making Predictions<3>.
* Exporting the Classifier: Exporting the Classifier<3>.
* Using a learned classifier: Using a learned classifier<2>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Learning a Classifier<3>,  Next: Making Predictions<3>,  Up: Usage<77>

6.174.5.1 Learning a Classifier
...............................

     % Learn from a dataset object
     | ?- naive_bayes_classifier::learn(my_dataset, Classifier).
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Making Predictions<3>,  Next: Exporting the Classifier<3>,  Prev: Learning a Classifier<3>,  Up: Usage<77>

6.174.5.2 Making Predictions
............................

     % Predict class for a new instance and the probability distribution
     | ?- Instance = [...],
          naive_bayes_classifier::learn(my_dataset, Classifier),
          naive_bayes_classifier::predict(Classifier, Instance, PredictedClass),
          naive_bayes_classifier::predict_probability(Classifier, Instance, Probabilities).
     PredictedClass = ...,
     Probabilities = [...]
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Exporting the Classifier<3>,  Next: Using a learned classifier<2>,  Prev: Making Predictions<3>,  Up: Usage<77>

6.174.5.3 Exporting the Classifier
..................................

Learned classifiers can be exported as a list of clauses or to a file
for later use.

     % Export as predicate clauses
     | ?- naive_bayes_classifier::learn(my_dataset, Classifier),
          naive_bayes_classifier::export_to_clauses(Classifier, my_classifier, Clauses).
     Clauses = [my_classifier(...)]
     ...

     % Export to a file
     | ?- naive_bayes_classifier::learn(my_dataset, Classifier),
          naive_bayes_classifier::export_to_file(Classifier, my_classifier, 'classifier.pl').
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Using a learned classifier<2>,  Prev: Exporting the Classifier<3>,  Up: Usage<77>

6.174.5.4 Using a learned classifier
....................................

Learned and saved classifiers can later be used for predictions without
needing to access the original training dataset.

     % Later, load the file and use the classifier
     | ?- consult('classifier.pl'),
          my_classifier(Classifier),
          Instance = [...],
          naive_bayes_classifier::predict(Classifier, Instance, Class).
     Class = ...
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Classifier representation<8>,  Next: References<37>,  Prev: Usage<77>,  Up: naive_bayes_classifier

6.174.6 Classifier representation
---------------------------------

The learned classifier is represented as a compound term:

     nb_classifier(Classes, ClassPriors, AttributeNames, FeatureTypes, FeatureParams)

Where:

   - ‘Classes’: List of class labels

   - ‘ClassPriors’: List of ‘Class-Prior’ probability pairs

   - ‘AttributeNames’: List of attribute names in order

   - ‘FeatureTypes’: List of types (‘categorical’ or ‘continuous’)

   - ‘FeatureParams’: List of learned parameters for each feature

When exported using ‘export_to_clauses/4’ or ‘export_to_file/4’, this
classifier term is serialized directly as the single argument of the
generated predicate clause so that the exported model can be loaded and
reused as-is.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<37>,  Prev: Classifier representation<8>,  Up: naive_bayes_classifier

6.174.7 References
------------------

  1. Rish, I. (2001).  “An empirical study of the naive Bayes
     classifier”.

  2. Russell, S. & Norvig, P. (2020).  “Artificial Intelligence: A
     Modern Approach”.

  3. Mitchell, T. (1997).  “Machine Learning”.  Chapter 6: Bayesian
     Learning.


File: TheLogtalkHandbook-3.101.0.info,  Node: nearest_centroid_classifier,  Next: nested_dictionaries,  Prev: naive_bayes_classifier,  Up: Libraries

6.175 ‘nearest_centroid_classifier’
===================================

Nearest Centroid classifier.  Assigns to an instance the class of the
training samples whose mean (centroid) is closest to the instance.

The library implements the ‘classifier_protocol’ defined in the
‘classification_protocols’ library.  It provides predicates for learning
a classifier from a dataset, using it to make predictions, and exporting
it as a list of predicate clauses or to a file.

Datasets are represented as objects implementing the ‘dataset_protocol’
protocol from the ‘classification_protocols’ library.  See ‘test_files’
directory for examples.

* Menu:

* API documentation: API documentation<193>.
* Loading: Loading<195>.
* Testing: Testing<186>.
* Features: Features<54>.
* Usage: Usage<78>.
* Options: Options<52>.
* Classifier representation: Classifier representation<9>.
* References: References<38>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<193>,  Next: Loading<195>,  Up: nearest_centroid_classifier

6.175.1 API documentation
-------------------------

Open the ‘../../docs/library_index.html#nearest_centroid_classifier’
link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<195>,  Next: Testing<186>,  Prev: API documentation<193>,  Up: nearest_centroid_classifier

6.175.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(nearest_centroid_classifier(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<186>,  Next: Features<54>,  Prev: Loading<195>,  Up: nearest_centroid_classifier

6.175.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(nearest_centroid_classifier(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<54>,  Next: Usage<78>,  Prev: Testing<186>,  Up: nearest_centroid_classifier

6.175.4 Features
----------------

   - 'Multiple Distance Metrics': Euclidean, Manhattan, cosine

   - 'Mixed Features': Automatically handles categorical and continuous
     features

   - 'Configurable Option': distance metric via predicate options

   - 'Probability Estimation': Provides confidence scores for
     predictions

   - 'Classifier Export': Learned classifiers can be exported as
     predicate clauses


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<78>,  Next: Options<52>,  Prev: Features<54>,  Up: nearest_centroid_classifier

6.175.5 Usage
-------------

* Menu:

* Learning a Classifier: Learning a Classifier<4>.
* Making Predictions: Making Predictions<4>.
* Exporting the Classifier: Exporting the Classifier<4>.
* Using a learned classifier: Using a learned classifier<3>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Learning a Classifier<4>,  Next: Making Predictions<4>,  Up: Usage<78>

6.175.5.1 Learning a Classifier
...............................

     % Learn from a dataset object with default options (euclidean distance)
     | ?- nearest_centroid_classifier::learn(my_dataset, Classifier).
     ...

     % Learn with custom options
     | ?- nearest_centroid_classifier::learn(my_dataset, Classifier, [distance_metric(manhattan)]).
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Making Predictions<4>,  Next: Exporting the Classifier<4>,  Prev: Learning a Classifier<4>,  Up: Usage<78>

6.175.5.2 Making Predictions
............................

     % Predict class for a new instance
     | ?- Instance = [attr1-value1, attr2-value2, ...],
          nearest_centroid_classifier::learn(my_dataset, Classifier),
          nearest_centroid_classifier::predict(Classifier, Instance, PredictedClass).
     PredictedClass = ...
     ...

     % Predict with custom options
     | ?- nearest_centroid_classifier::predict(Classifier, Instance, PredictedClass, [distance_metric(cosine)]).
     ...

     % Get probability distribution
     | ?- nearest_centroid_classifier::predict_probabilities(Classifier, Instance, Probabilities).
     Probabilities = [class1-0.67, class2-0.33]
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Exporting the Classifier<4>,  Next: Using a learned classifier<3>,  Prev: Making Predictions<4>,  Up: Usage<78>

6.175.5.3 Exporting the Classifier
..................................

Learned classifiers can be exported as a list of clauses or to a file
for later use.

     % Export as predicate clauses
     | ?- nearest_centroid_classifier::learn(my_dataset, Classifier),
          nearest_centroid_classifier::export_to_clauses(my_dataset, Classifier, my_classifier, Clauses).
     Clauses = [my_classifier(...)]
     ...

     % Export to a file
     | ?- nearest_centroid_classifier::learn(my_dataset, Classifier),
          nearest_centroid_classifier::export_to_file(my_dataset, Classifier, my_classifier, 'classifier.pl').
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Using a learned classifier<3>,  Prev: Exporting the Classifier<4>,  Up: Usage<78>

6.175.5.4 Using a learned classifier
....................................

Learned and saved classifiers can later be used for predictions without
needing to access the original training dataset.

     % Later, load the file and use the classifier
     | ?- consult('classifier.pl'),
          my_classifier(AttributeNames, FeatureTypes, Centroids),
          Instance = [...],
          nearest_centroid_classifier::predict(my_classifier(AttributeNames, FeatureTypes, Centroids), Instance, Class).
     Class = ...
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<52>,  Next: Classifier representation<9>,  Prev: Usage<78>,  Up: nearest_centroid_classifier

6.175.6 Options
---------------

The following options can be passed to the ‘predict/4’ and
‘predict_probabilities/4’ predicates:

   - ‘distance_metric(Metric)’: Distance metric to use.  Options:
     ‘euclidean’ (default), ‘manhattan’, ‘cosine’


File: TheLogtalkHandbook-3.101.0.info,  Node: Classifier representation<9>,  Next: References<38>,  Prev: Options<52>,  Up: nearest_centroid_classifier

6.175.7 Classifier representation
---------------------------------

The learned classifier is represented as a compound term:

     nc_classifier(AttributeNames, FeatureTypes, Centroids)

Where:

   - ‘AttributeNames’: List of attribute names in order

   - ‘FeatureTypes’: List of types (‘numeric’ or ‘categorical’)

   - ‘Centroids’: List of computed ‘Class-Centroid’ pairs

When exported using ‘export_to_clauses/4’ or ‘export_to_file/4’, this
classifier term is serialized directly as the single argument of the
generated predicate clause so that the exported model can be loaded and
reused as-is.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<38>,  Prev: Classifier representation<9>,  Up: nearest_centroid_classifier

6.175.8 References
------------------

  1. Manning, Raghavan & Schütze (2008) - “Introduction to Information
     Retrieval”.  Cambridge University Press.

  2. Tibshirani, Hastie, Narasimhan & Chu (2002) - “Diagnosis of
     multiple cancer types by shrunken centroids of gene expression”.
     Proceedings of the National Academy of Sciences, 99(10), 6567-6572.

  3. Hastie, Tibshirani & Friedman (2009) - “The Elements of Statistical
     Learning: Data Mining, Inference, and Prediction” (2nd Edition).
     Springer.


File: TheLogtalkHandbook-3.101.0.info,  Node: nested_dictionaries,  Next: nmea,  Prev: nearest_centroid_classifier,  Up: Libraries

6.176 ‘nested_dictionaries’
===========================

This library provides nested dictionary implementations based on private
extensions to the ‘dictionaries’ library objects.  The representations
of a nested dictionary should be regarded as opaque terms and only
accessed using the library predicates.

This library is experimental, a work in progress, and future versions
can introduce incompatible changes.

* Menu:

* API documentation: API documentation<194>.
* Loading: Loading<196>.
* Testing: Testing<187>.
* Usage: Usage<79>.
* Curly term representation::


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<194>,  Next: Loading<196>,  Up: nested_dictionaries

6.176.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#nested-dictionaries’ link in a
web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<196>,  Next: Testing<187>,  Prev: API documentation<194>,  Up: nested_dictionaries

6.176.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(nested_dictionaries(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<187>,  Next: Usage<79>,  Prev: Loading<196>,  Up: nested_dictionaries

6.176.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(nested_dictionaries(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<79>,  Next: Curly term representation,  Prev: Testing<187>,  Up: nested_dictionaries

6.176.4 Usage
-------------

First, select the nested dictionary implementation that you want to use.
For cases where the number of elements is relatively small and
performance is not critical, ‘nbintree’ can be a good choice.  For other
cases, ‘navltree’ or ‘nrbtree’ are likely better choices.  If you want
to compare the performance of the implementations, either define an
object alias or use a ‘uses/2’ directive so that you can switch between
implementations by simply changing the alias definition or the first
argument of the directive.  Note that you can switch between
implementations at runtime without code changes by using a parameter
variable in the first argument of a ‘uses/2’ directive.

To create an empty nested dictionary, you can use the ‘new/1’ predicate.
For example:

     | ?- navltree::new(Dictionary).
     Dictionary = ...
     yes

You can also create a new nested dictionary from a 'curly bracketed term
representation' (see below) by using the predicate
‘as_nested_dictionary/2’.  For example:

     | ?- navltree::as_nested_dictionary(
             {a-1, b-{c-3, d-{e-7,f-8}}},
             Dictionary
          ).

     Dictionary = ...
     yes

Several predicates are provided to insert, lookup, update, and delete
key-value pairs given a list of keys interpreted as an 'access path' to
a nested dictionary.  For example:

     | ?- navltree::as_nested_dictionary(
             {a-1, b-{c-3, d-{e-7,f-8}}},
             Dictionary
          ),
          navltree::lookup_in([b,d,f], Value, Dictionary).

     Dictionary = ...
     Value = 8
     yes

For details on these and other provided predicates, consult the library
API documentation.


File: TheLogtalkHandbook-3.101.0.info,  Node: Curly term representation,  Prev: Usage<79>,  Up: nested_dictionaries

6.176.5 Curly term representation
---------------------------------

To simplify importing and exporting data into a nested dictionary, the
library provides ‘as_nested_dictionary/2’ and ‘as_curly_bracketed/2’
predicates that work with a 'curly term representation'.  This format is
based on the JSON data interchange format.

A dictionary is represented by the ‘{Pairs}’ term where Pairs is a
conjunction of ‘Key-Value’ or ‘Key:Value’ pairs and ‘Value’ can be a
nested dictionary or lists of pairs.  An empty dictionary is represented
using the ‘{}’ term.


File: TheLogtalkHandbook-3.101.0.info,  Node: nmea,  Next: nmf_projection,  Prev: nested_dictionaries,  Up: Libraries

6.177 ‘nmea’
============

The ‘nmea’ library parses NMEA 0183 sentences from GPS/GNSS receivers
into canonical raw terms and provides typed semantic decoding for a
selected set of common sentence types.

* Menu:

* API documentation: API documentation<195>.
* Loading: Loading<197>.
* Testing: Testing<188>.
* Public API: Public API<3>.
* Raw Sentence Representation::
* Typed data/2 Results::
* Date Rule::
* Current Scope::


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<195>,  Next: Loading<197>,  Up: nmea

6.177.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#nmea’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<197>,  Next: Testing<188>,  Prev: API documentation<195>,  Up: nmea

6.177.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(nmea(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<188>,  Next: Public API<3>,  Prev: Loading<197>,  Up: nmea

6.177.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(nmea(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Public API<3>,  Next: Raw Sentence Representation,  Prev: Testing<188>,  Up: nmea

6.177.4 Public API
------------------

   - ‘parse/2’ parses sentences from ‘atom(Atom)’, ‘chars(List)’,
     ‘codes(List)’, ‘stream(Stream)’, or ‘file(Path)’ sources.

   - ‘parse/3’ accepts parser options:

        - ‘checksum(required)’

        - ‘checksum(optional)’

        - ‘checksum(ignore)’

        - ‘unknown_type(keep)’

        - ‘unknown_type(error)’

   - malformed sentence identifiers and malformed supported
     coordinate/date fields are rejected as invalid NMEA sentences
     during parsing

   - ‘talker/2’, ‘sentence_type/2’, ‘fields/2’, and ‘checksum/2’ access
     parts of the raw parsed term.

   - ‘data/2’ maps supported sentence types into typed semantic terms.


File: TheLogtalkHandbook-3.101.0.info,  Node: Raw Sentence Representation,  Next: Typed data/2 Results,  Prev: Public API<3>,  Up: nmea

6.177.5 Raw Sentence Representation
-----------------------------------

Parsed sentences are represented as:

     nmea_sentence(Talker, Type, Fields, checksum(Provided, Computed))

Where:

   - ‘Talker’ is a normalized lowercase talker atom such as ‘gp’ or ‘gn’

   - proprietary ‘$P...’ sentences use the atom ‘proprietary’

   - ‘Type’ is the normalized lowercase sentence type atom

   - ‘Fields’ is the ordered list of field atoms after the sentence
     identifier

   - ‘Provided’ is either a normalized uppercase hexadecimal checksum
     atom or ‘missing’

   - ‘Computed’ is the normalized uppercase hexadecimal checksum atom
     computed from the sentence payload


File: TheLogtalkHandbook-3.101.0.info,  Node: Typed data/2 Results,  Next: Date Rule,  Prev: Raw Sentence Representation,  Up: nmea

6.177.6 Typed ‘data/2’ Results
------------------------------

The library currently provides semantic decoding for these sentence
types:

   - ‘gga(Time, Coordinate, fix(FixQuality, SatellitesUsed, HDOP),
     altitude(AntennaAltitudeMeters, GeoidSeparationMeters),
     dgps(DifferentialAgeSeconds, StationId))’

   - ‘rmc(Time, Status, Coordinate, movement(SpeedKnots, CourseDegrees),
     Date, MagneticVariation, Mode)’

   - ‘gsa(SelectionMode, FixType, SatelliteIds, dop(PDOP, HDOP, VDOP),
     SystemId)’

   - ‘gsv(MessageCount, MessageNumber, SatellitesInView, Satellites)’

   - ‘vtg(track(TrueCourseDegrees, MagneticCourseDegrees),
     speed(SpeedKnots, SpeedKph), Mode)’

   - ‘gll(Coordinate, Time, Status, Mode)’

Shared semantic subterms include:

   - ‘geographic(Latitude, Longitude)’

   - ‘utc_time(Hour, Minute, Second, fraction(Numerator, Denominator))’

   - ‘date(Year, Month, Day)’

   - ‘magnetic_variation(Degrees, east|west)’

   - ‘satellite(PRN, ElevationDegrees, AzimuthDegrees, SnrDbHz)’

   - ‘missing’


File: TheLogtalkHandbook-3.101.0.info,  Node: Date Rule,  Next: Current Scope,  Prev: Typed data/2 Results,  Up: nmea

6.177.7 Date Rule
-----------------

Two-digit ‘RMC’ years are expanded using a fixed GPS-era rule:

   - ‘80..99’ map to ‘1980..1999’

   - ‘00..79’ map to ‘2000..2079’


File: TheLogtalkHandbook-3.101.0.info,  Node: Current Scope,  Prev: Date Rule,  Up: nmea

6.177.8 Current Scope
---------------------

Implemented in this first version:

   - raw parsing from text sources

   - configurable checksum handling

   - proprietary ‘$P...’ sentence passthrough

   - semantic decoding for ‘GGA’, ‘RMC’, ‘GSA’, ‘GSV’, ‘VTG’, and ‘GLL’

Deliberately out of scope for this first version:

   - sentence generation

   - AIS ‘!’ sentences

   - serial or socket transport helpers

   - corrupted-stream resynchronization

   - ‘GSV’ multi-fragment aggregation

   - typed proprietary sentence decoding


File: TheLogtalkHandbook-3.101.0.info,  Node: nmf_projection,  Next: open_api,  Prev: nmea,  Up: Libraries

6.178 ‘nmf_projection’
======================

This library implements Non-negative Matrix Factorization (NMF) for
continuous datasets whose attribute values are all non-negative.  It
learns a non-negative basis using deterministic multiplicative updates
and represents each transformed instance as a list of non-negative
component weights.

* Menu:

* API documentation: API documentation<196>.
* Loading: Loading<198>.
* Testing: Testing<189>.
* Features: Features<55>.
* Options: Options<53>.
* Usage: Usage<80>.
* Dimension reducer representation: Dimension reducer representation<4>.
* References: References<39>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<196>,  Next: Loading<198>,  Up: nmf_projection

6.178.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#nmf_projection’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<198>,  Next: Testing<189>,  Prev: API documentation<196>,  Up: nmf_projection

6.178.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(nmf_projection(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<189>,  Next: Features<55>,  Prev: Loading<198>,  Up: nmf_projection

6.178.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(nmf_projection(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<55>,  Next: Options<53>,  Prev: Testing<189>,  Up: nmf_projection

6.178.4 Features
----------------

   - Implements deterministic multiplicative-update training for NMF.

   - Requires all training and inference attribute values to be
     non-negative.

   - Supports exporting learned reducers and reloading them for later
     use.

   - Records diagnostics including convergence status, iteration count,
     final update delta, and reconstruction error.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<53>,  Next: Usage<80>,  Prev: Features<55>,  Up: nmf_projection

6.178.5 Options
---------------

   - ‘n_components/1’

     Number of latent components to learn.  The current implementation
     requires the requested count to not exceed the minimum of the
     sample count and the number of features.  Larger requests raise
     ‘domain_error(component_count, Requested-Maximum)’.

   - ‘center/1’

     Always ‘false’.  Centering is intentionally disabled because NMF
     requires non-negative features.

   - ‘feature_scaling/1’

     When ‘true’, each continuous attribute is divided by its maximum
     observed training value.  When ‘false’, raw non-negative values are
     used.

   - ‘maximum_iterations/1’

     Maximum number of multiplicative-update iterations used during both
     training and per-instance coefficient inference.

   - ‘tolerance/1’

     Stop iteration when the maximum absolute update delta is less than
     or equal to this value.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<80>,  Next: Dimension reducer representation<4>,  Prev: Options<53>,  Up: nmf_projection

6.178.6 Usage
-------------

Assuming a dataset object ‘parts_based_measurements’ implementing the
‘dimension_reduction_dataset_protocol’ protocol:

     | ?- nmf_projection::learn(parts_based_measurements, DimensionReducer).

     | ?- nmf_projection::learn(parts_based_measurements, DimensionReducer, [n_components(2), feature_scaling(true), maximum_iterations(250), tolerance(1.0e-7)]).

     | ?- nmf_projection::learn(parts_based_measurements, DimensionReducer),
          nmf_projection::transform(DimensionReducer, [f1-3.0, f2-0.0, f3-1.5, f4-0.0], ReducedInstance).

     | ?- nmf_projection::learn(parts_based_measurements, DimensionReducer, [n_components(2)]),
          nmf_projection::export_to_file(parts_based_measurements, DimensionReducer, reducer, 'nmf_reducer.pl').

     | ?- logtalk_load('nmf_reducer.pl'),
          reducer(Reducer),
          nmf_projection::transform(Reducer, [f1-3.0, f2-0.0, f3-1.5, f4-0.0], ReducedInstance).


File: TheLogtalkHandbook-3.101.0.info,  Node: Dimension reducer representation<4>,  Next: References<39>,  Prev: Usage<80>,  Up: nmf_projection

6.178.7 Dimension reducer representation
----------------------------------------

Learned NMF reducers use the representation:

     nmf_reducer(Encoders, Components, Diagnostics)

where ‘Encoders’ stores the continuous attribute encoders used to map
instances into a non-negative feature vector, ‘Components’ stores the
learned non-negative basis vectors, and ‘Diagnostics’ stores metadata
about the learned reducer.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<39>,  Prev: Dimension reducer representation<4>,  Up: nmf_projection

6.178.8 References
------------------

   - Daniel D. Lee and H. Sebastian Seung.  'Algorithms for Non-negative
     Matrix Factorization'.  Advances in Neural Information Processing
     Systems 13, 2001.


File: TheLogtalkHandbook-3.101.0.info,  Node: open_api,  Next: open_ai,  Prev: nmf_projection,  Up: Libraries

6.179 ‘open_api’
================

The ‘open_api’ library provides a first-pass implementation for
deriving, parsing, generating, and structurally validating OpenAPI 3.1.0
documents.  It builds on top of the ‘json’, ‘json_schema’, and
‘application’ libraries.

This initial implementation focuses on deriving OpenAPI documents from
objects implementing the ‘open_api_provider_protocol’ protocol using a
small, portable descriptor vocabulary.  This provides the following
benefits:

   - Earlier validation: malformed descriptors can be rejected by
     functor shape and argument checks before any JSON normalization.

   - Better portability: provider objects depend on a Logtalk-level
     vocabulary, not on OpenAPI object field spelling.

   - Better reuse: the same descriptors could later feed both OpenAPI
     generation and a future authentication or HTTP integration layer.

   - Cleaner provider code: provider objects avoid raw camelCase OpenAPI
     keys and nested curly terms for common security cases.

* Menu:

* Layering: Layering<3>.
* API documentation: API documentation<197>.
* Loading: Loading<199>.
* Testing: Testing<190>.
* Current scope: Current scope<22>.
* Current limitations: Current limitations<16>.
* Provider descriptors::
* Usage: Usage<81>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Layering<3>,  Next: API documentation<197>,  Up: open_api

6.179.1 Layering
----------------

‘open_api’ is a companion library for the HTTP stack rather than a
transport or dispatch layer:

   - Use it standalone when you only need to parse, generate, or
     structurally validate OpenAPI documents.

   - Pair it with the ‘http_core’ library when you need request or
     response contract validation against normalized HTTP terms or wire
     sources.

   - Pair it with ‘http_router’ library when router objects expose
     ‘open_api_provider_protocol’ metadata derived from ‘route/4’,
     ‘route_metadata/2’, and ‘route_produces/2’.

   - Pair it with ‘rest’ library when you want the same validation and
     document derivation over higher-level endpoint descriptors built on
     top of ‘http_router’.

   - Use it directly with custom provider objects when your API
     description source is not a router or REST object.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<197>,  Next: Loading<199>,  Prev: Layering<3>,  Up: open_api

6.179.2 API documentation
-------------------------

Open the ‘../../apis/library_index.html#open_api’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<199>,  Next: Testing<190>,  Prev: API documentation<197>,  Up: open_api

6.179.3 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(open_api(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<190>,  Next: Current scope<22>,  Prev: Loading<199>,  Up: open_api

6.179.4 Testing
---------------

To test this library, load the ‘tester.lgt’ file:

     | ?- logtalk_load(open_api(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Current scope<22>,  Next: Current limitations<16>,  Prev: Testing<190>,  Up: open_api

6.179.5 Current scope
---------------------

   - Derive OpenAPI 3.1.0 documents from provider objects implementing
     the ‘open_api_provider_protocol’ protocol

   - Construct reusable JSON descriptor terms using helper predicates
     for ‘media/2’, ‘request_body/3’, and ‘response/3’, validating
     JSON-compatible media types, response status keys, and shallow
     schema-term shape, including boolean schemas

   - Resolve provider operations by ‘operationId’ using ‘operation/3’

   - Validate normalized HTTP request and response terms, or objects
     implementing the ‘http_request_protocol’ and
     ‘http_response_protocol’ protocols, against provider operation
     descriptors

   - Parse HTTP request and response wire sources through the
     ‘http_core’ library before validating them against provider
     operation descriptors

   - Parse and generate OpenAPI documents using the repository-standard
     JSON term representation

   - Perform structural validation of derived or parsed documents using
     an inline phase-1 JSON Schema

   - Reject provider descriptor sets that reuse the same ‘operationId’
     atom for more than one operation

   - Derive top-level OpenAPI ‘security’ defaults from provider
     ‘security/1’

   - Derive reusable security schemes under ‘components.securitySchemes’
     and reject top-level or operation ‘security/1’ references to
     undeclared scheme names or undeclared OAuth flow scopes when
     locally available

   - Reject malformed reusable security scheme descriptors that omit
     fixed fields required by their ‘type’, and reject malformed
     declared OAuth flow objects that omit their required URLs or
     ‘scopes’

   - Reject provider-side invalid ‘apiKey.in’ values and malformed
     URL-valued security fields such as OAuth token or authorization
     endpoints

   - Validate provider server descriptor URLs and reject malformed
     values

   - Accept wildcard response status descriptors such as ‘'2XX'’

   - Reject provider path parameter descriptors that are not declared in
     the operation path template or that do not use ‘Required = true’

   - Reject parsed or derived documents whose inline path parameters
     violate the OpenAPI path-parameter invariants

   - Accept webhook-only OpenAPI 3.1.0 documents during structural
     validation


File: TheLogtalkHandbook-3.101.0.info,  Node: Current limitations<16>,  Next: Provider descriptors,  Prev: Current scope<22>,  Up: open_api

6.179.6 Current limitations
---------------------------

   - Validation is intentionally partial and does not attempt to
     implement the full OpenAPI 3.1 meta-schema.  Only selected
     type-specific fixed-field checks, such as those for Security Scheme
     Objects and OAuth Flow Objects, are provided

   - The library derives only ‘components.schemas’ and
     ‘components.securitySchemes’ plus the root ‘security’ field

   - The library integrates with the ‘http_core’ library for request and
     response parsing and for protocol-based access to normalized HTTP
     messages, but it limits itself to contract validation rather than
     transport concerns

   - The supported ‘security_scheme/2’ descriptor vocabulary is limited
     to the forms summarized below

   - Scope validation cross-checks against locally declared OAuth flow
     scopes when they are present in a reusable security scheme.  Full
     OpenID Connect discovery-based scope resolution is out of scope

   - Query and cookie parameter validation relies on typed request
     properties such as ‘query_pairs/1’ and ‘cookies/1’; raw
     query-string parsing is intentionally out of scope

   - Request and response body validation supports ‘json/1’, ‘text/1’,
     ‘binary/1’, and ‘form/1’ payload terms; multipart payload
     validation remains out of scope

   - The JSON helper predicates validate media types and response status
     keys eagerly, but schema validation at the helper boundary is
     intentionally shallow and only checks for boolean schemas, JSON
     object terms, or ‘schema_ref/1’ references


File: TheLogtalkHandbook-3.101.0.info,  Node: Provider descriptors,  Next: Usage<81>,  Prev: Current limitations<16>,  Up: open_api

6.179.7 Provider descriptors
----------------------------

* Menu:

* API metadata::
* Server descriptors::
* Top-level security defaults::
* Operation descriptors::
* Reusable schemas::
* Reusable security schemes::


File: TheLogtalkHandbook-3.101.0.info,  Node: API metadata,  Next: Server descriptors,  Up: Provider descriptors

6.179.7.1 API metadata
......................

The ‘api_info/1’ predicate returns an ‘info(Title, Version, Summary,
Properties)’ descriptor for the top-level OpenAPI ‘info’ object.
Currently recognized metadata properties are limited to
‘description(Description)’.

Provider objects that also implement ‘application_protocol’ can
contribute missing OpenAPI metadata:

   - ‘description/1’ maps to ‘info.description’

   - ‘license/1’ maps to ‘info.license.name’

   - ‘homepage/1’ maps to the top-level ‘externalDocs.url’


File: TheLogtalkHandbook-3.101.0.info,  Node: Server descriptors,  Next: Top-level security defaults,  Prev: API metadata,  Up: Provider descriptors

6.179.7.2 Server descriptors
............................

The ‘servers/1’ predicate returns a list of ‘server(URL, Description)’
descriptors used to build the top-level OpenAPI ‘servers’ array.  ‘URL’
must be a valid OpenAPI Server Object URL string, allowing absolute
URLs, relative references, and templated variables such as
‘https://{username}.example.com:{port}/{basePath}’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Top-level security defaults,  Next: Operation descriptors,  Prev: Server descriptors,  Up: Provider descriptors

6.179.7.3 Top-level security defaults
.....................................

The ‘security/1’ predicate returns a list of top-level OpenAPI security
requirement alternatives.  The returned list uses the same
‘Requirements’ representation accepted by operation
‘security(Requirements)’ properties: each requirement alternative is a
list of ‘Scheme-Scopes’ pairs and ‘[]’ denotes an empty security
requirement object.  Scheme names must match declarations exposed by
‘security_scheme/2’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Operation descriptors,  Next: Reusable schemas,  Prev: Top-level security defaults,  Up: Provider descriptors

6.179.7.4 Operation descriptors
...............................

The ‘operations/1’ predicate returns a list of ‘operation(Id, Method,
Path, Summary, Parameters, RequestBody, Responses, Properties)’
descriptors.  ‘Id’ is used as the OpenAPI ‘operationId’ and must be
unique across the returned descriptor list.

Nested descriptors are ‘parameter(Name, In, Description, Required,
Schema)’, ‘request_body(Description, Required, MediaTypes)’,
‘response(Status, Description, MediaTypes)’, and ‘media(MediaType,
Schema)’.  ‘Status’ may be an integer HTTP status code, ‘default’, or a
wildcard range atom such as ‘'2XX'’.  Path parameters must match a
template expression in ‘Path’ and must use ‘Required = true’.

The current implementation keeps the operation property vocabulary
narrow and supports only:

   - ‘description(Description)’

   - ‘tags(Tags)’

   - ‘deprecated(Boolean)’

   - ‘security(Requirements)’ where ‘Requirements’ is a list of
     requirement alternatives represented as lists of ‘Scheme-Scopes’
     pairs and ‘[]’ denotes an empty security requirement object

Scheme names referenced from ‘security(Requirements)’ must match names
exposed by ‘security_scheme/2’, and operation-level security overrides
any top-level ‘security/1’ declaration.


File: TheLogtalkHandbook-3.101.0.info,  Node: Reusable schemas,  Next: Reusable security schemes,  Prev: Operation descriptors,  Up: Provider descriptors

6.179.7.5 Reusable schemas
..........................

The ‘schema/2’ predicate maps reusable schema names to JSON Schema curly
terms compatible with the ‘json_schema’ library.  References to reusable
schemas are expressed using ‘schema_ref(Name)’ terms.


File: TheLogtalkHandbook-3.101.0.info,  Node: Reusable security schemes,  Prev: Reusable schemas,  Up: Provider descriptors

6.179.7.6 Reusable security schemes
...................................

The ‘security_scheme/2’ predicate maps reusable security scheme names to
portable descriptor terms.  This library accepts those terms and
normalizes them to OpenAPI Security Scheme Objects when deriving the
final document.  The scheme names must match names referenced from
operation ‘security(Requirements)’ properties.  The descriptor
vocabulary keeps provider objects at the Logtalk domain level instead of
exposing OpenAPI JSON surface spelling directly:

   - provider code does not need raw OpenAPI field names such as
     ‘openIdConnectUrl’ or ‘clientCredentials’

   - validation can happen at the level of Logtalk terms before document
     generation

   - the same provider facts are easier to reuse in a future portable
     HTTP or authentication library because they describe security
     intent rather than emitted OpenAPI object structure

Supported descriptor shapes are:

   - ‘api_key(In, Name)’

   - ‘api_key(In, Name, Options)’

   - ‘http(Scheme)’

   - ‘http(Scheme, Options)’

   - ‘mutual_tls’

   - ‘mutual_tls(Options)’

   - ‘oauth2(Flows)’

   - ‘oauth2(Flows, Options)’

   - ‘openid_connect(URL)’

   - ‘openid_connect(URL, Options)’

Supported scheme options are:

   - ‘description(Description)’ for all scheme kinds

   - ‘bearer_format(Format)’ for ‘http/2’

   - ‘flows(Flows)’ for ‘openid_connect/2’ when locally declared scopes
     are needed without relying on OpenID Connect discovery; these local
     flow declarations are used only for provider-side
     security-reference validation and are not emitted into the final
     OpenAPI document

Supported OAuth flow descriptors are:

   - ‘implicit(AuthorizationURL, Scopes)’

   - ‘implicit(AuthorizationURL, Scopes, [refresh_url(URL)])’

   - ‘password(TokenURL, Scopes)’

   - ‘password(TokenURL, Scopes, [refresh_url(URL)])’

   - ‘client_credentials(TokenURL, Scopes)’

   - ‘client_credentials(TokenURL, Scopes, [refresh_url(URL)])’

   - ‘authorization_code(AuthorizationURL, TokenURL, Scopes)’

   - ‘authorization_code(AuthorizationURL, TokenURL, Scopes,
     [refresh_url(URL)])’

Scope descriptors are expressed as a list of ‘scope(Name, Description)’
terms.

Use descriptor terms such as:

     security_scheme(
       user_oauth,
       oauth2([
         client_credentials(
           'https://auth.example.com/oauth/token',
           [scope(read_users, 'Read user data')]
         )
       ])
     ).

     security_scheme(api_key, api_key(header, 'X-API-Key')).

     security_scheme(user_bearer, http(bearer, [bearer_format('JWT')])).

     security_scheme(user_oidc, openid_connect('https://example.com/.well-known/openid-configuration')).

An OpenID Connect scheme can also declare local scopes for the existing
security reference validation path:

     security_scheme(
       user_oidc,
       openid_connect(
         'https://example.com/.well-known/openid-configuration',
         [flows([
           authorization_code(
             'https://example.com/oauth/authorize',
             'https://example.com/oauth/token',
             [
               scope(read_users, 'Read user data')
             ]
           )
         ])]
       )
     ).

Those local flow declarations are used only for provider-side security
reference validation.  They are not emitted into the derived OpenAPI
document, as OpenID Connect Security Scheme Objects do not define a
‘flows’ field.

Provider-side validation checks, among other things:

   - duplicate scheme names

   - invalid descriptor functors or arities

   - required fixed fields after normalization

   - valid ‘apiKey’ locations

   - malformed OAuth flow or scope descriptors

   - malformed URL-valued fields such as ‘tokenUrl’, ‘authorizationUrl’,
     ‘refreshUrl’, and ‘openIdConnectUrl’


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<81>,  Prev: Provider descriptors,  Up: open_api

6.179.8 Usage
-------------

Load the library and derive a document from a provider object:

     | ?- logtalk_load(open_api(loader)),
          open_api::document(sample_open_api_provider, Document).

Parse and generate OpenAPI documents in JSON term form:

     | ?- open_api::parse(atom('{"openapi":"3.1.0","info":{"title":"Demo","version":"1.0.0"},"paths":{}}'), Document).

     | ?- open_api::generate(atom(JSON), {openapi-'3.1.0', info-{title-'Demo', version-'1.0.0'}, paths-{}}).

Validate a document and inspect any structural errors:

     | ?- open_api::validate_document(Document, Errors).

Resolve an operation descriptor and validate normalized requests,
responses, or HTTP wire sources against it:

     | ?- open_api::operation(sample_open_api_provider, update_user, Operation).

     | ?- open_api::validate_request(
           sample_open_api_provider,
           update_user,
           request(
               put,
               origin('/users/11111111-1111-1111-1111-111111111111'),
               http(1, 1),
               [],
               content('application/json', json({name-'Alice Example', active-true})),
               [query_pairs([verbose-true])]
           ),
           Errors
        ).

     | ?- open_api::validate_response(
             sample_open_api_provider,
             get_user,
             response(
                 http(1, 1),
                 status(404, 'Not Found'),
                 [],
                 content('application/json', json({code-not_found, message-'User not found'})),
                 []
             )
          ).

     | ?- open_api::validate_http_request(
             sample_open_api_provider,
             update_user,
             atom('PUT /users/11111111-1111-1111-1111-111111111111?verbose=true HTTP/1.1\r\ncontent-type: application/json\r\n\r\n{"name":"Alice Example","active":true}')
          ).

Construct standard JSON request and response descriptors when building
provider operations programmatically:

     | ?- open_api::json_request_body_descriptor(
             'Message payload',
             true,
             {type-object, properties-{title-{type-string}}, required-[title], additionalProperties- @false},
             RequestBody
          ).

     | ?- open_api::problem_response_descriptor(default, 'Problem response', Response).


File: TheLogtalkHandbook-3.101.0.info,  Node: open_ai,  Next: open_id,  Prev: open_api,  Up: Libraries

6.180 ‘open_ai’
===============

The ‘open_ai’ library provides a portable OpenAI-compatible public
non-admin API surface.  It uses the existing HTTP, REST, and OpenAPI
libraries and defaults to the ‘http_process_transport’ transport for
HTTPS and WSS support.

The library implements the OpenAI wire-format routing, client request
construction, OpenAPI document generation, and validation hooks.
Server-side model, file, eval, tool, realtime, and media behavior is
supplied by an application backend object implementing
‘open_ai_backend_protocol’.

Requires a backend supporting sockets and unbound integer arithmetic due
to the library dependencies.  Supported backends include ECLiPSe,
SICStus Prolog, SWI-Prolog, Trealla Prolog, and XVM.

* Menu:

* Loading: Loading<200>.
* Testing: Testing<191>.
* Current scope: Current scope<23>.
* Basic client usage::
* Basic server usage::


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<200>,  Next: Testing<191>,  Up: open_ai

6.180.1 Loading
---------------

To load the library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(open_ai(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<191>,  Next: Current scope<23>,  Prev: Loading<200>,  Up: open_ai

6.180.2 Testing
---------------

To test this library, load the ‘tester.lgt’ file:

     | ?- logtalk_load(open_ai(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Current scope<23>,  Next: Basic client usage,  Prev: Testing<191>,  Up: open_ai

6.180.3 Current scope
---------------------

   - Public non-admin endpoints from the pinned official OpenAI OpenAPI
     ‘2.3.0’ document.

   - Organization and project administration paths are excluded.

   - The generated catalog currently covers 161 operations.

   - Request and response schemas are intentionally permissive in this
     first catalog pass; endpoint coverage, routing, OpenAPI document
     generation, and client URL/header construction are the primary
     compatibility surface.


File: TheLogtalkHandbook-3.101.0.info,  Node: Basic client usage,  Next: Basic server usage,  Prev: Current scope<23>,  Up: open_ai

6.180.4 Basic client usage
--------------------------

     | ?- logtalk_load(open_ai(loader)).
     ...

     | ?- open_ai_client::request(
             createResponse,
             [],
             content('application/json', json({model-'gpt-4.1', input-'Hello'})),
             Response,
             [api_key('sk-...')]
          ).

See the ‘ollama_client’ for a complete example of using this library.


File: TheLogtalkHandbook-3.101.0.info,  Node: Basic server usage,  Prev: Basic client usage,  Up: open_ai

6.180.5 Basic server usage
--------------------------

Define a backend object implementing ‘open_ai_backend_protocol’:

     :- object(my_backend,
         implements(open_ai_backend_protocol)).

         handle_open_ai(OperationId, Request, Result) :-
             % inspect OperationId and Request, then return a REST result term
             Result = ok({operation-OperationId}).

     :- end_object.

The ‘handle_open_ai/3’ predicate is expected to succeed once and return
a REST result term for both successful and application error outcomes.
Plain failure is treated as a backend contract violation by the server
facade and is converted by the REST dispatch layer into an unexpected
server error response.

Then dispatch normalized HTTP requests through:

     open_ai_server(my_backend)::handle(Request, Response).


File: TheLogtalkHandbook-3.101.0.info,  Node: open_id,  Next: optics_clusterer,  Prev: open_ai,  Up: Libraries

6.181 ‘open_id’
===============

The ‘open_id’ library provides a portable OpenID Connect client for the
Authorization Code + PKCE flow.  It supports provider discovery,
authorization URL construction, authorization response parsing and state
validation, authorization-code and refresh-token exchanges, UserInfo
requests, RP-initiated logout URL construction, JWKS retrieval and
caching, and ID-token verification for ‘RS256’ and ‘ES256’.

The library uses ‘http_client’ with ‘transport(http_process_transport)’
for HTTP requests.  HTTPS requests are made using
‘http_process_transport’ TLS connections, which require the ‘openssl’
command to be available unless overridden with the
‘openssl_executable/1’ option.

This library can be used with backend Prolog systems that support
unbound integer arithmetic and the ‘sockets’ library: ECLiPSe, SICStus
Prolog, SWI-Prolog, Trealla Prolog, and XVM.

* Menu:

* Loading: Loading<201>.
* Testing: Testing<192>.
* Basic usage: Basic usage<4>.
* Current scope: Current scope<24>.
* Current limitations: Current limitations<17>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<201>,  Next: Testing<192>,  Up: open_id

6.181.1 Loading
---------------

To load the library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(open_id(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<192>,  Next: Basic usage<4>,  Prev: Loading<201>,  Up: open_id

6.181.2 Testing
---------------

To test this library, load the ‘tester.lgt’ file:

     | ?- logtalk_load(open_id(tester)).

To run the optional live tests against Google’s public OpenID Connect
discovery and JWKS endpoints, load the ‘tester_live.lgt’ file:

     | ?- logtalk_load(open_id(tester_live)).

The Google discovery and JWKS live tests do not require credentials.
The optional Google ID-token verification live test requires a fresh
Google-issued ID token and its expected audience:

     $ export LOGTALK_OPEN_ID_GOOGLE_ID_TOKEN="..."
     $ export LOGTALK_OPEN_ID_GOOGLE_AUDIENCE="..."

If the ID token includes a nonce claim, also define the
‘LOGTALK_OPEN_ID_GOOGLE_NONCE’ environment variable.

The live tests also include an end-to-end Authorization Code + PKCE flow
against the community-run ‘https://oidctest.wsweet.org/’ OpenID Connect
test provider, using its documented test account ‘dwho’/‘dwho’ and
pre-registered client ‘private’/‘tardis’.  This provider has no
availability guarantees.


File: TheLogtalkHandbook-3.101.0.info,  Node: Basic usage<4>,  Next: Current scope<24>,  Prev: Testing<192>,  Up: open_id

6.181.3 Basic usage
-------------------

     | ?- open_id::discover('https://issuer.example', Provider, []),
          open_id::authorization_url(
              Provider,
              authorization_request([
                  client_id('client-id'),
                  redirect_uri('https://client.example/callback'),
                  scope([openid, profile])
              ]),
              URL,
              Session,
              []
          ).

After redirecting the user to ‘URL’ and receiving the callback URL:

     | ?- open_id::authorization_code(CallbackURL, Session, Code, []),
          open_id::exchange_code(
              Provider,
              Code,
              Session,
              Tokens,
              [client_authentication(client_secret_basic('client-secret'))]
          ),
          Tokens = tokens(Properties),
          member(id_token(IDToken), Properties),
          open_id::verify_id_token(IDToken, Provider, Claims,
              [expected_audience('client-id')]).

To call the UserInfo endpoint with the resulting access token:

     | ?- Tokens = tokens(Properties),
          member(access_token(AccessToken), Properties),
          open_id::userinfo(Provider, AccessToken, UserInfo, []).

To use a refresh token:

     | ?- open_id::refresh_token(
              Provider,
              RefreshToken,
              RefreshedTokens,
              [
                  client_id('client-id'),
                  client_authentication(client_secret_basic('client-secret'))
              ]
          ).

To build an RP-initiated logout URL:

     | ?- open_id::logout_url(
              Provider,
              logout_request([
                  id_token_hint(IDToken),
                  post_logout_redirect_uri('https://client.example/logout/callback'),
                  state('logout-state')
              ]),
              LogoutURL,
              []
          ).


File: TheLogtalkHandbook-3.101.0.info,  Node: Current scope<24>,  Next: Current limitations<17>,  Prev: Basic usage<4>,  Up: open_id

6.181.4 Current scope
---------------------

   - OpenID Provider discovery.

   - Authorization Code + PKCE (‘S256’) URL construction.

   - Authorization response parsing and state validation.

   - Authorization-code token exchange for public clients,
     ‘client_secret_post/1’, and ‘client_secret_basic/1’.

   - Refresh-token exchange and UserInfo retrieval.

   - RP-initiated logout URL construction.

   - JWKS retrieval, caching, and refresh-on-unknown-‘kid’ key rotation.

   - ID-token JWT verification for ‘RS256’ and ‘ES256’ using OpenSSL.

   - Claim validation for issuer, subject, audience, authorized party,
     nonce, expiration, not-before, and issued-at tolerance.


File: TheLogtalkHandbook-3.101.0.info,  Node: Current limitations<17>,  Prev: Current scope<24>,  Up: open_id

6.181.5 Current limitations
---------------------------

   - Device authorization, dynamic client registration, browser
     launching, and callback server ownership are outside the current
     scope.

   - ID-token verification requires the ‘openssl’ command.


File: TheLogtalkHandbook-3.101.0.info,  Node: optics_clusterer,  Next: optionals,  Prev: open_id,  Up: Libraries

6.182 ‘optics_clusterer’
========================

OPTICS clusterer.  It uses deterministic OPTICS ordering with
epsilon-based cluster extraction for the fixed clusterer protocol.
Supports continuous attributes only.

The library implements the ‘clusterer_protocol’ defined in the
‘clustering_protocols’ library.  It provides predicates for learning a
clusterer from a dataset, assigning new instances to clusters, and
exporting the learned clusterer as a list of predicate clauses or to a
file.

Datasets are represented as objects implementing the
‘clustering_dataset_protocol’ protocol from the ‘clustering_protocols’
library.

* Menu:

* API documentation: API documentation<198>.
* Loading: Loading<202>.
* Testing: Testing<193>.
* Features: Features<56>.
* Options: Options<54>.
* Clusterer representation: Clusterer representation<12>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<198>,  Next: Loading<202>,  Up: optics_clusterer

6.182.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#optics_clusterer’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<202>,  Next: Testing<193>,  Prev: API documentation<198>,  Up: optics_clusterer

6.182.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(optics_clusterer(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<193>,  Next: Features<56>,  Prev: Loading<202>,  Up: optics_clusterer

6.182.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(optics_clusterer(tester)).

To run the performance benchmark suite, load the
‘tester_performance.lgt’ file:

     | ?- logtalk_load(optics_clusterer(tester_performance)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<56>,  Next: Options<54>,  Prev: Testing<193>,  Up: optics_clusterer

6.182.4 Features
----------------

   - 'OPTICS Ordering': Learns a deterministic ordering using
     density-based reachability over continuous datasets.

   - 'Adaptive Neighborhood Indexing': Uses a low-dimensional
     epsilon-grid index when it is likely to be cheaper and otherwise
     falls back to a deterministic metric tree for neighborhood search
     during ordering construction.  The search backend can also be
     selected explicitly.

   - 'Continuous Datasets': Accepts datasets containing only continuous
     attributes.

   - 'Distance Metrics': Supports Euclidean and Manhattan distances.

   - 'Optional Feature Scaling': Continuous attributes can be
     standardized using z-score scaling.

   - 'Epsilon-Based Extraction': Extracts clusters from the ordering
     using a configurable extraction epsilon threshold.

   - 'Noise Detection': New instances not reachable from an extracted
     core cluster within the extraction threshold are assigned to
     ‘noise’.

   - 'Prediction Pruning': Classification reuses per-cluster core-point
     bounds to prune clusters that cannot beat the current best
     reachable match.

   - 'Portable Export': Learned clusterers can be exported as clauses or
     files and reused later.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<54>,  Next: Clusterer representation<12>,  Prev: Features<56>,  Up: optics_clusterer

6.182.5 Options
---------------

The following options can be passed to the ‘learn/3’ predicate:

   - ‘ordering_and_extraction_epsilons(MaximumOrderingEpsilon,
     ExtractionEpsilon)’: Pair of epsilon thresholds where
     ‘MaximumOrderingEpsilon’ is the neighborhood radius used while
     constructing the OPTICS ordering and ‘ExtractionEpsilon’ is the
     threshold used when extracting clusters from the learned ordering
     and when classifying new instances.  Default is
     ‘ordering_and_extraction_epsilons(1.0, 1.0)’.  ‘ExtractionEpsilon’
     must not be greater than ‘MaximumOrderingEpsilon’.

   - ‘search_index(SearchIndex)’: Search backend selection used while
     constructing the OPTICS ordering.  Options are ‘auto’ (default),
     ‘grid’, and ‘metric_tree’.

   - ‘minimum_points(MinimumPoints)’: Minimum neighborhood size required
     for a point to be considered a core point.  Default is ‘2’.

   - ‘distance_metric(Metric)’: Distance metric to use.  Options:
     ‘euclidean’ (default) or ‘manhattan’.

   - ‘feature_scaling(FeatureScaling)’: Whether to standardize
     continuous attributes before clustering.  Options: ‘on’ (default)
     or ‘off’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Clusterer representation<12>,  Prev: Options<54>,  Up: optics_clusterer

6.182.6 Clusterer representation
--------------------------------

The learned clusterer is represented as a compound term with the functor
chosen by the user when exporting the clusterer and arity 5.  For
example:

     optics_clusterer(Encoders, Ordering, Clusters, Noise, Options)

Where:

   - ‘Encoders’: List of continuous attribute encoders storing attribute
     name, mean, and scale.

   - ‘Ordering’: List of ordered points annotated with reachability and
     core-distance information.

   - ‘Clusters’: List of extracted clusters in cluster-id order.

   - ‘Noise’: List of extracted noise points.

   - ‘Options’: Effective training options used to learn the clusterer.


File: TheLogtalkHandbook-3.101.0.info,  Node: optionals,  Next: options,  Prev: optics_clusterer,  Up: Libraries

6.183 ‘optionals’
=================

This library provides an implementation of 'optional terms' with an API
modeled after the Java 8 ‘Optional’ class (originally due to requests by
users working in Logtalk/Java hybrid applications).  An optional term is
an opaque compound term that may or may not hold a value.  Optional
terms avoid forcing the user to define a representation for the absence
of a value by providing an API with predicates that depend on the
presence or absence of a value.  Optional terms also allow separating
the code that constructs optional terms from the code that processes
them, which is then free to deal if necessary and at its convenience
with any case where the values held by optional terms are not present.

* Menu:

* API documentation: API documentation<199>.
* Loading: Loading<203>.
* Testing: Testing<194>.
* Usage: Usage<82>.
* See also: See also<3>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<199>,  Next: Loading<203>,  Up: optionals

6.183.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#optionals’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<203>,  Next: Testing<194>,  Prev: API documentation<199>,  Up: optionals

6.183.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(optionals(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<194>,  Next: Usage<82>,  Prev: Loading<203>,  Up: optionals

6.183.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(optionals(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<82>,  Next: See also<3>,  Prev: Testing<194>,  Up: optionals

6.183.4 Usage
-------------

The ‘optional’ object provides constructors for optional terms.  For
example:

     | ?- optional::of(1, Optional).
     ...

The created optional terms can then be passed as parameters to the
‘optional/1’ parametric object.  For example:

     | ?- optional::of(1, Optional), optional(Optional)::or_else(Term, 0).
     Optional = optional(1),
     Term = 1
     yes

     | ?- optional::empty(Optional), optional(Optional)::or_else(Term, 0).
     Optional = empty,
     Term = 0
     yes

The ‘maybe’ object provides types and predicates for type-checking of
the term held by optional terms.  It also provides some predicates for
handling lists of optional terms, including ‘sequence/2’ and
‘traverse/3’.

The ‘optional/1’ parametric object also provides ‘map_or_else/3’ for
applying a closure to the value held by the optional term if not empty,
returning a default value otherwise:

     | ?- optional::of(a, Optional),
          optional(Optional)::map_or_else(char_code, 0, Value).
     Value = 97
     yes

     | ?- optional::empty(Optional),
          optional(Optional)::map_or_else(char_code, 0, Value).
     Value = 0
     yes

The ‘zip/3’ predicate combines two optional terms using a closure when
both are not empty:

     | ?- optional::of(1, O1), optional::of(3, O2),
          optional(O1)::zip([X,Y,Z]>>(Z is X+Y), O2, NewOptional).
     NewOptional = optional(4)
     yes

     | ?- optional::of(1, O1), optional::empty(O2),
          optional(O1)::zip([X,Y,Z]>>(Z is X+Y), O2, NewOptional).
     NewOptional = empty
     yes

The ‘flatten/1’ predicate unwraps a nested optional term:

     | ?- optional::of(1, Inner), optional::of(Inner, Outer),
          optional(Outer)::flatten(NewOptional).
     NewOptional = optional(1)
     yes

     | ?- optional::empty(Inner), optional::of(Inner, Outer),
          optional(Outer)::flatten(NewOptional).
     NewOptional = empty
     yes

The ‘to_expected/2’ predicate converts an optional to an expected term:

     | ?- optional::of(1, Optional),
          optional(Optional)::to_expected(missing, Expected).
     Expected = expected(1)
     yes

     | ?- optional::empty(Optional),
          optional(Optional)::to_expected(missing, Expected).
     Expected = unexpected(missing)
     yes

The ‘from_goal/3’ and ‘from_goal/2’ constructors silently convert goal
exceptions to empty optional terms.  Use ‘from_goal_or_throw/3’ or
‘from_goal_or_throw/2’ if exceptions should be propagated instead:

     | ?- optional::from_goal_or_throw(Y is 1+2, Y, Optional).
     Optional = optional(3)
     yes

     | ?- optional::from_goal_or_throw(2 is 3, _, Optional).
     Optional = empty
     yes

     | ?- catch(
            optional::from_goal_or_throw(Y is _, Y, _),
            Error,
            true
          ).
     Error = error(instantiation_error, ...)
     yes

Examples:

     | ?- optional::of(1, O1), optional::of(2, O2),
          maybe::sequence([O1, O2], Optional).
     Optional = optional([1,2])
     yes

     | ?- maybe::traverse({optional}/[X,O]>>optional::of(X, O), [1,2], Optional).
     Optional = optional([1,2])
     yes

     | ?- maybe::traverse({optional}/[X,O]>>(
            integer(X) -> optional::of(X, O)
          ; optional::empty(O)
          ), [1,a,2], Optional).
     Optional = empty
     yes

     | ?- optional::of(1, O1), optional::empty(O2),
          maybe::sequence([O1, O2], Optional).
     Optional = empty
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: See also<3>,  Prev: Usage<82>,  Up: optionals

6.183.5 See also
----------------

The ‘expecteds’ and ‘validations’ libraries.


File: TheLogtalkHandbook-3.101.0.info,  Node: options,  Next: os,  Prev: optionals,  Up: Libraries

6.184 ‘options’
===============

This library provides useful predicates for managing developer tool and
application options.

* Menu:

* API documentation: API documentation<200>.
* Loading: Loading<204>.
* Testing: Testing<195>.
* Usage: Usage<83>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<200>,  Next: Loading<204>,  Up: options

6.184.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#options’ file in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<204>,  Next: Testing<195>,  Prev: API documentation<200>,  Up: options

6.184.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ utility
file:

     | ?- logtalk_load(options(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<195>,  Next: Usage<83>,  Prev: Loading<204>,  Up: options

6.184.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(options(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<83>,  Prev: Testing<195>,  Up: options

6.184.4 Usage
-------------

The ‘options’ category is usually imported by the root object of the
developer tool or application.  The importing object should define the
‘default_option/1’ predicate and, if option type-checking is required,
the ‘valid_option/1’ predicate must be defined for each option.  This
library requires options to be represented by compound terms where the
functor is the option name (e.g., ‘trim(true)’ or (‘box(0,2)’)).  The
‘option/2-3’ can be used to get or test an option given a list of
options.  When an option appears multiple times in a list, the
‘option/2-3’ predicates get or test the first (leftmost) occurrence.

The library also supports a user-defined ‘fix_option/2’ predicate.  A
usage example is when an option value can be a relative file path that
should be expanded before use.  Another usage example would be
converting from a user-friendly option to a form more suitable for
internal processing.  When a call to the ‘fix_option/2’ predicate fails,
the option is used as-is.

A simple example:

     :- object(foo,
         imports(options)).

         :- uses(type, [
             valid/2
         ]).

         :- public(p/0).
         p :-
             % use default options
             p([]).

         :- public(p/1).
         p(UserOptions) :-
             ^^check_options(UserOptions),
             % construct the full set of options from
             % the user options and the default options
             ^^merge_options(UserOptions, Options),
             ...
             % query an option
             ^^option(baz(Boolean), Options),
             q(Boolean),
             ...

         default_option(baz(true)).
         ...

         valid_option(baz(Boolean)) :-
             valid(boolean, Boolean).
         ...

     :- end_object.

Note that you can use protected or private import of the ‘options’
category if you don’t want to add its public predicates to the object
protocol.


File: TheLogtalkHandbook-3.101.0.info,  Node: os,  Next: otp,  Prev: options,  Up: Libraries

6.185 ‘os’
==========

This library provides a 'portable' operating-system interface for the
supported backend Prolog compilers.

The ‘os_types’ category defines some useful operating-system types for
type-checking when using with the ‘type’ library object.

* Menu:

* API documentation: API documentation<201>.
* Loading: Loading<205>.
* Testing: Testing<196>.
* Known issues: Known issues<16>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<201>,  Next: Loading<205>,  Up: os

6.185.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#os’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<205>,  Next: Testing<196>,  Prev: API documentation<201>,  Up: os

6.185.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(os(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<196>,  Next: Known issues<16>,  Prev: Loading<205>,  Up: os

6.185.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(os(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Known issues<16>,  Prev: Testing<196>,  Up: os

6.185.4 Known issues
--------------------

Some predicates may only be supported by a subset of backend Prolog
compilers on a subset of operating-systems.  They should be used with
care and fully tested in your application domain, as some backend Prolog
compilers have buggy and inconsistent interfaces, notably across
operating-systems.  See the remarks section in the ‘os’ object
documentation for details.


File: TheLogtalkHandbook-3.101.0.info,  Node: otp,  Next: partitions,  Prev: os,  Up: Libraries

6.186 ‘otp’
===========

The ‘otp’ library provides predicates for generating and verifying HOTP
and TOTP one-time passwords following:

‘https://www.rfc-editor.org/rfc/rfc4226’

‘https://www.rfc-editor.org/rfc/rfc6238’

The implementation is built on top of the ‘hmac’ and ‘base32’ libraries.

* Menu:

* API documentation: API documentation<202>.
* Loading: Loading<206>.
* Testing: Testing<197>.
* Public predicates::
* Secrets::
* Generation::
* Verification::
* Hash support::
* Bounded-backend limitation::


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<202>,  Next: Loading<206>,  Up: otp

6.186.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#otp’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<206>,  Next: Testing<197>,  Prev: API documentation<202>,  Up: otp

6.186.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ utility
file:

     | ?- logtalk_load(otp(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<197>,  Next: Public predicates,  Prev: Loading<206>,  Up: otp

6.186.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(otp(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Public predicates,  Next: Secrets,  Prev: Testing<197>,  Up: otp

6.186.4 Public predicates
-------------------------

The library currently provides the following public predicates:

   - ‘otp::hotp/5’

   - ‘otp::totp/5’

   - ‘otp::hotp_verify/7’

   - ‘otp::totp_verify/7’

The arguments are:

   - ‘hotp(Hash, Secret, Counter, Digits, OTP)’

   - ‘totp(Hash, Secret, UnixTime, Digits, OTP)’

   - ‘hotp_verify(Hash, Secret, Counter, Window, Digits, OTP,
     MatchedCounter)’

   - ‘totp_verify(Hash, Secret, UnixTime, Window, Digits, OTP,
     MatchedTimeStep)’

The ‘totp/5’ and ‘totp_verify/7’ predicates take an explicit Unix time
in seconds.  The current implementation uses the standard 30-second time
step and the Unix epoch ‘T0 = 0’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Secrets,  Next: Generation,  Prev: Public predicates,  Up: otp

6.186.5 Secrets
---------------

The ‘Secret’ argument can be given either as a raw byte list or using
one of the following Base32 wrapper terms:

   - ‘base32(atom(Atom))’

   - ‘base32(chars(Chars))’

   - ‘base32(codes(Codes))’

For example:

     | ?- otp::hotp(sha1, base32(atom('GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ')), 0, 6, OTP).
     OTP = '755224'
     yes

     | ?- atom_codes('12345678901234567890', Secret),
          otp::hotp(sha1, Secret, 1, 6, OTP).
     OTP = '287082'
     Secret = [49,50,51,52,53,54,55,56,57,48,49,50,51,52,53,54,55,56,57,48]
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: Generation,  Next: Verification,  Prev: Secrets,  Up: otp

6.186.6 Generation
------------------

HOTP generation uses the supplied moving counter directly:

     | ?- atom_codes('12345678901234567890', Secret),
          otp::hotp(sha1, Secret, 9, 6, OTP).
     OTP = '520489'
     yes

TOTP generation first converts the explicit Unix time to the
corresponding 30-second time step and then computes an HOTP value for
that step:

     | ?- atom_codes('12345678901234567890', Secret),
          otp::totp(sha1, Secret, 59, 8, OTP).
     OTP = '94287082'
     yes

Generated OTP values are returned as zero-padded atoms so that leading
zeros are preserved.


File: TheLogtalkHandbook-3.101.0.info,  Node: Verification,  Next: Hash support,  Prev: Generation,  Up: otp

6.186.7 Verification
--------------------

The ‘otp::hotp_verify/7’ predicate searches forward from the supplied
counter through a bounded counter window and returns the matching
counter on success.

     | ?- atom_codes('12345678901234567890', Secret),
          otp::hotp_verify(sha1, Secret, 0, 9, 6, '520489', MatchedCounter).
     MatchedCounter = 9
     Secret = [49,50,51,52,53,54,55,56,57,48,49,50,51,52,53,54,55,56,57,48]
     yes

The ‘otp::totp_verify/7’ predicate searches within a symmetric time-step
window around the current time step and returns the matching time step
on success.

     | ?- atom_codes('12345678901234567890', Secret),
          otp::totp_verify(sha1, Secret, 29, 1, 8, '94287082', MatchedTimeStep).
     MatchedTimeStep = 1
     Secret = [49,50,51,52,53,54,55,56,57,48,49,50,51,52,53,54,55,56,57,48]
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: Hash support,  Next: Bounded-backend limitation,  Prev: Verification,  Up: otp

6.186.8 Hash support
--------------------

The ‘Hash’ argument must identify a currently loaded hash object that
provides ‘digest/2’, ‘digest_size/1’, and ‘block_size/1’, and whose
digest size is at least 20 bytes.

In practice, the standard RFC examples in this library use ‘sha1’,
‘sha256’, and ‘sha512’ on unbounded-integer backends.  Hashes such as
‘md5’ are rejected because their digest size is too short for this
library’s validation rules.


File: TheLogtalkHandbook-3.101.0.info,  Node: Bounded-backend limitation,  Prev: Hash support,  Up: otp

6.186.9 Bounded-backend limitation
----------------------------------

The current repository hash implementation only defines ‘sha1’,
‘sha256’, and ‘sha512’ on unbounded-integer backends.  On
bounded-integer backends, the ‘hashes’ library loads ‘hash_32.lgt’,
which does not provide those digest objects.

As a consequence:

   - the ‘otp’ library itself still loads on bounded backends

   - standard HOTP/TOTP generation with ‘sha1’, ‘sha256’, or ‘sha512’ is
     not available there

   - calls such as ‘otp::hotp(sha1, Secret, Counter, Digits, OTP)’ fail
     with ‘domain_error(otp_hash, sha1)’ on bounded-integer backends

This is a limitation of the currently available hash objects in the
repository, not of the OTP control-flow logic itself.


File: TheLogtalkHandbook-3.101.0.info,  Node: partitions,  Next: pattern_mining_protocols,  Prev: otp,  Up: Libraries

6.187 ‘partitions’
==================

This library provides predicates for generating and querying set
partitions of lists.  A set partition divides a list into non-empty,
non-overlapping blocks whose union is the original list.  The following
categories of predicates are provided:

   - 'Generation operations' - Predicates for generating all set
     partitions and set partitions with an exact number of blocks.

   - 'Ordering variants' - Predicates that support an additional order
     argument (‘default’ or ‘lexicographic’) for controlling output
     order.

   - 'Distinct-value generation' - Predicates for generating set
     partitions while deduplicating equal-valued partitions after
     canonicalizing block order.

   - 'Indexed access' - Predicates for retrieving partitions and
     distinct partitions by zero-based index and for recovering the
     index of a partition.

   - 'Random selection' - Predicates for selecting random partitions and
     taking random samples, with distinct-value and exact-block-count
     variants.

   - 'Lexicographic stepping' - Predicates for moving to the next or
     previous distinct partition value in lexicographic order.

   - 'Counting operations' - Predicates for counting set partitions and
     distinct set partitions, including exact-block counts.

Base predicates are position-sensitive, matching the existing
combinatorics libraries.  Inputs with repeated values can therefore
yield duplicate-valued partitions.  Distinct predicates collapse those
equal-valued results.

The lexicographic stepping predicates operate on the distinct partition
view, using the same canonical block ordering as the distinct generation
predicates.

The counting predicates are connected to Bell numbers (for all
partitions of an N-element list) and Stirling numbers of the second kind
(for partitions with an exact number of blocks).

Dedicated ‘arrangements’, ‘cartesian_products’, ‘combinations’,
‘derangements’, ‘multisets’, ‘permutations’, and ‘subsequences’
libraries are also available for focused APIs on related operations.

* Menu:

* API documentation: API documentation<203>.
* Loading: Loading<207>.
* Testing: Testing<198>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<203>,  Next: Loading<207>,  Up: partitions

6.187.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#partitions’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<207>,  Next: Testing<198>,  Prev: API documentation<203>,  Up: partitions

6.187.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(partitions(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<198>,  Prev: Loading<207>,  Up: partitions

6.187.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(partitions(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: pattern_mining_protocols,  Next: pca_projection,  Prev: partitions,  Up: Libraries

6.188 ‘pattern_mining_protocols’
================================

This library provides the generic core entities used in the
implementation of machine learning pattern-finding algorithms.
Pattern-mining algorithm implementations typically import the
‘pattern_miner_common’ category, which implements the
‘pattern_miner_protocol’ protocol and provides shared defaults, option
handling, diagnostics accessors, and export helpers.

The family-specific dataset protocols and bundled smoke-test datasets
are provided by the ‘frequent_pattern_mining_protocols’ and
‘sequential_pattern_mining_protocols’ support libraries.

* Menu:

* API documentation: API documentation<204>.
* Loading: Loading<208>.
* Testing: Testing<199>.
* Common options: Common options<2>.
* Diagnostics: Diagnostics<9>.
* Related support libraries::


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<204>,  Next: Loading<208>,  Up: pattern_mining_protocols

6.188.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#pattern_mining_protocols’ link
in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<208>,  Next: Testing<199>,  Prev: API documentation<204>,  Up: pattern_mining_protocols

6.188.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(pattern_mining_protocols(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<199>,  Next: Common options<2>,  Prev: Loading<208>,  Up: pattern_mining_protocols

6.188.3 Testing
---------------

To run the library smoke tests, load the ‘tester.lgt’ file:

     | ?- logtalk_load(pattern_mining_protocols(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Common options<2>,  Next: Diagnostics<9>,  Prev: Testing<199>,  Up: pattern_mining_protocols

6.188.4 Common options
----------------------

The ‘pattern_miner_common’ category supports the following options used
by importing pattern miners to control support thresholds and pattern
length filtering:

   - ‘minimum_support(0.5)’ sets the relative minimum support threshold
     as a proportion in the interval ‘]0.0, 1.0]’.

   - ‘minimum_support_count(N)’ sets the absolute minimum support count.
     If both support options are provided, this option takes precedence.

   - ‘maximum_pattern_length(1000)’ sets the maximum pattern length to
     mine.  The effective value is capped by the longest transaction or
     sequence in the dataset.

   - ‘minimum_pattern_length(1)’ sets the minimum pattern length
     retained in the mined result.

The current ‘apriori_pattern_miner’, ‘eclat_pattern_miner’,
‘fp_growth_pattern_miner’, and ‘prefix_span_pattern_miner’ libraries all
use these shared defaults.


File: TheLogtalkHandbook-3.101.0.info,  Node: Diagnostics<9>,  Next: Related support libraries,  Prev: Common options<2>,  Up: pattern_mining_protocols

6.188.5 Diagnostics
-------------------

The ‘pattern_miner_protocol’ protocol also defines the ‘diagnostics/2’,
‘diagnostic/2’, and ‘pattern_miner_options/2’ predicates.  These expose
representation-independent metadata about mined results.

All pattern miners now provide at least the following generic
diagnostics terms:

   - ‘model(Model)’

   - ‘options(Options)’

   - ‘item_domain_size(Size)’

   - ‘pattern_count(Count)’

   - ‘pattern_length_histogram(Histogram)’

   - ‘support_range(MinimumSupport, MaximumSupport)’

Each miner also provides algorithm-specific diagnostics terms describing
its mining strategy and support representation, such as
candidate-generation style, projected-database growth, closure
filtering, or vertical support layout.


File: TheLogtalkHandbook-3.101.0.info,  Node: Related support libraries,  Prev: Diagnostics<9>,  Up: pattern_mining_protocols

6.188.6 Related support libraries
---------------------------------

   - ‘frequent_pattern_mining_protocols’: Provides the
     ‘transaction_dataset_protocol’ protocol plus bundled transaction
     smoke-test datasets for frequent itemset miners.

   - ‘sequential_pattern_mining_protocols’: Provides the
     ‘sequence_dataset_protocol’ protocol plus bundled sequence
     smoke-test datasets for sequential pattern miners.


File: TheLogtalkHandbook-3.101.0.info,  Node: pca_projection,  Next: permutations,  Prev: pattern_mining_protocols,  Up: Libraries

6.189 ‘pca_projection’
======================

Principal Component Analysis reducer for continuous datasets.  The
library implements the ‘dimension_reducer_protocol’ defined in the
‘dimension_reduction_protocols’ library and learns a linear projection
by centering the training data, optionally standardizing continuous
attributes, computing the covariance matrix, and extracting principal
components using deterministic power iteration with deflation.

* Menu:

* API documentation: API documentation<205>.
* Loading: Loading<209>.
* Testing: Testing<200>.
* Features: Features<57>.
* Options: Options<55>.
* Usage: Usage<84>.
* Dimension reducer representation: Dimension reducer representation<5>.
* References: References<40>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<205>,  Next: Loading<209>,  Up: pca_projection

6.189.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#pca_projection’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<209>,  Next: Testing<200>,  Prev: API documentation<205>,  Up: pca_projection

6.189.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(pca_projection(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<200>,  Next: Features<57>,  Prev: Loading<209>,  Up: pca_projection

6.189.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(pca_projection(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<57>,  Next: Options<55>,  Prev: Testing<200>,  Up: pca_projection

6.189.4 Features
----------------

   - 'Continuous Datasets': Accepts datasets containing only continuous
     attributes.

   - 'Centering and Optional Scaling': Centers all attributes and
     optionally standardizes them before extracting principal
     directions.

   - 'Portable Eigensolver': Uses deterministic power iteration with
     deflation instead of backend-specific linear algebra libraries.

   - 'Projection API': Transforms a new instance into a list of
     ‘component_N-Value’ pairs.

   - 'Model Export': Learned reducers can be exported as predicate
     clauses or written to a file.

   - 'Missing Values': Missing or nonnumeric values are rejected.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<55>,  Next: Usage<84>,  Prev: Features<57>,  Up: pca_projection

6.189.5 Options
---------------

The ‘learn/3’ predicate accepts the following options:

   - ‘n_components/1’: Number of principal components to extract.
     Requests that exceed the number of features raise
     ‘domain_error(component_count, Requested-Maximum)’.  The default is
     ‘2’.

   - ‘feature_scaling/1’: Whether to standardize continuous attributes
     before extracting components.  Options: ‘true’ (default) or
     ‘false’.

   - ‘maximum_iterations/1’: Maximum number of power-iteration steps
     used when estimating each principal direction.  The default is
     ‘1000’.

   - ‘tolerance/1’: Positive convergence tolerance used both for
     power-iteration stopping and for deciding when deflated eigenvalues
     are negligible.  The default is ‘1.0e-8’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<84>,  Next: Dimension reducer representation<5>,  Prev: Options<55>,  Up: pca_projection

6.189.6 Usage
-------------

The following examples use the sample datasets shipped with the
‘dimension_reduction_protocols’ library:

     | ?- logtalk_load(dimension_reduction_protocols('test_datasets/correlated_plane')),
          logtalk_load(dimension_reduction_protocols('test_datasets/high_dimensional_measurements')).

* Menu:

* Learning a reducer: Learning a reducer<4>.
* Transforming new instances: Transforming new instances<4>.
* Exporting and reusing the reducer: Exporting and reusing the reducer<4>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Learning a reducer<4>,  Next: Transforming new instances<4>,  Up: Usage<84>

6.189.6.1 Learning a reducer
............................

     | ?- pca_projection::learn(correlated_plane, DimensionReducer).

     | ?- pca_projection::learn(correlated_plane, DimensionReducer, [n_components(1), feature_scaling(false), maximum_iterations(200), tolerance(1.0e-7)]).


File: TheLogtalkHandbook-3.101.0.info,  Node: Transforming new instances<4>,  Next: Exporting and reusing the reducer<4>,  Prev: Learning a reducer<4>,  Up: Usage<84>

6.189.6.2 Transforming new instances
....................................

     | ?- pca_projection::learn(high_dimensional_measurements, DimensionReducer),
          pca_projection::transform(DimensionReducer, [f1-0.9, f2-1.1, f3-1.0, f4-2.0, f5-2.2, f6-2.1], ReducedInstance).

     | ?- pca_projection::learn(correlated_plane, DimensionReducer, [n_components(1)]),
          pca_projection::transform(DimensionReducer, [x-1.0, y-2.0, z-3.0], ReducedInstance).


File: TheLogtalkHandbook-3.101.0.info,  Node: Exporting and reusing the reducer<4>,  Prev: Transforming new instances<4>,  Up: Usage<84>

6.189.6.3 Exporting and reusing the reducer
...........................................

     | ?- pca_projection::learn(correlated_plane, DimensionReducer, [n_components(1)]),
          pca_projection::export_to_file(correlated_plane, DimensionReducer, reducer, 'pca_reducer.pl').

     | ?- logtalk_load('pca_reducer.pl'),
          reducer(Reducer),
          pca_projection::transform(Reducer, [x-1.0, y-2.0, z-3.0], ReducedInstance).


File: TheLogtalkHandbook-3.101.0.info,  Node: Dimension reducer representation<5>,  Next: References<40>,  Prev: Usage<84>,  Up: pca_projection

6.189.7 Dimension reducer representation
----------------------------------------

The learned dimension reducer is represented by a compound term with the
functor chosen by the implementation and arity 4.  For example:

     pca_reducer(Encoders, Components, ExplainedVariances, Diagnostics)

Where:

   - ‘Encoders’: List of continuous attribute encoders storing attribute
     name, mean, and scale.

   - ‘Components’: List of principal direction vectors in descending
     variance order.

   - ‘ExplainedVariances’: List of eigenvalues matching the extracted
     components.

   - ‘Diagnostics’: Learned reducer metadata including the effective
     training options and learned model details.

When exported using ‘export_to_clauses/4’ or ‘export_to_file/4’, this
reducer term is serialized directly as the single argument of the
generated predicate clause so that the exported model can be loaded and
reused as-is.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<40>,  Prev: Dimension reducer representation<5>,  Up: pca_projection

6.189.8 References
------------------

  1. Pearson, K. (1901) - “On lines and planes of closest fit to systems
     of points in space”.

  2. Hotelling, H. (1933) - “Analysis of a complex of statistical
     variables into principal components”.


File: TheLogtalkHandbook-3.101.0.info,  Node: permutations,  Next: plackett_luce_ranker,  Prev: pca_projection,  Up: Libraries

6.190 ‘permutations’
====================

This library provides predicates for generating and querying
permutations over lists.  The following categories of predicates are
provided:

   - 'Generation operations' - Predicates for generating permutations
     and k-permutations.

   - 'Ordering variants' - Predicates that support an additional order
     argument (‘default’, ‘lexicographic’, or ‘shortlex’) for
     controlling output order.

   - 'Distinct-value generation' - Predicates for generating
     permutations while deduplicating equal-valued results.

   - 'Lexicographic stepping' - Predicates for navigating permutations
     in lexicographic order.

   - 'Indexed access' - Predicates for direct access to permutations at
     specific positions, including distinct permutations.

   - 'Counting operations' - Predicates for counting permutations and
     distinct permutations.

   - 'Random selection' - Predicates for randomly selecting and sampling
     permutations and distinct permutations.

Dedicated ‘arrangements’, ‘cartesian_products’, ‘combinations’,
‘derangements’, ‘multisets’, ‘partitions’, and ‘subsequences’ libraries
are also available for focused APIs on related operations.  The
‘arrangements’ library is the repetition-allowed counterpart to this
library.

* Menu:

* API documentation: API documentation<206>.
* Loading: Loading<210>.
* Testing: Testing<201>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<206>,  Next: Loading<210>,  Up: permutations

6.190.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#permutations’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<210>,  Next: Testing<201>,  Prev: API documentation<206>,  Up: permutations

6.190.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(permutations(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<201>,  Prev: Loading<210>,  Up: permutations

6.190.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(permutations(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: plackett_luce_ranker,  Next: plackett_luce_last_ranker,  Prev: permutations,  Up: Libraries

6.191 ‘plackett_luce_ranker’
============================

Tie-aware Plackett-Luce grouped-ranking ranker.  It processes each group
as a sequence of top-choice selections from highest relevance to lowest
relevance, using grouped tie blocks and a deterministic fixed-point
update on positive item strengths.

The library implements the ‘ranker_protocol’ defined in the
‘ranking_protocols’ library.  It provides predicates for learning a
ranker from grouped rankings, using it to order candidate items, and
exporting it as a list of predicate clauses or to a file.

Datasets are represented as objects implementing the
‘ranking_dataset_protocol’ protocol from the ‘ranking_protocols’
library.  See the ‘test_datasets’ directory for examples.  The training
dataset must declare each group once, use only declared groups and items
in relevance judgments, assign non-negative integer relevance values,
and induce a strongly connected directed strict-order graph across
groups so that a finite Plackett-Luce maximum-likelihood estimate
exists.

* Menu:

* API documentation: API documentation<207>.
* Loading: Loading<211>.
* Testing: Testing<202>.
* Features: Features<58>.
* Dataset requirements: Dataset requirements<2>.
* Usage: Usage<85>.
* Diagnostics syntax: Diagnostics syntax<17>.
* Options: Options<56>.
* Ranker representation: Ranker representation<11>.
* See also: See also<4>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<207>,  Next: Loading<211>,  Up: plackett_luce_ranker

6.191.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#plackett_luce_ranker’ link in a
web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<211>,  Next: Testing<202>,  Prev: API documentation<207>,  Up: plackett_luce_ranker

6.191.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(plackett_luce_ranker(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<202>,  Next: Features<58>,  Prev: Loading<211>,  Up: plackett_luce_ranker

6.191.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(plackett_luce_ranker(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<58>,  Next: Dataset requirements<2>,  Prev: Testing<202>,  Up: plackett_luce_ranker

6.191.4 Features
----------------

   - 'Grouped Top-Choice Learning': Learns positive item strengths from
     grouped rankings by processing each group from highest relevance to
     lowest relevance.

   - 'Tie-Aware Likelihood': Uses grouped tie blocks so equal relevance
     judgments are handled as unordered top-choice blocks instead of
     being broken arbitrarily.  Each tie block contributes a
     size-constrained choice likelihood term against the remaining
     lower-relevance items.

   - 'Deterministic Ranking': Orders candidate items by learned strength
     with deterministic tie-breaking.

   - 'Strict Dataset Validation': Rejects malformed grouped datasets,
     unsupported options, duplicate candidates, and invalid ranker
     terms.

   - 'Regular MLE Fidelity': Rejects grouped datasets whose strict-order
     graph does not admit a finite Plackett-Luce maximum-likelihood
     estimate instead of masking non-identifiability with implicit
     regularization.

   - 'Missing relevance semantics': Missing relevance facts are treated
     as zero by default using the ‘missing_relevance(zero)’ option and
     can be rejected using the ‘missing_relevance(error)’ option.

   - 'Training Diagnostics': Learned rankers include convergence,
     iteration, final update delta, and dataset summary metadata
     accessible using the ‘diagnostics/2’ predicate.

   - 'Ranker Export': Learned rankers can be exported as self-contained
     terms.

   - 'Shared Grouped Infrastructure': Reuses the shared grouped
     tie-block representation and iterative positive-strength
     scaffolding from the ‘ranking_protocols’ library.


File: TheLogtalkHandbook-3.101.0.info,  Node: Dataset requirements<2>,  Next: Usage<85>,  Prev: Features<58>,  Up: plackett_luce_ranker

6.191.5 Dataset requirements
----------------------------

This implementation requires more than grouped-dataset well-formedness.
In order to admit a finite Plackett-Luce maximum-likelihood estimate,
the directed strict-order graph induced by the grouped rankings must be
strongly connected.  Intuitively, no partition of the items may dominate
all others in only one direction across the observed groups.

Unlike ‘borda_ranker’, this model therefore rejects grouped datasets
that consist of disconnected query universes or one-way dominance
chains, because those data do not identify a finite global strength
scale.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<85>,  Next: Diagnostics syntax<17>,  Prev: Dataset requirements<2>,  Up: plackett_luce_ranker

6.191.6 Usage
-------------

* Menu:

* Learning a ranker: Learning a ranker<11>.
* Inspecting diagnostics: Inspecting diagnostics<9>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Learning a ranker<11>,  Next: Inspecting diagnostics<9>,  Up: Usage<85>

6.191.6.1 Learning a ranker
...........................

     % Learn from a grouped ranking dataset object
     | ?- plackett_luce_ranker::learn(my_dataset, Ranker).
     ...

     % Learn with custom iteration and missing-relevance options
     | ?- plackett_luce_ranker::learn(my_dataset, Ranker, [maximum_iterations(500), tolerance(1.0e-7), missing_relevance(error)]).
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Inspecting diagnostics<9>,  Prev: Learning a ranker<11>,  Up: Usage<85>

6.191.6.2 Inspecting diagnostics
................................

     % Inspect convergence and dataset summary metadata
     | ?- plackett_luce_ranker::learn(my_dataset, Ranker),
          plackett_luce_ranker::diagnostics(Ranker, Diagnostics).
     Diagnostics = [...]
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Diagnostics syntax<17>,  Next: Options<56>,  Prev: Usage<85>,  Up: plackett_luce_ranker

6.191.7 Diagnostics syntax
--------------------------

The ‘diagnostics/2’ predicate returns a list of metadata terms with the
form:

     [
         model(plackett_luce_ranker),
         options(Options),
         convergence(Status),
         iterations(Iterations),
         final_delta(FinalDelta),
         dataset_summary(DatasetSummary)
     ]

Where:

   - ‘model(plackett_luce_ranker)’ identifies the learning algorithm
     that produced the ranker.

   - ‘options(Options)’ stores the effective learning options after
     merging the user options with the library defaults.

   - ‘convergence(Status)’ records the training stop condition.  The
     current values are ‘converged’ and ‘maximum_iterations_exhausted’.

   - ‘iterations(Iterations)’ stores the number of update iterations
     that were executed.

   - ‘final_delta(FinalDelta)’ stores the maximum absolute strength
     update in the last iteration.

   - ‘dataset_summary(DatasetSummary)’ stores a summary list describing
     the validated training dataset.

Use the ‘ranking_protocols’ ‘diagnostic/2’ and ‘ranker_options/2’ helper
predicates when you only need a single metadata term or the effective
options.

* Menu:

* Ranking candidate items: Ranking candidate items<10>.
* Exporting the ranker: Exporting the ranker<9>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Ranking candidate items<10>,  Next: Exporting the ranker<9>,  Up: Diagnostics syntax<17>

6.191.7.1 Ranking candidate items
.................................

     % Rank a candidate set from most preferred to least preferred
     | ?- plackett_luce_ranker::learn(my_dataset, Ranker),
          plackett_luce_ranker::rank(Ranker, [item_a, item_b, item_c], Ranking).
     Ranking = [...]
     ...

Candidate lists must be proper lists of unique, ground items declared by
the training dataset.  Invalid ranker terms, duplicate candidates, and
candidates containing variables are rejected with errors instead of
being silently accepted.


File: TheLogtalkHandbook-3.101.0.info,  Node: Exporting the ranker<9>,  Prev: Ranking candidate items<10>,  Up: Diagnostics syntax<17>

6.191.7.2 Exporting the ranker
..............................

Learned rankers can be exported as a list of clauses or to a file for
later use.

     % Export as predicate clauses
     | ?- plackett_luce_ranker::learn(my_dataset, Ranker),
          plackett_luce_ranker::export_to_clauses(my_dataset, Ranker, my_ranker, Clauses).
     Clauses = [my_ranker(plackett_luce_ranker(...))]
     ...

     % Export to a file
     | ?- plackett_luce_ranker::learn(my_dataset, Ranker),
          plackett_luce_ranker::export_to_file(my_dataset, Ranker, my_ranker, 'ranker.pl').
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<56>,  Next: Ranker representation<11>,  Prev: Diagnostics syntax<17>,  Up: plackett_luce_ranker

6.191.8 Options
---------------

The following options can be passed to the ‘learn/3’ predicate:

   - ‘maximum_iterations(MaximumIterations)’: Positive integer iteration
     bound.

   - ‘tolerance(Tolerance)’: Positive convergence tolerance.

   - ‘missing_relevance(zero|error)’: Policy used when a declared item
     in a group has no explicit relevance judgment.


File: TheLogtalkHandbook-3.101.0.info,  Node: Ranker representation<11>,  Next: See also<4>,  Prev: Options<56>,  Up: plackett_luce_ranker

6.191.9 Ranker representation
-----------------------------

The learned ranker is represented by a compound term of the form:

     plackett_luce_ranker(Items, Strengths, Diagnostics)

Where:

   - ‘Items’: List of ranked items.

   - ‘Scores’: List of normalized ‘Item-Strength’ pairs.

   - ‘Diagnostics’: List of metadata terms, including the effective
     options, convergence status, iteration count, final update delta,
     and dataset summary.

When exported using ‘export_to_clauses/4’ or ‘export_to_file/4’, this
ranker term is serialized directly as the single argument of the
generated predicate clause so that the exported model can be loaded and
reused as-is.


File: TheLogtalkHandbook-3.101.0.info,  Node: See also<4>,  Prev: Ranker representation<11>,  Up: plackett_luce_ranker

6.191.10 See also
-----------------

For the complementary grouped last-choice variant over the same dataset
protocol, see the ‘plackett_luce_last_ranker’ library.


File: TheLogtalkHandbook-3.101.0.info,  Node: plackett_luce_last_ranker,  Next: pls_projection,  Prev: plackett_luce_ranker,  Up: Libraries

6.192 ‘plackett_luce_last_ranker’
=================================

Tie-aware Plackett-Luce-last grouped-ranking ranker.  It processes each
group as a sequence of last-choice eliminations from lowest relevance to
highest relevance, using grouped tie blocks and a deterministic
fixed-point update on positive item strengths.

The library implements the ‘ranker_protocol’ defined in the
‘ranking_protocols’ library.  It provides predicates for learning a
ranker from grouped rankings, using it to order candidate items, and
exporting it as a list of predicate clauses or to a file.

Datasets are represented as objects implementing the
‘ranking_dataset_protocol’ protocol from the ‘ranking_protocols’
library.  See the ‘test_datasets’ directory for examples.  The training
dataset must declare each group once, use only declared groups and items
in relevance judgments, assign non-negative integer relevance values,
and induce a strongly connected directed strict-order graph across
groups so that a finite Plackett-Luce-last maximum-likelihood estimate
exists.

* Menu:

* API documentation: API documentation<208>.
* Loading: Loading<212>.
* Testing: Testing<203>.
* Features: Features<59>.
* Dataset requirements: Dataset requirements<3>.
* Usage: Usage<86>.
* Diagnostics syntax: Diagnostics syntax<18>.
* Options: Options<57>.
* Ranker representation: Ranker representation<12>.
* See also: See also<5>.
* References: References<41>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<208>,  Next: Loading<212>,  Up: plackett_luce_last_ranker

6.192.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#plackett_luce_last_ranker’ link
in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<212>,  Next: Testing<203>,  Prev: API documentation<208>,  Up: plackett_luce_last_ranker

6.192.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(plackett_luce_last_ranker(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<203>,  Next: Features<59>,  Prev: Loading<212>,  Up: plackett_luce_last_ranker

6.192.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(plackett_luce_last_ranker(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<59>,  Next: Dataset requirements<3>,  Prev: Testing<203>,  Up: plackett_luce_last_ranker

6.192.4 Features
----------------

   - 'Grouped Last-Choice Learning': Learns positive item strengths from
     grouped rankings by processing each group from lowest relevance to
     highest relevance.

   - 'Tie-Aware Likelihood': Uses grouped tie blocks so equal relevance
     judgments are handled as unordered last-choice blocks instead of
     being broken arbitrarily.  Each tie block contributes a
     size-constrained last-choice likelihood term against the remaining
     higher-relevance items.

   - 'Deterministic Ranking': Orders candidate items by learned strength
     with deterministic tie-breaking.

   - 'Strict Dataset Validation': Rejects malformed grouped datasets,
     unsupported options, duplicate candidates, and invalid ranker
     terms.

   - 'Regular MLE Fidelity': Rejects grouped datasets whose strict-order
     graph does not admit a finite Plackett-Luce-last maximum-likelihood
     estimate instead of masking non-identifiability with implicit
     regularization.

   - 'Missing relevance semantics': Missing relevance facts are treated
     as zero by default using the ‘missing_relevance(zero)’ option and
     can be rejected using ‘missing_relevance(error)’.

   - 'Training Diagnostics': Learned rankers include convergence,
     iteration, final update delta, and dataset summary metadata
     accessible using the ‘diagnostics/2’ predicate.

   - 'Ranker Export': Learned rankers can be exported as self-contained
     terms.

   - 'Shared Grouped Infrastructure': Reuses the shared grouped
     tie-block representation and iterative positive-strength
     scaffolding from the ‘ranking_protocols’ library.


File: TheLogtalkHandbook-3.101.0.info,  Node: Dataset requirements<3>,  Next: Usage<86>,  Prev: Features<59>,  Up: plackett_luce_last_ranker

6.192.5 Dataset requirements
----------------------------

This implementation requires more than grouped-dataset well-formedness.
In order to admit a finite Plackett-Luce-last maximum-likelihood
estimate, the directed strict-order graph induced by the grouped
rankings must be strongly connected.  Intuitively, no partition of the
items may dominate all others in only one direction across the observed
groups.

Unlike ‘borda_ranker’, this model therefore rejects grouped datasets
that consist of disconnected query universes or one-way dominance
chains, because those data do not identify a finite global strength
scale.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<86>,  Next: Diagnostics syntax<18>,  Prev: Dataset requirements<3>,  Up: plackett_luce_last_ranker

6.192.6 Usage
-------------

* Menu:

* Learning a ranker: Learning a ranker<12>.
* Inspecting diagnostics: Inspecting diagnostics<10>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Learning a ranker<12>,  Next: Inspecting diagnostics<10>,  Up: Usage<86>

6.192.6.1 Learning a ranker
...........................

     % Learn from a grouped ranking dataset object
     | ?- plackett_luce_last_ranker::learn(my_dataset, Ranker).
     ...

     % Learn with custom iteration and missing-relevance options
     | ?- plackett_luce_last_ranker::learn(my_dataset, Ranker, [maximum_iterations(500), tolerance(1.0e-7), missing_relevance(error)]).
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Inspecting diagnostics<10>,  Prev: Learning a ranker<12>,  Up: Usage<86>

6.192.6.2 Inspecting diagnostics
................................

     % Inspect convergence and dataset summary metadata
     | ?- plackett_luce_last_ranker::learn(my_dataset, Ranker),
          plackett_luce_last_ranker::diagnostics(Ranker, Diagnostics).
     Diagnostics = [...]
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Diagnostics syntax<18>,  Next: Options<57>,  Prev: Usage<86>,  Up: plackett_luce_last_ranker

6.192.7 Diagnostics syntax
--------------------------

The ‘diagnostics/2’ predicate returns a list of metadata terms with the
form:

     [
         model(plackett_luce_last_ranker),
         options(Options),
         convergence(Status),
         iterations(Iterations),
         final_delta(FinalDelta),
         dataset_summary(DatasetSummary)
     ]

Where:

   - ‘model(plackett_luce_last_ranker)’ identifies the learning
     algorithm that produced the ranker.

   - ‘options(Options)’ stores the effective learning options after
     merging the user options with the library defaults.

   - ‘convergence(Status)’ records the training stop condition.  The
     current values are ‘converged’ and ‘maximum_iterations_exhausted’.

   - ‘iterations(Iterations)’ stores the number of update iterations
     that were executed.

   - ‘final_delta(FinalDelta)’ stores the maximum absolute strength
     update in the last iteration.

   - ‘dataset_summary(DatasetSummary)’ stores a summary list describing
     the validated training dataset.

Use the ‘ranking_protocols’ ‘diagnostic/2’ and ‘ranker_options/2’ helper
predicates when you only need a single metadata term or the effective
options.

* Menu:

* Ranking candidate items: Ranking candidate items<11>.
* Exporting the ranker: Exporting the ranker<10>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Ranking candidate items<11>,  Next: Exporting the ranker<10>,  Up: Diagnostics syntax<18>

6.192.7.1 Ranking candidate items
.................................

     % Rank a candidate set from most preferred to least preferred
     | ?- plackett_luce_last_ranker::learn(my_dataset, Ranker),
          plackett_luce_last_ranker::rank(Ranker, [item_a, item_b, item_c], Ranking).
     Ranking = [...]
     ...

Candidate lists must be proper lists of unique, ground items declared by
the training dataset.  Invalid ranker terms, duplicate candidates, and
candidates containing variables are rejected with errors instead of
being silently accepted.


File: TheLogtalkHandbook-3.101.0.info,  Node: Exporting the ranker<10>,  Prev: Ranking candidate items<11>,  Up: Diagnostics syntax<18>

6.192.7.2 Exporting the ranker
..............................

Learned rankers can be exported as a list of clauses or to a file for
later use.

     % Export as predicate clauses
     | ?- plackett_luce_last_ranker::learn(my_dataset, Ranker),
          plackett_luce_last_ranker::export_to_clauses(my_dataset, Ranker, my_ranker, Clauses).
     Clauses = [my_ranker(plackett_luce_last_ranker(...))]
     ...

     % Export to a file
     | ?- plackett_luce_last_ranker::learn(my_dataset, Ranker),
          plackett_luce_last_ranker::export_to_file(my_dataset, Ranker, my_ranker, 'ranker.pl').
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<57>,  Next: Ranker representation<12>,  Prev: Diagnostics syntax<18>,  Up: plackett_luce_last_ranker

6.192.8 Options
---------------

The following options can be passed to the ‘learn/3’ predicate:

   - ‘maximum_iterations(MaximumIterations)’: Positive integer iteration
     bound.

   - ‘tolerance(Tolerance)’: Positive convergence tolerance.

   - ‘missing_relevance(zero|error)’: Policy used when a declared item
     in a group has no explicit relevance judgment.


File: TheLogtalkHandbook-3.101.0.info,  Node: Ranker representation<12>,  Next: See also<5>,  Prev: Options<57>,  Up: plackett_luce_last_ranker

6.192.9 Ranker representation
-----------------------------

The learned ranker is represented by a compound term of the form:

     plackett_luce_last_ranker(Items, Strengths, Diagnostics)

Where:

   - ‘Items’: List of ranked items.

   - ‘Scores’: List of normalized ‘Item-Strength’ pairs.

   - ‘Diagnostics’: List of metadata terms, including the effective
     options, convergence status, iteration count, final update delta,
     and dataset summary.

When exported using ‘export_to_clauses/4’ or ‘export_to_file/4’, this
ranker term is serialized directly as the single argument of the
generated predicate clause so that the exported model can be loaded and
reused as-is.


File: TheLogtalkHandbook-3.101.0.info,  Node: See also<5>,  Next: References<41>,  Prev: Ranker representation<12>,  Up: plackett_luce_last_ranker

6.192.10 See also
-----------------

For the complementary grouped top-choice variant over the same dataset
protocol, see the ‘plackett_luce_ranker’ library.  For a deterministic
non-probabilistic grouped-ranking baseline over the same dataset
protocol, see the ‘borda_ranker’ library.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<41>,  Prev: See also<5>,  Up: plackett_luce_last_ranker

6.192.11 References
-------------------

  1. Plackett, R. L. (1975).  The analysis of permutations.  'Applied
     Statistics', 24(2), 193-202.

  2. Luce, R. D. (1959).  'Individual Choice Behavior: A Theoretical
     Analysis'.  Wiley.

  3. Hunter, D. R. (2004).  MM algorithms for generalized Bradley-Terry
     models.  'The Annals of Statistics', 32(1), 384-406.


File: TheLogtalkHandbook-3.101.0.info,  Node: pls_projection,  Next: prefix_span_pattern_miner,  Prev: plackett_luce_last_ranker,  Up: Libraries

6.193 ‘pls_projection’
======================

Partial Least Squares projection reducer for target-valued continuous
datasets.  The library implements the ‘dimension_reducer_protocol’
defined in the ‘dimension_reduction_protocols’ library and learns a
deterministic PLS1 projection by centering the training data, optionally
standardizing continuous attributes, centering the numeric target,
extracting latent directions using repeated cross-covariance
maximization with sequential deflation, and storing the resulting direct
projection rotations for future transforms.

Requires a dataset implementing
‘target_supervised_dimension_reduction_dataset_protocol’ and therefore
uses a numeric target during training.

* Menu:

* API documentation: API documentation<209>.
* Loading: Loading<213>.
* Testing: Testing<204>.
* Features: Features<60>.
* Options: Options<58>.
* Usage: Usage<87>.
* Dimension reducer representation: Dimension reducer representation<6>.
* References: References<42>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<209>,  Next: Loading<213>,  Up: pls_projection

6.193.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#pls_projection’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<213>,  Next: Testing<204>,  Prev: API documentation<209>,  Up: pls_projection

6.193.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(pls_projection(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<204>,  Next: Features<60>,  Prev: Loading<213>,  Up: pls_projection

6.193.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(pls_projection(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<60>,  Next: Options<58>,  Prev: Testing<204>,  Up: pls_projection

6.193.4 Features
----------------

   - 'Continuous Datasets': Accepts datasets containing only continuous
     attributes and rejects datasets that also declare the target name
     as an input feature.  Missing or nonnumeric values are also
     rejected.

   - 'Target-Supervised Learning': Uses a numeric target attribute
     declared by datasets implementing
     ‘target_supervised_dimension_reduction_dataset_protocol’.

   - 'Centering and Optional Scaling': Centers all attributes and
     optionally standardizes them before learning latent directions.

   - 'Deterministic Components': Learns components deterministically
     from feature-target cross-covariance without stochastic
     initialization.

   - 'Configurable Shortfall Handling': Lets callers choose whether an
     extraction shortfall raises an error or truncates the learned
     reducer with explicit diagnostics.

   - 'Projection API': Transforms a new instance into a list of
     ‘component_N-Value’ pairs using the learned direct PLS rotation
     vectors.

   - 'Model Export': Learned reducers can be exported as predicate
     clauses or written to a file.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<58>,  Next: Usage<87>,  Prev: Features<60>,  Up: pls_projection

6.193.5 Options
---------------

The ‘learn/3’ predicate accepts the following options:

   - ‘n_components/1’: Number of latent PLS components to extract.
     Requests that exceed ‘min(FeatureCount, SampleCount - 1)’ raise
     ‘domain_error(component_count, Requested-Maximum)’.  The default is
     ‘2’.

   - ‘feature_scaling/1’: Whether to standardize continuous attributes
     before projection.  Options: ‘true’ (default) or ‘false’.

   - ‘shortfall_policy/1’: Controls what happens when residual
     feature-target cross-covariance becomes negligible before all
     requested components are extracted.  Options: ‘truncate’ (default),
     which returns a reducer with fewer components and records a
     ‘shortfall(truncated(Requested, Learned, ScoreEnergy, Tolerance))’
     diagnostic, or ‘error’, which raises ‘domain_error(component_count,
     Requested-Learned)’.

   - ‘tolerance/1’: Positive numerical tolerance used to stop extracting
     components when the residual feature-target cross-covariance
     becomes negligible.  The default is ‘1.0e-8’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<87>,  Next: Dimension reducer representation<6>,  Prev: Options<58>,  Up: pls_projection

6.193.6 Usage
-------------

The following example uses the sample target-valued dataset shipped with
the ‘dimension_reduction_protocols’ library:

     | ?- logtalk_load(dimension_reduction_protocols('test_datasets/target_latent_measurements')).

* Menu:

* Learning a reducer: Learning a reducer<5>.
* Transforming new instances: Transforming new instances<5>.
* Exporting and reusing the reducer: Exporting and reusing the reducer<5>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Learning a reducer<5>,  Next: Transforming new instances<5>,  Up: Usage<87>

6.193.6.1 Learning a reducer
............................

     | ?- pls_projection::learn(target_latent_measurements, DimensionReducer).

     | ?- pls_projection::learn(target_latent_measurements, DimensionReducer, [n_components(1), feature_scaling(false)]).


File: TheLogtalkHandbook-3.101.0.info,  Node: Transforming new instances<5>,  Next: Exporting and reusing the reducer<5>,  Prev: Learning a reducer<5>,  Up: Usage<87>

6.193.6.2 Transforming new instances
....................................

     | ?- pls_projection::learn(target_latent_measurements, DimensionReducer, [n_components(2)]),
          pls_projection::transform(DimensionReducer, [f1-4.0, f2-8.0, f3-2.0, f4-(-2.0)], ReducedInstance).


File: TheLogtalkHandbook-3.101.0.info,  Node: Exporting and reusing the reducer<5>,  Prev: Transforming new instances<5>,  Up: Usage<87>

6.193.6.3 Exporting and reusing the reducer
...........................................

     | ?- pls_projection::learn(target_latent_measurements, DimensionReducer, [n_components(2)]),
          pls_projection::export_to_file(target_latent_measurements, DimensionReducer, reducer, 'pls_projection_reducer.pl').

     | ?- logtalk_load('pls_projection_reducer.pl'),
          reducer(Reducer),
          pls_projection::transform(Reducer, [f1-4.0, f2-8.0, f3-2.0, f4-(-2.0)], ReducedInstance).


File: TheLogtalkHandbook-3.101.0.info,  Node: Dimension reducer representation<6>,  Next: References<42>,  Prev: Usage<87>,  Up: pls_projection

6.193.7 Dimension reducer representation
----------------------------------------

The learned dimension reducer is represented by a compound term with the
functor chosen by the implementation and arity 3.  For example:

     pls_projection_reducer(Encoders, Rotations, Diagnostics)

Where:

   - ‘Encoders’: List of continuous attribute encoders storing attribute
     name, mean, and scale.

   - ‘Rotations’: List of direct PLS projection vectors derived from the
     learned latent weights and loadings.

   - ‘Diagnostics’: Learned metadata including the effective training
     options, target information, target loadings, and optional
     truncate-mode shortfall details.

When exported using ‘export_to_clauses/4’ or ‘export_to_file/4’, this
reducer term is serialized directly as the single argument of the
generated predicate clause so that the exported model can be loaded and
reused as-is.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<42>,  Prev: Dimension reducer representation<6>,  Up: pls_projection

6.193.8 References
------------------

  1. Wold, H. (1975) - “Soft modelling by latent variables; the
     nonlinear iterative partial least squares (NIPALS) approach”.

  2. Geladi, P. and Kowalski, B. R. (1986) - “Partial least-squares
     regression: a tutorial”.


File: TheLogtalkHandbook-3.101.0.info,  Node: prefix_span_pattern_miner,  Next: probabilistic_pca_projection,  Prev: pls_projection,  Up: Libraries

6.194 ‘prefix_span_pattern_miner’
=================================

PrefixSpan sequential pattern miner for sequence datasets.  The library
depends on the ‘sequential_pattern_mining_protocols’ support library,
implements the generic ‘pattern_miner_protocol’ defined in the
‘pattern_mining_protocols’ core library, and mines frequent sequential
patterns using recursive projected databases with both same-event and
next-event extensions.

Requires a dataset implementing ‘sequence_dataset_protocol’ with
sequences represented as ordered lists of canonical sorted itemsets over
a declared item domain.

* Menu:

* API documentation: API documentation<210>.
* Loading: Loading<214>.
* Testing: Testing<205>.
* Features: Features<61>.
* Options: Options<59>.
* Pattern miner representation: Pattern miner representation<6>.
* References: References<43>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<210>,  Next: Loading<214>,  Up: prefix_span_pattern_miner

6.194.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#prefix_span_pattern_miner’ link
in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<214>,  Next: Testing<205>,  Prev: API documentation<210>,  Up: prefix_span_pattern_miner

6.194.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(prefix_span_pattern_miner(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<205>,  Next: Features<61>,  Prev: Loading<214>,  Up: prefix_span_pattern_miner

6.194.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(prefix_span_pattern_miner(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<61>,  Next: Options<59>,  Prev: Testing<205>,  Up: prefix_span_pattern_miner

6.194.4 Features
----------------

   - 'Projected Database Mining': Mines sequential patterns by
     recursively projecting suffix databases.

   - 'Itemset and Sequence Extensions': Supports both extending the last
     itemset and appending a new singleton itemset.

   - 'Canonical Sequences': Validates that itemsets are sorted,
     duplicate-free, non-empty, and restricted to declared items.

   - 'Flexible Support Thresholds': Supports minimum support specified
     either as a relative proportion or as an absolute count.

   - 'Model Export': Mined pattern collections can be exported as
     predicate clauses or written to a file.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<59>,  Next: Pattern miner representation<6>,  Prev: Features<61>,  Up: prefix_span_pattern_miner

6.194.5 Options
---------------

The ‘mine/3’ predicate accepts the following options:

   - ‘minimum_support/1’: Relative minimum support threshold in the
     interval ‘]0.0, 1.0]’.  The default is ‘0.5’.

   - ‘minimum_support_count/1’: Absolute minimum support count.  When
     both support options are provided, this option takes precedence.

   - ‘maximum_pattern_length/1’: Maximum total number of items in a
     mined sequential pattern.  The default is ‘1000’, effectively
     capped by the longest sequence in the dataset.

   - ‘minimum_pattern_length/1’: Minimum total number of items retained
     in the mined result.  The default is ‘1’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Pattern miner representation<6>,  Next: References<43>,  Prev: Options<59>,  Up: prefix_span_pattern_miner

6.194.6 Pattern miner representation
------------------------------------

The mined pattern miner result is represented by a compound term with
the functor chosen by the implementation and arity 3.  For example:

     prefix_span_pattern_miner(ItemDomain, Patterns, Options)

Where:

   - ‘ItemDomain’: Canonical sorted list of declared dataset items.

   - ‘Patterns’: List of ‘sequence_pattern(Pattern, SupportCount)’ terms
     ordered first by total item count and then lexicographically.

   - ‘Options’: Effective mining options used to mine the frequent
     sequential patterns.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<43>,  Prev: Pattern miner representation<6>,  Up: prefix_span_pattern_miner

6.194.7 References
------------------

  1. Pei, J., Han, J., Mortazavi-Asl, B., et al.  (2001) - “PrefixSpan:
     Mining sequential patterns efficiently by prefix-projected pattern
     growth”.


File: TheLogtalkHandbook-3.101.0.info,  Node: probabilistic_pca_projection,  Next: process,  Prev: prefix_span_pattern_miner,  Up: Libraries

6.195 ‘probabilistic_pca_projection’
====================================

Probabilistic Principal Component Analysis reducer for continuous
datasets.  The library implements the ‘dimension_reducer_protocol’
defined in the ‘dimension_reduction_protocols’ library and learns a
linear latent-variable projection by centering the training data,
optionally standardizing continuous attributes, estimating the sample
covariance matrix, extracting deterministic leading eigenvectors using
portable power iteration with deflation, and converting them into the
closed-form maximum-likelihood PPCA loading matrix and posterior latent
projection.

* Menu:

* API documentation: API documentation<211>.
* Loading: Loading<215>.
* Testing: Testing<206>.
* Features: Features<62>.
* Options: Options<60>.
* Usage: Usage<88>.
* Dimension reducer representation: Dimension reducer representation<7>.
* References: References<44>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<211>,  Next: Loading<215>,  Up: probabilistic_pca_projection

6.195.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#probabilistic_pca_projection’
link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<215>,  Next: Testing<206>,  Prev: API documentation<211>,  Up: probabilistic_pca_projection

6.195.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(probabilistic_pca_projection(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<206>,  Next: Features<62>,  Prev: Loading<215>,  Up: probabilistic_pca_projection

6.195.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(probabilistic_pca_projection(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<62>,  Next: Options<60>,  Prev: Testing<206>,  Up: probabilistic_pca_projection

6.195.4 Features
----------------

   - 'Continuous Datasets': Accepts datasets containing only continuous
     attributes.  Missing or nonnumeric values are rejected.

   - 'Centering and Optional Scaling': Centers all attributes and
     optionally standardizes them before fitting the covariance model.

   - 'Probabilistic Latent Model': Estimates the PPCA loading matrix and
     isotropic observation noise variance from the learned covariance
     eigensystem.

   - 'Configurable Shortfall Handling': Lets callers choose whether a
     numerical-rank shortfall raises an error or returns a truncated
     reducer with explicit diagnostics.

   - 'Projection API': Transforms a new instance into posterior latent
     means returned as ‘component_N-Value’ pairs.

   - 'Model Export': Learned reducers can be exported as predicate
     clauses or written to a file.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<60>,  Next: Usage<88>,  Prev: Features<62>,  Up: probabilistic_pca_projection

6.195.5 Options
---------------

The ‘learn/3’ predicate accepts the following options:

   - ‘n_components/1’: Number of latent dimensions to extract.  Requests
     that exceed the structural PPCA limit ‘min(FeatureCount,
     SampleCount - 1)’ raise ‘domain_error(component_count,
     Requested-Maximum)’.  The default is ‘2’.

   - ‘feature_scaling/1’: Whether to standardize continuous attributes
     before fitting the covariance model.  Options: ‘true’ (default) or
     ‘false’.

   - ‘shortfall_policy/1’: Controls what happens when the covariance
     matrix yields fewer numerically significant components than
     requested after passing the structural PPCA bound above.  Options:
     ‘truncate’ (default), which returns a reducer with fewer components
     and records a ‘shortfall(truncated(Requested, Learned,
     ResidualEigenvalue, Tolerance))’ diagnostic, or ‘error’, which
     raises ‘domain_error(component_count, Requested-Learned)’.

   - ‘maximum_iterations/1’: Maximum number of power-iteration steps
     used when estimating each covariance eigenvector.  The default is
     ‘1000’.

   - ‘tolerance/1’: Positive convergence tolerance used both for
     power-iteration stopping and for deciding when residual eigenvalues
     are negligible.  The default is ‘1.0e-8’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<88>,  Next: Dimension reducer representation<7>,  Prev: Options<60>,  Up: probabilistic_pca_projection

6.195.6 Usage
-------------

The following examples use the sample datasets shipped with the
‘dimension_reduction_protocols’ library:

     | ?- logtalk_load(dimension_reduction_protocols('test_datasets/correlated_plane')).

* Menu:

* Learning a reducer: Learning a reducer<6>.
* Transforming new instances: Transforming new instances<6>.
* Exporting and reusing the reducer: Exporting and reusing the reducer<6>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Learning a reducer<6>,  Next: Transforming new instances<6>,  Up: Usage<88>

6.195.6.1 Learning a reducer
............................

     | ?- probabilistic_pca_projection::learn(correlated_plane, DimensionReducer).

     | ?- probabilistic_pca_projection::learn(correlated_plane, DimensionReducer, [n_components(1), feature_scaling(false), shortfall_policy(error)]).


File: TheLogtalkHandbook-3.101.0.info,  Node: Transforming new instances<6>,  Next: Exporting and reusing the reducer<6>,  Prev: Learning a reducer<6>,  Up: Usage<88>

6.195.6.2 Transforming new instances
....................................

     | ?- probabilistic_pca_projection::learn(correlated_plane, DimensionReducer, [n_components(2)]),
          probabilistic_pca_projection::transform(DimensionReducer, [x-2.0, y-4.0, z-6.0], ReducedInstance).


File: TheLogtalkHandbook-3.101.0.info,  Node: Exporting and reusing the reducer<6>,  Prev: Transforming new instances<6>,  Up: Usage<88>

6.195.6.3 Exporting and reusing the reducer
...........................................

     | ?- probabilistic_pca_projection::learn(correlated_plane, DimensionReducer, [n_components(1)]),
          probabilistic_pca_projection::export_to_file(correlated_plane, DimensionReducer, reducer, 'probabilistic_pca_reducer.pl').

     | ?- logtalk_load('probabilistic_pca_reducer.pl'),
          reducer(Reducer),
          probabilistic_pca_projection::transform(Reducer, [x-1.0, y-2.0, z-3.0], ReducedInstance).


File: TheLogtalkHandbook-3.101.0.info,  Node: Dimension reducer representation<7>,  Next: References<44>,  Prev: Usage<88>,  Up: probabilistic_pca_projection

6.195.7 Dimension reducer representation
----------------------------------------

The learned dimension reducer is represented by a compound term with the
functor chosen by the implementation and arity 6.  For example:

     probabilistic_pca_reducer(Encoders, Components, Loadings, NoiseVariance, ExplainedVariances, Diagnostics)

Where:

   - ‘Encoders’: List of continuous attribute encoders storing attribute
     name, mean, and scale.

   - ‘Components’: List of posterior latent projection vectors in
     descending explained-variance order.

   - ‘Loadings’: List of maximum-likelihood PPCA loading vectors aligned
     with the extracted latent dimensions.

   - ‘NoiseVariance’: Estimated isotropic observation noise variance.

   - ‘ExplainedVariances’: List of retained covariance eigenvalues
     matching the extracted latent dimensions.

   - ‘Diagnostics’: Learned metadata including the effective training
     options, sample count, retained explained variances, estimated
     noise variance, preprocessing details, and optional truncate-mode
     shortfall details.

When exported using ‘export_to_clauses/4’ or ‘export_to_file/4’, this
reducer term is serialized directly as the single argument of the
generated predicate clause so that the exported model can be loaded and
reused as-is.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<44>,  Prev: Dimension reducer representation<7>,  Up: probabilistic_pca_projection

6.195.8 References
------------------

  1. Tipping, M. E. and Bishop, C. M. (1999) - “Probabilistic Principal
     Component Analysis”.

  2. Bishop, C. M. (2006) - “Pattern Recognition and Machine Learning”.
     Section 12.2.


File: TheLogtalkHandbook-3.101.0.info,  Node: process,  Next: protobuf,  Prev: probabilistic_pca_projection,  Up: Libraries

6.196 ‘process’
===============

This library provides a portable abstraction over process handling
predicates found in some backend Prolog systems.  Currently supports
ECLiPSe, GNU Prolog, SICStus Prolog, SWI-Prolog, Trealla Prolog, and
XVM.

* Menu:

* API documentation: API documentation<212>.
* Loading: Loading<216>.
* Testing: Testing<207>.
* Usage: Usage<89>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<212>,  Next: Loading<216>,  Up: process

6.196.1 API documentation
-------------------------

Open the ‘../../docs/library_index.html#process’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<216>,  Next: Testing<207>,  Prev: API documentation<212>,  Up: process

6.196.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(process(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<207>,  Next: Usage<89>,  Prev: Loading<216>,  Up: process

6.196.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(process(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<89>,  Prev: Testing<207>,  Up: process

6.196.4 Usage
-------------

The ‘process’ object provides the following predicates for portable
process handling:

   - ‘create(Executable, Arguments, Options)’ - Creates a new process

   - ‘wait(Process, Status)’ - Waits for a process to terminate

   - ‘kill(Process, Signal)’ - Terminates a process with a specific
     signal

   - ‘kill(Process)’ - Terminates a process using the default signal
     (SIGKILL)

Exit status depends on the backend.  For a successfully terminated
process, ‘Status’ is either ‘0’ or ‘exit(0)’.  For unsuccessful
processes, ‘Status’ cannot be sensibly abstracted.  Consult the backens
documentation for the details.

The ‘create/3’ predicate supports the following options:

   - ‘process(Pid)’ - Unifies Pid with the process identifier (an opaque
     ground term)

   - ‘stdin(Stream)’ - Binds Stream to the process standard input

   - ‘stdout(Stream)’ - Binds Stream to the process standard output

   - ‘stderr(Stream)’ - Binds Stream to the process standard error

   - ‘type(Type)’ - Sets the type (‘binary’ or ‘text’) of the ‘stdin/1’
     and ‘stdout/1’ streams

Process identifiers (PIDs) should be treated as opaque ground terms.
Their internal representation varies between backend Prolog systems.

The ‘type/1’ option is ignored on ECLiPSe, GNU Prolog, Trealla Prolog,
and XVM as these systems don’t provide the necessary support to set the
streams type at process creation.

Example:

     | ?- process::create('/bin/echo', ['hello.'], [stdout(Out), process(PID)]),
          read_term(Out, Term, []),
          close(Out).
     Out = ..., PID = ..., Term = hello.


File: TheLogtalkHandbook-3.101.0.info,  Node: protobuf,  Next: qda_classifier,  Prev: process,  Up: Libraries

6.197 ‘protobuf’
================

The ‘protobuf’ library implements predicates for reading (parsing) and
writing (generating) data in the Google Protocol Buffers binary format.

This implementation is based on the Protocol Buffers Language Guide
(proto3) and the Protocol Buffers Encoding specification:

   - ‘https://protobuf.dev/programming-guides/proto3/’

   - ‘https://protobuf.dev/programming-guides/encoding/’

'This library requires a backend supporting unbounded integer
arithmetic.'

* Menu:

* API documentation: API documentation<213>.
* Loading: Loading<217>.
* Testing: Testing<208>.
* Protocol Buffers Overview::
* Schema Representation::
* Data Representation::
* Encoding: Encoding<9>.
* Decoding: Decoding<9>.
* Wire Format Details::
* Binary Format Compatibility::
* Examples and Test Files::
* Further Reading::


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<213>,  Next: Loading<217>,  Up: protobuf

6.197.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#protobuf’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<217>,  Next: Testing<208>,  Prev: API documentation<213>,  Up: protobuf

6.197.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(protobuf(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<208>,  Next: Protocol Buffers Overview,  Prev: Loading<217>,  Up: protobuf

6.197.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(protobuf(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Protocol Buffers Overview,  Next: Schema Representation,  Prev: Testing<208>,  Up: protobuf

6.197.4 Protocol Buffers Overview
---------------------------------

Protocol Buffers (protobuf) is a language-neutral, platform-neutral
extensible mechanism for serializing structured data.  It is widely used
for data storage, communication protocols, and more.


File: TheLogtalkHandbook-3.101.0.info,  Node: Schema Representation,  Next: Data Representation,  Prev: Protocol Buffers Overview,  Up: protobuf

6.197.5 Schema Representation
-----------------------------

In this library, Protocol Buffers schemas (normally defined in ‘.proto’
files) are represented as Logtalk terms.  The schema representation uses
a curly-bracketed syntax similar to JSON representation.

A message schema is represented as:

     {message-MessageName, fields-FieldList}

Where ‘FieldList’ is a list of field definitions, each with:

     {number-FieldNumber, name-FieldName, type-FieldType}

* Menu:

* Supported Types::
* Schema Examples: Schema Examples<2>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Supported Types,  Next: Schema Examples<2>,  Up: Schema Representation

6.197.5.1 Supported Types
.........................

* Menu:

* Scalar Value Types::
* Complex Types::


File: TheLogtalkHandbook-3.101.0.info,  Node: Scalar Value Types,  Next: Complex Types,  Up: Supported Types

6.197.5.2 Scalar Value Types
............................

   - ‘int32’ - Uses variable-length encoding.  Inefficient for negative
     numbers (use ‘sint32’ instead).

   - ‘int64’ - Uses variable-length encoding.  Inefficient for negative
     numbers (use ‘sint64’ instead).

   - ‘uint32’ - Uses variable-length encoding.

   - ‘uint64’ - Uses variable-length encoding.

   - ‘sint32’ - Uses variable-length encoding with ZigZag encoding.
     More efficient for negative numbers.

   - ‘sint64’ - Uses variable-length encoding with ZigZag encoding.
     More efficient for negative numbers.

   - ‘bool’ - Boolean value: ‘true’ or ‘false’.

   - ‘fixed32’ - Always four bytes.  More efficient than ‘uint32’ if
     values are often greater than 2^28.

   - ‘fixed64’ - Always eight bytes.  More efficient than ‘uint64’ if
     values are often greater than 2^56.

   - ‘sfixed32’ - Always four bytes.  Signed fixed-width integer.

   - ‘sfixed64’ - Always eight bytes.  Signed fixed-width integer.

   - ‘float’ - 32-bit IEEE 754 floating point.

   - ‘double’ - 64-bit IEEE 754 floating point.

   - ‘string’ - UTF-8 encoded text.

   - ‘bytes’ - Arbitrary byte sequence.


File: TheLogtalkHandbook-3.101.0.info,  Node: Complex Types,  Prev: Scalar Value Types,  Up: Supported Types

6.197.5.3 Complex Types
.......................

   - ‘{message-Name, fields-Fields}’ - Embedded message (nested
     structure).


File: TheLogtalkHandbook-3.101.0.info,  Node: Schema Examples<2>,  Prev: Supported Types,  Up: Schema Representation

6.197.5.4 Schema Examples
.........................

Simple primitive type schemas:

   - ‘int32’

   - ‘string’

   - ‘bool’

Message schema example:

     {message-'Person', fields-[
         {number-1, name-name, type-string},
         {number-2, name-id, type-int32},
         {number-3, name-email, type-string}
     ]}

Nested message schema:

     {message-'AddressBook', fields-[
         {number-1, name-people, type-{message-'Person', fields-[
             {number-1, name-name, type-string},
             {number-2, name-id, type-int32}
         ]}}
     ]}


File: TheLogtalkHandbook-3.101.0.info,  Node: Data Representation,  Next: Encoding<9>,  Prev: Schema Representation,  Up: protobuf

6.197.6 Data Representation
---------------------------

Data to be serialized is represented as a list of field name-value pairs
using the ‘-’ operator.  For example:

     [name-'John Doe', id-42, email-'john@example.com']

For primitive types, data is represented directly as Logtalk values:

   - Integers: ‘42’, ‘-17’

   - Booleans: ‘true’, ‘false’

   - Floats: ‘3.14’, ‘-273.15’

   - Strings: ‘'Hello World'’, ‘hello’

   - Bytes: ‘[0x48, 0x65, 0x6c, 0x6c, 0x6f]’


File: TheLogtalkHandbook-3.101.0.info,  Node: Encoding<9>,  Next: Decoding<9>,  Prev: Data Representation,  Up: protobuf

6.197.7 Encoding
----------------

Encoding is accomplished using the ‘generate/3’ or ‘generate/4’
predicates.

* Menu:

* Simple Value Encoding::
* Message Encoding::
* Including Schema in Output::


File: TheLogtalkHandbook-3.101.0.info,  Node: Simple Value Encoding,  Next: Message Encoding,  Up: Encoding<9>

6.197.7.1 Simple Value Encoding
...............................

For example, encoding an integer using the ‘int32’ schema:

     | ?- protobuf::generate(bytes(Bytes), int32, 150).
     Bytes = [150, 1]
     yes

Encoding a string:

     | ?- protobuf::generate(bytes(Bytes), string, 'testing').
     Bytes = [116, 101, 115, 116, 105, 110, 103]
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: Message Encoding,  Next: Including Schema in Output,  Prev: Simple Value Encoding,  Up: Encoding<9>

6.197.7.2 Message Encoding
..........................

To encode a complete message:

     | ?- Schema = {message-'Person', fields-[
     |        {number-1, name-name, type-string},
     |        {number-2, name-id, type-int32}
     |    ]},
     |    Data = [name-'John', id-42],
     |    protobuf::generate(bytes(Bytes), Schema, Data).

     Schema = {...},
     Data = [name-'John', id-42],
     Bytes = [10, 4, 74, 111, 104, 110, 16, 84]
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: Including Schema in Output,  Prev: Message Encoding,  Up: Encoding<9>

6.197.7.3 Including Schema in Output
....................................

To include the schema in the output (as a custom wrapper message), use
the ‘generate/4’ predicate with the second argument set to ‘true’:

     | ?- protobuf::generate(file('output.pb'), true, Schema, Data).
     yes

This generates a wrapper message with:

   - Field 1: schema (as a JSON string)

   - Field 2: data (as encoded bytes)


File: TheLogtalkHandbook-3.101.0.info,  Node: Decoding<9>,  Next: Wire Format Details,  Prev: Encoding<9>,  Up: protobuf

6.197.8 Decoding
----------------

Decoding is accomplished using the ‘parse/2’ or ‘parse/3’ predicates.

* Menu:

* Parsing with Schema Embedded::
* Parsing with Known Schema::
* Parsing from Different Sources::


File: TheLogtalkHandbook-3.101.0.info,  Node: Parsing with Schema Embedded,  Next: Parsing with Known Schema,  Up: Decoding<9>

6.197.8.1 Parsing with Schema Embedded
......................................

When parsing a file that includes a schema (wrapper message format), use
‘parse/2’ which returns a ‘Schema-Data’ pair:

     | ?- protobuf::parse(file('input.pb'), Schema-Data).

When the schema is not present in the file, ‘Schema’ is unified with
‘false’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Parsing with Known Schema,  Next: Parsing from Different Sources,  Prev: Parsing with Schema Embedded,  Up: Decoding<9>

6.197.8.2 Parsing with Known Schema
...................................

When the schema is known and not embedded in the file, use ‘parse/3’:

     | ?- Schema = {message-'Person', fields-[
     |        {number-1, name-name, type-string},
     |        {number-2, name-id, type-int32}
     |    ]},
     |    protobuf::parse(file('person.pb'), Schema, Data).

     Schema = {...},
     Data = [name-'Alice', id-123]
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: Parsing from Different Sources,  Prev: Parsing with Known Schema,  Up: Decoding<9>

6.197.8.3 Parsing from Different Sources
........................................

The library supports three types of sources:

   - ‘bytes(List)’ - Parse from a list of bytes

   - ‘stream(Stream)’ - Parse from an open binary stream

   - ‘file(Path)’ - Parse from a file


File: TheLogtalkHandbook-3.101.0.info,  Node: Wire Format Details,  Next: Binary Format Compatibility,  Prev: Decoding<9>,  Up: protobuf

6.197.9 Wire Format Details
---------------------------

Protocol Buffers uses an efficient binary wire format with the following
wire types:

   - '0 (Varint)': ‘int32’, ‘int64’, ‘uint32’, ‘uint64’, ‘sint32’,
     ‘sint64’, ‘bool’

   - '1 (64-bit)': ‘fixed64’, ‘sfixed64’, ‘double’

   - '2 (Length-delimited)': ‘string’, ‘bytes’, embedded messages

   - '5 (32-bit)': ‘fixed32’, ‘sfixed32’, ‘float’

Each field is encoded with a tag (field number and wire type) followed
by the value.


File: TheLogtalkHandbook-3.101.0.info,  Node: Binary Format Compatibility,  Next: Examples and Test Files,  Prev: Wire Format Details,  Up: protobuf

6.197.10 Binary Format Compatibility
------------------------------------

The binary format produced by this library is compatible with:

   - Official Protocol Buffers implementations (C++, Java, Python, Go,
     etc.)

   - Other third-party implementations that follow the protobuf
     specification

Note: This library implements the core binary encoding format.  Advanced
features like ‘oneof’, ‘map’, ‘enum’, and ‘repeated’ fields are not yet
supported in this initial version.


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples and Test Files,  Next: Further Reading,  Prev: Binary Format Compatibility,  Up: protobuf

6.197.11 Examples and Test Files
--------------------------------

The ‘test_files’ subdirectory contains example schemas and data files
that demonstrate the library’s capabilities:

* Menu:

* person.proto: person proto.
* addressbook.proto: addressbook proto.
* Performance Considerations::


File: TheLogtalkHandbook-3.101.0.info,  Node: person proto,  Next: addressbook proto,  Up: Examples and Test Files

6.197.11.1 person.proto
.......................

A simple Person message schema.  This is a classic Protocol Buffers
example demonstrating basic field types:

   - 'Source': Adapted from the official Protocol Buffers tutorial

   - 'URL': ‘https://protobuf.dev/getting-started/’

   - 'License': Apache License 2.0 (compatible with Protocol Buffers
     documentation)


File: TheLogtalkHandbook-3.101.0.info,  Node: addressbook proto,  Next: Performance Considerations,  Prev: person proto,  Up: Examples and Test Files

6.197.11.2 addressbook.proto
............................

An AddressBook schema demonstrating nested messages.  Shows how to
represent complex hierarchical data structures:

   - 'Source': Adapted from the official Protocol Buffers tutorial

   - 'URL': ‘https://protobuf.dev/getting-started/’

   - 'License': Apache License 2.0


File: TheLogtalkHandbook-3.101.0.info,  Node: Performance Considerations,  Prev: addressbook proto,  Up: Examples and Test Files

6.197.11.3 Performance Considerations
.....................................

Protocol Buffers binary format is designed for:

   - 'Compactness': Variable-length encoding for integers

   - 'Speed': Simple encoding/decoding rules

   - 'Forward/backward compatibility': Unknown fields can be skipped

For optimal performance:

   - Use ‘sint32’/‘sint64’ for negative numbers

   - Use ‘fixed32’/‘fixed64’ for large numbers

   - Keep field numbers low (1-15 use only 1 byte for tags)


File: TheLogtalkHandbook-3.101.0.info,  Node: Further Reading,  Prev: Examples and Test Files,  Up: protobuf

6.197.12 Further Reading
------------------------

   - Protocol Buffers Language Guide:
     ‘https://protobuf.dev/programming-guides/proto3/’

   - Protocol Buffers Encoding Guide:
     ‘https://protobuf.dev/programming-guides/encoding/’

   - Protocol Buffers Tutorials: ‘https://protobuf.dev/getting-started/’


File: TheLogtalkHandbook-3.101.0.info,  Node: qda_classifier,  Next: queues,  Prev: protobuf,  Up: Libraries

6.198 ‘qda_classifier’
======================

Quadratic Discriminant Analysis classifier for continuous datasets using
class-specific covariance estimates with diagonal regularization.  The
implementation learns one quadratic discriminant model per class and
predicts the class with the highest class-specific score.

The library implements the ‘classifier_protocol’ defined in the
‘classification_protocols’ library.  It provides predicates for learning
a classifier from a dataset, using it to make predictions, inspecting
class scores, and exporting it as a list of predicate clauses or to a
file.

Datasets are represented as objects implementing the ‘dataset_protocol’
protocol from the ‘classification_protocols’ library.  All dataset
attributes must be declared as ‘continuous’.

* Menu:

* API documentation: API documentation<214>.
* Loading: Loading<218>.
* Testing: Testing<209>.
* Features: Features<63>.
* Options: Options<61>.
* Usage: Usage<90>.
* Classifier representation: Classifier representation<10>.
* References: References<45>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<214>,  Next: Loading<218>,  Up: qda_classifier

6.198.1 API documentation
-------------------------

Open the ‘../../docs/library_index.html#qda_classifier’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<218>,  Next: Testing<209>,  Prev: API documentation<214>,  Up: qda_classifier

6.198.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(qda_classifier(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<209>,  Next: Features<63>,  Prev: Loading<218>,  Up: qda_classifier

6.198.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(qda_classifier(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<63>,  Next: Options<61>,  Prev: Testing<209>,  Up: qda_classifier

6.198.4 Features
----------------

   - 'Continuous Datasets': Accepts only datasets whose attributes are
     all declared as continuous.

   - 'Class-Specific Covariances': Learns one covariance matrix, mean
     vector, and prior per class.

   - 'Regularized Estimation': Applies configurable diagonal
     regularization to each class covariance matrix before inversion.

   - 'Feature Scaling': Supports optional z-score scaling of continuous
     features before training.

   - 'Score Inspection': Provides class scores for all classes using
     ‘predict_scores/3’.

   - 'Classifier Export': Learned classifiers can be exported as
     predicate clauses or written to a file.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<61>,  Next: Usage<90>,  Prev: Features<63>,  Up: qda_classifier

6.198.5 Options
---------------

The ‘learn/3’ predicate supports these options:

   - ‘feature_scaling/1’ - whether to standardize continuous attributes
     before training (default: ‘true’)

   - ‘regularization/1’ - positive diagonal value added to each class
     covariance matrix before inversion (default: ‘1.0e-6’)


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<90>,  Next: Classifier representation<10>,  Prev: Options<61>,  Up: qda_classifier

6.198.6 Usage
-------------

* Menu:

* Learning a classifier: Learning a classifier<6>.
* Making predictions: Making predictions<6>.
* Exporting the classifier: Exporting the classifier<6>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Learning a classifier<6>,  Next: Making predictions<6>,  Up: Usage<90>

6.198.6.1 Learning a classifier
...............................

     | ?- qda_classifier::learn(iris_small, Classifier).

     | ?- qda_classifier::learn(iris_small, Classifier, [regularization(1.0e-5)]).


File: TheLogtalkHandbook-3.101.0.info,  Node: Making predictions<6>,  Next: Exporting the classifier<6>,  Prev: Learning a classifier<6>,  Up: Usage<90>

6.198.6.2 Making predictions
............................

     | ?- qda_classifier::learn(iris_small, Classifier),
          qda_classifier::predict(Classifier, [sepal_length-5.9, sepal_width-3.0, petal_length-5.1, petal_width-1.8], Class).

     | ?- qda_classifier::learn(iris_small, Classifier),
          qda_classifier::predict_scores(Classifier, [sepal_length-6.4, sepal_width-3.2, petal_length-4.5, petal_width-1.5], Scores).


File: TheLogtalkHandbook-3.101.0.info,  Node: Exporting the classifier<6>,  Prev: Making predictions<6>,  Up: Usage<90>

6.198.6.3 Exporting the classifier
..................................

     | ?- qda_classifier::learn(iris_small, Classifier),
          qda_classifier::export_to_clauses(iris_small, Classifier, classify, Clauses).

     | ?- qda_classifier::learn(iris_small, Classifier),
          qda_classifier::export_to_file(iris_small, Classifier, classify, 'classifier.pl').


File: TheLogtalkHandbook-3.101.0.info,  Node: Classifier representation<10>,  Next: References<45>,  Prev: Usage<90>,  Up: qda_classifier

6.198.7 Classifier representation
---------------------------------

The learned classifier is represented as a compound term with the form:

     qda_classifier(Encoders, Models, Options)

Where:

   - ‘Encoders’: list of continuous feature encoders with learned
     scaling parameters

   - ‘Models’: list of ‘class_model(Class, Prior, Mean, Precision,
     LogDeterminant, Constant)’ terms

   - ‘Options’: merged training options used to learn the classifier

When exported using ‘export_to_clauses/4’ or ‘export_to_file/4’, this
classifier term is serialized directly as the single argument of the
generated predicate clause so that the exported model can be loaded and
reused as-is.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<45>,  Prev: Classifier representation<10>,  Up: qda_classifier

6.198.8 References
------------------

  1. Hastie, T., Tibshirani, R. and Friedman, J. (2009).  “The Elements
     of Statistical Learning”.  Section 4.3.

  2. Bishop, C.M. (2006).  “Pattern Recognition and Machine Learning”.
     Section 4.2.

  3. Duda, R.O., Hart, P.E. and Stork, D.G. (2001).  “Pattern
     Classification”.  Chapter 2.


File: TheLogtalkHandbook-3.101.0.info,  Node: queues,  Next: random,  Prev: qda_classifier,  Up: Libraries

6.199 ‘queues’
==============

This library implements queues.  The queue representation should be
regarded as an opaque term and only accessed using the library
predicates.

* Menu:

* API documentation: API documentation<215>.
* Loading: Loading<219>.
* Testing: Testing<210>.
* Usage: Usage<91>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<215>,  Next: Loading<219>,  Up: queues

6.199.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#queues’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<219>,  Next: Testing<210>,  Prev: API documentation<215>,  Up: queues

6.199.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(queues(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<210>,  Next: Usage<91>,  Prev: Loading<219>,  Up: queues

6.199.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(queues(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<91>,  Prev: Testing<210>,  Up: queues

6.199.4 Usage
-------------

To create a new queue, use the ‘new/1’ predicate:

     | ?- queue::new(Queue).
     Queue = ...
     yes

Elements can be added to either the end of the queue or the front of the
queue using, respectively, the ‘join/3’ and ‘join_all/3’ predicates or
the ‘jump/3’ and ‘jump_all/3’.  For example:

     | ?- queue::(new(Queue0), join_all([1,2,3], Queue0, Queue1)).
     Queue0 = ...,
     Queue1 = ...
     yes

We can query the head of the queue or remove the head of the queue
using, respectively, the ‘head/2’ and ‘serve/3’ predicates.  For
example:

     | ?- queue::(new(Queue0), join(1, Queue0, Queue1), head(Queue1, Head)).
     Queue0 = ...,
     Queue1 = ...,
     Head = 1
     yes

For details on these and other provided predicates, consult the library
API documentation.


File: TheLogtalkHandbook-3.101.0.info,  Node: random,  Next: random_forest_classifier,  Prev: queues,  Up: Libraries

6.200 ‘random’
==============

This library provides portable random number generators and an
abstraction over the native backend Prolog compiler random number
generator if available.  It includes predicates for generating random
floats and random integers in a given interval; predicates for
generating random sequences and sets; predicates for randomly selecting,
enumerating, and swapping elements from a list; predicates that succeed,
fail, or call another predicate with a given probability; and predicates
for sampling common probability distributions.

* Menu:

* API documentation: API documentation<216>.
* Loading: Loading<220>.
* Testing: Testing<211>.
* Algorithms::
* Usage: Usage<92>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<216>,  Next: Loading<220>,  Up: random

6.200.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#random’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<220>,  Next: Testing<211>,  Prev: API documentation<216>,  Up: random

6.200.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(random(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<211>,  Next: Algorithms,  Prev: Loading<220>,  Up: random

6.200.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(random(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Algorithms,  Next: Usage<92>,  Prev: Testing<211>,  Up: random

6.200.4 Algorithms
------------------

The ‘random(Algorithm)’ and ‘fast_random(Algorithm)’ parametric objects
support the following pseudo-random number generator algorithms:

   - ‘as183’ - Algorithm AS 183 from Applied Statistics.  3x32-bit PRNG
     with period 2^60.

   - ‘splitmix64’ - SplitMix64 1x64-bit PRNG primarily used for seeding
     other generators.  Algorithm by Guy L. Steele Jr.  et al.

   - ‘xoshiro128pp’ - Xoshiro128++ 4x32-bit state-of-the-art PRNG with
     period 2^128-1.  Algorithm by David Blackman and Sebastiano Vigna.

   - ‘xoshiro128ss’ - Xoshiro128** 4x32-bit state-of-the-art PRNG with
     period 2^128-1.  Algorithm by David Blackman and Sebastiano Vigna.

   - ‘xoshiro256pp’ - Xoshiro256++ 4x64-bit state-of-the-art PRNG with
     period 2^256-1.  Algorithm by David Blackman and Sebastiano Vigna.

   - ‘xoshiro256ss’ - Xoshiro256** 4x64-bit state-of-the-art PRNG with
     period 2^256-1.  Algorithm by David Blackman and Sebastiano Vigna.

   - ‘well512a’ - WELL512a 16x32-bit state-of-the-art PRNG with period
     2^512-1.  Algorithm by by François Panneton, Pierre L’Ecuyer, and
     Makoto Matsumoto.

Note that none of the above algorithms are cryptographically secure.

The SplitMix64, Xoshiro256++, and Xoshiro256** algorithms require a
backend supporting unbound integer arithmetic.

The ‘random’ and ‘fast_random’ objects use the ‘as183’ algorithm and are
provided for backward compatibility.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<92>,  Prev: Algorithms,  Up: random

6.200.5 Usage
-------------

The ‘random(Algorithm)’ object implements a portable random number
generator and supports multiple random number generators, using
different seeds, by defining derived objects.  For example:

     :- object(my_random_generator_1,
         extends(random(xoshiro128pp))).

         :- initialization(::reset_seed).

     :- end_object.

The ‘fast_random(Algorithm)’ object also implements a portable random
number generator but does not support deriving multiple random number
generators, which makes it a bit faster than the ‘random(Algorithm)’
object.

The ‘random(Algorithm)’, ‘random’, ‘fast_random(Algorithm)’, and
‘fast_random’ objects manage the random number generator seed using
internal dynamic state.  The predicates that update the seed are
declared as synchronized (when running on Prolog backends that support
threads).  Still, care must be taken when using these objects from
multi-threaded applications, as there is no portable solution to protect
seed updates from signals and prevent inconsistent state when threads
are canceled.

The ‘random(Algorithm)’, ‘random’, ‘fast_random(Algorithm)’, and
‘fast_random’ objects always initialize the random generator seed to the
same value, thus providing a pseudo random number generator.  The
‘randomize/1’ predicate can be used to initialize the seed with a random
value.  The argument should be a large positive integer.  In
alternative, when using a small integer argument, discard the first
dozen random values.

The ‘backend_random’ object abstracts the native backend Prolog compiler
random number generator for the basic ‘random/1’, ‘get_seed/1’, and
‘set_seed/1’ predicates providing a portable implementation for the
remaining predicates.  This makes the object stateless, which allows
reliable use from multiple threads.  Consult the backend Prolog compiler
documentation for details on its random number generator properties.
Note that several of the supported backend Prolog systems, notably
B-Prolog, CxProlog, ECLiPSe, JIProlog, and Quintus Prolog, do not
provide implementations for both the ‘get_seed/1’ and ‘set_seed/1’
predicates and calling these predicates simply succeed without
performing any action.

All random objects implement the ‘sampling_protocol’ protocol.  To
maximize performance, the shared implementations of the sampling
predicates is defined in the ‘sampling.lgt’ file that’s included in the
random objects.  This allows these predicates to call the basic
‘random/1’ and ‘random/3’ predicates as locally defined predicates.


File: TheLogtalkHandbook-3.101.0.info,  Node: random_forest_classifier,  Next: random_forest_regression,  Prev: random,  Up: Libraries

6.201 ‘random_forest_classifier’
================================

Random Forest classifier using C4.5 decision trees as base learners.
Builds an ensemble of decision trees trained on bootstrap samples with
random feature subsets and combines their predictions through majority
voting.

The library implements the ‘classifier_protocol’ defined in the
‘classification_protocols’ library.  It provides predicates for learning
an ensemble classifier from a dataset, using it to make predictions
(with class probabilities), and exporting it as a list of predicate
clauses or to a file.

Datasets are represented as objects implementing the ‘dataset_protocol’
protocol from the ‘classification_protocols’ library.  See ‘test_files’
directory for examples.

* Menu:

* API documentation: API documentation<217>.
* Loading: Loading<221>.
* Testing: Testing<212>.
* Features: Features<64>.
* Options: Options<62>.
* Classifier representation: Classifier representation<11>.
* References: References<46>.
* Usage: Usage<93>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<217>,  Next: Loading<221>,  Up: random_forest_classifier

6.201.1 API documentation
-------------------------

Open the ‘../../docs/library_index.html#random_forest_classifier’ link
in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<221>,  Next: Testing<212>,  Prev: API documentation<217>,  Up: random_forest_classifier

6.201.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(random_forest_classifier(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<212>,  Next: Features<64>,  Prev: Loading<221>,  Up: random_forest_classifier

6.201.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(random_forest_classifier(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<64>,  Next: Options<62>,  Prev: Testing<212>,  Up: random_forest_classifier

6.201.4 Features
----------------

   - 'Ensemble Learning': Combines multiple C4.5 decision trees for
     robust predictions.

   - 'Bootstrap Sampling': Each tree is trained on a bootstrap sample
     (random sample with replacement) of the training data.

   - 'Feature Randomization': Random subset of features selected for
     each tree (default: sqrt(TotalFeatures)).

   - 'Portable Seeded Sampling': Uses ‘fast_random(xoshiro128pp)’ so
     bootstrap sampling and feature subset selection are portable and
     reproducible.

   - 'Majority Voting': Final predictions determined by voting across
     all trees.

   - 'Probability Estimation': Provides confidence scores based on vote
     proportions.

   - 'Configurable Options': Number of trees, maximum features per tree,
     and random seed via predicate options.

   - 'Classifier Export': Learned classifiers can be exported as
     predicate clauses.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<62>,  Next: Classifier representation<11>,  Prev: Features<64>,  Up: random_forest_classifier

6.201.5 Options
---------------

The following options can be passed to the ‘learn/3’ predicate:

   - ‘number_of_trees(N)’: Number of trees in the forest (default:
     ‘10’).

   - ‘maximum_features_per_tree(N)’: Maximum number of features to
     consider per tree (default: sqrt(TotalFeatures)).

   - ‘random_seed(N)’: Positive integer seed used by the portable
     ‘fast_random(xoshiro128pp)’ pseudo-random generator when drawing
     bootstrap samples and random feature subsets.  Using the same seed
     with the same dataset and options reproduces the same learned
     classifier (default: ‘1357911’).


File: TheLogtalkHandbook-3.101.0.info,  Node: Classifier representation<11>,  Next: References<46>,  Prev: Options<62>,  Up: random_forest_classifier

6.201.6 Classifier representation
---------------------------------

The learned classifier is represented as a compound term:

     rf_classifier(Trees, ClassValues, Options)

Where:

   - ‘Trees’: List of ‘tree(C45Tree, AttributeNames)’ pairs

   - ‘ClassValues’: List of possible class values

   - ‘Options’: List of options used during learning

When exported using ‘export_to_clauses/4’ or ‘export_to_file/4’, this
classifier term is serialized directly as the single argument of the
generated predicate clause so that the exported model can be loaded and
reused as-is.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<46>,  Next: Usage<93>,  Prev: Classifier representation<11>,  Up: random_forest_classifier

6.201.7 References
------------------

  1. Breiman, L. (2001).  “Random Forests”.  Machine Learning, 45(1),
     5-32.

  2. Ho, T.K. (1995).  “Random Decision Forests”.  Proceedings of the
     3rd International Conference on Document Analysis and Recognition.

  3. Quinlan, J.R. (1993).  “C4.5: Programs for Machine Learning”.
     Morgan Kaufmann.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<93>,  Prev: References<46>,  Up: random_forest_classifier

6.201.8 Usage
-------------

* Menu:

* Learning a Classifier: Learning a Classifier<5>.
* Making Predictions: Making Predictions<5>.
* Exporting the Classifier: Exporting the Classifier<5>.
* Using a Saved Classifier: Using a Saved Classifier<2>.
* Printing the Classifier: Printing the Classifier<2>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Learning a Classifier<5>,  Next: Making Predictions<5>,  Up: Usage<93>

6.201.8.1 Learning a Classifier
...............................

     % Learn a random forest with default options (10 trees)
     | ?- random_forest_classifier::learn(play_tennis, Classifier).
     ...

     % Learn with custom options
     | ?- random_forest_classifier::learn(play_tennis, Classifier, [number_of_trees(20), maximum_features_per_tree(2), random_seed(17)]).
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Making Predictions<5>,  Next: Exporting the Classifier<5>,  Prev: Learning a Classifier<5>,  Up: Usage<93>

6.201.8.2 Making Predictions
............................

     % Predict class for a new instance
     | ?- random_forest_classifier::learn(play_tennis, Classifier),
          random_forest_classifier::predict(Classifier, [outlook-sunny, temperature-hot, humidity-high, wind-weak], Class).
     Class = no
     ...

     % Get probability distribution from ensemble voting
     | ?- random_forest_classifier::learn(play_tennis, Classifier),
          random_forest_classifier::predict_probabilities(Classifier, [outlook-overcast, temperature-mild, humidity-normal, wind-weak], Probabilities).
     Probabilities = [yes-0.9, no-0.1]
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Exporting the Classifier<5>,  Next: Using a Saved Classifier<2>,  Prev: Making Predictions<5>,  Up: Usage<93>

6.201.8.3 Exporting the Classifier
..................................

     % Export as predicate clauses
     | ?- random_forest_classifier::learn(play_tennis, Classifier),
          random_forest_classifier::export_to_clauses(play_tennis, Classifier, my_forest, Clauses).
     Clauses = [my_forest(random_forest_classifier(...))]
     ...

     % Export to a file
     | ?- random_forest_classifier::learn(play_tennis, Classifier),
          random_forest_classifier::export_to_file(play_tennis, Classifier, my_forest, 'forest.pl').
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Using a Saved Classifier<2>,  Next: Printing the Classifier<2>,  Prev: Exporting the Classifier<5>,  Up: Usage<93>

6.201.8.4 Using a Saved Classifier
..................................

     % Load and use a previously saved classifier
     | ?- logtalk_load('forest.pl'),
          my_forest(Classifier),
          random_forest_classifier::predict(Classifier, [outlook-sunny, temperature-cool, humidity-normal, wind-weak], Class).
     Class = yes
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Printing the Classifier<2>,  Prev: Using a Saved Classifier<2>,  Up: Usage<93>

6.201.8.5 Printing the Classifier
.................................

     % Print a summary of the random forest
     | ?- random_forest_classifier::learn(play_tennis, Classifier),
          random_forest_classifier::print_classifier(Classifier).

     Random Forest Classifier
     ========================

     Number of trees: 10
     Class values: [yes,no]
     Options: [number_of_trees(10)]

     Trees:
       Tree 1 (features: [outlook,humidity]):
         -> tree rooted at outlook
       ...
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: random_forest_regression,  Next: random_projection,  Prev: random_forest_classifier,  Up: Libraries

6.202 ‘random_forest_regression’
================================

Random Forest regressor supporting continuous and mixed-feature
datasets.  The library implements the ‘regressor_protocol’ defined in
the ‘regression_protocols’ library and learns an ensemble of regression
trees trained on bootstrap samples and per-split random feature subsets,
predicting with the arithmetic mean of the individual tree predictions.

* Menu:

* API documentation: API documentation<218>.
* Loading: Loading<222>.
* Testing: Testing<213>.
* Features: Features<65>.
* Regressor representation: Regressor representation<8>.
* Diagnostics syntax: Diagnostics syntax<19>.
* Options: Options<63>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<218>,  Next: Loading<222>,  Up: random_forest_regression

6.202.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#random_forest_regression’ link
in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<222>,  Next: Testing<213>,  Prev: API documentation<218>,  Up: random_forest_regression

6.202.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(random_forest_regression(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<213>,  Next: Features<65>,  Prev: Loading<222>,  Up: random_forest_regression

6.202.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(random_forest_regression(tester)).

To run the performance benchmark suite, load the
‘tester_performance.lgt’ file:

     | ?- logtalk_load(random_forest_regression(tester_performance)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<65>,  Next: Regressor representation<8>,  Prev: Testing<213>,  Up: random_forest_regression

6.202.4 Features
----------------

   - 'Bootstrap Ensembles': Trains multiple regression trees on
     bootstrap samples.

   - 'Random Feature Subsets': Samples a random subset of the available
     dataset attributes at each split of every tree.

   - 'Portable Seeded Sampling': Uses ‘fast_random(xoshiro128pp)’ so
     bootstrap and split-level feature sampling are portable and
     reproducible.

   - 'Tree Averaging': Predicts numeric targets using the arithmetic
     mean of the tree predictions.

   - 'Tree Configuration': Exposes the underlying regression-tree
     split-feature, depth, minimum-leaf, variance-reduction, and scaling
     options.

   - 'Categorical Features Encoding': Uses reference-level dummy coding
     derived from the declared dataset attribute values, with a
     missing-value indicator, and the resulting encoded features are
     treated as ordinary numeric split features by the tree learners.

   - 'Diagnostics Metadata': Learned regressors record model name,
     target, training example count, attribute count, tree count, and
     effective options, accessible using the shared regression
     diagnostics predicates.

   - 'Model Export': Learned regressors can be exported as predicate
     clauses or written to a file.

   - 'Reference Benchmarks': Includes a dedicated performance suite
     reporting training time, RMSE, and MAE for representative
     regression datasets.


File: TheLogtalkHandbook-3.101.0.info,  Node: Regressor representation<8>,  Next: Diagnostics syntax<19>,  Prev: Features<65>,  Up: random_forest_regression

6.202.5 Regressor representation
--------------------------------

The learned regressor is represented by default as:

   - ‘rf_regressor(Trees, Diagnostics)’

The exported predicate clauses therefore use the shape:

   - ‘Functor(Trees, Diagnostics)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Diagnostics syntax<19>,  Next: Options<63>,  Prev: Regressor representation<8>,  Up: random_forest_regression

6.202.6 Diagnostics syntax
--------------------------

The ‘diagnostics/2’ predicate returns a list of metadata terms with the
form:

     [
         model(random_forest_regression),
         target(Target),
         training_example_count(TrainingExampleCount),
         options(Options),
         attribute_count(AttributeCount),
         tree_count(TreeCount)
     ]

Where:

   - ‘model(random_forest_regression)’ identifies the learning algorithm
     that produced the regressor.

   - ‘target(Target)’ stores the target attribute name declared by the
     training dataset.

   - ‘training_example_count(TrainingExampleCount)’ stores the number of
     examples used during training.

   - ‘options(Options)’ stores the effective learning options after
     merging the user options with the library defaults.

   - ‘attribute_count(AttributeCount)’ stores the number of dataset
     attributes available to the ensemble before split-level
     subsampling.

   - ‘tree_count(TreeCount)’ stores the number of trained regression
     trees in the ensemble.

Use the ‘regression_protocols’ ‘diagnostic/2’ and ‘regressor_options/2’
helper predicates when you only need a single metadata term or the
effective options.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<63>,  Prev: Diagnostics syntax<19>,  Up: random_forest_regression

6.202.7 Options
---------------

The ‘learn/3’ predicate accepts the following options:

   - ‘number_of_trees/1’: Number of regression trees to train in the
     ensemble.  Increasing this value usually improves stability at the
     cost of additional training and prediction time.  The default is
     ‘10’.

   - ‘maximum_features_per_split/1’: Number of dataset attributes
     randomly sampled at each split when searching for the best
     partition.  Accepted values are a positive integer or ‘all’.  When
     omitted, the library uses the square root of the total number of
     available attributes, with a minimum of one attribute.  Passing
     ‘all’ disables split-level attribute subsampling.

   - ‘maximum_depth/1’: Maximum depth allowed for each regression-tree
     base learner.  The default is ‘10’.

   - ‘minimum_samples_leaf/1’: Minimum number of training examples
     required in each leaf of a base learner tree.  The default is ‘1’.

   - ‘minimum_variance_reduction/1’: Minimum split gain required by each
     base learner tree before accepting a partition.  The default is
     ‘0.0’.

   - ‘feature_scaling/1’: Controls z-score standardization of continuous
     attributes inside each regression-tree base learner.  Accepted
     values are ‘true’ and ‘false’.  The default is ‘false’.

   - ‘random_seed/1’: Positive integer seed used by the portable
     ‘fast_random(xoshiro128pp)’ pseudo-random generator when drawing
     bootstrap samples and split-level random feature subsets.  Using
     the same seed with the same dataset and options reproduces the same
     learned regressor.  The default is ‘1357911’.


File: TheLogtalkHandbook-3.101.0.info,  Node: random_projection,  Next: rank_centrality,  Prev: random_forest_regression,  Up: Libraries

6.203 ‘random_projection’
=========================

Random projection reducer for continuous datasets.  The library
implements the ‘dimension_reducer_protocol’ defined in the
‘dimension_reduction_protocols’ library and learns a seeded dense
Rademacher projection matrix using the portable ‘fast_random’
pseudo-random generator after centering the training data, optionally
standardizing continuous attributes, and sampling entries in
‘{-$1/sqrt(k)$, +$1/sqrt(k)$}’ where ‘$k$’ is the requested reduced
dimensionality.

* Menu:

* API documentation: API documentation<219>.
* Loading: Loading<223>.
* Testing: Testing<214>.
* Features: Features<66>.
* Options: Options<64>.
* Usage: Usage<94>.
* Dimension reducer representation: Dimension reducer representation<8>.
* References: References<47>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<219>,  Next: Loading<223>,  Up: random_projection

6.203.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#random_projection’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<223>,  Next: Testing<214>,  Prev: API documentation<219>,  Up: random_projection

6.203.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(random_projection(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<214>,  Next: Features<66>,  Prev: Loading<223>,  Up: random_projection

6.203.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(random_projection(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<66>,  Next: Options<64>,  Prev: Testing<214>,  Up: random_projection

6.203.4 Features
----------------

   - 'Continuous Datasets': Accepts datasets containing only continuous
     attributes.  Missing or nonnumeric values are rejected.

   - 'Centering and Optional Scaling': Centers all attributes and
     optionally standardizes them before projection.

   - 'Portable Seeded Sampling': Uses ‘fast_random(xoshiro128pp)’ so
     learned projection matrices are portable and reproducible.

   - 'Projection API': Transforms a new instance into a list of
     ‘component_N-Value’ pairs.

   - 'Model Export': Learned reducers can be exported as predicate
     clauses or written to a file.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<64>,  Next: Usage<94>,  Prev: Features<66>,  Up: random_projection

6.203.5 Options
---------------

The ‘learn/3’ predicate accepts the following options:

   - ‘n_components/1’: Number of random projection components to sample.
     Requests that exceed the number of features raise
     ‘domain_error(component_count, Requested-Maximum)’.  The default is
     ‘2’.

   - ‘feature_scaling/1’: Whether to standardize continuous attributes
     before projection.  Options: ‘true’ (default) or ‘false’.

   - ‘random_seed/1’: Positive integer used to seed the portable
     pseudo-random generator before sampling the projection matrix.  The
     default is ‘1357911’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<94>,  Next: Dimension reducer representation<8>,  Prev: Options<64>,  Up: random_projection

6.203.6 Usage
-------------

The following examples use the sample datasets shipped with the
‘dimension_reduction_protocols’ library:

     | ?- logtalk_load(dimension_reduction_protocols('test_datasets/correlated_plane')),
          logtalk_load(dimension_reduction_protocols('test_datasets/high_dimensional_measurements')).

* Menu:

* Learning a reducer: Learning a reducer<7>.
* Transforming new instances: Transforming new instances<7>.
* Exporting and reusing the reducer: Exporting and reusing the reducer<7>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Learning a reducer<7>,  Next: Transforming new instances<7>,  Up: Usage<94>

6.203.6.1 Learning a reducer
............................

     | ?- random_projection::learn(correlated_plane, DimensionReducer).

     | ?- random_projection::learn(correlated_plane, DimensionReducer, [n_components(1), feature_scaling(false), random_seed(17)]).


File: TheLogtalkHandbook-3.101.0.info,  Node: Transforming new instances<7>,  Next: Exporting and reusing the reducer<7>,  Prev: Learning a reducer<7>,  Up: Usage<94>

6.203.6.2 Transforming new instances
....................................

     | ?- random_projection::learn(high_dimensional_measurements, DimensionReducer, [random_seed(11)]),
          random_projection::transform(DimensionReducer, [f1-0.9, f2-1.1, f3-1.0, f4-2.0, f5-2.2, f6-2.1], ReducedInstance).

     | ?- random_projection::learn(correlated_plane, DimensionReducer, [n_components(1), random_seed(19)]),
          random_projection::transform(DimensionReducer, [x-1.0, y-2.0, z-3.0], ReducedInstance).


File: TheLogtalkHandbook-3.101.0.info,  Node: Exporting and reusing the reducer<7>,  Prev: Transforming new instances<7>,  Up: Usage<94>

6.203.6.3 Exporting and reusing the reducer
...........................................

     | ?- random_projection::learn(correlated_plane, DimensionReducer, [n_components(1), random_seed(29)]),
          random_projection::export_to_file(correlated_plane, DimensionReducer, reducer, 'random_projection_reducer.pl').

     | ?- logtalk_load('random_projection_reducer.pl'),
          reducer(Reducer),
          random_projection::transform(Reducer, [x-1.0, y-2.0, z-3.0], ReducedInstance).


File: TheLogtalkHandbook-3.101.0.info,  Node: Dimension reducer representation<8>,  Next: References<47>,  Prev: Usage<94>,  Up: random_projection

6.203.7 Dimension reducer representation
----------------------------------------

The learned dimension reducer is represented by a compound term with the
functor chosen by the implementation and arity 3.  For example:

     random_projection_reducer(Encoders, Components, Diagnostics)

Where:

   - ‘Encoders’: List of continuous attribute encoders storing attribute
     name, mean, and scale.

   - ‘Components’: List of sampled projection vectors in component
     order.

   - ‘Diagnostics’: Learned reducer metadata including the effective
     training options and reproducibility details.

When exported using ‘export_to_clauses/4’ or ‘export_to_file/4’, this
reducer term is serialized directly as the single argument of the
generated predicate clause so that the exported model can be loaded and
reused as-is.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<47>,  Prev: Dimension reducer representation<8>,  Up: random_projection

6.203.8 References
------------------

  1. Johnson, W. B. and Lindenstrauss, J. (1984) - “Extensions of
     Lipschitz mappings into a Hilbert space”.

  2. Achlioptas, D. (2003) - “Database-friendly random projections:
     Johnson-Lindenstrauss with binary coins”.


File: TheLogtalkHandbook-3.101.0.info,  Node: rank_centrality,  Next: ranked_pairs,  Prev: random_projection,  Up: Libraries

6.204 ‘rank_centrality’
=======================

Rank Centrality pairwise preference ranker.  It uses the Rank Centrality
transition rule where each observed opponent contributes an outgoing
transition proportional to the empirical probability of beating the
current item, scaled by the maximum comparison degree, and estimates the
stationary distribution using deterministic power iteration.

The library implements the ‘ranker_protocol’ defined in the
‘ranking_protocols’ library.  It provides predicates for learning a
ranker from pairwise preferences, using it to order candidate items, and
exporting it as a list of predicate clauses or to a file.

Datasets are represented as objects implementing the
‘pairwise_ranking_dataset_protocol’ protocol from the
‘ranking_protocols’ library.  See the ‘test_datasets’ directory for
examples.  The training dataset must declare each ranked item once,
enumerate positive-weight pairwise preferences between distinct declared
items, induce a connected undirected comparison graph, and induce a
strongly connected directed transition graph so that the learned
stationary distribution is unique.

* Menu:

* API documentation: API documentation<220>.
* Loading: Loading<224>.
* Testing: Testing<215>.
* Features: Features<67>.
* Dataset requirements: Dataset requirements<4>.
* Usage: Usage<95>.
* Diagnostics syntax: Diagnostics syntax<20>.
* Options: Options<65>.
* Ranker representation: Ranker representation<13>.
* References: References<48>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<220>,  Next: Loading<224>,  Up: rank_centrality

6.204.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#rank_centrality’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<224>,  Next: Testing<215>,  Prev: API documentation<220>,  Up: rank_centrality

6.204.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(rank_centrality(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<215>,  Next: Features<67>,  Prev: Loading<224>,  Up: rank_centrality

6.204.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(rank_centrality(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<67>,  Next: Dataset requirements<4>,  Prev: Testing<215>,  Up: rank_centrality

6.204.4 Features
----------------

   - 'Pairwise Preference Learning': Learns one stationary probability
     score per item from weighted head-to-head outcomes.

   - 'Original Rank Centrality Transition Rule': Builds the Markov chain
     from empirical pairwise win probabilities scaled by the maximum
     comparison degree, then estimates the stationary distribution by
     deterministic power iteration.

   - 'Deterministic Ranking': Orders candidate items by learned
     stationary probability with deterministic tie-breaking.

   - 'Strict Dataset Validation': Rejects duplicate items, undeclared
     items, self-preferences, non-positive weights, disconnected
     undirected comparison graphs, and pairwise datasets whose directed
     transition graph is not strongly connected.

   - 'Training Diagnostics': Learned rankers include convergence,
     iteration, maximum-degree, and dataset summary metadata that can be
     accessed using the ‘diagnostics/2’ predicate.

   - 'Ranker Export': Learned rankers can be exported as self-contained
     terms.

   - 'Sparse Transition Processing': Training aggregates observed
     pairwise comparisons into sparse incoming transition lists so each
     power-iteration step scales with observed matchups instead of a
     dense item cross-product.


File: TheLogtalkHandbook-3.101.0.info,  Node: Dataset requirements<4>,  Next: Usage<95>,  Prev: Features<67>,  Up: rank_centrality

6.204.5 Dataset requirements
----------------------------

This implementation requires more than undirected connectedness.  In
order to guarantee a unique stationary distribution, the directed
transition graph induced by the aggregated pairwise outcomes must be
strongly connected.  Datasets that create one-way dominance sinks or
other disconnected directed transition components are rejected instead
of producing ambiguous stationary scores.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<95>,  Next: Diagnostics syntax<20>,  Prev: Dataset requirements<4>,  Up: rank_centrality

6.204.6 Usage
-------------

* Menu:

* Learning a ranker: Learning a ranker<13>.
* Inspecting diagnostics: Inspecting diagnostics<11>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Learning a ranker<13>,  Next: Inspecting diagnostics<11>,  Up: Usage<95>

6.204.6.1 Learning a ranker
...........................

     % Learn from a pairwise ranking dataset object
     | ?- rank_centrality::learn(my_dataset, Ranker).
     ...

     % Learn with custom iteration and convergence options
     | ?- rank_centrality::learn(my_dataset, Ranker, [maximum_iterations(500), tolerance(1.0e-9)]).
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Inspecting diagnostics<11>,  Prev: Learning a ranker<13>,  Up: Usage<95>

6.204.6.2 Inspecting diagnostics
................................

     % Inspect convergence and dataset summary metadata
     | ?- rank_centrality::learn(my_dataset, Ranker),
          rank_centrality::diagnostics(Ranker, Diagnostics).
     Diagnostics = [...]
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Diagnostics syntax<20>,  Next: Options<65>,  Prev: Usage<95>,  Up: rank_centrality

6.204.7 Diagnostics syntax
--------------------------

The ‘diagnostics/2’ predicate returns a list of metadata terms with the
form:

     [
         model(rank_centrality),
         options(Options),
         convergence(Status),
         iterations(Iterations),
         final_delta(FinalDelta),
         maximum_degree(MaximumDegree),
         dataset_summary(DatasetSummary)
     ]

Where:

   - ‘model(rank_centrality)’ identifies the learning algorithm that
     produced the ranker.

   - ‘options(Options)’ stores the effective learning options after
     merging the user options with the library defaults.

   - ‘convergence(Status)’ records the training stop condition.  The
     current values are ‘converged’ and ‘maximum_iterations_exhausted’.

   - ‘iterations(Iterations)’ stores the number of power-iteration steps
     that were executed.

   - ‘final_delta(FinalDelta)’ stores the maximum absolute score update
     in the last iteration.

   - ‘maximum_degree(MaximumDegree)’ stores the maximum number of
     observed opponents for any single item in the training dataset.

   - ‘dataset_summary(DatasetSummary)’ stores a summary list describing
     the validated training dataset.

The current ‘dataset_summary/1’ payload has the form:

     [
         items(NumberOfItems),
         preferences(NumberOfPreferences),
         connected_components(NumberOfComponents),
         isolated_items(IsolatedItems)
     ]

Use the ‘ranking_protocols’ ‘diagnostic/2’ and ‘ranker_options/2’ helper
predicates when you only need a single metadata term or the effective
options.

* Menu:

* Ranking candidate items: Ranking candidate items<12>.
* Exporting the ranker: Exporting the ranker<11>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Ranking candidate items<12>,  Next: Exporting the ranker<11>,  Up: Diagnostics syntax<20>

6.204.7.1 Ranking candidate items
.................................

     % Rank a candidate set from most preferred to least preferred
     | ?- rank_centrality::learn(my_dataset, Ranker),
          rank_centrality::rank(Ranker, [item_a, item_b, item_c], Ranking).
     Ranking = [...]
     ...

Candidate lists must be proper lists of unique, ground items declared by
the training dataset.  Invalid ranker terms, duplicate candidates, and
candidates containing variables are rejected with errors instead of
being silently accepted.


File: TheLogtalkHandbook-3.101.0.info,  Node: Exporting the ranker<11>,  Prev: Ranking candidate items<12>,  Up: Diagnostics syntax<20>

6.204.7.2 Exporting the ranker
..............................

Learned rankers can be exported as a list of clauses or to a file for
later use.

     % Export as predicate clauses
     | ?- rank_centrality::learn(my_dataset, Ranker),
          rank_centrality::export_to_clauses(my_dataset, Ranker, my_ranker, Clauses).
     Clauses = [my_ranker(rank_centrality_ranker(...))]
     ...

     % Export to a file
     | ?- rank_centrality::learn(my_dataset, Ranker),
          rank_centrality::export_to_file(my_dataset, Ranker, my_ranker, 'ranker.pl').
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<65>,  Next: Ranker representation<13>,  Prev: Diagnostics syntax<20>,  Up: rank_centrality

6.204.8 Options
---------------

The following options can be passed to the ‘learn/3’ predicate:

   - ‘maximum_iterations(MaximumIterations)’: Positive integer iteration
     bound.

   - ‘tolerance(Tolerance)’: Positive convergence tolerance.


File: TheLogtalkHandbook-3.101.0.info,  Node: Ranker representation<13>,  Next: References<48>,  Prev: Options<65>,  Up: rank_centrality

6.204.9 Ranker representation
-----------------------------

The learned ranker is represented by a compound term of the form:

     rank_centrality_ranker(Items, Scores, Diagnostics)

Where:

   - ‘Items’: List of ranked items.

   - ‘Scores’: List of ‘Item-Score’ pairs.

   - ‘Diagnostics’: List of metadata terms, including the effective
     options, convergence status, iteration count, final update delta,
     maximum degree, and dataset summary.

The ‘Scores’ payload is expected to contain positive stationary
probability values summing to ‘1.0’.  The ranker validation logic
enforces this invariant when consuming serialized or exported ranker
terms so that malformed payloads are rejected instead of silently
accepted.

When exported using ‘export_to_clauses/4’ or ‘export_to_file/4’, this
ranker term is serialized directly as the single argument of the
generated predicate clause so that the exported model can be loaded and
reused as-is.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<48>,  Prev: Ranker representation<13>,  Up: rank_centrality

6.204.10 References
-------------------

  1. Negahban, S., Oh, S., and Shah, D. (2012).  Rank Centrality:
     Ranking from pairwise comparisons.  'Operations Research', 65(1),
     266-287.


File: TheLogtalkHandbook-3.101.0.info,  Node: ranked_pairs,  Next: ranking_protocols,  Prev: rank_centrality,  Up: Libraries

6.205 ‘ranked_pairs’
====================

Ranked Pairs pairwise preference ranker.  It builds the direct pairwise
victory graph from aggregated matchups, considers victories in
descending direct-victory strength order, and locks each victory unless
it would create a directed cycle in the accepted lock graph.

The library implements the ‘ranker_protocol’ defined in the
‘ranking_protocols’ library.  It provides predicates for learning a
ranker from pairwise preferences, using it to order candidate items, and
exporting it as a list of predicate clauses or to a file.

Datasets are represented as objects implementing the
‘pairwise_ranking_dataset_protocol’ protocol from the
‘ranking_protocols’ library.  See the ‘test_datasets’ directory for
examples.  The current implementation requires a well-formed connected
pairwise dataset so that all ranked items remain part of a single
comparison graph.

* Menu:

* API documentation: API documentation<221>.
* Loading: Loading<225>.
* Testing: Testing<216>.
* Features: Features<68>.
* Usage: Usage<96>.
* Diagnostics syntax: Diagnostics syntax<21>.
* Options: Options<66>.
* Scoring semantics: Scoring semantics<7>.
* Ranker representation: Ranker representation<14>.
* See also: See also<6>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<221>,  Next: Loading<225>,  Up: ranked_pairs

6.205.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#ranked_pairs’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<225>,  Next: Testing<216>,  Prev: API documentation<221>,  Up: ranked_pairs

6.205.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(ranked_pairs(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<216>,  Next: Features<68>,  Prev: Loading<225>,  Up: ranked_pairs

6.205.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(ranked_pairs(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<68>,  Next: Usage<96>,  Prev: Testing<216>,  Up: ranked_pairs

6.205.4 Features
----------------

   - 'Pairwise Preference Learning': Learns one deterministic score per
     item from aggregated pairwise outcomes.

   - 'Ranked Pairs Locking': Processes direct victories in descending
     strength order and accepts each victory unless it would create a
     directed cycle in the current lock graph.

   - 'Configurable Direct Victory Semantics': Supports both
     winning-votes and victory-margins victory-strength modes before
     locking.

   - 'Configurable Equal-Strength Tie Breaking': Supports both standard
     term-order and dataset declaration-order resolution when direct
     victories have the same strength.

   - 'Locked-Pair Access': Exposes the accepted lock graph in lock order
     using the ‘locked_pairs/2’ predicate.

   - 'Deterministic Ranking': Orders candidate items by the number of
     opponents reachable in the final locked relation with deterministic
     tie-breaking.

   - 'Strict Dataset Validation': Rejects duplicate items, undeclared
     items, self-preferences, non-positive weights, and disconnected
     comparison graphs.

   - 'Training Diagnostics': Learned rankers include dataset summary
     metadata, the effective victory-strength mode, and the accepted
     lock graph.

   - 'Ranker Export': Learned rankers can be exported as self-contained
     terms.

   - 'Shared Condorcet Infrastructure': Reuses the shared direct-victory
     preprocessing helpers from the ‘ranking_protocols’ library.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<96>,  Next: Diagnostics syntax<21>,  Prev: Features<68>,  Up: ranked_pairs

6.205.5 Usage
-------------

* Menu:

* Learning a ranker: Learning a ranker<14>.
* Inspecting diagnostics: Inspecting diagnostics<12>.
* Ranking candidate items: Ranking candidate items<13>.
* Inspecting locked pairs::
* Exporting the ranker: Exporting the ranker<12>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Learning a ranker<14>,  Next: Inspecting diagnostics<12>,  Up: Usage<96>

6.205.5.1 Learning a ranker
...........................

     % Learn from a pairwise ranking dataset object
     | ?- ranked_pairs::learn(my_dataset, Ranker).
     ...

     % Learn with custom direct-victory semantics
     | ?- ranked_pairs::learn(my_dataset, Ranker, [victory_strength(margins)]).
     ...

     % Learn with custom equal-strength tie breaking
     | ?- ranked_pairs::learn(my_dataset, Ranker, [tie_breaking(declaration_order)]).
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Inspecting diagnostics<12>,  Next: Ranking candidate items<13>,  Prev: Learning a ranker<14>,  Up: Usage<96>

6.205.5.2 Inspecting diagnostics
................................

     % Inspect the effective options and accepted locks
     | ?- ranked_pairs::learn(my_dataset, Ranker),
          ranked_pairs::diagnostics(Ranker, Diagnostics).
     Diagnostics = [...]
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Ranking candidate items<13>,  Next: Inspecting locked pairs,  Prev: Inspecting diagnostics<12>,  Up: Usage<96>

6.205.5.3 Ranking candidate items
.................................

     % Rank a candidate set from most preferred to least preferred
     | ?- ranked_pairs::learn(my_dataset, Ranker),
          ranked_pairs::rank(Ranker, [item_a, item_b, item_c], Ranking).
     Ranking = [...]
     ...

Candidate lists must be proper lists of unique, ground items declared by
the training dataset.  Invalid ranker terms, duplicate candidates, and
candidates containing variables are rejected with errors instead of
being silently accepted.


File: TheLogtalkHandbook-3.101.0.info,  Node: Inspecting locked pairs,  Next: Exporting the ranker<12>,  Prev: Ranking candidate items<13>,  Up: Usage<96>

6.205.5.4 Inspecting locked pairs
.................................

     % Inspect the accepted lock graph in lock order
     | ?- ranked_pairs::learn(my_dataset, Ranker),
          ranked_pairs::locked_pairs(Ranker, LockedPairs).
     LockedPairs = [...]
     ...

The ‘locked_pairs/2’ predicate returns an ordered list of ‘lock(Winner,
Loser, Strength)’ terms representing the victories that were accepted
during the Ranked Pairs locking phase.


File: TheLogtalkHandbook-3.101.0.info,  Node: Exporting the ranker<12>,  Prev: Inspecting locked pairs,  Up: Usage<96>

6.205.5.5 Exporting the ranker
..............................

Learned rankers can be exported as a list of clauses or to a file for
later use.

     % Export as predicate clauses
     | ?- ranked_pairs::learn(my_dataset, Ranker),
          ranked_pairs::export_to_clauses(my_dataset, Ranker, my_ranker, Clauses).
     Clauses = [my_ranker(ranked_pairs_ranker(...))]
     ...

     % Export to a file
     | ?- ranked_pairs::learn(my_dataset, Ranker),
          ranked_pairs::export_to_file(my_dataset, Ranker, my_ranker, 'ranker.pl').
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Diagnostics syntax<21>,  Next: Options<66>,  Prev: Usage<96>,  Up: ranked_pairs

6.205.6 Diagnostics syntax
--------------------------

The ‘diagnostics/2’ predicate returns a list of metadata terms with the
form:

     [
         model(ranked_pairs),
         options(Options),
         locked_pairs(LockedPairs),
         dataset_summary(DatasetSummary)
     ]

Where:

   - ‘model(ranked_pairs)’ identifies the learning algorithm that
     produced the ranker.

   - ‘options(Options)’ stores the effective learning options after
     merging the user options with the library defaults.

   - ‘locked_pairs(LockedPairs)’ stores the accepted lock graph in the
     order in which victories were locked.

   - ‘dataset_summary(DatasetSummary)’ stores a summary list describing
     the validated training dataset.

Use the ‘ranking_protocols’ ‘diagnostic/2’ and ‘ranker_options/2’ helper
predicates when you only need a single metadata term or the effective
options.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<66>,  Next: Scoring semantics<7>,  Prev: Diagnostics syntax<21>,  Up: ranked_pairs

6.205.7 Options
---------------

The following options can be passed to the ‘learn/3’ predicate:

   - ‘victory_strength(winning_votes)’: Use the winning side’s
     aggregated vote total as the direct victory strength.

   - ‘victory_strength(margins)’: Use the victory margin as the direct
     victory strength.

   - ‘tie_breaking(term_order)’: Break equal-strength direct-victory
     ties using the standard term order of the winner and loser item
     identifiers.

   - ‘tie_breaking(declaration_order)’: Break equal-strength
     direct-victory ties using the training item declaration order
     preserved by the pairwise dataset helpers.

The defaults are ‘victory_strength(winning_votes)’ and
‘tie_breaking(term_order)’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Scoring semantics<7>,  Next: Ranker representation<14>,  Prev: Options<66>,  Up: ranked_pairs

6.205.8 Scoring semantics
-------------------------

The learned ‘scores/2’ values count how many opponents are reachable
from each item in the final locked relation.  These scores are therefore
integers in the range from ‘0’ to ‘N-1’, where ‘N’ is the number of
learned items.

This choice keeps the ‘rank/3’ behavior aligned with the locked graph
that the algorithm actually accepts: a higher score means that the item
precedes more opponents after all accepted locks are closed
transitively.

The effective scores can therefore change when ‘tie_breaking/1’ changes
the order in which equal-strength victories are considered for locking.


File: TheLogtalkHandbook-3.101.0.info,  Node: Ranker representation<14>,  Next: See also<6>,  Prev: Scoring semantics<7>,  Up: ranked_pairs

6.205.9 Ranker representation
-----------------------------

The learned ranker is represented by a compound term of the form:

     ranked_pairs_ranker(Items, Scores, Diagnostics)

Where:

   - ‘Items’: List of ranked items.

   - ‘Scores’: List of integer ‘Item-Score’ pairs.

   - ‘Diagnostics’: List of metadata terms, including the effective
     options, the accepted locked pairs, and the dataset summary.

When exported using ‘export_to_clauses/4’ or ‘export_to_file/4’, this
ranker term is serialized directly as the single argument of the
generated predicate clause so that the exported model can be loaded and
reused as-is.


File: TheLogtalkHandbook-3.101.0.info,  Node: See also<6>,  Prev: Ranker representation<14>,  Up: ranked_pairs

6.205.10 See also
-----------------

For the strongest-path Condorcet-family alternative sharing the same
‘victory_strength(...)’ option, see the ‘schulze_ranker’ library.


File: TheLogtalkHandbook-3.101.0.info,  Node: ranking_protocols,  Next: reader,  Prev: ranked_pairs,  Up: Libraries

6.206 ‘ranking_protocols’
=========================

This library provides protocols used in the implementation of machine
learning ranking algorithms.  Rankers are represented as objects
implementing the ‘ranker_protocol’ protocol.  Datasets are represented
as objects implementing the ‘pairwise_ranking_dataset_protocol’,
‘pairwise_measurement_dataset_protocol’,
‘temporal_pairwise_ranking_dataset_protocol’, or the
‘ranking_dataset_protocol’ protocol.

This library also provides reusable test datasets and smoke tests for
the shared ranking-family contracts.

* Menu:

* Protocol requirements::
* Shared categories::
* Diagnostics: Diagnostics<10>.
* Export header format: Export header format<3>.
* API documentation: API documentation<222>.
* Loading: Loading<226>.
* Testing: Testing<217>.
* Test datasets: Test datasets<6>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Protocol requirements,  Next: Shared categories,  Up: ranking_protocols

6.206.1 Protocol requirements
-----------------------------

The dataset protocols defined by this library impose the following
semantic and validity expectations:

   - ‘pairwise_ranking_dataset_protocol’ datasets should declare each
     item once, use only declared items in preferences, assign positive
     weights to preferences between distinct items, and may still need
     stronger conditions such as a strongly connected directed win graph
     for algorithms like Bradley-Terry that require finite
     maximum-likelihood estimates.

   - ‘pairwise_measurement_dataset_protocol’ datasets should declare
     each item once, use only declared items in measurements, assign
     numeric measurement values, and assign positive weights to
     measurements between distinct items.  Each ‘measurement(Item1,
     Item2, Value, Weight)’ fact denotes a weighted signed scalar
     observation on the oriented edge ‘Item1 -> Item2’, where positive
     values favor ‘Item1’, negative values favor ‘Item2’, and zero
     denotes a neutral observation.

   - ‘temporal_pairwise_ranking_dataset_protocol’ datasets should
     declare each item and period once, use only declared items and
     periods in games, keep game participants distinct, and restrict
     scores to the set ‘{0.0, 0.5, 1.0}’.  A fact ‘game(Period, Item1,
     Item2, Score)’ records the observed result for ‘Item1’ against
     ‘Item2’, with the score for ‘Item2’ implicitly equal to ‘1.0 -
     Score’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Shared categories,  Next: Diagnostics<10>,  Prev: Protocol requirements,  Up: ranking_protocols

6.206.2 Shared categories
-------------------------

The library includes a small family of reusable categories intended to
be imported by ranking algorithm implementations:

   - ‘ranking_dataset_common’ — dataset collection, summaries, graph
     connectivity, connected-component analysis, and pairwise/grouped
     dataset correctness checks, including pairwise measurement helpers,
     temporal pairwise rating-period helpers, and grouped tie-block
     extraction helpers for algorithms that consume tied rankings
     directly.

   - ‘glicko2_common’ — shared internal Glicko-2 numeric helpers for
     scale conversions, per-period player updates, and volatility root
     solving used by both the batch and periodic Glicko-2 rankers.

   - ‘condorcet_victory_common’ — shared direct-victory preprocessing
     helpers for Condorcet-family rankers that derive dense directed
     victory strengths from aggregated pairwise matchups under the
     ‘victory_strength(...)’ option semantics.

   - ‘ranker_common’ — representation-independent access to
     learned-ranker diagnostics plus reusable helpers for exporting
     learned rankers.

   - ‘grouped_strength_ranker_common’ — reusable positive-strength,
     strong-connectivity, and iterative-update helpers for grouped
     ranking models that estimate one latent strength parameter per
     item.

These categories are designed to keep ranking implementations compact
while keeping the shared protocol-facing behavior reusable.


File: TheLogtalkHandbook-3.101.0.info,  Node: Diagnostics<10>,  Next: Export header format<3>,  Prev: Shared categories,  Up: ranking_protocols

6.206.3 Diagnostics
-------------------

The ‘ranker_common’ category provides shared accessor predicates such as
‘diagnostics/2’, ‘diagnostic/2’, and ‘ranker_options/2’, together with
the shared ‘export_to_file/4’ export helper.  These predicates make it
possible to inspect and export learned rankers without depending on the
exact term representation used by a particular ranking algorithm
implementation.

The detailed contents of the diagnostics data are ranking algorithm
implementation dependent.  For example, one ranker may report
convergence status, iteration count, and dataset summaries, while
another may report a different set of metadata terms or only a subset of
those details.  When using diagnostics in application code, rely on the
shared access predicates and the documentation of the specific ranking
algorithm you are using.


File: TheLogtalkHandbook-3.101.0.info,  Node: Export header format<3>,  Next: API documentation<222>,  Prev: Diagnostics<10>,  Up: ranking_protocols

6.206.4 Export header format
----------------------------

The shared ranker exporter in the ‘ranker_common’ category writes a
header before the exported clauses in the following format:

     % exported ranker predicate: Functor/Arity
     % training dataset: Dataset
     % diagnostics: Diagnostics
     % Functor(Ranker)
     Functor(Ranker)

When exporting a serialized ranker term, using a noun such as ‘ranker/1’
or ‘model/1’ is recommended.  The ‘Ranker’ argument can then be passed
to the rank predicates.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<222>,  Next: Loading<226>,  Prev: Export header format<3>,  Up: ranking_protocols

6.206.5 API documentation
-------------------------

Open the ‘../../apis/library_index.html#ranking_protocols’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<226>,  Next: Testing<217>,  Prev: API documentation<222>,  Up: ranking_protocols

6.206.6 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(ranking_protocols(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<217>,  Next: Test datasets<6>,  Prev: Loading<226>,  Up: ranking_protocols

6.206.7 Testing
---------------

To test this library predicates and datasets, load the ‘tester.lgt’
file:

     | ?- logtalk_load(ranking_protocols(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Test datasets<6>,  Prev: Testing<217>,  Up: ranking_protocols

6.206.8 Test datasets
---------------------

Several sample datasets are included in the ‘test_datasets’ directory:

   - ‘head_to_head.lgt’ — A compact pairwise-comparison dataset with
     four items and weighted preferences suitable for smoke testing
     deterministic ranking.

   - ‘search_results.lgt’ — A grouped ranking dataset with two query
     groups, three items per group, and non-negative integer relevance
     judgments.

   - ‘malformed_pairwise.lgt’ — A negative fixture where a preference
     mentions an undeclared item.

   - ‘malformed_duplicate_items.lgt’ — A negative pairwise fixture where
     an item is declared more than once.

   - ‘malformed_self_preference.lgt’ — A negative pairwise fixture where
     an item is preferred over itself.

   - ‘malformed_non_positive_weight.lgt’ — A negative pairwise fixture
     where a preference weight is not positive.

   - ‘disconnected_pairwise.lgt’ — A pairwise fixture with more than one
     connected component, useful for testing algorithms that require
     identifiable global scores.

   - ‘cyclic_pairwise.lgt’ — A connected pairwise fixture with a
     preference cycle, useful for smoke testing algorithms on
     non-transitive data.

   - ‘condorcet_divergence_pairwise.lgt’ — A compact connected pairwise
     fixture where the current ‘schulze_ranker’ and ‘ranked_pairs’
     implementations produce different rankings, useful for cross-method
     regression tests.

   - ‘malformed_grouped.lgt’ — A negative fixture where a grouped
     relevance value is not a non-negative integer.

   - ‘sparse_preferences.lgt’ — A sparse pairwise dataset with an
     isolated item, useful for testing dataset summaries and
     disconnected-graph detection.

   - ‘two_item_measurements.lgt’ — A compact pairwise measurement
     dataset with two items and one signed measurement, useful for smoke
     testing exact two-item least-squares fits.

   - ‘regular_measurements.lgt’ — A compact connected pairwise
     measurement dataset whose measurements are perfectly explained by a
     zero-sum score potential, useful for regression tests with zero
     residuals.

   - ‘cyclic_measurements.lgt’ — A compact connected pairwise
     measurement dataset with cyclic inconsistency, useful for smoke
     testing zero global scores with non-zero residuals.

   - ‘disconnected_measurements.lgt’ — A pairwise measurement fixture
     with more than one connected component, useful for testing
     identifiable-score checks.

   - ‘malformed_measurement_unknown_item.lgt’ — A negative measurement
     fixture where a measurement mentions an undeclared item.

   - ‘malformed_measurement_duplicate_items.lgt’ — A negative
     measurement fixture where an item is declared more than once.

   - ‘malformed_measurement_self.lgt’ — A negative measurement fixture
     where an item is measured against itself.

   - ‘malformed_measurement_non_numeric.lgt’ — A negative measurement
     fixture where a measurement value is not numeric.

   - ‘malformed_measurement_non_positive_weight.lgt’ — A negative
     measurement fixture where a measurement weight is not positive.

   - ‘temporal_two_period_chain.lgt’ — A compact temporal pairwise
     dataset with two rating periods and three players, useful for smoke
     testing periodic rating carryover.

   - ‘temporal_draws.lgt’ — A compact temporal pairwise dataset with a
     draw, useful for testing score handling in temporal game results.

   - ‘temporal_idle_periods.lgt’ — A temporal pairwise dataset with an
     empty period between two played periods, useful for testing
     inactivity handling.


File: TheLogtalkHandbook-3.101.0.info,  Node: reader,  Next: recorded_database,  Prev: ranking_protocols,  Up: Libraries

6.207 ‘reader’
==============

The ‘reader’ object provides portable predicates for reading text file
and text stream contents to lists of terms, characters, or character
codes and for reading binary files to lists of bytes.  The text file API
is loosely based on the SWI-Prolog ‘readutil’ module.

* Menu:

* API documentation: API documentation<223>.
* Loading: Loading<227>.
* Testing: Testing<218>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<223>,  Next: Loading<227>,  Up: reader

6.207.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#reader’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<227>,  Next: Testing<218>,  Prev: API documentation<223>,  Up: reader

6.207.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(reader(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<218>,  Prev: Loading<227>,  Up: reader

6.207.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(reader(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: recorded_database,  Next: redis,  Prev: reader,  Up: Libraries

6.208 ‘recorded_database’
=========================

The ‘recorded_database’ library aims to help port Prolog code using the
legacy recorded database.  Ported applications should still consider
migrating to more standard solutions to handle dynamic data that must
survive backtracking.

* Menu:

* API documentation: API documentation<224>.
* Loading: Loading<228>.
* Testing: Testing<219>.
* Usage: Usage<97>.
* Known issues: Known issues<17>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<224>,  Next: Loading<228>,  Up: recorded_database

6.208.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#recorded_database’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<228>,  Next: Testing<219>,  Prev: API documentation<224>,  Up: recorded_database

6.208.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(recorded_database(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<219>,  Next: Usage<97>,  Prev: Loading<228>,  Up: recorded_database

6.208.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(recorded_database(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<97>,  Next: Known issues<17>,  Prev: Testing<219>,  Up: recorded_database

6.208.4 Usage
-------------

The ‘recorded_database_core’ category implements the library predicates.
This category is imported by the default ‘recorded_database’ object to
provide application global database.  To make the database local and
thus minimize potential record clashes, the category can be imported by
one or more application objects.  Use protected or private import to
restrict the scope of the library predicates.  For example:

     :- object(foo,
         imports(private::recorded_database_core)).

         bar :-
             ^^recorda(key, value(1)),
             ...

     :- end_object.


File: TheLogtalkHandbook-3.101.0.info,  Node: Known issues<17>,  Prev: Usage<97>,  Up: recorded_database

6.208.5 Known issues
--------------------

Currently, references are non-negative integers.  They still must be
regarded as opaque terms and subject to change without notice.  But
using integers can result in integer overflows when running on backends
with bounded integers in applications performing a large number of
database updates.


File: TheLogtalkHandbook-3.101.0.info,  Node: redis,  Next: regression_protocols,  Prev: recorded_database,  Up: Libraries

6.209 ‘redis’
=============

Redis client library.  Supports ECLiPSe, GNU Prolog, SICStus Prolog,
SWI-Prolog, Trealla Prolog, and XVM.

For general information on Redis, including a list of the available
commands, visit:

     https://redis.io

* Menu:

* API documentation: API documentation<225>.
* Loading: Loading<229>.
* Testing: Testing<220>.
* Supported Redis Features::
* Credits: Credits<4>.
* Known issues: Known issues<18>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<225>,  Next: Loading<229>,  Up: redis

6.209.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#redis’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<229>,  Next: Testing<220>,  Prev: API documentation<225>,  Up: redis

6.209.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(redis(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<220>,  Next: Supported Redis Features,  Prev: Loading<229>,  Up: redis

6.209.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(redis(tester)).

The tests assume a localhost Redis server running on the default port
(6379) if the ‘REDIS_HOST’ and ‘REDIS_PORT’ environment variables are
not defined.  If the server is not detected, the tests are skipped.

The unit tests were originally written by Sean Charles for his GNU
Prolog Redis client library:

     https://github.com/emacstheviking/gnuprolog-redisclient

The Logtalk version is a straight-forward port of the original tests
using the ‘test/1’ dialect of ‘lgtunit’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Supported Redis Features,  Next: Credits<4>,  Prev: Testing<220>,  Up: redis

6.209.4 Supported Redis Features
--------------------------------

This library provides wrapper predicates for commonly used Redis
operations across multiple data types.  For Redis commands not covered
by a wrapper, use the generic ‘redis::send/3’ predicate with the command
as a compound term.

* Menu:

* Connection Management::
* String Operations::
* Key Operations::
* Hash Operations::
* List Operations::
* Set Operations::
* Sorted Set Operations::
* Usage Examples::


File: TheLogtalkHandbook-3.101.0.info,  Node: Connection Management,  Next: String Operations,  Up: Supported Redis Features

6.209.4.1 Connection Management
...............................

   - ‘connect/1’ - Connect to localhost on default port (6379)

   - ‘connect/3’ - Connect to specified host and port

   - ‘disconnect/1’ - Disconnect from Redis server

   - ‘send/3’ - Send any Redis command and receive reply


File: TheLogtalkHandbook-3.101.0.info,  Node: String Operations,  Next: Key Operations,  Prev: Connection Management,  Up: Supported Redis Features

6.209.4.2 String Operations
...........................

   - ‘get/3’ - Get the value of a key

   - ‘set/4’ - Set the value of a key

   - ‘append/4’ - Append a value to a key

   - ‘getrange/5’ - Get substring of string stored at key

   - ‘setrange/5’ - Overwrite part of a string at key starting at offset

   - ‘strlen/3’ - Get the length of the value stored at key

   - ‘mget/3’ - Get values of multiple keys

   - ‘mset/3’ - Set multiple key-value pairs atomically

   - ‘incr/3’ - Increment integer value of key by one

   - ‘decr/3’ - Decrement integer value of key by one

   - ‘incrby/4’ - Increment integer value of key by amount

   - ‘decrby/4’ - Decrement integer value of key by amount


File: TheLogtalkHandbook-3.101.0.info,  Node: Key Operations,  Next: Hash Operations,  Prev: String Operations,  Up: Supported Redis Features

6.209.4.3 Key Operations
........................

   - ‘del/3’ - Delete a key

   - ‘exists/3’ - Check if a key exists

   - ‘keys/3’ - Find all keys matching a pattern

   - ‘ttl/3’ - Get time to live for a key in seconds

   - ‘expire/4’ - Set a timeout on a key in seconds

   - ‘persist/3’ - Remove the expiration from a key

   - ‘rename/4’ - Rename a key

   - ‘type/3’ - Get the type of value stored at key


File: TheLogtalkHandbook-3.101.0.info,  Node: Hash Operations,  Next: List Operations,  Prev: Key Operations,  Up: Supported Redis Features

6.209.4.4 Hash Operations
.........................

Hashes are maps between string fields and string values, ideal for
representing objects.

   - ‘hset/5’ - Set field in a hash

   - ‘hget/4’ - Get value of field in a hash

   - ‘hgetall/3’ - Get all fields and values in a hash

   - ‘hdel/4’ - Delete field from a hash

   - ‘hexists/4’ - Check if field exists in a hash

   - ‘hkeys/3’ - Get all field names in a hash

   - ‘hvals/3’ - Get all values in a hash

   - ‘hlen/3’ - Get number of fields in a hash


File: TheLogtalkHandbook-3.101.0.info,  Node: List Operations,  Next: Set Operations,  Prev: Hash Operations,  Up: Supported Redis Features

6.209.4.5 List Operations
.........................

Redis lists are ordered collections of strings, sorted by insertion
order.

   - ‘lpush/4’ - Prepend value to a list

   - ‘rpush/4’ - Append value to a list

   - ‘lpop/3’ - Remove and return first element of list

   - ‘rpop/3’ - Remove and return last element of list

   - ‘lrange/5’ - Get range of elements from list

   - ‘llen/3’ - Get length of list

   - ‘lrem/5’ - Remove elements from list

   - ‘ltrim/5’ - Trim list to specified range


File: TheLogtalkHandbook-3.101.0.info,  Node: Set Operations,  Next: Sorted Set Operations,  Prev: List Operations,  Up: Supported Redis Features

6.209.4.6 Set Operations
........................

Redis sets are unordered collections of unique strings.

   - ‘sadd/4’ - Add member to a set

   - ‘srem/4’ - Remove member from a set

   - ‘smembers/3’ - Get all members in a set

   - ‘sismember/4’ - Check if value is member of set

   - ‘scard/3’ - Get number of members in a set


File: TheLogtalkHandbook-3.101.0.info,  Node: Sorted Set Operations,  Next: Usage Examples,  Prev: Set Operations,  Up: Supported Redis Features

6.209.4.7 Sorted Set Operations
...............................

Sorted sets are collections of unique strings (members) ordered by an
associated score.  Members are unique, but scores may repeat.

   - ‘zadd/5’ - Add member with score to sorted set

   - ‘zrem/4’ - Remove member from sorted set

   - ‘zrange/5’ - Get range of members from sorted set by index

   - ‘zrank/4’ - Get rank (index) of member in sorted set

   - ‘zcard/3’ - Get number of members in sorted set

   - ‘zscore/4’ - Get score of member in sorted set


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage Examples,  Prev: Sorted Set Operations,  Up: Supported Redis Features

6.209.4.8 Usage Examples
........................

     % Connect and perform basic string operations
     ?- redis::connect(Connection),
        redis::set(Connection, mykey, 'Hello World', Status),
        redis::get(Connection, mykey, Value),
        redis::disconnect(Connection).
     Status = 'OK',
     Value = 'Hello World'.

     % Working with hashes
     ?- redis::connect(Connection),
        redis::hset(Connection, user:1000, name, 'John Doe', _),
        redis::hset(Connection, user:1000, email, 'john@example.com', _),
        redis::hgetall(Connection, user:1000, Fields),
        redis::disconnect(Connection).
     Fields = [bulk(name), bulk('John Doe'), bulk(email), bulk('john@example.com')].

     % Using lists as queues
     ?- redis::connect(Connection),
        redis::rpush(Connection, queue, task1, _),
        redis::rpush(Connection, queue, task2, _),
        redis::lpop(Connection, queue, Task),
        redis::disconnect(Connection).
     Task = task1.

     % Batch operations with mget/mset
     ?- redis::connect(Connection),
        redis::mset(Connection, [key1, val1, key2, val2], Status),
        redis::mget(Connection, [key1, key2], Values),
        redis::disconnect(Connection).
     Status = 'OK',
     Values = [bulk(val1), bulk(val2)].

     % Key expiration
     ?- redis::connect(Connection),
        redis::set(Connection, session:xyz, 'user_data', _),
        redis::expire(Connection, session:xyz, 3600, _), % Expire in 1 hour
        redis::ttl(Connection, session:xyz, TTL),
        redis::disconnect(Connection).
     TTL = 3600.

     % Using send/3 for commands without wrappers
     ?- redis::connect(Connection),
        redis::send(Connection, info(server), Reply),
        redis::disconnect(Connection).


File: TheLogtalkHandbook-3.101.0.info,  Node: Credits<4>,  Next: Known issues<18>,  Prev: Supported Redis Features,  Up: redis

6.209.5 Credits
---------------

This library is inspired by the Sean Charles GNU Prolog Redis client
library.


File: TheLogtalkHandbook-3.101.0.info,  Node: Known issues<18>,  Prev: Credits<4>,  Up: redis

6.209.6 Known issues
--------------------

Recent versions of macOS seem to disable the mapping of ‘localhost’ to
‘127.0.0.1’.  This issue may prevent running this library unit tests and
the ‘redis::connect/1’ predicate from working.  This can be fixed either
by editing the ‘/etc/hosts’ file or by using in alternative the
predicate ‘redis::connect/3’ with ‘'127.0.0.1'’ as the first argument.


File: TheLogtalkHandbook-3.101.0.info,  Node: regression_protocols,  Next: regression_tree,  Prev: redis,  Up: Libraries

6.210 ‘regression_protocols’
============================

This library provides protocols used in the implementation of machine
learning regression algorithms.  Datasets are represented as objects
implementing the ‘regression_dataset_protocol’ protocol.  Regressors are
represented as objects importing the ‘regressor_common’ category.  This
category provides shared helpers for regressor defaults, dataset
validation, diagnostics metadata, export, and pretty-printing support.

Learned regressors expose diagnostics using the shared ‘diagnostics/2’,
‘diagnostic/2’, and ‘regressor_options/2’ predicates.  Concrete
regressor implementations store effective training options in the
diagnostics metadata under an ‘options(Options)’ term.

This library also provides regression test datasets under the
‘test_datasets’ directory.

* Menu:

* API documentation: API documentation<226>.
* Loading: Loading<230>.
* Testing: Testing<221>.
* Test datasets: Test datasets<7>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<226>,  Next: Loading<230>,  Up: regression_protocols

6.210.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#regression_protocols’ link in a
web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<230>,  Next: Testing<221>,  Prev: API documentation<226>,  Up: regression_protocols

6.210.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(regression_protocols(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<221>,  Next: Test datasets<7>,  Prev: Loading<230>,  Up: regression_protocols

6.210.3 Testing
---------------

To test this library predicates, shared categories, and datasets, load
the ‘tester.lgt’ file:

| ?- logtalk_load(regression_protocols(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Test datasets<7>,  Prev: Testing<221>,  Up: regression_protocols

6.210.4 Test datasets
---------------------

The ‘test_datasets’ directory includes the following compact regression
datasets and validation fixtures:

   - ‘duplicate_attribute_declaration.lgt’: invalid dataset fixture
     containing a duplicated attribute declaration in the dataset
     schema.

   - ‘duplicate_attribute_example.lgt’: invalid dataset fixture
     containing a duplicated declared attribute binding in one example.

   - ‘grouped_categorical_signal.lgt’: regression dataset with one
     relevant continuous attribute and one irrelevant categorical
     attribute for testing shrinkage of encoded categorical
     coefficients.

   - ‘intercept_only.lgt’: constant-target dataset for
     intercept-learning tests.

   - ‘invalid_target.lgt’: invalid dataset with a non-numeric target for
     negative tests.

   - ‘mixed_signal.lgt’: mixed continuous and categorical regression
     dataset.

   - ‘plane.lgt’: two-feature regression dataset following the plane ‘z
     = 3x1 - 2x2 + 5’.

   - ‘simple_line.lgt’: single-feature regression dataset following the
     line ‘y = 2x + 1’.

   - ‘sparse_mixed_signal.lgt’: mixed regression dataset with omitted
     attribute-value pairs used to exercise missing-value handling
     during training and prediction.

   - ‘sparse_signal.lgt’: two-feature regression dataset where only the
     signal attribute contributes to the target and the noise attribute
     is orthogonal to it.

   - ‘step_signal.lgt’: piecewise-constant regression dataset for
     tree-based and neighborhood regressor testing.

   - ‘undeclared_attribute_example.lgt’: invalid dataset fixture
     containing an undeclared attribute binding in one example.

   - ‘wide_mixed_signal.lgt’: synthetic wide mixed regression dataset
     with many continuous and categorical predictors for non-trivial
     linear-model benchmarking.


File: TheLogtalkHandbook-3.101.0.info,  Node: regression_tree,  Next: regularized_bradley_terry_ranker,  Prev: regression_protocols,  Up: Libraries

6.211 ‘regression_tree’
=======================

Regression tree regressor supporting continuous and mixed-feature
datasets.  The library implements the ‘regressor_protocol’ defined in
the ‘regression_protocols’ library and learns a binary regression tree
using recursive variance-reduction splits that select the encoded
feature threshold maximizing variance reduction.

* Menu:

* API documentation: API documentation<227>.
* Loading: Loading<231>.
* Testing: Testing<222>.
* Export header format: Export header format<4>.
* Features: Features<69>.
* Regressor representation: Regressor representation<9>.
* Diagnostics syntax: Diagnostics syntax<22>.
* Options: Options<67>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<227>,  Next: Loading<231>,  Up: regression_tree

6.211.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#regression_tree’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<231>,  Next: Testing<222>,  Prev: API documentation<227>,  Up: regression_tree

6.211.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(regression_tree(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<222>,  Next: Export header format<4>,  Prev: Loading<231>,  Up: regression_tree

6.211.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(regression_tree(tester)).

To run the performance benchmark suite, load the
‘tester_performance.lgt’ file:

     | ?- logtalk_load(regression_tree(tester_performance)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Export header format<4>,  Next: Features<69>,  Prev: Testing<222>,  Up: regression_tree

6.211.4 Export header format
----------------------------

The shared exporter in the ‘regressor_common’ category writes a header
before the exported clauses in the following format:

     % exported regressor predicate: Functor/Arity
     % training dataset: Dataset
     % target: Target
     % attributes: Attributes
     % diagnostics: Diagnostics
     % Functor(Encoders, FeatureLabels, Tree, Diagnostics)
     Functor(Encoders, FeatureLabels, Tree, Diagnostics)

The exported clauses serialize the learned regressor state so that
loading the file gives a regressor term that can be passed directly to
the ‘predict/3’ predicate.

When exporting a serialized regressor term, using a noun such as
‘regressor/4’ or ‘model/4’ is recommended.


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<69>,  Next: Regressor representation<9>,  Prev: Export header format<4>,  Up: regression_tree

6.211.5 Features
----------------

   - 'Variance-Reduction Splits': Selects binary thresholds over encoded
     features to reduce target variance.

   - 'Continuous and Mixed Features': Supports continuous attributes and
     categorical attributes.

   - 'Categorical Features Encoding': Uses reference-level dummy coding
     derived from the declared dataset attribute values, with a
     missing-value indicator, and the resulting encoded features are
     treated as ordinary numeric split features.

   - 'Missing Values': Missing feature values represented using
     anonymous variables or omitted attribute-value pairs are encoded
     using explicit missing-value indicator features during both
     training and prediction.

   - 'Per-Split Feature Sampling': Optionally samples a subset of
     dataset attributes at each split before searching for the best
     partition.

   - 'Optional Feature Scaling': Continuous attributes can be
     standardized using z-score scaling before tree induction.

   - 'Diagnostics Metadata': Learned regressors record model name,
     target, training example count, encoded feature count, and
     effective options, accessible using the shared regression
     diagnostics predicates.

   - 'Model Export': Learned regressors can be exported as predicate
     clauses or written to a file.

   - 'Readable Trees': Includes a pretty-printer for inspecting learned
     tree structure.

   - 'Reference Benchmarks': Includes a dedicated performance suite
     reporting training time, RMSE, and MAE for representative
     regression datasets.


File: TheLogtalkHandbook-3.101.0.info,  Node: Regressor representation<9>,  Next: Diagnostics syntax<22>,  Prev: Features<69>,  Up: regression_tree

6.211.6 Regressor representation
--------------------------------

The learned regressor is represented by default as:

   - ‘regression_tree_regressor(Encoders, FeatureLabels, Tree,
     Diagnostics)’

In this representation, ‘Tree’ is built from ‘leaf(Prediction)’ and
‘node(Index, Threshold, FallbackPrediction, Left, Right)’ terms and
‘Diagnostics’ stores training metadata including the effective options.


File: TheLogtalkHandbook-3.101.0.info,  Node: Diagnostics syntax<22>,  Next: Options<67>,  Prev: Regressor representation<9>,  Up: regression_tree

6.211.7 Diagnostics syntax
--------------------------

The ‘diagnostics/2’ predicate returns a list of metadata terms with the
form:

     [
         model(regression_tree),
         target(Target),
         training_example_count(TrainingExampleCount),
         options(Options),
         encoded_feature_count(FeatureCount)
     ]

Where:

   - ‘model(regression_tree)’ identifies the learning algorithm that
     produced the regressor.

   - ‘target(Target)’ stores the target attribute name declared by the
     training dataset.

   - ‘training_example_count(TrainingExampleCount)’ stores the number of
     examples used during training.

   - ‘options(Options)’ stores the effective learning options after
     merging the user options with the library defaults.

   - ‘encoded_feature_count(FeatureCount)’ stores the number of numeric
     features induced by the encoder list, including missing-value
     indicator features.

Use the ‘regression_protocols’ ‘diagnostic/2’ and ‘regressor_options/2’
helper predicates when you only need a single metadata term or the
effective options.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<67>,  Prev: Diagnostics syntax<22>,  Up: regression_tree

6.211.8 Options
---------------

The ‘learn/3’ predicate accepts the following options:

   - ‘maximum_depth/1’: Maximum depth allowed for the induced regression
     tree.  Lower values yield smaller trees; higher values allow more
     detailed partitioning of the training data.  The default is ‘10’.

   - ‘minimum_samples_leaf/1’: Minimum number of training examples
     required in a leaf.  This option also prevents candidate splits
     that would create child nodes smaller than the requested size.  The
     default is ‘1’.

   - ‘minimum_variance_reduction/1’: Minimum variance-reduction gain
     required for accepting a split.  Higher values make the learner
     more conservative by pruning weak splits during induction.  The
     default is ‘0.0’.

   - ‘maximum_features_per_split/1’: Number of dataset attributes
     sampled at each split when searching for the best partition.
     Accepted values are a positive integer or ‘all’.  The default is
     ‘all’.

   - ‘feature_scaling/1’: Controls z-score standardization of continuous
     attributes before tree induction.  Accepted values are ‘true’ and
     ‘false’.  The default is ‘false’.


File: TheLogtalkHandbook-3.101.0.info,  Node: regularized_bradley_terry_ranker,  Next: rest,  Prev: regression_tree,  Up: Libraries

6.212 ‘regularized_bradley_terry_ranker’
========================================

Regularized Bradley-Terry MAP pairwise preference ranker.  It uses a
deterministic MM-style posterior-mode update for a Bradley-Terry
likelihood regularized by an explicit independent Gamma prior over item
strengths.

The library implements the ‘ranker_protocol’ defined in the
‘ranking_protocols’ library.  It provides predicates for learning a
ranker from pairwise preferences, using it to order candidate items, and
exporting it as a list of predicate clauses or to a file.

Datasets are represented as objects implementing the
‘pairwise_ranking_dataset_protocol’ protocol from the
‘ranking_protocols’ library.  See the ‘test_datasets’ directory for
examples.  The training dataset must declare each ranked item once,
enumerate positive-weight pairwise preferences between distinct declared
items, and induce a connected undirected comparison graph.  Unlike the
unregularized Bradley-Terry model, the directed win graph is not
required to be strongly connected.

* Menu:

* API documentation: API documentation<228>.
* Loading: Loading<232>.
* Testing: Testing<223>.
* Features: Features<70>.
* Dataset requirements: Dataset requirements<5>.
* Usage: Usage<98>.
* Diagnostics syntax: Diagnostics syntax<23>.
* Options: Options<68>.
* Ranker representation: Ranker representation<15>.
* References: References<49>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<228>,  Next: Loading<232>,  Up: regularized_bradley_terry_ranker

6.212.1 API documentation
-------------------------

Open the
‘../../apis/library_index.html#regularized_bradley_terry_ranker’ link in
a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<232>,  Next: Testing<223>,  Prev: API documentation<228>,  Up: regularized_bradley_terry_ranker

6.212.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(regularized_bradley_terry_ranker(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<223>,  Next: Features<70>,  Prev: Loading<232>,  Up: regularized_bradley_terry_ranker

6.212.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(regularized_bradley_terry_ranker(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<70>,  Next: Dataset requirements<5>,  Prev: Testing<223>,  Up: regularized_bradley_terry_ranker

6.212.4 Features
----------------

   - 'Pairwise Preference Learning': Learns positive item strengths from
     weighted head-to-head outcomes.

   - 'Explicit Gamma Prior': Uses a separate MAP model with an explicit
     independent Gamma prior over item strengths.

   - 'Finite Regularized Fit': Admits connected pairwise datasets whose
     directed win graph is not strongly connected, instead of rejecting
     them as non-identifiable maximum-likelihood problems.

   - 'Deterministic Ranking': Orders candidate items by learned strength
     with deterministic tie-breaking.

   - 'Strict Dataset Validation': Rejects duplicate items, undeclared
     items, self-preferences, non-positive weights, and disconnected
     undirected comparison graphs.

   - 'Training Diagnostics': Learned rankers include the effective Gamma
     prior, convergence, iteration, and dataset summary metadata that
     can be accessed using the ‘diagnostics/2’ predicate.

   - 'Ranker Export': Learned rankers can be exported as self-contained
     terms.

   - 'Shared Pairwise Infrastructure': Reuses the shared pairwise
     preprocessing and MM-iteration scaffolding from the
     ‘ranking_protocols’ library.


File: TheLogtalkHandbook-3.101.0.info,  Node: Dataset requirements<5>,  Next: Usage<98>,  Prev: Features<70>,  Up: regularized_bradley_terry_ranker

6.212.5 Dataset requirements
----------------------------

This implementation still requires the undirected comparison graph
induced by the preferences to be connected, but unlike the unregularized
Bradley-Terry model it does not require the directed win graph to be
strongly connected.  The explicit Gamma prior regularizes dominance
partitions and one-way chains, yielding a finite posterior mode for
connected datasets that would otherwise fail the maximum-likelihood
existence check.

For the original unregularized maximum-likelihood Bradley-Terry model,
which keeps the same pairwise-preference interface but requires the
directed win graph to be strongly connected, see the
‘bradley_terry_ranker’ library.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<98>,  Next: Diagnostics syntax<23>,  Prev: Dataset requirements<5>,  Up: regularized_bradley_terry_ranker

6.212.6 Usage
-------------

* Menu:

* Learning a ranker: Learning a ranker<15>.
* Inspecting diagnostics: Inspecting diagnostics<13>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Learning a ranker<15>,  Next: Inspecting diagnostics<13>,  Up: Usage<98>

6.212.6.1 Learning a ranker
...........................

     % Learn from a pairwise ranking dataset object
     | ?- regularized_bradley_terry_ranker::learn(my_dataset, Ranker).
     ...

     % Learn with custom iteration and Gamma-prior options
     | ?- regularized_bradley_terry_ranker::learn(my_dataset, Ranker, [maximum_iterations(500), tolerance(1.0e-7), gamma_prior(gamma(3.0, 4.0))]).
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Inspecting diagnostics<13>,  Prev: Learning a ranker<15>,  Up: Usage<98>

6.212.6.2 Inspecting diagnostics
................................

     % Inspect convergence, prior, and dataset summary metadata
     | ?- regularized_bradley_terry_ranker::learn(my_dataset, Ranker),
          regularized_bradley_terry_ranker::diagnostics(Ranker, Diagnostics).
     Diagnostics = [...]
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Diagnostics syntax<23>,  Next: Options<68>,  Prev: Usage<98>,  Up: regularized_bradley_terry_ranker

6.212.7 Diagnostics syntax
--------------------------

The ‘diagnostics/2’ predicate returns a list of metadata terms with the
form:

     [
         model(regularized_bradley_terry_ranker),
         options(Options),
         prior(gamma(Shape, Rate)),
         convergence(Status),
         iterations(Iterations),
         final_delta(FinalDelta),
         dataset_summary(DatasetSummary)
     ]

Where:

   - ‘model(regularized_bradley_terry_ranker)’ identifies the learning
     algorithm that produced the ranker.

   - ‘options(Options)’ stores the effective learning options after
     merging the user options with the library defaults.

   - ‘prior(gamma(Shape, Rate))’ stores the effective Gamma prior
     hyperparameters.

   - ‘convergence(Status)’ records the training stop condition.  The
     current values are ‘converged’ and ‘maximum_iterations_exhausted’.

   - ‘iterations(Iterations)’ stores the number of update iterations
     that were executed.

   - ‘final_delta(FinalDelta)’ stores the maximum absolute strength
     update in the last iteration.

   - ‘dataset_summary(DatasetSummary)’ stores a summary list describing
     the validated training dataset.

Use the ‘ranking_protocols’ ‘diagnostic/2’ and ‘ranker_options/2’ helper
predicates when you only need a single metadata term or the effective
options.

* Menu:

* Ranking candidate items: Ranking candidate items<14>.
* Exporting the ranker: Exporting the ranker<13>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Ranking candidate items<14>,  Next: Exporting the ranker<13>,  Up: Diagnostics syntax<23>

6.212.7.1 Ranking candidate items
.................................

     % Rank a candidate set from most preferred to least preferred
     | ?- regularized_bradley_terry_ranker::learn(my_dataset, Ranker),
          regularized_bradley_terry_ranker::rank(Ranker, [item_a, item_b, item_c], Ranking).
     Ranking = [...]
     ...

Candidate lists must be proper lists of unique, ground items declared by
the training dataset.  Invalid ranker terms, duplicate candidates, and
candidates containing variables are rejected with errors instead of
being silently accepted.


File: TheLogtalkHandbook-3.101.0.info,  Node: Exporting the ranker<13>,  Prev: Ranking candidate items<14>,  Up: Diagnostics syntax<23>

6.212.7.2 Exporting the ranker
..............................

Learned rankers can be exported as a list of clauses or to a file for
later use.

     % Export as predicate clauses
     | ?- regularized_bradley_terry_ranker::learn(my_dataset, Ranker),
          regularized_bradley_terry_ranker::export_to_clauses(my_dataset, Ranker, my_ranker, Clauses).
     Clauses = [my_ranker(regularized_bt_ranker(...))]
     ...

     % Export to a file
     | ?- regularized_bradley_terry_ranker::learn(my_dataset, Ranker),
          regularized_bradley_terry_ranker::export_to_file(my_dataset, Ranker, my_ranker, 'ranker.pl').
     ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<68>,  Next: Ranker representation<15>,  Prev: Diagnostics syntax<23>,  Up: regularized_bradley_terry_ranker

6.212.8 Options
---------------

The following options can be passed to the ‘learn/3’ predicate:

   - ‘maximum_iterations(MaximumIterations)’: Positive integer iteration
     bound.

   - ‘tolerance(Tolerance)’: Positive convergence tolerance.

   - ‘gamma_prior(gamma(Shape, Rate))’: Gamma-prior hyperparameters.
     The current implementation requires ‘Shape > 1’ and ‘Rate > 0’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Ranker representation<15>,  Next: References<49>,  Prev: Options<68>,  Up: regularized_bradley_terry_ranker

6.212.9 Ranker representation
-----------------------------

The learned ranker is represented by a compound term of the form:

     regularized_bt_ranker(Items, Strengths, Diagnostics)

Where:

   - ‘Items’: List of ranked items.

   - ‘Scores’: List of ‘Item-Strength’ pairs.

   - ‘Diagnostics’: List of metadata terms, including the effective
     options, Gamma prior, convergence status, iteration count, final
     update delta, and dataset summary.

When exported using ‘export_to_clauses/4’ or ‘export_to_file/4’, this
ranker term is serialized directly as the single argument of the
generated predicate clause so that the exported model can be loaded and
reused as-is.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<49>,  Prev: Ranker representation<15>,  Up: regularized_bradley_terry_ranker

6.212.10 References
-------------------

  1. Bradley, R. A. and Terry, M. E. (1952).  Rank analysis of
     incomplete block designs: I. The method of paired comparisons.
     'Biometrika', 39(3/4), 324-345.

  2. Hunter, D. R. (2004).  MM algorithms for generalized Bradley-Terry
     models.  'The Annals of Statistics', 32(1), 384-406.

  3. Caron, F. and Doucet, A. (2012).  Efficient Bayesian inference for
     generalized Bradley-Terry models.  'Journal of Computational and
     Graphical Statistics', 21(1), 174-196.


File: TheLogtalkHandbook-3.101.0.info,  Node: rest,  Next: ridge_regression,  Prev: regularized_bradley_terry_ranker,  Up: Libraries

6.213 ‘rest’
============

The ‘rest’ library provides a small REST authoring layer on top of the
existing ‘http_router’ library.  It is implemented as a category so that
REST application objects can continue to implement the
‘http_handler_protocol’ protocol directly while reusing the existing
router dispatch, request annotation, middleware, and OpenAPI derivation
logic.

This library reuses the ‘http_core’ and ‘http_router’.  It derives
router hooks from higher-level endpoint descriptors, provides small
request and response helpers, and normalizes simple action result terms
into HTTP responses.

* Menu:

* Layering: Layering<4>.
* API documentation: API documentation<229>.
* Loading: Loading<233>.
* Testing: Testing<224>.
* Current scope: Current scope<25>.
* OpenAPI integration::
* Current limitations: Current limitations<18>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Layering<4>,  Next: API documentation<229>,  Up: rest

6.213.1 Layering
----------------

‘rest’ is the highest-level authoring layer in the current HTTP stack:

   - Start with ‘http_core’ library for normalized HTTP messages and
     with the ‘http_router’ library for declarative routing.

   - Use the ‘rest’ library when you want to describe endpoints with
     ‘endpoint/5’, keep the inherited ‘handle/2’ entry point, and return
     small result terms instead of building every response manually.

   - Stay with the ‘http_router’ library when you need direct control
     over ‘route/4’, custom handler predicates, or router hooks without
     the higher-level endpoint layer.

   - Pair REST applications with the ‘open_api’ library when you want
     derived OpenAPI documents or opt-in request and response contract
     validation.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<229>,  Next: Loading<233>,  Prev: Layering<4>,  Up: rest

6.213.2 API documentation
-------------------------

Open the ‘../../apis/library_index.html#rest’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<233>,  Next: Testing<224>,  Prev: API documentation<229>,  Up: rest

6.213.3 Loading
---------------

To load the library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(rest(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<224>,  Next: Current scope<25>,  Prev: Loading<233>,  Up: rest

6.213.4 Testing
---------------

To test this library, load the ‘tester.lgt’ file:

     | ?- logtalk_load(rest(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Current scope<25>,  Next: OpenAPI integration,  Prev: Testing<224>,  Up: rest

6.213.5 Current scope
---------------------

The current version provides one imported routing predicate through the
category inheritance from ‘http_router’ plus request and response helper
predicates:

   - ‘handle/2’

   - ‘path_parameter/3’

   - ‘query_parameter/3’

   - ‘request_header/3’

   - ‘request_body/2’

   - ‘json_body/2’

   - ‘json_object_body/2’

   - ‘json_array_body/2’

   - ‘form_body/2’

   - ‘text_body/2’

   - ‘binary_body/2’

   - ‘json_response/4-5’

   - ‘created_response/4’

   - ‘no_content_response/2’

   - ‘problem_response/6’

The category also exposes optional OpenAPI contract validation hooks:

   - ‘open_api_validate_request/1’

   - ‘open_api_request_validation_error_response/4’

   - ‘open_api_validate_response/1’

   - ‘open_api_response_validation_error_response/5’

The category also exposes optional action failure and error
normalization hooks:

   - ‘rest_action_failure_response/3’

   - ‘rest_action_error_response/4’

Importing REST application objects are expected to define endpoint
descriptors using:

   - ‘endpoint(Id, Method, Path, Action, Options)’

Endpoint identifiers must be unique within the importing object.  When
the object also exposes OpenAPI operations through ‘http_router’, those
same identifiers are reused as operation identifiers.

The ‘Action’ argument is the name of a declared local predicate with
arity 2, typically a protected predicate.  The action predicate receives
the annotated request and returns or throws one of the currently
supported result terms:

   - ‘ok(JSON)’

   - ‘created(Location, JSON)’

   - ‘no_content’

   - ‘json(Status, JSON)’

   - ‘json(Status, Headers, JSON)’

   - ‘problem(Status, Type, Title, Detail)’

   - ‘response(Response)’ or a normalized ‘response/5’ term directly

The category derives the ‘http_router’ hooks from those endpoint
descriptors:

   - ‘route/4’

   - ‘route_metadata/2’

   - ‘route_produces/2’

All matched routes dispatch through a single internal action runner that
calls the endpoint action and normalizes its returned or thrown result.

Endpoint options are passed through as route metadata except for the
special ‘produces(MediaTypes)’ option, which is translated into
‘route_produces/2’.  This keeps endpoint metadata available to action
predicates and response middleware and also allows router-level OpenAPI
derivation to keep working.

That same metadata pass-through also allows REST applications to reuse
router companion categories.  For example, an object can import
‘http_router_digest_auth(_, _, _)’, declare ‘digest_auth(Options)’ in
endpoint options, delegate ‘authorize_routed_request/2’ to
‘authorize_digest_auth_request/2’, and register
‘add_digest_authentication_info/3’ as response middleware.

The current helper predicates read the normalized HTTP request terms
provided by ‘http_core’:

     request(Method, Target, Version, Headers, Body, Properties)

They rely on router annotations such as ‘route/1’ and ‘path_params/1’
plus the normalized derived properties produced by the ‘http_core’
library such as ‘query_pairs/1’.  The ‘path_parameter/3’ and
‘query_parameter/3’ helpers are deterministic lookups.  The decoded body
helpers return ‘400 Bad Request’ problem responses when the current
action expects a JSON, form, text, or binary body and the normalized
request body is missing or has a different decoded shape.  The
‘json_object_body/2’ and ‘json_array_body/2’ helpers build on
‘json_body/2’ and additionally require the decoded JSON payload to be an
object or array term respectively.

Action result normalization currently builds normalized HTTP response
terms from returned or thrown supported result terms using these rules:

   - successful JSON responses use the negotiated router media type when
     the request carries a JSON-compatible ‘response_media_type/1’
     annotation and otherwise fall back to ‘application/json’

   - problem responses always use ‘application/problem+json’

Plain action failure and unsupported exceptions still default to generic
‘500 Internal Server Error’ problem responses, but importing objects can
override those defaults using ‘rest_action_failure_response/3’ and
‘rest_action_error_response/4’.

When ‘open_api_validate_request/1’ succeeds for a matched endpoint, the
category validates the normalized request against the derived OpenAPI
operation descriptor before calling the endpoint action.  When
‘open_api_validate_response/1’ succeeds for a matched endpoint, the
category validates the normalized response after action result
normalization.

By default, request validation failures preserve three classes of client
error: unsupported request media types return ‘415 Unsupported Media
Type’, schema-invalid request bodies return ‘422 Unprocessable Content’,
and other request validation failures return ‘400 Bad Request’.
Response validation failures still return a ‘500 Internal Server Error’
‘application/problem+json’ response.  Importing objects can override
those defaults using the corresponding validation error response hooks.
Validation is skipped for the synthetic router requests used internally
for OpenAPI request and response inference.


File: TheLogtalkHandbook-3.101.0.info,  Node: OpenAPI integration,  Next: Current limitations<18>,  Prev: Current scope<25>,  Up: rest

6.213.6 OpenAPI integration
---------------------------

When an importing object also implements the
‘open_api_provider_protocol’ protocol, the inherited ‘http_router’
OpenAPI derivation continues to work.  Endpoint options such as
‘summary/1’, ‘description/1’, ‘tags/1’, ‘deprecated/1’, ‘security/1’,
‘parameters/1’, ‘request_body/1’, and ‘responses/1’ are exposed through
‘route_metadata/2’, while ‘produces(MediaTypes)’ drives
‘route_produces/2’ and therefore response media type inference.


File: TheLogtalkHandbook-3.101.0.info,  Node: Current limitations<18>,  Prev: OpenAPI integration,  Up: rest

6.213.7 Current limitations
---------------------------

   - Request and response OpenAPI contract validation is opt-in per
     endpoint using the validation hooks

   - The library does not include dedicated pagination, filtering, or
     rate-limiting helpers of its own

   - Result normalization focuses on JSON and problem responses; it does
     not provide specialized helpers for redirects, streaming, or
     multipart payloads


File: TheLogtalkHandbook-3.101.0.info,  Node: ridge_regression,  Next: s3,  Prev: rest,  Up: Libraries

6.214 ‘ridge_regression’
========================

Ridge regression regressor supporting continuous and mixed-feature
datasets.  The library implements the ‘regressor_protocol’ defined in
the ‘regression_protocols’ library and learns a linear model by solving
the weighted ridge normal equations directly via the shared regression
encoding core in ‘regressor_common’, leaving the intercept unpenalized
while penalizing encoded feature columns using scale-aware weights that
match standardizing penalized columns before applying the L2 penalty.

* Menu:

* API documentation: API documentation<230>.
* Loading: Loading<234>.
* Testing: Testing<225>.
* Features: Features<71>.
* Regressor representation: Regressor representation<10>.
* Diagnostics syntax: Diagnostics syntax<24>.
* Options: Options<69>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<230>,  Next: Loading<234>,  Up: ridge_regression

6.214.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#ridge_regression’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<234>,  Next: Testing<225>,  Prev: API documentation<230>,  Up: ridge_regression

6.214.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(ridge_regression(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<225>,  Next: Features<71>,  Prev: Loading<234>,  Up: ridge_regression

6.214.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(ridge_regression(tester)).

To run the performance benchmark suite, load the
‘tester_performance.lgt’ file:

     | ?- logtalk_load(ridge_regression(tester_performance)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<71>,  Next: Regressor representation<10>,  Prev: Testing<225>,  Up: ridge_regression

6.214.4 Features
----------------

   - 'Continuous and Mixed Features': Supports continuous attributes and
     categorical attributes encoded using reference-level dummy coding.

   - 'Feature Scaling and Penalty Scaling': Continuous attributes can be
     standardized using z-score scaling.  Ridge regularization uses
     scale-aware weights equivalent to standardizing each penalized
     encoded feature column before applying the L2 penalty.

   - 'Missing Values': Missing numeric and categorical values
     represented using anonymous variables are encoded using explicit
     missing-value indicator features.

   - 'Unknown Values': Prediction requests containing categorical values
     that are not declared by the dataset raise a domain error.

   - 'Zero-Variance Features': Encoded columns with zero variance are
     excluded from the direct solve and assigned zero coefficients in
     the learned regressor.

   - 'Ridge Penalty': Applies L2 regularization to the learned weights
     using the shared ‘regularization/1’ option.

   - 'Diagnostics Metadata': Learned regressors record model name,
     target, training example count, solver, linear-system residual,
     active feature count, penalty scaling strategy, encoded feature
     count, and effective options, accessible using the shared
     regression diagnostics predicates.

   - 'Model Export': Learned regressors can be exported as predicate
     clauses or written to a file.

   - 'Reference Benchmarks': Includes a dedicated performance suite
     reporting training time, RMSE, and MAE for representative
     regression datasets.


File: TheLogtalkHandbook-3.101.0.info,  Node: Regressor representation<10>,  Next: Diagnostics syntax<24>,  Prev: Features<71>,  Up: ridge_regression

6.214.5 Regressor representation
--------------------------------

The learned regressor is represented by default as:

   - ‘ridge_regressor(Encoders, Bias, Weights, Diagnostics)’

The exported predicate clauses therefore use the shape:

   - ‘Functor(Encoders, Bias, Weights, Diagnostics)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Diagnostics syntax<24>,  Next: Options<69>,  Prev: Regressor representation<10>,  Up: ridge_regression

6.214.6 Diagnostics syntax
--------------------------

The ‘diagnostics/2’ predicate returns a list of metadata terms with the
form:

     [
         model(ridge_regression),
         target(Target),
         training_example_count(TrainingExampleCount),
         options(Options),
         solver(Solver),
         linear_system_residual(Residual),
         active_feature_count(ActiveFeatureCount),
         penalty_scaling(encoded_feature_standardization),
         encoded_feature_count(FeatureCount)
     ]

Where:

   - ‘model(ridge_regression)’ identifies the learning algorithm that
     produced the regressor.

   - ‘target(Target)’ stores the target attribute name declared by the
     training dataset.

   - ‘training_example_count(TrainingExampleCount)’ stores the number of
     examples used during training.

   - ‘options(Options)’ stores the effective learning options after
     merging the user options with the library defaults.

   - ‘solver(Solver)’ records the direct linear-system solver used
     during training.  The current value is
     ‘pivoted_gaussian_elimination’.

   - ‘linear_system_residual(Residual)’ stores the maximum absolute
     residual of the solved ridge linear system.

   - ‘active_feature_count(ActiveFeatureCount)’ stores the number of
     encoded feature columns retained for the direct solve after
     dropping zero-variance columns.

   - ‘penalty_scaling(encoded_feature_standardization)’ records that the
     ridge penalty is scaled as if each penalized encoded feature column
     had been standardized before applying the L2 penalty.

   - ‘encoded_feature_count(FeatureCount)’ stores the number of numeric
     features induced by the encoder list, including missing-value
     indicator features.

Use the ‘regression_protocols’ ‘diagnostic/2’ and ‘regressor_options/2’
helper predicates when you only need a single metadata term or the
effective options.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<69>,  Prev: Diagnostics syntax<24>,  Up: ridge_regression

6.214.7 Options
---------------

The ‘learn/3’ predicate accepts the following options:

   - ‘regularization/1’: Ridge penalty coefficient applied to the weight
     vector during the direct solve.  Higher values increase shrinkage
     and can reduce overfitting.  The default is ‘0.01’.

   - ‘feature_scaling/1’: Controls z-score standardization of continuous
     attributes before training and prediction.  Accepted values are
     ‘true’ and ‘false’.  The default is ‘true’.


File: TheLogtalkHandbook-3.101.0.info,  Node: s3,  Next: schulze_ranker,  Prev: ridge_regression,  Up: Libraries

6.215 ‘s3’
==========

Portable S3-compatible client library layered on top of the normalized
‘http_client’ stack.  The current implementation focuses on
general-purpose bucket operations and AWS Signature Version 4 request
signing.

The library depends on the contributed ‘xml_parser’ parser to decode S3
XML responses and wraps it behind the ‘s3_xml’ adapter so the public API
exposes stable S3-specific terms instead of generic XML parse trees.

This library can be used with backend Prolog systems that support
unbound integer arithmetic and the ‘sockets’ library: ECLiPSe, SICStus
Prolog, SWI-Prolog, Trealla Prolog, and XVM.

* Menu:

* API documentation: API documentation<231>.
* Loading: Loading<235>.
* Testing: Testing<226>.
* Current scope: Current scope<26>.
* Basic usage: Basic usage<5>.
* Current limitations: Current limitations<19>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<231>,  Next: Loading<235>,  Up: s3

6.215.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#s3’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<235>,  Next: Testing<226>,  Prev: API documentation<231>,  Up: s3

6.215.2 Loading
---------------

To load the library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(s3(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<226>,  Next: Current scope<26>,  Prev: Loading<235>,  Up: s3

6.215.3 Testing
---------------

To test this library, load the ‘tester.lgt’ file:

     | ?- logtalk_load(s3(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Current scope<26>,  Next: Basic usage<5>,  Prev: Testing<226>,  Up: s3

6.215.4 Current scope
---------------------

   - ‘list_buckets/2’

   - ‘head_bucket/3’

   - ‘list_objects_v2/4’

   - ‘head_object/4’

   - ‘get_object/5’

   - ‘presigned_get_object/4’

   - ‘put_object/6’

   - ‘presigned_put_object/4’

   - ‘presigned_post_object/4’

   - ‘delete_object/4’

   - ‘copy_object/5’

   - explicit session wrapper via ‘s3_session(_HTTPSocket_)’

   - AWS Signature Version 4 request signing for service ‘s3’

   - virtual-hosted and path-style endpoint generation

   - direct support for custom S3-compatible endpoints such as MinIO


File: TheLogtalkHandbook-3.101.0.info,  Node: Basic usage<5>,  Next: Current limitations<19>,  Prev: Current scope<26>,  Up: s3

6.215.5 Basic usage
-------------------

For typical file transfers, prefer the file-based arities:

   - ‘get_object/5’ downloads an object to a local file path and returns
     response metadata separately.

   - ‘put_object/6’ uploads a local file path and returns the object
     ETag and response metadata separately.

The ‘presigned_get_object/4’, ‘presigned_put_object/4’, and
‘presigned_post_object/4’ predicates generate portable SigV4
query-string URLs for external HTTP clients.  They default to
‘UNSIGNED-PAYLOAD’, accept ‘expires(Seconds)’ with a maximum of ‘604800’
seconds, support signed payloads using ‘payload_hash_mode(signed)’ plus
‘payload_hash(Hash)’, and sign any extra request headers supplied using
‘headers/1’.

Result terms for the predicates returning a ‘Result’ argument are:

   - ‘delete_object/4’ -> ‘delete_result(Properties)’

   - ‘copy_object/5’ -> ‘copy_result(ETag, Properties)’

List buckets using the default TLS-capable transport:

     | ?- s3_client::list_buckets(
              Buckets,
              [
                  credentials(access_key_id('AKIDEXAMPLE'), secret_access_key('secret')),
                  amz_date('20240627T120000Z')
              ]
          ).

Download ‘report.txt’ from a custom S3-compatible endpoint into a local
file:

     | ?- s3_client::get_object(
             photos,
             'report.txt',
             'report.txt',
             Properties,
             [
                  endpoint('http://127.0.0.1:9000'),
                  addressing_style(path),
                  credentials(access_key_id('minioadmin'), secret_access_key('minioadmin')),
                  amz_date('20240627T120000Z')
              ]
          ).

Upload the same local ‘report.txt’ file to the same custom endpoint:

     | ?- s3_client::put_object(
             photos,
             'report.txt',
             'report.txt',
             ETag,
             Properties,
             [
                 endpoint('http://127.0.0.1:9000'),
                 addressing_style(path),
                 credentials(access_key_id('minioadmin'), secret_access_key('minioadmin')),
                 amz_date('20240627T120000Z')
             ]
          ).

Use an explicit session handle to carry defaults:

     | ?- s3_session(http_process_transport)::open(
              Session,
              [
                  region('eu-west-1'),
                  credentials(access_key_id('AKIDEXAMPLE'), secret_access_key('secret')),
                  amz_date('20240627T120000Z')
              ]
          ),
          s3_session(http_process_transport)::list_buckets(Session, Buckets, []),
          s3_session(http_process_transport)::close(Session).

Generate a presigned download URL for ‘report.txt’:

     | ?- s3_client::presigned_get_object(
             photos,
             'report.txt',
             URL,
             [
                 region('eu-west-1'),
                 credentials(access_key_id('AKIDEXAMPLE'), secret_access_key('secret')),
                 amz_date('20240627T120000Z'),
                 expires(600)
             ]
          ).

Generate a presigned upload URL for the same ‘report.txt’ object:

     | ?- s3_client::presigned_put_object(
             photos,
             'report.txt',
             URL,
             [
                 endpoint('http://127.0.0.1:9000'),
                 addressing_style(path),
                 credentials(access_key_id('minioadmin'), secret_access_key('minioadmin')),
                 headers([content_type-'text/plain']),
                 amz_date('20240627T120000Z'),
                 expires(300)
             ]
          ).

Generate a presigned POST URL for the same ‘report.txt’ object:

     | ?- s3_client::presigned_post_object(
             photos,
             'report.txt',
             URL,
             [
                 endpoint('http://127.0.0.1:9000'),
                 addressing_style(path),
                 credentials(access_key_id('minioadmin'), secret_access_key('minioadmin')),
                 amz_date('20240627T120000Z'),
                 expires(300)
             ]
          ).

Generate a presigned URL that signs a precomputed SHA-256 payload hash:

     | ?- s3_client::presigned_put_object(
             photos,
             'report.txt',
             URL,
             [
                 region('eu-west-1'),
                 credentials(access_key_id('AKIDEXAMPLE'), secret_access_key('secret')),
                 amz_date('20240627T120000Z'),
                 payload_hash_mode(signed),
                 payload_hash('2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824')
             ]
          ).

When using signed extra headers such as ‘content_type-'text/plain'’, the
eventual HTTP client must send the same headers when dereferencing the
URL.


File: TheLogtalkHandbook-3.101.0.info,  Node: Current limitations<19>,  Prev: Basic usage<5>,  Up: s3

6.215.6 Current limitations
---------------------------

   - Time signing defaults derive UTC from the local system clock plus
     the configurable ‘utc_offset_seconds/1’ option.  For deterministic
     use and tests, prefer passing ‘amz_date/1’ or ‘request_time/1’.

   - Multipart uploads are not implemented yet.

   - S3 Express / directory bucket APIs are outside the current scope.


File: TheLogtalkHandbook-3.101.0.info,  Node: schulze_ranker,  Next: sequential_pattern_mining_protocols,  Prev: s3,  Up: Libraries

6.216 ‘schulze_ranker’
======================

Schulze pairwise preference ranker.  It builds the direct pairwise
strength graph from aggregated matchups and applies the Schulze
strongest-path dynamic program to derive the final pairwise preference
relation.

The library implements the ‘ranker_protocol’ defined in the
‘ranking_protocols’ library.  It provides predicates for learning a
ranker from pairwise preferences, using it to order candidate items, and
exporting it as a list of predicate clauses or to a file.

Datasets are represented as objects implementing the
‘pairwise_ranking_dataset_protocol’ protocol from the
‘ranking_protocols’ library.  See the ‘test_datasets’ directory for
examples.  The current implementation requires a well-formed connected
pairwise dataset so that all ranked items remain comparable in the
aggregated matchup graph.

* Menu:

* API documentation: API documentation<232>.
* Loading: Loading<236>.
* Testing: Testing<227>.
* Features: Features<72>.
* Options: Options<70>.
* Strongest paths::
* Diagnostics syntax: Diagnostics syntax<25>.
* Ranker representation: Ranker representation<16>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<232>,  Next: Loading<236>,  Up: schulze_ranker

6.216.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#schulze_ranker’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<236>,  Next: Testing<227>,  Prev: API documentation<232>,  Up: schulze_ranker

6.216.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(schulze_ranker(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<227>,  Next: Features<72>,  Prev: Loading<236>,  Up: schulze_ranker

6.216.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(schulze_ranker(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<72>,  Next: Options<70>,  Prev: Testing<227>,  Up: schulze_ranker

6.216.4 Features
----------------

   - 'Pairwise Preference Learning': Learns one deterministic score per
     item from aggregated pairwise outcomes.

   - 'Schulze Strongest Paths': Computes the final ranking relation
     using the Schulze strongest-path dynamic program over aggregated
     head-to-head data.

   - 'Configurable Direct Edge Semantics': Supports both winning-votes
     and victory-margins victory-strength modes.  The
     ‘victory_strength/1’ option selects whether direct edges use
     winning votes or victory margins before strongest-path propagation.

   - 'Strongest-Path Access': Exposes the labeled strongest-path
     relation for ordered item pairs using the ‘strongest_paths/2’
     predicate.

   - 'Deterministic Ranking': Orders candidate items by final Schulze
     relation win counts with deterministic tie-breaking.

   - 'Tie-breaking': Items tied in the final Schulze relation receive
     the same learned score, and ranking ties are then broken
     deterministically using the standard term order of the item
     identifiers.

   - 'Strict Dataset Validation': Rejects duplicate items, undeclared
     items, self-preferences, non-positive weights, and disconnected
     comparison graphs.

   - 'Training Diagnostics': Learned rankers include dataset summary
     metadata and the effective victory-strength mode.

   - 'Ranker Export': Learned rankers can be exported as self-contained
     terms.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<70>,  Next: Strongest paths,  Prev: Features<72>,  Up: schulze_ranker

6.216.5 Options
---------------

The following options can be passed to the ‘learn/3’ predicate:

   - ‘victory_strength(winning_votes)’: Use the winning side’s
     aggregated vote total as the direct edge strength.

   - ‘victory_strength(margins)’: Use the victory margin as the direct
     edge strength.

The default is ‘victory_strength(winning_votes)’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Strongest paths,  Next: Diagnostics syntax<25>,  Prev: Options<70>,  Up: schulze_ranker

6.216.6 Strongest paths
-----------------------

The ‘strongest_paths/2’ predicate returns the learned strongest-path
matrix as an ordered list of ‘path(Item1, Item2, Strength)’ terms for
all ordered pairs of distinct learned items.

This predicate complements ‘scores/2’ and ‘rank/3’ without changing
their semantics.  The ‘scores/2’ predicate still returns the number of
opponents that each item beats in the final Schulze relation, while
‘strongest_paths/2’ exposes the underlying pairwise path strengths used
to derive that relation.


File: TheLogtalkHandbook-3.101.0.info,  Node: Diagnostics syntax<25>,  Next: Ranker representation<16>,  Prev: Strongest paths,  Up: schulze_ranker

6.216.7 Diagnostics syntax
--------------------------

The ‘diagnostics/2’ predicate returns a list of metadata terms with the
form:

     [
         model(schulze_ranker),
         options(Options),
         strongest_paths(StrongestPaths),
         dataset_summary(DatasetSummary)
     ]


File: TheLogtalkHandbook-3.101.0.info,  Node: Ranker representation<16>,  Prev: Diagnostics syntax<25>,  Up: schulze_ranker

6.216.8 Ranker representation
-----------------------------

The learned ranker is represented by a compound term of the form:

     schulze_ranker(Items, Scores, Diagnostics)

Where:

   - ‘Items’: List of ranked items.

   - ‘Scores’: List of ‘Item-Score’ pairs.

   - ‘Diagnostics’: List of metadata terms, including the effective
     ‘victory_strength/1’ option, the labeled strongest paths, and the
     dataset summary.


File: TheLogtalkHandbook-3.101.0.info,  Node: sequential_pattern_mining_protocols,  Next: sets,  Prev: schulze_ranker,  Up: Libraries

6.217 ‘sequential_pattern_mining_protocols’
===========================================

This library provides support entities for sequential pattern mining
algorithms.  Ordered sequence datasets are represented as objects
implementing the ‘sequence_dataset_protocol’ protocol.  The generic
‘pattern_miner_protocol’ protocol and the ‘pattern_miner_common’
category used by concrete miners are loaded from the
‘pattern_mining_protocols’ core library.

The ‘sequential_pattern_mining_common’ category builds on that generic
core with sequential-specific helpers for dataset validation, support
count accumulation, and sequential pattern ordering/filtering.

This library also provides reusable sequence smoke-test datasets and a
small smoke-test suite.

* Menu:

* API documentation: API documentation<233>.
* Loading: Loading<237>.
* Testing: Testing<228>.
* Test datasets: Test datasets<8>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<233>,  Next: Loading<237>,  Up: sequential_pattern_mining_protocols

6.217.1 API documentation
-------------------------

Open the
‘../../apis/library_index.html#sequential_pattern_mining_protocols’ link
in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<237>,  Next: Testing<228>,  Prev: API documentation<233>,  Up: sequential_pattern_mining_protocols

6.217.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(sequential_pattern_mining_protocols(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<228>,  Next: Test datasets<8>,  Prev: Loading<237>,  Up: sequential_pattern_mining_protocols

6.217.3 Testing
---------------

To run the library smoke tests, load the ‘tester.lgt’ file:

     | ?- logtalk_load(sequential_pattern_mining_protocols(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Test datasets<8>,  Prev: Testing<228>,  Up: sequential_pattern_mining_protocols

6.217.4 Test datasets
---------------------

The ‘test_datasets’ directory includes the following sample sequence
datasets:

   - ‘clickstream_sequences.lgt’: A compact sequence dataset with
     repeated prefixes intended for sequential-pattern smoke tests.

   - ‘prefix_ladder_sequences.lgt’: A small ladder-shaped dataset of
     singleton events intended for exact baseline checks across
     sequential mining algorithms.

   - ‘same_event_vs_next_event_sequences.lgt’: A compact dataset
     intended to distinguish same-event extensions from next-event
     extensions.

   - ‘repeated_embedding_sequences.lgt’: A dataset where the same
     subsequence admits multiple embeddings inside a single sequence,
     intended for support-count semantics checks.

   - ‘border_threshold_sequences.lgt’: A compact dataset with patterns
     just above and below typical support thresholds, intended for
     pruning and threshold regression tests.

   - ‘closure_sequences.lgt’: A compact dataset intended for
     closed-pattern tests where some frequent patterns share the same
     support as one of their supersequences.

   - ‘dense_overlap_sequences.lgt’: A denser dataset with overlapping
     subsequences and mixed singleton and multi-item events, intended
     for overlap-heavy mining scenarios.

   - ‘branching_sequences.lgt’: A dataset with a common prefix and
     several competing branches, intended for candidate-generation and
     branching coverage.

The directory also includes invalid fixtures useful for validation and
error-handling tests:

   - ‘invalid_undeclared_item_sequences.lgt’: Uses an item not listed in
     the declared item domain.

   - ‘invalid_unsorted_itemset_sequences.lgt’: Uses an event with items
     not in canonical sorted order.

   - ‘invalid_duplicate_item_in_event_sequences.lgt’: Uses an event with
     a duplicate item.

   - ‘invalid_empty_event_sequences.lgt’: Uses an empty event inside a
     sequence.


File: TheLogtalkHandbook-3.101.0.info,  Node: sets,  Next: sgd_classifier,  Prev: sequential_pattern_mining_protocols,  Up: Libraries

6.218 ‘sets’
============

This library provides a set protocol, two implementations of this
protocol using 'ordered lists' (one of them a parametric object that
takes the type of the set elements as a parameter), and an
implementation using 'treaps' (tree heaps).

The set representations should be regarded as 'opaque terms' and only
constructed, accessed, and updated them using the library predicates.

For small sets, the ordered list implementations are likely to provide
the best performance.  For larger sets, the treap implementation likely
provides better performance, notably for the ‘memberchk/2’, ‘insert/3’,
and ‘delete/3’ operations.  Benchmark both implementations to select the
best one for your application.

The current implementations use ‘==/2’ for element comparison and
standard term ordering.  This allows non-ground set elements.  But
requires caution with later unifications with output arguments and when
using the ‘member/2’ and ‘select/3’ predicates, which can break the
ordered representation.  Note also that, per the ISO Prolog Core
Standard, variable ordering is implementation dependent.  This can
result in unexpected results and portability issues.

* Menu:

* API documentation: API documentation<234>.
* Loading: Loading<238>.
* Testing: Testing<229>.
* Usage: Usage<99>.
* Credits: Credits<5>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<234>,  Next: Loading<238>,  Up: sets

6.218.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#sets’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<238>,  Next: Testing<229>,  Prev: API documentation<234>,  Up: sets

6.218.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(sets(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<229>,  Next: Usage<99>,  Prev: Loading<238>,  Up: sets

6.218.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(sets(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<99>,  Next: Credits<5>,  Prev: Testing<229>,  Up: sets

6.218.4 Usage
-------------

First, select a set implementation.  Use the ‘set(Type)’ object if you
want to type-check the set elements.  Otherwise, use the ‘set’ object.

To create a new set, you can use the ‘new/1’ predicate.  For example:

     | ?- set::new(Set).
     Set = []
     yes

You can also create a new set with all unique elements from a list of
terms by using the ‘as_set/2’ predicate.  For example:

     | ?- set::as_set([1,3,2,1,2], Set).
     Set = [1, 2, 3]
     yes

Predicates are provided for the most common set operations.  For
example:

     | ?- set::(
             as_set([1,3,2,1,2], Set1),
             as_set([7,4,2,5,1], Set2),
             intersection(Set1, Set2, Intersection),
             symdiff(Set1, Set2, Difference)
         ).
     Set1 = [1, 2, 3],
     Set2 = [1, 2, 4, 5, 7],
     Intersection = [1, 2],
     Difference = [3, 4, 5, 7]
     yes

When working with a custom type of set elements and the ordered list
representation, the corresponding object must implement the ‘comparingp’
protocol.  For example:

     :- object(rainbow_colors,
         implements(comparingp)).

         order(red,    1).
         order(orange, 2).
         order(yellow, 3).
         order(green,  4).
         order(blue,   5).
         order(indigo, 6).
         order(violet, 7).

         Color1 < Color2 :-
             order(Color1, N1),
             order(Color2, N2),
             {N1 < N2}.

         Color1 =< Color2 :-
             order(Color1, N1),
             order(Color2, N2),
             {N1 =< N2}.

         ...

     :- end_object.

We can then use this object with the ‘set/1’ parametric object.  For
example:

     | ?- set(rainbow_colors)::as_set([blue, yellow, violet], Set).
     Set = [yellow, blue, violet]
     yes

For details on these and other provided predicates, consult the library
API documentation.


File: TheLogtalkHandbook-3.101.0.info,  Node: Credits<5>,  Prev: Usage<99>,  Up: sets

6.218.5 Credits
---------------

Some predicates adapted from code authored by Richard O’Keefe.


File: TheLogtalkHandbook-3.101.0.info,  Node: sgd_classifier,  Next: snowflakeid,  Prev: sets,  Up: Libraries

6.219 ‘sgd_classifier’
======================

Linear stochastic-gradient classifier for tabular datasets using a
one-vs-rest scheme with configurable losses.  The implementation reuses
the shared linear encoder pipeline so continuous and categorical
features, including missing values, are represented consistently with
the existing linear classifiers.

The library implements the ‘classifier_protocol’ defined in the
‘classification_protocols’ library.  It provides predicates for learning
a classifier from a dataset, using it to make predictions, estimating
class probabilities, and exporting it as a list of predicate clauses or
to a file.

Datasets are represented as objects implementing the ‘dataset_protocol’
protocol from the ‘classification_protocols’ library.  Continuous,
categorical, and mixed-feature datasets are supported.

* Menu:

* API documentation: API documentation<235>.
* Loading: Loading<239>.
* Testing: Testing<230>.
* Features: Features<73>.
* Options: Options<71>.
* Usage: Usage<100>.
* Classifier representation: Classifier representation<12>.
* References: References<50>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<235>,  Next: Loading<239>,  Up: sgd_classifier

6.219.1 API documentation
-------------------------

Open the ‘../../docs/library_index.html#sgd_classifier’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<239>,  Next: Testing<230>,  Prev: API documentation<235>,  Up: sgd_classifier

6.219.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(sgd_classifier(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<230>,  Next: Features<73>,  Prev: Loading<239>,  Up: sgd_classifier

6.219.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(sgd_classifier(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<73>,  Next: Options<71>,  Prev: Testing<230>,  Up: sgd_classifier

6.219.4 Features
----------------

   - 'Binary and Multiclass Classification': Learns one-vs-rest linear
     models and predicts the class with the highest decision score.

   - 'Multiple Losses': Supports ‘log_loss’, ‘hinge’, ‘squared_hinge’,
     ‘modified_huber’, and ‘perceptron’ losses.

   - 'Mixed Features': Reuses the shared tabular encoders for continuous
     and categorical attributes, including missing-value indicators.

   - 'Probability Estimation': Provides class probabilities using a
     softmax over linear decision scores.

   - 'Configurable Optimization': Exposes learning-rate scheduling,
     convergence tolerance, and L2 regularization options.

   - 'Classifier Export': Learned classifiers can be exported as
     predicate clauses or written to a file.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<71>,  Next: Usage<100>,  Prev: Features<73>,  Up: sgd_classifier

6.219.5 Options
---------------

The ‘learn/3’ predicate supports these options:

   - ‘loss/1’ - optimization loss, one of ‘log_loss’, ‘hinge’,
     ‘squared_hinge’, ‘modified_huber’, or ‘perceptron’ (default:
     ‘log_loss’)

   - ‘learning_rate/1’ - base learning rate for optimization (default:
     ‘0.05’)

   - ‘learning_schedule/1’ - learning-rate schedule, either ‘constant’
     or ‘inverse_scaling(Power)’ (default: ‘constant’)

   - ‘maximum_iterations/1’ - maximum number of optimization epochs
     (default: ‘100’)

   - ‘tolerance/1’ - convergence threshold for the maximum parameter
     update (default: ‘1.0e-5’)

   - ‘l2_regularization/1’ - L2 penalty factor applied to the weight
     vectors (default: ‘0.0001’)

   - ‘feature_scaling/1’ - whether to standardize continuous attributes
     before encoding (default: ‘true’)


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<100>,  Next: Classifier representation<12>,  Prev: Options<71>,  Up: sgd_classifier

6.219.6 Usage
-------------

* Menu:

* Learning a classifier: Learning a classifier<7>.
* Making predictions: Making predictions<7>.
* Exporting the classifier: Exporting the classifier<7>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Learning a classifier<7>,  Next: Making predictions<7>,  Up: Usage<100>

6.219.6.1 Learning a classifier
...............................

     | ?- sgd_classifier::learn(weather, Classifier).

     | ?- sgd_classifier::learn(mixed, Classifier, [loss(hinge), maximum_iterations(250)]).


File: TheLogtalkHandbook-3.101.0.info,  Node: Making predictions<7>,  Next: Exporting the classifier<7>,  Prev: Learning a classifier<7>,  Up: Usage<100>

6.219.6.2 Making predictions
............................

     | ?- sgd_classifier::learn(weather, Classifier),
          sgd_classifier::predict(Classifier, [outlook-rainy, temperature-mild, humidity-normal, windy-false], Class).

     | ?- sgd_classifier::learn(missing_mixed, Classifier),
          sgd_classifier::predict_probabilities(Classifier, [age-38, income-72000, student-yes, credit_rating-fair], Probabilities).


File: TheLogtalkHandbook-3.101.0.info,  Node: Exporting the classifier<7>,  Prev: Making predictions<7>,  Up: Usage<100>

6.219.6.3 Exporting the classifier
..................................

     | ?- sgd_classifier::learn(weather, Classifier),
          sgd_classifier::export_to_clauses(weather, Classifier, classify, Clauses).

     | ?- sgd_classifier::learn(weather, Classifier),
          sgd_classifier::export_to_file(weather, Classifier, classify, 'classifier.pl').


File: TheLogtalkHandbook-3.101.0.info,  Node: Classifier representation<12>,  Next: References<50>,  Prev: Usage<100>,  Up: sgd_classifier

6.219.7 Classifier representation
---------------------------------

The learned classifier is represented as a compound term with the form:

     sgd_classifier(Classes, Encoders, Loss, Models, Options)

Where:

   - ‘Classes’: list of class labels

   - ‘Encoders’: list of continuous scaling descriptors and categorical
     value encoders

   - ‘Loss’: selected optimization loss

   - ‘Models’: list of ‘class_model(Class, Bias, Weights)’ terms

   - ‘Options’: merged training options used to learn the classifier

When exported using ‘export_to_clauses/4’ or ‘export_to_file/4’, this
classifier term is serialized directly as the single argument of the
generated predicate clause so that the exported model can be loaded and
reused as-is.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<50>,  Prev: Classifier representation<12>,  Up: sgd_classifier

6.219.8 References
------------------

  1. Bottou, L. (2010).  “Large-Scale Machine Learning with Stochastic
     Gradient Descent”.

  2. Shalev-Shwartz, S. and Ben-David, S. (2014).  “Understanding
     Machine Learning”.  Chapter 15.

  3. Hastie, T., Tibshirani, R. and Friedman, J. (2009).  “The Elements
     of Statistical Learning”.  Chapter 12.


File: TheLogtalkHandbook-3.101.0.info,  Node: snowflakeid,  Next: sockets,  Prev: sgd_classifier,  Up: Libraries

6.220 ‘snowflakeid’
===================

This library generates Snowflake-style identifiers using a generic
generator object and predefined profile objects.

'This library requires a backend supporting unbounded integer
arithmetic.'

See also the ‘cuid2’, ‘ids’, ‘nanoid’, ‘ksuid’, ‘uuid’, and ‘ulid’
libraries.

* Menu:

* API documentation: API documentation<236>.
* Loading: Loading<240>.
* Testing: Testing<231>.
* Usage: Usage<101>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<236>,  Next: Loading<240>,  Up: snowflakeid

6.220.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#snowflakeid’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<240>,  Next: Testing<231>,  Prev: API documentation<236>,  Up: snowflakeid

6.220.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(snowflakeid(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<231>,  Next: Usage<101>,  Prev: Loading<240>,  Up: snowflakeid

6.220.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(snowflakeid(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<101>,  Prev: Testing<231>,  Up: snowflakeid

6.220.4 Usage
-------------

The generic generator is the parametric object:

     snowflakeid(Representation, EpochMilliseconds, TimeUnitMilliseconds, TimestampBits, NodeBits, SequenceBits, Node)

where ‘Representation’ can be ‘integer’, ‘atom’, ‘chars’, or ‘codes’.

Predefined profiles are provided as objects extending the generic
object:

   - ‘snowflakeid_twitter(_Representation_)’

   - ‘snowflakeid_sonyflake(_Representation_)’

   - ‘snowflakeid_instagram(_Representation_)’

The default object ‘snowflakeid’ uses the Twitter-style profile with
atom representation.

To generate a Snowflake ID using the default Twitter-style profile:

     | ?- snowflakeid::generate(ID).
     ID = '1917401915609202688'
     yes

To generate a Twitter-style Snowflake ID represented as an integer:

     | ?- snowflakeid_twitter(integer)::generate(ID).
     ID = 1917401915609202688
     yes

To generate a Sonyflake-style Snowflake ID represented as chars:

     | ?- snowflakeid_sonyflake(chars)::generate(ID).
     ID = ['9','2','8','5','6','7','2','8','0','1','4','8','9','5','5','7','5','9']
     yes

To define a custom profile:

     | ?- snowflakeid(atom, 1704067200000, 1, 41, 10, 12, 7)::generate(ID).
     ID = '28842191400263680'
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: sockets,  Next: spade_pattern_miner,  Prev: snowflakeid,  Up: Libraries

6.221 ‘sockets’
===============

Portable abstraction over TCP sockets.  Provides a high-level API for
client and server socket operations that works across all supported
backend Prolog systems: ECLiPSe, GNU Prolog, SICStus Prolog, SWI-Prolog,
Trealla Prolog, and XVM.

* Menu:

* Design rationale::
* API documentation: API documentation<237>.
* Loading: Loading<241>.
* Testing: Testing<232>.
* Usage: Usage<102>.
* API Summary: API Summary<3>.
* Backend-specific notes::
* Known issues: Known issues<19>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Design rationale,  Next: API documentation<237>,  Up: sockets

6.221.1 Design rationale
------------------------

Different Prolog systems provide socket functionality at different
abstraction levels.  Some backends (notably SICStus Prolog and Trealla
Prolog) do not provide low-level socket creation predicates that can be
separated from binding or connecting.  This library therefore provides a
higher-level API with predicates ‘client_open/4-5’ and ‘server_open/2-3’
that abstracts over these differences.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<237>,  Next: Loading<241>,  Prev: Design rationale,  Up: sockets

6.221.2 API documentation
-------------------------

Open the ‘../../apis/library_index.html#sockets’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<241>,  Next: Testing<232>,  Prev: API documentation<237>,  Up: sockets

6.221.3 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(sockets(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<232>,  Next: Usage<102>,  Prev: Loading<241>,  Up: sockets

6.221.4 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(sockets(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<102>,  Next: API Summary<3>,  Prev: Testing<232>,  Up: sockets

6.221.5 Usage
-------------

* Menu:

* Creating a client connection::
* Creating a server::
* Getting the current host name::


File: TheLogtalkHandbook-3.101.0.info,  Node: Creating a client connection,  Next: Creating a server,  Up: Usage<102>

6.221.5.1 Creating a client connection
......................................

To connect to a server using default options:

     ?- socket::client_open(localhost, 8080, Input, Output).

The predicates ‘client_open/4-5’ and ‘server_accept/4-5’ return separate
input and output streams.  For backends where the same stream is used
for bidirectional communication (SICStus Prolog and ECLiPSe), the same
stream handle is returned in both arguments.  Use ‘socket::close/2’ to
close both streams when done.


File: TheLogtalkHandbook-3.101.0.info,  Node: Creating a server,  Next: Getting the current host name,  Prev: Creating a client connection,  Up: Usage<102>

6.221.5.2 Creating a server
...........................

To create a server that accepts connections using default options on all
interfaces:

     ?- socket::server_open(8080, ServerSocket),
        socket::server_accept(ServerSocket, Input, Output, ClientInfo),
        % ... communicate with client using Input and Output ...
        socket::close(Input, Output),
        socket::server_close(ServerSocket).

If the port is passed as a variable to the ‘server_open/2-3’ predicates,
an available port will be selected and unified with the variable.

The ‘server_open/4’ predicate can be used to accept a connection only on
the given interface.


File: TheLogtalkHandbook-3.101.0.info,  Node: Getting the current host name,  Prev: Creating a server,  Up: Usage<102>

6.221.5.3 Getting the current host name
.......................................

     ?- socket::current_host(Host).


File: TheLogtalkHandbook-3.101.0.info,  Node: API Summary<3>,  Next: Backend-specific notes,  Prev: Usage<102>,  Up: sockets

6.221.6 API Summary
-------------------

   - ‘client_open(+Host, +Port, -InputStream, -OutputStream, +Options)’
     - Connect to a server

   - ‘client_open(+Host, +Port, -InputStream, -OutputStream)’ - Connect
     to a server using default options

   - ‘server_open(+Host, ?Port, -ServerSocket, +Options)’ - Create a
     server socket on the given interface

   - ‘server_open(?Port, -ServerSocket, +Options)’ - Create a server
     socket on all interfaces

   - ‘server_open(?Port, -ServerSocket)’ - Create a server socket using
     default options

   - ‘server_accept(+ServerSocket, -InputStream, -OutputStream,
     -ClientInfo, +Options)’ - Accept connection

   - ‘server_accept(+ServerSocket, -InputStream, -OutputStream,
     -ClientInfo)’ - Accept connection using default options

   - ‘server_close(+ServerSocket)’ - Close a server socket

   - ‘close(+InputStream, +OutputStream)’ - Close a client or accepted
     connection

   - ‘current_host(-Host)’ - Get the current machine’s hostname


File: TheLogtalkHandbook-3.101.0.info,  Node: Backend-specific notes,  Next: Known issues<19>,  Prev: API Summary<3>,  Up: sockets

6.221.7 Backend-specific notes
------------------------------

* Menu:

* Stream representation::
* Binary and text modes::


File: TheLogtalkHandbook-3.101.0.info,  Node: Stream representation,  Next: Binary and text modes,  Up: Backend-specific notes

6.221.7.1 Stream representation
...............................

The library provides separate input and output stream arguments in
‘client_open/4-5’ and ‘server_accept/4-5’.  For backends where the same
stream is used for bidirectional communication (ECLiPSe, SICStus Prolog,
and Trealla Prolog), the same stream handle is returned in both the
input and output arguments.  For backends that use separate streams (GNU
Prolog and SWI-Prolog), separate stream handles are returned.


File: TheLogtalkHandbook-3.101.0.info,  Node: Binary and text modes,  Prev: Stream representation,  Up: Backend-specific notes

6.221.7.2 Binary and text modes
...............................

The library automatically sets streams by default to binary mode (e.g.,
for sending and receiving raw bytes).  An option is supported for
opening streams in text mode.


File: TheLogtalkHandbook-3.101.0.info,  Node: Known issues<19>,  Prev: Backend-specific notes,  Up: sockets

6.221.8 Known issues
--------------------

Recent versions of macOS seem to disable the mapping of ‘localhost’ to
‘127.0.0.1’.  This issue may prevent some functionality from working.
This can be fixed either by editing the ‘/etc/hosts’ file or by using
‘'127.0.0.1'’ as the host argument instead of ‘localhost’.


File: TheLogtalkHandbook-3.101.0.info,  Node: spade_pattern_miner,  Next: simulated_annealing,  Prev: sockets,  Up: Libraries

6.222 ‘spade_pattern_miner’
===========================

SPADE sequential pattern miner for sequence datasets.  The library
depends on the ‘sequential_pattern_mining_protocols’ support library,
implements the generic ‘pattern_miner_protocol’ defined in the
‘pattern_mining_protocols’ core library, and mines frequent sequential
patterns using Zaki’s equivalence-class decomposition with temporal
joins over vertical occurrence lists keyed by sequence and event
identifiers.

Requires a dataset implementing ‘sequence_dataset_protocol’ with
sequences represented as ordered lists of canonical sorted itemsets over
a declared item domain.

* Menu:

* API documentation: API documentation<238>.
* Loading: Loading<242>.
* Testing: Testing<233>.
* Features: Features<74>.
* Options: Options<72>.
* Pattern miner representation: Pattern miner representation<7>.
* References: References<51>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<238>,  Next: Loading<242>,  Up: spade_pattern_miner

6.222.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#spade_pattern_miner’ link in a
web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<242>,  Next: Testing<233>,  Prev: API documentation<238>,  Up: spade_pattern_miner

6.222.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(spade_pattern_miner(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<233>,  Next: Features<74>,  Prev: Loading<242>,  Up: spade_pattern_miner

6.222.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(spade_pattern_miner(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<74>,  Next: Options<72>,  Prev: Testing<233>,  Up: spade_pattern_miner

6.222.4 Features
----------------

   - 'Equivalence-Class Decomposition': Mines frequent sequences using
     Zaki’s equivalence-class decomposition over prefix-sharing classes.

   - 'Vertical Occurrence Lists': Represents frequent patterns using
     sequence and event occurrence lists.

   - 'Active Class Candidate Pruning': Restricts class joins to members
     that occur in the supporting sequences of the current prefix, using
     per-sequence member-id indexes instead of storing full pattern
     terms in the sequence index.

   - 'Same-Event and Sequence Extensions': Supports both itemset growth
     and next-event sequence growth.

   - 'Canonical Sequences': Validates that itemsets are sorted,
     duplicate-free, non-empty, and restricted to declared items.

   - 'Flexible Support Thresholds': Supports relative minimum support
     and absolute minimum support count.

   - 'Model Export': Mined pattern collections can be exported as
     predicate clauses or written to a file.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<72>,  Next: Pattern miner representation<7>,  Prev: Features<74>,  Up: spade_pattern_miner

6.222.5 Options
---------------

The ‘mine/3’ predicate accepts the following options:

   - ‘minimum_support/1’: Relative minimum support threshold in the
     interval ‘]0.0, 1.0]’.  The default is ‘0.5’.

   - ‘minimum_support_count/1’: Absolute minimum support count.  When
     both support options are provided, this option takes precedence.

   - ‘maximum_pattern_length/1’: Maximum total number of items in a
     mined sequential pattern.  The default is ‘1000’, effectively
     capped by the longest sequence in the dataset.

   - ‘minimum_pattern_length/1’: Minimum total number of items retained
     in the mined result.  The default is ‘1’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Pattern miner representation<7>,  Next: References<51>,  Prev: Options<72>,  Up: spade_pattern_miner

6.222.6 Pattern miner representation
------------------------------------

The mined pattern miner result is represented by a compound term with
the functor chosen by the implementation and arity 3.  For example:

     spade_pattern_miner(ItemDomain, Patterns, Options)

Where:

   - ‘ItemDomain’: Canonical sorted list of declared dataset items.

   - ‘Patterns’: List of ‘sequence_pattern(Pattern, SupportCount)’ terms
     ordered first by total item count and then lexicographically.

   - ‘Options’: Effective mining options used to mine the frequent
     sequential patterns.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<51>,  Prev: Pattern miner representation<7>,  Up: spade_pattern_miner

6.222.7 References
------------------

  1. Zaki, M. J. (2001) - “SPADE: An efficient algorithm for mining
     frequent sequences”.


File: TheLogtalkHandbook-3.101.0.info,  Node: simulated_annealing,  Next: statistics,  Prev: spade_pattern_miner,  Up: Libraries

6.223 ‘simulated_annealing’
===========================

Simulated annealing is a probabilistic meta-heuristic for approximating
the global optimum of a given function.  It is particularly useful for
combinatorial optimization problems such as the Traveling Salesman
Problem (TSP), graph coloring, and scheduling.

The library provides the parametric object ‘simulated_annealing(Problem,
RandomAlgorithm)’ where ‘Problem’ is an object implementing the
‘simulated_annealing_protocol’ protocol and ‘RandomAlgorithm’ is one of
the algorithms supported by the ‘fast_random’ library.  The algorithm
minimizes the energy (cost) function defined by the problem.

A convenience object ‘simulated_annealing(Problem)’ is also provided,
using the Xoshiro128++ random number generator (‘xoshiro128pp’) as the
default.

* Menu:

* API documentation: API documentation<239>.
* Loading: Loading<243>.
* Testing: Testing<234>.
* Features: Features<75>.
* Defining a problem::
* Options: Options<73>.
* Run statistics::
* Usage: Usage<103>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<239>,  Next: Loading<243>,  Up: simulated_annealing

6.223.1 API documentation
-------------------------

Open the ‘../../docs/library_index.html#simulated-annealing’ link in a
web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<243>,  Next: Testing<234>,  Prev: API documentation<239>,  Up: simulated_annealing

6.223.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(simulated_annealing(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<234>,  Next: Features<75>,  Prev: Loading<243>,  Up: simulated_annealing

6.223.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(simulated_annealing(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<75>,  Next: Defining a problem,  Prev: Testing<234>,  Up: simulated_annealing

6.223.4 Features
----------------

   - 'Configurable random number generator' — the algorithm is
     parameterized by a ‘fast_random’ algorithm.  Available algorithms
     include ‘xoshiro128pp’, ‘xoshiro128ss’, ‘xoshiro256pp’,
     ‘xoshiro256ss’, ‘well512a’, ‘splitmix64’, and ‘as183’.  The
     convenience object ‘simulated_annealing(Problem)’ defaults to
     ‘xoshiro128pp’.

   - 'Boltzmann acceptance criterion' — a worse neighbor is accepted
     with probability ‘exp(-DeltaE / Temperature)’, allowing the search
     to escape local minima early in the run while converging as the
     temperature cools.

   - 'Configurable cooling schedule' — default geometric cooling
     (‘NewTemp is Temp * 0.995’), overridable by defining
     ‘cooling_schedule/3’ in the problem object.

   - 'Custom stop conditions' — the search stops when the maximum number
     of steps is reached or the temperature drops below the minimum
     temperature.  A problem object can define ‘stop_condition/3’ to
     terminate early (e.g.  when a good-enough solution is found).

   - 'Delta-energy optimization' — when the problem object defines
     ‘neighbor_state/3’, the algorithm uses the returned energy delta
     directly instead of recomputing the full energy.  This is useful
     when computing the change is cheaper than evaluating the full cost
     (e.g.  a 2-opt swap in TSP).

   - 'Best state tracking' — the algorithm tracks the best state found
     across all iterations and across all restart cycles, not just the
     final state.

   - 'Progress reporting' — if the problem object defines ‘progress/5’,
     it is called periodically with the current step, temperature, best
     energy, acceptance rate, and improvement rate.  A final report is
     always produced when the loop terminates.

   - 'Run statistics' — the ‘run/4’ predicate returns a list of
     statistics including the number of steps, acceptances,
     improvements, and the final temperature.

   - 'Seed control' — the ‘seed(S)’ option initializes the random number
     generator for reproducible runs.

   - 'Reheating restarts' — the ‘restarts(N)’ option runs N additional
     SA cycles after the first.  Each restart reheats the temperature to
     the initial value and begins from the best state found so far,
     allowing the search to escape deep local minima.  Statistics
     accumulate across all cycles.

   - 'Auto-temperature estimation' — the ‘estimate_temperature/1-2’
     predicates sample random neighbor transitions and compute an
     initial temperature that would produce a target acceptance rate,
     avoiding manual tuning.


File: TheLogtalkHandbook-3.101.0.info,  Node: Defining a problem,  Next: Options<73>,  Prev: Features<75>,  Up: simulated_annealing

6.223.5 Defining a problem
--------------------------

A problem object must implement the ‘simulated_annealing_protocol’
protocol by defining (at least) the following four predicates:

   - ‘initial_state(-State)’ — returns the starting state.

   - ‘neighbor_state(+State, -Neighbor)’ — generates a neighboring
     state.

   - ‘state_energy(+State, -Energy)’ — computes the cost of a state (to
     be minimized).

   - ‘initial_temperature(-Temperature)’ — returns the starting
     temperature.

Optionally, the problem object may also define:

   - ‘neighbor_state(+State, -Neighbor, -DeltaEnergy)’ — generates a
     neighboring state and returns the energy change directly, avoiding
     a full energy recomputation.  Useful when computing the delta is
     cheaper than recomputing the full energy (e.g.  TSP with a 2-opt
     swap).

   - ‘cooling_schedule(+Temperature, +Step, -NewTemperature)’ — computes
     the next temperature.  Default: geometric cooling (‘NewTemp is Temp
     * 0.995’).

   - ‘stop_condition(+Step, +Temperature, +BestEnergy)’ — succeeds when
     the search should terminate early (e.g.  when a good-enough
     solution is found).  Default: the search runs until the maximum
     number of steps is reached or the temperature drops below the
     minimum temperature.

   - ‘progress(+Step, +Temperature, +BestEnergy, +AcceptanceRate,
     +ImprovementRate)’ — called periodically during the optimization to
     report progress.  A final report is always produced when the loop
     terminates.  The acceptance and improvement rates are floats
     between 0.0 and 1.0.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<73>,  Next: Run statistics,  Prev: Defining a problem,  Up: simulated_annealing

6.223.6 Options
---------------

Options for the ‘run/3-4’ predicates:

   - ‘max_steps(N)’ — maximum number of iterations per cycle (default:
     ‘10000’).

   - ‘min_temperature(T)’ — minimum temperature floor; the search stops
     when the temperature drops below this value (default: ‘0.001’).

   - ‘updates(N)’ — number of progress reports during the run.  Progress
     is reported by calling ‘progress/5’ on the problem object.  Set to
     ‘0’ to disable (default: ‘0’).

   - ‘seed(S)’ — positive integer seed for the random number generator,
     enabling reproducible runs (default: none).

   - ‘restarts(N)’ — number of additional SA cycles after the first.
     Each restart reheats the temperature to the initial value and
     begins from the best state found so far, allowing the search to
     escape local minima (default: ‘0’).

Options for the ‘estimate_temperature/2’ predicate:

   - ‘samples(N)’ — number of random neighbor transitions to sample
     (default: ‘200’).

   - ‘acceptance_rate(P)’ — target initial acceptance rate as an integer
     percentage between 1 and 99 (default: ‘80’).


File: TheLogtalkHandbook-3.101.0.info,  Node: Run statistics,  Next: Usage<103>,  Prev: Options<73>,  Up: simulated_annealing

6.223.7 Run statistics
----------------------

The ‘run/4’ predicate returns a list of statistics about the completed
run:

   - ‘steps(N)’ — total number of steps executed.

   - ‘acceptances(A)’ — number of accepted moves (both improving and
     uphill).

   - ‘improvements(I)’ — number of moves that strictly improved the best
     energy found.

   - ‘final_temperature(T)’ — temperature at termination.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<103>,  Prev: Run statistics,  Up: simulated_annealing

6.223.8 Usage
-------------

* Menu:

* Defining a problem: Defining a problem<2>.
* Running the algorithm::
* Running with custom options::
* Running with statistics::
* Reproducible runs with seed::
* Reheating restarts::
* Auto-temperature estimation::
* Using a custom random number generator::


File: TheLogtalkHandbook-3.101.0.info,  Node: Defining a problem<2>,  Next: Running the algorithm,  Up: Usage<103>

6.223.8.1 Defining a problem
............................

Define an object implementing the ‘simulated_annealing_protocol’
protocol.  For example, a simple quadratic minimization problem:

     :- object(quadratic,
         implements(simulated_annealing_protocol)).

         initial_state(50.0).
         neighbor_state(X, Y) :-
             random::random(-5.0, 5.0, Delta),
             Y is X + Delta.
         state_energy(X, E) :-
             E is (X - 3.0) * (X - 3.0).
         initial_temperature(100.0).

     :- end_object.


File: TheLogtalkHandbook-3.101.0.info,  Node: Running the algorithm,  Next: Running with custom options,  Prev: Defining a problem<2>,  Up: Usage<103>

6.223.8.2 Running the algorithm
...............................

     | ?- simulated_annealing(quadratic)::run(State, Energy).
     State = 3.001..., Energy = 0.000...


File: TheLogtalkHandbook-3.101.0.info,  Node: Running with custom options,  Next: Running with statistics,  Prev: Running the algorithm,  Up: Usage<103>

6.223.8.3 Running with custom options
.....................................

     | ?- simulated_annealing(quadratic)::run(State, Energy, [max_steps(50000)]).
     State = 3.000..., Energy = 0.000...


File: TheLogtalkHandbook-3.101.0.info,  Node: Running with statistics,  Next: Reproducible runs with seed,  Prev: Running with custom options,  Up: Usage<103>

6.223.8.4 Running with statistics
.................................

     | ?- simulated_annealing(quadratic)::run(State, Energy, Stats, []).
     State = 3.001..., Energy = 0.000...,
     Stats = [steps(10000), acceptances(...), improvements(...), final_temperature(...)]


File: TheLogtalkHandbook-3.101.0.info,  Node: Reproducible runs with seed,  Next: Reheating restarts,  Prev: Running with statistics,  Up: Usage<103>

6.223.8.5 Reproducible runs with seed
.....................................

     | ?- simulated_annealing(quadratic)::run(S1, E1, [seed(42)]),
          simulated_annealing(quadratic)::run(S2, E2, [seed(42)]).
     S1 = S2, E1 = E2.


File: TheLogtalkHandbook-3.101.0.info,  Node: Reheating restarts,  Next: Auto-temperature estimation,  Prev: Reproducible runs with seed,  Up: Usage<103>

6.223.8.6 Reheating restarts
............................

Run 3 SA cycles (1 initial + 2 restarts).  Each restart reheats the
temperature and begins from the best state found so far:

     | ?- simulated_annealing(quadratic)::run(State, Energy, [restarts(2)]).
     State = 3.000..., Energy = 0.000...


File: TheLogtalkHandbook-3.101.0.info,  Node: Auto-temperature estimation,  Next: Using a custom random number generator,  Prev: Reheating restarts,  Up: Usage<103>

6.223.8.7 Auto-temperature estimation
.....................................

Estimate a good initial temperature for the problem by sampling random
neighbor transitions:

     | ?- simulated_annealing(quadratic)::estimate_temperature(T).
     T = ...

With custom parameters (500 samples, 90% target acceptance rate):

     | ?- simulated_annealing(quadratic)::estimate_temperature(T, [samples(500), acceptance_rate(90)]).
     T = ...


File: TheLogtalkHandbook-3.101.0.info,  Node: Using a custom random number generator,  Prev: Auto-temperature estimation,  Up: Usage<103>

6.223.8.8 Using a custom random number generator
................................................

Use the two-parameter version to select a specific ‘fast_random’
algorithm:

     | ?- simulated_annealing(quadratic, well512a)::run(State, Energy).
     State = 3.001..., Energy = 0.000...

     | ?- simulated_annealing(quadratic, xoshiro256ss)::run(State, Energy, [seed(42)]).
     State = 3.000..., Energy = 0.000...


File: TheLogtalkHandbook-3.101.0.info,  Node: statistics,  Next: stemming,  Prev: simulated_annealing,  Up: Libraries

6.224 ‘statistics’
==================

The entities in this library define some useful predicates for
descriptive statistics.  Data is represented as a list of numbers
(integers or floats).  Use the object ‘sample’ if your data represents a
sample.  Use the object ‘population’ if your data represents a
population.

The ‘variance/2’, ‘standard_deviation/2’, ‘skewness/2’, ‘kurtosis/2’,
‘covariance/3’, ‘standard_error/2’, ‘correlation/3’, and
‘rank_correlation/3’ predicates use different formulas depending on
whether the data represents a sample (dividing by 'N-1') or a population
(dividing by 'N'). All other predicates share the same implementation.

* Menu:

* API documentation: API documentation<240>.
* Loading: Loading<244>.
* Testing: Testing<235>.
* API overview::


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<240>,  Next: Loading<244>,  Up: statistics

6.224.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#statistics’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<244>,  Next: Testing<235>,  Prev: API documentation<240>,  Up: statistics

6.224.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(statistics(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<235>,  Next: API overview,  Prev: Loading<244>,  Up: statistics

6.224.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(statistics(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: API overview,  Prev: Testing<235>,  Up: statistics

6.224.4 API overview
--------------------

* Menu:

* Aggregation::
* Extremes and Range::
* Central Tendency::
* Measures of Position / Quantiles::
* Measures of Dispersion::
* Measures of Shape::
* Measures of Association::
* Error Metrics::
* Normalization::
* Frequency / Counting::
* Validation: Validation<2>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Aggregation,  Next: Extremes and Range,  Up: API overview

6.224.4.1 Aggregation
.....................

Predicate         Description
                  
--------------------------------------------------
‘product/2’       Product of all list numbers
                  
‘sum/2’           Sum of all list numbers
                  


File: TheLogtalkHandbook-3.101.0.info,  Node: Extremes and Range,  Next: Central Tendency,  Prev: Aggregation,  Up: API overview

6.224.4.2 Extremes and Range
............................

Predicate         Description
                  
-------------------------------------------------
‘min/2’           Minimum value
                  
‘max/2’           Maximum value
                  
‘min_max/3’       Minimum and maximum values
                  
‘range/2’         Range (max - min)
                  


File: TheLogtalkHandbook-3.101.0.info,  Node: Central Tendency,  Next: Measures of Position / Quantiles,  Prev: Extremes and Range,  Up: API overview

6.224.4.3 Central Tendency
..........................

Predicate                   Description
                            
-------------------------------------------------------------------------------
‘arithmetic_mean/2’         Arithmetic mean
                            
‘geometric_mean/2’          Geometric mean
                            
‘harmonic_mean/2’           Harmonic mean
                            
‘weighted_mean/3’           Weighted mean
                            
‘trimmed_mean/3’            Trimmed mean (removing a fraction of extreme
                            values)
                            
‘median/2’                  Median
                            
‘modes/2’                   Modes (in ascending order)
                            


File: TheLogtalkHandbook-3.101.0.info,  Node: Measures of Position / Quantiles,  Next: Measures of Dispersion,  Prev: Central Tendency,  Up: API overview

6.224.4.4 Measures of Position / Quantiles
..........................................

Predicate                       Description
                                
-------------------------------------------------------------------------------
‘fractile/3’                    Fractile (quantile given a fraction in (0.0,
                                1.0))
                                
‘percentile/3’                  Percentile (quantile given a value in (0,
                                100))
                                
‘quartiles/4’                   Quartiles (Q1, Q2, Q3)
                                
‘interquartile_range/2’         Interquartile range (Q3 - Q1)
                                


File: TheLogtalkHandbook-3.101.0.info,  Node: Measures of Dispersion,  Next: Measures of Shape,  Prev: Measures of Position / Quantiles,  Up: API overview

6.224.4.5 Measures of Dispersion
................................

Predicate                               Description
                                        
-------------------------------------------------------------------------------
‘variance/2’                            Variance (sample or population)
                                        
‘standard_deviation/2’                  Standard deviation (sample or
                                        population)
                                        
‘mean_deviation/2’                      Mean absolute deviation
                                        
‘median_deviation/2’                    Median absolute deviation
                                        
‘average_deviation/3’                   Average absolute deviation from a
                                        given central tendency
                                        
‘coefficient_of_variation/2’            Coefficient of variation
                                        
‘relative_standard_deviation/2’         Relative standard deviation
                                        (percentage)
                                        
‘sum_of_squares/2’                      Sum of squared deviations from the
                                        mean
                                        
‘standard_error/2’                      Standard error of the mean
                                        


File: TheLogtalkHandbook-3.101.0.info,  Node: Measures of Shape,  Next: Measures of Association,  Prev: Measures of Dispersion,  Up: API overview

6.224.4.6 Measures of Shape
...........................

Predicate                Description
                         
--------------------------------------------------------------------
‘skewness/2’             Moment skewness (sample or population)
                         
‘kurtosis/2’             Excess kurtosis (sample or population)
                         
‘central_moment/3’       K-th central moment
                         


File: TheLogtalkHandbook-3.101.0.info,  Node: Measures of Association,  Next: Error Metrics,  Prev: Measures of Shape,  Up: API overview

6.224.4.7 Measures of Association
.................................

Predicate                  Description
                           
---------------------------------------------------------------------
‘covariance/3’             Covariance (sample or population)
                           
‘correlation/3’            Pearson correlation coefficient
                           
‘rank_correlation/3’       Spearman rank correlation coefficient
                           


File: TheLogtalkHandbook-3.101.0.info,  Node: Error Metrics,  Next: Normalization,  Prev: Measures of Association,  Up: API overview

6.224.4.8 Error Metrics
.......................

Predicate                         Description
                                  
--------------------------------------------------------------------------------
‘mean_squared_error/3’            Mean squared error between two lists
                                  
‘root_mean_squared_error/3’       Root mean squared error between two lists
                                  


File: TheLogtalkHandbook-3.101.0.info,  Node: Normalization,  Next: Frequency / Counting,  Prev: Error Metrics,  Up: API overview

6.224.4.9 Normalization
.......................

Predicate                       Description
                                
--------------------------------------------------------------------------------
‘z_normalization/2’             Z-score normalization (mean ~= 0, std ~= 1)
                                
‘min_max_normalization/2’       Min-max normalization (rescale to [0, 1])
                                


File: TheLogtalkHandbook-3.101.0.info,  Node: Frequency / Counting,  Next: Validation<2>,  Prev: Normalization,  Up: API overview

6.224.4.10 Frequency / Counting
...............................

Predicate                        Description
                                 
--------------------------------------------------------------------------------
‘frequency_distribution/2’       Frequency distribution (Value-Count pairs)
                                 


File: TheLogtalkHandbook-3.101.0.info,  Node: Validation<2>,  Prev: Frequency / Counting,  Up: API overview

6.224.4.11 Validation
.....................

Predicate       Description
                
-----------------------------------------------------
‘valid/1’       Term is a closed list of numbers
                


File: TheLogtalkHandbook-3.101.0.info,  Node: stemming,  Next: stomp,  Prev: statistics,  Up: Libraries

6.225 ‘stemming’
================

This library provides word stemming predicates for English text, with
support for different word representations: atoms, character lists, or
character code lists.

The library includes implementations of two well-known stemming
algorithms:

   - 'Porter Stemmer' - The Porter stemming algorithm (Porter, 1980) is
     a widely used algorithm for reducing English words to their root
     form by applying a series of rules that remove common suffixes.

   - 'Lovins Stemmer' - The Lovins stemming algorithm (Lovins, 1968)
     removes the longest suffix from a word using a list of endings,
     each associated with a condition for removal.  It then applies
     transformation rules to fix spelling.

* Menu:

* API documentation: API documentation<241>.
* Loading: Loading<245>.
* Testing: Testing<236>.
* Usage: Usage<104>.
* Algorithms: Algorithms<2>.
* Choosing an Algorithm::
* Known Limitations: Known Limitations<3>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<241>,  Next: Loading<245>,  Up: stemming

6.225.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#stemming’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<245>,  Next: Testing<236>,  Prev: API documentation<241>,  Up: stemming

6.225.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(stemming(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<236>,  Next: Usage<104>,  Prev: Loading<245>,  Up: stemming

6.225.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(stemming(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<104>,  Next: Algorithms<2>,  Prev: Testing<236>,  Up: stemming

6.225.4 Usage
-------------

The stemming predicates are defined in parametric objects where the
parameter specifies the word representation:

   - ‘atom’ - words are represented as atoms

   - ‘chars’ - words are represented as lists of characters

   - ‘codes’ - words are represented as lists of character codes

The parameter must be bound when sending messages to the objects.

* Menu:

* Porter Stemmer::
* Lovins Stemmer::


File: TheLogtalkHandbook-3.101.0.info,  Node: Porter Stemmer,  Next: Lovins Stemmer,  Up: Usage<104>

6.225.4.1 Porter Stemmer
........................

To stem a single word using atoms:

     | ?- porter_stemmer(atom)::stem(running, Stem).
     Stem = run
     yes

To stem a list of words:

     | ?- porter_stemmer(atom)::stems([running, walks, easily], Stems).
     Stems = [run, walk, easili]
     yes

Using character lists:

     | ?- porter_stemmer(chars)::stem([r,u,n,n,i,n,g], Stem).
     Stem = [r,u,n]
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: Lovins Stemmer,  Prev: Porter Stemmer,  Up: Usage<104>

6.225.4.2 Lovins Stemmer
........................

To stem a single word using atoms:

     | ?- lovins_stemmer(atom)::stem(running, Stem).
     Stem = run
     yes

To stem a list of words:

     | ?- lovins_stemmer(atom)::stems([running, walks, easily], Stems).
     Stems = [run, walk, eas]
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: Algorithms<2>,  Next: Choosing an Algorithm,  Prev: Usage<104>,  Up: stemming

6.225.5 Algorithms
------------------

* Menu:

* Porter Stemmer: Porter Stemmer<2>.
* Lovins Stemmer: Lovins Stemmer<2>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Porter Stemmer<2>,  Next: Lovins Stemmer<2>,  Up: Algorithms<2>

6.225.5.1 Porter Stemmer
........................

The Porter stemming algorithm, developed by Martin Porter in 1980, is
one of the most widely used stemming algorithms for the English
language.  It operates through a series of steps that progressively
remove suffixes from words:

  1. 'Step 1a': Handle plurals (e.g., “caresses” → “caress”, “ponies” →
     “poni”)

  2. 'Step 1b': Handle past tense and progressive forms (e.g., “agreed”
     → “agree”)

  3. 'Step 1c': Replace terminal “y” with “i” when preceded by a vowel

  4. 'Steps 2-4': Remove various suffixes based on the “measure” of the
     stem

  5. 'Step 5': Clean up final “e” and double consonants

The algorithm uses the concept of “measure” (m), which counts
vowel-consonant sequences in the stem, to determine when suffixes can be
safely removed.

'Reference': Porter, M.F. (1980).  An algorithm for suffix stripping.
Program, 14(3), 130-137.


File: TheLogtalkHandbook-3.101.0.info,  Node: Lovins Stemmer<2>,  Prev: Porter Stemmer<2>,  Up: Algorithms<2>

6.225.5.2 Lovins Stemmer
........................

The Lovins stemming algorithm, developed by Julie Beth Lovins in 1968,
was one of the earliest stemming algorithms.  It takes a different
approach from Porter:

  1. 'Ending removal': The algorithm maintains a list of 294 possible
     endings, ordered by length.  It removes the longest matching ending
     that satisfies its associated condition (e.g., minimum stem
     length).

  2. 'Transformation rules': After removing the ending, spelling
     transformations are applied to fix common irregularities (e.g.,
     “iev” → “ief”, “uct” → “uc”).

The Lovins algorithm tends to be more aggressive than Porter, sometimes
producing stems that are not actual words but are consistent across
related word forms.

'Reference': Lovins, J.B. (1968).  Development of a stemming algorithm.
Mechanical Translation and Computational Linguistics, 11(1-2), 22-31.


File: TheLogtalkHandbook-3.101.0.info,  Node: Choosing an Algorithm,  Next: Known Limitations<3>,  Prev: Algorithms<2>,  Up: stemming

6.225.6 Choosing an Algorithm
-----------------------------

   - 'Porter': More conservative, produces more readable stems, widely
     used in information retrieval and search applications.  Good choice
     for most applications.

   - 'Lovins': More aggressive, may conflate more word forms together.
     Can be useful when broader matching is desired, but may over-stem
     in some cases.

Both algorithms are designed for English text only.


File: TheLogtalkHandbook-3.101.0.info,  Node: Known Limitations<3>,  Prev: Choosing an Algorithm,  Up: stemming

6.225.7 Known Limitations
-------------------------

   - Both algorithms work only with English words.

   - Stemming is not lemmatization - stems may not be valid dictionary
     words.

   - Proper nouns and abbreviations may not be handled correctly.

   - Very short words (1-2 characters) are returned unchanged.


File: TheLogtalkHandbook-3.101.0.info,  Node: stomp,  Next: string_distance,  Prev: stemming,  Up: Libraries

6.226 ‘stomp’
=============

Portable STOMP 1.2 (Simple Text Orientated Messaging Protocol) client
implementation.  This library uses the ‘sockets’ library and supports
all backend Prolog systems supported by that library: ECLiPSe, GNU
Prolog, SICStus Prolog, SWI-Prolog, Trealla Prolog, and XVM.

* Menu:

* Protocol Version: Protocol Version<2>.
* Features: Features<76>.
* API documentation: API documentation<242>.
* Loading: Loading<246>.
* Testing: Testing<237>.
* Usage: Usage<105>.
* API Summary: API Summary<4>.
* Connection Options::
* Send Options::
* Subscribe Options::
* Receive Options::
* Error Handling: Error Handling<3>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Protocol Version<2>,  Next: Features<76>,  Up: stomp

6.226.1 Protocol Version
------------------------

This library implements the STOMP 1.2 protocol specification:

‘https://stomp.github.io/stomp-specification-1.2.html’

STOMP 1.2 is backwards compatible with STOMP 1.1 with minor differences
in frame line endings and message acknowledgment.


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<76>,  Next: API documentation<242>,  Prev: Protocol Version<2>,  Up: stomp

6.226.2 Features
----------------

   - Full STOMP 1.2 protocol support

   - Heartbeat negotiation and automatic heartbeat handling

   - Multiple concurrent subscriptions with unique IDs

   - All acknowledgment modes: ‘auto’, ‘client’, ‘client-individual’

   - Transaction support: ‘BEGIN’, ‘COMMIT’, ‘ABORT’

   - Graceful disconnect with receipt confirmation

   - Proper frame encoding/decoding with header escaping

   - User-defined headers for messages


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<242>,  Next: Loading<246>,  Prev: Features<76>,  Up: stomp

6.226.3 API documentation
-------------------------

Open the ‘../../apis/library_index.html#stomp’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<246>,  Next: Testing<237>,  Prev: API documentation<242>,  Up: stomp

6.226.4 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(stomp(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<237>,  Next: Usage<105>,  Prev: Loading<246>,  Up: stomp

6.226.5 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(stomp(tester)).

Note: Integration tests require a running STOMP server (e.g., RabbitMQ
with the STOMP plugin, ActiveMQ, or Apache Apollo).  They are usually
run using RabbitMQ with the STOMP plugin.  As RabbitMQ uses ‘/’ as its
default virtual host, the tests assume this and use the ‘host('/')’
option when calling the ‘connect/4’ predicate (otherwise the connection
would fail with a ‘"Virtual host 'localhost' access denied"’ error
message).  To enable the RabbitMQ’s STOMP plugin:

     $ rabbitmq-plugins enable rabbitmq_stomp

RabbitMQ STOMP listens on port 61613 by default.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<105>,  Next: API Summary<4>,  Prev: Testing<237>,  Up: stomp

6.226.6 Usage
-------------

* Menu:

* Connecting to a STOMP server::
* Sending messages::
* Subscribing to destinations::
* Receiving messages::
* Acknowledging messages::
* Unsubscribing::
* Transactions: Transactions<2>.
* Disconnecting: Disconnecting<3>.
* Heartbeat handling::
* Working with frames::


File: TheLogtalkHandbook-3.101.0.info,  Node: Connecting to a STOMP server,  Next: Sending messages,  Up: Usage<105>

6.226.6.1 Connecting to a STOMP server
......................................

Basic connection assuming RabbitMQ, which uses ‘host('/')’ as shown:

     ?- stomp::connect(localhost, 61613, Connection, [host('/')]).

Connection with authentication:

     ?- stomp::connect(localhost, 61613, Connection, [
            login('user'),
            passcode('password')
        ]).

Connection with heartbeat:

     ?- stomp::connect(localhost, 61613, Connection, [
            heartbeat(10000, 10000)
        ]).

Connection with virtual host:

     ?- stomp::connect(localhost, 61613, Connection, [
            host('/my-vhost')
        ]).


File: TheLogtalkHandbook-3.101.0.info,  Node: Sending messages,  Next: Subscribing to destinations,  Prev: Connecting to a STOMP server,  Up: Usage<105>

6.226.6.2 Sending messages
..........................

Send a simple text message:

     ?- stomp::send(Connection, '/queue/test', 'Hello, World!', []).

Send a message with content type:

     ?- stomp::send(Connection, '/queue/test', '{"key":"value"}', [
            content_type('application/json')
        ]).

Send with custom headers:

     ?- stomp::send(Connection, '/queue/test', 'Message', [
            header('priority', '9'),
            header('persistent', 'true')
        ]).

Send within a transaction:

     ?- stomp::begin_transaction(Connection, 'tx-001', []),
        stomp::send(Connection, '/queue/test', 'Message 1', [transaction('tx-001')]),
        stomp::send(Connection, '/queue/test', 'Message 2', [transaction('tx-001')]),
        stomp::commit_transaction(Connection, 'tx-001', []).


File: TheLogtalkHandbook-3.101.0.info,  Node: Subscribing to destinations,  Next: Receiving messages,  Prev: Sending messages,  Up: Usage<105>

6.226.6.3 Subscribing to destinations
.....................................

Subscribe with auto acknowledgment (default):

     ?- stomp::subscribe(Connection, '/queue/test', 'sub-0', []).

Subscribe with client acknowledgment:

     ?- stomp::subscribe(Connection, '/queue/test', 'sub-0', [
            ack(client)
        ]).

Subscribe with client-individual acknowledgment:

     ?- stomp::subscribe(Connection, '/topic/events', 'sub-1', [
            ack(client_individual)
        ]).


File: TheLogtalkHandbook-3.101.0.info,  Node: Receiving messages,  Next: Acknowledging messages,  Prev: Subscribing to destinations,  Up: Usage<105>

6.226.6.4 Receiving messages
............................

Poll for a message (non-blocking):

     ?- stomp::receive(Connection, Frame, [timeout(0)]).

Wait for a message with timeout (milliseconds):

     ?- stomp::receive(Connection, Frame, [timeout(5000)]).

Process received MESSAGE frame:

     ?- stomp::receive(Connection, Frame, []),
        stomp::frame_command(Frame, 'MESSAGE'),
        stomp::frame_header(Frame, 'destination', Destination),
        stomp::frame_header(Frame, 'message-id', MessageId),
        stomp::frame_body(Frame, Body).


File: TheLogtalkHandbook-3.101.0.info,  Node: Acknowledging messages,  Next: Unsubscribing,  Prev: Receiving messages,  Up: Usage<105>

6.226.6.5 Acknowledging messages
................................

For ‘client’ or ‘client-individual’ acknowledgment modes:

     ?- stomp::receive(Connection, Frame, []),
        stomp::frame_header(Frame, 'ack', AckId),
        stomp::ack(Connection, AckId, []).

Negative acknowledgment:

     ?- stomp::nack(Connection, AckId, []).

Acknowledgment within a transaction:

     ?- stomp::ack(Connection, AckId, [transaction('tx-001')]).


File: TheLogtalkHandbook-3.101.0.info,  Node: Unsubscribing,  Next: Transactions<2>,  Prev: Acknowledging messages,  Up: Usage<105>

6.226.6.6 Unsubscribing
.......................

     ?- stomp::unsubscribe(Connection, 'sub-0', []).


File: TheLogtalkHandbook-3.101.0.info,  Node: Transactions<2>,  Next: Disconnecting<3>,  Prev: Unsubscribing,  Up: Usage<105>

6.226.6.7 Transactions
......................

Begin a transaction:

     ?- stomp::begin_transaction(Connection, 'tx-001', []).

Commit a transaction:

     ?- stomp::commit_transaction(Connection, 'tx-001', []).

Abort a transaction:

     ?- stomp::abort_transaction(Connection, 'tx-001', []).


File: TheLogtalkHandbook-3.101.0.info,  Node: Disconnecting<3>,  Next: Heartbeat handling,  Prev: Transactions<2>,  Up: Usage<105>

6.226.6.8 Disconnecting
.......................

Graceful disconnect with receipt confirmation:

     ?- stomp::disconnect(Connection, []).


File: TheLogtalkHandbook-3.101.0.info,  Node: Heartbeat handling,  Next: Working with frames,  Prev: Disconnecting<3>,  Up: Usage<105>

6.226.6.9 Heartbeat handling
............................

Send a heartbeat (if needed manually):

     ?- stomp::send_heartbeat(Connection).

Check connection health:

     ?- stomp::connection_alive(Connection).


File: TheLogtalkHandbook-3.101.0.info,  Node: Working with frames,  Prev: Heartbeat handling,  Up: Usage<105>

6.226.6.10 Working with frames
..............................

Get frame command:

     ?- stomp::frame_command(Frame, Command).

Get frame header value:

     ?- stomp::frame_header(Frame, HeaderName, Value).

Get frame body:

     ?- stomp::frame_body(Frame, Body).

Get all frame headers:

     ?- stomp::frame_headers(Frame, Headers).


File: TheLogtalkHandbook-3.101.0.info,  Node: API Summary<4>,  Next: Connection Options,  Prev: Usage<105>,  Up: stomp

6.226.7 API Summary
-------------------

* Menu:

* Connection management: Connection management<2>.
* Messaging::
* Acknowledgment::
* Transactions: Transactions<3>.
* Heartbeat::
* Frame inspection::


File: TheLogtalkHandbook-3.101.0.info,  Node: Connection management<2>,  Next: Messaging,  Up: API Summary<4>

6.226.7.1 Connection management
...............................

   - ‘connect(+Host, +Port, -Connection, +Options)’ - Connect to server

   - ‘disconnect(+Connection, +Options)’ - Disconnect from server

   - ‘connection_alive(+Connection)’ - Check if connection is alive


File: TheLogtalkHandbook-3.101.0.info,  Node: Messaging,  Next: Acknowledgment,  Prev: Connection management<2>,  Up: API Summary<4>

6.226.7.2 Messaging
...................

   - ‘send(+Connection, +Destination, +Body, +Options)’ - Send message

   - ‘subscribe(+Connection, +Destination, +Id, +Options)’ - Subscribe

   - ‘unsubscribe(+Connection, +Id, +Options)’ - Unsubscribe

   - ‘receive(+Connection, -Frame, +Options)’ - Receive frame


File: TheLogtalkHandbook-3.101.0.info,  Node: Acknowledgment,  Next: Transactions<3>,  Prev: Messaging,  Up: API Summary<4>

6.226.7.3 Acknowledgment
........................

   - ‘ack(+Connection, +Id, +Options)’ - Acknowledge message

   - ‘nack(+Connection, +Id, +Options)’ - Negative acknowledge


File: TheLogtalkHandbook-3.101.0.info,  Node: Transactions<3>,  Next: Heartbeat,  Prev: Acknowledgment,  Up: API Summary<4>

6.226.7.4 Transactions
......................

   - ‘begin_transaction(+Connection, +TransactionId, +Options)’ - Begin

   - ‘commit_transaction(+Connection, +TransactionId, +Options)’ -
     Commit

   - ‘abort_transaction(+Connection, +TransactionId, +Options)’ - Abort


File: TheLogtalkHandbook-3.101.0.info,  Node: Heartbeat,  Next: Frame inspection,  Prev: Transactions<3>,  Up: API Summary<4>

6.226.7.5 Heartbeat
...................

   - ‘send_heartbeat(+Connection)’ - Send heartbeat EOL


File: TheLogtalkHandbook-3.101.0.info,  Node: Frame inspection,  Prev: Heartbeat,  Up: API Summary<4>

6.226.7.6 Frame inspection
..........................

   - ‘frame_command(+Frame, -Command)’ - Get frame command

   - ‘frame_header(+Frame, +Name, -Value)’ - Get header value

   - ‘frame_headers(+Frame, -Headers)’ - Get all headers

   - ‘frame_body(+Frame, -Body)’ - Get frame body


File: TheLogtalkHandbook-3.101.0.info,  Node: Connection Options,  Next: Send Options,  Prev: API Summary<4>,  Up: stomp

6.226.8 Connection Options
--------------------------

   - ‘login(Login)’ - Username for authentication

   - ‘passcode(Passcode)’ - Password for authentication

   - ‘host(VirtualHost)’ - Virtual host name (default: from Host
     parameter)

   - ‘heartbeat(ClientMs, ServerMs)’ - Heartbeat timing in milliseconds


File: TheLogtalkHandbook-3.101.0.info,  Node: Send Options,  Next: Subscribe Options,  Prev: Connection Options,  Up: stomp

6.226.9 Send Options
--------------------

   - ‘content_type(MimeType)’ - MIME type of the body

   - ‘content_length(Length)’ - Byte length of body (auto-calculated if
     omitted)

   - ‘transaction(TransactionId)’ - Include in transaction

   - ‘receipt(ReceiptId)’ - Request receipt from server

   - ‘header(Name, Value)’ - Add custom header


File: TheLogtalkHandbook-3.101.0.info,  Node: Subscribe Options,  Next: Receive Options,  Prev: Send Options,  Up: stomp

6.226.10 Subscribe Options
--------------------------

   - ‘ack(Mode)’ - Acknowledgment mode: ‘auto’, ‘client’, or
     ‘client_individual’


File: TheLogtalkHandbook-3.101.0.info,  Node: Receive Options,  Next: Error Handling<3>,  Prev: Subscribe Options,  Up: stomp

6.226.11 Receive Options
------------------------

   - ‘timeout(Milliseconds)’ - Wait timeout; 0 for non-blocking, -1 for
     infinite


File: TheLogtalkHandbook-3.101.0.info,  Node: Error Handling<3>,  Prev: Receive Options,  Up: stomp

6.226.12 Error Handling
-----------------------

Most predicates throw ‘error(stomp_error(Reason), Context)’ on failure.
Common error reasons:

   - ‘connection_failed’ - Could not establish TCP connection

   - ‘protocol_error(Message)’ - Server sent ERROR frame

   - ‘not_connected’ - Connection was closed

   - ‘invalid_frame’ - Malformed frame received

   - ‘timeout’ - Operation timed out


File: TheLogtalkHandbook-3.101.0.info,  Node: string_distance,  Next: strings,  Prev: stomp,  Up: Libraries

6.227 ‘string_distance’
=======================

This library provides string distance predicates with support for
different string representations: atoms, character lists, or character
code lists.

The predicates are defined in the ‘string_distance(_Representation_)’
parametric object where ‘_Representation_’ can be one of:

   - ‘atom’ - strings are represented as atoms

   - ‘chars’ - strings are represented as lists of characters

   - ‘codes’ - strings are represented as lists of character codes

The parameter must be bound when sending messages to the object.

* Menu:

* API documentation: API documentation<243>.
* Loading: Loading<247>.
* Testing: Testing<238>.
* Algorithms: Algorithms<3>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<243>,  Next: Loading<247>,  Up: string_distance

6.227.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#string_distance’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<247>,  Next: Testing<238>,  Prev: API documentation<243>,  Up: string_distance

6.227.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(string_distance(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<238>,  Next: Algorithms<3>,  Prev: Loading<247>,  Up: string_distance

6.227.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(string_distance(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Algorithms<3>,  Prev: Testing<238>,  Up: string_distance

6.227.4 Algorithms
------------------

This library implements the following string distance algorithms:

   - 'Levenshtein' distance is probably the most well-known.  It counts
     the minimum number of single-character edits — insertions,
     deletions, or substitutions — needed to transform one string into
     another.  For example, the distance between “kitten” and “sitting”
     is 3.

   - 'Damerau-Levenshtein' distance extends Levenshtein by also allowing
     transpositions of two adjacent characters as a single edit
     operation.  This makes it more practical for catching common typos
     like “ab” -> “ba”.

   - 'Hamming' distance only works on strings of equal length and counts
     the number of positions where the corresponding characters differ.
     It’s very fast but limited by that equal-length constraint, making
     it useful for things like comparing binary codes or fixed-format
     identifiers.

   - 'Jaro and Jaro-Winkler' distance produce a similarity score between
     0 and 1 rather than a raw edit count.  Jaro considers matching
     characters and transpositions, while Jaro-Winkler adds a
     prefix-weighting boost — the idea being that strings matching at
     the start are more likely to be the same (useful for name
     matching).

   - 'Edit similarity' is a normalized version of the edit distance,
     defined as 1 - (edit distance / max length of the two strings).  It
     produces a similarity score between 0 and 1.  Can be computed from
     Levenshtein, Damerau-Levenshtein, Hamming, or Longest Common
     Subsequence distances.

   - 'Longest Common Subsequence' (LCS) finds the length of the longest
     sequence of characters that appears in both strings in the same
     relative order (not necessarily contiguous).  It’s heavily used in
     diff tools for comparing files.

   - 'Longest Common Substring' is similar to LCS but requires the
     shared characters to be contiguous.  Useful when caring about
     shared blocks of text rather than scattered matches.

   - 'Cosine Similarity' shifts the approach from character edits to
     vector-based comparison.  Strings are converted into vectors (often
     using character n-grams or word tokens), and then the cosine of the
     angle between them is computed.  It’s widely used in NLP and
     information retrieval.

   - 'Jaccard Index' compares two sets of tokens (often words or
     n-grams) by dividing the size of their intersection by the size of
     their union.  Simple and intuitive, though it ignores term
     frequency.

   - 'Soundex/Metaphone' are phonetic algorithms rather than strict
     string comparisons.  They encode strings based on how they sound,
     so “Smith” and “Smythe” would match.  Useful for name deduplication
     where spelling varies but pronunciation is similar.

General advice: use Levenshtein or Damerau-Levenshtein for
general-purpose edit distance, Jaro-Winkler for short strings like
names, LCS for diff-style comparisons, and cosine/Jaccard when working
at the word or document level rather than character level.


File: TheLogtalkHandbook-3.101.0.info,  Node: strings,  Next: subsequences,  Prev: string_distance,  Up: Libraries

6.228 ‘strings’
===============

This library provides string manipulation predicates with support for
different string representations: atoms, character lists, or character
code lists.  Its API is partially based on work and libraries found in
ECLiPSe and SWI-Prolog.

The predicates are defined in the ‘string(_Representation_)’ parametric
object where ‘_Representation_’ can be one of:

   - ‘atom’ - strings are represented as atoms

   - ‘chars’ - strings are represented as lists of characters

   - ‘codes’ - strings are represented as lists of character codes

The parameter must be bound when sending messages to the object.

* Menu:

* API documentation: API documentation<244>.
* Loading: Loading<248>.
* Testing: Testing<239>.
* Predicates: Predicates<2>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<244>,  Next: Loading<248>,  Up: strings

6.228.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#strings’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<248>,  Next: Testing<239>,  Prev: API documentation<244>,  Up: strings

6.228.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(strings(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<239>,  Next: Predicates<2>,  Prev: Loading<248>,  Up: strings

6.228.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(strings(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Predicates<2>,  Prev: Testing<239>,  Up: strings

6.228.4 Predicates
------------------

The library provides the following compatibility predicates:

   - ‘atom_string/2’ - converts between atoms and strings

   - ‘number_string/2’ - converts between numbers and strings

   - ‘string_chars/2’ - converts between strings and character lists

   - ‘string_codes/2’ - converts between strings and character code
     lists

   - ‘string_concat/3’ - concatenates two strings

   - ‘string_length/2’ - returns the length of a string

   - ‘sub_string/5’ - extracts substrings

   - ‘string_upper/2’ - converts a string to uppercase

   - ‘string_lower/2’ - converts a string to lowercase

   - ‘split_string/4’ - splits a string into substrings using separators
     and padding

   - ‘atomics_to_string/2’ - concatenates a list of atomic terms into a
     string

   - ‘atomics_to_string/3’ - concatenates a list of atomic terms into a
     string with separator

It also provides the following string trimming predicates:

   - ‘trim/2-3’ - trims leading and trailing characters from a string

   - ‘trim_left/2-3’ - trims leading characters from a string

   - ‘trim_right/2-3’ - trims trailing characters from a string

For converting between terms and strings, see the ‘term_io’ library.


File: TheLogtalkHandbook-3.101.0.info,  Node: subsequences,  Next: term_io,  Prev: strings,  Up: Libraries

6.229 ‘subsequences’
====================

This library provides predicates for working with subsequences
represented using lists, including generation, search, contiguous
subsequence operations, and random selection.  The following categories
of predicates are provided:

   - 'Generation operations' - Predicates for generating subsequences
     and variants thereof.

   - 'Ordering variants' - Predicates that support an additional order
     argument (‘default’, ‘lexicographic’, or ‘shortlex’) for
     controlling output order.

   - 'Filtered generation' - Predicates for generating specific types of
     subsequences (combinations, permutations).

   - 'Indexed access' - Predicates for direct access to subsequences at
     specific positions.

   - 'Searching and matching' - Predicates for finding specific
     subsequences with desired properties.

   - 'Prefix and suffix operations' - Predicates for checking and
     finding prefixes and suffixes.

   - 'Contiguous subsequences' - Predicates for working with contiguous
     subsequences (subslices, sliding windows).

   - 'Random selection' - Predicates for randomly selecting
     subsequences.

   - 'Constrained operations' - Predicates for generating subsequences
     with specific constraints.

   - 'Utility predicates' - Predicates that support subsequence
     operations.

Dedicated ‘arrangements’, ‘cartesian_products’, ‘derangements’,
‘combinations’, ‘multisets’, and ‘permutations’ libraries are also
available for focused APIs on related operations.

* Menu:

* API documentation: API documentation<245>.
* Loading: Loading<249>.
* Testing: Testing<240>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<245>,  Next: Loading<249>,  Up: subsequences

6.229.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#subsequences’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<249>,  Next: Testing<240>,  Prev: API documentation<245>,  Up: subsequences

6.229.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(subsequences(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<240>,  Prev: Loading<249>,  Up: subsequences

6.229.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(subsequences(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: term_io,  Next: thurstone_mosteller_ranker,  Prev: subsequences,  Up: Libraries

6.230 ‘term_io’
===============

This library implements predicates for reading/writing terms from/to
atoms, chars (lists of characters), and codes (lists of character
codes).  These predicates are implemented using a single temporary file
created when the library is loaded.  This temporary file is unique per
Logtalk process.  The predicates can be safely used in multi-threaded
applications.

* Menu:

* API documentation: API documentation<246>.
* Loading: Loading<250>.
* Testing: Testing<241>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<246>,  Next: Loading<250>,  Up: term_io

6.230.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#term-io’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<250>,  Next: Testing<241>,  Prev: API documentation<246>,  Up: term_io

6.230.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(term_io(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<241>,  Prev: Loading<250>,  Up: term_io

6.230.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(term_io(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: thurstone_mosteller_ranker,  Next: time_scales,  Prev: term_io,  Up: Libraries

6.231 ‘thurstone_mosteller_ranker’
==================================

Thurstone-Mosteller Case V pairwise preference ranker.  It aggregates
pairwise outcomes into matchup probabilities, applies a fixed continuity
correction to avoid infinite probit values, transforms them with the
inverse standard normal CDF, and fits Case V latent utilities using a
deterministic weighted least-squares linear solve.

The library implements the ‘ranker_protocol’ defined in the
‘ranking_protocols’ library.  It provides predicates for learning a
ranker from pairwise preferences, using it to order candidate items, and
exporting it as a list of predicate clauses or to a file.

Datasets are represented as objects implementing the
‘pairwise_ranking_dataset_protocol’ protocol from the
‘ranking_protocols’ library.  See the ‘test_datasets’ directory for
examples.  The current implementation requires a well-formed connected
pairwise dataset so that all learned utilities remain comparable across
the ranked items.

* Menu:

* API documentation: API documentation<247>.
* Loading: Loading<251>.
* Testing: Testing<242>.
* Features: Features<77>.
* Scoring semantics: Scoring semantics<8>.
* Options: Options<74>.
* Diagnostics syntax: Diagnostics syntax<26>.
* Ranker representation: Ranker representation<17>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<247>,  Next: Loading<251>,  Up: thurstone_mosteller_ranker

6.231.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#thurstone_mosteller_ranker’ link
in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<251>,  Next: Testing<242>,  Prev: API documentation<247>,  Up: thurstone_mosteller_ranker

6.231.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(thurstone_mosteller_ranker(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<242>,  Next: Features<77>,  Prev: Loading<251>,  Up: thurstone_mosteller_ranker

6.231.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(thurstone_mosteller_ranker(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<77>,  Next: Scoring semantics<8>,  Prev: Testing<242>,  Up: thurstone_mosteller_ranker

6.231.4 Features
----------------

   - 'Pairwise Preference Learning': Learns one deterministic latent
     utility per item from aggregated pairwise outcomes.

   - 'Case V Thurstone-Mosteller Fit': Uses continuity-corrected matchup
     win probabilities transformed by the inverse standard normal CDF
     and fitted with a deterministic weighted least-squares solve.

   - 'Centered Utility Scale': Learned scores are centered so that only
     utility differences encode preference strength while the absolute
     location remains arbitrary.

   - 'Deterministic Ranking': Orders candidate items by learned utility
     with deterministic tie-breaking.

   - 'Strict Dataset Validation': Rejects duplicate items, undeclared
     items, self-preferences, non-positive weights, and disconnected
     comparison graphs.

   - 'Training Diagnostics': Learned rankers include metadata describing
     the fitting method, continuity correction, and validated dataset
     summary.

   - 'Ranker Export': Learned rankers can be exported as self-contained
     terms.


File: TheLogtalkHandbook-3.101.0.info,  Node: Scoring semantics<8>,  Next: Options<74>,  Prev: Features<77>,  Up: thurstone_mosteller_ranker

6.231.5 Scoring semantics
-------------------------

This implementation aggregates pairwise preferences into matchup totals
and then estimates latent utilities under the Thurstone-Mosteller Case V
model.  For each observed unordered pair, it computes a
continuity-corrected empirical win probability

     (wins + 0.5) / (total + 1.0)

maps that probability through the inverse standard normal CDF, and fits
utility differences using weighted least squares with matchup totals as
the weights.

The resulting utilities are centered, real-valued scores on an arbitrary
additive scale.  Only differences between utilities are meaningful when
interpreting implied paired-comparison probabilities and ranking order.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<74>,  Next: Diagnostics syntax<26>,  Prev: Scoring semantics<8>,  Up: thurstone_mosteller_ranker

6.231.6 Options
---------------

The current ‘learn/3’ implementation does not define any user options
beyond the default empty list.  Non-empty options lists are rejected.


File: TheLogtalkHandbook-3.101.0.info,  Node: Diagnostics syntax<26>,  Next: Ranker representation<17>,  Prev: Options<74>,  Up: thurstone_mosteller_ranker

6.231.7 Diagnostics syntax
--------------------------

The ‘diagnostics/2’ predicate returns a list of metadata terms with the
form:

     [
         model(thurstone_mosteller_ranker),
         options(Options),
         fitting(weighted_least_squares_case_v),
         continuity_correction(0.5),
         dataset_summary(DatasetSummary)
     ]


File: TheLogtalkHandbook-3.101.0.info,  Node: Ranker representation<17>,  Prev: Diagnostics syntax<26>,  Up: thurstone_mosteller_ranker

6.231.8 Ranker representation
-----------------------------

The learned ranker is represented by a compound term of the form:

     thurstone_mosteller_ranker(Items, Scores, Diagnostics)

Where:

   - ‘Items’: List of ranked items.

   - ‘Scores’: List of ‘Item-Score’ pairs.

   - ‘Diagnostics’: List of metadata terms, including the fitting
     method, continuity correction, and dataset summary.


File: TheLogtalkHandbook-3.101.0.info,  Node: time_scales,  Next: timeout,  Prev: thurstone_mosteller_ranker,  Up: Libraries

6.232 ‘time_scales’
===================

The ‘time_scales’ library provides predicates for converting instants
between UTC, TAI, TT, UT1, TDB, GPS, GST, TCG, and TCB using bundled
reference data and optional user-provided override files.

The library is designed to complement (not replace) the ‘dates’ and
‘iso8601’ libraries:

   - Use ‘dates’ for civil date-time arithmetic and Unix epoch
     conversions.

   - Use ‘iso8601’ for string parsing and formatting.

   - Use ‘time_scales’ for physical time-scale conversions.

* Menu:

* API documentation: API documentation<248>.
* Loading: Loading<252>.
* Testing: Testing<243>.
* Features: Features<78>.
* Limitations: Limitations<5>.
* Representation: Representation<18>.
* Examples: Examples<176>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<248>,  Next: Loading<252>,  Up: time_scales

6.232.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#time_scales’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<252>,  Next: Testing<243>,  Prev: API documentation<248>,  Up: time_scales

6.232.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(time_scales(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<243>,  Next: Features<78>,  Prev: Loading<252>,  Up: time_scales

6.232.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(time_scales(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<78>,  Next: Limitations<5>,  Prev: Testing<243>,  Up: time_scales

6.232.4 Features
----------------

Current feature set:

   - Supported scales: ‘utc’, ‘tai’, ‘tt’, ‘ut1’, ‘tdb’, ‘gps’, ‘gst’,
     ‘tcg’, and ‘tcb’.

   - UTC support starts at ‘1972-01-01T00:00:00Z’.

   - Leap seconds are provided by a bundled static table with optional
     override file.

   - DUT1 (‘UT1-UTC’) is provided by bundled data with optional override
     file.

   - Active leap-second and DUT1 tables can be queried as ordered term
     lists for reproducibility.

   - Active leap-second and DUT1 tables can be saved to deterministic
     term files and reloaded as overrides.

   - Fail- and error-based validation predicates for validating and
     type-checking instant terms and conversion requests.

   - TDB conversions use a practical TT/TDB approximation suitable for
     application-level use.

   - Real-valued approximation offsets converted to rationals using
     high-resolution nanosecond scaling.


File: TheLogtalkHandbook-3.101.0.info,  Node: Limitations<5>,  Next: Representation<18>,  Prev: Features<78>,  Up: time_scales

6.232.5 Limitations
-------------------

Current non-implemented features:

   - UTC coverage before 1972-01-01T00:00:00Z is not implemented.

   - network-driven leap-second and DUT1 data updates are not
     implemented.

   - high-precision ephemeris-based relativistic modeling (beyond the
     current practical approximation formulas) is not implemented.

For full functionality (including all high-precision conversion paths
and their corresponding tests), a Prolog backend with support for
unbounded integer arithmetic is required.


File: TheLogtalkHandbook-3.101.0.info,  Node: Representation<18>,  Next: Examples<176>,  Prev: Limitations<5>,  Up: time_scales

6.232.6 Representation
----------------------

Instants are represented as:

     instant(Scale, Seconds, fraction(Numerator, Denominator))

Where:

   - ‘Scale’ is one of ‘utc’, ‘tai’, ‘tt’, ‘ut1’, ‘tdb’, ‘gps’, ‘gst’,
     ‘tcg’, or ‘tcb’;

   - ‘Seconds’ is integer epoch seconds;

   - ‘fraction(Numerator, Denominator)’ is a normalized fraction in the
     ‘[0,1[’ interval.

Offsets are returned as:

     rational(Numerator, Denominator)


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<176>,  Prev: Representation<18>,  Up: time_scales

6.232.7 Examples
----------------

Convert UTC to TAI:

     | ?- time_scales::convert(instant(utc, 1483228800, fraction(0,1)), utc, tai, TAI).

Strictly validate an instant term (throws on invalid input):

     | ?- time_scales::check_instant(instant(utc, 1483228800, fraction(0,1))).

Strict conversion (throws on invalid scale or mismatched instant scale):

     | ?- time_scales::check_convert(instant(utc, 1483228800, fraction(0,1)), utc, tai, TAI).

Convert TAI to TT:

     | ?- time_scales::convert(instant(tai, 1483228837, fraction(0,1)), tai, tt, TT).

Convert UTC to UT1:

     | ?- time_scales::convert(instant(utc, 1483228800, fraction(0,1)), utc, ut1, UT1).

Convert TT to TDB:

     | ?- time_scales::convert(instant(tt, 1483228869, fraction(0,1)), tt, tdb, TDB).

Convert UTC to GPS:

     | ?- time_scales::convert(instant(utc, 1483228800, fraction(0,1)), utc, gps, GPS).

Convert UTC to GST:

     | ?- time_scales::convert(instant(utc, 1483228800, fraction(0,1)), utc, gst, GST).

Convert UTC to TCG:

     | ?- time_scales::convert(instant(utc, 1483228800, fraction(0,1)), utc, tcg, TCG).

Convert UTC to TCB:

     | ?- time_scales::convert(instant(utc, 1483228800, fraction(0,1)), utc, tcb, TCB).

Lookup an effective leap-second date:

     | ?- time_scales::leap_second_date(Date, Offset).

Load leap-second and DUT1 override files:

     | ?- time_scales::load_leap_seconds_override('test_files/leap_seconds_override.pl').

     | ?- time_scales::load_dut1_override('test_files/dut1_override.pl').

Query active leap-second and DUT1 data tables:

     | ?- time_scales::leap_seconds_entries(LeapEntries).

     | ?- time_scales::dut1_entries(DUT1Entries).

Save active leap-second and DUT1 data tables:

     | ?- time_scales::save_leap_seconds_entries('/tmp/logtalk_time_scales_leap_snapshot.pl').

     | ?- time_scales::save_dut1_entries('/tmp/logtalk_time_scales_dut1_snapshot.pl').

Validate an instant or conversion request:

     | ?- time_scales::valid_instant(instant(utc, 1483228800, fraction(0,1))).

     | ?- time_scales::valid_conversion(instant(tai, 1483228837, fraction(0,1)), tai, tdb).


File: TheLogtalkHandbook-3.101.0.info,  Node: timeout,  Next: tle_orbits,  Prev: time_scales,  Up: Libraries

6.233 ‘timeout’
===============

The ‘timeout’ object provides a portable abstraction over calling a goal
deterministically with a time limit as made available in some form by
some of the supported backend Prolog systems (B-Prolog, ECLiPSe, SICStus
Prolog, SWI-Prolog, Trealla Prolog, XSB, XVM, and YAP).

For better performance, compile calls to this library meta-predicates
with the ‘optimize’ flag turned on so that the meta-arguments, i.e.  the
goals that you are timing, are also compiled.

* Menu:

* API documentation: API documentation<249>.
* Loading: Loading<253>.
* Testing: Testing<244>.
* Known issues: Known issues<20>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<249>,  Next: Loading<253>,  Up: timeout

6.233.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#timeout’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<253>,  Next: Testing<244>,  Prev: API documentation<249>,  Up: timeout

6.233.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(timeout(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<244>,  Next: Known issues<20>,  Prev: Loading<253>,  Up: timeout

6.233.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(timeout(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Known issues<20>,  Prev: Testing<244>,  Up: timeout

6.233.4 Known issues
--------------------

Two tests are currently skipped when using the SWI-Prolog backend as
they cannot be interrupted and generate the expected timeout exceptions
due to tests being run from an ‘initialization/1’ directive goal that,
in the SWI-Prolog implementation of this directive, ignores signals.
The test goals do generate the expected timeout exception when not
called from an ‘initialization/1’ directive.


File: TheLogtalkHandbook-3.101.0.info,  Node: tle_orbits,  Next: toml,  Prev: timeout,  Up: Libraries

6.234 ‘tle_orbits’
==================

The ‘tle_orbits’ library parses Two-Line Element (TLE) records and
provides a small set of helpers for portable approximate orbit
propagation and ground-track generation.

The current version defaults to an approximate automatic propagation
mode that dispatches between dedicated near-earth and deep-space
variants.  The near-earth variant applies low-order B* drag damping
together with J2 secular and short-period position corrections.  The
deep-space variant uses its own long-period and resonance-aware
corrections so high-period orbits no longer share the near-earth path.
The two-body Keplerian approximation is also available as an explicit
baseline model for comparison and simple fallback use.  Propagated
states can also be queried together with direct velocity outputs in
inertial, Earth-fixed, or local ENU frames.

* Menu:

* API documentation: API documentation<250>.
* Loading: Loading<254>.
* Testing: Testing<245>.
* Representation: Representation<19>.
* Public API: Public API<4>.
* Examples: Examples<177>.
* Notes: Notes<11>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<250>,  Next: Loading<254>,  Up: tle_orbits

6.234.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#tle_orbits’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<254>,  Next: Testing<245>,  Prev: API documentation<250>,  Up: tle_orbits

6.234.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(tle_orbits(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<245>,  Next: Representation<19>,  Prev: Loading<254>,  Up: tle_orbits

6.234.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(tle_orbits(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Representation<19>,  Next: Public API<4>,  Prev: Testing<245>,  Up: tle_orbits

6.234.4 Representation
----------------------

Parsed TLE records are represented as:

     ```
         tle(
             Name,
             satellite(CatalogNumber, Classification, designator(LaunchYear, LaunchNumber, Piece)),
             epoch_julian_date(EpochJulianDate),
             drag(MeanMotionDot, MeanMotionDdot, BStar),
             orbit(InclinationDegrees, RightAscensionDegrees, Eccentricity,
                 ArgumentOfPerigeeDegrees, MeanAnomalyDegrees, MeanMotionRevolutionsPerDay),
             ephemeris_type(EphemerisType),
             element_set(ElementSetNumber),
             revolution(RevolutionNumber)
         )
     ```

If the optional title line is absent, ‘Name’ is the atom ‘none’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Public API<4>,  Next: Examples<177>,  Prev: Representation<19>,  Up: tle_orbits

6.234.5 Public API
------------------

   - ‘parse/2’ parses one or more TLE records from ‘atom(Atom)’,
     ‘chars(List)’, ‘codes(List)’, ‘stream(Stream)’, or ‘file(Path)’
     sources.

   - ‘parse_lines/4’ parses a single TLE record from an optional name
     and the two fixed-width element lines.

   - ‘propagate/3’ propagates to a default
     ‘geographic(Latitude,Longitude,Height)’ coordinate in WGS84 using
     the default ‘approximate’ model.

   - ‘propagate/4’ supports the frames ‘eci’, ‘ecef’, and ‘wgs84_3d’
     using the default ‘approximate’ model.

   - ‘propagate/5’ additionally allows choosing one of the
     ‘approximate’, ‘approximate_near_earth’, ‘approximate_deep_space’,
     or ‘two_body’ models.

   - ‘propagate_state/4’ returns ‘state(Position,Velocity)’ in a
     requested frame using the default ‘approximate’ model.

   - ‘propagate_state/5’ additionally allows choosing one of the
     ‘approximate’, ‘approximate_near_earth’, ‘approximate_deep_space’,
     or ‘two_body’ models.  Velocity is derived directly from the
     propagated orbital elements in ECI and then analytically
     transformed to ECEF or local ENU when requested.

   - ‘ground_track/5’ samples ‘sample(DateTime,
     geographic(Latitude,Longitude,Height))’ points over a time range
     using a fixed step in seconds and the default ‘approximate’ model.

   - ‘ground_track/6’ additionally allows choosing one of the
     ‘approximate’, ‘approximate_near_earth’, ‘approximate_deep_space’,
     or ‘two_body’ models.

Supported propagation time specifications are:

   - ‘date_time(Year, Month, Day, Hours, Minutes, Seconds)’

   - ‘julian_date(JulianDate)’

   - ‘offset_seconds(SecondsSinceEpoch)’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<177>,  Next: Notes<11>,  Prev: Public API<4>,  Up: tle_orbits

6.234.6 Examples
----------------

Parse one named TLE record:

     | ?- tle_orbits::parse(atom('ISS (ZARYA)\n1 25544U 98067A   24120.51782528  .00012051  00000-0  21940-3 0  9995\n2 25544  51.6393 184.4452 0003580  32.9443 327.1663 15.50957687452123\n'), TLEs).

Propagate to a WGS84 3D geodetic coordinate using the TLE epoch:

     | ?- TLEs = [TLE], tle_orbits::propagate(TLE, offset_seconds(0.0), Coordinate).

Propagate to ECI or ECEF coordinates:

     | ?- tle_orbits::propagate(TLE, offset_seconds(600.0), eci, ECI).
     | ?- tle_orbits::propagate(TLE, offset_seconds(600.0), ecef, ECEF).

Select the propagation model explicitly:

     | ?- tle_orbits::propagate(TLE, offset_seconds(600.0), eci, two_body, ECI).
     | ?- tle_orbits::propagate(TLE, offset_seconds(600.0), eci, approximate_near_earth, ECI).
     | ?- tle_orbits::propagate(TLE, offset_seconds(600.0), eci, approximate, ECI).
     | ?- tle_orbits::propagate(TLE, offset_seconds(43200.0), eci, approximate_deep_space, ECI).

Request propagated state plus velocity:

     | ?- tle_orbits::propagate_state(TLE, offset_seconds(600.0), eci, State).
     | ?- tle_orbits::propagate_state(TLE, offset_seconds(600.0), wgs84_3d, approximate, State).

Generate a ground track sampled every 10 minutes:

     | ?- tle_orbits::ground_track(
         TLE,
         date_time(2024, 4, 29, 12, 25, 40.0),
         date_time(2024, 4, 29, 13, 25, 40.0),
         600.0,
         Samples
     ).


File: TheLogtalkHandbook-3.101.0.info,  Node: Notes<11>,  Prev: Examples<177>,  Up: tle_orbits

6.234.7 Notes
-------------

   - Parsing validates the TLE checksums and rejects malformed records.

   - The ‘approximate’ family includes low-order B* drag handling,
     near-earth short-period corrections, and a separate deep-space
     approximation with independent solar, lunar, and resonance-aware
     perturbation terms.  It is a portable approximation, not an
     implementation of standards-grade SGP4/SDP4.

   - State velocity output is no longer estimated using centered finite
     differences.  The library now computes ECI velocity directly from
     the propagated orbital elements and transforms that velocity
     analytically to ECEF and local ENU.

   - Position and velocity frame conversion now share the same
     Earth-rotation basis to keep propagated state components internally
     consistent across frames.

   - The geodetic output path reuses the ‘crs_projections’ library for
     converting propagated ‘ecef(X,Y,Z)’ coordinates to ‘geographic/3’
     coordinates.


File: TheLogtalkHandbook-3.101.0.info,  Node: toml,  Next: toon,  Prev: tle_orbits,  Up: Libraries

6.235 ‘toml’
============

The ‘toml’ library provides predicates for parsing and generating data
in the TOML format:

‘https://toml.io’

It includes parametric objects whose parameters allow selecting the
representation for parsed TOML tables (‘compound’ or ‘curly’), TOML text
strings (‘atom’, ‘chars’, or ‘codes’) and TOML pairs (‘dash’, ‘equal’,
or ‘colon’).

* Menu:

* API documentation: API documentation<251>.
* Loading: Loading<255>.
* Testing: Testing<246>.
* Status::
* Representation: Representation<20>.
* Examples: Examples<178>.
* Notes: Notes<12>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<251>,  Next: Loading<255>,  Up: toml

6.235.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#toml’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<255>,  Next: Testing<246>,  Prev: API documentation<251>,  Up: toml

6.235.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(toml(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<246>,  Next: Status,  Prev: Loading<255>,  Up: toml

6.235.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(toml(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Status,  Next: Representation<20>,  Prev: Testing<246>,  Up: toml

6.235.4 Status
--------------

The full TOML 1.0.0 data model is covered:

   - key/value assignments

   - standard tables using ‘[table]’ headers

   - dotted keys

   - arrays

   - inline tables

   - array-of-tables

   - booleans

   - decimal, hexadecimal, octal, and binary integers

   - decimal floats plus ‘inf’ and ‘nan’

   - single-line and multiline basic and literal strings

   - local dates, local times, local date-times, and offset date-times

   - parsing and generation from files, streams, chars, codes, and atoms


File: TheLogtalkHandbook-3.101.0.info,  Node: Representation<20>,  Next: Examples<178>,  Prev: Status,  Up: toml

6.235.5 Representation
----------------------

The following choices of syntax have been made to represent TOML
elements as terms:

   - By default, TOML tables are represented using the compound term
     ‘toml(Pairs)’, where ‘Pairs’ is a list using the selected pair
     representation.

   - Alternatively, TOML tables can be represented using curly-bracketed
     terms, ‘{Pairs}’, where ‘Pairs’ uses the selected pair
     representation.

   - Arrays are represented using lists.

   - Text strings can be represented as atoms, ‘chars(List)’, or
     ‘codes(List)’.  The default when decoding is to use atoms when
     using the ‘toml’ object.  To decode text strings into lists of
     chars or codes, use the ‘toml/1’ object with the parameter bound to
     ‘chars’ or ‘codes’.

   - TOML booleans are represented by ‘@true’ and ‘@false’.

   - TOML special floats are represented by ‘@(inf)’, ‘@(-inf)’, and
     ‘@(nan)’.

Examples using the default ‘toml’ object:

TOML                             term
                                 
--------------------------------------------------------------------------
‘title = "Example"’              ‘toml([title-'Example'])’
                                 
‘point = {x = 1, y = 2}’         ‘toml([point-toml([x-1, y-2])])’
                                 
‘[owner]’ ‘name = "Tom"’         ‘toml([owner-toml([name-'Tom'])])’
                                 
‘enabled = true’                 ‘toml([enabled-@true])’
                                 
‘limits = [1, 2, 3]’             ‘toml([limits-[1,2,3]])’
                                 


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<178>,  Next: Notes<12>,  Prev: Representation<20>,  Up: toml

6.235.6 Examples
----------------

* Menu:

* Parsing a TOML String::
* Parsing with Curly Table Representation::
* Generating TOML::


File: TheLogtalkHandbook-3.101.0.info,  Node: Parsing a TOML String,  Next: Parsing with Curly Table Representation,  Up: Examples<178>

6.235.6.1 Parsing a TOML String
...............................

     |?- toml::parse(atom('title = "Example"\n[owner]\nname = "Tom"\n'), TOML).
     TOML = toml([title-'Example', owner-toml([name-'Tom'])]).


File: TheLogtalkHandbook-3.101.0.info,  Node: Parsing with Curly Table Representation,  Next: Generating TOML,  Prev: Parsing a TOML String,  Up: Examples<178>

6.235.6.2 Parsing with Curly Table Representation
.................................................

     | ?- toml(curly,dash,atom)::parse(atom('title = "Example"\n[owner]\nname = "Tom"\n'), TOML).
     TOML = {title-'Example', owner-{name-'Tom'}}.


File: TheLogtalkHandbook-3.101.0.info,  Node: Generating TOML,  Prev: Parsing with Curly Table Representation,  Up: Examples<178>

6.235.6.3 Generating TOML
.........................

     | ?- toml::generate(atom(Atom), toml([title-'Example', owner-toml([name-'Tom'])])).
     Atom = 'title = "Example"\n\n[owner]\nname = "Tom"\n'.


File: TheLogtalkHandbook-3.101.0.info,  Node: Notes<12>,  Prev: Examples<178>,  Up: toml

6.235.7 Notes
-------------

Generation is canonical and semantic.  The current implementation does
not preserve comments, original quoting style, or whether a table was
originally written as an inline table or a standard table.


File: TheLogtalkHandbook-3.101.0.info,  Node: toon,  Next: truncated_svd_projection,  Prev: toml,  Up: Libraries

6.236 ‘toon’
============

The ‘toon’ library provides predicates for parsing and generating data
in the TOON (Token-Oriented Object Notation) format.  TOON is a compact,
human-readable, line-oriented format that encodes the JSON data model
while minimizing tokens.  For more information on the TOON format, see:

‘https://github.com/toon-format/toon’

* Menu:

* API documentation: API documentation<252>.
* Loading: Loading<256>.
* Testing: Testing<247>.
* Representation: Representation<21>.
* TOON format features::
* Usage examples: Usage examples<3>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<252>,  Next: Loading<256>,  Up: toon

6.236.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#toon’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<256>,  Next: Testing<247>,  Prev: API documentation<252>,  Up: toon

6.236.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(toon(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<247>,  Next: Representation<21>,  Prev: Loading<256>,  Up: toon

6.236.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(toon(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Representation<21>,  Next: TOON format features,  Prev: Testing<247>,  Up: toon

6.236.4 Representation
----------------------

TOON objects are represented using the same conventions as the ‘json’
library.  The representation of TOON objects and TOON pairs can be
controlled using the ‘toon/3’ parametric object.  The three parameters
are:

   - ‘ObjectRepresentation’: ‘curly’ (default) or ‘list’

   - ‘PairRepresentation’: ‘dash’ (default), ‘equal’, or ‘colon’

   - ‘StringRepresentation’: ‘atom’ (default), ‘chars’, or ‘codes’

The ‘toon(StringRepresentation)’ and ‘toon’ objects use the default
representations.

* Menu:

* Objects: Objects<2>.
* Arrays::
* Primitives::


File: TheLogtalkHandbook-3.101.0.info,  Node: Objects<2>,  Next: Arrays,  Up: Representation<21>

6.236.4.1 Objects
.................

TOON objects are represented using curly terms by default:

     {Key1-Value1, Key2-Value2, ...}

Or using lists when using ‘list’ for the ‘ObjectRepresentation’
parameter:

     toon([Key1-Value1, Key2-Value2, ...])


File: TheLogtalkHandbook-3.101.0.info,  Node: Arrays,  Next: Primitives,  Prev: Objects<2>,  Up: Representation<21>

6.236.4.2 Arrays
................

TOON arrays are represented as lists:

     [Element1, Element2, ...]


File: TheLogtalkHandbook-3.101.0.info,  Node: Primitives,  Prev: Arrays,  Up: Representation<21>

6.236.4.3 Primitives
....................

TOON primitive values are represented as follows:

   - Strings: atoms (default), ‘chars(ListOfChars)’, or
     ‘codes(ListOfCodes)’

   - Numbers: Prolog numbers

   - Booleans: ‘@true’ and ‘@false’

   - Null: ‘@null’


File: TheLogtalkHandbook-3.101.0.info,  Node: TOON format features,  Next: Usage examples<3>,  Prev: Representation<21>,  Up: toon

6.236.5 TOON format features
----------------------------

TOON is a line-oriented format with the following key features:

   - Uses indentation (2 spaces) instead of braces for objects

   - Arrays declare their length: ‘[N]:’ for inline or ‘[N]{fields}:’
     for tabular

   - Tabular form for uniform arrays of objects with primitive values

   - Minimal quoting rules for strings

   - Three delimiters: comma (default), tab, and pipe

   - UTF-8 encoding with LF line endings

   - File extension: ‘.toon’, media type: ‘text/toon’


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage examples<3>,  Prev: TOON format features,  Up: toon

6.236.6 Usage examples
----------------------

Parsing TOON from an atom:

     | ?- toon::parse(atom('name: John\nage: 30'), Term).
     Term = {name-'John', age-30}
     yes

Generating TOON to an atom:

     | ?- toon::generate(atom(Atom), {name-'John', age-30}).
     Atom = 'name: John\nage: 30'
     yes

Parsing TOON from a file:

     | ?- toon::parse(file('data.toon'), Term).
     ...

Generating TOON to a file:

     | ?- toon::generate(file('output.toon'), {name-'John', age-30}).
     ...

Using different representations:

     | ?- toon(list, dash, atom)::parse(atom('name: John'), Term).
     Term = toon([name-'John'])
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: truncated_svd_projection,  Next: tsv,  Prev: toon,  Up: Libraries

6.237 ‘truncated_svd_projection’
================================

Truncated singular value decomposition reducer for continuous datasets.
The library implements the ‘dimension_reducer_protocol’ defined in the
‘dimension_reduction_protocols’ library and learns a low-rank linear
projection by building a preprocessed data matrix using optional
centering and scaling, extracting singular triplets using deterministic
two-sided power iteration, and applying rank-one deflation directly to
the data matrix.

* Menu:

* API documentation: API documentation<253>.
* Loading: Loading<257>.
* Testing: Testing<248>.
* Features: Features<79>.
* Options: Options<75>.
* Usage: Usage<106>.
* Dimension reducer representation: Dimension reducer representation<9>.
* References: References<52>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<253>,  Next: Loading<257>,  Up: truncated_svd_projection

6.237.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#truncated_svd_projection’ link
in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<257>,  Next: Testing<248>,  Prev: API documentation<253>,  Up: truncated_svd_projection

6.237.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(truncated_svd_projection(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<248>,  Next: Features<79>,  Prev: Loading<257>,  Up: truncated_svd_projection

6.237.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(truncated_svd_projection(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<79>,  Next: Options<75>,  Prev: Testing<248>,  Up: truncated_svd_projection

6.237.4 Features
----------------

   - 'Continuous Datasets': Accepts datasets containing only continuous
     attributes.  Missing or nonnumeric values are rejected.

   - 'Low-Rank Projection': Extracts right singular vectors and singular
     values in descending order.

   - 'Portable SVD Solver': Uses deterministic two-sided power iteration
     with rank-one deflation over the data matrix instead of
     backend-specific linear algebra libraries.

   - 'Optional Centering and Scaling': Supports explicit control over
     whether training and transform inputs are centered and/or scaled.

   - 'Training Diagnostics': Records per-component convergence reasons,
     iteration counts, and final deltas alongside the learned singular
     values.

   - 'Projection API': Transforms a new instance into a list of
     ‘component_N-Value’ pairs.

   - 'Model Export': Learned reducers can be exported as predicate
     clauses or written to a file.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<75>,  Next: Usage<106>,  Prev: Features<79>,  Up: truncated_svd_projection

6.237.5 Options
---------------

The ‘learn/3’ predicate accepts the following options:

   - ‘n_components/1’: Number of singular vectors to extract.  The
     default is ‘2’.  Requests that exceed the numerical rank after
     shape capping raise ‘domain_error(component_count,
     Requested-Extracted)’ instead of silently returning fewer
     components.

   - ‘center/1’: Whether to center the training and transform inputs
     using the training-set means.  Options: ‘true’ or ‘false’
     (default).

   - ‘feature_scaling/1’: Whether to divide each continuous attribute by
     its training-set standard deviation.  Options: ‘true’ or ‘false’
     (default).

   - ‘maximum_iterations/1’: Maximum number of power-iteration steps
     used when estimating each singular vector.  The default is ‘1000’.

   - ‘tolerance/1’: Positive convergence tolerance used both for
     power-iteration stopping and for deciding when the residual matrix
     no longer supports the requested number of components.  The default
     is ‘1.0e-8’.

The learned diagnostics also include:

   - ‘convergence(Statuses)’: Per-component stop reasons, such as
     ‘tolerance’ or ‘maximum_iterations_exhausted’.

   - ‘iterations(Counts)’: Per-component iteration counts aligned with
     the extracted singular vectors.

   - ‘final_delta(Deltas)’: Per-component final update magnitudes
     aligned with the extracted singular vectors.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<106>,  Next: Dimension reducer representation<9>,  Prev: Options<75>,  Up: truncated_svd_projection

6.237.6 Usage
-------------

The following examples use the sample datasets shipped with the
‘dimension_reduction_protocols’ library:

     | ?- logtalk_load(dimension_reduction_protocols('test_datasets/low_rank_rectangular')).

* Menu:

* Learning a reducer: Learning a reducer<8>.
* Transforming new instances: Transforming new instances<8>.
* Exporting and reusing the reducer: Exporting and reusing the reducer<8>.


File: TheLogtalkHandbook-3.101.0.info,  Node: Learning a reducer<8>,  Next: Transforming new instances<8>,  Up: Usage<106>

6.237.6.1 Learning a reducer
............................

     | ?- truncated_svd_projection::learn(low_rank_rectangular, DimensionReducer).

     | ?- truncated_svd_projection::learn(low_rank_rectangular, DimensionReducer, [n_components(1), center(false), feature_scaling(false), maximum_iterations(200), tolerance(1.0e-7)]).


File: TheLogtalkHandbook-3.101.0.info,  Node: Transforming new instances<8>,  Next: Exporting and reusing the reducer<8>,  Prev: Learning a reducer<8>,  Up: Usage<106>

6.237.6.2 Transforming new instances
....................................

     | ?- truncated_svd_projection::learn(low_rank_rectangular, DimensionReducer),
          truncated_svd_projection::transform(DimensionReducer, [f1-1.0, f2-1.0, f3-2.0], ReducedInstance).


File: TheLogtalkHandbook-3.101.0.info,  Node: Exporting and reusing the reducer<8>,  Prev: Transforming new instances<8>,  Up: Usage<106>

6.237.6.3 Exporting and reusing the reducer
...........................................

     | ?- truncated_svd_projection::learn(low_rank_rectangular, DimensionReducer, [n_components(1)]),
          truncated_svd_projection::export_to_file(low_rank_rectangular, DimensionReducer, reducer, 'truncated_svd_reducer.pl').

     | ?- logtalk_load('truncated_svd_reducer.pl'),
          reducer(Reducer),
          truncated_svd_projection::transform(Reducer, [f1-1.0, f2-1.0, f3-2.0], ReducedInstance).


File: TheLogtalkHandbook-3.101.0.info,  Node: Dimension reducer representation<9>,  Next: References<52>,  Prev: Usage<106>,  Up: truncated_svd_projection

6.237.7 Dimension reducer representation
----------------------------------------

The learned dimension reducer is represented by a compound term with the
functor chosen by the implementation and arity 4.  For example:

     truncated_svd_reducer(Encoders, Components, SingularValues, Diagnostics)

Where:

   - ‘Encoders’: List of continuous attribute encoders storing attribute
     name, centering offset, and scale factor.

   - ‘Components’: List of right singular vectors in descending
     singular-value order.

   - ‘SingularValues’: List of singular values matching the extracted
     components.

   - ‘Diagnostics’: Learned reducer metadata including the effective
     training options, singular values, and per-component convergence
     information.


File: TheLogtalkHandbook-3.101.0.info,  Node: References<52>,  Prev: Dimension reducer representation<9>,  Up: truncated_svd_projection

6.237.8 References
------------------

  1. Eckart, C. and Young, G. (1936) - “The approximation of one matrix
     by another of lower rank”.


File: TheLogtalkHandbook-3.101.0.info,  Node: tsv,  Next: types,  Prev: truncated_svd_projection,  Up: Libraries

6.238 ‘tsv’
===========

The ‘tsv’ library provides predicates for reading and writing TSV files
and streams:

‘https://www.iana.org/assignments/media-types/text/tab-separated-values’

The main object, ‘tsv/2’, is a parametric object allowing passing two
options: header handling (‘keep’ or ‘skip’) and comment handling
(‘false’ or ‘true’).  When comment handling is ‘true’, lines starting
with the ‘#’ character are skipped when reading files and streams.

The ‘tsv/1’ parametric object is kept for backward compatibility and
extends ‘tsv/2’ by setting the comments option to ‘false’.  The ‘tsv’
object extends the ‘tsv/2’ parametric object using the default options
‘keep’ and ‘false’.

Files and streams can be read into a list of rows (with each row being
represented by a list of fields) or asserted using a user-defined
dynamic predicate.  Reading can be done by first loading the whole file
(using the ‘read_file/2-3’ predicates) into memory or line by line
(using the ‘read_file_by_line/2-3’ predicates).  Reading line by line is
usually the best option for parsing large TSV files.

Data can be saved to a TSV file or stream by providing the object and
predicate for accessing the data plus the name of the destination file
or the stream handle or alias.

* Menu:

* API documentation: API documentation<254>.
* Loading: Loading<258>.
* Testing: Testing<249>.
* Usage: Usage<107>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<254>,  Next: Loading<258>,  Up: tsv

6.238.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#tsv’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<258>,  Next: Testing<249>,  Prev: API documentation<254>,  Up: tsv

6.238.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(tsv(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<249>,  Next: Usage<107>,  Prev: Loading<258>,  Up: tsv

6.238.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(tsv(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<107>,  Prev: Testing<249>,  Up: tsv

6.238.4 Usage
-------------

A TSV file can be read as a list of rows:

     | ?- tsv::read_file('test_files/data.tsv', Rows).

     Rows = [['Name','Age','Address'], ['Paul',23,'1115 W Franklin'], ['Bessy the Cow',5,'Big Farm Way'], ['Zeke,45,'W Main St']]
     yes

Alternatively, The TSV data can be saved using a public and dynamic
object predicate (that must be previously declared).  For example:

     | ?- assertz(p(_,_,_)), retractall(p(_,_,_)).
     yes

     | ?- tsv(skip)::read_file('test_files/data.tsv', user, p/3).
     yes

     | ?- tsv(skip, true)::read_file('test_files/data_with_comments.tsv', user, p/3).
     yes

     | ?-  p(A,B,C).

     A = 'Paul', B = 23, C = '1115 W Franklin' ? ;
     ...

Given a predicate representing a table, the predicate data can be
written to a file or stream.  For example:

     | ?- tsv::write_file('output.tsv', user, p/3).
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: types,  Next: tzif,  Prev: tsv,  Up: Libraries

6.239 ‘types’
=============

This library implements predicates over standard Prolog term types and
also terms representing common data structures such as lists and pairs.

It also includes a user-extensible ‘type’ object defining type checking
predicates over common Logtalk and Prolog term types.  The types define
a hierarchy with the Prolog type ‘term’ at the root (i.e., type-checking
a predicate argument of type ‘term’ trivially succeeds).  Some types are
only meaningful for backend Prolog systems supporting non-universal
features (e.g., ‘cyclic’ or ‘char(CharSet)’ with a Unicode character
set).  See the API documentation for a full list of the types defined by
default.

* Menu:

* API documentation: API documentation<255>.
* Loading: Loading<259>.
* Testing: Testing<250>.
* Type-checking: Type-checking<2>.
* Defining new types::
* Examples: Examples<179>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<255>,  Next: Loading<259>,  Up: types

6.239.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#types’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<259>,  Next: Testing<250>,  Prev: API documentation<255>,  Up: types

6.239.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(types(loader)).

If your code only requires the most basic types, you can load in
alternative the file:

     | ?- logtalk_load(basic_types(loader)).

See the notes on the ‘basic_types’ virtual library for details.


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<250>,  Next: Type-checking<2>,  Prev: Loading<259>,  Up: types

6.239.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(types(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Type-checking<2>,  Next: Defining new types,  Prev: Testing<250>,  Up: types

6.239.4 Type-checking
---------------------

This library ‘type’ object can be used to type-check common Logtalk and
Prolog term types (see the object documentation for a listing of all the
pre-defined types).  The ‘valid/2’ predicate succeeds or fails if a term
is of a given type.  For example:

     | ?- type::valid(positive_integer, 42).
     yes

     | ?- type::valid(positive_integer, -13).
     no

The ‘check/2’ and ‘check/3’ predicates throw an exception if a term is
not of a given type.  For example:

     | ?- catch(type::check(integer, abc), Error, true).
     Error = type_error(integer, abc)
     yes

If we require a standard ‘error/2’ exception term, the ‘check/3’
predicate takes a 'context' argument.  For example:

     | ?- catch(type::check(integer, abc, foo/3), Error, true).
     Error = error(type_error(integer, abc), foo/3)
     yes

Typically, the context is provided by calling the built-in ‘context/1’
method.


File: TheLogtalkHandbook-3.101.0.info,  Node: Defining new types,  Next: Examples<179>,  Prev: Type-checking<2>,  Up: types

6.239.5 Defining new types
--------------------------

To define a custom type, define clauses for the multifile predicates
‘type::type/1’ (to declare the type) and ‘type::check/2’ (to type-check
values).  For example:

     :- multifile(type::type/1).
     type::type(age).

     :- multifile(type::check/2).
     type::check(age, Term) :-
         type::check(between(non_negative_integer, 0, 150), Term).

Be careful to ensure that the new type definitions don’t introduce
spurious choice-points for these predicates.  The unit tests of the
‘types’ library perform this check for pre-defined and loaded
user-defined ground types.

When defining a meta-type (i.e., a type with arguments that are also
types), add also a clause for the ‘type::meta_type/3’ multifile
predicate.  For example:

     :- multifile(type::meta_type/3).
     type::meta_type(tuple(Type1, Type2, Type3), [Type1, Type2, Type3], []).

This predicate is called when checking if a type is a defined type.  For
meta-types, that check must extend to the sub-types.


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<179>,  Prev: Defining new types,  Up: types

6.239.6 Examples
----------------

See e.g.  the ‘os’ library implementation of custom types for files and
directories.  Or the ‘expecteds’ and ‘optionals’ libraries custom types.
See also the ‘my_types’ programming example.


File: TheLogtalkHandbook-3.101.0.info,  Node: tzif,  Next: ulid,  Prev: types,  Up: Libraries

6.240 ‘tzif’
============

The ‘tzif’ library loads TZif v1, v2, and v3 files from the IANA time
zone database into inspectable terms and answers UTC-based lookup
queries over one or more zones.

'Requires a backend Prolog compiler with unbounded integer arithmetic.'

Current feature set:

   - Loads sources given as ‘file(Path, ZoneId)’, ‘files(Root, Paths)’,
     ‘directory(Root)’, ‘stream(Stream, ZoneId)’, ‘bytes(Bytes,
     ZoneId)’, or ‘snapshot(File)’ using ‘load/1’ or ‘load/2’.

   - Supports TZif v1, v2, and v3, including validated skipping of the
     v1 compatibility block in v2/v3 files.

   - Parses POSIX footers, including signed-hour and signed-minute
     offsets.

   - Exposes zone-aware lookup predicates over loaded ‘tzif(...)’ terms,
     plus cached convenience variants for zone and single-zone queries.

   - Exposes strict local civil-time lookup predicates that fail cleanly
     for ambiguous or nonexistent times.

   - Exposes ‘*_with_resolution’ local civil-time query predicates for
     explicit resolution modes (‘strict’, ‘first’, ‘second’, and ‘all’).

   - Exposes ‘*_reified’ local civil-time query predicates that return
     ‘unique(...)’, ‘ambiguous(...)’, or ‘nonexistent’ results.

   - Caches successful ‘load/1’ calls automatically, while ‘load/2’
     returns a loaded term without changing the cache.

   - Provides ‘cache/1’ for making an already loaded ‘tzif(...)’ term
     the active cached term.

   - Saves and reloads ‘tzif(...)’ terms as plain Prolog snapshot files,
     with ‘save/1’ providing a convenience predicate for saving the
     cached term.

   - Returns the source term recorded in the active cached term via
     ‘cache_source/1’.

   - Exposes the active cached term using ‘cached_tzif/1’.

   - Exposes the cached zone list using ‘zones/1’.

   - Accepts UTC queries as Unix seconds or ‘date_time/6’ terms.

   - Validates zone identifiers against bundled IANA TZDB 2026a
     canonical names plus backward-compatible aliases.

* Menu:

* API documentation: API documentation<256>.
* Loading: Loading<260>.
* Testing: Testing<251>.
* Representation: Representation<22>.
* Zone identifier validation::
* Local Queries::
* Examples: Examples<180>.
* Known issues: Known issues<21>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<256>,  Next: Loading<260>,  Up: tzif

6.240.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#tzif’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<260>,  Next: Testing<251>,  Prev: API documentation<256>,  Up: tzif

6.240.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(tzif(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<251>,  Next: Representation<22>,  Prev: Loading<260>,  Up: tzif

6.240.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(tzif(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Representation<22>,  Next: Zone identifier validation,  Prev: Testing<251>,  Up: tzif

6.240.4 Representation
----------------------

Loaded sources are returned by ‘load/2’ as lists of ‘tzif(Zone, Source,
ZoneData)’ terms, one term per loaded zone.

Each nested ‘ZoneData’ term contains the parsed block data, leap-second
records, and parsed footer for a single zone.  These per-zone
‘tzif(...)’ terms are stable enough to be serialized directly using
‘save/2’ and restored using ‘load(snapshot(File), TZifs)’.

For directory and file-set loads, zone identifiers are the relative
paths used to locate the TZif files inside the root directory, and each
loaded term records its own ‘file(File, ZoneId)’ source.

When loading a ‘directory(Root)’, regular files whose relative paths are
not recognized zone identifiers are ignored.  This allows loading system
zoneinfo trees that also contain metadata files such as ‘leapseconds’.

For single-zone file, stream, and byte-list loads, the caller must
provide the zone identifier explicitly using ‘file(Path, ZoneId)’,
‘stream(Stream, ZoneId)’, or ‘bytes(Bytes, ZoneId)’.

The cache stores one ‘tzif(...)’ term per zone id.  ‘load/1’ and
‘cache/1’ replace only cached entries whose zone ids match the newly
loaded terms.


File: TheLogtalkHandbook-3.101.0.info,  Node: Zone identifier validation,  Next: Local Queries,  Prev: Representation<22>,  Up: tzif

6.240.5 Zone identifier validation
----------------------------------

The library validates zone identifiers using bundled data derived from
the official IANA TZDB 2026a release.  Accepted identifiers include both
canonical zone names such as ‘America/New_York’ and backward-compatible
aliases such as ‘US/Eastern’.

The bundled data is generated from the IANA ‘zone1970.tab’ and
‘backward’ files and does not consult the host operating system’s
installed zoneinfo tree.

To refresh the bundled table for a newer IANA release, run:

     $ ./update_zone_ids.sh 2026a


File: TheLogtalkHandbook-3.101.0.info,  Node: Local Queries,  Next: Examples<180>,  Prev: Zone identifier validation,  Up: tzif

6.240.6 Local Queries
---------------------

The library provides three sets of predicates for local civil-time
queries.

Strict predicates:

   - ‘local_time_type/2-4’

   - ‘local_offset/2-4’

   - ‘local_daylight_saving_time/2-4’

   - ‘local_abbreviation/2-4’

These predicates are intended for local civil times with a unique
interpretation.  They fail for ambiguous fold times and nonexistent gap
times.

Explicit-resolution predicates:

   - ‘local_time_type_with_resolution/3-5’

   - ‘local_offset_with_resolution/3-5’

   - ‘local_daylight_saving_time_with_resolution/3-5’

   - ‘local_abbreviation_with_resolution/3-5’

These predicates accept an explicit resolution mode argument.  Supported
modes are ‘strict’, ‘first’, ‘second’, and ‘all’.

   - ‘strict’: succeed only when the local civil time has a unique
     interpretation

   - ‘first’: select the earliest valid interpretation

   - ‘second’: select the latest valid interpretation

   - ‘all’: enumerate all valid interpretations in chronological order

Reified predicates:

   - ‘local_time_type_reified/2-4’

   - ‘local_offset_reified/2-4’

   - ‘local_daylight_saving_time_reified/2-4’

   - ‘local_abbreviation_reified/2-4’

These predicates never use failure to distinguish ambiguity from
absence.  Instead, they return one of the following results:

   - ‘unique(...)’

   - ‘ambiguous(...)’

   - ‘nonexistent’


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<180>,  Next: Known issues<21>,  Prev: Local Queries,  Up: tzif

6.240.7 Examples
----------------

Load a single TZif payload without caching it:

     | ?- tzif::load(bytes(Bytes, 'America/New_York'), TZifs).

Cache an already loaded term explicitly:

     | ?- tzif::load(bytes(Bytes, 'America/New_York'), TZifs), tzif::cache(TZifs).

Load a directory tree of TZif files:

     | ?- tzif::load(directory('/usr/share/zoneinfo'), TZifs).

Query a specific zone in a loaded term:

     | ?- tzif::load(bytes(Bytes, 'America/New_York'), [TZif]).
     | ?- tzif::offset(TZif, 'America/New_York', date_time(2024, 7, 1, 12, 0, 0), Offset).

Query a specific zone in the cached term:

     | ?- tzif::load(directory('/usr/share/zoneinfo')).
     | ?- tzif::offset('America/New_York', date_time(2024, 7, 1, 12, 0, 0), Offset).

Persist and reload a snapshot:

     | ?- tzif::save(TZifs, 'snapshot.pl').
     | ?- tzif::load(snapshot('snapshot.pl'), ReloadedTZifs).

Save the cached terms directly:

     | ?- tzif::load(directory('/usr/share/zoneinfo')).
     | ?- tzif::save('snapshot.pl').

Load using a backward-compatible alias:

     | ?- tzif::load(bytes(Bytes, 'US/Eastern'), TZifs).

Use the automatic cache populated by ‘load/1’:

     | ?- tzif::load(snapshot('snapshot.pl')).
     | ?- tzif::abbreviation(date_time(2024, 7, 1, 12, 0, 0), Abbreviation).

Resolve an ambiguous local civil time explicitly:

     | ?- tzif::local_offset_with_resolution('America/New_York', date_time(2024, 11, 3, 1, 30, 0), first, Offset).

Inspect whether a local civil time is unique, ambiguous, or nonexistent:

     | ?- tzif::local_time_type_reified('America/New_York', date_time(2024, 11, 3, 1, 30, 0), Result).

List cached zones directly:

     | ?- tzif::load(directory('/usr/share/zoneinfo')).
     | ?- tzif::zones(Zones).


File: TheLogtalkHandbook-3.101.0.info,  Node: Known issues<21>,  Prev: Examples<180>,  Up: tzif

6.240.8 Known issues
--------------------

Some tests may fail on Windows depending on the backend.  When using
SICStus Prolog, test failures result from file name case-normalization
by this system file and directory library predicates.  When using
SWI-Prolog, the same issues with file name case-normalization are fixed
in version 10.1.12.


File: TheLogtalkHandbook-3.101.0.info,  Node: ulid,  Next: unicode_data,  Prev: tzif,  Up: Libraries

6.241 ‘ulid’
============

This library implements a Universally Unique Lexicographically Sortable
Identifier (ULID) generator.

‘https://github.com/ulid/spec’

Note that most backends provide time stamps with lower granularity than
required (i.e., seconds but not milliseconds).  Also note that, per
spec, within the same millisecond, monotonic sort order is not
guaranteed.

The generation of ULIDs uses the ‘/dev/urandom’ random number generator
when available.  This includes macOS, Linux, *BSD, and other POSIX
operating-systems.  On Windows, a pseudo-random generator is used, but
randomized using the current wall time.

ULIDs can be generated as atoms, lists of characters, or lists of
character codes.

See also the ‘cuid2’, ‘ids’, ‘ksuid’, ‘snowflakeid’, ‘nanoid’, and
‘uuid’ libraries.

* Menu:

* API documentation: API documentation<257>.
* Loading: Loading<261>.
* Testing: Testing<252>.
* Generating ULIDs::
* Type-checking ULIDs::


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<257>,  Next: Loading<261>,  Up: ulid

6.241.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#ulid’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<261>,  Next: Testing<252>,  Prev: API documentation<257>,  Up: ulid

6.241.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(ulid(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<252>,  Next: Generating ULIDs,  Prev: Loading<261>,  Up: ulid

6.241.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(ulid(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Generating ULIDs,  Next: Type-checking ULIDs,  Prev: Testing<252>,  Up: ulid

6.241.4 Generating ULIDs
------------------------

By default, ULIDs are generated as atoms.  For example:

     | ?- ulid::generate(ULID).
     ULID = '01H0J31SYQXHJZWPRAKHQ6YVYH'
     yes

To generate a ULID using a list of characters representation, use
instead the ‘ulid/1’ parametric object:

     | ?- ulid(chars)::generate(ULID).
     ULID = ['0','1','H','0','J','3','2','Y','V','5','V','S','P','K','5','P','4','5','G','G','0','9','8','8','M','2']
     yes

Similarly, to get a ULID using a list of character codes representation:

     | ?- ulid(codes)::generate(ULID).
     ULID = [48,49,72,48,74,51,52,66,54,48,55,57,54,49,67,82,70,65,67,51,67,67,86,82,48,66]
     yes

It’s also possible to generate ULIDs from a given timestamp, i.e.  the
number of milliseconds since the Unix epoch (00:00:00 UTC on January 1,
1970), using the ‘generate/2’ predicate.  The timestamp must be an
integer.  For example, assuming a backend Prolog system providing a
‘time_stamp/1’ predicate returning the Unix epoch in milliseconds:

     | ?- time_stamp(Milliseconds), ulid(atom)::generate(Seconds, ULID).
     Seconds = 1684245175344, ULID = '01H0JDBQ1GAWJF35C44Y5S97DX'
     yes

You can also use timestamp discrete components using the ‘generate/8’
predicate.  For example:

     | ?- ulid(atom)::generate(2023, 5, 17, 16, 23, 38, 591, ULID).
     ULID = '01H0N8CDAZK75C5H3BJSGS4VCQ'
     yes

To extract the timestamp from a given ULID, use the ‘timestamp/2’ and
‘timestamp/8’ predicates.  For example:

     | ?- ulid(atom)::timestamp('01H0JDBQ1GAWJF35C44Y5S97DX', Milliseconds).
     Milliseconds = 1684245175344
     yes

     | ?- ulid(atom)::timestamp('01H0N8CDAZK75C5H3BJSGS4VCQ', Year, Month, Day, Hours, Minutes, Seconds, Milliseconds).
     Year = 2023, Month = 5, Day = 17, Hours = 16, Minutes = 23, Seconds = 38, Milliseconds = 591
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: Type-checking ULIDs,  Prev: Generating ULIDs,  Up: ulid

6.241.5 Type-checking ULIDs
---------------------------

This library also defines a ‘ulid(Representation)’ type for
type-checking ULIDs.  For example, with an atom containing invalid
characters:

     | ?- type::check(ulid(atom), '01BX5ZIKBKALTAV9OEVGEMMVRY').
     uncaught exception: domain_error(ulid,'01BX5ZIKBKALTAV9OEVGEMMVRY')


File: TheLogtalkHandbook-3.101.0.info,  Node: unicode_data,  Next: union_find,  Prev: ulid,  Up: Libraries

6.242 ‘unicode_data’
====================

VivoMind Prolog Unicode Resources

* Menu:

* Authors::
* License::
* Website::
* Description: Description<165>.
* Requirements: Requirements<8>.
* Usage: Usage<108>.
* Known issues: Known issues<22>.
* Acknowledgements::
* Files and API Summary::


File: TheLogtalkHandbook-3.101.0.info,  Node: Authors,  Next: License,  Up: unicode_data

6.242.1 Authors
---------------

     Arun Majumdar @ VivoMind LLC
     Paulo Moura @ VivoMind LLC


File: TheLogtalkHandbook-3.101.0.info,  Node: License,  Next: Website,  Prev: Authors,  Up: unicode_data

6.242.2 License
---------------

Creative Commons CC0 1.0 Universal (CC0 1.0) - Public Domain Dedication:

     https://creativecommons.org/publicdomain/zero/1.0/

We do appreciate acknowledgment if you use these resources, however, and
we also welcome contributions to improve them.


File: TheLogtalkHandbook-3.101.0.info,  Node: Website,  Next: Description<165>,  Prev: License,  Up: unicode_data

6.242.3 Website
---------------

The latest release of the VivoMind Prolog Unicode Resources is available
at the URL:

     https://github.com/VivoMind

At this address you can also find additional information about the
VivoMind Prolog Unicode Resources and submit your bug reports and
contributions.


File: TheLogtalkHandbook-3.101.0.info,  Node: Description<165>,  Next: Requirements<8>,  Prev: Website,  Up: unicode_data

6.242.4 Description
-------------------

The VivoMind Prolog Unicode Resources are a set of files resulting from
the conversion of most (but not all) official UCD 6.1 files and updated
for the few changes in the 6.2 standard.  The original files can be
downloaded from:

     http://www.unicode.org

The conversion of the UCD files resulted in a large number of Prolog
tables and also a set of auxiliary predicates (described below) for
accessing these tables.  Other than the obvious conversion in the
provided predicate names, no attempt was made to convert the identifiers
used for properties and other data.


File: TheLogtalkHandbook-3.101.0.info,  Node: Requirements<8>,  Next: Usage<108>,  Prev: Description<165>,  Up: unicode_data

6.242.5 Requirements
--------------------

Most of the auxiliary predicates assume that the de facto Prolog
standard predicate ‘between/3’ is available.  Unicode code point values
are represented using the ISO Prolog standard notation for hexadecimal
integers.  In addition, the ISO Prolog standard directives ‘include/1’
and ‘ensure_loaded/1’ are used in some of the files to load auxiliary
files.


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<108>,  Next: Known issues<22>,  Prev: Requirements<8>,  Up: unicode_data

6.242.6 Usage
-------------

Most applications only require some of the tables present in these
resources.  Most of these tables define properties for ranges of code
points and not for single code points, but the provided auxiliary
predicates allow access for a single code point.  When increased
performance is required, consider using the existing tables and
auxiliary predicates to generate derived tables more fit for your
specific application.


File: TheLogtalkHandbook-3.101.0.info,  Node: Known issues<22>,  Next: Acknowledgements,  Prev: Usage<108>,  Up: unicode_data

6.242.7 Known issues
--------------------

In the file ‘unicode_unihan_variant.pl’, when there’s more than one
variant for a code point, only the first one (as listed in the original
UCD file) is returned.

The ‘include/1’ and ‘ensure_loaded/1’ directives are specified in the
ISO Prolog standard published in 1995.  But some Prolog compilers either
don’t implement one or both directives or have flawed implementations.
Thus, you may need to change how some of the files are loaded depending
on the chosen Prolog compiler.  Using conditional compilation directives
would help in some cases, but it would also raise portability issues on
its own.


File: TheLogtalkHandbook-3.101.0.info,  Node: Acknowledgements,  Next: Files and API Summary,  Prev: Known issues<22>,  Up: unicode_data

6.242.8 Acknowledgements
------------------------

We thank Richard O’Keefe for helpful suggestions to improve the
usability of these resources.


File: TheLogtalkHandbook-3.101.0.info,  Node: Files and API Summary,  Prev: Acknowledgements,  Up: unicode_data

6.242.9 Files and API Summary
-----------------------------

The Prolog file names are derived from the original file names by
prefixing them with the ‘unicode_’ string, converting to lower case, and
replacing the camel case spelling with underscores.  There are, however,
two exceptions: the files and directories holding the code point
categories and names.

There’s also a utility file, ‘unicode_data.pl’, that can be used to load
all the files in these resources.  It is mostly used to test the
portability of the code across Prolog compilers.  Also included is a
Logtalk version of this file, ‘unicode_data.lgt’, which uses Logtalk’s
own implementation of the ‘include/1’ directive and the ‘logtak_load/1’
predicate to load all files.  This file can be used to workaround Prolog
systems with buggy or missing implementations of the ‘ensure_loaded/1’
and ‘include/1’ directives.

An overview of the original file names and the code point properties can
be found at:

     http://www.unicode.org/reports/tr44/#Directory_Structure

     http://www.unicode.org/reports/tr44/#Property_Definitions

* Menu:

* unicode_arabic_shaping.pl: unicode_arabic_shaping pl.
* unicode_bidi_mirroring.pl: unicode_bidi_mirroring pl.
* unicode_blocks.pl: unicode_blocks pl.
* unicode_case_folding.pl: unicode_case_folding pl.
* unicode_categories.pl: unicode_categories pl.
* unicode_cjk_radicals.pl: unicode_cjk_radicals pl.
* unicode_composition_exclusions.pl: unicode_composition_exclusions pl.
* unicode_core_properties.pl: unicode_core_properties pl.
* unicode_decomposition_type.pl: unicode_decomposition_type pl.
* unicode_derived_age.pl: unicode_derived_age pl.
* unicode_derived_bidi_class.pl: unicode_derived_bidi_class pl.
* unicode_derived_combining_class.pl: unicode_derived_combining_class pl.
* unicode_derived_core_properties.pl: unicode_derived_core_properties pl.
* unicode_derived_decomposition_type.pl: unicode_derived_decomposition_type pl.
* unicode_derived_east_asian_width.pl: unicode_derived_east_asian_width pl.
* unicode_derived_joining_group.pl: unicode_derived_joining_group pl.
* unicode_derived_joining_type.pl: unicode_derived_joining_type pl.
* unicode_derived_line_break.pl: unicode_derived_line_break pl.
* unicode_derived_normalization_props.pl: unicode_derived_normalization_props pl.
* unicode_derived_numeric_type.pl: unicode_derived_numeric_type pl.
* unicode_derived_numeric_values.pl: unicode_derived_numeric_values pl.
* unicode_hangul_syllable_type.pl: unicode_hangul_syllable_type pl.
* unicode_indic_matra_category.pl: unicode_indic_matra_category pl.
* unicode_indic_syllabic_category.pl: unicode_indic_syllabic_category pl.
* unicode_jamo.pl: unicode_jamo pl.
* unicode_name_aliases.pl: unicode_name_aliases pl.
* unicode_names.pl: unicode_names pl.
* unicode_prop_list.pl: unicode_prop_list pl.
* unicode_range_scripts.pl: unicode_range_scripts pl.
* unicode_script_extensions.pl: unicode_script_extensions pl.
* unicode_scripts.pl: unicode_scripts pl.
* unicode_special_casing.pl: unicode_special_casing pl.
* unicode_unihan_variants.pl: unicode_unihan_variants pl.
* unicode_version.pl: unicode_version pl.


File: TheLogtalkHandbook-3.101.0.info,  Node: unicode_arabic_shaping pl,  Next: unicode_bidi_mirroring pl,  Up: Files and API Summary

6.242.9.1 ‘unicode_arabic_shaping.pl’
.....................................

   - Provides: ‘unicode_arabic_shaping/4’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.101.0.info,  Node: unicode_bidi_mirroring pl,  Next: unicode_blocks pl,  Prev: unicode_arabic_shaping pl,  Up: Files and API Summary

6.242.9.2 ‘unicode_bidi_mirroring.pl’
.....................................

   - Provides: ‘unicode_bidi_mirroring/2’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.101.0.info,  Node: unicode_blocks pl,  Next: unicode_case_folding pl,  Prev: unicode_bidi_mirroring pl,  Up: Files and API Summary

6.242.9.3 ‘unicode_blocks.pl’
.............................

   - Provides: ‘unicode_block/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.101.0.info,  Node: unicode_case_folding pl,  Next: unicode_categories pl,  Prev: unicode_blocks pl,  Up: Files and API Summary

6.242.9.4 ‘unicode_case_folding.pl’
...................................

   - Provides: ‘unicode_case_folding/3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.101.0.info,  Node: unicode_categories pl,  Next: unicode_cjk_radicals pl,  Prev: unicode_case_folding pl,  Up: Files and API Summary

6.242.9.5 ‘unicode_categories.pl’
.................................

   - Provides: ‘unicode_category/2’

   - Dependencies: files in the ‘unicode_categories’ directory


File: TheLogtalkHandbook-3.101.0.info,  Node: unicode_cjk_radicals pl,  Next: unicode_composition_exclusions pl,  Prev: unicode_categories pl,  Up: Files and API Summary

6.242.9.6 ‘unicode_cjk_radicals.pl’
...................................

   - Provides: ‘unicode_cjk_radical/3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.101.0.info,  Node: unicode_composition_exclusions pl,  Next: unicode_core_properties pl,  Prev: unicode_cjk_radicals pl,  Up: Files and API Summary

6.242.9.7 ‘unicode_composition_exclusions.pl’
.............................................

   - Provides: ‘unicode_composition_exclusion/1’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.101.0.info,  Node: unicode_core_properties pl,  Next: unicode_decomposition_type pl,  Prev: unicode_composition_exclusions pl,  Up: Files and API Summary

6.242.9.8 ‘unicode_core_properties.pl’
......................................

   - Provides: ‘unicode_math/1-2’ ‘unicode_alphabetic/1-2’
     ‘unicode_range_alphabetic/2’ ‘unicode_lowercase/1-2’
     ‘unicode_uppercase/1-2’ ‘unicode_cased/1-2’
     ‘unicode_case_ignorable/1-2’ ‘unicode_changes_when_lowercased/1-2’
     ‘unicode_changes_when_uppercased/1-2’
     ‘unicode_changes_when_titlecased/1-2’
     ‘unicode_changes_when_casefolded/1-2’
     ‘unicode_changes_when_casemapped/1-2’ ‘unicode_id_start/1-2’
     ‘unicode_id_continue/1-2’ ‘unicode_xid_start/1-2’
     ‘unicode_xid_continue/1-2’ ‘unicode_default_ignorable/1-2’
     ‘unicode_grapheme_extend/1-2’ ‘unicode_grapheme_base/1-2’
     ‘unicode_grapheme_link/1-2’

   - Dependencies: files in the ‘unicode_core_properties’ directory


File: TheLogtalkHandbook-3.101.0.info,  Node: unicode_decomposition_type pl,  Next: unicode_derived_age pl,  Prev: unicode_core_properties pl,  Up: Files and API Summary

6.242.9.9 ‘unicode_decomposition_type.pl’
.........................................

   - Provides: ‘unicode_canonical/1-2’ ‘unicode_compat/1-2’
     ‘unicode_font/1-2’ ‘unicode_nobreak/1-2’ ‘unicode_initial/1-2’
     ‘unicode_medial/1-2’ ‘unicode_final/1-2’ ‘unicode_isolated/1-2’
     ‘unicode_circle/1-2’ ‘unicode_super/1-2’ ‘unicode_sub/1-2’
     ‘unicode_vertical/1-2’ ‘unicode_wide/1-2’ ‘unicode_narrow/1-2’
     ‘unicode_small/1-2’ ‘unicode_square/1-2’ ‘unicode_fraction/1-2’

   - Dependencies: files in the ‘unicode_decomposition_type’ directory


File: TheLogtalkHandbook-3.101.0.info,  Node: unicode_derived_age pl,  Next: unicode_derived_bidi_class pl,  Prev: unicode_decomposition_type pl,  Up: Files and API Summary

6.242.9.10 ‘unicode_derived_age.pl’
...................................

   - Provides: ‘unicode_age/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.101.0.info,  Node: unicode_derived_bidi_class pl,  Next: unicode_derived_combining_class pl,  Prev: unicode_derived_age pl,  Up: Files and API Summary

6.242.9.11 ‘unicode_derived_bidi_class.pl’
..........................................

   - Provides: ‘unicode_bidi_class/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.101.0.info,  Node: unicode_derived_combining_class pl,  Next: unicode_derived_core_properties pl,  Prev: unicode_derived_bidi_class pl,  Up: Files and API Summary

6.242.9.12 ‘unicode_derived_combining_class.pl’
...............................................

   - Provides: ‘unicode_combining_class/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.101.0.info,  Node: unicode_derived_core_properties pl,  Next: unicode_derived_decomposition_type pl,  Prev: unicode_derived_combining_class pl,  Up: Files and API Summary

6.242.9.13 ‘unicode_derived_core_properties.pl’
...............................................

   - Provides: ‘unicode_core_property/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.101.0.info,  Node: unicode_derived_decomposition_type pl,  Next: unicode_derived_east_asian_width pl,  Prev: unicode_derived_core_properties pl,  Up: Files and API Summary

6.242.9.14 ‘unicode_derived_decomposition_type.pl’
..................................................

   - Provides: ‘unicode_decomposition_type/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.101.0.info,  Node: unicode_derived_east_asian_width pl,  Next: unicode_derived_joining_group pl,  Prev: unicode_derived_decomposition_type pl,  Up: Files and API Summary

6.242.9.15 ‘unicode_derived_east_asian_width.pl’
................................................

   - Provides: ‘unicode_east_asian_width/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.101.0.info,  Node: unicode_derived_joining_group pl,  Next: unicode_derived_joining_type pl,  Prev: unicode_derived_east_asian_width pl,  Up: Files and API Summary

6.242.9.16 ‘unicode_derived_joining_group.pl’
.............................................

   - Provides: ‘unicode_joining_group/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.101.0.info,  Node: unicode_derived_joining_type pl,  Next: unicode_derived_line_break pl,  Prev: unicode_derived_joining_group pl,  Up: Files and API Summary

6.242.9.17 ‘unicode_derived_joining_type.pl’
............................................

   - Provides: ‘unicode_joining_type/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.101.0.info,  Node: unicode_derived_line_break pl,  Next: unicode_derived_normalization_props pl,  Prev: unicode_derived_joining_type pl,  Up: Files and API Summary

6.242.9.18 ‘unicode_derived_line_break.pl’
..........................................

   - Provides: ‘unicode_line_break/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.101.0.info,  Node: unicode_derived_normalization_props pl,  Next: unicode_derived_numeric_type pl,  Prev: unicode_derived_line_break pl,  Up: Files and API Summary

6.242.9.19 ‘unicode_derived_normalization_props.pl’
...................................................

   - Provides: ‘unicode_fc_nfkc/2’ ‘unicode_nfkc_cf/2’
     ‘unicode_full_composition_exclusion/1-2’ ‘unicode_nfd_qc_no/1-2’
     ‘unicode_nfc_qc_no/1-2’ ‘unicode_nfc_qc_maybe/1-2’
     ‘unicode_nfkd_qc_no/1-2’ ‘unicode_nfkc_qc_no/1-2’
     ‘unicode_nfkc_qc_maybe/1-2’ ‘unicode_expands_on_nfd/1-2’
     ‘unicode_expands_on_nfc/1-2’ ‘unicode_expands_on_nfkd/1-2’
     ‘unicode_expands_on_nfkc/1-2’
     ‘unicode_changes_when_nfkc_casefolded/1-2’

   - Dependencies: files in the ‘unicode_derived_normalization_props’
     directory


File: TheLogtalkHandbook-3.101.0.info,  Node: unicode_derived_numeric_type pl,  Next: unicode_derived_numeric_values pl,  Prev: unicode_derived_normalization_props pl,  Up: Files and API Summary

6.242.9.20 ‘unicode_derived_numeric_type.pl’
............................................

   - Provides: ‘unicode_numeric_type/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.101.0.info,  Node: unicode_derived_numeric_values pl,  Next: unicode_hangul_syllable_type pl,  Prev: unicode_derived_numeric_type pl,  Up: Files and API Summary

6.242.9.21 ‘unicode_derived_numeric_values.pl’
..............................................

   - Provides: ‘unicode_numerical_value/3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.101.0.info,  Node: unicode_hangul_syllable_type pl,  Next: unicode_indic_matra_category pl,  Prev: unicode_derived_numeric_values pl,  Up: Files and API Summary

6.242.9.22 ‘unicode_hangul_syllable_type.pl’
............................................

   - Provides: ‘unicode_hangul_syllable_type/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.101.0.info,  Node: unicode_indic_matra_category pl,  Next: unicode_indic_syllabic_category pl,  Prev: unicode_hangul_syllable_type pl,  Up: Files and API Summary

6.242.9.23 ‘unicode_indic_matra_category.pl’
............................................

   - Provides: ‘unicode_indic_matra_category/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.101.0.info,  Node: unicode_indic_syllabic_category pl,  Next: unicode_jamo pl,  Prev: unicode_indic_matra_category pl,  Up: Files and API Summary

6.242.9.24 ‘unicode_indic_syllabic_category.pl’
...............................................

   - Provides: ‘unicode_indic_syllabic_category/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.101.0.info,  Node: unicode_jamo pl,  Next: unicode_name_aliases pl,  Prev: unicode_indic_syllabic_category pl,  Up: Files and API Summary

6.242.9.25 ‘unicode_jamo.pl’
............................

   - Provides: ‘unicode_jamo/2’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.101.0.info,  Node: unicode_name_aliases pl,  Next: unicode_names pl,  Prev: unicode_jamo pl,  Up: Files and API Summary

6.242.9.26 ‘unicode_name_aliases.pl’
....................................

   - Provides: ‘unicode_name_alias/3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.101.0.info,  Node: unicode_names pl,  Next: unicode_prop_list pl,  Prev: unicode_name_aliases pl,  Up: Files and API Summary

6.242.9.27 ‘unicode_names.pl’
.............................

   - Provides: ‘unicode_name/2’

   - Dependencies: files in the ‘unicode_names’ directory


File: TheLogtalkHandbook-3.101.0.info,  Node: unicode_prop_list pl,  Next: unicode_range_scripts pl,  Prev: unicode_names pl,  Up: Files and API Summary

6.242.9.28 ‘unicode_prop_list.pl’
.................................

   - Provides: ‘unicode_white_space/1-2’ ‘unicode_bidi_control/1-2’
     ‘unicode_join_control/1-2’ ‘unicode_dash/1-2’ ‘unicode_hyphen/1-2’
     ‘unicode_quotation_mark/1-2’ ‘unicode_terminal_punctuation/1-2’
     ‘unicode_other_math/1-2’ ‘unicode_hex_digit/1-2’
     ‘unicode_ascii_hex_digit/1-2’ ‘unicode_other_alphabetic/1-2’
     ‘unicode_ideographic/1-2’ ‘unicode_diacritic/1-2’
     ‘unicode_extender/1-2’ ‘unicode_other_lowercase/1-2’
     ‘unicode_other_uppercase/1-2’ ‘unicode_noncharacter_code_point/1-2’
     ‘unicode_other_grapheme_extend/1-2’
     ‘unicode_ids_binary_operator/1-2’
     ‘unicode_ids_trinary_operator/1-2’ ‘unicode_radical/1-2’
     ‘unicode_unified_ideograph/1-2’
     ‘unicode_other_default_ignorable/1-2’ ‘unicode_deprecated/1-2’
     ‘unicode_soft_dotted/1-2’ ‘unicode_logical_order_exception/1-2’
     ‘unicode_other_id_start/1-2’ ‘unicode_other_id_continue/1-2’
     ‘unicode_sterm/1-2’ ‘unicode_variation_selector/1-2’
     ‘unicode_pattern_white_space/1-2’ ‘unicode_pattern_syntax/1-2’

   - Dependencies: files in the ‘unicode_prop_list’ directory


File: TheLogtalkHandbook-3.101.0.info,  Node: unicode_range_scripts pl,  Next: unicode_script_extensions pl,  Prev: unicode_prop_list pl,  Up: Files and API Summary

6.242.9.29 ‘unicode_range_scripts.pl’
.....................................

   - Provides: ‘unicode_range_script/3’ ‘unicode_script/2’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.101.0.info,  Node: unicode_script_extensions pl,  Next: unicode_scripts pl,  Prev: unicode_range_scripts pl,  Up: Files and API Summary

6.242.9.30 ‘unicode_script_extensions.pl’
.........................................

   - Provides: ‘unicode_script_extension/2-3’

   - Dependencies: ‘unicode_scripts.pl’


File: TheLogtalkHandbook-3.101.0.info,  Node: unicode_scripts pl,  Next: unicode_special_casing pl,  Prev: unicode_script_extensions pl,  Up: Files and API Summary

6.242.9.31 ‘unicode_scripts.pl’
...............................

   - Provides: ‘unicode_script/6’ ‘unicode_script_category/3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.101.0.info,  Node: unicode_special_casing pl,  Next: unicode_unihan_variants pl,  Prev: unicode_scripts pl,  Up: Files and API Summary

6.242.9.32 ‘unicode_special_casing.pl’
......................................

   - Provides: ‘unicode_special_casing/5’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.101.0.info,  Node: unicode_unihan_variants pl,  Next: unicode_version pl,  Prev: unicode_special_casing pl,  Up: Files and API Summary

6.242.9.33 ‘unicode_unihan_variants.pl’
.......................................

   - Provides: ‘unicode_unihan_variant/2-3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.101.0.info,  Node: unicode_version pl,  Prev: unicode_unihan_variants pl,  Up: Files and API Summary

6.242.9.34 ‘unicode_version.pl’
...............................

   - Provides: ‘unicode_version/3’

   - Dependencies: (none)


File: TheLogtalkHandbook-3.101.0.info,  Node: union_find,  Next: url,  Prev: unicode_data,  Up: Libraries

6.243 ‘union_find’
==================

This library implements a union-find data structure.  This structure
tracks a set of elements partitioned into a number of disjoint
(non-overlapping) subsets.  It provides fast operations to add new sets,
to merge existing sets, and to determine whether elements are in the
same set.  This implementation of the union-find algorithm provides the
following features:

   - Path compression: Path compression flattens the structure of the
     tree by making every node point to the root whenever a find
     predicate is used on it.

   - Union by rank: Union predicates always attach the shorter tree to
     the root of the taller tree.  Thus, the resulting tree is no taller
     than the original unless they were of equal height, in which case
     the resulting tree is taller by one node.

For a general and extended discussion on this data structure, see e.g.

‘https://en.wikipedia.org/wiki/Disjoint-set_data_structure’

* Menu:

* API documentation: API documentation<258>.
* Loading: Loading<262>.
* Testing: Testing<253>.
* Usage: Usage<109>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<258>,  Next: Loading<262>,  Up: union_find

6.243.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#union-find’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<262>,  Next: Testing<253>,  Prev: API documentation<258>,  Up: union_find

6.243.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(union_find(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<253>,  Next: Usage<109>,  Prev: Loading<262>,  Up: union_find

6.243.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(union_find(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<109>,  Prev: Testing<253>,  Up: union_find

6.243.4 Usage
-------------

An usage example is Kruskal’s algorithm, a minimum-spanning-tree
algorithm which finds an edge of the least possible weight that connects
any two trees in the forest.  It is a greedy algorithm in graph theory
as it finds a minimum spanning tree for a connected weighted graph by
adding increasing cost arcs at each step.

     :- object(kruskal).

         :- public(kruskal/2).

         :- uses(union_find, [
             new/2, find/4, union/4
         ]).

         kruskal(g(Vertices-Edges), g(Vertices-Tree)) :-
             new(Vertices, UnionFind),
             keysort(Edges, Sorted),
             kruskal(UnionFind, Sorted, Tree).

         kruskal(_, [], []).
         kruskal(UnionFind0, [Edge| Edges], [Edge| Tree]) :-
             Edge = _-(Vertex1, Vertex2),
             find(UnionFind0, Vertex1, Root1, UnionFind1),
             find(UnionFind1, Vertex2, Root2, UnionFind2),
             Root1 \== Root2,
             !,
             union(UnionFind2, Vertex1, Vertex2, UnionFind3),
             kruskal(UnionFind3, Edges, Tree).
         kruskal(UnionFind, [_| Edges], Tree) :-
             kruskal(UnionFind, Edges, Tree).

     :- end_object.

Sample query:

     | ?- kruskal::kruskal(g([a,b,c,d,e,f,g]-[7-(a,b), 5-(a,d), 8-(b,c), 7-(b,e), 9-(b,d), 5-(c,e), 15-(d,e), 6-(d,f), 8-(e,f), 9-(e,g), 11-(f,g)]), Tree).

     Tree = g([a,b,c,d,e,f,g]-[5-(a,d),5-(c,e),6-(d,f),7-(a,b),7-(b,e),9-(e,g)])
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: url,  Next: uuid,  Prev: union_find,  Up: Libraries

6.244 ‘url’
===========

This library implements validation, parsing, generating, and
normalization of URLs, which can be represented as atoms, character
lists, or code lists.  It currently supports the following URL schemes:

Web protocols:

   - ‘http’

   - ‘https’

   - ‘ws’

   - ‘wss’

   - ‘gopher’

File transfer and version control:

   - ‘ftp’

   - ‘ftps’

   - ‘sftp’

   - ‘git’

File access:

   - ‘file’

Databases:

   - ‘jdbc’

   - ‘mongodb’

   - ‘mysql’

   - ‘postgresql’

Email and news:

   - ‘mailto’

   - ‘news’

   - ‘nntp’

Media streaming:

   - ‘mms’

   - ‘rtmp’

   - ‘rtsp’

Shell access:

   - ‘ssh’

   - ‘telnet’

Directory services:

   - ‘ldap’

   - ‘ldaps’

Other protocols:

   - ‘tel’

   - ‘urn’

The library predicates are defined in the ‘url(_Representation_)’
parametric object where ‘_Representation_’ can be one of:

   - ‘atom’ - strings are represented as atoms

   - ‘chars’ - strings are represented as lists of characters

   - ‘codes’ - strings are represented as lists of character codes

The parameter must be bound when sending messages to the object.

The library also provides an utility predicate,
‘file_path_components/2’, for converting a file-system path into file
URL components.  This predicate also handles Windows drive-letter and
UNC paths.

* Menu:

* API documentation: API documentation<259>.
* Loading: Loading<263>.
* Testing: Testing<254>.
* Usage: Usage<110>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<259>,  Next: Loading<263>,  Up: url

6.244.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#url’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<263>,  Next: Testing<254>,  Prev: API documentation<259>,  Up: url

6.244.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(url(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<254>,  Next: Usage<110>,  Prev: Loading<263>,  Up: url

6.244.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(url(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<110>,  Prev: Testing<254>,  Up: url

6.244.4 Usage
-------------

The ‘valid/1’ and ‘parse/2’ predicates are intended for absolute URLs:

     | ?- url(atom)::valid('https://example.com/path?x=1#frag').
     true.

     | ?- url(atom)::parse('https://example.com/path?x=1#frag', Components).
     Components = [scheme(https), authority('example.com'), path('/path'), query('x=1'), fragment(frag)].

For RFC 3986 relative references, use ‘parse/3’ or ‘reference_kind/2’:

     | ?- url(atom)::parse('../users/42?verbose=true#details', Components, Kind).
     Components = [path('../users/42'), query('verbose=true'), fragment(details)],
     Kind = relative_path.

     | ?- url(atom)::reference_kind('//example.com/v1', Kind).
     Kind = network_path.

The ‘generate/2’ and ‘normalize/2’ predicates work with both absolute
URLs and relative references:

     | ?- url(atom)::generate([authority('example.com'), path('/v1')], Reference).
     Reference = '//example.com/v1'.

     | ?- url(atom)::normalize('../users/./42', NormalizedReference).
     NormalizedReference = '../users/42'.

The ‘resolve/3’ predicate resolves a reference against an absolute base
URL, while ‘relativize/3’ computes a relative reference between
compatible URLs:

     | ?- url(atom)::resolve('http://example.com/a/b/c', '../d', Resolved).
     Resolved = 'http://example.com/a/d'.

     | ?- url(atom)::relativize('http://example.com/a/b/c', 'http://example.com/v1', Relative).
     Relative = '../../v1'.

The ‘file_path_components/2’ predicate converts file-system paths into
file URL components and supports both POSIX and Windows paths:

     | ?- url(atom)::file_path_components('/home/user/document.txt', Components).
     Components = [authority(''), path('/home/user/document.txt')].

     | ?- url(atom)::file_path_components('C:\\Temp\\app\\file.txt', Components).
     Components = [authority(''), path('/C:/Temp/app/file.txt')].


File: TheLogtalkHandbook-3.101.0.info,  Node: uuid,  Next: validations,  Prev: url,  Up: Libraries

6.245 ‘uuid’
============

This library implements a Universally Unique Identifier (UUID)
generator.  Currently version 1, version 3, version 4, version 5, and
version 7 UUIDs are supported.  Version 5 support requires a Prolog
backend with support for unbounded integer arithmetic.  For reference
material, see e.g.

‘https://en.wikipedia.org/wiki/Universally_unique_identifier’

Some backends provide time stamps with low granularity (e.g., seconds
but not milliseconds or nanoseconds).  To compensate, the generation of
version 1 UUIDs uses 14 random bits for the clock sequence.

Some backends only provide access to local time.  On those backends, the
‘uuid_v1/2’ and ‘uuid_v7/1’ predicates preserve the backend behavior and
use the available local time fields when computing the UUID timestamp.
To compute UUID timestamps using UTC instead, use the ‘uuid_v1/3’ and
‘uuid_v7/2’ predicates and pass the current local UTC offset as ‘Z’,
‘+HH:MM’, or ‘-HH:MM’.

The generation of version 4 and version 7 UUIDs uses the ‘/dev/urandom’
random number generator when available.  This includes macOS, Linux,
*BSD, and other POSIX operating-systems.  On Windows, a pseudo-random
generator is used, but randomized using the current wall time.

Version 3 and version 5 UUIDs are namespace-name based UUIDs using the
MD5 and SHA-1 hash functions, respectively.

Version 7 UUIDs are time-ordered using a Unix Epoch timestamp in
milliseconds, as specified in RFC 9562.  They are recommended over
version 1 UUIDs for new applications due to improved entropy and
sortability characteristics.

UUIDs can be generated as atoms, lists of characters, or lists of
character codes.

See also the ‘cuid2’, ‘ksuid’, ‘ids’, ‘nanoid’, ‘snowflakeid’, and
‘ulid’ libraries.

* Menu:

* API documentation: API documentation<260>.
* Loading: Loading<264>.
* Testing: Testing<255>.
* Generating version 1 UUIDs::
* Generating version 4 UUIDs::
* Generating version 3 UUIDs::
* Generating version 5 UUIDs::
* Generating version 7 UUIDs::
* Generating the Nil and Max UUIDs::


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<260>,  Next: Loading<264>,  Up: uuid

6.245.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#uuid’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<264>,  Next: Testing<255>,  Prev: API documentation<260>,  Up: uuid

6.245.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(uuid(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<255>,  Next: Generating version 1 UUIDs,  Prev: Loading<264>,  Up: uuid

6.245.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(uuid(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Generating version 1 UUIDs,  Next: Generating version 4 UUIDs,  Prev: Testing<255>,  Up: uuid

6.245.4 Generating version 1 UUIDs
----------------------------------

By default, version 1 UUIDs are generated as atoms.  For example:

     | ?- uuid::uuid_v1([0xf2,0xd1,0x90,0x94,0xdc,0x4b], UUID).
     UUID = '00a66fc0-82cf-11eb-bc83-f2d19094dc4b'
     yes

To generate a UUID using a list of characters representation, use
instead the ‘uuid/1’ parametric object:

     | ?- uuid(chars)::uuid_v1([0xf2,0xd1,0x90,0x94,0xdc,0x4b], UUID).
     UUID = ['0','0',d,e,'9','0',c,'0',-,'8','2',c,f,-,'1','1',e,b,-,
             a,'9','8','5',-,f,'2',d,'1','9','0','9','4',d,c,'4',b]
     yes

Similarly, to get a UUID using a list of character codes representation:

     | ?- uuid(codes)::uuid_v1([0xf2,0xd1,0x90,0x94,0xdc,0x4b], UUID).
     UUID = [48,48,52,99,99,54,99,48,45,56,50,99,102,45,49,49,101,98,45,
             98,57,102,52,45,102,50,100,49,57,48,57,52,100,99,52,98]
     yes

When the backend only provides access to local time, use ‘uuid_v1/3’
with the current local UTC offset to compute the UUID timestamp using
UTC:

     | ?- uuid::uuid_v1([0xf2,0xd1,0x90,0x94,0xdc,0x4b], '+01:00', UUID).
     UUID = '00a66fc0-82cf-11eb-bc83-f2d19094dc4b'
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: Generating version 4 UUIDs,  Next: Generating version 3 UUIDs,  Prev: Generating version 1 UUIDs,  Up: uuid

6.245.5 Generating version 4 UUIDs
----------------------------------

By default, version 4 UUIDs are generated as atoms.  For example:

     | ?- uuid::uuid_v4(UUID).
     UUID = '1c652782-69c5-4252-88c8-09e576a44db5'
     yes

To generate a UUID using a list of characters representation, use
instead the ‘uuid/1’ parametric object:

     | ?- uuid(chars)::uuid_v4(UUID).
     UUID = [d,'3',d,'3','3','5','1','3',-,'8','1',e,c,-,'4',d,'2','6',-,
             '9',f,'2','2',-,e,d,'9','5',e,'0','0',e,'1','5','7','0']
     yes

Similar to get a UUID using a list of character codes representation:

     | ?- uuid(codes)::uuid_v4(UUID).
     UUID = [102,97,52,54,57,98,100,50,45,51,57,54,51,45,52,97,100,55,45,
             98,50,50,55,45,101,100,52,99,56,55,99,54,53,55,102,98]
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: Generating version 3 UUIDs,  Next: Generating version 5 UUIDs,  Prev: Generating version 4 UUIDs,  Up: uuid

6.245.6 Generating version 3 UUIDs
----------------------------------

Version 3 UUIDs are namespace-name based UUIDs using the MD5 hash
function.  For example:

     | ?- uuid::uuid_v3('6ba7b810-9dad-11d1-80b4-00c04fd430c8', 'www.widgets.com', UUID).
     UUID = '3d813cbb-47fb-32ba-91df-831e1593ac29'
     yes

To generate a UUID using a list of characters representation, use
instead the ‘uuid/1’ parametric object:

     | ?- uuid(chars)::uuid_v3('6ba7b810-9dad-11d1-80b4-00c04fd430c8', 'www.widgets.com', UUID).
     UUID = ['3',d,'8','1','3',c,b,b,-,'4','7',f,b,-,'3','2',b,a,-,
             '9','1',d,f,-,'8','3','1',e,'1','5','9','3',a,c,'2','9']
     yes

Similarly, to get a UUID using a list of character codes representation:

     | ?- uuid(codes)::uuid_v3('6ba7b810-9dad-11d1-80b4-00c04fd430c8', 'www.widgets.com', UUID).
     UUID = [51,100,56,49,51,99,98,98,45,52,55,102,98,45,51,50,98,97,45,
             57,49,100,102,45,56,51,49,101,49,53,57,51,97,99,50,57]
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: Generating version 5 UUIDs,  Next: Generating version 7 UUIDs,  Prev: Generating version 3 UUIDs,  Up: uuid

6.245.7 Generating version 5 UUIDs
----------------------------------

Version 5 UUIDs are namespace-name based UUIDs using the SHA-1 hash
function.  This predicate is only available on Prolog backends with
support for unbounded integer arithmetic.  For example:

     | ?- uuid::uuid_v5('6ba7b810-9dad-11d1-80b4-00c04fd430c8', 'www.widgets.com', UUID).
     UUID = '21f7f8de-8051-5b89-8680-0195ef798b6a'
     yes

To generate a UUID using a list of characters representation, use
instead the ‘uuid/1’ parametric object:

     | ?- uuid(chars)::uuid_v5('6ba7b810-9dad-11d1-80b4-00c04fd430c8', 'www.widgets.com', UUID).
     UUID = ['2','1',f,'7',f,'8',d,e,-,'8','0','5','1',-,'5',b,'8','9',-,
             '8','6','8','0',-,'0','1','9','5',e,f,'7','9','8',b,'6',a]
     yes

Similarly, to get a UUID using a list of character codes representation:

     | ?- uuid(codes)::uuid_v5('6ba7b810-9dad-11d1-80b4-00c04fd430c8', 'www.widgets.com', UUID).
     UUID = [50,49,102,55,102,56,100,101,45,56,48,53,49,45,53,98,56,57,45,
             56,54,56,48,45,48,49,57,53,101,102,55,57,56,98,54,97]
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: Generating version 7 UUIDs,  Next: Generating the Nil and Max UUIDs,  Prev: Generating version 5 UUIDs,  Up: uuid

6.245.8 Generating version 7 UUIDs
----------------------------------

Version 7 UUIDs are time-ordered using the Unix Epoch timestamp in
milliseconds (as specified in RFC 9562).  By default, version 7 UUIDs
are generated as atoms.  For example:

     | ?- uuid::uuid_v7(UUID).
     UUID = '018d5f3c-9b5a-7c4e-8f2a-1b3c4d5e6f70'
     yes

To generate a UUID using a list of characters representation, use
instead the ‘uuid/1’ parametric object:

     | ?- uuid(chars)::uuid_v7(UUID).
     UUID = ['0','1','8',d,'5',f,'3',c,-,'9',b,'5',a,-,'7',c,'4',e,-,
             '8',f,'2',a,-,'1',b,'3',c,'4',d,'5',e,'6',f,'7','0']
     yes

Similar to get a UUID using a list of character codes representation:

     | ?- uuid(codes)::uuid_v7(UUID).
     UUID = [48,49,56,100,53,102,51,99,45,57,98,53,97,45,55,99,52,101,45,
             56,102,50,97,45,49,98,51,99,52,100,53,101,54,102,55,48]
     yes

When the backend only provides access to local time, use ‘uuid_v7/2’
with the current local UTC offset to compute the UUID timestamp using
UTC:

     | ?- uuid::uuid_v7('+01:00', UUID).
     UUID = '018d5f3c-9b5a-7c4e-8f2a-1b3c4d5e6f70'
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: Generating the Nil and Max UUIDs,  Prev: Generating version 7 UUIDs,  Up: uuid

6.245.9 Generating the Nil and Max UUIDs
----------------------------------------

Predicates are also provided that return the Nil and Max UUIDs:

     | ?- uuid::uuid_nil(UUID).
     UUID = '00000000-0000-0000-0000-000000000000'
     yes

     | ?- uuid::uuid_max(UUID).
     UUID = 'FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF'
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: validations,  Next: wkt_wkb,  Prev: uuid,  Up: Libraries

6.246 ‘validations’
===================

This library provides an implementation of 'validation terms' with an
API for applicative-style error accumulation.  A validation term is an
opaque compound term that either contains a valid value (‘valid(Value)’)
or a list of errors (‘invalid(Errors)’).

The library follows the same design pattern as the ‘optionals’ and
‘expecteds’ libraries:

   - ‘validation’ — factory object for constructing validation terms

   - ‘validation/1’ — parametric object wrapping a validation term

   - ‘validated’ — companion helper object for list operations,
     type-checking, and QuickCheck support

The naming follows the convention used in Scala Cats and Kotlin Arrow,
where the companion type is called ‘Validated’.

* Menu:

* API documentation: API documentation<261>.
* Loading: Loading<265>.
* Testing: Testing<256>.
* Usage: Usage<111>.
* Comparison with the expecteds library::
* See also: See also<7>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<261>,  Next: Loading<265>,  Up: validations

6.246.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#validations’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<265>,  Next: Testing<256>,  Prev: API documentation<261>,  Up: validations

6.246.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(validations(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<256>,  Next: Usage<111>,  Prev: Loading<265>,  Up: validations

6.246.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(validations(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Usage<111>,  Next: Comparison with the expecteds library,  Prev: Testing<256>,  Up: validations

6.246.4 Usage
-------------

The ‘validation’ object provides constructors for validation terms.  For
example:

     | ?- validation::of_valid(1, Validation).
     ...

The created validation terms can then be passed as parameters to the
‘validation/1’ parametric object.  For example:

     | ?- validation::of_valid(1, V1), validation::of_valid(2, V2),
          validation::sequence([V1, V2], Validation).
     Validation = valid([1,2])
     yes

     | ?- validation::of_invalid(e1, V1), validation::of_invalid(e2, V2),
          validation::sequence([V1, V2], Validation).
     Validation = invalid([e1,e2])
     yes

     | ?- validation(valid(1))::flat_map([X,V]>>(Y is X+1, V = valid(Y)), Validation).
     Validation = valid(2)
     yes

Validation terms can be constructed from goals, optionals, and
expecteds:

     | ?- validation::from_goal(succ(1, Value), Value, Validation).
     Validation = valid(2)
     yes

     | ?- validation::from_optional(empty, no_value, Validation).
     Validation = invalid([no_value])
     yes

     | ?- validation::from_expected(unexpected(e), Validation).
     Validation = invalid([e])
     yes

Validation terms can be converted to optionals and expecteds:

     | ?- validation(valid(42))::to_optional(Optional).
     Optional = optional(42)
     yes

     | ?- validation(invalid([e1,e2]))::to_expected(Expected).
     Expected = unexpected([e1,e2])
     yes

The key feature of validation is error accumulation via ‘zip/3’:

     | ?- validation::of_valid(1, V1), validation::of_invalid(e1, V2),
          validation(V1)::zip([_,_,_]>>true, V2, Result).
     Result = invalid([e1])
     yes

     | ?- validation::of_invalid(e1, V1), validation::of_invalid(e2, V2),
          validation(V1)::zip([_,_,_]>>true, V2, Result).
     Result = invalid([e1,e2])
     yes

The companion ‘validated’ object provides predicates for handling lists
of validation terms, including ‘valids/2’, ‘invalids/2’, ‘partition/3’,
and ‘map/3-4’.

     | ?- validation::of_valid(1, V1), validation::of_invalids([e1,e2], V2), validation::of_valid(2, V3),
          validated::partition([V1, V2, V3], Values, Errors).
     Values = [1,2],
     Errors = [e1,e2]
     yes

     | ?- validated::map([Term,Validation]>>(
            integer(Term) -> validation::of_valid(Term, Validation)
          ; validation::of_invalid(not_integer(Term), Validation)
          ), [1,a,2,b], ValuesErrors).
     ValuesErrors = [1,2]-[not_integer(a),not_integer(b)]
     yes

     | ?- validated::map([Term,Validation]>>(
            integer(Term) -> validation::of_valid(Term, Validation)
          ; validation::of_invalid(not_integer(Term), Validation)
          ), [1,a,2,b], Values, Errors).
     Values = [1,2],
     Errors = [not_integer(a),not_integer(b)]
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: Comparison with the expecteds library,  Next: See also<7>,  Prev: Usage<111>,  Up: validations

6.246.5 Comparison with the ‘expecteds’ library
-----------------------------------------------

Both this library and the ‘expecteds’ library wrap computations that may
succeed or fail.  The fundamental difference is the 'error model':

   - ‘expecteds’ carries a 'single' error and 'short-circuits' on the
     first failure (monadic error handling).  Once an unexpected term is
     produced, subsequent operations are skipped.

   - ‘validations’ carries a 'list' of errors and 'accumulates all
     failures' (applicative error handling).  Operations such as
     ‘zip/3’, ‘sequence/2’, and ‘traverse/3’ collect every error.

Use ‘expecteds’ when you only care about the first error.  Use
‘validations’ when you want to 'report all problems at once' (e.g.  form
validation, configuration checking, or batch input processing).

* Menu:

* Example; form validation with error accumulation: Example form validation with error accumulation.


File: TheLogtalkHandbook-3.101.0.info,  Node: Example form validation with error accumulation,  Up: Comparison with the expecteds library

6.246.5.1 Example: form validation with error accumulation
..........................................................

Consider validating a form with a name (must be an atom) and an age
(must be a positive integer).  Each field is validated independently and
the results are combined with ‘validated::sequence/2’, which accumulates
all errors:

     | ?- Name = 123, Age = young,
          validation::from_goal(atom(Name), Name, invalid_name, V1),
          validation::from_goal((integer(Age), Age > 0), Age, invalid_age, V2),
          validated::sequence([V1, V2], Result),
          validation(Result)::or_else_throw(_).
     uncaught exception: [invalid_name,invalid_age]

Both errors are reported.  When all fields are valid, ‘or_else_throw/1’
returns the list of valid values:

     | ?- Name = john, Age = 25,
          validation::from_goal(atom(Name), Name, invalid_name, V1),
          validation::from_goal((integer(Age), Age > 0), Age, invalid_age, V2),
          validated::sequence([V1, V2], Result),
          validation(Result)::or_else_throw(Values).
     Values = [john,25]
     yes

Compare with the ‘expecteds’ library, where ‘either::sequence/2’
short-circuits at the first failure:

     | ?- Name = 123, Age = young,
          expected::from_goal(atom(Name), Name, invalid_name, E1),
          expected::from_goal((integer(Age), Age > 0), Age, invalid_age, E2),
          either::sequence([E1, E2], Result),
          expected(Result)::or_else_throw(_).
     uncaught exception: invalid_name

Only ‘invalid_name’ is reported — ‘either::sequence/2’ stops at the
first unexpected term.

The two libraries are complementary.  Use ‘expecteds’ for sequential
pipelines where only the first error matters.  Use ‘validations’ with
‘sequence/2’, ‘traverse/3’, or ‘zip/3’ for independent validations where
all errors should be collected.


File: TheLogtalkHandbook-3.101.0.info,  Node: See also<7>,  Prev: Comparison with the expecteds library,  Up: validations

6.246.6 See also
----------------

The ‘expecteds’ and ‘optionals’ libraries.


File: TheLogtalkHandbook-3.101.0.info,  Node: wkt_wkb,  Next: yaml,  Prev: validations,  Up: Libraries

6.247 ‘wkt_wkb’
===============

The ‘wkt_wkb’ library provides predicates for parsing, generating, and
validating geometries represented using the Well-Known Text (WKT) and
Well-Known Binary (WKB) interchange formats.

It complements the ‘geojson’ and ‘geospatial’ libraries by reusing the
same geometry constructors while adding support for the standard text
and binary geometry encodings widely used by spatial databases and GIS
tooling.

* Menu:

* API documentation: API documentation<262>.
* Loading: Loading<266>.
* Testing: Testing<257>.
* Representation: Representation<23>.
* Sources and sinks::
* Examples: Examples<181>.
* Notes: Notes<13>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<262>,  Next: Loading<266>,  Up: wkt_wkb

6.247.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#wkt_wkb’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<266>,  Next: Testing<257>,  Prev: API documentation<262>,  Up: wkt_wkb

6.247.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(wkt_wkb(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<257>,  Next: Representation<23>,  Prev: Loading<266>,  Up: wkt_wkb

6.247.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(wkt_wkb(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Representation<23>,  Next: Sources and sinks,  Prev: Testing<257>,  Up: wkt_wkb

6.247.4 Representation
----------------------

The library uses the same native geometry constructors as the ‘geojson’
library for geometry values:

   - ‘point(Position)’ or ‘point(Position, Options)’

   - ‘multi_point(Positions)’ or ‘multi_point(Positions, Options)’

   - ‘line_string(Positions)’ or ‘line_string(Positions, Options)’

   - ‘multi_line_string(LineStrings)’ or ‘multi_line_string(LineStrings,
     Options)’

   - ‘polygon(Rings)’ or ‘polygon(Rings, Options)’

   - ‘multi_polygon(Polygons)’ or ‘multi_polygon(Polygons, Options)’

   - ‘geometry_collection(Geometries)’ or
     ‘geometry_collection(Geometries, Options)’

Positions are represented as lists of numeric coordinates.  Empty
geometries use empty lists, e.g.  ‘point([])’ or ‘polygon([])’.

The optional ‘Options’ lists currently support:

   - ‘dimensions(xy)’

   - ‘dimensions(z)’

   - ‘dimensions(m)’

   - ‘dimensions(zm)’

The ‘dimensions/1’ option is mainly required to distinguish ‘Z’ and ‘M’
three-coordinate geometries and to preserve dimensionality for empty
geometries.  When the option is omitted, dimensionality is inferred from
the coordinates and defaults to ‘xy’ for empty geometries.


File: TheLogtalkHandbook-3.101.0.info,  Node: Sources and sinks,  Next: Examples<181>,  Prev: Representation<23>,  Up: wkt_wkb

6.247.5 Sources and sinks
-------------------------

WKT sources and sinks are wrapped as ‘wkt(...)’ terms:

   - ‘wkt(file(Path))’

   - ‘wkt(stream(Stream))’

   - ‘wkt(atom(Atom))’

   - ‘wkt(chars(List))’

   - ‘wkt(codes(List))’

WKB sources and sinks are wrapped as ‘wkb(...)’ terms:

   - ‘wkb(file(Path))’

   - ‘wkb(stream(Stream))’

   - ‘wkb(bytes(List))’

   - ‘wkb(hex(atom(Atom)))’

   - ‘wkb(hex(chars(List)))’

   - ‘wkb(hex(codes(List)))’

When generating WKB, byte order defaults to little-endian.  A specific
byte order can be selected using ‘wkb(Sink, little)’ or ‘wkb(Sink,
big)’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<181>,  Next: Notes<13>,  Prev: Sources and sinks,  Up: wkt_wkb

6.247.6 Examples
----------------

Parse a WKT point:

     | ?- wkt_wkb::parse(wkt(atom('POINT Z (1 2 3)')), Geometry).
     Geometry = point([1, 2, 3], [dimensions(z)])
     yes

Generate canonical WKT for a polygon:

     | ?- wkt_wkb::generate(wkt(atom(WKT)), polygon([[[0,0],[1,0],[1,1],[0,1],[0,0]]])).
     WKT = 'POLYGON ((0 0, 1 0, 1 1, 0 1, 0 0))'
     yes

Generate WKB hex for a point:

     | ?- wkt_wkb::generate(wkb(hex(atom(Hex))), point([1, 2])).
     Hex = '0101000000000000000000f03f0000000000000040'
     yes

Round-trip through a big-endian WKB byte sequence:

     | ?- wkt_wkb::generate(wkb(bytes(Bytes), big), line_string([[0,0],[1,1]])),
          wkt_wkb::parse(wkb(bytes(Bytes)), Geometry).

Validate a geometry term:

     | ?- wkt_wkb::validate(multi_point([[], [1, 2], [3, 4]])).
     yes

     | ?- wkt_wkb::validate(polygon([[[0,0],[1,0],[1,1],[0,1]]]), Errors).
     Errors = [ring_not_closed([coordinates,0])]
     yes


File: TheLogtalkHandbook-3.101.0.info,  Node: Notes<13>,  Prev: Examples<181>,  Up: wkt_wkb

6.247.7 Notes
-------------

   - WKT parsing accepts the standard geometry keywords ‘POINT’,
     ‘LINESTRING’, ‘POLYGON’, ‘MULTIPOINT’, ‘MULTILINESTRING’,
     ‘MULTIPOLYGON’, and ‘GEOMETRYCOLLECTION’, together with the ‘Z’,
     ‘M’, and ‘ZM’ dimension tags.

   - Canonical WKT generation always uses uppercase geometry keywords.

   - WKB generation uses the ISO/OGC type-code offsets ‘1000’, ‘2000’,
     and ‘3000’ for ‘Z’, ‘M’, and ‘ZM’ dimensionality.

   - Empty WKB points are encoded using quiet NaN ordinates as required
     by the format, while empty non-point geometries are encoded using
     zero counts.

   - Geometry validation checks coordinate dimensionality consistency,
     minimum cardinalities for line strings and rings, and polygon ring
     closure.


File: TheLogtalkHandbook-3.101.0.info,  Node: yaml,  Next: z_score_anomaly_detector,  Prev: wkt_wkb,  Up: Libraries

6.248 ‘yaml’
============

The ‘yaml’ library provides predicates for parsing and generating data
in the YAML format:

‘https://yaml.org’

It includes parsing and generation of simple scalar values, lists,
mappings, and nested structures.

* Menu:

* API documentation: API documentation<263>.
* Loading: Loading<267>.
* Testing: Testing<258>.
* API::
* Data Representation: Data Representation<2>.
* Examples: Examples<182>.
* Features: Features<80>.
* Supported YAML Features::
* Limitations: Limitations<6>.
* Error Handling: Error Handling<4>.
* File Organization::
* Test Files::
* Performance Considerations: Performance Considerations<2>.
* Integration with Other Libraries::
* Future Enhancements::
* See Also::


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<263>,  Next: Loading<267>,  Up: yaml

6.248.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#yaml’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<267>,  Next: Testing<258>,  Prev: API documentation<263>,  Up: yaml

6.248.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(yaml(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<258>,  Next: API,  Prev: Loading<267>,  Up: yaml

6.248.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(yaml(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: API,  Next: Data Representation<2>,  Prev: Testing<258>,  Up: yaml

6.248.4 API
-----------

* Menu:

* Parsing: Parsing<3>.
* Generating: Generating<3>.
* Multi-Document Parsing::
* Multi-Document Generation::


File: TheLogtalkHandbook-3.101.0.info,  Node: Parsing<3>,  Next: Generating<3>,  Up: API

6.248.4.1 Parsing
.................

The ‘parse/2’ predicate parses YAML content from various sources into a
structured Logtalk term representation.

     parse(+Source, -YAML)

Sources can be:

   - ‘file(Path)’ - parse YAML from a file

   - ‘stream(Stream)’ - parse YAML from an open stream

   - ‘codes(Codes)’ - parse YAML from a list of character codes

   - ‘chars(Chars)’ - parse YAML from a list of characters

   - ‘atom(Atom)’ - parse YAML from an atom

The parsed YAML is returned as a compound term with the functor
‘yaml/1’.


File: TheLogtalkHandbook-3.101.0.info,  Node: Generating<3>,  Next: Multi-Document Parsing,  Prev: Parsing<3>,  Up: API

6.248.4.2 Generating
....................

The ‘generate/2’ predicate generates YAML output from a structured term.

     generate(+Sink, +YAML)

Sinks can be:

   - ‘file(Path)’ - write YAML to a file

   - ‘stream(Stream)’ - write YAML to an open stream

   - ‘codes(Codes)’ - get YAML as a list of character codes

   - ‘chars(Chars)’ - get YAML as a list of characters

   - ‘atom(Atom)’ - get YAML as an atom

The input must be a compound term representing YAML data (e.g.,
‘yaml([...])’ for mappings, ‘[...]’ for sequences).


File: TheLogtalkHandbook-3.101.0.info,  Node: Multi-Document Parsing,  Next: Multi-Document Generation,  Prev: Generating<3>,  Up: API

6.248.4.3 Multi-Document Parsing
................................

The ‘parse_all/2’ predicate parses all YAML documents from a source into
a list.

     parse_all(+Source, -YAMLs)

Documents are separated by ‘---’ markers and optionally terminated by
‘...’ markers.  Returns a list of YAML terms, even for single-document
sources.


File: TheLogtalkHandbook-3.101.0.info,  Node: Multi-Document Generation,  Prev: Multi-Document Parsing,  Up: API

6.248.4.4 Multi-Document Generation
...................................

The ‘generate_all/2’ predicate generates YAML output with multiple
documents.

     generate_all(+Sink, +YAMLs)

Takes a list of YAML terms and generates output with ‘---’ separators
between documents.  For a single document, no separator is added.


File: TheLogtalkHandbook-3.101.0.info,  Node: Data Representation<2>,  Next: Examples<182>,  Prev: API,  Up: yaml

6.248.5 Data Representation
---------------------------

YAML data is represented using the following mappings:

YAML Value          Logtalk Representation
                    
---------------------------------------------------
‘null’              ‘'@'(null)’
                    
‘true’              ‘'@'(true)’
                    
‘false’             ‘'@'(false)’
                    
Number (42)         ‘42’
                    
String (“text”)     ‘text’ (as atom)
                    
Array/List          ‘[item1, item2, ...]’
                    
Mapping/Object      ‘yaml([key1-val1, ...])’
                    


File: TheLogtalkHandbook-3.101.0.info,  Node: Examples<182>,  Next: Features<80>,  Prev: Data Representation<2>,  Up: yaml

6.248.6 Examples
----------------

* Menu:

* Parsing a Simple YAML String::
* Parsing a YAML List::
* Parsing a YAML File::
* Generating YAML from a Term::
* Generating YAML to a File::
* Working with Nested Structures::


File: TheLogtalkHandbook-3.101.0.info,  Node: Parsing a Simple YAML String,  Next: Parsing a YAML List,  Up: Examples<182>

6.248.6.1 Parsing a Simple YAML String
......................................

     ?- parse(atom('name: John\nage: 30'), YAML).
     YAML = yaml([name-'John', age-30]).


File: TheLogtalkHandbook-3.101.0.info,  Node: Parsing a YAML List,  Next: Parsing a YAML File,  Prev: Parsing a Simple YAML String,  Up: Examples<182>

6.248.6.2 Parsing a YAML List
.............................

     ?- parse(codes([0'-, 0' , 0'a, ...]), YAML).
     YAML = yaml([apple, banana, orange]).


File: TheLogtalkHandbook-3.101.0.info,  Node: Parsing a YAML File,  Next: Generating YAML from a Term,  Prev: Parsing a YAML List,  Up: Examples<182>

6.248.6.3 Parsing a YAML File
.............................

     ?- parse(file('config.yaml'), YAML).
     % Reads and parses config.yaml


File: TheLogtalkHandbook-3.101.0.info,  Node: Generating YAML from a Term,  Next: Generating YAML to a File,  Prev: Parsing a YAML File,  Up: Examples<182>

6.248.6.4 Generating YAML from a Term
.....................................

     ?- generate(atom(Result), yaml([title-'Project', version-1])).
     Result = '{title:Project,version:1}'.


File: TheLogtalkHandbook-3.101.0.info,  Node: Generating YAML to a File,  Next: Working with Nested Structures,  Prev: Generating YAML from a Term,  Up: Examples<182>

6.248.6.5 Generating YAML to a File
...................................

     ?- Data = yaml([name-'Alice', score-95]),
        generate(file('output.yaml'), Data).
     % Writes YAML data to output.yaml


File: TheLogtalkHandbook-3.101.0.info,  Node: Working with Nested Structures,  Prev: Generating YAML to a File,  Up: Examples<182>

6.248.6.6 Working with Nested Structures
........................................

     ?- YAML = yaml([
          person-yaml([
            name-'Bob',
            age-25,
            skills-[logtalk, prolog, python]
          ])
        ]),
        generate(atom(Result), YAML).
     % Generates YAML representation of nested structure


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<80>,  Next: Supported YAML Features,  Prev: Examples<182>,  Up: yaml

6.248.7 Features
----------------

   - 'Scalar values': Supports atoms, numbers, booleans, and null

   - 'Collections': Supports lists (sequences) and mappings (objects)

   - 'Nested structures': Fully supports nested mappings and sequences

   - 'Comments': Handles YAML comments (lines starting with #)

   - 'Multiple source formats': Parse from files, streams, codes, chars,
     or atoms

   - 'Multiple output formats': Generate to files, streams, codes,
     chars, or atoms

   - 'Error handling': Provides appropriate error messages for invalid
     input


File: TheLogtalkHandbook-3.101.0.info,  Node: Supported YAML Features,  Next: Limitations<6>,  Prev: Features<80>,  Up: yaml

6.248.8 Supported YAML Features
-------------------------------

The library currently supports a subset of YAML 1.2 features suitable
for common configuration and data serialization tasks:

'Scalars'

   - Strings: unquoted, single-quoted (‘'...'’), and double-quoted
     (‘"..."’)

   - Multi-line flow scalars: quoted strings spanning multiple lines
     with proper line folding

        - Single newline becomes a space

        - Blank lines (consecutive newlines) become literal newlines

        - Leading/trailing whitespace around newlines is trimmed

   - Multi-word keys: keys containing spaces (e.g., ‘Mark McGwire: 65’)

   - Numbers:

        - Integers: decimal (‘42’), signed positive (‘+12345’), octal
          (‘0o14’), hexadecimal (‘0xC’)

        - Floats: decimal (‘3.14’), scientific notation (‘1.23e+3’)

        - Special values: ‘.inf’, ‘-.inf’, ‘.nan’ (represented as
          ‘'@'(inf)’, ‘'@'(-inf)’, ‘'@'(nan)’)

   - Booleans: ‘true’ and ‘false’

   - Null: ‘null’ or empty values

   - Timestamps: ISO 8601 dates and times (parsed as strings)

'Collections'

   - Block sequences: using ‘-’ indicator with proper indentation

   - Flow sequences: using ‘[ ]’ syntax with comma separation

   - Block mappings: using ‘key: value’ syntax with proper indentation

   - Flow mappings: using ‘{ key: value }’ syntax

   - Nested structures: arbitrary nesting of sequences and mappings

   - Trailing commas: supported in flow collections

'Block Scalars'

   - Literal block scalars: ‘|’ style preserves newlines exactly

   - Folded block scalars: ‘>’ style folds newlines into spaces

   - Chomping indicators: ‘-’ (strip), ‘+’ (keep), default (clip) for
     trailing newlines

   - More-indented lines: preserved with original indentation in folded
     scalars

   - Blank lines: preserved in both literal and folded block scalars

'Anchors and Aliases'

   - Anchor definitions: ‘&name’ to define a reusable node

   - Alias references: ‘*name’ to reference a previously defined anchor

   - Merge key: ‘<<’ to merge mappings from aliases

   - Works with scalars, sequences, and mappings

'Document Structure'

   - Document start marker: ‘---’ is recognized and skipped

   - Document end marker: ‘...’ is recognized and handled

   - Multi-document streams: multiple ‘---’ or ‘...’ separated documents
     (via ‘parse_all/2’)

   - Comments: lines starting with ‘#’ and inline comments after values

   - Tags: ‘!tag’, ‘!!type’, and ‘!<uri>’ tags are recognized and
     skipped

'Escape Sequences' (in double-quoted strings)

   - ‘\\’ - backslash

   - ‘\"’ - double quote

   - ‘\/’ - forward slash

   - ‘\n’ - newline

   - ‘\t’ - tab

   - ‘\r’ - carriage return

   - ‘\b’ - backspace

   - ‘\f’ - form feed

   - ‘\0’ - null character

   - ‘\xXX’ - hex escape (2 hex digits)

   - ‘\uXXXX’ - Unicode escape (4 hex digits)


File: TheLogtalkHandbook-3.101.0.info,  Node: Limitations<6>,  Next: Error Handling<4>,  Prev: Supported YAML Features,  Up: yaml

6.248.9 Limitations
-------------------

The following YAML features are 'not' currently supported:

   - Tag interpretation: Tags are recognized and skipped, but not
     interpreted

   - Complex keys: ‘?’ indicator for multi-line or complex keys

   - Multi-line plain scalars: plain scalars spanning multiple lines

   - Aliases in flow sequences: ‘[*alias1, *alias2]’ (aliases work in
     block context)

   - Merge with list of aliases: ‘<<: [*a, *b]’ (single alias merge
     works)

   - Directives: ‘%YAML’ and ‘%TAG’ directives


File: TheLogtalkHandbook-3.101.0.info,  Node: Error Handling<4>,  Next: File Organization,  Prev: Limitations<6>,  Up: yaml

6.248.10 Error Handling
-----------------------

The library raises the following errors:

   - ‘instantiation_error’ - when a required argument is a variable

   - ‘domain_error(yaml_source, Source)’ - when an invalid source is
     provided

   - ‘domain_error(yaml_sink, Sink)’ - when an invalid sink is provided

   - ‘domain_error(yaml_term, Term)’ - when an invalid YAML term is
     provided


File: TheLogtalkHandbook-3.101.0.info,  Node: File Organization,  Next: Test Files,  Prev: Error Handling<4>,  Up: yaml

6.248.11 File Organization
--------------------------

   - ‘yaml_protocol.lgt’ - Defines the protocol for YAML
     parser/generator

   - ‘yaml.lgt’ - Main implementation object

   - ‘loader.lgt’ - Library loader

   - ‘tester.lgt’ - Test runner

   - ‘test_files/’ - Directory containing test files and sample YAML
     files for testing


File: TheLogtalkHandbook-3.101.0.info,  Node: Test Files,  Next: Performance Considerations<2>,  Prev: File Organization,  Up: yaml

6.248.12 Test Files
-------------------

The library includes several sample YAML files for testing:

   - ‘simple.yaml’ - Simple key-value pairs

   - ‘list.yaml’ - A YAML list

   - ‘nested.yaml’ - Nested structures

   - ‘complex.yaml’ - Lists of mappings

   - ‘config.yaml’ - Configuration file example

   - ‘metadata.yaml’ - Metadata example with quoted strings


File: TheLogtalkHandbook-3.101.0.info,  Node: Performance Considerations<2>,  Next: Integration with Other Libraries,  Prev: Test Files,  Up: yaml

6.248.13 Performance Considerations
-----------------------------------

   - Parsing is done recursively, which may affect performance with
     deeply nested structures

   - Large YAML files are processed in memory

   - For very large files, consider splitting them into smaller chunks


File: TheLogtalkHandbook-3.101.0.info,  Node: Integration with Other Libraries,  Next: Future Enhancements,  Prev: Performance Considerations<2>,  Up: yaml

6.248.14 Integration with Other Libraries
-----------------------------------------

The YAML library can be integrated with other Logtalk libraries:

   - Use with ‘os’ library for file path handling

   - Use with ‘reader’ library for stream management

   - Compatible with ‘term_io’ library for term serialization


File: TheLogtalkHandbook-3.101.0.info,  Node: Future Enhancements,  Next: See Also,  Prev: Integration with Other Libraries,  Up: yaml

6.248.15 Future Enhancements
----------------------------

Potential future enhancements may include:

   - Support for tag interpretation (e.g., ‘!!binary’ for base64
     decoding)

   - Support for complex keys using ‘?’ indicator

   - Support for multi-line plain scalars

   - Aliases in flow sequences

   - Merge key with list of aliases

   - Parametric objects for custom representation choices


File: TheLogtalkHandbook-3.101.0.info,  Node: See Also,  Prev: Future Enhancements,  Up: yaml

6.248.16 See Also
-----------------

   - ‘json_lines’ library for JSON Lines format parsing and generation

   - Logtalk documentation on DCGs for grammar rules

   - YAML specification: ‘https://yaml.org’


File: TheLogtalkHandbook-3.101.0.info,  Node: z_score_anomaly_detector,  Next: zippers,  Prev: yaml,  Up: Libraries

6.249 ‘z_score_anomaly_detector’
================================

Statistical Z-score anomaly detector for continuous datasets.  It is a
statistical anomaly-detection method based on standard scores: the
detector estimates a population mean and standard deviation for each
continuous attribute and supports two learn-time score modes,
‘root_mean_square’ for dense multivariate deviation scores and
‘any_feature_extreme’ for the maximum absolute Z-score when sparse
single-feature anomalies are more informative.

The library implements the ‘anomaly_detector_protocol’ defined in the
‘anomaly_detection_protocols’ library.  It learns a detector from a
continuous dataset, computes anomaly scores for new instances, predicts
‘normal’ or ‘anomaly’, and exports learned detectors as clauses or
files.

Datasets are represented as objects implementing the
‘anomaly_dataset_protocol’ protocol from the
‘anomaly_detection_protocols’ library.  See the
‘anomaly_detection_protocols/test_datasets’ directory for examples.

* Menu:

* API documentation: API documentation<264>.
* Loading: Loading<268>.
* Testing: Testing<259>.
* Features: Features<81>.
* Options: Options<76>.
* Detector representation: Detector representation<8>.
* Notes: Notes<14>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<264>,  Next: Loading<268>,  Up: z_score_anomaly_detector

6.249.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#z-score’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<268>,  Next: Testing<259>,  Prev: API documentation<264>,  Up: z_score_anomaly_detector

6.249.2 Loading
---------------

To load this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(z_score_anomaly_detector(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<259>,  Next: Features<81>,  Prev: Loading<268>,  Up: z_score_anomaly_detector

6.249.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(z_score_anomaly_detector(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Features<81>,  Next: Options<76>,  Prev: Testing<259>,  Up: z_score_anomaly_detector

6.249.4 Features
----------------

   - 'Statistical method': implements anomaly detection based on
     standard scores, using the population mean and standard deviation
     of each continuous attribute to measure how far new observations
     deviate from the training data distribution.

   - 'Classical per-attribute Z-score': for each known attribute value
     ‘x’, the library computes the standard score ‘z = (x - mu) /
     sigma’, where ‘mu’ is the learned population mean for that
     attribute and ‘sigma’ is the learned population standard deviation.

   - 'Continuous features only': accepts datasets whose declared
     attributes are all ‘continuous’.

   - 'Population statistics': reuses the ‘statistics’ library
     ‘population’ object to compute per-attribute arithmetic means and
     standard deviations.

   - 'Baseline training selection': supports learn-time
     ‘baseline_class_values(ClassValues)’ and
     ‘baseline_selection_policy(Policy)’ options.  The default baseline
     class values are ‘[normal]’.  The default ‘reject’ policy throws an
     error if non-baseline examples are present, while ‘filter’ removes
     them before fitting.

   - 'Missing-value tolerant': ignores missing values when fitting
     attribute statistics.  During scoring, queries must provide at
     least one known value.  In the default
     ‘score_mode(root_mean_square)’, the raw score is normalized by the
     number of known values so that scores remain comparable across
     different missing-value patterns.

   - 'Configurable scoring semantics': supports both dense multivariate
     deviation scoring using ‘score_mode(root_mean_square)’ and sparse
     anomaly detection using ‘score_mode(any_feature_extreme)’.  The
     default root-mean-square mode reuses the ‘numberlist’ library
     Euclidean norm predicate as part of the computation.  The
     ‘score_mode/1’ option only controls how the per-attribute Z-scores
     are aggregated into a single raw anomaly score.

   - 'Bounded scoring': maps the raw multivariate Z-score to ‘[0.0,
     1.0)’ using ‘Score = Raw / (1 + Raw)’.

   - 'Default threshold': the default ‘anomaly_threshold(0.70)’ provides
     a practical out-of-the-box cutoff for the built-in anomaly fixtures
     while remaining overrideable in ‘learn/3’ and ‘predict/4’.

   - 'Learn-time score mode': ‘score_mode/1’ is recorded in the learned
     detector and reused for subsequent scoring and prediction.  Passing
     a ‘score_mode/1’ option to ‘predict/4’ does not override the
     learned mode.

   - 'All-missing queries rejected': scoring and prediction throw a
     ‘domain_error(non_empty_known_values, AttributeNames)’ exception
     when every declared feature is missing in the query.

   - 'Featureless datasets rejected': datasets must declare at least one
     continuous feature; otherwise ‘learn/2-3’ throws a
     ‘domain_error(non_empty_features, Dataset)’ exception.

   - 'Detector export': learned detectors can be exported as predicate
     clauses.

   - 'Explicit validation and diagnostics': supports the shared
     ‘check_anomaly_detector/1’, ‘valid_anomaly_detector/1’,
     ‘diagnostics/2’, ‘diagnostic/2’, and ‘anomaly_detector_options/2’
     predicates.


File: TheLogtalkHandbook-3.101.0.info,  Node: Options<76>,  Next: Detector representation<8>,  Prev: Features<81>,  Up: z_score_anomaly_detector

6.249.5 Options
---------------

The following options are supported by the public API:

   - ‘anomaly_threshold(Threshold)’: Threshold for ‘predict/3-4’
     (default: ‘0.70’)

   - ‘baseline_class_values(ClassValues)’: Learn-time class labels that
     are admissible for baseline fitting (default: ‘[normal]’)

   - ‘baseline_selection_policy(Policy)’: Learn-time handling of
     examples whose class is not listed in ‘baseline_class_values/1’.
     Supported values are ‘filter’ and ‘reject’ (default: ‘reject’)

   - ‘score_mode(Mode)’: Learn-time score aggregation mode for
     ‘learn/3’.  Supported values are ‘root_mean_square’ and
     ‘any_feature_extreme’ (default: ‘root_mean_square’).  If passed to
     ‘predict/4’, it is ignored and the value stored in the learned
     detector is used.


File: TheLogtalkHandbook-3.101.0.info,  Node: Detector representation<8>,  Next: Notes<14>,  Prev: Options<76>,  Up: z_score_anomaly_detector

6.249.6 Detector representation
-------------------------------

The learned detector is represented by default as:

     z_score_detector(TrainingDataset, Encoders, Diagnostics)

Where:

   - ‘TrainingDataset’: training dataset object identifier

   - ‘Encoders’: list of ‘zscore(Attribute, Mean, Scale)’ records

   - ‘Diagnostics’: learned metadata terms including ‘model/1’,
     ‘training_dataset/1’, ‘attribute_names/1’, ‘feature_count/1’,
     ‘example_count/1’, and ‘options/1’

When exported using ‘export_to_clauses/4’ or ‘export_to_file/4’, this
detector term is serialized directly as the single argument of the
generated predicate clause so that the exported model can be loaded and
reused as-is.


File: TheLogtalkHandbook-3.101.0.info,  Node: Notes<14>,  Prev: Detector representation<8>,  Up: z_score_anomaly_detector

6.249.7 Notes
-------------

Scoring has three stages.  First, the detector computes one classical
per-attribute Z-score for each known attribute value using ‘z = (x - mu)
/ sigma’.  Second, those per-attribute Z-scores are aggregated into a
single raw anomaly score according to the learned ‘score_mode/1’ option.
Third, the raw score is mapped to the interval ‘[0.0, 1.0)’ using ‘Score
= Raw / (1 + Raw)’.

With this normalization, a raw score of ‘3.0’ maps to ‘0.75’.

The ‘score_mode/1’ option does not change the classical per-attribute
formula.  It only changes the aggregation step.  With
‘score_mode(root_mean_square)’, the raw score is the root mean square of
the per-attribute Z-scores.  With ‘score_mode(any_feature_extreme)’, the
raw score is the maximum absolute per-attribute Z-score.

The ‘baseline_class_values/1’ option declares which dataset class labels
are admissible for fitting the baseline means and standard deviations.
The ‘baseline_selection_policy/1’ option then controls what happens when
other labels are present in the training data.  The default ‘reject’
policy raises a ‘domain_error(baseline_only_training_data, Dataset)’
exception when any non-baseline example is found.  The ‘filter’ policy
removes non-baseline examples before fitting.

Attributes with zero observed dispersion are assigned a fallback scale
of ‘1.0’.  This keeps the detector well-defined for singleton datasets
or constant columns while still yielding zero score for matching values
and positive scores for deviating values.

The root-mean-square aggregation keeps the default threshold stable as
the number of observed dimensions grows and avoids penalizing partially
observed queries solely for having fewer known attributes.

Use ‘score_mode(any_feature_extreme)’ when a single extreme feature
should be sufficient to flag an anomaly in high-dimensional data.


File: TheLogtalkHandbook-3.101.0.info,  Node: zippers,  Prev: z_score_anomaly_detector,  Up: Libraries

6.250 ‘zippers’
===============

This library implements zippers over lists.

* Menu:

* API documentation: API documentation<265>.
* Loading: Loading<269>.
* Testing: Testing<260>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<265>,  Next: Loading<269>,  Up: zippers

6.250.1 API documentation
-------------------------

Open the ‘../../apis/library_index.html#zippers’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<269>,  Next: Testing<260>,  Prev: API documentation<265>,  Up: zippers

6.250.2 Loading
---------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(zippers(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<260>,  Prev: Loading<269>,  Up: zippers

6.250.3 Testing
---------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(zippers(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Ports,  Next: Contributions,  Prev: Libraries,  Up: Top

7 Ports
*******

The documentation of each port can also be found in the port directory
in the ‘NOTES.md’ file.

* Menu:

* fcube::
* metagol::
* toychr::


File: TheLogtalkHandbook-3.101.0.info,  Node: fcube,  Next: metagol,  Up: Ports

7.1 ‘fcube’
===========

This folder contains a Logtalk port of FCube: An Efficient Prover for
Intuitionistic Propositional Logic available from:

     https://www.vidal-rosset.net/fCube/

The port includes portability changes (notably, operator names) plus
changes to use an ordered representation for sets.  Also some code
formatting changes for Logtalk coding guidelines.

The port tests are adapted from the examples available from the web page
above.

To load this port and for sample queries, please see the ‘SCRIPT.txt’
file.

For more information about FCube, see the following paper:

     @InProceedings{10.1007/978-3-642-16242-8_21,
         author="Ferrari, Mauro and Fiorentini, Camillo and Fiorino, Guido",
         editor="Ferm{\"u}ller, Christian G. and Voronkov, Andrei",
         title="fCube: An Efficient Prover for Intuitionistic Propositional Logic",
         booktitle="Logic for Programming, Artificial Intelligence, and Reasoning",
         year="2010",
         publisher="Springer Berlin Heidelberg",
         address="Berlin, Heidelberg",
         pages="294--301",
         isbn="978-3-642-16242-8"
     }

For sample queries, please see the ‘SCRIPT.txt’ file.

* Menu:

* API documentation: API documentation<266>.
* Loading: Loading<270>.
* Testing: Testing<261>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<266>,  Next: Loading<270>,  Up: fcube

7.1.1 API documentation
-----------------------

Open the ‘../../apis/library_index.html#fcube’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<270>,  Next: Testing<261>,  Prev: API documentation<266>,  Up: fcube

7.1.2 Loading
-------------

To load all entities in this port, load the ‘loader.lgt’ file:

     | ?- logtalk_load(fcube(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<261>,  Prev: Loading<270>,  Up: fcube

7.1.3 Testing
-------------

To test this port predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(fcube(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: metagol,  Next: toychr,  Prev: fcube,  Up: Ports

7.2 ‘metagol’
=============

This folder contains a Logtalk port of ‘metagol’, an inductive logic
programming (ILP) system based on meta-interpretive learning available
from:

     https://github.com/metagol/metagol

See the original code git repo for details and bibliography on Metagol
and ILP.

The port allows any number of datasets to be loaded simultaneously with
per-dataset learning options.  A dataset is simply wrapped in an object
that extends and is expanded by the ‘metagol’ object as illustrated by
the ported examples.

Both the original code and the port requires the coroutining ‘when/2’
predicate, which is only available in some backend Prolog systems.  The
port currently supports ECLiPSe, XVM, SICStus Prolog, SWI-Prolog, and
YAP. It can be used on both POSIX and Windows operating-systems.

The examples are ported from the original Metagol distribution.  Some of
the examples are taken from the following paper (with the original
Prolog examples source code files made available by MystikNinja):

     @article{DBLP:journals/jair/EvansG18,
         author    = {Richard Evans and Edward Grefenstette},
         title     = {Learning Explanatory Rules from Noisy Data},
         journal   = {J. Artif. Intell. Res.},
         volume    = {61},
         pages     = {1--64},
         year      = {2018},
         url       = {https://doi.org/10.1613/jair.5714},
         doi       = {10.1613/jair.5714},
         timestamp = {Mon, 21 Jan 2019 15:01:17 +0100},
         biburl    = {https://dblp.org/rec/bib/journals/jair/EvansG18},
         bibsource = {dblp computer science bibliography, https://dblp.org}
     }

The paper can be downloaded at

     https://arxiv.org/pdf/1711.04574.pdf

For sample queries, please see the ‘SCRIPT.txt’ file.

* Menu:

* API documentation: API documentation<267>.
* Loading: Loading<271>.
* Testing: Testing<262>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<267>,  Next: Loading<271>,  Up: metagol

7.2.1 API documentation
-----------------------

Open the ‘../../apis/library_index.html#metagol’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<271>,  Next: Testing<262>,  Prev: API documentation<267>,  Up: metagol

7.2.2 Loading
-------------

To load all entities in this port, load the ‘loader.lgt’ file:

     | ?- logtalk_load(metagol(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<262>,  Prev: Loading<271>,  Up: metagol

7.2.3 Testing
-------------

To test this port predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(metagol(tester)).

There are three lengthy tests that only run when the tests are being run
manually instead of automatically.


File: TheLogtalkHandbook-3.101.0.info,  Node: toychr,  Prev: metagol,  Up: Ports

7.3 ‘toychr’
============

This folder contains a Logtalk port of ToyCHR, a reference
implementation of Constraint Handling Rules (CHR) available from:

     https://www.comp.nus.edu.sg/~gregory/toychr/

The port is work in progress and includes significant modifications to
the original code:

   - Instead of compiling ‘.chr’ files, it uses the term-expansion
     mechanism, by defining ‘toychrdb’ as a hook object, to support
     writing rules inside objects and categories.  As a consequence, the
     original ‘chr_compile/1’ is not available.

   - The port is portable and should run on all supported backends.

The port also includes examples ported from the SWI-Prolog CHR package
examples and documentation.  These examples are ported using the same
license of the original code (BSD-2-Clause).

For sample queries, please see the ‘SCRIPT.txt’ file.

* Menu:

* API documentation: API documentation<268>.
* Loading: Loading<272>.
* Testing: Testing<263>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<268>,  Next: Loading<272>,  Up: toychr

7.3.1 API documentation
-----------------------

Open the ‘../../apis/library_index.html#toychr’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<272>,  Next: Testing<263>,  Prev: API documentation<268>,  Up: toychr

7.3.2 Loading
-------------

To load all entities in this port, load the ‘loader.lgt’ file:

     | ?- logtalk_load(toychr(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<263>,  Prev: Loading<272>,  Up: toychr

7.3.3 Testing
-------------

To test this port predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(toychr(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Contributions,  Next: Glossary,  Prev: Ports,  Up: Top

8 Contributions
***************

The documentation of contribution can also be found in the contribution
directory in the ‘NOTES.md’ file.

* Menu:

* flags::
* iso8601::
* pddl_parser::
* verdi_neruda::
* xml_parser::


File: TheLogtalkHandbook-3.101.0.info,  Node: flags,  Next: iso8601,  Up: Contributions

8.1 ‘flags’
===========

Flags was developed at Katholieke Universiteit Leuven

SPDX-FileCopyrightText: 2010 Katholieke Universiteit Leuven
SPDX-License-Identifier: Artistic-2.0

     Contributions to this file:
     Author: Theofrastos Mantadelis
     Suggestions: Paulo Moura
     Version: 1
     Date: 27/11/2010

* Menu:

* API documentation: API documentation<269>.
* Loading: Loading<273>.
* Testing: Testing<264>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<269>,  Next: Loading<273>,  Up: flags

8.1.1 API documentation
-----------------------

Open the ‘../../apis/library_index.html#flags’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<273>,  Next: Testing<264>,  Prev: API documentation<269>,  Up: flags

8.1.2 Loading
-------------

To load all entities in this library, load the ‘loader.lgt’ file:

     ?- logtalk_load(flags(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<264>,  Prev: Loading<273>,  Up: flags

8.1.3 Testing
-------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(flags(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: iso8601,  Next: pddl_parser,  Prev: flags,  Up: Contributions

8.2 ‘iso8601’
=============

ISO 8601 (and European civil calendar) compliant library of date and
time (clock) related predicates.  That is, an ISO 8601 handler.

The library supports date and time-of-day representations plus ISO 8601
duration and interval string conversions using ‘time_string/3’,
‘date_time_string/3’, ‘duration_string/2’, and ‘interval_string/2’.

Supported 'time-of-day strings' include basic and extended forms with
the required ‘T’ prefix, e.g.  ‘T143000’, ‘T14:30:00’, ‘T143000.125’,
‘T14:30:00.125’, ‘T143000,125’, and ‘T14:30:00,125’.

Supported 'combined date-time strings' include calendar-date,
ordinal-date, and complete week-date basic and extended forms with
optional UTC ‘Z’ or numeric offsets, using either ‘.’ or ‘,’ as
fractional separator, e.g.  ‘20260407T143000’, ‘2026-04-07T14:30:00’,
‘2026097T143000Z’, ‘2026-097T14:30:00+05:45’, ‘2026W152T143000Z’,
‘2026-W15-2T14:30:00+05:45’, ‘20260407T143000.125+0545’, and
‘2026-04-07T14:30:00,125Z’.

Normalized term shapes are:

   - ‘time(Hours,Minutes,Seconds)’ for time-of-day strings

   - ‘date_time(Year,Month,Day,Hours,Minutes,Seconds)’ for local
     date-time strings

   - ‘date_time(Year,Month,Day,Hours,Minutes,Seconds,OffsetSeconds)’ for
     UTC or offset date-time strings, using an offset in seconds from
     UTC

An 'ISO 8601 duration string' represents a time amount (e.g.  ‘P3D’ for
three days or ‘P1Y2M3DT4H5M6S’ for a mixed date/time duration).

An 'ISO 8601 interval string' represents a time interval using two parts
separated by ‘/’, where each part can be a date, a date-time, or a
duration (e.g.  ‘2026-02-25/2026-03-01’,
‘2026-04-07T14:30:00Z/2026-04-07T15:00:00Z’,
‘2026-097T14:30:00Z/2026-097T15:00:00Z’, ‘2026-W15-2T14:30:00Z/PT30M’,
or ‘2026-02-25/P3D’).

Author: Daniel L. Dudley Created: 2004-02-18

     Modified: 2014-09-26 (to use the ‘os’ library object to get the current date)
     Modified: 2026-02-25 (to add ‘duration_string/2’ and ‘interval_string/2’ predicates) Modified: 2026-04-07 (to add ‘time_string/3’ and ‘date_time_string/3’ predicates and extend ‘interval_string/2’, including ordinal-date and week-date date-time forms) Modified: 2026-04-08 (to add support for comma as fractional separator in ‘time_string/3’ and ‘date_time_string/3’ and for corresponding interval parsing)

* Menu:

* API documentation: API documentation<270>.
* Loading: Loading<274>.
* Testing: Testing<265>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<270>,  Next: Loading<274>,  Up: iso8601

8.2.1 API documentation
-----------------------

Open the ‘../../apis/library_index.html#iso8601’ link in a web browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<274>,  Next: Testing<265>,  Prev: API documentation<270>,  Up: iso8601

8.2.2 Loading
-------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(iso8601(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<265>,  Prev: Loading<274>,  Up: iso8601

8.2.3 Testing
-------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(iso8601(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: pddl_parser,  Next: verdi_neruda,  Prev: iso8601,  Up: Contributions

8.3 ‘pddl_parser’
=================

     PDDL 3.0 parser
     Release 1.0

Copyright (c) 2011 Robert Sasak.  All Rights Reserved.  This is free
software.  You can redistribute it and/or modify it under the terms of
the “Artistic License 2.0” as published by The Perl Foundation.  Consult
the “LICENSE.txt” file for details.

This PDDL 3.0 file parser converts PDDL files to Logtalk/Prolog friendly
syntax.  For example:

     PDDL         Prolog
     (on ?x ?y)   on(?x, ?y)

Syntax sugar: op(200, fy, ?).

For whole example check the “pddl.lgt” file for usage and example
output.

* Menu:

* API documentation: API documentation<271>.
* Loading: Loading<275>.
* Testing: Testing<266>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<271>,  Next: Loading<275>,  Up: pddl_parser

8.3.1 API documentation
-----------------------

Open the ‘../../apis/library_index.html#pddl_parser’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<275>,  Next: Testing<266>,  Prev: API documentation<271>,  Up: pddl_parser

8.3.2 Loading
-------------

To load all entities in this library, load the ‘loader.lgt’ file:

     ?- logtalk_load(pddl_parser(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<266>,  Prev: Loading<275>,  Up: pddl_parser

8.3.3 Testing
-------------

The provided unit tests are based on a collection of problem set files
from International Planning Competition 2008.  In order to run all unit
tests from the parser’s directory type:

     ?- logtalk_load(tester).

Or from any directory by typing:

     ?- logtalk_load(pddl_parser(tester)).

Some of the unit tests fail in some Prolog compilers due to limitations
to the maximum arity of a term.


File: TheLogtalkHandbook-3.101.0.info,  Node: verdi_neruda,  Next: xml_parser,  Prev: pddl_parser,  Up: Contributions

8.4 ‘verdi_neruda’
==================

     Verdi Neruda - Meta-interpreter collection for Prolog.
     Release 1.0

Copyright (c) 2010 Victor Lagerkvist.  All Rights Reserved.  Verdi
Neruda is free software.  You can redistribute it and/or modify it under
the terms of the simplified BSD license.

CONTENTS

  1. License

  2. About

  3. Verdi Neruda web site

  4. Installation and running

  5. Examples

  6. Authors

  7. LICENSE

Copyright 2010 Victor Lagerkvist.  All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

  1. Redistributions of source code must retain the above copyright
     notice, this list of conditions and the following disclaimer.

  2. Redistributions in binary form must reproduce the above copyright
     notice, this list of conditions and the following disclaimer in the
     documentation and/or other materials provided with the
     distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ‘’AS IS’’ AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

The views and conclusions contained in the software and documentation
are those of the authors and should not be interpreted as representing
official policies, either expressed or implied, of the copyright
holders.

  2. ABOUT

Verdi Neruda is a meta-interpreter collection for Prolog.  Or, to be
more precise, for a Prolog like language.  Or, to be pedantically
precise to the point that you are annoying people, it’s not really a
meta-interpreter collection at all since the interpreters themselves
aren’t interpreting the language that they are written in.  Let’s just
say that it is a collection of interpreters for a logic programming
language very much like pure Prolog with negation as finite failure.

Verdi Neruda is written entirely in Logtalk and compatible with most
major Prolog systems.  The name is sadly not a subtle wordplay or an
acronym, but was generated by a computer with the help of a soundex
algorithm.  The purpose of the interpreter suite was to compare top-down
methods to bottom-up methods and how resolution tree search rules
affected performance and completeness.  In the top-down family we find
such interpreters as the long-time standing champion depth-first, its
slow but orderly brother breadth-first and the youngster iterative
deepening.  A best-first framework can be found a stone throw away.
With it it’s possible to define interpreters that use greedy best-first
search as well as A* search.

In the bottom-up camp we find an interpreter that uses a semi naive
fixpoint construction.  Since bottom-up interpreters by their very
nature are not goal oriented a transformation technique called magic
transformation is used on logic programs before any inferences are made.
This technique allows the interpreter to only generate the facts that a
top-down interpreter would have used on the same logic program.

A shell akin to a Prolog top loop is also included.  It has commands
both for proving goals with an interpreter of choice and for
benchmarking logical inferences.  If Verdi Neruda is run with a Prolog
system that supports statistics/2 it’s possible to obtain statistics
such as CPU-time as well.

  3. VERDI NERUDA WEB SITE

Visit the Verdi Neruda GitHub www-page at:

‘https://github.com/Joelbyte/verdi-neruda’

  4. INSTALLATION AND RUNNING

Verdi Neruda requires Logtalk 2.40.0 or a later version.

To use the snapshot of Verdi Neruda bundled with Logtalk:

   - Start Logtalk.

   - Type ‘{verdi_neruda(loader)}.’ (Including ‘.’).

To use the latest version of Verdi Neruda, fetch the latest source code,
either as an archive or from the git repository, extract it to a
directory of your choice, and:

   - Start Logtalk from that directory.

   - Type ‘{loader}.’ (Including ‘.’).  If everything went according to
     the plan you should be greeted by the welcoming message.  If you
     replace the bundled version with the new one, you can use in
     alternative the steps above.

  5. EXAMPLES

Follow the previous instructions to get everything up and running.
First we’re going to run some predefined programs in the included
databases.  Begin by typing ‘databases.’ from the shell - this should
print a list of the currently loaded databases.  The demo database
‘demodb’ should be included in the list.  Next type ‘listing(demodb).’
to print the contents of the database.  The output should look something
like:

     append([],A,A) if
         true.
     append([A|B],C,[A|D]) if
         append(B,C,D).
     .
     .
     .

Which means that the ‘append/3’ program is loaded and ready for action.
Next we need to decide which interpreter to use.  Fortunately the shell
does not leave much to the imagination - as might be expected, the
‘interpreters.’ command prints the currently loaded interpreters.  The
list should look like:

     dfs_interpreter
     bfs_interpreter
     iddfs_interpreter(A)
     bup_interpreter
     a_star_interpreter(A)

The variables means that the interpreters are parametric objects and
that additional information is needed in order to run them.  The
iddfs-interpreter needs to know the increment and the A*-interpreter
needs to know what weight should be used when calculating the cost of
nodes.  To start with let’s use the dfs-interpreter and do something
exciting, namely appending two lists!

     prove(dfs_interpreter, append([a,b], [c,d], Xs), demodb).

The prove command takes three arguments.  The first is a interpreter,
the second the goal that shall be proved and the last the database that
the clauses are derived from.

To accomplish the same thing with the iddfs-interpreter with an
increment of 1 we need only type

     prove(iddfs_interpreter(1), append([a,b], [c,d], Xs), demodb).

The shell also has support for counting logical inferences.  To compare
the dfs- and iddfs-interpreter with the append program we could write:

     benchmark(dfs_interpreter, append([a,b,c,d],[e,f], Xs), demodb).  ->
     dfs_interpreter inferences: 5

     benchmark(iddfs_interpreter(1), append([a,b,c,d],[e,f], Xs), demodb).
     -> iddfs_interpreter(1) inferences: 15

For more information regarding the built in shell commands consult the
‘help.’ command.

  6. AUTHORS

The bulk of Verdi Neruda was written by Victor Lagerkvist during his
bachelor thesis at Linköping university in the spring of 2010.  Paulo
Moura also helped a great deal during the later stages of development,
especially with regards to compatibility between various Prolog systems.


File: TheLogtalkHandbook-3.101.0.info,  Node: xml_parser,  Prev: verdi_neruda,  Up: Contributions

8.5 ‘xml_parser’
================

This folder contains a Logtalk version of John Fletcher’s Prolog XML
parser:

‘https://binding-time.co.uk/index.php/Parsing_XML_with_Prolog’

For a detailed description of this XML parser, please see the comments
in the ‘xml.lgt’ source file or convert the automatically generated
documentation to HTML or PDF. For sample queries, please see the
‘SCRIPT.txt’ file.

See the copyright and license information on the contributed files for
usage and distributions conditions.

* Menu:

* API documentation: API documentation<272>.
* Loading: Loading<276>.
* Testing: Testing<267>.
* Known issues: Known issues<23>.


File: TheLogtalkHandbook-3.101.0.info,  Node: API documentation<272>,  Next: Loading<276>,  Up: xml_parser

8.5.1 API documentation
-----------------------

Open the ‘../../apis/library_index.html#xml_parser’ link in a web
browser.


File: TheLogtalkHandbook-3.101.0.info,  Node: Loading<276>,  Next: Testing<267>,  Prev: API documentation<272>,  Up: xml_parser

8.5.2 Loading
-------------

To load all entities in this library, load the ‘loader.lgt’ file:

     | ?- logtalk_load(xml_parser(loader)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Testing<267>,  Next: Known issues<23>,  Prev: Loading<276>,  Up: xml_parser

8.5.3 Testing
-------------

To test this library predicates, load the ‘tester.lgt’ file:

     | ?- logtalk_load(xml_parser(tester)).


File: TheLogtalkHandbook-3.101.0.info,  Node: Known issues<23>,  Prev: Testing<267>,  Up: xml_parser

8.5.4 Known issues
------------------

When using GNU Prolog as the backend compiler, you may need to to use a
larger default global stack size (see the GNU Prolog documentation on
the environment variable ‘GLOBALSZ’).


File: TheLogtalkHandbook-3.101.0.info,  Node: Glossary,  Next: Index<2>,  Prev: Contributions,  Up: Top

9 Glossary
**********

abstract class

     A *note class: 14c3. that cannot be instantiated by sending it a
     message.  Usually used to contain common predicates that are
     inherited by other classes.

abstract method

     A *note method: 14c5. implementing an algorithm whose step
     corresponds to calls to methods defined in the descendants of the
     object (or *note category: 14c6.) containing it.

adapter file

     A Prolog source file defining a minimal abstraction layer between
     the Logtalk compiler/runtime and a specific *note backend Prolog
     compiler: 34.

after method

     The *note predicate definition: 58. used to answer an ‘after’
     event.

ancestor

     A *note class: 14c3. or a parent *note prototype: 14c9. that
     contributes (via inheritance) to the definition of an object.  For
     class-based hierarchies, the ancestors of an instance are its
     class(es) and all the superclasses of its class(es).  For
     prototype-based hierarchies, the ancestors of a prototype are its
     parent(s) and the ancestors of its parent(s).

around method

     An overriding definition for a predicate that calls additional
     goals before and after a call to the overriden predicate
     definition.

backend Prolog compiler

     The Prolog compiler that is used to host and run Logtalk and that
     is called for compiling the intermediate Prolog code generated by
     the Logtalk compiler when compiling source files.

before method

     The *note predicate definition: 58. used to answer a ‘before’
     event.

built-in method

     A predefined *note method: 14c5. that can be called from within any
     object or *note category: 14c6.  I.e.  built-in methods are
     built-in object and category predicates.  Built-in methods cannot
     be redefined.

built-in predicate

     A predefined predicate that can be called from anywhere.  Built-in
     predicates can be redefined within *note objects: 534. and *note
     categories: 14c6.

category

     A set of *note predicates directives: 14ce. and clauses that can be
     (virtually) imported by any object.  Categories support composing
     objects using fine-grained units of code reuse and also *note hot
     patching: 10b. of existing objects.  A category should be
     functionally-cohesive, defining a single functionality.

class

     An *note object: 534. that specializes another object, interpreted
     as its *note superclass: 60.  A class defines the common predicates
     of a set of objects that instantiate it.  An object can also be
     interpreted as a class when it instantiates itself.

clause reference

     An opaque term that uniquely identifies a clause.  Provided by some
     backends via alternative database built-in predicates.

closed-world assumption

     The assumption that what cannot be proved true is false.
     Therefore, sending a *note message: 43. corresponding to a
     'declared' but not 'defined' predicate, or calling a declared
     predicate with no clauses, fails.  But messages or calls to
     undeclared predicates generate an error.

closure

     A callable term (i.e., an atom or a compound term) passed to a
     *note meta-predicate: 52. call where it is extended with additional
     arguments to form a goal called by the meta-predicate.

coinductive predicate

     A predicate whose calls are proved using greatest fixed point
     semantics.  Coinductive predicates allows reasoning about infinite
     rational entities such as cyclic terms and ω-automata.

complementing category

     A category used for *note hot patching: 10b. an existing object (or
     a set of objects).

component

     A unique atom or compound term template identifying a library,
     tool, application, or application sub-system.  Component names are
     notably used by the message printing and question asking
     mechanisms.  Compound terms are used instead of atoms when
     parameterization is required.

debug handler

     An object or category that defines clauses for the multifile
     predicates that handle the trace and debug events generated by the
     runtime.

directive

     A source file term that affects the interpretation of source code.
     Directives use the ‘(:-)/1’ prefix operator as functor.

discontiguous predicate

     A predicate whose clauses are not contiguous in a *note source
     file: 61d.  I.e.  a predicate whose clauses are mixed with clauses
     for other predicates.

doclet file

     A *note source file: 61d. whose main purpose is to generate
     documentation for a *note library: 6e. or an application.

doclet object

     An object specifying the steps necessary to (re)generate the API
     documentation for a project.  See the *note doclet: 32e. and *note
     lgtdoc: 323. tools for details.

dynamic binding

     Runtime lookup of a *note predicate declaration: 57. and *note
     predicate definition: 58. to verify the validity of a *note
     message: 43. (or a *note super call: 115.) and find the predicate
     definition that will be used to answer the message (or the super
     call).  Also known as 'late binding'.  See also *note static
     binding: 35.

dynamic entity

     See *note entity: 14d3.

dynamic predicate

     A predicate whose clauses can be dynamically added or retracted at
     runtime.

early binding

     See *note static binding: 35.

encapsulation

     The hiding of an object implementation.  This promotes software
     reuse by isolating the object clients from its implementation
     details.  Encapsulation is enforced in Logtalk by using *note
     predicate scope directives: 1e4.

entity

     Generic name for Logtalk compilation units: *note objects: 534,
     *note categories: 14c6, and *note protocols: 59.  Entities share a
     single namespace (i.e., entity *note identifiers: 14d6. must be
     unique) and can be static (the default) or dynamic.  Static
     entities are defined in source files.  Dynamic entities can also be
     defined in source files but are usually created and abolished at
     runtime using the language built-in predicates.

entity alias

     An alternative name for an entity.  Entity aliases can be defined
     using the *note uses/1: 4a. and *note use_module/1: 4c. directives.
     Entity aliases can be used to improve code clarity by using
     alternative names that are more meaningful in the calling context,
     to bind parametric entity parameters, and to simplify experimenting
     with alternative entities implementing the same protocol.

entity directive

     A directive that affects how Logtalk *note entities: 14d3. are used
     or compiled.

event

     The sending of a *note message: 43. to an object.  An event can be
     expressed as an ordered tuple: ‘(Event, Object, Message, Sender)’.
     Logtalk distinguishes between the sending of a message — ‘before’
     event — and the return of control to the sender — ‘after’ event.

expansion workflow

     A sequence of *note term-expansion: 14da. or *note goal-expansion:
     14db. steps where each step is usually defined using a *note hook
     object: 39f. or a combination of hook objects.

flaky test

     A test that can unpredictably succeed, fail, or throw an error and
     thus can yield different results when repeated without any code
     changes.  Can result from, e.g., race conditions or dependencies on
     external resources outside user control.

goal-expansion

     The transformation of a goal into another goal, defined by clauses
     for the *note goal_expansion/2: fd. predicate that is declared by
     the expanding(1) built-in protocol.  Goal-expansion is usually
     recursively applied at compile time until a fixed-point is reached
     (i.e., until the result of an expansion cannot be further
     expanded).  See also *note term-expansion: 14da. and *note
     expansion workflow: 14d9.

grammar rule

     An alternative notation for predicates used to parse or generate
     sentences in some language.  This notation hides the arguments used
     to pass the sequences of tokens being processed, thus simplifying
     the representation of grammars.  Grammar rules are represented
     using as functor the infix operator ‘(-->)/2’ instead of the
     ‘(:-)/2’ operator used with predicate clauses.

grammar rule non-terminal

     A syntactic category of words or phrases.  A non-terminal is
     identified by its 'non-terminal indicator', i.e.  by its name and
     number of arguments using the notation ‘Name//Arity’.

grammar rule terminal

     A word or basic symbol of a language.

homoiconic

     A property of programming languages where 'code' and 'data' use the
     same representation.  Logtalk (and Prolog) are examples of
     homoiconic programming languages.  A Logtalk program is a set of
     terms (clauses and directives) that can be handled as 'data' by
     e.g.  the *note term-expansion: 14da. mechanism.

hook object

     An object, implementing the expanding(2) built-in protocol,
     defining *note term-expansion: 14da. and *note goal-expansion:
     14db. predicates, used in the compilation of Logtalk or Prolog
     source files.  A hook object can be specified using the *note hook:
     fe. flag.  It can also be specified using a *note
     set_logtalk_flag/2: 50. directive in the source files to be
     expanded.

hook predicate

     A predicate, usually declared *note multifile: 16b, that allows the
     user to customize another predicate or provide alternative
     definitions for a default predicate definition.

hot patching

     The act of fixing *note entity directives: 14d7. and predicates or
     adding new entity directives and predicates to loaded *note
     entities: 14d3. in a running application without requiring access
     to the entities source code or restarting the application.
     Achieved using *note complementing categories: 14cf.

identity

     Property of an *note entity: 14d3. 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: 14c6. identifiers can be atoms or compound terms.
     Protocol identities must be atoms.  All Logtalk entities (objects,
     protocols, and categories) share the same namespace.

inheritance

     An *note entity: 14d3. inherits *note predicates directives: 14ce.
     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: 14e0, *note protected inheritance:
     14e1, and *note private inheritance: 14e2.

instance

     An *note object: 534. that instantiates another object, interpreted
     as its *note class: 14c3.  An object may instantiate multiple
     objects (also known as multiple instantiation).

instantiation

     The process of creating a new *note class: 14c3. *note instance:
     14e3.  In Logtalk, this does not necessarily imply dynamic creation
     of an object at runtime; an instance may also be defined as a
     static object in a source file.

interface

     See *note protocol: 59.

lambda expression

     A compound term that can be used in place of a goal or *note
     closure: 14f. meta-argument and that abstracts a *note predicate
     definition: 58. by listing its variables and a callable term that
     implements the definition.  Lambda expressions help avoid the need
     of naming and defining auxiliary predicates.

lambda free variable

     A variable that is global to a *note lambda expression: 182.  All
     used global variables must be explicitly listed in a lambda
     expression for well-defined semantics.

lambda parameter

     A term (usually a variable or a non-ground compound term) that is
     local to a *note lambda expression: 182.  All lambda parameters
     must be explicitly enumerated in a lambda expression for
     well-defined semantics.

late binding

     See *note dynamic binding: 36.

library

     A directory containing source files.  See also *note library alias:
     14e7. and *note library notation: 2a8.

library alias

     An atom that can be used as an alias for a *note library: 6e. full
     path.  Library aliases and their corresponding paths can be defined
     using the *note logtalk_library_path/2: 2a7. predicate.  See also
     *note library notation: 2a8.

library notation

     A compound term where the name is a *note library alias: 14e7. and
     the single argument is a *note source file: 61d. 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: 61d. whose main purpose is to load a set of
     source files (possibly with specific compiler flags) and any
     library dependencies.

local predicate

     A predicate that is defined in an object (or in a *note category:
     14c6.) but that is not listed in a *note scope directive: 1e4.
     These predicates behave like private predicates but are invisible
     to the reflection *note built-in methods: 14cc.  Local predicates
     are usually auxiliary predicates and only relevant to the entity
     where they are defined.

message

     A query sent to an object.  In logical terms, a message can be
     interpreted as a request for proof construction using an object
     database and the databases of related entities.

message lookup

     Sending a message to an object requires a lookup for the *note
     predicate declaration: 57, to check if the message is within the
     scope of the sender, and a lookup for the *note predicate
     definition: 58. that is going to be called to answer the message.
     Message lookup can occur at *note compile: 35. time or at *note
     runtime: 36.

message to self

     A message sent to the object that received the original message
     under processing.  Messages to self require *note dynamic binding:
     36. as the value of self is only know at runtime.

meta-argument

     A predicate argument that is called as a goal, used as a *note
     closure: 14f. to construct a goal that will be called, or that is
     handled in a way that requires awareness of the predicate calling
     context.

meta-interpreter

     A program capable of running other programs written in the same
     language.

meta-predicate

     A predicate with one or more *note meta-arguments: 14e8.  For
     example, *note call/1-N: 181. and *note findall/3: 1c0. are
     built-in meta-predicates.

meta-variable

     A variable in a *note meta-argument: 14e8. position that is
     expected to be unified with a goal or a closure at runtime.

metaclass

     The *note class: 14c3. of a class, when interpreted as an *note
     instance: 14e3.  Metaclass instances are themselves classes.
     Metaclasses are optional, except for the root class, and can be
     shared by several classes.

method

     The *note predicate definition: 58. used to answer a *note message:
     43. sent to an object.  Logtalk supports both *note static binding:
     35. and *note dynamic binding: 36. to find which method to run to
     answer a message.  See also *note built-in method: 14cc.

mocking

     Techniques used to replace dependencies in the code being tested
     with controlled substitutes, simplifying testing.  Can be
     accomplished using, e.g., *note term-expansion: 14da, hot patching,
     or message interception.

module

     A Prolog entity characterized by an identity and a set of *note
     predicates directives: 14ce. and clauses.  Prolog modules are
     usually static although some Prolog systems allow the creation of
     dynamic modules at runtime.  Prolog modules can be interpreted as
     *note prototypes: 14c9.

monitor

     Any object, implementing the monitoring(3) built-in protocol, that
     is notified by the runtime when a spied event occurs.  The spied
     *note events: 14d8. 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: 14d3. and *note source files: 61d.  The object or
     category holding the directive without an entity prefix qualifying
     the predicate holds the multifile predicate 'primary declaration',
     which consists of both a *note scope directive: 1e4. and a *note
     multifile/1: 16c. directive for the predicate.

naked meta-variable

     A *note meta-variable: 183. used as the body of a predicate clause
     or grammar rule or used in a cut-transparent argument of a control
     construct.  The “naked” designation highlights that the
     meta-variable is not wrapped by ‘call/1’ or ‘phrase//1’ goals.

object

     An entity characterized by an *note identity: 14d6. and a set of
     *note predicates directives: 14ce. and clauses.  Logtalk objects
     can be either static or dynamic.  Logtalk objects can play the
     'role' of classes, instances, or prototypes.  The role or roles an
     object plays are a function of its relations with other objects.

object database

     The set of predicates locally defined inside an object.

parameter

     An argument of a parametric object or a parametric category
     identifier.  Parameters are 'logical variables' implicitly shared
     by all the entity directives and predicate clauses.

parameter variable

     A variable used as parameter in a parametric object or a parametric
     category using the syntax ‘_ParameterName_’ (i.e., a variable whose
     name stars and ends with an underscore).  Parameter variables are
     'logical variables' shared by all entity terms.  Occurrences of
     parameter variables in *note entity directives: 14d7. and clauses
     are implicitly unified with the corresponding entity parameters.

parametric category

     See *note parametric entity: 6a1.

parametric entity

     An *note object: 534. or *note category: 14c6. whose *note
     identifier: 14d6. 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: 6a1.

parametric object proxy

     A compound term (usually represented as a plain Prolog fact) with
     the same name and number of arguments as the identifier of a
     parametric object.

parent

     A *note prototype: 14c9. that is extended by another prototype.

polymorphism

     Different objects (and categories) can provide different
     implementations of the same predicate.  The predicate declaration
     can be inherited from a common ancestor, also known as 'subtype
     polymorphism'.  Logtalk implements 'single dispatch' on the
     receiver of a message, which can be described as 'single-argument
     polymorphism'.  As *note message lookup: 37. only uses the
     predicate functor, multiple predicate implementations for different
     types of arguments are possible, also known as 'ad hoc
     polymorphism'.  *note Parametric objects and categories: 6a1.
     enable implementation of 'parametric polymorphism' by using one or
     more parameters to pass object identifiers that can be used to
     parameterize generic predicate definitions.

predicate

     Predicates describe what is true about the application domain.  A
     predicate is identified by its 'predicate indicator', i.e.  by its
     name and number of arguments using the notation ‘Name/Arity’.  See
     also *note built-in predicate: 14cd. and *note method: 14c5.

predicate alias

     An alternative functor (‘Name/Arity’) for a predicate.  Predicate
     aliases can be defined for any inherited predicate using the *note
     alias/2: 165. directive and for predicates listed in *note uses/2:
     4b. and *note use_module/2: 4d. directives.  Predicate aliases can
     be used to solve inheritance conflicts, to improve code clarity by
     using alternative names that are more meaningful in the calling
     context, and to use a different order of the predicate arguments.

predicate calling context

     The object or category from within a predicate is called (either
     directly or using a control construct such as a message-sending
     control construct).

predicate declaration

     A predicate declaration is composed by a set of *note predicates
     directives: 14ce, which must include at least a *note scope
     directive: 1e4.

predicate definition

     The set of clauses for a predicate, contained in an object or
     category.  Predicate definitions can be overridden or specialized
     in descendant entities.

predicate definition context

     The object or category that contains the definition (i.e., clauses)
     for a predicate.

predicate directive

     A directive that specifies a predicate property that affects how
     predicates are called or compiled.

predicate execution context

     The implicit arguments (including *note sender: 39a, *note self:
     69, and *note this: 114.) required for the correct execution of a
     predicate call.

predicate scope container

     The object that inherits a *note predicate declaration: 57. from an
     imported *note category: 14c6. or an implemented *note protocol:
     59.

predicate scope directive

     A directive that declares a predicate by specifying its visibility
     as 'public', 'protected', or 'private'.

predicate shorthand

     A *note predicate alias: ca. that defines a call template, possibly
     using a different name, with a reduced number of arguments by
     hard-coding the value of the omitted arguments in the original call
     template.  Predicate shorthands can be defined using *note uses/2:
     4b. and *note use_module/2: 4d. directives.  They can be used to
     simplify predicate calls and to ensure consistent call patterns
     when some of the arguments always use the same fixed values in the
     calling context.

primary predicate declaration

     See *note multifile predicate: 16b.

private inheritance

     All public and protected predicates are inherited as private
     predicates.  See also *note public inheritance: 14e0. and *note
     protected inheritance: 14e1.

private predicate

     A predicate that can only be called from the object that contains
     its *note scope directive: 1e4.

profiler

     A program that collects data about other program performance.

protected inheritance

     All public predicates are inherited as protected.  No scope change
     for protected or private predicates.  See also *note public
     inheritance: 14e0. and *note private inheritance: 14e2.

protected predicate

     A predicate that can only be called from the object containing its
     *note scope directive: 1e4. or from an object that inherits the
     predicate.

protocol

     An entity that contains *note predicate declarations: 57.  A
     predicate is declared using a *note scope directive: 1e4.  It may
     be further specified by additional predicate directives.  Protocols
     support the separation between interface and implementation, can be
     implemented by both objects and categories, and can be extended by
     other protocols.  A protocol should be functionally-cohesive,
     specifying a single functionality.  Also known as 'interface'.

prototype

     A self-describing *note object: 534. that may extend or be extended
     by other objects.  A prototype typically describes a concrete
     object instead of an abstraction of a set of objects.  An object
     with no instantiation or specialization relations with other
     objects is always interpreted as a prototype.

public inheritance

     All inherited predicates maintain their declared scope.  See also
     *note protected inheritance: 14e1. and *note private inheritance:
     14e2.

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: 61d.

self

     The object that received the *note message: 43. under processing.

sender

     An object that sends a *note message: 43. to other object.  When a
     message is sent from within a *note category: 14c6, the 'sender' is
     the object importing the category on which behalf the message was
     sent.

settings file

     A *note source file: 61d, compiled and loaded automatically by
     default at Logtalk startup, mainly defining default values for
     compiler flags that override the defaults found on the backend
     Prolog compiler *note adapter files: 154.

singleton method

     A *note method: 14c5. defined in an *note instance: 14e3. itself.
     Singleton methods are supported in Logtalk and can also be found in
     other object-oriented programming languages.

source file

     A text file defining Logtalk and/or Prolog code.  Multiple Logtalk
     entities may be defined in a single source file.  Plain Prolog code
     may be intermixed with Logtalk entity definitions.  Depending on
     the used *note backend Prolog compiler: 34, the text encoding may
     be specified using an *note encoding/1: 298. directive as the first
     term in the first line in the file.

source file directive

     A *note directive: 14d0. that affects how a *note source file: 61d.
     is compiled.

specialization

     A *note class: 14c3. is specialized by defining a new class that
     inherits its predicates and possibly adds new ones.

static binding

     Compile time lookup of a *note predicate declaration: 57. and *note
     predicate definition: 58. when compiling a *note message: 43.
     sending call (or a *note super call: 115.).  Dynamic binding is
     used whenever static binding is not possible (e.g., due to the
     predicate being dynamic or due to lack of enough information at
     compilation time).  Also known as 'early binding'.  See also *note
     dynamic binding: 36.

static entity

     See *note entity: 14d3.

steadfastness

     A predicate definition is 'steadfast' when it still generates only
     correct answers when called with unexpectedly bound arguments
     (notably, bound output arguments).  Typically, a predicate may not
     be steadfast when output argument unifications can occur before a
     cut in a predicate clause body.

subclass

     A *note class: 14c3. that is a specialization, direct or
     indirectly, of another class.  A class may have multiple
     subclasses.

super call

     Call of an inherited (or imported) *note predicate definition: 58.
     Mainly used when redefining an inherited (or imported) predicate to
     call the overridden definition while making additional calls.
     Super calls preserve *note self: 69. and may require *note dynamic
     binding: 36. if the predicate is dynamic.

superclass

     A *note class: 14c3. 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: 14c4.

term-expansion

     The transformation of a term (usually a directive or a clause) into
     another term or a list of terms, defined by clauses for the *note
     term_expansion/2: fc. predicate that is declared by the
     expanding(4) built-in protocol.  Term-expansion is usually applied
     at compile time once (i.e., the result of an expansion is not
     further expanded).  See also *note goal-expansion: 14db. and *note
     expansion workflow: 14d9.

test dialect

     Predicate syntax for defining a test.  I.e., the predicate name;
     the number, syntax, and semantics of the predicate arguments; and
     the syntax and semantics of any options.

test outcome

     The expected result of a test goal.  E.g., success, failure, an
     error, deterministic success, success with bindings that subsume or
     are a variant of specific terms.

tester file

     A *note source file: 61d. 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: 14c6,
     'this' is a reference to the object importing the category on which
     behalf the predicate clause is being used to prove the current
     goal.

threaded engine

     A computing thread running a goal whose solutions can be lazily and
     concurrently computed and retrieved.  A threaded engine also
     supports a term queue that allows passing arbitrary terms to the
     engine.  This queue can be used to pass e.g.  data and new goals to
     the engine.

top-level interpreter shorthand

     Aliases for frequently used built-in predicates such as *note
     logtalk_load/1: 46. and *note logtalk_make/1: 2a0.  These
     shorthands are 'not' part of the Logtalk language and must only be
     used at the top-level interpreter.

visible predicate

     A predicate that is within scope, a locally defined predicate, a
     *note built-in method: 14cc, a Logtalk built-in predicate, or a
     Prolog built-in predicate.

(Alexiev93) Mutable Object State for Object-Oriented Logic Programming:
A Survey Alexiev, V. Technical Report TR 93-15, Department of Computing
Science, University of Alberta, Canada

(Belli_et_al_92) Object-oriented programming in Prolog: rationale and a
case study Belli, F., Jack, O., Naish, L. Technical Report 92/2,
Department of Electrical and Electronics Engineering, University of
Paderborn, Germany URL:
‘https://lee-naish.github.io/papers/oolp/index.html’

(Block89) An Extended Frame Language Block, F. P., Chan, N. C.
Proceedings OOPLSLA 89(10):151-157, ACM

(Bobrow_et_al_88) Common Lisp Object System Specification Bobrow, D. G.,
Michiel, L. G., Gabriel, R. P., Keene, S. E., Kiczales, G., Moon, D. A.
ACM SIGPLAN Notices(23)

(Bratko90) Prolog Programming for Artificial Intelligence Bratko, I.
Addison Wesley, 2º edition, 1990

(Champaux92) A comparative Study of Object-Oriented Analysis Methods
Champaux, D., Faure, P. Journal of Object-Oriented Programming, Vol.  5,
N.1, 1992

(Clocksin87) Programming in Prolog Clocksin, W.F., Mellish, C.S.
Springer-Verlag, New York, 1987

(Cointe87) Metaclasses are First Class: the ObjVlisp Model Cointe, P.
Proceedings OOPLSLA 87(10):156-167, ACM

(Cordes91) The Literate Programming Paradigm Cordes, D., Brown, M. IEEE
Computer, June 1991:52-61

(Covington94) ISO Prolog: A Summary of the Draft Proposed Standard
Covington, M. A. URL: ‘ftp://ai.uga.edu/pub/prolog.standard/’

(Cox86) Object-Oriented Programming: An Evolutionary Approach Cox, Brad
J. Addison-Wesley Publishing Company, Don Mills, Ontario

(Davison89) Polka: A Parlog Object oriented language Davison, A. Ph.D.
Thesis, Imperial College, London, 1989

(Davison92) A survey of logic programming-based object oriented
languages Davison, A. Tech Report 92/3, Dept.  of Computer Science,
University of Melbourne, Australia URL:
‘https://catalogue.nla.gov.au/catalog/772526’

(Davison93) The deductive and object oriented features of BeBOP Davison,
A. Tech Report 93/6, Dept.  of Computer Science, University of
Melbourne, Australia URL: ‘https://catalogue.nla.gov.au/catalog/1273317’

(Delzanno97) Logic and Object-Oriented Programming in Linear Logic
Delzanno, G. Ph.D. Thesis, University of Pisa, Italy URL:
‘https://opac.bncf.firenze.sbn.it/Record/BVE0136144?uri=BVE0136144’

(Dony90) Exception Handling and Object-Oriented Programming: Towards a
Synthesis Dony, C. Proceedings OOPLSLA 90:322-330, ACM

(Fornarino_et_al_89) An Original Object-Oriented Approach for Relation
Management Fornarino, M., Pinna, A.-M.,Trousse, B. Proceedings of the
4th Portuguese Conference on Artificial Intelligence Lecture Notes in
Artificial Intelligence, Springer-Verlag (390):13-26

(Fromherz93) OL(P): Object Layer for Prolog Fromherz, M. URL:
‘ftp://parcftp.xerox.com/ftp/pub/ol/’

(Fukunaga86) An Experience with a Prolog-based Object-Oriented Language
Fukunaga, K., Hirose, S. Proceedings OOPLSLA 86, 21(11):224-231, ACM

(Goldberg83) Smalltalk-80 The language and its implementation Goldberg,
A., Robson, D. Addison-Wesley Series in Computer Science

(Joy_et_al_00) The Java Language Specification, Second Edition Joy, B.,
Steele, G., Gosling, J., Bracha, G. Addison-Wesley, 2000

(ISO95) ISO/IEC DIS 13211-1 - Programming Language Prolog Part 1:
General Core Joint Technical Committee ISO/IEC JTC 1 URL:
‘https://www.iso.org/standard/21413.html’

(Knuth84) Literate Programming Knuth, D. E. Computer Journal, May 84,
27(2):97-111

(Lieberman86) Using Prototypical Objects to Implement Shared Behaviour
in Object Oriented Systems Lieberman, H. Proceedings OOPLSLA 86:189-214,
ACM

(Maes87) Concepts and Experiments in Computational Reflection Maes, P.
Proceedings OOPLSLA 87, ACM

(McCabe92) Logic and Objects McCabe, F. G. Prentice Hall Series in
Computer Science

(Moon86) Object-Oriented Programming in Flavors Moon, D. Proceedings
OOPLSLA 86:1-8, ACM

(Moss94) Prolog++ The Power of Object-Oriented and Logic Programming
Moss, C. Addison-Wesley International Series in Logic Programming, 1994

(Moura94) Logtalk: Programação Orientada para Objectos em Prolog Moura,
P., Costa, E. 2ª Conferência e Exposição Portuguesa de Tecnologia
Orientada por Objectos 3i Consultores, Lisboa

(Moura99) Porting Prolog: Notes on porting a Prolog program to 22 Prolog
compilers or the relevance of the ISO Prolog standard Moura, P. ALP
Newsletter, Vol.  12/2, May 1999

(Moura00) Logtalk 2.6 Documentation Moura, P. Technical Report DMI
2000/1 University of Beira Interior, Portugal

(Razek92) Combining Objects and Relations Razek, G. Communications of
the ACM, 27(12):66-70

(Rumbaugh87) Relations as Semantic Constructs in an Object-Oriented
Language Rumbaugh, J. Proceedings OOPLSLA 87:466-481, ACM

(Rumbaugh88) Controlling Propagation of Operations using Attributes on
Relations Rumbaugh, J. Proceedings OOPLSLA 88:285-296, ACM

(Schachte95) Efficient Object-Oriented Programming in Prolog Schachte,
P., Saab, G. Logic Programming: Formal Methods and Pratical Applications
Studies in Computer Science and Artificial Intelligence, 11 Elsevier
Science B.V. North-Holland, Amsterdam, 1995

(SICStus95) SICStus Prolog Manual SICStus URL: ‘https://sicstus.sics.se’

(Shan_et_al_93) Is Multiple Inheritance Essential to OOP? (Panel) Shan,
Y., Cargill, T., Cox, B., Cook, W., Loomis, M., Snyder, A. Proceedings
OOPLSLA 93:360-363

(Stefik_et_al_86) Integrating Acess-Oriented Programming into a
Multiparadigm Environment Stefik, M. J., Bobrow, D. G. , Kahn, K. M.
IEEE Software, January 1986:10-18

(Stroustrup86) The C++ Programming Language Stroustrup, B.
Addison-Wesley Series in Computer Science

(Taenzer89) Problems in Object-Oriented Software Reuse Taenzer, D.,
Ganti, M., Podar, S. Proceedings of ECOOP 89 British Computer Society
Workshop Series, Cambridge University Press

(Tanzer95) Remarks on Object-Oriented Modeling of Associations Tanzer,
C. Journal of Object-Oriented Programming, February 1995, SIGS
Publications

(Tanenbaum87) Operating Systems - Design and Implementation Tanenbaum,
A. Prentice-Hall Software Series, 1987

(Welsch89) Reasoning Objects with Dynamic Knowledge Bases Welsch, C.,
Barth, G. Proceedings of the 4th Portuguese Conference on Artificial
Intelligence(390):257-268 Lecture Notes in Artificial Intelligence,
Springer-Verlag, 1989

   ---------- Footnotes ----------

   (1) ../apis/expanding_0.html#expanding-0

   (2) ../apis/expanding_0.html#expanding-0

   (3) ../apis/monitoring_0.html#monitoring-0

   (4) ../apis/expanding_0.html#expanding-0


File: TheLogtalkHandbook-3.101.0.info,  Node: Index<2>,  Next: Index,  Prev: Glossary,  Up: Top

10 Index
********


File: TheLogtalkHandbook-3.101.0.info,  Node: Index,  Prev: Index<2>,  Up: Top

Index
*****

[index]
* Menu:

* !/0; Built-in method:                  Logic and control.   (line   8)
* (;;)/1; Control construct:             Examples<2>.         (line  19)
* (;;)/2; Control construct:             Message sending<2>.  (line   8)
* (@)/1; Control construct:              Calling predicates in this.
                                                              (line   8)
* (\+)/1; Built-in method:               Examples<122>.       (line  19)
* (^^)/1; Control construct:             Calling imported and inherited predicates<2>.
                                                              (line   8)
* (<<)/2; Control construct:             Context switching calls.
                                                              (line   8)
* []/1; Control construct:               Message delegation.  (line   8)
* {}/1; Control construct:               Calling external predicates.
                                                              (line   8)
* abolish_category/1; Built-in predicate: Abolishing objects categories and protocols.
                                                              (line   8)
* abolish_events/5; Built-in predicate:  Event handling<2>.   (line   8)
* abolish_object/1; Built-in predicate:  Examples<55>.        (line  16)
* abolish_protocol/1; Built-in predicate: Examples<56>.       (line  17)
* abolish/1; Built-in method:            Database.            (line   8)
* abstract class:                        Glossary.            (line   6)
* abstract method:                       Glossary.            (line  10)
* adapter file:                          Glossary.            (line  16)
* after method:                          Glossary.            (line  22)
* after/3; Built-in method:              Examples<143>.       (line  22)
* alias/2; Directive:                    Predicate directives<2>.
                                                              (line   8)
* always_true_or_false_goals; Flag:      Lint flags.          (line  83)
* ancestor:                              Glossary.            (line  27)
* arithmetic_expressions; Flag:          Lint flags.          (line  96)
* around method:                         Glossary.            (line  36)
* ask_question/5; Built-in method:       Question asking.     (line   8)
* asserta/1; Built-in method:            Examples<114>.       (line  21)
* assertz/1; Built-in method:            Examples<115>.       (line  60)
* backend Prolog compiler:               Glossary.            (line  42)
* bagof/3; Built-in method:              All solutions.       (line   8)
* before method:                         Glossary.            (line  48)
* before/3; Built-in method:             Event handling<3>.   (line   8)
* begin_of_file:                         Hook objects.        (line  89)
* behavioral reflection:                 Black-box view.      (line  18)
* black-box view:                        Transparent-box view.
                                                              (line  31)
* built_in/0; Directive:                 Entity directives.   (line   8)
* built-in method:                       Glossary.            (line  53)
* built-in predicate:                    Glossary.            (line  60)
* call//1-N; Built-in method:            Definite clause grammar rules<2>.
                                                              (line   8)
* call/1-N; Built-in method:             Meta-calls.          (line   8)
* catch/3; Built-in method:              Error handling<2>.   (line   8)
* catchall_catch; Flag:                  Lint flags.          (line 171)
* category:                              Glossary.            (line  66)
* category_property/2; Built-in predicate: Enumerating objects categories and protocols properties.
                                                              (line   8)
* category/1-4; Directive:               Examples<18>.        (line   9)
* class:                                 Glossary.            (line  74)
* clause reference:                      Glossary.            (line  81)
* clause/2; Built-in method:             Examples<116>.       (line  60)
* clean; Flag:                           Other flags.         (line 108)
* closed-world assumption:               Glossary.            (line  86)
* closure:                               Glossary.            (line  94)
* code_prefix; Flag:                     Other flags.         (line  29)
* coinduction; Flag:                     Read-only flags.     (line  94)
* coinductive predicate:                 Glossary.            (line 100)
* coinductive_success_hook/1-2; Built-in method: Coinduction hooks.
                                                              (line   8)
* coinductive/1; Directive:              Examples<30>.        (line  19)
* complementing category:                Glossary.            (line 106)
* complements_object/2; Built-in predicate: Examples<62>.     (line  25)
* complements; Flag:                     Optional features compilation flags.
                                                              (line   6)
* component:                             Glossary.            (line 111)
* conditionals; Flag:                    Lint flags.          (line 163)
* conforms_to_protocol/2-3; Built-in predicate: Examples<61>. (line  25)
* consistency_error/3; Built-in method:  Examples<129>.       (line  23)
* context_switching_calls; Flag:         Optional features compilation flags.
                                                              (line  41)
* context/1; Built-in method:            Execution context.   (line   8)
* create_category/4; Built-in predicate: Creating new objects categories and protocols.
                                                              (line   8)
* create_logtalk_flag/3; Built-in predicate: Examples<98>.    (line  16)
* create_object/4; Built-in predicate:   Examples<52>.        (line  21)
* create_protocol/3; Built-in predicate: Examples<53>.        (line  63)
* current_category/1; Built-in predicate: Enumerating objects categories and protocols.
                                                              (line   8)
* current_event/5; Built-in predicate:   Examples<67>.        (line  17)
* current_logtalk_flag/2; Built-in predicate: Flags.          (line   8)
* current_object/1; Built-in predicate:  Examples<46>.        (line  20)
* current_op/3; Built-in method:         Reflection<2>.       (line   8)
* current_predicate/1; Built-in method:  Examples<111>.       (line  20)
* current_protocol/1; Built-in predicate: Examples<47>.       (line  22)
* debug handler:                         Glossary.            (line 119)
* debug; Flag:                           Other flags.         (line  73)
* define_events/5; Built-in predicate:   Examples<68>.        (line  16)
* deprecated; Flag:                      Lint flags.          (line  58)
* directive:                             Glossary.            (line 125)
* discontiguous predicate:               Glossary.            (line 130)
* discontiguous/1; Directive:            Examples<31>.        (line  17)
* disjunctions; Flag:                    Lint flags.          (line 155)
* doclet file:                           Glossary.            (line 136)
* doclet object:                         Glossary.            (line 141)
* domain_error/2; Built-in method:       Examples<128>.       (line  22)
* duplicated_clauses; Flag:              Lint flags.          (line 146)
* duplicated_directives; Flag:           Lint flags.          (line  69)
* dynamic binding:                       Glossary.            (line 147)
* dynamic entity:                        Glossary.            (line 156)
* dynamic predicate:                     Glossary.            (line 160)
* dynamic_declarations; Flag:            Optional features compilation flags.
                                                              (line  19)
* dynamic/0; Directive:                  Examples<19>.        (line  27)
* dynamic/1; Directive:                  Examples<32>.        (line  13)
* early binding:                         Glossary.            (line 165)
* elif/1; Directive:                     Examples<14>.        (line  42)
* else/0; Directive:                     Examples<15>.        (line  26)
* encapsulation:                         Glossary.            (line 169)
* encoding_directive; Flag:              Read-only flags.     (line  52)
* encoding/1; Directive:                 Source file directives<2>.
                                                              (line   8)
* encodings; Flag:                       Lint flags.          (line 195)
* end_category/0; Directive:             Examples<20>.        (line  15)
* end_object/0; Directive:               Examples<21>.        (line  14)
* end_of_file:                           Hook objects.        (line  89)
* end_protocol/0; Directive:             Examples<22>.        (line  14)
* endif/0; Directive:                    Examples<16>.        (line  30)
* engines; Flag:                         Read-only flags.     (line  73)
* entity:                                Glossary.            (line 176)
* entity alias:                          Glossary.            (line 186)
* entity directive:                      Glossary.            (line 195)
* eos//0; Built-in method:               Examples<146>.       (line  22)
* evaluation_error/1; Built-in method:   Examples<133>.       (line  21)
* event:                                 Glossary.            (line 200)
* events; Flag:                          Optional features compilation flags.
                                                              (line  30)
* existence_error/2; Built-in method:    Examples<130>.       (line  33)
* expand_goal/2; Built-in method:        Examples<152>.       (line  16)
* expand_term/2; Built-in method:        Term and goal expansion<2>.
                                                              (line   8)
* expansion workflow:                    Glossary.            (line 207)
* extends_category/2-3; Built-in predicate: Examples<59>.     (line  19)
* extends_object/2-3; Built-in predicate: Objects categories and protocols relations.
                                                              (line   8)
* extends_protocol/2-3; Built-in predicate: Examples<58>.     (line  19)
* fail/0; Built-in method:               Examples<102>.       (line  15)
* false/0; Built-in method:              Examples<103>.       (line  15)
* findall/3; Built-in method:            Examples<138>.       (line  20)
* findall/4; Built-in method:            Examples<139>.       (line  20)
* flaky test:                            Glossary.            (line 213)
* forall/2; Built-in method:             Examples<140>.       (line  20)
* forward/1; Built-in method:            Message forwarding.  (line   8)
* general; Flag:                         Lint flags.          (line 200)
* goal_expansion/2; Built-in method:     Examples<153>.       (line  15)
* goal-expansion:                        Glossary.            (line 220)
* grammar rule:                          Glossary.            (line 230)
* grammar rule non-terminal:             Glossary.            (line 239)
* grammar rule terminal:                 Glossary.            (line 245)
* grammar_rules; Flag:                   Lint flags.          (line  90)
* homoiconic:                            Glossary.            (line 249)
* hook object:                           Glossary.            (line 257)
* hook predicate:                        Glossary.            (line 267)
* hook; Flag:                            Other flags.         (line  99)
* hot patching:                          Glossary.            (line 273)
* identity:                              Glossary.            (line 281)
* if/1; Directive:                       Conditional compilation directives<2>.
                                                              (line   8)
* ignore/1; Built-in method:             Examples<120>.       (line  19)
* implements_protocol/2-3; Built-in predicate: Examples<60>.  (line  19)
* imports_category/2-3; Built-in predicate: Examples<63>.     (line  15)
* include/1; Directive:                  Examples<9>.         (line   9)
* info/1; Directive:                     Examples<23>.        (line  14)
* info/2; Directive:                     Examples<33>.        (line  18)
* inheritance:                           Glossary.            (line 290)
* initialization/1; Directive:           Examples<10>.        (line  22)
* instance:                              Glossary.            (line 300)
* instantiates_class/2-3; Built-in predicate: Examples<64>.   (line  18)
* instantiation:                         Glossary.            (line 306)
* instantiation_error/0; Built-in method: Examples<125>.      (line  20)
* interface:                             Glossary.            (line 313)
* lambda expression:                     Glossary.            (line 317)
* lambda free variable:                  Glossary.            (line 325)
* lambda parameter:                      Glossary.            (line 331)
* lambda_variables; Flag:                Lint flags.          (line 102)
* late binding:                          Glossary.            (line 338)
* left_recursion; Flag:                  Lint flags.          (line 179)
* library:                               Glossary.            (line 342)
* library alias:                         Glossary.            (line 347)
* library notation:                      Glossary.            (line 354)
* linter; Flag:                          Lint flags.          (line   6)
* loader file:                           Glossary.            (line 362)
* local predicate:                       Glossary.            (line 368)
* logtalk_compile/1; Built-in predicate: Compiling and loading source files.
                                                              (line   8)
* logtalk_compile/2; Built-in predicate: Examples<88>.        (line  26)
* logtalk_library_path/2; Built-in predicate: Examples<94>.   (line  20)
* logtalk_linter_hook/7; Built-in predicate: Linter.          (line   8)
* logtalk_load_context/2; Built-in predicate: Examples<95>.   (line  54)
* logtalk_load/1; Built-in predicate:    Examples<89>.        (line  26)
* logtalk_load/2; Built-in predicate:    Examples<90>.        (line  26)
* logtalk_make_target_action/1; Built-in predicate: Examples<93>.
                                                              (line  24)
* logtalk_make/0; Built-in predicate:    Examples<91>.        (line  26)
* logtalk_make/1; Built-in predicate:    Examples<92>.        (line  17)
* message:                               Glossary.            (line 377)
* message lookup:                        Glossary.            (line 383)
* message to self:                       Glossary.            (line 392)
* message_hook/4; Built-in method:       Examples<157>.       (line  21)
* message_prefix_file/6; Built-in method: Examples<159>.      (line  21)
* message_prefix_stream/4; Built-in method: Examples<158>.    (line  23)
* message_tokens//2; Built-in method:    Examples<156>.       (line  17)
* meta_non_terminal/1; Directive:        Examples<35>.        (line  23)
* meta_predicate/1; Directive:           Examples<34>.        (line  21)
* meta-argument:                         Glossary.            (line 398)
* meta-interpreter:                      Glossary.            (line 405)
* meta-predicate:                        Glossary.            (line 410)
* meta-variable:                         Glossary.            (line 416)
* metaclass:                             Glossary.            (line 421)
* method:                                Glossary.            (line 428)
* missing_directives; Flag:              Lint flags.          (line  63)
* mocking:                               Glossary.            (line 435)
* mode_non_terminal/2; Directive:        Examples<37>.        (line  20)
* mode/2; Directive:                     Examples<36>.        (line  15)
* module:                                Glossary.            (line 442)
* modules; Flag:                         Read-only flags.     (line  87)
* monitor:                               Glossary.            (line 450)
* multifile predicate:                   Glossary.            (line 457)
* multifile/1; Directive:                Examples<38>.        (line  14)
* naked meta-variable:                   Glossary.            (line 466)
* naming; Flag:                          Lint flags.          (line 136)
* object:                                Glossary.            (line 473)
* object database:                       Glossary.            (line 481)
* object_property/2; Built-in predicate: Examples<49>.        (line  22)
* object/1-5; Directive:                 Examples<24>.        (line  20)
* once/1; Built-in method:               Examples<121>.       (line  19)
* op/3; Directive:                       Examples<11>.        (line  30)
* optimize; Flag:                        Other flags.         (line  44)
* parameter:                             Glossary.            (line 485)
* parameter variable:                    Glossary.            (line 491)
* parameter/2; Built-in method:          Examples<106>.       (line  21)
* parametric category:                   Glossary.            (line 500)
* parametric entity:                     Glossary.            (line 504)
* parametric object:                     Glossary.            (line 515)
* parametric object proxy:               Glossary.            (line 519)
* parent:                                Glossary.            (line 525)
* permission_error/3; Built-in method:   Examples<131>.       (line  21)
* phrase//1; Built-in method:            Examples<147>.       (line  15)
* phrase/2; Built-in method:             Examples<148>.       (line  14)
* phrase/3; Built-in method:             Examples<149>.       (line  19)
* polymorphism:                          Glossary.            (line 529)
* portability; Flag:                     Lint flags.          (line  50)
* predicate:                             Glossary.            (line 544)
* predicate alias:                       Glossary.            (line 551)
* predicate calling context:             Glossary.            (line 561)
* predicate declaration:                 Glossary.            (line 567)
* predicate definition:                  Glossary.            (line 573)
* predicate definition context:          Glossary.            (line 579)
* predicate directive:                   Glossary.            (line 584)
* predicate execution context:           Glossary.            (line 589)
* predicate scope container:             Glossary.            (line 595)
* predicate scope directive:             Glossary.            (line 601)
* predicate shorthand:                   Glossary.            (line 606)
* predicate_property/2; Built-in method: Examples<112>.       (line  42)
* primary predicate declaration:         Glossary.            (line 617)
* print_message_token/4; Built-in method: Examples<161>.      (line  19)
* print_message_tokens/3; Built-in method: Examples<160>.     (line  21)
* print_message/3; Built-in method:      Message printing.    (line   8)
* private inheritance:                   Glossary.            (line 621)
* private predicate:                     Glossary.            (line 627)
* private/1; Directive:                  Examples<39>.        (line  16)
* profiler:                              Glossary.            (line 632)
* prolog_compatible_version; Flag:       Read-only flags.     (line  36)
* prolog_compiler; Flag:                 Backend Prolog compiler and loader flags.
                                                              (line  16)
* prolog_dialect; Flag:                  Read-only flags.     (line  22)
* prolog_loader; Flag:                   Backend Prolog compiler and loader flags.
                                                              (line  26)
* prolog_version; Flag:                  Read-only flags.     (line  28)
* protected inheritance:                 Glossary.            (line 636)
* protected predicate:                   Glossary.            (line 642)
* protected/1; Directive:                Examples<40>.        (line  19)
* protocol:                              Glossary.            (line 648)
* protocol_property/2; Built-in predicate: Examples<50>.      (line  25)
* protocol/1-2; Directive:               Examples<25>.        (line  35)
* prototype:                             Glossary.            (line 658)
* public inheritance:                    Glossary.            (line 666)
* public predicate:                      Glossary.            (line 672)
* public/1; Directive:                   Examples<41>.        (line  19)
* question_hook/6; Built-in method:      Examples<163>.       (line  19)
* question_prompt_stream/4; Built-in method: Examples<164>.   (line  21)
* redefined_built_ins; Flag:             Lint flags.          (line 114)
* redefined_operators; Flag:             Lint flags.          (line 123)
* reflection:                            Message sending.     (line  27)
* relative_to; Flag:                     Other flags.         (line  93)
* reload; Flag:                          Other flags.         (line  82)
* repeat/0; Built-in method:             Examples<104>.       (line  15)
* report; Flag:                          Other flags.         (line  21)
* representation_error/1; Built-in method: Examples<132>.     (line  21)
* resource_error/1; Built-in method:     Examples<134>.       (line  21)
* retract/1; Built-in method:            Examples<117>.       (line  21)
* retractall/1; Built-in method:         Examples<118>.       (line  21)
* scratch directory:                     Glossary.            (line 676)
* scratch_directory; Flag:               Other flags.         (line   6)
* self:                                  Glossary.            (line 681)
* self/1; Built-in method:               Examples<107>.       (line  42)
* sender:                                Glossary.            (line 685)
* sender/1; Built-in method:             Examples<108>.       (line  20)
* set_logtalk_flag/2; Built-in predicate: Examples<97>.       (line  15)
* set_logtalk_flag/2; Directive:         Examples<12>.        (line  61)
* setof/3; Built-in method:              Examples<141>.       (line  20)
* settings file:                         Glossary.            (line 692)
* settings_file; Flag:                   Read-only flags.     (line  10)
* singleton method:                      Glossary.            (line 699)
* singleton_variables; Flag:             Lint flags.          (line 131)
* sockets; Flag:                         Read-only flags.     (line  61)
* source file:                           Glossary.            (line 705)
* source file directive:                 Glossary.            (line 714)
* source_data; Flag:                     Other flags.         (line  61)
* specialization:                        Glossary.            (line 719)
* specializes_class/2-3; Built-in predicate: Examples<65>.    (line  20)
* static binding:                        Glossary.            (line 724)
* static entity:                         Glossary.            (line 734)
* steadfastness:                         Glossary.            (line 738)
* steadfastness; Flag:                   Lint flags.          (line  42)
* structural reflection:                 Reflection.          (line  13)
* subclass:                              Glossary.            (line 746)
* super call:                            Glossary.            (line 752)
* superclass:                            Glossary.            (line 760)
* suspicious_calls; Flag:                Lint flags.          (line 108)
* synchronized predicate:                Glossary.            (line 766)
* synchronized/1; Directive:             Examples<42>.        (line  19)
* syntax_error/1; Built-in method:       Examples<135>.       (line  21)
* system_error/0; Built-in method:       Examples<136>.       (line  19)
* tabling; Flag:                         Read-only flags.     (line  67)
* tail_recursive; Flag:                  Lint flags.          (line 186)
* template method:                       Glossary.            (line 772)
* term_expansion/2; Built-in method:     Examples<151>.       (line  15)
* term-expansion:                        Glossary.            (line 776)
* test dialect:                          Glossary.            (line 786)
* test outcome:                          Glossary.            (line 792)
* tester file:                           Glossary.            (line 798)
* this:                                  Glossary.            (line 803)
* this/1; Built-in method:               Examples<109>.       (line  20)
* threaded engine:                       Glossary.            (line 811)
* threaded_call/1-2; Built-in predicate: Examples<70>.        (line  18)
* threaded_cancel/1; Built-in predicate: Examples<75>.        (line  21)
* threaded_engine_create/3; Built-in predicate: Multi-threading engines.
                                                              (line   8)
* threaded_engine_destroy/1; Built-in predicate: Examples<79>.
                                                              (line  17)
* threaded_engine_fetch/1; Built-in predicate: Examples<86>.  (line  15)
* threaded_engine_next_reified/2; Built-in predicate: Examples<83>.
                                                              (line  16)
* threaded_engine_next/2; Built-in predicate: Examples<82>.   (line  19)
* threaded_engine_post/2; Built-in predicate: Examples<85>.   (line  16)
* threaded_engine_self/1; Built-in predicate: Examples<81>.   (line  22)
* threaded_engine_yield/1; Built-in predicate: Examples<84>.  (line  16)
* threaded_engine/1; Built-in predicate: Examples<80>.        (line  22)
* threaded_exit/1-2; Built-in predicate: Examples<73>.        (line  21)
* threaded_ignore/1; Built-in predicate: Examples<72>.        (line  21)
* threaded_notify/1; Built-in predicate: Examples<77>.        (line  15)
* threaded_once/1-2; Built-in predicate: Examples<71>.        (line  21)
* threaded_peek/1-2; Built-in predicate: Examples<74>.        (line  21)
* threaded_wait/1; Built-in predicate:   Examples<76>.        (line  16)
* threaded/0; Directive:                 Examples<26>.        (line  20)
* threaded/1; Built-in predicate:        Multi-threading.     (line   8)
* threads; Flag:                         Read-only flags.     (line  80)
* throw/1; Built-in method:              Examples<124>.       (line  20)
* top-level interpreter shorthand:       Glossary.            (line 819)
* transparent-box view:                  Structural reflection.
                                                              (line  11)
* trivial_goal_fails; Flag:              Lint flags.          (line  77)
* true/0; Built-in method:               Examples<101>.       (line  15)
* type_error/2; Built-in method:         Examples<127>.       (line  22)
* undefined_predicates; Flag:            Lint flags.          (line  34)
* underscore_variables; Flag:            Backend Prolog compiler and loader flags.
                                                              (line   6)
* unicode; Flag:                         Read-only flags.     (line  45)
* unknown_entities; Flag:                Lint flags.          (line  16)
* unknown_predicates; Flag:              Lint flags.          (line  24)
* ununinstantiation_error/1; Built-in method: Examples<126>.  (line  22)
* use_module/1; Directive:               Examples<28>.        (line  33)
* use_module/2; Directive:               Examples<44>.        (line  68)
* uses/1; Directive:                     Examples<27>.        (line  14)
* uses/2; Directive:                     Examples<43>.        (line  18)
* version_data; Flag:                    Version flags.       (line   6)
* visible predicate:                     Glossary.            (line 826)


Tag Table:
Node: Top474
Ref: index doc712
Ref: 0712
Node: User Manual129226
Ref: userman/index doc129334
Ref: 1129334
Ref: userman/index the-logtalk-handbook129334
Ref: 2129334
Ref: userman/index user-manual129334
Ref: 3129334
Node: Declarative object-oriented programming129861
Ref: userman/declarative doc129990
Ref: 4129990
Ref: userman/declarative declarative-declarative129990
Ref: 5129990
Ref: userman/declarative declarative-object-oriented-programming129990
Ref: 6129990
Node: Main features133841
Ref: userman/features doc133991
Ref: 9133991
Ref: userman/features features-features133991
Ref: a133991
Ref: userman/features main-features133991
Ref: b133991
Node: Integration of logic and object-oriented programming135937
Ref: userman/features features-logic136127
Ref: c136127
Ref: userman/features integration-of-logic-and-object-oriented-programming136127
Ref: d136127
Node: Integration of event-driven and object-oriented programming137178
Ref: userman/features features-events137416
Ref: e137416
Ref: userman/features integration-of-event-driven-and-object-oriented-programming137416
Ref: f137416
Node: Support for component-based programming138688
Ref: userman/features features-categories138924
Ref: 15138924
Ref: userman/features support-for-component-based-programming138924
Ref: 16138924
Node: Support for both prototype and class-based systems139757
Ref: userman/features features-both139973
Ref: 17139973
Ref: userman/features support-for-both-prototype-and-class-based-systems139973
Ref: 18139973
Node: Support for multiple object hierarchies140982
Ref: userman/features features-multiple141206
Ref: 1a141206
Ref: userman/features support-for-multiple-object-hierarchies141206
Ref: 1b141206
Node: Separation between interface and implementation142027
Ref: userman/features features-interface142241
Ref: 1f142241
Ref: userman/features separation-between-interface-and-implementation142241
Ref: 20142241
Node: Private protected and public inheritance142741
Ref: userman/features features-inheritance142962
Ref: 21142962
Ref: userman/features private-protected-and-public-inheritance142962
Ref: 22142962
Node: Private protected and public object predicates143308
Ref: userman/features features-predicates143500
Ref: 24143500
Ref: userman/features private-protected-and-public-object-predicates143500
Ref: 25143500
Node: Parametric objects143992
Ref: userman/features features-parametric144190
Ref: 26144190
Ref: userman/features parametric-objects144190
Ref: 27144190
Node: High level multi-threading programming support144934
Ref: userman/features features-threading145107
Ref: 2b145107
Ref: userman/features high-level-multi-threading-programming-support145107
Ref: 2c145107
Node: Smooth learning curve145663
Ref: userman/features features-learning145877
Ref: 2d145877
Ref: userman/features smooth-learning-curve145877
Ref: 2e145877
Node: Compatibility with most Prolog systems and the ISO standard146097
Ref: userman/features compatibility-with-most-prolog-systems-and-the-iso-standard146276
Ref: 2f146276
Ref: userman/features features-compatibility146276
Ref: 30146276
Node: Performance146651
Ref: userman/features features-performance146822
Ref: 32146822
Ref: userman/features performance146822
Ref: 33146822
Node: Logtalk scope148140
Ref: userman/features features-scope148243
Ref: 39148243
Ref: userman/features logtalk-scope148243
Ref: 3a148243
Node: Nomenclature150916
Ref: userman/nomenclature doc151035
Ref: 3b151035
Ref: userman/nomenclature nomenclature151035
Ref: 3c151035
Ref: userman/nomenclature nomenclature-nomenclature151035
Ref: 3d151035
Node: Prolog nomenclature152733
Ref: userman/nomenclature nomenclature-prolog152852
Ref: 40152852
Ref: userman/nomenclature prolog-nomenclature152852
Ref: 41152852
Node: Smalltalk nomenclature159876
Ref: userman/nomenclature nomenclature-smalltalk160020
Ref: 5a160020
Ref: userman/nomenclature smalltalk-nomenclature160020
Ref: 5b160020
Node: C++ nomenclature165291
Ref: userman/nomenclature c-nomenclature165433
Ref: 5e165433
Ref: userman/nomenclature nomenclature-cpp165433
Ref: 5f165433
Node: Java nomenclature168685
Ref: userman/nomenclature java-nomenclature168824
Ref: 6b168824
Ref: userman/nomenclature nomenclature-java168824
Ref: 6c168824
Node: Python nomenclature173799
Ref: userman/nomenclature nomenclature-python173913
Ref: 75173913
Ref: userman/nomenclature python-nomenclature173913
Ref: 76173913
Node: Messages177993
Ref: userman/messages doc178106
Ref: 77178106
Ref: userman/messages messages178106
Ref: 78178106
Ref: userman/messages messages-messages178106
Ref: 79178106
Node: Operators used in message-sending179804
Ref: userman/messages messages-operators179941
Ref: 7a179941
Ref: userman/messages operators-used-in-message-sending179941
Ref: 7b179941
Node: Sending a message to an object180496
Ref: userman/messages messages-sending180675
Ref: 7c180675
Ref: userman/messages sending-a-message-to-an-object180675
Ref: 7d180675
Node: Delegating a message to an object181203
Ref: userman/messages delegating-a-message-to-an-object181374
Ref: 7f181374
Ref: userman/messages messages-delegating181374
Ref: 80181374
Node: Sending a message to self181932
Ref: userman/messages sending-a-message-to-self182085
Ref: 82182085
Node: Broadcasting182851
Ref: userman/messages broadcasting183012
Ref: 83183012
Ref: userman/messages messages-broadcasting183012
Ref: 84183012
Node: Calling imported and inherited predicates183891
Ref: userman/messages calling-imported-and-inherited-predicates184063
Ref: 85184063
Ref: userman/messages messages-super184063
Ref: 86184063
Node: Message sending and event generation185235
Ref: userman/messages message-sending-and-event-generation185426
Ref: 87185426
Ref: userman/messages messages-events185426
Ref: 88185426
Node: Sending a message from a module187127
Ref: userman/messages messages-from-module187304
Ref: 8a187304
Ref: userman/messages sending-a-message-from-a-module187304
Ref: 8b187304
Node: Message sending performance188305
Ref: userman/messages message-sending-performance188437
Ref: 8d188437
Ref: userman/messages messages-performance188437
Ref: 8e188437
Node: Objects188605
Ref: userman/objects doc188715
Ref: 8f188715
Ref: userman/objects objects188715
Ref: 90188715
Ref: userman/objects objects-objects188715
Ref: 91188715
Ref: Objects-Footnote-1189690
Ref: Objects-Footnote-2189728
Node: Objects prototypes classes and instances189772
Ref: userman/objects objects-prototypes-classes-and-instances189906
Ref: 92189906
Ref: userman/objects objects-roles189906
Ref: 93189906
Node: Prototypes191538
Ref: userman/objects objects-prototypes191661
Ref: 94191661
Ref: userman/objects prototypes191661
Ref: 95191661
Node: Classes192280
Ref: userman/objects classes192403
Ref: 96192403
Ref: userman/objects objects-classes192403
Ref: 97192403
Node: Defining a new object192960
Ref: userman/objects defining-a-new-object193124
Ref: 98193124
Ref: userman/objects objects-defining193124
Ref: 99193124
Node: Parametric objects<2>198978
Ref: userman/objects objects-parametric199125
Ref: 66199125
Ref: userman/objects parametric-objects199125
Ref: 9f199125
Node: Accessing object parameters199981
Ref: userman/objects accessing-object-parameters200120
Ref: a0200120
Node: Parametric object proxies202403
Ref: userman/objects parametric-object-proxies202542
Ref: a3202542
Node: Finding defined objects204065
Ref: userman/objects finding-defined-objects204223
Ref: a4204223
Ref: userman/objects objects-finding204223
Ref: a5204223
Node: Creating a new object at runtime204652
Ref: userman/objects creating-a-new-object-at-runtime204818
Ref: a7204818
Ref: userman/objects objects-creating204818
Ref: a8204818
Node: Abolishing an existing object206076
Ref: userman/objects abolishing-an-existing-object206236
Ref: a9206236
Ref: userman/objects objects-abolishing206236
Ref: aa206236
Node: Object directives206536
Ref: userman/objects object-directives206684
Ref: ab206684
Ref: userman/objects objects-directives206684
Ref: ac206684
Node: Object initialization207065
Ref: userman/objects object-initialization207184
Ref: ad207184
Ref: userman/objects objects-initialization207184
Ref: ae207184
Node: Dynamic objects208406
Ref: userman/objects dynamic-objects208554
Ref: af208554
Ref: userman/objects objects-dynamic208554
Ref: b0208554
Node: Object documentation209280
Ref: userman/objects object-documentation209435
Ref: b2209435
Ref: userman/objects objects-documentation209435
Ref: b3209435
Node: Loading files into an object209665
Ref: userman/objects loading-files-into-an-object209829
Ref: b6209829
Ref: userman/objects objects-include209829
Ref: b7209829
Node: Declaring object aliases210576
Ref: userman/objects declaring-object-aliases210711
Ref: b9210711
Ref: userman/objects objects-object-aliases210711
Ref: ba210711
Node: Object relationships211125
Ref: userman/objects object-relationships211261
Ref: bb211261
Ref: userman/objects objects-relationships211261
Ref: bc211261
Node: Object properties213361
Ref: userman/objects object-properties213496
Ref: c4213496
Ref: userman/objects objects-properties213496
Ref: c5213496
Node: Built-in objects222317
Ref: userman/objects built-in-objects222460
Ref: cd222460
Ref: userman/objects objects-built-in222460
Ref: ce222460
Node: The built-in pseudo-object user222673
Ref: userman/objects objects-user222813
Ref: cf222813
Ref: userman/objects the-built-in-pseudo-object-user222813
Ref: d0222813
Ref: The built-in pseudo-object user-Footnote-1223803
Node: The built-in object logtalk223841
Ref: userman/objects objects-logtalk223981
Ref: d1223981
Ref: userman/objects the-built-in-object-logtalk223981
Ref: d2223981
Ref: The built-in object logtalk-Footnote-1224499
Node: Multi-threading applications224543
Ref: userman/objects multi-threading-applications224660
Ref: d6224660
Node: Protocols224958
Ref: userman/protocols doc225070
Ref: d7225070
Ref: userman/protocols protocols225070
Ref: d8225070
Ref: userman/protocols protocols-protocols225070
Ref: d9225070
Ref: Protocols-Footnote-1226032
Ref: Protocols-Footnote-2226082
Ref: Protocols-Footnote-3226130
Node: Defining a new protocol226180
Ref: userman/protocols defining-a-new-protocol226303
Ref: da226303
Ref: userman/protocols protocols-defining226303
Ref: db226303
Node: Finding defined protocols228392
Ref: userman/protocols finding-defined-protocols228558
Ref: de228558
Ref: userman/protocols protocols-finding228558
Ref: df228558
Node: Creating a new protocol at runtime228926
Ref: userman/protocols creating-a-new-protocol-at-runtime229100
Ref: e1229100
Ref: userman/protocols protocols-creating229100
Ref: e2229100
Node: Abolishing an existing protocol230146
Ref: userman/protocols abolishing-an-existing-protocol230314
Ref: e4230314
Ref: userman/protocols protocols-abolishing230314
Ref: e5230314
Node: Protocol directives230628
Ref: userman/protocols protocol-directives230784
Ref: e7230784
Node: Dynamic protocols231009
Ref: userman/protocols dynamic-protocols231133
Ref: e8231133
Ref: userman/protocols protocols-dynamic231133
Ref: e9231133
Node: Protocol documentation231776
Ref: userman/protocols protocol-documentation231938
Ref: ea231938
Ref: userman/protocols protocols-documentation231938
Ref: eb231938
Node: Loading files into a protocol232173
Ref: userman/protocols loading-files-into-a-protocol232309
Ref: ec232309
Ref: userman/protocols protocols-include232309
Ref: ed232309
Node: Protocol relationships232558
Ref: userman/protocols protocol-relationships232702
Ref: ee232702
Ref: userman/protocols protocols-relationships232702
Ref: ef232702
Node: Protocol properties233737
Ref: userman/protocols protocol-properties233884
Ref: f2233884
Ref: userman/protocols protocols-properties233884
Ref: f3233884
Node: Implementing protocols236396
Ref: userman/protocols implementing-protocols236539
Ref: f6236539
Ref: userman/protocols protocols-implementing236539
Ref: f7236539
Node: Built-in protocols237531
Ref: userman/protocols built-in-protocols237686
Ref: f8237686
Ref: userman/protocols protocols-built-in237686
Ref: f9237686
Node: The built-in protocol expanding237949
Ref: userman/protocols protocols-expanding238096
Ref: fa238096
Ref: userman/protocols the-built-in-protocol-expanding238096
Ref: fb238096
Ref: The built-in protocol expanding-Footnote-1238418
Node: The built-in protocol monitoring238466
Ref: userman/protocols protocols-monitoring238654
Ref: ff238654
Ref: userman/protocols the-built-in-protocol-monitoring238654
Ref: 100238654
Ref: The built-in protocol monitoring-Footnote-1238980
Node: The built-in protocol forwarding239030
Ref: userman/protocols protocols-forwarding239178
Ref: 103239178
Ref: userman/protocols the-built-in-protocol-forwarding239178
Ref: 104239178
Ref: The built-in protocol forwarding-Footnote-1239588
Node: Multi-threading applications<2>239638
Ref: userman/protocols multi-threading-applications239762
Ref: 106239762
Node: Categories240064
Ref: userman/categories doc240179
Ref: 107240179
Ref: userman/categories categories240179
Ref: 108240179
Ref: userman/categories categories-categories240179
Ref: 109240179
Ref: Categories-Footnote-1241685
Node: Defining a new category241741
Ref: userman/categories categories-defining241852
Ref: 10c241852
Ref: userman/categories defining-a-new-category241852
Ref: 10d241852
Node: Hot patching247263
Ref: userman/categories categories-patching247409
Ref: 110247409
Ref: userman/categories hot-patching247409
Ref: 111247409
Node: Finding defined categories250953
Ref: userman/categories categories-finding251110
Ref: 116251110
Ref: userman/categories finding-defined-categories251110
Ref: 117251110
Node: Creating a new category at runtime251501
Ref: userman/categories categories-creating251677
Ref: 118251677
Ref: userman/categories creating-a-new-category-at-runtime251677
Ref: 119251677
Node: Abolishing an existing category252928
Ref: userman/categories abolishing-an-existing-category253097
Ref: 11b253097
Ref: userman/categories categories-abolishing253097
Ref: 11c253097
Node: Category directives253413
Ref: userman/categories categories-directives253570
Ref: 11d253570
Ref: userman/categories category-directives253570
Ref: 11e253570
Node: Dynamic categories253941
Ref: userman/categories categories-dynamic254066
Ref: 11f254066
Ref: userman/categories dynamic-categories254066
Ref: 120254066
Node: Category documentation254724
Ref: userman/categories categories-documentation254887
Ref: 121254887
Ref: userman/categories category-documentation254887
Ref: 122254887
Node: Loading files into a category255122
Ref: userman/categories categories-include255294
Ref: 123255294
Ref: userman/categories loading-files-into-a-category255294
Ref: 124255294
Node: Declaring object aliases<2>255543
Ref: userman/categories categories-object-aliases255684
Ref: 125255684
Ref: userman/categories declaring-object-aliases255684
Ref: 126255684
Node: Category relationships256017
Ref: userman/categories categories-relationships256162
Ref: 127256162
Ref: userman/categories category-relationships256162
Ref: 128256162
Node: Category properties257808
Ref: userman/categories categories-properties257954
Ref: 12a257954
Ref: userman/categories category-properties257954
Ref: 12b257954
Node: Importing categories265915
Ref: userman/categories categories-importing266066
Ref: 12d266066
Ref: userman/categories importing-categories266066
Ref: 12e266066
Node: Calling category predicates266892
Ref: userman/categories calling-category-predicates267045
Ref: 12f267045
Ref: userman/categories categories-predicates267045
Ref: 130267045
Node: Parametric categories268839
Ref: userman/categories categories-parametric268991
Ref: 131268991
Ref: userman/categories parametric-categories268991
Ref: 132268991
Node: Built-in categories270212
Ref: userman/categories built-in-categories270368
Ref: 133270368
Ref: userman/categories categories-built-in270368
Ref: 134270368
Node: The built-in category core_messages270556
Ref: userman/categories categories-core-messages270667
Ref: 135270667
Ref: userman/categories the-built-in-category-core-messages270667
Ref: 136270667
Ref: The built-in category core_messages-Footnote-1270990
Node: Multi-threading applications<3>271046
Ref: userman/categories multi-threading-applications271172
Ref: 137271172
Node: Predicates271474
Ref: userman/predicates doc271591
Ref: 138271591
Ref: userman/predicates predicates271591
Ref: 139271591
Ref: userman/predicates predicates-predicates271591
Ref: 13a271591
Node: Reserved predicate names272385
Ref: userman/predicates predicates-reserved272505
Ref: 13b272505
Ref: userman/predicates reserved-predicate-names272505
Ref: 13c272505
Ref: Reserved predicate names-Footnote-1273180
Ref: Reserved predicate names-Footnote-2273228
Ref: Reserved predicate names-Footnote-3273278
Node: Declaring predicates273328
Ref: userman/predicates declaring-predicates273476
Ref: 13d273476
Ref: userman/predicates predicates-declaring273476
Ref: 13e273476
Node: Scope directives274587
Ref: userman/predicates predicates-scope274703
Ref: 13f274703
Ref: userman/predicates scope-directives274703
Ref: 140274703
Node: Mode directive277792
Ref: userman/predicates mode-directive277941
Ref: 147277941
Ref: userman/predicates predicates-mode277941
Ref: 148277941
Ref: userman/predicates predicates-mode-instantiation278337
Ref: 14b278337
Ref: userman/predicates predicates-mode-number-of-proofs280402
Ref: 14d280402
Node: Meta-predicate directive284443
Ref: userman/predicates meta-predicate-directive284599
Ref: 14e284599
Ref: userman/predicates predicates-meta284599
Ref: 65284599
Node: Discontiguous directive288546
Ref: userman/predicates discontiguous-directive288705
Ref: 155288705
Ref: userman/predicates predicates-discontiguous288705
Ref: 156288705
Node: Dynamic directive289404
Ref: userman/predicates dynamic-directive289557
Ref: 158289557
Ref: userman/predicates predicates-dynamic289557
Ref: 159289557
Node: Operator directive290791
Ref: userman/predicates operator-directive290935
Ref: 15b290935
Ref: userman/predicates predicates-op290935
Ref: 15c290935
Node: Uses directive292487
Ref: userman/predicates predicates-uses292629
Ref: 15f292629
Ref: userman/predicates uses-directive292629
Ref: 160292629
Node: Alias directive296477
Ref: userman/predicates alias-directive296622
Ref: 163296622
Ref: userman/predicates predicates-alias296622
Ref: 164296622
Node: Documenting directive300768
Ref: userman/predicates documenting-directive300918
Ref: 166300918
Ref: userman/predicates predicates-info300918
Ref: 167300918
Node: Multifile directive301239
Ref: userman/predicates multifile-directive301395
Ref: 169301395
Ref: userman/predicates predicates-multifile301395
Ref: 16a301395
Node: Coinductive directive305389
Ref: userman/predicates coinductive-directive305546
Ref: 16e305546
Ref: userman/predicates predicates-coinductive305546
Ref: 16f305546
Node: Synchronized directive306049
Ref: userman/predicates predicates-synchronized306178
Ref: 173306178
Ref: userman/predicates synchronized-directive306178
Ref: 174306178
Node: Defining predicates306518
Ref: userman/predicates defining-predicates306671
Ref: 177306671
Ref: userman/predicates predicates-defining306671
Ref: 178306671
Node: Object predicates306858
Ref: userman/predicates object-predicates306979
Ref: 179306979
Ref: userman/predicates predicates-objects306979
Ref: 17a306979
Node: Category predicates308155
Ref: userman/predicates category-predicates308300
Ref: 17b308300
Ref: userman/predicates predicates-categories308300
Ref: 17c308300
Node: Meta-predicates310092
Ref: userman/predicates meta-predicates310238
Ref: 17e310238
Ref: userman/predicates predicates-metadef310238
Ref: 17f310238
Node: Lambda expressions313377
Ref: userman/predicates lambda-expressions313534
Ref: 184313534
Ref: userman/predicates predicates-lambdas313534
Ref: 162313534
Ref: Lambda expressions-Footnote-1320130
Node: Redefining built-in predicates320184
Ref: userman/predicates predicates-redefining320317
Ref: 187320317
Ref: userman/predicates redefining-built-in-predicates320317
Ref: 188320317
Node: Definite clause grammar rules322661
Ref: userman/predicates definite-clause-grammar-rules322810
Ref: 18c322810
Ref: userman/predicates predicates-dcgs322810
Ref: 18d322810
Node: Built-in methods330608
Ref: userman/predicates built-in-methods330758
Ref: 192330758
Ref: userman/predicates predicates-methods330758
Ref: 193330758
Node: Logic and control methods331508
Ref: userman/predicates logic-and-control-methods331640
Ref: 194331640
Ref: userman/predicates predicates-logic331640
Ref: 195331640
Node: Execution context methods332102
Ref: userman/predicates execution-context-methods332278
Ref: 19b332278
Ref: userman/predicates predicates-context332278
Ref: 19c332278
Node: Error handling and throwing methods336727
Ref: userman/predicates error-handling-and-throwing-methods336894
Ref: 19f336894
Ref: userman/predicates predicates-errors336894
Ref: 1a0336894
Node: Database methods337687
Ref: userman/predicates database-methods337846
Ref: 1ae337846
Ref: userman/predicates predicates-database337846
Ref: 1af337846
Node: Meta-call methods339249
Ref: userman/predicates meta-call-methods339394
Ref: 1b9339394
Ref: userman/predicates predicates-metacalls339394
Ref: 1ba339394
Node: All solutions methods339847
Ref: userman/predicates all-solutions-methods339994
Ref: 1bd339994
Ref: userman/predicates predicates-solutions339994
Ref: 1be339994
Node: Reflection methods340365
Ref: userman/predicates predicates-reflection340552
Ref: 1c4340552
Ref: userman/predicates reflection-methods340552
Ref: 1c5340552
Node: Definite clause grammar parsing methods and non-terminals341783
Ref: userman/predicates definite-clause-grammar-parsing-methods-and-non-terminals341940
Ref: 1c6341940
Ref: userman/predicates predicates-parsing341940
Ref: 1c7341940
Node: Predicate properties342742
Ref: userman/predicates predicate-properties342890
Ref: 1cb342890
Ref: userman/predicates predicates-properties342890
Ref: 1cc342890
Node: Finding declared predicates348395
Ref: userman/predicates finding-declared-predicates348552
Ref: 1cd348552
Ref: userman/predicates predicates-finding348552
Ref: 1ce348552
Node: Calling Prolog predicates349444
Ref: userman/predicates calling-prolog-predicates349617
Ref: 1cf349617
Ref: userman/predicates predicates-prolog349617
Ref: 3e349617
Node: Calling Prolog built-in predicates350697
Ref: userman/predicates calling-prolog-built-in-predicates350874
Ref: 1d0350874
Node: Calling Prolog non-standard built-in meta-predicates352834
Ref: userman/predicates calling-prolog-non-standard-built-in-meta-predicates353053
Ref: 1d2353053
Ref: userman/predicates predicates-prolog-meta353053
Ref: 1d3353053
Node: Calling Prolog foreign predicates354289
Ref: userman/predicates calling-prolog-foreign-predicates354518
Ref: 1d4354518
Ref: userman/predicates predicates-prolog-foreign354518
Ref: 1d5354518
Node: Calling Prolog user-defined plain predicates355792
Ref: userman/predicates calling-prolog-user-defined-plain-predicates356001
Ref: 1d6356001
Ref: userman/predicates predicates-prolog-user356001
Ref: 1d7356001
Node: Calling Prolog module predicates357092
Ref: userman/predicates calling-prolog-module-predicates357305
Ref: 1d8357305
Ref: userman/predicates predicates-prolog-module357305
Ref: 1d9357305
Node: Calling Prolog module meta-predicates360849
Ref: userman/predicates calling-prolog-module-meta-predicates361009
Ref: 1da361009
Ref: userman/predicates predicates-prolog-module-meta-predicates361009
Ref: 1db361009
Node: Defining Prolog multifile predicates363793
Ref: userman/predicates defining-prolog-multifile-predicates363981
Ref: 1dc363981
Ref: userman/predicates predicates-prolog-multifile363981
Ref: 1dd363981
Node: Asserting and retracting Prolog predicates365162
Ref: userman/predicates asserting-and-retracting-prolog-predicates365316
Ref: 1de365316
Ref: userman/predicates predicates-prolog-dynamic365316
Ref: 1df365316
Node: Inheritance367161
Ref: userman/inheritance doc367292
Ref: 1e0367292
Ref: userman/inheritance inheritance367292
Ref: 1e1367292
Ref: userman/inheritance inheritance-inheritance367292
Ref: 8367292
Node: Protocol inheritance369300
Ref: userman/inheritance inheritance-protocol369423
Ref: 1e2369423
Ref: userman/inheritance protocol-inheritance369423
Ref: 1e3369423
Node: Lookup order for prototype hierarchies369901
Ref: userman/inheritance inheritance-protocol-prototype370059
Ref: 1e5370059
Ref: userman/inheritance lookup-order-for-prototype-hierarchies370059
Ref: 1e6370059
Node: Lookup order for class hierarchies370631
Ref: userman/inheritance inheritance-protocol-class370789
Ref: 1e7370789
Ref: userman/inheritance lookup-order-for-class-hierarchies370789
Ref: 1e8370789
Node: Implementation inheritance371379
Ref: userman/inheritance implementation-inheritance371551
Ref: 1e9371551
Ref: userman/inheritance inheritance-implementation371551
Ref: 1ea371551
Node: Lookup order for prototype hierarchies<2>372274
Ref: userman/inheritance id1372444
Ref: 1eb372444
Ref: userman/inheritance inheritance-implementation-prototype372444
Ref: 1ec372444
Node: Lookup order for class hierarchies<2>372731
Ref: userman/inheritance id2372952
Ref: 1ed372952
Ref: userman/inheritance inheritance-implementation-class372952
Ref: 1ee372952
Node: Redefining inherited predicate definitions373450
Ref: userman/inheritance inheritance-implementation-redefinition373674
Ref: 1ef373674
Ref: userman/inheritance redefining-inherited-predicate-definitions373674
Ref: 1f0373674
Node: Specializing inherited predicate definitions374699
Ref: userman/inheritance inheritance-specialization374936
Ref: 1f1374936
Ref: userman/inheritance specializing-inherited-predicate-definitions374936
Ref: 1f2374936
Node: Union of inherited and local predicate definitions375752
Ref: userman/inheritance inheritance-union375993
Ref: 1f3375993
Ref: userman/inheritance union-of-inherited-and-local-predicate-definitions375993
Ref: 1f4375993
Node: Selective inheritance of predicate definitions376894
Ref: userman/inheritance inheritance-selective377082
Ref: 1f5377082
Ref: userman/inheritance selective-inheritance-of-predicate-definitions377082
Ref: 1f6377082
Node: Public protected and private inheritance377913
Ref: userman/inheritance inheritance-scope378085
Ref: 9e378085
Ref: userman/inheritance public-protected-and-private-inheritance378085
Ref: 1f7378085
Node: Multiple inheritance379382
Ref: userman/inheritance inheritance-multiple379567
Ref: 1f8379567
Ref: userman/inheritance multiple-inheritance379567
Ref: 1f9379567
Node: Composition versus multiple inheritance380456
Ref: userman/inheritance composition-versus-multiple-inheritance380592
Ref: 1fa380592
Ref: userman/inheritance inheritance-composition380592
Ref: 1fb380592
Node: Event-driven programming382298
Ref: userman/events doc382446
Ref: 200382446
Ref: userman/events event-driven-programming382446
Ref: 201382446
Ref: userman/events events-events382446
Ref: 6d382446
Node: Definitions384254
Ref: userman/events definitions384371
Ref: 204384371
Ref: userman/events events-definitions384371
Ref: 205384371
Node: Event384598
Ref: userman/events event384687
Ref: 206384687
Ref: userman/events events-event384687
Ref: 207384687
Node: Monitor386554
Ref: userman/events events-monitor386643
Ref: 208386643
Ref: userman/events monitor386643
Ref: 209386643
Ref: Monitor-Footnote-1388145
Node: Event generation388195
Ref: userman/events event-generation388353
Ref: 20a388353
Ref: userman/events events-generation388353
Ref: 20b388353
Node: Communicating events to monitors389004
Ref: userman/events communicating-events-to-monitors389171
Ref: 20c389171
Ref: userman/events events-communicating389171
Ref: 20d389171
Ref: Communicating events to monitors-Footnote-1389701
Node: Performance concerns389751
Ref: userman/events events-performance389919
Ref: 20e389919
Ref: userman/events performance-concerns389919
Ref: 20f389919
Node: Monitor semantics390826
Ref: userman/events events-semantics390990
Ref: 210390990
Ref: userman/events monitor-semantics390990
Ref: 211390990
Node: Activation order of monitors391884
Ref: userman/events activation-order-of-monitors392042
Ref: 212392042
Ref: userman/events events-order392042
Ref: 213392042
Node: Event handling393212
Ref: userman/events event-handling393344
Ref: 214393344
Ref: userman/events events-handling393344
Ref: 215393344
Node: Defining new events393811
Ref: userman/events defining-new-events393935
Ref: 216393935
Ref: userman/events events-defining393935
Ref: 217393935
Node: Abolishing defined events394337
Ref: userman/events abolishing-defined-events394492
Ref: 219394492
Ref: userman/events events-abolishing394492
Ref: 21a394492
Node: Finding defined events394816
Ref: userman/events events-finding394975
Ref: 21c394975
Ref: userman/events finding-defined-events394975
Ref: 21d394975
Node: Defining event handlers395365
Ref: userman/events defining-event-handlers395490
Ref: 21f395490
Ref: userman/events events-handlers395490
Ref: 220395490
Ref: Defining event handlers-Footnote-1398609
Ref: Defining event handlers-Footnote-2398659
Node: Multi-threading programming398709
Ref: userman/threads doc398860
Ref: 221398860
Ref: userman/threads multi-threading-programming398860
Ref: 222398860
Ref: userman/threads threads-threads398860
Ref: 73398860
Node: Enabling multi-threading support400043
Ref: userman/threads enabling-multi-threading-support400214
Ref: 223400214
Ref: userman/threads threads-enabling400214
Ref: 224400214
Node: Enabling objects to make multi-threading calls400497
Ref: userman/threads enabling-objects-to-make-multi-threading-calls400712
Ref: 226400712
Ref: userman/threads threads-directive400712
Ref: 227400712
Node: Multi-threading built-in predicates400944
Ref: userman/threads multi-threading-built-in-predicates401153
Ref: 229401153
Ref: userman/threads threads-predicates401153
Ref: 22a401153
Node: Proving goals concurrently using threads401916
Ref: userman/threads proving-goals-concurrently-using-threads402099
Ref: 22c402099
Ref: userman/threads threads-threaded402099
Ref: 22d402099
Node: Proving goals asynchronously using threads404460
Ref: userman/threads proving-goals-asynchronously-using-threads404643
Ref: 22e404643
Ref: userman/threads threads-call404643
Ref: 22f404643
Node: One-way asynchronous calls409130
Ref: userman/threads one-way-asynchronous-calls409339
Ref: 235409339
Ref: userman/threads threads-ignore409339
Ref: 236409339
Node: Asynchronous calls and synchronized predicates410013
Ref: userman/threads asynchronous-calls-and-synchronized-predicates410230
Ref: 238410230
Ref: userman/threads threads-synchronized-predicates410230
Ref: 176410230
Node: Synchronizing threads through notifications413640
Ref: userman/threads synchronizing-threads-through-notifications413847
Ref: 239413847
Ref: userman/threads threads-notifications413847
Ref: 23a413847
Node: Threaded engines415264
Ref: userman/threads threaded-engines415452
Ref: 23d415452
Ref: userman/threads threads-engines415452
Ref: 23e415452
Node: Multi-threading performance419327
Ref: userman/threads multi-threading-performance419463
Ref: 246419463
Ref: userman/threads threads-performance419463
Ref: 247419463
Node: Error handling420518
Ref: userman/errors doc420655
Ref: 248420655
Ref: userman/errors error-handling420655
Ref: 249420655
Ref: userman/errors errors-errors420655
Ref: 24a420655
Ref: Error handling-Footnote-1421878
Node: Raising Exceptions421942
Ref: userman/errors raising-exceptions422053
Ref: 24b422053
Node: Type-checking422611
Ref: userman/errors type-checking422745
Ref: 24d422745
Ref: Type-checking-Footnote-1425384
Ref: Type-checking-Footnote-2425422
Ref: Type-checking-Footnote-3425468
Ref: Type-checking-Footnote-4425514
Node: Expected terms425560
Ref: userman/errors expected-terms425704
Ref: 24e425704
Node: Compiler warnings and errors425993
Ref: userman/errors compiler-warnings-and-errors426138
Ref: 250426138
Node: Unknown entities427577
Ref: userman/errors errors-unknown427706
Ref: 252427706
Ref: userman/errors unknown-entities427706
Ref: 253427706
Node: Singleton variables428091
Ref: userman/errors errors-singletons428271
Ref: 254428271
Ref: userman/errors singleton-variables428271
Ref: 255428271
Node: Redefinition of Prolog built-in predicates428707
Ref: userman/errors errors-prolog428914
Ref: 256428914
Ref: userman/errors redefinition-of-prolog-built-in-predicates428914
Ref: 257428914
Node: Redefinition of Logtalk built-in predicates429444
Ref: userman/errors errors-redefinition-predicates429672
Ref: 258429672
Ref: userman/errors redefinition-of-logtalk-built-in-predicates429672
Ref: 259429672
Node: Redefinition of Logtalk built-in methods429991
Ref: userman/errors errors-redefinition-methods430211
Ref: 25a430211
Ref: userman/errors redefinition-of-logtalk-built-in-methods430211
Ref: 25b430211
Node: Misspell calls of local predicates430503
Ref: userman/errors errors-misspell430700
Ref: 25c430700
Ref: userman/errors misspell-calls-of-local-predicates430700
Ref: 25d430700
Node: Portability warnings431041
Ref: userman/errors errors-portability431217
Ref: 25e431217
Ref: userman/errors portability-warnings431217
Ref: 25f431217
Node: Deprecated elements431577
Ref: userman/errors deprecated-elements431737
Ref: 260431737
Ref: userman/errors errors-deprecated431737
Ref: 261431737
Node: Missing directives432032
Ref: userman/errors errors-missing-directives432193
Ref: 262432193
Ref: userman/errors missing-directives432193
Ref: 263432193
Node: Duplicated directives432366
Ref: userman/errors duplicated-directives432526
Ref: 264432526
Ref: userman/errors errors-duplicated-directives432526
Ref: 265432526
Node: Duplicated clauses432848
Ref: userman/errors duplicated-clauses433025
Ref: 266433025
Ref: userman/errors errors-duplicated-clauses433025
Ref: 267433025
Node: Goals that are always true or false433229
Ref: userman/errors errors-always-true-or-false-goals433398
Ref: 268433398
Ref: userman/errors goals-that-are-always-true-or-false433398
Ref: 269433398
Node: Trivial fails433667
Ref: userman/errors errors-trivial-fails433834
Ref: 26a433834
Ref: userman/errors trivial-fails433834
Ref: 26b433834
Node: Suspicious calls433977
Ref: userman/errors errors-suspicious-calls434125
Ref: 26c434125
Ref: userman/errors suspicious-calls434125
Ref: 26d434125
Node: Lambda variables434472
Ref: userman/errors errors-lambda-variables434679
Ref: 26e434679
Ref: userman/errors lambda-variables434679
Ref: 26f434679
Node: Redefinition of predicates declared in uses/2 or use_module/2 directives435057
Ref: userman/errors errors-predicate-redefinition435273
Ref: 272435273
Ref: userman/errors redefinition-of-predicates-declared-in-uses-2-or-use-module-2-directives435273
Ref: 273435273
Node: Other warnings and errors435615
Ref: userman/errors errors-others435806
Ref: 274435806
Ref: userman/errors other-warnings-and-errors435806
Ref: 275435806
Node: Runtime errors436062
Ref: userman/errors errors-runtime436184
Ref: 276436184
Ref: userman/errors runtime-errors436184
Ref: 277436184
Node: Logtalk built-in predicates436562
Ref: userman/errors errors-predicates436693
Ref: 278436693
Ref: userman/errors logtalk-built-in-predicates436693
Ref: 279436693
Node: Logtalk built-in methods436893
Ref: userman/errors errors-methods437048
Ref: 27a437048
Ref: userman/errors logtalk-built-in-methods437048
Ref: 27b437048
Node: Message sending437238
Ref: userman/errors errors-sending437357
Ref: 27c437357
Ref: userman/errors message-sending437357
Ref: 27d437357
Ref: Message sending-Footnote-1438274
Node: Reflection438324
Ref: userman/reflection doc438466
Ref: 27e438466
Ref: userman/reflection reflection438466
Ref: 27f438466
Ref: userman/reflection reflection-reflection438466
Ref: 48438466
Node: Structural reflection438931
Ref: userman/reflection reflection-structural439049
Ref: 281439049
Ref: userman/reflection structural-reflection439049
Ref: 282439049
Node: Transparent-box view439397
Ref: userman/reflection transparent-box-view439518
Ref: 283439518
Ref: Transparent-box view-Footnote-1440943
Node: Black-box view440987
Ref: userman/reflection black-box-view441108
Ref: 286441108
Node: Behavioral reflection441834
Ref: userman/reflection behavioral-reflection441952
Ref: 287441952
Ref: userman/reflection reflection-behavioral441952
Ref: 288441952
Ref: Behavioral reflection-Footnote-1442565
Node: Writing and running applications442609
Ref: userman/programming doc442775
Ref: 28a442775
Ref: userman/programming programming-programming442775
Ref: 28b442775
Ref: userman/programming writing-and-running-applications442775
Ref: 28c442775
Node: Starting Logtalk444496
Ref: userman/programming programming-starting444644
Ref: 28e444644
Ref: userman/programming starting-logtalk444644
Ref: 28f444644
Node: Running parallel Logtalk processes445731
Ref: userman/programming programming-parallel-processes445900
Ref: 290445900
Ref: userman/programming running-parallel-logtalk-processes445900
Ref: 291445900
Node: Source files448076
Ref: userman/programming programming-source-files448248
Ref: 294448248
Ref: userman/programming source-files448248
Ref: 295448248
Ref: Source files-Footnote-1451274
Ref: Source files-Footnote-2451351
Node: Naming conventions451428
Ref: userman/programming naming-conventions451549
Ref: 296451549
Node: Source file text encoding452141
Ref: userman/programming source-file-text-encoding452262
Ref: 297452262
Node: Multi-pass compiler452609
Ref: userman/programming multi-pass-compiler452786
Ref: 29a452786
Ref: userman/programming programming-multi-pass-compiler452786
Ref: 29b452786
Node: Compiling and loading your applications455064
Ref: userman/programming compiling-and-loading-your-applications455266
Ref: 29c455266
Ref: userman/programming programming-compiling455266
Ref: 29d455266
Node: Compiler errors warnings and comments458268
Ref: userman/programming compiler-errors-warnings-and-comments458463
Ref: 2a1458463
Ref: userman/programming programming-errors-warnings-comments458463
Ref: 2a2458463
Node: Loader files459372
Ref: userman/programming loader-files459553
Ref: 2a3459553
Ref: userman/programming programming-loaders459553
Ref: 2a4459553
Node: Libraries of source files463112
Ref: userman/programming libraries-of-source-files463270
Ref: 2a5463270
Ref: userman/programming programming-libraries463270
Ref: 2a6463270
Node: Settings files466141
Ref: userman/programming programming-settings466302
Ref: 2a9466302
Ref: userman/programming settings-files466302
Ref: 2aa466302
Node: Compiler linter469051
Ref: userman/programming compiler-linter469201
Ref: 2ad469201
Ref: userman/programming programming-linter469201
Ref: 2ae469201
Node: Compiler flags469973
Ref: userman/programming compiler-flags470131
Ref: 2b1470131
Ref: userman/programming programming-flags470131
Ref: 251470131
Node: Read-only flags472729
Ref: userman/programming read-only-flags472837
Ref: 2b4472837
Ref: userman/programming flag-settings-file473047
Ref: 2ab473047
Ref: userman/programming flag-prolog-dialect473718
Ref: 2ac473718
Ref: userman/programming flag-prolog-version473916
Ref: 2b5473916
Ref: userman/programming flag-prolog-compatible-version474258
Ref: 2b6474258
Ref: userman/programming flag-unicode474656
Ref: 2b7474656
Ref: userman/programming flag-encoding-directive474929
Ref: 299474929
Ref: userman/programming flag-sockets475361
Ref: 2b8475361
Ref: userman/programming flag-tabling475552
Ref: 2b9475552
Ref: userman/programming flag-engines475744
Ref: 2ba475744
Ref: userman/programming flag-threads476004
Ref: 225476004
Ref: userman/programming flag-modules476286
Ref: 2bc476286
Ref: userman/programming flag-coinduction476582
Ref: 172476582
Node: Version flags476862
Ref: userman/programming version-flags476989
Ref: 2bd476989
Ref: userman/programming flag-version-data477038
Ref: 2be477038
Node: Lint flags477555
Ref: userman/programming lint-flags477702
Ref: 2bf477702
Ref: userman/programming programming-flags-lint477702
Ref: 2b0477702
Ref: userman/programming flag-linter477745
Ref: 2c0477745
Ref: userman/programming flag-unknown-entities478273
Ref: 2c1478273
Ref: userman/programming flag-unknown-predicates478666
Ref: 2c2478666
Ref: userman/programming flag-undefined-predicates479142
Ref: 2c3479142
Ref: userman/programming flag-steadfastness479500
Ref: 2c4479500
Ref: userman/programming flag-portability479832
Ref: 1d1479832
Ref: userman/programming flag-deprecated480152
Ref: 2c6480152
Ref: userman/programming flag-missing-directives480313
Ref: 2c7480313
Ref: userman/programming flag-duplicated-directives480512
Ref: 2c8480512
Ref: userman/programming flag-trivial-goal-fails480845
Ref: 2c9480845
Ref: userman/programming flag-always-true-or-false-goals481090
Ref: 2ca481090
Ref: userman/programming flag-grammar-rules481394
Ref: 190481394
Ref: userman/programming flag-arithmetic-expressions481594
Ref: 2cb481594
Ref: userman/programming flag-lambda-variables481811
Ref: 186481811
Ref: userman/programming flag-suspicious-calls482015
Ref: 2cc482015
Ref: userman/programming flag-redefined-built-ins482212
Ref: 189482212
Ref: userman/programming flag-redefined-operators482632
Ref: 2cd482632
Ref: userman/programming flag-singleton-variables483001
Ref: 2ce483001
Ref: userman/programming flag-naming483187
Ref: 2cf483187
Ref: userman/programming flag-duplicated-clauses483663
Ref: 2d0483663
Ref: userman/programming flag-disjunctions484095
Ref: 2d1484095
Ref: userman/programming flag-conditionals484432
Ref: 2d2484432
Ref: userman/programming flag-catchall-catch484766
Ref: 2d3484766
Ref: userman/programming flag-left-recursion485099
Ref: 2d4485099
Ref: userman/programming flag-tail-recursive485395
Ref: 2d5485395
Ref: userman/programming flag-encodings485844
Ref: 2d6485844
Ref: userman/programming flag-general486009
Ref: 2d7486009
Node: Optional features compilation flags486189
Ref: userman/programming optional-features-compilation-flags486363
Ref: 2d8486363
Ref: userman/programming flag-complements486456
Ref: 112486456
Ref: userman/programming flag-dynamic-declarations487144
Ref: 2d9487144
Ref: userman/programming flag-events487749
Ref: 89487749
Ref: userman/programming flag-context-switching-calls488305
Ref: 2da488305
Node: Backend Prolog compiler and loader flags488633
Ref: userman/programming backend-prolog-compiler-and-loader-flags488808
Ref: 2db488808
Ref: userman/programming flag-underscore-variables488911
Ref: 2dc488911
Ref: userman/programming flag-prolog-compiler489401
Ref: 2dd489401
Ref: userman/programming flag-prolog-loader489903
Ref: 2de489903
Node: Other flags490247
Ref: userman/programming other-flags490405
Ref: 2df490405
Ref: userman/programming flag-scratch-directory490450
Ref: 2e0490450
Ref: userman/programming flag-report491336
Ref: 2e1491336
Ref: userman/programming flag-code-prefix491714
Ref: 2e2491714
Ref: userman/programming flag-optimize492582
Ref: 8c492582
Ref: userman/programming flag-source-data493530
Ref: cc493530
Ref: userman/programming flag-debug494178
Ref: 2e3494178
Ref: userman/programming flag-reload494601
Ref: 2e4494601
Ref: userman/programming flag-relative-to495158
Ref: 2e5495158
Ref: userman/programming flag-hook495341
Ref: fe495341
Ref: userman/programming flag-clean495766
Ref: 292495766
Ref: Other flags-Footnote-1496798
Ref: Other flags-Footnote-2496836
Node: User-defined flags496884
Ref: userman/programming user-defined-flags496993
Ref: 2e6496993
Node: Reloading source files497157
Ref: userman/programming programming-reloading497316
Ref: 2e8497316
Ref: userman/programming reloading-source-files497316
Ref: 2e9497316
Node: Batch processing499805
Ref: userman/programming batch-processing499972
Ref: 2ea499972
Ref: userman/programming programming-batch499972
Ref: 2eb499972
Node: Optimizing performance500359
Ref: userman/programming optimizing-performance500525
Ref: 2ec500525
Ref: userman/programming programming-performance500525
Ref: 2ed500525
Node: Portable applications502576
Ref: userman/programming portable-applications502749
Ref: 2ef502749
Ref: userman/programming programming-portability502749
Ref: 2f0502749
Node: Conditional compilation503689
Ref: userman/programming conditional-compilation503862
Ref: 2f1503862
Ref: userman/programming programming-cc503862
Ref: 2f2503862
Node: Avoiding common errors504233
Ref: userman/programming avoiding-common-errors504408
Ref: 2f7504408
Ref: userman/programming programming-errors504408
Ref: 2f8504408
Node: Coding style guidelines506126
Ref: userman/programming coding-style-guidelines506269
Ref: 2f9506269
Ref: userman/programming programming-style506269
Ref: 2fa506269
Node: Printing messages and asking questions507068
Ref: userman/printing doc507247
Ref: 2fb507247
Ref: userman/printing printing-messages-and-asking-questions507247
Ref: 2fc507247
Ref: userman/printing printing-printing507247
Ref: 18b507247
Ref: Printing messages and asking questions-Footnote-1510573
Node: Printing messages510617
Ref: userman/printing id1510758
Ref: 2fe510758
Ref: userman/printing printing-messages510758
Ref: d3510758
Node: Message tokenization514477
Ref: userman/printing message-tokenization514640
Ref: 300514640
Node: Meta-messages516955
Ref: userman/printing meta-messages517145
Ref: 302517145
Ref: Meta-messages-Footnote-1517583
Node: Defining message prefixes and output streams517627
Ref: userman/printing defining-message-prefixes-and-output-streams517839
Ref: 304517839
Node: Defining message prefixes and output files519532
Ref: userman/printing defining-message-prefixes-and-output-files519752
Ref: 306519752
Node: Intercepting messages521390
Ref: userman/printing id2521582
Ref: 309521582
Ref: userman/printing intercepting-messages521582
Ref: 30a521582
Node: Asking questions523232
Ref: userman/printing asking-questions523404
Ref: 30b523404
Ref: userman/printing printing-questions523404
Ref: d4523404
Node: Intercepting questions526272
Ref: userman/printing intercepting-questions526454
Ref: 30d526454
Node: Multi-threading applications<4>527980
Ref: userman/printing multi-threading-applications528137
Ref: 30f528137
Node: Term and goal expansion528420
Ref: userman/expansion doc528578
Ref: 310528578
Ref: userman/expansion expansion-expansion528578
Ref: cb528578
Ref: userman/expansion term-and-goal-expansion528578
Ref: 311528578
Node: Defining expansions530037
Ref: userman/expansion defining-expansions530168
Ref: 312530168
Ref: Defining expansions-Footnote-1533978
Node: Expanding grammar rules534026
Ref: userman/expansion expanding-grammar-rules534186
Ref: 314534186
Node: Bypassing expansions534787
Ref: userman/expansion bypassing-expansions534940
Ref: 315534940
Node: Hook objects535350
Ref: userman/expansion hook-objects535525
Ref: 316535525
Ref: Hook objects-Footnote-1537948
Node: Virtual source file terms and loading context537996
Ref: userman/expansion virtual-source-file-terms-and-loading-context538186
Ref: 317538186
Node: Default compiler expansion workflow540162
Ref: userman/expansion default-compiler-expansion-workflow540372
Ref: 319540372
Node: User defined expansion workflows541118
Ref: userman/expansion user-defined-expansion-workflows541314
Ref: 31a541314
Ref: User defined expansion workflows-Footnote-1543033
Ref: User defined expansion workflows-Footnote-2543089
Ref: User defined expansion workflows-Footnote-3543135
Ref: User defined expansion workflows-Footnote-4543205
Node: Using Prolog defined expansions543261
Ref: userman/expansion using-prolog-defined-expansions543442
Ref: 31d543442
Ref: Using Prolog defined expansions-Footnote-1545195
Node: Debugging expansions545261
Ref: userman/expansion debugging-expansions545401
Ref: 31e545401
Node: Documenting548424
Ref: userman/documenting doc548553
Ref: 321548553
Ref: userman/documenting documenting548553
Ref: 322548553
Ref: userman/documenting documenting-documenting548553
Ref: b5548553
Node: Entity documenting directives550053
Ref: userman/documenting documenting-entity550191
Ref: 324550191
Ref: userman/documenting entity-documenting-directives550191
Ref: 325550191
Ref: Entity documenting directives-Footnote-1553255
Ref: Entity documenting directives-Footnote-2553282
Node: Predicate documenting directives553317
Ref: userman/documenting documenting-predicate553485
Ref: 326553485
Ref: userman/documenting predicate-documenting-directives553485
Ref: 327553485
Node: Describing predicates557172
Ref: userman/documenting describing-predicates557343
Ref: 328557343
Ref: userman/documenting documenting-descriptions557343
Ref: 329557343
Node: Documenting predicate exceptions558602
Ref: userman/documenting documenting-exceptions558781
Ref: 32a558781
Ref: userman/documenting documenting-predicate-exceptions558781
Ref: 32b558781
Node: Processing and viewing documenting files561587
Ref: userman/documenting documenting-processing561779
Ref: 32c561779
Ref: userman/documenting processing-and-viewing-documenting-files561779
Ref: 32d561779
Node: Inline formatting in comments text565530
Ref: userman/documenting documenting-formatting565698
Ref: 32f565698
Ref: userman/documenting inline-formatting-in-comments-text565698
Ref: 330565698
Node: Diagrams566740
Ref: userman/documenting diagrams566859
Ref: 331566859
Node: Debugging567493
Ref: userman/debugging doc567613
Ref: 332567613
Ref: userman/debugging debugging567613
Ref: 333567613
Ref: userman/debugging debugging-debugging567613
Ref: 47567613
Node: Compiling source files in debug mode569401
Ref: userman/debugging compiling-source-files-in-debug-mode569531
Ref: 334569531
Ref: userman/debugging debugging-debug-mode569531
Ref: 335569531
Node: Procedure box model571461
Ref: userman/debugging debugging-box-model571623
Ref: 336571623
Ref: userman/debugging procedure-box-model571623
Ref: 337571623
Node: Activating the debugger573557
Ref: userman/debugging activating-the-debugger573703
Ref: 338573703
Ref: Activating the debugger-Footnote-1574242
Ref: Activating the debugger-Footnote-2574298
Ref: Activating the debugger-Footnote-3574354
Node: Defining breakpoints574412
Ref: userman/debugging defining-breakpoints574558
Ref: 33a574558
Node: Defining predicate and clause breakpoints576603
Ref: userman/debugging defining-predicate-and-clause-breakpoints576762
Ref: 33b576762
Node: Defining conditional breakpoints578118
Ref: userman/debugging defining-conditional-breakpoints578316
Ref: 33c578316
Node: Defining hit count breakpoints579526
Ref: userman/debugging defining-hit-count-breakpoints579713
Ref: 33d579713
Node: Defining triggered breakpoints580733
Ref: userman/debugging defining-triggered-breakpoints580916
Ref: 33e580916
Node: Defining context breakpoints581778
Ref: userman/debugging defining-context-breakpoints581955
Ref: 33f581955
Node: Removing all breakpoints583147
Ref: userman/debugging removing-all-breakpoints583285
Ref: 340583285
Node: Defining log points583662
Ref: userman/debugging defining-log-points583810
Ref: 341583810
Node: Tracing program execution585708
Ref: userman/debugging programming-trace585863
Ref: 342585863
Ref: userman/debugging tracing-program-execution585863
Ref: 343585863
Node: Debugging using breakpoints588023
Ref: userman/debugging debugging-debug588177
Ref: 344588177
Ref: userman/debugging debugging-using-breakpoints588177
Ref: 345588177
Node: Debugging commands588859
Ref: userman/debugging debugging-commands589012
Ref: 346589012
Ref: userman/debugging id1589012
Ref: 347589012
Node: Customizing term writing592132
Ref: userman/debugging customizing-term-writing592281
Ref: 348592281
Ref: userman/debugging debugging-term-write592281
Ref: 349592281
Node: Term write depth592832
Ref: userman/debugging debugging-term-write-depth592957
Ref: 34a592957
Ref: userman/debugging term-write-depth592957
Ref: 34b592957
Ref: Term write depth-Footnote-1594012
Ref: Term write depth-Footnote-2594078
Node: Custom term writing594148
Ref: userman/debugging custom-term-writing594273
Ref: 34c594273
Ref: userman/debugging debugging-custom-term-writing594273
Ref: 34d594273
Node: Context-switching calls594896
Ref: userman/debugging context-switching-calls595045
Ref: 34e595045
Ref: userman/debugging debugging-context595045
Ref: 34f595045
Node: Debugging messages597010
Ref: userman/debugging debugging-messages597183
Ref: 303597183
Ref: userman/debugging id2597183
Ref: 350597183
Node: Meta-messages<2>597795
Ref: userman/debugging meta-messages597931
Ref: 351597931
Node: Selective printing of debug messages601056
Ref: userman/debugging selective-printing-of-debug-messages601192
Ref: 352601192
Node: Using the term-expansion mechanism for debugging602269
Ref: userman/debugging debugging-hooks602434
Ref: 355602434
Ref: userman/debugging using-the-term-expansion-mechanism-for-debugging602434
Ref: 356602434
Ref: Using the term-expansion mechanism for debugging-Footnote-1603032
Node: Ports profiling603092
Ref: userman/debugging debugging-ports-profiling603261
Ref: 357603261
Ref: userman/debugging ports-profiling603261
Ref: 358603261
Node: Debug and trace events603602
Ref: userman/debugging debug-and-trace-events603744
Ref: 35a603744
Ref: userman/debugging debugging-events603744
Ref: d5603744
Ref: Debug and trace events-Footnote-1606273
Ref: Debug and trace events-Footnote-2606331
Ref: Debug and trace events-Footnote-3606391
Ref: Debug and trace events-Footnote-4606451
Ref: Debug and trace events-Footnote-5606520
Ref: Debug and trace events-Footnote-6606591
Node: Source-level debugger606649
Ref: userman/debugging debugging-source-level-debugger606767
Ref: 35b606767
Ref: userman/debugging source-level-debugger606767
Ref: 35c606767
Node: Performance<2>607159
Ref: userman/performance doc607286
Ref: 35d607286
Ref: userman/performance performance607286
Ref: 35e607286
Ref: userman/performance performance-performance607286
Ref: 38607286
Node: Source code compilation modes608937
Ref: userman/performance source-code-compilation-modes609075
Ref: 362609075
Node: Source code compilation order609809
Ref: userman/performance source-code-compilation-order609977
Ref: 363609977
Ref: Source code compilation order-Footnote-1610709
Ref: Source code compilation order-Footnote-2610786
Node: Local predicate calls610863
Ref: userman/performance local-predicate-calls611043
Ref: 364611043
Node: Calls to imported or inherited predicates611254
Ref: userman/performance calls-to-imported-or-inherited-predicates611431
Ref: 365611431
Node: Calls to module predicates611683
Ref: userman/performance calls-to-module-predicates611850
Ref: 366611850
Node: Messages<2>612074
Ref: userman/performance messages612247
Ref: 367612247
Node: Automatic expansion of built-in meta-predicates614880
Ref: userman/performance automatic-expansion-of-built-in-meta-predicates615035
Ref: 368615035
Node: Inlining615578
Ref: userman/performance inlining615769
Ref: 369615769
Node: Generated code simplification and optimizations616302
Ref: userman/performance generated-code-simplification-and-optimizations616472
Ref: 36a616472
Node: Size of the generated code617083
Ref: userman/performance size-of-the-generated-code617264
Ref: 36c617264
Node: Circular references618434
Ref: userman/performance circular-references618587
Ref: 36d618587
Node: Debug mode overhead619023
Ref: userman/performance debug-mode-overhead619170
Ref: 36e619170
Ref: Debug mode overhead-Footnote-1620535
Ref: Debug mode overhead-Footnote-2620593
Node: Other considerations620653
Ref: userman/performance other-considerations620772
Ref: 36f620772
Ref: Other considerations-Footnote-1621386
Ref: Other considerations-Footnote-2621464
Ref: Other considerations-Footnote-3621547
Node: Installing Logtalk621592
Ref: userman/installing doc621742
Ref: 370621742
Ref: userman/installing installing-installing621742
Ref: 371621742
Ref: userman/installing installing-logtalk621742
Ref: 372621742
Node: Hardware and software requirements623707
Ref: userman/installing hardware-and-software-requirements623843
Ref: 373623843
Ref: userman/installing installing-requirements623843
Ref: 374623843
Node: Computer and operating system623992
Ref: userman/installing computer-and-operating-system624136
Ref: 375624136
Ref: userman/installing installing-computer624136
Ref: 376624136
Node: Prolog compiler624343
Ref: userman/installing installing-compiler624487
Ref: 377624487
Ref: userman/installing prolog-compiler624487
Ref: 378624487
Node: Logtalk installers625769
Ref: userman/installing installing-installers625933
Ref: 379625933
Ref: userman/installing logtalk-installers625933
Ref: 37a625933
Node: Source distribution626231
Ref: userman/installing installing-sources626382
Ref: 37b626382
Ref: userman/installing source-distribution626382
Ref: 37c626382
Node: Distribution overview627030
Ref: userman/installing distribution-overview627154
Ref: 37d627154
Ref: userman/installing installing-organization627154
Ref: 37e627154
Node: Adapter files631484
Ref: userman/installing adapter-files631604
Ref: 37f631604
Ref: userman/installing installing-adapters631604
Ref: 380631604
Node: Compiler and runtime633096
Ref: userman/installing compiler-and-runtime633232
Ref: 381633232
Ref: userman/installing installing-runtime633232
Ref: 382633232
Node: Library633594
Ref: userman/installing installing-library633725
Ref: 383633725
Ref: userman/installing library633725
Ref: 384633725
Node: Examples633944
Ref: userman/installing examples634075
Ref: 385634075
Ref: userman/installing installing-examples634075
Ref: 386634075
Node: Logtalk source files634585
Ref: userman/installing installing-entities634700
Ref: 387634700
Ref: userman/installing logtalk-source-files634700
Ref: 388634700
Node: Prolog integration and migration635352
Ref: userman/migration doc635479
Ref: 389635479
Ref: userman/migration migration-migration635479
Ref: 38a635479
Ref: userman/migration prolog-integration-and-migration635479
Ref: 38b635479
Node: Source files with both Prolog code and Logtalk code636501
Ref: userman/migration migration-hybrid636692
Ref: 38d636692
Ref: userman/migration source-files-with-both-prolog-code-and-logtalk-code636692
Ref: 38e636692
Node: Encapsulating plain Prolog code in objects637559
Ref: userman/migration encapsulating-plain-prolog-code-in-objects637797
Ref: 38f637797
Ref: userman/migration migration-encapsulating637797
Ref: 390637797
Node: Prolog multifile predicates639808
Ref: userman/migration migration-multifile639934
Ref: 391639934
Ref: userman/migration prolog-multifile-predicates639934
Ref: 392639934
Node: Converting Prolog modules into objects641626
Ref: userman/migration converting-prolog-modules-into-objects641848
Ref: 394641848
Ref: userman/migration migration-converting641848
Ref: 395641848
Node: Compiling Prolog modules as objects646726
Ref: userman/migration compiling-prolog-modules-as-objects646963
Ref: 396646963
Ref: userman/migration migration-compiling646963
Ref: 397646963
Node: Supported module directives648872
Ref: userman/migration migration-compatibility649029
Ref: 398649029
Ref: userman/migration supported-module-directives649029
Ref: 399649029
Node: Unsupported module directives653103
Ref: userman/migration migration-unsupported-module-directives653309
Ref: 39b653309
Ref: userman/migration unsupported-module-directives653309
Ref: 39c653309
Node: Modules using a term-expansion mechanism654478
Ref: userman/migration migration-module-expansions654674
Ref: 39d654674
Ref: userman/migration modules-using-a-term-expansion-mechanism654674
Ref: 39e654674
Node: File search paths656887
Ref: userman/migration file-search-paths657045
Ref: 3a0657045
Ref: userman/migration migration-file-search-paths657045
Ref: 3a1657045
Node: Dealing with proprietary Prolog directives and predicates657656
Ref: userman/migration dealing-with-proprietary-prolog-directives-and-predicates657890
Ref: 3a2657890
Ref: userman/migration migration-proprietary657890
Ref: 3a3657890
Node: Calling Prolog module predicates<2>660255
Ref: userman/migration calling-prolog-module-predicates660491
Ref: 3a4660491
Ref: userman/migration migration-calling660491
Ref: 3a5660491
Node: Loading converted Prolog applications662988
Ref: userman/migration loading-converted-prolog-applications663158
Ref: 3a6663158
Ref: userman/migration migration-loading663158
Ref: 3a7663158
Node: Reference Manual664621
Ref: refman/index doc664734
Ref: 3a8664734
Ref: refman/index reference-manual664734
Ref: 3a9664734
Node: Grammar664912
Ref: refman/grammar doc665019
Ref: 3aa665019
Ref: refman/grammar grammar665019
Ref: 3ab665019
Ref: refman/grammar grammar-grammar665019
Ref: 3ac665019
Node: Entities665667
Ref: refman/grammar entities665765
Ref: 3ad665765
Ref: refman/grammar grammar-entities665765
Ref: 3ae665765
Node: Object definition665866
Ref: refman/grammar grammar-object-definition665992
Ref: 3af665992
Ref: refman/grammar object-definition665992
Ref: 3b0665992
Node: Category definition666876
Ref: refman/grammar category-definition667013
Ref: 3b1667013
Ref: refman/grammar grammar-category-definition667013
Ref: 3b2667013
Node: Protocol definition667554
Ref: refman/grammar grammar-protocol-definition667690
Ref: 3b3667690
Ref: refman/grammar protocol-definition667690
Ref: 3b4667690
Node: Entity relations668012
Ref: refman/grammar entity-relations668147
Ref: 3b5668147
Ref: refman/grammar grammar-entity-relations668147
Ref: 3b6668147
Node: Implemented protocols669021
Ref: refman/grammar grammar-implemented-protocols669142
Ref: 3b7669142
Ref: refman/grammar implemented-protocols669142
Ref: 3b8669142
Node: Extended protocols669646
Ref: refman/grammar extended-protocols669795
Ref: 3b9669795
Ref: refman/grammar grammar-extended-protocols669795
Ref: 3ba669795
Node: Imported categories670260
Ref: refman/grammar grammar-imported-categories670404
Ref: 3bb670404
Ref: refman/grammar imported-categories670404
Ref: 3bc670404
Node: Extended objects670872
Ref: refman/grammar extended-objects671017
Ref: 3bd671017
Ref: refman/grammar grammar-extended-objects671017
Ref: 3be671017
Node: Extended categories671452
Ref: refman/grammar extended-categories671598
Ref: 3bf671598
Ref: refman/grammar grammar-extended-categories671598
Ref: 3c0671598
Node: Instantiated objects672066
Ref: refman/grammar grammar-instantiated-objects672215
Ref: 3c1672215
Ref: refman/grammar instantiated-objects672215
Ref: 3c2672215
Node: Specialized objects672702
Ref: refman/grammar grammar-specialized-objects672852
Ref: 3c3672852
Ref: refman/grammar specialized-objects672852
Ref: 3c4672852
Node: Complemented objects673326
Ref: refman/grammar complemented-objects673482
Ref: 3c5673482
Ref: refman/grammar grammar-complemented-objects673482
Ref: 3c6673482
Node: Entity and predicate scope673864
Ref: refman/grammar entity-and-predicate-scope673992
Ref: 3c7673992
Ref: refman/grammar grammar-scope673992
Ref: 3c8673992
Node: Entity identifiers674138
Ref: refman/grammar entity-identifiers674269
Ref: 3c9674269
Ref: refman/grammar grammar-entity-identifiers674269
Ref: 3ca674269
Node: Object identifiers674540
Ref: refman/grammar grammar-object-identifiers674662
Ref: 3cb674662
Ref: refman/grammar object-identifiers674662
Ref: 3cc674662
Node: Category identifiers674777
Ref: refman/grammar category-identifiers674928
Ref: 3cd674928
Ref: refman/grammar grammar-category-identifiers674928
Ref: 3ce674928
Node: Protocol identifiers675049
Ref: refman/grammar grammar-protocol-identifiers675200
Ref: 3cf675200
Ref: refman/grammar protocol-identifiers675200
Ref: 3d0675200
Node: Module identifiers675302
Ref: refman/grammar grammar-module-identifiers675424
Ref: 3d1675424
Ref: refman/grammar module-identifiers675424
Ref: 3d2675424
Node: Source files<2>675520
Ref: refman/grammar grammar-source-files675652
Ref: 3d3675652
Ref: refman/grammar source-files675652
Ref: 3d4675652
Node: Source file names675863
Ref: refman/grammar grammar-source-file-names675982
Ref: 3d5675982
Ref: refman/grammar source-file-names675982
Ref: 3d6675982
Node: Terms676211
Ref: refman/grammar grammar-terms676325
Ref: 3d7676325
Ref: refman/grammar terms676325
Ref: 3d8676325
Node: Object terms676396
Ref: refman/grammar grammar-object-terms676493
Ref: 3d9676493
Ref: refman/grammar object-terms676493
Ref: 3da676493
Node: Category terms676623
Ref: refman/grammar category-terms676720
Ref: 3db676720
Ref: refman/grammar grammar-category-terms676720
Ref: 3dc676720
Node: Directives676858
Ref: refman/grammar directives676972
Ref: 3dd676972
Ref: refman/grammar grammar-directives676972
Ref: 3de676972
Node: Source file directives677247
Ref: refman/grammar grammar-source-file-directives677379
Ref: 3df677379
Ref: refman/grammar source-file-directives677379
Ref: 3e0677379
Node: Conditional compilation directives677636
Ref: refman/grammar conditional-compilation-directives677797
Ref: 3e1677797
Ref: refman/grammar grammar-conditional-compilation-directives677797
Ref: 3e2677797
Node: Object directives<2>678039
Ref: refman/grammar grammar-object-directives678200
Ref: 3e3678200
Ref: refman/grammar object-directives678200
Ref: 3e4678200
Node: Category directives<2>678710
Ref: refman/grammar category-directives678859
Ref: 3e5678859
Ref: refman/grammar grammar-category-directives678859
Ref: 3e6678859
Node: Protocol directives<2>679305
Ref: refman/grammar grammar-protocol-directives679454
Ref: 3e7679454
Ref: refman/grammar protocol-directives679454
Ref: 3e8679454
Node: Predicate directives679806
Ref: refman/grammar grammar-predicate-directives679924
Ref: 3e9679924
Ref: refman/grammar predicate-directives679924
Ref: 3ea679924
Node: Clauses and goals690093
Ref: refman/grammar clauses-and-goals690223
Ref: 3eb690223
Ref: refman/grammar grammar-clauses690223
Ref: 3ec690223
Node: Lambda expressions<2>691374
Ref: refman/grammar grammar-lambdas691511
Ref: 185691511
Ref: refman/grammar lambda-expressions691511
Ref: 3ed691511
Node: Entity properties691979
Ref: refman/grammar entity-properties692122
Ref: 3ee692122
Ref: refman/grammar grammar-entity-properties692122
Ref: c8692122
Node: Predicate properties<2>699015
Ref: refman/grammar grammar-predicate-properties699154
Ref: 3ef699154
Ref: refman/grammar predicate-properties699154
Ref: 3f0699154
Node: Compiler flags<2>700506
Ref: refman/grammar compiler-flags700619
Ref: 3f1700619
Ref: refman/grammar grammar-compiler-flags700619
Ref: 3f2700619
Node: Control constructs700720
Ref: refman/control/index doc700849
Ref: 3f3700849
Ref: refman/control/index control-constructs700849
Ref: 3f4700849
Node: Message sending<2>701150
Ref: refman/control/message_sending doc701270
Ref: 3f5701270
Ref: refman/control/message_sending id1701270
Ref: 3f6701270
Ref: refman/control/message_sending message-sending701270
Ref: 361701270
Node: /2701374
Ref: refman/control/send_to_object_2 doc701462
Ref: 3f7701462
Ref: refman/control/send_to_object_2 control-send-to-object-2701462
Ref: 7e701462
Ref: refman/control/send_to_object_2 id1701462
Ref: 3f8701462
Node: Description701594
Ref: refman/control/send_to_object_2 description701699
Ref: 3f9701699
Node: Modes and number of proofs703369
Ref: refman/control/send_to_object_2 modes-and-number-of-proofs703489
Ref: 3fc703489
Node: Errors703663
Ref: refman/control/send_to_object_2 errors703783
Ref: 3fd703783
Node: Examples<2>705033
Ref: refman/control/send_to_object_2 examples705118
Ref: 3fe705118
Node: /1705332
Ref: refman/control/send_to_self_1 doc705420
Ref: 3ff705420
Ref: refman/control/send_to_self_1 control-send-to-self-1705420
Ref: 5c705420
Ref: refman/control/send_to_self_1 id1705420
Ref: 400705420
Node: Description<2>705607
Ref: refman/control/send_to_self_1 description705718
Ref: 401705718
Node: Modes and number of proofs<2>706846
Ref: refman/control/send_to_self_1 modes-and-number-of-proofs706975
Ref: 402706975
Node: Errors<2>707079
Ref: refman/control/send_to_self_1 errors707205
Ref: 403707205
Node: Examples<3>707718
Ref: refman/control/send_to_self_1 examples707806
Ref: 404707806
Node: Message delegation708020
Ref: refman/control/message_delegation doc708193
Ref: 405708193
Ref: refman/control/message_delegation id1708193
Ref: 406708193
Ref: refman/control/message_delegation message-delegation708193
Ref: 407708193
Node: []/1708284
Ref: refman/control/delegate_message_1 doc708363
Ref: 408708363
Ref: refman/control/delegate_message_1 control-delegate-message-1708363
Ref: 81708363
Ref: refman/control/delegate_message_1 id1708363
Ref: 409708363
Node: Description<3>708546
Ref: refman/control/delegate_message_1 description708659
Ref: 40a708659
Node: Modes and number of proofs<3>709587
Ref: refman/control/delegate_message_1 modes-and-number-of-proofs709718
Ref: 40b709718
Node: Errors<3>709896
Ref: refman/control/delegate_message_1 errors710024
Ref: 40c710024
Node: Examples<4>711456
Ref: refman/control/delegate_message_1 examples711546
Ref: 40d711546
Node: Calling imported and inherited predicates<2>711788
Ref: refman/control/super_calls doc711969
Ref: 40e711969
Ref: refman/control/super_calls calling-imported-and-inherited-predicates711969
Ref: 40f711969
Ref: refman/control/super_calls super-calls711969
Ref: 410711969
Node: ^^ /1712114
Ref: refman/control/call_super_1 doc712220
Ref: 411712220
Ref: refman/control/call_super_1 control-call-super-1712220
Ref: 5d712220
Ref: refman/control/call_super_1 id1712220
Ref: 412712220
Node: Description<4>712407
Ref: refman/control/call_super_1 description712521
Ref: 413712521
Node: Modes and number of proofs<4>714491
Ref: refman/control/call_super_1 modes-and-number-of-proofs714623
Ref: 414714623
Node: Errors<4>714727
Ref: refman/control/call_super_1 errors714856
Ref: 415714856
Node: Examples<5>715379
Ref: refman/control/call_super_1 examples715470
Ref: 416715470
Node: Calling predicates in this715713
Ref: refman/control/call_in_this doc715903
Ref: 417715903
Ref: refman/control/call_in_this call-in-this715903
Ref: 418715903
Ref: refman/control/call_in_this calling-predicates-in-this715903
Ref: 419715903
Node: @ /1716020
Ref: refman/control/call_in_this_1 doc716107
Ref: 41a716107
Ref: refman/control/call_in_this_1 call-in-this-1716107
Ref: 113716107
Ref: refman/control/call_in_this_1 id1716107
Ref: 41b716107
Node: Description<5>716292
Ref: refman/control/call_in_this_1 description716405
Ref: 41c716405
Node: Modes and number of proofs<5>717069
Ref: refman/control/call_in_this_1 modes-and-number-of-proofs717200
Ref: 41d717200
Node: Errors<5>717304
Ref: refman/control/call_in_this_1 errors717432
Ref: 41e717432
Node: Examples<6>717613
Ref: refman/control/call_in_this_1 examples717703
Ref: 41f717703
Node: Calling external predicates718066
Ref: refman/control/external_calls doc718235
Ref: 420718235
Ref: refman/control/external_calls calling-external-predicates718235
Ref: 421718235
Ref: refman/control/external_calls external-calls718235
Ref: 422718235
Node: {}/1718344
Ref: refman/control/external_call_1 doc718432
Ref: 423718432
Ref: refman/control/external_call_1 control-external-call-1718432
Ref: 191718432
Ref: refman/control/external_call_1 id1718432
Ref: 424718432
Node: Description<6>718615
Ref: refman/control/external_call_1 description718728
Ref: 425718728
Node: Modes and number of proofs<6>720229
Ref: refman/control/external_call_1 modes-and-number-of-proofs720360
Ref: 427720360
Node: Errors<6>720464
Ref: refman/control/external_call_1 errors720592
Ref: 428720592
Node: Examples<7>721162
Ref: refman/control/external_call_1 examples721252
Ref: 429721252
Node: Context switching calls721873
Ref: refman/control/context_switching_calls doc722007
Ref: 42a722007
Ref: refman/control/context_switching_calls context-switching-calls722007
Ref: 42b722007
Ref: refman/control/context_switching_calls id1722007
Ref: 42c722007
Node: << /2722116
Ref: refman/control/context_switch_2 doc722201
Ref: 42d722201
Ref: refman/control/context_switch_2 control-context-switch-2722201
Ref: c7722201
Ref: refman/control/context_switch_2 id1722201
Ref: 42e722201
Node: Description<7>722388
Ref: refman/control/context_switch_2 description722502
Ref: 42f722502
Node: Modes and number of proofs<7>724045
Ref: refman/control/context_switch_2 modes-and-number-of-proofs724177
Ref: 430724177
Node: Errors<7>724351
Ref: refman/control/context_switch_2 errors724480
Ref: 431724480
Node: Examples<8>725588
Ref: refman/control/context_switch_2 examples725679
Ref: 432725679
Node: Directives<2>725848
Ref: refman/directives/index doc725989
Ref: 433725989
Ref: refman/directives/index directives725989
Ref: 434725989
Node: Source file directives<2>726231
Ref: refman/directives/source_file_directives doc726372
Ref: 435726372
Ref: refman/directives/source_file_directives id1726372
Ref: 436726372
Ref: refman/directives/source_file_directives source-file-directives726372
Ref: 437726372
Node: encoding/1726536
Ref: refman/directives/encoding_1 doc726646
Ref: 438726646
Ref: refman/directives/encoding_1 directives-encoding-1726646
Ref: 298726646
Ref: refman/directives/encoding_1 encoding-1726646
Ref: 439726646
Node: Description<8>726782
Ref: refman/directives/encoding_1 description726890
Ref: 43a726890
Ref: Description<8>-Footnote-1728363
Node: Template and modes728440
Ref: refman/directives/encoding_1 template-and-modes728568
Ref: 43b728568
Node: Examples<9>728645
Ref: refman/directives/encoding_1 examples728750
Ref: 43c728750
Node: include/1728826
Ref: refman/directives/include_1 doc728961
Ref: 43d728961
Ref: refman/directives/include_1 directives-include-1728961
Ref: b8728961
Ref: refman/directives/include_1 include-1728961
Ref: 43e728961
Node: Description<9>729118
Ref: refman/directives/include_1 description729228
Ref: 43f729228
Node: Template and modes<2>731577
Ref: refman/directives/include_1 template-and-modes731708
Ref: 440731708
Node: Examples<10>731796
Ref: refman/directives/include_1 examples731904
Ref: 441731904
Node: initialization/1732510
Ref: refman/directives/initialization_1 doc732639
Ref: 442732639
Ref: refman/directives/initialization_1 directives-initialization-1732639
Ref: 42732639
Ref: refman/directives/initialization_1 initialization-1732639
Ref: 443732639
Node: Description<10>732811
Ref: refman/directives/initialization_1 description732929
Ref: 444732929
Node: Template and modes<3>734553
Ref: refman/directives/initialization_1 template-and-modes734692
Ref: 445734692
Node: Examples<11>734781
Ref: refman/directives/initialization_1 examples734896
Ref: 446734896
Node: op/3735476
Ref: refman/directives/op_3 doc735614
Ref: 447735614
Ref: refman/directives/op_3 directives-op-3735614
Ref: 15d735614
Ref: refman/directives/op_3 op-3735614
Ref: 448735614
Node: Description<11>735764
Ref: refman/directives/op_3 description735870
Ref: 449735870
Node: Template and modes<4>736321
Ref: refman/directives/op_3 template-and-modes736448
Ref: 44a736448
Node: Examples<12>736560
Ref: refman/directives/op_3 examples736663
Ref: 44b736663
Node: set_logtalk_flag/2737743
Ref: refman/directives/set_logtalk_flag_2 doc737856
Ref: 44c737856
Ref: refman/directives/set_logtalk_flag_2 directives-set-logtalk-flag-2737856
Ref: 50737856
Ref: refman/directives/set_logtalk_flag_2 set-logtalk-flag-2737856
Ref: 44d737856
Node: Description<12>738055
Ref: refman/directives/set_logtalk_flag_2 description738175
Ref: 44e738175
Node: Template and modes<5>738722
Ref: refman/directives/set_logtalk_flag_2 template-and-modes738860
Ref: 44f738860
Node: Errors<8>738956
Ref: refman/directives/set_logtalk_flag_2 errors739091
Ref: 450739091
Node: Examples<13>739590
Ref: refman/directives/set_logtalk_flag_2 examples739695
Ref: 451739695
Node: Conditional compilation directives<2>740266
Ref: refman/directives/conditional_compilation_directives doc740433
Ref: 452740433
Ref: refman/directives/conditional_compilation_directives conditional-compilation-directives740433
Ref: 18a740433
Ref: refman/directives/conditional_compilation_directives id1740433
Ref: 453740433
Node: if/1740582
Ref: refman/directives/if_1 doc740695
Ref: 454740695
Ref: refman/directives/if_1 directives-if-1740695
Ref: 2f3740695
Ref: refman/directives/if_1 if-1740695
Ref: 455740695
Node: Description<13>740843
Ref: refman/directives/if_1 description740949
Ref: 456740949
Node: Template and modes<6>741960
Ref: refman/directives/if_1 template-and-modes742087
Ref: 457742087
Node: Examples<14>742162
Ref: refman/directives/if_1 examples742265
Ref: 458742265
Node: elif/1743157
Ref: refman/directives/elif_1 doc743285
Ref: 459743285
Ref: refman/directives/elif_1 directives-elif-1743285
Ref: 2f4743285
Ref: refman/directives/elif_1 elif-1743285
Ref: 45a743285
Node: Description<14>743437
Ref: refman/directives/elif_1 description743545
Ref: 45b743545
Node: Template and modes<7>744510
Ref: refman/directives/elif_1 template-and-modes744639
Ref: 45c744639
Node: Examples<15>744716
Ref: refman/directives/elif_1 examples744821
Ref: 45d744821
Node: else/0745174
Ref: refman/directives/else_0 doc745305
Ref: 45e745305
Ref: refman/directives/else_0 directives-else-0745305
Ref: 2f5745305
Ref: refman/directives/else_0 else-0745305
Ref: 45f745305
Node: Description<15>745457
Ref: refman/directives/else_0 description745565
Ref: 460745565
Node: Template and modes<8>745820
Ref: refman/directives/else_0 template-and-modes745949
Ref: 461745949
Node: Examples<16>746017
Ref: refman/directives/else_0 examples746122
Ref: 462746122
Node: endif/0746726
Ref: refman/directives/endif_0 doc746842
Ref: 463746842
Ref: refman/directives/endif_0 directives-endif-0746842
Ref: 2f6746842
Ref: refman/directives/endif_0 endif-0746842
Ref: 464746842
Node: Description<16>746998
Ref: refman/directives/endif_0 description747107
Ref: 465747107
Node: Template and modes<9>747237
Ref: refman/directives/endif_0 template-and-modes747367
Ref: 466747367
Node: Examples<17>747436
Ref: refman/directives/endif_0 examples747542
Ref: 467747542
Node: Entity directives747762
Ref: refman/directives/entity_directives doc747927
Ref: 468747927
Ref: refman/directives/entity_directives entity-directives747927
Ref: 469747927
Ref: refman/directives/entity_directives id1747927
Ref: 46a747927
Node: built_in/0748186
Ref: refman/directives/built_in_0 doc748291
Ref: 46b748291
Ref: refman/directives/built_in_0 built-in-0748291
Ref: 46c748291
Ref: refman/directives/built_in_0 directives-built-in-0748291
Ref: 46d748291
Node: Description<17>748452
Ref: refman/directives/built_in_0 description748565
Ref: 46e748565
Node: Template and modes<10>748845
Ref: refman/directives/built_in_0 template-and-modes748979
Ref: 46f748979
Node: Examples<18>749049
Ref: refman/directives/built_in_0 examples749159
Ref: 470749159
Node: category/1-4749226
Ref: refman/directives/category_1_4 doc749349
Ref: 471749349
Ref: refman/directives/category_1_4 category-1-4749349
Ref: 472749349
Ref: refman/directives/category_1_4 directives-category-1-4749349
Ref: 10e749349
Node: Description<18>749514
Ref: refman/directives/category_1_4 description749629
Ref: 473749629
Node: Template and modes<11>750272
Ref: refman/directives/category_1_4 template-and-modes750408
Ref: 474750408
Node: Examples<19>751279
Ref: refman/directives/category_1_4 examples751391
Ref: 475751391
Node: dynamic/0751805
Ref: refman/directives/dynamic_0 doc751932
Ref: 476751932
Ref: refman/directives/dynamic_0 directives-dynamic-0751932
Ref: b1751932
Ref: refman/directives/dynamic_0 dynamic-0751932
Ref: 477751932
Node: Description<19>752091
Ref: refman/directives/dynamic_0 description752203
Ref: 478752203
Node: Template and modes<12>752835
Ref: refman/directives/dynamic_0 template-and-modes752968
Ref: 479752968
Node: Examples<20>753039
Ref: refman/directives/dynamic_0 examples753148
Ref: 47a753148
Node: end_category/0753350
Ref: refman/directives/end_category_0 doc753477
Ref: 47b753477
Ref: refman/directives/end_category_0 directives-end-category-0753477
Ref: 10f753477
Ref: refman/directives/end_category_0 end-category-0753477
Ref: 47c753477
Node: Description<20>753648
Ref: refman/directives/end_category_0 description753765
Ref: 47d753765
Node: Template and modes<13>753855
Ref: refman/directives/end_category_0 template-and-modes753993
Ref: 47e753993
Node: Examples<21>754069
Ref: refman/directives/end_category_0 examples754183
Ref: 47f754183
Node: end_object/0754301
Ref: refman/directives/end_object_0 doc754433
Ref: 480754433
Ref: refman/directives/end_object_0 directives-end-object-0754433
Ref: 9b754433
Ref: refman/directives/end_object_0 end-object-0754433
Ref: 481754433
Node: Description<21>754600
Ref: refman/directives/end_object_0 description754715
Ref: 482754715
Node: Template and modes<14>754801
Ref: refman/directives/end_object_0 template-and-modes754937
Ref: 483754937
Node: Examples<22>755011
Ref: refman/directives/end_object_0 examples755123
Ref: 484755123
Node: end_protocol/0755236
Ref: refman/directives/end_protocol_0 doc755360
Ref: 485755360
Ref: refman/directives/end_protocol_0 directives-end-protocol-0755360
Ref: dd755360
Ref: refman/directives/end_protocol_0 end-protocol-0755360
Ref: 486755360
Node: Description<22>755531
Ref: refman/directives/end_protocol_0 description755648
Ref: 487755648
Node: Template and modes<15>755738
Ref: refman/directives/end_protocol_0 template-and-modes755876
Ref: 488755876
Node: Examples<23>755952
Ref: refman/directives/end_protocol_0 examples756066
Ref: 489756066
Node: info/1756183
Ref: refman/directives/info_1 doc756305
Ref: 48a756305
Ref: refman/directives/info_1 directives-info-1756305
Ref: b4756305
Ref: refman/directives/info_1 info-1756305
Ref: 48b756305
Node: Description<23>756460
Ref: refman/directives/info_1 description756569
Ref: 48c756569
Node: Template and modes<16>756882
Ref: refman/directives/info_1 template-and-modes757012
Ref: 48d757012
Node: Examples<24>757099
Ref: refman/directives/info_1 examples757205
Ref: 48e757205
Node: object/1-5757538
Ref: refman/directives/object_1_5 doc757658
Ref: 48f757658
Ref: refman/directives/object_1_5 directives-object-1-5757658
Ref: 9a757658
Ref: refman/directives/object_1_5 object-1-5757658
Ref: 490757658
Node: Description<24>757821
Ref: refman/directives/object_1_5 description757934
Ref: 491757934
Node: Template and modes<17>759775
Ref: refman/directives/object_1_5 template-and-modes759909
Ref: 492759909
Node: Examples<25>762460
Ref: refman/directives/object_1_5 examples762570
Ref: 493762570
Node: protocol/1-2763113
Ref: refman/directives/protocol_1_2 doc763237
Ref: 494763237
Ref: refman/directives/protocol_1_2 directives-protocol-1-2763237
Ref: dc763237
Ref: refman/directives/protocol_1_2 protocol-1-2763237
Ref: 495763237
Node: Description<25>763404
Ref: refman/directives/protocol_1_2 description763519
Ref: 496763519
Node: Template and modes<18>763671
Ref: refman/directives/protocol_1_2 template-and-modes763807
Ref: 497763807
Node: Examples<26>763977
Ref: refman/directives/protocol_1_2 examples764089
Ref: 498764089
Node: threaded/0764329
Ref: refman/directives/threaded_0 doc764449
Ref: 499764449
Ref: refman/directives/threaded_0 directives-threaded-0764449
Ref: 228764449
Ref: refman/directives/threaded_0 threaded-0764449
Ref: 49a764449
Node: Description<26>764612
Ref: refman/directives/threaded_0 description764725
Ref: 49b764725
Node: Template and modes<19>765804
Ref: refman/directives/threaded_0 template-and-modes765938
Ref: 49c765938
Node: Examples<27>766010
Ref: refman/directives/threaded_0 examples766120
Ref: 49d766120
Node: uses/1766264
Ref: refman/directives/uses_1 doc766384
Ref: 49e766384
Ref: refman/directives/uses_1 directives-uses-1766384
Ref: 4a766384
Ref: refman/directives/uses_1 uses-1766384
Ref: 49f766384
Node: Description<27>766539
Ref: refman/directives/uses_1 description766648
Ref: 4a0766648
Node: Template and modes<20>767756
Ref: refman/directives/uses_1 template-and-modes767886
Ref: 4a1767886
Node: Examples<28>767974
Ref: refman/directives/uses_1 examples768080
Ref: 4a2768080
Node: use_module/1768847
Ref: refman/directives/use_module_1 doc768948
Ref: 4a3768948
Ref: refman/directives/use_module_1 directives-use-module-1768948
Ref: 4c768948
Ref: refman/directives/use_module_1 use-module-1768948
Ref: 4a4768948
Node: Description<28>769115
Ref: refman/directives/use_module_1 description769230
Ref: 4a5769230
Node: Template and modes<21>770394
Ref: refman/directives/use_module_1 template-and-modes770530
Ref: 4a6770530
Node: Examples<29>770624
Ref: refman/directives/use_module_1 examples770736
Ref: 4a7770736
Node: Predicate directives<2>771232
Ref: refman/directives/predicate_directives doc771351
Ref: 4a8771351
Ref: refman/directives/predicate_directives id1771351
Ref: 4a9771351
Ref: refman/directives/predicate_directives predicate-directives771351
Ref: 4aa771351
Node: alias/2771690
Ref: refman/directives/alias_2 doc771799
Ref: 4ab771799
Ref: refman/directives/alias_2 alias-2771799
Ref: 4ac771799
Ref: refman/directives/alias_2 directives-alias-2771799
Ref: 165771799
Node: Description<29>771954
Ref: refman/directives/alias_2 description772064
Ref: 4ad772064
Node: Template and modes<22>773175
Ref: refman/directives/alias_2 template-and-modes773306
Ref: 4ae773306
Node: Examples<30>773495
Ref: refman/directives/alias_2 examples773602
Ref: 4af773602
Node: coinductive/1773979
Ref: refman/directives/coinductive_1 doc774112
Ref: 4b0774112
Ref: refman/directives/coinductive_1 coinductive-1774112
Ref: 4b1774112
Ref: refman/directives/coinductive_1 directives-coinductive-1774112
Ref: 171774112
Node: Description<30>774279
Ref: refman/directives/coinductive_1 description774395
Ref: 4b2774395
Node: Template and modes<23>776024
Ref: refman/directives/coinductive_1 template-and-modes776161
Ref: 4b4776161
Node: Examples<31>776363
Ref: refman/directives/coinductive_1 examples776476
Ref: 4b5776476
Node: discontiguous/1776736
Ref: refman/directives/discontiguous_1 doc776871
Ref: 4b6776871
Ref: refman/directives/discontiguous_1 directives-discontiguous-1776871
Ref: 157776871
Ref: refman/directives/discontiguous_1 discontiguous-1776871
Ref: 4b7776871
Node: Description<31>777042
Ref: refman/directives/discontiguous_1 description777160
Ref: 4b8777160
Node: Template and modes<24>778383
Ref: refman/directives/discontiguous_1 template-and-modes778522
Ref: 4ba778522
Node: Examples<32>778675
Ref: refman/directives/discontiguous_1 examples778790
Ref: 4bb778790
Node: dynamic/1778966
Ref: refman/directives/dynamic_1 doc779094
Ref: 4bc779094
Ref: refman/directives/dynamic_1 directives-dynamic-1779094
Ref: 15a779094
Ref: refman/directives/dynamic_1 dynamic-1779094
Ref: 4bd779094
Node: Description<32>779255
Ref: refman/directives/dynamic_1 description779367
Ref: 4be779367
Node: Template and modes<25>781118
Ref: refman/directives/dynamic_1 template-and-modes781251
Ref: 4c0781251
Node: Examples<33>781412
Ref: refman/directives/dynamic_1 examples781521
Ref: 4c1781521
Node: info/2781753
Ref: refman/directives/info_2 doc781882
Ref: 4c2781882
Ref: refman/directives/info_2 directives-info-2781882
Ref: 168781882
Ref: refman/directives/info_2 info-2781882
Ref: 4c3781882
Node: Description<33>782037
Ref: refman/directives/info_2 description782146
Ref: 4c4782146
Node: Template and modes<26>782616
Ref: refman/directives/info_2 template-and-modes782746
Ref: 4c5782746
Node: Examples<34>782915
Ref: refman/directives/info_2 examples783021
Ref: 4c6783021
Node: meta_predicate/1783405
Ref: refman/directives/meta_predicate_1 doc783544
Ref: 4c7783544
Ref: refman/directives/meta_predicate_1 directives-meta-predicate-1783544
Ref: 152783544
Ref: refman/directives/meta_predicate_1 meta-predicate-1783544
Ref: 4c8783544
Node: Description<34>783719
Ref: refman/directives/meta_predicate_1 description783838
Ref: 4c9783838
Node: Template and modes<27>785998
Ref: refman/directives/meta_predicate_1 template-and-modes786138
Ref: 4ca786138
Node: Examples<35>786463
Ref: refman/directives/meta_predicate_1 examples786579
Ref: 4cb786579
Node: meta_non_terminal/1787089
Ref: refman/directives/meta_non_terminal_1 doc787228
Ref: 4cc787228
Ref: refman/directives/meta_non_terminal_1 directives-meta-non-terminal-1787228
Ref: 153787228
Ref: refman/directives/meta_non_terminal_1 meta-non-terminal-1787228
Ref: 4cd787228
Node: Description<35>787409
Ref: refman/directives/meta_non_terminal_1 description787531
Ref: 4ce787531
Node: Template and modes<28>788843
Ref: refman/directives/meta_non_terminal_1 template-and-modes788986
Ref: 4cf788986
Node: Examples<36>789335
Ref: refman/directives/meta_non_terminal_1 examples789454
Ref: 4d0789454
Node: mode/2789662
Ref: refman/directives/mode_2 doc789804
Ref: 4d1789804
Ref: refman/directives/mode_2 directives-mode-2789804
Ref: 149789804
Ref: refman/directives/mode_2 mode-2789804
Ref: 4d2789804
Node: Description<36>789959
Ref: refman/directives/mode_2 description790068
Ref: 4d3790068
Node: Template and modes<29>790453
Ref: refman/directives/mode_2 template-and-modes790583
Ref: 4d4790583
Node: Examples<37>790746
Ref: refman/directives/mode_2 examples790852
Ref: 4d5790852
Node: mode_non_terminal/2791220
Ref: refman/directives/mode_non_terminal_2 doc791354
Ref: 4d6791354
Ref: refman/directives/mode_non_terminal_2 directives-mode-non-terminal-2791354
Ref: 14a791354
Ref: refman/directives/mode_non_terminal_2 mode-non-terminal-2791354
Ref: 4d7791354
Node: Description<37>791535
Ref: refman/directives/mode_non_terminal_2 description791657
Ref: 4d8791657
Node: Template and modes<30>792058
Ref: refman/directives/mode_non_terminal_2 template-and-modes792201
Ref: 4d9792201
Node: Examples<38>792390
Ref: refman/directives/mode_non_terminal_2 examples792509
Ref: 4da792509
Node: multifile/1792712
Ref: refman/directives/multifile_1 doc792849
Ref: 4db792849
Ref: refman/directives/multifile_1 directives-multifile-1792849
Ref: 16c792849
Ref: refman/directives/multifile_1 multifile-1792849
Ref: 4dc792849
Node: Description<38>793014
Ref: refman/directives/multifile_1 description793128
Ref: 4dd793128
Node: Template and modes<31>794732
Ref: refman/directives/multifile_1 template-and-modes794867
Ref: 4de794867
Node: Examples<39>795032
Ref: refman/directives/multifile_1 examples795143
Ref: 4df795143
Node: private/1795375
Ref: refman/directives/private_1 doc795504
Ref: 4e0795504
Ref: refman/directives/private_1 directives-private-1795504
Ref: 145795504
Ref: refman/directives/private_1 private-1795504
Ref: 4e1795504
Node: Description<39>795665
Ref: refman/directives/private_1 description795777
Ref: 4e2795777
Node: Template and modes<32>796527
Ref: refman/directives/private_1 template-and-modes796660
Ref: 4e3796660
Node: Examples<40>796837
Ref: refman/directives/private_1 examples796946
Ref: 4e4796946
Node: protected/1797202
Ref: refman/directives/protected_1 doc797328
Ref: 4e5797328
Ref: refman/directives/protected_1 directives-protected-1797328
Ref: 144797328
Ref: refman/directives/protected_1 protected-1797328
Ref: 4e6797328
Node: Description<40>797493
Ref: refman/directives/protected_1 description797607
Ref: 4e7797607
Node: Template and modes<33>798628
Ref: refman/directives/protected_1 template-and-modes798763
Ref: 4e8798763
Node: Examples<41>798946
Ref: refman/directives/protected_1 examples799057
Ref: 4e9799057
Node: public/1799311
Ref: refman/directives/public_1 doc799442
Ref: 4ea799442
Ref: refman/directives/public_1 directives-public-1799442
Ref: 143799442
Ref: refman/directives/public_1 public-1799442
Ref: 4eb799442
Node: Description<41>799601
Ref: refman/directives/public_1 description799712
Ref: 4ec799712
Node: Template and modes<34>800666
Ref: refman/directives/public_1 template-and-modes800798
Ref: 4ed800798
Node: Examples<42>800972
Ref: refman/directives/public_1 examples801080
Ref: 4ee801080
Node: synchronized/1801339
Ref: refman/directives/synchronized_1 doc801465
Ref: 4ef801465
Ref: refman/directives/synchronized_1 directives-synchronized-1801465
Ref: 74801465
Ref: refman/directives/synchronized_1 synchronized-1801465
Ref: 4f0801465
Node: Description<42>801636
Ref: refman/directives/synchronized_1 description801753
Ref: 4f1801753
Node: Template and modes<35>803141
Ref: refman/directives/synchronized_1 template-and-modes803279
Ref: 4f2803279
Node: Examples<43>803430
Ref: refman/directives/synchronized_1 examples803544
Ref: 4f3803544
Node: uses/2803801
Ref: refman/directives/uses_2 doc803931
Ref: 4f4803931
Ref: refman/directives/uses_2 directives-uses-2803931
Ref: 4b803931
Ref: refman/directives/uses_2 uses-2803931
Ref: 4f5803931
Node: Description<43>804086
Ref: refman/directives/uses_2 description804195
Ref: 4f6804195
Node: Template and modes<36>806642
Ref: refman/directives/uses_2 template-and-modes806772
Ref: 4f7806772
Node: Examples<44>807187
Ref: refman/directives/uses_2 examples807293
Ref: 4f8807293
Node: use_module/2809087
Ref: refman/directives/use_module_2 doc809194
Ref: 4f9809194
Ref: refman/directives/use_module_2 directives-use-module-2809194
Ref: 4d809194
Ref: refman/directives/use_module_2 use-module-2809194
Ref: 4fa809194
Node: Description<44>809361
Ref: refman/directives/use_module_2 description809476
Ref: 4fb809476
Node: Template and modes<37>812832
Ref: refman/directives/use_module_2 template-and-modes812968
Ref: 4fc812968
Node: Examples<45>813433
Ref: refman/directives/use_module_2 examples813545
Ref: 4fd813545
Node: Built-in predicates814912
Ref: refman/predicates/index doc815054
Ref: 4fe815054
Ref: refman/predicates/index built-in-predicates815054
Ref: 4ff815054
Node: Enumerating objects categories and protocols815752
Ref: refman/predicates/enumerating_entity_predicates doc815936
Ref: 500815936
Ref: refman/predicates/enumerating_entity_predicates enumerating-entity-predicates815936
Ref: 284815936
Ref: refman/predicates/enumerating_entity_predicates enumerating-objects-categories-and-protocols815936
Ref: 501815936
Node: current_category/1816140
Ref: refman/predicates/current_category_1 doc816284
Ref: 502816284
Ref: refman/predicates/current_category_1 current-category-1816284
Ref: 503816284
Ref: refman/predicates/current_category_1 predicates-current-category-1816284
Ref: f1816284
Node: Description<45>816497
Ref: refman/predicates/current_category_1 description816625
Ref: 504816625
Node: Modes and number of proofs<8>816827
Ref: refman/predicates/current_category_1 modes-and-number-of-proofs816973
Ref: 505816973
Node: Errors<9>817104
Ref: refman/predicates/current_category_1 errors817247
Ref: 506817247
Node: Examples<46>817412
Ref: refman/predicates/current_category_1 examples817517
Ref: 507817517
Node: current_object/1817905
Ref: refman/predicates/current_object_1 doc818076
Ref: 508818076
Ref: refman/predicates/current_object_1 current-object-1818076
Ref: 509818076
Ref: refman/predicates/current_object_1 predicates-current-object-1818076
Ref: a6818076
Node: Description<46>818286
Ref: refman/predicates/current_object_1 description818412
Ref: 50a818412
Node: Modes and number of proofs<9>818603
Ref: refman/predicates/current_object_1 modes-and-number-of-proofs818748
Ref: 50b818748
Node: Errors<10>818875
Ref: refman/predicates/current_object_1 errors819017
Ref: 50c819017
Node: Examples<47>819174
Ref: refman/predicates/current_object_1 examples819278
Ref: 50d819278
Node: current_protocol/1819698
Ref: refman/predicates/current_protocol_1 doc819842
Ref: 50e819842
Ref: refman/predicates/current_protocol_1 current-protocol-1819842
Ref: 50f819842
Ref: refman/predicates/current_protocol_1 predicates-current-protocol-1819842
Ref: e0819842
Node: Description<47>820059
Ref: refman/predicates/current_protocol_1 description820188
Ref: 510820188
Node: Modes and number of proofs<10>820390
Ref: refman/predicates/current_protocol_1 modes-and-number-of-proofs820538
Ref: 511820538
Node: Errors<11>820671
Ref: refman/predicates/current_protocol_1 errors820816
Ref: 512820816
Node: Examples<48>820983
Ref: refman/predicates/current_protocol_1 examples821089
Ref: 513821089
Node: Enumerating objects categories and protocols properties821514
Ref: refman/predicates/enumerating_entity_property_predicates doc821752
Ref: 514821752
Ref: refman/predicates/enumerating_entity_property_predicates enumerating-entity-property-predicates821752
Ref: 6f821752
Ref: refman/predicates/enumerating_entity_property_predicates enumerating-objects-categories-and-protocols-properties821752
Ref: 515821752
Node: category_property/2821981
Ref: refman/predicates/category_property_2 doc822138
Ref: 516822138
Ref: refman/predicates/category_property_2 category-property-2822138
Ref: 517822138
Ref: refman/predicates/category_property_2 predicates-category-property-2822138
Ref: 12c822138
Node: Description<48>822355
Ref: refman/predicates/category_property_2 description822485
Ref: 518822485
Node: Modes and number of proofs<11>822828
Ref: refman/predicates/category_property_2 modes-and-number-of-proofs822977
Ref: 519822977
Node: Errors<12>823129
Ref: refman/predicates/category_property_2 errors823275
Ref: 51a823275
Node: Examples<49>823693
Ref: refman/predicates/category_property_2 examples823800
Ref: 51b823800
Node: object_property/2824283
Ref: refman/predicates/object_property_2 doc824468
Ref: 51c824468
Ref: refman/predicates/object_property_2 object-property-2824468
Ref: 51d824468
Ref: refman/predicates/object_property_2 predicates-object-property-2824468
Ref: c6824468
Node: Description<49>824681
Ref: refman/predicates/object_property_2 description824809
Ref: 51e824809
Node: Modes and number of proofs<12>825142
Ref: refman/predicates/object_property_2 modes-and-number-of-proofs825289
Ref: 51f825289
Node: Errors<13>825435
Ref: refman/predicates/object_property_2 errors825579
Ref: 520825579
Node: Examples<50>825974
Ref: refman/predicates/object_property_2 examples826079
Ref: 521826079
Node: protocol_property/2826642
Ref: refman/predicates/protocol_property_2 doc826799
Ref: 522826799
Ref: refman/predicates/protocol_property_2 predicates-protocol-property-2826799
Ref: f4826799
Ref: refman/predicates/protocol_property_2 protocol-property-2826799
Ref: 523826799
Node: Description<50>827018
Ref: refman/predicates/protocol_property_2 description827148
Ref: 524827148
Node: Modes and number of proofs<13>827501
Ref: refman/predicates/protocol_property_2 modes-and-number-of-proofs827650
Ref: 525827650
Node: Errors<14>827804
Ref: refman/predicates/protocol_property_2 errors827950
Ref: 526827950
Node: Examples<51>828359
Ref: refman/predicates/protocol_property_2 examples828466
Ref: 527828466
Node: Creating new objects categories and protocols828928
Ref: refman/predicates/creating_entity_predicates doc829165
Ref: 528829165
Ref: refman/predicates/creating_entity_predicates creating-entity-predicates829165
Ref: 529829165
Ref: refman/predicates/creating_entity_predicates creating-new-objects-categories-and-protocols829165
Ref: 52a829165
Node: create_category/4829368
Ref: refman/predicates/create_category_4 doc829511
Ref: 52b829511
Ref: refman/predicates/create_category_4 create-category-4829511
Ref: 52c829511
Ref: refman/predicates/create_category_4 predicates-create-category-4829511
Ref: 11a829511
Node: Description<51>829724
Ref: refman/predicates/create_category_4 description829852
Ref: 52d829852
Node: Modes and number of proofs<14>830747
Ref: refman/predicates/create_category_4 modes-and-number-of-proofs830894
Ref: 52e830894
Node: Errors<15>831083
Ref: refman/predicates/create_category_4 errors831227
Ref: 52f831227
Node: Examples<52>832461
Ref: refman/predicates/create_category_4 examples832566
Ref: 530832566
Node: create_object/4833027
Ref: refman/predicates/create_object_4 doc833196
Ref: 531833196
Ref: refman/predicates/create_object_4 create-object-4833196
Ref: 532833196
Ref: refman/predicates/create_object_4 predicates-create-object-4833196
Ref: 62833196
Node: Description<52>833405
Ref: refman/predicates/create_object_4 description833531
Ref: 533833531
Node: Modes and number of proofs<15>834672
Ref: refman/predicates/create_object_4 modes-and-number-of-proofs834817
Ref: 535834817
Node: Errors<16>834998
Ref: refman/predicates/create_object_4 errors835140
Ref: 536835140
Node: Examples<53>836513
Ref: refman/predicates/create_object_4 examples836616
Ref: 537836616
Node: create_protocol/3838160
Ref: refman/predicates/create_protocol_3 doc838303
Ref: 538838303
Ref: refman/predicates/create_protocol_3 create-protocol-3838303
Ref: 539838303
Ref: refman/predicates/create_protocol_3 predicates-create-protocol-3838303
Ref: e3838303
Node: Description<53>838518
Ref: refman/predicates/create_protocol_3 description838646
Ref: 53a838646
Node: Modes and number of proofs<16>839381
Ref: refman/predicates/create_protocol_3 modes-and-number-of-proofs839528
Ref: 53b839528
Node: Errors<17>839704
Ref: refman/predicates/create_protocol_3 errors839848
Ref: 53c839848
Node: Examples<54>840667
Ref: refman/predicates/create_protocol_3 examples840772
Ref: 53d840772
Node: Abolishing objects categories and protocols841179
Ref: refman/predicates/abolishing_entity_predicates doc841403
Ref: 53e841403
Ref: refman/predicates/abolishing_entity_predicates abolishing-entity-predicates841403
Ref: 53f841403
Ref: refman/predicates/abolishing_entity_predicates abolishing-objects-categories-and-protocols841403
Ref: 540841403
Node: abolish_category/1841605
Ref: refman/predicates/abolish_category_1 doc841748
Ref: 541841748
Ref: refman/predicates/abolish_category_1 abolish-category-1841748
Ref: 542841748
Ref: refman/predicates/abolish_category_1 predicates-abolish-category-1841748
Ref: f5841748
Node: Description<54>841963
Ref: refman/predicates/abolish_category_1 description842092
Ref: 543842092
Node: Modes and number of proofs<17>842271
Ref: refman/predicates/abolish_category_1 modes-and-number-of-proofs842419
Ref: 544842419
Node: Errors<18>842541
Ref: refman/predicates/abolish_category_1 errors842686
Ref: 545842686
Node: Examples<55>843137
Ref: refman/predicates/abolish_category_1 examples843243
Ref: 546843243
Node: abolish_object/1843550
Ref: refman/predicates/abolish_object_1 doc843720
Ref: 547843720
Ref: refman/predicates/abolish_object_1 abolish-object-1843720
Ref: 548843720
Ref: refman/predicates/abolish_object_1 predicates-abolish-object-1843720
Ref: 64843720
Node: Description<55>843931
Ref: refman/predicates/abolish_object_1 description844058
Ref: 549844058
Node: Modes and number of proofs<18>844227
Ref: refman/predicates/abolish_object_1 modes-and-number-of-proofs844373
Ref: 54a844373
Node: Errors<19>844491
Ref: refman/predicates/abolish_object_1 errors844634
Ref: 54b844634
Node: Examples<56>845061
Ref: refman/predicates/abolish_object_1 examples845165
Ref: 54c845165
Node: abolish_protocol/1845490
Ref: refman/predicates/abolish_protocol_1 doc845633
Ref: 54d845633
Ref: refman/predicates/abolish_protocol_1 abolish-protocol-1845633
Ref: 54e845633
Ref: refman/predicates/abolish_protocol_1 predicates-abolish-protocol-1845633
Ref: e6845633
Node: Description<56>845850
Ref: refman/predicates/abolish_protocol_1 description845979
Ref: 54f845979
Node: Modes and number of proofs<19>846160
Ref: refman/predicates/abolish_protocol_1 modes-and-number-of-proofs846308
Ref: 550846308
Node: Errors<20>846432
Ref: refman/predicates/abolish_protocol_1 errors846577
Ref: 551846577
Node: Examples<57>847030
Ref: refman/predicates/abolish_protocol_1 examples847136
Ref: 552847136
Node: Objects categories and protocols relations847422
Ref: refman/predicates/entity_relation_predicates doc847618
Ref: 553847618
Ref: refman/predicates/entity_relation_predicates entity-relation-predicates847618
Ref: 285847618
Ref: refman/predicates/entity_relation_predicates objects-categories-and-protocols-relations847618
Ref: 554847618
Node: extends_object/2-3847986
Ref: refman/predicates/extends_object_2_3 doc848132
Ref: 555848132
Ref: refman/predicates/extends_object_2_3 extends-object-2-3848132
Ref: 556848132
Ref: refman/predicates/extends_object_2_3 predicates-extends-object-2-3848132
Ref: bf848132
Node: Description<57>848347
Ref: refman/predicates/extends_object_2_3 description848476
Ref: 557848476
Node: Modes and number of proofs<20>848796
Ref: refman/predicates/extends_object_2_3 modes-and-number-of-proofs848944
Ref: 558848944
Node: Errors<21>849174
Ref: refman/predicates/extends_object_2_3 errors849319
Ref: 559849319
Node: Examples<58>849799
Ref: refman/predicates/extends_object_2_3 examples849905
Ref: 55a849905
Node: extends_protocol/2-3850306
Ref: refman/predicates/extends_protocol_2_3 doc850481
Ref: 55b850481
Ref: refman/predicates/extends_protocol_2_3 extends-protocol-2-3850481
Ref: 55c850481
Ref: refman/predicates/extends_protocol_2_3 predicates-extends-protocol-2-3850481
Ref: f0850481
Node: Description<58>850700
Ref: refman/predicates/extends_protocol_2_3 description850831
Ref: 55d850831
Node: Modes and number of proofs<21>851171
Ref: refman/predicates/extends_protocol_2_3 modes-and-number-of-proofs851321
Ref: 55e851321
Node: Errors<22>851563
Ref: refman/predicates/extends_protocol_2_3 errors851710
Ref: 55f851710
Node: Examples<59>852212
Ref: refman/predicates/extends_protocol_2_3 examples852320
Ref: 560852320
Node: extends_category/2-3852733
Ref: refman/predicates/extends_category_2_3 doc852913
Ref: 561852913
Ref: refman/predicates/extends_category_2_3 extends-category-2-3852913
Ref: 562852913
Ref: refman/predicates/extends_category_2_3 predicates-extends-category-2-3852913
Ref: 129852913
Node: Description<59>853134
Ref: refman/predicates/extends_category_2_3 description853265
Ref: 563853265
Node: Modes and number of proofs<22>853608
Ref: refman/predicates/extends_category_2_3 modes-and-number-of-proofs853758
Ref: 564853758
Node: Errors<23>854002
Ref: refman/predicates/extends_category_2_3 errors854149
Ref: 565854149
Node: Examples<60>854653
Ref: refman/predicates/extends_category_2_3 examples854761
Ref: 566854761
Node: implements_protocol/2-3855181
Ref: refman/predicates/implements_protocol_2_3 doc855365
Ref: 567855365
Ref: refman/predicates/implements_protocol_2_3 implements-protocol-2-3855365
Ref: 568855365
Ref: refman/predicates/implements_protocol_2_3 predicates-implements-protocol-2-3855365
Ref: c1855365
Node: Description<60>855592
Ref: refman/predicates/implements_protocol_2_3 description855726
Ref: 569855726
Node: Modes and number of proofs<23>856312
Ref: refman/predicates/implements_protocol_2_3 modes-and-number-of-proofs856465
Ref: 56a856465
Node: Errors<24>856888
Ref: refman/predicates/implements_protocol_2_3 errors857038
Ref: 56b857038
Node: Examples<61>857655
Ref: refman/predicates/implements_protocol_2_3 examples857766
Ref: 56c857766
Node: conforms_to_protocol/2-3858503
Ref: refman/predicates/conforms_to_protocol_2_3 doc858687
Ref: 56d858687
Ref: refman/predicates/conforms_to_protocol_2_3 conforms-to-protocol-2-3858687
Ref: 56e858687
Ref: refman/predicates/conforms_to_protocol_2_3 predicates-conforms-to-protocol-2-3858687
Ref: c2858687
Node: Description<61>858916
Ref: refman/predicates/conforms_to_protocol_2_3 description859051
Ref: 56f859051
Node: Modes and number of proofs<24>859588
Ref: refman/predicates/conforms_to_protocol_2_3 modes-and-number-of-proofs859742
Ref: 570859742
Node: Errors<25>860169
Ref: refman/predicates/conforms_to_protocol_2_3 errors860320
Ref: 571860320
Node: Examples<62>860937
Ref: refman/predicates/conforms_to_protocol_2_3 examples861049
Ref: 572861049
Node: complements_object/2861819
Ref: refman/predicates/complements_object_2 doc862000
Ref: 573862000
Ref: refman/predicates/complements_object_2 complements-object-2862000
Ref: 574862000
Ref: refman/predicates/complements_object_2 predicates-complements-object-2862000
Ref: c3862000
Node: Description<62>862221
Ref: refman/predicates/complements_object_2 description862352
Ref: 575862352
Node: Modes and number of proofs<25>862554
Ref: refman/predicates/complements_object_2 modes-and-number-of-proofs862704
Ref: 576862704
Node: Errors<26>862859
Ref: refman/predicates/complements_object_2 errors863006
Ref: 577863006
Node: Examples<63>863299
Ref: refman/predicates/complements_object_2 examples863407
Ref: 578863407
Node: imports_category/2-3863670
Ref: refman/predicates/imports_category_2_3 doc863849
Ref: 579863849
Ref: refman/predicates/imports_category_2_3 imports-category-2-3863849
Ref: 57a863849
Ref: refman/predicates/imports_category_2_3 predicates-imports-category-2-3863849
Ref: c0863849
Node: Description<63>864070
Ref: refman/predicates/imports_category_2_3 description864201
Ref: 57b864201
Node: Modes and number of proofs<26>864515
Ref: refman/predicates/imports_category_2_3 modes-and-number-of-proofs864665
Ref: 57c864665
Node: Errors<27>864905
Ref: refman/predicates/imports_category_2_3 errors865052
Ref: 57d865052
Node: Examples<64>865536
Ref: refman/predicates/imports_category_2_3 examples865644
Ref: 57e865644
Node: instantiates_class/2-3866037
Ref: refman/predicates/instantiates_class_2_3 doc866217
Ref: 57f866217
Ref: refman/predicates/instantiates_class_2_3 instantiates-class-2-3866217
Ref: 580866217
Ref: refman/predicates/instantiates_class_2_3 predicates-instantiates-class-2-3866217
Ref: bd866217
Node: Description<64>866442
Ref: refman/predicates/instantiates_class_2_3 description866575
Ref: 581866575
Node: Modes and number of proofs<27>866906
Ref: refman/predicates/instantiates_class_2_3 modes-and-number-of-proofs867058
Ref: 582867058
Node: Errors<28>867298
Ref: refman/predicates/instantiates_class_2_3 errors867447
Ref: 583867447
Node: Examples<65>867925
Ref: refman/predicates/instantiates_class_2_3 examples868035
Ref: 584868035
Node: specializes_class/2-3868476
Ref: refman/predicates/specializes_class_2_3 doc868627
Ref: 585868627
Ref: refman/predicates/specializes_class_2_3 predicates-specializes-class-2-3868627
Ref: be868627
Ref: refman/predicates/specializes_class_2_3 specializes-class-2-3868627
Ref: 586868627
Node: Description<65>868850
Ref: refman/predicates/specializes_class_2_3 description868982
Ref: 587868982
Node: Modes and number of proofs<28>869314
Ref: refman/predicates/specializes_class_2_3 modes-and-number-of-proofs869465
Ref: 588869465
Node: Errors<29>869703
Ref: refman/predicates/specializes_class_2_3 errors869851
Ref: 589869851
Node: Examples<66>870333
Ref: refman/predicates/specializes_class_2_3 examples870442
Ref: 58a870442
Node: Event handling<2>870846
Ref: refman/predicates/event_handling_predicates doc871014
Ref: 58b871014
Ref: refman/predicates/event_handling_predicates event-handling871014
Ref: 58c871014
Ref: refman/predicates/event_handling_predicates event-handling-predicates871014
Ref: 71871014
Node: abolish_events/5871150
Ref: refman/predicates/abolish_events_5 doc871264
Ref: 58d871264
Ref: refman/predicates/abolish_events_5 abolish-events-5871264
Ref: 58e871264
Ref: refman/predicates/abolish_events_5 predicates-abolish-events-5871264
Ref: 21b871264
Node: Description<66>871475
Ref: refman/predicates/abolish_events_5 description871602
Ref: 58f871602
Node: Modes and number of proofs<29>871920
Ref: refman/predicates/abolish_events_5 modes-and-number-of-proofs872066
Ref: 590872066
Node: Errors<30>872199
Ref: refman/predicates/abolish_events_5 errors872342
Ref: 591872342
Node: Examples<67>872969
Ref: refman/predicates/abolish_events_5 examples873073
Ref: 592873073
Node: current_event/5873413
Ref: refman/predicates/current_event_5 doc873551
Ref: 593873551
Ref: refman/predicates/current_event_5 current-event-5873551
Ref: 594873551
Ref: refman/predicates/current_event_5 predicates-current-event-5873551
Ref: 21e873551
Node: Description<67>873760
Ref: refman/predicates/current_event_5 description873886
Ref: 595873886
Node: Modes and number of proofs<30>874122
Ref: refman/predicates/current_event_5 modes-and-number-of-proofs874267
Ref: 596874267
Node: Errors<31>874422
Ref: refman/predicates/current_event_5 errors874564
Ref: 597874564
Node: Examples<68>875191
Ref: refman/predicates/current_event_5 examples875294
Ref: 598875294
Node: define_events/5875603
Ref: refman/predicates/define_events_5 doc875716
Ref: 599875716
Ref: refman/predicates/define_events_5 define-events-5875716
Ref: 59a875716
Ref: refman/predicates/define_events_5 predicates-define-events-5875716
Ref: 218875716
Node: Description<68>875927
Ref: refman/predicates/define_events_5 description876053
Ref: 59b876053
Node: Modes and number of proofs<31>876470
Ref: refman/predicates/define_events_5 modes-and-number-of-proofs876615
Ref: 59c876615
Node: Errors<32>876762
Ref: refman/predicates/define_events_5 errors876904
Ref: 59d876904
Node: Examples<69>877849
Ref: refman/predicates/define_events_5 examples877952
Ref: 59e877952
Node: Multi-threading878264
Ref: refman/predicates/multi_threading_predicates doc878413
Ref: 59f878413
Ref: refman/predicates/multi_threading_predicates multi-threading878413
Ref: 5a0878413
Ref: refman/predicates/multi_threading_predicates multi-threading-predicates878413
Ref: 5a1878413
Node: threaded/1878679
Ref: refman/predicates/threaded_1 doc878787
Ref: 5a2878787
Ref: refman/predicates/threaded_1 predicates-threaded-1878787
Ref: 22b878787
Ref: refman/predicates/threaded_1 threaded-1878787
Ref: 5a3878787
Node: Description<69>879014
Ref: refman/predicates/threaded_1 description879128
Ref: 5a4879128
Node: Meta-predicate template880894
Ref: refman/predicates/threaded_1 meta-predicate-template881047
Ref: 5a5881047
Node: Modes and number of proofs<32>881130
Ref: refman/predicates/threaded_1 modes-and-number-of-proofs881278
Ref: 5a6881278
Node: Errors<33>881389
Ref: refman/predicates/threaded_1 errors881526
Ref: 5a7881526
Node: Examples<70>881932
Ref: refman/predicates/threaded_1 examples882030
Ref: 5a8882030
Node: threaded_call/1-2882430
Ref: refman/predicates/threaded_call_1_2 doc882564
Ref: 5a9882564
Ref: refman/predicates/threaded_call_1_2 predicates-threaded-call-1-2882564
Ref: 230882564
Ref: refman/predicates/threaded_call_1_2 threaded-call-1-2882564
Ref: 5aa882564
Node: Description<70>882832
Ref: refman/predicates/threaded_call_1_2 description882956
Ref: 5ab882956
Node: Meta-predicate template<2>883915
Ref: refman/predicates/threaded_call_1_2 meta-predicate-template884078
Ref: 5ac884078
Node: Modes and number of proofs<33>884191
Ref: refman/predicates/threaded_call_1_2 modes-and-number-of-proofs884349
Ref: 5ad884349
Node: Errors<34>884505
Ref: refman/predicates/threaded_call_1_2 errors884649
Ref: 5ae884649
Node: Examples<71>884929
Ref: refman/predicates/threaded_call_1_2 examples885034
Ref: 5af885034
Node: threaded_once/1-2885615
Ref: refman/predicates/threaded_once_1_2 doc885756
Ref: 5b0885756
Ref: refman/predicates/threaded_once_1_2 predicates-threaded-once-1-2885756
Ref: 232885756
Ref: refman/predicates/threaded_once_1_2 threaded-once-1-2885756
Ref: 5b1885756
Node: Description<71>886026
Ref: refman/predicates/threaded_once_1_2 description886150
Ref: 5b2886150
Node: Meta-predicate template<3>887039
Ref: refman/predicates/threaded_once_1_2 meta-predicate-template887202
Ref: 5b3887202
Node: Modes and number of proofs<34>887317
Ref: refman/predicates/threaded_once_1_2 modes-and-number-of-proofs887475
Ref: 5b4887475
Node: Errors<35>887631
Ref: refman/predicates/threaded_once_1_2 errors887775
Ref: 5b5887775
Node: Examples<72>888037
Ref: refman/predicates/threaded_once_1_2 examples888142
Ref: 5b6888142
Node: threaded_ignore/1888723
Ref: refman/predicates/threaded_ignore_1 doc888864
Ref: 5b7888864
Ref: refman/predicates/threaded_ignore_1 predicates-threaded-ignore-1888864
Ref: 237888864
Ref: refman/predicates/threaded_ignore_1 threaded-ignore-1888864
Ref: 5b8888864
Node: Description<72>889134
Ref: refman/predicates/threaded_ignore_1 description889258
Ref: 5b9889258
Node: Meta-predicate template<4>889925
Ref: refman/predicates/threaded_ignore_1 meta-predicate-template890088
Ref: 5ba890088
Node: Modes and number of proofs<35>890180
Ref: refman/predicates/threaded_ignore_1 modes-and-number-of-proofs890338
Ref: 5bb890338
Node: Errors<36>890450
Ref: refman/predicates/threaded_ignore_1 errors890594
Ref: 5bc890594
Node: Examples<73>890797
Ref: refman/predicates/threaded_ignore_1 examples890902
Ref: 5bd890902
Node: threaded_exit/1-2891459
Ref: refman/predicates/threaded_exit_1_2 doc891600
Ref: 5be891600
Ref: refman/predicates/threaded_exit_1_2 predicates-threaded-exit-1-2891600
Ref: 231891600
Ref: refman/predicates/threaded_exit_1_2 threaded-exit-1-2891600
Ref: 5bf891600
Node: Description<73>891815
Ref: refman/predicates/threaded_exit_1_2 description891943
Ref: 5c0891943
Node: Modes and number of proofs<36>893277
Ref: refman/predicates/threaded_exit_1_2 modes-and-number-of-proofs893424
Ref: 5c1893424
Node: Errors<37>893597
Ref: refman/predicates/threaded_exit_1_2 errors893741
Ref: 5c2893741
Node: Examples<74>894144
Ref: refman/predicates/threaded_exit_1_2 examples894249
Ref: 5c3894249
Node: threaded_peek/1-2894780
Ref: refman/predicates/threaded_peek_1_2 doc894921
Ref: 5c4894921
Ref: refman/predicates/threaded_peek_1_2 predicates-threaded-peek-1-2894921
Ref: 233894921
Ref: refman/predicates/threaded_peek_1_2 threaded-peek-1-2894921
Ref: 5c5894921
Node: Description<74>895136
Ref: refman/predicates/threaded_peek_1_2 description895264
Ref: 5c6895264
Node: Modes and number of proofs<37>896511
Ref: refman/predicates/threaded_peek_1_2 modes-and-number-of-proofs896658
Ref: 5c7896658
Node: Errors<38>896829
Ref: refman/predicates/threaded_peek_1_2 errors896973
Ref: 5c8896973
Node: Examples<75>897376
Ref: refman/predicates/threaded_peek_1_2 examples897481
Ref: 5c9897481
Node: threaded_cancel/1898015
Ref: refman/predicates/threaded_cancel_1 doc898154
Ref: 5ca898154
Ref: refman/predicates/threaded_cancel_1 predicates-threaded-cancel-1898154
Ref: 234898154
Ref: refman/predicates/threaded_cancel_1 threaded-cancel-1898154
Ref: 5cb898154
Node: Description<75>898369
Ref: refman/predicates/threaded_cancel_1 description898497
Ref: 5cc898497
Node: Modes and number of proofs<38>899208
Ref: refman/predicates/threaded_cancel_1 modes-and-number-of-proofs899355
Ref: 5cd899355
Node: Errors<39>899465
Ref: refman/predicates/threaded_cancel_1 errors899609
Ref: 5ce899609
Node: Examples<76>899709
Ref: refman/predicates/threaded_cancel_1 examples899814
Ref: 5cf899814
Node: threaded_wait/1900044
Ref: refman/predicates/threaded_wait_1 doc900183
Ref: 5d0900183
Ref: refman/predicates/threaded_wait_1 predicates-threaded-wait-1900183
Ref: 23b900183
Ref: refman/predicates/threaded_wait_1 threaded-wait-1900183
Ref: 5d1900183
Node: Description<76>900394
Ref: refman/predicates/threaded_wait_1 description900520
Ref: 5d2900520
Node: Modes and number of proofs<39>901316
Ref: refman/predicates/threaded_wait_1 modes-and-number-of-proofs901461
Ref: 5d3901461
Node: Errors<40>901605
Ref: refman/predicates/threaded_wait_1 errors901747
Ref: 5d4901747
Node: Examples<77>901788
Ref: refman/predicates/threaded_wait_1 examples901891
Ref: 5d5901891
Node: threaded_notify/1902111
Ref: refman/predicates/threaded_notify_1 doc902224
Ref: 5d6902224
Ref: refman/predicates/threaded_notify_1 predicates-threaded-notify-1902224
Ref: 23c902224
Ref: refman/predicates/threaded_notify_1 threaded-notify-1902224
Ref: 5d7902224
Node: Description<77>902439
Ref: refman/predicates/threaded_notify_1 description902567
Ref: 5d8902567
Node: Modes and number of proofs<40>903363
Ref: refman/predicates/threaded_notify_1 modes-and-number-of-proofs903510
Ref: 5d9903510
Node: Errors<41>903658
Ref: refman/predicates/threaded_notify_1 errors903802
Ref: 5da903802
Node: Examples<78>903843
Ref: refman/predicates/threaded_notify_1 examples903948
Ref: 5db903948
Node: Multi-threading engines904126
Ref: refman/predicates/engine_predicates doc904292
Ref: 5dc904292
Ref: refman/predicates/engine_predicates engine-predicates904292
Ref: 5dd904292
Ref: refman/predicates/engine_predicates multi-threading-engines904292
Ref: 5de904292
Node: threaded_engine_create/3904638
Ref: refman/predicates/threaded_engine_create_3 doc904776
Ref: 5df904776
Ref: refman/predicates/threaded_engine_create_3 predicates-threaded-engine-create-3904776
Ref: 23f904776
Ref: refman/predicates/threaded_engine_create_3 threaded-engine-create-3904776
Ref: 5e0904776
Node: Description<78>905058
Ref: refman/predicates/threaded_engine_create_3 description905189
Ref: 5e1905189
Node: Meta-predicate template<5>905892
Ref: refman/predicates/threaded_engine_create_3 meta-predicate-template906062
Ref: 5e2906062
Node: Modes and number of proofs<41>906165
Ref: refman/predicates/threaded_engine_create_3 modes-and-number-of-proofs906330
Ref: 5e3906330
Node: Errors<42>906525
Ref: refman/predicates/threaded_engine_create_3 errors906676
Ref: 5e4906676
Node: Examples<79>906987
Ref: refman/predicates/threaded_engine_create_3 examples907099
Ref: 5e5907099
Node: threaded_engine_destroy/1907480
Ref: refman/predicates/threaded_engine_destroy_1 doc907644
Ref: 5e8907644
Ref: refman/predicates/threaded_engine_destroy_1 predicates-threaded-engine-destroy-1907644
Ref: 242907644
Ref: refman/predicates/threaded_engine_destroy_1 threaded-engine-destroy-1907644
Ref: 5e9907644
Node: Description<79>907873
Ref: refman/predicates/threaded_engine_destroy_1 description908009
Ref: 5ea908009
Node: Modes and number of proofs<42>908358
Ref: refman/predicates/threaded_engine_destroy_1 modes-and-number-of-proofs908513
Ref: 5eb908513
Node: Errors<43>908629
Ref: refman/predicates/threaded_engine_destroy_1 errors908781
Ref: 5ec908781
Node: Examples<80>909008
Ref: refman/predicates/threaded_engine_destroy_1 examples909121
Ref: 5ed909121
Node: threaded_engine/1909523
Ref: refman/predicates/threaded_engine_1 doc909685
Ref: 5ee909685
Ref: refman/predicates/threaded_engine_1 predicates-threaded-engine-1909685
Ref: 5e7909685
Ref: refman/predicates/threaded_engine_1 threaded-engine-1909685
Ref: 5ef909685
Node: Description<80>909900
Ref: refman/predicates/threaded_engine_1 description910028
Ref: 5f0910028
Node: Modes and number of proofs<43>910477
Ref: refman/predicates/threaded_engine_1 modes-and-number-of-proofs910624
Ref: 5f1910624
Node: Errors<44>910743
Ref: refman/predicates/threaded_engine_1 errors910887
Ref: 5f2910887
Node: Examples<81>910928
Ref: refman/predicates/threaded_engine_1 examples911033
Ref: 5f3911033
Node: threaded_engine_self/1911460
Ref: refman/predicates/threaded_engine_self_1 doc911619
Ref: 5f4911619
Ref: refman/predicates/threaded_engine_self_1 predicates-threaded-engine-self-1911619
Ref: 5e6911619
Ref: refman/predicates/threaded_engine_self_1 threaded-engine-self-1911619
Ref: 5f5911619
Node: Description<81>911844
Ref: refman/predicates/threaded_engine_self_1 description911977
Ref: 5f6911977
Node: Modes and number of proofs<44>912445
Ref: refman/predicates/threaded_engine_self_1 modes-and-number-of-proofs912597
Ref: 5f7912597
Node: Errors<45>912720
Ref: refman/predicates/threaded_engine_self_1 errors912869
Ref: 5f8912869
Node: Examples<82>912910
Ref: refman/predicates/threaded_engine_self_1 examples913020
Ref: 5f9913020
Node: threaded_engine_next/2913410
Ref: refman/predicates/threaded_engine_next_2 doc913582
Ref: 5fa913582
Ref: refman/predicates/threaded_engine_next_2 predicates-threaded-engine-next-2913582
Ref: 240913582
Ref: refman/predicates/threaded_engine_next_2 threaded-engine-next-2913582
Ref: 5fb913582
Node: Description<82>913807
Ref: refman/predicates/threaded_engine_next_2 description913940
Ref: 5fc913940
Node: Modes and number of proofs<45>914606
Ref: refman/predicates/threaded_engine_next_2 modes-and-number-of-proofs914758
Ref: 5fd914758
Node: Errors<46>914888
Ref: refman/predicates/threaded_engine_next_2 errors915037
Ref: 5fe915037
Node: Examples<83>915264
Ref: refman/predicates/threaded_engine_next_2 examples915374
Ref: 5ff915374
Node: threaded_engine_next_reified/2915673
Ref: refman/predicates/threaded_engine_next_reified_2 doc915846
Ref: 600915846
Ref: refman/predicates/threaded_engine_next_reified_2 predicates-threaded-engine-next-reified-2915846
Ref: 241915846
Ref: refman/predicates/threaded_engine_next_reified_2 threaded-engine-next-reified-2915846
Ref: 601915846
Node: Description<83>916087
Ref: refman/predicates/threaded_engine_next_reified_2 description916228
Ref: 602916228
Node: Modes and number of proofs<46>916821
Ref: refman/predicates/threaded_engine_next_reified_2 modes-and-number-of-proofs916981
Ref: 603916981
Node: Errors<47>917113
Ref: refman/predicates/threaded_engine_next_reified_2 errors917270
Ref: 604917270
Node: Examples<84>917497
Ref: refman/predicates/threaded_engine_next_reified_2 examples917615
Ref: 605917615
Node: threaded_engine_yield/1917922
Ref: refman/predicates/threaded_engine_yield_1 doc918095
Ref: 606918095
Ref: refman/predicates/threaded_engine_yield_1 predicates-threaded-engine-yield-1918095
Ref: 245918095
Ref: refman/predicates/threaded_engine_yield_1 threaded-engine-yield-1918095
Ref: 607918095
Node: Description<84>918322
Ref: refman/predicates/threaded_engine_yield_1 description918456
Ref: 608918456
Node: Modes and number of proofs<47>919375
Ref: refman/predicates/threaded_engine_yield_1 modes-and-number-of-proofs919528
Ref: 609919528
Node: Errors<48>919650
Ref: refman/predicates/threaded_engine_yield_1 errors919800
Ref: 60a919800
Node: Examples<85>919841
Ref: refman/predicates/threaded_engine_yield_1 examples919952
Ref: 60b919952
Node: threaded_engine_post/2920244
Ref: refman/predicates/threaded_engine_post_2 doc920410
Ref: 60c920410
Ref: refman/predicates/threaded_engine_post_2 predicates-threaded-engine-post-2920410
Ref: 244920410
Ref: refman/predicates/threaded_engine_post_2 threaded-engine-post-2920410
Ref: 60d920410
Node: Description<85>920635
Ref: refman/predicates/threaded_engine_post_2 description920768
Ref: 60e920768
Node: Modes and number of proofs<48>921131
Ref: refman/predicates/threaded_engine_post_2 modes-and-number-of-proofs921283
Ref: 60f921283
Node: Errors<49>921405
Ref: refman/predicates/threaded_engine_post_2 errors921554
Ref: 610921554
Node: Examples<86>921781
Ref: refman/predicates/threaded_engine_post_2 examples921891
Ref: 611921891
Node: threaded_engine_fetch/1922115
Ref: refman/predicates/threaded_engine_fetch_1 doc922249
Ref: 612922249
Ref: refman/predicates/threaded_engine_fetch_1 predicates-threaded-engine-fetch-1922249
Ref: 243922249
Ref: refman/predicates/threaded_engine_fetch_1 threaded-engine-fetch-1922249
Ref: 613922249
Node: Description<86>922476
Ref: refman/predicates/threaded_engine_fetch_1 description922610
Ref: 614922610
Node: Modes and number of proofs<49>923049
Ref: refman/predicates/threaded_engine_fetch_1 modes-and-number-of-proofs923202
Ref: 615923202
Node: Errors<50>923324
Ref: refman/predicates/threaded_engine_fetch_1 errors923474
Ref: 616923474
Node: Examples<87>923515
Ref: refman/predicates/threaded_engine_fetch_1 examples923626
Ref: 617923626
Node: Compiling and loading source files923810
Ref: refman/predicates/compiling_predicates doc923966
Ref: 618923966
Ref: refman/predicates/compiling_predicates compiling-and-loading-source-files923966
Ref: 619923966
Ref: refman/predicates/compiling_predicates compiling-predicates923966
Ref: 45923966
Node: logtalk_compile/1924288
Ref: refman/predicates/logtalk_compile_1 doc924422
Ref: 61a924422
Ref: refman/predicates/logtalk_compile_1 logtalk-compile-1924422
Ref: 61b924422
Ref: refman/predicates/logtalk_compile_1 predicates-logtalk-compile-1924422
Ref: 29e924422
Node: Description<87>924635
Ref: refman/predicates/logtalk_compile_1 description924763
Ref: 61c924763
Node: Modes and number of proofs<50>926285
Ref: refman/predicates/logtalk_compile_1 modes-and-number-of-proofs926432
Ref: 61e926432
Node: Errors<51>926618
Ref: refman/predicates/logtalk_compile_1 errors926762
Ref: 61f926762
Node: Examples<88>927435
Ref: refman/predicates/logtalk_compile_1 examples927540
Ref: 620927540
Node: logtalk_compile/2928159
Ref: refman/predicates/logtalk_compile_2 doc928316
Ref: 621928316
Ref: refman/predicates/logtalk_compile_2 logtalk-compile-2928316
Ref: 622928316
Ref: refman/predicates/logtalk_compile_2 predicates-logtalk-compile-2928316
Ref: 2b2928316
Node: Description<88>928529
Ref: refman/predicates/logtalk_compile_2 description928657
Ref: 623928657
Node: Modes and number of proofs<51>930657
Ref: refman/predicates/logtalk_compile_2 modes-and-number-of-proofs930804
Ref: 624930804
Node: Errors<52>931034
Ref: refman/predicates/logtalk_compile_2 errors931178
Ref: 625931178
Node: Examples<89>932496
Ref: refman/predicates/logtalk_compile_2 examples932601
Ref: 626932601
Node: logtalk_load/1933367
Ref: refman/predicates/logtalk_load_1 doc933521
Ref: 627933521
Ref: refman/predicates/logtalk_load_1 logtalk-load-1933521
Ref: 628933521
Ref: refman/predicates/logtalk_load_1 predicates-logtalk-load-1933521
Ref: 46933521
Node: Description<89>933730
Ref: refman/predicates/logtalk_load_1 description933855
Ref: 629933855
Node: Modes and number of proofs<52>935485
Ref: refman/predicates/logtalk_load_1 modes-and-number-of-proofs935629
Ref: 62a935629
Node: Errors<53>935811
Ref: refman/predicates/logtalk_load_1 errors935952
Ref: 62b935952
Node: Examples<90>936628
Ref: refman/predicates/logtalk_load_1 examples936730
Ref: 62c936730
Node: logtalk_load/2937352
Ref: refman/predicates/logtalk_load_2 doc937503
Ref: 62d937503
Ref: refman/predicates/logtalk_load_2 logtalk-load-2937503
Ref: 62e937503
Ref: refman/predicates/logtalk_load_2 predicates-logtalk-load-2937503
Ref: 4e937503
Node: Description<90>937712
Ref: refman/predicates/logtalk_load_2 description937837
Ref: 62f937837
Node: Modes and number of proofs<53>939842
Ref: refman/predicates/logtalk_load_2 modes-and-number-of-proofs939986
Ref: 630939986
Node: Errors<54>940212
Ref: refman/predicates/logtalk_load_2 errors940353
Ref: 631940353
Node: Examples<91>941662
Ref: refman/predicates/logtalk_load_2 examples941764
Ref: 632941764
Node: logtalk_make/0942509
Ref: refman/predicates/logtalk_make_0 doc942660
Ref: 633942660
Ref: refman/predicates/logtalk_make_0 logtalk-make-0942660
Ref: 634942660
Ref: refman/predicates/logtalk_make_0 predicates-logtalk-make-0942660
Ref: 29f942660
Node: Description<91>942869
Ref: refman/predicates/logtalk_make_0 description942994
Ref: 635942994
Node: Modes and number of proofs<54>944375
Ref: refman/predicates/logtalk_make_0 modes-and-number-of-proofs944519
Ref: 637944519
Node: Errors<55>944617
Ref: refman/predicates/logtalk_make_0 errors944758
Ref: 638944758
Node: Examples<92>944799
Ref: refman/predicates/logtalk_make_0 examples944901
Ref: 639944901
Node: logtalk_make/1945237
Ref: refman/predicates/logtalk_make_1 doc945402
Ref: 63a945402
Ref: refman/predicates/logtalk_make_1 logtalk-make-1945402
Ref: 63b945402
Ref: refman/predicates/logtalk_make_1 predicates-logtalk-make-1945402
Ref: 2a0945402
Node: Description<92>945611
Ref: refman/predicates/logtalk_make_1 description945736
Ref: 63c945736
Ref: Description<92>-Footnote-1950214
Node: Modes and number of proofs<55>950267
Ref: refman/predicates/logtalk_make_1 modes-and-number-of-proofs950411
Ref: 63e950411
Node: Errors<56>950524
Ref: refman/predicates/logtalk_make_1 errors950665
Ref: 63f950665
Node: Examples<93>950706
Ref: refman/predicates/logtalk_make_1 examples950808
Ref: 640950808
Node: logtalk_make_target_action/1951367
Ref: refman/predicates/logtalk_make_target_action_1 doc951540
Ref: 641951540
Ref: refman/predicates/logtalk_make_target_action_1 logtalk-make-target-action-1951540
Ref: 642951540
Ref: refman/predicates/logtalk_make_target_action_1 predicates-logtalk-make-target-action-1951540
Ref: 636951540
Node: Description<93>951777
Ref: refman/predicates/logtalk_make_target_action_1 description951916
Ref: 643951916
Node: Modes and number of proofs<56>952289
Ref: refman/predicates/logtalk_make_target_action_1 modes-and-number-of-proofs952447
Ref: 644952447
Node: Errors<57>952575
Ref: refman/predicates/logtalk_make_target_action_1 errors952730
Ref: 645952730
Node: Examples<94>952771
Ref: refman/predicates/logtalk_make_target_action_1 examples952887
Ref: 646952887
Node: logtalk_library_path/2953258
Ref: refman/predicates/logtalk_library_path_2 doc953439
Ref: 647953439
Ref: refman/predicates/logtalk_library_path_2 logtalk-library-path-2953439
Ref: 648953439
Ref: refman/predicates/logtalk_library_path_2 predicates-logtalk-library-path-2953439
Ref: 2a7953439
Node: Description<94>953664
Ref: refman/predicates/logtalk_library_path_2 description953797
Ref: 649953797
Ref: Description<94>-Footnote-1956655
Node: Modes and number of proofs<57>956724
Ref: refman/predicates/logtalk_library_path_2 modes-and-number-of-proofs956876
Ref: 64b956876
Node: Errors<58>957064
Ref: refman/predicates/logtalk_library_path_2 errors957213
Ref: 64c957213
Node: Examples<95>957254
Ref: refman/predicates/logtalk_library_path_2 examples957364
Ref: 64d957364
Node: logtalk_load_context/2958499
Ref: refman/predicates/logtalk_load_context_2 doc958643
Ref: 64e958643
Ref: refman/predicates/logtalk_load_context_2 logtalk-load-context-2958643
Ref: 64f958643
Ref: refman/predicates/logtalk_load_context_2 predicates-logtalk-load-context-2958643
Ref: 318958643
Node: Description<95>958868
Ref: refman/predicates/logtalk_load_context_2 description959001
Ref: 650959001
Node: Modes and number of proofs<58>962642
Ref: refman/predicates/logtalk_load_context_2 modes-and-number-of-proofs962794
Ref: 651962794
Node: Errors<59>962929
Ref: refman/predicates/logtalk_load_context_2 errors963078
Ref: 652963078
Node: Examples<96>963327
Ref: refman/predicates/logtalk_load_context_2 examples963437
Ref: 653963437
Node: Flags964151
Ref: refman/predicates/flag_predicates doc964290
Ref: 654964290
Ref: refman/predicates/flag_predicates flag-predicates964290
Ref: 655964290
Ref: refman/predicates/flag_predicates flags964290
Ref: 656964290
Node: current_logtalk_flag/2964447
Ref: refman/predicates/current_logtalk_flag_2 doc964561
Ref: 657964561
Ref: refman/predicates/current_logtalk_flag_2 current-logtalk-flag-2964561
Ref: 658964561
Ref: refman/predicates/current_logtalk_flag_2 predicates-current-logtalk-flag-2964561
Ref: 2b3964561
Node: Description<96>964786
Ref: refman/predicates/current_logtalk_flag_2 description964919
Ref: 659964919
Node: Modes and number of proofs<59>965188
Ref: refman/predicates/current_logtalk_flag_2 modes-and-number-of-proofs965340
Ref: 65a965340
Node: Errors<60>965469
Ref: refman/predicates/current_logtalk_flag_2 errors965618
Ref: 65b965618
Node: Examples<97>965832
Ref: refman/predicates/current_logtalk_flag_2 examples965942
Ref: 65c965942
Node: set_logtalk_flag/2<2>966192
Ref: refman/predicates/set_logtalk_flag_2 doc966336
Ref: 65d966336
Ref: refman/predicates/set_logtalk_flag_2 predicates-set-logtalk-flag-2966336
Ref: 51966336
Ref: refman/predicates/set_logtalk_flag_2 set-logtalk-flag-2966336
Ref: 65e966336
Node: Description<97>966553
Ref: refman/predicates/set_logtalk_flag_2 description966685
Ref: 65f966685
Node: Modes and number of proofs<60>967167
Ref: refman/predicates/set_logtalk_flag_2 modes-and-number-of-proofs967318
Ref: 660967318
Node: Errors<61>967436
Ref: refman/predicates/set_logtalk_flag_2 errors967584
Ref: 661967584
Node: Examples<98>968136
Ref: refman/predicates/set_logtalk_flag_2 examples968245
Ref: 662968245
Node: create_logtalk_flag/3968537
Ref: refman/predicates/create_logtalk_flag_3 doc968650
Ref: 663968650
Ref: refman/predicates/create_logtalk_flag_3 create-logtalk-flag-3968650
Ref: 664968650
Ref: refman/predicates/create_logtalk_flag_3 predicates-create-logtalk-flag-3968650
Ref: 2e7968650
Node: Description<98>968875
Ref: refman/predicates/create_logtalk_flag_3 description969007
Ref: 665969007
Node: Modes and number of proofs<61>970207
Ref: refman/predicates/create_logtalk_flag_3 modes-and-number-of-proofs970358
Ref: 666970358
Node: Errors<62>970496
Ref: refman/predicates/create_logtalk_flag_3 errors970644
Ref: 667970644
Node: Examples<99>971543
Ref: refman/predicates/create_logtalk_flag_3 examples971652
Ref: 668971652
Node: Linter971905
Ref: refman/predicates/linter_predicates doc972001
Ref: 669972001
Ref: refman/predicates/linter_predicates linter972001
Ref: 66a972001
Ref: refman/predicates/linter_predicates linter-predicates972001
Ref: 66b972001
Node: logtalk_linter_hook/7972088
Ref: refman/predicates/logtalk_linter_hook_7 doc972172
Ref: 66c972172
Ref: refman/predicates/logtalk_linter_hook_7 logtalk-linter-hook-7972172
Ref: 66d972172
Ref: refman/predicates/logtalk_linter_hook_7 predicates-logtalk-linter-hook-7972172
Ref: 66e972172
Node: Description<99>972396
Ref: refman/predicates/logtalk_linter_hook_7 description972528
Ref: 66f972528
Node: Modes and number of proofs<62>973139
Ref: refman/predicates/logtalk_linter_hook_7 modes-and-number-of-proofs973290
Ref: 670973290
Node: Errors<63>973483
Ref: refman/predicates/logtalk_linter_hook_7 errors973632
Ref: 671973632
Node: Examples<100>973673
Ref: refman/predicates/logtalk_linter_hook_7 examples973783
Ref: 672973783
Node: Built-in methods<2>974213
Ref: refman/methods/index doc974333
Ref: 673974333
Ref: refman/methods/index built-in-methods974333
Ref: 674974333
Node: Logic and control974787
Ref: refman/methods/logic_and_control_methods doc974906
Ref: 675974906
Ref: refman/methods/logic_and_control_methods logic-and-control974906
Ref: 676974906
Ref: refman/methods/logic_and_control_methods logic-and-control-methods974906
Ref: 677974906
Node: !/0975039
Ref: refman/methods/cut_0 doc975131
Ref: 678975131
Ref: refman/methods/cut_0 id1975131
Ref: 679975131
Ref: refman/methods/cut_0 methods-cut-0975131
Ref: 196975131
Node: Description<100>975318
Ref: refman/methods/cut_0 description975433
Ref: 67a975433
Node: Modes and number of proofs<63>975691
Ref: refman/methods/cut_0 modes-and-number-of-proofs975825
Ref: 67b975825
Node: Errors<64>975910
Ref: refman/methods/cut_0 errors976041
Ref: 67c976041
Node: Examples<101>976080
Ref: refman/methods/cut_0 examples976172
Ref: 67d976172
Node: true/0976333
Ref: refman/methods/true_0 doc976440
Ref: 67e976440
Ref: refman/methods/true_0 methods-true-0976440
Ref: 197976440
Ref: refman/methods/true_0 true-0976440
Ref: 67f976440
Node: Description<101>976633
Ref: refman/methods/true_0 description976751
Ref: 680976751
Node: Modes and number of proofs<64>976963
Ref: refman/methods/true_0 modes-and-number-of-proofs977100
Ref: 681977100
Node: Errors<65>977188
Ref: refman/methods/true_0 errors977322
Ref: 682977322
Node: Examples<102>977361
Ref: refman/methods/true_0 examples977456
Ref: 683977456
Node: fail/0977616
Ref: refman/methods/fail_0 doc977727
Ref: 684977727
Ref: refman/methods/fail_0 fail-0977727
Ref: 685977727
Ref: refman/methods/fail_0 methods-fail-0977727
Ref: 198977727
Node: Description<102>977922
Ref: refman/methods/fail_0 description978040
Ref: 686978040
Node: Modes and number of proofs<65>978251
Ref: refman/methods/fail_0 modes-and-number-of-proofs978388
Ref: 687978388
Node: Errors<66>978478
Ref: refman/methods/fail_0 errors978612
Ref: 688978612
Node: Examples<103>978653
Ref: refman/methods/fail_0 examples978748
Ref: 689978748
Node: false/0978908
Ref: refman/methods/false_0 doc979021
Ref: 68a979021
Ref: refman/methods/false_0 false-0979021
Ref: 68b979021
Ref: refman/methods/false_0 methods-false-0979021
Ref: 199979021
Node: Description<103>979218
Ref: refman/methods/false_0 description979337
Ref: 68c979337
Node: Modes and number of proofs<66>979549
Ref: refman/methods/false_0 modes-and-number-of-proofs979687
Ref: 68d979687
Node: Errors<67>979778
Ref: refman/methods/false_0 errors979913
Ref: 68e979913
Node: Examples<104>979954
Ref: refman/methods/false_0 examples980050
Ref: 68f980050
Node: repeat/0980209
Ref: refman/methods/repeat_0 doc980307
Ref: 690980307
Ref: refman/methods/repeat_0 methods-repeat-0980307
Ref: 19a980307
Ref: refman/methods/repeat_0 repeat-0980307
Ref: 691980307
Node: Description<104>980506
Ref: refman/methods/repeat_0 description980626
Ref: 692980626
Node: Modes and number of proofs<67>980931
Ref: refman/methods/repeat_0 modes-and-number-of-proofs981070
Ref: 693981070
Node: Errors<68>981170
Ref: refman/methods/repeat_0 errors981306
Ref: 694981306
Node: Examples<105>981347
Ref: refman/methods/repeat_0 examples981444
Ref: 695981444
Node: Execution context981583
Ref: refman/methods/context_methods doc981724
Ref: 696981724
Ref: refman/methods/context_methods context-methods981724
Ref: 360981724
Ref: refman/methods/context_methods execution-context981724
Ref: 697981724
Node: context/1981867
Ref: refman/methods/context_1 doc981970
Ref: 698981970
Ref: refman/methods/context_1 context-1981970
Ref: 699981970
Ref: refman/methods/context_1 methods-context-1981970
Ref: 19e981970
Node: Description<105>982169
Ref: refman/methods/context_1 description982290
Ref: 69a982290
Ref: Description<105>-Footnote-1983244
Node: Modes and number of proofs<68>983311
Ref: refman/methods/context_1 modes-and-number-of-proofs983451
Ref: 69b983451
Node: Errors<69>983554
Ref: refman/methods/context_1 errors983691
Ref: 69c983691
Node: Examples<106>983730
Ref: refman/methods/context_1 examples983828
Ref: 69d983828
Node: parameter/2984198
Ref: refman/methods/parameter_2 doc984316
Ref: 69e984316
Ref: refman/methods/parameter_2 methods-parameter-2984316
Ref: a2984316
Ref: refman/methods/parameter_2 parameter-2984316
Ref: 69f984316
Node: Description<106>984519
Ref: refman/methods/parameter_2 description984642
Ref: 6a0984642
Node: Modes and number of proofs<69>985686
Ref: refman/methods/parameter_2 modes-and-number-of-proofs985828
Ref: 6a2985828
Node: Errors<70>985946
Ref: refman/methods/parameter_2 errors986085
Ref: 6a3986085
Node: Examples<107>986535
Ref: refman/methods/parameter_2 examples986635
Ref: 6a4986635
Node: self/1987358
Ref: refman/methods/self_1 doc987475
Ref: 6a5987475
Ref: refman/methods/self_1 methods-self-1987475
Ref: 67987475
Ref: refman/methods/self_1 self-1987475
Ref: 6a6987475
Node: Description<107>987670
Ref: refman/methods/self_1 description987788
Ref: 6a7987788
Node: Modes and number of proofs<70>988207
Ref: refman/methods/self_1 modes-and-number-of-proofs988344
Ref: 6a8988344
Node: Errors<71>988462
Ref: refman/methods/self_1 errors988596
Ref: 6a9988596
Node: Examples<108>988637
Ref: refman/methods/self_1 examples988732
Ref: 6aa988732
Node: sender/1989097
Ref: refman/methods/sender_1 doc989209
Ref: 6ab989209
Ref: refman/methods/sender_1 methods-sender-1989209
Ref: 19d989209
Ref: refman/methods/sender_1 sender-1989209
Ref: 6ac989209
Node: Description<108>989408
Ref: refman/methods/sender_1 description989528
Ref: 6ad989528
Node: Modes and number of proofs<71>989949
Ref: refman/methods/sender_1 modes-and-number-of-proofs990088
Ref: 6ae990088
Node: Errors<72>990208
Ref: refman/methods/sender_1 errors990344
Ref: 6af990344
Node: Examples<109>990385
Ref: refman/methods/sender_1 examples990482
Ref: 6b0990482
Node: this/1990866
Ref: refman/methods/this_1 doc990963
Ref: 6b1990963
Ref: refman/methods/this_1 methods-this-1990963
Ref: 68990963
Ref: refman/methods/this_1 this-1990963
Ref: 6b2990963
Node: Description<109>991158
Ref: refman/methods/this_1 description991276
Ref: 6b3991276
Node: Modes and number of proofs<72>992070
Ref: refman/methods/this_1 modes-and-number-of-proofs992207
Ref: 6b4992207
Node: Errors<73>992325
Ref: refman/methods/this_1 errors992459
Ref: 6b5992459
Node: Examples<110>992500
Ref: refman/methods/this_1 examples992595
Ref: 6b6992595
Node: Reflection<2>992948
Ref: refman/methods/reflection_methods doc993080
Ref: 6b7993080
Ref: refman/methods/reflection_methods reflection993080
Ref: 6b8993080
Ref: refman/methods/reflection_methods reflection-methods993080
Ref: 70993080
Node: current_op/3993210
Ref: refman/methods/current_op_3 doc993320
Ref: 6b9993320
Ref: refman/methods/current_op_3 current-op-3993320
Ref: 6ba993320
Ref: refman/methods/current_op_3 methods-current-op-3993320
Ref: 15e993320
Node: Description<110>993525
Ref: refman/methods/current_op_3 description993649
Ref: 6bb993649
Node: Modes and number of proofs<73>993882
Ref: refman/methods/current_op_3 modes-and-number-of-proofs994025
Ref: 6bc994025
Node: Errors<74>994176
Ref: refman/methods/current_op_3 errors994316
Ref: 6bd994316
Node: Examples<111>994905
Ref: refman/methods/current_op_3 examples995006
Ref: 6be995006
Node: current_predicate/1995637
Ref: refman/methods/current_predicate_1 doc995776
Ref: 6bf995776
Ref: refman/methods/current_predicate_1 current-predicate-1995776
Ref: 6c0995776
Ref: refman/methods/current_predicate_1 methods-current-predicate-1995776
Ref: 141995776
Node: Description<111>995995
Ref: refman/methods/current_predicate_1 description996126
Ref: 6c1996126
Node: Modes and number of proofs<74>996670
Ref: refman/methods/current_predicate_1 modes-and-number-of-proofs996820
Ref: 6c2996820
Node: Errors<75>996952
Ref: refman/methods/current_predicate_1 errors997099
Ref: 6c3997099
Node: Examples<112>997694
Ref: refman/methods/current_predicate_1 examples997802
Ref: 6c4997802
Node: predicate_property/2998884
Ref: refman/methods/predicate_property_2 doc999002
Ref: 6c5999002
Ref: refman/methods/predicate_property_2 methods-predicate-property-2999002
Ref: 142999002
Ref: refman/methods/predicate_property_2 predicate-property-2999002
Ref: 6c6999002
Node: Description<112>999225
Ref: refman/methods/predicate_property_2 description999357
Ref: 6c7999357
Node: Modes and number of proofs<75>1000162
Ref: refman/methods/predicate_property_2 modes-and-number-of-proofs1000313
Ref: 6c81000313
Node: Errors<76>1000458
Ref: refman/methods/predicate_property_2 errors1000606
Ref: 6c91000606
Node: Examples<113>1000957
Ref: refman/methods/predicate_property_2 examples1001066
Ref: 6ca1001066
Node: Database1002291
Ref: refman/methods/database_methods doc1002416
Ref: 6cb1002416
Ref: refman/methods/database_methods database1002416
Ref: 6cc1002416
Ref: refman/methods/database_methods database-methods1002416
Ref: 6cd1002416
Node: abolish/11002562
Ref: refman/methods/abolish_1 doc1002654
Ref: 6ce1002654
Ref: refman/methods/abolish_1 abolish-11002654
Ref: 6cf1002654
Ref: refman/methods/abolish_1 methods-abolish-11002654
Ref: 1b11002654
Node: Description<113>1002853
Ref: refman/methods/abolish_1 description1002974
Ref: 6d01002974
Node: Modes and number of proofs<76>1003574
Ref: refman/methods/abolish_1 modes-and-number-of-proofs1003714
Ref: 6d11003714
Node: Errors<77>1003827
Ref: refman/methods/abolish_1 errors1003964
Ref: 6d21003964
Node: Examples<114>1005151
Ref: refman/methods/abolish_1 examples1005249
Ref: 6d31005249
Node: asserta/11005864
Ref: refman/methods/asserta_1 doc1005974
Ref: 6d41005974
Ref: refman/methods/asserta_1 asserta-11005974
Ref: 6d51005974
Ref: refman/methods/asserta_1 methods-asserta-11005974
Ref: 1b21005974
Node: Description<114>1006173
Ref: refman/methods/asserta_1 description1006294
Ref: 6d61006294
Node: Modes and number of proofs<77>1007687
Ref: refman/methods/asserta_1 modes-and-number-of-proofs1007827
Ref: 6d71007827
Node: Errors<78>1007927
Ref: refman/methods/asserta_1 errors1008064
Ref: 6d81008064
Node: Examples<115>1009138
Ref: refman/methods/asserta_1 examples1009236
Ref: 6d91009236
Node: assertz/11010937
Ref: refman/methods/assertz_1 doc1011046
Ref: 6da1011046
Ref: refman/methods/assertz_1 assertz-11011046
Ref: 6db1011046
Ref: refman/methods/assertz_1 methods-assertz-11011046
Ref: 1b31011046
Node: Description<115>1011247
Ref: refman/methods/assertz_1 description1011368
Ref: 6dc1011368
Node: Modes and number of proofs<78>1012754
Ref: refman/methods/assertz_1 modes-and-number-of-proofs1012894
Ref: 6dd1012894
Node: Errors<79>1012996
Ref: refman/methods/assertz_1 errors1013133
Ref: 6de1013133
Node: Examples<116>1014206
Ref: refman/methods/assertz_1 examples1014304
Ref: 6df1014304
Node: clause/21016002
Ref: refman/methods/clause_2 doc1016111
Ref: 6e01016111
Ref: refman/methods/clause_2 clause-21016111
Ref: 6e11016111
Ref: refman/methods/clause_2 methods-clause-21016111
Ref: 1b41016111
Node: Description<116>1016310
Ref: refman/methods/clause_2 description1016430
Ref: 6e21016430
Node: Modes and number of proofs<79>1017036
Ref: refman/methods/clause_2 modes-and-number-of-proofs1017175
Ref: 6e31017175
Node: Errors<80>1017294
Ref: refman/methods/clause_2 errors1017430
Ref: 6e41017430
Node: Examples<117>1018347
Ref: refman/methods/clause_2 examples1018444
Ref: 6e51018444
Node: retract/11019128
Ref: refman/methods/retract_1 doc1019240
Ref: 6e61019240
Ref: refman/methods/retract_1 methods-retract-11019240
Ref: 1b51019240
Ref: refman/methods/retract_1 retract-11019240
Ref: 6e71019240
Node: Description<117>1019441
Ref: refman/methods/retract_1 description1019562
Ref: 6e81019562
Node: Modes and number of proofs<80>1020233
Ref: refman/methods/retract_1 modes-and-number-of-proofs1020373
Ref: 6e91020373
Node: Errors<81>1020484
Ref: refman/methods/retract_1 errors1020621
Ref: 6ea1020621
Node: Examples<118>1021470
Ref: refman/methods/retract_1 examples1021568
Ref: 6eb1021568
Node: retractall/11022210
Ref: refman/methods/retractall_1 doc1022305
Ref: 6ec1022305
Ref: refman/methods/retractall_1 methods-retractall-11022305
Ref: 1b61022305
Ref: refman/methods/retractall_1 retractall-11022305
Ref: 6ed1022305
Node: Description<118>1022512
Ref: refman/methods/retractall_1 description1022636
Ref: 6ee1022636
Node: Modes and number of proofs<81>1023242
Ref: refman/methods/retractall_1 modes-and-number-of-proofs1023385
Ref: 6ef1023385
Node: Errors<82>1023492
Ref: refman/methods/retractall_1 errors1023632
Ref: 6f01023632
Node: Examples<119>1024481
Ref: refman/methods/retractall_1 examples1024582
Ref: 6f11024582
Node: Meta-calls1025250
Ref: refman/methods/meta_call_methods doc1025379
Ref: 6f21025379
Ref: refman/methods/meta_call_methods meta-call-methods1025379
Ref: 6f31025379
Ref: refman/methods/meta_call_methods meta-calls1025379
Ref: 6f41025379
Node: call/1-N1025497
Ref: refman/methods/call_N doc1025589
Ref: 6f51025589
Ref: refman/methods/call_N call-1-n1025589
Ref: 6f61025589
Ref: refman/methods/call_N methods-call-n1025589
Ref: 1811025589
Node: Description<119>1025841
Ref: refman/methods/call_N description1025957
Ref: 6f71025957
Node: Meta-predicate template<6>1026664
Ref: refman/methods/call_N meta-predicate-template1026819
Ref: 6f81026819
Node: Modes and number of proofs<82>1026942
Ref: refman/methods/call_N modes-and-number-of-proofs1027091
Ref: 6f91027091
Node: Errors<83>1027301
Ref: refman/methods/call_N errors1027437
Ref: 6fa1027437
Node: Examples<120>1027816
Ref: refman/methods/call_N examples1027913
Ref: 6fb1027913
Node: ignore/11028569
Ref: refman/methods/ignore_1 doc1028676
Ref: 6fc1028676
Ref: refman/methods/ignore_1 ignore-11028676
Ref: 6fd1028676
Ref: refman/methods/ignore_1 methods-ignore-11028676
Ref: 1801028676
Node: Description<120>1028928
Ref: refman/methods/ignore_1 description1029044
Ref: 6fe1029044
Node: Meta-predicate template<7>1029366
Ref: refman/methods/ignore_1 meta-predicate-template1029521
Ref: 6ff1029521
Node: Modes and number of proofs<83>1029602
Ref: refman/methods/ignore_1 modes-and-number-of-proofs1029751
Ref: 7001029751
Node: Errors<84>1029854
Ref: refman/methods/ignore_1 errors1029990
Ref: 7011029990
Node: Examples<121>1030193
Ref: refman/methods/ignore_1 examples1030290
Ref: 7021030290
Node: once/11030718
Ref: refman/methods/once_1 doc1030822
Ref: 7031030822
Ref: refman/methods/once_1 methods-once-11030822
Ref: 1bb1030822
Ref: refman/methods/once_1 once-11030822
Ref: 7041030822
Node: Description<121>1031072
Ref: refman/methods/once_1 description1031186
Ref: 7051031186
Node: Meta-predicate template<8>1031487
Ref: refman/methods/once_1 meta-predicate-template1031640
Ref: 7061031640
Node: Modes and number of proofs<84>1031721
Ref: refman/methods/once_1 modes-and-number-of-proofs1031868
Ref: 7071031868
Node: Errors<85>1031977
Ref: refman/methods/once_1 errors1032111
Ref: 7081032111
Node: Examples<122>1032314
Ref: refman/methods/once_1 examples1032409
Ref: 7091032409
Node: \+ /11032878
Ref: refman/methods/not_1 doc1032965
Ref: 70a1032965
Ref: refman/methods/not_1 id11032965
Ref: 70b1032965
Ref: refman/methods/not_1 methods-not-11032965
Ref: 1bc1032965
Node: Description<122>1033215
Ref: refman/methods/not_1 description1033328
Ref: 70c1033328
Node: Meta-predicate template<9>1034464
Ref: refman/methods/not_1 meta-predicate-template1034616
Ref: 70d1034616
Node: Modes and number of proofs<85>1034694
Ref: refman/methods/not_1 modes-and-number-of-proofs1034840
Ref: 70e1034840
Node: Errors<86>1034946
Ref: refman/methods/not_1 errors1035079
Ref: 70f1035079
Node: Examples<123>1035282
Ref: refman/methods/not_1 examples1035376
Ref: 7101035376
Node: Error handling<2>1035787
Ref: refman/methods/error_handling_methods doc1035921
Ref: 7111035921
Ref: refman/methods/error_handling_methods error-handling1035921
Ref: 7121035921
Ref: refman/methods/error_handling_methods error-handling-methods1035921
Ref: 24c1035921
Node: catch/31036285
Ref: refman/methods/catch_3 doc1036382
Ref: 7131036382
Ref: refman/methods/catch_3 catch-31036382
Ref: 7141036382
Ref: refman/methods/catch_3 methods-catch-31036382
Ref: 1a11036382
Node: Description<123>1036577
Ref: refman/methods/catch_3 description1036696
Ref: 7151036696
Node: Modes and number of proofs<86>1037093
Ref: refman/methods/catch_3 modes-and-number-of-proofs1037231
Ref: 7161037231
Node: Errors<87>1037358
Ref: refman/methods/catch_3 errors1037493
Ref: 7171037493
Node: Examples<124>1037532
Ref: refman/methods/catch_3 examples1037628
Ref: 7181037628
Node: throw/11038116
Ref: refman/methods/throw_1 doc1038243
Ref: 71a1038243
Ref: refman/methods/throw_1 methods-throw-11038243
Ref: 1a21038243
Ref: refman/methods/throw_1 throw-11038243
Ref: 71b1038243
Node: Description<124>1038438
Ref: refman/methods/throw_1 description1038557
Ref: 71c1038557
Node: Modes and number of proofs<87>1038782
Ref: refman/methods/throw_1 modes-and-number-of-proofs1038920
Ref: 71d1038920
Node: Errors<88>1039020
Ref: refman/methods/throw_1 errors1039155
Ref: 71e1039155
Node: Examples<125>1039385
Ref: refman/methods/throw_1 examples1039481
Ref: 71f1039481
Node: instantiation_error/01039971
Ref: refman/methods/instantiation_error_0 doc1040114
Ref: 7201040114
Ref: refman/methods/instantiation_error_0 instantiation-error-01040114
Ref: 7211040114
Ref: refman/methods/instantiation_error_0 methods-instantiation-error-01040114
Ref: 1a31040114
Node: Description<125>1040339
Ref: refman/methods/instantiation_error_0 description1040472
Ref: 7221040472
Node: Modes and number of proofs<88>1041085
Ref: refman/methods/instantiation_error_0 modes-and-number-of-proofs1041237
Ref: 7231041237
Node: Errors<89>1041344
Ref: refman/methods/instantiation_error_0 errors1041493
Ref: 7241041493
Node: Examples<126>1041581
Ref: refman/methods/instantiation_error_0 examples1041691
Ref: 7251041691
Node: uninstantiation_error/11042215
Ref: refman/methods/uninstantiation_error_1 doc1042363
Ref: 7261042363
Ref: refman/methods/uninstantiation_error_1 methods-uninstantiation-error-11042363
Ref: 1a41042363
Ref: refman/methods/uninstantiation_error_1 uninstantiation-error-11042363
Ref: 7271042363
Node: Description<126>1042592
Ref: refman/methods/uninstantiation_error_1 description1042727
Ref: 7281042727
Node: Modes and number of proofs<89>1043337
Ref: refman/methods/uninstantiation_error_1 modes-and-number-of-proofs1043491
Ref: 7291043491
Node: Errors<90>1043609
Ref: refman/methods/uninstantiation_error_1 errors1043760
Ref: 72a1043760
Node: Examples<127>1043859
Ref: refman/methods/uninstantiation_error_1 examples1043971
Ref: 72b1043971
Node: type_error/21044506
Ref: refman/methods/type_error_2 doc1044647
Ref: 72c1044647
Ref: refman/methods/type_error_2 methods-type-error-21044647
Ref: 1a51044647
Ref: refman/methods/type_error_2 type-error-21044647
Ref: 72d1044647
Node: Description<127>1044854
Ref: refman/methods/type_error_2 description1044978
Ref: 72e1044978
Node: Modes and number of proofs<90>1045786
Ref: refman/methods/type_error_2 modes-and-number-of-proofs1045929
Ref: 72f1045929
Node: Errors<91>1046043
Ref: refman/methods/type_error_2 errors1046183
Ref: 7301046183
Node: Examples<128>1046277
Ref: refman/methods/type_error_2 examples1046378
Ref: 7311046378
Node: domain_error/21046915
Ref: refman/methods/domain_error_2 doc1047052
Ref: 7321047052
Ref: refman/methods/domain_error_2 domain-error-21047052
Ref: 7331047052
Ref: refman/methods/domain_error_2 methods-domain-error-21047052
Ref: 1a61047052
Node: Description<128>1047263
Ref: refman/methods/domain_error_2 description1047389
Ref: 7341047389
Node: Modes and number of proofs<91>1049274
Ref: refman/methods/domain_error_2 modes-and-number-of-proofs1049419
Ref: 7351049419
Node: Errors<92>1049535
Ref: refman/methods/domain_error_2 errors1049677
Ref: 7361049677
Node: Examples<129>1049775
Ref: refman/methods/domain_error_2 examples1049878
Ref: 7371049878
Node: consistency_error/31050437
Ref: refman/methods/consistency_error_3 doc1050579
Ref: 7381050579
Ref: refman/methods/consistency_error_3 consistency-error-31050579
Ref: 7391050579
Ref: refman/methods/consistency_error_3 methods-consistency-error-31050579
Ref: 7191050579
Node: Description<129>1050800
Ref: refman/methods/consistency_error_3 description1050931
Ref: 73a1050931
Node: Modes and number of proofs<92>1051824
Ref: refman/methods/consistency_error_3 modes-and-number-of-proofs1051974
Ref: 73b1051974
Node: Errors<93>1052104
Ref: refman/methods/consistency_error_3 errors1052251
Ref: 73c1052251
Node: Examples<130>1052372
Ref: refman/methods/consistency_error_3 examples1052480
Ref: 73d1052480
Node: existence_error/21053425
Ref: refman/methods/existence_error_2 doc1053571
Ref: 73e1053571
Ref: refman/methods/existence_error_2 existence-error-21053571
Ref: 73f1053571
Ref: refman/methods/existence_error_2 methods-existence-error-21053571
Ref: 1a71053571
Node: Description<130>1053788
Ref: refman/methods/existence_error_2 description1053917
Ref: 7401053917
Node: Modes and number of proofs<93>1054924
Ref: refman/methods/existence_error_2 modes-and-number-of-proofs1055072
Ref: 7411055072
Node: Errors<94>1055193
Ref: refman/methods/existence_error_2 errors1055338
Ref: 7421055338
Node: Examples<131>1055438
Ref: refman/methods/existence_error_2 examples1055544
Ref: 7431055544
Node: permission_error/31056099
Ref: refman/methods/permission_error_3 doc1056248
Ref: 7441056248
Ref: refman/methods/permission_error_3 methods-permission-error-31056248
Ref: 1a81056248
Ref: refman/methods/permission_error_3 permission-error-31056248
Ref: 7451056248
Node: Description<131>1056467
Ref: refman/methods/permission_error_3 description1056597
Ref: 7461056597
Node: Modes and number of proofs<94>1058134
Ref: refman/methods/permission_error_3 modes-and-number-of-proofs1058283
Ref: 7471058283
Node: Errors<95>1058414
Ref: refman/methods/permission_error_3 errors1058560
Ref: 7481058560
Node: Examples<132>1058681
Ref: refman/methods/permission_error_3 examples1058788
Ref: 7491058788
Node: representation_error/11059337
Ref: refman/methods/representation_error_1 doc1059487
Ref: 74a1059487
Ref: refman/methods/representation_error_1 methods-representation-error-11059487
Ref: 1a91059487
Ref: refman/methods/representation_error_1 representation-error-11059487
Ref: 74b1059487
Node: Description<132>1059714
Ref: refman/methods/representation_error_1 description1059848
Ref: 74c1059848
Node: Modes and number of proofs<95>1060736
Ref: refman/methods/representation_error_1 modes-and-number-of-proofs1060889
Ref: 74d1060889
Node: Errors<96>1061004
Ref: refman/methods/representation_error_1 errors1061154
Ref: 74e1061154
Node: Examples<133>1061249
Ref: refman/methods/representation_error_1 examples1061360
Ref: 74f1061360
Node: evaluation_error/11061898
Ref: refman/methods/evaluation_error_1 doc1062046
Ref: 7501062046
Ref: refman/methods/evaluation_error_1 evaluation-error-11062046
Ref: 7511062046
Ref: refman/methods/evaluation_error_1 methods-evaluation-error-11062046
Ref: 1aa1062046
Node: Description<133>1062265
Ref: refman/methods/evaluation_error_1 description1062395
Ref: 7521062395
Node: Modes and number of proofs<96>1063066
Ref: refman/methods/evaluation_error_1 modes-and-number-of-proofs1063215
Ref: 7531063215
Node: Errors<97>1063328
Ref: refman/methods/evaluation_error_1 errors1063474
Ref: 7541063474
Node: Examples<134>1063570
Ref: refman/methods/evaluation_error_1 examples1063677
Ref: 7551063677
Node: resource_error/11064216
Ref: refman/methods/resource_error_1 doc1064356
Ref: 7561064356
Ref: refman/methods/resource_error_1 methods-resource-error-11064356
Ref: 1ab1064356
Ref: refman/methods/resource_error_1 resource-error-11064356
Ref: 7571064356
Node: Description<134>1064571
Ref: refman/methods/resource_error_1 description1064699
Ref: 7581064699
Node: Modes and number of proofs<97>1065407
Ref: refman/methods/resource_error_1 modes-and-number-of-proofs1065554
Ref: 7591065554
Node: Errors<98>1065665
Ref: refman/methods/resource_error_1 errors1065809
Ref: 75a1065809
Node: Examples<135>1065902
Ref: refman/methods/resource_error_1 examples1066007
Ref: 75b1066007
Node: syntax_error/11066504
Ref: refman/methods/syntax_error_1 doc1066640
Ref: 75c1066640
Ref: refman/methods/syntax_error_1 methods-syntax-error-11066640
Ref: 1ac1066640
Ref: refman/methods/syntax_error_1 syntax-error-11066640
Ref: 75d1066640
Node: Description<135>1066851
Ref: refman/methods/syntax_error_1 description1066977
Ref: 75e1066977
Node: Modes and number of proofs<98>1067491
Ref: refman/methods/syntax_error_1 modes-and-number-of-proofs1067636
Ref: 75f1067636
Node: Errors<99>1067745
Ref: refman/methods/syntax_error_1 errors1067887
Ref: 7601067887
Node: Examples<136>1067981
Ref: refman/methods/syntax_error_1 examples1068084
Ref: 7611068084
Node: system_error/01068536
Ref: refman/methods/system_error_0 doc1068647
Ref: 7621068647
Ref: refman/methods/system_error_0 methods-system-error-01068647
Ref: 1ad1068647
Ref: refman/methods/system_error_0 system-error-01068647
Ref: 7631068647
Node: Description<136>1068859
Ref: refman/methods/system_error_0 description1068985
Ref: 7641068985
Node: Modes and number of proofs<99>1069510
Ref: refman/methods/system_error_0 modes-and-number-of-proofs1069656
Ref: 7651069656
Node: Errors<100>1069756
Ref: refman/methods/system_error_0 errors1069899
Ref: 7661069899
Node: Examples<137>1069980
Ref: refman/methods/system_error_0 examples1070084
Ref: 7671070084
Node: All solutions1070548
Ref: refman/methods/solution_methods doc1070689
Ref: 7681070689
Ref: refman/methods/solution_methods all-solutions1070689
Ref: 7691070689
Ref: refman/methods/solution_methods solutions-methods1070689
Ref: 76a1070689
Node: bagof/31070824
Ref: refman/methods/bagof_3 doc1070919
Ref: 76b1070919
Ref: refman/methods/bagof_3 bagof-31070919
Ref: 76c1070919
Ref: refman/methods/bagof_3 methods-bagof-31070919
Ref: 1bf1070919
Node: Description<137>1071172
Ref: refman/methods/bagof_3 description1071288
Ref: 76d1071288
Node: Meta-predicate template<10>1072186
Ref: refman/methods/bagof_3 meta-predicate-template1072342
Ref: 76e1072342
Node: Modes and number of proofs<100>1072428
Ref: refman/methods/bagof_3 modes-and-number-of-proofs1072579
Ref: 76f1072579
Node: Errors<101>1072702
Ref: refman/methods/bagof_3 errors1072839
Ref: 7701072839
Node: Examples<138>1073149
Ref: refman/methods/bagof_3 examples1073246
Ref: 7711073246
Node: findall/31073797
Ref: refman/methods/findall_3 doc1073910
Ref: 7721073910
Ref: refman/methods/findall_3 findall-31073910
Ref: 7731073910
Ref: refman/methods/findall_3 methods-findall-31073910
Ref: 1c01073910
Node: Description<138>1074167
Ref: refman/methods/findall_3 description1074285
Ref: 7741074285
Node: Meta-predicate template<11>1074668
Ref: refman/methods/findall_3 meta-predicate-template1074826
Ref: 7751074826
Node: Modes and number of proofs<101>1074914
Ref: refman/methods/findall_3 modes-and-number-of-proofs1075067
Ref: 7761075067
Node: Errors<102>1075193
Ref: refman/methods/findall_3 errors1075332
Ref: 7771075332
Node: Examples<139>1075644
Ref: refman/methods/findall_3 examples1075743
Ref: 7781075743
Node: findall/41076285
Ref: refman/methods/findall_4 doc1076399
Ref: 7791076399
Ref: refman/methods/findall_4 findall-41076399
Ref: 77a1076399
Ref: refman/methods/findall_4 methods-findall-41076399
Ref: 1c11076399
Node: Description<139>1076658
Ref: refman/methods/findall_4 description1076776
Ref: 77b1076776
Node: Meta-predicate template<12>1077142
Ref: refman/methods/findall_4 meta-predicate-template1077300
Ref: 77c1077300
Node: Modes and number of proofs<102>1077393
Ref: refman/methods/findall_4 modes-and-number-of-proofs1077546
Ref: 77d1077546
Node: Errors<103>1077679
Ref: refman/methods/findall_4 errors1077818
Ref: 77e1077818
Node: Examples<140>1078130
Ref: refman/methods/findall_4 examples1078229
Ref: 77f1078229
Node: forall/21078789
Ref: refman/methods/forall_2 doc1078901
Ref: 7801078901
Ref: refman/methods/forall_2 forall-21078901
Ref: 7811078901
Ref: refman/methods/forall_2 methods-forall-21078901
Ref: 1c31078901
Node: Description<140>1079158
Ref: refman/methods/forall_2 description1079275
Ref: 7821079275
Node: Meta-predicate template<13>1079912
Ref: refman/methods/forall_2 meta-predicate-template1080069
Ref: 7831080069
Node: Modes and number of proofs<103>1080155
Ref: refman/methods/forall_2 modes-and-number-of-proofs1080307
Ref: 7841080307
Node: Errors<104>1080429
Ref: refman/methods/forall_2 errors1080567
Ref: 7851080567
Node: Examples<141>1080908
Ref: refman/methods/forall_2 examples1081006
Ref: 7861081006
Node: setof/31081508
Ref: refman/methods/setof_3 doc1081602
Ref: 7871081602
Ref: refman/methods/setof_3 methods-setof-31081602
Ref: 1c21081602
Ref: refman/methods/setof_3 setof-31081602
Ref: 7881081602
Node: Description<141>1081857
Ref: refman/methods/setof_3 description1081973
Ref: 7891081973
Node: Meta-predicate template<14>1082847
Ref: refman/methods/setof_3 meta-predicate-template1083003
Ref: 78a1083003
Node: Modes and number of proofs<104>1083091
Ref: refman/methods/setof_3 modes-and-number-of-proofs1083242
Ref: 78b1083242
Node: Errors<105>1083367
Ref: refman/methods/setof_3 errors1083504
Ref: 78c1083504
Node: Examples<142>1083816
Ref: refman/methods/setof_3 examples1083913
Ref: 78d1083913
Node: Event handling<3>1084447
Ref: refman/methods/event_methods doc1084589
Ref: 78e1084589
Ref: refman/methods/event_methods event-handling1084589
Ref: 78f1084589
Ref: refman/methods/event_methods event-methods1084589
Ref: 7901084589
Node: before/31084686
Ref: refman/methods/before_3 doc1084784
Ref: 7911084784
Ref: refman/methods/before_3 before-31084784
Ref: 7921084784
Ref: refman/methods/before_3 methods-before-31084784
Ref: 1011084784
Node: Description<142>1084983
Ref: refman/methods/before_3 description1085104
Ref: 7931085104
Ref: Description<142>-Footnote-11085724
Node: Modes and number of proofs<105>1085777
Ref: refman/methods/before_3 modes-and-number-of-proofs1085918
Ref: 7941085918
Node: Errors<106>1086068
Ref: refman/methods/before_3 errors1086206
Ref: 7951086206
Node: Examples<143>1086245
Ref: refman/methods/before_3 examples1086343
Ref: 7961086343
Node: after/31086800
Ref: refman/methods/after_3 doc1086898
Ref: 7971086898
Ref: refman/methods/after_3 after-31086898
Ref: 7981086898
Ref: refman/methods/after_3 methods-after-31086898
Ref: 1021086898
Node: Description<143>1087095
Ref: refman/methods/after_3 description1087215
Ref: 7991087215
Ref: Description<143>-Footnote-11087833
Node: Modes and number of proofs<106>1087886
Ref: refman/methods/after_3 modes-and-number-of-proofs1088026
Ref: 79a1088026
Node: Errors<107>1088175
Ref: refman/methods/after_3 errors1088312
Ref: 79b1088312
Node: Examples<144>1088351
Ref: refman/methods/after_3 examples1088448
Ref: 79c1088448
Node: Message forwarding1088894
Ref: refman/methods/forwarding_methods doc1089055
Ref: 79d1089055
Ref: refman/methods/forwarding_methods forwarding-methods1089055
Ref: 79e1089055
Ref: refman/methods/forwarding_methods message-forwarding1089055
Ref: 79f1089055
Node: forward/11089149
Ref: refman/methods/forward_1 doc1089233
Ref: 7a01089233
Ref: refman/methods/forward_1 forward-11089233
Ref: 7a11089233
Ref: refman/methods/forward_1 methods-forward-11089233
Ref: 1051089233
Node: Description<144>1089434
Ref: refman/methods/forward_1 description1089556
Ref: 7a21089556
Ref: Description<144>-Footnote-11090085
Node: Modes and number of proofs<107>1090138
Ref: refman/methods/forward_1 modes-and-number-of-proofs1090280
Ref: 7a31090280
Node: Errors<108>1090391
Ref: refman/methods/forward_1 errors1090530
Ref: 7a41090530
Node: Examples<145>1090569
Ref: refman/methods/forward_1 examples1090668
Ref: 7a51090668
Node: Definite clause grammar rules<2>1090932
Ref: refman/methods/dcg_methods doc1091102
Ref: 7a61091102
Ref: refman/methods/dcg_methods dcg-methods1091102
Ref: 7a71091102
Ref: refman/methods/dcg_methods definite-clause-grammar-rules1091102
Ref: 7a81091102
Node: call//1-N1091271
Ref: refman/methods/call_1 doc1091384
Ref: 7a91091384
Ref: refman/methods/call_1 call-1-n1091384
Ref: 7aa1091384
Ref: refman/methods/call_1 methods-call-11091384
Ref: 1c91091384
Node: Description<145>1091618
Ref: refman/methods/call_1 description1091735
Ref: 7ab1091735
Node: Meta-non-terminal template1092903
Ref: refman/methods/call_1 meta-non-terminal-template1093060
Ref: 7ac1093060
Node: Modes and number of proofs<108>1093191
Ref: refman/methods/call_1 modes-and-number-of-proofs1093343
Ref: 7ad1093343
Node: Errors<109>1093555
Ref: refman/methods/call_1 errors1093694
Ref: 7ae1093694
Node: Examples<146>1093906
Ref: refman/methods/call_1 examples1094005
Ref: 7af1094005
Node: eos//01094845
Ref: refman/methods/eos_0 doc1094976
Ref: 7b01094976
Ref: refman/methods/eos_0 eos-01094976
Ref: 7b11094976
Ref: refman/methods/eos_0 methods-eos-01094976
Ref: 1ca1094976
Node: Description<146>1095173
Ref: refman/methods/eos_0 description1095292
Ref: 7b21095292
Node: Modes and number of proofs<109>1095481
Ref: refman/methods/eos_0 modes-and-number-of-proofs1095620
Ref: 7b31095620
Node: Errors<110>1095717
Ref: refman/methods/eos_0 errors1095853
Ref: 7b41095853
Node: Examples<147>1095896
Ref: refman/methods/eos_0 examples1095992
Ref: 7b51095992
Node: phrase//11096184
Ref: refman/methods/phrase_1 doc1096314
Ref: 7b61096314
Ref: refman/methods/phrase_1 methods-phrase-11096314
Ref: 1c81096314
Ref: refman/methods/phrase_1 phrase-11096314
Ref: 7b71096314
Node: Description<147>1096580
Ref: refman/methods/phrase_1 description1096700
Ref: 7b81096700
Node: Meta-non-terminal template<2>1097022
Ref: refman/methods/phrase_1 meta-non-terminal-template1097182
Ref: 7ba1097182
Node: Modes and number of proofs<110>1097273
Ref: refman/methods/phrase_1 modes-and-number-of-proofs1097428
Ref: 7bb1097428
Node: Errors<111>1097542
Ref: refman/methods/phrase_1 errors1097681
Ref: 7bc1097681
Node: Examples<148>1097919
Ref: refman/methods/phrase_1 examples1098018
Ref: 7bd1098018
Node: phrase/21098173
Ref: refman/methods/phrase_2 doc1098305
Ref: 7be1098305
Ref: refman/methods/phrase_2 methods-phrase-21098305
Ref: 18e1098305
Ref: refman/methods/phrase_2 phrase-21098305
Ref: 7bf1098305
Node: Description<148>1098564
Ref: refman/methods/phrase_2 description1098681
Ref: 7c01098681
Node: Meta-predicate template<15>1099645
Ref: refman/methods/phrase_2 meta-predicate-template1099802
Ref: 7c11099802
Node: Modes and number of proofs<111>1099890
Ref: refman/methods/phrase_2 modes-and-number-of-proofs1100042
Ref: 7c21100042
Node: Errors<112>1100163
Ref: refman/methods/phrase_2 errors1100301
Ref: 7c31100301
Node: Examples<149>1100539
Ref: refman/methods/phrase_2 examples1100637
Ref: 7c41100637
Node: phrase/31101150
Ref: refman/methods/phrase_3 doc1101264
Ref: 7c51101264
Ref: refman/methods/phrase_3 methods-phrase-31101264
Ref: 18f1101264
Ref: refman/methods/phrase_3 phrase-31101264
Ref: 7c61101264
Node: Description<149>1101523
Ref: refman/methods/phrase_3 description1101640
Ref: 7c71101640
Node: Meta-predicate template<16>1102657
Ref: refman/methods/phrase_3 meta-predicate-template1102814
Ref: 7c81102814
Node: Modes and number of proofs<112>1102905
Ref: refman/methods/phrase_3 modes-and-number-of-proofs1103057
Ref: 7c91103057
Node: Errors<113>1103185
Ref: refman/methods/phrase_3 errors1103323
Ref: 7ca1103323
Node: Examples<150>1103561
Ref: refman/methods/phrase_3 examples1103659
Ref: 7cb1103659
Node: Term and goal expansion<2>1104170
Ref: refman/methods/expansion_methods doc1104339
Ref: 7cc1104339
Ref: refman/methods/expansion_methods expansion-methods1104339
Ref: 7cd1104339
Ref: refman/methods/expansion_methods term-and-goal-expansion1104339
Ref: 7ce1104339
Node: expand_term/21104509
Ref: refman/methods/expand_term_2 doc1104630
Ref: 7cf1104630
Ref: refman/methods/expand_term_2 expand-term-21104630
Ref: 7d01104630
Ref: refman/methods/expand_term_2 methods-expand-term-21104630
Ref: 1b71104630
Node: Description<150>1104841
Ref: refman/methods/expand_term_2 description1104967
Ref: 7d11104967
Node: Modes and number of proofs<113>1106405
Ref: refman/methods/expand_term_2 modes-and-number-of-proofs1106551
Ref: 7d21106551
Node: Errors<114>1106662
Ref: refman/methods/expand_term_2 errors1106805
Ref: 7d31106805
Node: Examples<151>1106846
Ref: refman/methods/expand_term_2 examples1106949
Ref: 7d41106949
Node: term_expansion/21107115
Ref: refman/methods/term_expansion_2 doc1107258
Ref: 7d51107258
Ref: refman/methods/term_expansion_2 methods-term-expansion-21107258
Ref: fc1107258
Ref: refman/methods/term_expansion_2 term-expansion-21107258
Ref: 7d61107258
Node: Description<151>1107475
Ref: refman/methods/term_expansion_2 description1107604
Ref: 7d71107604
Ref: Description<151>-Footnote-11109025
Node: Modes and number of proofs<114>1109076
Ref: refman/methods/term_expansion_2 modes-and-number-of-proofs1109225
Ref: 7d81109225
Node: Errors<115>1109409
Ref: refman/methods/term_expansion_2 errors1109555
Ref: 7d91109555
Node: Examples<152>1109596
Ref: refman/methods/term_expansion_2 examples1109702
Ref: 7da1109702
Node: expand_goal/21110047
Ref: refman/methods/expand_goal_2 doc1110193
Ref: 7db1110193
Ref: refman/methods/expand_goal_2 expand-goal-21110193
Ref: 7dc1110193
Ref: refman/methods/expand_goal_2 methods-expand-goal-21110193
Ref: 3131110193
Node: Description<152>1110406
Ref: refman/methods/expand_goal_2 description1110532
Ref: 7dd1110532
Node: Modes and number of proofs<115>1111424
Ref: refman/methods/expand_goal_2 modes-and-number-of-proofs1111570
Ref: 7de1111570
Node: Errors<116>1111683
Ref: refman/methods/expand_goal_2 errors1111826
Ref: 7df1111826
Node: Examples<153>1111869
Ref: refman/methods/expand_goal_2 examples1111972
Ref: 7e01111972
Node: goal_expansion/21112140
Ref: refman/methods/goal_expansion_2 doc1112261
Ref: 7e11112261
Ref: refman/methods/goal_expansion_2 goal-expansion-21112261
Ref: 7e21112261
Ref: refman/methods/goal_expansion_2 methods-goal-expansion-21112261
Ref: fd1112261
Node: Description<153>1112480
Ref: refman/methods/goal_expansion_2 description1112609
Ref: 7e31112609
Ref: Description<153>-Footnote-11114075
Node: Modes and number of proofs<116>1114126
Ref: refman/methods/goal_expansion_2 modes-and-number-of-proofs1114275
Ref: 7e41114275
Node: Errors<117>1114407
Ref: refman/methods/goal_expansion_2 errors1114553
Ref: 7e51114553
Node: Examples<154>1114596
Ref: refman/methods/goal_expansion_2 examples1114702
Ref: 7e61114702
Node: Coinduction hooks1115006
Ref: refman/methods/coinduction_methods doc1115159
Ref: 7e71115159
Ref: refman/methods/coinduction_methods coinduction-hooks1115159
Ref: 7e81115159
Ref: refman/methods/coinduction_methods coinduction-methods1115159
Ref: 7e91115159
Node: coinductive_success_hook/1-21115272
Ref: refman/methods/coinductive_success_hook_1_2 doc1115374
Ref: 7ea1115374
Ref: refman/methods/coinductive_success_hook_1_2 coinductive-success-hook-1-21115374
Ref: 7eb1115374
Ref: refman/methods/coinductive_success_hook_1_2 methods-coinductive-success-hook-1-21115374
Ref: 4b31115374
Node: Description<154>1115615
Ref: refman/methods/coinductive_success_hook_1_2 description1115756
Ref: 7ec1115756
Node: Modes and number of proofs<117>1116637
Ref: refman/methods/coinductive_success_hook_1_2 modes-and-number-of-proofs1116798
Ref: 7ed1116798
Node: Errors<118>1116993
Ref: refman/methods/coinductive_success_hook_1_2 errors1117151
Ref: 7ee1117151
Node: Examples<155>1117192
Ref: refman/methods/coinductive_success_hook_1_2 examples1117310
Ref: 7ef1117310
Node: Message printing1117887
Ref: refman/methods/printing_methods doc1118029
Ref: 7f01118029
Ref: refman/methods/printing_methods message-printing1118029
Ref: 7f11118029
Ref: refman/methods/printing_methods printing-methods1118029
Ref: 7f21118029
Node: print_message/31118275
Ref: refman/methods/print_message_3 doc1118389
Ref: 7f31118389
Ref: refman/methods/print_message_3 methods-print-message-31118389
Ref: 2ff1118389
Ref: refman/methods/print_message_3 print-message-31118389
Ref: 7f41118389
Node: Description<155>1118604
Ref: refman/methods/print_message_3 description1118732
Ref: 7f51118732
Ref: Description<155>-Footnote-11120066
Node: Modes and number of proofs<118>1120113
Ref: refman/methods/print_message_3 modes-and-number-of-proofs1120261
Ref: 7f61120261
Node: Errors<119>1120387
Ref: refman/methods/print_message_3 errors1120532
Ref: 7f71120532
Node: Examples<156>1120573
Ref: refman/methods/print_message_3 examples1120678
Ref: 7f81120678
Node: message_tokens//21121098
Ref: refman/methods/message_tokens_2 doc1121235
Ref: 7fc1121235
Ref: refman/methods/message_tokens_2 message-tokens-21121235
Ref: 7fd1121235
Ref: refman/methods/message_tokens_2 methods-message-tokens-21121235
Ref: 3011121235
Node: Description<156>1121454
Ref: refman/methods/message_tokens_2 description1121584
Ref: 7fe1121584
Ref: Description<156>-Footnote-11122070
Node: Modes and number of proofs<119>1122117
Ref: refman/methods/message_tokens_2 modes-and-number-of-proofs1122267
Ref: 7ff1122267
Node: Errors<120>1122394
Ref: refman/methods/message_tokens_2 errors1122541
Ref: 8001122541
Node: Examples<157>1122582
Ref: refman/methods/message_tokens_2 examples1122689
Ref: 8011122689
Node: message_hook/41123235
Ref: refman/methods/message_hook_4 doc1123380
Ref: 8021123380
Ref: refman/methods/message_hook_4 message-hook-41123380
Ref: 8031123380
Ref: refman/methods/message_hook_4 methods-message-hook-41123380
Ref: 3071123380
Node: Description<157>1123595
Ref: refman/methods/message_hook_4 description1123722
Ref: 8041123722
Ref: Description<157>-Footnote-11124211
Node: Modes and number of proofs<120>1124258
Ref: refman/methods/message_hook_4 modes-and-number-of-proofs1124405
Ref: 8051124405
Node: Errors<121>1124555
Ref: refman/methods/message_hook_4 errors1124699
Ref: 8061124699
Node: Examples<158>1124742
Ref: refman/methods/message_hook_4 examples1124846
Ref: 8071124846
Node: message_prefix_stream/41125524
Ref: refman/methods/message_prefix_stream_4 doc1125673
Ref: 8081125673
Ref: refman/methods/message_prefix_stream_4 message-prefix-stream-41125673
Ref: 8091125673
Ref: refman/methods/message_prefix_stream_4 methods-message-prefix-stream-41125673
Ref: 3051125673
Node: Description<158>1125906
Ref: refman/methods/message_prefix_stream_4 description1126042
Ref: 80a1126042
Ref: Description<158>-Footnote-11126645
Ref: Description<158>-Footnote-21126692
Node: Modes and number of proofs<121>1126739
Ref: refman/methods/message_prefix_stream_4 modes-and-number-of-proofs1126895
Ref: 80b1126895
Node: Errors<122>1127056
Ref: refman/methods/message_prefix_stream_4 errors1127209
Ref: 80c1127209
Node: Examples<159>1127252
Ref: refman/methods/message_prefix_stream_4 examples1127365
Ref: 80d1127365
Node: message_prefix_file/61127904
Ref: refman/methods/message_prefix_file_6 doc1128061
Ref: 80e1128061
Ref: refman/methods/message_prefix_file_6 message-prefix-file-61128061
Ref: 80f1128061
Ref: refman/methods/message_prefix_file_6 methods-message-prefix-file-61128061
Ref: 3081128061
Node: Description<159>1128290
Ref: refman/methods/message_prefix_file_6 description1128424
Ref: 8101128424
Ref: Description<159>-Footnote-11129178
Ref: Description<159>-Footnote-21129225
Node: Modes and number of proofs<122>1129272
Ref: refman/methods/message_prefix_file_6 modes-and-number-of-proofs1129426
Ref: 8111129426
Node: Errors<123>1129598
Ref: refman/methods/message_prefix_file_6 errors1129749
Ref: 8121129749
Node: Examples<160>1129792
Ref: refman/methods/message_prefix_file_6 examples1129903
Ref: 8131129903
Node: print_message_tokens/31130448
Ref: refman/methods/print_message_tokens_3 doc1130603
Ref: 8141130603
Ref: refman/methods/print_message_tokens_3 methods-print-message-tokens-31130603
Ref: 7f91130603
Ref: refman/methods/print_message_tokens_3 print-message-tokens-31130603
Ref: 8151130603
Node: Description<160>1130834
Ref: refman/methods/print_message_tokens_3 description1130969
Ref: 8161130969
Ref: Description<160>-Footnote-11131729
Node: Modes and number of proofs<123>1131776
Ref: refman/methods/print_message_tokens_3 modes-and-number-of-proofs1131931
Ref: 8171131931
Node: Errors<124>1132087
Ref: refman/methods/print_message_tokens_3 errors1132239
Ref: 8181132239
Node: Examples<161>1132282
Ref: refman/methods/print_message_tokens_3 examples1132394
Ref: 8191132394
Node: print_message_token/41132832
Ref: refman/methods/print_message_token_4 doc1132957
Ref: 81a1132957
Ref: refman/methods/print_message_token_4 methods-print-message-token-41132957
Ref: 7fa1132957
Ref: refman/methods/print_message_token_4 print-message-token-41132957
Ref: 81b1132957
Node: Description<161>1133186
Ref: refman/methods/print_message_token_4 description1133320
Ref: 81c1133320
Ref: Description<161>-Footnote-11133786
Node: Modes and number of proofs<124>1133833
Ref: refman/methods/print_message_token_4 modes-and-number-of-proofs1133987
Ref: 81d1133987
Node: Errors<125>1134151
Ref: refman/methods/print_message_token_4 errors1134302
Ref: 81e1134302
Node: Examples<162>1134345
Ref: refman/methods/print_message_token_4 examples1134456
Ref: 81f1134456
Node: Question asking1134965
Ref: refman/methods/asking_methods doc1135081
Ref: 8201135081
Ref: refman/methods/asking_methods asking-methods1135081
Ref: 8211135081
Ref: refman/methods/asking_methods question-asking1135081
Ref: 8221135081
Node: ask_question/51135225
Ref: refman/methods/ask_question_5 doc1135335
Ref: 8231135335
Ref: refman/methods/ask_question_5 ask-question-51135335
Ref: 8241135335
Ref: refman/methods/ask_question_5 methods-ask-question-51135335
Ref: 30c1135335
Node: Description<162>1135604
Ref: refman/methods/ask_question_5 description1135731
Ref: 8251135731
Node: Modes and number of proofs<125>1136820
Ref: refman/methods/ask_question_5 modes-and-number-of-proofs1136983
Ref: 8261136983
Node: Meta-predicate template<17>1137126
Ref: refman/methods/ask_question_5 meta-predicate-template1137284
Ref: 8271137284
Node: Errors<126>1137385
Ref: refman/methods/ask_question_5 errors1137525
Ref: 8281137525
Node: Examples<163>1137566
Ref: refman/methods/ask_question_5 examples1137670
Ref: 8291137670
Node: question_hook/61138092
Ref: refman/methods/question_hook_6 doc1138235
Ref: 82a1138235
Ref: refman/methods/question_hook_6 methods-question-hook-61138235
Ref: 30e1138235
Ref: refman/methods/question_hook_6 question-hook-61138235
Ref: 82b1138235
Node: Description<163>1138506
Ref: refman/methods/question_hook_6 description1138634
Ref: 82c1138634
Ref: Description<163>-Footnote-11139144
Node: Modes and number of proofs<126>1139191
Ref: refman/methods/question_hook_6 modes-and-number-of-proofs1139355
Ref: 82d1139355
Node: Meta-predicate template<18>1139522
Ref: refman/methods/question_hook_6 meta-predicate-template1139681
Ref: 82e1139681
Node: Errors<127>1139788
Ref: refman/methods/question_hook_6 errors1139929
Ref: 82f1139929
Node: Examples<164>1139972
Ref: refman/methods/question_hook_6 examples1140077
Ref: 8301140077
Node: question_prompt_stream/41140629
Ref: refman/methods/question_prompt_stream_4 doc1140749
Ref: 8311140749
Ref: refman/methods/question_prompt_stream_4 methods-question-prompt-stream-41140749
Ref: 7fb1140749
Ref: refman/methods/question_prompt_stream_4 question-prompt-stream-41140749
Ref: 8321140749
Node: Description<164>1140984
Ref: refman/methods/question_prompt_stream_4 description1141121
Ref: 8331141121
Ref: Description<164>-Footnote-11141511
Node: Modes and number of proofs<127>1141558
Ref: refman/methods/question_prompt_stream_4 modes-and-number-of-proofs1141715
Ref: 8341141715
Node: Errors<128>1141877
Ref: refman/methods/question_prompt_stream_4 errors1142031
Ref: 8351142031
Node: Examples<165>1142074
Ref: refman/methods/question_prompt_stream_4 examples1142188
Ref: 8361142188
Node: Tutorial1142680
Ref: tutorial/index doc1142785
Ref: 8371142785
Ref: tutorial/index tutorial1142785
Ref: 8381142785
Node: List predicates1142927
Ref: tutorial/lists doc1143041
Ref: 8391143041
Ref: tutorial/lists list-predicates1143041
Ref: 83a1143041
Node: Defining a list object1143281
Ref: tutorial/lists defining-a-list-object1143408
Ref: 83b1143408
Ref: tutorial/lists object1143408
Ref: 83c1143408
Node: Defining a list protocol1145951
Ref: tutorial/lists defining-a-list-protocol1146094
Ref: 83d1146094
Ref: tutorial/lists protocol1146094
Ref: 83e1146094
Node: Summary1148292
Ref: tutorial/lists summary1148404
Ref: 83f1148404
Node: Dynamic object attributes1148856
Ref: tutorial/attributes doc1149010
Ref: 8401149010
Ref: tutorial/attributes dynamic-object-attributes1149010
Ref: 8411149010
Node: Defining a category1149372
Ref: tutorial/attributes category1149504
Ref: 8421149504
Ref: tutorial/attributes defining-a-category1149504
Ref: 8431149504
Node: Importing the category1153168
Ref: tutorial/attributes importing1153319
Ref: 8441153319
Ref: tutorial/attributes importing-the-category1153319
Ref: 8451153319
Node: Summary<2>1153881
Ref: tutorial/attributes summary1154004
Ref: 8461154004
Node: A reflective class-based system1154637
Ref: tutorial/reflection doc1154794
Ref: 8471154794
Ref: tutorial/reflection a-reflective-class-based-system1154794
Ref: 8481154794
Node: Defining the base classes1155909
Ref: tutorial/reflection classes1156041
Ref: 8491156041
Ref: tutorial/reflection defining-the-base-classes1156041
Ref: 84a1156041
Node: Summary<3>1157424
Ref: tutorial/reflection summary1157556
Ref: 84b1157556
Node: Profiling programs1158154
Ref: tutorial/profiling doc1158277
Ref: 84c1158277
Ref: tutorial/profiling profiling-programs1158277
Ref: 84d1158277
Node: Messages as events1158599
Ref: tutorial/profiling messages-as-events1158722
Ref: 84e1158722
Ref: tutorial/profiling profiling-events1158722
Ref: 84f1158722
Node: Profilers as monitors1159854
Ref: tutorial/profiling profilers-as-monitors1159996
Ref: 8501159996
Ref: tutorial/profiling profiling-monitors1159996
Ref: 8511159996
Node: Summary<4>1162979
Ref: tutorial/profiling summary1163094
Ref: 8521163094
Node: FAQ1163962
Ref: faq/index doc1164066
Ref: 8531164066
Ref: faq/index faq1164066
Ref: 8541164066
Node: General1164274
Ref: faq/general doc1164363
Ref: 8551164363
Ref: faq/general faq-general1164363
Ref: 8561164363
Ref: faq/general general1164363
Ref: 8571164363
Node: Why are all versions of Logtalk numbered 2 x or 3 x?1164955
Ref: faq/general faq-general-versions1165127
Ref: 8581165127
Ref: faq/general why-are-all-versions-of-logtalk-numbered-2-x-or-3-x1165127
Ref: 85c1165127
Node: Why do I need a Prolog compiler to use Logtalk?1165793
Ref: faq/general faq-general-prolog1166028
Ref: 8591166028
Ref: faq/general why-do-i-need-a-prolog-compiler-to-use-logtalk1166028
Ref: 85d1166028
Node: Is the Logtalk implementation based on Prolog modules?1166661
Ref: faq/general faq-general-modules1166895
Ref: 85a1166895
Ref: faq/general is-the-logtalk-implementation-based-on-prolog-modules1166895
Ref: 85e1166895
Node: Does the Logtalk implementation use term-expansion?1167549
Ref: faq/general does-the-logtalk-implementation-use-term-expansion1167727
Ref: 85f1167727
Ref: faq/general faq-general-expansion1167727
Ref: 85b1167727
Node: Compatibility1167950
Ref: faq/compatibility doc1168060
Ref: 8601168060
Ref: faq/compatibility compatibility1168060
Ref: 8611168060
Ref: faq/compatibility faq-compatibility1168060
Ref: 8621168060
Node: What are the backend Prolog compiler requirements to run Logtalk?1168541
Ref: faq/compatibility faq-compatibility-requirements1168734
Ref: 8631168734
Ref: faq/compatibility what-are-the-backend-prolog-compiler-requirements-to-run-logtalk1168734
Ref: 8661168734
Ref: What are the backend Prolog compiler requirements to run Logtalk?-Footnote-11168971
Node: Can I use constraint-based packages with Logtalk?1169025
Ref: faq/compatibility can-i-use-constraint-based-packages-with-logtalk1169289
Ref: 8671169289
Ref: faq/compatibility faq-compatibility-constraints1169289
Ref: 8641169289
Node: Can I use Logtalk objects and Prolog modules at the same time?1169930
Ref: faq/compatibility can-i-use-logtalk-objects-and-prolog-modules-at-the-same-time1170120
Ref: 8681170120
Ref: faq/compatibility faq-compatibility-modules1170120
Ref: 8651170120
Node: Installation1170708
Ref: faq/installation doc1170822
Ref: 8691170822
Ref: faq/installation faq-installation1170822
Ref: 86a1170822
Ref: faq/installation installation1170822
Ref: 86b1170822
Node: The integration scripts/shortcuts are not working!1171172
Ref: faq/installation faq-installation-scripts1171376
Ref: 86c1171376
Ref: faq/installation the-integration-scripts-shortcuts-are-not-working1171376
Ref: 86e1171376
Node: I get errors when starting up Logtalk after upgrading to the latest version!1172326
Ref: faq/installation faq-installation-startup-errors1172530
Ref: 86d1172530
Ref: faq/installation i-get-errors-when-starting-up-logtalk-after-upgrading-to-the-latest-version1172530
Ref: 86f1172530
Node: Portability1173099
Ref: faq/portability doc1173211
Ref: 8701173211
Ref: faq/portability faq-portability1173211
Ref: 8711173211
Ref: faq/portability portability1173211
Ref: 8721173211
Node: Are my Logtalk applications portable across Prolog compilers?1173558
Ref: faq/portability are-my-logtalk-applications-portable-across-prolog-compilers1173758
Ref: 8751173758
Ref: faq/portability faq-portability-prolog1173758
Ref: 8731173758
Node: Are my Logtalk applications portable across operating systems?1174548
Ref: faq/portability are-my-logtalk-applications-portable-across-operating-systems1174748
Ref: 8761174748
Ref: faq/portability faq-portability-os1174748
Ref: 8741174748
Node: Programming1175306
Ref: faq/programming doc1175421
Ref: 8771175421
Ref: faq/programming faq-programming1175421
Ref: 8781175421
Ref: faq/programming programming1175421
Ref: 8791175421
Node: Should I use prototypes or classes in my application?1176370
Ref: faq/programming faq-programming-either-prototypes-classes1176562
Ref: 87a1176562
Ref: faq/programming should-i-use-prototypes-or-classes-in-my-application1176562
Ref: 8801176562
Node: Can I use both classes and prototypes in the same application?1177065
Ref: faq/programming can-i-use-both-classes-and-prototypes-in-the-same-application1177321
Ref: 8811177321
Ref: faq/programming faq-programming-both-prototypes-classes1177321
Ref: 87b1177321
Node: Can I mix classes and prototypes in the same hierarchy?1177557
Ref: faq/programming can-i-mix-classes-and-prototypes-in-the-same-hierarchy1177828
Ref: 8821177828
Ref: faq/programming faq-programming-hierarchy1177828
Ref: 87c1177828
Node: Can I use a protocol or a category with both prototypes and classes?1178078
Ref: faq/programming can-i-use-a-protocol-or-a-category-with-both-prototypes-and-classes1178357
Ref: 8831178357
Ref: faq/programming faq-programming-protocols-categories1178357
Ref: 87d1178357
Node: What support is provided in Logtalk for defining and using components?1178695
Ref: faq/programming faq-programming-components1178982
Ref: 87e1178982
Ref: faq/programming what-support-is-provided-in-logtalk-for-defining-and-using-components1178982
Ref: 8841178982
Node: What support is provided in Logtalk for reflective programming?1179626
Ref: faq/programming faq-programming-reflection1179836
Ref: 87f1179836
Ref: faq/programming what-support-is-provided-in-logtalk-for-reflective-programming1179836
Ref: 8851179836
Node: Troubleshooting1180272
Ref: faq/troubleshooting doc1180385
Ref: 8861180385
Ref: faq/troubleshooting faq-troubleshooting1180385
Ref: 8871180385
Ref: faq/troubleshooting troubleshooting1180385
Ref: 8881180385
Node: Using compiler options on calls to the Logtalk compiling and loading predicates does not work!1181322
Ref: faq/troubleshooting faq-troubleshooting-options1181598
Ref: 8891181598
Ref: faq/troubleshooting using-compiler-options-on-calls-to-the-logtalk-compiling-and-loading-predicates-does-not-work1181598
Ref: 88c1181598
Node: Gecko-based browsers e g Firefox show non-rendered HTML entities when browsing XML documenting files!1182290
Ref: faq/troubleshooting faq-troubleshooting-gecko1182722
Ref: 88a1182722
Ref: faq/troubleshooting gecko-based-browsers-e-g-firefox-show-non-rendered-html-entities-when-browsing-xml-documenting-files1182722
Ref: 88d1182722
Node: Compiling a source file results in errors or warnings but the Logtalk compiler reports a successful compilation with zero errors and zero warnings!1183523
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-warnings1183852
Ref: 88e1183852
Ref: faq/troubleshooting faq-troubleshooting-warnings1183852
Ref: 88b1183852
Node: Usability1184882
Ref: faq/usability doc1184994
Ref: 88f1184994
Ref: faq/usability faq-usability1184994
Ref: 8901184994
Ref: faq/usability usability1184994
Ref: 8911184994
Node: Is there a shortcut for compiling and loading source files?1185473
Ref: faq/usability faq-usability-shortcuts1185680
Ref: 8921185680
Ref: faq/usability is-there-a-shortcut-for-compiling-and-loading-source-files1185680
Ref: 8951185680
Node: Is there an equivalent directive to the ensure_loaded/1 Prolog directive?1186084
Ref: faq/usability faq-usability-ensure-loaded1186347
Ref: 8931186347
Ref: faq/usability is-there-an-equivalent-directive-to-the-ensure-loaded-1-prolog-directive1186347
Ref: 8961186347
Node: Are there shortcuts for the make functionality?1186708
Ref: faq/usability are-there-shortcuts-for-the-make-functionality1186903
Ref: 8971186903
Ref: faq/usability faq-usability-make1186903
Ref: 8941186903
Node: Deployment1187595
Ref: faq/deployment doc1187706
Ref: 8981187706
Ref: faq/deployment deployment1187706
Ref: 8991187706
Ref: faq/deployment faq-deployment1187706
Ref: 89a1187706
Node: Can I create standalone applications with Logtalk?1187871
Ref: faq/deployment can-i-create-standalone-applications-with-logtalk1187988
Ref: 89c1187988
Ref: faq/deployment faq-deployment-create1187988
Ref: 89b1187988
Ref: Can I create standalone applications with Logtalk?-Footnote-11188594
Node: Performance<3>1188637
Ref: faq/performance doc1188748
Ref: 89d1188748
Ref: faq/performance id11188748
Ref: 89e1188748
Ref: faq/performance performance1188748
Ref: 89f1188748
Node: Is Logtalk implemented as a meta-interpreter?1189586
Ref: faq/performance is-logtalk-implemented-as-a-meta-interpreter1189797
Ref: 8a41189797
Ref: faq/performance performance-meta-interpreter1189797
Ref: 8a01189797
Node: What kind of code Logtalk generates when compiling objects? Dynamic code? Static code?1190147
Ref: faq/performance performance-code-generated1190457
Ref: 8a11190457
Ref: faq/performance what-kind-of-code-logtalk-generates-when-compiling-objects-dynamic-code-static-code1190457
Ref: 8a51190457
Node: How about message-sending performance? Does Logtalk use static binding or dynamic binding?1191020
Ref: faq/performance how-about-message-sending-performance-does-logtalk-use-static-binding-or-dynamic-binding1191362
Ref: 8a61191362
Ref: faq/performance performance-binding1191362
Ref: 8a21191362
Node: Which Prolog-dependent factors are most crucial for good Logtalk performance?1192417
Ref: faq/performance which-prolog-dependent-factors-are-most-crucial-for-good-logtalk-performance1192752
Ref: 8a71192752
Node: How does Logtalk performance compare with plain Prolog and with Prolog modules?1193517
Ref: faq/performance how-does-logtalk-performance-compare-with-plain-prolog-and-with-prolog-modules1193753
Ref: 8a81193753
Ref: faq/performance performance-prolog1193753
Ref: 8a31193753
Ref: How does Logtalk performance compare with plain Prolog and with Prolog modules?-Footnote-11194558
Node: Licensing1194603
Ref: faq/licensing doc1194711
Ref: 8a91194711
Ref: faq/licensing faq-licensing1194711
Ref: 8aa1194711
Ref: faq/licensing licensing1194711
Ref: 8ab1194711
Node: What’s the Logtalk distribution license?1195165
Ref: faq/licensing faq-licensing-license1195329
Ref: 8ac1195329
Ref: faq/licensing what-s-the-logtalk-distribution-license1195329
Ref: 8af1195329
Ref: What’s the Logtalk distribution license?-Footnote-11195508
Node: Can Logtalk be used in commercial applications?1195582
Ref: faq/licensing can-logtalk-be-used-in-commercial-applications1195834
Ref: 8b01195834
Ref: faq/licensing faq-licensing-commercial1195834
Ref: 8ad1195834
Ref: Can Logtalk be used in commercial applications?-Footnote-11196088
Node: What’s the final license for a combination of Logtalk with a Prolog compiler?1196147
Ref: faq/licensing faq-licensing-combining1196348
Ref: 8ae1196348
Ref: faq/licensing what-s-the-final-license-for-a-combination-of-logtalk-with-a-prolog-compiler1196348
Ref: 8b11196348
Ref: What’s the final license for a combination of Logtalk with a Prolog compiler?-Footnote-11196621
Node: Support1196664
Ref: faq/support doc1196749
Ref: 8b21196749
Ref: faq/support faq-support1196749
Ref: 8b31196749
Ref: faq/support support1196749
Ref: 8b41196749
Node: Are there professional consulting training and supporting services?1197019
Ref: faq/support are-there-professional-consulting-training-and-supporting-services1197150
Ref: 8b61197150
Ref: faq/support faq-support-professional1197150
Ref: 8b51197150
Ref: Are there professional consulting training and supporting services?-Footnote-11197453
Node: Developer Tools1197481
Ref: devtools/index doc1197586
Ref: 2801197586
Ref: devtools/index developer-tools1197586
Ref: 8b71197586
Node: Overview1198090
Ref: devtools/overview doc1198183
Ref: 8b81198183
Ref: devtools/overview overview1198183
Ref: 8b91198183
Node: Loading the developer tools1199093
Ref: devtools/overview loading-the-developer-tools1199213
Ref: 8ba1199213
Node: Tools documentation1200482
Ref: devtools/overview tools-documentation1200629
Ref: 8bb1200629
Node: Tools common flags1200922
Ref: devtools/overview tools-common-flags1201060
Ref: 8bc1201060
Node: Tools requirements1201504
Ref: devtools/overview tools-requirements1201614
Ref: 8bd1201614
Node: Tool dependencies for full functionality1202515
Ref: devtools/overview tool-dependencies-for-full-functionality1202680
Ref: 8be1202680
Node: Python dependencies all operating-systems1203245
Ref: devtools/overview python-dependencies-all-operating-systems1203435
Ref: 8bf1203435
Node: macOS - MacPorts1203830
Ref: devtools/overview macos-macports1203996
Ref: 8c01203996
Node: macOS - Homebrew1204347
Ref: devtools/overview macos-homebrew1204478
Ref: 8c11204478
Node: Ubuntu1204796
Ref: devtools/overview ubuntu1204917
Ref: 8c21204917
Node: RedHat1205235
Ref: devtools/overview redhat1205360
Ref: 8c31205360
Node: Windows - Chocolatey1205593
Ref: devtools/overview windows-chocolatey1205722
Ref: 8c41205722
Node: Installers1206017
Ref: devtools/overview installers1206168
Ref: 8c51206168
Node: Windows - PowerShell add-ons1206539
Ref: devtools/overview windows-powershell-add-ons1206661
Ref: 8c61206661
Node: asdf1206777
Ref: devtools/asdf doc1206889
Ref: 8c71206889
Ref: devtools/asdf asdf1206889
Ref: 8c81206889
Ref: devtools/asdf library-asdf1206889
Ref: 8c91206889
Ref: asdf-Footnote-11207310
Node: assertions1207338
Ref: devtools/assertions doc1207454
Ref: 8ca1207454
Ref: devtools/assertions assertions1207454
Ref: 8cb1207454
Ref: devtools/assertions library-assertions1207454
Ref: 8cc1207454
Node: API documentation1208176
Ref: devtools/assertions api-documentation1208276
Ref: 8cd1208276
Node: Loading1208419
Ref: devtools/assertions loading1208535
Ref: 8ce1208535
Node: Testing1208651
Ref: devtools/assertions testing1208787
Ref: 8cf1208787
Node: Adding assertions to your source code1208913
Ref: devtools/assertions adding-assertions-to-your-source-code1209110
Ref: 8d01209110
Node: Automatically adding file and line context information to assertions1209768
Ref: devtools/assertions automatically-adding-file-and-line-context-information-to-assertions1210002
Ref: 8d11210002
Node: Suppressing assertion calls from source code1210798
Ref: devtools/assertions suppressing-assertion-calls-from-source-code1211033
Ref: 8d21211033
Node: Redirecting assertion failure messages1211529
Ref: devtools/assertions redirecting-assertion-failure-messages1211737
Ref: 8d31211737
Node: Converting assertion failures into errors1212343
Ref: devtools/assertions converting-assertion-failures-into-errors1212498
Ref: 8d41212498
Node: code_metrics1213443
Ref: devtools/code_metrics doc1213572
Ref: 8d51213572
Ref: devtools/code_metrics code-metrics1213572
Ref: 8d61213572
Ref: devtools/code_metrics library-code-metrics1213572
Ref: 8d71213572
Node: API documentation<2>1214831
Ref: devtools/code_metrics api-documentation1214939
Ref: 8d81214939
Node: Loading<2>1215084
Ref: devtools/code_metrics loading1215211
Ref: 8d91215211
Node: Testing<2>1215329
Ref: devtools/code_metrics testing1215453
Ref: 8da1215453
Node: Available metrics1215581
Ref: devtools/code_metrics available-metrics1215711
Ref: 8db1215711
Node: Coupling metrics1216816
Ref: devtools/code_metrics coupling-metrics1216959
Ref: 8dc1216959
Node: Lack of cohesion metric1220030
Ref: devtools/code_metrics lack-of-cohesion-metric1220166
Ref: 8dd1220166
Node: WMC metric1221641
Ref: devtools/code_metrics wmc-metric1221771
Ref: 8de1221771
Node: RFC metric1222872
Ref: devtools/code_metrics rfc-metric1223006
Ref: 8df1223006
Node: Cognitive complexity metric1224528
Ref: devtools/code_metrics cognitive-complexity-metric1224664
Ref: 8e01224664
Node: Lines metric1225777
Ref: devtools/code_metrics lines-metric1225931
Ref: 8e11225931
Node: Maintainability index metric1226668
Ref: devtools/code_metrics maintainability-index-metric1226810
Ref: 8e21226810
Node: Halstead metric1227572
Ref: devtools/code_metrics halstead-metric1227712
Ref: 8e31227712
Node: UPN metric1229481
Ref: devtools/code_metrics upn-metric1229621
Ref: 8e41229621
Node: Cyclomatic complexity metric1230378
Ref: devtools/code_metrics cyclomatic-complexity-metric1230508
Ref: 8e51230508
Node: Usage1231914
Ref: devtools/code_metrics usage1232062
Ref: 8e61232062
Node: Excluding code from analysis1232432
Ref: devtools/code_metrics excluding-code-from-analysis1232572
Ref: 8e71232572
Node: Defining new metrics1233412
Ref: devtools/code_metrics defining-new-metrics1233564
Ref: 8e81233564
Node: Third-party tools1233873
Ref: devtools/code_metrics third-party-tools1234031
Ref: 8e91234031
Node: Applying metrics to Prolog modules1234437
Ref: devtools/code_metrics applying-metrics-to-prolog-modules1234612
Ref: 8ea1234612
Node: Applying metrics to plain Prolog code1235075
Ref: devtools/code_metrics applying-metrics-to-plain-prolog-code1235224
Ref: 8eb1235224
Node: dead_code_scanner1236140
Ref: devtools/dead_code_scanner doc1236273
Ref: 8ec1236273
Ref: devtools/dead_code_scanner dead-code-scanner1236273
Ref: 8ed1236273
Ref: devtools/dead_code_scanner library-dead-code-scanner1236273
Ref: 8ee1236273
Node: API documentation<3>1238273
Ref: devtools/dead_code_scanner api-documentation1238386
Ref: 8ef1238386
Node: Loading<3>1238617
Ref: devtools/dead_code_scanner loading1238749
Ref: 8f01238749
Node: Testing<3>1238872
Ref: devtools/dead_code_scanner testing1238992
Ref: 8f11238992
Node: Usage<2>1239125
Ref: devtools/dead_code_scanner usage1239266
Ref: 8f21239266
Node: Excluding code from analysis<2>1241471
Ref: devtools/dead_code_scanner excluding-code-from-analysis1241628
Ref: 8f31241628
Node: Machine-readable summaries1243117
Ref: devtools/dead_code_scanner machine-readable-summaries1243301
Ref: 8f41243301
Node: Machine-readable preflight warnings1244175
Ref: devtools/dead_code_scanner machine-readable-preflight-warnings1244358
Ref: 8f51244358
Node: Finding classes and confidence1244981
Ref: devtools/dead_code_scanner finding-classes-and-confidence1245151
Ref: 8f61245151
Node: SARIF reports1247176
Ref: devtools/dead_code_scanner sarif-reports1247341
Ref: 8f71247341
Node: Integration with the make tool1249268
Ref: devtools/dead_code_scanner integration-with-the-make-tool1249410
Ref: 8f81249410
Node: Caveats1249699
Ref: devtools/dead_code_scanner caveats1249851
Ref: 8f91249851
Node: Scanning Prolog modules1250297
Ref: devtools/dead_code_scanner scanning-prolog-modules1250446
Ref: 8fa1250446
Node: Scanning plain Prolog files1250877
Ref: devtools/dead_code_scanner scanning-plain-prolog-files1251031
Ref: 8fb1251031
Node: Known issues1251953
Ref: devtools/dead_code_scanner known-issues1252075
Ref: 8fc1252075
Node: debug_messages1252433
Ref: devtools/debug_messages doc1252562
Ref: 3531252562
Ref: devtools/debug_messages debug-messages1252562
Ref: 8fd1252562
Ref: devtools/debug_messages library-debug-messages1252562
Ref: 8fe1252562
Node: API documentation<4>1253050
Ref: devtools/debug_messages api-documentation1253160
Ref: 8ff1253160
Node: Loading<4>1253486
Ref: devtools/debug_messages loading1253615
Ref: 9001253615
Node: Testing<4>1253735
Ref: devtools/debug_messages testing1253852
Ref: 9011253852
Node: Usage<3>1253982
Ref: devtools/debug_messages usage1254080
Ref: 9021254080
Node: debugger1255623
Ref: devtools/debugger doc1255743
Ref: 2fd1255743
Ref: devtools/debugger debugger1255743
Ref: 9031255743
Ref: devtools/debugger library-debugger1255743
Ref: 9041255743
Node: API documentation<5>1256264
Ref: devtools/debugger api-documentation1256368
Ref: 9051256368
Node: Loading<5>1256509
Ref: devtools/debugger loading1256632
Ref: 9061256632
Node: Testing<5>1256904
Ref: devtools/debugger testing1257015
Ref: 9071257015
Node: Usage<4>1257139
Ref: devtools/debugger usage1257266
Ref: 9081257266
Node: Alternative debugger tools1258469
Ref: devtools/debugger alternative-debugger-tools1258601
Ref: 9091258601
Node: Known issues<2>1259446
Ref: devtools/debugger known-issues1259561
Ref: 90a1259561
Node: diagrams1260562
Ref: devtools/diagrams doc1260674
Ref: 2ee1260674
Ref: devtools/diagrams diagrams1260674
Ref: 90b1260674
Ref: devtools/diagrams library-diagrams1260674
Ref: 90c1260674
Node: Requirements1262797
Ref: devtools/diagrams requirements1262903
Ref: 90d1262903
Node: macOS - MacPorts<2>1263387
Ref: devtools/diagrams macos-macports1263503
Ref: 90e1263503
Node: macOS - Homebrew<2>1263592
Ref: devtools/diagrams macos-homebrew1263740
Ref: 90f1263740
Node: Windows - Chocolatey<2>1263824
Ref: devtools/diagrams windows-chocolatey1263966
Ref: 9101263966
Node: Installers<2>1264059
Ref: devtools/diagrams installers1264173
Ref: 9111264173
Node: API documentation<6>1264303
Ref: devtools/diagrams api-documentation1264428
Ref: 9121264428
Node: Loading<6>1264650
Ref: devtools/diagrams loading1264773
Ref: 9131264773
Node: Testing<6>1264887
Ref: devtools/diagrams testing1265008
Ref: 9141265008
Node: Supported diagrams1265132
Ref: devtools/diagrams supported-diagrams1265257
Ref: 9151265257
Node: Graph elements1267853
Ref: devtools/diagrams graph-elements1267993
Ref: 9161267993
Node: Supported graph languages1271207
Ref: devtools/diagrams supported-graph-languages1271342
Ref: 9171271342
Node: Customization1276007
Ref: devtools/diagrams customization1276144
Ref: 9181276144
Node: Linking diagrams1288736
Ref: devtools/diagrams linking-diagrams1288896
Ref: 9191288896
Node: Creating diagrams for Prolog module applications1293795
Ref: devtools/diagrams creating-diagrams-for-prolog-module-applications1293982
Ref: 91a1293982
Node: Creating diagrams for plain Prolog files1294616
Ref: devtools/diagrams creating-diagrams-for-plain-prolog-files1294798
Ref: 91b1294798
Node: Other notes1295624
Ref: devtools/diagrams other-notes1295749
Ref: 91c1295749
Node: doclet1298364
Ref: devtools/doclet doc1298472
Ref: 32e1298472
Ref: devtools/doclet doclet1298472
Ref: 91d1298472
Ref: devtools/doclet library-doclet1298472
Ref: 91e1298472
Node: API documentation<7>1299618
Ref: devtools/doclet api-documentation1299720
Ref: 91f1299720
Node: Loading<7>1299940
Ref: devtools/doclet loading1300077
Ref: 9201300077
Node: Automating running doclets1300189
Ref: devtools/doclet automating-running-doclets1300339
Ref: 9211300339
Node: Integration with the make tool<2>1300683
Ref: devtools/doclet integration-with-the-make-tool1300814
Ref: 9221300814
Node: help1301096
Ref: devtools/help doc1301209
Ref: 9231301209
Ref: devtools/help help1301209
Ref: 9241301209
Ref: devtools/help library-help1301209
Ref: 9251301209
Node: Requirements<2>1301677
Ref: devtools/help requirements1301778
Ref: 9261301778
Node: Customization<2>1303609
Ref: devtools/help customization1303739
Ref: 9271303739
Node: API documentation<8>1305592
Ref: devtools/help api-documentation1305717
Ref: 9281305717
Node: Loading<8>1305856
Ref: devtools/help loading1305975
Ref: 9291305975
Node: Testing<7>1306045
Ref: devtools/help testing1306171
Ref: 92a1306171
Node: Supported operating-systems1306293
Ref: devtools/help supported-operating-systems1306417
Ref: 92b1306417
Node: Usage<5>1306628
Ref: devtools/help usage1306757
Ref: 92c1306757
Node: Known issues<3>1308196
Ref: devtools/help known-issues1308289
Ref: 92d1308289
Node: issue_creator1309243
Ref: devtools/issue_creator doc1309356
Ref: 92e1309356
Ref: devtools/issue_creator issue-creator1309356
Ref: 92f1309356
Ref: devtools/issue_creator library-issue-creator1309356
Ref: 9301309356
Node: Requirements<3>1309669
Ref: devtools/issue_creator requirements1309773
Ref: 9311309773
Node: Loading<9>1310031
Ref: devtools/issue_creator loading1310152
Ref: 9321310152
Node: Usage<6>1310395
Ref: devtools/issue_creator usage1310516
Ref: 9331310516
Node: Known issues<4>1313375
Ref: devtools/issue_creator known-issues1313477
Ref: 9341313477
Node: lgtdoc1313877
Ref: devtools/lgtdoc doc1313993
Ref: 3231313993
Ref: devtools/lgtdoc lgtdoc1313993
Ref: 9351313993
Ref: devtools/lgtdoc library-lgtdoc1313993
Ref: 9361313993
Node: Requirements<4>1315026
Ref: devtools/lgtdoc requirements1315133
Ref: 9371315133
Node: API documentation<9>1316582
Ref: devtools/lgtdoc api-documentation1316709
Ref: 9381316709
Node: Loading<10>1316850
Ref: devtools/lgtdoc loading1316972
Ref: 9391316972
Node: Testing<8>1317086
Ref: devtools/lgtdoc testing1317211
Ref: 93a1317211
Node: Documenting source code1317335
Ref: devtools/lgtdoc documenting-source-code1317473
Ref: 93b1317473
Node: Generating documentation1318456
Ref: devtools/lgtdoc generating-documentation1318611
Ref: 93c1318611
Ref: Generating documentation-Footnote-11320474
Node: Documentation linter checks1320524
Ref: devtools/lgtdoc documentation-linter-checks1320647
Ref: 93d1320647
Node: lgtunit1322234
Ref: devtools/lgtunit doc1322343
Ref: 1461322343
Ref: devtools/lgtunit lgtunit1322343
Ref: 93e1322343
Ref: devtools/lgtunit library-lgtunit1322343
Ref: 93f1322343
Node: Main files1324255
Ref: devtools/lgtunit main-files1324359
Ref: 9401324359
Node: API documentation<10>1324922
Ref: devtools/lgtunit api-documentation1325046
Ref: 9411325046
Node: Loading<11>1325188
Ref: devtools/lgtunit loading1325312
Ref: 9421325312
Node: Testing<9>1325427
Ref: devtools/lgtunit testing1325555
Ref: 9431325555
Node: Writing and running tests1325680
Ref: devtools/lgtunit writing-and-running-tests1325821
Ref: 9441325821
Node: Automating running tests1331820
Ref: devtools/lgtunit automating-running-tests1331974
Ref: 9461331974
Node: Parametric test objects1335122
Ref: devtools/lgtunit parametric-test-objects1335264
Ref: 9471335264
Node: Test dialects1336387
Ref: devtools/lgtunit test-dialects1336531
Ref: 9451336531
Node: User-defined test dialects1342707
Ref: devtools/lgtunit user-defined-test-dialects1342838
Ref: 9481342838
Node: QuickCheck1344280
Ref: devtools/lgtunit quickcheck1344412
Ref: 9491344412
Node: Skipping tests1357182
Ref: devtools/lgtunit skipping-tests1357303
Ref: 94a1357303
Node: Selecting tests1358573
Ref: devtools/lgtunit selecting-tests1358710
Ref: 94b1358710
Node: Checking test goal results1359728
Ref: devtools/lgtunit checking-test-goal-results1359875
Ref: 94c1359875
Node: Testing local predicates1362957
Ref: devtools/lgtunit testing-local-predicates1363125
Ref: 94d1363125
Node: Testing non-deterministic predicates1363736
Ref: devtools/lgtunit testing-non-deterministic-predicates1363896
Ref: 94e1363896
Node: Testing generators1364970
Ref: devtools/lgtunit testing-generators1365137
Ref: 94f1365137
Node: Testing input/output predicates1366071
Ref: devtools/lgtunit testing-input-output-predicates1366238
Ref: 9501366238
Node: Suppressing tested predicates output1369830
Ref: devtools/lgtunit suppressing-tested-predicates-output1370004
Ref: 9511370004
Node: Tests with timeout limits1372171
Ref: devtools/lgtunit tests-with-timeout-limits1372337
Ref: 9521372337
Node: Setup and cleanup goals1373271
Ref: devtools/lgtunit setup-and-cleanup-goals1373417
Ref: 9531373417
Node: Test annotations1374405
Ref: devtools/lgtunit test-annotations1374563
Ref: 9541374563
Node: Test execution times and memory usage1375756
Ref: devtools/lgtunit test-execution-times-and-memory-usage1375919
Ref: 9551375919
Node: Working with test data files1377672
Ref: devtools/lgtunit working-with-test-data-files1377830
Ref: 9561377830
Node: Flaky tests1379443
Ref: devtools/lgtunit flaky-tests1379571
Ref: 9571379571
Node: Mocking1380412
Ref: devtools/lgtunit mocking1380539
Ref: 9581380539
Node: Debugging messages in tests1383586
Ref: devtools/lgtunit debugging-messages-in-tests1383724
Ref: 9591383724
Node: Debugging failed tests1384700
Ref: devtools/lgtunit debugging-failed-tests1384844
Ref: 95a1384844
Node: Code coverage1387120
Ref: devtools/lgtunit code-coverage1387255
Ref: 95b1387255
Node: Utility predicates1391323
Ref: devtools/lgtunit utility-predicates1391458
Ref: 95c1391458
Node: Exporting test results1395552
Ref: devtools/lgtunit exporting-test-results1395699
Ref: 95d1395699
Node: xUnit XML format1395856
Ref: devtools/lgtunit xunit-xml-format1395977
Ref: 95e1395977
Node: TAP output format1397703
Ref: devtools/lgtunit tap-output-format1397849
Ref: 95f1397849
Node: CTRF JSON format1399185
Ref: devtools/lgtunit ctrf-json-format1399330
Ref: 9601399330
Node: Subunit formats1400239
Ref: devtools/lgtunit subunit-formats1400358
Ref: 9611400358
Node: Generating Allure reports1401521
Ref: devtools/lgtunit generating-allure-reports1401681
Ref: 9621401681
Ref: Generating Allure reports-Footnote-11406378
Node: Exporting code coverage results1406417
Ref: devtools/lgtunit exporting-code-coverage-results1406607
Ref: 9631406607
Node: Simple XML format1407357
Ref: devtools/lgtunit simple-xml-format1407491
Ref: 9641407491
Node: Cobertura XML format1409983
Ref: devtools/lgtunit cobertura-xml-format1410137
Ref: 9651410137
Node: LCOV format1410540
Ref: devtools/lgtunit lcov-format1410668
Ref: 9661410668
Node: Automatically creating bug reports at issue trackers1411030
Ref: devtools/lgtunit automatically-creating-bug-reports-at-issue-trackers1411225
Ref: 9671411225
Node: Minimizing test results output1411471
Ref: devtools/lgtunit minimizing-test-results-output1411653
Ref: 9681411653
Node: Help with warnings1411959
Ref: devtools/lgtunit help-with-warnings1412104
Ref: 9691412104
Node: Known issues<5>1412256
Ref: devtools/lgtunit known-issues1412362
Ref: 96a1412362
Node: linter1413092
Ref: devtools/linter doc1413210
Ref: 2af1413210
Ref: devtools/linter library-linter1413210
Ref: 96b1413210
Ref: devtools/linter linter1413210
Ref: 96c1413210
Ref: linter-Footnote-11414621
Ref: linter-Footnote-21414680
Ref: linter-Footnote-31414733
Ref: linter-Footnote-41414786
Node: Main linter checks1414834
Ref: devtools/linter main-linter-checks1414947
Ref: 96d1414947
Node: Help on linter warnings1418504
Ref: devtools/linter help-on-linter-warnings1418646
Ref: 96e1418646
Ref: Help on linter warnings-Footnote-11418944
Node: Extending the linter1419001
Ref: devtools/linter extending-the-linter1419147
Ref: 96f1419147
Ref: Extending the linter-Footnote-11419576
Node: Linting Prolog modules1419632
Ref: devtools/linter linting-prolog-modules1419781
Ref: 9701419781
Node: Linting plain Prolog files1420210
Ref: devtools/linter linting-plain-prolog-files1420330
Ref: 9711420330
Node: linter_reporter1421207
Ref: devtools/linter_reporter doc1421322
Ref: 9721421322
Ref: devtools/linter_reporter library-linter-reporter1421322
Ref: 9731421322
Ref: devtools/linter_reporter linter-reporter1421322
Ref: 9741421322
Node: API documentation<11>1421716
Ref: devtools/linter_reporter api-documentation1421829
Ref: 9751421829
Node: Loading<12>1421979
Ref: devtools/linter_reporter loading1422112
Ref: 9761422112
Node: Testing<10>1422224
Ref: devtools/linter_reporter testing1422344
Ref: 9771422344
Node: Usage<7>1422714
Ref: devtools/linter_reporter usage1422830
Ref: 9781422830
Node: Options1423907
Ref: devtools/linter_reporter options1424003
Ref: 9791424003
Node: make1424297
Ref: devtools/make doc1424422
Ref: 97a1424422
Ref: devtools/make library-make1424422
Ref: 97b1424422
Ref: devtools/make make1424422
Ref: 97c1424422
Node: API documentation<12>1424750
Ref: devtools/make api-documentation1424862
Ref: 97d1424862
Node: Help with warnings<2>1425415
Ref: devtools/make help-with-warnings1425551
Ref: 97e1425551
Node: Known issues<6>1425698
Ref: devtools/make known-issues1425804
Ref: 97f1425804
Node: mutation_testing1426337
Ref: devtools/mutation_testing doc1426452
Ref: 9801426452
Ref: devtools/mutation_testing library-mutation-testing1426452
Ref: 9811426452
Ref: devtools/mutation_testing mutation-testing1426452
Ref: 9821426452
Node: API documentation<13>1426894
Ref: devtools/mutation_testing api-documentation1427008
Ref: 9831427008
Node: Loading<13>1427159
Ref: devtools/mutation_testing loading1427293
Ref: 9841427293
Node: Testing<11>1427417
Ref: devtools/mutation_testing testing1427538
Ref: 9851427538
Node: Features1427880
Ref: devtools/mutation_testing features1428006
Ref: 9861428006
Node: Default mutators1428577
Ref: devtools/mutation_testing default-mutators1428700
Ref: 9871428700
Node: Usage<8>1430223
Ref: devtools/mutation_testing usage1430349
Ref: 9881430349
Node: Limitations1432754
Ref: devtools/mutation_testing limitations1432874
Ref: 9891432874
Node: Options<2>1433544
Ref: devtools/mutation_testing options1433674
Ref: 98a1433674
Node: Sampling semantics1436983
Ref: devtools/mutation_testing sampling-semantics1437123
Ref: 98b1437123
Node: Sampling modes1438539
Ref: devtools/mutation_testing sampling-modes1438663
Ref: 98c1438663
Node: Sampling usage in practice1439358
Ref: devtools/mutation_testing sampling-usage-in-practice1439482
Ref: 98d1439482
Node: Defining new mutators1440281
Ref: devtools/mutation_testing defining-new-mutators1440402
Ref: 98e1440402
Node: packs1441928
Ref: devtools/packs doc1442053
Ref: 64a1442053
Ref: devtools/packs library-packs1442053
Ref: 98f1442053
Ref: devtools/packs packs1442053
Ref: 9901442053
Node: Requirements<5>1444008
Ref: devtools/packs requirements1444115
Ref: 9911444115
Ref: Requirements<5>-Footnote-11446316
Node: API documentation<14>1446365
Ref: devtools/packs api-documentation1446492
Ref: 9921446492
Node: Loading<14>1446632
Ref: devtools/packs loading1446755
Ref: 9931446755
Node: Testing<12>1446868
Ref: devtools/packs testing1446978
Ref: 9941446978
Node: Usage<9>1447157
Ref: devtools/packs usage1447278
Ref: 9951447278
Node: Programmatic query API1447739
Ref: devtools/packs programmatic-query-api1447877
Ref: 9961447877
Node: Registries and packs storage1451977
Ref: devtools/packs registries-and-packs-storage1452127
Ref: 9971452127
Node: Virtual environments1453374
Ref: devtools/packs virtual-environments1453512
Ref: 9981453512
Ref: Virtual environments-Footnote-11457701
Ref: Virtual environments-Footnote-21457751
Ref: Virtual environments-Footnote-31457792
Node: Lock files1457841
Ref: devtools/packs lock-files1457973
Ref: 9991457973
Node: Registry specification1458720
Ref: devtools/packs registry-specification1458849
Ref: 99a1458849
Node: Registry handling1462011
Ref: devtools/packs registry-handling1462150
Ref: 99b1462150
Ref: Registry handling-Footnote-11464897
Node: Registry development1464934
Ref: devtools/packs registry-development1465069
Ref: 99c1465069
Node: Pack specification1465991
Ref: devtools/packs pack-specification1466124
Ref: 99d1466124
Ref: Pack specification-Footnote-11469157
Node: Encrypted packs1469192
Ref: devtools/packs encrypted-packs1469317
Ref: 99e1469317
Node: Signed packs1470063
Ref: devtools/packs signed-packs1470198
Ref: 99f1470198
Node: Pack URLs and Single Sign-On1471134
Ref: devtools/packs pack-urls-and-single-sign-on1471276
Ref: 9a01471276
Node: Multiple pack versions1473473
Ref: devtools/packs multiple-pack-versions1473620
Ref: 9a11473620
Node: Pack dependencies1474821
Ref: devtools/packs pack-dependencies1474956
Ref: 9a21474956
Node: Pack portability1478102
Ref: devtools/packs pack-portability1478231
Ref: 9a31478231
Node: Pack development1479051
Ref: devtools/packs pack-development1479176
Ref: 9a41479176
Node: Pack handling1480413
Ref: devtools/packs pack-handling1480540
Ref: 9a51480540
Ref: Pack handling-Footnote-11485998
Node: Pack documentation1486030
Ref: devtools/packs pack-documentation1486169
Ref: 9a61486169
Node: Pinning registries and packs1487857
Ref: devtools/packs pinning-registries-and-packs1487996
Ref: 9a71487996
Node: Testing packs1489175
Ref: devtools/packs testing-packs1489319
Ref: 9a81489319
Node: Security considerations1490085
Ref: devtools/packs security-considerations1490215
Ref: 9a91490215
Node: Best practices1491468
Ref: devtools/packs best-practices1491608
Ref: 9aa1491608
Node: Installing Prolog packs1492760
Ref: devtools/packs installing-prolog-packs1492898
Ref: 9ab1492898
Node: Help with warnings<3>1493938
Ref: devtools/packs help-with-warnings1494077
Ref: 9ac1494077
Node: Known issues<7>1494227
Ref: devtools/packs known-issues1494334
Ref: 9ad1494334
Node: ports_profiler1495699
Ref: devtools/ports_profiler doc1495816
Ref: 3591495816
Ref: devtools/ports_profiler library-ports-profiler1495816
Ref: 9ae1495816
Ref: devtools/ports_profiler ports-profiler1495816
Ref: 9af1495816
Node: API documentation<15>1497007
Ref: devtools/ports_profiler api-documentation1497119
Ref: 9b01497119
Node: Loading<15>1497349
Ref: devtools/ports_profiler loading1497481
Ref: 9b11497481
Node: Testing<13>1497561
Ref: devtools/ports_profiler testing1497713
Ref: 9b21497713
Node: Compiling source files for port profiling1497845
Ref: devtools/ports_profiler compiling-source-files-for-port-profiling1498011
Ref: 9b31498011
Node: Generating profiling data1498763
Ref: devtools/ports_profiler generating-profiling-data1498949
Ref: 9b41498949
Node: Printing profiling data reports1499567
Ref: devtools/ports_profiler printing-profiling-data-reports1499739
Ref: 9b51499739
Node: Interpreting profiling data1502330
Ref: devtools/ports_profiler interpreting-profiling-data1502501
Ref: 9b61502501
Node: Profiling Prolog modules1503312
Ref: devtools/ports_profiler profiling-prolog-modules1503479
Ref: 9b71503479
Node: Profiling plain Prolog code1503923
Ref: devtools/ports_profiler profiling-plain-prolog-code1504078
Ref: 9b81504078
Node: Known issues<8>1505501
Ref: devtools/ports_profiler known-issues1505623
Ref: 9b91505623
Node: profiler1505769
Ref: devtools/profiler doc1505886
Ref: 9ba1505886
Ref: devtools/profiler library-profiler1505886
Ref: 9bb1505886
Ref: devtools/profiler profiler1505886
Ref: 9bc1505886
Node: Loading<16>1506132
Ref: devtools/profiler loading1506228
Ref: 9bd1506228
Node: Testing<14>1506423
Ref: devtools/profiler testing1506562
Ref: 9be1506562
Node: Supported backend Prolog compilers1506688
Ref: devtools/profiler supported-backend-prolog-compilers1506851
Ref: 9bf1506851
Node: Compiling source code for profiling1508874
Ref: devtools/profiler compiling-source-code-for-profiling1509017
Ref: 9c01509017
Node: sarif1509532
Ref: devtools/sarif doc1509639
Ref: 9c11509639
Ref: devtools/sarif library-sarif1509639
Ref: 9c21509639
Ref: devtools/sarif sarif1509639
Ref: 9c31509639
Node: API documentation<16>1510033
Ref: devtools/sarif api-documentation1510136
Ref: 9c41510136
Node: Loading<17>1510276
Ref: devtools/sarif loading1510399
Ref: 9c51510399
Node: Testing<15>1510492
Ref: devtools/sarif testing1510603
Ref: 9c61510603
Node: Usage<10>1510899
Ref: devtools/sarif usage1511020
Ref: 9c71511020
Node: Diagnostics producers1512104
Ref: devtools/sarif diagnostics-producers1512234
Ref: 9c81512234
Node: Report visualization1512553
Ref: devtools/sarif report-visualization1512665
Ref: 9c91512665
Node: sbom1512878
Ref: devtools/sbom doc1512993
Ref: 9ca1512993
Ref: devtools/sbom library-sbom1512993
Ref: 9cb1512993
Ref: devtools/sbom sbom1512993
Ref: 9cc1512993
Node: API documentation<17>1513474
Ref: devtools/sbom api-documentation1513576
Ref: 9cd1513576
Node: Loading<18>1513715
Ref: devtools/sbom loading1513837
Ref: 9ce1513837
Node: Testing<16>1513949
Ref: devtools/sbom testing1514059
Ref: 9cf1514059
Node: Usage<11>1514168
Ref: devtools/sbom usage1514282
Ref: 9d01514282
Node: Known issues<9>1532934
Ref: devtools/sbom known-issues1533028
Ref: 9d11533028
Node: tool_diagnostics1533375
Ref: devtools/tool_diagnostics doc1533490
Ref: 9d21533490
Ref: devtools/tool_diagnostics library-tool-diagnostics1533490
Ref: 9d31533490
Ref: devtools/tool_diagnostics tool-diagnostics1533490
Ref: 9d41533490
Node: API documentation<18>1534177
Ref: devtools/tool_diagnostics api-documentation1534291
Ref: 9d51534291
Node: Loading<19>1534451
Ref: devtools/tool_diagnostics loading1534591
Ref: 9d61534591
Node: Protocol overview1534740
Ref: devtools/tool_diagnostics protocol-overview1534875
Ref: 9d71534875
Node: Term conventions1535859
Ref: devtools/tool_diagnostics term-conventions1535992
Ref: 9d81535992
Node: Usage<12>1541286
Ref: devtools/tool_diagnostics usage1541393
Ref: 9d91541393
Node: tutor1542399
Ref: devtools/tutor doc1542517
Ref: 9da1542517
Ref: devtools/tutor library-tutor1542517
Ref: 9db1542517
Ref: devtools/tutor tutor1542517
Ref: 9dc1542517
Node: API documentation<19>1542934
Ref: devtools/tutor api-documentation1543037
Ref: 9dd1543037
Node: Loading<20>1543177
Ref: devtools/tutor loading1543298
Ref: 9de1543298
Node: Usage<13>1543411
Ref: devtools/tutor usage1543502
Ref: 9df1543502
Node: wrapper1544992
Ref: devtools/wrapper doc1545085
Ref: 38c1545085
Ref: devtools/wrapper library-wrapper1545085
Ref: 9e01545085
Ref: devtools/wrapper wrapper1545085
Ref: 9e11545085
Node: API documentation<20>1546192
Ref: devtools/wrapper api-documentation1546297
Ref: 9e21546297
Node: Loading<21>1546439
Ref: devtools/wrapper loading1546562
Ref: 9e31546562
Node: Workflows1546677
Ref: devtools/wrapper workflows1546795
Ref: 9e41546795
Node: Customization<3>1547056
Ref: devtools/wrapper customization1547182
Ref: 9e51547182
Node: Current limitations1549166
Ref: devtools/wrapper current-limitations1549274
Ref: 9e61549274
Ref: libraries/index library-library1550289
Ref: 9e71550289
Node: Libraries1550290
Ref: libraries/index doc1550397
Ref: 9e81550397
Ref: libraries/index libraries1550397
Ref: 9e91550397
Node: Overview<2>1555110
Ref: libraries/overview doc1555224
Ref: 9ea1555224
Ref: libraries/overview overview1555224
Ref: 9eb1555224
Node: Library groups1555600
Ref: libraries/overview library-groups1555712
Ref: 9ec1555712
Node: Library documentation1563457
Ref: libraries/overview library-documentation1563595
Ref: 9ed1563595
Node: Loading libraries1563898
Ref: libraries/overview loading-libraries1564039
Ref: 9ee1564039
Node: Testing libraries1564858
Ref: libraries/overview testing-libraries1564985
Ref: 9ef1564985
Node: Credits1565641
Ref: libraries/overview credits1565765
Ref: 9f01565765
Node: Other notes<2>1566532
Ref: libraries/overview other-notes1566630
Ref: 9f11566630
Node: adaptive_boosting_classifier1566792
Ref: libraries/adaptive_boosting_classifier doc1566938
Ref: 9f21566938
Ref: libraries/adaptive_boosting_classifier adaptive-boosting-classifier1566938
Ref: 9f31566938
Ref: libraries/adaptive_boosting_classifier library-adaptive-boosting-classifier1566938
Ref: 9f41566938
Node: API documentation<21>1568292
Ref: libraries/adaptive_boosting_classifier api-documentation1568418
Ref: 9f51568418
Node: Loading<22>1568565
Ref: libraries/adaptive_boosting_classifier loading1568711
Ref: 9f61568711
Node: Testing<17>1568874
Ref: libraries/adaptive_boosting_classifier testing1569010
Ref: 9f71569010
Node: Features<2>1569168
Ref: libraries/adaptive_boosting_classifier features1569303
Ref: 9f81569303
Node: Options<3>1570192
Ref: libraries/adaptive_boosting_classifier options1570341
Ref: 9f91570341
Node: Classifier representation1570537
Ref: libraries/adaptive_boosting_classifier classifier-representation1570685
Ref: 9fa1570685
Node: References1571322
Ref: libraries/adaptive_boosting_classifier references1571469
Ref: 9fb1571469
Node: Usage<14>1571943
Ref: libraries/adaptive_boosting_classifier usage1572056
Ref: 9fc1572056
Node: Learning a Classifier1572226
Ref: libraries/adaptive_boosting_classifier learning-a-classifier1572340
Ref: 9fd1572340
Node: Making Predictions1572699
Ref: libraries/adaptive_boosting_classifier making-predictions1572846
Ref: 9fe1572846
Node: Exporting the Classifier1573501
Ref: libraries/adaptive_boosting_classifier exporting-the-classifier1573651
Ref: 9ff1573651
Node: Using a Saved Classifier1574147
Ref: libraries/adaptive_boosting_classifier using-a-saved-classifier1574302
Ref: a001574302
Node: Printing the Classifier1574645
Ref: libraries/adaptive_boosting_classifier printing-the-classifier1574767
Ref: a011574767
Node: agglomerative_clusterer1575345
Ref: libraries/agglomerative_clusterer doc1575484
Ref: a021575484
Ref: libraries/agglomerative_clusterer agglomerative-clusterer1575484
Ref: a031575484
Ref: libraries/agglomerative_clusterer library-agglomerative-clusterer1575484
Ref: a041575484
Node: API documentation<22>1576199
Ref: libraries/agglomerative_clusterer api-documentation1576320
Ref: a051576320
Node: Loading<23>1576462
Ref: libraries/agglomerative_clusterer loading1576603
Ref: a061576603
Node: Testing<18>1576745
Ref: libraries/agglomerative_clusterer testing1576876
Ref: a071576876
Node: Features<3>1577184
Ref: libraries/agglomerative_clusterer features1577314
Ref: a081577314
Node: Options<4>1579273
Ref: libraries/agglomerative_clusterer options1579416
Ref: a091579416
Node: Clusterer representation1580014
Ref: libraries/agglomerative_clusterer clusterer-representation1580157
Ref: a0a1580157
Node: Diagnostics1580924
Ref: libraries/agglomerative_clusterer diagnostics1581048
Ref: a0b1581048
Node: amqp1581485
Ref: libraries/amqp doc1581623
Ref: a0c1581623
Ref: libraries/amqp amqp1581623
Ref: a0d1581623
Ref: libraries/amqp library-amqp1581623
Ref: a0e1581623
Node: API documentation<23>1582585
Ref: libraries/amqp api-documentation1582687
Ref: a0f1582687
Node: Loading<24>1582810
Ref: libraries/amqp loading1582932
Ref: a101582932
Node: Testing<19>1583055
Ref: libraries/amqp testing1583167
Ref: a111583167
Node: Features<4>1583654
Ref: libraries/amqp features1583764
Ref: a121583764
Node: Usage<15>1584614
Ref: libraries/amqp usage1584731
Ref: a131584731
Node: Connecting to an AMQP server1585069
Ref: libraries/amqp connecting-to-an-amqp-server1585189
Ref: a141585189
Node: Opening a channel1586288
Ref: libraries/amqp opening-a-channel1586447
Ref: a151586447
Node: Declaring exchanges and queues1586699
Ref: libraries/amqp declaring-exchanges-and-queues1586849
Ref: a161586849
Node: Publishing messages1587505
Ref: libraries/amqp publishing-messages1587656
Ref: a171587656
Node: Consuming messages1588412
Ref: libraries/amqp consuming-messages1588548
Ref: a181588548
Node: Synchronous get1589178
Ref: libraries/amqp synchronous-get1589313
Ref: a191589313
Node: Quality of Service1589463
Ref: libraries/amqp quality-of-service1589592
Ref: a1a1589592
Node: Transactions1589758
Ref: libraries/amqp transactions1589909
Ref: a1b1589909
Node: Publisher Confirms RabbitMQ extension1590319
Ref: libraries/amqp publisher-confirms-rabbitmq-extension1590471
Ref: a1c1590471
Node: Closing connections1590636
Ref: libraries/amqp closing-connections1590767
Ref: a1d1590767
Node: Connection Pooling1590940
Ref: libraries/amqp connection-pooling1591067
Ref: a1e1591067
Node: Defining a pool1591493
Ref: libraries/amqp defining-a-pool1591613
Ref: a1f1591613
Node: Initializing the pool1591737
Ref: libraries/amqp initializing-the-pool1591901
Ref: a201591901
Node: Acquiring and releasing connections1592704
Ref: libraries/amqp acquiring-and-releasing-connections1592876
Ref: a211592876
Node: Using with_connection/11593209
Ref: libraries/amqp using-with-connection-11593375
Ref: a221593375
Node: Pool statistics1593840
Ref: libraries/amqp pool-statistics1593988
Ref: a231593988
Node: Resizing the pool1594134
Ref: libraries/amqp resizing-the-pool1594278
Ref: a241594278
Node: Destroying the pool1594393
Ref: libraries/amqp destroying-the-pool1594548
Ref: a251594548
Node: Creating pools dynamically1594677
Ref: libraries/amqp creating-pools-dynamically1594806
Ref: a261594806
Node: Binary Frame Encoding1595077
Ref: libraries/amqp binary-frame-encoding1595205
Ref: a271595205
Node: Frame structure1595449
Ref: libraries/amqp frame-structure1595575
Ref: a281595575
Node: Encoding/decoding frames1595900
Ref: libraries/amqp encoding-decoding-frames1596026
Ref: a291596026
Node: Data Types1596231
Ref: libraries/amqp data-types1596371
Ref: a2a1596371
Node: Float/Double Encoding/Decoding1597272
Ref: libraries/amqp float-double-encoding-decoding1597405
Ref: a2b1597405
Node: Error Handling1598755
Ref: libraries/amqp error-handling1598899
Ref: a2c1598899
Node: Comparison with STOMP1599501
Ref: libraries/amqp comparison-with-stomp1599626
Ref: a2d1599626
Node: Future Work1600767
Ref: libraries/amqp future-work1600906
Ref: a2e1600906
Node: Known Limitations and Issues1601109
Ref: libraries/amqp known-limitations-and-issues1601249
Ref: a2f1601249
Node: AMQP 1 0 vs AMQP 0-9-11601726
Ref: libraries/amqp amqp-1-0-vs-amqp-0-9-11601846
Ref: a301601846
Ref: libraries/amqp amqp-10-vs-amqp-0-9-11601846
Ref: a311601846
Node: anomaly_detection_protocols1603416
Ref: libraries/anomaly_detection_protocols doc1603542
Ref: a321603542
Ref: libraries/anomaly_detection_protocols anomaly-detection-protocols1603542
Ref: a331603542
Ref: libraries/anomaly_detection_protocols library-anomaly-detection-protocols1603542
Ref: a341603542
Node: Export header format1605221
Ref: libraries/anomaly_detection_protocols export-header-format1605355
Ref: a351605355
Node: API documentation<24>1606048
Ref: libraries/anomaly_detection_protocols api-documentation1606202
Ref: a361606202
Node: Loading<25>1606348
Ref: libraries/anomaly_detection_protocols loading1606493
Ref: a371606493
Node: Testing<20>1606650
Ref: libraries/anomaly_detection_protocols testing1606787
Ref: a381606787
Node: Test datasets1606981
Ref: libraries/anomaly_detection_protocols test-datasets1607098
Ref: a391607098
Node: application1609769
Ref: libraries/application doc1609912
Ref: a3a1609912
Ref: libraries/application application1609912
Ref: a3b1609912
Ref: libraries/application library-application1609912
Ref: a3c1609912
Node: API documentation<25>1611081
Ref: libraries/application api-documentation1611190
Ref: a3d1611190
Node: Loading<26>1611320
Ref: libraries/application loading1611449
Ref: a3e1611449
Node: Testing<21>1611595
Ref: libraries/application testing1611712
Ref: a3f1611712
Node: Usage<16>1611853
Ref: libraries/application usage1611950
Ref: a401611950
Node: apriori_pattern_miner1616724
Ref: libraries/apriori_pattern_miner doc1616849
Ref: a411616849
Ref: libraries/apriori_pattern_miner apriori-pattern-miner1616849
Ref: a421616849
Ref: libraries/apriori_pattern_miner library-apriori-pattern-miner1616849
Ref: a431616849
Node: API documentation<26>1617746
Ref: libraries/apriori_pattern_miner api-documentation1617865
Ref: a441617865
Node: Loading<27>1618005
Ref: libraries/apriori_pattern_miner loading1618144
Ref: a451618144
Node: Testing<22>1618284
Ref: libraries/apriori_pattern_miner testing1618413
Ref: a461618413
Node: Features<5>1618564
Ref: libraries/apriori_pattern_miner features1618692
Ref: a471618692
Node: Options<5>1620080
Ref: libraries/apriori_pattern_miner options1620225
Ref: a481620225
Node: Pattern miner representation1620890
Ref: libraries/apriori_pattern_miner pattern-miner-representation1621037
Ref: a491621037
Node: References<2>1621610
Ref: libraries/apriori_pattern_miner references1621738
Ref: a4a1621738
Node: arbitrary1621892
Ref: libraries/arbitrary doc1622018
Ref: a4b1622018
Ref: libraries/arbitrary arbitrary1622018
Ref: a4c1622018
Ref: libraries/arbitrary library-arbitrary1622018
Ref: a4d1622018
Node: API documentation<27>1622921
Ref: libraries/arbitrary api-documentation1623028
Ref: a4e1623028
Node: Loading<28>1623156
Ref: libraries/arbitrary loading1623283
Ref: a4f1623283
Node: Testing<23>1623427
Ref: libraries/arbitrary testing1623550
Ref: a501623550
Node: Pre-defined types1623854
Ref: libraries/arbitrary pre-defined-types1623975
Ref: a511623975
Ref: Pre-defined types-Footnote-11624220
Node: Usage<17>1624268
Ref: libraries/arbitrary usage1624415
Ref: a521624415
Node: Defining new generators and shrinkers1624651
Ref: libraries/arbitrary defining-new-generators-and-shrinkers1624812
Ref: a531624812
Node: Scoped generators and shrinkers1630619
Ref: libraries/arbitrary scoped-generators-and-shrinkers1630811
Ref: a541630811
Node: Reproducing sequences of arbitrary terms1632233
Ref: libraries/arbitrary reproducing-sequences-of-arbitrary-terms1632419
Ref: a551632419
Node: Default size of generated terms1633546
Ref: libraries/arbitrary default-size-of-generated-terms1633717
Ref: a561633717
Node: Known issues<10>1634287
Ref: libraries/arbitrary known-issues1634409
Ref: a571634409
Node: arrangements1635091
Ref: libraries/arrangements doc1635206
Ref: a581635206
Ref: libraries/arrangements arrangements1635206
Ref: a591635206
Ref: libraries/arrangements library-arrangements1635206
Ref: a5a1635206
Node: API documentation<28>1636608
Ref: libraries/arrangements api-documentation1636718
Ref: a5b1636718
Node: Loading<29>1636849
Ref: libraries/arrangements loading1636979
Ref: a5c1636979
Node: Testing<24>1637126
Ref: libraries/arrangements testing1637226
Ref: a5d1637226
Node: assignvars1637368
Ref: libraries/assignvars doc1637478
Ref: a5e1637478
Ref: libraries/assignvars assignvars1637478
Ref: a5f1637478
Ref: libraries/assignvars library-assignvars1637478
Ref: a601637478
Node: API documentation<29>1638442
Ref: libraries/assignvars api-documentation1638550
Ref: a611638550
Node: Loading<30>1638681
Ref: libraries/assignvars loading1638809
Ref: a621638809
Node: Testing<25>1638956
Ref: libraries/assignvars testing1639054
Ref: a631639054
Node: avro1639196
Ref: libraries/avro doc1639300
Ref: a641639300
Ref: libraries/avro avro1639300
Ref: a651639300
Ref: libraries/avro library-avro1639300
Ref: a661639300
Node: API documentation<30>1639799
Ref: libraries/avro api-documentation1639901
Ref: a671639901
Node: Loading<31>1640026
Ref: libraries/avro loading1640148
Ref: a681640148
Node: Testing<26>1640289
Ref: libraries/avro testing1640411
Ref: a691640411
Node: Schema representation1640547
Ref: libraries/avro schema-representation1640677
Ref: a6a1640677
Node: Data representation1640903
Ref: libraries/avro data-representation1641037
Ref: a6b1641037
Node: Schema Examples1641295
Ref: libraries/avro schema-examples1641416
Ref: a6c1641416
Node: Encoding1641712
Ref: libraries/avro encoding1641822
Ref: a6d1641822
Node: Decoding1642484
Ref: libraries/avro decoding1642570
Ref: a6e1642570
Node: base321643133
Ref: libraries/base32 doc1643233
Ref: a6f1643233
Ref: libraries/base32 base321643233
Ref: a701643233
Ref: libraries/base32 library-base321643233
Ref: a711643233
Node: API documentation<31>1643597
Ref: libraries/base32 api-documentation1643701
Ref: a721643701
Node: Loading<32>1643828
Ref: libraries/base32 loading1643952
Ref: a731643952
Node: Testing<27>1644103
Ref: libraries/base32 testing1644217
Ref: a741644217
Node: Encoding<2>1644355
Ref: libraries/base32 encoding1644469
Ref: a751644469
Node: Decoding<2>1645126
Ref: libraries/base32 decoding1645220
Ref: a761645220
Node: base581645920
Ref: libraries/base58 doc1646022
Ref: a771646022
Ref: libraries/base58 base581646022
Ref: a781646022
Ref: libraries/base58 library-base581646022
Ref: a791646022
Node: API documentation<32>1646814
Ref: libraries/base58 api-documentation1646918
Ref: a7a1646918
Node: Loading<33>1647045
Ref: libraries/base58 loading1647169
Ref: a7b1647169
Node: Testing<28>1647320
Ref: libraries/base58 testing1647434
Ref: a7c1647434
Node: Encoding<3>1647572
Ref: libraries/base58 encoding1647686
Ref: a7d1647686
Node: Decoding<3>1648190
Ref: libraries/base58 decoding1648284
Ref: a7e1648284
Node: base641648599
Ref: libraries/base64 doc1648701
Ref: a7f1648701
Ref: libraries/base64 base641648701
Ref: a801648701
Ref: libraries/base64 library-base641648701
Ref: a811648701
Node: API documentation<33>1649081
Ref: libraries/base64 api-documentation1649185
Ref: a821649185
Node: Loading<34>1649312
Ref: libraries/base64 loading1649436
Ref: a831649436
Node: Testing<29>1649587
Ref: libraries/base64 testing1649701
Ref: a841649701
Node: Encoding<4>1649839
Ref: libraries/base64 encoding1649953
Ref: a851649953
Node: Decoding<4>1651148
Ref: libraries/base64 decoding1651242
Ref: a861651242
Node: base851652277
Ref: libraries/base85 doc1652384
Ref: a871652384
Ref: libraries/base85 base851652384
Ref: a881652384
Ref: libraries/base85 library-base851652384
Ref: a891652384
Node: API documentation<34>1652943
Ref: libraries/base85 api-documentation1653047
Ref: a8a1653047
Node: Loading<35>1653174
Ref: libraries/base85 loading1653298
Ref: a8b1653298
Node: Testing<30>1653449
Ref: libraries/base85 testing1653563
Ref: a8c1653563
Node: Encoding<5>1653701
Ref: libraries/base85 encoding1653815
Ref: a8d1653815
Node: Decoding<5>1654257
Ref: libraries/base85 decoding1654351
Ref: a8e1654351
Node: basic_types1654843
Ref: libraries/basic_types doc1654969
Ref: a8f1654969
Ref: libraries/basic_types basic-types1654969
Ref: a901654969
Ref: libraries/basic_types library-basic-types1654969
Ref: a911654969
Node: API documentation<35>1655413
Ref: libraries/basic_types api-documentation1655522
Ref: a921655522
Node: Loading<36>1655648
Ref: libraries/basic_types loading1655777
Ref: a931655777
Node: Testing<31>1655925
Ref: libraries/basic_types testing1656024
Ref: a941656024
Node: bayesian_ridge_regression1656189
Ref: libraries/bayesian_ridge_regression doc1656321
Ref: a951656321
Ref: libraries/bayesian_ridge_regression bayesian-ridge-regression1656321
Ref: a961656321
Ref: libraries/bayesian_ridge_regression library-bayesian-ridge-regression1656321
Ref: a971656321
Node: API documentation<36>1656949
Ref: libraries/bayesian_ridge_regression api-documentation1657072
Ref: a981657072
Node: Loading<37>1657218
Ref: libraries/bayesian_ridge_regression loading1657361
Ref: a991657361
Node: Testing<32>1657507
Ref: libraries/bayesian_ridge_regression testing1657640
Ref: a9a1657640
Node: Features<6>1657954
Ref: libraries/bayesian_ridge_regression features1658100
Ref: a9b1658100
Node: Regressor representation1660776
Ref: libraries/bayesian_ridge_regression regressor-representation1660929
Ref: a9c1660929
Node: Diagnostics syntax1661345
Ref: libraries/bayesian_ridge_regression diagnostics-syntax1661497
Ref: a9d1661497
Node: Options<6>1663349
Ref: libraries/bayesian_ridge_regression options1663468
Ref: a9e1663468
Node: borda_ranker1665263
Ref: libraries/borda_ranker doc1665404
Ref: a9f1665404
Ref: libraries/borda_ranker borda-ranker1665404
Ref: aa01665404
Ref: libraries/borda_ranker library-borda-ranker1665404
Ref: aa11665404
Node: API documentation<37>1666506
Ref: libraries/borda_ranker api-documentation1666616
Ref: aa21666616
Node: Loading<38>1666749
Ref: libraries/borda_ranker loading1666879
Ref: aa31666879
Node: Testing<33>1667012
Ref: libraries/borda_ranker testing1667132
Ref: aa41667132
Node: Features<7>1667420
Ref: libraries/borda_ranker features1667546
Ref: aa51667546
Node: Scoring semantics1669517
Ref: libraries/borda_ranker scoring-semantics1669641
Ref: aa61669641
Node: Usage<18>1670771
Ref: libraries/borda_ranker usage1670905
Ref: aa71670905
Node: Learning a ranker1671044
Ref: libraries/borda_ranker learning-a-ranker1671158
Ref: aa81671158
Node: Inspecting diagnostics1671879
Ref: libraries/borda_ranker inspecting-diagnostics1672025
Ref: aa91672025
Node: Ranking candidate items1672284
Ref: libraries/borda_ranker ranking-candidate-items1672433
Ref: aaa1672433
Node: Exporting the ranker1672960
Ref: libraries/borda_ranker exporting-the-ranker1673078
Ref: aab1673078
Node: Diagnostics syntax<2>1673615
Ref: libraries/borda_ranker diagnostics-syntax1673742
Ref: aac1673742
Node: Options<7>1674691
Ref: libraries/borda_ranker options1674830
Ref: aad1674830
Node: Ranker representation1675337
Ref: libraries/borda_ranker ranker-representation1675468
Ref: aae1675468
Node: References<3>1676079
Ref: libraries/borda_ranker references1676191
Ref: aaf1676191
Node: bradley_terry_ranker1676355
Ref: libraries/bradley_terry_ranker doc1676485
Ref: ab01676485
Ref: libraries/bradley_terry_ranker bradley-terry-ranker1676485
Ref: ab11676485
Ref: libraries/bradley_terry_ranker library-bradley-terry-ranker1676485
Ref: ab21676485
Node: API documentation<38>1677827
Ref: libraries/bradley_terry_ranker api-documentation1677945
Ref: ab31677945
Node: Loading<39>1678086
Ref: libraries/bradley_terry_ranker loading1678224
Ref: ab41678224
Node: Testing<34>1678365
Ref: libraries/bradley_terry_ranker testing1678493
Ref: ab51678493
Node: Features<8>1678797
Ref: libraries/bradley_terry_ranker features1678934
Ref: ab61678934
Node: Dataset requirements1680132
Ref: libraries/bradley_terry_ranker dataset-requirements1680267
Ref: ab71680267
Node: Usage<19>1681032
Ref: libraries/bradley_terry_ranker usage1681177
Ref: ab81681177
Node: Learning a ranker<2>1681310
Ref: libraries/bradley_terry_ranker learning-a-ranker1681430
Ref: ab91681430
Node: Inspecting diagnostics<2>1681780
Ref: libraries/bradley_terry_ranker inspecting-diagnostics1681900
Ref: aba1681900
Node: Diagnostics syntax<3>1682181
Ref: libraries/bradley_terry_ranker diagnostics-syntax1682316
Ref: abb1682316
Node: Ranking candidate items<2>1684589
Ref: libraries/bradley_terry_ranker ranking-candidate-items1684725
Ref: abc1684725
Node: Exporting the ranker<2>1685268
Ref: libraries/bradley_terry_ranker exporting-the-ranker1685404
Ref: abd1685404
Node: Options<8>1685970
Ref: libraries/bradley_terry_ranker options1686120
Ref: abe1686120
Node: Ranker representation<2>1686376
Ref: libraries/bradley_terry_ranker ranker-representation1686518
Ref: abf1686518
Node: References<4>1687195
Ref: libraries/bradley_terry_ranker references1687318
Ref: ac01687318
Node: c45_classifier1687657
Ref: libraries/c45_classifier doc1687793
Ref: ac11687793
Ref: libraries/c45_classifier c45-classifier1687793
Ref: ac21687793
Ref: libraries/c45_classifier library-c45-classifier1687793
Ref: ac31687793
Node: API documentation<39>1688844
Ref: libraries/c45_classifier api-documentation1688956
Ref: ac41688956
Node: Loading<40>1689091
Ref: libraries/c45_classifier loading1689223
Ref: ac51689223
Node: Testing<35>1689374
Ref: libraries/c45_classifier testing1689505
Ref: ac61689505
Node: Implemented features1689651
Ref: libraries/c45_classifier implemented-features1689798
Ref: ac71689798
Node: Learned tree representation1691204
Ref: libraries/c45_classifier learned-tree-representation1691354
Ref: ac81691354
Node: Limitations<2>1691949
Ref: libraries/c45_classifier limitations1692092
Ref: ac91692092
Node: References<5>1692234
Ref: libraries/c45_classifier references1692359
Ref: aca1692359
Node: Usage<20>1692793
Ref: libraries/c45_classifier usage1692895
Ref: acb1692895
Node: cartesian_products1694197
Ref: libraries/cartesian_products doc1694317
Ref: acc1694317
Ref: libraries/cartesian_products cartesian-products1694317
Ref: acd1694317
Ref: libraries/cartesian_products library-cartesian-products1694317
Ref: ace1694317
Node: API documentation<40>1695587
Ref: libraries/cartesian_products api-documentation1695703
Ref: acf1695703
Node: Loading<41>1695842
Ref: libraries/cartesian_products loading1695978
Ref: ad01695978
Node: Testing<36>1696133
Ref: libraries/cartesian_products testing1696239
Ref: ad11696239
Node: cbor1696389
Ref: libraries/cbor doc1696509
Ref: ad21696509
Ref: libraries/cbor cbor1696509
Ref: ad31696509
Ref: libraries/cbor library-cbor1696509
Ref: ad41696509
Node: Representation1697042
Ref: libraries/cbor representation1697137
Ref: ad51697137
Node: Encoding<6>1698994
Ref: libraries/cbor encoding1699109
Ref: ad61699109
Node: Decoding<6>1699535
Ref: libraries/cbor decoding1699657
Ref: ad71699657
Node: API documentation<41>1699879
Ref: libraries/cbor api-documentation1700001
Ref: ad81700001
Node: Loading<42>1700126
Ref: libraries/cbor loading1700248
Ref: ad91700248
Node: Testing<37>1700389
Ref: libraries/cbor testing1700481
Ref: ada1700481
Node: character_sets1700617
Ref: libraries/character_sets doc1700731
Ref: adb1700731
Ref: libraries/character_sets character-sets1700731
Ref: adc1700731
Ref: libraries/character_sets library-character-sets1700731
Ref: add1700731
Node: API documentation<42>1702690
Ref: libraries/character_sets api-documentation1702802
Ref: ade1702802
Node: Loading<43>1702937
Ref: libraries/character_sets loading1703069
Ref: adf1703069
Node: Testing<38>1703220
Ref: libraries/character_sets testing1703340
Ref: ae01703340
Node: Usage<21>1703486
Ref: libraries/character_sets usage1703586
Ref: ae11703586
Node: ccsds_frames1704091
Ref: libraries/ccsds_frames doc1704220
Ref: ae21704220
Ref: libraries/ccsds_frames ccsds-frames1704220
Ref: ae31704220
Ref: libraries/ccsds_frames library-ccsds-frames1704220
Ref: ae41704220
Node: API documentation<43>1704818
Ref: libraries/ccsds_frames api-documentation1704928
Ref: ae51704928
Node: Loading<44>1705061
Ref: libraries/ccsds_frames loading1705191
Ref: ae61705191
Node: Testing<39>1705340
Ref: libraries/ccsds_frames testing1705467
Ref: ae71705467
Node: Available entities1705611
Ref: libraries/ccsds_frames available-entities1705744
Ref: ae81705744
Node: Representation<2>1706713
Ref: libraries/ccsds_frames representation1706857
Ref: ae91706857
Node: Parsing and generating1708492
Ref: libraries/ccsds_frames parsing-and-generating1708623
Ref: aea1708623
Node: Types1710289
Ref: libraries/ccsds_frames types1710417
Ref: aeb1710417
Node: Facade helpers1711938
Ref: libraries/ccsds_frames facade-helpers1712035
Ref: aec1712035
Node: ccsds_link_profiles1713455
Ref: libraries/ccsds_link_profiles doc1713591
Ref: aed1713591
Ref: libraries/ccsds_link_profiles ccsds-link-profiles1713591
Ref: aee1713591
Ref: libraries/ccsds_link_profiles library-ccsds-link-profiles1713591
Ref: aef1713591
Node: API documentation<44>1714238
Ref: libraries/ccsds_link_profiles api-documentation1714355
Ref: af01714355
Node: Loading<45>1714495
Ref: libraries/ccsds_link_profiles loading1714632
Ref: af11714632
Node: Testing<40>1714788
Ref: libraries/ccsds_link_profiles testing1714921
Ref: af21714921
Node: Representation<3>1715072
Ref: libraries/ccsds_link_profiles representation1715204
Ref: af31715204
Node: Public API1715779
Ref: libraries/ccsds_link_profiles public-api1715925
Ref: af41715925
Node: Parsing and generating<2>1716432
Ref: libraries/ccsds_link_profiles parsing-and-generating1716575
Ref: af51716575
Node: Packet helpers1717560
Ref: libraries/ccsds_link_profiles packet-helpers1717684
Ref: af61717684
Node: ccsds_packet_services1718984
Ref: libraries/ccsds_packet_services doc1719127
Ref: af71719127
Ref: libraries/ccsds_packet_services ccsds-packet-services1719127
Ref: af81719127
Ref: libraries/ccsds_packet_services library-ccsds-packet-services1719127
Ref: af91719127
Node: API documentation<45>1721357
Ref: libraries/ccsds_packet_services api-documentation1721476
Ref: afa1721476
Node: Loading<46>1721618
Ref: libraries/ccsds_packet_services loading1721757
Ref: afb1721757
Node: Testing<41>1721915
Ref: libraries/ccsds_packet_services testing1722050
Ref: afc1722050
Node: Representation<4>1722203
Ref: libraries/ccsds_packet_services representation1722346
Ref: afd1722346
Node: Packet-zone helpers1725367
Ref: libraries/ccsds_packet_services packet-zone-helpers1725531
Ref: afe1725531
Node: Telemetry transfer frame helpers1726047
Ref: libraries/ccsds_packet_services telemetry-transfer-frame-helpers1726227
Ref: aff1726227
Node: Advanced orbiting systems helpers1727022
Ref: libraries/ccsds_packet_services advanced-orbiting-systems-helpers1727212
Ref: b001727212
Node: Cross-frame packet reassembly1728424
Ref: libraries/ccsds_packet_services cross-frame-packet-reassembly1728587
Ref: b011728587
Node: Scope1732570
Ref: libraries/ccsds_packet_services scope1732691
Ref: b021732691
Node: ccsds_packetization1733126
Ref: libraries/ccsds_packetization doc1733263
Ref: b031733263
Ref: libraries/ccsds_packetization ccsds-packetization1733263
Ref: b041733263
Ref: libraries/ccsds_packetization library-ccsds-packetization1733263
Ref: b051733263
Node: API documentation<46>1734111
Ref: libraries/ccsds_packetization api-documentation1734228
Ref: b061734228
Node: Loading<47>1734368
Ref: libraries/ccsds_packetization loading1734505
Ref: b071734505
Node: Testing<42>1734661
Ref: libraries/ccsds_packetization testing1734794
Ref: b081734794
Node: Representation<5>1734945
Ref: libraries/ccsds_packetization representation1735080
Ref: b091735080
Node: Packetization1736019
Ref: libraries/ccsds_packetization packetization1736149
Ref: b0a1736149
Node: Events1737689
Ref: libraries/ccsds_packetization events1737814
Ref: b0b1737814
Node: Idle packets1738333
Ref: libraries/ccsds_packetization idle-packets1738436
Ref: b0c1738436
Node: ccsds_packets1738607
Ref: libraries/ccsds_packets doc1738740
Ref: b0d1738740
Ref: libraries/ccsds_packets ccsds-packets1738740
Ref: b0e1738740
Ref: libraries/ccsds_packets library-ccsds-packets1738740
Ref: b0f1738740
Node: API documentation<47>1739453
Ref: libraries/ccsds_packets api-documentation1739564
Ref: b101739564
Node: Loading<48>1739698
Ref: libraries/ccsds_packets loading1739829
Ref: b111739829
Node: Testing<43>1739979
Ref: libraries/ccsds_packets testing1740105
Ref: b121740105
Node: Packet Structure1740414
Ref: libraries/ccsds_packets packet-structure1740546
Ref: b131740546
Node: Representation<6>1741204
Ref: libraries/ccsds_packets representation1741332
Ref: b141741332
Node: Parsing1742229
Ref: libraries/ccsds_packets parsing1742351
Ref: b151742351
Node: Generating1743442
Ref: libraries/ccsds_packets generating1743566
Ref: b161743566
Node: Accessor Predicates1744315
Ref: libraries/ccsds_packets accessor-predicates1744462
Ref: b171744462
Node: Types and arbitrary generators1745517
Ref: libraries/ccsds_packets types-and-arbitrary-generators1745645
Ref: b181745645
Node: ccsds_tc_services1746566
Ref: libraries/ccsds_tc_services doc1746696
Ref: b191746696
Ref: libraries/ccsds_tc_services ccsds-tc-services1746696
Ref: b1a1746696
Ref: libraries/ccsds_tc_services library-ccsds-tc-services1746696
Ref: b1b1746696
Node: API documentation<48>1748121
Ref: libraries/ccsds_tc_services api-documentation1748236
Ref: b1c1748236
Node: Loading<49>1748374
Ref: libraries/ccsds_tc_services loading1748509
Ref: b1d1748509
Node: Testing<44>1748663
Ref: libraries/ccsds_tc_services testing1748794
Ref: b1e1748794
Node: Representation<7>1748943
Ref: libraries/ccsds_tc_services representation1749071
Ref: b1f1749071
Node: Scope<2>1752729
Ref: libraries/ccsds_tc_services scope1752859
Ref: b201752859
Node: Examples<166>1753336
Ref: libraries/ccsds_tc_services examples1753440
Ref: b211753440
Node: ccsds_time_codes1755818
Ref: libraries/ccsds_time_codes doc1755952
Ref: b221755952
Ref: libraries/ccsds_time_codes ccsds-time-codes1755952
Ref: b231755952
Ref: libraries/ccsds_time_codes library-ccsds-time-codes1755952
Ref: b241755952
Node: API documentation<49>1756695
Ref: libraries/ccsds_time_codes api-documentation1756809
Ref: b251756809
Node: Loading<50>1756946
Ref: libraries/ccsds_time_codes loading1757080
Ref: b261757080
Node: Testing<45>1757233
Ref: libraries/ccsds_time_codes testing1757367
Ref: b271757367
Node: Available entities<2>1757515
Ref: libraries/ccsds_time_codes available-entities1757655
Ref: b281757655
Node: Representation<8>1758460
Ref: libraries/ccsds_time_codes representation1758614
Ref: b291758614
Node: Parsing and generating<3>1759938
Ref: libraries/ccsds_time_codes parsing-and-generating1760091
Ref: b2a1760091
Node: Unix time conversion1761734
Ref: libraries/ccsds_time_codes unix-time-conversion1761903
Ref: b2b1761903
Node: Types and arbitrary generators<2>1763044
Ref: libraries/ccsds_time_codes types-and-arbitrary-generators1763179
Ref: b2c1763179
Node: ccsds_time_fields1764304
Ref: libraries/ccsds_time_fields doc1764445
Ref: b2d1764445
Ref: libraries/ccsds_time_fields ccsds-time-fields1764445
Ref: b2e1764445
Ref: libraries/ccsds_time_fields library-ccsds-time-fields1764445
Ref: b2f1764445
Node: API documentation<50>1765350
Ref: libraries/ccsds_time_fields api-documentation1765465
Ref: b301765465
Node: Loading<51>1765603
Ref: libraries/ccsds_time_fields loading1765738
Ref: b311765738
Node: Testing<46>1765892
Ref: libraries/ccsds_time_fields testing1766023
Ref: b321766023
Node: Representation<9>1766172
Ref: libraries/ccsds_time_fields representation1766317
Ref: b331766317
Node: Parsing and generating<4>1767115
Ref: libraries/ccsds_time_fields parsing-and-generating1767267
Ref: b341767267
Node: Descriptor helpers1768422
Ref: libraries/ccsds_time_fields descriptor-helpers1768548
Ref: b351768548
Node: classification_protocols1768915
Ref: libraries/classification_protocols doc1769062
Ref: b361769062
Ref: libraries/classification_protocols classification-protocols1769062
Ref: b371769062
Ref: libraries/classification_protocols library-classification-protocols1769062
Ref: b381769062
Node: Shared category1770081
Ref: libraries/classification_protocols shared-category1770200
Ref: b391770200
Node: Diagnostics<2>1770605
Ref: libraries/classification_protocols diagnostics1770756
Ref: b3a1770756
Node: Export header format<2>1771386
Ref: libraries/classification_protocols export-header-format1771543
Ref: b3b1771543
Node: API documentation<51>1772409
Ref: libraries/classification_protocols api-documentation1772563
Ref: b3c1772563
Node: Loading<52>1772708
Ref: libraries/classification_protocols loading1772850
Ref: b3d1772850
Node: Testing<47>1773006
Ref: libraries/classification_protocols testing1773143
Ref: b3e1773143
Node: Test datasets<2>1773327
Ref: libraries/classification_protocols test-datasets1773444
Ref: b3f1773444
Node: clo_span_pattern_miner1775652
Ref: libraries/clo_span_pattern_miner doc1775802
Ref: b401775802
Ref: libraries/clo_span_pattern_miner clo-span-pattern-miner1775802
Ref: b411775802
Ref: libraries/clo_span_pattern_miner library-clo-span-pattern-miner1775802
Ref: b421775802
Node: API documentation<52>1776872
Ref: libraries/clo_span_pattern_miner api-documentation1776992
Ref: b431776992
Node: Loading<53>1777135
Ref: libraries/clo_span_pattern_miner loading1777275
Ref: b441777275
Node: Testing<48>1777418
Ref: libraries/clo_span_pattern_miner testing1777548
Ref: b451777548
Node: Features<9>1777702
Ref: libraries/clo_span_pattern_miner features1777831
Ref: b461777831
Node: Options<9>1778693
Ref: libraries/clo_span_pattern_miner options1778842
Ref: b471778842
Node: Pattern miner representation<2>1779533
Ref: libraries/clo_span_pattern_miner pattern-miner-representation1779684
Ref: b481779684
Node: References<6>1780282
Ref: libraries/clo_span_pattern_miner references1780414
Ref: b491780414
Node: clustering_protocols1780572
Ref: libraries/clustering_protocols doc1780711
Ref: b4a1780711
Ref: libraries/clustering_protocols clustering-protocols1780711
Ref: b4b1780711
Ref: libraries/clustering_protocols library-clustering-protocols1780711
Ref: b4c1780711
Node: API documentation<53>1781647
Ref: libraries/clustering_protocols api-documentation1781765
Ref: b4d1781765
Node: Loading<54>1781906
Ref: libraries/clustering_protocols loading1782044
Ref: b4e1782044
Node: Testing<49>1782201
Ref: libraries/clustering_protocols testing1782334
Ref: b4f1782334
Node: Test datasets<3>1782513
Ref: libraries/clustering_protocols test-datasets1782626
Ref: b501782626
Node: colley_ranker1786573
Ref: libraries/colley_ranker doc1786702
Ref: b511786702
Ref: libraries/colley_ranker colley-ranker1786702
Ref: b521786702
Ref: libraries/colley_ranker library-colley-ranker1786702
Ref: b531786702
Node: API documentation<54>1787698
Ref: libraries/colley_ranker api-documentation1787809
Ref: b541787809
Node: Loading<55>1787943
Ref: libraries/colley_ranker loading1788074
Ref: b551788074
Node: Testing<50>1788208
Ref: libraries/colley_ranker testing1788330
Ref: b561788330
Node: Features<10>1788475
Ref: libraries/colley_ranker features1788606
Ref: b571788606
Node: Scoring semantics<2>1789729
Ref: libraries/colley_ranker scoring-semantics1789858
Ref: b581789858
Node: Usage<22>1790661
Ref: libraries/colley_ranker usage1790799
Ref: b591790799
Node: Learning a ranker<3>1791036
Ref: libraries/colley_ranker learning-a-ranker1791156
Ref: b5a1791156
Node: Inspecting diagnostics<3>1791554
Ref: libraries/colley_ranker inspecting-diagnostics1791709
Ref: b5b1791709
Node: Ranking candidate items<3>1791970
Ref: libraries/colley_ranker ranking-candidate-items1792128
Ref: b5c1792128
Node: Exporting the ranker<3>1792657
Ref: libraries/colley_ranker exporting-the-ranker1792781
Ref: b5d1792781
Node: Diagnostics syntax<4>1793323
Ref: libraries/colley_ranker diagnostics-syntax1793465
Ref: b5e1793465
Node: Ranker representation<3>1793715
Ref: libraries/colley_ranker ranker-representation1793861
Ref: b5f1793861
Node: References<7>1794245
Ref: libraries/colley_ranker references1794361
Ref: b601794361
Node: combinations1794517
Ref: libraries/combinations doc1794646
Ref: b611794646
Ref: libraries/combinations combinations1794646
Ref: b621794646
Ref: libraries/combinations library-combinations1794646
Ref: b631794646
Node: API documentation<55>1796078
Ref: libraries/combinations api-documentation1796188
Ref: b641796188
Node: Loading<56>1796321
Ref: libraries/combinations loading1796451
Ref: b651796451
Node: Testing<51>1796600
Ref: libraries/combinations testing1796700
Ref: b661796700
Node: command_line_options1796844
Ref: libraries/command_line_options doc1796964
Ref: b671796964
Ref: libraries/command_line_options command-line-options1796964
Ref: b681796964
Ref: libraries/command_line_options library-command-line-options1796964
Ref: b691796964
Node: API documentation<56>1798175
Ref: libraries/command_line_options api-documentation1798293
Ref: b6a1798293
Node: Loading<57>1798434
Ref: libraries/command_line_options loading1798572
Ref: b6b1798572
Node: Testing<52>1798737
Ref: libraries/command_line_options testing1798865
Ref: b6c1798865
Node: Terminology1799017
Ref: libraries/command_line_options terminology1799157
Ref: b6d1799157
Node: Defining option objects1800161
Ref: libraries/command_line_options defining-option-objects1800319
Ref: b6e1800319
Node: Validating option definitions1801412
Ref: libraries/command_line_options validating-option-definitions1801581
Ref: b6f1801581
Node: Example option objects1802654
Ref: libraries/command_line_options example-option-objects1802830
Ref: b701802830
Node: Parsing command-line arguments1804346
Ref: libraries/command_line_options parsing-command-line-arguments1804513
Ref: b711804513
Node: Generating help text1805038
Ref: libraries/command_line_options generating-help-text1805195
Ref: b721805195
Node: Help options1805584
Ref: libraries/command_line_options help-options1805724
Ref: b731805724
Node: Parse options1806266
Ref: libraries/command_line_options parse-options1806400
Ref: b741806400
Node: Notes and tips1807036
Ref: libraries/command_line_options notes-and-tips1807149
Ref: b751807149
Node: core1807698
Ref: libraries/core doc1807821
Ref: b761807821
Ref: libraries/core core1807821
Ref: b771807821
Ref: libraries/core library-core1807821
Ref: b781807821
Node: API documentation<57>1807997
Ref: libraries/core api-documentation1808099
Ref: b791808099
Node: Loading<58>1808232
Ref: libraries/core loading1808354
Ref: b7a1808354
Node: Testing<53>1808460
Ref: libraries/core testing1808552
Ref: b7b1808552
Node: copeland_ranker1808667
Ref: libraries/copeland_ranker doc1808781
Ref: b7c1808781
Ref: libraries/copeland_ranker copeland-ranker1808781
Ref: b7d1808781
Ref: libraries/copeland_ranker library-copeland-ranker1808781
Ref: b7e1808781
Node: API documentation<58>1810034
Ref: libraries/copeland_ranker api-documentation1810147
Ref: b7f1810147
Node: Loading<59>1810283
Ref: libraries/copeland_ranker loading1810416
Ref: b801810416
Node: Testing<54>1810552
Ref: libraries/copeland_ranker testing1810676
Ref: b811810676
Node: Features<11>1810823
Ref: libraries/copeland_ranker features1810956
Ref: b821810956
Node: Scoring semantics<3>1812275
Ref: libraries/copeland_ranker scoring-semantics1812406
Ref: b831812406
Node: Usage<23>1813407
Ref: libraries/copeland_ranker usage1813547
Ref: b841813547
Node: Learning a ranker<4>1813784
Ref: libraries/copeland_ranker learning-a-ranker1813904
Ref: b851813904
Node: Inspecting diagnostics<4>1814306
Ref: libraries/copeland_ranker inspecting-diagnostics1814461
Ref: b861814461
Node: Ranking candidate items<4>1814726
Ref: libraries/copeland_ranker ranking-candidate-items1814884
Ref: b871814884
Node: Exporting the ranker<4>1815417
Ref: libraries/copeland_ranker exporting-the-ranker1815541
Ref: b881815541
Node: Diagnostics syntax<5>1816093
Ref: libraries/copeland_ranker diagnostics-syntax1816224
Ref: b891816224
Node: Options<10>1817231
Ref: libraries/copeland_ranker options1817377
Ref: b8a1817377
Node: Ranker representation<4>1817553
Ref: libraries/copeland_ranker ranker-representation1817691
Ref: b8b1817691
Node: References<8>1818620
Ref: libraries/copeland_ranker references1818738
Ref: b8c1818738
Node: coroutining1818929
Ref: libraries/coroutining doc1819045
Ref: b8d1819045
Ref: libraries/coroutining coroutining1819045
Ref: b8e1819045
Ref: libraries/coroutining library-coroutining1819045
Ref: b8f1819045
Node: API documentation<59>1819790
Ref: libraries/coroutining api-documentation1819899
Ref: b901819899
Node: Loading<60>1820031
Ref: libraries/coroutining loading1820160
Ref: b911820160
Node: Testing<55>1820308
Ref: libraries/coroutining testing1820425
Ref: b921820425
Node: Usage<24>1820568
Ref: libraries/coroutining usage1820665
Ref: b931820665
Node: crypto1821032
Ref: libraries/crypto doc1821148
Ref: b941821148
Ref: libraries/crypto crypto1821148
Ref: b951821148
Ref: libraries/crypto library-crypto1821148
Ref: b961821148
Node: API documentation<60>1823260
Ref: libraries/crypto api-documentation1823364
Ref: b971823364
Node: Loading<61>1823491
Ref: libraries/crypto loading1823615
Ref: b981823615
Node: Testing<56>1823741
Ref: libraries/crypto testing1823857
Ref: b991823857
Node: Examples<167>1823984
Ref: libraries/crypto examples1824080
Ref: b9a1824080
Node: crs_projections1824768
Ref: libraries/crs_projections doc1824876
Ref: b9b1824876
Ref: libraries/crs_projections crs-projections1824876
Ref: b9c1824876
Ref: libraries/crs_projections library-crs-projections1824876
Ref: b9d1824876
Node: API documentation<61>1825380
Ref: libraries/crs_projections api-documentation1825493
Ref: b9e1825493
Node: Loading<62>1825629
Ref: libraries/crs_projections loading1825762
Ref: b9f1825762
Node: Testing<57>1825914
Ref: libraries/crs_projections testing1826064
Ref: ba01826064
Node: Supported coordinate reference systems1826211
Ref: libraries/crs_projections supported-coordinate-reference-systems1826359
Ref: ba11826359
Node: Usage<25>1828031
Ref: libraries/crs_projections usage1828173
Ref: ba21828173
Node: Notes1831286
Ref: libraries/crs_projections notes1831381
Ref: ba31831381
Node: csv1832293
Ref: libraries/csv doc1832400
Ref: ba41832400
Ref: libraries/csv csv1832400
Ref: ba51832400
Ref: libraries/csv library-csv1832400
Ref: ba61832400
Node: API documentation<62>1833951
Ref: libraries/csv api-documentation1834052
Ref: ba71834052
Node: Loading<63>1834176
Ref: libraries/csv loading1834297
Ref: ba81834297
Node: Testing<58>1834437
Ref: libraries/csv testing1834546
Ref: ba91834546
Node: Usage<26>1834681
Ref: libraries/csv usage1834770
Ref: baa1834770
Node: cuid21837504
Ref: libraries/cuid2 doc1837618
Ref: bab1837618
Ref: libraries/cuid2 cuid21837618
Ref: bac1837618
Ref: libraries/cuid2 library-cuid21837618
Ref: bad1837618
Node: API documentation<63>1838534
Ref: libraries/cuid2 api-documentation1838637
Ref: bae1838637
Node: Loading<64>1838763
Ref: libraries/cuid2 loading1838886
Ref: baf1838886
Node: Testing<59>1839028
Ref: libraries/cuid2 testing1839139
Ref: bb01839139
Node: Usage<27>1839276
Ref: libraries/cuid2 usage1839367
Ref: bb11839367
Node: cusum_anomaly_detector1839737
Ref: libraries/cusum_anomaly_detector doc1839855
Ref: bb21839855
Ref: libraries/cusum_anomaly_detector cusum-anomaly-detector1839855
Ref: bb31839855
Ref: libraries/cusum_anomaly_detector library-cusum-anomaly-detector1839855
Ref: bb41839855
Node: API documentation<64>1840993
Ref: libraries/cusum_anomaly_detector api-documentation1841113
Ref: bb51841113
Node: Loading<65>1841256
Ref: libraries/cusum_anomaly_detector loading1841396
Ref: bb61841396
Node: Testing<60>1841539
Ref: libraries/cusum_anomaly_detector testing1841670
Ref: bb71841670
Node: Features<12>1841824
Ref: libraries/cusum_anomaly_detector features1841955
Ref: bb81841955
Node: Options<11>1845447
Ref: libraries/cusum_anomaly_detector options1845590
Ref: bb91845590
Node: Detector representation1846522
Ref: libraries/cusum_anomaly_detector detector-representation1846661
Ref: bba1846661
Node: Notes<2>1847732
Ref: libraries/cusum_anomaly_detector notes1847851
Ref: bbb1847851
Node: datalog1849472
Ref: libraries/datalog doc1849590
Ref: bbc1849590
Ref: libraries/datalog datalog1849590
Ref: bbd1849590
Ref: libraries/datalog library-datalog1849590
Ref: bbe1849590
Node: API documentation<65>1850054
Ref: libraries/datalog api-documentation1850159
Ref: bbf1850159
Node: Loading<66>1850287
Ref: libraries/datalog loading1850412
Ref: bc01850412
Node: Testing<61>1850556
Ref: libraries/datalog testing1850668
Ref: bc11850668
Node: Scope<3>1850805
Ref: libraries/datalog scope1850925
Ref: bc21850925
Node: Public API overview1851775
Ref: libraries/datalog public-api-overview1851895
Ref: bc31851895
Node: Basic usage1853167
Ref: libraries/datalog basic-usage1853293
Ref: bc41853293
Node: Limitations<3>1853672
Ref: libraries/datalog limitations1853770
Ref: bc51853770
Node: dates1854116
Ref: libraries/dates doc1854220
Ref: bc61854220
Ref: libraries/dates dates1854220
Ref: bc71854220
Ref: libraries/dates library-dates1854220
Ref: bc81854220
Node: API documentation<66>1857787
Ref: libraries/dates api-documentation1857890
Ref: bc91857890
Node: Loading<67>1858016
Ref: libraries/dates loading1858139
Ref: bca1858139
Node: Testing<62>1858289
Ref: libraries/dates testing1858382
Ref: bcb1858382
Node: dates_tz1858519
Ref: libraries/dates_tz doc1858632
Ref: bcc1858632
Ref: libraries/dates_tz dates-tz1858632
Ref: bcd1858632
Ref: libraries/dates_tz library-dates-tz1858632
Ref: bce1858632
Node: API documentation<67>1859434
Ref: libraries/dates_tz api-documentation1859540
Ref: bcf1859540
Node: Loading<68>1859669
Ref: libraries/dates_tz loading1859795
Ref: bd01859795
Node: Testing<63>1859948
Ref: libraries/dates_tz testing1860062
Ref: bd11860062
Node: Usage<28>1860202
Ref: libraries/dates_tz usage1860318
Ref: bd21860318
Node: Examples<168>1860685
Ref: libraries/dates_tz examples1860798
Ref: bd31860798
Node: Notes<3>1863144
Ref: libraries/dates_tz notes1863239
Ref: bd41863239
Node: dbscan_clusterer1863896
Ref: libraries/dbscan_clusterer doc1864014
Ref: bd51864014
Ref: libraries/dbscan_clusterer dbscan-clusterer1864014
Ref: bd61864014
Ref: libraries/dbscan_clusterer library-dbscan-clusterer1864014
Ref: bd71864014
Node: API documentation<68>1864893
Ref: libraries/dbscan_clusterer api-documentation1865007
Ref: bd81865007
Node: Loading<69>1865144
Ref: libraries/dbscan_clusterer loading1865278
Ref: bd91865278
Node: Testing<64>1865415
Ref: libraries/dbscan_clusterer testing1865540
Ref: bda1865540
Node: Features<13>1865836
Ref: libraries/dbscan_clusterer features1865961
Ref: bdb1865961
Node: Options<12>1867073
Ref: libraries/dbscan_clusterer options1867214
Ref: bdc1867214
Node: Clusterer representation<2>1868123
Ref: libraries/dbscan_clusterer clusterer-representation1868265
Ref: bdd1868265
Node: References<9>1868907
Ref: libraries/dbscan_clusterer references1869029
Ref: bde1869029
Node: dependents1869232
Ref: libraries/dependents doc1869348
Ref: 2891869348
Ref: libraries/dependents dependents1869348
Ref: bdf1869348
Ref: libraries/dependents library-dependents1869348
Ref: be01869348
Node: API documentation<69>1869678
Ref: libraries/dependents api-documentation1869786
Ref: be11869786
Node: Loading<70>1869917
Ref: libraries/dependents loading1870025
Ref: be21870025
Node: deques1870180
Ref: libraries/deques doc1870292
Ref: be31870292
Ref: libraries/deques deques1870292
Ref: be41870292
Ref: libraries/deques library-deques1870292
Ref: be51870292
Node: API documentation<70>1870613
Ref: libraries/deques api-documentation1870717
Ref: be61870717
Node: Loading<71>1870844
Ref: libraries/deques loading1870968
Ref: be71870968
Node: Testing<65>1871111
Ref: libraries/deques testing1871223
Ref: be81871223
Node: Usage<29>1871361
Ref: libraries/deques usage1871453
Ref: be91871453
Node: derangements1872474
Ref: libraries/derangements doc1872588
Ref: bea1872588
Ref: libraries/derangements derangements1872588
Ref: beb1872588
Ref: libraries/derangements library-derangements1872588
Ref: bec1872588
Node: API documentation<71>1874044
Ref: libraries/derangements api-documentation1874154
Ref: bed1874154
Node: Loading<72>1874287
Ref: libraries/derangements loading1874417
Ref: bee1874417
Node: Testing<66>1874566
Ref: libraries/derangements testing1874666
Ref: bef1874666
Node: dictionaries1874810
Ref: libraries/dictionaries doc1874921
Ref: bf01874921
Ref: libraries/dictionaries dictionaries1874921
Ref: bf11874921
Ref: libraries/dictionaries library-dictionaries1874921
Ref: bf21874921
Node: API documentation<72>1875428
Ref: libraries/dictionaries api-documentation1875538
Ref: bf31875538
Node: Loading<73>1875671
Ref: libraries/dictionaries loading1875801
Ref: bf41875801
Node: Testing<67>1875950
Ref: libraries/dictionaries testing1876068
Ref: bf51876068
Node: Usage<30>1876212
Ref: libraries/dictionaries usage1876329
Ref: bf61876329
Node: Credits<2>1878396
Ref: libraries/dictionaries credits1878493
Ref: bf71878493
Node: dif1878964
Ref: libraries/dif doc1879092
Ref: bf81879092
Ref: libraries/dif dif1879092
Ref: bf91879092
Ref: libraries/dif library-dif1879092
Ref: bfa1879092
Node: API documentation<73>1879723
Ref: libraries/dif api-documentation1879824
Ref: bfb1879824
Node: Loading<74>1879948
Ref: libraries/dif loading1880069
Ref: bfc1880069
Node: Testing<68>1880209
Ref: libraries/dif testing1880318
Ref: bfd1880318
Node: Usage<31>1880453
Ref: libraries/dif usage1880542
Ref: bfe1880542
Node: dimension_reduction_protocols1880823
Ref: libraries/dimension_reduction_protocols doc1880958
Ref: bff1880958
Ref: libraries/dimension_reduction_protocols dimension-reduction-protocols1880958
Ref: c001880958
Ref: libraries/dimension_reduction_protocols library-dimension-reduction-protocols1880958
Ref: c011880958
Node: API documentation<74>1883047
Ref: libraries/dimension_reduction_protocols api-documentation1883174
Ref: c021883174
Node: Loading<75>1883324
Ref: libraries/dimension_reduction_protocols loading1883474
Ref: c031883474
Node: Common options1883640
Ref: libraries/dimension_reduction_protocols common-options1883780
Ref: c041883780
Node: Testing<69>1884620
Ref: libraries/dimension_reduction_protocols testing1884765
Ref: c051884765
Node: Test datasets<4>1884925
Ref: libraries/dimension_reduction_protocols test-datasets1885047
Ref: c061885047
Node: eclat_pattern_miner1887172
Ref: libraries/eclat_pattern_miner doc1887308
Ref: c071887308
Ref: libraries/eclat_pattern_miner eclat-pattern-miner1887308
Ref: c081887308
Ref: libraries/eclat_pattern_miner library-eclat-pattern-miner1887308
Ref: c091887308
Node: API documentation<75>1888362
Ref: libraries/eclat_pattern_miner api-documentation1888479
Ref: c0a1888479
Node: Loading<76>1888619
Ref: libraries/eclat_pattern_miner loading1888756
Ref: c0b1888756
Node: Testing<70>1888896
Ref: libraries/eclat_pattern_miner testing1889024
Ref: c0c1889024
Node: Features<14>1889175
Ref: libraries/eclat_pattern_miner features1889303
Ref: c0d1889303
Node: Options<13>1890184
Ref: libraries/eclat_pattern_miner options1890332
Ref: c0e1890332
Node: Pattern miner representation<3>1890999
Ref: libraries/eclat_pattern_miner pattern-miner-representation1891149
Ref: c0f1891149
Node: References<10>1891722
Ref: libraries/eclat_pattern_miner references1891852
Ref: c101891852
Node: edcg1891966
Ref: libraries/edcg doc1892095
Ref: 3201892095
Ref: libraries/edcg edcg1892095
Ref: c111892095
Ref: libraries/edcg library-edcg1892095
Ref: c121892095
Node: API documentation<76>1893609
Ref: libraries/edcg api-documentation1893711
Ref: c131893711
Node: Loading<77>1893836
Ref: libraries/edcg loading1893958
Ref: c141893958
Node: Testing<71>1894107
Ref: libraries/edcg testing1894217
Ref: c151894217
Node: Usage<32>1894381
Ref: libraries/edcg usage1894492
Ref: c161894492
Node: Introduction1895231
Ref: libraries/edcg introduction1895337
Ref: c171895337
Node: Syntax1895969
Ref: libraries/edcg syntax1896091
Ref: c181896091
Node: Declaration of Predicates1897986
Ref: libraries/edcg declaration-of-predicates1898123
Ref: c191898123
Node: Declaration of Accumulators1898453
Ref: libraries/edcg declaration-of-accumulators1898615
Ref: c1a1898615
Node: Declaration of Passed Arguments1900001
Ref: libraries/edcg declaration-of-passed-arguments1900162
Ref: c1b1900162
Node: Additional documentation1900821
Ref: libraries/edcg additional-documentation1900946
Ref: c1c1900946
Ref: Additional documentation-Footnote-11901328
Ref: Additional documentation-Footnote-21901383
Ref: Additional documentation-Footnote-31901451
Ref: Additional documentation-Footnote-41901524
Node: elastic_net_regression1901597
Ref: libraries/elastic_net_regression doc1901717
Ref: c1d1901717
Ref: libraries/elastic_net_regression elastic-net-regression1901717
Ref: c1e1901717
Ref: libraries/elastic_net_regression library-elastic-net-regression1901717
Ref: c1f1901717
Node: API documentation<77>1902432
Ref: libraries/elastic_net_regression api-documentation1902552
Ref: c201902552
Node: Loading<78>1902695
Ref: libraries/elastic_net_regression loading1902835
Ref: c211902835
Node: Testing<72>1902978
Ref: libraries/elastic_net_regression testing1903109
Ref: c221903109
Node: Features<15>1903558
Ref: libraries/elastic_net_regression features1903705
Ref: c231903705
Node: Regressor representation<2>1905432
Ref: libraries/elastic_net_regression regressor-representation1905589
Ref: c241905589
Node: Diagnostics syntax<6>1905894
Ref: libraries/elastic_net_regression diagnostics-syntax1906050
Ref: c251906050
Node: Options<14>1907924
Ref: libraries/elastic_net_regression options1908044
Ref: c261908044
Node: elo_ranker1909394
Ref: libraries/elo_ranker doc1909516
Ref: c271909516
Ref: libraries/elo_ranker elo-ranker1909516
Ref: c281909516
Ref: libraries/elo_ranker library-elo-ranker1909516
Ref: c291909516
Node: API documentation<78>1910658
Ref: libraries/elo_ranker api-documentation1910766
Ref: c2a1910766
Node: Loading<79>1910897
Ref: libraries/elo_ranker loading1911025
Ref: c2b1911025
Node: Testing<73>1911156
Ref: libraries/elo_ranker testing1911275
Ref: c2c1911275
Node: Features<16>1911417
Ref: libraries/elo_ranker features1911541
Ref: c2d1911541
Node: Rating semantics1912916
Ref: libraries/elo_ranker rating-semantics1913038
Ref: c2e1913038
Node: Usage<33>1913916
Ref: libraries/elo_ranker usage1914037
Ref: c2f1914037
Node: Learning a ranker<5>1914274
Ref: libraries/elo_ranker learning-a-ranker1914394
Ref: c301914394
Node: Inspecting diagnostics<5>1914722
Ref: libraries/elo_ranker inspecting-diagnostics1914877
Ref: c311914877
Node: Ranking candidate items<5>1915142
Ref: libraries/elo_ranker ranking-candidate-items1915300
Ref: c321915300
Node: Exporting the ranker<5>1915823
Ref: libraries/elo_ranker exporting-the-ranker1915947
Ref: c331915947
Node: Options<15>1916474
Ref: libraries/elo_ranker options1916603
Ref: c341916603
Node: Ranker representation<5>1917054
Ref: libraries/elo_ranker ranker-representation1917188
Ref: c351917188
Node: References<11>1917569
Ref: libraries/elo_ranker references1917683
Ref: c361917683
Node: events1917805
Ref: libraries/events doc1917926
Ref: c371917926
Ref: libraries/events events1917926
Ref: c381917926
Ref: libraries/events library-events1917926
Ref: c391917926
Node: API documentation<79>1918581
Ref: libraries/events api-documentation1918685
Ref: c3a1918685
Node: Loading<80>1918812
Ref: libraries/events loading1918916
Ref: c3b1918916
Node: ewma_anomaly_detector1919066
Ref: libraries/ewma_anomaly_detector doc1919203
Ref: c3c1919203
Ref: libraries/ewma_anomaly_detector ewma-anomaly-detector1919203
Ref: c3d1919203
Ref: libraries/ewma_anomaly_detector library-ewma-anomaly-detector1919203
Ref: c3e1919203
Node: API documentation<80>1920583
Ref: libraries/ewma_anomaly_detector api-documentation1920702
Ref: c3f1920702
Node: Loading<81>1920844
Ref: libraries/ewma_anomaly_detector loading1920983
Ref: c401920983
Node: Testing<74>1921125
Ref: libraries/ewma_anomaly_detector testing1921255
Ref: c411921255
Node: Features<17>1921408
Ref: libraries/ewma_anomaly_detector features1921538
Ref: c421921538
Node: Options<16>1925128
Ref: libraries/ewma_anomaly_detector options1925273
Ref: c431925273
Node: Detector representation<2>1926084
Ref: libraries/ewma_anomaly_detector detector-representation1926225
Ref: c441926225
Node: Notes<4>1927294
Ref: libraries/ewma_anomaly_detector notes1927415
Ref: c451927415
Node: expand_library_alias_paths1929437
Ref: libraries/expand_library_alias_paths doc1929577
Ref: c461929577
Ref: libraries/expand_library_alias_paths expand-library-alias-paths1929577
Ref: c471929577
Ref: libraries/expand_library_alias_paths library-expand-library-alias-paths1929577
Ref: c481929577
Node: API documentation<81>1929986
Ref: libraries/expand_library_alias_paths api-documentation1930110
Ref: c491930110
Node: Loading<82>1930257
Ref: libraries/expand_library_alias_paths loading1930399
Ref: c4a1930399
Node: Usage<34>1930570
Ref: libraries/expand_library_alias_paths usage1930682
Ref: c4b1930682
Node: expecteds1931037
Ref: libraries/expecteds doc1931162
Ref: 24f1931162
Ref: libraries/expecteds expecteds1931162
Ref: c4c1931162
Ref: libraries/expecteds library-expecteds1931162
Ref: c4d1931162
Node: API documentation<82>1932003
Ref: libraries/expecteds api-documentation1932110
Ref: c4e1932110
Node: Loading<83>1932240
Ref: libraries/expecteds loading1932367
Ref: c4f1932367
Node: Testing<75>1932513
Ref: libraries/expecteds testing1932628
Ref: c501932628
Node: Usage<35>1932769
Ref: libraries/expecteds usage1932881
Ref: c511932881
Node: See also1938742
Ref: libraries/expecteds see-also1938834
Ref: c521938834
Node: format1938921
Ref: libraries/format doc1939043
Ref: c531939043
Ref: libraries/format format1939043
Ref: c541939043
Ref: libraries/format library-format1939043
Ref: c551939043
Node: API documentation<83>1940169
Ref: libraries/format api-documentation1940273
Ref: c561940273
Node: Loading<84>1940400
Ref: libraries/format loading1940524
Ref: c571940524
Node: Testing<76>1940667
Ref: libraries/format testing1940779
Ref: c581940779
Node: Usage<36>1941203
Ref: libraries/format usage1941318
Ref: c591941318
Node: Portability<2>1941611
Ref: libraries/format portability1941706
Ref: c5a1941706
Node: fp_growth_pattern_miner1942676
Ref: libraries/fp_growth_pattern_miner doc1942822
Ref: c5b1942822
Ref: libraries/fp_growth_pattern_miner fp-growth-pattern-miner1942822
Ref: c5c1942822
Ref: libraries/fp_growth_pattern_miner library-fp-growth-pattern-miner1942822
Ref: c5d1942822
Node: API documentation<84>1943819
Ref: libraries/fp_growth_pattern_miner api-documentation1943940
Ref: c5e1943940
Node: Loading<85>1944084
Ref: libraries/fp_growth_pattern_miner loading1944225
Ref: c5f1944225
Node: Testing<77>1944369
Ref: libraries/fp_growth_pattern_miner testing1944501
Ref: c601944501
Node: Features<18>1944656
Ref: libraries/fp_growth_pattern_miner features1944788
Ref: c611944788
Node: Options<17>1945668
Ref: libraries/fp_growth_pattern_miner options1945820
Ref: c621945820
Node: Pattern miner representation<4>1946487
Ref: libraries/fp_growth_pattern_miner pattern-miner-representation1946641
Ref: c631946641
Node: References<12>1947218
Ref: libraries/fp_growth_pattern_miner references1947352
Ref: c641947352
Node: frequent_pattern_mining_protocols1947500
Ref: libraries/frequent_pattern_mining_protocols doc1947666
Ref: c651947666
Ref: libraries/frequent_pattern_mining_protocols frequent-pattern-mining-protocols1947666
Ref: c661947666
Ref: libraries/frequent_pattern_mining_protocols library-frequent-pattern-mining-protocols1947666
Ref: c671947666
Node: API documentation<85>1948562
Ref: libraries/frequent_pattern_mining_protocols api-documentation1948693
Ref: c681948693
Node: Loading<86>1948847
Ref: libraries/frequent_pattern_mining_protocols loading1948998
Ref: c691948998
Node: Testing<78>1949168
Ref: libraries/frequent_pattern_mining_protocols testing1949314
Ref: c6a1949314
Node: Test datasets<5>1949478
Ref: libraries/frequent_pattern_mining_protocols test-datasets1949604
Ref: c6b1949604
Node: gaussian_mixture_clusterer1950879
Ref: libraries/gaussian_mixture_clusterer doc1951049
Ref: c6c1951049
Ref: libraries/gaussian_mixture_clusterer gaussian-mixture-clusterer1951049
Ref: c6d1951049
Ref: libraries/gaussian_mixture_clusterer library-gaussian-mixture-clusterer1951049
Ref: c6e1951049
Node: API documentation<86>1952041
Ref: libraries/gaussian_mixture_clusterer api-documentation1952165
Ref: c6f1952165
Node: Loading<87>1952312
Ref: libraries/gaussian_mixture_clusterer loading1952456
Ref: c701952456
Node: Testing<79>1952603
Ref: libraries/gaussian_mixture_clusterer testing1952738
Ref: c711952738
Node: Features<19>1953054
Ref: libraries/gaussian_mixture_clusterer features1953218
Ref: c721953218
Node: Gaussian-Mixture-Specific Prediction API1954504
Ref: libraries/gaussian_mixture_clusterer gaussian-mixture-specific-prediction-api1954668
Ref: c731954668
Node: Options<18>1955118
Ref: libraries/gaussian_mixture_clusterer options1955297
Ref: c741955297
Node: Clusterer representation<3>1956487
Ref: libraries/gaussian_mixture_clusterer clusterer-representation1956617
Ref: c751956617
Node: gaussian_process_regression1957423
Ref: libraries/gaussian_process_regression doc1957566
Ref: c761957566
Ref: libraries/gaussian_process_regression gaussian-process-regression1957566
Ref: c771957566
Ref: libraries/gaussian_process_regression library-gaussian-process-regression1957566
Ref: c781957566
Node: API documentation<87>1958821
Ref: libraries/gaussian_process_regression api-documentation1958946
Ref: c791958946
Node: Loading<88>1959094
Ref: libraries/gaussian_process_regression loading1959239
Ref: c7a1959239
Node: Testing<80>1959387
Ref: libraries/gaussian_process_regression testing1959523
Ref: c7b1959523
Node: Features<20>1959841
Ref: libraries/gaussian_process_regression features1959993
Ref: c7c1959993
Node: Regressor representation<3>1962277
Ref: libraries/gaussian_process_regression regressor-representation1962432
Ref: c7d1962432
Node: Prediction API1963435
Ref: libraries/gaussian_process_regression prediction-api1963599
Ref: c7e1963599
Node: Diagnostics syntax<7>1964087
Ref: libraries/gaussian_process_regression diagnostics-syntax1964235
Ref: c7f1964235
Node: Options<19>1967541
Ref: libraries/gaussian_process_regression options1967666
Ref: c801967666
Node: genint1971165
Ref: libraries/genint doc1971288
Ref: c811971288
Ref: libraries/genint genint1971288
Ref: c821971288
Ref: libraries/genint library-genint1971288
Ref: c831971288
Node: API documentation<88>1971688
Ref: libraries/genint api-documentation1971792
Ref: c841971792
Node: Loading<89>1971919
Ref: libraries/genint loading1972043
Ref: c851972043
Node: Testing<81>1972186
Ref: libraries/genint testing1972298
Ref: c861972298
Node: Usage<37>1972436
Ref: libraries/genint usage1972528
Ref: c871972528
Node: gensym1972963
Ref: libraries/gensym doc1973066
Ref: c881973066
Ref: libraries/gensym gensym1973066
Ref: c891973066
Ref: libraries/gensym library-gensym1973066
Ref: c8a1973066
Node: API documentation<89>1973440
Ref: libraries/gensym api-documentation1973544
Ref: c8b1973544
Node: Loading<90>1973671
Ref: libraries/gensym loading1973795
Ref: c8c1973795
Node: Testing<82>1973938
Ref: libraries/gensym testing1974050
Ref: c8d1974050
Node: Usage<38>1974188
Ref: libraries/gensym usage1974280
Ref: c8e1974280
Node: geojson1974875
Ref: libraries/geojson doc1974982
Ref: c8f1974982
Ref: libraries/geojson geojson1974982
Ref: c901974982
Ref: libraries/geojson library-geojson1974982
Ref: c911974982
Node: API documentation<90>1975598
Ref: libraries/geojson api-documentation1975703
Ref: c921975703
Node: Loading<91>1975831
Ref: libraries/geojson loading1975956
Ref: c931975956
Node: Testing<83>1976100
Ref: libraries/geojson testing1976222
Ref: c941976222
Node: Representation<10>1976361
Ref: libraries/geojson representation1976485
Ref: c951976485
Node: Examples<169>1978038
Ref: libraries/geojson examples1978159
Ref: c961978159
Node: Notes<5>1979229
Ref: libraries/geojson notes1979323
Ref: c971979323
Node: geospatial1981090
Ref: libraries/geospatial doc1981194
Ref: c981981194
Ref: libraries/geospatial geospatial1981194
Ref: c991981194
Ref: libraries/geospatial library-geospatial1981194
Ref: c9a1981194
Node: API documentation<91>1981647
Ref: libraries/geospatial api-documentation1981755
Ref: c9b1981755
Node: Loading<92>1981886
Ref: libraries/geospatial loading1982014
Ref: c9c1982014
Node: Testing<84>1982161
Ref: libraries/geospatial testing1982288
Ref: c9d1982288
Node: Available predicates1982430
Ref: libraries/geospatial available-predicates1982554
Ref: c9e1982554
Node: Notes<6>1984287
Ref: libraries/geospatial notes1984409
Ref: c9f1984409
Node: Usage<39>1984651
Ref: libraries/geospatial usage1984744
Ref: ca01984744
Node: git1992807
Ref: libraries/git doc1992918
Ref: ca11992918
Ref: libraries/git git1992918
Ref: ca21992918
Ref: libraries/git library-git1992918
Ref: ca31992918
Node: API documentation<92>1993312
Ref: libraries/git api-documentation1993413
Ref: ca41993413
Node: Loading<93>1993537
Ref: libraries/git loading1993658
Ref: ca51993658
Node: Testing<85>1993798
Ref: libraries/git testing1993907
Ref: ca61993907
Node: Usage<40>1994042
Ref: libraries/git usage1994131
Ref: ca71994131
Node: glicko2_ranker1995491
Ref: libraries/glicko2_ranker doc1995615
Ref: ca81995615
Ref: libraries/glicko2_ranker glicko2-ranker1995615
Ref: ca91995615
Ref: libraries/glicko2_ranker library-glicko2-ranker1995615
Ref: caa1995615
Node: API documentation<93>1996851
Ref: libraries/glicko2_ranker api-documentation1996963
Ref: cab1996963
Node: Loading<94>1997098
Ref: libraries/glicko2_ranker loading1997230
Ref: cac1997230
Node: Testing<86>1997365
Ref: libraries/glicko2_ranker testing1997488
Ref: cad1997488
Node: Features<21>1997634
Ref: libraries/glicko2_ranker features1997765
Ref: cae1997765
Node: Rating semantics<2>1999150
Ref: libraries/glicko2_ranker rating-semantics1999279
Ref: caf1999279
Node: Usage<41>2000137
Ref: libraries/glicko2_ranker usage2000265
Ref: cb02000265
Node: Learning a ranker<6>2000502
Ref: libraries/glicko2_ranker learning-a-ranker2000622
Ref: cb12000622
Node: Inspecting diagnostics<6>2000988
Ref: libraries/glicko2_ranker inspecting-diagnostics2001143
Ref: cb22001143
Node: Ranking candidate items<6>2001434
Ref: libraries/glicko2_ranker ranking-candidate-items2001592
Ref: cb32001592
Node: Exporting the ranker<6>2002123
Ref: libraries/glicko2_ranker exporting-the-ranker2002247
Ref: cb42002247
Node: Options<20>2002794
Ref: libraries/glicko2_ranker options2002924
Ref: cb52002924
Node: Diagnostics syntax<8>2003623
Ref: libraries/glicko2_ranker diagnostics-syntax2003768
Ref: cb62003768
Node: Ranker representation<6>2004096
Ref: libraries/glicko2_ranker ranker-representation2004244
Ref: cb72004244
Node: References<13>2004687
Ref: libraries/glicko2_ranker references2004805
Ref: cb82004805
Node: glicko2_periodic_ranker2004909
Ref: libraries/glicko2_periodic_ranker doc2005058
Ref: cb92005058
Ref: libraries/glicko2_periodic_ranker glicko2-periodic-ranker2005058
Ref: cba2005058
Ref: libraries/glicko2_periodic_ranker library-glicko2-periodic-ranker2005058
Ref: cbb2005058
Node: API documentation<94>2006848
Ref: libraries/glicko2_periodic_ranker api-documentation2006969
Ref: cbc2006969
Node: Loading<95>2007113
Ref: libraries/glicko2_periodic_ranker loading2007254
Ref: cbd2007254
Node: Testing<87>2007398
Ref: libraries/glicko2_periodic_ranker testing2007530
Ref: cbe2007530
Node: Features<22>2007685
Ref: libraries/glicko2_periodic_ranker features2007825
Ref: cbf2007825
Node: Rating semantics<3>2009619
Ref: libraries/glicko2_periodic_ranker rating-semantics2009757
Ref: cc02009757
Node: Usage<42>2010682
Ref: libraries/glicko2_periodic_ranker usage2010819
Ref: cc12010819
Node: Learning a ranker<7>2011056
Ref: libraries/glicko2_periodic_ranker learning-a-ranker2011176
Ref: cc22011176
Node: Inspecting diagnostics<7>2011569
Ref: libraries/glicko2_periodic_ranker inspecting-diagnostics2011724
Ref: cc32011724
Node: Ranking candidate items<7>2012032
Ref: libraries/glicko2_periodic_ranker ranking-candidate-items2012190
Ref: cc42012190
Node: Exporting the ranker<7>2012739
Ref: libraries/glicko2_periodic_ranker exporting-the-ranker2012863
Ref: cc52012863
Node: Options<21>2013455
Ref: libraries/glicko2_periodic_ranker options2013594
Ref: cc62013594
Node: Diagnostics syntax<9>2014361
Ref: libraries/glicko2_periodic_ranker diagnostics-syntax2014515
Ref: cc72014515
Node: Ranker representation<7>2014934
Ref: libraries/glicko2_periodic_ranker ranker-representation2015091
Ref: cc82015091
Node: References<14>2015581
Ref: libraries/glicko2_periodic_ranker references2015708
Ref: cc92015708
Node: gradient_boosting_classifier2015812
Ref: libraries/gradient_boosting_classifier doc2015975
Ref: cca2015975
Ref: libraries/gradient_boosting_classifier gradient-boosting-classifier2015975
Ref: ccb2015975
Ref: libraries/gradient_boosting_classifier library-gradient-boosting-classifier2015975
Ref: ccc2015975
Node: API documentation<95>2017146
Ref: libraries/gradient_boosting_classifier api-documentation2017272
Ref: ccd2017272
Node: Loading<96>2017421
Ref: libraries/gradient_boosting_classifier loading2017567
Ref: cce2017567
Node: Testing<88>2017716
Ref: libraries/gradient_boosting_classifier testing2017853
Ref: ccf2017853
Node: Features<23>2018013
Ref: libraries/gradient_boosting_classifier features2018150
Ref: cd02018150
Node: Options<22>2018887
Ref: libraries/gradient_boosting_classifier options2019022
Ref: cd12019022
Node: Usage<43>2019742
Ref: libraries/gradient_boosting_classifier usage2019893
Ref: cd22019893
Node: Learning a classifier2020008
Ref: libraries/gradient_boosting_classifier learning-a-classifier2020122
Ref: cd32020122
Node: Making predictions2020375
Ref: libraries/gradient_boosting_classifier making-predictions2020522
Ref: cd42020522
Node: Exporting the classifier2020996
Ref: libraries/gradient_boosting_classifier exporting-the-classifier2021113
Ref: cd52021113
Node: Classifier representation<2>2021523
Ref: libraries/gradient_boosting_classifier classifier-representation2021677
Ref: cd62021677
Node: References<15>2022502
Ref: libraries/gradient_boosting_classifier references2022638
Ref: cd72022638
Node: gradient_boosting_regression2022992
Ref: libraries/gradient_boosting_regression doc2023140
Ref: cd82023140
Ref: libraries/gradient_boosting_regression gradient-boosting-regression2023140
Ref: cd92023140
Ref: libraries/gradient_boosting_regression library-gradient-boosting-regression2023140
Ref: cda2023140
Node: API documentation<96>2024016
Ref: libraries/gradient_boosting_regression api-documentation2024142
Ref: cdb2024142
Node: Loading<97>2024291
Ref: libraries/gradient_boosting_regression loading2024437
Ref: cdc2024437
Node: Testing<89>2024586
Ref: libraries/gradient_boosting_regression testing2024723
Ref: cdd2024723
Node: Features<24>2025043
Ref: libraries/gradient_boosting_regression features2025196
Ref: cde2025196
Node: Regressor representation<4>2026263
Ref: libraries/gradient_boosting_regression regressor-representation2026427
Ref: cdf2026427
Node: Diagnostics syntax<10>2026941
Ref: libraries/gradient_boosting_regression diagnostics-syntax2027104
Ref: ce02027104
Node: Options<23>2028387
Ref: libraries/gradient_boosting_regression options2028514
Ref: ce12028514
Node: grammars2030073
Ref: libraries/grammars doc2030199
Ref: ce22030199
Ref: libraries/grammars grammars2030199
Ref: ce32030199
Ref: libraries/grammars library-grammars2030199
Ref: ce42030199
Node: API documentation<97>2030830
Ref: libraries/grammars api-documentation2030936
Ref: ce52030936
Node: Loading<98>2031065
Ref: libraries/grammars loading2031191
Ref: ce62031191
Node: Testing<90>2031336
Ref: libraries/grammars testing2031450
Ref: ce72031450
Node: Usage<44>2031616
Ref: libraries/grammars usage2031710
Ref: ce82031710
Node: graphs2032048
Ref: libraries/graphs doc2032154
Ref: ce92032154
Ref: libraries/graphs graphs2032154
Ref: cea2032154
Ref: libraries/graphs library-graphs2032154
Ref: ceb2032154
Node: API documentation<98>2033444
Ref: libraries/graphs api-documentation2033548
Ref: cec2033548
Node: Loading<99>2033675
Ref: libraries/graphs loading2033799
Ref: ced2033799
Node: Testing<91>2033942
Ref: libraries/graphs testing2034054
Ref: cee2034054
Node: Usage<45>2034316
Ref: libraries/graphs usage2034408
Ref: cef2034408
Node: Graph types2034523
Ref: libraries/graphs graph-types2034624
Ref: cf02034624
Node: Creating graphs2034984
Ref: libraries/graphs creating-graphs2035109
Ref: cf12035109
Node: Querying graphs2035622
Ref: libraries/graphs querying-graphs2035753
Ref: cf22035753
Node: Undirected graphs2036093
Ref: libraries/graphs undirected-graphs2036200
Ref: cf32036200
Node: gravatar2036473
Ref: libraries/gravatar doc2036588
Ref: cf42036588
Ref: libraries/gravatar gravatar2036588
Ref: cf52036588
Ref: libraries/gravatar library-gravatar2036588
Ref: cf62036588
Node: API documentation<99>2037269
Ref: libraries/gravatar api-documentation2037376
Ref: cf72037376
Node: Loading<100>2037505
Ref: libraries/gravatar loading2037632
Ref: cf82037632
Node: Testing<92>2037760
Ref: libraries/gravatar testing2037880
Ref: cf92037880
Node: Basic usage<2>2038384
Ref: libraries/gravatar basic-usage2038483
Ref: cfa2038483
Node: gsp_pattern_miner2039646
Ref: libraries/gsp_pattern_miner doc2039761
Ref: cfb2039761
Ref: libraries/gsp_pattern_miner gsp-pattern-miner2039761
Ref: cfc2039761
Ref: libraries/gsp_pattern_miner library-gsp-pattern-miner2039761
Ref: cfd2039761
Node: API documentation<100>2040713
Ref: libraries/gsp_pattern_miner api-documentation2040830
Ref: cfe2040830
Node: Loading<101>2040968
Ref: libraries/gsp_pattern_miner loading2041105
Ref: cff2041105
Node: Testing<93>2041243
Ref: libraries/gsp_pattern_miner testing2041370
Ref: d002041370
Node: Features<25>2041519
Ref: libraries/gsp_pattern_miner features2041645
Ref: d012041645
Node: Options<24>2042538
Ref: libraries/gsp_pattern_miner options2042684
Ref: d022042684
Node: Pattern miner representation<5>2043375
Ref: libraries/gsp_pattern_miner pattern-miner-representation2043523
Ref: d032043523
Node: References<16>2044118
Ref: libraries/gsp_pattern_miner references2044246
Ref: d042044246
Node: hashes2044411
Ref: libraries/hashes doc2044535
Ref: d052044535
Ref: libraries/hashes hashes2044535
Ref: d062044535
Ref: libraries/hashes library-hashes2044535
Ref: d072044535
Node: API documentation<101>2045068
Ref: libraries/hashes api-documentation2045174
Ref: d082045174
Node: Loading<102>2045301
Ref: libraries/hashes loading2045427
Ref: d092045427
Node: Testing<94>2045570
Ref: libraries/hashes testing2045699
Ref: d0a2045699
Node: Supported hash algorithms2045837
Ref: libraries/hashes supported-hash-algorithms2045972
Ref: d0b2045972
Node: HMAC compatibility2050890
Ref: libraries/hashes hmac-compatibility2051031
Ref: d0c2051031
Node: Segmented hashing2051612
Ref: libraries/hashes segmented-hashing2051741
Ref: d0d2051741
Node: Examples<170>2053018
Ref: libraries/hashes examples2053120
Ref: d0e2053120
Node: hdbscan_clusterer2055586
Ref: libraries/hdbscan_clusterer doc2055698
Ref: d0f2055698
Ref: libraries/hdbscan_clusterer hdbscan-clusterer2055698
Ref: d102055698
Ref: libraries/hdbscan_clusterer library-hdbscan-clusterer2055698
Ref: d112055698
Node: API documentation<102>2056702
Ref: libraries/hdbscan_clusterer api-documentation2056819
Ref: d122056819
Node: Loading<103>2056957
Ref: libraries/hdbscan_clusterer loading2057094
Ref: d132057094
Node: Testing<95>2057232
Ref: libraries/hdbscan_clusterer testing2057359
Ref: d142057359
Node: Features<26>2057657
Ref: libraries/hdbscan_clusterer features2057783
Ref: d152057783
Node: Options<25>2058907
Ref: libraries/hdbscan_clusterer options2059049
Ref: d162059049
Node: Clusterer representation<4>2059855
Ref: libraries/hdbscan_clusterer clusterer-representation2059976
Ref: d172059976
Node: heaps2060639
Ref: libraries/heaps doc2060768
Ref: d182060768
Ref: libraries/heaps heaps2060768
Ref: d192060768
Ref: libraries/heaps library-heaps2060768
Ref: d1a2060768
Node: API documentation<103>2061564
Ref: libraries/heaps api-documentation2061669
Ref: d1b2061669
Node: Loading<104>2061795
Ref: libraries/heaps loading2061920
Ref: d1c2061920
Node: Testing<96>2062062
Ref: libraries/heaps testing2062174
Ref: d1d2062174
Node: Usage<46>2062311
Ref: libraries/heaps usage2062421
Ref: d1e2062421
Node: Credits<3>2063351
Ref: libraries/heaps credits2063441
Ref: d1f2063441
Node: hierarchical_clustering2063581
Ref: libraries/hierarchical_clustering doc2063704
Ref: d202063704
Ref: libraries/hierarchical_clustering hierarchical-clustering2063704
Ref: d212063704
Ref: libraries/hierarchical_clustering library-hierarchical-clustering2063704
Ref: d222063704
Node: API documentation<104>2064739
Ref: libraries/hierarchical_clustering api-documentation2064862
Ref: d232064862
Node: Loading<105>2065006
Ref: libraries/hierarchical_clustering loading2065149
Ref: d242065149
Node: Testing<97>2065293
Ref: libraries/hierarchical_clustering testing2065426
Ref: d252065426
Node: Features<27>2065736
Ref: libraries/hierarchical_clustering features2065868
Ref: d262065868
Node: Options<26>2067761
Ref: libraries/hierarchical_clustering options2067909
Ref: d272067909
Node: Clusterer representation<5>2068531
Ref: libraries/hierarchical_clustering clusterer-representation2068681
Ref: d282068681
Node: Additional API2069772
Ref: libraries/hierarchical_clustering additional-api2069925
Ref: d292069925
Node: Diagnostics<3>2070110
Ref: libraries/hierarchical_clustering diagnostics2070227
Ref: d2a2070227
Node: hierarchies2070739
Ref: libraries/hierarchies doc2070861
Ref: d2b2070861
Ref: libraries/hierarchies hierarchies2070861
Ref: d2c2070861
Ref: libraries/hierarchies library-hierarchies2070861
Ref: d2d2070861
Node: API documentation<105>2071206
Ref: libraries/hierarchies api-documentation2071317
Ref: d2e2071317
Node: Loading<106>2071449
Ref: libraries/hierarchies loading2071580
Ref: d2f2071580
Node: Testing<98>2071728
Ref: libraries/hierarchies testing2071828
Ref: d302071828
Node: hmac2071971
Ref: libraries/hmac doc2072080
Ref: d312072080
Ref: libraries/hmac hmac2072080
Ref: d322072080
Ref: libraries/hmac library-hmac2072080
Ref: d332072080
Node: API documentation<106>2073397
Ref: libraries/hmac api-documentation2073501
Ref: d342073501
Node: Loading<107>2073626
Ref: libraries/hmac loading2073750
Ref: d352073750
Node: Testing<99>2073891
Ref: libraries/hmac testing2074006
Ref: d362074006
Node: Examples<171>2074142
Ref: libraries/hmac examples2074236
Ref: d372074236
Node: hodge_rank2075174
Ref: libraries/hodge_rank doc2075282
Ref: d382075282
Ref: libraries/hodge_rank hodge-rank2075282
Ref: d392075282
Ref: libraries/hodge_rank library-hodge-rank2075282
Ref: d3a2075282
Node: API documentation<107>2076674
Ref: libraries/hodge_rank api-documentation2076784
Ref: d3b2076784
Node: Loading<108>2076915
Ref: libraries/hodge_rank loading2077046
Ref: d3c2077046
Node: Testing<100>2077177
Ref: libraries/hodge_rank testing2077298
Ref: d3d2077298
Node: Features<28>2077440
Ref: libraries/hodge_rank features2077569
Ref: d3e2077569
Node: Scoring semantics<4>2078600
Ref: libraries/hodge_rank scoring-semantics2078735
Ref: d3f2078735
Node: Residual semantics2079700
Ref: libraries/hodge_rank residual-semantics2079832
Ref: d402079832
Node: Usage<47>2080092
Ref: libraries/hodge_rank usage2080226
Ref: d412080226
Node: Learning a ranker<8>2080331
Ref: libraries/hodge_rank learning-a-ranker2080446
Ref: d422080446
Node: Inspecting residuals2080842
Ref: libraries/hodge_rank inspecting-residuals2080957
Ref: d432080957
Node: Diagnostics syntax<11>2081212
Ref: libraries/hodge_rank diagnostics-syntax2081352
Ref: d442081352
Node: Ranker representation<8>2081668
Ref: libraries/hodge_rank ranker-representation2081813
Ref: d452081813
Node: References<17>2082226
Ref: libraries/hodge_rank references2082340
Ref: d462082340
Node: hook_flows2082494
Ref: libraries/hook_flows doc2082610
Ref: 31b2082610
Ref: libraries/hook_flows hook-flows2082610
Ref: d472082610
Ref: libraries/hook_flows library-hook-flows2082610
Ref: d482082610
Node: API documentation<108>2083506
Ref: libraries/hook_flows api-documentation2083616
Ref: d492083616
Node: Loading<109>2083747
Ref: libraries/hook_flows loading2083878
Ref: d4a2083878
Node: Testing<101>2084025
Ref: libraries/hook_flows testing2084143
Ref: d4b2084143
Node: Usage<48>2084285
Ref: libraries/hook_flows usage2084382
Ref: d4c2084382
Node: hook_objects2086163
Ref: libraries/hook_objects doc2086273
Ref: 31c2086273
Ref: libraries/hook_objects hook-objects2086273
Ref: d4d2086273
Ref: libraries/hook_objects library-hook-objects2086273
Ref: d4e2086273
Node: API documentation<109>2086782
Ref: libraries/hook_objects api-documentation2086894
Ref: d4f2086894
Node: Loading<110>2087027
Ref: libraries/hook_objects loading2087160
Ref: d502087160
Node: Testing<102>2087452
Ref: libraries/hook_objects testing2087572
Ref: d512087572
Node: Usage<49>2087718
Ref: libraries/hook_objects usage2087817
Ref: d522087817
Node: Using the Prolog backend adapter file expansion rules2088498
Ref: libraries/hook_objects using-the-prolog-backend-adapter-file-expansion-rules2088675
Ref: d532088675
Node: Restoring the default compiler expansion workflow2089023
Ref: libraries/hook_objects restoring-the-default-compiler-expansion-workflow2089267
Ref: d542089267
Node: Preventing applying any other user-defined expansion rules2089624
Ref: libraries/hook_objects preventing-applying-any-other-user-defined-expansion-rules2089881
Ref: d552089881
Node: Expanding grammar rules into clauses independently of the compiler2090780
Ref: libraries/hook_objects expanding-grammar-rules-into-clauses-independently-of-the-compiler2091040
Ref: d562091040
Node: Using the expansion rules defined in a Prolog module2091438
Ref: libraries/hook_objects using-the-expansion-rules-defined-in-a-prolog-module2091693
Ref: d572091693
Node: Wrap the contents of a plain Prolog file as an object2092097
Ref: libraries/hook_objects wrap-the-contents-of-a-plain-prolog-file-as-an-object2092341
Ref: d582092341
Node: Outputting term-expansion results to a stream or a file2093826
Ref: libraries/hook_objects outputting-term-expansion-results-to-a-stream-or-a-file2094078
Ref: d592094078
Node: Printing entity predicate goals before or after calling them2095204
Ref: libraries/hook_objects printing-entity-predicate-goals-before-or-after-calling-them2095420
Ref: d5a2095420
Node: Suppressing goals2096031
Ref: libraries/hook_objects suppressing-goals2096183
Ref: d5b2096183
Node: html2096872
Ref: libraries/html doc2096989
Ref: d5c2096989
Ref: libraries/html html2096989
Ref: d5d2096989
Ref: libraries/html library-html2096989
Ref: d5e2096989
Node: API documentation<110>2098687
Ref: libraries/html api-documentation2098791
Ref: d5f2098791
Node: Loading<111>2098916
Ref: libraries/html loading2099041
Ref: d602099041
Node: Testing<103>2099182
Ref: libraries/html testing2099311
Ref: d612099311
Node: Generating a HTML document2099447
Ref: libraries/html generating-a-html-document2099590
Ref: d622099590
Node: Generating a HTML fragment2100325
Ref: libraries/html generating-a-html-fragment2100498
Ref: d632100498
Node: Working with callbacks to generate content2100968
Ref: libraries/html working-with-callbacks-to-generate-content2101149
Ref: d642101149
Node: Working with resource declarations2102125
Ref: libraries/html working-with-resource-declarations2102314
Ref: d652102314
Node: Aggregating and ordering resources2103870
Ref: libraries/html aggregating-and-ordering-resources2104045
Ref: d662104045
Node: Working with custom elements2104895
Ref: libraries/html working-with-custom-elements2105027
Ref: d672105027
Node: http_authenticate2105639
Ref: libraries/http_authenticate doc2105755
Ref: d682105755
Ref: libraries/http_authenticate http-authenticate2105755
Ref: d692105755
Ref: libraries/http_authenticate library-http-authenticate2105755
Ref: d6a2105755
Node: API documentation<111>2106829
Ref: libraries/http_authenticate api-documentation2106946
Ref: d6b2106946
Node: Loading<112>2107084
Ref: libraries/http_authenticate loading2107222
Ref: d6c2107222
Node: Testing<104>2107359
Ref: libraries/http_authenticate testing2107489
Ref: d6d2107489
Node: Usage overview2107627
Ref: libraries/http_authenticate usage-overview2107758
Ref: d6e2107758
Node: Current scope2108591
Ref: libraries/http_authenticate current-scope2108727
Ref: d6f2108727
Node: Option validation2109514
Ref: libraries/http_authenticate option-validation2109660
Ref: d702109660
Node: Non-implemented features2110370
Ref: libraries/http_authenticate non-implemented-features2110494
Ref: d712110494
Node: http_client2110779
Ref: libraries/http_client doc2110907
Ref: d722110907
Ref: libraries/http_client http-client2110907
Ref: d732110907
Ref: libraries/http_client library-http-client2110907
Ref: d742110907
Node: API documentation<112>2112609
Ref: libraries/http_client api-documentation2112720
Ref: d752112720
Node: Loading<113>2112852
Ref: libraries/http_client loading2112984
Ref: d762112984
Node: Testing<105>2113115
Ref: libraries/http_client testing2113239
Ref: d772113239
Node: Usage examples2113371
Ref: libraries/http_client usage-examples2113499
Ref: d782113499
Node: Current scope<2>2118037
Ref: libraries/http_client current-scope2118171
Ref: d792118171
Node: Multipart workflow2121448
Ref: libraries/http_client multipart-workflow2121586
Ref: d7a2121586
Node: WebSocket workflow2123112
Ref: libraries/http_client websocket-workflow2123256
Ref: d7b2123256
Node: Current limitations<2>2125043
Ref: libraries/http_client current-limitations2125160
Ref: d7c2125160
Node: http_client_core2125417
Ref: libraries/http_client_core doc2125540
Ref: d7d2125540
Ref: libraries/http_client_core http-client-core2125540
Ref: d7e2125540
Ref: libraries/http_client_core library-http-client-core2125540
Ref: d7f2125540
Node: API documentation<113>2126138
Ref: libraries/http_client_core api-documentation2126254
Ref: d802126254
Node: Loading<114>2126391
Ref: libraries/http_client_core loading2126528
Ref: d812126528
Node: Testing<106>2126664
Ref: libraries/http_client_core testing2126795
Ref: d822126795
Node: Current scope<3>2126932
Ref: libraries/http_client_core current-scope2127064
Ref: d832127064
Node: Framing rules2127301
Ref: libraries/http_client_core framing-rules2127443
Ref: d842127443
Node: Current limitations<3>2128532
Ref: libraries/http_client_core current-limitations2128649
Ref: d852128649
Node: http_cookies2129082
Ref: libraries/http_cookies doc2129203
Ref: d862129203
Ref: libraries/http_cookies http-cookies2129203
Ref: d872129203
Ref: libraries/http_cookies library-http-cookies2129203
Ref: d882129203
Node: API documentation<114>2129598
Ref: libraries/http_cookies api-documentation2129710
Ref: d892129710
Node: Loading<115>2129843
Ref: libraries/http_cookies loading2129976
Ref: d8a2129976
Node: Testing<107>2130125
Ref: libraries/http_cookies testing2130245
Ref: d8b2130245
Node: Usage<50>2130389
Ref: libraries/http_cookies usage2130488
Ref: d8c2130488
Node: http_core2132347
Ref: libraries/http_core doc2132461
Ref: d8d2132461
Ref: libraries/http_core http-core2132461
Ref: d8e2132461
Ref: libraries/http_core library-http-core2132461
Ref: d8f2132461
Node: API documentation<115>2133020
Ref: libraries/http_core api-documentation2133129
Ref: d902133129
Node: Loading<116>2133259
Ref: libraries/http_core loading2133389
Ref: d912133389
Node: Testing<108>2133535
Ref: libraries/http_core testing2133651
Ref: d922133651
Node: Layering2133792
Ref: libraries/http_core layering2133912
Ref: d932133912
Ref: Layering-Footnote-12134761
Ref: Layering-Footnote-22134798
Ref: Layering-Footnote-32134830
Ref: Layering-Footnote-42134862
Ref: Layering-Footnote-52134887
Node: Current scope<4>2134916
Ref: libraries/http_core current-scope2135040
Ref: d942135040
Node: Normalized terms2137906
Ref: libraries/http_core normalized-terms2138044
Ref: d952138044
Node: Current limitations<4>2139575
Ref: libraries/http_core current-limitations2139688
Ref: d962139688
Node: http_cors2141071
Ref: libraries/http_cors doc2141184
Ref: d972141184
Ref: libraries/http_cors http-cors2141184
Ref: d982141184
Ref: libraries/http_cors library-http-cors2141184
Ref: d992141184
Node: API documentation<116>2142042
Ref: libraries/http_cors api-documentation2142151
Ref: d9a2142151
Node: Loading<117>2142281
Ref: libraries/http_cors loading2142411
Ref: d9b2142411
Node: Testing<109>2142540
Ref: libraries/http_cors testing2142664
Ref: d9c2142664
Node: Current scope<5>2142794
Ref: libraries/http_cors current-scope2142927
Ref: d9d2142927
Node: Route-level overrides2146474
Ref: libraries/http_cors route-level-overrides2146613
Ref: d9e2146613
Node: Router integration2147126
Ref: libraries/http_cors router-integration2147274
Ref: d9f2147274
Node: Plain handler integration2148726
Ref: libraries/http_cors plain-handler-integration2148875
Ref: da02148875
Node: Current limitations<5>2149519
Ref: libraries/http_cors current-limitations2149641
Ref: da12149641
Node: http_digest2149794
Ref: libraries/http_digest doc2149920
Ref: da22149920
Ref: libraries/http_digest http-digest2149920
Ref: da32149920
Ref: libraries/http_digest library-http-digest2149920
Ref: da42149920
Node: API documentation<117>2150479
Ref: libraries/http_digest api-documentation2150590
Ref: da52150590
Node: Loading<118>2150722
Ref: libraries/http_digest loading2150854
Ref: da62150854
Node: Testing<110>2150985
Ref: libraries/http_digest testing2151112
Ref: da72151112
Node: Usage overview<2>2151244
Ref: libraries/http_digest usage-overview2151375
Ref: da82151375
Node: Current scope<6>2154814
Ref: libraries/http_digest current-scope2154960
Ref: da92154960
Node: Non-implemented features<2>2156102
Ref: libraries/http_digest non-implemented-features2156222
Ref: daa2156222
Node: http_directory_listing2156396
Ref: libraries/http_directory_listing doc2156522
Ref: dab2156522
Ref: libraries/http_directory_listing http-directory-listing2156522
Ref: dac2156522
Ref: libraries/http_directory_listing library-http-directory-listing2156522
Ref: dad2156522
Node: API documentation<118>2157257
Ref: libraries/http_directory_listing api-documentation2157379
Ref: dae2157379
Node: Loading<119>2157522
Ref: libraries/http_directory_listing loading2157665
Ref: daf2157665
Node: Testing<111>2157807
Ref: libraries/http_directory_listing testing2157944
Ref: db02157944
Node: Current scope<7>2158087
Ref: libraries/http_directory_listing current-scope2158203
Ref: db12158203
Node: http_htmx2163411
Ref: libraries/http_htmx doc2163540
Ref: db22163540
Ref: libraries/http_htmx http-htmx2163540
Ref: db32163540
Ref: libraries/http_htmx library-http-htmx2163540
Ref: db42163540
Node: API documentation<119>2164444
Ref: libraries/http_htmx api-documentation2164553
Ref: db52164553
Node: Loading<120>2164685
Ref: libraries/http_htmx loading2164815
Ref: db62164815
Node: Testing<112>2164946
Ref: libraries/http_htmx testing2165070
Ref: db72165070
Node: Current scope<8>2165202
Ref: libraries/http_htmx current-scope2165305
Ref: db82165305
Node: http_multipart2169785
Ref: libraries/http_multipart doc2169907
Ref: db92169907
Ref: libraries/http_multipart http-multipart2169907
Ref: dba2169907
Ref: libraries/http_multipart library-http-multipart2169907
Ref: dbb2169907
Node: API documentation<120>2170618
Ref: libraries/http_multipart api-documentation2170732
Ref: dbc2170732
Node: Loading<121>2170869
Ref: libraries/http_multipart loading2171004
Ref: dbd2171004
Node: Testing<113>2171140
Ref: libraries/http_multipart testing2171269
Ref: dbe2171269
Node: Current scope<9>2171406
Ref: libraries/http_multipart current-scope2171544
Ref: dbf2171544
Node: Form-data descriptors2172760
Ref: libraries/http_multipart form-data-descriptors2172905
Ref: dc02172905
Node: Normalized terms<2>2173656
Ref: libraries/http_multipart normalized-terms2173801
Ref: dc12173801
Node: Current workflow2174049
Ref: libraries/http_multipart current-workflow2174195
Ref: dc22174195
Node: Current limitations<6>2174860
Ref: libraries/http_multipart current-limitations2174978
Ref: dc32174978
Node: http_parameters2175602
Ref: libraries/http_parameters doc2175726
Ref: dc42175726
Ref: libraries/http_parameters http-parameters2175726
Ref: dc52175726
Ref: libraries/http_parameters library-http-parameters2175726
Ref: dc62175726
Node: API documentation<121>2176361
Ref: libraries/http_parameters api-documentation2176476
Ref: dc72176476
Node: Loading<122>2176614
Ref: libraries/http_parameters loading2176750
Ref: dc82176750
Node: Testing<114>2176887
Ref: libraries/http_parameters testing2177013
Ref: dc92177013
Node: Declarations2177151
Ref: libraries/http_parameters declarations2177282
Ref: dca2177282
Node: Error handling<3>2179798
Ref: libraries/http_parameters error-handling2179938
Ref: dcb2179938
Node: Router integration<2>2180796
Ref: libraries/http_parameters router-integration2180915
Ref: dcc2180915
Node: http_router2181982
Ref: libraries/http_router doc2182103
Ref: dcd2182103
Ref: libraries/http_router http-router2182103
Ref: dce2182103
Ref: libraries/http_router library-http-router2182103
Ref: dcf2182103
Node: API documentation<122>2183016
Ref: libraries/http_router api-documentation2183127
Ref: dd02183127
Node: Loading<123>2183261
Ref: libraries/http_router loading2183393
Ref: dd12183393
Node: Testing<115>2183526
Ref: libraries/http_router testing2183647
Ref: dd22183647
Node: Layering<2>2183781
Ref: libraries/http_router layering2183907
Ref: dd32183907
Node: Current scope<10>2185012
Ref: libraries/http_router current-scope2185144
Ref: dd42185144
Node: Route declarations2185462
Ref: libraries/http_router route-declarations2185597
Ref: dd52185597
Node: Path templates2186198
Ref: libraries/http_router path-templates2186335
Ref: dd62186335
Node: Request annotations2186640
Ref: libraries/http_router request-annotations2186773
Ref: dd72186773
Node: Route metadata2187384
Ref: libraries/http_router route-metadata2187522
Ref: dd82187522
Node: Route authorization2188178
Ref: libraries/http_router route-authorization2188316
Ref: dd92188316
Node: Content negotiation2189018
Ref: libraries/http_router content-negotiation2189161
Ref: dda2189161
Node: Middleware chaining2189905
Ref: libraries/http_router middleware-chaining2190048
Ref: ddb2190048
Node: Response middleware2190629
Ref: libraries/http_router response-middleware2190766
Ref: ddc2190766
Node: HEAD fallback2191371
Ref: libraries/http_router head-fallback2191505
Ref: ddd2191505
Node: OPTIONS handling2191664
Ref: libraries/http_router options-handling2191807
Ref: dde2191807
Node: Custom bad-request responses2192881
Ref: libraries/http_router custom-bad-request-responses2193033
Ref: ddf2193033
Node: Custom error responses2193693
Ref: libraries/http_router custom-error-responses2193856
Ref: de02193856
Node: Custom negotiation failures2194911
Ref: libraries/http_router custom-negotiation-failures2195064
Ref: de12195064
Node: OpenAPI derivation2195423
Ref: libraries/http_router openapi-derivation2195576
Ref: de22195576
Node: Current limitations<7>2197936
Ref: libraries/http_router current-limitations2198053
Ref: de32198053
Node: http_server2198448
Ref: libraries/http_server doc2198570
Ref: de42198570
Ref: libraries/http_server http-server2198570
Ref: de52198570
Ref: libraries/http_server library-http-server2198570
Ref: de62198570
Node: API documentation<123>2199376
Ref: libraries/http_server api-documentation2199487
Ref: de72199487
Node: Loading<124>2199621
Ref: libraries/http_server loading2199753
Ref: de82199753
Node: Testing<116>2199903
Ref: libraries/http_server testing2200028
Ref: de92200028
Node: Bounded serving2200173
Ref: libraries/http_server bounded-serving2200304
Ref: dea2200304
Node: Open-ended serving2200754
Ref: libraries/http_server open-ended-serving2200878
Ref: deb2200878
Node: HTTPS2201427
Ref: libraries/http_server https2201560
Ref: dec2201560
Node: Handling server requests2202850
Ref: libraries/http_server handling-server-requests2202976
Ref: ded2202976
Node: Options<27>2204276
Ref: libraries/http_server options2204388
Ref: dee2204388
Node: http_server_core2207823
Ref: libraries/http_server_core doc2207946
Ref: def2207946
Ref: libraries/http_server_core http-server-core2207946
Ref: df02207946
Ref: libraries/http_server_core library-http-server-core2207946
Ref: df12207946
Node: API documentation<124>2208975
Ref: libraries/http_server_core api-documentation2209091
Ref: df22209091
Node: Loading<125>2209230
Ref: libraries/http_server_core loading2209367
Ref: df32209367
Node: Testing<117>2209505
Ref: libraries/http_server_core testing2209637
Ref: df42209637
Node: Usage examples<2>2209776
Ref: libraries/http_server_core usage-examples2209913
Ref: df52209913
Node: Current scope<11>2215265
Ref: libraries/http_server_core current-scope2215406
Ref: df62215406
Node: Framing rules<2>2217828
Ref: libraries/http_server_core framing-rules2217973
Ref: df72217973
Node: Multipart workflow<2>2218441
Ref: libraries/http_server_core multipart-workflow2218597
Ref: df82218597
Node: WebSocket handshake workflow2218969
Ref: libraries/http_server_core websocket-handshake-workflow2219131
Ref: df92219131
Node: Current limitations<8>2220602
Ref: libraries/http_server_core current-limitations2220734
Ref: dfa2220734
Node: http_session2221013
Ref: libraries/http_session doc2221146
Ref: dfb2221146
Ref: libraries/http_session http-session2221146
Ref: dfc2221146
Ref: libraries/http_session library-http-session2221146
Ref: dfd2221146
Node: API documentation<125>2222966
Ref: libraries/http_session api-documentation2223078
Ref: dfe2223078
Node: Loading<126>2223213
Ref: libraries/http_session loading2223346
Ref: dff2223346
Node: Testing<118>2223480
Ref: libraries/http_session testing2223608
Ref: e002223608
Node: Usage overview<3>2223743
Ref: libraries/http_session usage-overview2223876
Ref: e012223876
Node: Current scope<12>2227219
Ref: libraries/http_session current-scope2227362
Ref: e022227362
Node: Current limitations<9>2228948
Ref: libraries/http_session current-limitations2229065
Ref: e032229065
Node: http_socket_transport2229705
Ref: libraries/http_socket_transport doc2229844
Ref: e042229844
Ref: libraries/http_socket_transport http-socket-transport2229844
Ref: e052229844
Ref: libraries/http_socket_transport library-http-socket-transport2229844
Ref: e062229844
Node: API documentation<126>2230674
Ref: libraries/http_socket_transport api-documentation2230795
Ref: e072230795
Node: Loading<127>2230939
Ref: libraries/http_socket_transport loading2231081
Ref: e082231081
Node: Testing<119>2231224
Ref: libraries/http_socket_transport testing2231361
Ref: e092231361
Node: Current scope<13>2231505
Ref: libraries/http_socket_transport current-scope2231661
Ref: e0a2231661
Node: WebSocket handshake workflow<2>2236762
Ref: libraries/http_socket_transport websocket-handshake-workflow2236929
Ref: e0b2236929
Node: Current limitations<10>2238652
Ref: libraries/http_socket_transport current-limitations2238793
Ref: e0c2238793
Node: http_process_transport2239390
Ref: libraries/http_process_transport doc2239534
Ref: e0d2239534
Ref: libraries/http_process_transport http-process-transport2239534
Ref: e0e2239534
Ref: libraries/http_process_transport library-http-process-transport2239534
Ref: e0f2239534
Node: Requirements<6>2241041
Ref: libraries/http_process_transport requirements2241166
Ref: e102241166
Node: API documentation<127>2241827
Ref: libraries/http_process_transport api-documentation2241973
Ref: e112241973
Node: Loading<128>2242118
Ref: libraries/http_process_transport loading2242261
Ref: e122242261
Node: Testing<120>2242405
Ref: libraries/http_process_transport testing2242543
Ref: e132242543
Node: Current scope<14>2242688
Ref: libraries/http_process_transport current-scope2242837
Ref: e142242837
Node: Current limitations<11>2243695
Ref: libraries/http_process_transport current-limitations2243848
Ref: e152243848
Node: Live smoke tests2249249
Ref: libraries/http_process_transport live-smoke-tests2249376
Ref: e162249376
Node: http_static_files2250803
Ref: libraries/http_static_files doc2250940
Ref: e172250940
Ref: libraries/http_static_files http-static-files2250940
Ref: e182250940
Ref: libraries/http_static_files library-http-static-files2250940
Ref: e192250940
Node: API documentation<128>2251864
Ref: libraries/http_static_files api-documentation2251981
Ref: e1a2251981
Node: Loading<129>2252121
Ref: libraries/http_static_files loading2252259
Ref: e1b2252259
Node: Testing<121>2252398
Ref: libraries/http_static_files testing2252531
Ref: e1c2252531
Node: Current scope<15>2252671
Ref: libraries/http_static_files current-scope2252783
Ref: e1d2252783
Node: http_websocket2259992
Ref: libraries/http_websocket doc2260128
Ref: e1e2260128
Ref: libraries/http_websocket http-websocket2260128
Ref: e1f2260128
Ref: libraries/http_websocket library-http-websocket2260128
Ref: e202260128
Node: API documentation<129>2261193
Ref: libraries/http_websocket api-documentation2261307
Ref: e212261307
Node: Loading<130>2261444
Ref: libraries/http_websocket loading2261579
Ref: e222261579
Node: Testing<122>2261720
Ref: libraries/http_websocket testing2261850
Ref: e232261850
Node: Current scope<16>2261987
Ref: libraries/http_websocket current-scope2262124
Ref: e242262124
Node: Current workflow<2>2263611
Ref: libraries/http_websocket current-workflow2263754
Ref: e252263754
Node: Lower-level layers2265231
Ref: libraries/http_websocket lower-level-layers2265348
Ref: e262265348
Node: http_websocket_frames2266068
Ref: libraries/http_websocket_frames doc2266211
Ref: e272266211
Ref: libraries/http_websocket_frames http-websocket-frames2266211
Ref: e282266211
Ref: libraries/http_websocket_frames library-http-websocket-frames2266211
Ref: e292266211
Node: API documentation<130>2266879
Ref: libraries/http_websocket_frames api-documentation2267000
Ref: e2a2267000
Node: Loading<131>2267144
Ref: libraries/http_websocket_frames loading2267286
Ref: e2b2267286
Node: Testing<123>2267434
Ref: libraries/http_websocket_frames testing2267571
Ref: e2c2267571
Node: Current scope<17>2267715
Ref: libraries/http_websocket_frames current-scope2267859
Ref: e2d2267859
Node: Normalized terms<3>2268400
Ref: libraries/http_websocket_frames normalized-terms2268548
Ref: e2e2268548
Node: Valid properties2269133
Ref: libraries/http_websocket_frames valid-properties2269283
Ref: e2f2269283
Node: Current workflow<3>2270007
Ref: libraries/http_websocket_frames current-workflow2270161
Ref: e302270161
Node: Current limitations<12>2270841
Ref: libraries/http_websocket_frames current-limitations2270970
Ref: e312270970
Node: http_websocket_handshake2271676
Ref: libraries/http_websocket_handshake doc2271828
Ref: e322271828
Ref: libraries/http_websocket_handshake http-websocket-handshake2271828
Ref: e332271828
Ref: libraries/http_websocket_handshake library-http-websocket-handshake2271828
Ref: e342271828
Node: API documentation<131>2272281
Ref: libraries/http_websocket_handshake api-documentation2272405
Ref: e352272405
Node: Loading<132>2272552
Ref: libraries/http_websocket_handshake loading2272697
Ref: e362272697
Node: Testing<124>2272848
Ref: libraries/http_websocket_handshake testing2272988
Ref: e372272988
Node: Current scope<18>2273135
Ref: libraries/http_websocket_handshake current-scope2273282
Ref: e382273282
Node: Current workflow<4>2273594
Ref: libraries/http_websocket_handshake current-workflow2273720
Ref: e392273720
Node: http_websocket_messages2273932
Ref: libraries/http_websocket_messages doc2274085
Ref: e3a2274085
Ref: libraries/http_websocket_messages http-websocket-messages2274085
Ref: e3b2274085
Ref: libraries/http_websocket_messages library-http-websocket-messages2274085
Ref: e3c2274085
Node: API documentation<132>2274831
Ref: libraries/http_websocket_messages api-documentation2274954
Ref: e3d2274954
Node: Loading<133>2275100
Ref: libraries/http_websocket_messages loading2275244
Ref: e3e2275244
Node: Testing<125>2275389
Ref: libraries/http_websocket_messages testing2275528
Ref: e3f2275528
Node: Current scope<19>2275674
Ref: libraries/http_websocket_messages current-scope2275820
Ref: e402275820
Node: Normalized terms<4>2276625
Ref: libraries/http_websocket_messages normalized-terms2276778
Ref: e412276778
Node: Current workflow<5>2277480
Ref: libraries/http_websocket_messages current-workflow2277639
Ref: e422277639
Node: Current limitations<13>2278469
Ref: libraries/http_websocket_messages current-limitations2278600
Ref: e432278600
Node: http_websocket_service2279458
Ref: libraries/http_websocket_service doc2279609
Ref: e442279609
Ref: libraries/http_websocket_service http-websocket-service2279609
Ref: e452279609
Ref: libraries/http_websocket_service library-http-websocket-service2279609
Ref: e462279609
Node: API documentation<133>2281272
Ref: libraries/http_websocket_service api-documentation2281394
Ref: e472281394
Node: Loading<134>2281539
Ref: libraries/http_websocket_service loading2281682
Ref: e482281682
Node: Testing<126>2281826
Ref: libraries/http_websocket_service testing2281964
Ref: e492281964
Node: Current scope<20>2282109
Ref: libraries/http_websocket_service current-scope2282260
Ref: e4a2282260
Node: Higher-level session loop2283938
Ref: libraries/http_websocket_service higher-level-session-loop2284106
Ref: e4b2284106
Node: Registry-backed server helper2289008
Ref: libraries/http_websocket_service registry-backed-server-helper2289190
Ref: e4c2289190
Node: Backends without thread support2290872
Ref: libraries/http_websocket_service backends-without-thread-support2291048
Ref: e4d2291048
Node: Current workflow<6>2293164
Ref: libraries/http_websocket_service current-workflow2293334
Ref: e4e2293334
Node: Current limitations<14>2294863
Ref: libraries/http_websocket_service current-limitations2294993
Ref: e4f2294993
Node: http_websocket_session2295511
Ref: libraries/http_websocket_session doc2295653
Ref: e502295653
Ref: libraries/http_websocket_session http-websocket-session2295653
Ref: e512295653
Ref: libraries/http_websocket_session library-http-websocket-session2295653
Ref: e522295653
Node: API documentation<134>2296908
Ref: libraries/http_websocket_session api-documentation2297030
Ref: e532297030
Node: Loading<135>2297175
Ref: libraries/http_websocket_session loading2297318
Ref: e542297318
Node: Testing<127>2297462
Ref: libraries/http_websocket_session testing2297600
Ref: e552297600
Node: Current scope<21>2297745
Ref: libraries/http_websocket_session current-scope2297889
Ref: e562297889
Node: Role-aware objects2298726
Ref: libraries/http_websocket_session role-aware-objects2298872
Ref: e572298872
Node: Stateful reads2299464
Ref: libraries/http_websocket_session stateful-reads2299619
Ref: e582299619
Node: Automatic control handling2300453
Ref: libraries/http_websocket_session automatic-control-handling2300612
Ref: e592300612
Node: Outgoing fragmentation2301338
Ref: libraries/http_websocket_session outgoing-fragmentation2301502
Ref: e5a2301502
Node: Current workflow<7>2301934
Ref: libraries/http_websocket_session current-workflow2302095
Ref: e5b2302095
Node: Current limitations<15>2302909
Ref: libraries/http_websocket_session current-limitations2303039
Ref: e5c2303039
Node: ica_projection2303270
Ref: libraries/ica_projection doc2303393
Ref: e5d2303393
Ref: libraries/ica_projection ica-projection2303393
Ref: e5e2303393
Ref: libraries/ica_projection library-ica-projection2303393
Ref: e5f2303393
Node: API documentation<135>2304284
Ref: libraries/ica_projection api-documentation2304398
Ref: e602304398
Node: Loading<136>2304535
Ref: libraries/ica_projection loading2304670
Ref: e612304670
Node: Testing<128>2304807
Ref: libraries/ica_projection testing2304932
Ref: e622304932
Node: Features<29>2305080
Ref: libraries/ica_projection features2305204
Ref: e632305204
Node: Options<28>2306218
Ref: libraries/ica_projection options2306339
Ref: e642306339
Node: Usage<51>2307969
Ref: libraries/ica_projection usage2308110
Ref: e652308110
Node: Learning a reducer2308449
Ref: libraries/ica_projection learning-a-reducer2308568
Ref: e662308568
Node: Transforming new instances2308871
Ref: libraries/ica_projection transforming-new-instances2309032
Ref: e672309032
Node: Exporting and reusing the reducer2309293
Ref: libraries/ica_projection exporting-and-reusing-the-reducer2309427
Ref: e682309427
Node: Dimension reducer representation2309897
Ref: libraries/ica_projection dimension-reducer-representation2310041
Ref: e692310041
Node: References<18>2310691
Ref: libraries/ica_projection references2310817
Ref: e6a2310817
Node: ids2310969
Ref: libraries/ids doc2311078
Ref: e6b2311078
Ref: libraries/ids ids2311078
Ref: e6c2311078
Ref: libraries/ids library-ids2311078
Ref: e6d2311078
Node: API documentation<136>2311865
Ref: libraries/ids api-documentation2311968
Ref: e6e2311968
Node: Loading<137>2312094
Ref: libraries/ids loading2312218
Ref: e6f2312218
Node: Testing<129>2312360
Ref: libraries/ids testing2312471
Ref: e702312471
Node: Usage<52>2312608
Ref: libraries/ids usage2312698
Ref: e712312698
Node: ieee_7542313538
Ref: libraries/ieee_754 doc2313642
Ref: e722313642
Ref: libraries/ieee_754 ieee-7542313642
Ref: e732313642
Ref: libraries/ieee_754 library-ieee-7542313642
Ref: e742313642
Node: Loading<138>2314062
Ref: libraries/ieee_754 loading2314160
Ref: e752314160
Node: Testing<130>2314307
Ref: libraries/ieee_754 testing2314426
Ref: e762314426
Node: Object model2314568
Ref: libraries/ieee_754 object-model2314695
Ref: e772314695
Node: Value representation2315392
Ref: libraries/ieee_754 value-representation2315520
Ref: e782315520
Node: Public API<2>2316722
Ref: libraries/ieee_754 public-api2316847
Ref: e792316847
Node: Semantics2318659
Ref: libraries/ieee_754 semantics2318755
Ref: e7a2318755
Node: intervals2319579
Ref: libraries/intervals doc2319700
Ref: e7b2319700
Ref: libraries/intervals intervals2319700
Ref: e7c2319700
Ref: libraries/intervals library-intervals2319700
Ref: e7d2319700
Node: Practical limits2321583
Ref: libraries/intervals practical-limits2321696
Ref: e7e2321696
Node: API documentation<137>2322893
Ref: libraries/intervals api-documentation2323027
Ref: e7f2323027
Node: Loading<139>2323159
Ref: libraries/intervals loading2323289
Ref: e802323289
Node: Testing<131>2323437
Ref: libraries/intervals testing2323558
Ref: e812323558
Node: Examples<172>2323701
Ref: libraries/intervals examples2323801
Ref: e822323801
Node: iqr_anomaly_detector2327079
Ref: libraries/iqr_anomaly_detector doc2327199
Ref: e832327199
Ref: libraries/iqr_anomaly_detector iqr-anomaly-detector2327199
Ref: e842327199
Ref: libraries/iqr_anomaly_detector library-iqr-anomaly-detector2327199
Ref: e852327199
Node: API documentation<138>2328603
Ref: libraries/iqr_anomaly_detector api-documentation2328723
Ref: e862328723
Node: Loading<140>2328866
Ref: libraries/iqr_anomaly_detector loading2329007
Ref: e872329007
Node: Testing<132>2329150
Ref: libraries/iqr_anomaly_detector testing2329281
Ref: e882329281
Node: Features<30>2329435
Ref: libraries/iqr_anomaly_detector features2329565
Ref: e892329565
Node: Options<29>2333183
Ref: libraries/iqr_anomaly_detector options2333327
Ref: e8a2333327
Node: Detector representation<3>2334329
Ref: libraries/iqr_anomaly_detector detector-representation2334469
Ref: e8b2334469
Node: Notes<7>2335359
Ref: libraries/iqr_anomaly_detector notes2335479
Ref: e8c2335479
Node: iso_6392338043
Ref: libraries/iso_639 doc2338162
Ref: e8d2338162
Ref: libraries/iso_639 iso-6392338162
Ref: e8e2338162
Ref: libraries/iso_639 library-iso-6392338162
Ref: e8f2338162
Node: API documentation<139>2338921
Ref: libraries/iso_639 api-documentation2339028
Ref: e902339028
Node: Loading<141>2339158
Ref: libraries/iso_639 loading2339286
Ref: e912339286
Node: Testing<133>2339432
Ref: libraries/iso_639 testing2339529
Ref: e922339529
Node: iso_31662339670
Ref: libraries/iso_3166 doc2339777
Ref: e932339777
Ref: libraries/iso_3166 iso-31662339777
Ref: e942339777
Ref: libraries/iso_3166 library-iso-31662339777
Ref: e952339777
Node: API documentation<140>2340741
Ref: libraries/iso_3166 api-documentation2340849
Ref: e962340849
Node: Loading<142>2340980
Ref: libraries/iso_3166 loading2341109
Ref: e972341109
Node: Testing<134>2341256
Ref: libraries/iso_3166 testing2341354
Ref: e982341354
Node: iso_42172341496
Ref: libraries/iso_4217 doc2341604
Ref: e992341604
Ref: libraries/iso_4217 iso-42172341604
Ref: e9a2341604
Ref: libraries/iso_4217 library-iso-42172341604
Ref: e9b2341604
Node: API documentation<141>2342443
Ref: libraries/iso_4217 api-documentation2342551
Ref: e9c2342551
Node: Loading<143>2342682
Ref: libraries/iso_4217 loading2342811
Ref: e9d2342811
Node: Testing<135>2342958
Ref: libraries/iso_4217 testing2343056
Ref: e9e2343056
Node: iso_93622343198
Ref: libraries/iso_9362 doc2343307
Ref: e9f2343307
Ref: libraries/iso_9362 iso-93622343307
Ref: ea02343307
Ref: libraries/iso_9362 library-iso-93622343307
Ref: ea12343307
Node: API documentation<142>2344347
Ref: libraries/iso_9362 api-documentation2344455
Ref: ea22344455
Node: Loading<144>2344586
Ref: libraries/iso_9362 loading2344715
Ref: ea32344715
Node: Testing<136>2344862
Ref: libraries/iso_9362 testing2344960
Ref: ea42344960
Node: iso_136162345102
Ref: libraries/iso_13616 doc2345236
Ref: ea52345236
Ref: libraries/iso_13616 iso-136162345236
Ref: ea62345236
Ref: libraries/iso_13616 library-iso-136162345236
Ref: ea72345236
Node: API documentation<143>2346492
Ref: libraries/iso_13616 api-documentation2346601
Ref: ea82346601
Node: Loading<145>2346733
Ref: libraries/iso_13616 loading2346863
Ref: ea92346863
Node: Testing<137>2347011
Ref: libraries/iso_13616 testing2347110
Ref: eaa2347110
Node: isolation_forest_anomaly_detector2347253
Ref: libraries/isolation_forest_anomaly_detector doc2347383
Ref: eab2347383
Ref: libraries/isolation_forest_anomaly_detector isolation-forest-anomaly-detector2347383
Ref: eac2347383
Ref: libraries/isolation_forest_anomaly_detector library-isolation-forest-anomaly-detector2347383
Ref: ead2347383
Node: API documentation<144>2348837
Ref: libraries/isolation_forest_anomaly_detector api-documentation2348970
Ref: eae2348970
Node: Loading<146>2349109
Ref: libraries/isolation_forest_anomaly_detector loading2349263
Ref: eaf2349263
Node: Testing<138>2349435
Ref: libraries/isolation_forest_anomaly_detector testing2349590
Ref: eb02349590
Node: Implemented features<2>2349757
Ref: libraries/isolation_forest_anomaly_detector implemented-features2349911
Ref: eb12349911
Node: Options<30>2352019
Ref: libraries/isolation_forest_anomaly_detector options2352187
Ref: eb22352187
Node: Detector representation<4>2353241
Ref: libraries/isolation_forest_anomaly_detector detector-representation2353400
Ref: eb32353400
Node: Limitations<4>2354534
Ref: libraries/isolation_forest_anomaly_detector limitations2354696
Ref: eb42354696
Node: References<19>2354879
Ref: libraries/isolation_forest_anomaly_detector references2355024
Ref: eb52355024
Node: Usage<53>2355496
Ref: libraries/isolation_forest_anomaly_detector usage2355618
Ref: eb62355618
Node: java2357681
Ref: libraries/java doc2357806
Ref: eb72357806
Ref: libraries/java java2357806
Ref: eb82357806
Ref: libraries/java library-java2357806
Ref: eb92357806
Node: API documentation<145>2359042
Ref: libraries/java api-documentation2359146
Ref: eba2359146
Node: Loading<147>2359273
Ref: libraries/java loading2359398
Ref: ebb2359398
Node: Testing<139>2359541
Ref: libraries/java testing2359653
Ref: ebc2359653
Node: Usage<54>2359791
Ref: libraries/java usage2359907
Ref: ebd2359907
Node: Known issues<11>2360509
Ref: libraries/java known-issues2360604
Ref: ebe2360604
Node: json2361008
Ref: libraries/json doc2361110
Ref: ebf2361110
Ref: libraries/json json2361110
Ref: ec02361110
Ref: libraries/json library-json2361110
Ref: ec12361110
Node: API documentation<146>2361915
Ref: libraries/json api-documentation2362019
Ref: ec22362019
Node: Loading<148>2362146
Ref: libraries/json loading2362271
Ref: ec32362271
Node: Testing<140>2362414
Ref: libraries/json testing2362535
Ref: ec42362535
Node: Representation<11>2362774
Ref: libraries/json representation2362894
Ref: ec52362894
Node: Encoding<7>2368340
Ref: libraries/json encoding2368459
Ref: ec62368459
Node: Decoding<7>2369267
Ref: libraries/json decoding2369384
Ref: ec72369384
Node: Known issues<12>2369912
Ref: libraries/json known-issues2370009
Ref: ec82370009
Node: json_graph2370216
Ref: libraries/json_graph doc2370321
Ref: ec92370321
Ref: libraries/json_graph json-graph2370321
Ref: eca2370321
Ref: libraries/json_graph library-json-graph2370321
Ref: ecb2370321
Node: API documentation<147>2372027
Ref: libraries/json_graph api-documentation2372137
Ref: ecc2372137
Node: Loading<149>2372270
Ref: libraries/json_graph loading2372401
Ref: ecd2372401
Node: Testing<141>2372550
Ref: libraries/json_graph testing2372668
Ref: ece2372668
Node: Usage<55>2372954
Ref: libraries/json_graph usage2373090
Ref: ecf2373090
Node: Roundtrip and fixture coverage2373544
Ref: libraries/json_graph roundtrip-and-fixture-coverage2373659
Ref: ed02373659
Node: json_ld2374332
Ref: libraries/json_ld doc2374443
Ref: ed12374443
Ref: libraries/json_ld json-ld2374443
Ref: ed22374443
Ref: libraries/json_ld library-json-ld2374443
Ref: ed32374443
Node: API documentation<148>2375442
Ref: libraries/json_ld api-documentation2375549
Ref: ed42375549
Node: Loading<150>2375679
Ref: libraries/json_ld loading2375807
Ref: ed52375807
Node: Testing<142>2375953
Ref: libraries/json_ld testing2376069
Ref: ed62376069
Node: Parsing<2>2376210
Ref: libraries/json_ld parsing2376327
Ref: ed72376327
Node: Generating<2>2376706
Ref: libraries/json_ld generating2376820
Ref: ed82376820
Node: Expansion2377060
Ref: libraries/json_ld expansion2377174
Ref: ed92377174
Node: Compaction2377704
Ref: libraries/json_ld compaction2377815
Ref: eda2377815
Node: Flattening2378297
Ref: libraries/json_ld flattening2378406
Ref: edb2378406
Node: Framing2378989
Ref: libraries/json_ld framing2379108
Ref: edc2379108
Node: Implemented Features2379829
Ref: libraries/json_ld implemented-features2379955
Ref: edd2379955
Node: Known Limitations2382336
Ref: libraries/json_ld known-limitations2382473
Ref: ede2382473
Node: Representation<12>2385692
Ref: libraries/json_ld representation2385800
Ref: edf2385800
Node: json_lines2387392
Ref: libraries/json_lines doc2387503
Ref: ee02387503
Ref: libraries/json_lines json-lines2387503
Ref: ee12387503
Ref: libraries/json_lines library-json-lines2387503
Ref: ee22387503
Node: API documentation<149>2388196
Ref: libraries/json_lines api-documentation2388306
Ref: ee32388306
Node: Loading<151>2388439
Ref: libraries/json_lines loading2388570
Ref: ee42388570
Node: Testing<143>2388719
Ref: libraries/json_lines testing2388846
Ref: ee52388846
Node: Representation<13>2389092
Ref: libraries/json_lines representation2389218
Ref: ee62389218
Node: Encoding<8>2394753
Ref: libraries/json_lines encoding2394878
Ref: ee72394878
Node: Decoding<8>2395700
Ref: libraries/json_lines decoding2395823
Ref: ee82395823
Node: Known issues<13>2396338
Ref: libraries/json_lines known-issues2396441
Ref: ee92396441
Node: json_patch2396578
Ref: libraries/json_patch doc2396691
Ref: eea2396691
Ref: libraries/json_patch json-patch2396691
Ref: eeb2396691
Ref: libraries/json_patch library-json-patch2396691
Ref: eec2396691
Node: API documentation<150>2397273
Ref: libraries/json_patch api-documentation2397383
Ref: eed2397383
Node: Loading<152>2397516
Ref: libraries/json_patch loading2397647
Ref: eee2397647
Node: Testing<144>2397845
Ref: libraries/json_patch testing2397972
Ref: eef2397972
Node: Representation<14>2398116
Ref: libraries/json_patch representation2398255
Ref: ef02398255
Node: Patch document structure2398677
Ref: libraries/json_patch patch-document-structure2398820
Ref: ef12398820
Node: Valid operations2399953
Ref: libraries/json_patch valid-operations2400088
Ref: ef22400088
Node: Path rules2402658
Ref: libraries/json_patch path-rules2402789
Ref: ef32402789
Node: Representation notes2403283
Ref: libraries/json_patch representation-notes2403416
Ref: ef42403416
Node: Failure and errors2404071
Ref: libraries/json_patch failure-and-errors2404185
Ref: ef52404185
Node: json_path2404822
Ref: libraries/json_path doc2404937
Ref: ef62404937
Ref: libraries/json_path json-path2404937
Ref: ef72404937
Ref: libraries/json_path library-json-path2404937
Ref: ef82404937
Node: Current implementation status2405381
Ref: libraries/json_path current-implementation-status2405507
Ref: ef92405507
Node: API documentation<151>2406959
Ref: libraries/json_path api-documentation2407106
Ref: efa2407106
Node: Loading<153>2407238
Ref: libraries/json_path loading2407368
Ref: efb2407368
Node: Testing<145>2407516
Ref: libraries/json_path testing2407642
Ref: efc2407642
Node: Representation<15>2407785
Ref: libraries/json_path representation2407912
Ref: efd2407912
Node: Examples<173>2408458
Ref: libraries/json_path examples2408564
Ref: efe2408564
Node: json_pointer2409514
Ref: libraries/json_pointer doc2409627
Ref: eff2409627
Ref: libraries/json_pointer json-pointer2409627
Ref: f002409627
Ref: libraries/json_pointer library-json-pointer2409627
Ref: f012409627
Node: API documentation<152>2410378
Ref: libraries/json_pointer api-documentation2410490
Ref: f022410490
Node: Loading<154>2410625
Ref: libraries/json_pointer loading2410758
Ref: f032410758
Node: Testing<146>2410909
Ref: libraries/json_pointer testing2411038
Ref: f042411038
Node: Representation<16>2411184
Ref: libraries/json_pointer representation2411314
Ref: f052411314
Node: Examples<174>2412061
Ref: libraries/json_pointer examples2412170
Ref: f062412170
Node: json_rpc2412761
Ref: libraries/json_rpc doc2412876
Ref: f072412876
Ref: libraries/json_rpc json-rpc2412876
Ref: f082412876
Ref: libraries/json_rpc library-json-rpc2412876
Ref: f092412876
Node: API documentation<153>2413539
Ref: libraries/json_rpc api-documentation2413647
Ref: f0a2413647
Node: Loading<155>2413778
Ref: libraries/json_rpc loading2413907
Ref: f0b2413907
Node: Testing<147>2414038
Ref: libraries/json_rpc testing2414154
Ref: f0c2414154
Node: Usage<56>2414296
Ref: libraries/json_rpc usage2414411
Ref: f0d2414411
Node: Constructing JSON-RPC 2 0 messages2414796
Ref: libraries/json_rpc constructing-json-rpc-2-0-messages2414932
Ref: f0e2414932
Ref: libraries/json_rpc constructing-json-rpc-20-messages2414932
Ref: f0f2414932
Node: Standard error constructors2415538
Ref: libraries/json_rpc standard-error-constructors2415704
Ref: f102415704
Node: Encoding and decoding2416095
Ref: libraries/json_rpc encoding-and-decoding2416249
Ref: f112416249
Node: Message classification2416568
Ref: libraries/json_rpc message-classification2416711
Ref: f122416711
Node: Field extraction2417045
Ref: libraries/json_rpc field-extraction2417199
Ref: f132417199
Node: Stream I/O client and server API2417648
Ref: libraries/json_rpc stream-i-o-client-and-server-api2417823
Ref: f142417823
Node: Content-Length framed I/O LSP/MCP protocols2418249
Ref: libraries/json_rpc content-length-framed-i-o-lsp-mcp-protocols2418399
Ref: f152418399
Node: API summary2419025
Ref: libraries/json_rpc api-summary2419119
Ref: f162419119
Node: Message construction2419384
Ref: libraries/json_rpc message-construction2419505
Ref: f172419505
Node: Standard error responses2420361
Ref: libraries/json_rpc standard-error-responses2420515
Ref: f182420515
Node: Encoding and decoding<2>2421028
Ref: libraries/json_rpc encoding-and-decoding-12421187
Ref: f192421187
Ref: libraries/json_rpc id12421187
Ref: f1a2421187
Node: Message classification<2>2421466
Ref: libraries/json_rpc id22421620
Ref: f1b2421620
Ref: libraries/json_rpc message-classification-12421620
Ref: f1c2421620
Node: Field extraction<2>2422093
Ref: libraries/json_rpc field-extraction-12422233
Ref: f1d2422233
Ref: libraries/json_rpc id32422233
Ref: f1e2422233
Node: Stream I/O2422877
Ref: libraries/json_rpc stream-i-o2422983
Ref: f1f2422983
Node: json_schema2423677
Ref: libraries/json_schema doc2423783
Ref: f202423783
Ref: libraries/json_schema json-schema2423783
Ref: f212423783
Ref: libraries/json_schema library-json-schema2423783
Ref: f222423783
Node: API documentation<154>2424380
Ref: libraries/json_schema api-documentation2424491
Ref: f232424491
Node: Loading<156>2424625
Ref: libraries/json_schema loading2424757
Ref: f242424757
Node: Testing<148>2424907
Ref: libraries/json_schema testing2425031
Ref: f252425031
Node: Schema Parsing2425176
Ref: libraries/json_schema schema-parsing2425298
Ref: f262425298
Node: Validation2425604
Ref: libraries/json_schema validation2425732
Ref: f272425732
Node: Supported Keywords2426362
Ref: libraries/json_schema supported-keywords2426496
Ref: f282426496
Node: Known Limitations<2>2429522
Ref: libraries/json_schema known-limitations2429637
Ref: f292429637
Node: jwt2430042
Ref: libraries/jwt doc2430158
Ref: f2a2430158
Ref: libraries/jwt jwt2430158
Ref: f2b2430158
Ref: libraries/jwt library-jwt2430158
Ref: f2c2430158
Node: Requirements<7>2430880
Ref: libraries/jwt requirements2430986
Ref: f2d2430986
Node: API documentation<155>2431537
Ref: libraries/jwt api-documentation2431664
Ref: f2e2431664
Node: Loading<157>2431790
Ref: libraries/jwt loading2431914
Ref: f2f2431914
Node: Testing<149>2432039
Ref: libraries/jwt testing2432152
Ref: f302432152
Node: Options<31>2432278
Ref: libraries/jwt options2432396
Ref: f312432396
Node: Validation policy2434420
Ref: libraries/jwt validation-policy2434540
Ref: f322434540
Node: Basic usage<3>2436676
Ref: libraries/jwt basic-usage2436776
Ref: f332436776
Node: kcenters_clusterer2438426
Ref: libraries/kcenters_clusterer doc2438550
Ref: f342438550
Ref: libraries/kcenters_clusterer kcenters-clusterer2438550
Ref: f352438550
Ref: libraries/kcenters_clusterer library-kcenters-clusterer2438550
Ref: f362438550
Node: API documentation<156>2439439
Ref: libraries/kcenters_clusterer api-documentation2439557
Ref: f372439557
Node: Loading<158>2439698
Ref: libraries/kcenters_clusterer loading2439837
Ref: f382439837
Node: Testing<150>2439978
Ref: libraries/kcenters_clusterer testing2440107
Ref: f392440107
Node: Features<31>2440409
Ref: libraries/kcenters_clusterer features2440537
Ref: f3a2440537
Node: Options<32>2441422
Ref: libraries/kcenters_clusterer options2441552
Ref: f3b2441552
Node: Diagnostics<4>2442137
Ref: libraries/kcenters_clusterer diagnostics2442282
Ref: f3c2442282
Node: Clusterer representation<6>2442567
Ref: libraries/kcenters_clusterer clusterer-representation2442715
Ref: f3d2442715
Node: References<20>2443360
Ref: libraries/kcenters_clusterer references2443485
Ref: f3e2443485
Node: kemeny_young_ranker2443661
Ref: libraries/kemeny_young_ranker doc2443803
Ref: f3f2443803
Ref: libraries/kemeny_young_ranker kemeny-young-ranker2443803
Ref: f402443803
Ref: libraries/kemeny_young_ranker library-kemeny-young-ranker2443803
Ref: f412443803
Node: API documentation<157>2445155
Ref: libraries/kemeny_young_ranker api-documentation2445274
Ref: f422445274
Node: Loading<159>2445416
Ref: libraries/kemeny_young_ranker loading2445556
Ref: f432445556
Node: Testing<151>2445698
Ref: libraries/kemeny_young_ranker testing2445828
Ref: f442445828
Node: Features<32>2445981
Ref: libraries/kemeny_young_ranker features2446108
Ref: f452446108
Node: Usage<57>2447508
Ref: libraries/kemeny_young_ranker usage2447634
Ref: f462447634
Node: Learning a ranker<9>2447808
Ref: libraries/kemeny_young_ranker learning-a-ranker2447935
Ref: f472447935
Node: Inspecting the learned consensus2448267
Ref: libraries/kemeny_young_ranker inspecting-the-learned-consensus2448429
Ref: f482448429
Node: Ranking candidate items<8>2448963
Ref: libraries/kemeny_young_ranker ranking-candidate-items2449096
Ref: f492449096
Node: Options<33>2449639
Ref: libraries/kemeny_young_ranker options2449773
Ref: f4a2449773
Node: Scoring semantics<5>2450270
Ref: libraries/kemeny_young_ranker scoring-semantics2450417
Ref: f4b2450417
Node: Diagnostics syntax<12>2450936
Ref: libraries/kemeny_young_ranker diagnostics-syntax2451096
Ref: f4c2451096
Node: Ranker representation<9>2451442
Ref: libraries/kemeny_young_ranker ranker-representation2451590
Ref: f4d2451590
Node: Notes<8>2452039
Ref: libraries/kemeny_young_ranker notes2452179
Ref: f4e2452179
Node: References<21>2452368
Ref: libraries/kemeny_young_ranker references2452475
Ref: f4f2452475
Node: kernel_svm_classifier2452638
Ref: libraries/kernel_svm_classifier doc2452783
Ref: f502452783
Ref: libraries/kernel_svm_classifier kernel-svm-classifier2452783
Ref: f512452783
Ref: libraries/kernel_svm_classifier library-kernel-svm-classifier2452783
Ref: f522452783
Node: API documentation<158>2453947
Ref: libraries/kernel_svm_classifier api-documentation2454068
Ref: f532454068
Node: Loading<160>2454212
Ref: libraries/kernel_svm_classifier loading2454354
Ref: f542454354
Node: Testing<152>2454498
Ref: libraries/kernel_svm_classifier testing2454630
Ref: f552454630
Node: Features<33>2454785
Ref: libraries/kernel_svm_classifier features2454916
Ref: f562454916
Node: Options<34>2455695
Ref: libraries/kernel_svm_classifier options2455823
Ref: f572455823
Node: Usage<58>2456664
Ref: libraries/kernel_svm_classifier usage2456808
Ref: f582456808
Node: Learning a classifier<2>2457000
Ref: libraries/kernel_svm_classifier learning-a-classifier2457120
Ref: f592457120
Node: Making predictions<2>2457351
Ref: libraries/kernel_svm_classifier making-predictions2457507
Ref: f5a2457507
Node: Exporting the classifier<2>2457951
Ref: libraries/kernel_svm_classifier exporting-the-classifier2458074
Ref: f5b2458074
Node: Classifier representation<3>2458458
Ref: libraries/kernel_svm_classifier classifier-representation2458605
Ref: f5c2458605
Node: References<22>2459493
Ref: libraries/kernel_svm_classifier references2459622
Ref: f5d2459622
Node: kernel_pca_projection2459899
Ref: libraries/kernel_pca_projection doc2460041
Ref: f5e2460041
Ref: libraries/kernel_pca_projection kernel-pca-projection2460041
Ref: f5f2460041
Ref: libraries/kernel_pca_projection library-kernel-pca-projection2460041
Ref: f602460041
Node: API documentation<159>2460840
Ref: libraries/kernel_pca_projection api-documentation2460961
Ref: f612460961
Node: Loading<161>2461105
Ref: libraries/kernel_pca_projection loading2461247
Ref: f622461247
Node: Testing<153>2461391
Ref: libraries/kernel_pca_projection testing2461523
Ref: f632461523
Node: Features<34>2461678
Ref: libraries/kernel_pca_projection features2461809
Ref: f642461809
Node: Options<35>2463036
Ref: libraries/kernel_pca_projection options2463164
Ref: f652463164
Node: Usage<59>2464721
Ref: libraries/kernel_pca_projection usage2464872
Ref: f662464872
Node: Learning a reducer<2>2465292
Ref: libraries/kernel_pca_projection learning-a-reducer2465417
Ref: f672465417
Node: Transforming new instances<2>2465668
Ref: libraries/kernel_pca_projection transforming-new-instances2465838
Ref: f682465838
Node: Exporting and reusing the reducer<2>2466130
Ref: libraries/kernel_pca_projection exporting-and-reusing-the-reducer2466270
Ref: f692466270
Node: Dimension reducer representation<2>2466745
Ref: libraries/kernel_pca_projection dimension-reducer-representation2466899
Ref: f6a2466899
Node: References<23>2468317
Ref: libraries/kernel_pca_projection references2468453
Ref: f6b2468453
Node: kmeans_clusterer2468725
Ref: libraries/kmeans_clusterer doc2468864
Ref: f6c2468864
Ref: libraries/kmeans_clusterer kmeans-clusterer2468864
Ref: f6d2468864
Ref: libraries/kmeans_clusterer library-kmeans-clusterer2468864
Ref: f6e2468864
Node: API documentation<160>2469743
Ref: libraries/kmeans_clusterer api-documentation2469859
Ref: f6f2469859
Node: Loading<162>2469998
Ref: libraries/kmeans_clusterer loading2470135
Ref: f702470135
Node: Testing<154>2470274
Ref: libraries/kmeans_clusterer testing2470401
Ref: f712470401
Node: Features<35>2470699
Ref: libraries/kmeans_clusterer features2470825
Ref: f722470825
Node: Options<36>2471622
Ref: libraries/kmeans_clusterer options2471750
Ref: f732471750
Node: Diagnostics<5>2472438
Ref: libraries/kmeans_clusterer diagnostics2472581
Ref: f742472581
Node: Clusterer representation<7>2472918
Ref: libraries/kmeans_clusterer clusterer-representation2473064
Ref: f752473064
Node: References<24>2473713
Ref: libraries/kmeans_clusterer references2473836
Ref: f762473836
Node: kmedians_clusterer2474204
Ref: libraries/kmedians_clusterer doc2474340
Ref: f772474340
Ref: libraries/kmedians_clusterer kmedians-clusterer2474340
Ref: f782474340
Ref: libraries/kmedians_clusterer library-kmedians-clusterer2474340
Ref: f792474340
Node: API documentation<161>2475242
Ref: libraries/kmedians_clusterer api-documentation2475360
Ref: f7a2475360
Node: Loading<163>2475501
Ref: libraries/kmedians_clusterer loading2475640
Ref: f7b2475640
Node: Testing<155>2475781
Ref: libraries/kmedians_clusterer testing2475910
Ref: f7c2475910
Node: Features<36>2476212
Ref: libraries/kmedians_clusterer features2476340
Ref: f7d2476340
Node: Options<37>2477235
Ref: libraries/kmedians_clusterer options2477365
Ref: f7e2477365
Node: Diagnostics<6>2478057
Ref: libraries/kmedians_clusterer diagnostics2478202
Ref: f7f2478202
Node: Clusterer representation<8>2478539
Ref: libraries/kmedians_clusterer clusterer-representation2478687
Ref: f802478687
Node: References<25>2479332
Ref: libraries/kmedians_clusterer references2479457
Ref: f812479457
Node: kmedoids_clusterer2479815
Ref: libraries/kmedoids_clusterer doc2479951
Ref: f822479951
Ref: libraries/kmedoids_clusterer kmedoids-clusterer2479951
Ref: f832479951
Ref: libraries/kmedoids_clusterer library-kmedoids-clusterer2479951
Ref: f842479951
Node: API documentation<162>2480890
Ref: libraries/kmedoids_clusterer api-documentation2481008
Ref: f852481008
Node: Loading<164>2481149
Ref: libraries/kmedoids_clusterer loading2481288
Ref: f862481288
Node: Testing<156>2481429
Ref: libraries/kmedoids_clusterer testing2481558
Ref: f872481558
Node: Features<37>2481860
Ref: libraries/kmedoids_clusterer features2481988
Ref: f882481988
Node: Options<38>2482849
Ref: libraries/kmedoids_clusterer options2482979
Ref: f892482979
Node: Diagnostics<7>2483793
Ref: libraries/kmedoids_clusterer diagnostics2483938
Ref: f8a2483938
Node: Clusterer representation<9>2484275
Ref: libraries/kmedoids_clusterer clusterer-representation2484423
Ref: f8b2484423
Node: References<26>2485068
Ref: libraries/kmedoids_clusterer references2485193
Ref: f8c2485193
Node: kmodes_clusterer2485497
Ref: libraries/kmodes_clusterer doc2485629
Ref: f8d2485629
Ref: libraries/kmodes_clusterer kmodes-clusterer2485629
Ref: f8e2485629
Ref: libraries/kmodes_clusterer library-kmodes-clusterer2485629
Ref: f8f2485629
Node: API documentation<163>2486559
Ref: libraries/kmodes_clusterer api-documentation2486675
Ref: f902486675
Node: Loading<165>2486814
Ref: libraries/kmodes_clusterer loading2486951
Ref: f912486951
Node: Testing<157>2487090
Ref: libraries/kmodes_clusterer testing2487217
Ref: f922487217
Node: Features<38>2487515
Ref: libraries/kmodes_clusterer features2487641
Ref: f932487641
Node: Options<39>2488318
Ref: libraries/kmodes_clusterer options2488446
Ref: f942488446
Node: Diagnostics<8>2488967
Ref: libraries/kmodes_clusterer diagnostics2489111
Ref: f952489111
Node: Clusterer representation<10>2489444
Ref: libraries/kmodes_clusterer clusterer-representation2489591
Ref: f962489591
Node: References<27>2490194
Ref: libraries/kmodes_clusterer references2490318
Ref: f972490318
Node: knn_classifier2490536
Ref: libraries/knn_classifier doc2490679
Ref: f982490679
Ref: libraries/knn_classifier knn-classifier2490679
Ref: f992490679
Ref: libraries/knn_classifier library-knn-classifier2490679
Ref: f9a2490679
Node: API documentation<164>2491706
Ref: libraries/knn_classifier api-documentation2491820
Ref: f9b2491820
Node: Loading<166>2491957
Ref: libraries/knn_classifier loading2492092
Ref: f9c2492092
Node: Testing<158>2492229
Ref: libraries/knn_classifier testing2492354
Ref: f9d2492354
Node: Features<39>2492502
Ref: libraries/knn_classifier features2492624
Ref: f9e2492624
Node: Usage<60>2493202
Ref: libraries/knn_classifier usage2493323
Ref: f9f2493323
Node: Learning a Classifier<2>2493546
Ref: libraries/knn_classifier learning-a-classifier2493666
Ref: fa02493666
Node: Making Predictions<2>2494016
Ref: libraries/knn_classifier making-predictions2494172
Ref: fa12494172
Node: Exporting the Classifier<2>2494824
Ref: libraries/knn_classifier exporting-the-classifier2494982
Ref: fa22494982
Node: Using a learned classifier2495559
Ref: libraries/knn_classifier using-a-learned-classifier2495687
Ref: fa32495687
Node: Options<40>2496127
Ref: libraries/knn_classifier options2496264
Ref: fa42496264
Node: Classifier representation<4>2496761
Ref: libraries/knn_classifier classifier-representation2496903
Ref: fa52496903
Node: References<28>2497570
Ref: libraries/knn_classifier references2497692
Ref: fa62497692
Node: knn_distance_anomaly_detector2498075
Ref: libraries/knn_distance_anomaly_detector doc2498216
Ref: fa72498216
Ref: libraries/knn_distance_anomaly_detector knn-distance-anomaly-detector2498216
Ref: fa82498216
Ref: libraries/knn_distance_anomaly_detector library-knn-distance-anomaly-detector2498216
Ref: fa92498216
Node: API documentation<165>2499489
Ref: libraries/knn_distance_anomaly_detector api-documentation2499618
Ref: faa2499618
Node: Loading<167>2499770
Ref: libraries/knn_distance_anomaly_detector loading2499920
Ref: fab2499920
Node: Testing<159>2500072
Ref: libraries/knn_distance_anomaly_detector testing2500212
Ref: fac2500212
Node: Features<40>2500375
Ref: libraries/knn_distance_anomaly_detector features2500514
Ref: fad2500514
Node: Options<41>2501558
Ref: libraries/knn_distance_anomaly_detector options2501711
Ref: fae2501711
Node: Detector representation<5>2502564
Ref: libraries/knn_distance_anomaly_detector detector-representation2502719
Ref: faf2502719
Node: References<29>2504314
Ref: libraries/knn_distance_anomaly_detector references2504449
Ref: fb02504449
Node: knn_regression2504722
Ref: libraries/knn_regression doc2504870
Ref: fb12504870
Ref: libraries/knn_regression knn-regression2504870
Ref: fb22504870
Ref: libraries/knn_regression library-knn-regression2504870
Ref: fb32504870
Node: API documentation<166>2505623
Ref: libraries/knn_regression api-documentation2505737
Ref: fb42505737
Node: Loading<168>2505874
Ref: libraries/knn_regression loading2506009
Ref: fb52506009
Node: Testing<160>2506146
Ref: libraries/knn_regression testing2506271
Ref: fb62506271
Node: Features<41>2506565
Ref: libraries/knn_regression features2506705
Ref: fb72506705
Node: Regressor representation<5>2508062
Ref: libraries/knn_regression regressor-representation2508212
Ref: fb82508212
Node: Diagnostics syntax<13>2508668
Ref: libraries/knn_regression diagnostics-syntax2508817
Ref: fb92508817
Node: Options<42>2509947
Ref: libraries/knn_regression options2510060
Ref: fba2510060
Node: kprototypes_clusterer2511235
Ref: libraries/kprototypes_clusterer doc2511359
Ref: fbb2511359
Ref: libraries/kprototypes_clusterer kprototypes-clusterer2511359
Ref: fbc2511359
Ref: libraries/kprototypes_clusterer library-kprototypes-clusterer2511359
Ref: fbd2511359
Node: API documentation<167>2512330
Ref: libraries/kprototypes_clusterer api-documentation2512451
Ref: fbe2512451
Node: Loading<169>2512595
Ref: libraries/kprototypes_clusterer loading2512737
Ref: fbf2512737
Node: Testing<161>2512881
Ref: libraries/kprototypes_clusterer testing2513013
Ref: fc02513013
Node: Features<42>2513321
Ref: libraries/kprototypes_clusterer features2513452
Ref: fc12513452
Node: Options<43>2514537
Ref: libraries/kprototypes_clusterer options2514673
Ref: fc22514673
Node: Distance Function2515478
Ref: libraries/kprototypes_clusterer distance-function2515630
Ref: fc32515630
Node: Clusterer representation<11>2516268
Ref: libraries/kprototypes_clusterer clusterer-representation2516423
Ref: fc42516423
Node: References<30>2517070
Ref: libraries/kprototypes_clusterer references2517199
Ref: fc52517199
Node: ksuid2517614
Ref: libraries/ksuid doc2517740
Ref: fc62517740
Ref: libraries/ksuid ksuid2517740
Ref: fc72517740
Ref: libraries/ksuid library-ksuid2517740
Ref: fc82517740
Node: API documentation<168>2518697
Ref: libraries/ksuid api-documentation2518802
Ref: fc92518802
Node: Loading<170>2518930
Ref: libraries/ksuid loading2519056
Ref: fca2519056
Node: Testing<162>2519200
Ref: libraries/ksuid testing2519313
Ref: fcb2519313
Node: Usage<61>2519452
Ref: libraries/ksuid usage2519544
Ref: fcc2519544
Node: lasso_regression2520012
Ref: libraries/lasso_regression doc2520131
Ref: fcd2520131
Ref: libraries/lasso_regression lasso-regression2520131
Ref: fce2520131
Ref: libraries/lasso_regression library-lasso-regression2520131
Ref: fcf2520131
Node: API documentation<169>2521037
Ref: libraries/lasso_regression api-documentation2521153
Ref: fd02521153
Node: Loading<171>2521292
Ref: libraries/lasso_regression loading2521429
Ref: fd12521429
Node: Testing<163>2521568
Ref: libraries/lasso_regression testing2521695
Ref: fd22521695
Node: Features<43>2521993
Ref: libraries/lasso_regression features2522135
Ref: fd32522135
Node: Regressor representation<6>2523667
Ref: libraries/lasso_regression regressor-representation2523819
Ref: fd42523819
Node: Diagnostics syntax<14>2524369
Ref: libraries/lasso_regression diagnostics-syntax2524520
Ref: fd52524520
Node: Options<44>2526384
Ref: libraries/lasso_regression options2526499
Ref: fd62526499
Node: lda_classifier2527535
Ref: libraries/lda_classifier doc2527663
Ref: fd72527663
Ref: libraries/lda_classifier lda-classifier2527663
Ref: fd82527663
Ref: libraries/lda_classifier library-lda-classifier2527663
Ref: fd92527663
Node: API documentation<170>2528734
Ref: libraries/lda_classifier api-documentation2528848
Ref: fda2528848
Node: Loading<172>2528985
Ref: libraries/lda_classifier loading2529120
Ref: fdb2529120
Node: Testing<164>2529257
Ref: libraries/lda_classifier testing2529382
Ref: fdc2529382
Node: Features<44>2529530
Ref: libraries/lda_classifier features2529654
Ref: fdd2529654
Node: Options<45>2530350
Ref: libraries/lda_classifier options2530471
Ref: fde2530471
Node: Usage<62>2530816
Ref: libraries/lda_classifier usage2530953
Ref: fdf2530953
Node: Learning a classifier<3>2531145
Ref: libraries/lda_classifier learning-a-classifier2531265
Ref: fe02531265
Node: Making predictions<3>2531472
Ref: libraries/lda_classifier making-predictions2531628
Ref: fe12531628
Node: Exporting the classifier<3>2532063
Ref: libraries/lda_classifier exporting-the-classifier2532186
Ref: fe22532186
Node: Classifier representation<5>2532554
Ref: libraries/lda_classifier classifier-representation2532694
Ref: fe32532694
Node: References<31>2533389
Ref: libraries/lda_classifier references2533511
Ref: fe42533511
Node: lda_projection2533861
Ref: libraries/lda_projection doc2533978
Ref: fe52533978
Ref: libraries/lda_projection lda-projection2533978
Ref: fe62533978
Ref: libraries/lda_projection library-lda-projection2533978
Ref: fe72533978
Node: API documentation<171>2535013
Ref: libraries/lda_projection api-documentation2535127
Ref: fe82535127
Node: Loading<173>2535264
Ref: libraries/lda_projection loading2535399
Ref: fe92535399
Node: Testing<165>2535536
Ref: libraries/lda_projection testing2535661
Ref: fea2535661
Node: Features<45>2535809
Ref: libraries/lda_projection features2535933
Ref: feb2535933
Node: Options<46>2536766
Ref: libraries/lda_projection options2536887
Ref: fec2536887
Node: Usage<63>2537979
Ref: libraries/lda_projection usage2538123
Ref: fed2538123
Node: Learning a reducer<3>2538554
Ref: libraries/lda_projection learning-a-reducer2538679
Ref: fee2538679
Node: Transforming new instances<3>2538997
Ref: libraries/lda_projection transforming-new-instances2539167
Ref: fef2539167
Node: Exporting and reusing the reducer<3>2539651
Ref: libraries/lda_projection exporting-and-reusing-the-reducer2539791
Ref: ff02539791
Node: Dimension reducer representation<3>2540287
Ref: libraries/lda_projection dimension-reducer-representation2540434
Ref: ff12540434
Node: References<32>2541354
Ref: libraries/lda_projection references2541483
Ref: ff22541483
Node: linda2541738
Ref: libraries/linda doc2541855
Ref: ff32541855
Ref: libraries/linda library-linda2541855
Ref: ff42541855
Ref: libraries/linda linda2541855
Ref: ff52541855
Node: API documentation<172>2542977
Ref: libraries/linda api-documentation2543082
Ref: ff62543082
Node: Loading<174>2543210
Ref: libraries/linda loading2543336
Ref: ff72543336
Node: Testing<166>2543464
Ref: libraries/linda testing2543577
Ref: ff82543577
Node: Usage<64>2543716
Ref: libraries/linda usage2543830
Ref: ff92543830
Node: Starting a server2544419
Ref: libraries/linda starting-a-server2544530
Ref: ffa2544530
Node: Connecting a client2544917
Ref: libraries/linda connecting-a-client2545053
Ref: ffb2545053
Node: Tuple operations2545188
Ref: libraries/linda tuple-operations2545320
Ref: ffc2545320
Node: Disconnecting2546356
Ref: libraries/linda disconnecting2546484
Ref: ffd2546484
Node: Timeout control2546718
Ref: libraries/linda timeout-control2546821
Ref: ffe2546821
Node: Examples<175>2547052
Ref: libraries/linda examples2547165
Ref: fff2547165
Node: Producer-Consumer2547272
Ref: libraries/linda producer-consumer2547383
Ref: 10002547383
Node: Critical Region2547659
Ref: libraries/linda critical-region2547794
Ref: 10012547794
Node: Synchronization2548039
Ref: libraries/linda synchronization2548148
Ref: 10022548148
Node: API Summary2548336
Ref: libraries/linda api-summary2548456
Ref: 10032548456
Node: Server predicates2548709
Ref: libraries/linda server-predicates2548820
Ref: 10042548820
Node: Client predicates2548983
Ref: libraries/linda client-predicates2549141
Ref: 10052549141
Node: Tuple predicates single/default server2549423
Ref: libraries/linda tuple-predicates-single-default-server2549597
Ref: 10062549597
Node: Tuple predicates multiple servers2550522
Ref: libraries/linda tuple-predicates-multiple-servers2550670
Ref: 10072550670
Node: Known issues<14>2550914
Ref: libraries/linda known-issues2551032
Ref: 10082551032
Node: See also<2>2551366
Ref: libraries/linda see-also2551464
Ref: 10092551464
Node: linear_algebra2551847
Ref: libraries/linear_algebra doc2551967
Ref: 100a2551967
Ref: libraries/linear_algebra library-linear-algebra2551967
Ref: 100b2551967
Ref: libraries/linear_algebra linear-algebra2551967
Ref: 100c2551967
Node: API documentation<173>2554308
Ref: libraries/linear_algebra api-documentation2554422
Ref: 100d2554422
Node: Loading<175>2554559
Ref: libraries/linear_algebra loading2554694
Ref: 100e2554694
Node: Testing<167>2554847
Ref: libraries/linear_algebra testing2554951
Ref: 100f2554951
Node: linear_regression2555099
Ref: libraries/linear_regression doc2555235
Ref: 10102555235
Ref: libraries/linear_regression library-linear-regression2555235
Ref: 10112555235
Ref: libraries/linear_regression linear-regression2555235
Ref: 10122555235
Node: API documentation<174>2556115
Ref: libraries/linear_regression api-documentation2556232
Ref: 10132556232
Node: Loading<176>2556372
Ref: libraries/linear_regression loading2556510
Ref: 10142556510
Node: Testing<168>2556650
Ref: libraries/linear_regression testing2556778
Ref: 10152556778
Node: Features<46>2557078
Ref: libraries/linear_regression features2557221
Ref: 10162557221
Node: Regressor representation<7>2558805
Ref: libraries/linear_regression regressor-representation2558958
Ref: 10172558958
Node: Diagnostics syntax<15>2559509
Ref: libraries/linear_regression diagnostics-syntax2559661
Ref: 10182559661
Node: Options<47>2561739
Ref: libraries/linear_regression options2561855
Ref: 10192561855
Node: linear_svm_classifier2562156
Ref: libraries/linear_svm_classifier doc2562285
Ref: 101a2562285
Ref: libraries/linear_svm_classifier library-linear-svm-classifier2562285
Ref: 101b2562285
Ref: libraries/linear_svm_classifier linear-svm-classifier2562285
Ref: 101c2562285
Node: API documentation<175>2563472
Ref: libraries/linear_svm_classifier api-documentation2563593
Ref: 101d2563593
Node: Loading<177>2563737
Ref: libraries/linear_svm_classifier loading2563879
Ref: 101e2563879
Node: Testing<169>2564023
Ref: libraries/linear_svm_classifier testing2564155
Ref: 101f2564155
Node: Features<47>2564463
Ref: libraries/linear_svm_classifier features2564594
Ref: 10202564594
Node: Options<48>2565847
Ref: libraries/linear_svm_classifier options2565975
Ref: 10212565975
Node: Usage<65>2566465
Ref: libraries/linear_svm_classifier usage2566609
Ref: 10222566609
Node: Learning a classifier<4>2566801
Ref: libraries/linear_svm_classifier learning-a-classifier2566921
Ref: 10232566921
Node: Making predictions<4>2567162
Ref: libraries/linear_svm_classifier making-predictions2567318
Ref: 10242567318
Node: Exporting the classifier<4>2567554
Ref: libraries/linear_svm_classifier exporting-the-classifier2567677
Ref: 10252567677
Node: Classifier representation<6>2568061
Ref: libraries/linear_svm_classifier classifier-representation2568208
Ref: 10262568208
Node: References<33>2568935
Ref: libraries/linear_svm_classifier references2569064
Ref: 10272569064
Node: listing2569392
Ref: libraries/listing doc2569524
Ref: 10282569524
Ref: libraries/listing library-listing2569524
Ref: 10292569524
Ref: libraries/listing listing2569524
Ref: 102a2569524
Node: API documentation<176>2569875
Ref: libraries/listing api-documentation2569982
Ref: 102b2569982
Node: Loading<178>2570112
Ref: libraries/listing loading2570240
Ref: 102c2570240
Node: Testing<170>2570394
Ref: libraries/listing testing2570509
Ref: 102d2570509
Node: Usage<66>2570650
Ref: libraries/listing usage2570744
Ref: 102e2570744
Node: lof_anomaly_detector2572840
Ref: libraries/lof_anomaly_detector doc2572958
Ref: 102f2572958
Ref: libraries/lof_anomaly_detector library-lof-anomaly-detector2572958
Ref: 10302572958
Ref: libraries/lof_anomaly_detector lof-anomaly-detector2572958
Ref: 10312572958
Node: API documentation<177>2574185
Ref: libraries/lof_anomaly_detector api-documentation2574305
Ref: 10322574305
Node: Loading<179>2574448
Ref: libraries/lof_anomaly_detector loading2574589
Ref: 10332574589
Node: Testing<171>2574732
Ref: libraries/lof_anomaly_detector testing2574863
Ref: 10342574863
Node: Features<48>2575017
Ref: libraries/lof_anomaly_detector features2575147
Ref: 10352575147
Node: Options<49>2576394
Ref: libraries/lof_anomaly_detector options2576538
Ref: 10362576538
Node: Detector representation<6>2577269
Ref: libraries/lof_anomaly_detector detector-representation2577415
Ref: 10372577415
Node: References<34>2579001
Ref: libraries/lof_anomaly_detector references2579127
Ref: 10382579127
Node: logging2579305
Ref: libraries/logging doc2579446
Ref: 10392579446
Ref: libraries/logging library-logging2579446
Ref: 103a2579446
Ref: libraries/logging logging2579446
Ref: 103b2579446
Node: API documentation<178>2579623
Ref: libraries/logging api-documentation2579730
Ref: 103c2579730
Node: Loading<180>2579860
Ref: libraries/logging loading2579967
Ref: 103d2579967
Node: logistic_regression_classifier2580121
Ref: libraries/logistic_regression_classifier doc2580247
Ref: 103e2580247
Ref: libraries/logistic_regression_classifier library-logistic-regression-classifier2580247
Ref: 103f2580247
Ref: libraries/logistic_regression_classifier logistic-regression-classifier2580247
Ref: 10402580247
Node: API documentation<179>2581490
Ref: libraries/logistic_regression_classifier api-documentation2581620
Ref: 10412581620
Node: Loading<181>2581773
Ref: libraries/logistic_regression_classifier loading2581924
Ref: 10422581924
Node: Testing<172>2582077
Ref: libraries/logistic_regression_classifier testing2582218
Ref: 10432582218
Node: Features<49>2582544
Ref: libraries/logistic_regression_classifier features2582684
Ref: 10442582684
Node: Options<50>2584074
Ref: libraries/logistic_regression_classifier options2584211
Ref: 10452584211
Node: Usage<67>2584690
Ref: libraries/logistic_regression_classifier usage2584843
Ref: 10462584843
Node: Learning a classifier<5>2585035
Ref: libraries/logistic_regression_classifier learning-a-classifier2585155
Ref: 10472585155
Node: Making predictions<5>2585414
Ref: libraries/logistic_regression_classifier making-predictions2585570
Ref: 10482585570
Node: Exporting the classifier<5>2586062
Ref: libraries/logistic_regression_classifier exporting-the-classifier2586185
Ref: 10492586185
Node: Classifier representation<7>2586605
Ref: libraries/logistic_regression_classifier classifier-representation2586761
Ref: 104a2586761
Node: References<35>2587480
Ref: libraries/logistic_regression_classifier references2587618
Ref: 104b2587618
Node: loops2587972
Ref: libraries/loops doc2588104
Ref: 104c2588104
Ref: libraries/loops library-loops2588104
Ref: 104d2588104
Ref: libraries/loops loops2588104
Ref: 104e2588104
Node: API documentation<180>2588360
Ref: libraries/loops api-documentation2588465
Ref: 104f2588465
Node: Loading<182>2588593
Ref: libraries/loops loading2588719
Ref: 10502588719
Node: Testing<173>2588868
Ref: libraries/loops testing2588981
Ref: 10512588981
Node: Usage<68>2589120
Ref: libraries/loops usage2589212
Ref: 10522589212
Node: massey_ranker2589281
Ref: libraries/massey_ranker doc2589393
Ref: 10532589393
Ref: libraries/massey_ranker library-massey-ranker2589393
Ref: 10542589393
Ref: libraries/massey_ranker massey-ranker2589393
Ref: 10552589393
Node: API documentation<181>2590703
Ref: libraries/massey_ranker api-documentation2590816
Ref: 10562590816
Node: Loading<183>2590952
Ref: libraries/massey_ranker loading2591086
Ref: 10572591086
Node: Testing<174>2591222
Ref: libraries/massey_ranker testing2591346
Ref: 10582591346
Node: Features<50>2591493
Ref: libraries/massey_ranker features2591625
Ref: 10592591625
Node: Scoring semantics<6>2592879
Ref: libraries/massey_ranker scoring-semantics2593008
Ref: 105a2593008
Node: Usage<69>2593913
Ref: libraries/massey_ranker usage2594052
Ref: 105b2594052
Node: Learning a ranker<10>2594292
Ref: libraries/massey_ranker learning-a-ranker2594413
Ref: 105c2594413
Node: Inspecting diagnostics<8>2594813
Ref: libraries/massey_ranker inspecting-diagnostics2594969
Ref: 105d2594969
Node: Ranking candidate items<9>2595232
Ref: libraries/massey_ranker ranking-candidate-items2595390
Ref: 105e2595390
Node: Exporting the ranker<8>2595921
Ref: libraries/massey_ranker exporting-the-ranker2596045
Ref: 105f2596045
Node: Diagnostics syntax<16>2596589
Ref: libraries/massey_ranker diagnostics-syntax2596733
Ref: 10602596733
Node: Ranker representation<10>2596985
Ref: libraries/massey_ranker ranker-representation2597134
Ref: 10612597134
Node: References<36>2597521
Ref: libraries/massey_ranker references2597639
Ref: 10622597639
Node: mcp_server2597769
Ref: libraries/mcp_server doc2597885
Ref: 10632597885
Ref: libraries/mcp_server library-mcp-server2597885
Ref: 10642597885
Ref: libraries/mcp_server mcp-server2597885
Ref: 10652597885
Node: API documentation<182>2598568
Ref: libraries/mcp_server api-documentation2598678
Ref: 10662598678
Node: Loading<184>2598811
Ref: libraries/mcp_server loading2598942
Ref: 10672598942
Node: Testing<175>2599075
Ref: libraries/mcp_server testing2599193
Ref: 10682599193
Node: Usage<70>2599337
Ref: libraries/mcp_server usage2599460
Ref: 10692599460
Node: Implementing the tool protocol2599936
Ref: libraries/mcp_server implementing-the-tool-protocol2600076
Ref: 106a2600076
Node: Auto-dispatch vs custom tool_call/32602324
Ref: libraries/mcp_server auto-dispatch-vs-custom-tool-call-32602510
Ref: 106b2602510
Ref: libraries/mcp_server auto-dispatch-vs-custom-tool-call32602510
Ref: 106c2602510
Node: Output schemas structured tool output2603799
Ref: libraries/mcp_server output-schemas-structured-tool-output2603988
Ref: 106d2603988
Node: Starting the server for debugging2604594
Ref: libraries/mcp_server starting-the-server-for-debugging2604772
Ref: 106e2604772
Node: MCP client configuration2605270
Ref: libraries/mcp_server mcp-client-configuration2605440
Ref: 106f2605440
Node: Elicitation interactive tools2606972
Ref: libraries/mcp_server elicitation-interactive-tools2607133
Ref: 10702607133
Node: Prompts prompt templates2609256
Ref: libraries/mcp_server prompts-prompt-templates2609416
Ref: 10712609416
Node: Resources data exposure2612448
Ref: libraries/mcp_server resources-data-exposure2612570
Ref: 10722612570
Node: Error handling<4>2615048
Ref: libraries/mcp_server error-handling2615167
Ref: 10732615167
Node: Protocol2615549
Ref: libraries/mcp_server protocol2615680
Ref: 10742615680
Node: Supported MCP methods2616963
Ref: libraries/mcp_server supported-mcp-methods2617068
Ref: 10752617068
Node: memcached2618468
Ref: libraries/memcached doc2618583
Ref: 10762618583
Ref: libraries/memcached library-memcached2618583
Ref: 10772618583
Ref: libraries/memcached memcached2618583
Ref: 10782618583
Node: API documentation<183>2619153
Ref: libraries/memcached api-documentation2619262
Ref: 10792619262
Node: Loading<185>2619394
Ref: libraries/memcached loading2619524
Ref: 107a2619524
Node: Testing<176>2619656
Ref: libraries/memcached testing2619780
Ref: 107b2619780
Node: Protocol Version2620319
Ref: libraries/memcached protocol-version2620443
Ref: 107c2620443
Node: Features<51>2620829
Ref: libraries/memcached features2620950
Ref: 107d2620950
Node: Usage<71>2621540
Ref: libraries/memcached usage2621659
Ref: 107e2621659
Node: Connecting to a Memcached server2621941
Ref: libraries/memcached connecting-to-a-memcached-server2622060
Ref: 107f2622060
Node: Storing data2622369
Ref: libraries/memcached storing-data2622512
Ref: 10802622512
Node: Retrieving data2623175
Ref: libraries/memcached retrieving-data2623303
Ref: 10812623303
Node: Check-and-Set CAS2623724
Ref: libraries/memcached check-and-set-cas2623853
Ref: 10822623853
Node: Deleting data2624283
Ref: libraries/memcached deleting-data2624416
Ref: 10832624416
Node: Increment/Decrement2624571
Ref: libraries/memcached increment-decrement2624710
Ref: 10842624710
Node: Touch and Get-and-Touch2625199
Ref: libraries/memcached touch-and-get-and-touch2625342
Ref: 10852625342
Node: Server management2625725
Ref: libraries/memcached server-management2625865
Ref: 10862625865
Node: Disconnecting<2>2626305
Ref: libraries/memcached disconnecting2626413
Ref: 10872626413
Node: API Summary<2>2626506
Ref: libraries/memcached api-summary2626630
Ref: 10882626630
Node: Connection management2626841
Ref: libraries/memcached connection-management2626958
Ref: 10892626958
Node: Storage commands2627227
Ref: libraries/memcached storage-commands2627371
Ref: 108a2627371
Node: Retrieval commands2628030
Ref: libraries/memcached retrieval-commands2628161
Ref: 108b2628161
Node: Deletion2628576
Ref: libraries/memcached deletion2628713
Ref: 108c2628713
Node: Increment/Decrement<2>2628804
Ref: libraries/memcached id12628928
Ref: 108d2628928
Ref: libraries/memcached incrementdecrement-12628928
Ref: 108e2628928
Node: Touch2629125
Ref: libraries/memcached touch2629256
Ref: 108f2629256
Node: Server commands2629521
Ref: libraries/memcached server-commands2629621
Ref: 10902629621
Node: Error Handling<2>2630014
Ref: libraries/memcached error-handling2630139
Ref: 10912630139
Node: Key Format2630866
Ref: libraries/memcached key-format2630993
Ref: 10922630993
Node: Expiration Times2631165
Ref: libraries/memcached expiration-times2631266
Ref: 10932631266
Node: message_pack2631576
Ref: libraries/message_pack doc2631685
Ref: 10942631685
Ref: libraries/message_pack library-message-pack2631685
Ref: 10952631685
Ref: libraries/message_pack message-pack2631685
Ref: 10962631685
Ref: message_pack-Footnote-12632360
Node: API documentation<184>2632389
Ref: libraries/message_pack api-documentation2632501
Ref: 10972632501
Node: Loading<186>2632636
Ref: libraries/message_pack loading2632769
Ref: 10982632769
Node: Testing<177>2632920
Ref: libraries/message_pack testing2633049
Ref: 10992633049
Node: Representation<17>2633195
Ref: libraries/message_pack representation2633320
Ref: 109a2633320
Node: Notes<9>2635580
Ref: libraries/message_pack notes2635684
Ref: 109b2635684
Node: meta2636987
Ref: libraries/meta doc2637100
Ref: 109c2637100
Ref: libraries/meta library-meta2637100
Ref: 109d2637100
Ref: libraries/meta meta2637100
Ref: 109e2637100
Node: API documentation<185>2637524
Ref: libraries/meta api-documentation2637628
Ref: 109f2637628
Node: Loading<187>2637755
Ref: libraries/meta loading2637880
Ref: 10a02637880
Node: Testing<178>2638028
Ref: libraries/meta testing2638140
Ref: 10a12638140
Node: Usage<72>2638278
Ref: libraries/meta usage2638369
Ref: 10a22638369
Node: meta_compiler2638458
Ref: libraries/meta_compiler doc2638569
Ref: 10a32638569
Ref: libraries/meta_compiler library-meta-compiler2638569
Ref: 36b2638569
Ref: libraries/meta_compiler meta-compiler2638569
Ref: 10a42638569
Node: API documentation<186>2638906
Ref: libraries/meta_compiler api-documentation2639019
Ref: 10a52639019
Node: Loading<188>2639155
Ref: libraries/meta_compiler loading2639289
Ref: 10a62639289
Node: Testing<179>2639446
Ref: libraries/meta_compiler testing2639567
Ref: 10a72639567
Node: Usage<73>2639714
Ref: libraries/meta_compiler usage2639839
Ref: 10a82639839
Node: Known issues<15>2640461
Ref: libraries/meta_compiler known-issues2640565
Ref: 10a92640565
Node: mime_types2640724
Ref: libraries/mime_types doc2640864
Ref: 10aa2640864
Ref: libraries/mime_types library-mime-types2640864
Ref: 10ab2640864
Ref: libraries/mime_types mime-types2640864
Ref: 10ac2640864
Node: API documentation<187>2641799
Ref: libraries/mime_types api-documentation2641909
Ref: 10ad2641909
Node: Loading<189>2642042
Ref: libraries/mime_types loading2642173
Ref: 10ae2642173
Node: Testing<180>2642322
Ref: libraries/mime_types testing2642440
Ref: 10af2642440
Node: Usage<74>2642584
Ref: libraries/mime_types usage2642681
Ref: 10b02642681
Node: modified_z_score_anomaly_detector2643304
Ref: libraries/modified_z_score_anomaly_detector doc2643440
Ref: 10b12643440
Ref: libraries/modified_z_score_anomaly_detector library-modified-z-score-anomaly-detector2643440
Ref: 10b22643440
Ref: libraries/modified_z_score_anomaly_detector modified-z-score-anomaly-detector2643440
Ref: 10b32643440
Node: API documentation<188>2644799
Ref: libraries/modified_z_score_anomaly_detector api-documentation2644932
Ref: 10b42644932
Node: Loading<190>2645071
Ref: libraries/modified_z_score_anomaly_detector loading2645225
Ref: 10b52645225
Node: Testing<181>2645381
Ref: libraries/modified_z_score_anomaly_detector testing2645525
Ref: 10b62645525
Node: Features<52>2645692
Ref: libraries/modified_z_score_anomaly_detector features2645835
Ref: 10b72645835
Node: Options<51>2649373
Ref: libraries/modified_z_score_anomaly_detector options2649530
Ref: 10b82649530
Node: Detector representation<7>2650414
Ref: libraries/modified_z_score_anomaly_detector detector-representation2650568
Ref: 10b92650568
Node: Notes<10>2651352
Ref: libraries/modified_z_score_anomaly_detector notes2651486
Ref: 10ba2651486
Node: mutations2653416
Ref: libraries/mutations doc2653551
Ref: 10bb2653551
Ref: libraries/mutations library-mutations2653551
Ref: 10bc2653551
Ref: libraries/mutations mutations2653551
Ref: 10bd2653551
Node: API documentation<189>2654609
Ref: libraries/mutations api-documentation2654718
Ref: 10be2654718
Node: Loading<191>2654850
Ref: libraries/mutations loading2654980
Ref: 10bf2654980
Node: Testing<182>2655128
Ref: libraries/mutations testing2655245
Ref: 10c02655245
Node: Usage<75>2655388
Ref: libraries/mutations usage2655484
Ref: 10c12655484
Node: multisets2656475
Ref: libraries/multisets doc2656583
Ref: 10c22656583
Ref: libraries/multisets library-multisets2656583
Ref: 10c32656583
Ref: libraries/multisets multisets2656583
Ref: 10c42656583
Node: API documentation<190>2657979
Ref: libraries/multisets api-documentation2658088
Ref: 10c52658088
Node: Loading<192>2658220
Ref: libraries/multisets loading2658350
Ref: 10c62658350
Node: Testing<183>2658498
Ref: libraries/multisets testing2658597
Ref: 10c72658597
Node: nanoid2658740
Ref: libraries/nanoid doc2658861
Ref: 10c82658861
Ref: libraries/nanoid library-nanoid2658861
Ref: 10c92658861
Ref: libraries/nanoid nanoid2658861
Ref: 10ca2658861
Node: API documentation<191>2659754
Ref: libraries/nanoid api-documentation2659860
Ref: 10cb2659860
Node: Loading<193>2659989
Ref: libraries/nanoid loading2660116
Ref: 10cc2660116
Node: Testing<184>2660261
Ref: libraries/nanoid testing2660375
Ref: 10cd2660375
Node: Usage<76>2660515
Ref: libraries/nanoid usage2660608
Ref: 10ce2660608
Node: naive_bayes_classifier2661283
Ref: libraries/naive_bayes_classifier doc2661422
Ref: 10cf2661422
Ref: libraries/naive_bayes_classifier library-naive-bayes-classifier2661422
Ref: 10d02661422
Ref: libraries/naive_bayes_classifier naive-bayes-classifier2661422
Ref: 10d12661422
Node: API documentation<192>2662392
Ref: libraries/naive_bayes_classifier api-documentation2662514
Ref: 10d22662514
Node: Loading<194>2662659
Ref: libraries/naive_bayes_classifier loading2662802
Ref: 10d32662802
Node: Testing<185>2662947
Ref: libraries/naive_bayes_classifier testing2663080
Ref: 10d42663080
Node: Features<53>2663236
Ref: libraries/naive_bayes_classifier features2663366
Ref: 10d52663366
Node: Usage<77>2663771
Ref: libraries/naive_bayes_classifier usage2663917
Ref: 10d62663917
Node: Learning a Classifier<3>2664170
Ref: libraries/naive_bayes_classifier learning-a-classifier2664290
Ref: 10d72664290
Node: Making Predictions<3>2664465
Ref: libraries/naive_bayes_classifier making-predictions2664621
Ref: 10d82664621
Node: Exporting the Classifier<3>2665083
Ref: libraries/naive_bayes_classifier exporting-the-classifier2665244
Ref: 10d92665244
Node: Using a learned classifier<2>2665829
Ref: libraries/naive_bayes_classifier using-a-learned-classifier2665960
Ref: 10da2665960
Node: Classifier representation<8>2666408
Ref: libraries/naive_bayes_classifier classifier-representation2666556
Ref: 10db2666556
Node: References<37>2667336
Ref: libraries/naive_bayes_classifier references2667466
Ref: 10dc2667466
Node: nearest_centroid_classifier2667773
Ref: libraries/nearest_centroid_classifier doc2667925
Ref: 10dd2667925
Ref: libraries/nearest_centroid_classifier library-nearest-centroid-classifier2667925
Ref: 10de2667925
Ref: libraries/nearest_centroid_classifier nearest-centroid-classifier2667925
Ref: 10df2667925
Node: API documentation<193>2668852
Ref: libraries/nearest_centroid_classifier api-documentation2668979
Ref: 10e02668979
Node: Loading<195>2669129
Ref: libraries/nearest_centroid_classifier loading2669277
Ref: 10e12669277
Node: Testing<186>2669427
Ref: libraries/nearest_centroid_classifier testing2669565
Ref: 10e22669565
Node: Features<54>2669726
Ref: libraries/nearest_centroid_classifier features2669861
Ref: 10e32669861
Node: Usage<78>2670283
Ref: libraries/nearest_centroid_classifier usage2670417
Ref: 10e42670417
Node: Learning a Classifier<4>2670670
Ref: libraries/nearest_centroid_classifier learning-a-classifier2670790
Ref: 10e52670790
Node: Making Predictions<4>2671155
Ref: libraries/nearest_centroid_classifier making-predictions2671311
Ref: 10e62671311
Node: Exporting the Classifier<4>2672009
Ref: libraries/nearest_centroid_classifier exporting-the-classifier2672170
Ref: 10e72672170
Node: Using a learned classifier<3>2672799
Ref: libraries/nearest_centroid_classifier using-a-learned-classifier2672930
Ref: 10e82672930
Node: Options<52>2673456
Ref: libraries/nearest_centroid_classifier options2673606
Ref: 10e92673606
Node: Classifier representation<9>2673878
Ref: libraries/nearest_centroid_classifier classifier-representation2674033
Ref: 10ea2674033
Node: References<38>2674669
Ref: libraries/nearest_centroid_classifier references2674804
Ref: 10eb2674804
Node: nested_dictionaries2675342
Ref: libraries/nested_dictionaries doc2675476
Ref: 10ec2675476
Ref: libraries/nested_dictionaries library-nested-dictionaries2675476
Ref: 10ed2675476
Ref: libraries/nested_dictionaries nested-dictionaries2675476
Ref: 10ee2675476
Node: API documentation<194>2676054
Ref: libraries/nested_dictionaries api-documentation2676173
Ref: 10ef2676173
Node: Loading<196>2676315
Ref: libraries/nested_dictionaries loading2676455
Ref: 10f02676455
Node: Testing<187>2676613
Ref: libraries/nested_dictionaries testing2676740
Ref: 10f12676740
Node: Usage<79>2676893
Ref: libraries/nested_dictionaries usage2677033
Ref: 10f22677033
Node: Curly term representation2678739
Ref: libraries/nested_dictionaries curly-term-representation2678858
Ref: 10f32678858
Node: nmea2679443
Ref: libraries/nmea doc2679564
Ref: 10f42679564
Ref: libraries/nmea library-nmea2679564
Ref: 10f52679564
Ref: libraries/nmea nmea2679564
Ref: 10f62679564
Node: API documentation<195>2680000
Ref: libraries/nmea api-documentation2680104
Ref: 10f72680104
Node: Loading<197>2680231
Ref: libraries/nmea loading2680356
Ref: 10f82680356
Node: Testing<188>2680483
Ref: libraries/nmea testing2680599
Ref: 10f92680599
Node: Public API<3>2680737
Ref: libraries/nmea public-api2680868
Ref: 10fa2680868
Node: Raw Sentence Representation2681632
Ref: libraries/nmea raw-sentence-representation2681771
Ref: 10fb2681771
Node: Typed data/2 Results2682489
Ref: libraries/nmea typed-data-2-results2682624
Ref: 10fc2682624
Node: Date Rule2683714
Ref: libraries/nmea date-rule2683835
Ref: 10fd2683835
Node: Current Scope2684026
Ref: libraries/nmea current-scope2684118
Ref: 10fe2684118
Node: nmf_projection2684692
Ref: libraries/nmf_projection doc2684802
Ref: 10ff2684802
Ref: libraries/nmf_projection library-nmf-projection2684802
Ref: 11002684802
Ref: libraries/nmf_projection nmf-projection2684802
Ref: 11012684802
Node: API documentation<196>2685426
Ref: libraries/nmf_projection api-documentation2685540
Ref: 11022685540
Node: Loading<198>2685677
Ref: libraries/nmf_projection loading2685812
Ref: 11032685812
Node: Testing<189>2685965
Ref: libraries/nmf_projection testing2686090
Ref: 11042686090
Node: Features<55>2686238
Ref: libraries/nmf_projection features2686362
Ref: 11052686362
Node: Options<53>2686757
Ref: libraries/nmf_projection options2686878
Ref: 11062686878
Node: Usage<80>2687820
Ref: libraries/nmf_projection usage2687964
Ref: 11072687964
Node: Dimension reducer representation<4>2688925
Ref: libraries/nmf_projection dimension-reducer-representation2689072
Ref: 11082689072
Node: References<39>2689504
Ref: libraries/nmf_projection references2689633
Ref: 11092689633
Node: open_api2689840
Ref: libraries/open_api doc2689953
Ref: 110a2689953
Ref: libraries/open_api library-open-api2689953
Ref: 110b2689953
Ref: libraries/open_api open-api2689953
Ref: 110c2689953
Node: Layering<3>2691255
Ref: libraries/open_api layering2691362
Ref: 110d2691362
Node: API documentation<197>2692273
Ref: libraries/open_api api-documentation2692401
Ref: 110e2692401
Node: Loading<199>2692532
Ref: libraries/open_api loading2692661
Ref: 110f2692661
Node: Testing<190>2692792
Ref: libraries/open_api testing2692916
Ref: 11102692916
Node: Current scope<22>2693047
Ref: libraries/open_api current-scope2693182
Ref: 11112693182
Node: Current limitations<16>2695604
Ref: libraries/open_api current-limitations2695747
Ref: 11122695747
Node: Provider descriptors2697401
Ref: libraries/open_api provider-descriptors2697536
Ref: 11132697536
Node: API metadata2697754
Ref: libraries/open_api api-metadata2697870
Ref: 11142697870
Node: Server descriptors2698437
Ref: libraries/open_api server-descriptors2698589
Ref: 11152698589
Node: Top-level security defaults2698991
Ref: libraries/open_api top-level-security-defaults2699152
Ref: 11162699152
Node: Operation descriptors2699663
Ref: libraries/open_api operation-descriptors2699822
Ref: 11172699822
Node: Reusable schemas2701180
Ref: libraries/open_api reusable-schemas2701337
Ref: 11182701337
Node: Reusable security schemes2701605
Ref: libraries/open_api reusable-security-schemes2701732
Ref: 11192701732
Node: Usage<81>2705702
Ref: libraries/open_api usage2705805
Ref: 111a2705805
Node: open_ai2708136
Ref: libraries/open_ai doc2708242
Ref: 111b2708242
Ref: libraries/open_ai library-open-ai2708242
Ref: 111c2708242
Ref: libraries/open_ai open-ai2708242
Ref: 111d2708242
Node: Loading<200>2709143
Ref: libraries/open_ai loading2709240
Ref: 111e2709240
Node: Testing<191>2709369
Ref: libraries/open_ai testing2709492
Ref: 111f2709492
Node: Current scope<23>2709622
Ref: libraries/open_ai current-scope2709751
Ref: 11202709751
Node: Basic client usage2710261
Ref: libraries/open_ai basic-client-usage2710396
Ref: 11212710396
Node: Basic server usage2710810
Ref: libraries/open_ai basic-server-usage2710919
Ref: 11222710919
Node: open_id2711751
Ref: libraries/open_id doc2711865
Ref: 11232711865
Ref: libraries/open_id library-open-id2711865
Ref: 11242711865
Ref: libraries/open_id open-id2711865
Ref: 11252711865
Node: Loading<201>2712978
Ref: libraries/open_id loading2713075
Ref: 11262713075
Node: Testing<192>2713204
Ref: libraries/open_id testing2713324
Ref: 11272713324
Node: Basic usage<4>2714371
Ref: libraries/open_id basic-usage2714496
Ref: 11282714496
Node: Current scope<24>2716406
Ref: libraries/open_id current-scope2716542
Ref: 11292716542
Node: Current limitations<17>2717255
Ref: libraries/open_id current-limitations2717368
Ref: 112a2717368
Node: optics_clusterer2717636
Ref: libraries/optics_clusterer doc2717752
Ref: 112b2717752
Ref: libraries/optics_clusterer library-optics-clusterer2717752
Ref: 112c2717752
Ref: libraries/optics_clusterer optics-clusterer2717752
Ref: 112d2717752
Node: API documentation<198>2718616
Ref: libraries/optics_clusterer api-documentation2718732
Ref: 112e2718732
Node: Loading<202>2718871
Ref: libraries/optics_clusterer loading2719008
Ref: 112f2719008
Node: Testing<193>2719147
Ref: libraries/optics_clusterer testing2719274
Ref: 11302719274
Node: Features<56>2719572
Ref: libraries/optics_clusterer features2719698
Ref: 11312719698
Node: Options<54>2720958
Ref: libraries/optics_clusterer options2721100
Ref: 11322721100
Node: Clusterer representation<12>2722358
Ref: libraries/optics_clusterer clusterer-representation2722479
Ref: 11332722479
Node: optionals2723185
Ref: libraries/optionals doc2723301
Ref: 11342723301
Ref: libraries/optionals library-optionals2723301
Ref: 11352723301
Ref: libraries/optionals optionals2723301
Ref: 11362723301
Node: API documentation<199>2724200
Ref: libraries/optionals api-documentation2724309
Ref: 11372724309
Node: Loading<203>2724441
Ref: libraries/optionals loading2724571
Ref: 11382724571
Node: Testing<194>2724719
Ref: libraries/optionals testing2724836
Ref: 11392724836
Node: Usage<82>2724979
Ref: libraries/optionals usage2725095
Ref: 113a2725095
Node: See also<3>2728608
Ref: libraries/optionals see-also2728703
Ref: 113b2728703
Node: options2728792
Ref: libraries/options doc2728894
Ref: 113c2728894
Ref: libraries/options library-options2728894
Ref: 113d2728894
Ref: libraries/options options2728894
Ref: 113e2728894
Node: API documentation<200>2729150
Ref: libraries/options api-documentation2729257
Ref: 113f2729257
Node: Loading<204>2729387
Ref: libraries/options loading2729515
Ref: 11402729515
Node: Testing<195>2729669
Ref: libraries/options testing2729784
Ref: 11412729784
Node: Usage<83>2729925
Ref: libraries/options usage2730019
Ref: 11422730019
Node: os2732009
Ref: libraries/os doc2732105
Ref: 11432732105
Ref: libraries/os library-os2732105
Ref: 11442732105
Ref: libraries/os os2732105
Ref: 11452732105
Node: API documentation<201>2732515
Ref: libraries/os api-documentation2732617
Ref: 11462732617
Node: Loading<205>2732742
Ref: libraries/os loading2732865
Ref: 11472732865
Node: Testing<196>2733006
Ref: libraries/os testing2733123
Ref: 11482733123
Node: Known issues<16>2733259
Ref: libraries/os known-issues2733355
Ref: 11492733355
Node: otp2733769
Ref: libraries/otp doc2733868
Ref: 114a2733868
Ref: libraries/otp library-otp2733868
Ref: 114b2733868
Ref: libraries/otp otp2733868
Ref: 114c2733868
Node: API documentation<202>2734406
Ref: libraries/otp api-documentation2734509
Ref: 114d2734509
Node: Loading<206>2734635
Ref: libraries/otp loading2734759
Ref: 114e2734759
Node: Testing<197>2734909
Ref: libraries/otp testing2735028
Ref: 114f2735028
Node: Public predicates2735165
Ref: libraries/otp public-predicates2735279
Ref: 11502735279
Node: Secrets2736005
Ref: libraries/otp secrets2736117
Ref: 11512736117
Node: Generation2736703
Ref: libraries/otp generation2736810
Ref: 11522736810
Node: Verification2737408
Ref: libraries/otp verification2737520
Ref: 11532737520
Node: Hash support2738372
Ref: libraries/otp hash-support2738500
Ref: 11542738500
Node: Bounded-backend limitation2738983
Ref: libraries/otp bounded-backend-limitation2739090
Ref: 11552739090
Node: partitions2739887
Ref: libraries/partitions doc2740008
Ref: 11562740008
Ref: libraries/partitions library-partitions2740008
Ref: 11572740008
Ref: libraries/partitions partitions2740008
Ref: 11582740008
Node: API documentation<203>2742240
Ref: libraries/partitions api-documentation2742350
Ref: 11592742350
Node: Loading<207>2742483
Ref: libraries/partitions loading2742614
Ref: 115a2742614
Node: Testing<198>2742763
Ref: libraries/partitions testing2742863
Ref: 115b2742863
Node: pattern_mining_protocols2743007
Ref: libraries/pattern_mining_protocols doc2743139
Ref: 115c2743139
Ref: libraries/pattern_mining_protocols library-pattern-mining-protocols2743139
Ref: 115d2743139
Ref: libraries/pattern_mining_protocols pattern-mining-protocols2743139
Ref: 115e2743139
Node: API documentation<204>2743981
Ref: libraries/pattern_mining_protocols api-documentation2744105
Ref: 115f2744105
Node: Loading<208>2744252
Ref: libraries/pattern_mining_protocols loading2744397
Ref: 11602744397
Node: Testing<199>2744560
Ref: libraries/pattern_mining_protocols testing2744700
Ref: 11612744700
Node: Common options<2>2744857
Ref: libraries/pattern_mining_protocols common-options2744999
Ref: 11622744999
Node: Diagnostics<9>2745954
Ref: libraries/pattern_mining_protocols diagnostics2746109
Ref: 11632746109
Node: Related support libraries2746910
Ref: libraries/pattern_mining_protocols related-support-libraries2747039
Ref: 11642747039
Node: pca_projection2747482
Ref: libraries/pca_projection doc2747616
Ref: 11652747616
Ref: libraries/pca_projection library-pca-projection2747616
Ref: 11662747616
Ref: libraries/pca_projection pca-projection2747616
Ref: 11672747616
Node: API documentation<205>2748360
Ref: libraries/pca_projection api-documentation2748474
Ref: 11682748474
Node: Loading<209>2748611
Ref: libraries/pca_projection loading2748746
Ref: 11692748746
Node: Testing<200>2748883
Ref: libraries/pca_projection testing2749008
Ref: 116a2749008
Node: Features<57>2749156
Ref: libraries/pca_projection features2749280
Ref: 116b2749280
Node: Options<55>2749961
Ref: libraries/pca_projection options2750082
Ref: 116c2750082
Node: Usage<84>2750908
Ref: libraries/pca_projection usage2751052
Ref: 116d2751052
Node: Learning a reducer<4>2751574
Ref: libraries/pca_projection learning-a-reducer2751699
Ref: 116e2751699
Node: Transforming new instances<4>2751985
Ref: libraries/pca_projection transforming-new-instances2752155
Ref: 116f2752155
Node: Exporting and reusing the reducer<4>2752619
Ref: libraries/pca_projection exporting-and-reusing-the-reducer2752759
Ref: 11702752759
Node: Dimension reducer representation<5>2753199
Ref: libraries/pca_projection dimension-reducer-representation2753346
Ref: 11712753346
Node: References<40>2754295
Ref: libraries/pca_projection references2754424
Ref: 11722754424
Node: permutations2754681
Ref: libraries/permutations doc2754811
Ref: 11732754811
Ref: libraries/permutations library-permutations2754811
Ref: 11742754811
Ref: libraries/permutations permutations2754811
Ref: 11752754811
Node: API documentation<206>2756260
Ref: libraries/permutations api-documentation2756372
Ref: 11762756372
Node: Loading<210>2756507
Ref: libraries/permutations loading2756640
Ref: 11772756640
Node: Testing<201>2756791
Ref: libraries/permutations testing2756893
Ref: 11782756893
Node: plackett_luce_ranker2757039
Ref: libraries/plackett_luce_ranker doc2757180
Ref: 11792757180
Ref: libraries/plackett_luce_ranker library-plackett-luce-ranker2757180
Ref: 117a2757180
Ref: libraries/plackett_luce_ranker plackett-luce-ranker2757180
Ref: 117b2757180
Node: API documentation<207>2758590
Ref: libraries/plackett_luce_ranker api-documentation2758710
Ref: 117c2758710
Node: Loading<211>2758853
Ref: libraries/plackett_luce_ranker loading2758994
Ref: 117d2758994
Node: Testing<202>2759137
Ref: libraries/plackett_luce_ranker testing2759268
Ref: 117e2759268
Node: Features<58>2759422
Ref: libraries/plackett_luce_ranker features2759564
Ref: 117f2759564
Node: Dataset requirements<2>2761236
Ref: libraries/plackett_luce_ranker dataset-requirements2761375
Ref: 11802761375
Node: Usage<85>2761998
Ref: libraries/plackett_luce_ranker usage2762147
Ref: 11812762147
Node: Learning a ranker<11>2762283
Ref: libraries/plackett_luce_ranker learning-a-ranker2762404
Ref: 11822762404
Node: Inspecting diagnostics<9>2762787
Ref: libraries/plackett_luce_ranker inspecting-diagnostics2762908
Ref: 11832762908
Node: Diagnostics syntax<17>2763191
Ref: libraries/plackett_luce_ranker diagnostics-syntax2763328
Ref: 11842763328
Node: Ranking candidate items<10>2764682
Ref: libraries/plackett_luce_ranker ranking-candidate-items2764820
Ref: 11852764820
Node: Exporting the ranker<9>2765365
Ref: libraries/plackett_luce_ranker exporting-the-ranker2765503
Ref: 11862765503
Node: Options<56>2766082
Ref: libraries/plackett_luce_ranker options2766235
Ref: 11872766235
Node: Ranker representation<11>2766621
Ref: libraries/plackett_luce_ranker ranker-representation2766763
Ref: 11882766763
Node: See also<4>2767464
Ref: libraries/plackett_luce_ranker see-also2767586
Ref: 11892767586
Node: plackett_luce_last_ranker2767755
Ref: libraries/plackett_luce_last_ranker doc2767898
Ref: 118a2767898
Ref: libraries/plackett_luce_last_ranker library-plackett-luce-last-ranker2767898
Ref: 118b2767898
Ref: libraries/plackett_luce_last_ranker plackett-luce-last-ranker2767898
Ref: 118c2767898
Node: API documentation<208>2769361
Ref: libraries/plackett_luce_last_ranker api-documentation2769486
Ref: 118d2769486
Node: Loading<212>2769634
Ref: libraries/plackett_luce_last_ranker loading2769780
Ref: 118e2769780
Node: Testing<203>2769928
Ref: libraries/plackett_luce_last_ranker testing2770064
Ref: 118f2770064
Node: Features<59>2770223
Ref: libraries/plackett_luce_last_ranker features2770370
Ref: 11902770370
Node: Dataset requirements<3>2772044
Ref: libraries/plackett_luce_last_ranker dataset-requirements2772188
Ref: 11912772188
Node: Usage<86>2772816
Ref: libraries/plackett_luce_last_ranker usage2772970
Ref: 11922772970
Node: Learning a ranker<12>2773107
Ref: libraries/plackett_luce_last_ranker learning-a-ranker2773229
Ref: 11932773229
Node: Inspecting diagnostics<10>2773622
Ref: libraries/plackett_luce_last_ranker inspecting-diagnostics2773744
Ref: 11942773744
Node: Diagnostics syntax<18>2774037
Ref: libraries/plackett_luce_last_ranker diagnostics-syntax2774179
Ref: 11952774179
Node: Ranking candidate items<11>2775544
Ref: libraries/plackett_luce_last_ranker ranking-candidate-items2775683
Ref: 11962775683
Node: Exporting the ranker<10>2776238
Ref: libraries/plackett_luce_last_ranker exporting-the-ranker2776377
Ref: 11972776377
Node: Options<57>2776981
Ref: libraries/plackett_luce_last_ranker options2777139
Ref: 11982777139
Node: Ranker representation<12>2777525
Ref: libraries/plackett_luce_last_ranker ranker-representation2777672
Ref: 11992777672
Node: See also<5>2778378
Ref: libraries/plackett_luce_last_ranker see-also2778528
Ref: 119a2778528
Node: References<41>2778823
Ref: libraries/plackett_luce_last_ranker references2778939
Ref: 119b2778939
Node: pls_projection2779310
Ref: libraries/pls_projection doc2779458
Ref: 119c2779458
Ref: libraries/pls_projection library-pls-projection2779458
Ref: 119d2779458
Ref: libraries/pls_projection pls-projection2779458
Ref: 119e2779458
Node: API documentation<209>2780466
Ref: libraries/pls_projection api-documentation2780580
Ref: 119f2780580
Node: Loading<213>2780717
Ref: libraries/pls_projection loading2780852
Ref: 11a02780852
Node: Testing<204>2780989
Ref: libraries/pls_projection testing2781114
Ref: 11a12781114
Node: Features<60>2781262
Ref: libraries/pls_projection features2781386
Ref: 11a22781386
Node: Options<58>2782541
Ref: libraries/pls_projection options2782662
Ref: 11a32782662
Node: Usage<87>2783797
Ref: libraries/pls_projection usage2783941
Ref: 11a42783941
Node: Learning a reducer<5>2784384
Ref: libraries/pls_projection learning-a-reducer2784509
Ref: 11a52784509
Node: Transforming new instances<5>2784771
Ref: libraries/pls_projection transforming-new-instances2784941
Ref: 11a62784941
Node: Exporting and reusing the reducer<5>2785224
Ref: libraries/pls_projection exporting-and-reusing-the-reducer2785364
Ref: 11a72785364
Node: Dimension reducer representation<6>2785860
Ref: libraries/pls_projection dimension-reducer-representation2786007
Ref: 11a82786007
Node: References<42>2786933
Ref: libraries/pls_projection references2787062
Ref: 11a92787062
Node: prefix_span_pattern_miner2787340
Ref: libraries/prefix_span_pattern_miner doc2787491
Ref: 11aa2787491
Ref: libraries/prefix_span_pattern_miner library-prefix-span-pattern-miner2787491
Ref: 11ab2787491
Ref: libraries/prefix_span_pattern_miner prefix-span-pattern-miner2787491
Ref: 11ac2787491
Node: API documentation<210>2788363
Ref: libraries/prefix_span_pattern_miner api-documentation2788488
Ref: 11ad2788488
Node: Loading<214>2788636
Ref: libraries/prefix_span_pattern_miner loading2788782
Ref: 11ae2788782
Node: Testing<205>2788930
Ref: libraries/prefix_span_pattern_miner testing2789066
Ref: 11af2789066
Node: Features<61>2789225
Ref: libraries/prefix_span_pattern_miner features2789360
Ref: 11b02789360
Node: Options<59>2790008
Ref: libraries/prefix_span_pattern_miner options2790162
Ref: 11b12790162
Node: Pattern miner representation<6>2790855
Ref: libraries/prefix_span_pattern_miner pattern-miner-representation2791011
Ref: 11b22791011
Node: References<43>2791616
Ref: libraries/prefix_span_pattern_miner references2791752
Ref: 11b32791752
Node: probabilistic_pca_projection2791954
Ref: libraries/probabilistic_pca_projection doc2792098
Ref: 11b42792098
Ref: libraries/probabilistic_pca_projection library-probabilistic-pca-projection2792098
Ref: 11b52792098
Ref: libraries/probabilistic_pca_projection probabilistic-pca-projection2792098
Ref: 11b62792098
Node: API documentation<211>2793026
Ref: libraries/probabilistic_pca_projection api-documentation2793154
Ref: 11b72793154
Node: Loading<215>2793305
Ref: libraries/probabilistic_pca_projection loading2793454
Ref: 11b82793454
Node: Testing<206>2793605
Ref: libraries/probabilistic_pca_projection testing2793744
Ref: 11b92793744
Node: Features<62>2793906
Ref: libraries/probabilistic_pca_projection features2794044
Ref: 11ba2794044
Node: Options<60>2794922
Ref: libraries/probabilistic_pca_projection options2795057
Ref: 11bb2795057
Node: Usage<88>2796427
Ref: libraries/probabilistic_pca_projection usage2796585
Ref: 11bc2796585
Node: Learning a reducer<6>2797005
Ref: libraries/probabilistic_pca_projection learning-a-reducer2797130
Ref: 11bd2797130
Node: Transforming new instances<6>2797425
Ref: libraries/probabilistic_pca_projection transforming-new-instances2797595
Ref: 11be2797595
Node: Exporting and reusing the reducer<6>2797882
Ref: libraries/probabilistic_pca_projection exporting-and-reusing-the-reducer2798022
Ref: 11bf2798022
Node: Dimension reducer representation<7>2798532
Ref: libraries/probabilistic_pca_projection dimension-reducer-representation2798693
Ref: 11c02798693
Node: References<44>2800037
Ref: libraries/probabilistic_pca_projection references2800180
Ref: 11c12800180
Node: process2800418
Ref: libraries/process doc2800545
Ref: 11c22800545
Ref: libraries/process library-process2800545
Ref: 11c32800545
Ref: libraries/process process2800545
Ref: 11c42800545
Node: API documentation<212>2800918
Ref: libraries/process api-documentation2801025
Ref: 11c52801025
Node: Loading<216>2801155
Ref: libraries/process loading2801283
Ref: 11c62801283
Node: Testing<207>2801429
Ref: libraries/process testing2801544
Ref: 11c72801544
Node: Usage<89>2801685
Ref: libraries/process usage2801779
Ref: 11c82801779
Node: protobuf2803477
Ref: libraries/protobuf doc2803590
Ref: 11c92803590
Ref: libraries/protobuf library-protobuf2803590
Ref: 11ca2803590
Ref: libraries/protobuf protobuf2803590
Ref: 11cb2803590
Node: API documentation<213>2804441
Ref: libraries/protobuf api-documentation2804549
Ref: 11cc2804549
Node: Loading<217>2804680
Ref: libraries/protobuf loading2804809
Ref: 11cd2804809
Node: Testing<208>2804956
Ref: libraries/protobuf testing2805088
Ref: 11ce2805088
Node: Protocol Buffers Overview2805230
Ref: libraries/protobuf protocol-buffers-overview2805371
Ref: 11cf2805371
Node: Schema Representation2805635
Ref: libraries/protobuf schema-representation2805783
Ref: 11d02805783
Node: Supported Types2806328
Ref: libraries/protobuf supported-types2806448
Ref: 11d12806448
Node: Scalar Value Types2806552
Ref: libraries/protobuf scalar-value-types2806664
Ref: 11d22806664
Node: Complex Types2807927
Ref: libraries/protobuf complex-types2808039
Ref: 11d32808039
Node: Schema Examples<2>2808174
Ref: libraries/protobuf schema-examples2808294
Ref: 11d42808294
Node: Data Representation2808876
Ref: libraries/protobuf data-representation2809010
Ref: 11d52809010
Node: Encoding<9>2809524
Ref: libraries/protobuf encoding2809648
Ref: 11d62809648
Node: Simple Value Encoding2809856
Ref: libraries/protobuf simple-value-encoding2809970
Ref: 11d72809970
Node: Message Encoding2810329
Ref: libraries/protobuf message-encoding2810478
Ref: 11d82810478
Node: Including Schema in Output2810932
Ref: libraries/protobuf including-schema-in-output2811051
Ref: 11d92811051
Node: Decoding<9>2811472
Ref: libraries/protobuf decoding2811596
Ref: 11da2811596
Node: Parsing with Schema Embedded2811818
Ref: libraries/protobuf parsing-with-schema-embedded2811948
Ref: 11db2811948
Node: Parsing with Known Schema2812301
Ref: libraries/protobuf parsing-with-known-schema2812470
Ref: 11dc2812470
Node: Parsing from Different Sources2812902
Ref: libraries/protobuf parsing-from-different-sources2813034
Ref: 11dd2813034
Node: Wire Format Details2813321
Ref: libraries/protobuf wire-format-details2813461
Ref: 11de2813461
Node: Binary Format Compatibility2814010
Ref: libraries/protobuf binary-format-compatibility2814162
Ref: 11df2814162
Node: Examples and Test Files2814665
Ref: libraries/protobuf examples-and-test-files2814813
Ref: 11e02814813
Node: person proto2815113
Ref: libraries/protobuf person-proto2815231
Ref: 11e12815231
Ref: libraries/protobuf personproto2815231
Ref: 11e22815231
Node: addressbook proto2815605
Ref: libraries/protobuf addressbook-proto2815758
Ref: 11e32815758
Ref: libraries/protobuf addressbookproto2815758
Ref: 11e42815758
Node: Performance Considerations2816094
Ref: libraries/protobuf performance-considerations2816226
Ref: 11e52816226
Node: Further Reading2816727
Ref: libraries/protobuf further-reading2816839
Ref: 11e62816839
Node: qda_classifier2817166
Ref: libraries/qda_classifier doc2817278
Ref: 11e72817278
Ref: libraries/qda_classifier library-qda-classifier2817278
Ref: 11e82817278
Ref: libraries/qda_classifier qda-classifier2817278
Ref: 11e92817278
Node: API documentation<214>2818355
Ref: libraries/qda_classifier api-documentation2818469
Ref: 11ea2818469
Node: Loading<218>2818606
Ref: libraries/qda_classifier loading2818741
Ref: 11eb2818741
Node: Testing<209>2818878
Ref: libraries/qda_classifier testing2819003
Ref: 11ec2819003
Node: Features<63>2819151
Ref: libraries/qda_classifier features2819275
Ref: 11ed2819275
Node: Options<61>2819966
Ref: libraries/qda_classifier options2820087
Ref: 11ee2820087
Node: Usage<90>2820432
Ref: libraries/qda_classifier usage2820570
Ref: 11ef2820570
Node: Learning a classifier<6>2820762
Ref: libraries/qda_classifier learning-a-classifier2820882
Ref: 11f02820882
Node: Making predictions<6>2821089
Ref: libraries/qda_classifier making-predictions2821245
Ref: 11f12821245
Node: Exporting the classifier<6>2821680
Ref: libraries/qda_classifier exporting-the-classifier2821803
Ref: 11f22821803
Node: Classifier representation<10>2822171
Ref: libraries/qda_classifier classifier-representation2822312
Ref: 11f32822312
Node: References<45>2823027
Ref: libraries/qda_classifier references2823150
Ref: 11f42823150
Node: queues2823506
Ref: libraries/queues doc2823616
Ref: 11f52823616
Ref: libraries/queues library-queues2823616
Ref: 11f62823616
Ref: libraries/queues queues2823616
Ref: 11f72823616
Node: API documentation<215>2823920
Ref: libraries/queues api-documentation2824026
Ref: 11f82824026
Node: Loading<219>2824155
Ref: libraries/queues loading2824282
Ref: 11f92824282
Node: Testing<210>2824427
Ref: libraries/queues testing2824541
Ref: 11fa2824541
Node: Usage<91>2824681
Ref: libraries/queues usage2824774
Ref: 11fb2824774
Node: random2825615
Ref: libraries/random doc2825735
Ref: 11fc2825735
Ref: libraries/random library-random2825735
Ref: 11fd2825735
Ref: libraries/random random2825735
Ref: 11fe2825735
Node: API documentation<216>2826439
Ref: libraries/random api-documentation2826545
Ref: 11ff2826545
Node: Loading<220>2826674
Ref: libraries/random loading2826801
Ref: 12002826801
Node: Testing<211>2826946
Ref: libraries/random testing2827061
Ref: 12012827061
Node: Algorithms2827201
Ref: libraries/random algorithms2827313
Ref: 12022827313
Node: Usage<92>2828812
Ref: libraries/random usage2828903
Ref: 12032828903
Node: random_forest_classifier2831542
Ref: libraries/random_forest_classifier doc2831680
Ref: 12042831680
Ref: libraries/random_forest_classifier library-random-forest-classifier2831680
Ref: 12052831680
Ref: libraries/random_forest_classifier random-forest-classifier2831680
Ref: 12062831680
Node: API documentation<217>2832721
Ref: libraries/random_forest_classifier api-documentation2832845
Ref: 12072832845
Node: Loading<221>2832992
Ref: libraries/random_forest_classifier loading2833137
Ref: 12082833137
Node: Testing<212>2833300
Ref: libraries/random_forest_classifier testing2833435
Ref: 12092833435
Node: Features<64>2833593
Ref: libraries/random_forest_classifier features2833727
Ref: 120a2833727
Node: Options<62>2834653
Ref: libraries/random_forest_classifier options2834804
Ref: 120b2834804
Node: Classifier representation<11>2835447
Ref: libraries/random_forest_classifier classifier-representation2835600
Ref: 120c2835600
Node: References<46>2836201
Ref: libraries/random_forest_classifier references2836352
Ref: 120d2836352
Node: Usage<93>2836718
Ref: libraries/random_forest_classifier usage2836831
Ref: 120e2836831
Node: Learning a Classifier<5>2837135
Ref: libraries/random_forest_classifier learning-a-classifier2837255
Ref: 120f2837255
Node: Making Predictions<5>2837640
Ref: libraries/random_forest_classifier making-predictions2837796
Ref: 12102837796
Node: Exporting the Classifier<5>2838439
Ref: libraries/random_forest_classifier exporting-the-classifier2838598
Ref: 12112838598
Node: Using a Saved Classifier<2>2839143
Ref: libraries/random_forest_classifier using-a-saved-classifier2839307
Ref: 12122839307
Node: Printing the Classifier<2>2839652
Ref: libraries/random_forest_classifier printing-the-classifier2839780
Ref: 12132839780
Node: random_forest_regression2840293
Ref: libraries/random_forest_regression doc2840442
Ref: 12142840442
Ref: libraries/random_forest_regression library-random-forest-regression2840442
Ref: 12152840442
Ref: libraries/random_forest_regression random-forest-regression2840442
Ref: 12162840442
Node: API documentation<218>2841131
Ref: libraries/random_forest_regression api-documentation2841255
Ref: 12172841255
Node: Loading<222>2841402
Ref: libraries/random_forest_regression loading2841547
Ref: 12182841547
Node: Testing<213>2841694
Ref: libraries/random_forest_regression testing2841829
Ref: 12192841829
Node: Features<65>2842143
Ref: libraries/random_forest_regression features2842293
Ref: 121a2842293
Node: Regressor representation<8>2843729
Ref: libraries/random_forest_regression regressor-representation2843889
Ref: 121b2843889
Node: Diagnostics syntax<19>2844151
Ref: libraries/random_forest_regression diagnostics-syntax2844310
Ref: 121c2844310
Node: Options<63>2845573
Ref: libraries/random_forest_regression options2845696
Ref: 121d2845696
Node: random_projection2847422
Ref: libraries/random_projection doc2847562
Ref: 121e2847562
Ref: libraries/random_projection library-random-projection2847562
Ref: 121f2847562
Ref: libraries/random_projection random-projection2847562
Ref: 12202847562
Node: API documentation<219>2848384
Ref: libraries/random_projection api-documentation2848501
Ref: 12212848501
Node: Loading<223>2848641
Ref: libraries/random_projection loading2848779
Ref: 12222848779
Node: Testing<214>2848919
Ref: libraries/random_projection testing2849047
Ref: 12232849047
Node: Features<66>2849198
Ref: libraries/random_projection features2849325
Ref: 12242849325
Node: Options<64>2849956
Ref: libraries/random_projection options2850080
Ref: 12252850080
Node: Usage<94>2850718
Ref: libraries/random_projection usage2850865
Ref: 12262850865
Node: Learning a reducer<7>2851387
Ref: libraries/random_projection learning-a-reducer2851512
Ref: 12272851512
Node: Transforming new instances<7>2851777
Ref: libraries/random_projection transforming-new-instances2851947
Ref: 12282851947
Node: Exporting and reusing the reducer<7>2852459
Ref: libraries/random_projection exporting-and-reusing-the-reducer2852599
Ref: 12292852599
Node: Dimension reducer representation<8>2853093
Ref: libraries/random_projection dimension-reducer-representation2853243
Ref: 122a2853243
Node: References<47>2854085
Ref: libraries/random_projection references2854217
Ref: 122b2854217
Node: rank_centrality2854494
Ref: libraries/rank_centrality doc2854622
Ref: 122c2854622
Ref: libraries/rank_centrality library-rank-centrality2854622
Ref: 122d2854622
Ref: libraries/rank_centrality rank-centrality2854622
Ref: 122e2854622
Node: API documentation<220>2856137
Ref: libraries/rank_centrality api-documentation2856252
Ref: 122f2856252
Node: Loading<224>2856390
Ref: libraries/rank_centrality loading2856526
Ref: 12302856526
Node: Testing<215>2856664
Ref: libraries/rank_centrality testing2856790
Ref: 12312856790
Node: Features<67>2856939
Ref: libraries/rank_centrality features2857076
Ref: 12322857076
Node: Dataset requirements<4>2858391
Ref: libraries/rank_centrality dataset-requirements2858525
Ref: 12332858525
Node: Usage<95>2858971
Ref: libraries/rank_centrality usage2859115
Ref: 12342859115
Node: Learning a ranker<13>2859252
Ref: libraries/rank_centrality learning-a-ranker2859374
Ref: 12352859374
Node: Inspecting diagnostics<11>2859716
Ref: libraries/rank_centrality inspecting-diagnostics2859838
Ref: 12362859838
Node: Diagnostics syntax<20>2860111
Ref: libraries/rank_centrality diagnostics-syntax2860243
Ref: 12372860243
Node: Ranking candidate items<12>2862007
Ref: libraries/rank_centrality ranking-candidate-items2862146
Ref: 12382862146
Node: Exporting the ranker<11>2862681
Ref: libraries/rank_centrality exporting-the-ranker2862820
Ref: 12392862820
Node: Options<65>2863381
Ref: libraries/rank_centrality options2863529
Ref: 123a2863529
Node: Ranker representation<13>2863787
Ref: libraries/rank_centrality ranker-representation2863927
Ref: 123b2863927
Node: References<48>2864913
Ref: libraries/rank_centrality references2865033
Ref: 123c2865033
Node: ranked_pairs2865226
Ref: libraries/ranked_pairs doc2865354
Ref: 123d2865354
Ref: libraries/ranked_pairs library-ranked-pairs2865354
Ref: 123e2865354
Ref: libraries/ranked_pairs ranked-pairs2865354
Ref: 123f2865354
Node: API documentation<221>2866622
Ref: libraries/ranked_pairs api-documentation2866734
Ref: 12402866734
Node: Loading<225>2866869
Ref: libraries/ranked_pairs loading2867002
Ref: 12412867002
Node: Testing<216>2867137
Ref: libraries/ranked_pairs testing2867260
Ref: 12422867260
Node: Features<68>2867406
Ref: libraries/ranked_pairs features2867526
Ref: 12432867526
Node: Usage<96>2869024
Ref: libraries/ranked_pairs usage2869154
Ref: 12442869154
Node: Learning a ranker<14>2869425
Ref: libraries/ranked_pairs learning-a-ranker2869547
Ref: 12452869547
Node: Inspecting diagnostics<12>2870006
Ref: libraries/ranked_pairs inspecting-diagnostics2870164
Ref: 12462870164
Node: Ranking candidate items<13>2870431
Ref: libraries/ranked_pairs ranking-candidate-items2870591
Ref: 12472870591
Node: Inspecting locked pairs2871120
Ref: libraries/ranked_pairs inspecting-locked-pairs2871278
Ref: 12482871278
Node: Exporting the ranker<12>2871735
Ref: libraries/ranked_pairs exporting-the-ranker2871857
Ref: 12492871857
Node: Diagnostics syntax<21>2872403
Ref: libraries/ranked_pairs diagnostics-syntax2872532
Ref: 124a2872532
Node: Options<66>2873452
Ref: libraries/ranked_pairs options2873592
Ref: 124b2873592
Node: Scoring semantics<7>2874356
Ref: libraries/ranked_pairs scoring-semantics2874499
Ref: 124c2874499
Node: Ranker representation<14>2875164
Ref: libraries/ranked_pairs ranker-representation2875307
Ref: 124d2875307
Node: See also<6>2875967
Ref: libraries/ranked_pairs see-also2876081
Ref: 124e2876081
Node: ranking_protocols2876262
Ref: libraries/ranking_protocols doc2876381
Ref: 124f2876381
Ref: libraries/ranking_protocols library-ranking-protocols2876381
Ref: 12502876381
Ref: libraries/ranking_protocols ranking-protocols2876381
Ref: 12512876381
Node: Protocol requirements2877238
Ref: libraries/ranking_protocols protocol-requirements2877359
Ref: 12522877359
Node: Shared categories2878892
Ref: libraries/ranking_protocols shared-categories2879037
Ref: 12532879037
Node: Diagnostics<10>2880567
Ref: libraries/ranking_protocols diagnostics2880714
Ref: 12542880714
Node: Export header format<3>2881582
Ref: libraries/ranking_protocols export-header-format2881734
Ref: 12552881734
Node: API documentation<222>2882265
Ref: libraries/ranking_protocols api-documentation2882414
Ref: 12562882414
Node: Loading<226>2882554
Ref: libraries/ranking_protocols loading2882692
Ref: 12572882692
Node: Testing<217>2882848
Ref: libraries/ranking_protocols testing2882980
Ref: 12582882980
Node: Test datasets<6>2883144
Ref: libraries/ranking_protocols test-datasets2883255
Ref: 12592883255
Node: reader2887044
Ref: libraries/reader doc2887168
Ref: 125a2887168
Ref: libraries/reader library-reader2887168
Ref: 125b2887168
Ref: libraries/reader reader2887168
Ref: 125c2887168
Node: API documentation<223>2887584
Ref: libraries/reader api-documentation2887690
Ref: 125d2887690
Node: Loading<227>2887819
Ref: libraries/reader loading2887946
Ref: 125e2887946
Node: Testing<218>2888091
Ref: libraries/reader testing2888187
Ref: 125f2888187
Node: recorded_database2888327
Ref: libraries/recorded_database doc2888439
Ref: 12602888439
Ref: libraries/recorded_database library-recorded-database2888439
Ref: 12612888439
Ref: libraries/recorded_database recorded-database2888439
Ref: 12622888439
Node: API documentation<224>2888893
Ref: libraries/recorded_database api-documentation2889010
Ref: 12632889010
Node: Loading<228>2889150
Ref: libraries/recorded_database loading2889288
Ref: 12642889288
Node: Testing<219>2889444
Ref: libraries/recorded_database testing2889569
Ref: 12652889569
Node: Usage<97>2889720
Ref: libraries/recorded_database usage2889849
Ref: 12662889849
Node: Known issues<17>2890468
Ref: libraries/recorded_database known-issues2890576
Ref: 12672890576
Node: redis2890914
Ref: libraries/redis doc2891040
Ref: 12682891040
Ref: libraries/redis library-redis2891040
Ref: 12692891040
Ref: libraries/redis redis2891040
Ref: 126a2891040
Node: API documentation<225>2891480
Ref: libraries/redis api-documentation2891585
Ref: 126b2891585
Node: Loading<229>2891713
Ref: libraries/redis loading2891839
Ref: 126c2891839
Node: Testing<220>2891967
Ref: libraries/redis testing2892095
Ref: 126d2892095
Node: Supported Redis Features2892729
Ref: libraries/redis supported-redis-features2892855
Ref: 126e2892855
Node: Connection Management2893337
Ref: libraries/redis connection-management2893465
Ref: 126f2893465
Node: String Operations2893775
Ref: libraries/redis string-operations2893926
Ref: 12702893926
Node: Key Operations2894678
Ref: libraries/redis key-operations2894823
Ref: 12712894823
Node: Hash Operations2895271
Ref: libraries/redis hash-operations2895414
Ref: 12722895414
Node: List Operations2895961
Ref: libraries/redis list-operations2896104
Ref: 12732896104
Node: Set Operations2896638
Ref: libraries/redis set-operations2896787
Ref: 12742896787
Node: Sorted Set Operations2897143
Ref: libraries/redis sorted-set-operations2897291
Ref: 12752897291
Node: Usage Examples2897844
Ref: libraries/redis usage-examples2897969
Ref: 12762897969
Node: Credits<4>2899736
Ref: libraries/redis credits2899866
Ref: 12772899866
Node: Known issues<18>2899978
Ref: libraries/redis known-issues2900075
Ref: 12782900075
Node: regression_protocols2900495
Ref: libraries/regression_protocols doc2900619
Ref: 12792900619
Ref: libraries/regression_protocols library-regression-protocols2900619
Ref: 127a2900619
Ref: libraries/regression_protocols regression-protocols2900619
Ref: 127b2900619
Node: API documentation<226>2901619
Ref: libraries/regression_protocols api-documentation2901739
Ref: 127c2901739
Node: Loading<230>2901882
Ref: libraries/regression_protocols loading2902023
Ref: 127d2902023
Node: Testing<221>2902182
Ref: libraries/regression_protocols testing2902317
Ref: 127e2902317
Node: Test datasets<7>2902499
Ref: libraries/regression_protocols test-datasets2902613
Ref: 127f2902613
Node: regression_tree2904553
Ref: libraries/regression_tree doc2904704
Ref: 12802904704
Ref: libraries/regression_tree library-regression-tree2904704
Ref: 12812904704
Ref: libraries/regression_tree regression-tree2904704
Ref: 12822904704
Node: API documentation<227>2905395
Ref: libraries/regression_tree api-documentation2905510
Ref: 12832905510
Node: Loading<231>2905648
Ref: libraries/regression_tree loading2905784
Ref: 12842905784
Node: Testing<222>2905922
Ref: libraries/regression_tree testing2906059
Ref: 12852906059
Node: Export header format<4>2906355
Ref: libraries/regression_tree export-header-format2906492
Ref: 12862906492
Node: Features<69>2907252
Ref: libraries/regression_tree features2907404
Ref: 12872907404
Node: Regressor representation<9>2909000
Ref: libraries/regression_tree regressor-representation2909151
Ref: 12882909151
Node: Diagnostics syntax<22>2909583
Ref: libraries/regression_tree diagnostics-syntax2909733
Ref: 12892909733
Node: Options<67>2910865
Ref: libraries/regression_tree options2910979
Ref: 128a2910979
Node: regularized_bradley_terry_ranker2912201
Ref: libraries/regularized_bradley_terry_ranker doc2912336
Ref: 128b2912336
Ref: libraries/regularized_bradley_terry_ranker library-regularized-bradley-terry-ranker2912336
Ref: 128c2912336
Ref: libraries/regularized_bradley_terry_ranker regularized-bradley-terry-ranker2912336
Ref: 128d2912336
Node: API documentation<228>2913761
Ref: libraries/regularized_bradley_terry_ranker api-documentation2913893
Ref: 128e2913893
Node: Loading<232>2914048
Ref: libraries/regularized_bradley_terry_ranker loading2914201
Ref: 128f2914201
Node: Testing<223>2914356
Ref: libraries/regularized_bradley_terry_ranker testing2914499
Ref: 12902914499
Node: Features<70>2914665
Ref: libraries/regularized_bradley_terry_ranker features2914819
Ref: 12912914819
Node: Dataset requirements<5>2916032
Ref: libraries/regularized_bradley_terry_ranker dataset-requirements2916183
Ref: 12922916183
Node: Usage<98>2916902
Ref: libraries/regularized_bradley_terry_ranker usage2917063
Ref: 12932917063
Node: Learning a ranker<15>2917200
Ref: libraries/regularized_bradley_terry_ranker learning-a-ranker2917322
Ref: 12942917322
Node: Inspecting diagnostics<13>2917728
Ref: libraries/regularized_bradley_terry_ranker inspecting-diagnostics2917850
Ref: 12952917850
Node: Diagnostics syntax<23>2918165
Ref: libraries/regularized_bradley_terry_ranker diagnostics-syntax2918314
Ref: 12962918314
Node: Ranking candidate items<14>2919822
Ref: libraries/regularized_bradley_terry_ranker ranking-candidate-items2919961
Ref: 12972919961
Node: Exporting the ranker<13>2920530
Ref: libraries/regularized_bradley_terry_ranker exporting-the-ranker2920669
Ref: 12982920669
Node: Options<68>2921297
Ref: libraries/regularized_bradley_terry_ranker options2921462
Ref: 12992921462
Node: Ranker representation<15>2921871
Ref: libraries/regularized_bradley_terry_ranker ranker-representation2922028
Ref: 129a2922028
Node: References<49>2922732
Ref: libraries/regularized_bradley_terry_ranker references2922869
Ref: 129b2922869
Node: rest2923397
Ref: libraries/rest doc2923533
Ref: 129c2923533
Ref: libraries/rest library-rest2923533
Ref: 129d2923533
Ref: libraries/rest rest2923533
Ref: 129e2923533
Node: Layering<4>2924399
Ref: libraries/rest layering2924502
Ref: 129f2924502
Node: API documentation<229>2925328
Ref: libraries/rest api-documentation2925452
Ref: 12a02925452
Node: Loading<233>2925579
Ref: libraries/rest loading2925704
Ref: 12a12925704
Node: Testing<224>2925830
Ref: libraries/rest testing2925950
Ref: 12a22925950
Node: Current scope<25>2926077
Ref: libraries/rest current-scope2926204
Ref: 12a32926204
Node: OpenAPI integration2931649
Ref: libraries/rest openapi-integration2931787
Ref: 12a42931787
Node: Current limitations<18>2932335
Ref: libraries/rest current-limitations2932447
Ref: 12a52932447
Node: ridge_regression2932887
Ref: libraries/ridge_regression doc2932993
Ref: 12a62932993
Ref: libraries/ridge_regression library-ridge-regression2932993
Ref: 12a72932993
Ref: libraries/ridge_regression ridge-regression2932993
Ref: 12a82932993
Node: API documentation<230>2933813
Ref: libraries/ridge_regression api-documentation2933929
Ref: 12a92933929
Node: Loading<234>2934068
Ref: libraries/ridge_regression loading2934205
Ref: 12aa2934205
Node: Testing<225>2934344
Ref: libraries/ridge_regression testing2934471
Ref: 12ab2934471
Node: Features<71>2934769
Ref: libraries/ridge_regression features2934912
Ref: 12ac2934912
Node: Regressor representation<10>2936539
Ref: libraries/ridge_regression regressor-representation2936692
Ref: 12ad2936692
Node: Diagnostics syntax<24>2936993
Ref: libraries/ridge_regression diagnostics-syntax2937145
Ref: 12ae2937145
Node: Options<69>2939122
Ref: libraries/ridge_regression options2939237
Ref: 12af2939237
Node: s32939748
Ref: libraries/s3 doc2939864
Ref: 12b02939864
Ref: libraries/s3 library-s32939864
Ref: 12b12939864
Ref: libraries/s3 s32939864
Ref: 12b22939864
Node: API documentation<231>2940736
Ref: libraries/s3 api-documentation2940838
Ref: 12b32940838
Node: Loading<235>2940963
Ref: libraries/s3 loading2941086
Ref: 12b42941086
Node: Testing<226>2941210
Ref: libraries/s3 testing2941328
Ref: 12b52941328
Node: Current scope<26>2941453
Ref: libraries/s3 current-scope2941573
Ref: 12b62941573
Node: Basic usage<5>2942196
Ref: libraries/s3 basic-usage2942327
Ref: 12b72942327
Node: Current limitations<19>2947230
Ref: libraries/s3 current-limitations2947335
Ref: 12b82947335
Node: schulze_ranker2947738
Ref: libraries/schulze_ranker doc2947873
Ref: 12b92947873
Ref: libraries/schulze_ranker library-schulze-ranker2947873
Ref: 12ba2947873
Ref: libraries/schulze_ranker schulze-ranker2947873
Ref: 12bb2947873
Node: API documentation<232>2949030
Ref: libraries/schulze_ranker api-documentation2949144
Ref: 12bc2949144
Node: Loading<236>2949281
Ref: libraries/schulze_ranker loading2949416
Ref: 12bd2949416
Node: Testing<227>2949553
Ref: libraries/schulze_ranker testing2949678
Ref: 12be2949678
Node: Features<72>2949826
Ref: libraries/schulze_ranker features2949950
Ref: 12bf2949950
Node: Options<70>2951407
Ref: libraries/schulze_ranker options2951534
Ref: 12c02951534
Node: Strongest paths2951913
Ref: libraries/schulze_ranker strongest-paths2952050
Ref: 12c12952050
Node: Diagnostics syntax<25>2952613
Ref: libraries/schulze_ranker diagnostics-syntax2952764
Ref: 12c22952764
Node: Ranker representation<16>2953059
Ref: libraries/schulze_ranker ranker-representation2953186
Ref: 12c32953186
Node: sequential_pattern_mining_protocols2953634
Ref: libraries/sequential_pattern_mining_protocols doc2953771
Ref: 12c42953771
Ref: libraries/sequential_pattern_mining_protocols library-sequential-pattern-mining-protocols2953771
Ref: 12c52953771
Ref: libraries/sequential_pattern_mining_protocols sequential-pattern-mining-protocols2953771
Ref: 12c62953771
Node: API documentation<233>2954688
Ref: libraries/sequential_pattern_mining_protocols api-documentation2954823
Ref: 12c72954823
Node: Loading<237>2954981
Ref: libraries/sequential_pattern_mining_protocols loading2955137
Ref: 12c82955137
Node: Testing<228>2955311
Ref: libraries/sequential_pattern_mining_protocols testing2955461
Ref: 12c92955461
Node: Test datasets<8>2955629
Ref: libraries/sequential_pattern_mining_protocols test-datasets2955758
Ref: 12ca2955758
Node: sets2957775
Ref: libraries/sets doc2957912
Ref: 12cb2957912
Ref: libraries/sets library-sets2957912
Ref: 12cc2957912
Ref: libraries/sets sets2957912
Ref: 12cd2957912
Node: API documentation<234>2959274
Ref: libraries/sets api-documentation2959378
Ref: 12ce2959378
Node: Loading<238>2959505
Ref: libraries/sets loading2959630
Ref: 12cf2959630
Node: Testing<229>2959773
Ref: libraries/sets testing2959885
Ref: 12d02959885
Node: Usage<99>2960023
Ref: libraries/sets usage2960133
Ref: 12d12960133
Node: Credits<5>2962027
Ref: libraries/sets credits2962116
Ref: 12d22962116
Node: sgd_classifier2962215
Ref: libraries/sgd_classifier doc2962328
Ref: 12d32962328
Ref: libraries/sgd_classifier library-sgd-classifier2962328
Ref: 12d42962328
Ref: libraries/sgd_classifier sgd-classifier2962328
Ref: 12d52962328
Node: API documentation<235>2963455
Ref: libraries/sgd_classifier api-documentation2963569
Ref: 12d62963569
Node: Loading<239>2963706
Ref: libraries/sgd_classifier loading2963841
Ref: 12d72963841
Node: Testing<230>2963978
Ref: libraries/sgd_classifier testing2964103
Ref: 12d82964103
Node: Features<73>2964251
Ref: libraries/sgd_classifier features2964375
Ref: 12d92964375
Node: Options<71>2965183
Ref: libraries/sgd_classifier options2965305
Ref: 12da2965305
Node: Usage<100>2966242
Ref: libraries/sgd_classifier usage2966381
Ref: 12db2966381
Node: Learning a classifier<7>2966573
Ref: libraries/sgd_classifier learning-a-classifier2966694
Ref: 12dc2966694
Node: Making predictions<7>2966907
Ref: libraries/sgd_classifier making-predictions2967064
Ref: 12dd2967064
Node: Exporting the classifier<7>2967491
Ref: libraries/sgd_classifier exporting-the-classifier2967615
Ref: 12de2967615
Node: Classifier representation<12>2967971
Ref: libraries/sgd_classifier classifier-representation2968113
Ref: 12df2968113
Node: References<50>2968892
Ref: libraries/sgd_classifier references2969015
Ref: 12e02969015
Node: snowflakeid2969383
Ref: libraries/snowflakeid doc2969499
Ref: 12e12969499
Ref: libraries/snowflakeid library-snowflakeid2969499
Ref: 12e22969499
Ref: libraries/snowflakeid snowflakeid2969499
Ref: 12e32969499
Node: API documentation<236>2969966
Ref: libraries/snowflakeid api-documentation2970077
Ref: 12e42970077
Node: Loading<240>2970211
Ref: libraries/snowflakeid loading2970343
Ref: 12e52970343
Node: Testing<231>2970493
Ref: libraries/snowflakeid testing2970613
Ref: 12e62970613
Node: Usage<101>2970758
Ref: libraries/snowflakeid usage2970857
Ref: 12e72970857
Node: sockets2972140
Ref: libraries/sockets doc2972261
Ref: 12e82972261
Ref: libraries/sockets library-sockets2972261
Ref: 12e92972261
Ref: libraries/sockets sockets2972261
Ref: 12ea2972261
Node: Design rationale2972774
Ref: libraries/sockets design-rationale2972885
Ref: 12eb2972885
Node: API documentation<237>2973340
Ref: libraries/sockets api-documentation2973472
Ref: 12ec2973472
Node: Loading<241>2973602
Ref: libraries/sockets loading2973730
Ref: 12ed2973730
Node: Testing<232>2973860
Ref: libraries/sockets testing2973976
Ref: 12ee2973976
Node: Usage<102>2974117
Ref: libraries/sockets usage2974235
Ref: 12ef2974235
Node: Creating a client connection2974363
Ref: libraries/sockets creating-a-client-connection2974484
Ref: 12f02974484
Node: Creating a server2975000
Ref: libraries/sockets creating-a-server2975159
Ref: 12f12975159
Node: Getting the current host name2975814
Ref: libraries/sockets getting-the-current-host-name2975936
Ref: 12f22975936
Node: API Summary<3>2976054
Ref: libraries/sockets api-summary2976182
Ref: 12f32976182
Node: Backend-specific notes2977236
Ref: libraries/sockets backend-specific-notes2977370
Ref: 12f42977370
Node: Stream representation2977495
Ref: libraries/sockets stream-representation2977625
Ref: 12f52977625
Node: Binary and text modes2978114
Ref: libraries/sockets binary-and-text-modes2978244
Ref: 12f62978244
Node: Known issues<19>2978478
Ref: libraries/sockets known-issues2978589
Ref: 12f72978589
Node: spade_pattern_miner2978923
Ref: libraries/spade_pattern_miner doc2979052
Ref: 12f82979052
Ref: libraries/spade_pattern_miner library-spade-pattern-miner2979052
Ref: 12f92979052
Ref: libraries/spade_pattern_miner spade-pattern-miner2979052
Ref: 12fa2979052
Node: API documentation<238>2979962
Ref: libraries/spade_pattern_miner api-documentation2980081
Ref: 12fb2980081
Node: Loading<242>2980223
Ref: libraries/spade_pattern_miner loading2980363
Ref: 12fc2980363
Node: Testing<233>2980505
Ref: libraries/spade_pattern_miner testing2980635
Ref: 12fd2980635
Node: Features<74>2980788
Ref: libraries/spade_pattern_miner features2980917
Ref: 12fe2980917
Node: Options<72>2981924
Ref: libraries/spade_pattern_miner options2982072
Ref: 12ff2982072
Node: Pattern miner representation<7>2982765
Ref: libraries/spade_pattern_miner pattern-miner-representation2982915
Ref: 13002982915
Node: References<51>2983514
Ref: libraries/spade_pattern_miner references2983644
Ref: 13012983644
Node: simulated_annealing2983782
Ref: libraries/simulated_annealing doc2983914
Ref: 13022983914
Ref: libraries/simulated_annealing library-simulated-annealing2983914
Ref: 13032983914
Ref: libraries/simulated_annealing simulated-annealing2983914
Ref: 13042983914
Node: API documentation<239>2984971
Ref: libraries/simulated_annealing api-documentation2985090
Ref: 13052985090
Node: Loading<243>2985232
Ref: libraries/simulated_annealing loading2985372
Ref: 13062985372
Node: Testing<234>2985530
Ref: libraries/simulated_annealing testing2985660
Ref: 13072985660
Node: Features<75>2985813
Ref: libraries/simulated_annealing features2985949
Ref: 13082985949
Node: Defining a problem2988690
Ref: libraries/simulated_annealing defining-a-problem2988825
Ref: 13092988825
Node: Options<73>2990492
Ref: libraries/simulated_annealing options2990629
Ref: 130a2990629
Node: Run statistics2991832
Ref: libraries/simulated_annealing run-statistics2991961
Ref: 130b2991961
Node: Usage<103>2992400
Ref: libraries/simulated_annealing usage2992509
Ref: 130c2992509
Node: Defining a problem<2>2992809
Ref: libraries/simulated_annealing defining-a-problem-12992927
Ref: 130d2992927
Ref: libraries/simulated_annealing id12992927
Ref: 130e2992927
Node: Running the algorithm2993470
Ref: libraries/simulated_annealing running-the-algorithm2993624
Ref: 130f2993624
Node: Running with custom options2993793
Ref: libraries/simulated_annealing running-with-custom-options2993949
Ref: 13102993949
Node: Running with statistics2994150
Ref: libraries/simulated_annealing running-with-statistics2994312
Ref: 13112994312
Node: Reproducible runs with seed2994586
Ref: libraries/simulated_annealing reproducible-runs-with-seed2994739
Ref: 13122994739
Node: Reheating restarts2994974
Ref: libraries/simulated_annealing reheating-restarts2995131
Ref: 13132995131
Node: Auto-temperature estimation2995435
Ref: libraries/simulated_annealing auto-temperature-estimation2995603
Ref: 13142995603
Node: Using a custom random number generator2996040
Ref: libraries/simulated_annealing using-a-custom-random-number-generator2996181
Ref: 13152996181
Node: statistics2996605
Ref: libraries/statistics doc2996726
Ref: 13162996726
Ref: libraries/statistics library-statistics2996726
Ref: 13172996726
Ref: libraries/statistics statistics2996726
Ref: 13182996726
Node: API documentation<240>2997549
Ref: libraries/statistics api-documentation2997659
Ref: 13192997659
Node: Loading<244>2997792
Ref: libraries/statistics loading2997923
Ref: 131a2997923
Node: Testing<235>2998072
Ref: libraries/statistics testing2998193
Ref: 131b2998193
Node: API overview2998337
Ref: libraries/statistics api-overview2998437
Ref: 131c2998437
Node: Aggregation2998754
Ref: libraries/statistics aggregation2998861
Ref: 131d2998861
Node: Extremes and Range2999141
Ref: libraries/statistics extremes-and-range2999273
Ref: 131e2999273
Node: Central Tendency2999669
Ref: libraries/statistics central-tendency2999822
Ref: 131f2999822
Node: Measures of Position / Quantiles3000628
Ref: libraries/statistics id13000785
Ref: 13203000785
Ref: libraries/statistics measures-of-position-quantiles3000785
Ref: 13213000785
Node: Measures of Dispersion3001522
Ref: libraries/statistics measures-of-dispersion3001680
Ref: 13223001680
Node: Measures of Shape3003160
Ref: libraries/statistics measures-of-shape3003309
Ref: 13233003309
Node: Measures of Association3003762
Ref: libraries/statistics measures-of-association3003902
Ref: 13243003902
Node: Error Metrics3004390
Ref: libraries/statistics error-metrics3004526
Ref: 13253004526
Node: Normalization3004963
Ref: libraries/statistics normalization3005096
Ref: 13263005096
Node: Frequency / Counting3005528
Ref: libraries/statistics frequency-counting3005661
Ref: 13273005661
Ref: libraries/statistics id23005661
Ref: 13283005661
Node: Validation<2>3006001
Ref: libraries/statistics validation3006112
Ref: 13293006112
Node: stemming3006327
Ref: libraries/stemming doc3006434
Ref: 132a3006434
Ref: libraries/stemming library-stemming3006434
Ref: 132b3006434
Ref: libraries/stemming stemming3006434
Ref: 132c3006434
Node: API documentation<241>3007400
Ref: libraries/stemming api-documentation3007508
Ref: 132d3007508
Node: Loading<245>3007639
Ref: libraries/stemming loading3007768
Ref: 132e3007768
Node: Testing<236>3007915
Ref: libraries/stemming testing3008032
Ref: 132f3008032
Node: Usage<104>3008174
Ref: libraries/stemming usage3008292
Ref: 13303008292
Node: Porter Stemmer3008735
Ref: libraries/stemming porter-stemmer3008839
Ref: 13313008839
Node: Lovins Stemmer3009262
Ref: libraries/stemming lovins-stemmer3009366
Ref: 13323009366
Node: Algorithms<2>3009670
Ref: libraries/stemming algorithms3009797
Ref: 13333009797
Node: Porter Stemmer<2>3009920
Ref: libraries/stemming id13010033
Ref: 13343010033
Ref: libraries/stemming porter-stemmer-13010033
Ref: 13353010033
Node: Lovins Stemmer<2>3011000
Ref: libraries/stemming id23011113
Ref: 13363011113
Ref: libraries/stemming lovins-stemmer-13011113
Ref: 13373011113
Node: Choosing an Algorithm3012042
Ref: libraries/stemming choosing-an-algorithm3012179
Ref: 13383012179
Node: Known Limitations<3>3012629
Ref: libraries/stemming known-limitations3012744
Ref: 13393012744
Node: stomp3013064
Ref: libraries/stomp doc3013176
Ref: 133a3013176
Ref: libraries/stomp library-stomp3013176
Ref: 133b3013176
Ref: libraries/stomp stomp3013176
Ref: 133c3013176
Node: Protocol Version<2>3013825
Ref: libraries/stomp protocol-version3013927
Ref: 133d3013927
Node: Features<76>3014224
Ref: libraries/stomp features3014357
Ref: 133e3014357
Node: API documentation<242>3014845
Ref: libraries/stomp api-documentation3014971
Ref: 133f3014971
Node: Loading<246>3015099
Ref: libraries/stomp loading3015225
Ref: 13403015225
Node: Testing<237>3015353
Ref: libraries/stomp testing3015467
Ref: 13413015467
Node: Usage<105>3016191
Ref: libraries/stomp usage3016307
Ref: 13423016307
Node: Connecting to a STOMP server3016615
Ref: libraries/stomp connecting-to-a-stomp-server3016735
Ref: 13433016735
Node: Sending messages3017378
Ref: libraries/stomp sending-messages3017534
Ref: 13443017534
Node: Subscribing to destinations3018349
Ref: libraries/stomp subscribing-to-destinations3018495
Ref: 13453018495
Node: Receiving messages3018988
Ref: libraries/stomp receiving-messages3019140
Ref: 13463019140
Node: Acknowledging messages3019697
Ref: libraries/stomp acknowledging-messages3019835
Ref: 13473019835
Node: Unsubscribing3020284
Ref: libraries/stomp unsubscribing3020419
Ref: 13483020419
Node: Transactions<2>3020522
Ref: libraries/stomp transactions3020651
Ref: 13493020651
Node: Disconnecting<3>3020949
Ref: libraries/stomp disconnecting3021083
Ref: 134a3021083
Node: Heartbeat handling3021224
Ref: libraries/stomp heartbeat-handling3021362
Ref: 134b3021362
Node: Working with frames3021577
Ref: libraries/stomp working-with-frames3021690
Ref: 134c3021690
Node: API Summary<4>3022030
Ref: libraries/stomp api-summary3022152
Ref: 134d3022152
Node: Connection management<2>3022355
Ref: libraries/stomp connection-management3022468
Ref: 134e3022468
Node: Messaging3022754
Ref: libraries/stomp messaging3022890
Ref: 134f3022890
Node: Acknowledgment3023216
Ref: libraries/stomp acknowledgment3023343
Ref: 13503023343
Node: Transactions<3>3023528
Ref: libraries/stomp id13023655
Ref: 13513023655
Ref: libraries/stomp transactions-13023655
Ref: 13523023655
Node: Heartbeat3023940
Ref: libraries/stomp heartbeat3024069
Ref: 13533024069
Node: Frame inspection3024171
Ref: libraries/stomp frame-inspection3024276
Ref: 13543024276
Node: Connection Options3024579
Ref: libraries/stomp connection-options3024703
Ref: 13553024703
Node: Send Options3025037
Ref: libraries/stomp send-options3025164
Ref: 13563025164
Node: Subscribe Options3025534
Ref: libraries/stomp subscribe-options3025658
Ref: 13573025658
Node: Receive Options3025816
Ref: libraries/stomp receive-options3025945
Ref: 13583025945
Node: Error Handling<3>3026087
Ref: libraries/stomp error-handling3026190
Ref: 13593026190
Node: string_distance3026612
Ref: libraries/string_distance doc3026723
Ref: 135a3026723
Ref: libraries/string_distance library-string-distance3026723
Ref: 135b3026723
Ref: libraries/string_distance string-distance3026723
Ref: 135c3026723
Node: API documentation<243>3027454
Ref: libraries/string_distance api-documentation3027569
Ref: 135d3027569
Node: Loading<247>3027707
Ref: libraries/string_distance loading3027843
Ref: 135e3027843
Node: Testing<238>3027997
Ref: libraries/string_distance testing3028124
Ref: 135f3028124
Node: Algorithms<3>3028273
Ref: libraries/string_distance algorithms3028379
Ref: 13603028379
Node: strings3031513
Ref: libraries/strings doc3031631
Ref: 13613031631
Ref: libraries/strings library-strings3031631
Ref: 13623031631
Ref: libraries/strings strings3031631
Ref: 13633031631
Node: API documentation<244>3032424
Ref: libraries/strings api-documentation3032531
Ref: 13643032531
Node: Loading<248>3032661
Ref: libraries/strings loading3032789
Ref: 13653032789
Node: Testing<239>3032935
Ref: libraries/strings testing3033054
Ref: 13663033054
Node: Predicates<2>3033195
Ref: libraries/strings predicates3033293
Ref: 13673033293
Node: subsequences3034598
Ref: libraries/subsequences doc3034708
Ref: 13683034708
Ref: libraries/subsequences library-subsequences3034708
Ref: 13693034708
Ref: libraries/subsequences subsequences3034708
Ref: 136a3034708
Node: API documentation<245>3036389
Ref: libraries/subsequences api-documentation3036501
Ref: 136b3036501
Node: Loading<249>3036636
Ref: libraries/subsequences loading3036769
Ref: 136c3036769
Node: Testing<240>3036920
Ref: libraries/subsequences testing3037022
Ref: 136d3037022
Node: term_io3037168
Ref: libraries/term_io doc3037297
Ref: 136e3037297
Ref: libraries/term_io library-term-io3037297
Ref: 136f3037297
Ref: libraries/term_io term-io3037297
Ref: 13703037297
Node: API documentation<246>3037802
Ref: libraries/term_io api-documentation3037909
Ref: 13713037909
Node: Loading<250>3038039
Ref: libraries/term_io loading3038167
Ref: 13723038167
Node: Testing<241>3038313
Ref: libraries/term_io testing3038410
Ref: 13733038410
Node: thurstone_mosteller_ranker3038551
Ref: libraries/thurstone_mosteller_ranker doc3038679
Ref: 13743038679
Ref: libraries/thurstone_mosteller_ranker library-thurstone-mosteller-ranker3038679
Ref: 13753038679
Ref: libraries/thurstone_mosteller_ranker thurstone-mosteller-ranker3038679
Ref: 13763038679
Node: API documentation<247>3040001
Ref: libraries/thurstone_mosteller_ranker api-documentation3040127
Ref: 13773040127
Node: Loading<251>3040276
Ref: libraries/thurstone_mosteller_ranker loading3040423
Ref: 13783040423
Node: Testing<242>3040572
Ref: libraries/thurstone_mosteller_ranker testing3040709
Ref: 13793040709
Node: Features<77>3040869
Ref: libraries/thurstone_mosteller_ranker features3041014
Ref: 137a3041014
Node: Scoring semantics<8>3042082
Ref: libraries/thurstone_mosteller_ranker scoring-semantics3042226
Ref: 137b3042226
Node: Options<74>3042939
Ref: libraries/thurstone_mosteller_ranker options3043093
Ref: 137c3043093
Node: Diagnostics syntax<26>3043271
Ref: libraries/thurstone_mosteller_ranker diagnostics-syntax3043430
Ref: 137d3043430
Node: Ranker representation<17>3043781
Ref: libraries/thurstone_mosteller_ranker ranker-representation3043920
Ref: 137e3043920
Node: time_scales3044338
Ref: libraries/time_scales doc3044466
Ref: 137f3044466
Ref: libraries/time_scales library-time-scales3044466
Ref: 13803044466
Ref: libraries/time_scales time-scales3044466
Ref: 13813044466
Node: API documentation<248>3045248
Ref: libraries/time_scales api-documentation3045359
Ref: 13823045359
Node: Loading<252>3045493
Ref: libraries/time_scales loading3045625
Ref: 13833045625
Node: Testing<243>3045775
Ref: libraries/time_scales testing3045897
Ref: 13843045897
Node: Features<78>3046042
Ref: libraries/time_scales features3046166
Ref: 13853046166
Node: Limitations<5>3047146
Ref: libraries/time_scales limitations3047276
Ref: 13863047276
Node: Representation<18>3047817
Ref: libraries/time_scales representation3047948
Ref: 13873047948
Node: Examples<176>3048446
Ref: libraries/time_scales examples3048554
Ref: 13883048554
Node: timeout3050684
Ref: libraries/timeout doc3050796
Ref: 13893050796
Ref: libraries/timeout library-timeout3050796
Ref: 138a3050796
Ref: libraries/timeout timeout3050796
Ref: 138b3050796
Node: API documentation<249>3051443
Ref: libraries/timeout api-documentation3051550
Ref: 138c3051550
Node: Loading<253>3051680
Ref: libraries/timeout loading3051808
Ref: 138d3051808
Node: Testing<244>3051954
Ref: libraries/timeout testing3052076
Ref: 138e3052076
Node: Known issues<20>3052217
Ref: libraries/timeout known-issues3052318
Ref: 138f3052318
Node: tle_orbits3052763
Ref: libraries/tle_orbits doc3052868
Ref: 13903052868
Ref: libraries/tle_orbits library-tle-orbits3052868
Ref: 13913052868
Ref: libraries/tle_orbits tle-orbits3052868
Ref: 13923052868
Node: API documentation<250>3053962
Ref: libraries/tle_orbits api-documentation3054072
Ref: 13933054072
Node: Loading<254>3054205
Ref: libraries/tle_orbits loading3054336
Ref: 13943054336
Node: Testing<245>3054485
Ref: libraries/tle_orbits testing3054612
Ref: 13953054612
Node: Representation<19>3054756
Ref: libraries/tle_orbits representation3054884
Ref: 13963054884
Node: Public API<4>3055613
Ref: libraries/tle_orbits public-api3055742
Ref: 13973055742
Node: Examples<177>3057609
Ref: libraries/tle_orbits examples3057729
Ref: 13983057729
Node: Notes<11>3059185
Ref: libraries/tle_orbits notes3059283
Ref: 13993059283
Node: toml3060302
Ref: libraries/toml doc3060404
Ref: 139a3060404
Ref: libraries/toml library-toml3060404
Ref: 139b3060404
Ref: libraries/toml toml3060404
Ref: 139c3060404
Node: API documentation<251>3061013
Ref: libraries/toml api-documentation3061117
Ref: 139d3061117
Node: Loading<255>3061244
Ref: libraries/toml loading3061369
Ref: 139e3061369
Node: Testing<246>3061512
Ref: libraries/toml testing3061621
Ref: 139f3061621
Node: Status3061759
Ref: libraries/toml status3061874
Ref: 13a03061874
Node: Representation<20>3062424
Ref: libraries/toml representation3062540
Ref: 13a13062540
Node: Examples<178>3064251
Ref: libraries/toml examples3064370
Ref: 13a23064370
Node: Parsing a TOML String3064505
Ref: libraries/toml parsing-a-toml-string3064644
Ref: 13a33064644
Node: Parsing with Curly Table Representation3064853
Ref: libraries/toml parsing-with-curly-table-representation3065016
Ref: 13a43065016
Node: Generating TOML3065267
Ref: libraries/toml generating-toml3065400
Ref: 13a53065400
Node: Notes<12>3065603
Ref: libraries/toml notes3065695
Ref: 13a63065695
Node: toon3065925
Ref: libraries/toon doc3066041
Ref: 13a73066041
Ref: libraries/toon library-toon3066041
Ref: 13a83066041
Ref: libraries/toon toon3066041
Ref: 13a93066041
Node: API documentation<252>3066611
Ref: libraries/toon api-documentation3066715
Ref: 13aa3066715
Node: Loading<256>3066842
Ref: libraries/toon loading3066967
Ref: 13ab3066967
Node: Testing<247>3067110
Ref: libraries/toon testing3067231
Ref: 13ac3067231
Node: Representation<21>3067369
Ref: libraries/toon representation3067498
Ref: 13ad3067498
Node: Objects<2>3068156
Ref: libraries/toon objects3068256
Ref: 13ae3068256
Node: Arrays3068519
Ref: libraries/toon arrays3068638
Ref: 13af3068638
Node: Primitives3068744
Ref: libraries/toon primitives3068844
Ref: 13b03068844
Node: TOON format features3069128
Ref: libraries/toon toon-format-features3069262
Ref: 13b13069262
Node: Usage examples<3>3069817
Ref: libraries/toon usage-examples3069924
Ref: 13b23069924
Node: truncated_svd_projection3070571
Ref: libraries/truncated_svd_projection doc3070686
Ref: 13b33070686
Ref: libraries/truncated_svd_projection library-truncated-svd-projection3070686
Ref: 13b43070686
Ref: libraries/truncated_svd_projection truncated-svd-projection3070686
Ref: 13b53070686
Node: API documentation<253>3071482
Ref: libraries/truncated_svd_projection api-documentation3071606
Ref: 13b63071606
Node: Loading<257>3071753
Ref: libraries/truncated_svd_projection loading3071898
Ref: 13b73071898
Node: Testing<248>3072045
Ref: libraries/truncated_svd_projection testing3072180
Ref: 13b83072180
Node: Features<79>3072338
Ref: libraries/truncated_svd_projection features3072472
Ref: 13b93072472
Node: Options<75>3073434
Ref: libraries/truncated_svd_projection options3073566
Ref: 13ba3073566
Node: Usage<106>3075067
Ref: libraries/truncated_svd_projection usage3075222
Ref: 13bb3075222
Node: Learning a reducer<8>3075646
Ref: libraries/truncated_svd_projection learning-a-reducer3075772
Ref: 13bc3075772
Node: Transforming new instances<8>3076101
Ref: libraries/truncated_svd_projection transforming-new-instances3076272
Ref: 13bd3076272
Node: Exporting and reusing the reducer<8>3076539
Ref: libraries/truncated_svd_projection exporting-and-reusing-the-reducer3076680
Ref: 13be3076680
Node: Dimension reducer representation<9>3077181
Ref: libraries/truncated_svd_projection dimension-reducer-representation3077339
Ref: 13bf3077339
Node: References<52>3078122
Ref: libraries/truncated_svd_projection references3078261
Ref: 13c03078261
Node: tsv3078409
Ref: libraries/tsv doc3078525
Ref: 13c13078525
Ref: libraries/tsv library-tsv3078525
Ref: 13c23078525
Ref: libraries/tsv tsv3078525
Ref: 13c33078525
Node: API documentation<254>3079992
Ref: libraries/tsv api-documentation3080095
Ref: 13c43080095
Node: Loading<258>3080221
Ref: libraries/tsv loading3080345
Ref: 13c53080345
Node: Testing<249>3080487
Ref: libraries/tsv testing3080599
Ref: 13c63080599
Node: Usage<107>3080736
Ref: libraries/tsv usage3080827
Ref: 13c73080827
Node: types3081719
Ref: libraries/types doc3081815
Ref: 13c83081815
Ref: libraries/types library-types3081815
Ref: 14c3081815
Ref: libraries/types types3081815
Ref: 13c93081815
Node: API documentation<255>3082712
Ref: libraries/types api-documentation3082817
Ref: 13ca3082817
Node: Loading<259>3082945
Ref: libraries/types loading3083071
Ref: 13cb3083071
Node: Testing<250>3083418
Ref: libraries/types testing3083538
Ref: 13cc3083538
Node: Type-checking<2>3083677
Ref: libraries/types type-checking3083803
Ref: 13cd3083803
Node: Defining new types3084775
Ref: libraries/types defining-new-types3084902
Ref: 13ce3084902
Node: Examples<179>3085956
Ref: libraries/types examples3086058
Ref: 13cf3086058
Node: tzif3086300
Ref: libraries/tzif doc3086397
Ref: 13d03086397
Ref: libraries/tzif library-tzif3086397
Ref: 13d13086397
Ref: libraries/tzif tzif3086397
Ref: 13d23086397
Node: API documentation<256>3088775
Ref: libraries/tzif api-documentation3088879
Ref: 13d33088879
Node: Loading<260>3089006
Ref: libraries/tzif loading3089131
Ref: 13d43089131
Node: Testing<251>3089274
Ref: libraries/tzif testing3089395
Ref: 13d53089395
Node: Representation<22>3089533
Ref: libraries/tzif representation3089668
Ref: 13d63089668
Node: Zone identifier validation3090907
Ref: libraries/tzif zone-identifier-validation3091043
Ref: 13d73091043
Node: Local Queries3091630
Ref: libraries/tzif local-queries3091761
Ref: 13d83091761
Node: Examples<180>3093245
Ref: libraries/tzif examples3093366
Ref: 13d93093366
Node: Known issues<21>3095126
Ref: libraries/tzif known-issues3095225
Ref: 13da3095225
Node: ulid3095567
Ref: libraries/ulid doc3095671
Ref: 13db3095671
Ref: libraries/ulid library-ulid3095671
Ref: 13dc3095671
Ref: libraries/ulid ulid3095671
Ref: 13dd3095671
Node: API documentation<257>3096655
Ref: libraries/ulid api-documentation3096759
Ref: 13de3096759
Node: Loading<261>3096886
Ref: libraries/ulid loading3097011
Ref: 13df3097011
Node: Testing<252>3097154
Ref: libraries/ulid testing3097273
Ref: 13e03097273
Node: Generating ULIDs3097411
Ref: libraries/ulid generating-ulids3097537
Ref: 13e13097537
Node: Type-checking ULIDs3099413
Ref: libraries/ulid type-checking-ulids3099518
Ref: 13e23099518
Node: unicode_data3099858
Ref: libraries/unicode_data doc3099968
Ref: 13e33099968
Ref: libraries/unicode_data library-unicode-data3099968
Ref: 13e43099968
Ref: libraries/unicode_data unicode-data3099968
Ref: 13e53099968
Node: Authors3100264
Ref: libraries/unicode_data authors3100356
Ref: 13e63100356
Node: License3100456
Ref: libraries/unicode_data license3100564
Ref: 13e73100564
Node: Website3100849
Ref: libraries/unicode_data website3100966
Ref: 13e83100966
Node: Description<165>3101268
Ref: libraries/unicode_data description3101393
Ref: 13e93101393
Node: Requirements<8>3102006
Ref: libraries/unicode_data requirements3102134
Ref: 13ea3102134
Node: Usage<108>3102546
Ref: libraries/unicode_data usage3102674
Ref: 13eb3102674
Node: Known issues<22>3103124
Ref: libraries/unicode_data known-issues3103253
Ref: 13ec3103253
Node: Acknowledgements3103917
Ref: libraries/unicode_data acknowledgements3104057
Ref: 13ed3104057
Node: Files and API Summary3104205
Ref: libraries/unicode_data files-and-api-summary3104320
Ref: 13ee3104320
Node: unicode_arabic_shaping pl3107496
Ref: libraries/unicode_data unicode-arabic-shaping-pl3107633
Ref: 13ef3107633
Ref: libraries/unicode_data unicode-arabic-shapingpl3107633
Ref: 13f03107633
Node: unicode_bidi_mirroring pl3107788
Ref: libraries/unicode_data unicode-bidi-mirroring-pl3107951
Ref: 13f13107951
Ref: libraries/unicode_data unicode-bidi-mirroringpl3107951
Ref: 13f23107951
Node: unicode_blocks pl3108106
Ref: libraries/unicode_data unicode-blocks-pl3108267
Ref: 13f33108267
Ref: libraries/unicode_data unicode-blockspl3108267
Ref: 13f43108267
Node: unicode_case_folding pl3108399
Ref: libraries/unicode_data unicode-case-folding-pl3108556
Ref: 13f53108556
Ref: libraries/unicode_data unicode-case-foldingpl3108556
Ref: 13f63108556
Node: unicode_categories pl3108705
Ref: libraries/unicode_data unicode-categories-pl3108868
Ref: 13f73108868
Ref: libraries/unicode_data unicode-categoriespl3108868
Ref: 13f83108868
Node: unicode_cjk_radicals pl3109050
Ref: libraries/unicode_data unicode-cjk-radicals-pl3109223
Ref: 13f93109223
Ref: libraries/unicode_data unicode-cjk-radicalspl3109223
Ref: 13fa3109223
Node: unicode_composition_exclusions pl3109371
Ref: libraries/unicode_data unicode-composition-exclusions-pl3109549
Ref: 13fb3109549
Ref: libraries/unicode_data unicode-composition-exclusionspl3109549
Ref: 13fc3109549
Node: unicode_core_properties pl3109727
Ref: libraries/unicode_data unicode-core-properties-pl3109911
Ref: 13fd3109911
Ref: libraries/unicode_data unicode-core-propertiespl3109911
Ref: 13fe3109911
Node: unicode_decomposition_type pl3110796
Ref: libraries/unicode_data unicode-decomposition-type-pl3110969
Ref: 13ff3110969
Ref: libraries/unicode_data unicode-decomposition-typepl3110969
Ref: 14003110969
Node: unicode_derived_age pl3111601
Ref: libraries/unicode_data unicode-derived-age-pl3111777
Ref: 14013111777
Ref: libraries/unicode_data unicode-derived-agepl3111777
Ref: 14023111777
Node: unicode_derived_bidi_class pl3111919
Ref: libraries/unicode_data unicode-derived-bidi-class-pl3112100
Ref: 14033112100
Ref: libraries/unicode_data unicode-derived-bidi-classpl3112100
Ref: 14043112100
Node: unicode_derived_combining_class pl3112263
Ref: libraries/unicode_data unicode-derived-combining-class-pl3112456
Ref: 14053112456
Ref: libraries/unicode_data unicode-derived-combining-classpl3112456
Ref: 14063112456
Node: unicode_derived_core_properties pl3112634
Ref: libraries/unicode_data unicode-derived-core-properties-pl3112835
Ref: 14073112835
Ref: libraries/unicode_data unicode-derived-core-propertiespl3112835
Ref: 14083112835
Node: unicode_derived_decomposition_type pl3113011
Ref: libraries/unicode_data unicode-derived-decomposition-type-pl3113213
Ref: 14093113213
Ref: libraries/unicode_data unicode-derived-decomposition-typepl3113213
Ref: 140a3113213
Node: unicode_derived_east_asian_width pl3113400
Ref: libraries/unicode_data unicode-derived-east-asian-width-pl3113600
Ref: 140b3113600
Ref: libraries/unicode_data unicode-derived-east-asian-widthpl3113600
Ref: 140c3113600
Node: unicode_derived_joining_group pl3113781
Ref: libraries/unicode_data unicode-derived-joining-group-pl3113975
Ref: 140d3113975
Ref: libraries/unicode_data unicode-derived-joining-grouppl3113975
Ref: 140e3113975
Node: unicode_derived_joining_type pl3114147
Ref: libraries/unicode_data unicode-derived-joining-type-pl3114335
Ref: 140f3114335
Ref: libraries/unicode_data unicode-derived-joining-typepl3114335
Ref: 14103114335
Node: unicode_derived_line_break pl3114504
Ref: libraries/unicode_data unicode-derived-line-break-pl3114698
Ref: 14113114698
Ref: libraries/unicode_data unicode-derived-line-breakpl3114698
Ref: 14123114698
Node: unicode_derived_normalization_props pl3114861
Ref: libraries/unicode_data unicode-derived-normalization-props-pl3115055
Ref: 14133115055
Ref: libraries/unicode_data unicode-derived-normalization-propspl3115055
Ref: 14143115055
Node: unicode_derived_numeric_type pl3115756
Ref: libraries/unicode_data unicode-derived-numeric-type-pl3115954
Ref: 14153115954
Ref: libraries/unicode_data unicode-derived-numeric-typepl3115954
Ref: 14163115954
Node: unicode_derived_numeric_values pl3116123
Ref: libraries/unicode_data unicode-derived-numeric-values-pl3116314
Ref: 14173116314
Ref: libraries/unicode_data unicode-derived-numeric-valuespl3116314
Ref: 14183116314
Node: unicode_hangul_syllable_type pl3116488
Ref: libraries/unicode_data unicode-hangul-syllable-type-pl3116679
Ref: 14193116679
Ref: libraries/unicode_data unicode-hangul-syllable-typepl3116679
Ref: 141a3116679
Node: unicode_indic_matra_category pl3116856
Ref: libraries/unicode_data unicode-indic-matra-category-pl3117048
Ref: 141b3117048
Ref: libraries/unicode_data unicode-indic-matra-categorypl3117048
Ref: 141c3117048
Node: unicode_indic_syllabic_category pl3117225
Ref: libraries/unicode_data unicode-indic-syllabic-category-pl3117401
Ref: 141d3117401
Ref: libraries/unicode_data unicode-indic-syllabic-categorypl3117401
Ref: 141e3117401
Node: unicode_jamo pl3117587
Ref: libraries/unicode_data unicode-jamo-pl3117755
Ref: 141f3117755
Ref: libraries/unicode_data unicode-jamopl3117755
Ref: 14203117755
Node: unicode_name_aliases pl3117882
Ref: libraries/unicode_data unicode-name-aliases-pl3118032
Ref: 14213118032
Ref: libraries/unicode_data unicode-name-aliasespl3118032
Ref: 14223118032
Node: unicode_names pl3118181
Ref: libraries/unicode_data unicode-names-pl3118336
Ref: 14233118336
Ref: libraries/unicode_data unicode-namespl3118336
Ref: 14243118336
Node: unicode_prop_list pl3118501
Ref: libraries/unicode_data unicode-prop-list-pl3118657
Ref: 14253118657
Ref: libraries/unicode_data unicode-prop-listpl3118657
Ref: 14263118657
Node: unicode_range_scripts pl3119949
Ref: libraries/unicode_data unicode-range-scripts-pl3120117
Ref: 14273120117
Ref: libraries/unicode_data unicode-range-scriptspl3120117
Ref: 14283120117
Node: unicode_script_extensions pl3120293
Ref: libraries/unicode_data unicode-script-extensions-pl3120459
Ref: 14293120459
Ref: libraries/unicode_data unicode-script-extensionspl3120459
Ref: 142a3120459
Node: unicode_scripts pl3120644
Ref: libraries/unicode_data unicode-scripts-pl3120811
Ref: 142b3120811
Ref: libraries/unicode_data unicode-scriptspl3120811
Ref: 142c3120811
Node: unicode_special_casing pl3120978
Ref: libraries/unicode_data unicode-special-casing-pl3121143
Ref: 142d3121143
Ref: libraries/unicode_data unicode-special-casingpl3121143
Ref: 142e3121143
Node: unicode_unihan_variants pl3121300
Ref: libraries/unicode_data unicode-unihan-variants-pl3121465
Ref: 142f3121465
Ref: libraries/unicode_data unicode-unihan-variantspl3121465
Ref: 14303121465
Node: unicode_version pl3121626
Ref: libraries/unicode_data unicode-version-pl3121757
Ref: 14313121757
Ref: libraries/unicode_data unicode-versionpl3121757
Ref: 14323121757
Node: union_find3121893
Ref: libraries/union_find doc3122002
Ref: 14333122002
Ref: libraries/union_find library-union-find3122002
Ref: 14343122002
Ref: libraries/union_find union-find3122002
Ref: 14353122002
Node: API documentation<258>3123104
Ref: libraries/union_find api-documentation3123214
Ref: 14363123214
Node: Loading<262>3123347
Ref: libraries/union_find loading3123478
Ref: 14373123478
Node: Testing<253>3123627
Ref: libraries/union_find testing3123746
Ref: 14383123746
Node: Usage<109>3123890
Ref: libraries/union_find usage3123988
Ref: 14393123988
Node: url3125446
Ref: libraries/url doc3125547
Ref: 143a3125547
Ref: libraries/url library-url3125547
Ref: 143b3125547
Ref: libraries/url url3125547
Ref: 143c3125547
Node: API documentation<259>3127116
Ref: libraries/url api-documentation3127219
Ref: 143d3127219
Node: Loading<263>3127345
Ref: libraries/url loading3127469
Ref: 143e3127469
Node: Testing<254>3127611
Ref: libraries/url testing3127723
Ref: 143f3127723
Node: Usage<110>3127860
Ref: libraries/url usage3127951
Ref: 14403127951
Node: uuid3129872
Ref: libraries/uuid doc3129974
Ref: 14413129974
Ref: libraries/uuid library-uuid3129974
Ref: 14423129974
Ref: libraries/uuid uuid3129974
Ref: 14433129974
Node: API documentation<260>3132087
Ref: libraries/uuid api-documentation3132191
Ref: 14443132191
Node: Loading<264>3132318
Ref: libraries/uuid loading3132443
Ref: 14453132443
Node: Testing<255>3132586
Ref: libraries/uuid testing3132715
Ref: 14463132715
Node: Generating version 1 UUIDs3132853
Ref: libraries/uuid generating-version-1-uuids3132996
Ref: 14473132996
Node: Generating version 4 UUIDs3134170
Ref: libraries/uuid generating-version-4-uuids3134327
Ref: 14483134327
Node: Generating version 3 UUIDs3135121
Ref: libraries/uuid generating-version-3-uuids3135278
Ref: 14493135278
Node: Generating version 5 UUIDs3136269
Ref: libraries/uuid generating-version-5-uuids3136426
Ref: 144a3136426
Node: Generating version 7 UUIDs3137528
Ref: libraries/uuid generating-version-7-uuids3137691
Ref: 144b3137691
Node: Generating the Nil and Max UUIDs3138838
Ref: libraries/uuid generating-the-nil-and-max-uuids3138966
Ref: 144c3138966
Node: validations3139300
Ref: libraries/validations doc3139406
Ref: 144d3139406
Ref: libraries/validations library-validations3139406
Ref: 144e3139406
Ref: libraries/validations validations3139406
Ref: 144f3139406
Node: API documentation<261>3140395
Ref: libraries/validations api-documentation3140506
Ref: 14503140506
Node: Loading<265>3140640
Ref: libraries/validations loading3140772
Ref: 14513140772
Node: Testing<256>3140922
Ref: libraries/validations testing3141042
Ref: 14523141042
Node: Usage<111>3141187
Ref: libraries/validations usage3141332
Ref: 14533141332
Node: Comparison with the expecteds library3144149
Ref: libraries/validations comparison-with-the-expecteds-library3144293
Ref: 14543144293
Node: Example form validation with error accumulation3145272
Ref: libraries/validations example-form-validation-with-error-accumulation3145413
Ref: 14553145413
Node: See also<7>3147315
Ref: libraries/validations see-also3147440
Ref: 14563147440
Node: wkt_wkb3147527
Ref: libraries/wkt_wkb doc3147633
Ref: 14573147633
Ref: libraries/wkt_wkb library-wkt-wkb3147633
Ref: 14583147633
Ref: libraries/wkt_wkb wkt-wkb3147633
Ref: 14593147633
Node: API documentation<262>3148303
Ref: libraries/wkt_wkb api-documentation3148410
Ref: 145a3148410
Node: Loading<266>3148540
Ref: libraries/wkt_wkb loading3148668
Ref: 145b3148668
Node: Testing<257>3148814
Ref: libraries/wkt_wkb testing3148938
Ref: 145c3148938
Node: Representation<23>3149079
Ref: libraries/wkt_wkb representation3149208
Ref: 145d3149208
Node: Sources and sinks3150497
Ref: libraries/wkt_wkb sources-and-sinks3150627
Ref: 145e3150627
Node: Examples<181>3151290
Ref: libraries/wkt_wkb examples3151411
Ref: 145f3151411
Node: Notes<13>3152365
Ref: libraries/wkt_wkb notes3152460
Ref: 14603152460
Node: yaml3153306
Ref: libraries/yaml doc3153425
Ref: 14613153425
Ref: libraries/yaml library-yaml3153425
Ref: 14623153425
Ref: libraries/yaml yaml3153425
Ref: 14633153425
Node: API documentation<263>3154158
Ref: libraries/yaml api-documentation3154262
Ref: 14643154262
Node: Loading<267>3154389
Ref: libraries/yaml loading3154514
Ref: 14653154514
Node: Testing<258>3154657
Ref: libraries/yaml testing3154763
Ref: 14663154763
Node: API3154901
Ref: libraries/yaml api3155017
Ref: 14673155017
Node: Parsing<3>3155161
Ref: libraries/yaml parsing3155253
Ref: 14683155253
Node: Generating<3>3155821
Ref: libraries/yaml generating3155944
Ref: 14693155944
Node: Multi-Document Parsing3156508
Ref: libraries/yaml multi-document-parsing3156646
Ref: 146a3156646
Node: Multi-Document Generation3156991
Ref: libraries/yaml multi-document-generation3157107
Ref: 146b3157107
Node: Data Representation<2>3157438
Ref: libraries/yaml data-representation3157555
Ref: 146c3157555
Node: Examples<182>3158222
Ref: libraries/yaml examples3158348
Ref: 146d3158348
Node: Parsing a Simple YAML String3158571
Ref: libraries/yaml parsing-a-simple-yaml-string3158697
Ref: 146e3158697
Node: Parsing a YAML List3158868
Ref: libraries/yaml parsing-a-yaml-list3159022
Ref: 146f3159022
Node: Parsing a YAML File3159177
Ref: libraries/yaml parsing-a-yaml-file3159330
Ref: 14703159330
Node: Generating YAML from a Term3159470
Ref: libraries/yaml generating-yaml-from-a-term3159629
Ref: 14713159629
Node: Generating YAML to a File3159818
Ref: libraries/yaml generating-yaml-to-a-file3159988
Ref: 14723159988
Node: Working with Nested Structures3160193
Ref: libraries/yaml working-with-nested-structures3160327
Ref: 14733160327
Node: Features<80>3160666
Ref: libraries/yaml features3160793
Ref: 14743160793
Node: Supported YAML Features3161362
Ref: libraries/yaml supported-yaml-features3161490
Ref: 14753161490
Node: Limitations<6>3164557
Ref: libraries/yaml limitations3164690
Ref: 14763164690
Node: Error Handling<4>3165250
Ref: libraries/yaml error-handling3165377
Ref: 14773165377
Node: File Organization3165793
Ref: libraries/yaml file-organization3165916
Ref: 14783165916
Node: Test Files3166279
Ref: libraries/yaml test-files3166414
Ref: 14793166414
Node: Performance Considerations<2>3166808
Ref: libraries/yaml performance-considerations3166958
Ref: 147a3166958
Node: Integration with Other Libraries3167249
Ref: libraries/yaml integration-with-other-libraries3167408
Ref: 147b3167408
Node: Future Enhancements3167739
Ref: libraries/yaml future-enhancements3167877
Ref: 147c3167877
Node: See Also3168291
Ref: libraries/yaml see-also3168388
Ref: 147d3168388
Node: z_score_anomaly_detector3168604
Ref: libraries/z_score_anomaly_detector doc3168723
Ref: 147e3168723
Ref: libraries/z_score_anomaly_detector library-z-score-anomaly-detector3168723
Ref: 147f3168723
Ref: libraries/z_score_anomaly_detector z-score-anomaly-detector3168723
Ref: 14803168723
Node: API documentation<264>3170007
Ref: libraries/z_score_anomaly_detector api-documentation3170131
Ref: 14813170131
Node: Loading<268>3170261
Ref: libraries/z_score_anomaly_detector loading3170406
Ref: 14823170406
Node: Testing<259>3170553
Ref: libraries/z_score_anomaly_detector testing3170688
Ref: 14833170688
Node: Features<81>3170846
Ref: libraries/z_score_anomaly_detector features3170980
Ref: 14843170980
Node: Options<76>3174358
Ref: libraries/z_score_anomaly_detector options3174506
Ref: 14853174506
Node: Detector representation<8>3175376
Ref: libraries/z_score_anomaly_detector detector-representation3175521
Ref: 14863175521
Node: Notes<14>3176280
Ref: libraries/z_score_anomaly_detector notes3176405
Ref: 14873176405
Node: zippers3178337
Ref: libraries/zippers doc3178443
Ref: 14883178443
Ref: libraries/zippers library-zippers3178443
Ref: 14893178443
Ref: libraries/zippers zippers3178443
Ref: 148a3178443
Node: API documentation<265>3178630
Ref: libraries/zippers api-documentation3178737
Ref: 148b3178737
Node: Loading<269>3178867
Ref: libraries/zippers loading3178995
Ref: 148c3178995
Node: Testing<260>3179141
Ref: libraries/zippers testing3179238
Ref: 148d3179238
Node: Ports3179379
Ref: ports/index doc3179484
Ref: 148e3179484
Ref: ports/index ports3179484
Ref: 148f3179484
Node: fcube3179644
Ref: ports/fcube doc3179727
Ref: 14903179727
Ref: ports/fcube fcube3179727
Ref: 14913179727
Ref: ports/fcube library-fcube3179727
Ref: 14923179727
Node: API documentation<266>3181035
Ref: ports/fcube api-documentation3181140
Ref: 14933181140
Node: Loading<270>3181264
Ref: ports/fcube loading3181390
Ref: 14943181390
Node: Testing<261>3181527
Ref: ports/fcube testing3181622
Ref: 14953181622
Node: metagol3181754
Ref: ports/metagol doc3181852
Ref: 14963181852
Ref: ports/metagol library-metagol3181852
Ref: 14973181852
Ref: ports/metagol metagol3181852
Ref: 14983181852
Node: API documentation<267>3183744
Ref: ports/metagol api-documentation3183851
Ref: 14993183851
Node: Loading<271>3183977
Ref: ports/metagol loading3184105
Ref: 149a3184105
Node: Testing<262>3184244
Ref: ports/metagol testing3184341
Ref: 149b3184341
Node: toychr3184584
Ref: ports/toychr doc3184668
Ref: 149c3184668
Ref: ports/toychr library-toychr3184668
Ref: 149d3184668
Ref: ports/toychr toychr3184668
Ref: 149e3184668
Node: API documentation<268>3185656
Ref: ports/toychr api-documentation3185762
Ref: 149f3185762
Node: Loading<272>3185887
Ref: ports/toychr loading3186014
Ref: 14a03186014
Node: Testing<263>3186152
Ref: ports/toychr testing3186248
Ref: 14a13186248
Node: Contributions3186381
Ref: contributions/index doc3186485
Ref: 14a23186485
Ref: contributions/index contributions3186485
Ref: 14a33186485
Node: flags3186709
Ref: contributions/flags doc3186800
Ref: 14a43186800
Ref: contributions/flags flags3186800
Ref: 14a53186800
Ref: contributions/flags library-flags3186800
Ref: 14a63186800
Node: API documentation<269>3187226
Ref: contributions/flags api-documentation3187331
Ref: 14a73187331
Node: Loading<273>3187455
Ref: contributions/flags loading3187581
Ref: 14a83187581
Node: Testing<264>3187719
Ref: contributions/flags testing3187814
Ref: 14a93187814
Node: iso86013187949
Ref: contributions/iso8601 doc3188060
Ref: 14aa3188060
Ref: contributions/iso8601 iso86013188060
Ref: 14ab3188060
Ref: contributions/iso8601 library-iso86013188060
Ref: 14ac3188060
Node: API documentation<270>3190644
Ref: contributions/iso8601 api-documentation3190751
Ref: 14ad3190751
Node: Loading<274>3190877
Ref: contributions/iso8601 loading3191005
Ref: 14ae3191005
Node: Testing<265>3191147
Ref: contributions/iso8601 testing3191244
Ref: 14af3191244
Node: pddl_parser3191381
Ref: contributions/pddl_parser doc3191499
Ref: 14b03191499
Ref: contributions/pddl_parser library-pddl-parser3191499
Ref: 14b13191499
Ref: contributions/pddl_parser pddl-parser3191499
Ref: 14b23191499
Node: API documentation<271>3192203
Ref: contributions/pddl_parser api-documentation3192314
Ref: 14b33192314
Node: Loading<275>3192444
Ref: contributions/pddl_parser loading3192576
Ref: 14b43192576
Node: Testing<266>3192720
Ref: contributions/pddl_parser testing3192821
Ref: 14b53192821
Node: verdi_neruda3193250
Ref: contributions/verdi_neruda doc3193371
Ref: 14b63193371
Ref: contributions/verdi_neruda library-verdi-neruda3193371
Ref: 14b73193371
Ref: contributions/verdi_neruda verdi-neruda3193371
Ref: 14b83193371
Node: xml_parser3200639
Ref: contributions/xml_parser doc3200740
Ref: 14b93200740
Ref: contributions/xml_parser library-xml-parser3200740
Ref: 14ba3200740
Ref: contributions/xml_parser xml-parser3200740
Ref: 14bb3200740
Node: API documentation<272>3201406
Ref: contributions/xml_parser api-documentation3201516
Ref: 14bc3201516
Node: Loading<276>3201645
Ref: contributions/xml_parser loading3201776
Ref: 14bd3201776
Node: Testing<267>3201921
Ref: contributions/xml_parser testing3202046
Ref: 14be3202046
Node: Known issues<23>3202186
Ref: contributions/xml_parser known-issues3202290
Ref: 14bf3202290
Node: Glossary3202514
Ref: glossary doc3202621
Ref: 14c03202621
Ref: glossary glossary3202621
Ref: 14c13202621
Ref: glossary id13202644
Ref: 3f3202644
Ref: glossary term-abstract-class3202644
Ref: 14c23202644
Ref: glossary term-abstract-method3202828
Ref: 14c43202828
Ref: glossary term-adapter-file3203035
Ref: 1543203035
Ref: glossary term-after-method3203210
Ref: 14c73203210
Ref: glossary term-ancestor3203308
Ref: 14c83203308
Ref: glossary term-around-method3203709
Ref: 14ca3203709
Ref: glossary term-backend-Prolog-compiler3203872
Ref: 343203872
Ref: glossary term-before-method3204095
Ref: 14cb3204095
Ref: glossary term-built-in-method3204194
Ref: 14cc3204194
Ref: glossary term-built-in-predicate3204440
Ref: 14cd3204440
Ref: glossary term-category3204626
Ref: 14c63204626
Ref: glossary term-class3204976
Ref: 14c33204976
Ref: glossary term-clause-reference3205255
Ref: 1b83205255
Ref: glossary term-closed-world-assumption3205407
Ref: 6a3205407
Ref: glossary term-closure3205737
Ref: 14f3205737
Ref: glossary term-coinductive-predicate3205948
Ref: 1703205948
Ref: glossary term-complementing-category3206172
Ref: 14cf3206172
Ref: glossary term-component3206294
Ref: 3543206294
Ref: glossary term-debug-handler3206607
Ref: 3393206607
Ref: glossary term-directive3206775
Ref: 14d03206775
Ref: glossary term-discontiguous-predicate3206924
Ref: 4b93206924
Ref: glossary term-doclet-file3207117
Ref: 14d13207117
Ref: glossary term-doclet-object3207259
Ref: 63d3207259
Ref: glossary term-dynamic-binding3207454
Ref: 363207454
Ref: glossary term-dynamic-entity3207830
Ref: 14d23207830
Ref: glossary term-dynamic-predicate3207876
Ref: 4bf3207876
Ref: glossary term-early-binding3207982
Ref: 14d43207982
Ref: glossary term-encapsulation3208033
Ref: 14d53208033
Ref: glossary term-entity3208290
Ref: 14d33208290
Ref: glossary term-entity-alias3208770
Ref: c93208770
Ref: glossary term-entity-directive3209202
Ref: 14d73209202
Ref: glossary term-event3209312
Ref: 14d83209312
Ref: glossary term-expansion-workflow3209623
Ref: 14d93209623
Ref: glossary term-flaky-test3209839
Ref: 14dc3209839
Ref: glossary term-goal-expansion3210112
Ref: 14db3210112
Ref: glossary term-grammar-rule3210570
Ref: 14dd3210570
Ref: glossary term-grammar-rule-non-terminal3210993
Ref: 14de3210993
Ref: glossary term-grammar-rule-terminal3211221
Ref: 14df3211221
Ref: glossary term-homoiconic3211288
Ref: 73211288
Ref: glossary term-hook-object3211631
Ref: 39f3211631
Ref: glossary term-hook-predicate3212054
Ref: 16d3212054
Ref: glossary term-hot-patching3212261
Ref: 10b3212261
Ref: glossary term-identity3212606
Ref: 14d63212606
Ref: glossary term-inheritance3213021
Ref: 443213021
Ref: glossary term-instance3213489
Ref: 14e33213489
Ref: glossary term-instantiation3213693
Ref: 14e43213693
Ref: glossary term-interface3213956
Ref: 14e53213956
Ref: glossary term-lambda-expression3213997
Ref: 1823213997
Ref: glossary term-lambda-free-variable3214346
Ref: 2703214346
Ref: glossary term-lambda-parameter3214549
Ref: 2713214549
Ref: glossary term-late-binding3214799
Ref: 14e63214799
Ref: glossary term-library3214850
Ref: 6e3214850
Ref: glossary term-library-alias3214977
Ref: 14e73214977
Ref: glossary term-library-notation3215243
Ref: 2a83215243
Ref: glossary term-loader-file3215605
Ref: 4f3215605
Ref: glossary term-local-predicate3215782
Ref: 563215782
Ref: glossary term-message3216180
Ref: 433216180
Ref: glossary term-message-lookup3216380
Ref: 373216380
Ref: glossary term-message-to-self3216756
Ref: 17d3216756
Ref: glossary term-meta-argument3216970
Ref: 14e83216970
Ref: glossary term-meta-interpreter3217210
Ref: 14e93217210
Ref: glossary term-meta-predicate3217313
Ref: 523217313
Ref: glossary term-meta-variable3217493
Ref: 1833217493
Ref: glossary term-metaclass3217639
Ref: 723217639
Ref: glossary term-method3217887
Ref: 14c53217887
Ref: glossary term-mocking3218175
Ref: 14ea3218175
Ref: glossary term-module3218421
Ref: 14eb3218421
Ref: glossary term-monitor3218737
Ref: 31f3218737
Ref: glossary term-multifile-predicate3218976
Ref: 16b3218976
Ref: glossary term-naked-meta-variable3219393
Ref: 7b93219393
Ref: glossary term-object3219700
Ref: 5343219700
Ref: glossary term-object-database3220059
Ref: 1b03220059
Ref: glossary term-parameter3220138
Ref: 14ec3220138
Ref: glossary term-parameter-variable3220343
Ref: a13220343
Ref: glossary term-parametric-category3220795
Ref: 14ed3220795
Ref: glossary term-parametric-entity3220856
Ref: 6a13220856
Ref: glossary term-parametric-object3221419
Ref: 4263221419
Ref: glossary term-parametric-object-proxy3221478
Ref: 3fb3221478
Ref: glossary term-parent3221665
Ref: 14ee3221665
Ref: glossary term-polymorphism3221743
Ref: 14ef3221743
Ref: glossary term-predicate3222549
Ref: 613222549
Ref: glossary term-predicate-alias3222846
Ref: ca3222846
Ref: glossary term-predicate-calling-context3223367
Ref: 1503223367
Ref: glossary term-predicate-declaration3223559
Ref: 573223559
Ref: glossary term-predicate-definition3223739
Ref: 583223739
Ref: glossary term-predicate-definition-context3223929
Ref: 1513223929
Ref: glossary term-predicate-directive3224055
Ref: 14ce3224055
Ref: glossary term-predicate-execution-context3224187
Ref: 35f3224187
Ref: glossary term-predicate-scope-container3224379
Ref: 3fa3224379
Ref: glossary term-predicate-scope-directive3224559
Ref: 1e43224559
Ref: glossary term-predicate-shorthand3224704
Ref: 1613224704
Ref: glossary term-primary-predicate-declaration3225244
Ref: 3933225244
Ref: glossary term-private-inheritance3225317
Ref: 14e23225317
Ref: glossary term-private-predicate3225508
Ref: 553225508
Ref: glossary term-profiler3225636
Ref: 14f03225636
Ref: glossary term-protected-inheritance3225714
Ref: 14e13225714
Ref: glossary term-protected-predicate3225936
Ref: 543225936
Ref: glossary term-protocol3226115
Ref: 593226115
Ref: glossary term-prototype3226616
Ref: 14c93226616
Ref: glossary term-public-inheritance3226955
Ref: 14e03226955
Ref: glossary term-public-predicate3227129
Ref: 533227129
Ref: glossary term-scratch-directory3227201
Ref: 2933227201
Ref: glossary term-self3227354
Ref: 693227354
Ref: glossary term-sender3227432
Ref: 39a3227432
Ref: glossary term-settings-file3227668
Ref: 493227668
Ref: glossary term-singleton-method3227935
Ref: 14f13227935
Ref: glossary term-source-file3228148
Ref: 61d3228148
Ref: glossary term-source-file-directive3228562
Ref: 14f23228562
Ref: glossary term-specialization3228677
Ref: 14f33228677
Ref: glossary term-static-binding3228821
Ref: 353228821
Ref: glossary term-static-entity3229282
Ref: 14f43229282
Ref: glossary term-steadfastness3229327
Ref: 2c53229327
Ref: glossary term-subclass3229662
Ref: 633229662
Ref: glossary term-super-call3229814
Ref: 1153229814
Ref: glossary term-superclass3230158
Ref: 603230158
Ref: glossary term-synchronized-predicate3230337
Ref: 1753230337
Ref: glossary term-template-method3230526
Ref: 14f53230526
Ref: glossary term-term-expansion3230582
Ref: 14da3230582
Ref: glossary term-test-dialect3231046
Ref: 14f63231046
Ref: glossary term-test-outcome3231248
Ref: 14f73231248
Ref: glossary term-tester-file3231443
Ref: 14f83231443
Ref: glossary term-this3231554
Ref: 1143231554
Ref: glossary term-threaded-engine3231852
Ref: 2bb3231852
Ref: glossary term-top-level-interpreter-shorthand3232169
Ref: 14f93232169
Ref: glossary term-visible-predicate3232445
Ref: 14fa3232445
Ref: bibliography alexiev933232638
Ref: 14fb3232638
Ref: bibliography belli-et-al-923232822
Ref: 14fc3232822
Ref: bibliography block893233109
Ref: 14fd3233109
Ref: bibliography bobrow-et-al-883233213
Ref: 1fd3233213
Ref: bibliography bratko903233383
Ref: 14fe3233383
Ref: bibliography champaux923233487
Ref: 28d3233487
Ref: bibliography clocksin873233640
Ref: 14ff3233640
Ref: bibliography cointe873233738
Ref: 9c3233738
Ref: bibliography cordes913233849
Ref: 15003233849
Ref: bibliography covington943233948
Ref: 15013233948
Ref: bibliography cox863234082
Ref: 1d3234082
Ref: bibliography davison893234212
Ref: 15023234212
Ref: bibliography davison923234323
Ref: 15033234323
Ref: bibliography davison933234546
Ref: 15043234546
Ref: bibliography delzanno973234760
Ref: 15053234760
Ref: bibliography dony903234958
Ref: 15063234958
Ref: bibliography fornarino-et-al-893235085
Ref: 123235085
Ref: bibliography fromherz933235350
Ref: 293235350
Ref: bibliography fukunaga863235455
Ref: 15073235455
Ref: bibliography goldberg833235597
Ref: 1c3235597
Ref: bibliography joy-et-al-003235727
Ref: 1e3235727
Ref: bibliography iso953235857
Ref: 313235857
Ref: bibliography knuth843236028
Ref: 15083236028
Ref: bibliography lieberman863236112
Ref: 193236112
Ref: bibliography maes873236261
Ref: 143236261
Ref: bibliography mccabe923236361
Ref: 283236361
Ref: bibliography moon863236446
Ref: 10a3236446
Ref: bibliography moss943236536
Ref: 1fc3236536
Ref: bibliography moura943236678
Ref: 9d3236678
Ref: bibliography moura993236869
Ref: 15093236869
Ref: bibliography moura003237044
Ref: 150a3237044
Ref: bibliography razek923237158
Ref: 133237158
Ref: bibliography rumbaugh873237251
Ref: 103237251
Ref: bibliography rumbaugh883237378
Ref: 113237378
Ref: bibliography schachte953237509
Ref: 150b3237509
Ref: bibliography sicstus953237767
Ref: 2a3237767
Ref: bibliography shan-et-al-933237845
Ref: 1ff3237845
Ref: bibliography stefik-et-al-863238008
Ref: 2023238008
Ref: bibliography stroustrup863238176
Ref: 233238176
Ref: bibliography taenzer893238278
Ref: 1fe3238278
Ref: bibliography tanzer953238461
Ref: 150c3238461
Ref: bibliography tanenbaum873238609
Ref: 2033238609
Ref: bibliography welsch893238720
Ref: 150d3238720
Ref: Glossary-Footnote-13238986
Ref: Glossary-Footnote-23239031
Ref: Glossary-Footnote-33239076
Ref: Glossary-Footnote-43239123
Node: Index<2>3239168
Ref: genindex doc3239267
Ref: 150e3239267
Ref: genindex index3239267
Ref: 150f3239267
Node: Index3239286

End Tag Table


Local Variables:
coding: utf-8
End:
