yap-6.3/docs/yap.tex

\input texinfo @c -*- mode: texinfo; coding: utf-8; -*-

@documentencoding UTF-8

@c %**start of header
@setfilename yap.info
@setcontentsaftertitlepage
@settitle YAP Prolog User's Manual
@c For double-sided printing, uncomment:
@c @setchapternewpage odd
@c %**end of header

@set VERSION 6.3.4
@set EDITION 4.2.9
@set UPDATED Oct 2010

@c Index for C-Prolog compatible predicate
@defindex cy
@c Index for predicates not in C-Prolog
@defindex cn
@c Index for predicates sort of (almost) in C-Prolog
@defindex ca

@c Index for SICStus Prolog compatible predicate
@defindex sy
@c Index for predicates not in SICStus Prolog
@defindex sn
@c Index for predicates sort of (almost) in SICStus Prolog
@defindex sa

@alias pl_example=example 
@alias c_example=example 

@setchapternewpage odd
@c @smallbook
@comment %** end of header

@ifnottex
@format
@dircategory The YAP Prolog System
@direntry
* YAP: (yap).           YAP Prolog User's Manual.
@end direntry
@end format
@end ifnottex

@titlepage
@title YAP User's Manual
@subtitle Version @value{VERSION}
@author Vitor Santos Costa,
@author Luís Damas,
@author Rogério Reis
@author Rúben Azevedo
@page
@vskip 2pc
@copyright{} 1989-2014 L. Damas, V. Santos Costa and Universidade
do Porto.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions.

@end titlepage

@ifnottex
@node Top, , , (dir)
@top YAP Prolog

This file documents the YAP Prolog System version @value{VERSION}, a
high-performance Prolog compiler developed at LIACC, Universidade do
Porto. YAP is based on David H. D. Warren's WAM (Warren Abstract
Machine), with several optimizations for better performance. YAP follows
the Edinburgh tradition, and is largely compatible with DEC-10 Prolog,
Quintus Prolog, and especially with C-Prolog.


@ifplaintext
 

  + @subpage Install discusses how to download, compile and install YAP for your platform.

  + @subpage Syntax describes the syntax of YAP.

  + @subpage Run describes how to invoke YAP

  + @subpage Syntax describe the syntax of YAP.

  + @subpage Loading_Programs presents the main predicates and
  directives available to load files and to control the Prolog environment.

        + @subpage abs_file_name explains how to find a file full path.

  + Built-Ins describes predicates providing core YAP functionality:
        + @subpage page_arithmetic describes how arithmetic works in YAP.

        + @subpage Control describes the predicates for controlling the execution of Prolog programs.

        + @subpage Testing_Terms describes the main predicates on terms

        + @subpage  Input_Output goes into Input/Ouput.
		
        + @subpage Database discusses the clausal data-base

        + @subpage Grammars presents Grammar rules in Prolog that are
     both a  convenient way to express definite clause grammars and
     an extension of the well known context-free grammars.

        + @subpage OS discusses access to Operating System functionality

  + Libraries

        + @ref maplist introduces macros to apply an operation over
          all elements of a list


@end ifplaintext


This file contains extracts of the SWI-Prolog manual, as written by Jan
Wielemaker. Our thanks to the author for his kind permission in allowing
us to include his text in this document.

@menu
* Intro:: Introduction
* Install:: Installation
* Run:: Running YAP
* Syntax:: The syntax of YAP
* Loading Programs:: Loading Prolog programs
* Modules:: Using Modules in YAP
* Built-ins:: Built In Predicates
* Library:: Library Predicates
* SWI-Prolog:: SWI-Prolog emulation
* Global Variables ::  Global Variables for Prolog
* Extensions:: Extensions to Standard YAP
* Rational Trees:: Working with Rational Trees
* Co-routining:: Changing the Execution of Goals
* Attributed Variables:: Using attributed Variables
* CLPR:: The CLP(R) System
* CHR:: The CHR System
* Logtalk:: The Logtalk Object-Oriented System
* MYDDAS:: The YAP Database Interface
* Threads:: Thread Library
* Parallelism:: Running in Or-Parallel
* Tabling:: Storing Intermediate Solutions of programs 
* Low Level Profiling:: Profiling Abstract Machine Instructions
* Low Level Tracing:: Tracing at Abstract Machine Level
* Debugging:: Using the Debugger
* Efficiency:: Efficiency Considerations
* C-Interface:: Interfacing predicates written in C
* YAPLibrary:: Using YAP as a library in other programs
* Compatibility:: Compatibility with other Prolog systems
* Predicate Index:: An item for each predicate
* Concept Index:: An item for each concept

Built In Predicates
* Control:: Controlling the execution of Prolog programs
* Undefined Procedures:: Handling calls to Undefined Procedures
* Messages:: Message Handling in YAP
* Testing Terms:: Predicates on Terms
* Predicates on Atoms:: Manipulating Atoms
* Predicates on Characters:: Manipulating Characters
* Comparing Terms:: Comparison of Terms
* Arithmetic:: Arithmetic in YAP
* Input/Output:: Input/Output with YAP
* Database:: Modifying Prolog's Database
* Sets:: Finding All Possible Solutions
* Grammars:: Grammar Rules
* Preds:: Predicate Information
* OS:: Access to Operating System Functionality
* Term Modification:: Updating Prolog Terms
* Global Variables:: Manipulating Global Variables
* Profiling:: Profiling Prolog Execution
* Call Counting:: Limiting the Maximum Number of Reductions
* Arrays:: Supporting Global and Local Arrays
* Preds:: Information on Predicates
* Misc:: Miscellaneous Predicates


Subnodes of Running
* Running YAP Interactively:: Interacting with YAP
* Running Prolog Files:: Running Prolog files as scripts

Subnodes of Syntax
* Formal Syntax:: Syntax of Terms
* Tokens:: Syntax of Prolog tokens
* Encoding:: How characters are encoded and Wide Character Support

Subnodes of Tokens
* Numbers:: Integer and Floating-Point Numbers
* Strings:: Sequences of Characters
* Atoms:: Atomic Constants
* Variables:: Logical Variables
* Punctuation Tokens:: Tokens that separate other tokens
* Layout:: Comments and Other Layout Rules

Subnodes of Numbers
* Integers:: How Integers are read and represented
* Floats:: Floating Point Numbers

Subnodes of Encoding
* Stream Encoding:: How Prolog Streams can be coded
* BOM:: The Byte Order Mark

Subnodes of Loading Programs
* Compiling:: Program Loading and Updating
* Setting the Compiler:: Changing the compiler's parameters
* Conditional Compilation:: Compiling program fragments
* Saving:: Saving and Restoring Programs

Subnodes of Modules
* Module Concepts:: The Key Ideas in Modules
* Defining Modules:: How To Define a New Module
* Using Modules:: How to Use a Module
* Meta-Predicates in Modules:: How to Handle New Meta-Predicates
* Re-Exporting Modules:: How to Re-export Predicates From Other Modules

Subnodes of Input/Output
* Streams and Files:: Handling Streams and Files
* C-Prolog File Handling:: C-Prolog Compatible File Handling
* Input/Output of Terms:: Input/Output of terms
* Input/Output of Characters:: Input/Output of Characters
* Input/Output for Streams:: Input/Output using Streams
* C-Prolog to Terminal:: C-Prolog compatible Character Input/Output to terminal
* Input/Output Control:: Controlling your Input/Output
* Sockets:: Using Sockets from YAP

Subnodes of Database
* Modifying the Database:: Asserting and Retracting
* Looking at the Database:: Finding out what is in the Data Base
* Database References:: Using Data Base References
* Internal Database:: YAP's Internal Database
* BlackBoard:: Storing and Fetching Terms in the BlackBoard

Subnodes of Library
* Aggregate :: SWI and SICStus compatible aggregate library
* Apply:: SWI-Compatible Apply library.
* Association Lists:: Binary Tree Implementation of Association Lists.
* AVL Trees:: Predicates to add and lookup balanced binary  trees.
* BDDs:: Predicates to manipulate BDDs using the CUDD libraries
* Exo Intervals:: Play with the UDI and exo-compilation
* Gecode:: Interface to the gecode constraint library
* Heaps:: Labelled binary tree where the key of each node is less
    than or equal to the keys of its children.
* Lambda:: Ulrich Neumerkel's Lambda Library
* DBUsage:: Information bout data base usage.
* LineUtilities:: Line Manipulation Utilities
* Lists:: List Manipulation
* MapArgs:: Apply on Arguments of Compound Terms.
* MapList:: SWI-Compatible Apply library.
* matrix:: Matrix Objects
* MATLAB:: Matlab Interface
* Non-Backtrackable Data Structures:: Queues, Heaps, and Beams.
* Ordered Sets:: Ordered Set Manipulation
* Pseudo Random:: Pseudo Random Numbers
* Queues:: Queue Manipulation
* Random:: Random Numbers
* Read Utilities:: SWI inspired utilities for fast stream scanning.
* Red-Black Trees:: Predicates to add, lookup and delete in red-black binary  trees.
* RegExp:: Regular Expression Manipulation
* shlib:: SWI Prolog shlib library
* Splay Trees:: Splay Trees
* String Input/Output:: Writing To and Reading From Strings
* System:: System Utilities
* Terms:: Utilities on Terms
* Cleanup:: Call With registered Cleanup Calls
* Timeout:: Call With Timeout
* Trees:: Updatable Binary Trees
* Tries:: Trie Data Structure
* UGraphs:: Unweighted Graphs
* DGraphs:: Directed Graphs Implemented With Red-Black Trees
* UnDGraphs:: Undirected Graphs Using DGraphs
* LAM:: LAM MPI
* Block Diagram:: Block Diagrams of Prolog code


Subnodes of Debugging
* Deb Preds:: Debugging Predicates
* Deb Interaction:: Interacting with the debugger

Subnodes of Compatibility
* C-Prolog:: Compatibility with the C-Prolog interpreter
* SICStus Prolog:: Compatibility with the Quintus and SICStus Prolog systems
* ISO Prolog::  Compatibility with the ISO Prolog standard

Subnodes of Attributes
* Attribute Declarations:: Declaring New Attributes
* Attribute Manipulation:: Setting and Reading Attributes
* Attributed Unification:: Tuning the Unification Algorithm
* Displaying Attributes:: Displaying Attributes in User-Readable Form
* Projecting Attributes:: Obtaining the Attributes of Interest
* Attribute Examples:: Two Simple Examples of how to use Attributes.

Subnodes of SWI-Prolog
* Invoking Predicates on all Members of a List :: maplist and friends
* SWI-Prolog Global Variables :: Emulating SWI-like attributed variables

Subnodes of Gecode
* The Gecode Interface:: calling gecode from YAP
* Gecode and ClP(FD) :: using gecode in a CLP(FD) style

@c Subnodes of CLP(Q,R)
@c * Introduction to CLPQ:: The CLP(Q,R) System
@c * Referencing CLPQR:: How to Reference CLP(Q,R)
@c * CLPQR Acknowledgments:: Acknowledgments for CLP(Q,R)
@c * Solver Interface:: Using the CLP(Q,R) System
@c * Notational Conventions:: The CLP(Q,R) Notation
@c * Solver Predicates:: The CLP(Q,R) Interface Predicates
@c * Unification:: Unification and CLP(Q,R)
@c * Feedback and Bindings:: Information flow in CLP(Q,R)
@c * Linearity and Nonlinear Residues:: Linear and Nonlinear Constraints
@c * How Nonlinear Residues are made to disappear:: Handling Nonlinear Residues
@c * Isolation Axioms:: Isolating the Variable to be Solved
@c * Numerical Precision and Rationals:: Reals and Rationals
@c * Projection and Redundancy Elimination:: Presenting Bindings for Query Variables
@c * Variable Ordering:: Linear Relationships between Variables
@c * Turning Answers into Terms:: using @code{call_residue/2}
@c * Projecting Inequalities:: How to project linear inequations
@c * Why Disequations:: Using Disequations in CLP(Q,R)
@c * Syntactic Sugar:: An easier syntax
@c * Monash Examples:: The Monash Library
@c * Compatibility Notes:: CLP(Q,R) and the clp(R) interpreter
@c * A Mixed Integer Linear Optimization Example:: MIP models
@c * Implementation Architecture:: CLP(Q,R) Components
@c * Fragments and Bits:: Final Last Words on CLP(Q,R)
@c * CLPQR Bugs:: Bugs in CLP(Q,R)
@c * CLPQR References:: References for CLP(Q,R)

Subnodes of CLPR
* CLPR Solver Predicates::
* CLPR Syntax::
* CLPR Unification::
* CLPR Non-linear Constraints::               

Subnodes of CHR
* CHR Introduction::            
* CHR Syntax and Semantics::
* CHR in YAP Programs::
* CHR Debugging::               
* CHR Examples::       
* CHR Compatibility::     
* CHR Guidelines::  

Subnodes of C-Interface
* Manipulating Terms:: Primitives available to the C programmer
* Manipulating Terms:: Primitives available to the C programmer
* Unifying Terms:: How to Unify Two Prolog Terms
* Manipulating Strings:: From character arrays to Lists of codes and back
* Memory Allocation:: Stealing Memory From YAP
* Controlling Streams:: Control How YAP sees Streams
* Utility Functions:: From character arrays to Lists of codes and back
* Calling YAP From C:: From C to YAP to C to YAP 
* Module Manipulation in C:: Create and Test Modules from within C
* Miscellaneous C-Functions:: Other Helpful Interface Functions
* Writing C:: Writing Predicates in C
* Loading Objects:: Loading Object Files
* Save&Rest:: Saving and Restoring
* YAP4 Notes:: Changes in Foreign Predicates Interface

Subnodes of C-Prolog
* Major Differences with C-Prolog:: Major Differences between YAP and C-Prolog
* Fully C-Prolog Compatible:: YAP predicates fully compatible with
C-Prolog
* Not Strictly C-Prolog Compatible:: YAP predicates not strictly as C-Prolog
* Not in C-Prolog:: YAP predicates not available in C-Prolog
* Not in YAP:: C-Prolog predicates not available in YAP

Subnodes of SICStus Prolog
* Major Differences with SICStus:: Major Differences between YAP and SICStus Prolog
* Fully SICStus Compatible:: YAP predicates fully compatible with
SICStus Prolog
* Not Strictly SICStus Compatible:: YAP predicates not strictly as
SICStus Prolog
* Not in SICStus Prolog:: YAP predicates not available in SICStus Prolog


Tables
* Operators:: Predefined operators

@end menu

@end ifnottex

@node Intro, Install, , Top
@section Introduction

This document provides User information on version @value{VERSION} of
YAP (@emph{Yet Another Prolog}). The YAP Prolog System is a
high-performance Prolog compiler developed at LIACC, Universidade do
Porto. YAP provides several important features:

@itemize @bullet
 @item Speed: YAP is widely considered one of the fastest available
Prolog systems.

 @item Functionality: it supports stream Input/Output, sockets, modules,
exceptions, Prolog debugger, C-interface, dynamic code, internal
database, DCGs, saved states, co-routining, arrays, threads.

 @item We explicitly allow both commercial and non-commercial use of YAP.
@end itemize

YAP is based on the David H. D. Warren's WAM (Warren Abstract Machine),
with several optimizations for better performance. YAP follows the
Edinburgh tradition, and was originally designed to be largely
compatible with DEC-10 Prolog, Quintus Prolog, and especially with
C-Prolog.

YAP implements most of the ISO-Prolog standard. We are striving at
full compatibility, and the manual describes what is still
missing. The manual also includes a (largely incomplete) comparison
with SICStus Prolog.

The document is intended neither as an introduction to Prolog nor to the
implementation aspects of the compiler. A good introduction to
programming in Prolog is the book @cite{TheArtOfProlog}, by
L. Sterling and E. Shapiro, published by "The MIT Press, Cambridge
MA". Other references should include the classical @cite{ProgrammingInProlog}, by W.F. Clocksin and C.S. Mellish, published by
Springer-Verlag.

YAP 4.3 is known to build with many versions of gcc (<= gcc-2.7.2, >=
gcc-2.8.1, >= egcs-1.0.1, gcc-2.95.*) and on a variety of Unixen:
SunOS 4.1, Solaris 2.*, Irix 5.2, HP-UX 10, Dec Alpha Unix, Linux 1.2
and Linux 2.* (RedHat 4.0 thru 5.2, Debian 2.*) in both the x86 and
alpha platforms. It has been built on Windows NT 4.0 using Cygwin from
Cygnus Solutions (see @file{README.nt}) and using Visual C++ 6.0.

The overall copyright and permission notice for YAP4.3 can be found in
the Artistic file in this directory. YAP follows the Perl Artistic
license, and it is thus non-copylefted freeware.

If you have a question about this software, desire to add code, found a
bug, want to request a feature, or wonder how to get further assistance,
please send e-mail to @email{yap-users AT lists.sourceforge.net}.  To
subscribe to the mailing list, visit the page
@url{https://lists.sourceforge.net/lists/listinfo/yap-users}.

On-line documentation is available for YAP at:

        @url{http://www.ncc.up.pt/~vsc/YAP/}

Recent versions of YAP, including both source and selected binaries,
can be found from this same URL.

This manual was written by Vítor Santos Costa,
Luís Damas, Rogério Reis, and Rúben Azevedo. The
manual is largely based on the DECsystem-10 Prolog User's Manual by
D.L. Bowen, L. Byrd, F. C. N. Pereira, L. M. Pereira, and
D. H. D. Warren. We have also used comments from the Edinburgh Prolog
library written by R. O'Keefe and from the SWI-Prolog manual written by
Jan Wielemaker. We would also like to gratefully
acknowledge the contributions from Ashwin Srinivasian.

We are happy to include in YAP several excellent packages developed
under separate licenses. Our thanks to the authors for their kind
authorization to include these packages.

The packages are, in alphabetical order:

@itemize @bullet
@item The CHR package developed by Tom Schrijvers,
Christian Holzbaur, and Jan Wielemaker.

@item The CLP(R) package developed by Leslie De Koninck, Bart Demoen, Tom
Schrijvers, and Jan Wielemaker, based on the CLP(Q,R) implementation
by Christian Holzbaur.

@item The Logtalk Object-Oriented system is developed at the University 
of Beira Interior, Portugal, by Paulo Moura:

@url{http://logtalk.org/}

Logtalk is no longer distributed with YAP. Please use the Logtalk standalone 
installer for a smooth integration with YAP.

@item The Pillow WEB library developed at Universidad Politecnica de
Madrid by the CLIP group. This package is distributed under the FSF's
LGPL. Documentation on this package is distributed separately from
yap.tex.

@item The @file{yap2swi} library implements some of the functionality of
SWI's PL interface. Please do refer to the SWI-Prolog home page:

@url{http://www.swi-prolog.org}

for more information on SWI-Prolog and for a detailed description of its
foreign language interface.

@end itemize

@include install.tex

@include run.tex

@include syntax.tex

@include load.tex

@include builtins.tex

@node Library, SWI-Prolog, Built-ins, Top

@chapter Library Predicates

Library files reside in the library_directory path (set by the
@code{LIBDIR} variable in the Makefile for YAP). Currently,
most files in the library are from the Edinburgh Prolog library. 

@menu
 
Library, Extensions, Built-ins, Top
* Aggregate :: SWI and SICStus compatible aggregate library
* Apply:: SWI-Compatible Apply library.
* Association Lists:: Binary Tree Implementation of Association Lists.
* AVL Trees:: Predicates to add and lookup balanced binary  trees.
* BDDs:: Predicates to manipulate BDDs using the CUDD libraries
* Block Diagram:: Block Diagrams of Prolog code
* Cleanup:: Call With registered Cleanup Calls
* DGraphs:: Directed Graphs Implemented With Red-Black Trees
* Exo Intervals:: Play with the UDI and exo-compilation
* Gecode:: Interface to the gecode constraint library
* Heaps:: Labelled binary tree where the key of each node is less
    than or equal to the keys of its children.
* LAM:: LAM MPI
* Lambda:: Ulrich Neumerkel's Lambda Library
* DBUsage:: Information bout data base usage.
* Lists:: List Manipulation
* LineUtilities:: Line Manipulation Utilities
* MapArgs:: Apply on Arguments of Compound Terms.
* MapList:: SWI-Compatible Apply library.
* matrix:: Matrix Objects
* MATLAB:: Matlab Interface
* Non-Backtrackable Data Structures:: Queues, Heaps, and Beams.
* Ordered Sets:: Ordered Set Manipulation
* Pseudo Random:: Pseudo Random Numbers
* Queues:: Queue Manipulation
* Random:: Random Numbers
* Read Utilities:: SWI inspired utilities for fast stream scanning.
* Red-Black Trees:: Predicates to add, lookup and delete in red-black binary  trees.
* RegExp:: Regular Expression Manipulation
* shlib:: SWI Prolog shlib library
* Splay Trees:: Splay Trees
* String Input/Output:: Writing To and Reading From Strings
* System:: System Utilities
* Terms:: Utilities on Terms
* Timeout:: Call With Timeout
* Trees:: Updatable Binary Trees
* Tries:: Trie Data Structure
* UGraphs:: Unweighted Graphs
* UnDGraphs:: Undirected Graphs Using DGraphs


@end menu

 
@node Aggregate, Apply, , Library
@section Aggregate
@cindex aggregate
This is the SWI-Prolog library based on  the Quintus and SICStus 4
library.   @c To be done - Analysing the aggregation template
@c and compiling a predicate for the list aggregation can be done at
@c compile time.  - aggregate_all/3 can be rewritten to run in constant
@c space using non-backtrackable assignment on a term.

This library provides aggregating operators over the solutions of a
predicate. The operations are a generalisation of the @code{bagof/3},
@code{setof/3} and @code{findall/3} built-in predicates. The defined
aggregation operations are counting, computing the sum, minimum,
maximum, a bag of solutions and a set of solutions. We first give a
simple example, computing the country with the smallest area:

@pl_example
smallest_country(Name, Area) :-
        aggregate(min(A, N), country(N, A), min(Area, Name)).
@end pl_example

There are four aggregation predicates, distinguished on two properties.

@table @code

@item aggregate vs. aggregate_all
    The aggregate predicates use setof/3 (aggregate/4) or bagof/3
    (aggregate/3), dealing with existential qualified variables
    (@var{Var}/\@var{Goal}) and providing multiple solutions for the
    remaining free variables in @var{Goal}. The aggregate_all/3
    predicate uses findall/3, implicitly qualifying all free variables
    and providing exactly one solution, while aggregate_all/4 uses
    sort/2 over solutions and Distinguish (see below) generated using
    findall/3. 
@item The @var{Distinguish} argument
    The versions with 4 arguments provide a @var{Distinguish} argument
    that allow for keeping duplicate bindings of a variable in the
    result. For example, if we wish to compute the total population of
    all countries we do not want to lose results because two countries
    have the same population. Therefore we use:

@pl_example
        aggregate(sum(P), Name, country(Name, P), Total)
@end pl_example

@end table

All aggregation predicates support the following operator below in
@var{Template}. In addition, they allow for an arbitrary named compound
term where each of the arguments is a term from the list below. I.e. the
term @code{r(min(X), max(X))} computes both the minimum and maximum
binding for @var{X}.

@table @code

@item count
    Count number of solutions. Same as @code{sum(1)}. 
@item sum(@var{Expr})
    Sum of @var{Expr} for all solutions. 
@item min(@var{Expr})
    Minimum of @var{Expr} for all solutions. 
@item min(@var{Expr}, @var{Witness})
    A term min(@var{Min}, @var{Witness}), where @var{Min} is the minimal version of @var{Expr}
    over all Solution and @var{Witness} is any other template applied to
    Solution that produced @var{Min}. If multiple solutions provide the same
    minimum, @var{Witness} corresponds to the first solution. 
@item max(@var{Expr})
    Maximum of @var{Expr} for all solutions. 
@item max(@var{Expr}, @var{Witness})
    As min(@var{Expr}, @var{Witness}), but producing the maximum result. 
@item set(@var{X})
    An ordered set with all solutions for @var{X}. 
@item bag(@var{X})
    A list of all solutions for @var{X}. 
@end table

The predicates are:
@table @code

@item [nondet]aggregate(+@var{Template}, :@var{Goal}, -@var{Result})
@findex aggregate/3
@syindex aggregate/3
@cnindex aggregate/3
    Aggregate bindings in @var{Goal} according to @var{Template}. The
    aggregate/3 version performs bagof/3 on @var{Goal}.
@item [nondet]aggregate(+@var{Template}, +@var{Discriminator}, :@var{Goal}, -@var{Result})
@findex aggregate/4
@syindex aggregate/4
@cnindex aggregate/4
    Aggregate bindings in @var{Goal} according to @var{Template}. The
    aggregate/3 version performs setof/3 on @var{Goal}.
@item [semidet]aggregate_all(+@var{Template}, :@var{Goal}, -@var{Result})
@findex aggregate_all/3
@syindex aggregate_all/3
@cnindex aggregate_all/3
    Aggregate bindings in @var{Goal} according to @var{Template}. The
    aggregate_all/3 version performs findall/3 on @var{Goal}.
@item [semidet]aggregate_all(+@var{Template}, +@var{Discriminator}, :@var{Goal}, -@var{Result})
@findex aggregate_all/4
@syindex aggregate_all/4
@cnindex aggregate_all/4
    Aggregate bindings in @var{Goal} according to @var{Template}. The
    aggregate_all/3 version performs findall/3 followed by sort/2 on
    @var{Goal}.
@item foreach(:Generator, :@var{Goal})
@findex foreach/2
@syindex foreach/2
@cnindex foreach/2
    True if the conjunction of instances of @var{Goal} using the
    bindings from Generator is true. Unlike forall/2, which runs a
    failure-driven loop that proves @var{Goal} for each solution of
    Generator, foreach creates a conjunction. Each member of the
    conjunction is a copy of @var{Goal}, where the variables it shares
    with Generator are filled with the values from the corresponding
    solution.

    The implementation executes forall/2 if @var{Goal} does not contain
    any variables that are not shared with Generator.

    Here is an example:
@pl_example
    ?- foreach(between(1,4,X), dif(X,Y)), Y = 5.
    Y = 5
    ?- foreach(between(1,4,X), dif(X,Y)), Y = 3.
    No
@end pl_example

    Notice that @var{Goal} is copied repeatedly, which may cause
    problems if attributed variables are involved.

@item [det]free_variables(:Generator, +@var{Template}, +VarList0, -VarList)
@findex free_variables/4
@syindex free_variables/4
@cnindex free_variables/4
    In order to handle variables properly, we have to find all the universally quantified variables in the Generator. All variables as yet unbound are universally quantified, unless

@enumerate
@item they occur in the template
@item they are bound by X/\P, setof, or bagof
@end enumerate

    @code{free_variables(Generator, Template, OldList, NewList)} finds this set, using OldList as an accumulator.
@end table

The original author of this code was Richard O'Keefe. Jan Wielemaker
    made some SWI-Prolog enhancements, sponsored by SecuritEase,
    http://www.securitease.com. The code is public domain (from DEC10 library).
    @c To be done
    @c     - Distinguish between control-structures and data terms.
    @c     - Exploit our built-in term_variables/2 at some places? 



@node Apply, Association Lists, Aggregate, Library
@section   Apply Macros
@cindex apply

This library provides a SWI-compatible set of utilities for applying a
predicate to all elements of a list. The library just forwards
definitions from the @code{maplist} library.



@node Association Lists, AVL Trees, Apply, Library
@section Association Lists
@cindex association list

The following association list manipulation predicates are available
once included with the @code{use_module(library(assoc))} command. The
original library used Richard O'Keefe's implementation, on top of
unbalanced binary trees. The current code utilises code from the
red-black trees library and emulates the SICStus Prolog interface.

@table @code
@item assoc_to_list(+@var{Assoc},?@var{List})
@findex assoc_to_list/2
@syindex assoc_to_list/2
@cnindex assoc_to_list/2
Given an association list @var{Assoc} unify @var{List} with a list of
the form @var{Key-Val}, where the elements @var{Key} are in ascending
order.

@item del_assoc(+@var{Key}, +@var{Assoc}, ?@var{Val}, ?@var{NewAssoc})
@findex del_assoc/4
@syindex del_assoc/4
@cnindex del_assoc/4
Succeeds if @var{NewAssoc} is an association list, obtained by removing
the element with @var{Key} and @var{Val} from the list @var{Assoc}.

@item del_max_assoc(+@var{Assoc}, ?@var{Key}, ?@var{Val}, ?@var{NewAssoc})
@findex del_max_assoc/4
@syindex del_max_assoc/4
@cnindex del_max_assoc/4
Succeeds if @var{NewAssoc} is an association list, obtained by removing
the largest element of the list, with @var{Key} and @var{Val} from the
list @var{Assoc}.

@item del_min_assoc(+@var{Assoc}, ?@var{Key}, ?@var{Val}, ?@var{NewAssoc})
@findex del_min_assoc/4
@syindex del_min_assoc/4
@cnindex del_min_assoc/4
Succeeds if @var{NewAssoc} is an association list, obtained by removing
the smallest element of the list, with @var{Key} and @var{Val}
from the list @var{Assoc}.

@item empty_assoc(+@var{Assoc})
@findex empty_assoc/1
@syindex empty_assoc/1
@cnindex empty_assoc/1
Succeeds if association list @var{Assoc} is empty.

@item gen_assoc(+@var{Assoc},?@var{Key},?@var{Value})
@findex gen_assoc/3
@syindex gen_assoc/3
@cnindex gen_assoc/3
Given the association list @var{Assoc}, unify @var{Key} and @var{Value}
with two associated elements. It can be used to enumerate all elements
in the association list.

@item get_assoc(+@var{Key},+@var{Assoc},?@var{Value})
@findex get_next_assoc/4
@syindex get_next_assoc/4
@cnindex get_next_assoc/4
If @var{Key} is one of the elements in the association list @var{Assoc},
return the associated value.

@item get_assoc(+@var{Key},+@var{Assoc},?@var{Value},+@var{NAssoc},?@var{NValue})
@findex get_assoc/5
@syindex get_assoc/5
@cnindex get_assoc/5
If @var{Key} is one of the elements in the association list @var{Assoc},
return the associated value @var{Value} and a new association list
@var{NAssoc} where @var{Key} is associated with @var{NValue}.

@item get_prev_assoc(+@var{Key},+@var{Assoc},?@var{Next},?@var{Value})
@findex get_prev_assoc/4
@syindex get_prev_assoc/4
@cnindex get_prev_assoc/4
If @var{Key} is one of the elements in the association list @var{Assoc},
return the previous key, @var{Next}, and its value, @var{Value}.

@item get_next_assoc(+@var{Key},+@var{Assoc},?@var{Next},?@var{Value})
@findex get_assoc/3
@syindex get_assoc/3
@cnindex get_assoc/3
If @var{Key} is one of the elements in the association list @var{Assoc},
return the next key, @var{Next}, and its value, @var{Value}.

@item is_assoc(+@var{Assoc})
@findex is_assoc/1
@syindex is_assoc/1
@cnindex is_assoc/1
Succeeds if @var{Assoc} is an association list, that is, if it is a
red-black tree.

@item list_to_assoc(+@var{List},?@var{Assoc})
@findex list_to_assoc/2
@syindex list_to_assoc/2
@cnindex list_to_assoc/2
Given a list @var{List} such that each element of @var{List} is of the
form @var{Key-Val}, and all the @var{Keys} are unique, @var{Assoc} is
the corresponding association list.

@item map_assoc(+@var{Pred},+@var{Assoc})
@findex map_assoc/2
@syindex map_assoc/2
@cnindex map_assoc/2
Succeeds if the unary predicate name @var{Pred}(@var{Val}) holds for every
element in the association list.

@item map_assoc(+@var{Pred},+@var{Assoc},?@var{New})
@findex map_assoc/3
@syindex map_assoc/3
@cnindex map_assoc/3
Given the binary predicate name @var{Pred} and the association list
@var{Assoc}, @var{New} in an association list with keys in @var{Assoc},
and such that if @var{Key-Val} is in @var{Assoc}, and @var{Key-Ans} is in
@var{New}, then @var{Pred}(@var{Val},@var{Ans}) holds.

@item max_assoc(+@var{Assoc},-@var{Key},?@var{Value})
@findex max_assoc/3
@syindex max_assoc/3
@cnindex max_assoc/3
Given the association list
@var{Assoc}, @var{Key} in the largest key in the list, and @var{Value}
the associated value.

@item min_assoc(+@var{Assoc},-@var{Key},?@var{Value})
@findex min_assoc/3
@syindex min_assoc/3
@cnindex min_assoc/3
Given the association list
@var{Assoc}, @var{Key} in the smallest key in the list, and @var{Value}
the associated value.

@item ord_list_to_assoc(+@var{List},?@var{Assoc})
@findex ord_list_to_assoc/2
@syindex ord_list_to_assoc/2
@cnindex ord_list_to_assoc/2
Given an ordered list @var{List} such that each element of @var{List} is
of the form @var{Key-Val}, and all the @var{Keys} are unique, @var{Assoc} is
the corresponding association list.

@item put_assoc(+@var{Key},+@var{Assoc},+@var{Val},+@var{New})
@findex put_assoc/4
@syindex put_assoc/4
@cnindex put_assoc/4
The association list @var{New} includes and element of association
@var{key} with @var{Val}, and all elements of @var{Assoc} that did not
have key @var{Key}.

@end table

@node AVL Trees, Exo Intervals, Association Lists, Library
@section AVL Trees
@cindex AVL trees

AVL trees are balanced search binary trees. They are named after their
inventors, Adelson-Velskii and Landis, and they were the first
dynamically balanced trees to be proposed. The YAP AVL tree manipulation
predicates library uses code originally written by Martin van Emdem and
published in the Logic Programming Newsletter, Autumn 1981.  A bug in
this code was fixed by Philip Vasey, in the Logic Programming
Newsletter, Summer 1982. The library currently only includes routines to
insert and lookup elements in the tree. Please try red-black trees if
you need deletion.

@table @code
@item avl_new(+@var{T})
@findex avl_new/1
@snindex avl_new/1
@cnindex avl_new/1
Create a new tree.

@item avl_insert(+@var{Key},?@var{Value},+@var{T0},-@var{TF})
@findex avl_insert/4
@snindex avl_insert/4
@cnindex avl_insert/4
Add an element with key @var{Key} and @var{Value} to the AVL tree
@var{T0} creating a new AVL tree @var{TF}. Duplicated elements are
allowed.

@item avl_lookup(+@var{Key},-@var{Value},+@var{T})
@findex avl_lookup/3
@snindex avl_lookup/3
@cnindex avl_lookup/3
Lookup an element with key @var{Key} in the AVL tree
@var{T}, returning the value @var{Value}.

@end table

@node Exo Intervals, Gecode, AVL Trees, Library
@section Exo Intervals
@cindex Indexing Numeric Intervals in Exo-predicates
This package assumes you use exo-compilation, that is, that you loaded
the pedicate using the @code{exo} option to @code{load_files/2}, In this
case, YAP includes a package for improved search on  intervals of
integers.

The package is activated by @code{udi} declarations that state what is
the argument of interest:
@pl_example
:- udi(diagnoses(exo_interval,?,?)).

:- load_files(db, [consult(exo)]).
@end pl_example
It is designed to optimise the following type of queries:
@pl_example
?- max(X, diagnoses(X, 9, Y), X).

?- min(X, diagnoses(X, 9, 36211117), X).

?- X #< Y, min(X, diagnoses(X, 9, 36211117), X ), diagnoses(Y, 9, _).
@end pl_example
The first argument gives the time, the second the patient, and the
third the condition code. The first query should find the last time
the patient 9 had any code reported, the second looks for the first
report of code 36211117, and the last searches for reports after this
one. All queries run in  constant or log(n) time.

@node Gecode, Heaps, Exo Intervals, Library
@section Gecode Interface
@cindex gecode

The gecode library intreface was designed and implemented by Denis
Duchier, with recent work by Vítor Santos Costa to port it to version 4
of gecode and to have an higher level interface,

@menu
* The Gecode Interface:: calling gecode from YAP
* Gecode and ClP(FD) :: using gecode in a CLP(FD) style
@end menu

@node The Gecode Interface, ,Gecode and ClP(FD), Gecode
@subsection The Gecode Interface

This text is due to Denys Duchier. The gecode interface requires
@pl_example
:- use_module(library(gecode)).
@end pl_example
Several example programs are available with the distribution.

@table @code
@item CREATING A SPACE

A space is gecodes data representation for a store of constraints:
@pl_example
    Space := space
@end pl_example


@item CREATING VARIABLES

Unlike in Gecode, variable objects are not bound to a specific Space.  Each one
actually contains an index with which it is possible to access a Space-bound
Gecode variable.  Variables can be created using the following expressions:

@pl_example
   IVar := intvar(Space,SPEC...)
   BVar := boolvar(Space)
   SVar := setvar(Space,SPEC...)
@end pl_example

where SPEC... is the same as in Gecode.  For creating lists of variables use
the following variants:

@pl_example
   IVars := intvars(Space,N,SPEC...)
   BVars := boolvars(Space,N,SPEC...)
   SVars := setvars(Space,N,SPEC...)
@end pl_example

where N is the number of variables to create (just like for XXXVarArray in
Gecode).  Sometimes an IntSet is necessary:

@pl_example
   ISet := intset([SPEC...])
@end pl_example

where each SPEC is either an integer or a pair (I,J) of integers.  An IntSet
describes a set of ints by providing either intervals, or integers (which stand
for an interval of themselves).  It might be tempting to simply represent an
IntSet as a list of specs, but this would be ambiguous with IntArgs which,
here, are represented as lists of ints.

@pl_example
   Space += keep(Var)
   Space += keep(Vars)
@end pl_example

Variables can be marked as "kept".  In this case, only such variables will be
explicitly copied during search.  This could bring substantial benefits in
memory usage.  Of course, in a solution, you can then only look at variables
that have been "kept".  If no variable is marked as "kept", then they are all
kept.  Thus marking variables as "kept" is purely an optimization.


@item CONSTRAINTS AND BRANCHINGS

all constraint and branching posting functions are available just like in
Gecode.  Wherever a XXXArgs or YYYSharedArray is expected, simply use a list.
At present, there is no support for minimodel-like constraint posting.
Constraints and branchings are added to a space using:

@pl_example
    Space += CONSTRAINT
    Space += BRANCHING
@end pl_example

For example:

@pl_example
    Space += rel(X,'IRT_EQ',Y)
@end pl_example


arrays of variables are represented by lists of variables, and constants are
represented by atoms with the same name as the Gecode constant
(e.g. 'INT_VAR_SIZE_MIN').

@item SEARCHING FOR SOLUTIONS

@pl_example
    SolSpace := search(Space)
@end pl_example


This is a backtrackable predicate that enumerates all solution spaces
(SolSpace).  It may also take options:

@pl_example
    SolSpace := search(Space,Options)
@end pl_example


Options is a list whose elements maybe:

@table @code
@item restart
    to select the Restart search engine
@item threads=N
    to activate the parallel search engine and control the number of
    workers (see Gecode doc)
@item c_d=N
    to set the commit distance for recomputation
@item a_d=N
    to set the adaptive distance for recomputation

@end table

@item EXTRACTING INFO FROM A SOLUTION

An advantage of non Space-bound variables, is that you can use them both to
post constraints in the original space AND to consult their values in
solutions.  Below are methods for looking up information about variables.  Each
of these methods can either take a variable as argument, or a list of
variables, and returns resp. either a value, or a list of values:

@pl_example
    Val := assigned(Space,X)

    Val := min(Space,X)
    Val := max(Space,X)
    Val := med(Space,X)
    Val := val(Space,X)
    Val := size(Space,X)
    Val := width(Space,X)
    Val := regret_min(Space,X)
    Val := regret_max(Space,X)

    Val := glbSize(Space,V)
    Val := lubSize(Space,V)
    Val := unknownSize(Space,V)
    Val := cardMin(Space,V)
    Val := cardMax(Space,V)
    Val := lubMin(Space,V)
    Val := lubMax(Space,V)
    Val := glbMin(Space,V)
    Val := glbMax(Space,V)
    Val := glb_ranges(Space,V)
    Val := lub_ranges(Space,V)
    Val := unknown_ranges(Space,V)
    Val := glb_values(Space,V)
    Val := lub_values(Space,V)
    Val := unknown_values(Space,V)
 @end pl_example

@item DISJUNCTORS


Disjunctors provide support for disjunctions of clauses, where each clause is a
conjunction of constraints:

@pl_example
    C1 or C2 or ... or Cn
@end pl_example


Each clause is executed "speculatively": this means it does not affect the main
space.  When a clause becomes failed, it is discarded.  When only one clause
remains, it is committed: this means that it now affects the main space.

Example:

Consider the problem where either X=Y=0 or X=Y+(1 or 2) for variable X and Y
that take values in 0..3.

@pl_example
    Space := space,
    [X,Y] := intvars(Space,2,0,3),
@end pl_example

First, we must create a disjunctor as a manager for our 2 clauses:

@pl_example
    Disj := disjunctor(Space),
@end pl_example

We can now create our first clause:

@pl_example
    C1 := clause(Disj),
@end pl_example


This clause wants to constrain X and Y to 0.  However, since it must be
executed "speculatively", it must operate on new variables X1 and Y1 that
shadow X and Y:

@pl_example
    [X1,Y1] := intvars(C1,2,0,3),
    C1 += forward([X,Y],[X1,Y1]),
@end pl_example

The forward(...) stipulation indicates which global variable is shadowed by
which clause-local variable.  Now we can post the speculative clause-local
constraints for X=Y=0:

@pl_example
    C1 += rel(X1,'IRT_EQ',0),
    C1 += rel(Y1,'IRT_EQ',0),
@end pl_example

We now create the second clause which uses X2 and Y2 to shadow X and Y:

@pl_example
    C2 := clause(Disj),
    [X2,Y2] := intvars(C2,2,0,3),
    C2 += forward([X,Y],[X2,Y2]),
@end pl_example

However, this clause also needs a clause-local variable Z2 taking values 1 or
2 in order to post the clause-local constraint X2=Y2+Z2:

@pl_example
    Z2 := intvar(C2,1,2),
    C2 += linear([-1,1,1],[X2,Y2,Z2],'IRT_EQ',0),
@end pl_example

Finally, we can branch and search:

@pl_example
    Space += branch([X,Y],'INT_VAR_SIZE_MIN','INT_VAL_MIN'),
    SolSpace := search(Space),
@end pl_example

and lookup values of variables in each solution:

@pl_example
    [X_,Y_] := val(SolSpace,[X,Y]).
@end pl_example

@end table

@node Gecode and ClP(FD), The Gecode Interface, , Gecode
@subsection Programming Finite Domain Constraints in YAP/Gecode

The gecode/clp(fd) interface is designed to use the GECODE functionality
in a more CLP like style. It requires
@pl_example
:- use_module(library(gecode/clpfd)).
@end pl_example
Several example programs are available with the distribution.

Integer variables are declared as:
@table @code
@item @var{V} in @var{A}..@var{B}
declares an integer variable @var{V} with range @var{A} to @var{B}.
@item @var{Vs} ins @var{A}..@var{B}
declares a set of integer variabless @var{Vs} with range @var{A} to @var{B}.
@item boolvar(@var{V})
declares a  boolean variable.
@item boolvars(@var{Vs})
declares a set of  boolean variable.
@end table


Constraints supported are:
@table @code
@item @var{X} #= @var{Y}
equality
@item @var{X} #\= @var{Y}
disequality
@item @var{X} #> @var{Y}
larger
@item @var{X} #>= @var{Y}
larger or equal
@item @var{X} #=< @var{Y}
smaller
@item @var{X} #< @var{Y}
smaller or equal

Arguments to this constraint may be an arithmetic expression with @t{+},
@t{-}, @t{*}, integer division @t{/}, @t{min}, @t{max}, @t{sum},
@t{count}, and
@t{abs}. Boolean variables support conjunction (/\), disjunction (\/),
implication (=>), equivalence (<=>), and xor. The @t{sum} constraint allows  a two argument version using the
@code{where} conditional, in Zinc style. 

The send more money equation may be written as:
@pl_example
          1000*S + 100*E + 10*N + D +
          1000*M + 100*O + 10*R + E #=
10000*M + 1000*O + 100*N + 10*E + Y,
@end pl_example

This example uses @code{where} to select from
column @var{I} the elements that have value under @var{M}:
@pl_example
OutFlow[I] #= sum(J in 1..N where D[J,I]<M, X[J,I])
@end pl_example

The @t{count} constraint counts the number of elements that match a
certain constant or variable (integer sets are not available).

@item all_different(@var{Vs}    )
@item all_distinct(@var{Vs})
@item all_different(@var{Cs}, @var{Vs})
@item all_distinct(@var{Cs}, @var{Vs})
 verifies whether all elements of a list are different. In the second
case, tests if all the sums between a list of constants and a list of
variables are different.

This is a formulation of the queens problem that uses both versions of @code{all_different}:
@pl_example
queens(N, Queens) :-
    length(Queens, N),
    Queens ins 1..N,
    all_distinct(Queens),
    foldl(inc, Queens, Inc, 0, _), % [0, 1, 2, .... ]
    foldl(dec, Queens, Dec, 0, _), % [0, -1, -2, ... ]
    all_distinct(Inc,Queens),
    all_distinct(Dec,Queens),
    labeling([], Queens).

inc(_, I0, I0, I) :-
    I is I0+1.

dec(_, I0, I0, I) :-
    I is I0-1.
@end pl_example


The next example uses @code{all_different/1} and the functionality of the matrix package to verify that all squares in
sudoku have a different value:
@pl_example
    foreach( [I,J] ins 0..2 ,
           all_different(M[I*3+(0..2),J*3+(0..2)]) ),
@end pl_example

@item scalar_product(+@var{Cs}, +@var{Vs}, +@var{Rel}, ?@var{V}    )

The product of constant @var{Cs} by @var{Vs} must be in relation
@var{Rel} with @var{V} .

@item @var{X} #= 
all elements of @var{X}  must take the same value
@item @var{X} #\= 
not all elements of @var{X}  take the same value
@item @var{X} #> 
elements of @var{X}  must be increasing
@item @var{X} #>= 
elements of @var{X}  must be increasinga or equal
@item @var{X} #=< 
elements of @var{X}  must be decreasing
@item @var{X} #< 
elements of @var{X}  must be decreasing or equal


@item @var{X} #<==> @var{B}
reified equivalence
@item @var{X} #==> @var{B}
reified implication
@item @var{X} #< @var{B}
reified implication 

As an example. consider finding out the people who wanted to sit
next to a friend and that are are actually sitting together:
@pl_example
preference_satisfied(X-Y, B) :-
    abs(X - Y) #= 1 #<==> B.
@end pl_example
Note that not all constraints may be reifiable.

@item element(@var{X}, @var{Vs}    )
@var{X} is an element of list @var{Vs}

@item clause(@var{Type}, @var{Ps} , @var{Ns}, @var{V}     )
If @var{Type} is @code{and} it is the conjunction of boolean variables
@var{Ps} and the negation of boolean variables @var{Ns} and must have
result @var{V}. If @var{Type} is @code{or} it is a disjunction.

@item DFA
the interface allows creating and manipulation deterministic finite
automata. A DFA has a set of states, represented as integers
and is initialised with an initial state, a set of transitions from the
first to the last argument emitting the middle argument, and a final
state.

The swedish-drinkers protocol is represented as follows:
@pl_example
    A = [X,Y,Z],
    dfa( 0, [t(0,0,0),t(0,1,1),t(1,0,0),t(-1,0,0)], [0], C),
    in_dfa( A, C ),
@end pl_example
This code will enumeratae the valid tuples of three emissions.

@item extensional constraints
Constraints can also be represented as lists of tuples. 

The previous example
would be written as:
@pl_example
    extensional_constraint([[0,0,0],[0,1,0],[1,0,0]], C),
    in_relation( A, C ),
@end pl_example

@item minimum(@var{X}, @var{Vs})
@item min(@var{X}, @var{Vs})
First Argument is the least element of a list.

@item maximum(@var{X}, @var{Vs})
@item max(@var{X}, @var{Vs})
First Argument is the greatest element of a list.

@item lex_order(@var{Vs})
All elements must be ordered.

@end table

The following predicates control search:
@table @code
@item labeling(@var{Opts}, @var{Xs})
performs labeling, several variable and value selection options are
available. The defaults are @code{min} and @code{min_step}.

Variable selection options are as follows:
@table @code
@item leftmost
choose the first variable
@item min
choose one of the variables with smallest minimum value
@item max
choose one of the variables with greatest maximum value
@item ff
choose one of the most constrained variables, that is, with the smallest
domain.
@end table

Given that we selected a variable, the values chosen for branching may
be:
@table @code
@item min_step
smallest value
 @item max_step
 largest value
 @item bisect
 median
 @item enum
 all value starting from the minimum.
@end table


@item maximize(@var{V})
maximise variable @var{V}

@item minimize(@t{V}) 
minimise variable @var{V}

@end table



@node Heaps, Lists, Gecode, Library
@section Heaps
@cindex heap

A heap is a labelled binary tree where the key of each node is less than
or equal to the keys of its sons.  The point of a heap is that we can
keep on adding new elements to the heap and we can keep on taking out
the minimum element.  If there are N elements total, the total time is
O(NlgN).  If you know all the elements in advance, you are better off
doing a merge-sort, but this file is for when you want to do say a
best-first search, and have no idea when you start how many elements
there will be, let alone what they are.

The following heap manipulation routines are available once included
with the @code{use_module(library(heaps))} command. 

@table @code

@item add_to_heap(+@var{Heap},+@var{key},+@var{Datum},-@var{NewHeap})
@findex add_to_heap/4
@syindex        add_to_heap/4
@cnindex        add_to_heap/4
Inserts the new @var{Key-Datum} pair into the heap. The insertion is not
stable, that is, if you insert several pairs with the same @var{Key} it
is not defined which of them will come out first, and it is possible for
any of them to come out first depending on the  history of the heap.

@item empty_heap(?@var{Heap})
@findex empty_heap/1
@syindex        empty_heap/1
@cnindex        empty_heap/1
Succeeds if @var{Heap} is an empty heap.

@item get_from_heap(+@var{Heap},-@var{key},-@var{Datum},-@var{Heap})
@findex get_from_heap/4
@syindex        get_from_heap/4
@cnindex        get_from_heap/4
Returns the @var{Key-Datum} pair in @var{OldHeap} with the smallest
@var{Key}, and also a @var{Heap} which is the @var{OldHeap} with that
pair deleted.

@item heap_size(+@var{Heap}, -@var{Size})
@findex heap_size/2
@syindex        heap_size/2
@cnindex        heap_size/2
Reports the number of elements currently in the heap.

@item heap_to_list(+@var{Heap}, -@var{List})
@findex heap_to_list/2
@syindex        heap_to_list/2
@cnindex        heap_to_list/2
Returns the current set of @var{Key-Datum} pairs in the @var{Heap} as a
@var{List}, sorted into ascending order of @var{Keys}.

@item list_to_heap(+@var{List}, -@var{Heap})
@findex list_to_heap/2
@syindex        list_to_heap/2
@cnindex        list_to_heap/2
Takes a list of @var{Key-Datum} pairs (such as keysort could be used to sort)
and forms them into a heap.

@item min_of_heap(+@var{Heap},  -@var{Key},  -@var{Datum})
@findex min_of_heap/3
@syindex min_of_heap/3
@cnindex min_of_heap/3
Returns the Key-Datum pair at the top of the heap (which is of course
the pair with the smallest Key), but does not remove it from the heap.

@item min_of_heap(+@var{Heap},  -@var{Key1},  -@var{Datum1},
-@var{Key2},  -@var{Datum2})
@findex min_of_heap/5
@syindex min_of_heap/5
@cnindex min_of_heap/5
Returns the smallest (Key1) and second smallest (Key2) pairs in the
heap, without deleting them.
@end table

@node Lists, LineUtilities, Heaps, Library
@section List Manipulation
@cindex list manipulation

The following list manipulation routines are available once included
with the @code{use_module(library(lists))} command. 

@table @code

@item append(?@var{Prefix},?@var{Suffix},?@var{Combined})
@findex append/3
@syindex append/3
@cnindex append/3
True when all three arguments are lists, and the members of
@var{Combined} are the members of @var{Prefix} followed by the members of @var{Suffix}.
It may be used to form @var{Combined} from a given @var{Prefix}, @var{Suffix} or to take
a given @var{Combined} apart.

@item append(?@var{Lists},?@var{Combined})
@findex append/2
@syindex append/2
@cnindex append/2
Holds if the lists of @var{Lists} can be concatenated as a
@var{Combined} list.

@item delete(+@var{List}, ?@var{Element}, ?@var{Residue})
@findex delete/3
@syindex delete/3
@cnindex delete/3
True when @var{List} is a list, in which @var{Element} may or may not
occur, and @var{Residue} is a copy of @var{List} with all elements
identical to @var{Element} deleted.

@item flatten(+@var{List}, ?@var{FlattenedList})
@findex flatten/2
@syindex flatten/2
@cnindex flatten/2
Flatten a list of lists @var{List} into a single list
@var{FlattenedList}.

@pl_example
?- flatten([[1],[2,3],[4,[5,6],7,8]],L).

L = [1,2,3,4,5,6,7,8] ? ;

no
@end pl_example

@item last(+@var{List},?@var{Last})
@findex last/2
@syindex last/2
@cnindex last/2
True when @var{List} is a list and @var{Last} is identical to its last element.

@item list_concat(+@var{Lists},?@var{List})
@findex list_concat/2
@snindex list_concat/2
@cnindex list_concat/2
True when @var{Lists} is a list of lists and @var{List} is the
concatenation of @var{Lists}.

@item member(?@var{Element}, ?@var{Set})
@findex member/2
@syindex member/2
@cnindex member/2
True when @var{Set} is a list, and @var{Element} occurs in it.  It may be used
to test for an element or to enumerate all the elements by backtracking.

@item memberchk(+@var{Element}, +@var{Set})
@findex memberchk/2
@syindex memberchk/2
@cnindex memberchk/2
As @code{member/2}, but may only be used to test whether a known
@var{Element} occurs in a known Set.  In return for this limited use, it
is more efficient when it is applicable.

@item nth0(?@var{N}, ?@var{List}, ?@var{Elem})
@findex nth0/3
@syindex nth0/3
@cnindex nth0/3
True when @var{Elem} is the Nth member of @var{List},
counting the first as element 0.  (That is, throw away the first
N elements and unify @var{Elem} with the next.)  It can only be used to
select a particular element given the list and index.  For that
task it is more efficient than @code{member/2}

@item nth1(?@var{N}, ?@var{List}, ?@var{Elem})
@findex nth1/3
@syindex nth1/3
@cnindex nth1/3
The same as @code{nth0/3}, except that it counts from
1, that is @code{nth(1, [H|_], H)}.

@item nth(?@var{N}, ?@var{List}, ?@var{Elem})
@findex nth/3
@syindex nth/3
@cnindex nth/3
The same as @code{nth1/3}.

@item nth0(?@var{N}, ?@var{List}, ?@var{Elem}, ?@var{Rest})
@findex nth0/4
@syindex nth0/4
@cnindex nth0/4
Unifies @var{Elem} with the Nth element of @var{List},
counting from 0, and @var{Rest} with the other elements.  It can be used
to select the Nth element of @var{List} (yielding @var{Elem} and @var{Rest}), or to
insert @var{Elem} before the Nth (counting from 1) element of @var{Rest}, when
it yields @var{List}, e.g. @code{nth0(2, List, c, [a,b,d,e])} unifies List with
@code{[a,b,c,d,e]}.  @code{nth/4} is the same except that it counts from 1.  @code{nth0/4}
can be used to insert @var{Elem} after the Nth element of @var{Rest}.

@item nth1(?@var{N}, ?@var{List}, ?@var{Elem}, ?@var{Rest})
@findex nth1/4
@syindex nth1/4
@cnindex nth1/4
Unifies @var{Elem} with the Nth element of @var{List}, counting from 1,
and @var{Rest} with the other elements.  It can be used to select the
Nth element of @var{List} (yielding @var{Elem} and @var{Rest}), or to
insert @var{Elem} before the Nth (counting from 1) element of
@var{Rest}, when it yields @var{List}, e.g. @code{nth(3, List, c, [a,b,d,e])} unifies List with @code{[a,b,c,d,e]}.  @code{nth/4}
can be used to insert @var{Elem} after the Nth element of @var{Rest}.

@item nth(?@var{N}, ?@var{List}, ?@var{Elem}, ?@var{Rest})
@findex nth/4
@syindex nth/4
@cnindex nth/4
Same as @code{nth1/4}.

@item permutation(+@var{List},?@var{Perm})
@findex permutation/2
@syindex permutation/2
@cnindex permutation/2
True when @var{List} and @var{Perm} are permutations of each other.

@item remove_duplicates(+@var{List}, ?@var{Pruned})
@findex remove_duplicates/2
@syindex remove_duplicates/2
@cnindex remove_duplicates/2
Removes duplicated elements from @var{List}.  Beware: if the @var{List} has
non-ground elements, the result may surprise you.

@item reverse(+@var{List}, ?@var{Reversed})
@findex reverse/2
@syindex reverse/2
@cnindex reverse/2
True when @var{List} and @var{Reversed} are lists with the same elements
but in opposite orders. 
 
@item same_length(?@var{List1}, ?@var{List2})
@findex same_length/2
@syindex same_length/2
@cnindex same_length/2
True when @var{List1} and @var{List2} are both lists and have the same number
of elements.  No relation between the values of their elements is
implied.
Modes @code{same_length(-,+)} and @code{same_length(+,-)} generate either list given
the other; mode @code{same_length(-,-)} generates two lists of the same length,
in which case the arguments will be bound to lists of length 0, 1, 2, ...

@item select(?@var{Element}, ?@var{List}, ?@var{Residue})
@findex select/3
@syindex select/3
@cnindex select/3
True when @var{Set} is a list, @var{Element} occurs in @var{List}, and
@var{Residue} is everything in @var{List} except @var{Element} (things
stay in the same order).
 
@item selectchk(?@var{Element}, ?@var{List}, ?@var{Residue})
@findex selectchk/3
@snindex selectchk/3
@cnindex selectchk/3
Semi-deterministic selection from a list. Steadfast: defines as

@pl_example
selectchk(Elem, List, Residue) :-
        select(Elem, List, Rest0), !,
        Rest = Rest0.
@end pl_example

 
@item sublist(?@var{Sublist}, ?@var{List})
@findex sublist/2
@syindex sublist/2
@cnindex sublist/2
True when both @code{append(_,Sublist,S)} and @code{append(S,_,List)} hold.
 
@item suffix(?@var{Suffix}, ?@var{List})
@findex suffix/2
@syindex suffix/2
@cnindex suffix/2
Holds when @code{append(_,Suffix,List)} holds.

@item sum_list(?@var{Numbers}, ?@var{Total})
@findex sum_list/2
@syindex sum_list/2
@cnindex sum_list/2
True when @var{Numbers} is a list of numbers, and @var{Total} is their sum.

@item sum_list(?@var{Numbers}, +@var{SoFar}, ?@var{Total})
@findex sum_list/3
@syindex sum_list/3
@cnindex sum_list/3
True when @var{Numbers} is a list of numbers, and @var{Total} is the sum of their total plus @var{SoFar}.

@item sumlist(?@var{Numbers}, ?@var{Total})
@findex sumlist/2
@syindex sumlist/2
@cnindex sumlist/2
True when @var{Numbers} is a list of integers, and @var{Total} is their
sum. The same as @code{sum_list/2}, please do use @code{sum_list/2}
instead.

@item max_list(?@var{Numbers}, ?@var{Max})
@findex max_list/2
@syindex max_list/2
@cnindex max_list/2
True when @var{Numbers} is a list of numbers, and @var{Max} is the maximum.

@item min_list(?@var{Numbers}, ?@var{Min})
@findex min_list/2
@syindex min_list/2
@cnindex min_list/2
True when @var{Numbers} is a list of numbers, and @var{Min} is the minimum.

@item numlist(+@var{Low}, +@var{High}, +@var{List})
@findex numlist/3
@syindex numlist/3
@cnindex numlist/3
If @var{Low} and @var{High} are integers with @var{Low} =<
@var{High}, unify @var{List} to a list @code{[Low, Low+1, ...High]}. See
also @code{between/3}.

@item intersection(+@var{Set1}, +@var{Set2}, +@var{Set3})
@findex intersection/3
@syindex intersection/3
@cnindex intersection/3
Succeeds if @var{Set3} unifies with the intersection of @var{Set1} and
@var{Set2}. @var{Set1} and @var{Set2} are lists without duplicates. They
need not be ordered.

@item subtract(+@var{Set}, +@var{Delete}, ?@var{Result})
@findex subtract/3
@syindex subtract/3
@cnindex subtract/3
Delete all elements from @var{Set} that   occur  in @var{Delete} (a set)
and unify the  result  with  @var{Result}.   Deletion  is  based  on
unification using @code{memberchk/2}. The complexity is
@code{|Delete|*|Set|}.

See @code{ord_subtract/3}.
@end table

@node LineUtilities, MapArgs, Lists, Library
@section Line Manipulation Utilities
@cindex Line Utilities Library

This package provides a set of useful predicates to manipulate
sequences of characters codes, usually first read in as a line. It is
available by loading the library @code{library(lineutils)}.

@table @code

@item search_for(+@var{Char},+@var{Line})
@findex search_for/2
@snindex search_for/2
@cnindex search_for/2

Search for a character @var{Char} in the list of codes @var{Line}.

@item search_for(+@var{Char},+@var{Line},-@var{RestOfine})
@findex search_for/3
@snindex search_for/3
@cnindex search_for/3

Search for a character @var{Char} in the list of codes @var{Line},
@var{RestOfLine} has the line to the right.

@item scan_natural(?@var{Nat},+@var{Line},+@var{RestOfLine})
@findex scan_natural/3
@snindex scan_natural/3
@cnindex scan_natural/3

Scan the list of codes @var{Line} for a natural number @var{Nat}, zero
or a positive integer, and unify @var{RestOfLine} with the remainder
of the line.

@item scan_integer(?@var{Int},+@var{Line},+@var{RestOfLine})
@findex scan_integer/3
@snindex scan_integer/3
@cnindex scan_integer/3

Scan the list of codes @var{Line} for an integer @var{Nat}, either a
positive, zero, or negative integer, and unify @var{RestOfLine} with
the remainder of the line.

@item split(+@var{Line},+@var{Separators},-@var{Split})
@findex split/3
@snindex split/3
@cnindex split/3

Unify @var{Words} with a set of strings obtained from @var{Line} by
using the character codes in @var{Separators} as separators. As an
example, consider:
@pl_example
?- split("Hello * I am free"," *",S).

S = ["Hello","I","am","free"] ?

no
@end pl_example

@item split(+@var{Line},-@var{Split})
@findex split/2
@snindex split/2
@cnindex split/2

Unify @var{Words} with a set of strings obtained from @var{Line} by
using the blank characters  as separators.

@item fields(+@var{Line},+@var{Separators},-@var{Split})
@findex fields/3
@snindex fields/3
@cnindex fields/3

Unify @var{Words} with a set of strings obtained from @var{Line} by
using the character codes in @var{Separators} as separators for
fields. If two separators occur in a row, the field is considered
empty. As an example, consider:
@pl_example
?- fields("Hello  I am  free"," *",S).

S = ["Hello","","I","am","","free"] ?
@end pl_example

@item fields(+@var{Line},-@var{Split})
@findex fields/2
@snindex fields/2
@cnindex fields/2

Unify @var{Words} with a set of strings obtained from @var{Line} by
using the blank characters  as field separators.

@item glue(+@var{Words},+@var{Separator},-@var{Line})
@findex glue/3
@snindex glue/3
@cnindex glue/3

Unify @var{Line} with  string obtained by glueing @var{Words} with
the character code @var{Separator}.

@item copy_line(+@var{StreamInput},+@var{StreamOutput})
@findex copy_line/2
@snindex copy_line/2
@cnindex copy_line/2

Copy a line from @var{StreamInput} to @var{StreamOutput}.

@item process(+@var{StreamInp}, +@var{Goal})
@findex process/2
@snindex process/2
@cnindex process/2

For every line @var{LineIn} in stream @var{StreamInp}, call
@code{call(Goal,LineIn)}.

@item filter(+@var{StreamInp}, +@var{StreamOut}, +@var{Goal})
@findex filter/3
@snindex filter/3
@cnindex filter/3

For every line @var{LineIn} in stream @var{StreamInp}, execute
@code{call(Goal,LineIn,LineOut)}, and output @var{LineOut} to
stream @var{StreamOut}.

@item file_filter(+@var{FileIn}, +@var{FileOut}, +@var{Goal})
@findex file_filter/3
@snindex file_filter/3
@cnindex file_filter/3

For every line @var{LineIn} in file @var{FileIn}, execute
@code{call(Goal,LineIn,LineOut)}, and output @var{LineOut} to file
@var{FileOut}.

@item file_filter(+@var{FileIn}, +@var{FileOut}, +@var{Goal},
+@var{FormatCommand},   +@var{Arguments})
@findex file_filter_with_init/5
@snindex file_filter_with_init/5
@cnindex file_filter_with_init/5

Same as @code{file_filter/3}, but before starting the filter execute
@code{format/3} on the output stream, using @var{FormatCommand} and
@var{Arguments}.

@end table


@texinfo


@node MapArgs, MapList, LineUtilities, Library
@section Maplist
@cindex macros

This library provides a set of utilities for applying a predicate to
all sub-terms of a term. They allow to
easily perform the most common do-loop constructs in Prolog. To avoid
performance degradation due to @code{apply/2}, each call creates an
equivalent Prolog program, without meta-calls, which is executed by
the Prolog engine instead. 

@table @code
@item mapargs(+@var{Pred}, +@var{TermIn})
@findex mapargs/2
@snindex mapargs/2
@cnindex mapargs/2
      Applies the predicate @var{Pred} to all
      arguments of @var{TermIn}

@item mapargs(+@var{Pred}, +@var{TermIn}, ?@var{TermOut})
@findex mapargs/3
@snindex mapargs/3
@cnindex mapargs/3
      Creates @var{TermOut} by applying the predicate @var{Pred} to all
      arguments of @var{TermIn}

@item mapargs(+@var{Pred}, +@var{TermIn}, ?@var{TermOut1}, ?@var{TermOut2})
@findex mapargs/4
@snindex mapargs/4
@cnindex mapargs/4
      Creates  @var{TermOut1}  and @var{TermOut2} by applying the predicate @var{Pred} to all
      arguments of @var{TermIn}

@item mapargs(+@var{Pred}, +@var{TermIn}, ?@var{TermOut1}, ?@var{TermOut2}, ?@var{TermOut3})
@findex mapargs/5
@snindex mapargs/5
@cnindex mapargs/5
      Creates  @var{TermOut1}, @var{TermOut2} and  @var{TermOut3} by applying the predicate @var{Pred} to all
      arguments of @var{TermIn}

@item mapargs(+@var{Pred}, +@var{TermIn}, ?@var{TermOut1}, ?@var{TermOut2}, ?@var{TermOut3}, ?@var{TermOut4})
@findex mapargs/6
@snindex mapargs/6
@cnindex mapargs/6
      Creates  @var{TermOut1}, @var{TermOut2}, @var{TermOut3} and  @var{TermOut4} by applying the predicate @var{Pred} to all
      arguments of @var{TermIn}


@item foldargs(+@var{Pred}, +@var{Term}, ?@var{AccIn}, ?@var{AccOut})
@findex foldargs/4
@snindex foldargs/4
@cnindex foldargs/4
  Calls the predicate @var{Pred} on all arguments of @var{Term} and
collects a  result in @var{Accumulator}
         
@item foldargs(+@var{Pred}, +@var{Term}, +@var{Term1}, ?@var{AccIn}, ?@var{AccOut})
@findex foldargs/5
@snindex foldargs/5
@cnindex foldargs/5
  Calls the predicate @var{Pred} on all arguments of @var{Term} and @var{Term1} and
collects a  result in @var{Accumulator}

@item foldargs(+@var{Pred}, +@var{Term}, +@var{Term1}, +@var{Term2}, ?@var{AccIn}, ?@var{AccOut})
@findex foldargs/6
@snindex foldargs/6
@cnindex foldargs/6
  Calls the predicate @var{Pred} on all arguments of @var{Term}, +@var{Term1} and @var{Term2} and
collects a  result in @var{Accumulator}

@item foldargs(+@var{Pred}, +@var{Term}, +@var{Term1}, +@var{Term2}, +@var{Term3}, ?@var{AccIn}, ?@var{AccOut})
@findex foldargs/7
@snindex foldargs/7
@cnindex foldargs/7
  Calls the predicate @var{Pred} on all arguments of @var{Term}, +@var{Term1}, +@var{Term2} and @var{Term3} and
collects a  result in @var{Accumulator}

@item sumargs(+@var{Pred}, +@var{Term}, ?@var{AccIn}, ?@var{AccOut})
@findex sumargs/4
@snindex sumargs/4
@cnindex sumargs/4
  Calls the predicate @var{Pred} on all arguments of @var{Term} and
collects a  result in @var{Accumulator} (uses reverse order than foldargs).

@end table

@texinfo


@node MapList, matrix, MapArgs, Library
@section Maplist
@cindex macros

This library provides a set of utilities for applying a predicate to
all elements of a list or to all sub-terms of a term. They allow to
easily perform the most common do-loop constructs in Prolog. To avoid
performance degradation due to @code{apply/2}, each call creates an
equivalent Prolog program, without meta-calls, which is executed by
the Prolog engine instead. Note that if the equivalent Prolog program
already exists, it will be simply used. The library is based on code
by Joachim Schimpf and on code from SWI-Prolog.

The following routines are available once included with the
@code{use_module(library(apply_macros))} command.

@table @code
@item maplist(:@var{Pred}, ?@var{ListIn}, ?@var{ListOut})
@findex maplist/3
@snindex maplist/3
@cnindex maplist/3
      Creates @var{ListOut} by applying the predicate @var{Pred} to all
elements of @var{ListIn}.

@item maplist(:@var{Pred}, ?@var{ListIn})
@findex maplist/2
@snindex maplist/2
@cnindex maplist/2
      Creates @var{ListOut} by applying the predicate @var{Pred} to all
elements of @var{ListIn}.

@item maplist(:@var{Pred}, ?@var{L1}, ?@var{L2}, ?@var{L3})
@findex maplist/4
@snindex maplist/4
@cnindex maplist/4
      @var{L1},  @var{L2}, and @var{L3} are such that
      @code{call(@var{Pred},@var{A1},@var{A2},@var{A3})} holds for every
      corresponding element in lists @var{L1},  @var{L2}, and @var{L3}.

@item maplist(:@var{Pred}, ?@var{L1}, ?@var{L2}, ?@var{L3}, ?@var{L4})
@findex maplist/5
@snindex maplist/5
@cnindex maplist/5
      @var{L1}, @var{L2}, @var{L3}, and @var{L4} are such that
      @code{call(@var{Pred},@var{A1},@var{A2},@var{A3},@var{A4})} holds
      for every corresponding element in lists @var{L1}, @var{L2}, @var{L3}, and
      @var{L4}.

@item checklist(:@var{Pred}, +@var{List})
@findex checklist/2
@snindex checklist/2
@cnindex checklist/2
      Succeeds if the predicate @var{Pred} succeeds on all elements of @var{List}.

@item selectlist(:@var{Pred}, +@var{ListIn}, ?@var{ListOut})
@findex selectlist/3
@snindex selectlist/3
@cnindex selectlist/3
      Creates @var{ListOut} of all list elements of @var{ListIn} that pass a given test

@item selectlist(:@var{Pred}, +@var{ListIn}, +@var{ListInAux}, ?@var{ListOut})
@findex selectlist/4
@snindex selectlist/4
@cnindex selectlist/4
      Creates @var{ListOut} of all list elements of @var{ListIn} that
      pass the given test @var{Pred} using +@var{ListInAux} as an
      auxiliary element.

@item convlist(:@var{Pred}, +@var{ListIn}, ?@var{ListOut})
@findex convlist/3
@snindex convlist/3
@cnindex convlist/3
      A combination of @code{maplist} and @code{selectlist}: creates @var{ListOut} by
applying the predicate @var{Pred} to all list elements on which
@var{Pred} succeeds

@item sumlist(:@var{Pred}, +@var{List}, ?@var{AccIn}, ?@var{AccOut})
@findex sumlist/4
@snindex sumlist/4
@cnindex sumlist/4
      Calls @var{Pred} on all elements of List and collects a result in
@var{Accumulator}. Same as @code{foldl/4}.

@item foldl(:@var{Pred}, +@var{List}, ?@var{AccIn}, ?@var{AccOut})
@findex foldl/4
@snindex foldl/4
@cnindex foldl/4
      Calls @var{Pred} on all elements of @code{List} and collects a result in
@var{Accumulator}.

@item foldl(:@var{Pred}, +@var{List1}, +@var{List2}, ?@var{AccIn}, ?@var{AccOut})
@findex foldl/5
@snindex foldl/5
@cnindex foldl/5
      Calls @var{Pred} on all elements of @code{List1} and
@code{List2} and collects a result in @var{Accumulator}. Same as
@code{foldr/4}.

@item foldl(:@var{Pred}, +@var{List1}, +@var{List2}, +@var{List3}, ?@var{AccIn}, ?@var{AccOut})
@findex foldl/6
@snindex foldl/6
@cnindex foldl/6
      Calls @var{Pred} on all elements of @code{List1}, @code{List2}, and
@code{List3} and collects a result in @var{Accumulator}.

@item foldl(:@var{Pred}, +@var{List1}, +@var{List2}, +@var{List3}, +@var{List4}, ?@var{AccIn}, ?@var{AccOut})
@findex foldl/7
@snindex foldl/7
@cnindex foldl/7
      Calls @var{Pred} on all elements of @code{List1}, @code{List2}, @code{List3}, and
@code{List4} and collects a result in @var{Accumulator}.

@item foldl2(:@var{Pred}, +@var{List}, ?@var{X0}, ?@var{X}, ?@var{Y0}, ?@var{Y})
@findex foldl2/6
@snindex foldl2/6
@cnindex foldl2/6
      Calls @var{Pred} on all elements of @code{List} and collects a result in
@var{X} and @var{Y}.

@item foldl2(:@var{Pred}, +@var{List}, ?@var{List1}, ?@var{X0}, ?@var{X}, ?@var{Y0}, ?@var{Y})
@findex foldl2/7
@snindex foldl2/7
@cnindex foldl2/7
      Calls @var{Pred} on all elements of @var{List}  and @var{List1}  and collects a result in
@var{X} and @var{Y}.

@item foldl2(:@var{Pred}, +@var{List}, ?@var{List1}, ?@var{List2}, ?@var{X0}, ?@var{X}, ?@var{Y0}, ?@var{Y})
@findex foldl2/8
@snindex foldl2/8
@cnindex foldl2/8
      Calls @var{Pred} on all elements of @var{List}, @var{List1}  and @var{List2}  and collects a result in
@var{X} and @var{Y}.

@item foldl3(:@var{Pred}, +@var{List1}, ?@var{List2}, ?@var{X0}, ?@var{X}, ?@var{Y0}, ?@var{Y}, ?@var{Z0}, ?@var{Z})

@findex foldl3/6
@snindex foldl3/6
@cnindex foldl3/6
      Calls @var{Pred} on all elements of @code{List} and collects a
result in @var{X}, @var{Y} and @var{Z}.

@item foldl4(:@var{Pred}, +@var{List1}, ?@var{List2}, ?@var{X0}, ?@var{X}, ?@var{Y0}, ?@var{Y}, ?@var{Z0}, ?@var{Z}, ?@var{W0}, ?@var{W})

@findex foldl4/8
@snindex foldl4/8
@cnindex foldl4/8
      Calls @var{Pred} on all elements of @code{List} and collects a
result in @var{X}, @var{Y}, @var{Z} and @var{W}.

@item scanl(:@var{Pred}, +@var{List}, +@var{V0}, ?@var{Values})
@findex scanl/4
@snindex scanl/4
@cnindex scanl/4
         Left scan of  list.  The  scanl   family  of  higher  order list
    operations is defined by:

@pl_example
      scanl(P, [X11,...,X1n], ..., [Xm1,...,Xmn], V0, [V0,V1,...,Vn]) :-
        P(X11, ..., Xm1, V0, V1),
        ...
            P(X1n, ..., Xmn, Vn-1, Vn).
@end pl_example


@item scanl(:@var{Pred}, +@var{List1}, +@var{List2}, ?@var{V0}, ?@var{Vs})
@findex scanl/5
@snindex scanl/5
@cnindex scanl/5
         Left scan of  list.  

@item scanl(:@var{Pred}, +@var{List1}, +@var{List2}, +@var{List3}, ?@var{V0}, ?@var{Vs})
@findex scanl/6
@snindex scanl/6
@cnindex scanl/6
         Left scan of  list.  

@item scanl(:@var{Pred}, +@var{List1}, +@var{List2}, +@var{List3}, +@var{List4}, ?@var{V0}, ?@var{Vs})
@findex scanl/7
@snindex scanl/7
@cnindex scanl/7
         Left scan of  list.  

@item mapnodes(+@var{Pred}, +@var{TermIn}, ?@var{TermOut}) 
@findex mapnodes/3
@snindex mapnodes/3
@cnindex mapnodes/3
      Creates @var{TermOut} by applying the predicate @var{Pred}
      to all sub-terms of @var{TermIn} (depth-first and left-to-right order)

@item checknodes(+@var{Pred}, +@var{Term}) 
@findex checknodes/3
@snindex checknodes/3
@cnindex checknodes/3
      Succeeds if the predicate @var{Pred} succeeds on all sub-terms of
      @var{Term} (depth-first and left-to-right order)

@item sumnodes(+@var{Pred}, +@var{Term}, ?@var{AccIn}, ?@var{AccOut})
@findex sumnodes/4
@snindex sumnodes/4
@cnindex sumnodes/4
      Calls the predicate @var{Pred} on all sub-terms of @var{Term} and
collect a result in @var{Accumulator} (depth-first and left-to-right
order)

@item include(+@var{Pred}, +@var{ListIn}, ?@var{ListOut})
@findex include/3
@snindex include/3
@cnindex include/3
      Same as @code{selectlist/3}.

@item exclude(+@var{Goal}, +@var{List1}, ?@var{List2})
@findex exclude/3
@snindex exclude/3
@cnindex exclude/3
Filter elements for which @var{Goal} fails. True if @var{List2} contains
      those elements @var{Xi} of @var{List1} for which @code{call(Goal, Xi)} fails.

@item partition(+@var{Pred},  +@var{List1}, ?@var{Included}, ?@var{Excluded})
@findex partition/4
@snindex partition/4
@cnindex partition/4
Filter elements of @var{List} according to @var{Pred}. True if
@var{Included} contains all elements for which @code{call(Pred, X)}
succeeds and @var{Excluded} contains the remaining elements.

@item partition(+@var{Pred},  +@var{List1}, ?@var{Lesser}, ?@var{Equal}, ?@var{Greater})
@findex partition/5
@snindex partition/5
@cnindex partition/5
Filter list according to @var{Pred} in three sets. For each element
@var{Xi} of @var{List}, its destination is determined by
@code{call(Pred, Xi, Place)}, where @var{Place} must be unified to one
of @code{<}, @code{=} or @code{>}. @code{Pred} must be deterministic.

@end table

Examples:

@pl_example
%given
plus(X,Y,Z) :- Z is X + Y.
plus_if_pos(X,Y,Z) :- Y > 0, Z is X + Y.
vars(X, Y, [X|Y]) :- var(X), !.
vars(_, Y, Y).
trans(TermIn, TermOut) :-
  nonvar(TermIn),
  TermIn =.. [p|Args],
  TermOut =..[q|Args], !.
trans(X,X).

%success

maplist(plus(1), [1,2,3,4], [2,3,4,5]).
checklist(var, [X,Y,Z]).
selectlist(<(0), [-1,0,1], [1]).
convlist(plus_if_pos(1), [-1,0,1], [2]).
sumlist(plus, [1,2,3,4], 1, 11).
mapargs(number_atom,s(1,2,3), s('1','2','3')).
sumargs(vars, s(1,X,2,Y), [], [Y,X]).m
apnodes(trans, p(a,p(b,a),c), q(a,q(b,a),c)).
checknodes(\==(T), p(X,p(Y,X),Z)).
sumnodes(vars, [c(X), p(X,Y), q(Y)], [], [Y,Y,X,X]).
% another one
maplist(mapargs(number_atom),[c(1),s(1,2,3)],[c('1'),s('1','2','3')]).
@end pl_example

@end texinfo


@node matrix, MATLAB, MapList, Library
@section Matrix Library
@cindex Matrix Library

This package provides a fast implementation of multi-dimensional
matrices of integers and floats. In contrast to dynamic arrays, these
matrices are multi-dimensional and compact. In contrast to static
arrays. these arrays are allocated in the stack. Matrices are available
by loading the library @code{library(matrix)}. They are multimensional
objects of type:
@itemize 
@item @t{terms}: Prolog terms
@item  @t{ints}: bounded integers, represented as an opaque term. The
maximum integer depends on hardware, but should be obtained from the
natural size of the machine.
@item  @t{floats}: floating-poiny numbers, represented as an opaque term.
@end itemize

Matrix elements can be accessed through the @code{matrix_get/2}
predicate or through an @t{R}-inspired access notation (that uses the ciao
style extension to @code{[]}.  Examples include:

@table @code
@item @var{E} <== @var{X}[2,3]
Access the second row, third column of matrix @t{X}. Indices start from
@code{0},
@item @var{L} <== @var{X}[2,_]
Access all the second row, the output is a list ofe elements.
@item @var{L} <== @var{X}[2..4,_]
Access all the second, thrd and fourth rows, the output is a list of elements.
@item @var{L} <== @var{X}[2..4+3,_]
Access all the fifth, sixth and eight rows, the output is a list of elements.
@end table

The matrix library also supports a B-Prolog/ECliPSe inspired @code{foreach} ITerator to iterate over
elements of a matrix:

@table @code
@item foreach(I in 0..N1, X[I] <== Y[I])
Copies a vector, element by element.
@item foreach([I in 0..N1, J in I..N1], Z[I,J] <== X[I,J] - X[I,J])
The lower-triangular matrix @var{Z} is the difference between the
lower-triangular and upper-triangular parts of @var{X}.
@item foreach([I in 0..N1, J in 0..N1], plus(X[I,J]), 0, Sum)
Add all elements of a matrix by using @var{Sum} as an accumulator.
@end table

Notice that the library does not support all known matrix operations. Please
contact the YAP maintainers if you require extra functionality.

@table @code

@item @var{X} = array[@var{Dim1},...,@var{Dimn}] of @var{Objects}
@findex of/2
@snindex of/2
@cnindex of/2
The @code{of/2} operator can be used to create a new array of
@var{Objects}. The objects supported are:

@table @code
@item Unbound Variable
create an array of free variables
@item ints 
create an array of integers
@item floats 
create an array of floating-point numbers
@item @var{I}:@var{J}
create an array with integers from @var{I} to @var{J}
@item [..]
create an array from the values in a list
 @end table

The dimensions can be given as an integer, and the matrix will be
indexed @code{C}-style from  @code{0..(@var{Max}-1)}, or can be given
as  an interval @code{@var{Base}..@var{Limit}}. In the latter case,
matrices of integers and of floating-point numbers should have the same
@var{Base} on every dimension.

@item ?@var{LHS} <== @var{RHS}
@findex <==/2
@snindex <==/2
@cnindex <==/2
General matrix assignment operation. It evaluates the right-hand side
and then acts different according to the
left-hand side and to the matrix:
@itemize @bullet
@item if @var{LHS} is part of an integer or floating-point matrix,
perform non-backtrackable assignment.
@item other unify left-hand side and right-hand size.
@end itemize

The right-hand side supports the following operators: 
@table @code
@item []/2
written as @var{M}[@var{Offset}]: obtain an element or list of elements
of matrix @var{M} at offset @var{Offset}.
@item matrix/1
create a vector from a list
@item matrix/2
create a matrix from a list. Oprions are:
@table @code
@item dim=
a list of dimensiona
@item type=
integers, floating-point or terms
@item base=
a list of base offsets per dimension (all must be the same for arrays of
integers and floating-points
@end table
@item matrix/3
create matrix giving two options
@item dim/1
list with matrix dimensions
@item nrow/1
number of rows in bi-dimensional matrix
@item ncol/1
number of columns in bi-dimensional matrix
@item length/1
size of a matrix
@item size/1
size of a matrix
@item max/1
maximum element of a numeric matrix
@item maxarg/1
argument of maximum element of a numeric matrix
@item min/1
minimum element of a numeric matrix
@item minarg/1
argument of minimum element of a numeric matrix
@item list/1
represent matrix as a list
@item lists/2
represent matrix as list of embedded lists
@item ../2
@var{I}..@var{J} generates a list with all integers from @var{I} to
@var{J}, included.
@item +/2
add two numbers, add two matrices element-by-element, or add a number to
all elements of a matrix or list
@item -/2 
subtract two numbers, subtract two matrices or lists element-by-element, or subtract a number from
all elements of a matrix or list
@item * /2 
multiply two numbers, multiply two matrices or lists element-by-element, or multiply a number from
all elements of a matrix or list
@item log/1 
natural logarithm of a number, matrix or list
@item exp/1 
natural exponentiation of a number, matrix or list
@end table

@item foreach(@var{Sequence}, @var{Goal})
@findex foreach_matrix/2
@snindex foreach_matrix/2
@cnindex foreach_matrix/2
Deterministic iterator. The ranges are given by @var{Sequence} that is
either @code{@var{I} in @var{M}..@var{N}}, or of the form 
@code{[@var{I},@var{J}] ins @var{M}..@var{N}}, or a list of the above conditions. 

Variables in the goal are assumed to be global, ie, share a single value
in the execution. The exceptions are the iteration indices. Moreover, if
the goal is of the form @code{@var{Locals}^@var{G}} all variables
occurring in @var{Locals} are marked as local. As an example:
@pl_example
foreach([I,J] ins 1..N, A^(A <==M[I,J], N[I] <== N[I] + A*A) )
@end pl_example
the variables @var{I}, @var{J} and @var{A} are duplicated for every
call (local), whereas the matrices @var{M} and @var{N} are shared
throughout the execution (global).

@item foreach(@var{Sequence}, @var{Goal}, @var{Acc0}, @var{AccF})
@findex foreach/4
@snindex foreach/4
@cnindex foreach/4
Deterministic iterator with accumulator style arguments.

@item matrix_new(+@var{Type},+@var{Dims},-@var{Matrix})
@findex matrix_new/3
@snindex matrix_new/3
@cnindex matrix_new/3

Create a new matrix @var{Matrix} of type @var{Type}, which may be one of
@code{ints} or @code{floats}, and with a list of dimensions @var{Dims}.
The matrix will be initialised to zeros.

@example
?- matrix_new(ints,[2,3],Matrix).

Matrix = @{..@}
@end example
Notice that currently YAP will always write a matrix of numbers as @code{@{..@}}.

@item matrix_new(+@var{Type},+@var{Dims},+@var{List},-@var{Matrix})
@findex matrix_new/4
@snindex matrix_new/4
@cnindex matrix_new/4

Create a new matrix @var{Matrix} of type @var{Type}, which may be one of
@code{ints} or @code{floats}, with dimensions @var{Dims}, and
initialised from list @var{List}.

@item matrix_new_set(?@var{Dims},+@var{OldMatrix},+@var{Value},-@var{NewMatrix})
@findex matrix_new_set/4
@snindex matrix_new_set/4
@cnindex matrix_new_set/4

Create a new matrix @var{NewMatrix} of type @var{Type}, with dimensions
@var{Dims}. The elements of @var{NewMatrix} are set to @var{Value}.

@item matrix_dims(+@var{Matrix},-@var{Dims})
@findex matrix_dims/2
@snindex matrix_dims/2
@cnindex matrix_dims/2

Unify @var{Dims} with a list of dimensions for @var{Matrix}.

@item matrix_ndims(+@var{Matrix},-@var{Dims})
@findex matrix_ndims/2
@snindex matrix_ndims/2
@cnindex matrix_ndims/2

Unify @var{NDims} with the number of dimensions for @var{Matrix}.

@item matrix_size(+@var{Matrix},-@var{NElems})
@findex matrix_size/2
@snindex matrix_size/2
@cnindex matrix_size/2

Unify @var{NElems} with the number of elements for @var{Matrix}.

@item matrix_type(+@var{Matrix},-@var{Type})
@findex matrix_type/2
@snindex matrix_type/2
@cnindex matrix_type/2

Unify @var{NElems} with the type of the elements in @var{Matrix}.

@item matrix_to_list(+@var{Matrix},-@var{Elems})
@findex matrix_to_list/2
@snindex matrix_to_list/2
@cnindex matrix_to_list/2

Unify @var{Elems} with the list including all the elements in @var{Matrix}.

@item matrix_get(+@var{Matrix},+@var{Position},-@var{Elem})
@findex matrix_get/3
@snindex matrix_get/3
@cnindex matrix_get/3

Unify @var{Elem} with the element of @var{Matrix} at position
@var{Position}.

@item matrix_get(+@var{Matrix}[+@var{Position}],-@var{Elem})
@findex matrix_get/2
@snindex matrix_get/2
@cnindex matrix_get/2

Unify @var{Elem} with the element @var{Matrix}[@var{Position}].

@item matrix_set(+@var{Matrix},+@var{Position},+@var{Elem})
@findex matrix_set/3
@snindex matrix_set/3
@cnindex matrix_set/3

Set the element of @var{Matrix} at position
@var{Position} to  @var{Elem}.

@item matrix_set(+@var{Matrix}[+@var{Position}],+@var{Elem})
@findex matrix_set/2
@snindex matrix_set/2
@cnindex matrix_set/2

Set the element of @var{Matrix}[@var{Position}] to  @var{Elem}.

@item matrix_set_all(+@var{Matrix},+@var{Elem})
@findex matrix_set_all/2
@snindex matrix_set_all/2
@cnindex matrix_set_all/2

Set all element of @var{Matrix} to @var{Elem}.

@item matrix_add(+@var{Matrix},+@var{Position},+@var{Operand})
@findex matrix_add/3
@snindex matrix_add/3
@cnindex matrix_add/3

Add @var{Operand} to the element of @var{Matrix} at position
@var{Position}.

@item matrix_inc(+@var{Matrix},+@var{Position})
@findex matrix_inc/2
@snindex matrix_inc/2
@cnindex matrix_inc/2

Increment the element of @var{Matrix} at position @var{Position}.

@item matrix_inc(+@var{Matrix},+@var{Position},-@var{Element})
@findex matrix_inc/3
@snindex matrix_inc/3
@cnindex matrix_inc/3

Increment the element of @var{Matrix} at position @var{Position} and
unify with @var{Element}.

@item matrix_dec(+@var{Matrix},+@var{Position})
@findex matrix_dec/2
@snindex matrix_dec/2
@cnindex matrix_dec/2

Decrement the element of @var{Matrix} at position @var{Position}.

@item matrix_dec(+@var{Matrix},+@var{Position},-@var{Element})
@findex matrix_dec/3
@snindex matrix_dec/3
@cnindex matrix_dec/3

Decrement the element of @var{Matrix} at position @var{Position} and
unify with @var{Element}.

@item matrix_arg_to_offset(+@var{Matrix},+@var{Position},-@var{Offset})
@findex matrix_arg_to_offset/3
@snindex matrix_arg_to_offset/3
@cnindex matrix_arg_to_offset/3

Given matrix @var{Matrix} return what is the numerical @var{Offset} of
the element at @var{Position}.

@item matrix_offset_to_arg(+@var{Matrix},-@var{Offset},+@var{Position})
@findex matrix_offset_to_arg/3
@snindex matrix_offset_to_arg/3
@cnindex matrix_offset_to_arg/3

Given a position @var{Position } for matrix @var{Matrix} return the
corresponding numerical @var{Offset} from the beginning of the matrix.

@item matrix_max(+@var{Matrix},+@var{Max})
@findex matrix_max/2
@snindex matrix_max/2
@cnindex matrix_max/2

Unify @var{Max} with the maximum in matrix  @var{Matrix}.

@item matrix_maxarg(+@var{Matrix},+@var{Maxarg})
@findex matrix_maxarg/2
@snindex matrix_maxarg/2
@cnindex matrix_maxarg/2

Unify @var{Max} with the position of the maximum in matrix  @var{Matrix}.

@item matrix_min(+@var{Matrix},+@var{Min})
@findex matrix_min/2
@snindex matrix_min/2
@cnindex matrix_min/2

Unify @var{Min} with the minimum in matrix  @var{Matrix}.

@item matrix_minarg(+@var{Matrix},+@var{Minarg})
@findex matrix_minarg/2
@snindex matrix_minarg/2
@cnindex matrix_minarg/2

Unify @var{Min} with the position of the minimum in matrix  @var{Matrix}.

@item matrix_sum(+@var{Matrix},+@var{Sum})
@findex matrix_sum/2
@snindex matrix_sum/2
@cnindex matrix_sum/2

Unify @var{Sum} with the sum of all elements in matrix  @var{Matrix}.

@c @item matrix_add_to_all(+@var{Matrix},+@var{Element})
@c @findex matrix_add_to_all/2
@c @snindex matrix_add_to_all/2
@c @cnindex matrix_add_to_all/2

@c Add @var{Element} to all elements of matrix  @var{Matrix}.

@item matrix_agg_lines(+@var{Matrix},+@var{Aggregate})
@findex matrix_agg_lines/2
@snindex matrix_agg_lines/2
@cnindex matrix_agg_lines/2

If @var{Matrix} is a n-dimensional matrix, unify @var{Aggregate} with
the n-1 dimensional matrix where each element is obtained by adding all
Matrix elements with same last n-1 index.

@item matrix_agg_cols(+@var{Matrix},+@var{Aggregate})
@findex matrix_agg_cols/2
@snindex matrix_agg_cols/2
@cnindex matrix_agg_cols/2

If @var{Matrix} is a n-dimensional matrix, unify @var{Aggregate} with
the one dimensional matrix where each element is obtained by adding all
Matrix elements with same  first index.

@item matrix_op(+@var{Matrix1},+@var{Matrix2},+@var{Op},-@var{Result})
@findex matrix_op/4
@snindex matrix_op/4
@cnindex matrix_op/4

@var{Result} is the result of applying @var{Op} to matrix @var{Matrix1}
and @var{Matrix2}. Currently, only addition (@code{+}) is supported.

@item matrix_op_to_all(+@var{Matrix1},+@var{Op},+@var{Operand},-@var{Result})
@findex matrix_op_to_all/4
@snindex matrix_op_to_all/4
@cnindex matrix_op_to_all/4

@var{Result} is the result of applying @var{Op} to all elements of
@var{Matrix1}, with @var{Operand} as the second argument. Currently,
only addition (@code{+}), multiplication (@code{*}), and division
(@code{/}) are supported.

@item matrix_op_to_lines(+@var{Matrix1},+@var{Lines},+@var{Op},-@var{Result})
@findex matrix_op_to_lines/4
@snindex matrix_op_to_lines/4
@cnindex matrix_op_to_lines/4

@var{Result} is the result of applying @var{Op} to all elements of
@var{Matrix1}, with the corresponding element in @var{Lines} as the
second argument. Currently, only division (@code{/}) is supported.

@item matrix_op_to_cols(+@var{Matrix1},+@var{Cols},+@var{Op},-@var{Result})
@findex matrix_op_to_cols/4
@snindex matrix_op_to_cols/4
@cnindex matrix_op_to_cols/4

@var{Result} is the result of applying @var{Op} to all elements of
@var{Matrix1}, with the corresponding element in @var{Cols} as the
second argument. Currently, only addition (@code{+}) is
supported. Notice that @var{Cols} will have n-1 dimensions.

@item matrix_shuffle(+@var{Matrix},+@var{NewOrder},-@var{Shuffle})
@findex matrix_shuffle/3
@snindex matrix_shuffle/3
@cnindex matrix_shuffle/3

Shuffle the dimensions of matrix @var{Matrix} according to
@var{NewOrder}. The list @var{NewOrder} must have all the dimensions of
@var{Matrix}, starting from 0.

@item matrix_transpose(+@var{Matrix},-@var{Transpose})
@findex matrix_reorder/3
@snindex matrix_reorder/3
@cnindex matrix_reorder/3

Transpose matrix @var{Matrix} to  @var{Transpose}. Equivalent to:
@example
matrix_transpose(Matrix,Transpose) :-
        matrix_shuffle(Matrix,[1,0],Transpose).
@end example

@item matrix_expand(+@var{Matrix},+@var{NewDimensions},-@var{New})
@findex matrix_expand/3
@snindex matrix_expand/3
@cnindex matrix_expand/3

Expand @var{Matrix} to occupy new dimensions. The elements in
@var{NewDimensions} are either 0, for an existing dimension, or a
positive integer with the size of the new dimension.

@item matrix_select(+@var{Matrix},+@var{Dimension},+@var{Index},-@var{New})
@findex matrix_select/4
@snindex matrix_select/4
@cnindex matrix_select/4

Select from @var{Matrix} the elements who have @var{Index} at
@var{Dimension}.

@item matrix_row(+@var{Matrix},+@var{Column},-@var{NewMatrix})
@findex matrix_row/3
@snindex matrix_row/3
@cnindex matrix_row/3

Select from @var{Matrix} the row matching @var{Column} as new matrix @var{NewMatrix}. @var{Column} must have one less dimension than the original matrix.
@var{Dimension}.

@end table

@node MATLAB, Non-Backtrackable Data Structures, matrix, Library
@section MATLAB Package Interface
@cindex Matlab Interface

The MathWorks MATLAB is a widely used package for array
processing. YAP now includes a straightforward interface to MATLAB. To
actually use it, you need to install YAP calling @code{configure} with
the @code{--with-matlab=DIR} option, and you need to call
@code{use_module(library(lists))} command.

Accessing the matlab dynamic libraries can be complicated. In Linux
machines, to use this interface, you may have to set the environment
variable @t{LD_LIBRARY_PATH}. Next, follows an example using bash in a
64-bit Linux PC:
@example
export LD_LIBRARY_PATH=''$MATLAB_HOME"/sys/os/glnxa64:''$MATLAB_HOME"/bin/glnxa64:''$LD_LIBRARY_PATH"
@end example
where @code{MATLAB_HOME} is the directory where matlab is installed
at. Please replace @code{ax64} for @code{x86} on a 32-bit PC.

@table @code

@item start_matlab(+@var{Options})
@findex start_matlab/1
@snindex start_matlab/1
@cnindex start_matlab/1
Start a matlab session. The argument @var{Options} may either be the
empty string/atom or the command to call matlab. The command may fail.

@item close_matlab
@findex close_matlab/0
@snindex close_matlab/0
@cnindex close_matlab/0
Stop the current matlab session.

@item matlab_on
@findex matlab_on/0
@snindex matlab_on/0
@cnindex matlab_on/0
Holds if a matlab session is on.

@item matlab_eval_string(+@var{Command})
@findex matlab_eval_string/1
@snindex matlab_eval_string/1
@cnindex matlab_eval_string/1
Holds if matlab evaluated successfully the command @var{Command}.

@item matlab_eval_string(+@var{Command}, -@var{Answer})
@findex matlab_eval_string/2
@snindex matlab_eval_string/2
@cnindex matlab_eval_string/2
MATLAB will evaluate the command @var{Command} and unify @var{Answer}
with a string reporting the result.


@item matlab_cells(+@var{Size}, ?@var{Array})
@findex matlab_cells/2
@snindex matlab_cells/2
@cnindex matlab_cells/2
MATLAB will create an empty vector of cells of size @var{Size}, and if
@var{Array} is bound to an atom, store the array in the matlab
variable with name @var{Array}. Corresponds to the MATLAB command @code{cells}.


@item matlab_cells(+@var{SizeX}, +@var{SizeY}, ?@var{Array})
@findex matlab_cells/3
@snindex matlab_cells/3
@cnindex matlab_cells/3
MATLAB will create an empty array of cells of size @var{SizeX} and
@var{SizeY}, and if @var{Array} is bound to an atom, store the array
in the matlab variable with name @var{Array}.  Corresponds to the
MATLAB command @code{cells}.

@item matlab_initialized_cells(+@var{SizeX}, +@var{SizeY}, +@var{List}, ?@var{Array})
@findex matlab_initialized_cells/4
@snindex matlab_initialized_cells/4
@cnindex matlab_initialized_cells/4
MATLAB will create an array of cells of size @var{SizeX} and
@var{SizeY}, initialized from the list @var{List}, and if @var{Array}
is bound to an atom, store the array in the matlab variable with name
@var{Array}.

@item matlab_matrix(+@var{SizeX}, +@var{SizeY}, +@var{List}, ?@var{Array})
@findex matlab_matrix/4
@snindex matlab_matrix/4
@cnindex matlab_matrix/4
MATLAB will create an array of floats of size @var{SizeX} and @var{SizeY},
initialized from the list @var{List}, and if @var{Array} is bound to
an atom, store the array in the matlab variable with name @var{Array}.

@item matlab_set(+@var{MatVar}, +@var{X}, +@var{Y}, +@var{Value})
@findex matlab_set/4
@snindex matlab_set/4
@cnindex matlab_set/4
Call MATLAB to set element @var{MatVar}(@var{X}, @var{Y}) to
@var{Value}. Notice that this command uses the MATLAB array access
convention.

@item matlab_get_variable(+@var{MatVar}, -@var{List})
@findex matlab_get_variable/2
@snindex matlab_get_variable/2
@cnindex matlab_get_variable/2
Unify MATLAB variable @var{MatVar} with the List @var{List}.

@item matlab_item(+@var{MatVar}, +@var{X}, ?@var{Val})
@findex matlab_item/3
@snindex matlab_item/3
@cnindex matlab_item/3
Read or set MATLAB @var{MatVar}(@var{X}) from/to @var{Val}. Use
@code{C} notation for matrix access (ie, starting from 0).

@item matlab_item(+@var{MatVar}, +@var{X}, +@var{Y}, ?@var{Val})
@findex matlab_item/4
@snindex matlab_item/4
@cnindex matlab_item/4
Read or set MATLAB @var{MatVar}(@var{X},@var{Y}) from/to @var{Val}. Use
@code{C} notation for matrix access (ie, starting from 0).

@item matlab_item1(+@var{MatVar}, +@var{X}, ?@var{Val})
@findex matlab_item1/3
@snindex matlab_item1/3
@cnindex matlab_item1/3
Read or set MATLAB @var{MatVar}(@var{X}) from/to @var{Val}. Use
MATLAB notation for matrix access (ie, starting from 1).

@item matlab_item1(+@var{MatVar}, +@var{X}, +@var{Y}, ?@var{Val})
@findex matlab_item1/4
@snindex matlab_item1/4
@cnindex matlab_item1/4
Read or set MATLAB @var{MatVar}(@var{X},@var{Y}) from/to @var{Val}. Use
MATLAB notation for matrix access (ie, starting from 1).

@item matlab_sequence(+@var{Min}, +@var{Max}, ?@var{Array})
@findex matlab_sequence/3
@snindex matlab_sequence/3
@cnindex matlab_sequence/3
MATLAB will create a sequence going from @var{Min} to @var{Max}, and
if @var{Array} is bound to an atom, store the sequence in the matlab
variable with name @var{Array}.

@item matlab_vector(+@var{Size}, +@var{List}, ?@var{Array})
@findex matlab_vector/4
@snindex matlab_vector/4
@cnindex matlab_vector/4
MATLAB will create a vector of floats of size @var{Size}, initialized
from the list @var{List}, and if @var{Array} is bound to an atom,
store the array in the matlab variable with name @var{Array}.

@item matlab_zeros(+@var{Size}, ?@var{Array})
@findex matlab_zeros/2
@snindex matlab_zeros/2
@cnindex matlab_zeros/2
MATLAB will create a vector of zeros of size @var{Size}, and if
@var{Array} is bound to an atom, store the array in the matlab
variable with name @var{Array}. Corresponds to the MATLAB command
@code{zeros}.

@item matlab_zeros(+@var{SizeX}, +@var{SizeY}, ?@var{Array})
@findex matlab_zeros/3
@snindex matlab_zeros/3
@cnindex matlab_zeros/3
MATLAB will create an array of zeros of size @var{SizeX} and
@var{SizeY}, and if @var{Array} is bound to an atom, store the array
in the matlab variable with name @var{Array}.  Corresponds to the
MATLAB command @code{zeros}.


@item matlab_zeros(+@var{SizeX}, +@var{SizeY}, +@var{SizeZ}, ?@var{Array})
@findex matlab_zeros/4
@snindex matlab_zeros/4
@cnindex matlab_zeros/4
MATLAB will create an array of zeros of size @var{SizeX}, @var{SizeY},
and @var{SizeZ}. If @var{Array} is bound to an atom, store the array
in the matlab variable with name @var{Array}.  Corresponds to the
MATLAB command @code{zeros}.




@end table

@node Non-Backtrackable Data Structures, Ordered Sets, MATLAB, Library
@section Non-Backtrackable Data Structures

The following routines implement well-known data-structures using global
non-backtrackable variables (implemented on the Prolog stack). The
data-structures currently supported are Queues, Heaps, and Beam for Beam
search. They are allowed through @code{library(nb)}. 

@table @code
@item nb_queue(-@var{Queue})
@findex nb_queue/1
@snindex nb_queue/1
@cnindex nb_queue/1
Create a @var{Queue}.

@item nb_queue_close(+@var{Queue}, -@var{Head}, ?@var{Tail})
@findex nb_queue_close/3
@snindex nb_queue_close/3
@cnindex nb_queue_close/3
Unify the queue  @var{Queue} with a difference list
@var{Head}-@var{Tail}. The queue will now be empty and no further
elements can be added.

@item nb_queue_enqueue(+@var{Queue}, +@var{Element})
@findex nb_queue_enqueue/2
@snindex nb_queue_enqueue/2
@cnindex nb_queue_enqueue/2
Add @var{Element} to the front of the queue  @var{Queue}.

@item nb_queue_dequeue(+@var{Queue}, -@var{Element})
@findex nb_queue_dequeue/2
@snindex nb_queue_dequeue/2
@cnindex nb_queue_dequeue/2
Remove @var{Element} from the front of the queue  @var{Queue}. Fail if
the queue is empty.

@item nb_queue_peek(+@var{Queue}, -@var{Element})
@findex nb_queue_peek/2
@snindex nb_queue_peek/2
@cnindex nb_queue_peek/2
@var{Element} is the front of the queue  @var{Queue}. Fail if
the queue is empty.

@item nb_queue_size(+@var{Queue}, -@var{Size})
@findex nb_queue_size/2
@snindex nb_queue_size/2
@cnindex nb_queue_size/2
Unify @var{Size} with the number of elements in the queue  @var{Queue}.

@item nb_queue_empty(+@var{Queue})
@findex nb_queue_empty/1
@snindex nb_queue_empty/1
@cnindex nb_queue_empty/1
Succeeds if  @var{Queue} is empty.

@item nb_heap(+@var{DefaultSize},-@var{Heap})
@findex nb_heap/1
@snindex nb_heap/1
@cnindex nb_heap/1
Create a @var{Heap} with default size @var{DefaultSize}. Note that size
will expand as needed.

@item nb_heap_close(+@var{Heap})
@findex nb_heap_close/1
@snindex nb_heap_close/1
@cnindex nb_heap_close/1
Close the heap @var{Heap}: no further elements can be added.

@item nb_heap_add(+@var{Heap}, +@var{Key}, +@var{Value})
@findex nb_heap_add/3
@snindex nb_heap_add/3
@cnindex nb_heap_add/3
Add @var{Key}-@var{Value} to the heap @var{Heap}. The key is sorted on
@var{Key} only.

@item nb_heap_del(+@var{Heap}, -@var{Key}, -@var{Value})
@findex nb_heap_del/3
@snindex nb_heap_del/3
@cnindex nb_heap_del/3
Remove element @var{Key}-@var{Value} with smallest @var{Value} in heap
@var{Heap}. Fail if the heap is empty.

@item nb_heap_peek(+@var{Heap}, -@var{Key}, -@var{Value}))
@findex nb_heap_peek/3
@snindex nb_heap_peek/3
@cnindex nb_heap_peek/3
@var{Key}-@var{Value} is the element with smallest @var{Key} in the heap
@var{Heap}. Fail if the heap is empty.

@item nb_heap_size(+@var{Heap}, -@var{Size})
@findex nb_heap_size/2
@snindex nb_heap_size/2
@cnindex nb_heap_size/2
Unify @var{Size} with the number of elements in the heap  @var{Heap}.

@item nb_heap_empty(+@var{Heap})
@findex nb_heap_empty/1
@snindex nb_heap_empty/1
@cnindex nb_heap_empty/1
Succeeds if  @var{Heap} is empty.

@item nb_beam(+@var{DefaultSize},-@var{Beam})
@findex nb_beam/1
@snindex nb_beam/1
@cnindex nb_beam/1
Create a @var{Beam} with default size @var{DefaultSize}. Note that size
is fixed throughout.

@item nb_beam_close(+@var{Beam})
@findex nb_beam_close/1
@snindex nb_beam_close/1
@cnindex nb_beam_close/1
Close the beam @var{Beam}: no further elements can be added.

@item nb_beam_add(+@var{Beam}, +@var{Key}, +@var{Value})
@findex nb_beam_add/3
@snindex nb_beam_add/3
@cnindex nb_beam_add/3
Add @var{Key}-@var{Value} to the beam @var{Beam}. The key is sorted on
@var{Key} only.

@item nb_beam_del(+@var{Beam}, -@var{Key}, -@var{Value})
@findex nb_beam_del/3
@snindex nb_beam_del/3
@cnindex nb_beam_del/3
Remove element @var{Key}-@var{Value} with smallest @var{Value} in beam
@var{Beam}. Fail if the beam is empty.

@item nb_beam_peek(+@var{Beam}, -@var{Key}, -@var{Value}))
@findex nb_beam_peek/3
@snindex nb_beam_peek/3
@cnindex nb_beam_peek/3
@var{Key}-@var{Value} is the element with smallest @var{Key} in the beam
@var{Beam}. Fail if the beam is empty.

@item nb_beam_size(+@var{Beam}, -@var{Size})
@findex nb_beam_size/2
@snindex nb_beam_size/2
@cnindex nb_beam_size/2
Unify @var{Size} with the number of elements in the beam  @var{Beam}.

@item nb_beam_empty(+@var{Beam})
@findex nb_beam_empty/1
@snindex nb_beam_empty/1
@cnindex nb_beam_empty/1
Succeeds if  @var{Beam} is empty.

@end table


@node Ordered Sets, Pseudo Random, Non-Backtrackable Data Structures, Library
@section Ordered Sets
@cindex ordered set

The following ordered set manipulation routines are available once
included with the @code{use_module(library(ordsets))} command.  An
ordered set is represented by a list having unique and ordered
elements. Output arguments are guaranteed to be ordered sets, if the
relevant inputs are. This is a slightly patched version of Richard
O'Keefe's original library.

@table @code
@item list_to_ord_set(+@var{List}, ?@var{Set})
@findex list_to_ord_set/2
@syindex list_to_ord_set/2
@cnindex list_to_ord_set/2
Holds when @var{Set} is the ordered representation of the set
represented by the unordered representation @var{List}.

@item merge(+@var{List1}, +@var{List2}, -@var{Merged})
@findex merge/3
@syindex merge/3
@cnindex merge/3
Holds when @var{Merged} is the stable merge of the two given lists.

Notice that @code{merge/3} will not remove duplicates, so merging
ordered sets will not necessarily result in an ordered set. Use
@code{ord_union/3} instead.

@item ord_add_element(+@var{Set1}, +@var{Element}, ?@var{Set2})
@findex ord_add_element/3
@syindex ord_add_element/3
@cnindex ord_add_element/3
Inserting @var{Element} in @var{Set1} returns @var{Set2}.  It should give
exactly the same result as @code{merge(Set1, [Element], Set2)}, but a
bit faster, and certainly more clearly. The same as @code{ord_insert/3}.

@item ord_del_element(+@var{Set1}, +@var{Element}, ?@var{Set2})
@findex ord_del_element/3
@syindex ord_del_element/3
@cnindex ord_del_element/3
Removing @var{Element} from @var{Set1} returns @var{Set2}.

@item ord_disjoint(+@var{Set1}, +@var{Set2})
@findex ord_disjoint/2
@syindex ord_disjoint/2
@cnindex ord_disjoint/2
Holds when the two ordered sets have no element in common.

@item ord_member(+@var{Element}, +@var{Set})
@findex ord_member/2
@syindex ord_member/2
@cnindex ord_member/2
Holds when @var{Element} is a member of @var{Set}.

@item ord_insert(+@var{Set1}, +@var{Element}, ?@var{Set2})
@findex ord_insert/3
@syindex ord_insert/3
@cnindex ord_insert/3
Inserting @var{Element} in @var{Set1} returns @var{Set2}.  It should give
exactly the same result as @code{merge(Set1, [Element], Set2)}, but a
bit faster, and certainly more clearly. The same as @code{ord_add_element/3}.

@item ord_intersect(+@var{Set1}, +@var{Set2})
@findex ord_intersect/2
@syindex ord_intersect/2
@cnindex ord_intersect/2
Holds when the two ordered sets have at least one element in common.

@item ord_intersection(+@var{Set1}, +@var{Set2}, ?@var{Intersection})
@findex ord_intersect/3
@syindex ord_intersect/3
@cnindex ord_intersect/3
Holds when Intersection is the ordered representation of @var{Set1}
and @var{Set2}.

@item ord_intersection(+@var{Set1}, +@var{Set2}, ?@var{Intersection}, ?@var{Diff})
@findex ord_intersect/4
@syindex ord_intersect/4
@cnindex ord_intersect/4
Holds when Intersection is the ordered representation of @var{Set1}
and @var{Set2}. @var{Diff} is the difference between @var{Set2} and @var{Set1}.

@item ord_seteq(+@var{Set1}, +@var{Set2})
@findex ord_seteq/2
@syindex ord_seteq/2
@cnindex ord_seteq/2
Holds when the two arguments represent the same set.

@item ord_setproduct(+@var{Set1}, +@var{Set2}, -@var{Set})
@findex ord_setproduct/3
@syindex ord_setproduct/3
@cnindex ord_setproduct/3
If Set1 and Set2 are ordered sets, Product will be an ordered
set of x1-x2 pairs.

@item ord_subset(+@var{Set1}, +@var{Set2})
@findex ordsubset/2
@syindex ordsubset/2
@cnindex ordsubset/2
Holds when every element of the ordered set @var{Set1} appears in the
ordered set @var{Set2}.

@item ord_subtract(+@var{Set1}, +@var{Set2}, ?@var{Difference})
@findex ord_subtract/3
@syindex ord_subtract/3
@cnindex ord_subtract/3
Holds when @var{Difference} contains all and only the elements of @var{Set1}
which are not also in @var{Set2}.

@item ord_symdiff(+@var{Set1}, +@var{Set2}, ?@var{Difference})
@findex ord_symdiff/3
@syindex ord_symdiff/3
@cnindex ord_symdiff/3
Holds when @var{Difference} is the symmetric difference of @var{Set1}
and @var{Set2}.

@item ord_union(+@var{Sets}, ?@var{Union})
@findex ord_union/2
@syindex ord_union/2
@cnindex ord_union/2
Holds when @var{Union} is the union of the lists @var{Sets}.

@item ord_union(+@var{Set1}, +@var{Set2}, ?@var{Union})
@findex ord_union/3
@syindex ord_union/3
@cnindex ord_union/3
Holds when @var{Union} is the union of @var{Set1} and @var{Set2}.

@item ord_union(+@var{Set1}, +@var{Set2}, ?@var{Union}, ?@var{Diff})
@findex ord_union/4
@syindex ord_union/4
@cnindex ord_union/4
Holds when @var{Union} is the union of @var{Set1} and @var{Set2} and
@var{Diff} is the difference.

@end table

@node Pseudo Random, Queues, Ordered Sets, Library
@section Pseudo Random Number Integer Generator
@cindex pseudo random

The following routines produce random non-negative integers in the range
0 .. 2^(w-1) -1, where w is the word size available for integers, e.g.
32 for Intel machines and 64 for Alpha machines. Note that the numbers
generated by this random number generator are repeatable. This generator
was originally written by Allen Van Gelder and is based on Knuth Vol 2.

@table @code 
@item rannum(-@var{I})
@findex rannum/1
@snindex rannum/1
@cnindex rannum/1
Produces a random non-negative integer @var{I} whose low bits are not
all that random, so it should be scaled to a smaller range in general.
The integer @var{I} is in the range 0 .. 2^(w-1) - 1. You can use:
@example
rannum(X) :- yap_flag(max_integer,MI), rannum(R), X is R/MI.
@end example
to obtain a floating point number uniformly distributed between 0 and 1.

@item ranstart
@findex ranstart/0
@snindex ranstart/0
@cnindex ranstart/0
Initialize the random number generator using a built-in seed. The
@code{ranstart/0} built-in is always called by the system when loading
the package.

@item ranstart(+@var{Seed})
@findex ranstart/1
@snindex ranstart/1
@cnindex ranstart/1
Initialize the random number generator with user-defined @var{Seed}. The
same @var{Seed} always produces the same sequence of numbers.

@item ranunif(+@var{Range},-@var{I})
@findex ranunif/2
@snindex ranunif/2
@cnindex ranunif/2
@code{ranunif/2} produces a uniformly distributed non-negative random
integer @var{I} over a caller-specified range @var{R}.  If range is @var{R},
the result is in 0 .. @var{R}-1.

@end table

@node Queues, Random, Pseudo Random, Library
@section Queues
@cindex queue

The following queue manipulation routines are available once
included with the @code{use_module(library(queues))} command. Queues are
implemented with difference lists.

@table @code

@item make_queue(+@var{Queue})
@findex make_queue/1
@syindex make_queue/1
@cnindex make_queue/1
Creates a new empty queue. It should only be used to create a new queue.

@item join_queue(+@var{Element}, +@var{OldQueue}, -@var{NewQueue})
@findex join_queue/3
@syindex join_queue/3
@cnindex join_queue/3
Adds the new element at the end of the queue.

@item list_join_queue(+@var{List}, +@var{OldQueue}, -@var{NewQueue})
@findex list_join_queue/3
@syindex list_join_queue/3
@cnindex list_join_queue/3
Ads the new elements at the end of the queue.

@item jump_queue(+@var{Element}, +@var{OldQueue}, -@var{NewQueue})
@findex jump_queue/3
@syindex jump_queue/3
@cnindex jump_queue/3
Adds the new element at the front of the list.

@item list_jump_queue(+@var{List}, +@var{OldQueue}, +@var{NewQueue})
@findex list_jump_queue/3
@syindex list_jump_queue/3
@cnindex list_jump_queue/3
Adds all the elements of @var{List} at the front of the queue.

@item head_queue(+@var{Queue}, ?@var{Head})
@findex head_queue/2
@syindex head_queue/2
@cnindex head_queue/2
Unifies Head with the first element of the queue.

@item serve_queue(+@var{OldQueue}, +@var{Head}, -@var{NewQueue})
@findex serve_queue/3
@syindex serve_queue/3
@cnindex serve_queue/3
Removes the first element of the queue for service.

@item empty_queue(+@var{Queue})
@findex empty_queue/1
@syindex empty_queue/1
@cnindex empty_queue/1
Tests whether the queue is empty.

@item length_queue(+@var{Queue}, -@var{Length})
@findex length_queue/2
@syindex length_queue/2
@cnindex length_queue/2
Counts the number of elements currently in the queue.

@item list_to_queue(+@var{List}, -@var{Queue})
@findex list_to_queue/2
@syindex list_to_queue/2
@cnindex list_to_queue/2
Creates a new queue with the same elements as @var{List.}

@item queue_to_list(+@var{Queue}, -@var{List})
@findex queue_to_list/2
@syindex queue_to_list/2
@cnindex queue_to_list/2
Creates a new list with the same elements as @var{Queue}.

@end table


@node Random, Read Utilities, Queues, Library
@section Random Number Generator
@cindex random

The following random number operations are included with the
@code{use_module(library(random))} command. Since YAP-4.3.19 YAP uses
the O'Keefe public-domain algorithm, based on the "Applied Statistics"
algorithm AS183.

@table @code

@item getrand(-@var{Key})
@findex getrand/1
@syindex getrand/1
@cnindex getrand/1
Unify @var{Key} with a term of the form @code{rand(X,Y,Z)} describing the
current state of the random number generator.

@item random(-@var{Number})
@findex random/1
@syindex random/1
@cnindex random/1
Unify @var{Number} with a floating-point number in the range @code{[0...1)}.

@item random(+@var{LOW}, +@var{HIGH}, -@var{NUMBER})
@findex random/3
@syindex random/3
@cnindex random/3
Unify @var{Number} with a number in the range
@code{[LOW...HIGH)}. If both @var{LOW} and @var{HIGH} are
integers then @var{NUMBER} will also be an integer, otherwise
@var{NUMBER} will be a floating-point number.

@item randseq(+@var{LENGTH}, +@var{MAX}, -@var{Numbers})
@findex randseq/3
@syindex randseq/3
@cnindex randseq/3
Unify @var{Numbers} with a list of @var{LENGTH} unique random integers
in the range @code{[1...@var{MAX})}.

@item randset(+@var{LENGTH}, +@var{MAX}, -@var{Numbers})
@findex randset/3
@syindex randset/3
@cnindex randset/3
Unify @var{Numbers} with an ordered list of @var{LENGTH} unique random
integers in the range @code{[1...@var{MAX})}.

@item setrand(+@var{Key})
@findex setrand/1
@syindex setrand/1
@cnindex setrand/1
Use a term of the form @code{rand(X,Y,Z)} to set a new state for the
random number generator. The integer @code{X} must be in the range
@code{[1...30269)}, the integer @code{Y} must be in the range
@code{[1...30307)}, and the integer @code{Z} must be in the range
@code{[1...30323)}.

@end table

@node Read Utilities, Red-Black Trees, Random, Library
@section Read Utilities

The @code{readutil} library contains primitives to read lines, files,
multiple terms, etc.

@table @code
@item read_line_to_codes(+@var{Stream}, -@var{Codes})
@findex read_line_to_codes/2
@snindex read_line_to_codes/2
@cnindex read_line_to_codes/2

Read the next line of input from @var{Stream} and unify the result with
@var{Codes} @emph{after} the line has been read.  A line is ended by a
newline character or end-of-file. Unlike @code{read_line_to_codes/3},
this predicate removes trailing newline character.

On end-of-file the atom @code{end_of_file} is returned.  See also
@code{at_end_of_stream/[0,1]}.

@item read_line_to_codes(+@var{Stream}, -@var{Codes}, ?@var{Tail})
@findex read_line_to_codes/3
@snindex read_line_to_codes/3
@cnindex read_line_to_codes/3
Difference-list version to read an input line to a list of character
codes.  Reading stops at the newline or end-of-file character, but
unlike @code{read_line_to_codes/2}, the newline is retained in the
output.  This predicate is especially useful for reading a block of
lines upto some delimiter.  The following example reads an HTTP header
ended by a blank line:

@example
read_header_data(Stream, Header) :-
    read_line_to_codes(Stream, Header, Tail),
    read_header_data(Header, Stream, Tail).

read_header_data("\r\n", _, _) :- !.
read_header_data("\n", _, _) :- !.
read_header_data("", _, _) :- !.
read_header_data(_, Stream, Tail) :-
    read_line_to_codes(Stream, Tail, NewTail),
    read_header_data(Tail, Stream, NewTail).
@end example

@item read_stream_to_codes(+@var{Stream}, -@var{Codes})
@findex read_stream_to_codes/2
@snindex read_stream_to_codes/2
@cnindex read_stream_to_codes/2
Read all input until end-of-file and unify the result to @var{Codes}.

@item read_stream_to_codes(+@var{Stream}, -@var{Codes}, ?@var{Tail})
@findex read_stream_to_codes/3
@snindex read_stream_to_codes/3
@cnindex read_stream_to_codes/3
Difference-list version of @code{read_stream_to_codes/2}.

@item read_file_to_codes(+@var{Spec}, -@var{Codes}, +@var{Options})
@findex read_file_to_codes/3
@snindex read_file_to_codes/3
@cnindex read_file_to_codes/3
Read a file to a list of character codes. Currently ignores
@var{Options}.

@c  @var{Spec} is a
@c file-specification for absolute_file_name/3.  @var{Codes} is the
@c resulting code-list.  @var{Options} is a list of options for
@c absolute_file_name/3 and open/4.  In addition, the option
@c \term{tail}{Tail} is defined, forming a difference-list.

@item read_file_to_terms(+@var{Spec}, -@var{Terms}, +@var{Options})
@findex read_file_to_terms/3
@snindex read_file_to_terms/3
@cnindex read_file_to_terms/3
Read a file to a list of Prolog terms (see read/1). @c @var{Spec} is a
@c file-specification for absolute_file_name/3.  @var{Terms} is the
@c resulting list of Prolog terms.  @var{Options} is a list of options for
@c absolute_file_name/3 and open/4.  In addition, the option
@c \term{tail}{Tail} is defined, forming a difference-list.
@c \end{description}

@end table



@node Red-Black Trees, RegExp, Read Utilities, Library
@section Red-Black Trees
@cindex Red-Black Trees

Red-Black trees are balanced search binary trees. They are named because
nodes can be classified as either red or black. The code we include is
based on "Introduction to Algorithms", second edition, by Cormen,
Leiserson, Rivest and Stein.  The library includes routines to insert,
lookup and delete elements in the tree.

@table @code
@item rb_new(?@var{T})
@findex rb_new/1
@snindex rb_new/1
@cnindex rb_new/1
Create a new tree.

@item rb_empty(?@var{T})
@findex rb_empty/1
@snindex rb_empty/1
@cnindex rb_empty/1
Succeeds if tree @var{T} is empty.

@item is_rbtree(+@var{T})
@findex is_rbtree/1
@snindex is_rbtree/1
@cnindex is_rbtree/1
Check whether @var{T} is a valid red-black tree.

@item rb_insert(+@var{T0},+@var{Key},?@var{Value},+@var{TF})
@findex rb_insert/4
@snindex rb_insert/4
@cnindex rb_insert/4
Add an element with key @var{Key} and @var{Value} to the tree
@var{T0} creating a new red-black tree @var{TF}. Duplicated elements are not
allowed.

@snindex rb_insert_new/4
@cnindex rb_insert_new/4
Add a new element with key @var{Key} and @var{Value} to the tree
@var{T0} creating a new red-black tree @var{TF}. Fails is an element
with @var{Key} exists in the tree.

@item rb_lookup(+@var{Key},-@var{Value},+@var{T})
@findex rb_lookup/3
@snindex rb_lookup/3
@cnindex rb_lookup/3
Backtrack through all elements with key @var{Key} in the red-black tree
@var{T}, returning for each the value @var{Value}.

@item rb_lookupall(+@var{Key},-@var{Value},+@var{T})
@findex rb_lookupall/3
@snindex rb_lookupall/3
@cnindex rb_lookupall/3
Lookup all elements with key @var{Key} in the red-black tree
@var{T}, returning the value @var{Value}.

@item rb_delete(+@var{T},+@var{Key},-@var{TN})
@findex rb_delete/3
@snindex rb_delete/3
@cnindex rb_delete/3
Delete element with key @var{Key} from the tree @var{T}, returning a new
tree @var{TN}.

@item rb_delete(+@var{T},+@var{Key},-@var{Val},-@var{TN})
@findex rb_delete/4
@snindex rb_delete/4
@cnindex rb_delete/4
Delete element with key @var{Key} from the tree @var{T}, returning the
value @var{Val} associated with the key and a new tree @var{TN}.

@item rb_del_min(+@var{T},-@var{Key},-@var{Val},-@var{TN})
@findex rb_del_min/4
@snindex rb_del_min/4
@cnindex rb_del_min/4
Delete the least element from the tree @var{T}, returning the key
@var{Key}, the value @var{Val} associated with the key and a new tree
@var{TN}.

@item rb_del_max(+@var{T},-@var{Key},-@var{Val},-@var{TN})
@findex rb_del_max/4
@snindex rb_del_max/4
@cnindex rb_del_max/4
Delete the largest element from the tree @var{T}, returning the key
@var{Key}, the value @var{Val} associated with the key and a new tree
@var{TN}.

@item rb_update(+@var{T},+@var{Key},+@var{NewVal},-@var{TN})
@findex rb_update/4
@snindex rb_update/4
@cnindex rb_update/4
Tree @var{TN} is tree @var{T}, but with value for @var{Key} associated
with @var{NewVal}. Fails if it cannot find @var{Key} in @var{T}.

@item rb_apply(+@var{T},+@var{Key},+@var{G},-@var{TN})
@findex rb_apply/4
@snindex rb_apply/4
@cnindex rb_apply/4
If the value associated with key @var{Key} is @var{Val0} in @var{T}, and
if @code{call(G,Val0,ValF)} holds, then @var{TN} differs from
@var{T} only in that @var{Key} is associated with value @var{ValF} in
tree @var{TN}. Fails if it cannot find @var{Key} in @var{T}, or if
@code{call(G,Val0,ValF)} is not satisfiable.

@item rb_visit(+@var{T},-@var{Pairs})
@findex rb_visit/2
@snindex rb_visit/2
@cnindex rb_visit/2
@var{Pairs} is an infix visit of tree @var{T}, where each element of
@var{Pairs} is of the form  @var{K}-@var{Val}.

@item rb_size(+@var{T},-@var{Size})
@findex rb_size/2
@snindex rb_size/2
@cnindex rb_size/2
@var{Size} is the number of elements in @var{T}.

@item rb_keys(+@var{T},+@var{Keys})
@findex rb_keys/2
@snindex rb_keys/2
@cnindex rb_keys/2
@var{Keys} is an infix visit with all keys in tree @var{T}. Keys will be
sorted, but may be duplicate.

@item rb_map(+@var{T},+@var{G},-@var{TN})
@findex rb_map/3
@snindex rb_map/3
@cnindex rb_map/3
For all nodes @var{Key} in the tree @var{T}, if the value associated with
key @var{Key} is @var{Val0} in tree @var{T}, and if
@code{call(G,Val0,ValF)} holds, then the value associated with @var{Key}
in @var{TN} is @var{ValF}. Fails if or if @code{call(G,Val0,ValF)} is not
satisfiable for all @var{Var0}.

@item rb_partial_map(+@var{T},+@var{Keys},+@var{G},-@var{TN})
@findex rb_partial_map/4
@snindex rb_partial_map/4
@cnindex rb_partial_map/4
For all nodes @var{Key} in @var{Keys}, if the value associated with key
@var{Key} is @var{Val0} in tree @var{T}, and if @code{call(G,Val0,ValF)}
holds, then the value associated with @var{Key} in @var{TN} is
@var{ValF}. Fails if or if @code{call(G,Val0,ValF)} is not satisfiable
for all @var{Var0}. Assumes keys are not repeated.

@item rb_fold(+@var{T},+@var{G},+@var{Acc0}, -@var{AccF})
@findex rb_fold/4
@snindex rb_fold/4
@cnindex rb_fold/4
    For all nodes @var{Key} in the tree @var{T}, if the value
associated with key @var{Key} is @var{V} in tree @var{T}, if
@code{call(G,V,Acc1,Acc2)} holds, then if @var{VL} is value of the
previous node in inorder, @code{call(G,VL,_,Acc0)} must hold, and if
@var{VR} is the value of the next node in inorder,
@code{call(G,VR,Acc1,_)} must hold.

@item rb_key_fold(+@var{T},+@var{G},+@var{Acc0}, -@var{AccF})
@findex rb_key_fold/4
@snindex rb_key_fold/4
@cnindex rb_key_fold/4
    For all nodes @var{Key} in the tree @var{T}, if the value
associated with key @var{Key} is @var{V} in tree @var{T}, if
@code{call(G,Key,V,Acc1,Acc2)} holds, then if @var{VL} is value of the
previous node in inorder, @code{call(G,KeyL,VL,_,Acc0)} must hold, and if
@var{VR} is the value of the next node in inorder,
@code{call(G,KeyR,VR,Acc1,_)} must hold.

@item rb_clone(+@var{T},+@var{NT},+@var{Nodes})
@findex rb_clone/3
@snindex rb_clone/3
@cnindex rb_clone/3
``Clone'' the red-back tree into a new tree with the same keys as the
original but with all values set to unbound values. Nodes is a list
containing all new nodes as pairs @var{K-V}.

@item rb_min(+@var{T},-@var{Key},-@var{Value})
@findex rb_min/3
@snindex rb_min/3
@cnindex rb_min/3
@var{Key}  is the minimum key in @var{T}, and is associated with @var{Val}.

@item rb_max(+@var{T},-@var{Key},-@var{Value})
@findex rb_max/3
@snindex rb_max/3
@cnindex rb_max/3
@var{Key}  is the maximal key in @var{T}, and is associated with @var{Val}.

@item rb_next(+@var{T}, +@var{Key},-@var{Next},-@var{Value})
@findex rb_next/4
@snindex rb_next/4
@cnindex rb_next/4
@var{Next} is the next element after @var{Key} in @var{T}, and is
associated with @var{Val}.

@item rb_previous(+@var{T}, +@var{Key},-@var{Previous},-@var{Value})
@findex rb_previous/4
@snindex rb_previous/4
@cnindex rb_previous/4
@var{Previous} is the previous element after @var{Key} in @var{T}, and is
associated with @var{Val}.

@item ord_list_to_rbtree(+@var{L}, -@var{T})
@findex list_to_rbtree/2
@snindex list_to_rbtree/2
@cnindex list_to_rbtree/2
@var{T} is the red-black tree corresponding to the mapping in ordered
list @var{L}.
@end table

@node RegExp, shlib, Red-Black Trees, Library
@section Regular Expressions
@cindex regular expressions

This library includes routines to determine whether a regular expression
matches part or all of a string. The routines can also return which
parts parts of the string matched the expression or subexpressions of
it. This library relies on Henry Spencer's @code{C}-package and is only
available in operating systems that support dynamic loading. The
@code{C}-code has been obtained from the sources of FreeBSD-4.0 and is
protected by copyright from Henry Spencer and from the Regents of the
University of California (see the file library/regex/COPYRIGHT for
further details).

Much of the description of regular expressions below is copied verbatim
from Henry Spencer's manual page.

A regular expression is zero or more branches, separated by ``|''.  It
matches anything that matches one of the branches.

A branch is zero or more pieces, concatenated.  It matches a match for
the first, followed by a match for the second, etc.

A piece is an atom possibly followed by ``*'', ``+'', or ``?''.  An atom
followed by ``*'' matches a sequence of 0 or more matches of the atom.
An atom followed by ``+'' matches a sequence of 1 or more matches of the
atom.  An atom followed by ``?'' matches a match of the atom, or the
null string.

An atom is a regular expression in parentheses (matching a match for the
regular expression), a range (see below), ``.''  (matching any single
character), ``^'' (matching the null string at the beginning of the
input string), ``$'' (matching the null string at the end of the input
string), a ``\'' followed by a single character (matching that
character), or a single character with no other significance (matching
that character).

A range is a sequence of characters enclosed in ``[]''.  It normally
matches any single character from the sequence.  If the sequence begins
with ``^'', it matches any single character not from the rest of the
sequence.  If two characters in the sequence are separated by ``-'',
this is shorthand for the full list of ASCII characters between them
(e.g. ``[0-9]'' matches any decimal digit).  To include a literal ``]''
in the sequence, make it the first character (following a possible
``^'').  To include a literal ``-'', make it the first or last
character.

@table @code

@item regexp(+@var{RegExp},+@var{String},+@var{Opts})
@findex regexp/3
@snindex regexp/3
@cnindex regexp/3

Match regular expression @var{RegExp} to input string @var{String}
according to options @var{Opts}. The options may be:
@itemize @bullet
@item @code{nocase}: Causes upper-case characters  in  @var{String} to
        be treated  as  lower case during the matching process.
@end itemize

@item regexp(+@var{RegExp},+@var{String},+@var{Opts},?@var{SubMatchVars})
@findex regexp/4
@snindex regexp/4
@cnindex regexp/4

Match regular expression @var{RegExp} to input string @var{String}
according to options @var{Opts}. The variable @var{SubMatchVars} should
be originally unbound or a list of unbound variables all will contain a
sequence of matches, that is, the head of @var{SubMatchVars} will
contain the characters in @var{String} that matched the leftmost
parenthesized subexpression within @var{RegExp}, the next head of list
will contain the characters that matched the next parenthesized
subexpression to the right in @var{RegExp}, and so on.

The options may be:
@itemize @bullet
@item @code{nocase}: Causes upper-case characters  in  @var{String} to
        be treated  as  lower case during the matching process.
@item @code{indices}: Changes what  is  stored  in
@var{SubMatchVars}. Instead  of storing the matching characters from
@var{String}, each variable will contain a term of the form @var{IO-IF}
giving the indices in @var{String} of the first and last characters  in
the  matching range of characters.

@end itemize

In general there may be more than one way to match a regular expression
to an input string.  For example,  consider the command
@example
  regexp("(a*)b*","aabaaabb", [], [X,Y])
@end example
Considering only the rules given so far, @var{X} and @var{Y} could end up
with the values @code{"aabb"} and @code{"aa"}, @code{"aaab"} and
@code{"aaa"}, @code{"ab"} and @code{"a"}, or any of several other
combinations.  To resolve this potential ambiguity @code{regexp} chooses among
alternatives using the rule ``first then longest''.  In other words, it
considers the possible matches in order working from left to right
across the input string and the pattern, and it attempts to match longer
pieces of the input string before shorter ones.  More specifically, the
following rules apply in decreasing order of priority:


@enumerate 
@item    If a regular expression could match  two  different parts of an
input string then it will match the one that begins earliest.

@item  If a regular expression contains "|"  operators  then the leftmost matching sub-expression is chosen.

@item In *, +, and ? constructs, longer matches are chosen in preference to shorter ones.

@item In sequences of expression  components  the  components are considered from left to right.
@end enumerate

In the example from above, @code{"(a*)b*"} matches @code{"aab"}: the
@code{"(a*)"} portion of the pattern is matched first and it consumes
the leading @code{"aa"}; then the @code{"b*"} portion of the pattern
consumes the next @code{"b"}.  Or, consider the following example: 
@example
  regexp("(ab|a)(b*)c",  "abc", [], [X,Y,Z])
@end example

After this command @var{X} will be @code{"abc"}, @var{Y} will be
@code{"ab"}, and @var{Z} will be an empty string.  Rule 4 specifies that
@code{"(ab|a)"} gets first shot at the input string and Rule 2 specifies
that the @code{"ab"} sub-expression is checked before the @code{"a"}
sub-expression.  Thus the @code{"b"} has already been claimed before the
@code{"(b*)"} component is checked and @code{(b*)} must match an empty string.

@end table

@node shlib, Splay Trees, RegExp, Library
@section SWI-Prolog's shlib library

@cindex SWI-Compatible foreign file loading
This section discusses the functionality of the (autoload)
@code{library(shlib)}, providing an interface to manage shared
libraries.

One of the files provides a global function @code{install_mylib()} that
initialises the module using calls to @code{PL_register_foreign()}. Here is a
simple example file @code{mylib.c}, which creates a Windows MessageBox:

@c_example
#include <windows.h>
#include <SWI-Prolog.h>

static foreign_t
pl_say_hello(term_t to)
@{ char *a;

  if ( PL_get_atom_chars(to, &a) )
  @{ MessageBox(NULL, a, "DLL test", MB_OK|MB_TASKMODAL);

    PL_succeed;
  @}

  PL_fail;
@}

install_t
install_mylib()
@{ PL_register_foreign("say_hello", 1, pl_say_hello, 0);
@}
@end c_example

Now write a file mylib.pl:

@example
:- module(mylib, [ say_hello/1 ]).
:- use_foreign_library(foreign(mylib)).
@end example

The file mylib.pl can be loaded as a normal Prolog file and provides the predicate defined in C.

@table @code
@item load_foreign_library(:@var{FileSpec}) is det
@findex load_foreign_library/1
@snindex load_foreign_library/1
@cnindex load_foreign_library/1
@item load_foreign_library(:@var{FileSpec}, +@var{Entry}:atom) is det
@findex load_foreign_library/2
@snindex load_foreign_library/2
@cnindex load_foreign_library/2
    Load a shared object or DLL. After loading the @var{Entry} function is
    called without arguments. The default entry function is composed
    from @code{install_}, followed by the file base-name. E.g., the
    load-call below calls the function @code{install_mylib()}. If the platform
    prefixes extern functions with @code{_}, this prefix is added before
    calling.

@example
          ...
          load_foreign_library(foreign(mylib)),
          ...
@end example

    @var{FileSpec} is a specification for
    @code{absolute_file_name/3}. If searching the file fails, the plain
    name is passed to the OS to try the default method of the OS for
    locating foreign objects. The default definition of
    @code{file_search_path/2} searches <prolog home>/lib/Yap.

    See also
        @code{use_foreign_library/1,2} are intended for use in
        directives. 

@item [det] use_foreign_library(+@var{FileSpec}),  use_foreign_library(+@var{FileSpec}, +@var{Entry}:atom)
@findex use_foreign_library/1
@snindex use_foreign_library/1
@cnindex use_foreign_library/1
@findex use_foreign_library/2
@snindex use_foreign_library/2
@cnindex use_foreign_library/2
    Load and install a foreign library as @code{load_foreign_library/1}
    and @code{load_foreign_library/2} and
    register the installation using @code{initialization/2} with the option
    now. This is similar to using:

@example
    :- initialization(load_foreign_library(foreign(mylib))).
@end example

    but using the @code{initialization/1} wrapper causes the library to
    be loaded after loading of the file in which it appears is
    completed, while @code{use_foreign_library/1} loads the library
    immediately. I.e. the difference is only relevant if the remainder
    of the file uses functionality of the @code{C}-library. 

@item [det]unload_foreign_library(+@var{FileSpec})
@item [det]unload_foreign_library(+@var{FileSpec}, +@var{Exit}:atom) 
@findex unload_foreign_library/1
@snindex unload_foreign_library/1
@cnindex unload_foreign_library/1
@findex unload_foreign_library/2
@snindex unload_foreign_library/2
@cnindex unload_foreign_library/2

Unload a shared
object or DLL. After calling the @var{Exit} function, the shared object is
removed from the process. The default exit function is composed from
@code{uninstall_}, followed by the file base-name.

@item current_foreign_library(?@var{File}, ?@var{Public}) 
@findex current_foreign_library/2
@snindex current_foreign_library/2
@cnindex current_foreign_library/2

Query currently
loaded shared libraries.  

@c @item reload_foreign_libraries 
@c @findex reload_foreign_libraries/0
@c @snindex reload_foreign_libraries/0
@c @cnindex reload_foreign_libraries/0
@c Reload all foreign
@c libraries loaded (after restore of a state created using
@c @code{qsave_program/2}).
@end table

@node Splay Trees, String Input/Output, shlib, Library
@section Splay Trees
@cindex splay trees

Splay trees are explained in the paper "Self-adjusting Binary Search
Trees", by D.D. Sleator and R.E. Tarjan, JACM, vol. 32, No.3, July 1985,
p. 668. They are designed to support fast insertions, deletions and
removals in binary search trees without the complexity of traditional
balanced trees. The key idea is to allow the tree to become
unbalanced. To make up for this, whenever we find a node, we move it up
to the top. We use code by Vijay Saraswat originally posted to the Prolog
mailing-list.

@table @code

@item splay_access(-@var{Return},+@var{Key},?@var{Val},+@var{Tree},-@var{NewTree})
@findex splay_access/5
@snindex splay_access/5
@cnindex splay_access/5
If item @var{Key} is in tree @var{Tree}, return its @var{Val} and
unify @var{Return} with @code{true}. Otherwise unify @var{Return} with
@code{null}. The variable @var{NewTree} unifies with the new tree.

@item splay_delete(+@var{Key},?@var{Val},+@var{Tree},-@var{NewTree})
@findex splay_delete/4
@snindex splay_delete/4
@cnindex splay_delete/4
Delete item @var{Key} from tree @var{Tree}, assuming that it is present
already. The variable @var{Val} unifies with a value for key @var{Key},
and the variable @var{NewTree} unifies with the new tree. The predicate
will fail if @var{Key} is not present.

@item splay_init(-@var{NewTree})
@findex splay_init/3
@snindex splay_init/3
@cnindex splay_init/3
Initialize a new splay tree.

@item splay_insert(+@var{Key},?@var{Val},+@var{Tree},-@var{NewTree})
@findex splay_insert/4
@snindex splay_insert/4
@cnindex splay_insert/4
Insert item @var{Key} in tree @var{Tree}, assuming that it is not
there already. The variable @var{Val} unifies with a value for key
@var{Key}, and the variable @var{NewTree} unifies with the new
tree. In our implementation, @var{Key} is not inserted if it is
already there: rather it is unified with the item already in the tree.

@item splay_join(+@var{LeftTree},+@var{RighTree},-@var{NewTree})
@findex splay_join/3
@snindex splay_join/3
@cnindex splay_join/3
Combine trees @var{LeftTree} and @var{RighTree} into a single
tree@var{NewTree} containing all items from both trees. This operation
assumes that all items in @var{LeftTree} are less than all those in
@var{RighTree} and destroys both @var{LeftTree} and @var{RighTree}.

@item splay_split(+@var{Key},?@var{Val},+@var{Tree},-@var{LeftTree},-@var{RightTree})
@findex splay_split/5
@snindex splay_split/5
@cnindex splay_split/5
Construct and return two trees @var{LeftTree} and @var{RightTree},
where @var{LeftTree} contains all items in @var{Tree} less than
@var{Key}, and @var{RightTree} contains all items in @var{Tree}
greater than @var{Key}. This operations destroys @var{Tree}.

@end table

@node String Input/Output, System, Splay Trees, Library
@section Reading From and Writing To Strings
@cindex string Input/Output

From Version 4.3.2 onwards YAP implements SICStus Prolog compatible
String Input/Output. The library allows users to read from and write to a memory
buffer as if it was a file. The memory buffer is built from or converted
to a string of character codes by the routines in library. Therefore, if
one wants to read from a string the string must be fully instantiated
before the library built-in opens the string for reading. These commands
are available through the @code{use_module(library(charsio))} command.

@table @code

@item format_to_chars(+@var{Form}, +@var{Args}, -@var{Result})
@findex format_to_chars/3
@syindex format_to_chars/3
@cnindex format_to_chars/3

Execute the built-in procedure @code{format/2} with form @var{Form} and
arguments @var{Args} outputting the result to the string of character
codes @var{Result}.

@item format_to_chars(+@var{Form}, +@var{Args}, -@var{Result}, -@var{Result0})
@findex format_to_chars/4
@syindex format_to_chars/4
@cnindex format_to_chars/4

Execute the built-in procedure @code{format/2} with form @var{Form} and
arguments @var{Args} outputting the result to the difference list of
character codes @var{Result-Result0}.

@item write_to_chars(+@var{Term}, -@var{Result})
@findex write_to_chars/2
@syindex write_to_chars/2
@cnindex write_to_chars/2

Execute the built-in procedure @code{write/1} with argument @var{Term}
outputting the result to the string of character codes @var{Result}.

@item write_to_chars(+@var{Term}, -@var{Result0}, -@var{Result})
@findex write_to_chars/3
@syindex write_to_chars/3
@cnindex write_to_chars/3

Execute the built-in procedure @code{write/1} with argument @var{Term}
outputting the result to the difference list of character codes
@var{Result-Result0}.

@item atom_to_chars(+@var{Atom}, -@var{Result})
@findex atom_to_chars/2
@syindex atom_to_chars/2
@cnindex atom_to_chars/2

Convert the atom @var{Atom} to the string of character codes
@var{Result}.

@item atom_to_chars(+@var{Atom}, -@var{Result0}, -@var{Result})
@findex atom_to_chars/3
@syindex atom_to_chars/3
@cnindex atom_to_chars/3

Convert the atom @var{Atom} to the difference list of character codes
@var{Result-Result0}.

@item number_to_chars(+@var{Number}, -@var{Result})
@findex number_to_chars/2
@syindex number_to_chars/2
@cnindex number_to_chars/2

Convert the number @var{Number} to the string of character codes
@var{Result}.

@item number_to_chars(+@var{Number}, -@var{Result0}, -@var{Result})
@findex number_to_chars/3
@syindex number_to_chars/3
@cnindex number_to_chars/3

Convert the atom @var{Number} to the difference list of character codes
@var{Result-Result0}.

@item atom_to_term(+@var{Atom}, -@var{Term}, -@var{Bindings})
@findex atom_to_term/3
@syindex atom_to_term/3
@cnindex atom_to_term/3
Use @var{Atom} as input to @code{read_term/2} using the option @code{variable_names} and return the read term in @var{Term} and the variable bindings in @var{Bindings}. @var{Bindings} is a list of @code{Name = Var} couples, thus providing access to the actual variable names. See also @code{read_term/2}. If Atom has no valid syntax, a syntax_error exception is raised.

@item term_to_atom(?@var{Term}, ?@var{Atom})
@findex term_to_atom/2
@syindex term_to_atom/2
@cnindex term_to_atom/2
True if @var{Atom} describes a term that unifies with @var{Term}. When
@var{Atom} is instantiated @var{Atom} is converted and then unified with
@var{Term}. If @var{Atom} has no valid syntax, a syntax_error exception
is raised. Otherwise @var{Term} is ``written'' on @var{Atom} using
@code{write_term/2} with the option quoted(true).

@item read_from_chars(+@var{Chars}, -@var{Term})
@findex read_from_chars/2
@syindex read_from_chars/2
@cnindex read_from_chars/2

Parse the list of character codes @var{Chars} and return the result in
the term @var{Term}. The character codes to be read must terminate with
a dot character such that either (i) the dot character is followed by
blank characters; or (ii) the dot character is the last character in the
string.

@item open_chars_stream(+@var{Chars}, -@var{Stream})
@findex open_chars_stream/2
@syindex open_chars_stream/2
@cnindex open_chars_stream/2

Open the list of character codes @var{Chars} as a stream @var{Stream}.

@item with_output_to_chars(?@var{Goal}, -@var{Chars})
@findex with_output_to_chars/2
@syindex with_output_to_chars/2
@cnindex with_output_to_chars/2

Execute goal @var{Goal} such that its standard output will be sent to a
memory buffer. After successful execution the contents of the memory
buffer will be converted to the list of character codes @var{Chars}.

@item with_output_to_chars(?@var{Goal}, ?@var{Chars0}, -@var{Chars})
@findex with_output_to_chars/3
@syindex with_output_to_chars/3
@cnindex with_output_to_chars/3

Execute goal @var{Goal} such that its standard output will be sent to a
memory buffer. After successful execution the contents of the memory
buffer will be converted to the difference list of character codes
@var{Chars-Chars0}.

@item with_output_to_chars(?@var{Goal}, -@var{Stream}, ?@var{Chars0}, -@var{Chars})
@findex with_output_to_chars/4
@syindex with_output_to_chars/4
@cnindex with_output_to_chars/4

Execute goal @var{Goal} such that its standard output will be sent to a
memory buffer. After successful execution the contents of the memory
buffer will be converted to the difference list of character codes
@var{Chars-Chars0} and @var{Stream} receives the stream corresponding to
the memory buffer.

@end table

The implementation of the character IO operations relies on three YAP
built-ins:
@table @code

@item charsio:open_mem_read_stream(+@var{String}, -@var{Stream})
Store a string in a memory buffer and output a stream that reads from this
memory buffer.

@item charsio:open_mem_write_stream(-@var{Stream})
Create a new memory buffer and output a stream that writes to  it.

@item charsio:peek_mem_write_stream(-@var{Stream}, L0, L)
Convert the memory buffer associated with stream @var{Stream} to the
difference list of character codes @var{L-L0}.

@end table
@noindent
These built-ins are initialized to belong to the module @code{charsio} in
@code{init.yap}. Novel procedures for manipulating strings by explicitly
importing these built-ins.

YAP does not currently support opening a @code{charsio} stream in
@code{append} mode, or seeking in such a stream.

@node System, Terms, String Input/Output, Library
@section Calling The Operating System from YAP
@cindex Operating System Utilities

YAP now provides a library of system utilities compatible with the
SICStus Prolog system library. This library extends and to some point
replaces the functionality of Operating System access routines. The
library includes Unix/Linux and Win32 @code{C} code. They
are available through the @code{use_module(library(system))} command.

@table @code

@item datime(datime(-@var{Year}, -@var{Month}, -@var{DayOfTheMonth},
-@var{Hour}, -@var{Minute}, -@var{Second})
@findex  datime/1
@syindex datime/1
@cnindex datime/1
The @code{datime/1} procedure returns the current date and time, with
information on @var{Year}, @var{Month}, @var{DayOfTheMonth},
@var{Hour}, @var{Minute}, and @var{Second}. The @var{Hour} is returned
on local time. This function uses the WIN32
@code{GetLocalTime} function or the Unix @code{localtime} function.

@example
   ?- datime(X).

X = datime(2001,5,28,15,29,46) ? 
@end example

@item mktime(datime(+@var{Year}, +@var{Month}, +@var{DayOfTheMonth},
+@var{Hour}, +@var{Minute}, +@var{Second}), -@var{Seconds})
@findex  mktime/2
@snindex mktime/2
@cnindex mktime/2
The @code{mktime/1} procedure returns the number of @var{Seconds}
elapsed since 00:00:00 on January 1, 1970, Coordinated Universal Time
(UTC).  The user provides information on @var{Year}, @var{Month},
@var{DayOfTheMonth}, @var{Hour}, @var{Minute}, and @var{Second}. The
@var{Hour} is given on local time. This function uses the WIN32
@code{GetLocalTime} function or the Unix @code{mktime} function.

@example
   ?- mktime(datime(2001,5,28,15,29,46),X).

X = 991081786 ? ;
@end example

@item delete_file(+@var{File})
@findex  delete_file/1
@syindex delete_file/1
@cnindex delete_file/1
The @code{delete_file/1} procedure removes file @var{File}. If
@var{File} is a directory, remove the directory @emph{and all its subdirectories}.

@example
   ?- delete_file(x).
@end example

@item delete_file(+@var{File},+@var{Opts})
@findex  delete_file/2
@syindex delete_file/2
@cnindex delete_file/2
The @code{delete_file/2} procedure removes file @var{File} according to
options @var{Opts}. These options are @code{directory} if one should
remove directories, @code{recursive} if one should remove directories
recursively, and @code{ignore} if errors are not to be reported.

This example is equivalent to using the @code{delete_file/1} predicate:
@example
   ?- delete_file(x, [recursive]).
@end example


@item directory_files(+@var{Dir},+@var{List})
@findex  directory_files/2
@syindex directory_files/2
@cnindex directory_files/2
Given a directory @var{Dir},  @code{directory_files/2} procedures a
listing of all files and directories in the directory:
@example
    ?- directory_files('.',L), writeq(L).
['Makefile.~1~','sys.so','Makefile','sys.o',x,..,'.']
@end example
The predicates uses the @code{dirent} family of routines in Unix
environments, and @code{findfirst} in WIN32.

@item file_exists(+@var{File})
@findex  file_exists/1
@syindex file_exists/1
@cnindex file_exists/1
The atom @var{File} corresponds to an existing file.

@item file_exists(+@var{File},+@var{Permissions})
@findex  file_exists/2
@syindex file_exists/2
@cnindex file_exists/2
The atom @var{File} corresponds to an existing file with permissions
compatible with @var{Permissions}. YAP currently only accepts for
permissions to be described as a number. The actual meaning of this
number is Operating System dependent.

@item file_property(+@var{File},?@var{Property})
@findex  file_property/2
@syindex file_property/2
@cnindex file_property/2
The atom @var{File} corresponds to an existing file, and @var{Property}
will be unified with a property of this file. The properties are of the
form @code{type(@var{Type})}, which gives whether the file is a regular
file, a directory, a fifo file, or of unknown type;
@code{size(@var{Size})}, with gives the size for a file, and
@code{mod_time(@var{Time})}, which gives the last time a file was
modified according to some Operating System dependent
timestamp; @code{mode(@var{mode})}, gives the permission flags for the
file, and @code{linkto(@var{FileName})}, gives the file pointed to by a
symbolic link. Properties can be obtained through backtracking:

@example
   ?- file_property('Makefile',P).

P = type(regular) ? ;

P = size(2375) ? ;

P = mod_time(990826911) ? ;

no
@end example

@item make_directory(+@var{Dir})
@findex  make_directory/2
@syindex make_directory/2
@cnindex make_directory/2
Create a directory @var{Dir}. The name of the directory must be an atom.

@item rename_file(+@var{OldFile},+@var{NewFile})
@findex  rename_file/2
@syindex rename_file/2
@cnindex rename_file/2
Create file @var{OldFile} to @var{NewFile}. This predicate uses the
@code{C} built-in function @code{rename}.


@item environ(?@var{EnvVar},+@var{EnvValue})
@findex  sys_environ/2
@syindex sys_environ/2
@cnindex sys_environ/2
Unify environment variable @var{EnvVar} with its value @var{EnvValue},
if there is one. This predicate is backtrackable in Unix systems, but
not currently in Win32 configurations.

@example
   ?- environ('HOME',X).

X = 'C:\\cygwin\\home\\administrator' ?
@end example

@item host_id(-@var{Id})
@findex  host_id/1
@syindex host_id/1
@cnindex host_id/1

Unify @var{Id} with an identifier of the current host. YAP uses the
@code{hostid} function when available, 

@item host_name(-@var{Name})
@findex  host_name/1
@syindex host_name/1
@cnindex host_name/1

Unify @var{Name} with a name for the current host. YAP uses the
@code{hostname} function in Unix systems when available, and the
@code{GetComputerName} function in WIN32 systems. 

@item kill(@var{Id},+@var{SIGNAL})
@findex  kill/2
@syindex kill/2
@cnindex kill/2

Send signal @var{SIGNAL} to process @var{Id}. In Unix this predicate is
a direct interface to @code{kill} so one can send signals to groups of
processes. In WIN32 the predicate is an interface to
@code{TerminateProcess}, so it kills @var{Id} independently of @var{SIGNAL}.

@item mktemp(@var{Spec},-@var{File})
@findex  mktemp/2
@syindex mktemp/2
@cnindex mktemp/2

Direct interface to @code{mktemp}: given a @var{Spec}, that is a file
name with six @var{X} to it, create a file name @var{File}. Use
@code{tmpnam/1} instead.

@item pid(-@var{Id})
@findex  pid/1
@syindex pid/1
@cnindex pid/1

Unify @var{Id} with the process identifier for the current
process. An interface to the @t{getpid} function.

@item tmpnam(-@var{File})
@findex  tmpnam/1
@syindex tmpnam/1
@cnindex tmpnam/1

Interface with @var{tmpnam}: obtain a new, unique file name @var{File}.

@item tmp_file(-@var{File})
@findex  tmp_file/2
@snindex tmp_file/2
@cnindex tmp_file/2

Create a name for a temporary file. @var{Base} is an user provided
identifier for the category of file. The @var{TmpName} is guaranteed to
be unique. If the system halts, it will automatically remove all created
temporary files.


@item exec(+@var{Command},[+@var{InputStream},+@var{OutputStream},+@var{ErrorStream}],-@var{PID})
@findex  exec/3
@syindex exec/3
@cnindex exec/3
Execute command @var{Command} with its streams connected to
@var{InputStream}, @var{OutputStream}, and @var{ErrorStream}. The
process that executes the command is returned as @var{PID}. The
command is executed by the default shell @code{bin/sh -c} in Unix.

The following example demonstrates the use of @code{exec/3} to send a
command and process its output:

@example
exec(ls,[std,pipe(S),null],P),repeat, get0(S,C), (C = -1, close(S) ! ; put(C)).
@end example

The streams may be one of standard stream, @code{std}, null stream,
@code{null}, or @code{pipe(S)}, where @var{S} is a pipe stream. Note
that it is up to the user to close the pipe.

@item popen(+@var{Command}, +@var{TYPE}, -@var{Stream})
@findex  popen/3
@syindex popen/3
@cnindex popen/3
Interface to the @t{popen} function. It opens a process by creating a
pipe, forking and invoking @var{Command} on the current shell. Since a
pipe is by definition unidirectional the @var{Type} argument may be
@code{read} or @code{write}, not both. The stream should be closed
using @code{close/1}, there is no need for a special @code{pclose}
command.

The following example demonstrates the use of @code{popen/3} to process
the output of a command, as @code{exec/3} would do:

@pl_example
   ?- popen(ls,read,X),repeat, get0(X,C), (C = -1, ! ; put(C)).

X = 'C:\\cygwin\\home\\administrator' ?
@end pl_example


The WIN32 implementation of @code{popen/3} relies on @code{exec/3}.

@item shell
@findex  shell/0
@syindex shell/0
@cnindex shell/0
Start a new shell and leave YAP in background until the shell
completes. YAP uses the shell given by the environment variable
@code{SHELL}. In WIN32 environment YAP will use @code{COMSPEC} if
@code{SHELL} is undefined.

@item shell(+@var{Command})
@findex  shell/1
@syindex shell/1
@cnindex shell/1
Execute command @var{Command} under a new shell. YAP will be in
background until the command completes. In Unix environments YAP uses
the shell given by the environment variable @code{SHELL} with the option
@code{" -c "}. In WIN32 environment YAP will use @code{COMSPEC} if
@code{SHELL} is undefined, in this case with the option @code{" /c "}.

@item shell(+@var{Command},-@var{Status})
@findex  shell/2
@syindex shell/2
@cnindex shell/2
Execute command @var{Command} under a new shell and unify @var{Status}
with the exit for the command. YAP will be in background until the
command completes. In Unix environments YAP uses the shell given by the
environment variable @code{SHELL} with the option @code{" -c "}. In
WIN32 environment YAP will use @code{COMSPEC} if @code{SHELL} is
undefined, in this case with the option @code{" /c "}.

@item sleep(+@var{Time})
@findex  sleep/1
@syindex sleep/1
@cnindex sleep/1
Block the current thread for @var{Time} seconds. When YAP is compiled 
without multi-threading support, this predicate blocks the YAP process. 
The number of seconds must be a positive number, and it may an integer 
or a float. The Unix implementation uses @code{usleep} if the number of 
seconds is below one, and @code{sleep} if it is over a second. The WIN32 
implementation uses @code{Sleep} for both cases.

@item system
@findex  system/0
@syindex system/0
@cnindex system/0
Start a new default shell and leave YAP in background until the shell
completes. YAP uses @code{/bin/sh} in Unix systems and @code{COMSPEC} in
WIN32.

@item system(+@var{Command},-@var{Res})
@findex  system/2
@syindex system/2
@cnindex system/2
Interface to @code{system}: execute command @var{Command} and unify
@var{Res} with the result.

@item wait(+@var{PID},-@var{Status})
@findex  wait/2
@syindex wait/2
@cnindex wait/2
Wait until process @var{PID} terminates, and return its exits @var{Status}.

@end table


@node Terms, Tries, System, Library
@section Utilities On Terms
@cindex utilities on terms

The next routines provide a set of commonly used utilities to manipulate
terms. Most of these utilities have been implemented in @code{C} for
efficiency. They are available through the
@code{use_module(library(terms))} command.

@table @code

@item cyclic_term(?@var{Term})
@findex cyclic_term/1
@syindex cyclic_term/1
@cnindex cyclic_term/1
Succeed if the argument @var{Term} is not a cyclic term.

@item term_hash(+@var{Term}, ?@var{Hash})
@findex  term_hash/2
@syindex term_hash/2
@cnindex term_hash/2

If @var{Term} is ground unify @var{Hash} with a positive integer
calculated from the structure of the term. Otherwise the argument
@var{Hash} is left unbound. The range of the positive integer is from
@code{0} to, but not including, @code{33554432}.

@item term_hash(+@var{Term}, +@var{Depth}, +@var{Range}, ?@var{Hash})
@findex  term_hash/4
@syindex term_hash/4
@cnindex term_hash/4

Unify @var{Hash} with a positive integer calculated from the structure
of the term.  The range of the positive integer is from @code{0} to, but
not including, @var{Range}. If @var{Depth} is @code{-1} the whole term
is considered. Otherwise, the term is considered only up to depth
@code{1}, where the constants and the principal functor have depth
@code{1}, and an argument of a term with depth @var{I} has depth @var{I+1}. 

@item variables_within_term(+@var{Variables},?@var{Term}, -@var{OutputVariables})
@findex  variables_within_term/3
@snindex variables_within_term/3 
@cnindex variables_within_term/3  

Unify @var{OutputVariables} with the subset of the variables @var{Variables} that occurs in @var{Term}.

@item new_variables_in_term(+@var{Variables},?@var{Term}, -@var{OutputVariables})
@findex  new_variables_in_term/3
@snindex new_variables_in_term/3 
@cnindex new_variables_in_term/3  

Unify @var{OutputVariables} with all variables occurring in @var{Term} that are not in the list @var{Variables}.

@item variant(?@var{Term1}, ?@var{Term2})
@findex  variant/2
@syindex variant/2
@cnindex variant/2

Succeed if @var{Term1} and @var{Term2} are variant terms.

@item subsumes(?@var{Term1}, ?@var{Term2})
@findex  subsumes/2
@syindex subsumes/2
@cnindex subsumes/2

Succeed if @var{Term1} subsumes @var{Term2}.  Variables in term
@var{Term1} are bound so that the two terms become equal.


@item subsumes_chk(?@var{Term1}, ?@var{Term2})
@findex  subsumes_chk/2
@syindex subsumes_chk/2
@cnindex subsumes_chk/2

Succeed if @var{Term1} subsumes @var{Term2} but does not bind any
variable in @var{Term1}.

@item variable_in_term(?@var{Term},?@var{Var})
@findex variable_in_term/2
@snindex variable_in_term/2
@cnindex variable_in_term/2
Succeed if the second argument @var{Var} is a variable and occurs in
term @var{Term}.

@item unifiable(?@var{Term1}, ?@var{Term2}, -@var{Bindings})
@findex  unifiable/3
@syindex unifiable/3
@cnindex unifiable/3

Succeed if @var{Term1} and @var{Term2} are unifiable with substitution
@var{Bindings}.

@end table

@node Tries, Cleanup, Terms, Library
@section Trie DataStructure
@cindex tries

The next routines provide a set of utilities to create and manipulate
prefix trees of Prolog terms. Tries were originally proposed to
implement tabling in Logic Programming, but can be used for other
purposes. The tries will be stored in the Prolog database and can seen
as alternative to @code{assert} and @code{record} family of
primitives. Most of these utilities have been implemented in @code{C}
for efficiency. They are available through the
@code{use_module(library(tries))} command.

@table @code
@item trie_open(-@var{Id})
@findex trie_open/1
@snindex trie_open/1
@cnindex trie_open/1

Open a new trie with identifier @var{Id}.

@item trie_close(+@var{Id})
@findex trie_close/1
@snindex trie_close/1
@cnindex trie_close/1

Close trie with identifier @var{Id}.

@item trie_close_all
@findex trie_close_all/0
@snindex trie_close_all/0
@cnindex trie_close_all/0

Close all available tries.

@item trie_mode(?@var{Mode})
@findex trie_mode/1
@snindex trie_mode/1
@cnindex trie_mode/1

Unify @var{Mode} with trie operation mode. Allowed values are either
@code{std} (default) or @code{rev}.

@item trie_put_entry(+@var{Trie},+@var{Term},-@var{Ref})
@findex trie_put_entry/3
@snindex trie_put_entry/3
@cnindex trie_put_entry/3

Add term @var{Term} to trie @var{Trie}. The handle @var{Ref} gives
a reference to the term.

@item trie_check_entry(+@var{Trie},+@var{Term},-@var{Ref})
@findex trie_check_entry/3
@snindex trie_check_entry/3
@cnindex trie_check_entry/3

Succeeds if a variant of term @var{Term} is in trie @var{Trie}. An handle
 @var{Ref} gives a reference to the term.

@item trie_get_entry(+@var{Ref},-@var{Term})
@findex trie_get_entry/2
@snindex trie_get_entry/2
@cnindex trie_get_entry/2
Unify @var{Term} with the entry for handle @var{Ref}.

@item trie_remove_entry(+@var{Ref})
@findex trie_remove_entry/1
@snindex trie_remove_entry/1
@cnindex trie_remove_entry/1

Remove entry for handle @var{Ref}.

@item trie_remove_subtree(+@var{Ref})
@findex trie_remove_subtree/1
@snindex trie_remove_subtree/1
@cnindex trie_remove_subtree/1

Remove subtree rooted at handle @var{Ref}.

@item trie_save(+@var{Trie},+@var{FileName})
@findex trie_save/2
@snindex trie_save/2
@cnindex trie_save/2
Dump trie @var{Trie} into file @var{FileName}.


@item trie_load(+@var{Trie},+@var{FileName})
@findex trie_load/2
@snindex trie_load/2
@cnindex trie_load/2
Load trie @var{Trie} from the contents of file @var{FileName}.

@item trie_stats(-@var{Memory},-@var{Tries},-@var{Entries},-@var{Nodes})
@findex trie_stats/4
@snindex trie_stats/4
@cnindex trie_stats/4
Give generic statistics on tries, including the amount of memory,
@var{Memory}, the number of tries, @var{Tries}, the number of entries,
@var{Entries}, and the total number of nodes, @var{Nodes}.

@item trie_max_stats(-@var{Memory},-@var{Tries},-@var{Entries},-@var{Nodes})
@findex trie_max_stats/4
@snindex trie_max_stats/4
@cnindex trie_max_stats/4
Give maximal statistics on tries, including the amount of memory,
@var{Memory}, the number of tries, @var{Tries}, the number of entries,
@var{Entries}, and the total number of nodes, @var{Nodes}.


@item trie_usage(+@var{Trie},-@var{Entries},-@var{Nodes},-@var{VirtualNodes})
@findex trie_usage/4
@snindex trie_usage/4
@cnindex trie_usage/4
Give statistics on trie @var{Trie}, the number of entries,
@var{Entries}, and the total number of nodes, @var{Nodes}, and the
number of @var{VirtualNodes}.

@item trie_print(+@var{Trie})
@findex trie_print/1
@snindex trie_print/1
@cnindex trie_print/1
Print trie @var{Trie} on standard output.




@end table


@node Cleanup, Timeout, Tries, Library
@section Call Cleanup
@cindex cleanup

@t{call_cleanup/1} and @t{call_cleanup/2} allow predicates to register
code for execution after the call is finished. Predicates can be
declared to be @t{fragile} to ensure that @t{call_cleanup} is called
for any Goal which needs it. This library is loaded with the
@code{use_module(library(cleanup))} command.

@table @code
@item :- fragile @var{P},....,@var{Pn}
@findex fragile
@syindex fragile
@cnindex fragile
Declares the predicate @var{P}=@t{[module:]name/arity} as a fragile
predicate, module is optional, default is the current
typein_module. Whenever such a fragile predicate is used in a query
it will be called through call_cleanup/1.
@pl_example
:- fragile foo/1,bar:baz/2.
@end pl_example

@item call_cleanup(:@var{Goal})
@findex call_cleanup/1
@syindex call_cleanup/1
@cnindex call_cleanup/1
Execute goal @var{Goal} within a cleanup-context. Called predicates
might register cleanup Goals which are called right after the end of
the call to @var{Goal}. Cuts and exceptions inside Goal do not prevent the
execution of the cleanup calls. @t{call_cleanup} might be nested.

@item call_cleanup(:@var{Goal}, :@var{CleanUpGoal})
@findex call_cleanup/2
@syindex call_cleanup/2
@cnindex call_cleanup/2
This is similar to @t{call_cleanup/1} with an additional
@var{CleanUpGoal} which gets called after @var{Goal} is finished.

@item setup_call_cleanup(:@var{Setup},:@var{Goal}, :@var{CleanUpGoal})
@findex setup_call_cleanup/3
@snindex setup_call_cleanup/3
@cnindex setup_call_cleanup/3
Calls @code{(Setup, Goal)}. For each sucessful execution of @var{Setup}, calling @var{Goal}, the
cleanup handler @var{Cleanup} is guaranteed to be called exactly once.
This will happen after @var{Goal} completes, either through failure,
deterministic success, commit, or an exception.  @var{Setup} will
contain the goals that need to be protected from asynchronous interrupts
such as the ones received from @code{call_with_time_limit/2} or @code{thread_signal/2}.  In
most uses, @var{Setup} will perform temporary side-effects required by
@var{Goal} that are finally undone by @var{Cleanup}.

Success or failure of @var{Cleanup} is ignored and choice-points it
created are destroyed (as @code{once/1}). If @var{Cleanup} throws an exception,
this is executed as normal.

Typically, this predicate is used to cleanup permanent data storage
required to execute @var{Goal}, close file-descriptors, etc. The example
below provides a non-deterministic search for a term in a file, closing
the stream as needed.

@pl_example
term_in_file(Term, File) :-
    setup_call_cleanup(open(File, read, In),
               term_in_stream(Term, In),
               close(In) ).

term_in_stream(Term, In) :-
    repeat,
    read(In, T),
    (   T == end_of_file
    ->  !, fail
    ;   T = Term
    ).
@end pl_example

Note that it is impossible to implement this predicate in Prolog other than
by reading all terms into a list, close the file and call @code{member/2}.
Without @code{setup_call_cleanup/3} there is no way to gain control if the
choice-point left by @code{repeat} is removed by a cut or an exception.

@code{setup_call_cleanup/2} can also be used to test determinism of a goal:

@example
?- setup_call_cleanup(true,(X=1;X=2), Det=yes).

X = 1 ;

X = 2,
Det = yes ;
@end example

This predicate is under consideration for inclusion into the ISO standard.
For compatibility with other Prolog implementations see @code{call_cleanup/2}.

 @item setup_call_catcher_cleanup(:@var{Setup},:@var{Goal}, +@var{Catcher},:@var{CleanUpGoal})
@findex setup_call_catcher_cleanup/4
@snindex setup_call_catcher_cleanup/4
@cnindex setup_call_catcher_cleanup/4
Similar to @code{setup_call_cleanup(@var{Setup}, @var{Goal}, @var{Cleanup})} with
additional information on the reason of calling @var{Cleanup}.  Prior
to calling @var{Cleanup}, @var{Catcher} unifies with the termination
code.  If this unification fails, @var{Cleanup} is
@strong{not} called.


@item on_cleanup(+@var{CleanUpGoal})
@findex on_cleanup/1
@syindex on_cleanup/1
@cnindex on_cleanup/1
Any Predicate might registers a @var{CleanUpGoal}. The
@var{CleanUpGoal} is put onto the current cleanup context. All such
CleanUpGoals are executed in reverse order of their registration when
the surrounding cleanup-context ends. This call will throw an exception
if a predicate tries to register a @var{CleanUpGoal} outside of any
cleanup-context.

@item cleanup_all
@findex cleanup_all/0
@syindex cleanup_all/0
@cnindex cleanup_all/0
Calls all pending CleanUpGoals and resets the cleanup-system to an
initial state. Should only be used as one of the last calls in the
main program.

@end table

There are some private predicates which could be used in special
cases, such as manually setting up cleanup-contexts and registering
CleanUpGoals for other than the current cleanup-context.
Read the Source Luke.


@node Timeout, Trees, Cleanup, Library
@section Calls With Timeout
@cindex timeout

The @t{time_out/3} command relies on the @t{alarm/3} built-in to
implement a call with a maximum time of execution. The command is
available with the @code{use_module(library(timeout))} command.

@table @code


@item time_out(+@var{Goal}, +@var{Timeout}, -@var{Result})
@findex time_out/3
@syindex time_out/3
@cnindex time_out/3
Execute goal @var{Goal} with time limited @var{Timeout}, where
@var{Timeout} is measured in milliseconds. If the goal succeeds, unify
@var{Result} with success. If the timer expires before the goal
terminates, unify @var{Result} with @t{time_out}.

This command is implemented by activating an alarm at procedure
entry. If the timer expires before the goal completes, the alarm will
throw an exception @var{timeout}.

One should note that @code{time_out/3} is not reentrant, that is, a goal
called from @code{time_out} should never itself call
@code{time_out/3}. Moreover, @code{time_out/3} will deactivate any previous
alarms set by @code{alarm/3} and vice-versa, hence only one of these
calls should be used in a program.

Last, even though the timer is set in milliseconds, the current
implementation relies on @t{alarm/3}, and therefore can only offer
precision on the scale of seconds.

@end table

@node Trees, UGraphs, Timeout, Library
@section Updatable Binary Trees
@cindex updatable tree

The following queue manipulation routines are available once
included with the @code{use_module(library(trees))} command.

@table @code

@item get_label(+@var{Index}, +@var{Tree}, ?@var{Label})
@findex get_label/3
@syindex get_label/3
@cnindex get_label/3
Treats the tree as an array of @var{N} elements and returns the
@var{Index}-th.

@item list_to_tree(+@var{List}, -@var{Tree})
@findex list_to_tree/2
@syindex list_to_tree/2
@cnindex list_to_tree/2
Takes a given @var{List} of @var{N} elements and constructs a binary
@var{Tree}.

@item map_tree(+@var{Pred}, +@var{OldTree}, -@var{NewTree})
@findex map_tree/3
@syindex map_tree/3
@cnindex map_tree/3
Holds when @var{OldTree} and @var{NewTree} are binary trees of the same shape
and @code{Pred(Old,New)} is true for corresponding elements of the two trees.

@item put_label(+@var{Index}, +@var{OldTree}, +@var{Label}, -@var{NewTree})
@findex put_label/4
@syindex put_label/4
@cnindex put_label/4
constructs a new tree the same shape as the old which moreover has the
same elements except that the @var{Index}-th one is @var{Label}.

@item tree_size(+@var{Tree}, -@var{Size})
@findex tree_size/2
@syindex tree_size/2
@cnindex tree_size/2
Calculates the number of elements in the @var{Tree}.

@item tree_to_list(+@var{Tree}, -@var{List})
@findex tree_to_list/2
@syindex tree_to_list/2
@cnindex tree_to_list/2
Is the converse operation to list_to_tree.

@end table

@node UGraphs, DGraphs, Trees, Library
@section Unweighted Graphs
@cindex unweighted graphs

The following graph manipulation routines are based in code originally
written by Richard O'Keefe. The code was then extended to be compatible
with the SICStus Prolog ugraphs library. The routines assume directed
graphs, undirected graphs may be implemented by using two edges. Graphs
are represented in one of two ways:

@itemize @bullet
@item The P-representation of a graph is a list of (from-to) vertex
pairs, where the pairs can be in any old order.  This form is
convenient for input/output.
 
@item The S-representation of a graph is a list of (vertex-neighbors)
pairs, where the pairs are in standard order (as produced by keysort)
and the neighbors of each vertex are also in standard order (as
produced by sort).  This form is convenient for many calculations.
@end itemize

These built-ins are available once included with the
@code{use_module(library(ugraphs))} command.

@table @code

@item vertices_edges_to_ugraph(+@var{Vertices}, +@var{Edges}, -@var{Graph})
@findex  vertices_edges_to_ugraph/3
@syindex vertices_edges_to_ugraph/3
@cnindex vertices_edges_to_ugraph/3
Given a graph with a set of vertices @var{Vertices} and a set of edges
@var{Edges}, @var{Graph} must unify with the corresponding
s-representation. Note that the vertices without edges will appear in
@var{Vertices} but not in @var{Edges}. Moreover, it is sufficient for a
vertex to appear in @var{Edges}.
@pl_example
?- vertices_edges_to_ugraph([],[1-3,2-4,4-5,1-5],L).

L = [1-[3,5],2-[4],3-[],4-[5],5-[]] ? 

@end pl_example
In this case all edges are defined implicitly. The next example shows
three unconnected edges:
@pl_example 
?- vertices_edges_to_ugraph([6,7,8],[1-3,2-4,4-5,1-5],L).

L = [1-[3,5],2-[4],3-[],4-[5],5-[],6-[],7-[],8-[]] ? 

@end pl_example

@item vertices(+@var{Graph}, -@var{Vertices})
@findex  vertices/2
@syindex vertices/2
@cnindex vertices/2
Unify @var{Vertices} with all vertices appearing in graph
@var{Graph}. In the next example:
@pl_example
?- vertices([1-[3,5],2-[4],3-[],4-[5],5-[]], V).

L = [1,2,3,4,5]
@end pl_example

@item edges(+@var{Graph}, -@var{Edges})
@findex  edges/2
@syindex edges/2
@cnindex edges/2
Unify @var{Edges} with all edges appearing in graph
@var{Graph}. In the next example:
@pl_example
?- vertices([1-[3,5],2-[4],3-[],4-[5],5-[]], V).

L = [1,2,3,4,5]
@end pl_example

@item add_vertices(+@var{Graph}, +@var{Vertices}, -@var{NewGraph})
@findex  add_vertices/3
@syindex add_vertices/3
@cnindex add_vertices/3
Unify @var{NewGraph} with a new graph obtained by adding the list of
vertices @var{Vertices} to the graph @var{Graph}. In the next example:
@pl_example
?- add_vertices([1-[3,5],2-[4],3-[],4-[5],
                 5-[],6-[],7-[],8-[]],
                [0,2,9,10,11],
                   NG).

NG = [0-[],1-[3,5],2-[4],3-[],4-[5],5-[],
      6-[],7-[],8-[],9-[],10-[],11-[]]
@end pl_example

@item del_vertices(+@var{Graph}, +@var{Vertices}, -@var{NewGraph})
@findex  del_vertices/3
@syindex del_vertices/3
@cnindex del_vertices/3
Unify @var{NewGraph} with a new graph obtained by deleting the list of
vertices @var{Vertices} and all the edges that start from or go to a
vertex in @var{Vertices} to the graph @var{Graph}. In the next example:
@pl_example
?- del_vertices([2,1],[1-[3,5],2-[4],3-[],
                 4-[5],5-[],6-[],7-[2,6],8-[]],NL).

NL = [3-[],4-[5],5-[],6-[],7-[6],8-[]]
@end pl_example

@item add_edges(+@var{Graph}, +@var{Edges}, -@var{NewGraph})
@findex  add_edges/3
@syindex add_edges/3
@cnindex add_edges/3
Unify @var{NewGraph} with a new graph obtained by adding the list of
edges @var{Edges} to the graph @var{Graph}. In the next example:
@pl_example
?- add_edges([1-[3,5],2-[4],3-[],4-[5],5-[],6-[],
              7-[],8-[]],[1-6,2-3,3-2,5-7,3-2,4-5],NL).

NL = [1-[3,5,6],2-[3,4],3-[2],4-[5],5-[7],6-[],7-[],8-[]]
@end pl_example

@item del_edges(+@var{Graph}, +@var{Edges}, -@var{NewGraph})
@findex  del_edges/3
@syindex del_edges/3
@cnindex del_edges/3
Unify @var{NewGraph} with a new graph obtained by removing the list of
edges @var{Edges} from the graph @var{Graph}. Notice that no vertices
are deleted. In the next example:
@pl_example
?- del_edges([1-[3,5],2-[4],3-[],4-[5],5-[],
              6-[],7-[],8-[]],
             [1-6,2-3,3-2,5-7,3-2,4-5,1-3],NL).

NL = [1-[5],2-[4],3-[],4-[],5-[],6-[],7-[],8-[]]
@end pl_example

@item transpose(+@var{Graph}, -@var{NewGraph})
@findex  transpose/3
@syindex transpose/3
@cnindex transpose/3
Unify @var{NewGraph} with a new graph obtained from @var{Graph} by
replacing all edges of the form @var{V1-V2} by edges of the form
@var{V2-V1}. The cost is @code{O(|V|^2)}. In the next example:
@pl_example
?- transpose([1-[3,5],2-[4],3-[],
              4-[5],5-[],6-[],7-[],8-[]], NL).

NL = [1-[],2-[],3-[1],4-[2],5-[1,4],6-[],7-[],8-[]]
@end pl_example
Notice that an undirected graph is its own transpose.

@item neighbors(+@var{Vertex}, +@var{Graph}, -@var{Vertices})
@findex  neighbors/3
@syindex neighbors/3
@cnindex neighbors/3
Unify @var{Vertices} with the list of neighbors of vertex @var{Vertex}
in @var{Graph}. If the vertice is not in the graph fail. In the next
example:
@pl_example
?- neighbors(4,[1-[3,5],2-[4],3-[],
                4-[1,2,7,5],5-[],6-[],7-[],8-[]],
             NL).

NL = [1,2,7,5]
@end pl_example

@item neighbours(+@var{Vertex}, +@var{Graph}, -@var{Vertices})
@findex  neighbours/3
@syindex neighbours/3
@cnindex neighbours/3
Unify @var{Vertices} with the list of neighbours of vertex @var{Vertex}
in @var{Graph}. In the next example:
@pl_example
?- neighbours(4,[1-[3,5],2-[4],3-[],
                 4-[1,2,7,5],5-[],6-[],7-[],8-[]], NL).

NL = [1,2,7,5]
@end pl_example

@item complement(+@var{Graph}, -@var{NewGraph})
@findex  complement/2
@syindex complement/2
@cnindex complement/2
Unify @var{NewGraph} with the graph complementary to @var{Graph}.
 In the next example:
@pl_example
?- complement([1-[3,5],2-[4],3-[],
               4-[1,2,7,5],5-[],6-[],7-[],8-[]], NL).

NL = [1-[2,4,6,7,8],2-[1,3,5,6,7,8],3-[1,2,4,5,6,7,8],
      4-[3,5,6,8],5-[1,2,3,4,6,7,8],6-[1,2,3,4,5,7,8],
      7-[1,2,3,4,5,6,8],8-[1,2,3,4,5,6,7]]
@end pl_example

@item compose(+@var{LeftGraph}, +@var{RightGraph}, -@var{NewGraph})
@findex  compose/3
@syindex compose/3
@cnindex compose/3
Compose the graphs @var{LeftGraph} and @var{RightGraph} to form @var{NewGraph}.
 In the next example:
@pl_example
?- compose([1-[2],2-[3]],[2-[4],3-[1,2,4]],L).

L = [1-[4],2-[1,2,4],3-[]]
@end pl_example

@item top_sort(+@var{Graph}, -@var{Sort})
@findex  top_sort/2
@syindex top_sort/2
@cnindex top_sort/2
Generate the set of nodes @var{Sort} as a topological sorting of graph
@var{Graph}, if one is possible.
 In the next example we show how topological sorting works for a linear graph:
@pl_example
?- top_sort([_138-[_219],_219-[_139], _139-[]],L).

L = [_138,_219,_139]
@end pl_example

@item top_sort(+@var{Graph}, -@var{Sort0}, -@var{Sort})
@findex  top_sort/3
@syindex top_sort/3
@cnindex top_sort/3
Generate the difference list @var{Sort}-@var{Sort0} as a topological
sorting of graph @var{Graph}, if one is possible.

@item transitive_closure(+@var{Graph}, +@var{Closure})
@findex  transitive_closure/2
@syindex transitive_closure/2
@cnindex transitive_closure/2
Generate the graph @var{Closure} as the transitive closure of graph
@var{Graph}.
 In the next example:
@pl_example
?- transitive_closure([1-[2,3],2-[4,5],4-[6]],L).

L = [1-[2,3,4,5,6],2-[4,5,6],4-[6]]
@end pl_example

@item reachable(+@var{Node}, +@var{Graph}, -@var{Vertices})
@findex  reachable/3
@syindex reachable/3
@cnindex reachable/3
Unify @var{Vertices} with the set of all vertices in graph
@var{Graph} that are reachable from @var{Node}. In the next example:
@pl_example
?- reachable(1,[1-[3,5],2-[4],3-[],4-[5],5-[]],V).

V = [1,3,5]
@end pl_example

@end table

@node DGraphs, UnDGraphs, UGraphs, Library
@section Directed Graphs
@cindex Efficient Directed Graphs

The following graph manipulation routines use the red-black tree library
to try to avoid linear-time scans of the graph for all graph
operations. Graphs are represented as a red-black tree, where the key is
the vertex, and the associated value is a list of vertices reachable
from that vertex through an edge (ie, a list of edges). 

@table @code

@item dgraph_new(+@var{Graph})
@findex  dgraph_new/1
@snindex dgraph_new/1
@cnindex dgraph_new/1
Create a new directed graph. This operation must be performed before
trying to use the graph.

@item dgraph_vertices(+@var{Graph}, -@var{Vertices})
@findex  dgraph_vertices/2
@snindex dgraph_vertices/2
@cnindex dgraph_vertices/2
Unify @var{Vertices} with all vertices appearing in graph
@var{Graph}.

@item dgraph_edge(+@var{N1}, +@var{N2}, +@var{Graph})
@findex  dgraph_edge/2
@snindex dgraph_edge/2
@cnindex dgraph_edge/2
Edge @var{N1}-@var{N2} is an edge in directed graph @var{Graph}.

@item dgraph_edges(+@var{Graph}, -@var{Edges})
@findex  dgraph_edges/2
@snindex dgraph_edges/2
@cnindex dgraph_edges/2
Unify @var{Edges} with all edges appearing in graph
@var{Graph}.

@item dgraph_add_vertices(+@var{Graph}, +@var{Vertex}, -@var{NewGraph})
@findex  dgraph_add_vertex/3
@snindex dgraph_add_vertex/3
@cnindex dgraph_add_vertex/3
Unify @var{NewGraph} with a new graph obtained by adding
vertex @var{Vertex} to the graph @var{Graph}.

@item dgraph_add_vertices(+@var{Graph}, +@var{Vertices}, -@var{NewGraph})
@findex  dgraph_add_vertices/3
@snindex dgraph_add_vertices/3
@cnindex dgraph_add_vertices/3
Unify @var{NewGraph} with a new graph obtained by adding the list of
vertices @var{Vertices} to the graph @var{Graph}.

@item dgraph_del_vertex(+@var{Graph}, +@var{Vertex}, -@var{NewGraph})
@findex  dgraph_del_vertex/3
@syindex dgraph_del_vertex/3
@cnindex dgraph_del_vertex/3
Unify @var{NewGraph} with a new graph obtained by deleting vertex
@var{Vertex} and all the edges that start from or go to @var{Vertex} to
the graph @var{Graph}.

@item dgraph_del_vertices(+@var{Graph}, +@var{Vertices}, -@var{NewGraph})
@findex  dgraph_del_vertices/3
@syindex dgraph_del_vertices/3
@cnindex dgraph_del_vertices/3
Unify @var{NewGraph} with a new graph obtained by deleting the list of
vertices @var{Vertices} and all the edges that start from or go to a
vertex in @var{Vertices} to the graph @var{Graph}.

@item dgraph_add_edge(+@var{Graph}, +@var{N1}, +@var{N2}, -@var{NewGraph})
@findex  dgraph_add_edge/4
@snindex dgraph_add_edge/4
@cnindex dgraph_add_edge/4
Unify @var{NewGraph} with a new graph obtained by adding the edge
@var{N1}-@var{N2} to the graph @var{Graph}.

@item dgraph_add_edges(+@var{Graph}, +@var{Edges}, -@var{NewGraph})
@findex  dgraph_add_edges/3
@snindex dgraph_add_edges/3
@cnindex dgraph_add_edges/3
Unify @var{NewGraph} with a new graph obtained by adding the list of
edges @var{Edges} to the graph @var{Graph}.

@item dgraph_del_edge(+@var{Graph}, +@var{N1}, +@var{N2}, -@var{NewGraph})
@findex  dgraph_del_edge/4
@snindex dgraph_del_edge/4
@cnindex dgraph_del_edge/4
Succeeds if @var{NewGraph} unifies with a new graph obtained by
removing the edge @var{N1}-@var{N2} from the graph @var{Graph}. Notice
that no vertices are deleted.

@item dgraph_del_edges(+@var{Graph}, +@var{Edges}, -@var{NewGraph})
@findex  dgraph_del_edges/3
@snindex dgraph_del_edges/3
@cnindex dgraph_del_edges/3
Unify @var{NewGraph} with a new graph obtained by removing the list of
edges @var{Edges} from the graph @var{Graph}. Notice that no vertices
are deleted.

@item dgraph_to_ugraph(+@var{Graph}, -@var{UGraph})
@findex  dgraph_to_ugraph/2
@snindex dgraph_to_ugraph/2
@cnindex dgraph_to_ugraph/2
Unify @var{UGraph} with the representation used by the @var{ugraphs}
unweighted graphs library, that is, a list of the form
@var{V-Neighbors}, where @var{V} is a node and @var{Neighbors} the nodes
children.

@item ugraph_to_dgraph( +@var{UGraph}, -@var{Graph})
@findex  ugraph_to_dgraph/2
@snindex ugraph_to_dgraph/2
@cnindex ugraph_to_dgraph/2
Unify @var{Graph} with the directed graph obtain from @var{UGraph},
represented in the form used in the @var{ugraphs} unweighted graphs
library.

@item dgraph_neighbors(+@var{Vertex}, +@var{Graph}, -@var{Vertices})
@findex  dgraph_neighbors/3
@snindex dgraph_neighbors/3
@cnindex dgraph_neighbors/3
Unify @var{Vertices} with the list of neighbors of vertex @var{Vertex}
in @var{Graph}. If the vertice is not in the graph fail.

@item dgraph_neighbours(+@var{Vertex}, +@var{Graph}, -@var{Vertices})
@findex  dgraph_neighbours/3
@snindex dgraph_neighbours/3
@cnindex dgraph_neighbours/3
Unify @var{Vertices} with the list of neighbours of vertex @var{Vertex}
in @var{Graph}.

@item dgraph_complement(+@var{Graph}, -@var{NewGraph})
@findex  dgraph_complement/2
@snindex dgraph_complement/2
@cnindex dgraph_complement/2
Unify @var{NewGraph} with the graph complementary to @var{Graph}.

@item dgraph_transpose(+@var{Graph}, -@var{Transpose})
@findex  dgraph_transpose/2
@snindex dgraph_transpose/2
@cnindex dgraph_transpose/2
Unify @var{NewGraph} with a new graph obtained from @var{Graph} by
replacing all edges of the form @var{V1-V2} by edges of the form
@var{V2-V1}. 

@item dgraph_compose(+@var{Graph1}, +@var{Graph2}, -@var{ComposedGraph})
@findex  dgraph_compose/3
@snindex dgraph_compose/3
@cnindex dgraph_compose/3
Unify @var{ComposedGraph} with a new graph obtained by composing
@var{Graph1} and @var{Graph2}, ie, @var{ComposedGraph} has an edge
@var{V1-V2} iff there is a @var{V} such that @var{V1-V} in @var{Graph1}
and @var{V-V2} in @var{Graph2}.

@item dgraph_transitive_closure(+@var{Graph}, -@var{Closure})
@findex  dgraph_transitive_closure/2
@snindex dgraph_transitive_closure/2
@cnindex dgraph_transitive_closure/2
Unify @var{Closure} with the transitive closure of graph @var{Graph}.

@item dgraph_symmetric_closure(+@var{Graph}, -@var{Closure})
@findex  dgraph_symmetric_closure/2
@snindex dgraph_symmetric_closure/2
@cnindex dgraph_symmetric_closure/2
Unify @var{Closure} with the symmetric closure of graph @var{Graph},
that is,  if @var{Closure} contains an edge @var{U-V} it must also
contain the edge @var{V-U}.

@item dgraph_top_sort(+@var{Graph}, -@var{Vertices})
@findex  dgraph_top_sort/2
@snindex dgraph_top_sort/2
@cnindex dgraph_top_sort/2
Unify @var{Vertices} with the topological sort of graph @var{Graph}.

@item dgraph_top_sort(+@var{Graph}, -@var{Vertices}, ?@var{Vertices0})
@findex  dgraph_top_sort/3
@snindex dgraph_top_sort/3
@cnindex dgraph_top_sort/3
Unify the difference list @var{Vertices}-@var{Vertices0} with the
topological sort of graph @var{Graph}.

@item dgraph_min_path(+@var{V1}, +@var{V1}, +@var{Graph}, -@var{Path}, ?@var{Costt})
@findex  dgraph_min_path/5
@snindex dgraph_min_path/5
@cnindex dgraph_min_path/5
Unify the list @var{Path} with the minimal cost path between nodes
@var{N1} and @var{N2} in graph @var{Graph}. Path @var{Path} has cost
@var{Cost}.

@item dgraph_max_path(+@var{V1}, +@var{V1}, +@var{Graph}, -@var{Path}, ?@var{Costt})
@findex  dgraph_max_path/5
@snindex dgraph_max_path/5
@cnindex dgraph_max_path/5
Unify the list @var{Path} with the maximal cost path between nodes
@var{N1} and @var{N2} in graph @var{Graph}. Path @var{Path} has cost
@var{Cost}.

@item dgraph_min_paths(+@var{V1}, +@var{Graph}, -@var{Paths})
@findex  dgraph_min_paths/3
@snindex dgraph_min_paths/3
@cnindex dgraph_min_paths/3
Unify the list @var{Paths} with the minimal cost paths from node
@var{N1} to the nodes in graph @var{Graph}.

@item dgraph_isomorphic(+@var{Vs}, +@var{NewVs}, +@var{G0}, -@var{GF})
@findex  dgraph_isomorphic/4
@snindex dgraph_isomorphic/4
@cnindex dgraph_isomorphic/4
Unify the list @var{GF} with the graph isomorphic to @var{G0} where 
vertices in @var{Vs} map to vertices in @var{NewVs}.

@item dgraph_path(+@var{Vertex}, +@var{Graph}, ?@var{Path})
@findex  dgraph_path/3
@snindex dgraph_path/3
@cnindex dgraph_path/3
The path @var{Path} is a path starting at vertex @var{Vertex} in graph
@var{Graph}.

@item dgraph_path(+@var{Vertex}, +@var{Vertex1}, +@var{Graph}, ?@var{Path})
@findex  dgraph_path/4
@snindex dgraph_path/4
@cnindex dgraph_path/4
The path @var{Path} is a path starting at vertex @var{Vertex} in graph
@var{Graph} and ending at path @var{Vertex2}.

@item dgraph_reachable(+@var{Vertex}, +@var{Graph}, ?@var{Edges})
@findex  dgraph_reachable/3
@snindex dgraph_reachable/3
@cnindex dgraph_reachable/3
The path @var{Path} is a path starting at vertex @var{Vertex} in graph
@var{Graph}.

@item dgraph_leaves(+@var{Graph}, ?@var{Vertices})
@findex  dgraph_leaves/2
@snindex dgraph_leaves/2
@cnindex dgraph_leaves/2
The vertices @var{Vertices} have no outgoing edge in graph
@var{Graph}.

@end table

@node UnDGraphs, DBUsage , DGraphs, Library
@section Undirected Graphs
@cindex undirected graphs

The following graph manipulation routines use the red-black tree graph
library to implement undirected graphs. Mostly, this is done by having
two directed edges per undirected edge.

@table @code

@item undgraph_new(+@var{Graph})
@findex  undgraph_new/1
@snindex undgraph_new/1
@cnindex undgraph_new/1
Create a new directed graph. This operation must be performed before
trying to use the graph.

@item undgraph_vertices(+@var{Graph}, -@var{Vertices})
@findex  undgraph_vertices/2
@snindex undgraph_vertices/2
@cnindex undgraph_vertices/2
Unify @var{Vertices} with all vertices appearing in graph
@var{Graph}.

@item undgraph_edge(+@var{N1}, +@var{N2}, +@var{Graph})
@findex  undgraph_edge/2
@snindex undgraph_edge/2
@cnindex undgraph_edge/2
Edge @var{N1}-@var{N2} is an edge in undirected graph @var{Graph}.

@item undgraph_edges(+@var{Graph}, -@var{Edges})
@findex  undgraph_edges/2
@snindex undgraph_edges/2
@cnindex undgraph_edges/2
Unify @var{Edges} with all edges appearing in graph
@var{Graph}.

@item undgraph_add_vertices(+@var{Graph}, +@var{Vertices}, -@var{NewGraph})
@findex  undgraph_add_vertices/3
@snindex undgraph_add_vertices/3
@cnindex undgraph_add_vertices/3
Unify @var{NewGraph} with a new graph obtained by adding the list of
vertices @var{Vertices} to the graph @var{Graph}.

@item undgraph_del_vertices(+@var{Graph}, +@var{Vertices}, -@var{NewGraph})
@findex  undgraph_del_vertices/3
@syindex undgraph_del_vertices/3
@cnindex undgraph_del_vertices/3
Unify @var{NewGraph} with a new graph obtained by deleting the list of
vertices @var{Vertices} and all the edges that start from or go to a
vertex in @var{Vertices} to the graph @var{Graph}.

@item undgraph_add_edges(+@var{Graph}, +@var{Edges}, -@var{NewGraph})
@findex  undgraph_add_edges/3
@snindex undgraph_add_edges/3
@cnindex undgraph_add_edges/3
Unify @var{NewGraph} with a new graph obtained by adding the list of
edges @var{Edges} to the graph @var{Graph}.

@item undgraph_del_edges(+@var{Graph}, +@var{Edges}, -@var{NewGraph})
@findex  undgraph_del_edges/3
@snindex undgraph_del_edges/3
@cnindex undgraph_del_edges/3
Unify @var{NewGraph} with a new graph obtained by removing the list of
edges @var{Edges} from the graph @var{Graph}. Notice that no vertices
are deleted.

@item undgraph_neighbors(+@var{Vertex}, +@var{Graph}, -@var{Vertices})
@findex  undgraph_neighbors/3
@snindex undgraph_neighbors/3
@cnindex undgraph_neighbors/3
Unify @var{Vertices} with the list of neighbors of vertex @var{Vertex}
in @var{Graph}. If the vertice is not in the graph fail.

@item undgraph_neighbours(+@var{Vertex}, +@var{Graph}, -@var{Vertices})
@findex  undgraph_neighbours/3
@snindex undgraph_neighbours/3
@cnindex undgraph_neighbours/3
Unify @var{Vertices} with the list of neighbours of vertex @var{Vertex}
in @var{Graph}.

@item undgraph_complement(+@var{Graph}, -@var{NewGraph})
@findex  undgraph_complement/2
@snindex undgraph_complement/2
@cnindex undgraph_complement/2
Unify @var{NewGraph} with the graph complementary to @var{Graph}.

@item dgraph_to_undgraph( +@var{DGraph}, -@var{UndGraph})
@findex  dgraph_to_undgraph/2
@snindex dgraph_to_undgraph/2
@cnindex dgraph_to_undgraph/2
Unify @var{UndGraph} with the undirected graph obtained from the
directed graph @var{DGraph}.

@end table

@node DBUsage, Lambda, UnDGraphs, Library
@section Memory Usage in Prolog Data-Base
@cindex DBUsage

This library provides a set of utilities for studying memory usage in YAP.
The following routines are available once included with the
@code{use_module(library(dbusage))} command.

@table @code
@item db_usage
@findex db_usage/0
@snindex db_usage/0
@cnindex db_usage/0
Give general overview of data-base usage in the system.

@item db_static
@findex db_static/0
@snindex db_static/0
@cnindex db_static/0
List memory usage for every static predicate.

@item db_static(+@var{Threshold})
@findex db_static/1
@snindex db_static/1
@cnindex db_static/1
List memory usage for every static predicate. Predicate must use more
than @var{Threshold} bytes.

@item db_dynamic
@findex db_dynamic/0
@snindex db_dynamic/0
@cnindex db_dynamic/0
List memory usage for every dynamic predicate.

@item db_dynamic(+@var{Threshold})
@findex db_dynamic/1
@snindex db_dynamic/1
@cnindex db_dynamic/1
List memory usage for every dynamic predicate. Predicate must use more
than @var{Threshold} bytes.

@end table

@node Lambda, LAM, DBUsage, Library
@section Lambda Expressions
@cindex Lambda Expressions


This library, designed and implemented by Ulrich Neumerkel, provides
lambda expressions to simplify higher order programming based on @code{call/N}.

Lambda expressions are represented by ordinary Prolog terms.  There are
two kinds of lambda expressions:

@pl_example
    Free+\X1^X2^ ..^XN^Goal

         \X1^X2^ ..^XN^Goal
@end pl_example

The second is a shorthand for@code{ t+\X1^X2^..^XN^Goal}, where @code{Xi} are the parameters.

@var{Goal} is a goal or continuation (Syntax note: @var{Operators} within @var{Goal}
require parentheses due to the low precedence of the @code{^} operator).

Free contains variables that are valid outside the scope of the lambda
expression. They are thus free variables within.

All other variables of @var{Goal} are considered local variables. They must
not appear outside the lambda expression. This restriction is
currently not checked. Violations may lead to unexpected bindings.

In the following example the parentheses around @code{X>3} are necessary.

@pl_example
?- use_module(library(lambda)).
?- use_module(library(apply)).

?- maplist(\X^(X>3),[4,5,9]).
true.
@end pl_example

In the following @var{X} is a variable that is shared by both instances
of the lambda expression. The second query illustrates the cooperation
of continuations and lambdas. The lambda expression is in this case a
continuation expecting a further argument.

@pl_example
?- Xs = [A,B], maplist(X+\Y^dif(X,Y), Xs).
Xs = [A, B],
dif(X, A),
dif(X, B).

?- Xs = [A,B], maplist(X+\dif(X), Xs).
Xs = [A, B],
dif(X, A),
dif(X, B).

@end pl_example

The following queries are all equivalent. To see this, use
the fact @code{f(x,y)}.

@pl_example
?- call(f,A1,A2).
?- call(\X^f(X),A1,A2).
?- call(\X^Y^f(X,Y), A1,A2).                                                                                                            
?- call(\X^(X+\Y^f(X,Y)), A1,A2).
?- call(call(f, A1),A2).
?- call(f(A1),A2).
?- f(A1,A2).
A1 = x,
A2 = y.
@end pl_example

Further discussions
at Ulrich Neumerker's page in @url{http://www.complang.tuwien.ac.at/ulrich/Prolog-inedit/ISO-Hiord}.


@node LAM, BDDs, Lambda, Library
@section LAM
@cindex lam

This library provides a set of utilities for interfacing with LAM MPI.
The following routines are available once included with the
@code{use_module(library(lam_mpi))} command. The yap should be
invoked using the LAM mpiexec or mpirun commands (see LAM manual for
more details).

@table @code
@item mpi_init
@findex mpi_init/0
@snindex mpi_init/0
@cnindex mpi_init/0
      Sets up the mpi environment. This predicate should be called before any other MPI predicate.

@item mpi_finalize
@findex mpi_finalize/0
@snindex mpi_finalize/0
@cnindex mpi_finalize/0
      Terminates the MPI execution environment. Every process must call this predicate before  exiting.

@item mpi_comm_size(-@var{Size})
@findex mpi_comm_size/1
@snindex mpi_comm_size/1
@cnindex mpi_comm_size/1
      Unifies @var{Size} with the number of processes in the MPI environment.


@item mpi_comm_rank(-@var{Rank})
@findex mpi_comm_rank/1
@snindex mpi_comm_rank/1
@cnindex mpi_comm_rank/1
      Unifies @var{Rank} with the rank of the current process in the MPI environment.

@item mpi_version(-@var{Major},-@var{Minor})
@findex mpi_version/2
@snindex mpi_version/2
@cnindex mpi_version/2
      Unifies @var{Major} and @var{Minor} with, respectively, the major and minor version of the MPI.


@item mpi_send(+@var{Data},+@var{Dest},+@var{Tag})
@findex mpi_send/3
@snindex mpi_send/3
@cnindex mpi_send/3

Blocking communication predicate. The message in @var{Data}, with tag
@var{Tag}, is sent immediately to the processor with rank @var{Dest}.
The predicate succeeds after the message being sent.



@item mpi_isend(+@var{Data},+@var{Dest},+@var{Tag},-@var{Handle})
@findex mpi_isend/4
@snindex mpi_isend/4
@cnindex mpi_isend/4

Non blocking communication predicate. The message in @var{Data}, with
tag @var{Tag}, is sent whenever possible to the processor with rank
@var{Dest}. An @var{Handle} to the message is returned to be used to
check for the status of the message, using the @code{mpi_wait} or
@code{mpi_test} predicates. Until @code{mpi_wait} is called, the
memory allocated for the buffer containing the message is not
released.

@item mpi_recv(?@var{Source},?@var{Tag},-@var{Data})
@findex mpi_recv/3
@snindex mpi_recv/3
@cnindex mpi_recv/3

Blocking communication predicate. The predicate blocks until a message
is received from processor with rank @var{Source} and tag @var{Tag}.
The message is placed in @var{Data}.

@item mpi_irecv(?@var{Source},?@var{Tag},-@var{Handle})
@findex mpi_irecv/3
@snindex mpi_irecv/3
@cnindex mpi_irecv/3

Non-blocking communication predicate. The predicate returns an
@var{Handle} for a message that will be received from processor with
rank @var{Source} and tag @var{Tag}. Note that the predicate succeeds
immediately, even if no message has been received. The predicate
@code{mpi_wait_recv} should be used to obtain the data associated to
the handle.

@item mpi_wait_recv(?@var{Handle},-@var{Status},-@var{Data})
@findex mpi_wait_recv/3
@snindex mpi_wait_recv/3
@cnindex mpi_wait_recv/3

Completes a non-blocking receive operation. The predicate blocks until
a message associated with handle @var{Hanlde} is buffered. The
predicate succeeds unifying @var{Status} with the status of the
message and @var{Data} with the message itself. 

@item mpi_test_recv(?@var{Handle},-@var{Status},-@var{Data})
@findex mpi_test_recv/3
@snindex mpi_test_recv/3
@cnindex mpi_test_recv/3

Provides information regarding a handle. If the message associated
with handle @var{Hanlde} is buffered then the predicate succeeds
unifying @var{Status} with the status of the message and @var{Data}
with the message itself. Otherwise, the predicate fails.


@item mpi_wait(?@var{Handle},-@var{Status})
@findex mpi_wait/2
@snindex mpi_wait/2
@cnindex mpi_wait/2

Completes a non-blocking operation. If the operation was a
@code{mpi_send}, the predicate blocks until the message is buffered
or sent by the runtime system. At this point the send buffer is
released. If the operation was a @code{mpi_recv}, it waits until the
message is copied to the receive buffer. @var{Status} is unified with
the status of the message.

@item mpi_test(?@var{Handle},-@var{Status})
@findex mpi_test/2
@snindex mpi_test/2
@cnindex mpi_test/2

Provides information regarding the handle @var{Handle}, ie., if a
communication operation has been completed.  If the operation
associate with @var{Hanlde} has been completed the predicate succeeds
with the completion status in @var{Status}, otherwise it fails.

@item mpi_barrier
@findex mpi_barrier/0
@snindex mpi_barrier/0
@cnindex mpi_barrier/0

Collective communication predicate.  Performs a barrier
synchronization among all processes. Note that a collective
communication means that all processes call the same predicate. To be
able to use a regular @code{mpi_recv} to receive the messages, one
should use @code{mpi_bcast2}.


@item mpi_bcast2(+@var{Root}, ?@var{Data})
@findex mpi_bcast/2
@snindex mpi_bcast/2
@cnindex mpi_bcast/2

Broadcasts the message @var{Data} from the process with rank @var{Root}
to all other processes.

@item mpi_bcast3(+@var{Root}, +@var{Data}, +@var{Tag})
@findex mpi_bcast/3
@snindex mpi_bcast/3
@cnindex mpi_bcast/3

Broadcasts the message @var{Data} with tag @var{Tag} from the process with rank @var{Root}
to all other processes.

@item mpi_ibcast(+@var{Root}, +@var{Data}, +@var{Tag})
@findex mpi_ibcast/3
@snindex mpi_ibcast/3
@cnindex mpi_ibcast/3

Non-blocking operation. Broadcasts the message @var{Data} with tag @var{Tag}
from the process with rank @var{Root} to all other processes.

@item mpi_default_buffer_size(-@var{OldBufferSize}, ?@var{NewBufferSize})
@findex mpi_default_buffer_size/1
@snindex mpi_default_buffer_size/1
@cnindex mpi_default_buffer_size/1

The @var{OldBufferSize} argument unifies with the current size of the
MPI communication buffer size and sets the communication buffer size
@var{NewBufferSize}. The buffer is used for assynchronous waiting and
for broadcast receivers. Notice that buffer is local at each MPI
process.


@item mpi_msg_size(@var{Msg}, -@var{MsgSize})
@findex mpi_msg_size/2
@snindex mpi_msg_size/2
@cnindex mpi_msg_size/2
Unify @var{MsgSize} with the number of bytes YAP would need to send the
message @var{Msg}.

@item mpi_gc
@findex mpi_gc/0
@snindex mpi_gc/0
@cnindex mpi_gc/0

Attempts to perform garbage collection with all the open handles
associated with send and non-blocking broadcasts. For each handle it
tests it and the message has been delivered the handle and the buffer
are released.

@end table

@node BDDs, Block Diagram, LAM, Library
@section Binary Decision Diagrams and Friends
@cindex BDDs

This library provides an interface to the BDD package CUDD. It requires
CUDD compiled as a dynamic library. In Linux this is available out of
box in Fedora, but can easily be ported to other Linux
distributions. CUDD is available in the ports OSX package, and in
cygwin. To use it, call @code{:-use_module(library(bdd))}.

The following predicates construct a BDD:
@table @code
@item bbd_new(?@var{Exp}, -@var{BddHandle})
@findex bdd_new/2
create a new BDD from the logical expression @var{Exp}. The expression
may include:
@table @code
@item  Logical Variables:
a leaf-node can be a logical variable.
@item Constants 0 and 1
a leaf-node can also be one of these two constants.
@item or(@var{X}, @var{Y}), @var{X} \/ @var{Y}, @var{X} + @var{Y}
disjunction
@item and(@var{X}, @var{Y}), @var{X} /\ @var{Y}, @var{X} * @var{Y}
conjunction
@item nand(@var{X}, @var{Y})
negated conjunction@
@item nor(@var{X}, @var{Y})
negated disjunction
@item xor(@var{X}, @var{Y})
exclusive or
@item not(@var{X}), -@var{X}
negation
@end table

@item bdd_from_list(?@var{List}, -@var{BddHandle})
@findex bdd_from_list/2
Convert a @var{List} of logical expressions of the form above into a BDD
accessible through @var{BddHandle}.

@item mtbdd_new(?@var{Exp}, -@var{BddHandle})
@findex mtbdd_new/2
create a new algebraic decision diagram (ADD) from the logical
expression @var{Exp}. The expression may include:
@table @code
@item  Logical Variables:
a leaf-node can be a logical variable, or @emph{parameter}.
@item Number
a leaf-node can also be any number
@item  @var{X} * @var{Y}
product
@item @var{X} + @var{Y}
sum
@item @var{X} - @var{Y}
subtraction
@item or(@var{X}, @var{Y}), @var{X} \/ @var{Y}
logical or
@end table

@item bdd_tree(+@var{BDDHandle}, @var{Term})
@findex bdd_tree/2
Convert the BDD or ADD represented by @var{BDDHandle} to a Prolog term
of the form @code{bdd(@var{Dir}, @var{Nodes}, @var{Vars})} or @code{mtbdd(@var{Nodes}, @var{Vars})}, respectively. The arguments are:
@itemize
@item
 @var{Dir} direction of the BDD, usually 1
@item
 @var{Nodes} list of nodes in the BDD or ADD. 

In a BDD nodes may be @t{pp} (both terminals are positive) or @t{pn}
 (right-hand-side is negative), and have four arguments: a logical
 variable that will be bound to the value of the node, the logical
 variable corresponding to the node, a logical variable, a 0 or a 1 with
 the value of the left-hand side, and a logical variable, a 0 or a 1
 with the right-hand side.

@item 
@var{Vars} are the free variables in the original BDD, or the parameters of the BDD/ADD.
@end itemize
As an example, the BDD for the expression @code{X+(Y+X)*(-Z)} becomes:
@example
bdd(1,[pn(N2,X,1,N1),pp(N1,Y,N0,1),pn(N0,Z,1,1)],vs(X,Y,Z))
@end example

@item bdd_eval(+@var{BDDHandle}, @var{Val})
@findex bdd_eval/2
Unify @var{Val} with the value of the logical expression compiled in
@var{BDDHandle} given an assignment to its  variables.
@example
bdd_new(X+(Y+X)*(-Z), BDD), 
[X,Y,Z] = [0,0,0], 
bdd_eval(BDD, V), 
writeln(V).
@end example
would write 0 in the standard output stream.

The  Prolog code equivalent to @t{bdd_eval/2} is:
@example
    Tree = bdd(1, T, _Vs),
    reverse(T, RT),
    foldl(eval_bdd, RT, _, V).

eval_bdd(pp(P,X,L,R), _, P) :-
    P is ( X/\L ) \/ ( (1-X) /\ R ).
eval_bdd(pn(P,X,L,R), _, P) :-
    P is ( X/\L ) \/ ( (1-X) /\ (1-R) ).
@end example
First, the nodes are reversed to implement bottom-up evaluation. Then,
we use the @code{foldl} list manipulation predicate to walk every node,
computing the disjunction of the two cases and binding the output
variable. The top node gives the full expression value. Notice that
@code{(1-@var{X})}  implements negation.

@item bdd_size(+@var{BDDHandle}, -@var{Size})
@findex bdd_size/2
Unify @var{Size} with the number of nodes in @var{BDDHandle}.

@item bdd_print(+@var{BDDHandle}, +@var{File})
@findex bdd_print/2
Output bdd @var{BDDHandle} as a dot file to @var{File}.

@item bdd_to_probability_sum_product(+@var{BDDHandle}, -@var{Prob})
@findex bdd_to_probability_sum_product/2
Each node in a BDD is given a probability @var{Pi}. The total
probability of a corresponding sum-product network is @var{Prob}.

@item bdd_to_probability_sum_product(+@var{BDDHandle}, -@var{Probs}, -@var{Prob})
@findex bdd_to_probability_sum_product/3
Each node in a BDD is given a probability @var{Pi}. The total
probability of a corresponding sum-product network is @var{Prob}, and
the probabilities of the inner nodes are @var{Probs}.

In Prolog, this predicate would correspond to computing the value of a
BDD. The input variables will be bound to probabilities, eg
@code{[@var{X},@var{Y},@var{Z}] = [0.3.0.7,0.1]}, and the previous
@code{eval_bdd} would operate over real numbers:

@example
    Tree = bdd(1, T, _Vs),
    reverse(T, RT),
    foldl(eval_prob, RT, _, V).

eval_prob(pp(P,X,L,R), _, P) :-
    P is  X * L +  (1-X) * R.
eval_prob(pn(P,X,L,R), _, P) :-
    P is  X * L + (1-X) * (1-R).
@end example
@item bdd_close(@var{BDDHandle})
@findex bdd_close/1
close the BDD and release any resources it holds.

@end table

@node Block Diagram, , BDDs, Library
@section Block Diagram
@cindex Block Diagram

This library provides a way of visualizing a prolog program using
modules with blocks.  To use it use:
@code{:-use_module(library(block_diagram))}.
@table @code
@item make_diagram(+inputfilename, +ouputfilename)
@findex make_diagram/2
@snindex make_diagram/2
@cnindex make_diagram/2

This will crawl the files following the use_module, ensure_loaded directives withing the inputfilename.
The result will be a file in dot format.
You can make a pdf at the shell by asking @code{dot -Tpdf filename > output.pdf}.

@item make_diagram(+inputfilename, +ouputfilename, +predicate, +depth, +extension)
@findex make_diagram/5
@snindex make_diagram/5
@cnindex make_diagram/5

The same as @code{make_diagram/2} but you can define how many of the imported/exporeted predicates will be shown with predicate, and how deep the crawler is allowed to go with depth. The extension is used if the file use module directives do not include a file extension.

@end table


@node SWI-Prolog, SWI-Prolog Global Variables, Library, Top
@cindex SWI-Prolog

@menu SWI-Prolog Emulation
Subnodes of SWI-Prolog
* Invoking Predicates on all Members of a List :: maplist and friends
* Forall :: forall built-in
@end menu

@include swi.tex

@node Extensions,Debugging,SWI-Prolog Global Variables,Top 
@chapter Extensions to Prolog

@menu
* Rational Trees:: Working with Rational Trees
* Co-routining:: Changing the Execution of Goals
* Attributed Variables:: Using attributed Variables
* CLPR:: The CLP(R) System
* Logtalk:: The Logtalk Object-Oriented system
* MYDDAS:: The MYDDAS Database Interface package
* Threads:: Thread Library
* Parallelism:: Running in Or-Parallel
* Tabling:: Storing Intermediate Solutions of programs 
* Low Level Profiling:: Profiling Abstract Machine Instructions
* Low Level Tracing:: Tracing at Abstract Machine Level
@end menu

YAP includes a number of extensions over the original Prolog
language. Next, we discuss support to the most important ones.

@node Rational Trees, Co-routining, , Extensions
@section Rational Trees

Prolog unification is not a complete implementation. For efficiency
considerations, Prolog systems do not perform occur checks while
unifying terms. As an example, @code{X = a(X)} will not fail but instead
will create an infinite term of the form @code{a(a(a(a(a(...)))))}, or
@emph{rational tree}.

Rational trees are now supported by default in YAP. In previous
versions, this was not the default and these terms could easily lead
to infinite computation. For example, @code{X = a(X), X = X} would
enter an infinite loop.

The @code{RATIONAL_TREES} flag improves support for these
terms. Internal primitives are now aware that these terms can exist, and
will not enter infinite loops. Hence, the previous unification will
succeed. Another example, @code{X = a(X), ground(X)} will succeed
instead of looping. Other affected built-ins include the term comparison
primitives, @code{numbervars/3}, @code{copy_term/2}, and the internal
data base routines. The support does not extend to Input/Output routines
or to @code{assert/1} YAP does not allow directly reading
rational trees, and you need to use @code{write_depth/2} to avoid
entering an infinite cycle when trying to write an infinite term.

@node Co-routining, Attributed Variables, Rational Trees, Extensions
@section Co-routining

Prolog uses a simple left-to-right flow of control. It is sometimes
convenient to change this control so that goals will only be executed
when conditions are fulfilled. This may result in a more "data-driven"
execution, or may be necessary to correctly implement extensions such as
negation by default.

The @code{COROUTINING} flag enables this option. Note that the support for
coroutining  will in general slow down execution.

The following declaration is supported:

@table @code
@item block/1
The argument to @code{block/1} is a condition on a goal or a conjunction
of conditions, with each element separated by commas. Each condition is
of the form @code{predname(@var{C1},...,@var{CN})}, where @var{N} is the
arity of the goal, and each @var{CI} is of the form @code{-}, if the
argument must suspend until the first such variable is bound, or
@code{?}, otherwise.

@item wait/1
The argument to @code{wait/1} is a predicate descriptor or a conjunction
of these predicates. These predicates will suspend until their first
argument is bound.
@end table

The following primitives are supported:

@table @code
@item dif(@var{X},@var{Y})
@findex dif/2
@syindex dif/2
@cnindex dif/2
Succeed if the two arguments do not unify. A call to @code{dif/2} will
suspend if unification may still succeed or fail, and will fail if they
always unify.

@item freeze(?@var{X},:@var{G})
@findex freeze/2
@syindex freeze/2
@cnindex freeze/2
Delay execution of goal @var{G} until the variable @var{X} is bound.

@item frozen(@var{X},@var{G})
@findex frozen/2
@syindex frozen/2
@cnindex frozen/2
Unify @var{G} with a conjunction of goals suspended on variable @var{X},
or @code{true} if no goal has suspended.

@item when(+@var{C},:@var{G})
@findex when/2
@syindex when/2
@cnindex when/2
Delay execution of goal @var{G} until the conditions @var{C} are
satisfied. The conditions are of the following form:

@table @code
@item @var{C1},@var{C2}
Delay until both conditions @var{C1} and @var{C2} are satisfied.
@item @var{C1};@var{C2}
Delay until either condition @var{C1} or condition @var{C2} is satisfied.
@item ?=(@var{V1},@var{C2})
Delay until terms @var{V1} and @var{V1} have been unified.
@item nonvar(@var{V})
Delay until variable @var{V} is bound.
@item ground(@var{V})
Delay until variable @var{V} is ground.
@end table

Note that @code{when/2} will fail if the conditions fail.

@item call_residue(:@var{G},@var{L})
@findex call_residue/2
@syindex call_residue/2
@cnindex call_residue/2

Call goal @var{G}. If subgoals of @var{G} are still blocked, return
a list containing these goals and the variables they are blocked in. The
goals are then considered as unblocked. The next example shows a case
where @code{dif/2} suspends twice, once outside @code{call_residue/2},
and the other inside:

@example
?- dif(X,Y),
       call_residue((dif(X,Y),(X = f(Z) ; Y = f(Z))), L).

X = f(Z),
L = [[Y]-dif(f(Z),Y)],
dif(f(Z),Y) ? ;

Y = f(Z),
L = [[X]-dif(X,f(Z))],
dif(X,f(Z)) ? ;

no
@end example
The system only reports one invocation of @code{dif/2} as having
suspended. 

@item call_residue_vars(:@var{G},@var{L})
@findex call_residue_vars/2
@syindex call_residue_vars/2
@cnindex call_residue_vars/2

Call goal @var{G} and unify @var{L} with a list of all constrained variables created @emph{during} execution of @var{G}:

@example
  ?- dif(X,Z), call_residue_vars(dif(X,Y),L).
dif(X,Z), call_residue_vars(dif(X,Y),L).
L = [Y],
dif(X,Z),
dif(X,Y) ? ;

no
@end example

@end table

@node Attributed Variables, CLPR, Co-routining, Extensions
@section Attributed Variables
@cindex attributed variables

@menu
* New Style Attribute Declarations:: New Style code
* Old Style Attribute Declarations:: Old Style code (deprecated)
@end menu

YAP supports attributed variables, originally developed at OFAI by
Christian Holzbaur. Attributes are a means of declaring that an
arbitrary term is a property for a variable. These properties can be
updated during forward execution. Moreover, the unification algorithm is
aware of attributed variables and will call user defined handlers when
trying to unify these variables.

Attributed variables provide an elegant abstraction over which one can
extend Prolog systems. Their main application so far has been in
implementing constraint handlers, such as Holzbaur's CLPQR, Fruewirth
and Holzbaur's CHR, and CLP(BN). 

Different Prolog systems implement attributed variables in different
ways. Traditionally, YAP has used the interface designed by SICStus
Prolog. This interface is still
available in the @t{atts} library, but from YAP-6.0.3 we recommend using
the hProlog, SWI style interface. The main reason to do so is that 
most packages included in YAP that use attributed variables, such as CHR, CLP(FD), and CLP(QR),
rely on the SWI-Prolog interface.


@node New Style Attribute Declarations, Old Style Attribute Declarations, , Attributed Variables
@section hProlog and SWI-Prolog style Attribute Declarations

The following documentation is taken from the SWI-Prolog manual.

Binding an attributed variable schedules a goal to be executed at the
first possible opportunity. In the current implementation the hooks are
executed immediately after a successful unification of the clause-head
or successful completion of a foreign language (built-in) predicate. Each
attribute is associated to a module and the hook @code{attr_unify_hook/2} is
executed in this module.  The example below realises a very simple and
incomplete finite domain reasoner.

@example
:- module(domain,
      [ domain/2            % Var, ?Domain
      ]).
:- use_module(library(ordsets)).

domain(X, Dom) :-
    var(Dom), !,
    get_attr(X, domain, Dom).
domain(X, List) :-
    list_to_ord_set(List, Domain),
    put_attr(Y, domain, Domain),
    X = Y.

%    An attributed variable with attribute value Domain has been
%    assigned the value Y

attr_unify_hook(Domain, Y) :-
    (   get_attr(Y, domain, Dom2)
    ->  ord_intersection(Domain, Dom2, NewDomain),
        (   NewDomain == []
        ->    fail
        ;    NewDomain = [Value]
        ->    Y = Value
        ;    put_attr(Y, domain, NewDomain)
        )
    ;   var(Y)
    ->  put_attr( Y, domain, Domain )
    ;   ord_memberchk(Y, Domain)
    ).

%    Translate attributes from this module to residual goals

attribute_goals(X) -->
    @{ get_attr(X, domain, List) @},
    [domain(X, List)].
@end example


Before explaining the code we give some example queries:

@texinfo
@multitable @columnfractions .70 .30
            @item @code{?- domain(X, [a,b]), X = c}
@tab @code{fail}
@item @code{domain(X, [a,b]), domain(X, [a,c]).}
           @tab @code{X=a}
    @item @code{domain(X, [a,b,c]), domain(X, [a,c]).}
     @tab @code{domain(X, [a,c]).}
    @end multitable
@end texinfo


The predicate @code{domain/2} fetches (first clause) or assigns
(second clause) the variable a @emph{domain}, a set of values it can
be unified with.  In the second clause first associates the domain
with a fresh variable and then unifies X to this variable to deal
with the possibility that X already has a domain. The
predicate @code{attr_unify_hook/2} is a hook called after a variable with
a domain is assigned a value.  In the simple case where the variable
is bound to a concrete value we simply check whether this value is in
the domain. Otherwise we take the intersection of the domains and either
fail if the intersection is empty (first example), simply assign the
value if there is only one value in the intersection (second example) or
assign the intersection as the new domain of the variable (third
example). The nonterminal @code{attribute_goals/3} is used to translate
remaining attributes to user-readable goals that, when executed, reinstate
these attributes.

@table @code

@item put_attr(+@var{Var},+@var{Module},+@var{Value})
@findex put_attr/3
@snindex put_attr/3
@cnindex put_attr/3

If @var{Var} is a variable or attributed variable, set the value for the
attribute named @var{Module} to @var{Value}. If an attribute with this
name is already associated with @var{Var}, the old value is replaced.
Backtracking will restore the old value (i.e., an attribute is a mutable
term. See also @code{setarg/3}). This predicate raises a representation error if
@var{Var} is not a variable and a type error if @var{Module} is not an atom.

@item get_attr(+@var{Var},+@var{Module},-@var{Value})
@findex get_attr/3
@snindex get_attr/3
@cnindex get_attr/3

Request the current @var{value} for the attribute named @var{Module}.  If
@var{Var} is not an attributed variable or the named attribute is not
associated to @var{Var} this predicate fails silently.  If @var{Module}
is not an atom, a type error is raised.

@item del_attr(+@var{Var},+@var{Module})
@findex del_attr/2
@snindex del_attr/2
@cnindex del_attr/2

Delete the named attribute.  If @var{Var} loses its last attribute it
is transformed back into a traditional Prolog variable.  If @var{Module}
is not an atom, a type error is raised. In all other cases this
predicate succeeds regardless whether or not the named attribute is
present.

@item attr_unify_hook(+@var{AttValue},+@var{VarValue})
@findex attr_unify_hook/2
@snindex attr_unify_hook/2
@cnindex attr_unify_hook/2

Hook that must be defined in the module an attributed variable refers
to. Is is called @emph{after} the attributed variable has been
unified with a non-var term, possibly another attributed variable.
@var{AttValue} is the attribute that was associated to the variable
in this module and @var{VarValue} is the new value of the variable.
Normally this predicate fails to veto binding the variable to
@var{VarValue}, forcing backtracking to undo the binding.  If
@var{VarValue} is another attributed variable the hook often combines
the two attribute and associates the combined attribute with
@var{VarValue} using @code{put_attr/3}.

@item attr_portray_hook(+@var{AttValue},+@var{Var})
@findex attr_portray_hook/2
@snindex attr_portray_hook/2
@cnindex attr_portray_hook/2

Called by @code{write_term/2} and friends for each attribute if the option
@code{attributes(portray)} is in effect.  If the hook succeeds the
attribute is considered printed.  Otherwise  @code{Module = ...} is
printed to indicate the existence of a variable.

@item attribute_goals(+@var{Var},-@var{Gs},+@var{GsRest})
@findex attribute_goals/2
@snindex attribute_goals/2
@cnindex attribute_goals/2

This nonterminal, if it is defined in a module, is used by @var{copy_term/3}
to project attributes of that module to residual goals. It is also
used by the toplevel to obtain residual goals after executing a query.
@end table

Normal user code should deal with @code{put_attr/3}, @code{get_attr/3} and @code{del_attr/2}.
The routines in this section fetch or set the entire attribute list of a
variables. Use of these predicates is anticipated to be restricted to
printing and other special purpose operations.

@table @code

@item get_attrs(+@var{Var},-@var{Attributes})
@findex get_attrs/2
@snindex get_attrs/2
@cnindex get_attrs/2

Get all attributes of @var{Var}. @var{Attributes} is a term of the form
@code{att(@var{Module}, @var{Value}, @var{MoreAttributes})}, where @var{MoreAttributes} is
@code{[]} for the last attribute.

@item put_attrs(+@var{Var},+@var{Attributes})
@findex put_attrs/2
@snindex put_attrs/2
@cnindex put_attrs/2
Set all attributes of @var{Var}.  See @code{get_attrs/2} for a description of
@var{Attributes}.

@item del_attrs(+@var{Var})
@findex del_attrs/1
@snindex del_attrs/1
@cnindex del_attrs/1
If @var{Var} is an attributed variable, delete @emph{all} its
attributes.  In all other cases, this predicate succeeds without
side-effects.

@item term_attvars(+@var{Term},-@var{AttVars})
@findex term_attvars/2
@snindex term_attvars/2
@cnindex term_attvars/2
@var{AttVars} is a list of all attributed variables in @var{Term} and
its attributes. I.e., @code{term_attvars/2} works recursively through
attributes.  This predicate is Cycle-safe.

@item copy_term(?@var{TI},-@var{TF},-@var{Goals}) 
@findex copy_term/3
@syindex copy_term/3
@cnindex copy_term/3
Term @var{TF} is a variant of the original term @var{TI}, such that for
each variable @var{V} in the term @var{TI} there is a new variable @var{V'}
in term @var{TF} without any attributes attached.  Attributed
variables are thus converted to standard variables.  @var{Goals} is
unified with a list that represents the attributes.  The goal
@code{maplist(call,@var{Goals})} can be called to recreate the
attributes.

Before the actual copying, @code{copy_term/3} calls
@code{attribute_goals/1} in the module where the attribute is
defined.

@item copy_term_nat(?@var{TI},-@var{TF}) 
@findex copy_term_nat/2
@syindex copy_term_nat/2
@cnindex copy_term_nat/2
As @code{copy_term/2}.  Attributes however, are @emph{not} copied but replaced
by fresh variables.

@end table

@node Old Style Attribute Declarations, , New Style Attribute Declarations, Attributed Variables
@section SICStus Prolog style Attribute Declarations

@menu
* Attribute Declarations:: Declaring New Attributes
* Attribute Manipulation:: Setting and Reading Attributes
* Attributed Unification:: Tuning the Unification Algorithm
* Displaying Attributes:: Displaying Attributes in User-Readable Form
* Projecting Attributes:: Obtaining the Attributes of Interest
* Attribute Examples:: Two Simple Examples of how to use Attributes.
@end menu

Old style attribute declarations are activated through loading the library @t{atts} . The command
@example
| ?- use_module(library(atts)).
@end example
enables this form of use of attributed variables. The package provides the
following functionality:
@itemize @bullet
@item Each attribute must be declared first. Attributes are described by a functor
and are declared per module. Each Prolog module declares its own sets of
attributes. Different modules may have different functors with the same
module.
@item The built-in @code{put_atts/2} adds or deletes attributes to a
variable. The variable may be unbound or may be an attributed
variable. In the latter case, YAP discards previous values for the
attributes.
@item The built-in @code{get_atts/2} can be used to check the values of
an attribute associated with a variable.
@item The unification algorithm calls the user-defined predicate
@t{verify_attributes/3} before trying to bind an attributed
variable. Unification will resume after this call.
@item The user-defined predicate
@t{attribute_goal/2} converts from an attribute to a goal.
@item The user-defined predicate
@t{project_attributes/2} is used from a set of variables into a set of
constraints or goals. One application of @t{project_attributes/2} is in
the top-level, where it is used to output the set of
floundered constraints at the end of a query.
@end itemize

@node Attribute Declarations, Attribute Manipulation, , Old Style Attribute Declarations
@subsection Attribute Declarations

Attributes are compound terms associated with a variable. Each attribute
has a @emph{name} which is @emph{private} to the module in which the
attribute was defined. Variables may have at most one attribute with a
name. Attribute names are defined with the following declaration:

@cindex attribute declaration
@cindex declaration, attribute
@findex attribute/1 (declaration)

@example
:- attribute AttributeSpec, ..., AttributeSpec.
@end example

@noindent
where each @var{AttributeSpec} has the form (@var{Name}/@var{Arity}).
One single such declaration is allowed per module @var{Module}.

Although the YAP module system is predicate based, attributes are local
to modules. This is implemented by rewriting all calls to the
built-ins that manipulate attributes so that attribute names are
preprocessed depending on the module.  The @code{user:goal_expansion/3}
mechanism is used for this purpose.


@node Attribute Manipulation, Attributed Unification, Attribute Declarations, Old Style Attribute Declarations
@subsection Attribute Manipulation


The  attribute manipulation predicates always work as follows:
@enumerate
@item The first argument is the unbound variable associated with
attributes,
@item The second argument is a list of attributes. Each attribute will
be a Prolog term or a constant, prefixed with the @t{+} and @t{-} unary
operators. The prefix @t{+} may be dropped for convenience.
@end enumerate

The following three procedures are available to the user. Notice that
these built-ins are rewritten by the system into internal built-ins, and
that the rewriting process @emph{depends} on the module on which the
built-ins have been invoked.

@table @code
@item @var{Module}:get_atts(@var{-Var},@var{?ListOfAttributes})
@findex get_atts/2
@syindex get_atts/2
@cnindex get_atts/2
Unify the list @var{?ListOfAttributes} with the attributes for the unbound
variable @var{Var}. Each member of the list must be a bound term of the
form @code{+(@var{Attribute})}, @code{-(@var{Attribute})} (the @t{kbd}
prefix may be dropped). The meaning of @t{+} and @t{-} is:
@item +(@var{Attribute})
Unifies @var{Attribute} with a corresponding attribute associated with
@var{Var}, fails otherwise.

@item -(@var{Attribute})
Succeeds if a corresponding attribute is not associated with
@var{Var}. The arguments of @var{Attribute} are ignored.

@item @var{Module}:put_atts(@var{-Var},@var{?ListOfAttributes})
@findex put_atts/2
@syindex put_atts/2
@cnindex put_atts/2
Associate with or remove attributes from a variable @var{Var}. The
attributes are given in @var{?ListOfAttributes}, and the action depends
on how they are prefixed:
@item +(@var{Attribute})
Associate @var{Var} with @var{Attribute}. A previous value for the
attribute is simply replace (like with @code{set_mutable/2}).

@item -(@var{Attribute})
Remove the attribute with the same name. If no such attribute existed,
simply succeed.
@end table

@node Attributed Unification, Displaying Attributes, Attribute Manipulation, Old Style Attribute Declarations
@subsection Attributed Unification

The user-predicate predicate @code{verify_attributes/3} is called when
attempting to unify an attributed variable which might have attributes
in some @var{Module}.

@table @code
@item @var{Module}:verify_attributes(@var{-Var}, @var{+Value}, @var{-Goals})
@findex verify_attributes/3
@syindex verify_attributes/3
@cnindex verify_attributes/3

The predicate is called when trying to unify the attributed variable
@var{Var} with the Prolog term @var{Value}. Note that @var{Value} may be
itself an attributed variable, or may contain attributed variables.  The
goal @t{verify_attributes/3} is actually called before @var{Var} is
unified with @var{Value}.

It is up to the user to define which actions may be performed by
@t{verify_attributes/3} but the procedure is expected to return in
@var{Goals} a list of goals to be called @emph{after} @var{Var} is
unified with @var{Value}. If @t{verify_attributes/3} fails, the
unification will fail.

Notice that the @t{verify_attributes/3} may be called even if @var{Var}<
has no attributes in module @t{Module}. In this case the routine should
simply succeed with @var{Goals} unified with the empty list.

@item attvar(@var{-Var})
@findex attvar/1
@snindex attvar/1
@cnindex attvar/1
Succeed if @var{Var} is an attributed variable.
@end table



@node Displaying Attributes, Projecting Attributes,Attributed Unification, Old Style Attribute Declarations 
@subsection Displaying Attributes

Attributes are usually presented as goals. The following routines are
used by built-in predicates such as @code{call_residue/2} and by the
Prolog top-level to display attributes:

@table @code
@item @var{Module}:attribute_goal(@var{-Var}, @var{-Goal})
@findex attribute_goal/2
@syindex attribute_goal/2
@cnindex attribute_goal/2
User-defined procedure, called to convert the attributes in @var{Var} to
a @var{Goal}. Should fail when no interpretation is available.

@end table

@node Projecting Attributes, Attribute Examples, Displaying Attributes, Old Style Attribute Declarations
@subsection Projecting Attributes

Constraint solvers must be able to project a set of constraints to a set
of variables. This is useful when displaying the solution to a goal, but
may also be used to manipulate computations. The user-defined
@code{project_attributes/2} is responsible for implementing this
projection.


@table @code
@item @var{Module}:project_attributes(@var{+QueryVars}, @var{+AttrVars})
@findex project_attributes/2
@syindex project_attributes/2
@cnindex project_attributes/2
Given a list of variables @var{QueryVars} and list of attributed
variables @var{AttrVars}, project all attributes in @var{AttrVars} to
@var{QueryVars}. Although projection is constraint system dependent,
typically this will involve expressing all constraints in terms of
@var{QueryVars} and considering all remaining variables as existentially
quantified.
@end table

Projection interacts with @code{attribute_goal/2} at the Prolog top
level. When the query succeeds, the system first calls
@code{project_attributes/2}. The system then calls
@code{attribute_goal/2} to get a user-level representation of the
constraints. Typically, @code{attribute_goal/2} will convert from the
original constraints into a set of new constraints on the projection,
and these constraints are the ones that will have an
@code{attribute_goal/2} handler.

@node Attribute Examples, ,Projecting Attributes, Old Style Attribute Declarations
@subsection Attribute Examples

The following two examples example is taken from the SICStus Prolog manual. It
sketches the implementation of a simple finite domain ``solver''.  Note
that an industrial strength solver would have to provide a wider range
of functionality and that it quite likely would utilize a more efficient
representation for the domains proper.  The module exports a single
predicate @code{domain(@var{-Var},@var{?Domain})} which associates
@var{Domain} (a list of terms) with @var{Var}.  A variable can be
queried for its domain by leaving @var{Domain} unbound.

We do not present here a definition for @code{project_attributes/2}.
Projecting finite domain constraints happens to be difficult.


@example
:- module(domain, [domain/2]).

:- use_module(library(atts)).
:- use_module(library(ordsets), [
        ord_intersection/3,
        ord_intersect/2,
        list_to_ord_set/2
   ]).

:- attribute dom/1.

verify_attributes(Var, Other, Goals) :-
        get_atts(Var, dom(Da)), !,          % are we involved?
        (   var(Other) ->                   % must be attributed then
            (   get_atts(Other, dom(Db)) -> %   has a domain?
                ord_intersection(Da, Db, Dc),
                Dc = [El|Els],              % at least one element
                (   Els = [] ->             % exactly one element
                    Goals = [Other=El]      % implied binding
                ;   Goals = [],
                    put_atts(Other, dom(Dc))% rescue intersection
                )
            ;   Goals = [],
                put_atts(Other, dom(Da))    % rescue the domain
            )
        ;   Goals = [],
            ord_intersect([Other], Da)      % value in domain?
        ).
verify_attributes(_, _, []).                % unification triggered
                                            % because of attributes
                                            % in other modules

attribute_goal(Var, domain(Var,Dom)) :-     % interpretation as goal
        get_atts(Var, dom(Dom)).

domain(X, Dom) :-
        var(Dom), !,
        get_atts(X, dom(Dom)).
domain(X, List) :-
        list_to_ord_set(List, Set),
        Set = [El|Els],                     % at least one element
        (   Els = [] ->                     % exactly one element
            X = El                          % implied binding
        ;   put_atts(Fresh, dom(Set)),
            X = Fresh                       % may call
                                            % verify_attributes/3
        ).
@end example

Note that the ``implied binding'' @code{Other=El} was deferred until after
the completion of @code{verify_attribute/3}.  Otherwise, there might be a
danger of recursively invoking @code{verify_attribute/3}, which might bind
@code{Var}, which is not allowed inside the scope of @code{verify_attribute/3}.
Deferring unifications into the third argument of @code{verify_attribute/3}
effectively serializes the calls to @code{verify_attribute/3}.

Assuming that the code resides in the file @file{domain.yap}, we
can use it via:

@example
| ?- use_module(domain).
@end example

Let's test it:

@example
| ?- domain(X,[5,6,7,1]), domain(Y,[3,4,5,6]), domain(Z,[1,6,7,8]).

domain(X,[1,5,6,7]),
domain(Y,[3,4,5,6]),
domain(Z,[1,6,7,8]) ? 

yes
| ?- domain(X,[5,6,7,1]), domain(Y,[3,4,5,6]), domain(Z,[1,6,7,8]), 
     X=Y.

Y = X,
domain(X,[5,6]),
domain(Z,[1,6,7,8]) ? 

yes
| ?- domain(X,[5,6,7,1]), domain(Y,[3,4,5,6]), domain(Z,[1,6,7,8]),
     X=Y, Y=Z.

X = 6,
Y = 6,
Z = 6
@end example

To demonstrate the use of the @var{Goals} argument of
@code{verify_attributes/3}, we give an implementation of
@code{freeze/2}.  We have to name it @code{myfreeze/2} in order to
avoid a name clash with the built-in predicate of the same name.

@example
:- module(myfreeze, [myfreeze/2]).

:- use_module(library(atts)).

:- attribute frozen/1.

verify_attributes(Var, Other, Goals) :-
        get_atts(Var, frozen(Fa)), !,       % are we involved?
        (   var(Other) ->                   % must be attributed then
            (   get_atts(Other, frozen(Fb)) % has a pending goal?
            ->  put_atts(Other, frozen((Fa,Fb))) % rescue conjunction
            ;   put_atts(Other, frozen(Fa)) % rescue the pending goal
            ),
            Goals = []
        ;   Goals = [Fa]
        ).
verify_attributes(_, _, []).

attribute_goal(Var, Goal) :-                % interpretation as goal
        get_atts(Var, frozen(Goal)).

myfreeze(X, Goal) :-
        put_atts(Fresh, frozen(Goal)),
        Fresh = X.
@end example

Assuming that this code lives in file @file{myfreeze.yap},
we would use it via:

@example
| ?- use_module(myfreeze).
| ?- myfreeze(X,print(bound(x,X))), X=2.

bound(x,2)                      % side effect
X = 2                           % bindings
@end example

The two solvers even work together:

@example
| ?- myfreeze(X,print(bound(x,X))), domain(X,[1,2,3]),
     domain(Y,[2,10]), X=Y.

bound(x,2)                      % side effect
X = 2,                          % bindings
Y = 2
@end example

The two example solvers interact via bindings to shared attributed
variables only.  More complicated interactions are likely to be found
in more sophisticated solvers.  The corresponding
@code{verify_attributes/3} predicates would typically refer to the
attributes from other known solvers/modules via the module prefix in
@code{@var{Module}:get_atts/2}.

@node CLPR, CHR, Attributed Variables, Extensions
@cindex CLPQ
@cindex CLPR

@menu
* CLPR Solver Predicates::
* CLPR Syntax::
* CLPR Unification::
* CLPR Non-linear Constraints::               
@end menu


@include clpr.tex

@node CHR, Logtalk, CLPR, Top

@menu
* CHR Introduction::            
* CHR Syntax and Semantics::
* CHR in YAP Programs::
* CHR Debugging::               
* CHR Examples::       
* CHR Compatibility::     
* CHR Guidelines::  
@end menu

@include chr.tex

@node Logtalk, MYDDAS, CHR, Extensions
@section Logtalk
@cindex Logtalk

The Logtalk object-oriented extension is available after running its 
standalone installer by using the @code{yaplgt} command in POSIX 
systems or by using the @code{Logtalk - YAP} shortcut in the Logtalk 
program group in the Start Menu on Windows systems. For more information 
please see the URL @url{http://logtalk.org/}.

@node MYDDAS, Real, Logtalk, Extensions
@section MYDDAS
@cindex MYDDAS

The MYDDAS database project was developed within a FCT project aiming at
the development of a highly efficient deductive database system, based
on the coupling of the MySQL relational database system with the Yap
Prolog system. MYDDAS was later expanded to support the ODBC interface.

@menu
Subnodes of MYDDAS
* Requirements and Installation Guide:: 
* MYDDAS Architecture:: 
* Loading MYDDAS:: 
* Connecting to and disconnecting from a Database Server:: 
* Accessing a Relation:: 
* View Level Interface :: 
* Accessing Tables in Data Sources Using SQL:: 
* Insertion of Rows:: 
* Types of Attributes:: 
* Number of Fields:: 
* Describing a Relation:: 
* Enumerating Relations:: 
* The MYDDAS MySQL Top Level:: 
* Other MYDDAS Properties:: 
@end menu

@node Requirements and Installation Guide, MYDDAS Architecture, , MYDDAS
@section Requirements and Installation Guide

Next, we describe how to usen of the YAP with the MYDDAS System.  The
use of this system is entirely depend of the MySQL development libraries
or the ODBC development libraries. At least one of the this development
libraries must be installed on the computer system, otherwise MYDDAS
will not compile. The MySQL development libraries from MySQL 3.23 an
above are know to work. We recommend the usage of MySQL versusODBC,
but it is possible to have both options installed

At the same time, without any problem. The MYDDAS system automatically
controls the two options. Currently, MYDDAS is know to compile without
problems in Linux. The usage of this system on Windows has not been
tested yet.  MYDDAS must be enabled at configure time. This can be done
with the following options: 

@table @code

@item --enable-myddas
 This option will detect which development libraries are installed on the computer system, MySQL, ODBC or both, and will compile the Yap system with the support for which libraries it detects;
@item  --enable-myddas-stats
This option is only available in MySQL. It includes code to get
statistics from the MYDDAS system;
@item  --enable-top-level
This option is only available in MySQL.  It enables the option to interact with the MySQL server in
two different ways. As if we were on the MySQL Client Shell, and as if
we were using Datalog. 
@end table

@node MYDDAS Architecture, Loading MYDDAS, Requirements and Installation Guide, MYDDAS
@section MYDDAS Architecture

The system includes four main blocks that are put together through the
MYDDAS interface: the Yap Prolog compiler, the MySQL database system, an
ODBC layer and a Prolog to SQL compiler. Current effort is put on the
MySQL interface rather than on the ODBC interface. If you want to use
the full power of the MYDDAS interface we recommend you to use a MySQL
database. Other databases, such as Oracle, PostGres or Microsoft SQL
Server, can be interfaced through the ODBC layer, but with limited
performance and features support.  

The main structure of the MYDDAS interface is simple. Prolog queries
involving database goals are translated to SQL using the Prolog to SQL
compiler; then the SQL expression is sent to the database system, which
returns the set of tuples satisfying the query; and finally those tuples
are made available to the Prolog engine as terms. For recursive queries
involving database goals, the YapTab tabling engine provides the
necessary support for an efficient evaluation of such queries.

An important aspect of the MYDDAS interface is that for the programmer
the use of predicates which are defined in database relations is
completely transparent. An example of this transparent support is the
Prolog cut operator, which has exactly the same behaviour from
predicates defined in the Prolog program source code, or from predicates
defined in database as relations.

@node Loading MYDDAS, Connecting to and disconnecting from a Database Server, MYDDAS Architecture, MYDDAS 
@section Loading MYDDAS

Begin by starting YAP and loading the library
@code{use_module(library(myddas))}.  This library already includes the
Prolog to SQL Compiler described in [2] and [1]. In MYDDAS this compiler
has been extended to support further constructs which allow a more
efficient SQL translation.  

@node Connecting to and disconnecting from a Database Server, Accessing a Relation, Loading MYDDAS, MYDDAS
@section Connecting to and disconnecting from a Database Server


@table @code
@item db open(+,+,+,+,+). 
@findex db_open/5
@snindex db_open/5
@cnindex db_open/5

@item db open(+,+,+,+). 
@findex db_open/4
@snindex db_open/4
@cnindex db_open/4

@item db close(+). 
@findex db_close/1
@snindex db_close/1
@cnindex db_close/1

@end table 

  Assuming the MySQL server is running and we have an account, we can
login to MySQL by invoking @code{db_open/5} as one of the following:
@example
?- db_open(mysql,Connection,Host/Database,User,Password). 
?- db_open(mysql,Connection,Host/Database/Port,User,Password).
?- db_open(mysql,Connection,Host/Database/UnixSocket,User,Password). 
?- db_open(mysql,Connection,Host/Database/Port/UnixSocket,User,Password).

@end example
If the login is successful, there will be a response of @code{yes}. For
instance:
 @example
?- db_open(mysql,con1,localhost/guest_db,guest,'').
@end example
uses the MySQL native interface, selected by the first argument, to open
a connection identified by the @code{con1} atom, to an instance of a
MySQL server running on host @code{localhost}, using database guest @code{db}
and user @code{guest} with empty @code{password}.  To disconnect from the @code{con1}
connection we use: 
@example
?- db_close(con1).
@end example
 Alternatively, we can use @code{db_open/4} and @code{db_close/0,} without an argument
to identify the connection. In this case the default connection is used,
with atom @code{myddas}. Thus using 
@example
?- db_open(mysql,localhost/guest_db,guest,''). 
?- db_close.  
@end example
or
@example
?- db_open(mysql,myddas,localhost/guest_db,guest,''). 
?- db_close(myddas). 
@end example
is exactly the same.

MYDDAS also supports ODBC. To connect to a database using an ODBC driver
you must have configured on your system a ODBC DSN. If so, the @code{db_open/4}
and @code{db_open/5} have the following mode:
@example
 ?- db_open(odbc,Connection,ODBC_DSN,User,Password). 
 ?- db_open(odbc,ODBC_DSN,User,Password).
@end example

For instance, if you do @code{db_open(odbc,odbc_dsn,guest,'')}. it will connect
to a database, through ODBC, using the definitions on the @code{odbc_dsn} DSN
configured on the system. The user will be the user @code{guest} with no
password.

@node Accessing a Relation, View Level Interface , Connecting to and disconnecting from a Database Server, MYDDAS 
@section Accessing a Relation

@table @code
@item db_import(+Conn,+RelationName,+PredName). 
@findex db_import/3
@snindex db_import/3
@cnindex db_import/3

@item db_import(+RelationName,+PredName).  
@findex db_import/2
@snindex db_import/2
@cnindex db_import/2
@end table

Assuming you have access permission for the relation you wish to import,
you can use @code{db_import/3} or @code{db_import/2} as:
@example
?- db_import(Conn,RelationName,PredName).
?- db_import(RelationName,PredName).
@end example
 where @var{RelationName}, is the name of
relation we wish to access, @var{PredName} is the name of the predicate we
wish to use to access the relation from YAP. @var{Conn}, is the connection
identifier, which again can be dropped so that the default myddas connection
is used. For instance, if we want to access the relation phonebook,
using the predicate @code{phonebook/3} we write: 
@example
?- db_import(con1,phonebook,phonebook). 
yes
?- phonebook(Letter,Name,Number).
Letter = 'D',
Name = 'John Doe',
Number = 123456789 ? 
yes
@end example
Backtracking can then be used to retrieve the next row
of the relation phonebook.  Records with particular field values may be
selected in the same way as in Prolog. (In particular, no mode
specification for database predicates is required). For instance: 
@example
?- phonebook(Letter,'John Doe',Letter). 
Letter = 'D', 
Number = 123456789 ?
yes
@end example
generates the query
@example
SELECT A.Letter , 'John Doe' , A.Number 
FROM 'phonebook' A 
WHERE A.Name = 'John Doe';
@end example

@node View Level Interface, Accessing Tables in Data Sources Using SQL, Accessing a Relation, MYDDAS
@section View Level Interface

@table @code
@item db view(+,+,+).
@findex db_view/3
@snindex db_view/3
@cnindex db_view/3

@item db view(+,+).
@findex db_view/2
@snindex db_view/2
@cnindex db_view/2
@end table
If we import a database relation, such as an edge relation representing the edges of a directed graph, through
@example
?- db_import('Edge',edge). 
yes
@end example
and we then write a query to retrieve all the direct cycles in the
graph, such as
@example
?- edge(A,B), edge(B,A). 
A = 10, 
B = 20 ?
@end example
this is clearly inefficient [3], because of relation-level
access. Relation-level access means that a separate SQL query will be
generated for every goal in the body of the clause. For the second
@code{edge/2} goal, a SQL query is generated using the variable bindings that
result from the first @code{edge/2} goal execution. If the second
@code{edge/2} goal
fails, or if alternative solutions are demanded, backtracking access the
next tuple for the first @code{edge/2} goal and another SQL query will be
generated for the second @code{edge/2} goal. The generation of this large
number of queries and the communication overhead with the database
system for each of them, makes the relation-level approach inefficient.
To solve this problem the view level interface can be used for the
definition of rules whose bodies includes only imported database
predicates.  One can use the view level interface through the predicates
@code{db_view/3} and @code{db_view/2}:
@example
?- db_view(Conn,PredName(Arg_1,...,Arg_n),DbGoal).  
?- db_view(PredName(Arg_1,...,Arg_n),DbGoal).
@end example
 All arguments are standard Prolog terms. @var{Arg1} through @var{Argn}
define the attributes to be retrieved from the database, while
@var{DbGoal} defines the selection restrictions and join
conditions. @var{Conn} is the connection identifier, which again can be
dropped. Calling predicate @code{PredName/n} will retrieve database
tuples using a single SQL query generated for the @var{DbGoal}.  We next show
an example of a view definition for the direct cycles discussed
above. Assuming the declaration: 
@example
?- db_import('Edge',edge). 
yes
@end example
we
write:
@example
?- db_view(direct_cycle(A,B),(edge(A,B), edge(B,A))). 
yes 
?- direct_cycle(A,B)). 
A = 10, 
B = 20 ?  
@end example
This call generates the SQL
statement:
@example
SELECT A.attr1 , A.attr2
FROM Edge A , Edge B 
WHERE B.attr1 = A.attr2 AND B.attr2 = A.attr1;
@end example

Backtracking, as in relational level interface, can be used to retrieve the next row of the view.
The view interface also supports aggregate function predicates such as
@code{sum}, @code{avg}, @code{count}, @code{min} and @code{max}. For
instance:
@example
?- db_view(count(X),(X is count(B, B^edge(10,B)))).
@end example
generates the query :
@example
SELECT COUNT(A.attr2) 
FROM Edge A WHERE A.attr1 = 10;
@end example

To know how to use db @code{view/3}, please refer to Draxler's Prolog to
SQL Compiler Manual. 

@node Accessing Tables in Data Sources Using SQL, Insertion of Rows, View Level Interface , MYDDAS 
@section Accessing Tables in Data Sources Using SQL 

@table @code
@item db_sql(+,+,?). 
@findex db_sql/3
@snindex db_sql/3
@cnindex db_sql/3

@item db_sql(+,?).
@findex db_sql/2
@snindex db_sql/2
@cnindex db_sql/2
@end table

It is also possible to explicitly send a SQL query to the database server using
@example
?- db_sql(Conn,SQL,List).
?- db_sql(SQL,List).
@end example
where @var{SQL} is an arbitrary SQL expression, and @var{List} is a list
holding the first tuple of result set returned by the server. The result
set can also be navigated through backtracking.

Example:
@example
?- db_sql('SELECT * FROM phonebook',LA).
LA = ['D','John Doe',123456789] ?
@end example

@node  Insertion of Rows, Types of Attributes, Accessing Tables in Data Sources Using SQL, MYDDAS 
@section Insertion of Rows 

@table @code
@item db_assert(+,+). 
@findex db_assert/2
@snindex db_assert/2
@cnindex db_assert/2

@item db_assert(+).
@findex db_assert/1
@snindex db_assert/1
@cnindex db_assert/1

@end table

Assuming you have imported the related base table using
 @code{db_import/2} or @code{db_import/3}, you can insert to that table
 by using @code{db_assert/2} predicate any given fact.
@example
?- db_assert(Conn,Fact).
?- db_assert(Fact).
@end example
The second argument must be declared with all of its arguments bound to
constants. For example assuming @code{helloWorld} is imported through
@code{db_import/2}:
@example
?- db_import('Hello World',helloWorld).
yes
?- db_assert(helloWorld('A' ,'Ana',31)). 
yes
@end example
This, would generate the following query 
@example
INSERT INTO helloWorld
VALUES ('A','Ana',3)
@end example
which would insert into the helloWorld, the following row:
@code{A,Ana,31}. If we want to insert @code{NULL}  values into the
relation, we call @code{db_assert/2} with a uninstantiated variable in
the data base imported predicate. For example, the following query on
the YAP-prolog system:

@example
?- db_assert(helloWorld('A',NULL,31)).
yes
@end example

Would insert the row: @code{A,null value,31} into the relation
@code{Hello World}, assuming that the second row allows null values.

@table @code
@item db insert(+,+,+). 
@findex db_insert/3
@snindex db_insert/3
@cnindex db_insert/3

@item db insert(+,+).  
@findex db_insert/2
@snindex db_insert/2
@cnindex db_insert/2
@end table
 
This predicate would create a new database predicate, which will insert
any given tuple into the database.
@example
?- db_insert(Conn,RelationName,PredName).
?- db_insert(RelationName,PredName).
@end example
This would create a new predicate with name @var{PredName}, that will
insert tuples into the relation @var{RelationName}. is the connection
identifier. For example, if we wanted to insert the new tuple
@code{('A',null,31)} into the relation @code{Hello World}, we do: 
@example
?- db_insert('Hello World',helloWorldInsert). 
yes
?- helloWorldInsert('A',NULL,31).
yes
@end example

@node  Types of Attributes, Number of Fields, Insertion of Rows, MYDDAS 
@section Types of Attributes


@table @code
@item db_get_attributes_types(+,+,?).
@findex db_get_attributes_types/3
@snindex db_get_attributes_types/3
@cnindex db_get_attributes_types/3

@item db_get_attributes_types(+,?). 
@findex db_get_attributes_types/2
@snindex db_get_attributes_types/2
@cnindex db_get_attributes_types/2

@end table
 
The prototype for this predicate is the following: 
@example
?- db_get_attributes_types(Conn,RelationName,ListOfFields).
?- db_get_attributes_types(RelationName,ListOfFields). 
@end example

You can use the
predicate @code{db_get_attributes types/2} or @code{db_get_attributes_types/3}, to
know what are the names and attributes types of the fields of a given
relation. For example: 
@example
?- db_get_attributes_types(myddas,'Hello World',LA).
LA = ['Number',integer,'Name',string,'Letter',string] ? 
yes
@end example
where @t{Hello World} is the name of the relation and @t{myddas} is the
connection identifier. 

@node  Number of Fields, Describing a Relation, Types of Attributes, MYDDAS 
@section Number of Fields

@table @code
@item db_number_of_fields(+,?).
@findex db_number_of_fields/2
@snindex db_number_of_fields/2
@cnindex db_number_of_fields/2

@item db_number_of_fields(+,+,?).
@findex db_number_of_fields/3
@snindex db_number_of_fields/3
@cnindex db_number_of_fields/3
@end table
 
The prototype for this
predicate is the following:
@example
 ?- db_number_of_fields(Conn,RelationName,Arity).
 ?- db_number_of_fields(RelationName,Arity).  
@end example
You can use the predicate @code{db_number_of_fields/2} or
@code{db_number_of_fields/3} to know what is the arity of a given
relation. Example: 
@example
?- db_number_of_fields(myddas,'Hello World',Arity). 
Arity = 3 ? 
yes 
@end example
where @code{Hello World} is the name of the
relation and @code{myddas} is the connection identifier.

@node Describing a Relation, Enumerating Relations, Number of Fields, MYDDAS
@section Describing a Relation

@table @code
@item db_datalog_describe(+,+).
@findex db_datalog_describe/2
@snindex db_datalog_describe/2
@cnindex db_datalog_describe/2

@item db_datalog_describe(+).
@findex db_datalog_describe/1
@snindex db_datalog_describe/1
@cnindex db_datalog_describe/1
@end table
 

The db @code{datalog_describe/2} predicate does not really returns any
value. It simply prints to the screen the result of the MySQL describe
command, the same way as @code{DESCRIBE} in the MySQL prompt would.
@example
?- db_datalog_describe(myddas,'Hello World'). 
+----------+----------+------+-----+---------+-------+ 
|   Field  |  Type    | Null | Key | Default | Extra |
+----------+----------+------+-----+---------+-------+
+  Number  | int(11)  | YES  |     |   NULL  |       |
+  Name    | char(10) | YES  |     |   NULL  |       |
+  Letter  | char(1)  | YES  |     |   NULL  |       |
+----------+----------+------+-----+---------+-------+
yes
@end example

@table @code
@item db_describe(+,+).
@findex db_describe/2
@snindex db_describe/2
@cnindex db_describe/2

@item db_describe(+).
@findex db_describe/1
@snindex db_describe/1
@cnindex db_describe/1

@end table
 
The @code{db_describe/3} predicate does the same action as
@code{db_datalog_describe/2} predicate but with one major
difference. The results are returned by backtracking. For example, the
last query:
@example
 ?- db_describe(myddas,'Hello World',Term). 
Term = tableInfo('Number',int(11),'YES','',null(0),'') ? ;
Term = tableInfo('Name',char(10),'YES','',null(1),'' ? ; 
Term = tableInfo('Letter',char(1),'YES','',null(2),'') ? ;
no
@end example

@node Enumerating Relations, The MYDDAS MySQL Top Level, Describing a Relation, MYDDAS
@section Enumeration Relations

@table @code
@item db_datalog_show_tables(+).
@item db_datalog_show_tables
@end table
 

If we need to know what relations exists in a given MySQL Schema, we can use
the @code{db_datalog_show_tables/1} predicate. As @t{db_datalog_describe/2},
it does not returns any value, but instead prints to the screen the result of the
@code{SHOW TABLES} command, the same way as it would be in the MySQL prompt. 
@example
?- db_datalog_show_tables(myddas).
+-----------------+
| Tables_in_guest |
+-----------------+
|   Hello World   |
+-----------------+ 
yes
@end example

@table @code
@item db_show_tables(+, ?).
@findex db_show_tables/2
@snindex db_show_tables/2
@cnindex db_show_tables/2

@item db_show_tables(?)
@findex db_show_tables/1
@snindex db_show_tables/1
@cnindex db_show_tables/1

@end table
 
The @code{db_show_tables/2} predicate does the same action as
@code{db_show_tables/1} predicate but with one major difference. The
results are returned by backtracking. For example, given the last query:
@example
?- db_show_tables(myddas,Table).
Table = table('Hello World') ? ;
no
@end example

@node The MYDDAS MySQL Top Level, Other MYDDAS Properties, Enumerating Relations, MYDDAS
@section The MYDDAS MySQL Top Level


@table @code
@item db_top_level(+,+,+,+,+). 
@findex db_top_level/5
@snindex db_top_level/5
@cnindex db_top_level/5

@item db_top_level(+,+,+,+).
@findex db_top_level/4
@snindex db_top_level/4
@cnindex db_top_level/4

@end table
 
Through MYDDAS is also possible to access the MySQL Database Server, in
the same wthe mysql client. In this mode, is possible to query the
SQL server by just using the standard SQL language. This mode is exactly the same as 
different from the standard mysql client. We can use this
mode, by invoking the db top level/5. as one of the following:
@example
?- db_top_level(mysql,Connection,Host/Database,User,Password). 
?- db_top_level(mysql,Connection,Host/Database/Port,User,Password). 
?- db_top_level(mysql,Connection,Host/Database/UnixSocket,User,Password). 
?- db_top_level(mysql,Connection,Host/Database/Port/UnixSocket,User,Password).
@end example

Usage is similar as the one described for the @code{db_open/5} predicate
discussed above. If the login is successful, automatically the prompt of
the mysql client will be used.  For example:
@example
 ?- db_top_level(mysql,con1,localhost/guest_db,guest,''). 
@end  example
opens a
connection identified by the @code{con1} atom, to an instance of a MySQL server
running on host @code{localhost}, using database guest @code{db} and user @code{guest} with
empty password. After this is possible to use MYDDAS as the mysql
client.
@example
  ?- db_top_level(mysql,con1,localhost/guest_db,guest,''). 
Reading table information for completion of table and column names
You can turn off this feature to get a quicker startup with -A

Welcome to the MySQL monitor.
Commands end with ; or \g.

Your MySQL connection id is 4468 to server version: 4.0.20
Type 'help;' or '\h' for help.
Type '\c' to clear the buffer. 
mysql> exit
Bye 
yes
?- 
@end  example

@node Other MYDDAS Properties, , The MYDDAS MySQL Top Level , MYDDAS 
@section Other MYDDAS Properties 


@table @code
@item db_verbose(+). 
@item db_top_level(+,+,+,+).
@end table
 
When we ask a question to YAP, using a predicate asserted by
@code{db_import/3}, or by @code{db_view/3}, this will generate a SQL
@code{QUERY}. If we want to see that query, we must to this at a given
point in our session on YAP.
@example
?- db_verbose(1).
yes 
?- 
@end example
If we want to
disable this feature, we must call the @code{db_verbose/1} predicate with the value 0.

@table @code
@item db_module(?). 
@findex db_module/1
@snindex db_module/1
@cnindex db_module/1

@end table

When we create a new database predicate, by using @code{db_import/3},
@code{db_view/3} or @code{db_insert/3}, that predicate will be asserted
by default on the @code{user} module. If we want to change this value, we can
use the @code{db_module/1} predicate to do so.
@example
?- db_module(lists).
yes
?-
@end example
By executing this predicate, all of the predicates asserted by the
predicates enumerated earlier will created in the lists module.
If we want to put back the value on default, we can manually put the
value user. Example: 
@example
?- db_module(user).
yes
?-
@end example

We can also see in what module the predicates are being asserted by doing:
@example
?- db_module(X). 
X=user
yes
 ?-
@end example

@table @code
@item db_my_result_set(?).
@findex db_my_result_set/1
@snindex db_my_result_set/1
@cnindex db_my_result_set/1

@end table


The MySQL C API permits two modes for transferring the data generated by
a query to the client, in our case YAP. The first mode, and the default
mode used by the MYDDAS-MySQL, is to store the result. This mode copies all the
information generated to the client side.
@example
?- db_my_result_set(X).
X=store_result
yes
@end example


The other mode that we can use is use result. This one uses the result
set created directly from the server. If we want to use this mode, he
simply do
@example
 ?- db_my_result_set(use_result). 
yes
@end example
After this command, all
of the database predicates will use use result by default. We can change
this by doing again @code{db_my_result_set(store_result)}.  

@table @code
@item db_my_sql_mode(+Conn,?SQL_Mode).
@findex db_my_sql_mode/2
@snindex db_my_sql_mode/2
@cnindex db_my_sql_mode/2

@item db_my_sql_mode(?SQL_Mode).
@findex db_my_sql_mode/1
@snindex db_my_sql_mode/1
@cnindex db_my_sql_mode/1

@end table

The MySQL server allows the user to change the SQL mode. This can be
very useful for debugging proposes. For example, if we want MySQL server
not to ignore the INSERT statement warnings and instead of taking
action, report an error, we could use the following SQL mode.
@example
  ?-db_my_sql_mode(traditional). yes
@end example
You can see the available SQL Modes at the MySQL homepage at
@url{http://www.mysql.org}.

@node Real, Threads, MYDDAS, Extensions

@chapter Real::   Talking to the R language 

@ifplaintext

@copydoc real

@end ifplaintext

@node Threads, Parallelism, Real, Extensions
@chapter Threads

YAP implements a SWI-Prolog compatible multithreading
library. Like in SWI-Prolog, Prolog threads have their own stacks and
only share the Prolog @emph{heap}: predicates, records, flags and other
global non-backtrackable data.  The package is based on the POSIX thread
standard (Butenhof:1997:PPT) used on most popular systems except
for MS-Windows.

@comment On Windows it uses the
@comment \url[pthread-win32]{http://sources.redhat.com/pthreads-win32/} emulation
@comment of POSIX threads mixed with the Windows native API for smoother and
@comment faster operation.

@menu
Subnodes of Threads
* Creating and Destroying Prolog Threads::               
* Monitoring Threads::            
* Thread Communication::   
* Thread Synchronisation::                 

Subnodes of Thread Communication
* Message Queues::
* Signalling Threads::            
* Threads and Dynamic Predicates::   
@end menu

@node Creating and Destroying Prolog Threads, Monitoring Threads, ,Threads
@section Creating and Destroying Prolog Threads

@table @code

@item thread_create(:@var{Goal}, -@var{Id}, +@var{Options})
@findex thread_create/3
@snindex thread_create/3
@cnindex thread_create/3

Create a new Prolog thread (and underlying C-thread) and start it
by executing @var{Goal}.  If the thread is created successfully, the
thread-identifier of the created thread is unified to @var{Id}.
@var{Options} is a list of options.  Currently defined options are:

@table @code
    @item stack
Set the limit in K-Bytes to which the Prolog stacks of
this thread may grow.  If omitted, the limit of the calling thread is
used.  See also the  commandline @code{-S} option.

    @item trail
Set the limit in K-Bytes to which the trail stack of this thread may
grow.  If omitted, the limit of the calling thread is used. See also the
commandline option @code{-T}.

    @item alias
Associate an alias-name with the thread.  This named may be used to
refer to the thread and remains valid until the thread is joined
(see @code{thread_join/2}).

    @item at_exit
Define an exit hook for the thread.  This hook is called when the thread
terminates, no matter its exit status.

    @item detached
If @code{false} (default), the thread can be waited for using
@code{thread_join/2}. @code{thread_join/2} must be called on this thread
to reclaim the all resources associated to the thread. If @code{true},
the system will reclaim all associated resources automatically after the
thread finishes. Please note that thread identifiers are freed for reuse
after a detached thread finishes or a normal thread has been joined.
See also @code{thread_join/2} and @code{thread_detach/1}.
@end table

The @var{Goal} argument is @emph{copied} to the new Prolog engine.
This implies further instantiation of this term in either thread does
not have consequences for the other thread: Prolog threads do not share
data from their stacks.

@item thread_create(:@var{Goal}, -@var{Id})
@findex thread_create/2
@snindex thread_create/2
@cnindex thread_create/2

Create a new Prolog thread using default options. See @code{thread_create/3}.

@item thread_create(:@var{Goal})
@findex thread_create/1
@snindex thread_create/1
@cnindex thread_create/1

Create a new Prolog detached thread using default options. See @code{thread_create/3}.

@item thread_self(-@var{Id})
@findex thread_self/1
@snindex thread_self/1
@cnindex thread_self/1
Get the Prolog thread identifier of the running thread.  If the thread
has an alias, the alias-name is returned.

@item thread_join(+@var{Id}, -@var{Status})
@findex thread_join/2
@snindex thread_join/2
@cnindex thread_join/2
Wait for the termination of thread with given @var{Id}.  Then unify the
result-status of the thread with @var{Status}.  After this call,
@var{Id} becomes invalid and all resources associated with the thread
are reclaimed.  Note that threads with the attribute @code{detached}
@code{true} cannot be joined.  See also @code{current_thread/2}.

A thread that has been completed without @code{thread_join/2} being
called on it is partly reclaimed: the Prolog stacks are released and the
C-thread is destroyed. A small data-structure representing the
exit-status of the thread is retained until @code{thread_join/2} is called on
the thread.  Defined values for @var{Status} are:

@table @code
    @item true
The goal has been proven successfully.

    @item false
The goal has failed.

    @item exception(@var{Term})
 The thread is terminated on an
exception.  See @code{print_message/2} to turn system exceptions into
readable messages.

    @item exited(@var{Term})
The thread is terminated on @code{thread_exit/1} using the argument @var{Term}.
@end table


@item thread_detach(+@var{Id})
@findex thread_detach/1
@snindex thread_detach/1
@cnindex thread_detach/1
Switch thread into detached-state (see @code{detached} option at
@code{thread_create/3} at runtime.  @var{Id} is the identifier of the thread
placed in detached state.

One of the possible applications is to simplify debugging. Threads that
are created as @code{detached} leave no traces if they crash. For
not-detached threads the status can be inspected using
@code{current_thread/2}.  Threads nobody is waiting for may be created
normally and detach themselves just before completion.  This way they
leave no traces on normal completion and their reason for failure can be
inspected.

@item thread_yield
@findex thread_yield/0
@snindex thread_yield/0
@cnindex thread_yield/0
Voluntarily relinquish the processor.

@item thread_exit(+@var{Term})
@findex thread_exit/1
@snindex thread_exit/1
@cnindex thread_exit/1
Terminates the thread immediately, leaving @code{exited(@var{Term})} as
result-state for @code{thread_join/2}.  If the thread has the attribute
@code{detached} @code{true} it terminates, but its exit status cannot be
retrieved using @code{thread_join/2} making the value of @var{Term}
irrelevant.  The Prolog stacks and C-thread are reclaimed.

@item thread_at_exit(:@var{Term})
@findex thread_at_exit/1
@snindex thread_at_exit/1
@cnindex thread_at_exit/1
Run @var{Goal} just before releasing the thread resources. This is to
be compared to @code{at_halt/1}, but only for the current
thread. These hooks are ran regardless of why the execution of the
thread has been completed. As these hooks are run, the return-code is
already available through @code{thread_property/2} using the result of
@code{thread_self/1} as thread-identifier. If you want to guarantee the 
execution of an exit hook no matter how the thread terminates (the thread 
can be aborted before reaching the @code{thread_at_exit/1} call), consider
using instead the @code{at_exit/1} option of @code{thread_create/3}. 

@item thread_setconcurrency(+@var{Old}, -@var{New})
@findex thread_setconcurrency/2
@snindex thread_setconcurrency/2
@cnindex thread_setconcurrency/2
Determine the concurrency of the process, which is defined as the
maximum number of concurrently active threads. `Active' here means
they are using CPU time. This option is provided if the
thread-implementation provides
@code{pthread_setconcurrency()}. Solaris is a typical example of this
family. On other systems this predicate unifies @var{Old} to 0 (zero)
and succeeds silently.

@item thread_sleep(+@var{Time})
@findex thread_sleep/1
@snindex thread_sleep/1
@cnindex thread_sleep/1
Make current thread sleep for @var{Time} seconds. @var{Time} may be an
integer or a floating point number. When time is zero or a negative value 
the call succeeds and returns immediately. This call should not be used if
alarms are also being used.
@end table


@node Monitoring Threads, Thread Communication,Creating and Destroying Prolog Threads,Threads
@section Monitoring Threads

Normal multi-threaded applications should not need these the predicates
from this section because almost any usage of these predicates is
unsafe. For example checking the existence of a thread before signalling
it is of no use as it may vanish between the two calls. Catching
exceptions using @code{catch/3} is the only safe way to deal with
thread-existence errors.

These predicates are provided for diagnosis and monitoring tasks.


@table @code
@item thread_property(?@var{Id}, ?@var{Property})
@findex thread_property/2
@snindex thread_property/2
@cnindex thread_property/2
Enumerates the properties of the specified thread.
Calling @code{thread_property/2} does not influence any thread.  See also
@code{thread_join/2}.  For threads that have an alias-name, this name can
be used in @var{Id} instead of the numerical thread identifier.
@var{Property} is one of:

@table @code
    @item status(@var{Status})
The thread status of a thread (see below).

    @item alias(@var{Alias})
The thread alias, if it exists.

    @item at_exit(@var{AtExit})
The thread exit hook, if defined (not available if the thread is already terminated).

    @item detached(@var{Boolean})
The detached state of the thread.

    @item stack(@var{Size})
The thread stack data-area size.

    @item trail(@var{Size})
The thread trail data-area size.

    @item system(@var{Size})
The thread system data-area size.
@end table

@item current_thread(+@var{Id}, -@var{Status})
@findex current_thread/2
@snindex current_thread/2
@cnindex current_thread/2
Enumerates identifiers and status of all currently known threads.
Calling @code{current_thread/2} does not influence any thread.  See also
@code{thread_join/2}.  For threads that have an alias-name, this name is
returned in @var{Id} instead of the numerical thread identifier.
@var{Status} is one of:

@table @code
    @item running
The thread is running.  This is the initial status of a thread.  Please
note that threads waiting for something are considered running too.

    @item false
The @var{Goal} of the thread has been completed and failed.

    @item true
The @var{Goal} of the thread has been completed and succeeded.

    @item exited(@var{Term})
The @var{Goal} of the thread has been terminated using @code{thread_exit/1}
with @var{Term} as argument.  If the underlying native thread has
exited (using pthread_exit()) @var{Term} is unbound.

    @item exception(@var{Term})
The @var{Goal} of the thread has been terminated due to an uncaught
exception (see @code{throw/1} and @code{catch/3}).
@end table

@item thread_statistics(+@var{Id}, +@var{Key}, -@var{Value})
@findex thread_statistics/3
@snindex thread_statistics/3
@cnindex thread_statistics/3
Obtains statistical information on thread @var{Id} as @code{statistics/2}
does in single-threaded applications.  This call returns all keys
of @code{statistics/2}, although only information statistics about the
stacks and CPU time yield different values for each thread.

@item mutex_statistics
@findex mutex_statistics/0
@snindex mutex_statistics/0
@cnindex mutex_statistics/0
Print usage statistics on internal mutexes and mutexes associated
with dynamic predicates.  For each mutex two numbers are printed:
the number of times the mutex was acquired and the number of
collisions: the number times the calling thread has to
wait for the mutex.  The collision-count is not available on
Windows as this would break portability to Windows-95/98/ME or
significantly harm performance.  Generally collision count is
close to zero on single-CPU hardware.

@item threads
@findex threads/0
@snindex threads/0
@cnindex threads/0
Prints a table of current threads and their status.
@end table


@node Thread Communication, Thread Synchronisation, Monitoring Threads, Threads
@section Thread communication

@menu
Subnodes of Thread Communication
* Message Queues::
* Signalling Threads::            
* Threads and Dynamic Predicates::   
@end menu

@node Message Queues, Signalling Threads, ,Thread Communication
@subsection Message Queues

Prolog threads can exchange data using dynamic predicates, database
records, and other globally shared data. These provide no suitable means
to wait for data or a condition as they can only be checked in an
expensive polling loop. @emph{Message queues} provide a means for
threads to wait for data or conditions without using the CPU.

Each thread has a message-queue attached to it that is identified
by the thread. Additional queues are created using
@code{message_queue_create/2}.

@table @code

@item thread_send_message(+@var{Term})
@findex thread_send_message/1
@snindex thread_send_message/1
@cnindex thread_send_message/1
Places @var{Term} in the message-queue of the thread running the goal. 
Any term can be placed in a message queue, but note that the term is 
copied to the receiving thread and variable-bindings are thus lost. 
This call returns immediately.

@item thread_send_message(+@var{QueueOrThreadId}, +@var{Term})
@findex thread_send_message/2
@snindex thread_send_message/2
@cnindex thread_send_message/2
Place @var{Term} in the given queue or default queue of the indicated
thread (which can even be the message queue of itself (see
@code{thread_self/1}). Any term can be placed in a message queue, but note that
the term is copied to the receiving thread and variable-bindings are
thus lost. This call returns immediately.

If more than one thread is waiting for messages on the given queue and
at least one of these is waiting with a partially instantiated
@var{Term}, the waiting threads are @emph{all} sent a wakeup signal,
starting a rush for the available messages in the queue.  This behaviour
can seriously harm performance with many threads waiting on the same
queue as all-but-the-winner perform a useless scan of the queue. If
there is only one waiting thread or all waiting threads wait with an
unbound variable an arbitrary thread is restarted to scan the queue.
@comment    \footnote{See the documentation for the POSIX thread functions
@comment          pthread_cond_signal() v.s.\ pthread_cond_broadcastt()
@comment          for background information.}

@item thread_get_message(?@var{Term})
@findex thread_get_message/1
@snindex thread_get_message/1
@cnindex thread_get_message/1
Examines the thread message-queue and if necessary blocks execution
until a term that unifies to @var{Term} arrives in the queue.  After
a term from the queue has been unified unified to @var{Term}, the
term is deleted from the queue and this predicate returns.

Please note that not-unifying messages remain in the queue.  After
the following has been executed, thread 1 has the term @code{gnu}
in its queue and continues execution using @var{A} is @code{gnat}.

@example
   <thread 1>
   thread_get_message(a(A)),

   <thread 2>
   thread_send_message(b(gnu)),
   thread_send_message(a(gnat)),
@end example

See also @code{thread_peek_message/1}.

@item message_queue_create(?@var{Queue})
@findex message_queue_create/1
@snindex message_queue_create/1
@cnindex message_queue_create/1
If @var{Queue} is an atom, create a named queue.  To avoid ambiguity
on @code{thread_send_message/2}, the name of a queue may not be in use
as a thread-name.  If @var{Queue} is unbound an anonymous queue is
created and @var{Queue} is unified to its identifier.

@item message_queue_destroy(+@var{Queue})
@findex message_queue_destroy/1
@snindex message_queue_destroy/1
@cnindex message_queue_destroy/1
Destroy a message queue created with @code{message_queue_create/1}.  It is
@emph{not} allows to destroy the queue of a thread.  Neither is it
allowed to destroy a queue other threads are waiting for or, for
anonymous message queues, may try to wait for later.

@item thread_get_message(+@var{Queue}, ?@var{Term})
@findex thread_get_message/2
@snindex thread_get_message/2
@cnindex thread_get_message/2
As @code{thread_get_message/1}, operating on a given queue. It is allowed to
peek into another thread's message queue, an operation that can be used
to check whether a thread has swallowed a message sent to it.

@item thread_peek_message(?@var{Term})
@findex thread_peek_message/1
@snindex thread_peek_message/1
@cnindex thread_peek_message/1
Examines the thread message-queue and compares the queued terms
with @var{Term} until one unifies or the end of the queue has been
reached.  In the first case the call succeeds (possibly instantiating
@var{Term}.  If no term from the queue unifies this call fails.

@item thread_peek_message(+@var{Queue}, ?@var{Term})
@findex thread_peek_message/2
@snindex thread_peek_message/2
@cnindex thread_peek_message/2
As @code{thread_peek_message/1}, operating on a given queue. It is allowed to
peek into another thread's message queue, an operation that can be used
to check whether a thread has swallowed a message sent to it.

@end table


Explicit message queues are designed with the @emph{worker-pool} model
in mind, where multiple threads wait on a single queue and pick up the
first goal to execute.  Below is a simple implementation where the
workers execute arbitrary Prolog goals.  Note that this example provides
no means to tell when all work is done. This must be realised using
additional synchronisation.

@example
%    create_workers(+Id, +N)
%    
%    Create a pool with given Id and number of workers.

create_workers(Id, N) :-
    message_queue_create(Id),
    forall(between(1, N, _),
           thread_create(do_work(Id), _, [])).

do_work(Id) :-
    repeat,
      thread_get_message(Id, Goal),
      (   catch(Goal, E, print_message(error, E))
      ->  true
      ;   print_message(error, goal_failed(Goal, worker(Id)))
      ),
    fail.

%    work(+Id, +Goal)
%    
%    Post work to be done by the pool

work(Id, Goal) :-
    thread_send_message(Id, Goal).
@end example

@node Signalling Threads, Threads and Dynamic Predicates,Message Queues, Thread Communication
@subsection Signalling Threads

These predicates provide a mechanism to make another thread execute some
goal as an @emph{interrupt}.  Signalling threads is safe as these
interrupts are only checked at safe points in the virtual machine.
Nevertheless, signalling in multi-threaded environments should be
handled with care as the receiving thread may hold a @emph{mutex}
(see @code{with_mutex/2}).  Signalling probably only makes sense to start
debugging threads and to cancel no-longer-needed threads with @code{throw/1},
where the receiving thread should be designed carefully do handle
exceptions at any point.

@table @code
@item thread_signal(+@var{ThreadId}, :@var{Goal})
@findex thread_signal/2
@snindex thread_signal/2
@cnindex thread_signal/2
Make thread @var{ThreadId} execute @var{Goal} at the first
opportunity.  In the current implementation, this implies at the first
pass through the @emph{Call-port}. The predicate @code{thread_signal/2}
itself places @var{Goal} into the signalled-thread's signal queue
and returns immediately.

Signals (interrupts) do not cooperate well with the world of
multi-threading, mainly because the status of mutexes cannot be
guaranteed easily.  At the call-port, the Prolog virtual machine
holds no locks and therefore the asynchronous execution is safe.

@var{Goal} can be any valid Prolog goal, including @code{throw/1} to make
the receiving thread generate an exception and @code{trace/0} to start
tracing the receiving thread.

@comment In the Windows version, the receiving thread immediately executes
@comment the signal if it reaches a Windows GetMessage() call, which generally
@comment happens of the thread is waiting for (user-)input.
@end table

@node Threads and Dynamic Predicates, , Signalling Threads, Thread Communication
@subsection Threads and Dynamic Predicates

Besides queues threads can share and exchange data using dynamic
predicates. The multi-threaded version knows about two types of
dynamic predicates. By default, a predicate declared @emph{dynamic}
(see @code{dynamic/1}) is shared by all threads. Each thread may
assert, retract and run the dynamic predicate. Synchronisation inside
Prolog guarantees the consistency of the predicate. Updates are
@emph{logical}: visible clauses are not affected by assert/retract
after a query started on the predicate. In many cases primitive from
thread synchronisation should be used to ensure application invariants on
the predicate are maintained.

Besides shared predicates, dynamic predicates can be declared with the
@code{thread_local/1} directive. Such predicates share their
attributes, but the clause-list is different in each thread.

@table @code
@item thread_local(@var{+Functor/Arity}) 
@findex thread_local/1 (directive)
@snindex thread_local/1 (directive)
@cnindex thread_local/1 (directive)
related to the dynamic/1 directive.  It tells the system that the
predicate may be modified using @code{assert/1}, @code{retract/1},
etc, during execution of the program.  Unlike normal shared dynamic
data however each thread has its own clause-list for the predicate.
As a thread starts, this clause list is empty.  If there are still
clauses as the thread terminates these are automatically reclaimed by
the system.  The @code{thread_local} property implies
the property @code{dynamic}.

Thread-local dynamic predicates are intended for maintaining
thread-specific state or intermediate results of a computation.

It is not recommended to put clauses for a thread-local predicate into
a file as in the example below as the clause is only visible from the
thread that loaded the source-file.  All other threads start with an
empty clause-list.

@example
:- thread_local
    foo/1.

foo(gnat).
@end example

@end table


@node Thread Synchronisation, , Thread Communication, Threads
@section Thread Synchronisation

All internal Prolog operations are thread-safe. This implies two Prolog
threads can operate on the same dynamic predicate without corrupting the
consistency of the predicate. This section deals with user-level
@emph{mutexes} (called @emph{monitors} in ADA or
@emph{critical-sections} by Microsoft).  A mutex is a
@emph{MUT}ual @emph{EX}clusive device, which implies at most one thread
can @emph{hold} a mutex.

Mutexes are used to realise related updates to the Prolog database.
With `related', we refer to the situation where a `transaction' implies
two or more changes to the Prolog database.  For example, we have a
predicate @code{address/2}, representing the address of a person and we want
to change the address by retracting the old and asserting the new
address.  Between these two operations the database is invalid: this
person has either no address or two addresses, depending on the
assert/retract order.

Here is how to realise a correct update:

@example
:- initialization
    mutex_create(addressbook).

change_address(Id, Address) :-
    mutex_lock(addressbook),
    retractall(address(Id, _)),
    asserta(address(Id, Address)),
    mutex_unlock(addressbook).
@end example


@table @code
@item mutex_create(?@var{MutexId})
@findex mutex_create/1
@snindex mutex_create/1
@cnindex mutex_create/1
Create a mutex.  if @var{MutexId} is an atom, a @emph{named} mutex is
created.  If it is a variable, an anonymous mutex reference is returned.
There is no limit to the number of mutexes that can be created.

@item mutex_destroy(+@var{MutexId})
@findex mutex_destroy/1
@snindex mutex_destroy/1
@cnindex mutex_destroy/1
Destroy a mutex.  After this call, @var{MutexId} becomes invalid and
further references yield an @code{existence_error} exception.

@item with_mutex(+@var{MutexId}, :@var{Goal})
@findex with_mutex/2
@snindex with_mutex/2
@cnindex with_mutex/2
Execute @var{Goal} while holding @var{MutexId}.  If @var{Goal} leaves
choicepoints, these are destroyed (as in @code{once/1}).  The mutex is unlocked
regardless of whether @var{Goal} succeeds, fails or raises an exception.
An exception thrown by @var{Goal} is re-thrown after the mutex has been
successfully unlocked.  See also @code{mutex_create/2}.

Although described in the thread-section, this predicate is also
available in the single-threaded version, where it behaves simply as
@code{once/1}.

@item mutex_lock(+@var{MutexId})
@findex mutex_lock/1
@snindex mutex_lock/1
@cnindex mutex_lock/1
Lock the mutex.  Prolog mutexes are @emph{recursive} mutexes: they
can be locked multiple times by the same thread.  Only after unlocking
it as many times as it is locked, the mutex becomes available for
locking by other threads. If another thread has locked the mutex the
calling thread is suspended until to mutex is unlocked.

If @var{MutexId} is an atom, and there is no current mutex with that
name, the mutex is created automatically using @code{mutex_create/1}.  This
implies named mutexes need not be declared explicitly.

Please note that locking and unlocking mutexes should be paired
carefully. Especially make sure to unlock mutexes even if the protected
code fails or raises an exception. For most common cases use
@code{with_mutex/2}, which provides a safer way for handling Prolog-level
mutexes.

@item mutex_trylock(+@var{MutexId})
@findex mutex_trylock/1
@snindex mutex_trylock/1
@cnindex mutex_trylock/1
As mutex_lock/1, but if the mutex is held by another thread, this
predicates fails immediately.

@item mutex_unlock(+@var{MutexId})
@findex mutex_unlock/1
@snindex mutex_unlock/1
@cnindex mutex_unlock/1
Unlock the mutex. This can only be called if the mutex is held by the
calling thread. If this is not the case, a @code{permission_error}
exception is raised.

@item mutex_unlock_all
@findex mutex_unlock_all/0
@snindex mutex_unlock_all/0
@cnindex mutex_unlock_all/0
Unlock all mutexes held by the current thread.  This call is especially
useful to handle thread-termination using @code{abort/0} or exceptions.  See
also @code{thread_signal/2}.

@item current_mutex(?@var{MutexId}, ?@var{ThreadId}, ?@var{Count})
@findex current_mutex/3
@snindex current_mutex/3
@cnindex current_mutex/3
Enumerates all existing mutexes.  If the mutex is held by some thread,
@var{ThreadId} is unified with the identifier of the holding thread and
@var{Count} with the recursive count of the mutex. Otherwise,
@var{ThreadId} is @code{[]} and @var{Count} is 0.
@end table


@node Parallelism, Tabling, Threads, Extensions
@section Parallelism

@cindex parallelism
@cindex or-parallelism
There has been a sizeable amount of work on an or-parallel
implementation for YAP, called @strong{YAPOr}. Most of this work has
been performed by Ricardo Rocha. In this system parallelism is exploited
implicitly by running several alternatives in or-parallel. This option
can be enabled from the @code{configure} script or by checking the
system's @code{Makefile}.

@strong{YAPOr} is still a very experimental system, going through rapid
development. The following restrictions are of note:

@itemize @bullet
@item @strong{YAPOr} currently only supports the Linux/X86 and SPARC/Solaris
platforms. Porting to other Unix-like platforms should be straightforward.

@item @strong{YAPOr} does not support parallel updates to the
data-base.

@item @strong{YAPOr} does not support opening or closing of streams during
parallel execution.

@item Garbage collection and stack shifting are not supported in
@strong{YAPOr}.  

@item Built-ins that cause side-effects can only be executed when
left-most in the search-tree. There are no primitives to provide
asynchronous or cavalier execution of these built-ins, as in Aurora or
Muse.

@item YAP does not support voluntary suspension of work.
@end itemize

We expect that some of these restrictions will be removed in future
releases.

@node Tabling, Low Level Tracing, Parallelism , Extensions
@section Tabling
@cindex tabling

@strong{YAPTab} is the tabling engine that extends YAP's execution
model to support tabled evaluation for definite programs. YAPTab was
implemented by Ricardo Rocha and its implementation is largely based
on the ground-breaking design of the XSB Prolog system, which
implements the SLG-WAM. Tables are implemented using tries and YAPTab
supports the dynamic intermixing of batched scheduling and local
scheduling at the subgoal level. Currently, the following restrictions
are of note:
@itemize @bullet
@item YAPTab does not handle tabled predicates with loops through negation (undefined behaviour).
@item YAPTab does not handle tabled predicates with cuts (undefined behaviour).
@item YAPTab does not support coroutining (configure error).
@item YAPTab does not support tabling dynamic predicates (permission error).
@end itemize

To experiment with YAPTab use @code{--enable-tabling} in the configure
script or add @code{-DTABLING} to @code{YAP_EXTRAS} in the system's
@code{Makefile}. We next describe the set of built-ins predicates
designed to interact with YAPTab and control tabled execution:

@table @code
@item table +@var{P}
@findex table/1
@snindex table/1
@cnindex table/1
Declares predicate @var{P} (or a list of predicates
@var{P1},...,@var{Pn} or [@var{P1},...,@var{Pn}]) as a tabled
predicate. @var{P} must be written in the form
@var{name/arity}. Examples:
@example
:- table son/3.
:- table father/2.
:- table mother/2.
@end example
@noindent or
@example
:- table son/3, father/2, mother/2.
@end example
@noindent or
@example
:- table [son/3, father/2, mother/2].
@end example

@item is_tabled(+@var{P})
@findex is_tabled/1
@snindex is_tabled/1
@cnindex is_tabled/1
Succeeds if the predicate @var{P} (or a list of predicates
@var{P1},...,@var{Pn} or [@var{P1},...,@var{Pn}]), of the form
@var{name/arity}, is a tabled predicate.

@item tabling_mode(+@var{P},?@var{Mode})
@findex tabling_mode/2
@snindex tabling_mode/2
@cnindex tabling_mode/2
Sets or reads the default tabling mode for a tabled predicate @var{P}
(or a list of predicates @var{P1},...,@var{Pn} or
[@var{P1},...,@var{Pn}]). The list of @var{Mode} options includes:
@table @code
@item batched
      Defines that, by default, batched scheduling is the scheduling
      strategy to be used to evaluated calls to predicate @var{P}.
@item local
      Defines that, by default, local scheduling is the scheduling
      strategy to be used to evaluated calls to predicate @var{P}.
@item exec_answers
      Defines that, by default, when a call to predicate @var{P} is
      already evaluated (completed), answers are obtained by executing
      compiled WAM-like code directly from the trie data
      structure. This reduces the loading time when backtracking, but
      the order in which answers are obtained is undefined.
@item load_answers
      Defines that, by default, when a call to predicate @var{P} is
      already evaluated (completed), answers are obtained (as a
      consumer) by loading them from the trie data structure. This
      guarantees that answers are obtained in the same order as they
      were found. Somewhat less efficient but creates less choice-points.
@end table
The default tabling mode for a new tabled predicate is @code{batched}
and @code{exec_answers}. To set the tabling mode for all predicates at
once you can use the @code{yap_flag/2} predicate as described next.

@item yap_flag(tabling_mode,?@var{Mode})
@findex tabling_mode (yap_flag/2 option)
Sets or reads the tabling mode for all tabled predicates. The list of
@var{Mode} options includes:
@table @code
@item default
      Defines that (i) all calls to tabled predicates are evaluated
      using the predicate default mode, and that (ii) answers for all
      completed calls are obtained by using the predicate default mode.
@item batched
      Defines that all calls to tabled predicates are evaluated using
      batched scheduling. This option ignores the default tabling mode
      of each predicate.
@item local
      Defines that all calls to tabled predicates are evaluated using
      local scheduling. This option ignores the default tabling mode
      of each predicate.
@item exec_answers
      Defines that answers for all completed calls are obtained by
      executing compiled WAM-like code directly from the trie data
      structure. This option ignores the default tabling mode
      of each predicate.
@item load_answers
      Defines that answers for all completed calls are obtained by
      loading them from the trie data structure. This option ignores
      the default tabling mode of each predicate.
@end table

@item abolish_table(+@var{P})
@findex abolish_table/1
@snindex abolish_table/1
@cnindex abolish_table/1
Removes all the entries from the table space for predicate @var{P} (or
a list of predicates @var{P1},...,@var{Pn} or
[@var{P1},...,@var{Pn}]). The predicate remains as a tabled predicate.

@item abolish_all_tables/0
@findex abolish_all_tables/0
@snindex abolish_all_tables/0
@cnindex abolish_all_tables/0
Removes all the entries from the table space for all tabled
predicates. The predicates remain as tabled predicates.

@item show_table(+@var{P})
@findex show_table/1
@snindex show_table/1
@cnindex show_table/1
Prints table contents (subgoals and answers) for predicate @var{P}
(or a list of predicates @var{P1},...,@var{Pn} or
[@var{P1},...,@var{Pn}]).

@item table_statistics(+@var{P})
@findex table_statistics/1
@snindex table_statistics/1
@cnindex table_statistics/1
Prints table statistics (subgoals and answers) for predicate @var{P}
(or a list of predicates @var{P1},...,@var{Pn} or
[@var{P1},...,@var{Pn}]).

@item tabling_statistics/0
@findex tabling_statistics/0
@snindex tabling_statistics/0
@cnindex tabling_statistics/0
Prints statistics on space used by all tables.
@end table


@node Low Level Tracing, Low Level Profiling, Tabling, Extensions
@section Tracing at Low Level

It is possible to follow the flow at abstract machine level if
YAP is compiled with the flag @code{LOW_LEVEL_TRACER}. Note
that this option is of most interest to implementers, as it quickly generates
an huge amount of information.

Low level tracing can be toggled from an interrupt handler by using the
option @code{T}. There are also two built-ins that activate and
deactivate low level tracing:

@table @code
@item start_low_level_trace
@findex start_low_level_trace/0
@snindex start_low_level_trace/0
@cnindex start_low_level_trace/0
Begin display of messages at procedure entry and retry.

@item stop_low_level_trace
@findex stop_low_level_trace/0
@snindex stop_low_level_trace/0
@cnindex stop_low_level_trace/0
Stop display of messages at procedure entry and retry.
@end table

Note that this compile-time option will slow down execution.

@node Low Level Profiling, , Low Level Tracing, Extensions
@section Profiling the Abstract Machine

Implementors may be interested in detecting on which abstract machine
instructions are executed by a program. The @code{ANALYST} flag can give
WAM level information. Note that this option slows down execution very
substantially, and is only of interest to developers of the system
internals, or to system debuggers.

@table @code
@item reset_op_counters
@findex reset_op_counters/0
@snindex reset_op_counters/0
@cnindex reset_op_counters/0
Reinitialize all counters.

@item show_op_counters(+@var{A})
@findex show_op_counters/1
@snindex show_op_counters/1
@cnindex show_op_counters/1
Display the current value for the counters, using label @var{A}. The
label must be an atom.

@item show_ops_by_group(+@var{A})
@findex show_ops_by_group/1
@snindex show_ops_by_group/1
@cnindex show_ops_by_group/1
Display the current value for the counters, organized by groups, using
label @var{A}. The label must be an atom.

@end table

@node Debugging,Efficiency,Extensions,Top 
@section Debugging

@menu
* Deb Preds:: Debugging Predicates
* Deb Interaction:: Interacting with the debugger
@end menu

@node Deb Preds, Deb Interaction, , Debugging
@section Debugging Predicates

The following predicates are available to control the debugging of
programs:

@table @code
@item debug
@findex debug/0
@saindex debug/0
@cyindex debug/0
Switches the debugger on.

@item debugging
@findex debugging/0
@syindex debugging/0
@cyindex debugging/0
Outputs status information about the debugger which includes the leash
mode and the existing spy-points, when the debugger is on.

@item nodebug
@findex nodebug/0
@syindex nodebug/0
@cyindex nodebug/0
Switches the debugger off.

@item spy +@var{P}
@findex spy/1
@syindex spy/1
@cyindex spy/1
 Sets spy-points on all the predicates represented by
@var{P}. @var{P} can either be a single specification or a list of 
specifications. Each one must be of the form @var{Name/Arity} 
or @var{Name}. In the last case all predicates with the name 
@var{Name} will be spied. As in C-Prolog, system predicates and 
predicates written in C, cannot be spied.

@item nospy +@var{P}
@findex nospy/1
@syindex nospy/1
@cyindex nospy/1
 Removes spy-points from all predicates specified by @var{P}.
The possible forms for @var{P} are the same as in @code{spy P}.

@item nospyall
@findex nospyall/0
@syindex nospyall/0
@cnindex nospyall/0
Removes all existing spy-points.

@item leash(+@var{M})
@findex leash/1
@syindex leash/1
@cyindex leash/1
 Sets leashing mode to @var{M}.
The mode can be specified as:
@table @code
@item full
prompt on Call, Exit, Redo and Fail
@item tight
prompt on Call, Redo and Fail
@item half
prompt on Call and Redo
@item loose
prompt on Call
@item off
never prompt
@item none
never prompt, same as @code{off}
@end table
@noindent
The initial leashing mode is @code{full}.


@noindent
The user may also specify directly the debugger ports 
where he wants to be prompted. If the argument for leash 
is a number @var{N}, each of lower four bits of the number is used to
control prompting at one the ports of the box model. The debugger will 
prompt according to the following conditions:

@itemize @bullet
@item
if @code{N/\ 1 =\= 0}  prompt on fail 
@item
if @code{N/\ 2 =\= 0} prompt on redo
@item
if @code{N/\ 4 =\= 0} prompt on exit
@item
if @code{N/\ 8 =\= 0} prompt on call
@end itemize
@noindent
Therefore, @code{leash(15)} is equivalent to @code{leash(full)} and
@code{leash(0)} is equivalent to @code{leash(off)}.

@noindent
Another way of using @code{leash} is to give it a list with the names of
the ports where the debugger should stop. For example,
@code{leash([call,exit,redo,fail])} is the same as @code{leash(full)} or
@code{leash(15)} and @code{leash([fail])} might be used instead of
@code{leash(1)}.

@item spy_write(+@var{Stream},Term)
@findex spy_write/2
@snindex spy_write/2
@cnindex spy_write/2
If defined by the user, this predicate will be used to print goals by
the debugger instead of @code{write/2}.

@item trace
@findex trace/0
@syindex trace/0
@cyindex trace/0
Switches on the debugger and starts tracing.

@item notrace
@findex notrace/0
@syindex notrace/0
@cyindex notrace/0
Ends tracing and exits the debugger. This is the same as
@code{nodebug/0}.

@end table


@node Deb Interaction, , Deb Preds, Debugging
@section Interacting with the debugger

Debugging with YAP is similar to debugging with C-Prolog. Both systems
include a procedural debugger, based on Byrd's four port model. In this
model, execution is seen at the procedure level: each activation of a
procedure is seen as a box with control flowing into and out of that
box.

 In the four port model control is caught at four key points: before 
entering the procedure, after exiting the procedure (meaning successful 
evaluation of all queries activated by the procedure), after backtracking but 
before trying new alternative to the procedure and after failing the 
procedure. Each one of these points is named a port:

@smallexample
@group
           *--------------------------------------*
   Call    |                                      |    Exit
---------> +  descendant(X,Y) :- offspring(X,Y).  + --------->
           |                                      |
           |  descendant(X,Z) :-                  |
<--------- +     offspring(X,Y), descendant(Y,Z). + <---------
   Fail    |                                      |    Redo
           *--------------------------------------*
@end group
@end smallexample

@table @code

@item Call
The call port is activated before initial invocation of
procedure. Afterwards, execution will try to match the goal with the
head of existing clauses for the procedure.
@item Exit
This port is activated if the procedure succeeds.
Control will  now leave the procedure and return to its ancestor.
@item Redo
if the goal, or goals, activated after the call port
fail  then backtracking will eventually return control to this procedure
through  the redo port.
@item Fail
If all clauses for this predicate fail, then the
invocation fails,  and control will try to redo the ancestor of this
invocation.
@end table

To start debugging, the user will either call @code{trace} or spy the
relevant procedures, entering debug mode, and start execution of the
program. When finding the first spy-point, YAP's debugger will take
control and show a message of the form:

@example
* (1)  call:  quicksort([1,2,3],_38) ?
@end example

 The debugger message will be shown while creeping, or at spy-points,
and it includes four or five fields:

@itemize @bullet
@item
 The first three characters are used to point out special states of the
debugger. If the port is exit and the first character is '?', the
current call is non-deterministic, that is, it still has alternatives to
be tried. If the second character is a @code{*}, execution is at a
spy-point. If the third character is a @code{>}, execution has returned
either from a skip, a fail or a redo command.
@item
 The second field is the activation number, and uniquely identifies the
activation. The number will start from 1 and will be incremented for
each activation found by the debugger.
@item
 In the third field, the debugger shows the active port.
@item
 The fourth field is the goal. The goal is written by
 @code{write_term/3} on the standard error stream, using the options
 given by @code{debugger_print_options}.
@end itemize

 If the active port is leashed, the debugger will prompt the user with a
@code{?}, and wait for a command. A debugger command is just a
character, followed by a return. By default, only the call and redo
entries are leashed, but the @code{leash/1} predicate can be used in
order to make the debugger stop where needed.

 There are several commands available, but the user only needs to 
remember the help command, which is @code{h}. This command shows all the 
available options, which are:
@table @code
@item c - creep
this command makes YAP continue execution and stop at the next
leashed port.
@item return - creep
the same as c
@item l - leap
YAP will execute until it meets a port for a spied predicate; this mode
keeps all computation history for debugging purposes, so it is more
expensive than standard execution. Use @t{k} or @t{z} for fast execution.
@item k - quasi-leap
similar to leap but faster since the computation history is
not kept; useful when leap becomes too slow.
@item z - zip
same as @t{k}
@item s - skip
YAP will continue execution without showing any messages until
returning to the current activation. Spy-points will be  ignored in this
mode. Note that this command keeps all debugging history, use @t{t} for fast execution. This command is meaningless, and therefore illegal, in the fail
and exit ports.
@item t - fast-skip
similar to skip but faster since computation history is not
kept; useful if skip becomes slow.
@item f [@var{GoalId}] - fail
If given no argument, forces YAP to fail the goal, skipping the fail
port and backtracking to the parent. 
 If @t{f} receives a goal number as
the argument, the command fails all the way to the goal. If goal @var{GoalId} has completed execution, YAP fails until meeting the first active ancestor.
@item r [@var{GoalId}] - retry
This command forces YAP to jump back call to the port. Note that any
side effects of the goal cannot be undone. This command is not available
at the call port.  If @t{f} receives a goal number as the argument, the
command retries goal @var{GoalId} instead. If goal @var{GoalId} has
completed execution, YAP fails until meeting the first active ancestor.
    
@item a - abort
execution will be aborted, and the interpreter will return to the
top-level. YAP disactivates debug mode, but spypoints are not removed.
@item n - nodebug
stop debugging and continue execution. The command will not clear active
spy-points.
@item e - exit
leave YAP.
@item h - help
show the debugger commands.
@item ! Query
execute a query. YAP will not show the result of the query.
@item b - break
break active execution and launch a break level. This is  the same as @code{!break}.
@item + - spy this goal
start spying the active goal. The same as @code{! spy  G} where @var{G}
is the active goal.
@item - - nospy this goal
stop spying the active goal. The same as @code{! nospy G} where @var{G} is
the active goal.
@item p - print
shows the active goal using print/1
@item d - display
shows the active goal using display/1
@item <Depth - debugger write depth
sets the maximum write depth, both for composite terms and lists, that
will be used by the debugger. For more
information about @code{write_depth/2} (@pxref{Input/Output Control}).
@item < - full term
resets to the default of ten the debugger's maximum write depth. For
more information about @code{write_depth/2} (@pxref{Input/Output Control}).
@item A - alternatives
 show the list of backtrack points in the current execution. 
@item g [@var{N}] 
 show the list of ancestors in the current debugging environment. If it
 receives @var{N}, show the first @var{N} ancestors.
@end table

The debugging information, when fast-skip @code{quasi-leap} is used, will
be lost.

@node Efficiency, C-Interface, Debugging, Top

@chapter Efficiency Considerations

We next discuss several issues on trying to make Prolog programs run
fast in YAP. We assume two different programming styles:

@itemize @bullet
@item Execution of @emph{deterministic} programs often
boils down to a recursive loop of the form:
@example
loop(Env) :-
        do_something(Env,NewEnv),
        loop(NewEnv).
@end example

@end itemize

@c @section Deterministic Programs

@c @section Non-Deterministic Programs

@c @section Data-Base Operations

@section Indexing

The indexation mechanism restricts the set of clauses to be tried in a
procedure by using information about the status of the instantiated
arguments of the goal.  These arguments are then used as a key,
selecting a restricted set of a clauses from all the clauses forming the
procedure.

As an example, the two clauses for concatenate:

@example
concatenate([],L,L).
concatenate([H|T],A,[H|NT]) :- concatenate(T,A,NT).
@end example

If the first argument for the goal is a list, then only the second clause 
is of interest. If the first argument is the nil atom, the system needs to 
look only for the first clause. The indexation generates instructions that 
test the value of the first argument, and then proceed to a selected clause, 
or group of clauses.

Note that if the first argument was a free variable, then both clauses 
should be tried. In general, indexation will not be useful if the first 
argument is a free variable.

When activating a predicate, a Prolog system needs to store state 
information. This information, stored in a structure known as choice point 
or fail point, is necessary when backtracking to other clauses for the 
predicate. The operations of creating and using a choice point are very 
expensive, both in the terms of space used and time spent.
Creating a choice point is not necessary if there is only a clause for 
the predicate as there are no clauses to backtrack to. With indexation, this 
situation is extended: in the example, if the first argument was the atom 
nil, then only one clause would really be of interest, and it is pointless to 
create a choice point. This feature is even more useful if the first argument 
is a list: without indexation, execution would try the first clause, creating 
a choice point. The clause would fail, the choice point would then be used to 
restore the previous state of the computation and the second clause would 
be tried. The code generated by the indexation mechanism would behave 
much more efficiently: it would test the first argument and see whether it 
is a list, and then proceed directly to the second clause.

An important side effect concerns the use of "cut". In the above 
example, some programmers would use a "cut" in the first clause just to 
inform the system that the predicate is not backtrackable and force the 
removal the choice point just created. As a result, less space is needed but 
with a great loss in expressive power: the "cut" would prevent some uses of 
the procedure, like generating lists through backtracking. Of course, with 
indexation the "cut" becomes useless: the choice point is not even created.

Indexation is also very important for predicates with a large number 
of clauses that are used like tables:

@example
logician(aristoteles,greek).
logician(frege,german).
logician(russel,english).
logician(godel,german).
logician(whitehead,english).
@end example

An interpreter like C-Prolog, trying to answer the query:

@example
?- logician(godel,X).
@end example

@noindent
would blindly follow the standard Prolog strategy, trying first the
first clause, then the second, the third and finally finding the
relevant clause.  Also, as there are some more clauses after the
important one, a choice point has to be created, even if we know the
next clauses will certainly fail. A "cut" would be needed to prevent
some possible uses for the procedure, like generating all logicians.  In
this situation, the indexing mechanism generates instructions that
implement a search table. In this table, the value of the first argument
would be used as a key for fast search of possibly matching clauses. For
the query of the last example, the result of the search would be just
the fourth clause, and again there would be no need for a choice point.

 If the first argument is a complex term, indexation will select clauses
just by testing its main functor. However, there is an important
exception: if the first argument of a clause is a list, the algorithm
also uses the list's head if not a variable. For instance, with the
following clauses,

@example
rules([],B,B).
rules([n(N)|T],I,O) :- rules_for_noun(N,I,N), rules(T,N,O).
rules([v(V)|T],I,O) :- rules_for_verb(V,I,N), rules(T,N,O).
rules([q(Q)|T],I,O) :- rules_for_qualifier(Q,I,N), rules(T,N,O).
@end example
@noindent
if the first argument of the goal is a list, its head will be tested, and only 
the clauses matching it will be tried during execution.

Some advice on how to take a good advantage of this mechanism:

@itemize @bullet

@item
 Try to make the first argument an input argument.

@item
 Try to keep together all clauses whose first argument is not a 
variable, that will decrease the number of tests since the other clauses are 
always tried.

@item
 Try to avoid predicates having a lot of clauses with the same key. 
For instance, the procedure:

@end itemize

@example
type(n(mary),person).
type(n(john), person).
type(n(chair),object).
type(v(eat),active).
type(v(rest),passive).
@end example

@noindent
 becomes more efficient with:

@example
type(n(N),T) :- type_of_noun(N,T).
type(v(V),T) :- type_of_verb(V,T).

type_of_noun(mary,person).
type_of_noun(john,person).
type_of_noun(chair,object).

type_of_verb(eat,active).
type_of_verb(rest,passive).
@end example

@node C-Interface,YAPLibrary,Efficiency,Top
@chapter C Language interface to YAP

YAP provides the user with three facilities for writing
predicates in a language other than Prolog. Under Unix systems,
most language implementations were linkable to @code{C}, and the first interface exported  the YAP machinery to the C language. YAP also implements most of the SWI-Prolog foreign language interface.
This gives portability with a number of SWI-Prolog packages. Last, a new C++ based interface is 
being designed to work with the swig (@url(www.swig.org}) interface compiler.

@ifplaintext
<ul>
<li> The original YAP C-interface exports the YAP engine.
</li>
<li>The @ref swi-c-interface emulates Jan Wielemaker's SWI foreign language interface.
</li>
<li>The @ref  yap-cplus-interface is desiged to interface with Object-Oriented systems.
</li>
</ul>
@end ifplaintext

Before describing in full detail how to interface to C code, we will examine 
a brief example.

Assume the user requires a predicate @code{my_process_id(Id)} which succeeds
when @var{Id} unifies with the number of the process under which YAP is running.

In this case we will create a @code{my_process.c} file containing the
C-code described below.

@c_example
@cartouche
#include "YAP/YapInterface.h"

static int my_process_id(void) 
@{
     YAP_Term pid = YAP_MkIntTerm(getpid());
     YAP_Term out = YAP_ARG1;
     return(YAP_Unify(out,pid));
@}

void init_my_predicates()
@{
     YAP_UserCPredicate("my_process_id",my_process_id,1);
@}
@end cartouche
@end c_example

The commands to compile the above file depend on the operating
system. Under Linux (i386 and Alpha) you should use:
@example
      gcc -c -shared -fPIC my_process.c
      ld -shared -o my_process.so my_process.o
@end example
@noindent
Under WIN32 in a MINGW/CYGWIN environment, using the standard
installation path you should use:
@example
      gcc -mno-cygwin  -I "c:/Yap/include" -c my_process.c
      gcc -mno-cygwin "c:/Yap/bin/yap.dll" --shared -o my_process.dll my_process.o
@end example
@noindent
Under WIN32 in a pure CYGWIN environment, using the standard
installation path, you should use:
@example
      gcc -I/usr/local -c my_process.c
      gcc -shared -o my_process.dll my_process.o /usr/local/bin/yap.dll
@end example
@noindent
Under Solaris2 it is sufficient to use:
@example
      gcc  -fPIC -c my_process.c
@end example
@noindent
Under SunOS it is sufficient to use:
@example
      gcc -c my_process.c
@end example
@noindent
Under Digital Unix you need to create a @code{so} file. Use:
@example
      gcc tst.c -c -fpic
      ld my_process.o -o my_process.so -shared -expect_unresolved '*'
@end example
@noindent
and replace my @code{process.so} for my @code{process.o} in the
remainder of the example.
@noindent
And could be loaded, under YAP, by executing the following Prolog goal
@example
      load_foreign_files(['my_process'],[],init_my_predicates).
@end example
Note that since YAP4.3.3 you should not give the suffix for object
files. YAP will deduce the correct suffix from the operating system it
is running under.

After loading that file the following Prolog goal
@example
       my_process_id(N)
@end example
@noindent
would unify N with the number of the process under which YAP is running.


Having presented a full example, we will now examine in more detail the
contents of the C source code file presented above.

The include statement is used to make available to the C source code the
macros for the handling of Prolog terms and also some YAP public
definitions.

The function @code{my_process_id} is the implementation, in C, of the
desired predicate.  Note that it returns an integer denoting the success
of failure of the goal and also that it has no arguments even though the
predicate being defined has one.
 In fact the arguments of a Prolog predicate written in C are accessed
through macros, defined in the include file, with names @var{YAP_ARG1},
@var{YAP_ARG2}, ..., @var{YAP_ARG16} or with @var{YAP_A}(@var{N})
where @var{N} is the argument number (starting with 1).  In the present
case the function uses just one local variable of type @code{YAP_Term}, the
type used for holding YAP terms, where the integer returned by the
standard unix function @code{getpid()} is stored as an integer term (the
conversion is done by @code{YAP_MkIntTerm(Int))}. Then it calls the
pre-defined routine @code{YAP_Unify(YAP_Term, YAP_Term)} which in turn returns an
integer denoting success or failure of the unification.

@findex YAP_UserCPredicate
The role of the procedure @code{init_my_predicates} is to make known to
YAP, by calling @code{YAP_UserCPredicate}, the predicates being
defined in the file.  This is in fact why, in the example above,
@code{init_my_predicates} was passed as the third argument to
@code{load_foreign_files/3}.

The rest of this appendix describes exhaustively how to interface C to YAP.

@menu
* Manipulating Terms:: Primitives available to the C programmer
* Unifying Terms:: How to Unify Two Prolog Terms
* Manipulating Strings:: From character arrays to Lists of codes and back
* Memory Allocation:: Stealing Memory From YAP
* Controlling Streams:: Control How YAP sees Streams
* Utility Functions:: From character arrays to Lists of codes and back
* Calling YAP From C:: From C to YAP to C to YAP 
* Module Manipulation in C:: Create and Test Modules from within C
* Miscellaneous C-Functions:: Other Helpful Interface Functions
* Writing C:: Writing Predicates in C
* Loading Objects:: Loading Object Files
* Save&Rest:: Saving and Restoring
* YAP4 Notes:: Changes in Foreign Predicates Interface
@end menu

@node Manipulating Terms, Unifying Terms, , C-Interface
@section Terms

This section provides information about the primitives available to the C
programmer for manipulating Prolog terms.

Several C typedefs are included in the header file @code{yap/YAPInterface.h} to
describe, in a portable way, the C representation of Prolog terms.
The user should write is programs using this macros to ensure portability of
code across different versions of YAP.


The more important typedef is @var{YAP_Term} which is used to denote the
type of a Prolog term.

Terms, from a point of view of the C-programmer,  can be classified as
follows
@table @i
@item    uninstantiated variables
@item    instantiated variables
@item    integers
@item    floating-point numbers
@item    database references
@item    atoms
@item    pairs (lists)
@item    compound terms
@end table

The primitive
@table @code
@item     YAP_Bool YAP_IsVarTerm(YAP_Term @var{t})
@findex YAP_IsVarTerm (C-Interface function)
@noindent
returns true iff its argument is an uninstantiated variable. Conversely the
primitive
@item     YAP_Bool YAP_NonVarTerm(YAP_Term @var{t})
@findex YAP_IsNonVarTerm (C-Interface function)
returns true iff its argument is not a variable.
@end table 
@noindent 


The user can create a new uninstantiated variable using the primitive
@table @code
 @item     YAP_Term  YAP_MkVarTerm()
@end table


The following primitives can be used to discriminate among the different types
of non-variable terms:
@table @code
@item      YAP_Bool YAP_IsIntTerm(YAP_Term @var{t})
@findex YAP_IsIntTerm (C-Interface function)
@item      YAP_Bool YAP_IsFloatTerm(YAP_Term @var{t})
@findex YAP_IsFloatTerm (C-Interface function)
@item      YAP_Bool YAP_IsDbRefTerm(YAP_Term @var{t})
@findex YAP_IsDBRefTerm (C-Interface function)
@item      YAP_Bool YAP_IsAtomTerm(YAP_Term @var{t})
@findex YAP_IsAtomTerm (C-Interface function)
@item      YAP_Bool YAP_IsPairTerm(YAP_Term @var{t})
@findex YAP_IsPairTerm (C-Interface function)
@item     YAP_Bool YAP_IsApplTerm(YAP_Term @var{t})
@findex YAP_IsApplTerm (C-Interface function)
@item      YAP_Bool YAP_IsCompoundTerm(YAP_Term @var{t})
@findex YAP_IsCompoundTerm (C-Interface function)
@end table


The next primitive gives the type of a Prolog term:
@table @code
@item      YAP_tag_t YAP_TagOfTerm(YAP_Term @var{t})
@end table
The set of possible values is an enumerated type, with the following values:
@table @i
@item  @code{YAP_TAG_ATT}: an attributed variable
@item  @code{YAP_TAG_UNBOUND}: an unbound variable
@item  @code{YAP_TAG_REF}: a reference to a term
@item  @code{YAP_TAG_PAIR}: a list
@item  @code{YAP_TAG_ATOM}: an atom
@item  @code{YAP_TAG_INT}: a small integer
@item  @code{YAP_TAG_LONG_INT}: a word sized integer
@item  @code{YAP_TAG_BIG_INT}: a very large integer
@item  @code{YAP_TAG_RATIONAL}: a rational number
@item  @code{YAP_TAG_FLOAT}: a floating point number
@item  @code{YAP_TAG_OPAQUE}: an opaque term
@item  @code{YAP_TAG_APPL}: a compound term
@end table


Next, we mention the primitives that allow one to destruct and construct
terms. All the above primitives ensure that their result is
@i{dereferenced}, i.e. that it is not a pointer to another term.

The following primitives are provided for creating an integer term from an
integer and to access the value of an integer term.
@table @code
@item      YAP_Term YAP_MkIntTerm(YAP_Int  @var{i})
@findex YAP_MkIntTerm (C-Interface function)
@item     YAP_Int  YAP_IntOfTerm(YAP_Term @var{t})
@findex YAP_IntOfTerm (C-Interface function)
@end table
@noindent
where @code{YAP_Int} is a typedef for the C integer type appropriate for
the machine or compiler in question (normally a long integer). The size
of the allowed integers is implementation dependent but is always
greater or equal to 24 bits: usually 32 bits on 32 bit machines, and 64
on 64 bit machines.

The two following primitives play a similar role for floating-point terms
@table @code
@item      YAP_Term YAP_MkFloatTerm(YAP_flt @var{double})
@findex YAP_MkFloatTerm (C-Interface function)

@item     YAP_flt  YAP_FloatOfTerm(YAP_Term @var{t})
@findex YAP_FloatOfTerm (C-Interface function)
@end table
@noindent
where @code{flt} is a typedef for the appropriate C floating point type,
nowadays a @code{double}

The following primitives are provided for verifying whether a term is
a big int, creating a term from a big integer and to access the value
of a big int from a term.
@table @code
@item      YAP_Bool YAP_IsBigNumTerm(YAP_Term @var{t})
@findex YAP_IsBigNumTerm (C-Interface function)
@item      YAP_Term YAP_MkBigNumTerm(void  *@var{b})
@findex YAP_MkBigNumTerm (C-Interface function)
@item      void *YAP_BigNumOfTerm(YAP_Term @var{t}, void *@var{b})
@findex YAP_BigNumOfTerm (C-Interface function)
@end table
@noindent
YAP must support bignum for the configuration you are using (check the
YAP configuration and setup). For now, YAP only supports the GNU GMP
library, and @code{void *} will be a cast for @code{mpz_t}. Notice
that @code{YAP_BigNumOfTerm} requires the number to be already
initialised. As an example, we show how to print a bignum:

@example
static int
p_print_bignum(void)
@{
  mpz_t mz;
  if (!YAP_IsBigNumTerm(YAP_ARG1))
    return FALSE;

  mpz_init(mz);
  YAP_BigNumOfTerm(YAP_ARG1, mz);
  gmp_printf("Shows up as %Zd\n", mz);
  mpz_clear(mz);
  return TRUE;
@}
@end example


Currently, no primitives are supplied to users for manipulating data base
references. 

A special typedef @code{YAP_Atom} is provided to describe Prolog
@i{atoms} (symbolic constants). The two following primitives can be used
to manipulate atom terms
@table @code
 @item     YAP_Term YAP_MkAtomTerm(YAP_Atom at)
@findex YAP_MkAtomTerm (C-Interface function)
 @item     YAP_Atom YAP_AtomOfTerm(YAP_Term @var{t})
@findex YAP_AtomOfTerm (C-Interface function)
@end table
@noindent
The following primitives are available for associating atoms with their
names 
@table @code
 @item     YAP_Atom  YAP_LookupAtom(char * @var{s})
@findex YAP_LookupAtom (C-Interface function)
 @item     YAP_Atom  YAP_FullLookupAtom(char * @var{s})
@findex YAP_FullLookupAtom (C-Interface function)
 @item     char     *YAP_AtomName(YAP_Atom @var{t})
@findex YAP_AtomName (C-Interface function)
@end table
The function @code{YAP_LookupAtom} looks up an atom in the standard hash
table. The function @code{YAP_FullLookupAtom} will also search if the
atom had been "hidden": this is useful for system maintenance from C
code. The functor @code{YAP_AtomName} returns a pointer to the string
for the atom.

@noindent
The following primitives handle constructing atoms from strings with
wide characters, and vice-versa:
@table @code
  @item    YAP_Atom  YAP_LookupWideAtom(wchar_t * @var{s})
@findex YAP_LookupWideAtom (C-Interface function)
   @item   wchar_t  *YAP_WideAtomName(YAP_Atom @var{t})
@findex YAP_WideAtomName (C-Interface function)
@end table

@noindent
The following primitive tells whether an atom needs wide atoms in its
representation:
@table @code
@item      int  YAP_IsWideAtom(YAP_Atom @var{t})
@findex YAP_IsIsWideAtom (C-Interface function)
@end table

@noindent
The following primitive can be used to obtain the size of an atom in a
representation-independent way: 
@table @code
 @item     int      YAP_AtomNameLength(YAP_Atom @var{t})
@findex YAP_AtomNameLength (C-Interface function)
@end table

The next routines give users some control over  the atom
garbage collector. They allow the user to guarantee that an atom is not
to be garbage collected (this is important if the atom is hold
externally to the Prolog engine, allow it to be collected, and call a
hook on garbage collection:
@table @code
  @item    int  YAP_AtomGetHold(YAP_Atom @var{at})
@findex YAP_AtomGetHold  (C-Interface function)
@item      int  YAP_AtomReleaseHold(YAP_Atom @var{at})
@findex YAP_AtomReleaseHold  (C-Interface function)
 @item     int  YAP_AGCRegisterHook(YAP_AGC_hook @var{f})
@findex YAP_AGCHook  (C-Interface function)
@end table

A @i{pair} is a Prolog term which consists of a tuple of two Prolog
terms designated as the @i{head} and the @i{tail} of the term. Pairs are
most often used to build @emph{lists}. The following primitives can be
used to manipulate pairs:
@table @code
 @item     YAP_Term  YAP_MkPairTerm(YAP_Term @var{Head}, YAP_Term @var{Tail})
@findex YAP_MkPairTerm (C-Interface function)
 @item     YAP_Term  YAP_MkNewPairTerm(void)
@findex YAP_MkNewPairTerm (C-Interface function)
  @item    YAP_Term  YAP_HeadOfTerm(YAP_Term @var{t})
@findex YAP_HeadOfTerm (C-Interface function)
 @item     YAP_Term  YAP_TailOfTerm(YAP_Term @var{t})
@findex YAP_TailOfTerm (C-Interface function)
  @item    YAP_Term  YAP_MkListFromTerms(YAP_Term *@var{pt}, YAP_Int *@var{sz})
@findex YAP_MkListFromTerms (C-Interface function)
@end table
One can construct a new pair from two terms, or one can just build a
pair whose head and tail are new unbound variables. Finally, one can
fetch the head or the tail.

The last function supports the common operation of constructing a list from an
array of terms of size @var{sz} in a simple sweep.

Notice that the list constructors can call the garbage collector if
there is not enough space in the global stack. 

A @i{compound} term consists of a @i{functor} and a sequence of terms with
length equal to the @i{arity} of the functor. A functor, described in C by
the typedef @code{Functor}, consists of an atom and of an integer.
The following primitives were designed to manipulate compound terms and 
functors
@table @code
@item      YAP_Term     YAP_MkApplTerm(YAP_Functor @var{f}, unsigned long int @var{n}, YAP_Term[] @var{args})
@findex YAP_MkApplTerm (C-Interface function)
@item      YAP_Term     YAP_MkNewApplTerm(YAP_Functor @var{f}, int @var{n})
@findex YAP_MkNewApplTerm (C-Interface function)
@item      YAP_Term     YAP_ArgOfTerm(int argno,YAP_Term @var{ts})
@findex YAP_ArgOfTerm (C-Interface function)
 @item     YAP_Term    *YAP_ArgsOfTerm(YAP_Term @var{ts})
@findex YAP_ArgsOfTerm (C-Interface function)
 @item     YAP_Functor  YAP_FunctorOfTerm(YAP_Term @var{ts})
@findex YAP_FunctorOfTerm (C-Interface function)
@end table
@noindent
The @code{YAP_MkApplTerm} function constructs a new term, with functor
@var{f} (of arity @var{n}), and using an array @var{args} of @var{n}
terms with @var{n} equal to the arity of the
functor. @code{YAP_MkNewApplTerm} builds up a compound term whose
arguments are unbound variables. @code{YAP_ArgOfTerm} gives an argument
to a compound term. @code{argno} should be greater or equal to 1 and
less or equal to the arity of the functor.  @code{YAP_ArgsOfTerm}
returns a pointer to an array of arguments.

Notice that the compound term constructors can call the garbage
collector if there is not enough space in the global stack.

YAP allows one to manipulate the functors of compound term. The function
@code{YAP_FunctorOfTerm} allows one to obtain a variable of type
@code{YAP_Functor} with the functor to a term. The following functions
then allow one to construct functors, and to obtain their name and arity. 

@findex YAP_MkFunctor (C-Interface function)
@findex YAP_NameOfFunctor (C-Interface function)
@findex YAP_ArityOfFunctor (C-Interface function)
@table @code
 @item     YAP_Functor  YAP_MkFunctor(YAP_Atom @var{a},unsigned long int @var{arity})
 @item     YAP_Atom     YAP_NameOfFunctor(YAP_Functor @var{f})
  @item    YAP_Int      YAP_ArityOfFunctor(YAP_Functor @var{f})
@end table
@noindent

Note that the functor is essentially a pair formed by an atom, and
arity.

Constructing terms in the stack may lead to overflow. The routine
@table @code
 @item     int          YAP_RequiresExtraStack(size_t @var{min})
@end table
verifies whether you have at least @var{min} cells free in the stack,
and it returns true if it has to ensure enough memory by calling the
garbage collector and or stack shifter. The routine returns false if no
memory is needed, and a negative number if it cannot provide enough
memory.

You can set @var{min} to zero if you do not know how much room you need
but you do know you do not need a big chunk at a single go. Usually, the routine
would usually be called together with a long-jump to restart the
code. Slots can also be used if there is small state.

@node Unifying Terms, Manipulating Strings, Manipulating Terms, C-Interface
@section Unification

@findex YAP_Unify (C-Interface function)
YAP provides a single routine to attempt the unification of two Prolog
terms. The routine may succeed or fail:
@table @code
 @item     Int      YAP_Unify(YAP_Term @var{a}, YAP_Term @var{b})
@end table
@noindent
The routine attempts to unify the terms @var{a} and
@var{b} returning @code{TRUE} if the unification succeeds and @code{FALSE}
otherwise.

@node Manipulating Strings, Memory Allocation, Unifying Terms, C-Interface
@section Strings

@findex YAP_StringToBuffer (C-Interface function)
The YAP C-interface now includes an utility routine to copy a string
represented as a list of a character codes to a previously allocated buffer
@table @code
 @item     int YAP_StringToBuffer(YAP_Term @var{String}, char *@var{buf}, unsigned int @var{bufsize})
@end table
@noindent
The routine copies the list of character codes @var{String} to a
previously allocated buffer @var{buf}. The string including a
terminating null character must fit in @var{bufsize} characters,
otherwise the routine will simply fail. The @var{StringToBuffer} routine
fails and generates an exception if @var{String} is not a valid string.

@findex YAP_BufferToString (C-Interface function)
@findex YAP_NBufferToString (C-Interface function)
@findex YAP_WideBufferToString (C-Interface function)
@findex YAP_NWideBufferToString (C-Interface function)
@findex YAP_BufferToAtomList (C-Interface function)
@findex YAP_NBufferToAtomList (C-Interface function)
@findex YAP_WideBufferToAtomList (C-Interface function)
@findex YAP_NWideBufferToAtomList (C-Interface function)
@findex YAP_BufferToDiffList (C-Interface function)
@findex YAP_NBufferToDiffList (C-Interface function)
@findex YAP_WideBufferToDiffList (C-Interface function)
@findex YAP_NWideBufferToDiffList (C-Interface function)
The C-interface also includes utility routines to do the reverse, that
is, to copy a from a buffer to a list of character codes, to a
difference list,  or to a list of
character atoms. The routines work either on strings of characters or
strings of wide characters:
@table @code
@item      YAP_Term YAP_BufferToString(char *@var{buf})
 @item     YAP_Term YAP_NBufferToString(char *@var{buf}, size_t @var{len})
@item      YAP_Term YAP_WideBufferToString(wchar_t *@var{buf})
@item      YAP_Term YAP_NWideBufferToString(wchar_t *@var{buf}, size_t @var{len})
@item      YAP_Term YAP_BufferToAtomList(char *@var{buf})
@item      YAP_Term YAP_NBufferToAtomList(char *@var{buf}, size_t @var{len})
@item      YAP_Term YAP_WideBufferToAtomList(wchar_t *@var{buf})
@item      YAP_Term YAP_NWideBufferToAtomList(wchar_t *@var{buf}, size_t @var{len})
@end table
@noindent
Users are advised to use the @var{N} version of the routines. Otherwise,
the user-provided string must include a terminating null character.

@findex YAP_ReadBuffer (C-Interface function)
The C-interface function calls the parser on a sequence of characters
stored at @var{buf} and returns the resulting term.
@table @code
 @item     YAP_Term YAP_ReadBuffer(char *@var{buf},YAP_Term *@var{error})
@end table
@noindent
The user-provided string must include a terminating null
character. Syntax errors will cause returning @code{FALSE} and binding
@var{error} to a Prolog term.

@findex YAP_IntsToList (C-Interface function)
@findex YAP_FloatsToList (C-Interface function)
These C-interface functions are useful when converting chunks of data to Prolog:
@table @code
@item      YAP_Term YAP_FloatsToList(double *@var{buf},size_t @var{sz})
@item      YAP_Term YAP_IntsToList(YAP_Int *@var{buf},size_t @var{sz})
@end table
@noindent
Notice that they are unsafe, and may call the garbage collector. They
return 0 on error.

@findex YAP_ListToInts (C-Interface function)
@findex YAP_ToListFloats (C-Interface function)
These C-interface functions are useful when converting Prolog lists to arrays:
@table @code
@item      YAP_Int YAP_IntsToList(YAP_Term t, YAP_Int *@var{buf},size_t @var{sz})
@item      YAP_Int YAP_FloatsToList(YAP_Term t, double *@var{buf},size_t @var{sz})
@end table
@noindent
They return the number of integers scanned, up to a maximum of @t{sz},
and @t{-1} on error.

@node Memory Allocation, Controlling Streams, Manipulating Strings, C-Interface
@section Memory Allocation

@findex YAP_AllocSpaceFromYAP (C-Interface function)
The next routine can be used to ask space from the Prolog data-base:
@table @code
 @item     void      *YAP_AllocSpaceFromYAP(int @var{size})
@end table
@noindent
The routine returns a pointer to a buffer allocated from the code area,
or @code{NULL} if sufficient space was not available.

@findex YAP_FreeSpaceFromYAP (C-Interface function)
The space allocated with @code{YAP_AllocSpaceFromYAP} can be released
back to YAP by using:
@table @code
 @item     void      YAP_FreeSpaceFromYAP(void *@var{buf})
@end table
@noindent
The routine releases a buffer allocated from the code area. The system
may crash if @code{buf} is not a valid pointer to a buffer in the code
area.

@node Controlling Streams, Utility Functions, Memory Allocation, C-Interface
@section Controlling YAP Streams from @code{C}

@findex YAP_StreamToFileNo (C-Interface function)
The C-Interface also provides the C-application with a measure of
control over the YAP Input/Output system. The first routine allows one
to find a file number given a current stream:
@table @code
 @item     int      YAP_StreamToFileNo(YAP_Term @var{stream})
@end table
@noindent
This function gives the file descriptor for a currently available
stream. Note that null streams and in memory streams do not have
corresponding open streams, so the routine will return a
negative. Moreover, YAP will not be aware of any direct operations on
this stream, so information on, say, current stream position, may become
stale.

@findex YAP_CloseAllOpenStreams (C-Interface function)
A second routine that is sometimes useful is:
@table @code
@item      void      YAP_CloseAllOpenStreams(void)
@end table
@noindent
This routine closes the YAP Input/Output system except for the first
three streams, that are always associated with the three standard Unix
streams. It is most useful if you are doing @code{fork()}.

@findex YAP_FlushAllStreams (C-Interface function)
Last, one may sometimes need to flush all streams:
@table @code
 @item     void      YAP_CloseAllOpenStreams(void)
@end table
@noindent
It is also useful before you do a @code{fork()}, or otherwise you may
have trouble with unflushed output.

@findex YAP_OpenStream (C-Interface function)
The next routine allows a currently open file to become a stream. The
routine receives as arguments a file descriptor, the true file name as a
string, an atom with the user name, and a set of flags:
@table @code
  @item    void      YAP_OpenStream(void *@var{FD}, char *@var{name}, YAP_Term @var{t}, int @var{flags})
@end table
@noindent
The available flags are @code{YAP_INPUT_STREAM},
@code{YAP_OUTPUT_STREAM}, @code{YAP_APPEND_STREAM},
@code{YAP_PIPE_STREAM}, @code{YAP_TTY_STREAM}, @code{YAP_POPEN_STREAM},
@code{YAP_BINARY_STREAM}, and @code{YAP_SEEKABLE_STREAM}. By default, the
stream is supposed to be at position 0. The argument @var{name} gives
the name by which YAP should know the new stream.

@node Utility Functions, Calling YAP From C, Controlling Streams, C-Interface
@section Utility Functions in @code{C}


The C-Interface  provides the C-application with a a number of utility
functions that are useful.


@findex YAP_Record (C-Interface function)
The first provides a way to insert a term into the data-base
@table @code
@item      void      *YAP_Record(YAP_Term @var{t})
@end table
@noindent
This function returns a pointer to a copy of the term in the database
(or to @t{NULL} if the operation fails.

@findex YAP_Recorded (C-Interface function)
The next functions provides a way to recover the term from the data-base:
@table @code
 @item     YAP_Term      YAP_Recorded(void *@var{handle})
@end table
@noindent
Notice that the semantics are the same as for @code{recorded/3}: this
function creates a new copy of the term in the stack, with fresh
variables. The function returns @t{0L} if it cannot create a new term.

@findex YAP_Erase (C-Interface function)
Last, the next function allows one to recover space:
@table @code
  @item    int      YAP_Erase(void *@var{handle})
@end table
@noindent
Notice that any accesses using @var{handle} after this operation may
lead to a crash.

The following functions are often required to compare terms.

@findex YAP_ExactlyEqual (C-Interface function)
Succeed if two terms are actually the same term, as in
@code{==/2}:
@table @code
@item      int      YAP_ExactlyEqual(YAP_Term t1, YAP_Term t2)
@end table
@noindent

The next function succeeds if two terms are variant terms, and returns
0 otherwise, as
@code{=@=/2}:
@table @code
 @item     int      YAP_Variant(YAP_Term t1, YAP_Term t2)
@end table
@noindent

The next functions deal with numbering variables in terms:
@table @code
 @item     int      YAP_NumberVars(YAP_Term t, YAP_Int first_number)
 @item     YAP_Term YAP_UnNumberVars(YAP_Term t)
 @item     int      YAP_IsNumberedVariable(YAP_Term t)
@end table
@noindent

The next one returns the length of a well-formed list @var{t}, or
@code{-1} otherwise:
@table @code
@item      Int      YAP_ListLength(YAP_Term t)
@end table
@noindent


Last, this function succeeds if two terms are unifiable:
@code{=@=/2}:
@table @code
 @item     int      YAP_Unifiable(YAP_Term t1, YAP_Term t2)
@end table
@noindent

The second function computes a hash function for a term, as in
@code{term_hash/4}.
@table @code
 @item    YAP_Int    YAP_TermHash(YAP_Term t, YAP_Int range, YAP_Int depth, int  ignore_variables));
@end table
@noindent
The first three arguments follow @code{term_has/4}. The last argument
indicates what to do if we find a variable: if @code{0} fail, otherwise
ignore the variable. 

@node Calling YAP From C, Module Manipulation in C, Utility Functions, C-Interface
@section From @code{C} back to Prolog

@findex YAP_RunGoal (C-Interface function)
There are several ways to call Prolog code from C-code. By default, the
@code{YAP_RunGoal()} should be used for this task. It assumes the engine
has been initialised before:

@table @code
@item  YAP_Int YAP_RunGoal(YAP_Term Goal)
@end table
Execute query @var{Goal} and return 1 if the query succeeds, and 0
otherwise. The predicate returns 0 if failure, otherwise it will return
an @var{YAP_Term}. 

Quite often, one wants to run a query once. In this case you should use
@var{Goal}:
@table @code
 @item YAP_Int YAP_RunGoalOnce(YAP_Term Goal)
@end table
The  @code{YAP_RunGoal()} function makes sure to recover stack space at
the end of execution.

Prolog terms are pointers: a problem users often find is that the term
@var{Goal} may actually @emph{be moved around} during the execution of
@code{YAP_RunGoal()}, due to garbage collection or stack shifting. If
this is possible, @var{Goal} will become invalid after executing
@code{YAP_RunGoal()}. In this case, it is a good idea to save @var{Goal}
@emph{slots}, as shown next:

@example
  long sl = YAP_InitSlot(scoreTerm);

  out = YAP_RunGoal(t);
  t = YAP_GetFromSlot(sl);
  YAP_RecoverSlots(1);
  if (out == 0) return FALSE;
@end example

@ifplaintext

@copydoc real

@end ifplaintext

@texinfo

Slots are safe houses in the stack, the garbage collector and the stack
shifter know about them and make sure they have correct values. In this
case, we use a slot to preserve @var{t} during the execution of
@code{YAP_RunGoal}. When the execution of @var{t} is over we read the
(possibly changed) value of @var{t} back from the slot @var{sl} and tell
YAP that the slot @var{sl} is not needed and can be given back to the
system. The slot functions are as follows:

@table @code
@item YAP_Int YAP_NewSlots(int @var{NumberOfSlots})
@findex YAP_NewSlots (C-Interface function)
Allocate @var{NumberOfSlots} from the stack and return an handle to the
last one. The other handle can be obtained by decrementing the handle.

@item YAP_Int YAP_CurrentSlot(void)
@findex YAP_CurrentSlot (C-Interface function)
Return a handle to the system's default slot.

@item YAP_Int YAP_InitSlot(YAP_Term @var{t})
@findex YAP_InitSlot (C-Interface function)
Create a new slot, initialise it with @var{t}, and return a handle to
this slot, that also becomes the current slot.

@item YAP_Term *YAP_AddressFromSlot(YAP_Int @var{slot})
@findex YAP_AddressFromSlot (C-Interface function)
Return the address of slot @var{slot}: please use with care.

@item void YAP_PutInSlot(YAP_Int @var{slot}, YAP_Term @var{t})
@findex YAP_PutInSlot (C-Interface function)
Set the contents of slot @var{slot} to @var{t}.

@item int YAP_RecoverSlots(int @var{HowMany})
@findex YAP_RecoverSlots (C-Interface function)
Recover the space for @var{HowMany} slots: these will include the
current default slot. Fails if no such slots exist.

@item YAP_Int YAP_ArgsToSlots(int @var{HowMany})
@findex YAP_ArgsToSlots (C-Interface function)
Store the current first  @var{HowMany} arguments in new slots.

@item void YAP_SlotsToArgs(int @var{HowMany}, YAP_Int @var{slot})
@findex YAP_SlotsToArgs (C-Interface function)
Set the first @var{HowMany} arguments to the @var{HowMany} slots
starting at @var{slot}.
@end table

@end texinfo

The following functions complement @var{YAP_RunGoal}:
@table @code
@item  @code{int} YAP_RestartGoal(@code{void})
@findex YAP_RestartGoal (C-Interface function)
Look for the next solution to the current query by forcing YAP to
backtrack to the latest goal. Notice that slots allocated since the last
@code{YAP_RunGoal} will become invalid.

@Item  @code{int} YAP_Reset(@code{void})
@findex YAP_Reset (C-Interface function)
Reset execution environment (similar to the @code{abort/0}
built-in). This is useful when you want to start a new query before
asking all solutions to the previous query.

@item  @code{int} YAP_ShutdownGoal(@code{int backtrack})
@findex YAP_ShutdownGoal (C-Interface function)
Clean up the current goal. If
@code{backtrack} is true, stack space will be recovered and bindings
will be undone. In both cases, any slots allocated since the goal was
created will become invalid.

@item  @code{YAP_Bool} YAP_GoalHasException(@code{YAP_Term *tp})
@findex YAP_GoalHasException (C-Interface function)
Check if the last goal generated an exception, and if so copy it to the
space pointed to by @var{tp}

@item  @code{void} YAP_ClearExceptions(@code{void})
@findex YAP_ClearExceptions (C-Interface function)
Reset any exceptions left over by the system.
@end table

The @var{YAP_RunGoal} interface is designed to be very robust, but may
not be the most efficient when repeated calls to the same goal are made
and when there is no interest in processing exception. The
@var{YAP_EnterGoal} interface should have lower-overhead:
@table @code
@item  @code{YAP_PredEntryPtr} YAP_FunctorToPred(@code{YAP_Functor} @var{f},
@findex YAP_FunctorToPred (C-Interface function)
Return the predicate whose main functor is @var{f}.

@item  @code{YAP_PredEntryPtr} YAP_AtomToPred(@code{YAP_Atom} @var{at}
@findex YAP_AtomToPred (C-Interface function)
Return the arity 0 predicate whose name is @var{at}.

@item  @code{YAP_PredEntryPtr}
YAP_FunctorToPredInModule(@code{YAP_Functor} @var{f}, @code{YAP_Module} @var{m}),
@findex YAP_FunctorToPredInModule (C-Interface function)
Return the predicate in module @var{m} whose main functor is @var{f}.

@item  @code{YAP_PredEntryPtr} YAP_AtomToPred(@code{YAP_Atom} @var{at}, @code{YAP_Module} @var{m}),
@findex YAP_AtomToPredInModule (C-Interface function)
Return the arity 0 predicate in module @var{m} whose name is @var{at}.

@item  @code{YAP_Bool} YAP_EnterGoal(@code{YAP_PredEntryPtr} @var{pe},
@code{YAP_Term *} @var{array}, @code{YAP_dogoalinfo *} @var{infop})
@findex YAP_EnterGoal (C-Interface function)
Execute a  query for predicate @var{pe}. The query is given as an
array of terms @var{Array}. @var{infop} is the address of a goal
handle that can be used to backtrack and to recover space. Succeeds if
a solution was found.

Notice that you cannot create new slots if an YAP_EnterGoal goal is open.

@item  @code{YAP_Bool} YAP_RetryGoal(@code{YAP_dogoalinfo *} @var{infop})

@findex YAP_RetryGoal (C-Interface function)
Backtrack to a query created by @code{YAP_EnterGoal}. The query is
given by the handle @var{infop}. Returns whether a new solution could
be be found.

@item  @code{YAP_Bool} YAP_LeaveGoal(@code{YAP_Bool} @var{backtrack},
@code{YAP_dogoalinfo *} @var{infop})
@findex YAP_LeaveGoal (C-Interface function)
Exit a query query created by @code{YAP_EnterGoal}. If
@code{backtrack} is @code{TRUE}, variable bindings are undone and Heap
space is recovered.  Otherwise, only stack space is recovered, ie,
@code{LeaveGoal} executes a cut.
@end table
Next, follows an example of how to use @code{YAP_EnterGoal}:
@example
void
runall(YAP_Term g)
@{
    YAP_dogoalinfo goalInfo;
    YAP_Term *goalArgs = YAP_ArraysOfTerm(g);
    YAP_Functor *goalFunctor = YAP_FunctorOfTerm(g);
    YAP_PredEntryPtr goalPred = YAP_FunctorToPred(goalFunctor);
    
    result = YAP_EnterGoal( goalPred, goalArgs, &goalInfo );
    while (result)
       result = YAP_RetryGoal( &goalInfo );
    YAP_LeaveGoal(TRUE, &goalInfo);
@}
@end example

@findex YAP_CallProlog (C-Interface function)
YAP allows calling a @strong{new} Prolog interpreter from @code{C}. One
way is to first construct a goal @code{G}, and then it is sufficient to
perform:
@table @code
 @item     YAP_Bool      YAP_CallProlog(YAP_Term @var{G})
@end table
@noindent
the result will be @code{FALSE}, if the goal failed, or @code{TRUE}, if
the goal succeeded. In this case, the variables in @var{G} will store
the values they have been unified with. Execution only proceeds until
finding the first solution to the goal, but you can call
@code{findall/3} or friends if you need all the solutions.

Notice that during execution, garbage collection or stack shifting may
have moved the terms 

@node Module Manipulation in C, Miscellaneous C-Functions, Calling YAP From C, C-Interface
@section Module Manipulation in C

YAP allows one to create a new module from C-code. To create the new
code it is sufficient to call:
@table @code
  @item    YAP_Module      YAP_CreateModule(YAP_Atom @var{ModuleName})
@end table
@noindent
Notice that the new module does not have any predicates associated and
that it is not the current module. To find the current module, you can call:
@table @code
  @item    YAP_Module      YAP_CurrentModule()
@end table

Given a module, you may want to obtain the corresponding name. This is
possible by using:
@table @code
 @item     YAP_Term      YAP_ModuleName(YAP_Module mod)
@end table
@noindent
Notice that this function returns a term, and not an atom. You can
@code{YAP_AtomOfTerm} to extract the corresponding Prolog atom.

@node Miscellaneous C-Functions, Writing C, Module Manipulation in C, C-Interface
@section Miscellaneous C Functions

@table @code
@item  @code{void} YAP_Throw(@code{YAP_Term exception})
@item  @code{void} YAP_AsyncThrow(@code{YAP_Term exception})
@findex YAP_Throw (C-Interface function)
@findex YAP_AsyncThrow (C-Interface function)

Throw an exception with term  @var{exception}, just like if you called
@code{throw/2}. The function @t{YAP_AsyncThrow} is supposed to be used
from interrupt handlers.
@c See also @code{at_halt/1}.

@item  @code{int} YAP_SetYAPFlag(@code{yap_flag_t flag, int value})
@findex YAP_SetYAPFlag (C-Interface function)

This function allows setting some YAP flags from @code{C} .Currently,
only two boolean flags are accepted: @code{YAPC_ENABLE_GC} and
@code{YAPC_ENABLE_AGC}.  The first enables/disables the standard garbage
collector, the second does the same for the atom garbage collector.`

@item  @code{YAP_TERM} YAP_AllocExternalDataInStack(@code{size_t bytes})
@item  @code{void *} YAP_ExternalDataInStackFromTerm(@code{YAP_Term t})
@item  @code{YAP_Bool} YAP_IsExternalDataInStackTerm(@code{YAP_Term t})
@findex YAP_AllocExternalDataInStack (C-Interface function)

The next routines allow one to store external data in the Prolog
execution stack. The first routine reserves space for @var{sz} bytes
and returns an opaque handle. The second routines receives the handle
and returns a pointer to the data.  The last routine checks if a term
is an opaque handle.

Data will be automatically reclaimed during
backtracking. Also, this storage is opaque to the Prolog garbage compiler,
so it should not be used to store Prolog terms. On the other hand, it
may be useful to store arrays in a compact way, or pointers to external objects.

@item  @code{int} YAP_HaltRegisterHook(@code{YAP_halt_hook f, void *closure})
@findex YAP_HaltRegisterHook (C-Interface function)

Register the function @var{f} to be called if YAP is halted. The
function is called with two arguments: the exit code of the process
(@code{0} if this cannot be determined on your operating system) and
the closure argument @var{closure}.
@c See also @code{at_halt/1}.

@item  @code{int} YAP_Argv(@code{char ***argvp})
@findex YAP_Argv (C-Interface function)
Return the number of arguments to YAP and instantiate argvp to point to the list of such arguments.

@end table


@node Writing C, Loading Objects, Miscellaneous C-Functions, C-Interface
@section Writing predicates in C

We will distinguish two kinds of predicates:
@table @i
@item @i{deterministic} predicates which either fail or succeed but are not
backtrackable, like the one in the introduction;
@item @i{backtrackable}
predicates which can succeed more than once.
@end table

The first kind of predicates should be implemented as a C function with
no arguments which should return zero if the predicate fails and a
non-zero value otherwise. The predicate should be declared to
YAP, in the initialization routine, with a call to
@table @code
 @item     void YAP_UserCPredicate(char *@var{name}, YAP_Bool *@var{fn}(), unsigned long int @var{arity});
@findex YAP_UserCPredicate (C-Interface function)
@noindent
where @var{name} is a string with the name of the predicate, @var{init},
@var{cont}, @var{cut} are the C functions used to start, continue and
when pruning the execution of the predicate, @var{arity} is the
predicate arity, and @var{sizeof} is the size of the data to be
preserved in the stack.

For the second kind of predicates we need three C functions. The first one
 is called when the predicate is first activated; the second one
is called on backtracking to provide (possibly) other solutions; the
 last one is called on pruning. Note
also that we normally also need to preserve some information to find out
the next solution.

In fact the role of the two functions can be better understood from the
following Prolog definition
@example
       p :- start.
       p :- repeat,
                continue.
@end example
@noindent
where @code{start} and @code{continue} correspond to the two C functions
described above.

The interface works as follows:

@table @code
 @item   void YAP_UserBackCutCPredicate(char *@var{name}, int *@var{init}(), int *@var{cont}(), int *@var{cut}(), unsigned long int @var{arity}, unsigned int @var{sizeof})
@findex YAP_UserBackCutCPredicate (C-Interface function)
@noindent
describes a new predicate where @var{name} is the name of the predicate,
@var{init}, @var{cont}, and @var{cut} are the C functions that implement
the predicate and @var{arity} is the predicate's arity.

@item   void YAP_UserBackCPredicate(char *@var{name}, int *@var{init}(), int *@var{cont}(), unsigned long int @var{arity}, unsigned int @var{sizeof})
@findex YAP_UserBackCPredicate (C-Interface function)
@noindent
describes a new predicate where @var{name} is the name of the predicate,
@var{init}, and @var{cont} are the C functions that implement the
predicate and @var{arity} is the predicate's arity.

@item   void YAP_PRESERVE_DATA(@var{ptr}, @var{type});
@findex YAP_PRESERVE_DATA (C-Interface function)

@item   void YAP_PRESERVED_DATA(@var{ptr}, @var{type});
@findex YAP_PRESERVED_DATA (C-Interface function)

@item   void YAP_PRESERVED_DATA_CUT(@var{ptr}, @var{type});
@findex YAP_PRESERVED_DATA_CUT (C-Interface function)

@item    void YAP_cut_succeed( void );
@findex YAP_cut_succeed (C-Interface function)

@item    void YAP_cut_fail( void );
@findex YAP_cut_fail (C-Interface function)

@end table



As an example we will consider implementing in C a predicate @code{n100(N)}
which, when called with an instantiated argument should succeed if that
argument is a numeral less or equal to 100, and, when called with an
uninstantiated argument, should provide, by backtracking, all the positive
integers less or equal to 100.

   To do that we first declare a structure, which can only consist
of Prolog terms, containing the information to be preserved on backtracking
and a pointer variable to a structure of that type.

@example
#include "YAPInterface.h"

static int start_n100(void);
static int continue_n100(void);

typedef struct @{
    YAP_Term next_solution; 
   @} n100_data_type;

n100_data_type *n100_data;
@end example

We now write the @code{C} function to handle the first call:

@example
static int start_n100(void)
@{
      YAP_Term t = YAP_ARG1;
      YAP_PRESERVE_DATA(n100_data,n100_data_type);
      if(YAP_IsVarTerm(t)) @{
          n100_data->next_solution = YAP_MkIntTerm(0);
          return continue_n100();
       @}
      if(!YAP_IsIntTerm(t) || YAP_IntOfTerm(t)<0 || YAP_IntOfTerm(t)>100) @{
          YAP_cut_fail();
      @} else @{
          YAP_cut_succeed();
      @}
@}

@end example

The routine starts by getting the dereference value of the argument.
The call to @code{YAP_PRESERVE_DATA} is used to initialize the memory
which will hold the information to be preserved across
backtracking. The first argument is the variable we shall use, and the
second its type. Note that we can only use @code{YAP_PRESERVE_DATA}
once, so often we will want the variable to be a structure. This data
is visible to the garbage collector, so it should consist of Prolog
terms, as in the example. It is also correct to store pointers to
objects external to YAP stacks, as the garbage collector will ignore
such references.

If the argument of the predicate is a variable, the routine initializes the 
structure to be preserved across backtracking with the information
required to provide the next solution, and exits by calling
@code{continue_n100} to provide that solution.

If the argument was not a variable, the routine then checks if it was an
integer, and if so, if its value is positive and less than 100. In that
case it exits, denoting success, with @code{YAP_cut_succeed}, or
otherwise exits with @code{YAP_cut_fail} denoting failure.

The reason for using for using the functions @code{YAP_cut_succeed} and
@code{YAP_cut_fail} instead of just returning a non-zero value in the
first case, and zero in the second case, is that otherwise, if
backtracking occurred later, the routine @code{continue_n100} would be
called to provide additional solutions.

The code required for the second function is
@example
static int continue_n100(void)
@{
      int n;
      YAP_Term t;
      YAP_Term sol = YAP_ARG1;
      YAP_PRESERVED_DATA(n100_data,n100_data_type);
      n = YAP_IntOfTerm(n100_data->next_solution);
      if( n == 100) @{
           t = YAP_MkIntTerm(n);
           YAP_Unify(sol,t);
           YAP_cut_succeed();
        @}
       else @{
           YAP_Unify(sol,n100_data->next_solution);
           n100_data->next_solution = YAP_MkIntTerm(n+1);
           return(TRUE);
        @}
@}
@end example

Note that again the macro @code{YAP_PRESERVED_DATA} is used at the
beginning of the function to access the data preserved from the previous
solution.  Then it checks if the last solution was found and in that
case exits with @code{YAP_cut_succeed} in order to cut any further
backtracking.  If this is not the last solution then we save the value
for the next solution in the data structure and exit normally with 1
denoting success. Note also that in any of the two cases we use the
function @code{YAP_unify} to bind the argument of the call to the value
saved in @code{ n100_state->next_solution}.


Note also that the only correct way to signal failure in a backtrackable
predicate is to use the @code{YAP_cut_fail} macro.

Backtrackable predicates should be declared to YAP, in a way
similar to what happened with deterministic ones, but using instead a
call to
@example
     
@end example
@noindent
 In this example, we would have something like

@example
void
init_n100(void)
@{
  YAP_UserBackCutCPredicate("n100", start_n100, continue_n100, cut_n100, 1, 1);
@}
@end example
The argument before last is the predicate's arity. Notice again the
last argument to the call. function argument gives the extra space we
want to use for @code{PRESERVED_DATA}. Space is given in cells, where
a cell is the same size as a pointer. The garbage collector has access
to this space, hence users should use it either to store terms or to
store pointers to objects outside the stacks.

The code for @code{cut_n100} could be:
@example
static int cut_n100(void)
@{
  YAP_PRESERVED_DATA_CUT(n100_data,n100_data_type*);

  fprintf("n100 cut with counter %ld\n", YAP_IntOfTerm(n100_data->next_solution));
  return TRUE;
@}
@end example
Notice that we have to use @code{YAP_PRESERVED_DATA_CUT}: this is
because the Prolog engine is at a different state during cut.

If no work is required at cut, we can use:
@example
void
init_n100(void)
@{
  YAP_UserBackCutCPredicate("n100", start_n100, continue_n100, NULL, 1, 1);
@}
@end example
in this case no code is executed at cut time.

@node Loading Objects, Save&Rest, Writing C, C-Interface
@section Loading Object Files

The primitive predicate
@table @code
@item     load_foreign_files(@var{Files},@var{Libs},@var{InitRoutine})
@end table
@noindent
should be used, from inside YAP, to load object files produced by the C
compiler. The argument @var{ObjectFiles} should be a list of atoms
specifying the object files to load, @var{Libs} is a list (possibly
empty) of libraries to be passed to the unix loader (@code{ld}) and
InitRoutine is the name of the C routine (to be called after the files
are loaded) to perform the necessary declarations to YAP of the
predicates defined in the files. 

YAP will search for @var{ObjectFiles} in the current directory first. If
it cannot find them it will search for the files using the environment
variable:
@table @code
@item YAPLIBDIR
@findex YAPLIBDIR
@noindent
@end table
if defined, or in the default library.

YAP also supports the SWI-Prolog interface to loading foreign code:

@table @code
@item open_shared_object(+@var{File}, -@var{Handle})
@findex open_shared_object/2
@snindex open_shared_object/2
@cnindex open_shared_object/2
    File is the name of a shared object file (called dynamic load
    library in MS-Windows). This file is attached to the current process
    and @var{Handle} is unified with a handle to the library. Equivalent to
    @code{open_shared_object(File, [], Handle)}. See also
    @code{load_foreign_library/1} and @code{load_foreign_library/2}.

    On errors, an exception @code{shared_object}(@var{Action},
    @var{Message}) is raised. @var{Message} is the return value from
    dlerror().

@item open_shared_object(+@var{File}, -@var{Handle}, +@var{Options})
@findex open_shared_object/3
@snindex open_shared_object/3
@cnindex open_shared_object/3
    As @code{open_shared_object/2}, but allows for additional flags to
    be passed. @var{Options} is a list of atoms. @code{now} implies the
    symbols are 
    resolved immediately rather than lazily (default). @code{global} implies
    symbols of the loaded object are visible while loading other shared
    objects (by default they are local). Note that these flags may not
    be supported by your operating system. Check the documentation of
    @code{dlopen()} or equivalent on your operating system. Unsupported
    flags  are silently ignored. 

@item close_shared_object(+@var{Handle})
@findex close_shared_object/1
@snindex close_shared_object/1
@cnindex close_shared_object/1
    Detach the shared object identified by @var{Handle}. 

@item call_shared_object_function(+@var{Handle}, +@var{Function})
@findex call_shared_object_function/2
@snindex call_shared_object_function/2
@cnindex call_shared_object_function/2
    Call the named function in the loaded shared library. The function
    is called without arguments and the return-value is
    ignored. In SWI-Prolog, normally this function installs foreign
    language predicates using calls to @code{PL_register_foreign()}.
@end table

@node Save&Rest, YAP4 Notes, Loading Objects, C-Interface
@section Saving and Restoring

@comment The primitive predicates @code{save} and @code{restore} will save and restore
@comment object code loaded with @code{load_foreign_files/3}. However, the values of
@comment any non-static data created by the C files loaded will not be saved nor
@comment restored.

YAP4 currently does not support @code{save} and @code{restore} for object code
loaded with @code{load_foreign_files/3}. We plan to support save and restore
in future releases of YAP.

@node YAP4 Notes, , Save&Rest, C-Interface
@section Changes to the C-Interface in YAP4

YAP4 includes several changes over the previous @code{load_foreign_files/3}
interface. These changes were required to support the new binary code
formats, such as ELF used in Solaris2 and Linux.
@itemize @bullet
@item All Names of YAP objects now start with @var{YAP_}. This is
designed to avoid clashes with other code. Use @code{YAPInterface.h} to
take advantage of the new interface. @code{c_interface.h} is still
available if you cannot port the code to the new interface.

@item Access to elements in the new interface always goes through
@emph{functions}. This includes access to the argument registers,
@code{YAP_ARG1} to @code{YAP_ARG16}. This change breaks code such as
@code{unify(&ARG1,&t)}, which is nowadays:
@example
@{
   YAP_Unify(ARG1, t);
@}
@end example

@item @code{cut_fail()} and @code{cut_succeed()} are now functions.

@item The use of @code{Deref} is deprecated. All functions that return
Prolog terms, including the ones that access arguments, already
dereference their arguments.

@item Space allocated with PRESERVE_DATA is ignored by garbage
collection and stack shifting. As a result, any pointers to a Prolog
stack object, including some terms, may be corrupted after garbage
collection or stack shifting. Prolog terms should instead be stored as
arguments to the backtrackable procedure.

@end itemize

@node YAPLibrary, Compatibility, C-Interface, Top
@section Using YAP as a Library

YAP can be used as a library to be called from other
programs. To do so, you must first create the YAP library:
@example
make library
make install_library
@end example
This will install a file @code{libyap.a} in @var{LIBDIR} and the Prolog
headers in @var{INCLUDEDIR}. The library contains all the functionality
available in YAP, except the foreign function loader and for
@code{YAP}'s startup routines.

To actually use this library you must follow a five step process:

@enumerate
@item
 You must initialize the YAP environment. A single function,
@code{YAP_FastInit} asks for a contiguous chunk in your memory space, fills
it in with the data-base, and sets up YAP's stacks and
execution registers. You can use a saved space from a standard system by
calling @code{save_program/1}.
     
@item You then have to prepare a query to give to
YAP. A query is a Prolog term, and you just have to use the same
functions that are available in the C-interface.

@item You can then use @code{YAP_RunGoal(query)} to actually evaluate your
query. The argument is the query term @code{query}, and the result is 1
if the query succeeded, and 0 if it failed.

@item You can use the term destructor functions to check how
arguments were instantiated.

@item If you want extra solutions, you can use
@code{YAP_RestartGoal()} to obtain the next solution.

@end enumerate

The next program shows how to use this system. We assume the saved
program contains two facts for the procedure @t{b}:

@example
@cartouche
#include <stdio.h>
#include "YAP/YAPInterface.h"


int
main(int argc, char *argv[]) @{
  if (YAP_FastInit("saved_state") == YAP_BOOT_ERROR)
    exit(1);
  if (YAP_RunGoal(YAP_MkAtomTerm(YAP_LookupAtom("do")))) @{
    printf("Success\n");
    while (YAP_RestartGoal())
      printf("Success\n");
  @}
  printf("NO\n");
@}
@end cartouche
@end example

The program first initializes YAP, calls the query for the
first time and succeeds, and then backtracks twice. The first time
backtracking succeeds, the second it fails and exits.

To compile this program it should be sufficient to do:

@example
cc -o exem -I../YAP4.3.0 test.c -lYAP -lreadline -lm
@end example

You may need to adjust the libraries and library paths depending on the
Operating System and your installation of YAP.

Note that YAP4.3.0 provides the first version of the interface. The
interface may change and improve in the future.

The following C-functions are available from YAP:

@itemize @bullet
@item  YAP_CompileClause(@code{YAP_Term} @var{Clause})
@findex  YAP_CompileClause/1
Compile the Prolog term @var{Clause} and assert it as the last clause
for the corresponding procedure.

@item  @code{int} YAP_ContinueGoal(@code{void})
@findex YAP_ContinueGoal/0
Continue execution from the point where it stopped.

@item  @code{void} YAP_Error(@code{int} @var{ID},@code{YAP_Term} @var{Cause},@code{char *} @var{error_description})
@findex YAP_Error/1
Generate an YAP System Error with description given by the string
@var{error_description}. @var{ID} is the error ID, if known, or
@code{0}. @var{Cause} is the term that caused the crash.

@item  @code{void} YAP_Exit(@code{int} @var{exit_code})
@findex YAP_Exit/1
Exit YAP immediately. The argument @var{exit_code} gives the error code
and is supposed to be 0 after successful execution in Unix and Unix-like
systems.

@item  @code{YAP_Term} YAP_GetValue(@code{Atom} @var{at})
@findex  YAP_GetValue/1
Return the term @var{value} associated with the atom @var{at}. If no
such term exists the function will return the empty list.

@item  YAP_FastInit(@code{char *} @var{SavedState})
@findex  YAP_FastInit/1
Initialize a copy of YAP from @var{SavedState}. The copy is
monolithic and currently must be loaded at the same address where it was
saved. @code{YAP_FastInit} is a simpler version of @code{YAP_Init}.

@item  YAP_Init(@var{InitInfo})
@findex  YAP_Init/1
Initialize YAP. The arguments are in a @code{C}
structure of type @code{YAP_init_args}.

The fields of @var{InitInfo} are @code{char *} @var{SavedState},
@code{int} @var{HeapSize}, @code{int} @var{StackSize}, @code{int}
@var{TrailSize}, @code{int} @var{NumberofWorkers}, @code{int}
@var{SchedulerLoop}, @code{int} @var{DelayedReleaseLoad}, @code{int}
@var{argc}, @code{char **} @var{argv}, @code{int} @var{ErrorNo}, and
@code{char *} @var{ErrorCause}. The function returns an integer, which
indicates the current status. If the result is @code{YAP_BOOT_ERROR}
booting failed.

If @var{SavedState} is not NULL, try to open and restore the file
@var{SavedState}. Initially YAP will search in the current directory. If
the saved state does not exist in the current directory YAP will use
either the default library directory or the directory given by the
environment variable @code{YAPLIBDIR}. Note that currently
the saved state must be loaded at the same address where it was saved.

If @var{HeapSize} is different from 0 use @var{HeapSize} as the minimum
size of the Heap (or code space). If @var{StackSize} is different from 0
use @var{HeapSize} as the minimum size for the Stacks. If
@var{TrailSize} is different from 0 use @var{TrailSize} as the minimum
size for the Trails.

The @var{NumberofWorkers}, @var{NumberofWorkers}, and
@var{DelayedReleaseLoad} are only of interest to the or-parallel system.

The argument count @var{argc} and string of arguments @var{argv}
arguments are to be passed to user programs as the arguments used to
call YAP.

If booting failed you may consult @code{ErrorNo} and @code{ErrorCause}
for the cause of the error, or call
@code{YAP_Error(ErrorNo,0L,ErrorCause)} to do default processing. 


@item  @code{void} YAP_PutValue(@code{Atom} @var{at}, @code{YAP_Term} @var{value})
@findex  YAP_PutValue/2
Associate the term @var{value} with the atom @var{at}. The term
@var{value} must be a constant. This functionality is used by YAP as a
simple way for controlling and communicating with the Prolog run-time.

@item  @code{YAP_Term} YAP_Read(@code{IOSTREAM *Stream})
@findex  YAP_Read
Parse a @var{Term} from the stream @var{Stream}.

@item  @code{YAP_Term} YAP_Write(@code{YAP_Term} @var{t})
@findex  YAP_CopyTerm
Copy a Term @var{t} and all associated constraints. May call the garbage
collector and returns @code{0L} on error (such as no space being
available).

@item  @code{void} YAP_Write(@code{YAP_Term} @var{t}, @code{IOSTREAM} @var{stream}, @code{int} @var{flags})
@findex  YAP_Write/3
Write a Term @var{t} using the stream @var{stream} to output
characters. The term is written according to a mask of the following
flags in the @code{flag} argument: @code{YAP_WRITE_QUOTED},
@code{YAP_WRITE_HANDLE_VARS}, @code{YAP_WRITE_USE_PORTRAY},  and @code{YAP_WRITE_IGNORE_OPS}.

@item  @code{int} YAP_WriteBuffer(@code{YAP_Term} @var{t}, @code{char *} @var{buff}, @code{size_t} @var{size}, @code{int} @var{flags})
@findex  YAP_WriteBuffer
Write a YAP_Term @var{t} to buffer @var{buff} with size
@var{size}. The term is written
according to a mask of the following flags in the @code{flag}
argument: @code{YAP_WRITE_QUOTED}, @code{YAP_WRITE_HANDLE_VARS},
@code{YAP_WRITE_USE_PORTRAY}, and @code{YAP_WRITE_IGNORE_OPS}. The
function will fail if it does not have enough space in the buffer.

@item  @code{char *} YAP_WriteDynamicBuffer(@code{YAP_Term} @var{t}, @code{char *} @var{buff}, @code{size_t} @var{size}, @code{size_t} @var{*lengthp}, @code{size_t} @var{*encodingp}, @code{int} @var{flags})
@findex  YAP_WriteDynamicBuffer/6
Write a YAP_Term @var{t} to buffer @var{buff} with size
@var{size}. The code will allocate an extra buffer if @var{buff} is
@code{NULL} or if @code{buffer} does not have enough room. The
variable @code{lengthp} is assigned the size of the resulting buffer,
and @code{encodingp} will receive the type of encoding (currently only @code{PL_ENC_ISO_LATIN_1} and @code{PL_ENC_WCHAR} are supported)

@item  @code{void} YAP_InitConsult(@code{int} @var{mode}, @code{char *} @var{filename})
@findex YAP_InitConsult/2
Enter consult mode on file @var{filename}. This mode maintains a few
data-structures internally, for instance to know whether a predicate
before or not. It is still possible to execute goals in consult mode.

If @var{mode} is @code{TRUE} the file will be reconsulted, otherwise
just consulted. In practice, this function is most useful for
bootstrapping Prolog, as otherwise one may call the Prolog predicate
@code{compile/1} or @code{consult/1} to do compilation.

Note that it is up to the user to open the file @var{filename}. The
@code{YAP_InitConsult} function only uses the file name for internal
bookkeeping.

@item  @code{void} YAP_EndConsult(@code{void})
@findex YAP_EndConsult/0
Finish consult mode.

@end itemize

Some observations:

@itemize @bullet
@item The system will core dump if you try to load the saved state in a
different address from where it was made. This may be a problem if
your program uses @code{mmap}. This problem will be addressed in future
versions of YAP.

@item Currently, the YAP library will pollute the name
space for your program.

@item The initial library includes the complete YAP system. In
the future we plan to split this library into several smaller libraries
(e.g. if you do not want to perform Input/Output).

@item You can generate your own saved states. Look at  the
@code{boot.yap} and @code{init.yap} files.

@end itemize

@node Compatibility, Operators, YAPLibrary, Top
@chapter Compatibility with Other Prolog systems

YAP has been designed to be as compatible as possible with
other Prolog systems, and initially with C-Prolog. More recent work on
YAP has included features initially proposed for the Quintus
and SICStus Prolog systems.

Developments since @code{YAP4.1.6} we have striven at making
YAP compatible with the ISO-Prolog standard. 

@menu
* C-Prolog:: Compatibility with the C-Prolog interpreter
* SICStus Prolog:: Compatibility with the SICStus Prolog system
* ISO Prolog::  Compatibility with the ISO Prolog standard
@end menu

@node C-Prolog, SICStus Prolog, , Compatibility
@section Compatibility with the C-Prolog interpreter

@menu
C-Prolog Compatibility
* Major Differences with C-Prolog:: Major Differences between YAP and C-Prolog
* Fully C-Prolog Compatible:: YAP predicates fully compatible with
C-Prolog
* Not Strictly C-Prolog Compatible:: YAP predicates not strictly as C-Prolog
* Not in C-Prolog:: YAP predicates not available in C-Prolog
* Not in YAP:: C-Prolog predicates not available in YAP
@end menu

@node Major Differences with C-Prolog, Fully C-Prolog Compatible, , C-Prolog
@subsection Major Differences between YAP and C-Prolog.

YAP includes several extensions over the original C-Prolog system. Even
so, most C-Prolog programs should run under YAP without changes.

The most important difference between YAP and C-Prolog is that, being
YAP a compiler, some changes should be made if predicates such as
@code{assert}, @code{clause} and @code{retract} are used. First
predicates which will change during execution should be declared as
@code{dynamic} by using commands like:

@example
:- dynamic f/n.
@end example

@noindent where @code{f} is the predicate name and n is the arity of the
predicate. Note that  several such predicates can be declared in a
single command:
@example
 :- dynamic f/2, ..., g/1.
@end example

Primitive predicates such as @code{retract} apply only to dynamic
predicates.  Finally note that not all the C-Prolog primitive predicates
are implemented in YAP. They can easily be detected using the
@code{unknown} system predicate provided by YAP.

Last, by default YAP enables character escapes in strings. You can
disable the special interpretation for the escape character by using:
@example
:- yap_flag(character_escapes,off).
@end example
@noindent
or by using:
@example
:- yap_flag(language,cprolog).
@end example

@node Fully C-Prolog Compatible, Not Strictly C-Prolog Compatible, Major Differences with C-Prolog, C-Prolog
@subsection YAP predicates fully compatible with C-Prolog

These are the Prolog built-ins that are fully compatible in both
C-Prolog and YAP:

@printindex cy

@node Not Strictly C-Prolog Compatible, Not in C-Prolog, Fully C-Prolog Compatible, C-Prolog
@subsection YAP predicates not strictly compatible with C-Prolog

These are YAP built-ins that are also available in C-Prolog, but
that are not fully compatible:

@printindex ca

@node Not in C-Prolog, Not in YAP, Not Strictly C-Prolog Compatible, C-Prolog
@subsection YAP predicates not available in C-Prolog

These are YAP built-ins not available in C-Prolog.

@printindex cn

@node Not in YAP, , Not in C-Prolog, C-Prolog
@subsection YAP predicates not available in C-Prolog

These are C-Prolog built-ins not available in YAP:

@table @code
@item 'LC'
The following Prolog text uses lower case letters.

@item 'NOLC'
The following Prolog text uses upper case letters only.
@end table

@node SICStus Prolog, ISO Prolog, C-Prolog, Compatibility
@section Compatibility with the Quintus and SICStus Prolog systems

The Quintus Prolog system was the first Prolog compiler to use Warren's
Abstract Machine. This system was very influential in the Prolog
community. Quintus Prolog implemented compilation into an abstract
machine code, which was then emulated. Quintus Prolog also included
several new built-ins, an extensive library, and in later releases a
garbage collector. The SICStus Prolog system, developed at SICS (Swedish
Institute of Computer Science), is an emulator based Prolog system
largely compatible with Quintus Prolog. SICStus Prolog has evolved
through several versions. The current version includes several
extensions, such as an object implementation, co-routining, and
constraints.

Recent work in YAP has been influenced by work in Quintus and
SICStus Prolog. Wherever possible, we have tried to make YAP
compatible with recent versions of these systems, and specifically of
SICStus Prolog. You should use 
@example
:- yap_flag(language, sicstus).
@end example
@noindent
for maximum compatibility with SICStus Prolog.

@menu
SICStus Compatibility
* Major Differences with SICStus:: Major Differences between YAP and SICStus Prolog
* Fully SICStus Compatible:: YAP predicates fully compatible with
SICStus Prolog
* Not Strictly SICStus Compatible:: YAP predicates not strictly as
SICStus Prolog
* Not in SICStus Prolog:: YAP predicates not available in SICStus Prolog
@end menu

@node Major Differences with SICStus, Fully SICStus Compatible, , SICStus Prolog
@subsection Major Differences between YAP and SICStus Prolog.

Both YAP and SICStus Prolog obey the Edinburgh Syntax and are based on
the WAM. Even so, there are quite a few important differences:

@itemize @bullet
@item Differently from SICStus Prolog, YAP does not have a
notion of interpreted code. All code in YAP is compiled.

@item YAP does not support an intermediate byte-code
representation, so the @code{fcompile/1} and @code{load/1} built-ins are
not available in YAP.

@item YAP implements escape sequences as in the ISO standard. SICStus
Prolog implements Unix-like escape sequences.

@item YAP implements @code{initialization/1} as per the ISO
standard. Use @code{prolog_initialization/1} for the SICStus Prolog
compatible built-in.

@item Prolog flags are different in SICStus Prolog and in YAP.

@item The SICStus Prolog @code{on_exception/3} and
@code{raise_exception} built-ins correspond to the ISO built-ins
@code{catch/3} and @code{throw/1}.

@item The following SICStus Prolog v3 built-ins are not (currently)
implemented in YAP (note that this is only a partial list):
@code{file_search_path/2},
@code{stream_interrupt/3}, @code{reinitialize/0}, @code{help/0},
@code{help/1}, @code{trimcore/0}, @code{load_files/1},
@code{load_files/2}, and @code{require/1}.

      The previous list is incomplete. We also cannot guarantee full
compatibility for other built-ins (although we will try to address any
such incompatibilities). Last, SICStus Prolog is an evolving system, so
one can be expect new incompatibilities to be introduced in future
releases of SICStus Prolog.

@item YAP allows asserting and abolishing static code during
execution through the @code{assert_static/1} and @code{abolish/1}
built-ins. This is not allowed in Quintus Prolog or SICStus Prolog.

@item The socket predicates, although designed to be compatible with
SICStus Prolog, are built-ins, not library predicates, in YAP.

@item This list is incomplete.

@end itemize

The following differences only exist if the @code{language} flag is set
to @code{yap} (the default):

@itemize @bullet
@item The @code{consult/1} predicate in YAP follows C-Prolog
semantics. That is, it adds clauses to the data base, even for
preexisting procedures. This is different from @code{consult/1} in
SICStus Prolog or SWI-Prolog.

@cindex logical update semantics
@item 
By default, the data-base in YAP follows "logical update semantics", as
Quintus Prolog or SICStus Prolog do.  Previous versions followed
"immediate update semantics". The difference is depicted in the next
example:

@example
:- dynamic a/1.

?- assert(a(1)).

?- retract(a(X)), X1 is X +1, assertz(a(X)).
@end example
With immediate semantics, new clauses or entries to the data base are
visible in backtracking. In this example, the first call to
@code{retract/1} will succeed. The call to @strong{assertz/1} will then
succeed. On backtracking, the system will retry
@code{retract/1}. Because the newly asserted goal is visible to
@code{retract/1}, it can be retracted from the data base, and
@code{retract(a(X))} will succeed again. The process will continue
generating integers for ever. Immediate semantics were used in C-Prolog.

With logical update semantics, any additions or deletions of clauses
for a goal 
@emph{will not affect previous activations of the goal}. In the example,
the call to @code{assertz/1} will not see the 
update performed by the @code{assertz/1}, and the query will have a
single solution.

Calling @code{yap_flag(update_semantics,logical)} will switch
YAP to use logical update semantics.

@item @code{dynamic/1} is a built-in, not a directive, in YAP.

@item By default, YAP fails on undefined predicates. To follow default
SICStus Prolog use:
@example
:- yap_flag(unknown,error).
@end example

@item By default, directives in YAP can be called from the top level.

@end itemize

@node Fully SICStus Compatible, Not Strictly SICStus Compatible, Major Differences with SICStus, SICStus Prolog
@subsection YAP predicates fully compatible with SICStus Prolog

These are the Prolog built-ins that are fully compatible in both SICStus
Prolog and YAP:

@printindex sy

@node Not Strictly SICStus Compatible, Not in SICStus Prolog, Fully SICStus Compatible, SICStus Prolog
@subsection YAP predicates not strictly compatible with SICStus Prolog

These are YAP built-ins that are also available in SICStus Prolog, but
that are not fully compatible:

@printindex sa

@node Not in SICStus Prolog, , Not Strictly SICStus Compatible, SICStus Prolog
@subsection YAP predicates not available in SICStus Prolog

These are YAP built-ins not available in SICStus Prolog.

@printindex sn


@node ISO Prolog, , SICStus Prolog, Compatibility
@section Compatibility with the ISO Prolog standard

The Prolog standard was developed by ISO/IEC JTC1/SC22/WG17, the
international standardization working group for the programming language
Prolog. The book "Prolog: The Standard" by Deransart, Ed-Dbali and
Cervoni gives a complete description of this standard. Development in
YAP from YAP4.1.6 onwards have striven at making YAP
compatible with ISO Prolog. As such:

@itemize @bullet
@item   YAP now supports all of the built-ins required by the
ISO-standard, and,
@item   Error-handling is as required by the standard.
@end itemize

YAP by default is not fully ISO standard compliant. You can set the 
@code{language} flag to @code{iso} to obtain very good
compatibility. Setting this flag changes the following:

@itemize @bullet
@item By default, YAP uses "immediate update semantics" for its
database, and not "logical update semantics", as per the standard,
(@pxref{SICStus Prolog}). This affects @code{assert/1},
@code{retract/1}, and friends.

Calling @code{set_prolog_flag(update_semantics,logical)} will switch
YAP to use logical update semantics.

@item By default, YAP implements the 
@code{atom_chars/2}(@pxref{Testing Terms}), and 
@code{number_chars/2}, (@pxref{Testing Terms}), 
built-ins as per the original Quintus Prolog definition, and
not as per the ISO definition.

Calling @code{set_prolog_flag(to_chars_mode,iso)} will switch
YAP to use the ISO definition for
@code{atom_chars/2} and @code{number_chars/2}.

@item By default, YAP allows executable goals in directives. In ISO mode
most directives can only be called from top level (the exceptions are
@code{set_prolog_flag/2} and @code{op/3}).

@item Error checking for meta-calls under ISO Prolog mode is stricter
than by default.

@item The @code{strict_iso} flag automatically enables the ISO Prolog
standard. This feature should disable all features not present in the
standard.

@end itemize

The following incompatibilities between YAP and the ISO standard are
known to still exist:

@itemize @bullet

@item Currently, YAP does not handle overflow errors in integer
operations, and handles floating-point errors only in some
architectures. Otherwise, YAP follows IEEE arithmetic.

@end itemize

Please inform the authors on other incompatibilities that may still
exist.

@node Operators, Predicate Index, Compatibility, Top
@section Summary of YAP Predefined Operators


 The Prolog syntax caters for operators of three main kinds:

@itemize @bullet
@item
prefix;
@item
infix;
@item
postfix.
@end itemize

 Each operator has precedence in the range 1 to 1200, and this 
precedence is used to disambiguate expressions where the structure of the 
term denoted is not made explicit using brackets. The operator of higher 
precedence is the main functor.

 If there are two operators with the highest precedence, the ambiguity 
is solved analyzing the types of the operators. The possible infix types are: 
@var{xfx}, @var{xfy}, and @var{yfx}.

 With an operator of type @var{xfx} both sub-expressions must have lower 
precedence than the operator itself, unless they are bracketed (which 
assigns to them zero precedence). With an operator type @var{xfy} only the  
left-hand sub-expression must have lower precedence. The opposite happens 
for @var{yfx} type.

 A prefix operator can be of type @var{fx} or @var{fy}. 
A postfix operator can be of type @var{xf} or @var{yf}. 
The meaning of the notation is analogous to the above.
@example
a + b * c
@end example
@noindent
means
@example
a + (b * c)
@end example
@noindent
as + and * have the following types and precedences:
@example
:-op(500,yfx,'+').
:-op(400,yfx,'*').
@end example

Now defining
@example
:-op(700,xfy,'++').
:-op(700,xfx,'=:=').
a ++ b =:= c
@end example
@noindent means
@example  
a ++ (b =:= c)
@end example
 

The following is the list of the declarations of the predefined operators:

@example
:-op(1200,fx,['?-', ':-']).
:-op(1200,xfx,[':-','-->']).
:-op(1150,fx,[block,dynamic,mode,public,multifile,meta_predicate,
              sequential,table,initialization]).
:-op(1100,xfy,[';','|']).
:-op(1050,xfy,->).
:-op(1000,xfy,',').
:-op(999,xfy,'.').
:-op(900,fy,['\+', not]).
:-op(900,fx,[nospy, spy]).
:-op(700,xfx,[@@>=,@@=<,@@<,@@>,<,=,>,=:=,=\=,\==,>=,=<,==,\=,=..,is]).
:-op(500,yfx,['\/','/\','+','-']).
:-op(500,fx,['+','-']).
:-op(400,yfx,['<<','>>','//','*','/']).
:-op(300,xfx,mod).
:-op(200,xfy,['^','**']).
:-op(50,xfx,same).
@end example

@node Predicate Index, Concept Index, Operators, Top
@unnumbered Predicate Index
@printindex fn

@node Concept Index, , Predicate Index, Top
@unnumbered Concept Index
@printindex cp

@contents

@bye