diff --git a/C/cmppreds.c b/C/cmppreds.c index 31278c5fd..6ef967f01 100644 --- a/C/cmppreds.c +++ b/C/cmppreds.c @@ -15,11 +15,13 @@ * comments: comparing two prolog terms * * * *************************************************************************/ + /// @file cmppreds.c -/** @defgroup Comparing_Terms Comparing Terms +/** + @defgroup Comparing_Terms Comparing Terms @ingroup builtins The following predicates are used to compare and order terms, using the @@ -29,8 +31,7 @@ standard ordering: variables come before numbers, numbers come before atoms which in turn come before compound terms, i.e.: variables @< numbers @< atoms @< compound terms. -+ -Variables are roughly ordered by "age" (the "oldest" variable is put ++ Variables are roughly ordered by "age" (the "oldest" variable is put first); + Floating point numbers are sorted in increasing order; diff --git a/C/mavar.c b/C/mavar.c index 899f19b4b..3ce613ba8 100644 --- a/C/mavar.c +++ b/C/mavar.c @@ -16,9 +16,13 @@ *************************************************************************/ -/** @defgroup Term_Modification Term Modification +/** + +@file mavar.c + +@defgroup Term_Modification Term Modification @ingroup builtins -@{ + It is sometimes useful to change the value of instantiated variables. Although, this is against the spirit of logic programming, it @@ -26,14 +30,14 @@ is sometimes useful. As in other Prolog systems, YAP has several primitives that allow updating Prolog terms. Note that these primitives are also backtrackable. -The `setarg/3` primitive allows updating any argument of a Prolog -compound terms. The `mutable` family of predicates provides -mutable variables. They should be used instead of `setarg/3`, +The setarg/3 primitive allows updating any argument of a Prolog +compound terms. The _mutable_ family of predicates provides +mutable variables. They should be used instead of setarg/3, as they allow the encapsulation of accesses to updatable variables. Their implementation can also be more efficient for long deterministic computations. - +@{ */ @@ -315,7 +319,6 @@ p_update_mutable( USES_REGS1 ) return(TRUE); } -static Int /** @pred is_mutable(? _D_) @@ -323,6 +326,7 @@ Holds if _D_ is a mutable term. */ +static Int p_is_mutable( USES_REGS1 ) { Term t = Deref(ARG1); diff --git a/docs/yap.md b/docs/yap.md index 02a8eb8f0..e40bf33ea 100644 --- a/docs/yap.md +++ b/docs/yap.md @@ -774,6 +774,8 @@ YAP Built-ins {#builtins} + @ref YAP_Terms + @ref InputOutput + + + @ref AbsoluteFileName + @ref YAPOS @@ -806,6 +808,9 @@ language. Next, we discuss how to use the most important ones. The YAP Library {#library} =============== +@defgroup library YAP library files +@{ + 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. @@ -861,10 +866,14 @@ The YAP Library {#library} - @ref wgraphs - @ref wundgraphs - @ref ypp +@} The YAP Packages {#packages} ================ +@defgroup packages YAP packages files +@{ + + @ref real + @ref BDDs @@ -891,10 +900,16 @@ Leuven packages ported from SWI-Prolog: + @subpage clpqr +@} Compatibility {#swi} ============= + +@defgroup swi Compatibility +@{ + + YAP has been designed to be as compatible as possible with other Prolog systems, originally with C-Prolog\cite x and SICStus Prolog~\cite x . More recent work on YAP has striven at making YAP @@ -1075,9 +1090,15 @@ architectures. Otherwise, YAP follows IEEE arithmetic. Please inform the authors on other incompatibilities that may still exist. +@} + Foreign Language interface for YAP {#fli} ================================== +@defgroup fli Foreigd Code Interfacing + +@{ + YAP provides the user with three facilities for writing predicates in a language other than Prolog. Under Unix systems, most language implementations were linkable to `C`, and the first interface exported the YAP machinery to the C language. YAP also implements most of the SWI-Prolog foreign language interface. @@ -1088,4 +1109,9 @@ being designed to work with the swig (www.swig.orgv) interface compiler. + The @ref swi-c-interface emulates Jan Wielemaker's SWI foreign language interface. -+ The @ref yap-cplus-interface is desiged to interface with the SWI ackage \cite x Object-Oriented systems. ++ The @ref yap-cplus-interface is desiged to interface with the SWIG package by using Object-Oriented concepts + ++ The @ref LoadInterface handles the setup of foreign files + +@} + diff --git a/os/alias.c b/os/alias.c index a528e91e7..d4b403cb4 100644 --- a/os/alias.c +++ b/os/alias.c @@ -30,8 +30,8 @@ static char SccsId[] = "%W% %G%"; /** - * @group - * + * @defgroup Aliases + * @ingroup InputOutput * * Aliases: * This file defines the main operations on aliases, a second name for a file. Aliases are always diff --git a/os/charsio.c b/os/charsio.c index 4761e2e64..1218019cf 100644 --- a/os/charsio.c +++ b/os/charsio.c @@ -601,7 +601,7 @@ static Int put_char(USES_REGS1) { /* '$put'(Stream,N) */ return (TRUE); } -/** @pred tab(+ _N_) +/** @pred tab_1(+ _N_) Outputs _N_ spaces to the current output stream. diff --git a/os/chartypes.c b/os/chartypes.c index f8a9bdaa6..a2f047704 100644 --- a/os/chartypes.c +++ b/os/chartypes.c @@ -31,6 +31,10 @@ static char SccsId[] = "%W% %G%"; /// @addtogroup CharProps +/** + * @defgroup CharIO Character-Based Input/Output + * @ingroup InputOutput + */ /* * This file includes the definition of a character properties. diff --git a/os/console.c b/os/console.c index 02c05a344..6aca3ab2b 100644 --- a/os/console.c +++ b/os/console.c @@ -18,9 +18,20 @@ static char SccsId[] = "%W% %G%"; #endif +/** + * @file console.c + * @author VITOR SANTOS COSTA + * @date Wed Jan 20 00:56:23 2016 + * + * @brief + * + * + */ /* * This file includes the interface to the console IO, tty style. Refer also to the readline library. - * + * @defgroup console Support for console-based interaction. + * @ingroup InputOutput + */ #include "Yap.h" @@ -181,6 +192,13 @@ ConsoleGetc(int sno) return console_post_process_read_char(ch, s); } +/** @pred prompt1(+ _A__) + + +Changes YAP input prompt for the . + + +*/ static Int prompt1 ( USES_REGS1 ) @@ -198,7 +216,13 @@ prompt1 ( USES_REGS1 ) return (TRUE); } +/** @pred prompt(- _A_,+ _B_) + +Changes YAP input prompt from _A_ to _B_, active on *next* standard input interaction. + + +*/ static Int prompt ( USES_REGS1 ) { /* prompt(Old,New) */ @@ -211,7 +235,7 @@ prompt ( USES_REGS1 ) a = AtomOfTerm (t); if (strlen(RepAtom (a)->StrOfAE) > MAX_PROMPT) { Yap_Error(SYSTEM_ERROR_INTERNAL,t,"prompt %s is too long", RepAtom (a)->StrOfAE); - return(FALSE); + return false; } strncpy(LOCAL_Prompt, (char *)RepAtom (LOCAL_AtPrompt)->StrOfAE, MAX_PROMPT); LOCAL_AtPrompt = a; diff --git a/os/edio.yap b/os/edio.yap index 1b5c52d11..cba6e023c 100644 --- a/os/edio.yap +++ b/os/edio.yap @@ -1,7 +1,37 @@ % % Edinburgh IO. +/** + * @file edio.yap + * @author VITOR SANTOS COSTA + * @date Wed Jan 20 01:07:02 2016 + * + * @brief Input/Output according to the DEC-10 Prolog. PLease consider using the ISO + * standard predicates for new code. + * + * +*/ + + % +/** @pred see(+ _S_) + + +If _S_ is a currently opened input stream then it is assumed to be +the current input stream. If _S_ is an atom it is taken as a +filename. If there is no input stream currently associated with it, then +it is opened for input, and the new input stream thus created becomes +the current input stream. If it is not possible to open the file, an +error occurs. If there is a single opened input stream currently +associated with the file, it becomes the current input stream; if there +are more than one in that condition, then one of them is chosen. + +When _S_ is a stream not currently opened for input, an error may be +reported, depending on the state of the `file_errors` flag. If + _S_ is neither a stream nor an atom the predicates just fails. + + +*/ see(user) :- !, set_input(user_input). see(F) :- var(F), !, '$do_error'(instantiation_error,see(F)). @@ -13,6 +43,13 @@ see(Stream) :- '$stream'(Stream), current_stream(_,read,Stream), !, set_input(Stream). see(F) :- open(F,read,Stream), set_input(Stream). +/** @pred seeing(- _S_) + + +The current input stream is unified with _S_. + + +*/ seeing(File) :- current_input(Stream), stream_property(Stream,file_name(NFile)), ( @@ -23,8 +60,33 @@ seeing(File) :- current_input(Stream), NFile = File ). +/** @pred seen + + +Closes the current input stream, as opened by see/1. Standard input +stream goes to the original ùser_input`. + + */ seen :- current_input(Stream), close(Stream), set_input(user). +/** @pred tell(+ _S_) + + +If _S_ is a currently opened stream for output, it becomes the +current output stream. If _S_ is an atom it is taken to be a +filename. If there is no output stream currently associated with it, +then it is opened for output, and the new output stream created becomes +the current output stream. If it is not possible to open the file, an +error occurs. If there is a single opened output stream currently +associated with the file, then it becomes the current output stream; if +there are more than one in that condition, one of them is chosen. + +Whenever _S_ is a stream not currently opened for output, an error +may be reported, depending on the state of the file_errors flag. The +predicate just fails, if _S_ is neither a stream nor an atom. + + +*/ tell(user) :- !, set_output(user_output). tell(F) :- var(F), !, '$do_error'(instantiation_error,tell(F)). @@ -43,12 +105,29 @@ tell(Stream) :- tell(F) :- open(F,append,Stream), set_output(Stream). - + +/** @pred telling(- _S_) + + +The current output stream is unified with _S_. + + +*/ telling(File) :- current_output(Stream), stream_property(Stream,file_name(NFile)), ( stream_property(user_output,file_name(NFile)) -> File = user ; File = NFile ). +/** @pred told + + +Closes the current output stream, and the user's terminal becomes again +the current output stream. It is important to remember to close streams +after having finished using them, as the maximum number of +simultaneously opened streams is 17. + + +*/ told :- current_output(Stream), !, set_output(user), diff --git a/os/iopreds.h b/os/iopreds.h index 5f9e7bf31..499723efd 100644 --- a/os/iopreds.h +++ b/os/iopreds.h @@ -239,6 +239,7 @@ Yap_GetStreamHandle(Term t) #define YAP_ERROR NIL +/// maximum number of open streams #define MaxStreams 64 #define EXPAND_FILENAME 0x000080