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

more doc stuff

Browse Source
This commit is contained in:
Vitor Santos Costa
2018-05-10 13:11:56 +01:00
parent 74222843e5
commit 1206035805
25 changed files with 780 additions and 819 deletions
Download Patch File Download Diff File Expand all files Collapse all files

111
docs/md/attributes.md
View File

@@ -1,8 +1,9 @@
Attributed Variables and Co-Routining {#AttributedVariables}
====================================
@defgroup AttributedVariables Attributed Variables and Co-Routining
@ingroup extensions
@{
YAP supports attributed variables, originally developed at OFAI by
Christian Holzbaur. Attributes are a means of declaring that an
@@ -27,9 +28,8 @@ work with. Most packages included in YAP that use attributed
variables, such as CHR, CLP(FD), and CLP(QR), rely on the SWI-Prolog
awi interface.
[TOC]
@defgroup SICS_attributes SICStus Style attribute declarations.
## SICStus Style attribute declarations. {#SICS_attributes}
The YAP library `atts` implements attribute variables in the style of
SICStus Prolog. Attributed variables work as follows:
@@ -82,9 +82,10 @@ mechanism is used for this purpose.
The attribute manipulation predicates always work as follows:
+ The first argument is the unbound variable associated with
+ The first argument is the unbound variable associated with
attributes,
+ The second argument is a list of attributes. Each attribute will
+ 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.
@@ -99,9 +100,9 @@ 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:
At execution conclusion, attributes still unsatisfied are 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
@@ -269,12 +270,11 @@ 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`.
Module:get_atts/2.
@}
@{
#### hProlog and SWI-Prolog style Attribute Declarations {#New_Style_Attribute_Declarations}
hProlog and SWI-Prolog style Attribute Declarations {#New_Style_Attribute_Declarations}
------------------------------------------------
The following documentation is taken from the SWI-Prolog manual.
@@ -286,24 +286,28 @@ Module:get_atts/2`.
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)).
~~~~~
:- 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.
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 %
The next predicate is called *after* _X_, the attributed variable with attribute value _Domain_ has been
assigned the value Y.
attr_unify_hook(Domain, Y) :-
~~~~~
attr_unify_hook(Domain, Y) :-
( get_attr(Y, domain, Dom2)
-> ord_intersection(Domain, Dom2, NewDomain),
( NewDomain == []
@@ -316,15 +320,17 @@ v put_attr(Y, domain, Domain),
-> put_attr( Y, domain, Domain )
; ord_memberchk(Y, Domain)
).
~~~~~
% Translate attributes from this module to residual goals %
The user defined attribute_goals/1 attributes from this module to residual goals
attribute_goals(X) -->
~~~~~
attribute_goals(X) -->
{ get_attr(X, domain, List) },
[domain(X, List)].
~~~~~
~~~~~
Before explaining the code we give some example queries:
Before explaining the code in detail 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
@@ -342,11 +348,8 @@ v put_attr(Y, domain, Domain),
remaining attributes to user-readable goals that, when executed, reinstate
these attributes.
@}
@{
#### Co-routining {#CohYroutining}
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
@@ -359,31 +362,27 @@ 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.
+ 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.
+ 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
- freeze/2
- dif/2
- dif/2
- when/2
- when/2
- frozen/2
- frozen/2
@}
@}

56
docs/md/builtins.md
View File

@@ -6,57 +6,15 @@ Prolog programs, provide fundamental functionality such as termm manipulation or
resources,
Many of the predicates described here have been standardised by the International Standard Organization.
The corresponding standartised subset of Prolog also known as ISO-Prolog.
The corresponding standartised subset of Prolog also known as ISO-Prolog.
In the description of the arguments of predicates the following
notation will be used:
+ a preceding plus sign will denote an argument as an "input
argument" - the argument is read, not written, and 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.
+ a preceding plus sign will denote an argument as an "input
argument" - the argument is read, not written, and it cannot
be a free variable at the time of the call;
+ @ref AbsoluteFileName
+ @ref CompilerAnalysis
+ @ref New_Style_Attribute_Declarations
+ @ref YAPControl
+ @ref Profiling
+ @ref Call_Counting
+ @ref YAPConsulting
+ @ref YAPReadFiles
+ @ref ModPreds
+ @ref Conditional_Compilation
+ @ref YAPBigLoad
+ @ref Deb_Interaction
+ @ref DepthLimited
+ @ref Dialects
+ @ref Directives
+ @ref EAM
+ @ref SWI-error
+ @ref YAPErrorHandler
+ @ref CompiledExpression
+ @ref YAPFlags
+ @ref Grammars
+ @ref Hacks
+ @ref Listing
+ @ref LoadForeign
+ @ref Messages
+ @ref YAPMetaPredicates
+ @ref ModuleBuiltins
+ @ref YAPOS
+ @ref pathconf
+ @ref YAPPredDecls
+ @ref Database
+ @ref The_Count_Profiler
+ @ref QLY
+ @ref Sets
+ @ref Deb_Preds
+ @ref Statistics
+ @ref Tabling
+ @ref Threads
+ @ref TopLevel
+ @ref Undefined_Procedures
+ @ref MixBag
+ @ref InputOutput
+ @ref IO_Sockets
+ @ref ypp
+ a preceding minus sign will denote an "output argument";
+ an argument with no preceding symbol can be used in both ways.

29
docs/md/extensions.md
View File

@@ -4,18 +4,31 @@ Extensions to core Prolog. {#extensions}
YAP includes a number of extensions over the original Prolog
language. Next, we discuss how to use the most important ones.
+ @ref Rational_Trees
+ @ref Rational_Trees
+ @ref AttributedVariables
+ @ref AttributedVariables
+ @ref DepthLimited
+ @ref DepthLimited
+ @ref Tabling
+ @ref Tabling
+ @ref Threads
+ @ref Threads
+ @ref Profiling
+ @ref Profiling
+ @ref YAPArrays
+ @ref Parallelism
In the description of the arguments of predicates the following
notation will be used:
+ a preceding plus sign will denote an argument as an "input
argument": the argument is read, not written, and 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.
+ @ref YAPArrays
+ @ref Parallelism

74
docs/md/library.md
View File

@@ -1,61 +1,27 @@
YAP Prolog Library {#library}
YAP Prolog Library {#LibraryPage}
===================
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.
YAP provides a collection of Prolog utilities, that extend core Prolog
with data-structures such as balanced trees and hash tables, extend
Input Output, or use the `C`-interface to interact with the
Operating System or to implement arrays.
These programs are stored at the library_directory path (set by the
`LIBDIR` variable in the Makefile for YAP).
@tableofcontents
The files have different sources. Many were part of the public-domain
Edinburgh Prolog library. Other Prolog systems such as SWI-Prolog
were kind enough to allow using files from their distributions.
@copydoc library
+ @ref apply_stub
+ @ref apply_macros
+ @ref args
+ @ref Association_Lists
+ @ref sicsatts
+ @ref avl
+ @ref bhash
+ @ref block_diagram
+ @ref c_alarms
+ @ref charsio
+ @ref clauses
+ @ref cleanup
+ @ref dbqueues
+ @ref dbusage
+ @ref dgraphs
+ @ref exo_interval
+ @ref flags
+ @ref gensym
+ @ref yap_hacks
+ @ref heaps
+ @ref lam_mpi
+ @ref line_utils
+ @ref Log2MD
+ @ref mapargs
+ @ref maplist
+ @ref matlab
+ @ref matrix
+ @ref nb
+ @ref ordsets
+ @ref parameters
+ @ref queues
+ @ref random
+ @ref Pseudo_Random
+ @ref rbtrees
+ @ref readutil
+ @ref regexp
+ @ref rltrees
+ @ref Splay_Trees
+ @ref operating_system_support
+ @ref Terms
+ @ref timeout
+ @ref trees
+ @ref tries
+ @ref ugraphs
+ @ref undgraphs
+ @ref varnumbers
+ @ref wdgraphs
+ @ref wgraphs
+ @ref wundgraphs
@{
@defgroup library The YAP Library
@}

2
docs/md/load_files.md
View File

@@ -6,7 +6,7 @@ Loading and Organising YAP Programs {#load_files}
+ @ref YAPConsulting
- @page modules
+ @page modules
+ @ref YAPBigLoad

8
docs/md/modules.md
View File

@@ -40,7 +40,8 @@ the type-in module permanently by using the built-in `module/1`.
[TOC]
## Explicit Naming {#ExplicitNaming}
Explicit Naming {#ExplicitNaming}
+++++++++++++++
The module system allows one to _explicitly_ specify the source mode for
a clause by prefixing a clause with its module, say:
@@ -228,7 +229,8 @@ X = 2 ? ;
The state of the module system after this error is undefined.
## BuiltIn predicates {#ModuleBuiltins)
BuiltIn predicates {#ModuleBuiltins)
++++++++++++++++++
@\pred module(+ M:atom,+ L:list ) is directive
the current file defines module _M_ with exports _L_. The list may include
@@ -298,7 +300,7 @@ the graphs library is implemented on top of the red-black trees library, and som
Unfortunately it is still not possible to change argument order.
\pred module(+ M:atom,+ L:list ) is directive
@pred module(+ M:atom,+ L:list ) is directive
the current file defines module _M_ with exports _L_. The list may include
+ predicate indicators

67
docs/md/syntax.md
View File

@@ -1,6 +1,6 @@
YAP Syntax {#YAPSyntax}
============
@defgroup YAPSyntax YAP Syntax
@{
@ingroup YAPProgrammming
We will describe the syntax of YAP at two levels. We first will
@@ -9,6 +9,7 @@ the tokens from which Prolog terms are
built.
@defgroup Formal_Syntax Syntax of Terms
@{
@ingroup YAPSyntax
Below, we describe the syntax of YAP terms from the different
@@ -82,19 +83,22 @@ paragraph). When a name consisting of a single dot could be taken for
the end of term marker, the ambiguity should be avoided by surrounding the
dot with single quotes.
@}
@defgroup Tokens Prolog Tokens
# @defgroup Tokens Prolog Tokens
@{
@ingroup YAPSyntax
Prolog tokens are grouped into the following categories:
## @defgroup 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
@@ -141,8 +145,10 @@ YAP (version 6.3.4) supports integers that can fit
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.
@}
### @defgroup Floats Floats
@defgroup Floats Floats
@}
@ingroup Numbers
Floating-point numbers are described by:
@@ -167,7 +173,10 @@ Examples:
Floating-point numbers are represented as a double in the target
machine. This is usually a 64-bit number.
## Strings @defgroup Strings Character Strings
@}
@}
@defgroup Strings Character Strings
@{
Strings are described by the following rules:
@@ -218,7 +227,7 @@ Escape sequences can be used to include the non-printable characters
`f` (form feed), `t` (horizontal tabulation), `n` (new
line), and `v` (vertical tabulation). Escape sequences also be
include the meta-characters `\\`, `"`, `'`, and
```. Last, one can use escape sequences to include the characters
`''`. Last, one can use escape sequences to include the characters
either as an octal or hexadecimal number.
The next examples demonstrates the use of escape sequences in YAP:
@@ -237,7 +246,12 @@ versions of YAP up to 4.2.0. Escape sequences can be disabled by using:
:- yap_flag(character_escapes,false).
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
## @addgroup Atoms Atoms
@}
@addtogroup Atoms Atoms
@}
@ingroup Tokens
Atoms are defined by one of the following rules:
@@ -278,7 +292,10 @@ Version `4.2.0` of YAP removed the previous limit of 256
characters on an atom. Size of an atom is now only limited by the space
available in the system.
## @addgroup Variables Variables
@}
@addtogroup Variables Variables
@{
@ingroup Tokens
Variables are described by:
@@ -299,7 +316,9 @@ variables are known as anonymous variables. Note that different
occurrences of `_` on the same term represent <em>different</em>
anonymous variables.
## @addgroup Punctuation_Tokens Punctuation Tokens
@}
@addtogroup Punctuation_Tokens Punctuation Tokens
@{
@ingroup Tokens
Punctuation tokens consist of one of the following characters:
@@ -309,7 +328,10 @@ Punctuation tokens consist of one of the following characters:
These characters are used to group terms.
@subsection LayoutComents Character Layout
@}
@defgroup LayoutComents Character Layout
@{
@ingroup Tokens
Any characters with ASCII code less than or equal to 32 appearing before
a token are ignored.
@@ -321,8 +343,11 @@ 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.
## @addgroup WideChars Encoding Wide Character Support
@ingroup YAPSyntax
@}
@}
@addtogroup WideChars Encoding Wide Character Support
@{
@ingroup YAPSyntax
YAP now implements a SWI-Prolog compatible interface to wide
@@ -353,7 +378,8 @@ other software components using the foreign language interface. In this
section we only deal with I/O through streams, which includes file I/O
as well as I/O through network sockets.
== @addtogroup Stream_Encoding Wide character encodings on streams
@addtogroup Stream_Encoding Wide character encodings on streams
@{
@ingroup WideChars
The UCS standard describes all possible characters (or code points, as they include
@@ -460,9 +486,10 @@ errors can be controlled using `open/4` or `set_stream/2` (not
implemented). Initially the terminal stream write the characters using
Prolog escape sequences while other streams generate an I/O exception.
@{
@}
@addtogroup BOM BOM: Byte Order Mark
@{
@ingroup WideChars
From Stream Encoding, you may have got the impression that
@@ -483,11 +510,10 @@ 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.
@{
@}
@}
@addgroup Operators Summary of YAP Predefined Operators
@{
@ingroup YapSyntax
The Prolog syntax caters for operators of three main kinds:
@@ -567,3 +593,4 @@ The following is the list of the declarations of the predefined operators:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@}
@}

37
docs/md/yap.md
View File

@@ -60,43 +60,6 @@ Jan Wielemaker. We would also like to gratefully
acknowledge the contributions from Ashwin Srinivasian.
@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.
@page Extensions YAP Extensions
YAP includes a number of extensions over the original Prolog
language.
+ @subpage attributes.md
+ @ref Rational_Trees
+ @ref CohYroutining
+ @ref DepthLimited
+ @ref Tabling
+ @ref Threads
+ @ref Profiling
+ @ref YAPArrays
+ @ref Parallelism
@page YAPProgramming Programming in YAP
@page packages Packages for YAP