\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] 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 #include 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 /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_get_message(a(A)), 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
  • The original YAP C-interface exports the YAP engine.
  • The @ref swi-c-interface emulates Jan Wielemaker's SWI foreign language interface.
  • The @ref yap-cplus-interface is desiged to interface with Object-Oriented systems.
    • @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 #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