docs

C/exec.c

@@ -2107,12 +2107,12 @@ static Int jump_env(USES_REGS1) {
 
     Yap_find_prolog_culprit(PASS_REGS1);
     //    LOCAL_Error_TYPE = ERROR_EVENT;
-    t = ArgOfTerm(1, t);
+    Term t1 = ArgOfTerm(1, t);
-    if (IsApplTerm(t) && IsAtomTerm((t2 = ArgOfTerm(1, t)))) {
+    if (IsApplTerm(t) && IsAtomTerm((t2 = ArgOfTerm(1, t1)))) {
       LOCAL_ActiveError->errorAsText = AtomOfTerm(t2);
-      LOCAL_ActiveError->classAsText = NameOfFunctor(FunctorOfTerm(t));
+      LOCAL_ActiveError->classAsText = NameOfFunctor(FunctorOfTerm(t1));
     } else if (IsAtomTerm(t)) {
-      LOCAL_ActiveError->errorAsText = AtomOfTerm(t);
+      LOCAL_ActiveError->errorAsText = AtomOfTerm(t1);
       LOCAL_ActiveError->classAsText = NULL;
     }
   } else {

docs/Doxyfile.in

@@ -1153,9 +1153,9 @@ HTML_STYLESHEET        =
 # list). For an example see the documentation.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_EXTRA_STYLESHEET  = @CMAKE_SOURCE_DIR@/docs/custom/customdoxygen.css
+HTML_EXTRA_STYLESHEET  = @CMAKE_SOURCE_DIR@/docs/custom/customdoxygen.css \
+                         @CMAKE_SOURCE_DIR@/docs/solarized-light.css
 
-# @CMAKE_SOURCE_DIR@/docs/solarized-light.css
 # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or
 # other source files which should be copied to the HTML output directory. Note
 # that these files will be copied to the base HTML output directory. Use the

docs/md/attscorout.md

@@ -0,0 +1,391 @@
+Attributed Variables and Corouting {#atts}
+==================================
+
+
+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. Originally, YAP  used the interface designed by SICStus
+Prolog. This interface is still
+available through the <tt>atts</tt> library, and is used by CLPBN.
+
+From YAP-6.0.3 onwards we recommend using the hProlog, SWI style
+interface. We believe that this design is easier to understand and
+work with. Most packages included in YAP that use attributed
+variables, such as CHR, CLP(FD), and CLP(QR), rely on the SWI-Prolog
+interface.
+
+  + @ref SICS_attributes
+  + @ref sicsatts
+  + @ref New_Style_Attribute_Declarations
+  + @ref AttributedVariables_Builtins
+  + @ref corout
+
+###  SICStus Style attribute declarations.              {#SICS_attributes}
+
+The YAP library `atts` implements attribute variables in the style of
+SICStus Prolog. Attributed variables work as follows:
+
++ Each attribute must be declared beforehand. Attributes are described
+as a functor with name and arity and are local to a module. Each
+Prolog module declares its own sets of attributes. Different modules
+may have attributes with the same name and arity.
+
++ The built-in 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.
+
++ The built-in get_atts/2 can be used to check the values of
+an attribute associated with a variable.
+
++ The unification algorithm calls the user-defined predicate
+verify_attributes/3 before trying to bind an attributed
+variable. Unification will resume after this call.
+
++ The user-defined predicate
+<tt>attribute_goal/2</tt> converts from an attribute to a goal.
+
++ The user-defined predicate
+<tt>project_attributes/2</tt> is used from a set of variables into a set of
+constraints or goals. One application of <tt>project_attributes/2</tt> is in
+the top-level, where it is used to output the set of
+floundered constraints at the end of a query.
+
+
+Attributes are compound terms associated with a variable. Each attribute
+has a <em>name</em> which is <em>private</em> to the module in which the
+attribute was defined. Variables may have at most one attribute with a
+name. Attribute names are defined through the following declaration:
+
+~~~~~
+:- attribute AttributeSpec, ..., AttributeSpec.
+~~~~~
+
+where each  _AttributeSpec_ has the form ( _Name_/ _Arity_).
+One single such declaration is allowed per module  _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 `user:goal_expansion/3`
+mechanism is used for this purpose.
+
+
+The  attribute manipulation predicates always work as follows:
+
++ The first argument is the unbound variable associated with
+attributes,
++ The second argument is a list of attributes. Each attribute will
+be a Prolog term or a constant, prefixed with the <tt>+</tt> and <tt>-</tt> unary
+operators. The prefix <tt>+</tt> may be dropped for convenience.
+
+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 <em>depends</em> on the module on which the
+built-ins have been invoked.
+
+
+The user-predicate predicate verify_attributes/3 is called when
+attempting to unify an attributed variable which might have attributes
+in some  _Module_.
+
+
+Attributes are usually presented as goals. The following routines are
+used by built-in predicates such as call_residue/2 and by the
+Prolog top-level to display 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
+project_attributes/2 is responsible for implementing this
+projection.
+
+
+The following examples are taken from the SICStus Prolog
+manual. The 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 `domain( _-Var_, _?Domain_)` which
+associates _Domain_ (a list of terms) with _Var_.  A variable can be
+queried for its domain by leaving _Domain_ unbound.
+
+We do not present here a definition for project_attributes/2.
+Projecting finite domain constraints happens to be difficult.
+
+~~~~~
+:- 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
+        ).
+~~~~~
+
+Note that the _implied binding_ `Other=El` was deferred until after
+the completion of `verify_attribute/3`.  Otherwise, there might be a
+danger of recursively invoking `verify_attribute/3`, which might bind
+`Var`, which is not allowed inside the scope of `verify_attribute/3`.
+Deferring unifications into the third argument of `verify_attribute/3`
+effectively serializes the calls to `verify_attribute/3`.
+
+Assuming that the code resides in the file domain.yap, we
+can use it via:
+
+~~~~~
+| ?- use_module(domain).
+~~~~~
+
+Let's test it:
+
+~~~~~
+| ?- 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
+~~~~~
+
+To demonstrate the use of the  _Goals_ argument of
+verify_attributes/3, we give an implementation of
+freeze/2.  We have to name it `myfreeze/2` in order to
+avoid a name clash with the built-in predicate of the same name.
+
+~~~~~
+:- 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.  ~~~~~
+
+Assuming that this code lives in file myfreeze.yap,
+we would use it via:
+
+~~~~~
+| ?- use_module(myfreeze).
+| ?- myfreeze(X,print(bound(x,X))), X=2.
+
+bound(x,2)                      % side effect
+X = 2                           % bindings
+~~~~~
+
+The two solvers even work together:
+
+~~~~~
+| ?- 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
+~~~~~
+
+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
+verify_attributes/3 predicates would typically refer to the
+attributes from other known solvers/modules via the module prefix in
+Module:get_atts/2`.
+
+@}
+
+@{
+###  hProlog and SWI-Prolog style Attribute Declarations              {#New_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 attr_unify_hook/2 is
+  executed in this module.  The example below realises a very simple and
+  incomplete finite domain reasoner.
+
+  ~~~~~
+  :- 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),
+v  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)].
+  ~~~~~
+
+  Before explaining the code we give some example queries:
+
+  The predicate `domain/2` fetches (first clause) or assigns
+  (second clause) the variable a <em>domain</em>, 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 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 `attribute_goals/3` is used to translate
+  remaining attributes to user-readable goals that, when executed, reinstate
+  these attributes.
+
+@}
+
+
+@{
+###  Co-routining              {#CohYroutining}
+
+Prolog uses a simple left-to-right flow of control. It is sometimes
+convenient to change this control so that goals will only execute when
+sufficiently instantiated. This may result in a more "data-driven"
+execution, or may be necessary to correctly implement extensions such
+as negation by failure.
+
+Initially, YAP used a separate mechanism for co-routining. Nowadays, YAP uses
+attributed variables to implement co-routining.
+
+Two declarations are supported:
+
++ block/1
+The argument to `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 `predname( _C1_,..., _CN_)`, where  _N_ is the
+arity of the goal, and each  _CI_ is of the form `-`, if the
+argument must suspend until the first such variable is bound, or
+`?`, otherwise.
+
++ wait/1
+The argument to `wait/1` is a predicate descriptor or a conjunction
+of these predicates. These predicates will suspend until their first
+argument is bound.
+
+
+The following primitives can be used:
+
+- freeze/2
+
+- dif/2
+
+- when/2
+
+- frozen/2
+
+
+@}
+
+@}

docs/md/extensions.md

@@ -1,21 +0,0 @@
-Extensions to core Prolog. 								{#extensions}
-========================
-
-YAP includes a number of extensions over the original Prolog
-language.
-
-+ @subpage attributes
-
-+ @ref Rational_Trees
-
-+ @ref  DepthLimited
-
-+ @ref  Tabling
-
-+ @ref Threads
-
-+ @ref Profiling
-
-+ @ref YAPArrays
-
-+ @ref Parallelism

docs/md/fli.md

@@ -7,17 +7,18 @@ most language implementations were linkable to `C`, and the first interface expo
 This gives portability with a number of SWI-Prolog packages and avoids garnage collection by using @ref slotInterface. Last, a new C++ based interface is
 being designed to work with the swig (www.swig.orgv) interface compiler.
 
-  + The @subpage c-interface
 
   + The @ref swi-c-interface emulates Jan Wielemaker's SWI foreign language interface.
 
   + The @ref  yap-cplus-interface is desiged to interface with the SWIG package by using Object-Oriented concepts
 
-+ The @ref LoadForeign handles the setup of foreign files
+  + The @ref LoadForeign handles the setup of foreign files
+
+  + @subpage YAPAsLibrary
 
 
 
-@page c-interface  YAP original C-interface
+###   YAP original C-interface {#ChYInterface}
 
 Before describing in full detail how to interface to C code, we will examine
 a brief example.
@@ -1304,8 +1305,7 @@ arguments to the backtrackable procedure.
 
 
 
-@defgroup YAPAsLibrary Using YAP as a Library
+###  Using YAP as a Library {#YAPAsLibrary}
-@ingroup  c-interface
 
 YAP can be used as a library to be called from other
 programs. To do so, you must first create the YAP library:

docs/md/yap.md

@@ -23,11 +23,11 @@ The manual is organised as follows:
 
 + @subpage load_files
 
-+ @ref builtins
++ @subpage builtins
 
-+ @ref extensions
++ @subpage Extensions
 
-+ @ref library
++ @subpage library
 
 + @subpage packages
 
@@ -59,9 +59,8 @@ from
 Jan Wielemaker. We would also like to gratefully
 acknowledge the contributions from Ashwin Srinivasian.
 
-@defgroup builtins YAP Core Built-ins
+@page builtins YAP Core Built-ins
 
-@{}
 
 This chapter describes the core predicates  that control the execution of
 Prolog programs, provide fundamental functionality such as termm manipulation or arithmetic, and support interaction with external
@@ -75,34 +74,39 @@ argument" - it cannot be a free variable at the time of the call;
 + a preceding minus sign will denote an "output argument";
 + an argument with no preceding symbol can be used in both ways.
 
-@}
 
-  @defgroup library YAP Library
+@page Library YAP Library
+
 
-@{
  the library_directory path (set by the
   `LIBDIR` variable in the Makefile for YAP). Several files in the
   library are originally from the public-domain Edinburgh Prolog library.
 
-@defgroup attributes Attributed Variables and Coroutining
+ 
-@{
-    @subpage atts
-    @copydoc atts
-}
-
-@}
-
-@defgroup YAPProgramming Programming in YAP
-
-@{
-
-@defgroup YAPSyntax Prolog Syntax
-    @subpage syntax
-    @copydoc syntax
-@}
 
 
+ @defgroup extensions   YAP Extensions
+ @{
 
-@}
+@page Extensions  YAP Extensions
 
-  
+YAP includes a number of extensions over the original Prolog
+language.
+         @subpage atts
+
+ @}
+
+@page YAPProgramming Programming in YAP
+
+    @subpage yapsyntax.md
+
+
+@page packages Packages for YAP
+YAP includes a number of packages.
+ 
+ @subpage real.md
+
+ @subpage chr.md
+
+
+  

docs/md/yapsyntax.md

@@ -1,10 +1,13 @@
 
+@ingroup YAPProgramming
+
 We will describe the syntax of YAP at two levels. We first will
 describe the syntax for Prolog terms. In a second level we describe
 the  tokens from which Prolog  terms are
 built.
 
-###  Syntax of Terms                       {#Formal_Syntax}
+@defgroup Formal_Syntax Syntax of Terms
+@ingroup YAPSyntax
 
 Below, we describe the syntax of YAP terms from the different
 classes of tokens defined above. The formalism used will be <em>BNF</em>,
@@ -79,15 +82,17 @@ dot with single quotes.
 
 
 
-###  Prolog Tokens                    {#Tokens}
+# @defgroup Tokens Prolog Tokens
+@ingroup YAPSyntax
 
 Prolog tokens are grouped into the following categories:
 
-#### Numbers                      {#Numbers}
+## @defgroup Numbers Numbers
+@ingroup Tokens
 
 Numbers can be further subdivided into integer and floating-point numbers.
 
-##### @defgroup  Integers           {#Integers}
+### @defgroup  Integers Integers
 @ingroup Numbers
 
 Integer numbers
@@ -135,7 +140,7 @@ the word size of the machine. This is 32 bits in most current machines,
 but 64 in some others, such as the Alpha running Linux or Digital
 Unix. The scanner will read larger or smaller integers erroneously.
 
-#####  Floats                         {#Floats}
+### @defgroup  Floats Floats
 @ingroup Numbers
 
 Floating-point numbers are described by:
@@ -160,7 +165,7 @@ Examples:
 Floating-point numbers are represented as a double in the target
 machine. This is usually a 64-bit number.
 
-####   Strings Character Strings        {#Strings}
+## Strings @defgroup  Strings Character Strings
 
 Strings are described by the following rules:
 
@@ -230,7 +235,8 @@ versions of YAP up to 4.2.0. Escape sequences can be disabled by using:
 :- yap_flag(character_escapes,false).
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-####   Atoms                          {#Atoms}
+## @addgroup Atoms Atoms
+@ingroup Tokens
 
 Atoms are defined by one of the following rules:
 
@@ -301,8 +307,7 @@ Punctuation tokens consist of one of the following characters:
 
 These characters are used to group terms.
 
-#### Layout {#Layout}
+@subsection Layout Layout
-
 Any characters with ASCII code less than or equal to 32 appearing before
 a token are ignored.
 
@@ -314,8 +319,8 @@ layout characters, the YAP parser behaves as if it had found a
 single blank character. The end of a file also counts as a blank
 character for this purpose.
 
-####    Wide Character Support                 {#WideChars}
+## @addgroup WideChars Encoding Wide Character Support
-@ingroup YAP]Syntax
+@ingroup YAPSyntax
 
 
 YAP now implements a SWI-Prolog compatible interface to wide
@@ -455,7 +460,8 @@ Prolog escape sequences while other streams generate an I/O exception.
 
 
 
-##### BOM: Byte Order Mark            {#BOM}
+=== @addgroup BOM BOM: Byte Order Mark
+@ingroup WideChars
 
 From Stream Encoding, you may have got the impression that
 text-files are complicated. This section deals with a related topic,
@@ -475,7 +481,8 @@ writing, writing a BOM can be requested using the option
 UTF-32; otherwise the default is not to write a BOM. BOMs are not avaliable for ASCII and
 ISO-LATIN-1.
 
-###  Summary of YAP Predefined Operators            {#ops}
+= @addgroup Operators Summary of YAP Predefined Operators
+@ingroup YapSyntax
 
 The Prolog syntax caters for operators of three main kinds:
 

packages/real/real.md

@@ -1,7 +1,7 @@
 The R Prolog Progrmming Interface      {#real}
 ===================================
 
-@file real.pl
+@file real.md
 @author	Nicos Angelopoulos
 @author	Vitor Santos Costa
 @version	1:0:4, 2013/12/25, sinter_class
@@ -9,6 +9,7 @@ The R Prolog Progrmming Interface      {#real}
 
 @ingroup packages
 
+  + @ref realpl
 
 This library enables the communication with an R process started as a shared library.
 It is the result of the efforts of two research groups that have worked in parallel.

packages/real/real.pl

@@ -949,3 +949,5 @@ prolog:message( r_root ) -->
 :- initialization(start_r, now).
 
 :- initialization( set_prolog_flag( double_quotes, string) ).
+
+@}