From 12060358053a3d2bde711ed8b7927abdbbcc51d8 Mon Sep 17 00:00:00 2001 From: Vitor Santos Costa Date: Thu, 10 May 2018 13:11:56 +0100 Subject: [PATCH] more doc stuff --- C/attvar.c | 48 +- C/flags.c | 53 ++- C/modules.c | 2 + H/YapFlags.h | 9 +- H/YapGFlagInfo.h | 995 +++++++++++++++++++++--------------------- H/YapLFlagInfo.h | 11 +- docs/md/attributes.md | 111 +++-- docs/md/builtins.md | 56 +-- docs/md/extensions.md | 29 +- docs/md/library.md | 74 +--- docs/md/load_files.md | 2 +- docs/md/modules.md | 8 +- docs/md/syntax.md | 67 ++- docs/md/yap.md | 37 -- library/lists.yap | 3 +- pl/consult.yap | 4 +- pl/corout.yap | 11 +- pl/debug.yap | 35 +- pl/directives.yap | 5 +- pl/error.yap | 2 +- pl/init.yap | 10 + pl/load_foreign.yap | 2 +- pl/metadecls.yap | 6 +- pl/qly.yap | 2 +- pl/spy.yap | 17 +- 25 files changed, 780 insertions(+), 819 deletions(-) diff --git a/C/attvar.c b/C/attvar.c index 19882b9a4..eeb4ec8b3 100644 --- a/C/attvar.c +++ b/C/attvar.c @@ -8,10 +8,8 @@ * * ************************************************************************** * * - * File: attvar.c * - * Last rev: * - * mods: * - * comments: YAP support for attributed vars * + * File: attvar.c * Last rev: + ** mods: * comments: YAP support for attributed vars * * * *************************************************************************/ #ifdef SCCS @@ -22,26 +20,27 @@ static char SccsId[] = "%W% %G%"; * @file attvar.c * @author VITOR SANTOS COSTA * @date Mon Apr 30 09:31:59 2018 - * + * * @brief attributed variables * @namespace prolog - * + * */ #include "Yap.h" -#include "Yatom.h" #include "YapHeap.h" -#include "heapgc.h" +#include "Yatom.h" #include "attvar.h" +#include "heapgc.h" #ifndef NULL #define NULL (void *)0 #endif /** - @defgroup AttributedVariables_Builtins Low-level support for Attributed Variables - + @defgroup AttributedVariables_Builtins Low-level support for Attributed + Variables + @brief Implementation of Attribute Declarations - @ingroup attributes + @ingroup AttributedVariables @{ */ @@ -211,7 +210,7 @@ static void WakeAttVar(CELL *pt1, CELL reg2 USES_REGS) { void Yap_WakeUp(CELL *pt0) { CACHE_REGS - CELL d0 = *pt0; + CELL d0 = *pt0; RESET_VARIABLE(pt0); WakeAttVar(pt0, d0 PASS_REGS); } @@ -684,7 +683,6 @@ static Int free_att(USES_REGS1) { } } - static Int get_atts(USES_REGS1) { /* receive a variable in ARG1 */ Term inp = Deref(ARG1); @@ -896,7 +894,7 @@ static Term AllAttVars(USES_REGS1) { while (pt < myH) { switch (*pt) { - case (CELL) FunctorAttVar: + case (CELL)FunctorAttVar: if (IsUnboundVar(pt + 1)) { if (ASP - myH < 1024) { LOCAL_Error_Size = (ASP - HR) * sizeof(CELL); @@ -910,24 +908,23 @@ static Term AllAttVars(USES_REGS1) { } pt += (1 + ATT_RECORD_ARITY); break; - case (CELL) FunctorDouble: + case (CELL)FunctorDouble: #if SIZEOF_DOUBLE == 2 * SIZEOF_INT_P pt += 4; #else pt += 3; #endif break; - case (CELL) FunctorString: + case (CELL)FunctorString: pt += 3 + pt[1]; break; - case (CELL) FunctorBigInt: { - Int sz = 3 + - (sizeof(MP_INT) + - (((MP_INT *)(pt + 2))->_mp_alloc * sizeof(mp_limb_t))) / - sizeof(CELL); + case (CELL)FunctorBigInt: { + Int sz = 3 + (sizeof(MP_INT) + + (((MP_INT *)(pt + 2))->_mp_alloc * sizeof(mp_limb_t))) / + sizeof(CELL); pt += sz; } break; - case (CELL) FunctorLongInt: + case (CELL)FunctorLongInt: pt += 3; break; default: @@ -976,7 +973,7 @@ static Int is_attvar(USES_REGS1) { static Int attvar_bound(USES_REGS1) { Term t = Deref(ARG1); return IsVarTerm(t) && IsAttachedTerm(t) && - !IsUnboundVar(&(RepAttVar(VarOfTerm(t))->Done)); + !IsUnboundVar(&(RepAttVar(VarOfTerm(t))->Done)); } static Int void_term(USES_REGS1) { return Yap_unify(ARG1, TermVoidAtt); } @@ -1016,7 +1013,7 @@ static Int attvar_bound(USES_REGS1) { return FALSE; } void Yap_InitAttVarPreds(void) { CACHE_REGS - Term OldCurrentModule = CurrentModule; + Term OldCurrentModule = CurrentModule; CurrentModule = ATTRIBUTES_MODULE; #ifdef COROUTINING GLOBAL_attas[attvars_ext].bind_op = WakeAttVar; @@ -1038,8 +1035,7 @@ void Yap_InitAttVarPreds(void) { Yap_InitCPred("rm_att", 4, rm_att, 0); Yap_InitCPred("bind_attvar", 1, bind_attvar, SafePredFlag); Yap_InitCPred("unbind_attvar", 1, unbind_attvar, SafePredFlag); - Yap_InitCPred("modules_with_attributes", 2, modules_with_atts, - SafePredFlag); + Yap_InitCPred("modules_with_attributes", 2, modules_with_atts, SafePredFlag); Yap_InitCPred("void_term", 1, void_term, SafePredFlag); Yap_InitCPred("free_term", 1, free_term, SafePredFlag); Yap_InitCPred("fast_unify_attributed", 2, fast_unify, 0); diff --git a/C/flags.c b/C/flags.c index 3ae5969aa..dbf143e40 100644 --- a/C/flags.c +++ b/C/flags.c @@ -16,23 +16,29 @@ *************************************************************************/ /** @file C/flags.c - - @{ - @defgroup YAPFlags_Impl C-code to handle Prolog flags. - @ingroup YAPFlags - -@brief Low-level code to support flags. Flags can be: - = thread-local or global - = module-based or module-independent. - = read-only or read-write - = System or User Defined. - = Have type boolean, number, atom constant or may be a general term. - + + @brief Prolog parameter setting, */ /* * @namespace prolog - * / + */ + +/** + @{ + @defgroup YAPFlags_Impl C-code to handle Prolog flags. + @ingroup YAPFlags + +@brief Low-level code to support flags. + +Prolog Flags can be: += thread-local or global += module-based or module-independent. += read-only or read-write += System or User Defined. += Have type boolean, number, atom constant or may be a general term. + +*/ // this is where we define flags #define INIT_FLAGS 1 @@ -78,21 +84,22 @@ static Int set_prolog_flag(USES_REGS1); #include "YapEval.h" #include "yapio.h" -#define YAP_FLAG(ID, NAME, WRITABLE, DEF, INIT, HELPER) \ - { NAME, WRITABLE, DEF, INIT, HELPER } +#define YAP_FLAG(ID, NAME, WRITABLE, DEF, INIT, HELPER) { NAME, WRITABLE, DEF, INIT, HELPER } + +#define START_LOCAL_FLAGS static flag_info local_flags_setup[] = { +#define END_LOCAL_FLAGS LZERO_FLAG}; + +#define START_GLOBAL_FLAGS static flag_info global_flags_setup[] = { +#define END_GLOBAL_FLAGS GZERO_FLAG}; + + +#define GZERO_FLAG { NULL, false, NULL, NULL, NULL } +#define LZERO_FLAG { NULL, false, NULL, NULL, NULL } -#define GZERO_FLAG \ - { NULL, false, NULL, NULL, NULL } -#define LZERO_FLAG \ - { NULL, false, NULL, NULL, NULL } -static flag_info global_flags_setup[] = { #include "YapGFlagInfo.h" - GZERO_FLAG}; -static flag_info local_flags_setup[] = { #include "YapLFlagInfo.h" - LZERO_FLAG}; static Term indexer(Term inp) { if (inp == TermOff || inp == TermSingle || inp == TermCompact || diff --git a/C/modules.c b/C/modules.c index f91fa5ea2..7a55aacfd 100644 --- a/C/modules.c +++ b/C/modules.c @@ -14,6 +14,8 @@ * comments: module support * * * *************************************************************************/ + + #ifdef SCCSLookupSystemModule static char SccsId[] = "%W% %G%"; #endif diff --git a/H/YapFlags.h b/H/YapFlags.h index d426c79ea..5aa3fcb7c 100644 --- a/H/YapFlags.h +++ b/H/YapFlags.h @@ -239,7 +239,10 @@ Set or read system properties for _Param_: #define YAP_FLAG(ITEM, NAME, WRITABLE, DEF, INIT, HELPER) ITEM - +#define START_LOCAL_FLAGS enum { +#define END_LOCAL_FLAGS }; +#define START_GLOBAL_FLAGS enum { +#define END_GLOBAL_FLAGS }; /* */ #include "YapGFlagInfo.h" @@ -249,6 +252,10 @@ Set or read system properties for _Param_: #undef YAP_FLAG +#undef START_LOCAL_FLAGS +#undef END_LOCAL_FLAGS +#undef START_GLOBAL_FLAGS +#undef END_GLOBAL_FLAGS bool setYapFlag(Term tflag, Term t2); Term getYapFlag(Term tflag); diff --git a/H/YapGFlagInfo.h b/H/YapGFlagInfo.h index 9afd361e7..e3106b41b 100644 --- a/H/YapGFlagInfo.h +++ b/H/YapGFlagInfo.h @@ -1,325 +1,327 @@ /************************************************************************* -* * -* YAP Prolog * -* * -* Yap Prolog was developed at NCCUP - Universidade do Porto * -* * -* Copyright L.Damas, V.S.Costa and Universidade do Porto 2015- * -* * -************************************************************************** -* * -* File: YapGFlagInfo.h * -* Last rev: * -* mods: * -* comments: global flag enumeration. * -* * -*************************************************************************/ + * * + * YAP Prolog * + * * + * Yap Prolog was developed at NCCUP - Universidade do Porto * + * * + * Copyright L.Damas, V.S.Costa and Universidade do Porto 2015- * + * * + ************************************************************************** + * * + * File: YapGFlagInfo.h * + * Last rev: * + * mods: * + * comments: global flag enumeration. * + * * + *************************************************************************/ /** @file YapGFlagInfo.h - @addtogroup YAPFlags -@ingroup builtins -@{ + @addtogroup YAPGFlags YAPGlobalFlags + @ingroup builtins + @{ - @enum YapGFlag Prolog - -@enum GlobalFlags Global Flags supported by YAP - @brief global flag: + @enum global_flags_setup Global Flags supported by YAP + @brief global flags and their values. */ -typedef enum { -/**< `address_bits` - Number of address bits in the machine, either 64 or 32 bits */ -YAP_FLAG(ADDRESS_BITS_FLAG, "address_bits", false, nat, BITNESS, NULL), -/**< `agc_margin` -An integer: if this amount of atoms has been created since the last -atom-garbage collection, perform atom garbage collection at the first -opportunity. Initial value is 10,000. May be changed. A value of 0 -(zero) disables atom garbage collection. -*/ -YAP_FLAG(AGC_MARGIN_FLAG, "agc_margin", true, nat, "10000", - agc_threshold), + START_GLOBAL_FLAGS + + /** + `address_bits` + Number of address bits in the machine, either 64 or 32 bits + */ + YAP_FLAG(ADDRESS_BITS_FLAG, "address_bits", false, nat, BITNESS, NULL), - /**< `allow_assert_for_static_predicates` allow asserting and retracting clauses of static - predicates. */ -YAP_FLAG(ALLOW_ASSERT_FOR_STATIC_PREDICATES, - "allow_assert_for_static_predicates", true, booleanFlag, "true", - NULL), + /**< `agc_margin` + An integer: if this amount of atoms has been created since the last + atom-garbage collection, perform atom garbage collection at the first + opportunity. Initial value is 10,000. May be changed. A value of 0 + (zero) disables atom garbage collection. + */ + YAP_FLAG(AGC_MARGIN_FLAG, "agc_margin", true, nat, "10000", + agc_threshold), + + /**< `allow_assert_for_static_predicates` allow asserting and retracting clauses of static + predicates. */ + YAP_FLAG(ALLOW_ASSERT_FOR_STATIC_PREDICATES, + "allow_assert_for_static_predicates", true, booleanFlag, "true", + NULL), /**< `allow_variable_name_as_functor` boolean flag allows constructs such as -~~~ -Tree(Node(L,node,R)) :- + ~~~ + Tree(Node(L,node,R)) :- Tree(L), Tree(R). -~~~ - */ + ~~~ + */ YAP_FLAG( ALLOW_VARIABLE_NAME_AS_FUNCTOR_FLAG, "allow_variable_name_as_functor", false, booleanFlag, "false", NULL), - -/**< `answer_format` how to present answers, default is `~p`. */ -YAP_FLAG(ANSWER_FORMAT_FLAG, "answer_format", true, isatom, "~p", - NULL), + + /**< `answer_format` how to present answers, default is `~p`. */ + YAP_FLAG(ANSWER_FORMAT_FLAG, "answer_format", true, isatom, "~p", + NULL), #if __APPLE__ -/**< - `apple`: read-only boolean, a machine running an Apple Operating System * -*/ + /**< + `apple`: read-only boolean, a machine running an Apple Operating System * + */ YAP_FLAG(APPLE_FLAG, "apple", false, booleanFlag, "true", - NULL), + NULL), #endif - YAP_FLAG(ARCH_FLAG, "arch", false, isatom, YAP_ARCH, NULL), - YAP_FLAG(ARGV_FLAG, "argv", false, argv, "@boot", NULL), -/**< `arithmetic_exceptions` + YAP_FLAG(ARCH_FLAG, "arch", false, isatom, YAP_ARCH, NULL), + YAP_FLAG(ARGV_FLAG, "argv", false, argv, "@boot", NULL), + /**< `arithmetic_exceptions` -Read-write flag telling whether arithmetic exceptions generate -Prolog exceptions. If enabled: + Read-write flag telling whether arithmetic exceptions generate + Prolog exceptions. If enabled: -~~~ -?- X is 2/0. -ERROR!! -ZERO DIVISOR ERROR- X is Exp -~~~ + ~~~ + ?- X is 2/0. + ERROR!! + ZERO DIVISOR ERROR- X is Exp + ~~~ -If disabled: -~~~ -?- X is 2/0. -X = (+inf). -~~~ + If disabled: + ~~~ + ?- X is 2/0. + X = (+inf). + ~~~ -It is `true` by default, but it is disabled by packages like CLP(BN) and -ProbLog. -*/ - YAP_FLAG(ARITHMETIC_EXCEPTIONS_FLAG, "arithmetic_exceptions", true, - booleanFlag, "true", NULL), -/**> -If _Value_ is unbound, tell whether a back quoted list of characters -token is converted to a list of atoms, `chars`, to a list of integers, -`codes`, or to a single atom, `atom`. If _Value_ is bound, set to -the corresponding behavior. The default value is `string` -*/ + It is `true` by default, but it is disabled by packages like CLP(BN) and + ProbLog. + */ + YAP_FLAG(ARITHMETIC_EXCEPTIONS_FLAG, "arithmetic_exceptions", true, + booleanFlag, "true", NULL), + /**> + If _Value_ is unbound, tell whether a back quoted list of characters + token is converted to a list of atoms, `chars`, to a list of integers, + `codes`, or to a single atom, `atom`. If _Value_ is bound, set to + the corresponding behavior. The default value is `string` + */ YAP_FLAG(BACK_QUOTES_FLAG, "back_quotes", true, isatom, "true", NULL), - /**< `bounded` is iso + /**< `bounded` is iso -Read-only flag telling whether integers are bounded. The value depends -on whether YAP uses the GMP library or not. -*/ + Read-only flag telling whether integers are bounded. The value depends + on whether YAP uses the GMP library or not. + */ -YAP_FLAG(BOUNDED_FLAG, "bounded", false, booleanFlag, "false", - NULL), + YAP_FLAG(BOUNDED_FLAG, "bounded", false, booleanFlag, "false", + NULL), YAP_FLAG(C_CC_FLAG, "c_cc", false, isatom, C_CC, NULL), - YAP_FLAG(C_CFLAGS_FLAG, "c_cflags", false, isatom, C_CFLAGS, NULL), - YAP_FLAG(C_LDFLAGS_FLAG, "c_ldflags", false, isatom, C_LDFLAGS, NULL), - YAP_FLAG(C_LIBPLSO_FLAG, "c_libplso", false, isatom, C_LIBPLSO, NULL), - YAP_FLAG(C_LIBS_FLAG, "c_libs", false, isatom, C_LIBS, NULL), -/**< `char_conversion is iso` + YAP_FLAG(C_CFLAGS_FLAG, "c_cflags", false, isatom, C_CFLAGS, NULL), + YAP_FLAG(C_LDFLAGS_FLAG, "c_ldflags", false, isatom, C_LDFLAGS, NULL), + YAP_FLAG(C_LIBPLSO_FLAG, "c_libplso", false, isatom, C_LIBPLSO, NULL), + YAP_FLAG(C_LIBS_FLAG, "c_libs", false, isatom, C_LIBS, NULL), + /**< `char_conversion is iso` - Writable flag telling whether a character conversion table is used when - reading terms. The default value for this flag is `off` except in - `sicstus` and `iso` language modes, where it is `on`. - */ - YAP_FLAG(CHAR_CONVERSION_FLAG, "char_conversion", true, booleanFlag, - "false", NULL), - /**< `character_escapes is iso ` + Writable flag telling whether a character conversion table is used when + reading terms. The default value for this flag is `off` except in + `sicstus` and `iso` language modes, where it is `on`. + */ + YAP_FLAG(CHAR_CONVERSION_FLAG, "char_conversion", true, booleanFlag, + "false", NULL), + /**< `character_escapes is iso ` - Writable flag telling whether a character escapes are enables, - `true`, or disabled, `false`. The default value for this flag is - `true`. */ - YAP_FLAG(CHARACTER_ESCAPES_FLAG, "character_escapes", true, booleanFlag, - "true", NULL), - YAP_FLAG(COLON_SETS_CALLING_CONTEXT_FLAG, "colon_sets_calling_context", - true, booleanFlag, "true", NULL), -/**< `compiled_at ` + Writable flag telling whether a character escapes are enables, + `true`, or disabled, `false`. The default value for this flag is + `true`. */ + YAP_FLAG(CHARACTER_ESCAPES_FLAG, "character_escapes", true, booleanFlag, + "true", NULL), + YAP_FLAG(COLON_SETS_CALLING_CONTEXT_FLAG, "colon_sets_calling_context", + true, booleanFlag, "true", NULL), + /**< `compiled_at ` -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(COMPILED_AT_FLAG, "compiled_at", false, isatom, YAP_COMPILED_AT, - NULL), -/**< `debug is iso ` + 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(COMPILED_AT_FLAG, "compiled_at", false, isatom, YAP_COMPILED_AT, + NULL), + /**< `debug is iso ` -If _Value_ is unbound, tell whether debugging is `true` or -`false`. If _Value_ is bound to `true` enable debugging, and if -it is bound to `false` disable debugging. -*/ - YAP_FLAG(DEBUG_FLAG, "debug", true, booleanFlag, "false", - NULL), - YAP_FLAG(DEBUG_INFO_FLAG, "debug_info", true, booleanFlag, "true", NULL), - YAP_FLAG(DEBUG_ON_ERROR_FLAG, "debug_on_error", true, booleanFlag, "true", - NULL), - /**< `debugger_print_options ` + If _Value_ is unbound, tell whether debugging is `true` or + `false`. If _Value_ is bound to `true` enable debugging, and if + it is bound to `false` disable debugging. + */ + YAP_FLAG(DEBUG_FLAG, "debug", true, booleanFlag, "false", + NULL), + YAP_FLAG(DEBUG_INFO_FLAG, "debug_info", true, booleanFlag, "true", NULL), + YAP_FLAG(DEBUG_ON_ERROR_FLAG, "debug_on_error", true, booleanFlag, "true", + NULL), + /**< `debugger_print_options ` -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(DEBUGGER_PRINT_OPTIONS_FLAG, "debugger_print_options", true, - list_option, - "[quoted(true),numbervars(true),portrayed(true),max_depth(10)]", - NULL), - YAP_FLAG(DEBUGGER_SHOW_CONTEXT_FLAG, "debugger_show_context", true, - booleanFlag, "false", NULL), -/**< `dialect ` + 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(DEBUGGER_PRINT_OPTIONS_FLAG, "debugger_print_options", true, + list_option, + "[quoted(true),numbervars(true),portrayed(true),max_depth(10)]", + NULL), + YAP_FLAG(DEBUGGER_SHOW_CONTEXT_FLAG, "debugger_show_context", true, + booleanFlag, "false", NULL), + /**< `dialect ` - Read-only flag that always returns `yap`. - */ - YAP_FLAG(DIALECT_FLAG, "dialect", false, ro, "yap", - NULL), -/**< `discontiguous_warnings ` + Read-only flag that always returns `yap`. + */ + YAP_FLAG(DIALECT_FLAG, "dialect", false, ro, "yap", + NULL), + /**< `discontiguous_warnings ` -If `true` (default `true`) YAP checks for definitions of the same predicate that -are separated by clauses for other predicates. This may indicate that different -procedures have the same name. + If `true` (default `true`) YAP checks for definitions of the same predicate that + are separated by clauses for other predicates. This may indicate that different + procedures have the same name. -The declaration discontiguous/1 disables this warning for user-specified -predicates. + The declaration discontiguous/1 disables this warning for user-specified + predicates. - */ - YAP_FLAG(DISCONTIGUOUS_WARNINGS_FLAG, "discontiguous_warnings", true, - booleanFlag, "true", NULL), -/**< `dollar_as_lower_case ` + */ + YAP_FLAG(DISCONTIGUOUS_WARNINGS_FLAG, "discontiguous_warnings", true, + booleanFlag, "true", NULL), + /**< `dollar_as_lower_case ` -If `off` (default) consider the character `$` a control character, if -`on` consider `$` a lower case character. -*/ - YAP_FLAG(DOLLAR_AS_LOWER_CASE_FLAG, "dollar_as_lower_case", true, - booleanFlag, "false", - NULL), -/**< `double_quotes is iso ` + If `off` (default) consider the character `$` a control character, if + `on` consider `$` a lower case character. + */ + YAP_FLAG(DOLLAR_AS_LOWER_CASE_FLAG, "dollar_as_lower_case", true, + booleanFlag, "false", + NULL), + /**< `double_quotes is iso ` -If _Value_ is unbound, tell whether a double quoted list of characters -token is converted to a list of atoms, `chars`, to a list of integers, -`codes`, or to a single atom, `atom`. If _Value_ is bound, set to -the corresponding behavior. The default value is `codes`. */ - YAP_FLAG(DOUBLE_QUOTES_FLAG, "double_quotes", true, isatom, "codes", - dqs), - YAP_FLAG(EDITOR_FLAG, "editor", true, isatom, "$EDITOR", NULL), -/**< `executable ` + If _Value_ is unbound, tell whether a double quoted list of characters + token is converted to a list of atoms, `chars`, to a list of integers, + `codes`, or to a single atom, `atom`. If _Value_ is bound, set to + the corresponding behavior. The default value is `codes`. */ + YAP_FLAG(DOUBLE_QUOTES_FLAG, "double_quotes", true, isatom, "codes", + dqs), + YAP_FLAG(EDITOR_FLAG, "editor", true, isatom, "$EDITOR", NULL), + /**< `executable ` -Read-only flag. It unifies with an atom that gives the -original program path. -*/ - YAP_FLAG(EXECUTABLE_FLAG, "executable", false, executable, "@boot", - NULL), -/**< `fast ` + Read-only flag. It unifies with an atom that gives the + original program path. + */ + YAP_FLAG(EXECUTABLE_FLAG, "executable", false, executable, "@boot", + NULL), + /**< `fast ` - If `on` allow fast machine code, if `off` (default) disable it. Only -available in experimental implementations. - */ - YAP_FLAG(FAST_FLAG, "fast", true, booleanFlag, "false", NULL), - YAP_FLAG(FILE_NAME_VARIABLES_FLAG, "file_name_variables", true, booleanFlag, - "true", NULL), -/**< + `float_format ` + If `on` allow fast machine code, if `off` (default) disable it. Only + available in experimental implementations. + */ + YAP_FLAG(FAST_FLAG, "fast", true, booleanFlag, "false", NULL), + YAP_FLAG(FILE_NAME_VARIABLES_FLAG, "file_name_variables", true, booleanFlag, + "true", NULL), + /**< + `float_format ` - C-library `printf()` format specification used by write/1 and - friends to determine how floating point numbers are printed. The - default is `%.15g`. The specified value is passed to `printf()` - without further checking. For example, if you want less digits - printed, `%g` will print all floats using 6 digits instead of the - default 15. - */ - YAP_FLAG(FLOAT_FORMAT_FLAG, "float_format", true, isatom, "%.16g", - NULL), -/**< `gc` + C-library `printf()` format specification used by write/1 and + friends to determine how floating point numbers are printed. The + default is `%.15g`. The specified value is passed to `printf()` + without further checking. For example, if you want less digits + printed, `%g` will print all floats using 6 digits instead of the + default 15. + */ + YAP_FLAG(FLOAT_FORMAT_FLAG, "float_format", true, isatom, "%.16g", + NULL), + /**< `gc` - If `on` allow garbage collection (default), if `off` disable it. -*/ - YAP_FLAG(GC_FLAG, "gc", true, booleanFlag, "on", NULL), -/**< `gc_margin ` + If `on` allow garbage collection (default), if `off` disable it. + */ + YAP_FLAG(GC_FLAG, "gc", true, booleanFlag, "on", NULL), + /**< `gc_margin ` -Set or show the minimum free stack before starting garbage -collection. The default depends on total stack size. + Set or show the minimum free stack before starting garbage + collection. The default depends on total stack size. -*/ - YAP_FLAG(GC_MARGIN_FLAG, "gc_margin", true, nat, "0", - gc_margin), -/**< `gc_trace ` + */ + YAP_FLAG(GC_MARGIN_FLAG, "gc_margin", true, nat, "0", + gc_margin), + /**< `gc_trace ` -If `off` (default) do not show information on garbage collection -and stack shifts, if `on` inform when a garbage collection or stack -shift happened, if verbose give detailed information on garbage -collection and stack shifts. Last, if `very_verbose` give detailed -information on data-structures found during the garbage collection -process, namely, on choice-points. -*/ - YAP_FLAG(GC_TRACE_FLAG, "gc_trace", true, isatom, "off", - NULL), -/**< `generate_debug_info ` + If `off` (default) do not show information on garbage collection + and stack shifts, if `on` inform when a garbage collection or stack + shift happened, if verbose give detailed information on garbage + collection and stack shifts. Last, if `very_verbose` give detailed + information on data-structures found during the garbage collection + process, namely, on choice-points. + */ + YAP_FLAG(GC_TRACE_FLAG, "gc_trace", true, isatom, "off", + NULL), + /**< `generate_debug_info ` - If `true` (default) generate debugging information for - procedures, including source mode. If `false` predicates no - information is generated, although debugging is still possible, and - source mode is disabled. + If `true` (default) generate debugging information for + procedures, including source mode. If `false` predicates no + information is generated, although debugging is still possible, and + source mode is disabled. - */ - YAP_FLAG(GENERATE_DEBUGGING_INFO_FLAG, "generate_debug_info", true, - booleanFlag, "true", NULL), - YAP_FLAG(GMP_VERSION_FLAG, "gmp_version", false, isatom, "4.8.12", NULL), - YAP_FLAG(HALT_AFTER_CONSULT_FLAG, "halt_after_consult", false, booleanFlag, - "false", NULL), -/**< home ` + */ + YAP_FLAG(GENERATE_DEBUGGING_INFO_FLAG, "generate_debug_info", true, + booleanFlag, "true", NULL), + YAP_FLAG(GMP_VERSION_FLAG, "gmp_version", false, isatom, "4.8.12", NULL), + YAP_FLAG(HALT_AFTER_CONSULT_FLAG, "halt_after_consult", false, booleanFlag, + "false", NULL), + /**< home ` -the root of the YAP installation, by default `/usr/local` in Unix or -`c:\Yap` in Windows system. Can only be set at configure time - */ - YAP_FLAG(HOME_FLAG, "home", false, isatom, YAP_ROOTDIR, NULL), -/**< host_type ` + the root of the YAP installation, by default `/usr/local` in Unix or + `c:\Yap` in Windows system. Can only be set at configure time + */ + YAP_FLAG(HOME_FLAG, "home", false, isatom, YAP_ROOTDIR, NULL), + /**< host_type ` -Return `configure` system information, including the machine-id -for which YAP was compiled and Operating System information. -*/ - YAP_FLAG(HOST_TYPE_FLAG, "host_type", false, isatom, HOST_ALIAS, - NULL), -/**< `index ` + Return `configure` system information, including the machine-id + for which YAP was compiled and Operating System information. + */ + YAP_FLAG(HOST_TYPE_FLAG, "host_type", false, isatom, HOST_ALIAS, + NULL), + /**< `index ` - If `on` allow indexing (default), if `off` disable it, if -`single` allow on first argument only. - */ - YAP_FLAG(INDEX_FLAG, "index", true, indexer, "multi", NULL), -/**< `Index_sub_term_search_depth ` + If `on` allow indexing (default), if `off` disable it, if + `single` allow on first argument only. + */ + YAP_FLAG(INDEX_FLAG, "index", true, indexer, "multi", NULL), + /**< `Index_sub_term_search_depth ` -Maximum bound on searching sub-terms for indexing, if `0` (default) no bound. -*/ - YAP_FLAG(INDEX_SUB_TERM_SEARCH_DEPTH_FLAG, "index_sub_term_search_depth", - true, nat, "0", NULL), -/**< `informational_messages ` + Maximum bound on searching sub-terms for indexing, if `0` (default) no bound. + */ + YAP_FLAG(INDEX_SUB_TERM_SEARCH_DEPTH_FLAG, "index_sub_term_search_depth", + true, nat, "0", NULL), + /**< `informational_messages ` -If `on` allow printing of informational messages, such as the ones -that are printed when consulting. If `off` disable printing -these messages. It is `on` by default except if YAP is booted with -the `-L` flag. -*/ - YAP_FLAG(INFORMATIONAL_MESSAGES_FLAG, "informational_messages", true, - isatom, "normal", NULL), -/**< `integer_rounding_function is iso ` + If `on` allow printing of informational messages, such as the ones + that are printed when consulting. If `off` disable printing + these messages. It is `on` by default except if YAP is booted with + the `-L` flag. + */ + YAP_FLAG(INFORMATIONAL_MESSAGES_FLAG, "informational_messages", true, + isatom, "normal", NULL), + /**< `integer_rounding_function is iso ` -Read-only flag telling the rounding function used for integers. Takes the value -`toward_zero` for the current version of YAP. -*/ - YAP_FLAG(INTEGER_ROUNDING_FUNCTION_FLAG, "integer_rounding_function", true, - isatom, "toward_zero", - NULL), - YAP_FLAG(ISO_FLAG, "iso", true, booleanFlag, "false", NULL), -/**< `language ` + Read-only flag telling the rounding function used for integers. Takes the value + `toward_zero` for the current version of YAP. + */ + YAP_FLAG(INTEGER_ROUNDING_FUNCTION_FLAG, "integer_rounding_function", true, + isatom, "toward_zero", + NULL), + YAP_FLAG(ISO_FLAG, "iso", true, booleanFlag, "false", NULL), + /**< `language ` -Choose whether YAP follows native, closer to C-Prolog, `yap`, iso-prolog, -`iso` or SICStus Prolog, `sicstus`. The current default is -`cprolog`. This flag affects update semantics, leashing mode, -style checking, handling calls to undefined procedures, how directives -are interpreted, when to use dynamic, character escapes, and how files -are consulted. Also check the `dialect` option. -*/ - YAP_FLAG(LANGUAGE_FLAG, "language", true, isatom, "yap", - NULL), -/**< if defined, first location where YAP expects to find the YAP Prolog library. Takes precedence over library_directory */ - YAP_FLAG(PROLOG_LIBRARY_DIRECTORY_FLAG, "prolog_library_directory", true, isatom, "", NULL), + Choose whether YAP follows native, closer to C-Prolog, `yap`, iso-prolog, + `iso` or SICStus Prolog, `sicstus`. The current default is + `cprolog`. This flag affects update semantics, leashing mode, + style checking, handling calls to undefined procedures, how directives + are interpreted, when to use dynamic, character escapes, and how files + are consulted. Also check the `dialect` option. + */ + YAP_FLAG(LANGUAGE_FLAG, "language", true, isatom, "yap", + NULL), + /**< if defined, first location where YAP expects to find the YAP Prolog library. Takes precedence over library_directory */ + YAP_FLAG(PROLOG_LIBRARY_DIRECTORY_FLAG, "prolog_library_directory", true, isatom, "", NULL), -/**< if defined, first location where YAP expects to find the YAP Prolog shared libraries (DLLS). Takes precedence over executable_directory/2. */ - YAP_FLAG(PROLOG_FOREIGN_DIRECTORY_FLAG, "prolog_foreign_directory", true, isatom, "", NULL), - -/**< `max_arity is iso ` + /**< if defined, first location where YAP expects to find the YAP Prolog shared libraries (DLLS). Takes precedence over executable_directory/2. */ + YAP_FLAG(PROLOG_FOREIGN_DIRECTORY_FLAG, "prolog_foreign_directory", true, isatom, "", NULL), -Read-only flag telling the maximum arity of a functor. Takes the value -`unbounded` for the current version of YAP. - */ - YAP_FLAG(MAX_ARITY_FLAG, "max_arity", false, isatom, "unbounded", - NULL), + /**< `max_arity is iso ` + + Read-only flag telling the maximum arity of a functor. Takes the value + `unbounded` for the current version of YAP. + */ + YAP_FLAG(MAX_ARITY_FLAG, "max_arity", false, isatom, "unbounded", + NULL), YAP_FLAG(MAX_TAGGED_INTEGER_FLAG, "max_tagged_integer", false, at2n, "INT_MAX", NULL), YAP_FLAG(MAX_THREADS_FLAG, "max_threads", false, at2n, "MAX_THREADS", NULL), @@ -330,295 +332,294 @@ Read-only flag telling the maximum arity of a functor. Takes the value "256", NULL), YAP_FLAG(OCCURS_CHECK_FLAG, "occurs_check", true, booleanFlag, "false", NULL), -/**< `open_expands_filename ` + /**< `open_expands_filename ` -If `true` the open/3 builtin performs filename-expansion -before opening a file (SICStus Prolog like). If `false` it does not -(SWI-Prolog like). - */ - YAP_FLAG(OPEN_EXPANDS_FILENAME_FLAG, "open_expands_filename", true, - booleanFlag, "false", NULL), -/**< `open_shared_object ` + If `true` the open/3 builtin performs filename-expansion + before opening a file (SICStus Prolog like). If `false` it does not + (SWI-Prolog like). + */ + YAP_FLAG(OPEN_EXPANDS_FILENAME_FLAG, "open_expands_filename", true, + booleanFlag, "false", NULL), + /**< `open_shared_object ` -If true, `open_shared_object/2` and friends are implemented, -providing access to shared libraries (`.so` files) or to dynamic link -libraries (`.DLL` files). - */ - YAP_FLAG(OPEN_SHARED_OBJECT_FLAG, "open_shared_object", true, booleanFlag, - "true", NULL), -/**< `module_independent_operators ` + If true, `open_shared_object/2` and friends are implemented, + providing access to shared libraries (`.so` files) or to dynamic link + libraries (`.DLL` files). + */ + YAP_FLAG(OPEN_SHARED_OBJECT_FLAG, "open_shared_object", true, booleanFlag, + "true", NULL), + /**< `module_independent_operators ` + + If `true` an operator declaration will be valid for every module in the + program. This is for compatibility with old software that + might expect module-independent operators. + */ + // YAP_FLAG(MODULE_INDEPENDENT_OPERATORS_FLAG, + // "module_independent_operators", true, booleanFlag, + // "false", NULL), - If `true` an operator declaration will be valid for every module in the - program. This is for compatibility with old software that - might expect module-independent operators. - */ - // YAP_FLAG(MODULE_INDEPENDENT_OPERATORS_FLAG, - // "module_independent_operators", true, booleanFlag, - // "false", NULL), - YAP_FLAG(OPTIMISE_FLAG, "optimise", true, booleanFlag, "false", NULL), YAP_FLAG(OS_ARGV_FLAG, "os_argv", false, os_argv, "@boot", NULL), YAP_FLAG(PID_FLAG, "pid", false, sys_pid, "@boot", NULL), YAP_FLAG(PIPE_FLAG, "pipe", true, booleanFlag, "true", NULL), -/**< `profiling ` + /**< `profiling ` -If `off` (default) do not compile call counting information for -procedures. If `on` compile predicates so that they calls and -retries to the predicate may be counted. Profiling data can be read through the -call_count_data/3 built-in. - */ - YAP_FLAG(PROFILING_FLAG, "profiling", true, booleanFlag, "false", - NULL), -/**< `prompt_alternatives_on(atom, - changeable) ` + If `off` (default) do not compile call counting information for + procedures. If `on` compile predicates so that they calls and + retries to the predicate may be counted. Profiling data can be read through the + call_count_data/3 built-in. + */ + YAP_FLAG(PROFILING_FLAG, "profiling", true, booleanFlag, "false", + NULL), + /**< `prompt_alternatives_on(atom, + changeable) ` - SWI-Compatible option, determines prompting for alternatives in the Prolog - toplevel. Default is groundness, YAP prompts for alternatives if and - only if the query contains variables. The alternative, default in SWI-Prolog is - determinism which implies the system prompts for alternatives if the - goal succeeded while leaving choicepoints. */ - YAP_FLAG(PROMPT_ALTERNATIVES_ON_FLAG, "prompt_alternatives_on", true, - isatom, "determinism", NULL), + SWI-Compatible option, determines prompting for alternatives in the Prolog + toplevel. Default is groundness, YAP prompts for alternatives if and + only if the query contains variables. The alternative, default in SWI-Prolog is + determinism which implies the system prompts for alternatives if the + goal succeeded while leaving choicepoints. */ + YAP_FLAG(PROMPT_ALTERNATIVES_ON_FLAG, "prompt_alternatives_on", true, + isatom, "determinism", NULL), YAP_FLAG(QUASI_QUOTATIONS_FLAG, "quasi_quotations", true, booleanFlag, "true", NULL), -/**< `readline(boolean, changeable)` - } + /**< `readline(boolean, changeable)` + } - enable the use of the readline library for console interactions, true by default - if readline was found. */ - YAP_FLAG(READLINE_FLAG, "readline", true, booleanFlag, "false", - Yap_InitReadline), + enable the use of the readline library for console interactions, true by default + if readline was found. */ + YAP_FLAG(READLINE_FLAG, "readline", true, booleanFlag, "false", + Yap_InitReadline), YAP_FLAG(REPORT_ERROR_FLAG, "report_error", true, booleanFlag, "true", NULL), -/**<`resource_database` - Name of the resource file (saved-state or Prolog file) used to construct - the YAP - run-time environment. - */ - YAP_FLAG(RESOURCE_DATABASE_FLAG, "resource_database", false, isatom, + /**<`resource_database` + Name of the resource file (saved-state or Prolog file) used to construct + the YAP + run-time environment. + */ + YAP_FLAG(RESOURCE_DATABASE_FLAG, "resource_database", false, isatom, YAP_BOOTSTRAP, NULL), - -/**<`saved_program` - if `true` YAP booted from a `yss` file, usually `startup.yss'. If - `false`, YAP booted from a Prolog file, by default `boot.yap`. - */ - YAP_FLAG(SAVED_PROGRAM_FLAG, "saved_program", false, booleanFlag, "false", + + /**<`saved_program` + if `true` YAP booted from a `yss` file, usually `startup.yss'. If + `false`, YAP booted from a Prolog file, by default `boot.yap`. + */ + YAP_FLAG(SAVED_PROGRAM_FLAG, "saved_program", false, booleanFlag, "false", NULL), - -/**< `shared_object_extension ` -Suffix associated with loadable code. - */ - YAP_FLAG(SHARED_OBJECT_EXTENSION_FLAG, "shared_object_extension", false, - isatom, SO_EXT, NULL), -/**< `shared_object_search_path ` + /**< `shared_object_extension ` -Name of the environment variable used by the system to search for shared -objects. + Suffix associated with loadable code. + */ + YAP_FLAG(SHARED_OBJECT_EXTENSION_FLAG, "shared_object_extension", false, + isatom, SO_EXT, NULL), + /**< `shared_object_search_path ` - */ - YAP_FLAG(SHARED_OBJECT_SEARCH_PATH_FLAG, "shared_object_search_path", true, - isatom, SO_PATH, NULL), -/**< `single_quoted text is usuallly interpreted as atoms. This flagTerm allows other inerpretations such as strings_contains_strings */ - YAP_FLAG(SINGLE_QUOTES_FLAG, "single_quotes", true, isatom, "atom", - sqf), + Name of the environment variable used by the system to search for shared + objects. -/**< `signals` + */ + YAP_FLAG(SHARED_OBJECT_SEARCH_PATH_FLAG, "shared_object_search_path", true, + isatom, SO_PATH, NULL), + /**< `single_quoted text is usuallly interpreted as atoms. This flagTerm allows other inerpretations such as strings_contains_strings */ + YAP_FLAG(SINGLE_QUOTES_FLAG, "single_quotes", true, isatom, "atom", + sqf), -If `true` (default) YAP handles Signals such as `^C` -(`SIGINT`). + /**< `signals` - */ - YAP_FLAG(SIGNALS_FLAG, "signals", true, booleanFlag, "true", - NULL), -/**< `source` + If `true` (default) YAP handles Signals such as `^C` + (`SIGINT`). -If `true` maintain the source for all clauses. Notice that this is trivially -supported for facts, and always supported for dynamic code. + */ + YAP_FLAG(SIGNALS_FLAG, "signals", true, booleanFlag, "true", + NULL), + /**< `source` - */ - YAP_FLAG(SOURCE_FLAG, "source", true, booleanFlag, "true", - NULL), -/**< `strict_iso ` + If `true` maintain the source for all clauses. Notice that this is trivially + supported for facts, and always supported for dynamic code. -If _Value_ is unbound, tell whether strict ISO compatibility mode -is `on` or `off`. If _Value_ is bound to `on` set -language mode to `iso` and enable strict mode. If _Value_ is -bound to `off` disable strict mode, and keep the current language -mode. The default for YAP is `off`. -Under strict ISO Prolog mode all calls to non-ISO built-ins generate an -error. Compilation of clauses that would call non-ISO built-ins will -also generate errors. Pre-processing for grammar rules is also -disabled. Module expansion is still performed. -Arguably, ISO Prolog does not provide all the functionality required -from a modern Prolog system. Moreover, because most Prolog -implementations do not fully implement the standard and because the -standard itself gives the implementor latitude in a few important -questions, such as the unification algorithm and maximum size for -numbers there is no guarantee that programs compliant with this mode -will work the same way in every Prolog and in every platform. We thus -believe this mode is mostly useful when investigating how a program -depends on a Prolog's platform specific features. + */ + YAP_FLAG(SOURCE_FLAG, "source", true, booleanFlag, "true", + NULL), + /**< `strict_iso ` - */ - YAP_FLAG(STRICT_ISO_FLAG, "strict_iso", true, booleanFlag, "false", - NULL), -/**< `system_options ` + If _Value_ is unbound, tell whether strict ISO compatibility mode + is `on` or `off`. If _Value_ is bound to `on` set + language mode to `iso` and enable strict mode. If _Value_ is + bound to `off` disable strict mode, and keep the current language + mode. The default for YAP is `off`. + Under strict ISO Prolog mode all calls to non-ISO built-ins generate an + error. Compilation of clauses that would call non-ISO built-ins will + also generate errors. Pre-processing for grammar rules is also + disabled. Module expansion is still performed. + Arguably, ISO Prolog does not provide all the functionality required + from a modern Prolog system. Moreover, because most Prolog + implementations do not fully implement the standard and because the + standard itself gives the implementor latitude in a few important + questions, such as the unification algorithm and maximum size for + numbers there is no guarantee that programs compliant with this mode + will work the same way in every Prolog and in every platform. We thus + believe this mode is mostly useful when investigating how a program + depends on a Prolog's platform specific features. -This read only flag tells which options were used to compile -YAP. Currently it informs whether the system supports `big_numbers`, -`coroutining`, `depth_limit`, `low_level_tracer`, -`or-parallelism`, `rational_trees`, `readline`, `tabling`, -`threads`, or the `wam_profiler`. - */ - YAP_FLAG(SYSTEM_OPTIONS_FLAG, "system_options", false, options, - SYSTEM_OPTIONS, - NULL), + */ + YAP_FLAG(STRICT_ISO_FLAG, "strict_iso", true, booleanFlag, "false", + NULL), + /**< `system_options ` + + This read only flag tells which options were used to compile + YAP. Currently it informs whether the system supports `big_numbers`, + `coroutining`, `depth_limit`, `low_level_tracer`, + `or-parallelism`, `rational_trees`, `readline`, `tabling`, + `threads`, or the `wam_profiler`. + */ + YAP_FLAG(SYSTEM_OPTIONS_FLAG, "system_options", false, options, + SYSTEM_OPTIONS, NULL), YAP_FLAG(SYSTEM_THREAD_ID_FLAG, "system_thread_id", false, sys_thread_id, "@boot", NULL), -/**< `tabling_mode` + /**< `tabling_mode` -Sets or reads the tabling mode for all tabled predicates. Please -(see Tabling) for the list of options. + Sets or reads the tabling mode for all tabled predicates. Please + (see Tabling) for the list of options. - */ - YAP_FLAG(TABLING_MODE_FLAG, "tabling_mode", true, isatom, "[]", - NULL), + */ + YAP_FLAG(TABLING_MODE_FLAG, "tabling_mode", true, isatom, "[]", + NULL), YAP_FLAG(THREADS_FLAG, "threads", false, ro, "MAX_THREADS", NULL), YAP_FLAG(TIMEZONE_FLAG, "timezone", false, ro, "18000", NULL), YAP_FLAG(TOPLEVEL_PRINT_ANON_FLAG, "toplevel_print_anon", true, booleanFlag, "true", NULL), -/**< `toplevel_hook ` + /**< `toplevel_hook ` -If bound, set the argument to a goal to be executed before entering the -top-level. If unbound show the current goal or `true` if none is -presented. Only the first solution is considered and the goal is not -backtracked into. + If bound, set the argument to a goal to be executed before entering the + top-level. If unbound show the current goal or `true` if none is + presented. Only the first solution is considered and the goal is not + backtracked into. - */ - YAP_FLAG(TOPLEVEL_PRINT_OPTIONS_FLAG, "toplevel_print_options", true, + */ + YAP_FLAG(TOPLEVEL_PRINT_OPTIONS_FLAG, "toplevel_print_options", true, list_option, "[quoted(true),numbervars(true),portrayed(true)]", - NULL), + NULL), YAP_FLAG(TOPLEVEL_PROMPT_FLAG, "toplevel_prompt", true, isatom, "?- ", mkprompt), YAP_FLAG(TTY_CONTROL_FLAG, "tty_control", true, booleanFlag, "true", NULL), -/**< `unix` + /**< `unix` -Read-only BooleanFlag flag that unifies with `true` if YAP is -running on an Unix system. Defined if the C-compiler used to compile -this version of YAP either defines `__unix__` or `unix`. - */ - YAP_FLAG(UNIX_FLAG, "unix", false, ro, "true", NULL), -/**< `update_semantics ` + Read-only BooleanFlag flag that unifies with `true` if YAP is + running on an Unix system. Defined if the C-compiler used to compile + this version of YAP either defines `__unix__` or `unix`. + */ + YAP_FLAG(UNIX_FLAG, "unix", false, ro, "true", NULL), + /**< `update_semantics ` -Define whether YAP should follow `immediate` update -semantics, as in C-Prolog (default), `logical` update semantics, -as in Quintus Prolog, SICStus Prolog, or in the ISO standard. There is -also an intermediate mode, `logical_assert`, where dynamic -procedures follow logical semantics but the internal data base still -follows immediate semantics. - */ - YAP_FLAG(UPDATE_SEMANTICS_FLAG, "update_semantics", true, isatom, "logical", - NULL), -/**< - `user_flags ` + Define whether YAP should follow `immediate` update + semantics, as in C-Prolog (default), `logical` update semantics, + as in Quintus Prolog, SICStus Prolog, or in the ISO standard. There is + also an intermediate mode, `logical_assert`, where dynamic + procedures follow logical semantics but the internal data base still + follows immediate semantics. + */ + YAP_FLAG(UPDATE_SEMANTICS_FLAG, "update_semantics", true, isatom, "logical", + NULL), + /**< + `user_flags ` - Define the behaviour of set_prolog_flag/2 if the flag is not known. Values - are `silent`, `warning` and `error`. The first two create the flag - on-the-fly, with `warning` printing a message. The value `error` is - consistent with ISO: it raises an existence error and does not create the - flag. See also `create_prolog_flag/3`. The default is`error`, and developers - are encouraged to use `create_prolog_flag/3` to create flags for their - library. - */ - YAP_FLAG(USER_FLAGS_FLAG, "user_flags", true, isatom, "error", NULL), -/**< `unknown is iso` + Define the behaviour of set_prolog_flag/2 if the flag is not known. Values + are `silent`, `warning` and `error`. The first two create the flag + on-the-fly, with `warning` printing a message. The value `error` is + consistent with ISO: it raises an existence error and does not create the + flag. See also `create_prolog_flag/3`. The default is`error`, and developers + are encouraged to use `create_prolog_flag/3` to create flags for their + library. + */ + YAP_FLAG(USER_FLAGS_FLAG, "user_flags", true, isatom, "error", NULL), + /**< `unknown is iso` -Corresponds to calling the unknown/2 built-in. Possible ISO values -are `error`, `fail`, and `warning`. Yap includes the following extensions: -`fast_fail` does not invoke any handler. - */ - YAP_FLAG(UNKNOWN_FLAG, "unknown", true, isatom, "error", - Yap_unknown), + Corresponds to calling the unknown/2 built-in. Possible ISO values + are `error`, `fail`, and `warning`. Yap includes the following extensions: + `fast_fail` does not invoke any handler. + */ + YAP_FLAG(UNKNOWN_FLAG, "unknown", true, isatom, "error", + Yap_unknown), YAP_FLAG(VARIABLE_NAMES_MAY_END_WITH_QUOTES_FLAG, "variable_names_may_end_with_quotes", true, booleanFlag, "false", NULL), -/**< `verbose ` + /**< `verbose ` -If `normal` allow printing of informational and banner messages, -such as the ones that are printed when consulting. If `silent` -disable printing these messages. It is `normal` by default except if -YAP is booted with the `-q` or `-L` flag. + If `normal` allow printing of informational and banner messages, + such as the ones that are printed when consulting. If `silent` + disable printing these messages. It is `normal` by default except if + YAP is booted with the `-q` or `-L` flag. - */ - YAP_FLAG(VERBOSE_FLAG, "verbose", true, isatom, "normal", - NULL), + */ + YAP_FLAG(VERBOSE_FLAG, "verbose", true, isatom, "normal", + NULL), YAP_FLAG(VERBOSE_AUTOLOAD_FLAG, "verbose_autoload", true, booleanFlag, "false", NULL), -/**< `verbose_file_search ` + /**< `verbose_file_search ` -If `true` allow printing of informational messages when -searching for file names. If `false` disable printing these messages. It -is `false` by default except if YAP is booted with the `-L` -flag. - */ - YAP_FLAG(VERBOSE_FILE_SEARCH_FLAG, "verbose_file_search", true, booleanFlag, - "false", NULL), -/**< `verbose_load ` + If `true` allow printing of informational messages when + searching for file names. If `false` disable printing these messages. It + is `false` by default except if YAP is booted with the `-L` + flag. + */ + YAP_FLAG(VERBOSE_FILE_SEARCH_FLAG, "verbose_file_search", true, booleanFlag, + "false", NULL), + /**< `verbose_load ` -If `true` allow printing of informational messages when -consulting files. If `false` disable printing these messages. It -is `normal` by default except if YAP is booted with the `-L` -flag. - */ - YAP_FLAG(VERBOSE_LOAD_FLAG, "verbose_load", true, isatom, "normal", - NULL), -/**< `version_data ` + If `true` allow printing of informational messages when + consulting files. If `false` disable printing these messages. It + is `normal` by default except if YAP is booted with the `-L` + flag. + */ + YAP_FLAG(VERBOSE_LOAD_FLAG, "verbose_load", true, isatom, "normal", + NULL), + /**< `version_data ` -Read-only flag that unifies with a number of the form -`_Major_ * 100000 + _Minor_ *100 + _Patch_`, where -_Major_ is the major version, _Minor_ is the minor version, -and _Patch_ is the patch number. - */ - YAP_FLAG(VERSION_FLAG, "version", false, nat, YAP_NUMERIC_VERSION, - NULL), -/**< - `version ` Read-only flag that returns a compound term with the - current version of YAP. The term will have the name `yap` and arity 4, the first - argument will be the - major version, the second the minor version, the third the patch number, and the - last one is reserved. + Read-only flag that unifies with a number of the form + `_Major_ * 100000 + _Minor_ *100 + _Patch_`, where + _Major_ is the major version, _Minor_ is the minor version, + and _Patch_ is the patch number. + */ + YAP_FLAG(VERSION_FLAG, "version", false, nat, YAP_NUMERIC_VERSION, + NULL), + /**< + `version ` Read-only flag that returns a compound term with the + current version of YAP. The term will have the name `yap` and arity 4, the first + argument will be the + major version, the second the minor version, the third the patch number, and the + last one is reserved. - */ - YAP_FLAG(VERSION_DATA_FLAG, "version_data", false, ro, YAP_TVERSION, - NULL), -/**< `version_git ` - ` - this is the unique identifier for the last commit of the current GIT HEAD, it - xan be used to identify versions that differ on small (or large) updates. - */ - YAP_FLAG(VERSION_GIT_FLAG, "version_git", false, isatom, YAP_GIT_HEAD, - NULL), + */ + YAP_FLAG(VERSION_DATA_FLAG, "version_data", false, ro, YAP_TVERSION, + NULL), + /**< `version_git ` + ` + this is the unique identifier for the last commit of the current GIT HEAD, it + xan be used to identify versions that differ on small (or large) updates. + */ + YAP_FLAG(VERSION_GIT_FLAG, "version_git", false, isatom, YAP_GIT_HEAD, + NULL), YAP_FLAG(WRITE_ATTRIBUTES_FLAG, "write_attributes", true, isatom, "ignore", NULL), #if __WINDOWS__ -/**< `windows ` + /**< `windows` -Read-only booleanFlag flag that unifies with `true` if YAP is -running on an Windows machine. - */ - YAP_FLAG(WINDOWS_FLAG, "windows", false, ro, "true", NULL), + Read-only booleanFlag flag that unifies with `true` if YAP is + running on an Windows machine. + */ + YAP_FLAG(WINDOWS_FLAG, "windows", false, ro, "true", NULL), #endif -/**< `write_strings ` + /**< `write_strings ` -Writable flag telling whether the system should write lists of -integers that are writable character codes using the list notation. It -is `on` if enables or `off` if disabled. The default value for -this flag is `off`. - */ - YAP_FLAG(WRITE_STRINGS_FLAG, "write_strings", true, booleanFlag, "false", - NULL), + Writable flag telling whether the system should write lists of + integers that are writable character codes using the list notation. It + is `on` if enables or `off` if disabled. The default value for + this flag is `off`. + */ + YAP_FLAG(WRITE_STRINGS_FLAG, "write_strings", true, booleanFlag, "false", + NULL), -} global_flag_t; + END_GLOBAL_FLAGS - //! @} +//! @} diff --git a/H/YapLFlagInfo.h b/H/YapLFlagInfo.h index b657bbec9..28d7e15b8 100644 --- a/H/YapLFlagInfo.h +++ b/H/YapLFlagInfo.h @@ -24,12 +24,12 @@ @{ -@enum local_flags flag: +@enum local_flags_setup thread-local flag: */ -typedef enum local_flags_enum { - -/** + `autoload`: set the system to look for undefined procedures */ +START_LOCAL_FLAGS + + /** + `autoload`: set the system to look for undefined procedures */ YAP_FLAG( AUTOLOAD_FLAG, "autoload", true, booleanFlag, "false" , NULL ), /** + `read-only flag, that tells if Prolog is in an inner top-level */ YAP_FLAG( BREAK_LEVEL_FLAG, "break_level", true, nat, "0" , NULL ), @@ -128,7 +128,6 @@ automatically redirects the user_error alias to the original YAP_FLAG( USER_INPUT_FLAG, "user_input", true, stream, "user_input" , set_input_stream ), YAP_FLAG( USER_OUTPUT_FLAG, "user_output", true, stream, "user_output" , set_output_stream ), - -} local_flag_t; +END_LOCAL_FLAGS /// @} diff --git a/docs/md/attributes.md b/docs/md/attributes.md index a92388d02..82c6f1334 100644 --- a/docs/md/attributes.md +++ b/docs/md/attributes.md @@ -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 + and - unary operators. The prefix + 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 domain, 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 - -@} - -@} diff --git a/docs/md/builtins.md b/docs/md/builtins.md index aca08511b..eedf8fe8f 100644 --- a/docs/md/builtins.md +++ b/docs/md/builtins.md @@ -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. diff --git a/docs/md/extensions.md b/docs/md/extensions.md index 844c2e302..05f00531c 100644 --- a/docs/md/extensions.md +++ b/docs/md/extensions.md @@ -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 diff --git a/docs/md/library.md b/docs/md/library.md index 6fe1b9c32..e0103e5a8 100644 --- a/docs/md/library.md +++ b/docs/md/library.md @@ -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 + +@} + diff --git a/docs/md/load_files.md b/docs/md/load_files.md index 52628a024..b488d4ead 100644 --- a/docs/md/load_files.md +++ b/docs/md/load_files.md @@ -6,7 +6,7 @@ Loading and Organising YAP Programs {#load_files} + @ref YAPConsulting - - @page modules + + @page modules + @ref YAPBigLoad diff --git a/docs/md/modules.md b/docs/md/modules.md index 7e648f07f..e18f6e866 100644 --- a/docs/md/modules.md +++ b/docs/md/modules.md @@ -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 diff --git a/docs/md/syntax.md b/docs/md/syntax.md index ac0edd73d..22a0dfe26 100644 --- a/docs/md/syntax.md +++ b/docs/md/syntax.md @@ -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 different 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: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @} +@} diff --git a/docs/md/yap.md b/docs/md/yap.md index aef3ca5b8..eff0609d2 100644 --- a/docs/md/yap.md +++ b/docs/md/yap.md @@ -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 diff --git a/library/lists.yap b/library/lists.yap index 37696c0a8..bca8b707a 100644 --- a/library/lists.yap +++ b/library/lists.yap @@ -48,7 +48,8 @@ /** * @{ * - * @addtogroup library The Prolog Library + * @addtogroup lists List Predicates in the Prolog Library + * @ingroup library * * @brief List Manipulation Predicates * diff --git a/pl/consult.yap b/pl/consult.yap index 8fb9fdd4b..c4d99fbc7 100644 --- a/pl/consult.yap +++ b/pl/consult.yap @@ -91,7 +91,7 @@ /** @defgroup YAPConsulting Loading files into YAP - @ingroup consult + @ingroup load_files @{ @@ -1322,7 +1322,7 @@ account the following observations: + In order to obtain efficient execution, YAP compiles dependencies between re-exported predicates. In practice, this means that changing a `reexport` declaration and then *just* recompiling - the file may result in incorrect execution. + the file may result in incorrect execution. */ '$reexport'( TOpts, File, Reexport, Imports, OldF ) :- diff --git a/pl/corout.yap b/pl/corout.yap index e0fd90b08..0dc80ce00 100644 --- a/pl/corout.yap +++ b/pl/corout.yap @@ -41,14 +41,11 @@ /** - * @defgroup attscorouts Implementing Attributed Variables and Co-Routining - * - * @ingroup attributes + * @ingroup AttributedVariables_Builtins * @{ - * @brief Support for co-routining - * - * -”” */ + * + * + */ /** @pred attr_unify_hook(+ _AttValue_,+ _VarValue_) diff --git a/pl/debug.yap b/pl/debug.yap index c31f167b8..c90b36297 100644 --- a/pl/debug.yap +++ b/pl/debug.yap @@ -245,7 +245,9 @@ be lost. /** - * ### Implementation + * @defgroup DebImplementation Implementation of the Debugger + * @{ + * @brief Prolog code to do debugging. * * The debugger is an interpreter. with main predicates: * - $trace: this is the API @@ -256,7 +258,7 @@ be lost. * + asking Prolog to do it (system_library-builtins) * * |flag | description | initial | possible values - * ---------------------------------------------------------------- + * | ---------------------------------------------------------------- * | spy_gn | last goal number | 1 | 1... * | spy_trace | trace | 0 | 0, 1 * | spy_status | step | creep | creep,leap,skip @@ -395,7 +397,7 @@ be lost. %% @pred '$trace_query'( +G, +M, +CP, +Expanded) % % debug a complex query -% +% '$trace_query'(V, M, CP, _, '$trace'([M|V],CP)) :- var(V), !. '$trace_query'(!, _, CP, _, '$$cut_by'(CP)) :- @@ -496,13 +498,13 @@ be lost. /** * @pred '$enter_trace'(+L, 0:G, +Module, +Info) - * + * * call goal: prelims - * - * @parameter _Module_:_G_ + * + * @parameter _Module_:_G_ * @parameter _L_ is the list of active goals * @parameter _Info_ describes the goal - * + * */ '$enter_trace'(L, G, Module, Info) :- /* get goal no. */ @@ -533,16 +535,16 @@ be lost. /** * @pred '$enter_trace'(+L, 0:G, +Module, +Info) - * + * * call goal: setup the diferrent cases * - zip, just run through * - source, call an interpreter * - compiled code: try black magic. - * - * @parameter _Module_:_G_ + * + * @parameter _Module_:_G_ * @parameter _GoalNumber_ identifies the active goal * @parameter _Info_ describes the goal - * + * */ '$debug'(_, G, M, _H) :- '__NB_getval__'('$debug_status',state(zip,_Border,_), fail), @@ -558,16 +560,16 @@ be lost. /** * @pred '$trace_go'(+L, 0:G, +Module, +Info) - * + * * It needs to run in two separate steps: * 1. Select a clause; * 2. Debug it. * We use a marker to track who we are in gated_call. - * - * @parameter _Module_:_G_ + * + * @parameter _Module_:_G_ * @parameter _GoalNumber_ identifies the active goal * @parameter _Info_ describes the goal - * + * */ '$trace_go'(GoalNumber, G, M, Info) :- X=marker(_,M,G), @@ -1065,3 +1067,6 @@ be lost. '$creep'(creep) :- '$creep'. '$creep'(leap) :- '$creep'. '$creep'(zip). + +%% @} +%% @} diff --git a/pl/directives.yap b/pl/directives.yap index 0694b841b..aa1abb6d8 100644 --- a/pl/directives.yap +++ b/pl/directives.yap @@ -23,7 +23,8 @@ * @brief Control File Loading % % @defgroup Directives Prolog Directives - @ @ingroup consult + * @ingroup YAPConsulting + * @{ * * */ @@ -279,3 +280,5 @@ user_defined_directive(Dir,Action) :- !. '$process_directive'(G, _Mode, M, _VL, _Pos) :- format(user_error,':- ~w:~w failed.~n',[M,G]). + +%% @} diff --git a/pl/error.yap b/pl/error.yap index 0191fd557..2b96441e3 100644 --- a/pl/error.yap +++ b/pl/error.yap @@ -26,7 +26,7 @@ /** @defgroup SWI-error High-level error testing. -@ingroup YAPError +@ingroup builtins This SWI module provides predicates to simplify error generation and checking. Adapted to use YAP built-ins. diff --git a/pl/init.yap b/pl/init.yap index 91670911c..276b8c6f2 100644 --- a/pl/init.yap +++ b/pl/init.yap @@ -14,7 +14,17 @@ * comments: initializing the full prolog system * * * *************************************************************************/ +/** + * @file init.yap + * + * @brief how to boot and run the top-level. + * +*/ +/** + * @insection YAPControl + * +*/ '$init_globals' :- % set_prolog_flag(break_level, 0), diff --git a/pl/load_foreign.yap b/pl/load_foreign.yap index 3e8eef8f3..d086f356c 100644 --- a/pl/load_foreign.yap +++ b/pl/load_foreign.yap @@ -29,7 +29,7 @@ /** @defgroup LoadForeign Access to Foreign Language Programs -@ingroup fli_c_cx +@ingroup fli_c_cxx @{ diff --git a/pl/metadecls.yap b/pl/metadecls.yap index c972adb32..b38da488e 100644 --- a/pl/metadecls.yap +++ b/pl/metadecls.yap @@ -4,9 +4,11 @@ * @author VITOR SANTOS COSTA * @date Sat Apr 7 03:08:03 2018 * - * @brief meta=declarations to run early. + * @brief meta=declarations, must be run early. * + * @addtogroup Meta-Calls The Module System versus the meta-call. * @ingroup YAPMetaPredicates + * @{ * */ @@ -99,3 +101,5 @@ ->(2,2,?,?), \+(2,?,?), \+( 0 )]). + +@} diff --git a/pl/qly.yap b/pl/qly.yap index 31b669095..ec948ecbe 100755 --- a/pl/qly.yap +++ b/pl/qly.yap @@ -19,7 +19,7 @@ /** @defgroup QLY Creating and Using a saved state -@ingroup YAPConsulting +@ingroup load_files @{ */ diff --git a/pl/spy.yap b/pl/spy.yap index 79bcb259c..0aeecbb75 100644 --- a/pl/spy.yap +++ b/pl/spy.yap @@ -1,4 +1,8 @@ -:- system_module( '$_debug', [debug/0, +/** + * @file spy.yap + * @brief debugger operation. + */ + :- system_module( '$_debug', [debug/0, debugging/0, leash/1, nodebug/0, @@ -27,8 +31,9 @@ -----------------------------------------------------------------------------*/ -/** @defgroup Deb_Preds Debugging Predicates -@ingroup builtins +/** + * @defgroup DebSet Debugger Control + * @ingroup builtins Deb_Interaction @{ The @@ -39,10 +44,7 @@ programs: Switches the debugger on. -+ debuggi= -r - -g ++ debugging Outputs status information about the debugger which includes the leash @@ -50,7 +52,6 @@ mode and the existing spy-points, when the debugger is on. + nodebug - Switches the debugger off.