From 0507d804038d3a1b911042e8fec114eac36d9421 Mon Sep 17 00:00:00 2001 From: Vitor Santos Costa Date: Wed, 30 Jan 2019 11:17:53 +0000 Subject: [PATCH] docs --- H/YapGFlagInfo.h | 25 ++++++++++++++++--------- docs/md/INSTALL.md | 18 ++++++++---------- docs/md/run.md | 2 +- library/charsio.yap | 1 + library/clp/clpfd.pl | 12 +++++++----- library/coinduction.yap | 2 ++ library/maplist.yap | 19 ++++++++++++------- library/splay.yap | 37 +++++++++++++++++++------------------ pl/consult.yap | 10 ++++++---- pl/imports.yap | 17 +++++++++-------- pl/top.yap | 17 +++++++---------- 11 files changed, 88 insertions(+), 72 deletions(-) diff --git a/H/YapGFlagInfo.h b/H/YapGFlagInfo.h index f8466d7dd..e822ad1be 100644 --- a/H/YapGFlagInfo.h +++ b/H/YapGFlagInfo.h @@ -149,14 +149,14 @@ opportunity. Initial value is 10,000. May be changed. A value of 0 YAP_FLAG(CHARACTER_ESCAPES_FLAG, "character_escapes", true, booleanFlag, "true", NULL), - /**< `compiled_at ` + YAP_FLAG(COLON_SETS_CALLING_CONTEXT_FLAG, "colon_sets_calling_context", + true, booleanFlag, "true", NULL), + + /**< Read-only flag that gives the time when the main YAP binary was compiled. It is obtained staight from the __TIME__ macro, as defined in the C99. */ - YAP_FLAG(COLON_SETS_CALLING_CONTEXT_FLAG, "colon_sets_calling_context", - true, booleanFlag, "true", NULL), - YAP_FLAG(COMPILED_AT_FLAG, "compiled_at", false, isatom, YAP_COMPILED_AT, NULL), /**< @@ -167,18 +167,25 @@ opportunity. Initial value is 10,000. May be changed. A value of 0 */ YAP_FLAG(DEBUG_FLAG, "debug", true, booleanFlag, "false", NULL), - YAP_FLAG(DEBUG_INFO_FLAG, "debug_info", true, booleanFlag, "true", NULL), - /**< + // YAP_FLAG(DEBUG_INFO_FLAG, "debug_info", true, booleanFlag, "true", NULL), + /**< + +Says whether to call the debUgger on an exception. False in YAP.. + */ + YAP_FLAG(DEBUG_ON_ERROR_FLAG, "debug_on_error", true, booleanFlag, "false", + NULL), + + /**< If bound, set the argument to the `write_term/3` options the debugger uses to write terms. If unbound, show the current options. */ - YAP_FLAG(DEBUG_ON_ERROR_FLAG, "debug_on_error", true, booleanFlag, "true", - NULL), - YAP_FLAG(DEBUGGER_PRINT_OPTIONS_FLAG, "debugger_print_options", true, list_option, "[quoted(true),numbervars(true),portrayed(true),max_depth(10)]", NULL), + /**< +Show their ancestors while debuggIng + */ YAP_FLAG(DEBUGGER_SHOW_CONTEXT_FLAG, "debugger_show_context", true, booleanFlag, "false", NULL), /**< diff --git a/docs/md/INSTALL.md b/docs/md/INSTALL.md index 5d28f4063..5e1aaac9f 100644 --- a/docs/md/INSTALL.md +++ b/docs/md/INSTALL.md @@ -53,21 +53,19 @@ generate Makefiles, Ninja, Apple's XCode, VisualStudio and ANdroid Studio, and because it includes packaging suppport, The steps required to install core YAP under `cmake` are presented in detail next. -@subsubsection Compilation The compiler +@subsection Compilation The compiler: *Status as of early 2017* - *Status as of early 2017* +YAP should compile well under the [GNU-CC](https://gcc.gnu.org/) and + the [C-LANG](https://clang.llvm.org/) families, that are available + across most configurations. It sshould also compile well undder + Intel `icc`. - YAP should compile well under the [GNU-CC](https://gcc.gnu.org/) - and the [C-LANG](https://clang.llvm.org/) families, that are - available across most configurations. It sshould also compile well - undder Intel `icc`. - - We do not recommend using Microoft's VC++. To the best of our +We do not recommend using Microoft's VC++. To the best of our knowledge MSC does not support threaded emulation, which YAP recquires for performance, You can still use the IDE, and experiment with the c-lang plugin. - YAP compiles cleanly under cross-compilers, and we have used the +YAP compiles cleanly under cross-compilers, and we have used the crosss-compilation system [mxe](http://mxe.cc/) system with good results. @subsection cmake cmake @@ -214,7 +212,7 @@ brew install cudd cmake -DOPENSSL_ROOT_DIR=/usr/local/opt/openssl .. ~~~~~ -@sususbsection TuningDroid Compilation Notes for Android +@subsection TuningDroid Compilation Notes for Android Next we present the compilation process for Android. The environment is an OSX, but steps should be similar for Linux machines. We assume you have downloaded both the Android NDK and the Android SDK. diff --git a/docs/md/run.md b/docs/md/run.md index ed32ea1a2..c96a8221a 100644 --- a/docs/md/run.md +++ b/docs/md/run.md @@ -88,7 +88,7 @@ the environment variable YAPBINDIR. + YAP will try to find library files from the YAPSHAREDIR/library directory. @section RunningScripts Running Prolog Files --------------------- + YAP can also be used to run Prolog files as scripts, at least in Unix-like environments. A simple example is shown next (do not forget diff --git a/library/charsio.yap b/library/charsio.yap index 3055dac5b..150e4b8e4 100644 --- a/library/charsio.yap +++ b/library/charsio.yap @@ -45,6 +45,7 @@ /** @defgroup charsio Operations on Sequences of Codes. @ingroup library +@{ Term to sequence of codes conversion, mostly replaced by engine code. You can use the following directive to load the files. diff --git a/library/clp/clpfd.pl b/library/clp/clpfd.pl index e20b4ab8a..1615baaee 100644 --- a/library/clp/clpfd.pl +++ b/library/clp/clpfd.pl @@ -1,5 +1,7 @@ /* $Id$ +@file clpfd/clpfd.pl + Part of SWI-Prolog Author: Markus Triska @@ -91,7 +93,7 @@ used in modes that can also be handled by built-in arithmetic. To currently, let us define a new custom constraint "oneground(X,Y,Z)", where Z shall be 1 if at least one of X and Y is instantiated: - == + ~~ :- use_module(library(clpfd)). :- multifile clpfd:run_propagator/2. @@ -107,7 +109,7 @@ used in modes that can also be handled by built-in arithmetic. To ; integer(Y) -> clpfd:kill(MState), Z = 1 ; true ). - == + ~~~ First, clpfd:make_propagator/2 is used to transform a user-defined representation of the new constraint to an internal form. With @@ -124,12 +126,12 @@ used in modes that can also be handled by built-in arithmetic. To the constraint has become entailed, by using clpfd:kill/1. An example of using the new constraint: - == + ~~~ ?- oneground(X, Y, Z), Y = 5. Y = 5, Z = 1, X in inf..sup. - == + ~~~ @author Markus Triska */ @@ -192,7 +194,7 @@ used in modes that can also be handled by built-in arithmetic. To ]). -:- expects_dialect(swi). +% :- expects_dialect(swi). :- use_module(library(assoc)). :- use_module(library(apply)). diff --git a/library/coinduction.yap b/library/coinduction.yap index fe53d7712..9552a72fd 100644 --- a/library/coinduction.yap +++ b/library/coinduction.yap @@ -80,6 +80,8 @@ regardless of the cycle-length. @see "Co-Logic Programming: Extending Logic Programming with Coinduction" by Luke Somin et al. +@addtogroup coinduction Co-induction +@ingroup library @{ */ diff --git a/library/maplist.yap b/library/maplist.yap index 7d4cc40d2..b322fba98 100644 --- a/library/maplist.yap +++ b/library/maplist.yap @@ -488,6 +488,13 @@ sumnodes_body(Pred, Term, A1, A3, N0, Ar) :- /** @pred oldl(: _Pred_, + _List1_, + _List2_, ? _AccIn_, ? _AccOut_) + The foldl family of predicates is defined + == + foldl(P, [X11,...,X1n],V0, Vn, W0, WN) :- + P(X11, V0, V1, W0, W1), + ... + P(X1n, Vn1, Vn, Wn1, Wn). + == Calls _Pred_ on all elements of `List1` and collects a result in _Accumulator_. Same as foldr/3. */ @@ -506,13 +513,6 @@ foldl_([H|T], Goal, V0, V) :- _List2_ and collects a result in _Accumulator_. Same as foldr/4. - The foldl family of predicates is defined - == - foldl(P, [X11,...,X1n],V0, Vn, W0, WN) :- - P(X11, V0, V1, W0, W1), - ... - P(X1n, Vn1, Vn, Wn1, Wn). - == */ foldl(Goal, List1, List2, V0, V) :- foldl_(List1, List2, Goal, V0, V). @@ -524,6 +524,11 @@ foldl_([H1|T1], [H2|T2], Goal, V0, V) :- /** +@pred foldl(Goal, List1, List2, List3, V0, V) + +Apply _Goal_ plus five arguuments, three map to lists, +two can be used as a difference_type. + */ foldl(Goal, List1, List2, List3, V0, V) :- foldl_(List1, List2, List3, Goal, V0, V). diff --git a/library/splay.yap b/library/splay.yap index 37b17dd03..5066fb20f 100644 --- a/library/splay.yap +++ b/library/splay.yap @@ -147,13 +147,9 @@ will fail if _Key_ is not present. */ -/** @pred splay_init(- _NewTree_) +splay_access(V, Item, Val, Tree, NewTree):- + bst(access(V), Item, Val, Tree, NewTree). - -Initialize a new splay tree. - - -*/ /** @pred splay_insert(+ _Key_,? _Val_,+ _Tree_,- _NewTree_) @@ -165,6 +161,13 @@ already there: rather it is unified with the item already in the tree. */ +splay_insert(Item, Val,Tree, NewTree):- + bst(insert, Item, Val, Tree, NewTree). + +splay_del(Item, Tree, NewTree):- + bst(access(true), Item, Val, Tree, n(Item, Val, Left, Right)), + splay_join(Left, Right, NewTree). + /** @pred splay_join(+ _LeftTree_,+ _RighTree_,- _NewTree_) @@ -175,25 +178,16 @@ assumes that all items in _LeftTree_ are less than all those in */ -/** @pred splay_split(+ _Key_,? _Val_,+ _Tree_,- _LeftTree_,- _RightTree_) +splay_join(Left, Right, New):- + join(L-L, Left, Right, New). +/** @pred splay_split(+ _Key_,? _Val_,+ _Tree_,- _LeftTree_,- _RightTree_) Construct and return two trees _LeftTree_ and _RightTree_, where _LeftTree_ contains all items in _Tree_ less than _Key_, and _RightTree_ contains all items in _Tree_ greater than _Key_. This operations destroys _Tree_. */ - - -splay_access(V, Item, Val, Tree, NewTree):- - bst(access(V), Item, Val, Tree, NewTree). -splay_insert(Item, Val,Tree, NewTree):- - bst(insert, Item, Val, Tree, NewTree). -splay_del(Item, Tree, NewTree):- - bst(access(true), Item, Val, Tree, n(Item, Val, Left, Right)), - splay_join(Left, Right, NewTree). -splay_join(Left, Right, New):- - join(L-L, Left, Right, New). splay_split(Item, Val, Tree, Left, Right):- bst(access(true), Item, Val, Tree, n(Item, Val, Left, Right)). @@ -272,6 +266,13 @@ join(Left-n(Y, VY, n(X, VX, C, B), NL), n(X, VX, C, n(Y, VY, B, n(Z, VZ, A1, A2) join(Left-NL, n(Z, VZ,A1, A2), Right, New). +/** @pred splay_init(- _NewTree_) + + +Initialize a new splay tree. + + +*/ splay_init(_). /** @} */ diff --git a/pl/consult.yap b/pl/consult.yap index 59c57672a..029768dc7 100644 --- a/pl/consult.yap +++ b/pl/consult.yap @@ -1273,6 +1273,7 @@ module(Mod, Decls) :- % prevent modules within the kernel module... + /** @pred use_module(? _M_,? _F_,+ _L_) is directive SICStus compatible way of using a module @@ -1504,9 +1505,6 @@ initialization(_G,_OPT). @} */ -%% @{ - - /** @@ -1514,6 +1512,9 @@ initialization(_G,_OPT). @ingroup YAPCompilerSettings +%% @{ + + 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 @@ -1636,6 +1637,7 @@ no test succeeds the else branch is processed. '$elif'(_,_). /** @pred endif + End of conditional compilation. */ @@ -1688,7 +1690,7 @@ End of conditional compilation. current_prolog_flag(source, true), !. '$fetch_comp_status'(compact). -/** consult_depth(-int:_LV_) +/** @pred consult_depth(-int:_LV_) * * Unify _LV_ with the number of files being consulted. */ diff --git a/pl/imports.yap b/pl/imports.yap index 10c759ed7..606d9981a 100644 --- a/pl/imports.yap +++ b/pl/imports.yap @@ -7,7 +7,7 @@ */ /** - * @ingroup ModuleBuiltins + * @addtogroup ModuleBuiltins * @{ * * YAP follows the following protovol: @@ -15,10 +15,17 @@ * - predicate is in user * - predicate will be autoloaded, SWI style. */ + :- '$mk_dynamic'('$parent_module'(_,_),prolog). +/** @pred mimp + +debug import table + +*/ mimp :- - recorded('$import',I,_), %'$import'(ExportingMod,ImportingMod,G0,G,_,_),_), + recorded('$import',I,_), + %'$import'(ExportingMod,ImportingMod,G0,G,_,_),_), writeln(I), %(ImportingMod:G :- ExportingMod:G0)), fail. @@ -45,12 +52,6 @@ fail. -> '$get_undefined_predicates'(NewImportingMod:G, ExportingMod:G0). -/** - * - * @pred '$continue_imported'(+Modn, +ModOut, +Predn ,+PredOut) - * - * @return - */ '$continue_imported'(Mod:Pred,Mod,Pred) :- '$pred_exists'(Pred, Mod), !. diff --git a/pl/top.yap b/pl/top.yap index c401d98a5..bd76975b8 100644 --- a/pl/top.yap +++ b/pl/top.yap @@ -15,7 +15,7 @@ */ :- '$system_meta_predicates'([ - gated_call(0,0,?,0), + gated_call(0,0,?,0), catch(0,?,0), log_event(+,:)]). @@ -61,10 +61,6 @@ live :- throw(E). -/** @pred stream_property( Stream, Prop ) - -*/ - % reset alarms when entering top-level. '$enter_top_level' :- '$alarm'(0, 0, _, _), @@ -926,9 +922,9 @@ expand_term(Term,Expanded) :- %% @} -%% @addtogroup YAPControl - -%% @{ +%% @addtogroup CathThrow Catch and Throw +% @ingroup YAPControl +% @{ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % catch/throw implementation @@ -936,7 +932,9 @@ expand_term(Term,Expanded) :- % at each catch point I need to know: % what is ball; % where was the previous catch -/** @pred catch( : _Goal_,+ _Exception_,+ _Action_) is iso + +/** +@pred catch( : _Goal_,+ _Exception_,+ _Action_) is iso The goal `catch( _Goal_, _Exception_, _Action_)` tries to @@ -949,7 +947,6 @@ again throws the exception. The top-level of YAP maintains a default exception handler that is responsible to capture uncaught exceptions. - */ catch(G, C, A) :- '$catch'(G,C,A).