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

doc support

Browse Source
This commit is contained in:
Vítor Santos Costa
2015-01-04 23:58:23 +00:00
parent a87f1040ac
commit 3164ed2d61
124 changed files with 625 additions and 645 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
pl/absf.yap
View File

@@ -8,9 +8,11 @@
* *
*************************************************************************/
%% @{
/** @defgroup YAPAbsoluteFileName File Name Resolution
@ingroup YAPBuiltins
@ingroup builtins
Support for file name resolution through absolute_file_name/3 and
friends. These utility built-ins describe a list of directories that
@@ -18,9 +20,7 @@
plus user-defined directories, directories based on environment
variables and registry information to search for files.
@{
**/
**/
:- system_module( absolute_file_name, [absolute_file_name/2,
absolute_file_name/3,

2
pl/arith.yap
View File

@@ -57,6 +57,8 @@
*/
%% @{
/** @pred expand_exprs(- _O_,+ _N_)
Control term expansion during compilation.

3
pl/arithpreds.yap
View File

@@ -15,13 +15,14 @@
* *
*************************************************************************/
%% @{
/**
@file arithpreds.yap
@addtogroup arithmetic_preds
@{
*/
:- system_module(arithmetic_predicates, [

7
pl/arrays.yap
View File

@@ -15,6 +15,8 @@
* *
*************************************************************************/
%% @{
/**
@addtogroup YAPArrays
*/
@@ -102,7 +104,4 @@ static_array_properties(Name, Size, Type) :-
static_array_properties(Name, Size, Type) :-
'$do_error'(type_error(atom,Name),static_array_properties(Name,Size,Type)).
%% @}

7
pl/atoms.yap
View File

@@ -8,6 +8,8 @@
* *
*************************************************************************/
%% @{
:- system_module( '$_atoms', [
atom_concat/2,
string_concat/2,
@@ -17,8 +19,11 @@
:- use_system_module( '$_errors', ['$do_error'/2]).
%% @{
/**
* @addtogroup Predicates_on_Atoms
* @addtogroup Predicates_on_Atoms
* @ingroup YAPChars
*
*/

172
pl/attributes.yap
View File

@@ -1,6 +1,6 @@
/*************************************************************************
* *
* YAP Prolog *
* YAP Prolog *
* *
* Yap Prolog was developed at NCCUP - Universidade do Porto *
* *
@@ -15,17 +15,22 @@
* *
*************************************************************************/
%% @{
/** @defgroup Attributed_Variables Attributed Variables
@ingroup YAPExtensions
/**
@file attributes.yap
@defgroup Attributed_Variables Attributed Variables
@ingroup extensions
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
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.
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
@@ -42,85 +47,13 @@ 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.
@{
+ Old_Style_Attribute_Declarations
+ New_Style_Attribute_Declarations
*/
/** @defgroup New_Style_Attribute_Declarations hProlog and SWI-Prolog style Attribute Declarations
@ingroup Attributed_Variables
@{
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),
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.
*/
:- module('$attributes', [
delayed_goals/4
]).
@@ -145,6 +78,83 @@ these attributes.
woken_att_do/4]).
/**
@{
@defgroup New_Style_Attribute_Declarations hProlog and SWI-Prolog style Attribute Declarations
@ingroup Attributed_Variables
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),
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.
*/
:- dynamic attributes:attributed_module/3, attributes:modules_with_attributes/1.
/** @pred get_attr(+ _Var_,+ _Module_,- _Value_)

11
pl/boot.yap
View File

@@ -15,12 +15,13 @@
* *
*************************************************************************/
%% @{
/**
@defgroup YAPControl Control Predicates
@ingroup YAPBuiltins
@{
@ingroup builtins
*/
@@ -1529,8 +1530,6 @@ The goal `throw( _Ball_)` throws an exception. Execution is
stopped, and the exception is sent to the ancestor goals until reaching
a matching catch/3, or until reaching top-level.
@}
*/
throw(_Ball) :-
% use existing ball
@@ -1590,6 +1589,6 @@ log_event( String, Args ) :-
log_event( M ).
/**
@}
@}
*/

20
pl/callcount.yap
View File

@@ -15,11 +15,11 @@
* *
*************************************************************************/
%% @{
/** @defgroup Profiling Profiling Prolog Programs
@ingroup YAPExtensions
@{
@ingroup extensions
YAP includes two profilers. The count profiler keeps information on the
number of times a predicate was called. This information can be used to
detect what are the most commonly called predicates in the program. The
@@ -35,15 +35,11 @@ implementation.
*/
/**
@}
*/
%% @{
/** @defgroup Call_Counting Counting Calls
@ingroup Profiling
@{
Predicates compiled with YAP's flag call_counting set to
`on` update counters on the numbers of calls and of
retries. Counters are actually decreasing counters, so that they can be
@@ -63,10 +59,7 @@ The code for the call counters piggybacks on the profiling
code. Therefore, activating the call counters also activates the profiling
counters.
These are the predicates that access and manipulate the call counters:
These are the predicates that access and manipulate the call counters.
*/
:- system_module( '$_callcount', [call_count/3,
@@ -151,6 +144,7 @@ call_count(Calls, Retries, Both) :-
'$check_if_call_count_on'(Calls, A) :-
'$do_error'(type_error(integer,Calls),call_count(A)).
%% @}
/**
@}

6
pl/checker.yap
View File

@@ -69,6 +69,8 @@
'$syntax_check_multiple'/2,
'$syntax_check_single_var'/2]).
%% @{
/**
@defgroup YAPStyle Checker
@@ -113,9 +115,7 @@ By default, style checking is disabled in YAP unless we are in
The style_check/1 built-in is now deprecated. Please use
`set_prolog_flag/1` instead.
@{
**/
**/
%
% A Small style checker for YAP

6
pl/chtypes.yap
View File

@@ -17,6 +17,12 @@
:- system_module( '$_chtypes', [], []).
/**
* @defgroup YAPChars Sequences of Characters: atoms, strings, lists of codes.
* @ingroup builtins
*
*/
/*
In addition, there is the library library(ctype) providing compatibility to some other Prolog systems. The predicates of this library are defined in terms of code_type/2.

53
pl/consult.yap
View File

@@ -65,9 +65,11 @@
:- use_system_module( '$_preds', ['$current_predicate'/4]).
%% @{
/**
\defgroup YAPConsulting Loading files into YAP
@ingroup YAPLoading
@defgroup YAPConsulting Loading files into YAP
@ingroup consult
We present the main predicates and directives available to load
files and to set-up the Prolog environment. We discuss
@@ -79,10 +81,9 @@ files and to set-up the Prolog environment. We discuss
@{
@defgroup YAPReadFiles The Predicates that Read Source Files
@ingroup YAPConsulting
@{
@ingroup consult
*/
@@ -947,19 +948,20 @@ source_file(Mod:Pred, FileName) :-
SWI-compatible predicate. True if the predicate specified by _ModuleAndPred_ was loaded from file _File_, where _File_ is an absolute path name (see `absolute_file_name/2`).
@}
*/
%% @}
%% @{
{
/** @addtogroup YAPLibraries Library Predicates
Library files reside in the library_directory path (set by the
`LIBDIR` variable in the Makefile for YAP). Currently,
most files in the library are from the Edinburgh Prolog library.
@{
*/
*/
prolog_load_context(directory, DirName) :-
( source_location(F, _)
-> file_directory_name(F, DirName) ;
@@ -1223,15 +1225,15 @@ unload_file( F0 ) :-
erase(R),
fail.
%% @}
/**
@}
@{
@addtogroup YAPModules
@{
**/
%
@@ -1339,8 +1341,10 @@ account the following observations:
@}
**/
%% @{
/** @defgroup YAPCompilerSettings Directing and Configuring the Compiler
@ingroup YAPConsulting
@ingroup YAPProgramming
The YAP system also includes a number of primitives designed to set
compiler parameters and to track the state of the compiler. One
@@ -1352,7 +1356,6 @@ account the following observations:
This section presents a set of built-ins predicates designed to set the
environment for the compiler.
@{
*/
@@ -1365,8 +1368,6 @@ internal conventions are Unix and this predicates is equivalent to =/2
directory-separator, limit the filename length map dots, except for the
last one, onto underscores.
@{
*/
% add_multifile_predicate when we start consult
@@ -1495,15 +1496,17 @@ initialization(G,OPT) :-
@}
*/
%% @{
/**
@defgroup Conditional_Compilation Conditional Compilation
@ingroup YAPCompilerSettings
@{
Conditional compilation builds on the same principle as
Conditional compilation builds on the same principle as
term_expansion/2, goal_expansion/2 and the expansion of
grammar rules to compile sections of the source-code
conditionally. One of the reasons for introducing conditional
@@ -1533,12 +1536,9 @@ section_2.
section_3.
:- else.
section_else.
:- endif.
:- endif.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@{
*/
/** @pred if( : _Goal_)
@@ -1687,8 +1687,5 @@ consult_depth(LV) :- '$show_consult_level'(LV).
@}
@}
@}
*/

24
pl/corout.yap
View File

@@ -16,9 +16,10 @@
*************************************************************************/
/** @defgroup CohYroutining Co-routining
@ingroup YAPExtensions
@{
/**
@defgroup CohYroutining Co-routining
@ingroup extensions
@{
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
@@ -119,16 +120,14 @@ 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.
*/
@pred get_attrs(+ _Var_,- _Attributes_)
/**
@pred get_attrs(+ _Var_,- _Attributes_)
Get all attributes of _Var_. _Attributes_ is a term of the form
`att( _Module_, _Value_, _MoreAttributes_)`, where _MoreAttributes_ is
`[]` for the last attribute.
*/
attribute_goals(Var) -->
@@ -162,9 +161,9 @@ remove_when_declarations(Goal, Goal).
%
% operators defined in this module:
%
/** @pred freeze(? _X_,: _G_)
/**
@pred freeze(? _X_,: _G_)
Delay execution of goal _G_ until the variable _X_ is bound.
@@ -618,5 +617,6 @@ check_first_attvar([_|Vs], V0) :-
check_first_attvar(Vs, V0).
/**
@}
@}
@}
*/

2
pl/debug.yap
View File

@@ -46,7 +46,7 @@
-----------------------------------------------------------------------------*/
/** @defgroup Deb_Preds Debugging Predicates
@ingroup YAPBuiltins
@ingroup builtins
@{
The

2
pl/depth_bound.yap
View File

@@ -18,7 +18,7 @@
/**
@defgroup DepthLimited Depth Limited Search
@ingroup YAPExtensions
@ingroup extensions
YAP implements various extensions to the default Prolog search. One of
the most iseful s restricting the maximum search depth.

2
pl/flags.yap
View File

@@ -27,7 +27,7 @@
yap_flag/3], []).
/** @defgroup Flags YAP Execution Flags
@ingroup YAPBuiltins
@ingroup builtins
@{
*/

2
pl/grammar.yap
View File

@@ -18,7 +18,7 @@
/**
@defgroup Grammars Grammar Rules
@ingroup YAPBuiltins
@ingroup builtins
@{
Grammar rules in Prolog are both a convenient way to express definite

2
pl/init.yap
View File

@@ -14,7 +14,7 @@
* comments: initializing the full prolog system *
* *
*************************************************************************/
%% @defgroup YAPBuiltins YAP Built-Ins
%% @defgroup builtins YAP Built-Ins
/*

2
pl/load_foreign.yap
View File

@@ -25,7 +25,7 @@
:- use_system_module( '$_modules', ['$do_import'/3]).
/** @defgroup LoadForeign Access to Foreign Language Programs
@ingroup YAPBuiltins
@ingroup builtins
*/

10
pl/messages.yap
View File

@@ -16,9 +16,10 @@
* *
*************************************************************************/
/** @defgroup Messages Message Handling
@ingroup YAPControl
@{
/**
@defgroup Messages Message Handling
@ingroup YAPControl
@{
The interaction between YAP and the user relies on YAP's ability to
portray messages. These messages range from prompts to error
@@ -679,5 +680,6 @@ pred_arity(H,Name,Arity) :-
/**
@}
@}
@}
*/

76
pl/modules.yap
View File

@@ -15,83 +15,11 @@
* *
*************************************************************************/
/**
@defgroup YAPPackages The YAP packages
@defgroup YAPLibrary The YAP Library
Library files reside in 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.
+ @ref maplist
+ @ref Apply Apply Macros
+ @ref Association_Lists
+ @ref AVL_Trees
+ @ref Exo_Intervals
+ @ref Heaps
+ @ref Lists
+ @ref LineUtilities
+ @ref matrix
+ @ref NonhYBacktrackable_Data_Structures
+ @ref Ordered_Sets
+ @ref Pseudo_Random
+ @ref Queues Queues
+ @ref PseudoRandom
+ @ref RedhYBlack_Trees
+ @ref RegExp
+ @ref Splay_Trees
+ @ref System
+ @ref Terms
+ @ref Tries
+ @ref Cleanup
+ @ref Timeout
+ @ref Trees
+ @ref UGraphs
+ @ref DGraphs
+ @ref UnDGraphs
+ @ref DBUsage
+ @ref lambda
+ @ref clpfd
+ @ref Block_Diagram
*/
/**
\defgroup YAPModules The YAP Module system
@ingroup YAPLoading
@ingroup consult
The YAP module system is based on the Quintus/SISCtus module
system ˜\cite quintus . In this design, modules are named collections of predicates,
@@ -127,7 +55,7 @@ YAP includes a number of libraries and packages, most of them
The main mechanism to change the current type-in module is by using
the module/2 declaration.This declaration sets the source module when
it starts consulting a file, and resets it at the end. One can set
it starts consulting a file, and resets it at the end. One can set
the type-in module permanently by using the built-in `module/1`.
\subsection Explicit Naming

8
pl/os.yap
View File

@@ -22,10 +22,12 @@
], [] ).
:- use_system_module( '$_errors', ['$do_error'/2]).
/** @defgroup YAPOS Access to Operating System Functionality
@ingroup YAPBuiltins
@{
%% @{
/** @defgroup YAPOS Access to Operating System Functionality
@ingroup builtins
The following built-in predicates allow access to underlying
Operating System functionality.

6
pl/preds.yap
View File

@@ -1,6 +1,6 @@
/*************************************************************************
* *
* YAP Prolog *
* YAP Prolog *
* *
* Yap Prolog was developed at NCCUP - Universidade do Porto *
* *
@@ -16,7 +16,7 @@
*************************************************************************/
/** @defgroup Database Using the Clausal Data Base
@ingroup YAPBuiltins
@ingroup builtins
@{
Predicates in YAP may be dynamic or static. By default, when
@@ -1167,6 +1167,7 @@ predicate_erased_statistics(P,NCls,Sz,ISz) :-
Defines the relation: _P_ is a currently defined predicate whose name is the atom _A_.
*/
current_predicate(A,T) :-
'$system_module'(M),
'$ground_module'(T, M, T0),
(
'$current_predicate'(A, M, T0, _)
@@ -1187,7 +1188,6 @@ system_predicate(A,T) :-
;
'$current_predicate'(A, prolog, T0, Flags)
),
Flags /\ 0x00004000 =\= 0,
\+ '$hidden'(A).
/** @pred system_predicate( ?_P_ )

11
pl/protect.yap
View File

@@ -19,6 +19,13 @@
% This protects all code from further changes
% and also makes it impossible from some predicates to be seen
'$protect' :-
fail,
'$system_mod'( M ),
'$current_predicate'(A, M, T0, Flags),
NFlags is Flags \/ 0x00004000,
'$flags'(M:T0, Flags, NFlags),
fail.
'$protect' :-
current_atom(Name),
atom_codes(Name,[0'$|_]),
@@ -30,8 +37,8 @@
'$protect'.
'$hide_predicates'(Name) :-
'$current_predicate'(Name, prolog, P, _),
'$hide_predicate'(P,prolog),
'$current_predicate'(Name, Mod, P, _),
'$hide_predicate'(P,Mod),
fail.
'$hide_predicates'(_).

2
pl/qly.yap
View File

@@ -45,7 +45,7 @@
/**
@defgroup YAPSaving Saving and Loading Prolog States
@ingroup YAPLoading
@ingroup consult
YAP can save and read images of its current state to files, known as
saved states. It is possible to save the entire state or just a module

2
pl/setof.yap
View File

@@ -17,7 +17,7 @@
/** @defgroup Sets Collecting Solutions to a Goal
@ingroup YAPBuiltins
@ingroup builtins
@{
When there are several solutions to a goal, if the user wants to collect all

2
pl/tabling.yap
View File

@@ -17,7 +17,7 @@
:- use_system_module( '$_errors', ['$do_error'/2]).
/** @defgroup Tabling Tabling
@ingroup YAPExtensions
@ingroup extensions
@{
*YAPTab* is the tabling engine that extends YAP's execution

2
pl/threads.yap
View File

@@ -17,7 +17,7 @@
/**
@defgroup Threads Threads
@ingroup YAPExtensions
@ingroup extensions
@{
YAP implements a SWI-Prolog compatible multithreading

2
pl/yio.yap
View File

@@ -55,7 +55,7 @@
:- use_system_module( '$_errors', ['$do_error'/2]).
/** @defgroup InputOutput Input/Output Predicates
@ingroup YAPBuiltins
@ingroup builtins
Some of the Input/Output predicates described below will in certain conditions
provide error messages and abort only if the file_errors flag is set.