diogo/yap-6.3
Archived
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs

Browse Source
This commit is contained in:
Vitor Santos Costa 2017-05-08 18:55:34 +01:00
parent 6e7846e210
commit 3e3893ceff
9 changed files with 456 additions and 72 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
C/exec.c
View File

@ -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);
if (IsApplTerm(t) && IsAtomTerm((t2 = ArgOfTerm(1, t)))) {
Term t1 = 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 {

4
docs/Doxyfile.in
View File

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

391
docs/md/attscorout.md Normal file
View File

@ -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
@}
@}

21
docs/md/extensions.md
View File

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

10
docs/md/fli.md
View File

@ -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
@ingroup c-interface
### Using YAP as a Library {#YAPAsLibrary}
YAP can be used as a library to be called from other
programs. To do so, you must first create the YAP library:

56
docs/md/yap.md
View File

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

33
docs/md/syntax.md → docs/md/yapsyntax.md
View File

@ -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}
@ingroup YAP]Syntax
## @addgroup WideChars Encoding Wide Character Support
@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:

3
packages/real/real.md
View File

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

2
packages/real/real.pl
View File

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