From 8d1cc35a8a2bbe17bb2bc0a8284cb98ef00dbbd8 Mon Sep 17 00:00:00 2001 From: Vitor Santos Costa Date: Wed, 16 Nov 2016 17:17:33 -0600 Subject: [PATCH] docsc --- .gitignore | 2 + C/attvar.c | 7 +- PrologCommons/PROLOGCOMMONS.md | 3 +- README.md | 25 +- docs/Doxyfile | 7 +- docs/Doxyfile.in | 5 +- docs/builtins.md | 31 ++ docs/download.md | 17 + docs/extensions.md | 21 + docs/fli.md | 16 + docs/install.md | 0 docs/library.md | 58 +++ docs/load_files.md | 11 + docs/packages.md | 28 + docs/run.md | 19 +- docs/swi.md | 182 +++++++ docs/syntax.md | 33 +- docs/yap.md | 601 +--------------------- library/atts.yap | 6 +- misc/PROLOGCOMMONS.md | 2 + os/readterm.c | 94 +++- packages/bdd/{README => bdd.md} | 13 +- {docs => packages/chr}/chr.md | 4 - packages/chr/chr.yap | 536 ------------------- {docs => packages/clpqr}/clpqr.md | 5 +- packages/clpqr/clpr.pl | 5 +- packages/gecode/{DOC.txt => gecode.md} | 22 +- packages/myddas/myddas.md | 574 +++++++++++++++++++++ packages/myddas/pl/myddas.ypp | 685 +------------------------ packages/raptor/README.md | 8 +- packages/real/README.md | 227 +++++++- packages/real/real.pl | 223 -------- packages/udi/udi.md | 5 +- pl/attributes.md | 14 +- pl/modules.md | 5 +- run.md | 193 +++++++ 36 files changed, 1523 insertions(+), 2164 deletions(-) delete mode 100644 docs/install.md create mode 100644 docs/library.md create mode 100644 docs/load_files.md rename packages/bdd/{README => bdd.md} (67%) rename {docs => packages/chr}/chr.md (99%) rename {docs => packages/clpqr}/clpqr.md (97%) rename packages/gecode/{DOC.txt => gecode.md} (91%) create mode 100644 packages/myddas/myddas.md create mode 100644 run.md diff --git a/.gitignore b/.gitignore index e9a3c5a7c..634f7d844 100644 --- a/.gitignore +++ b/.gitignore @@ -203,3 +203,5 @@ packages/python/yap_kernel/x/__init__.py packages/python/yap_kernel/x/__main__.py *.gch +mxe +build diff --git a/C/attvar.c b/C/attvar.c index a2627a09e..e6045e8d8 100644 --- a/C/attvar.c +++ b/C/attvar.c @@ -28,10 +28,11 @@ static char SccsId[] = "%W% %G%"; #define NULL (void *)0 #endif -/** @{ */ +/** @file attvars.c + @{ */ -/** @defgroup AttributeVariables_Builtins Implementation of Attribute - Declarations +/** + * @defgroup AttributeVariables_Builtins Implementation of Attribute Declarations @ingroup AttributeVariables */ diff --git a/PrologCommons/PROLOGCOMMONS.md b/PrologCommons/PROLOGCOMMONS.md index a2d50cd9d..ecb96a348 100644 --- a/PrologCommons/PROLOGCOMMONS.md +++ b/PrologCommons/PROLOGCOMMONS.md @@ -1,4 +1,5 @@ - +Prolog Commons {#prolog_commons} +============= This directory should hold files from the Prolog Commons project. Please see diff --git a/README.md b/README.md index 610b8d187..756627999 100644 --- a/README.md +++ b/README.md @@ -3,12 +3,12 @@ ![The YAP Logo](docs/icons/yap_128x128x32.png) -README for YAP6 +User Manual for YAP6 (#main) ==================== -NOTE: this version of YAP is stil experimental, documentation may be out of date. +NOTE: this version of YAP is still experimental, documentation may be out of date. -## Introduction +## Introduction This document provides User information on version 6.3.4 of YAP (Yet Another Prolog). The YAP Prolog System is a @@ -94,22 +94,3 @@ DTAI group of KULeuven. + The [R](http://stoics.org.uk/~nicos/sware/packs/real/) interface package developed by Nicos Angelopoulos, Vítor Santos Costa, João Azevedo, Jan Wielemaker, and Rui Camacho. - - -Downloading YAP {#download} -============== - -The latest development version of Yap-6 is yap-6.3.4 and can be -obtained from the repositories - - - -and - - - -YAP-6.3.4 does not use modules. Please just use `git clone` to obtain the distribution. - -Most of these repositories are basically copies of the original -repositories at the SWI-Prolog site. YAP-6 will work either with or -without these packages. diff --git a/docs/Doxyfile b/docs/Doxyfile index b56d7949a..59e828927 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -785,9 +785,8 @@ INPUT = /Users/vsc/git/yap-6.3/pl \ /Users/vsc/git/yap-6.3/library \ /Users/vsc/git/yap-6.3/packages \ /Users/vsc/git/yap-6.3/swi/library \ - /Users/vsc/git/yap-6.3/docs/yap.md \ - /Users/vsc/git/yap-6.3/docs/chr.md \ - /Users/vsc/git/yap-6.3/docs/clpqr.md \ + /Users/vsc/git/yap-6.3/docs/*.md \ + /Users/vsc/git/yap-6.3/*.md \ # This tag can be used to specify the character encoding of the source files @@ -937,7 +936,7 @@ FILTER_SOURCE_PATTERNS = # (index.html). This can be useful if you have a project on for instance GitHub # and want to reuse the introduction page also for the doxygen output. -USE_MDFILE_AS_MAINPAGE = +USE_MDFILE_AS_MAINPAGE = #--------------------------------------------------------------------------- # Configuration options related to source browsing diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index f18062fa2..e53fe508f 100644 --- a/docs/Doxyfile.in +++ b/docs/Doxyfile.in @@ -785,9 +785,8 @@ INPUT = @PROJECT_SOURCE_DIR@/pl \ @PROJECT_SOURCE_DIR@/library \ @PROJECT_SOURCE_DIR@/packages \ @PROJECT_SOURCE_DIR@/swi/library \ - @PROJECT_SOURCE_DIR@/docs/yap.md \ - @PROJECT_SOURCE_DIR@/docs/chr.md \ - @PROJECT_SOURCE_DIR@/docs/clpqr.md \ + @PROJECT_SOURCE_DIR@/docs/*.md \ + @PROJECT_SOURCE_DIR@/*.md # This tag can be used to specify the character encoding of the source files diff --git a/docs/builtins.md b/docs/builtins.md index e69de29bb..5625441b5 100644 --- a/docs/builtins.md +++ b/docs/builtins.md @@ -0,0 +1,31 @@ +YAP Built-ins {#builtins} +================= + +This chapter describes the core predicates that control the execution of +Prolog programs, provide fundamental functionality such as termm manipulation or arithmetic, and support interaction with external +resources, Many of the predicates described here have been standardised by the ISO. The standartised subset of Proloh also known as ISO-Prolog. + +In the description of the arguments of functors the following notation +will be used: + ++ a preceding plus sign will denote an argument as an "input +argument" - 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 YAPControl + ++ @ref Arithmetic + ++ @ref YAPChars + ++ @ref YAP_Terms + ++ @ref InputOutput + ++ @ref AbsoluteFileName + ++ @ref YAPOS + ++ @ref Internal_Database + ++ @ref Sets diff --git a/docs/download.md b/docs/download.md index e69de29bb..492a0ce6c 100644 --- a/docs/download.md +++ b/docs/download.md @@ -0,0 +1,17 @@ +Downloading YAP {#download} +============== + +The latest development version of Yap-6 is yap-6.3.4 and can be +obtained from the repositories + + + +and + + + +YAP-6.3.4 does not use modules. Please just use `git clone` to obtain the distribution. + +Most of these repositories are basically copies of the original +repositories at the SWI-Prolog site. YAP-6 will work either with or +without these packages. diff --git a/docs/extensions.md b/docs/extensions.md index e69de29bb..844c2e302 100644 --- a/docs/extensions.md +++ b/docs/extensions.md @@ -0,0 +1,21 @@ +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 AttributedVariables + + + @ref DepthLimited + + + @ref Tabling + + + @ref Threads + + + @ref Profiling + + + @ref YAPArrays + + + @ref Parallelism diff --git a/docs/fli.md b/docs/fli.md index e69de29bb..31df4b1ea 100644 --- a/docs/fli.md +++ b/docs/fli.md @@ -0,0 +1,16 @@ +The Foreign Code Interface {#fli} +=========================== + +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. +This gives portability with a number of SWI-Prolog packages and avoids garnage collection by using @ref slotInterface. Last, a new C++ based interface is +being designed to work with the swig (www.swig.orgv) interface compiler. + ++ The @ref c-interface exports the YAP engine. + ++ The @ref swi-c-interface emulates Jan Wielemaker's SWI foreign language interface. + ++ 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/docs/install.md b/docs/install.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/library.md b/docs/library.md new file mode 100644 index 000000000..7e69e0d2a --- /dev/null +++ b/docs/library.md @@ -0,0 +1,58 @@ +The YAP Library (#library) +============== + + Library files reside in the library_directory path (set by the + `LIBDIR` variable in the Makefile for YAP). Several files in the + library are originally from the public-domain Edinburgh Prolog library. + +- @ref apply +- @ref apply_macros +- @ref arg +- @ref Association_Lists +- @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 swi_listing +- @ref lists +- @ref mapargs +- @ref maplist +- @ref matlab +- @ref matrix +- @ref nb +- @ref Ordered_Sets +- @ref parameters +- @ref queues +- @ref random +- @ref Pseudo_Random +- @ref rbtrees +- @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 wdgraphs +- @ref wdgraphs +- @ref wgraphs +- @ref wundgraphs +- @ref ypp diff --git a/docs/load_files.md b/docs/load_files.md new file mode 100644 index 000000000..9a95f40cf --- /dev/null +++ b/docs/load_files.md @@ -0,0 +1,11 @@ +Loading and Oganising YAP Programs {#consult} +=================================== + + Next, we present the main predicates and directives available to load + files and to control the Prolog environment. + + + @ref YAPConsulting + + + @subpage YAPModules + + + @ref YAPSaving diff --git a/docs/packages.md b/docs/packages.md index e69de29bb..076093040 100644 --- a/docs/packages.md +++ b/docs/packages.md @@ -0,0 +1,28 @@ +YAP packages files {#packages} +=================== + ++ @subpage real + ++ @ref BDDs + ++ @subpage ecode + ++ @subpage myddas + ++ @ref PFL/CLP(BN) + ++ @ref ProbLog1 + ++ @ref Python + ++ @subpage YAPRaptor + ++ @ref YAP-LBFGS + ++ @subpage yap-udi-indexers + +Leuven packages ported from SWI-Prolog: + ++ @subpage chr + ++ @subpage clpqr diff --git a/docs/run.md b/docs/run.md index e9b724366..e442df2b6 100644 --- a/docs/run.md +++ b/docs/run.md @@ -1,4 +1,4 @@ -Running YAP +Running YAP {#run} =========== We next describe how to invoke YAP in Unix systems. @@ -24,7 +24,7 @@ specify M bytes. allocate _Size_ KBytes for heap and auxiliary stacks + -t _Size_ allocate _Size_ KBytes for the trail stack -+ -L _Size_ ++ -L _Size_ SWI-compatible option to allocate _Size_ K bytes for local and global stacks, the local stack cannot be expanded. To avoid confusion with the load option, _Size_ must immediately follow the letter `L`. @@ -62,34 +62,34 @@ through the unix/1 built-in predicate. Note that YAP will output an error message on the following conditions: -+ ++ a file name was given but the file does not exist or is not a saved YAP state; -+ ++ the necessary amount of memory could not be allocated; -+ ++ the allocated memory is not enough to restore the state. - + When restoring a saved state, YAP will allocate the same amount of memory as that in use when the state was saved, unless a different amount is specified by flags in the command line. By default, YAP restores the file startup.yss from the current directory or from the YAP library. -+ ++ YAP usually boots from a saved state. The saved state will use the default installation directory to search for the YAP binary unless you define the environment variable YAPBINDIR. -+ ++ YAP always tries to find saved states from the current directory first. If it cannot it will use the environment variable YAPLIBDIR, if defined, or search the default library directory. -+ ++ YAP will try to find library files from the YAPSHAREDIR/library directory. @@ -188,4 +188,3 @@ they must be sent directly to the argv built-in. Hence, running ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ will write `test` on the standard output. - diff --git a/docs/swi.md b/docs/swi.md index e69de29bb..c82a99624 100644 --- a/docs/swi.md +++ b/docs/swi.md @@ -0,0 +1,182 @@ +Compatibility with other Prolog systems {#swi} +======================================= + +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 +compatible with the ISO-Prolog standard\cite x , and with Jan +Wielemaker's SWI-Prolog\cite x . + +SWI-Prolog and YAP have collaborated at improved compatibility \cite x . This +resulted in Prolog extensions such as the `dialect` feature. YAP +currently supports most of the SWI-Prolog foreign interface. The following SWI +libraries have been adapted to YAP: + + + @ref aggregate + + @ref base64 + + @ref broadcast + + @ref ctypes + + @ref date + + @ref prolog_debug + + @ref prolog_edit + + @ref error + + @ref nb_set + + @ref prolog_operator + + @ref swi_option + + @ref pairs + + @ref pio + + @ref predicate_options, + + @ref predopts + + @ref prolog_clause + + @ref prolog_colour + + @ref prolog_source + + @ref prolog_xref + + @ref pure_input + + @ref quasi_quotations + + @ref read_util + + @ref record + + @ref settings + + @ref shlib + + @ref thread_pool + + @ref url + + @ref utf8 + + @ref win_menu + + @ref www_browser + + +Note that in general SWI code may be from an earlier version than the +one available with SWI-Prolog. SWI-Prolog are obviously not +responsible for any incompatibilities and/or bugs in the YAP port. + +Please do refer to the SWI-Prolog home page: + + + +for more information on SWI-Prolog and the SWI packages. + +Compatibility with the C-Prolog interpreter {#ChYProlog} +------------------------------------------- + +YAP was designed so that most C-Prolog programs should run under YAP +without changes. +The most important difference between YAP and C-Prolog is that, being +YAP a compiler, some changes should be made if predicates such as +assert/1, clause/1 and retract/1 are used. First +predicates which will change during execution should be declared as +`dynamic` by using commands like: + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +:- dynamic f/n. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + where `f` is the predicate name and n is the arity of the +predicate. Note that several such predicates can be declared in a +single command: + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + :- dynamic f/2, ..., g/1. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Primitive predicates such as `retract` apply only to dynamic +predicates. Finally note that not all the C-Prolog primitive predicates +are implemented in YAP. They can easily be detected using the +`unknown` system predicate provided by YAP. + +Last, by default YAP enables character escapes in strings. You can +disable the special interpretation for the escape character by using: + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +:- yap_flag(character_escapes,off). +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +or by using: + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +:- yap_flag(language,cprolog). +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + +Compatibility with the Quintus and SICStus Prolog systems +--------------------------------------------------------- + +The Quintus Prolog system was the first Prolog compiler to use Warren's +Abstract Machine. This system was very influential in the Prolog +community. Quintus Prolog implemented compilation into an abstract +machine code, which was then emulated. Quintus Prolog also included +several new built-ins, an extensive library, and in later releases a +garbage collector. The SICStus Prolog system, developed at SICS (Swedish +Institute of Computer Science), is an emulator based Prolog system +largely compatible with Quintus Prolog. SICStus Prolog has evolved +through several versions. The current version includes several +extensions, such as an object implementation, co-routining, and +constraints. + +Both YAP and SICStus Prolog obey the Edinburgh Syntax and are based on +the WAM. Even so, there are major important differences: + + + Differently from SICStus Prolog, both consulted and dynamic code in YAP + are compiled, not interpreted. All code in YAP is compiled. + + + The following SICStus Prolog v3 built-ins are not (currently) +implemented in YAP (note that this is only a partial list): +stream_interrupt/3, reinitialize/0, help/0, help/1, +trimcore/0, and require/1. + + + The consult/1 predicate in YAP follows C-Prolog +semantics. That is, it adds clauses to the data base, even for +preexisting procedures. This is different from consult/1 in +SICStus Prolog or SWI-Prolog. + + + This list is incomplete. + +Compatibility with the ISO Prolog standard +------------------------------------------ + +The Prolog standard was developed by ISO/IEC JTC1/SC22/WG17, the +international standardization working group for the programming language +Prolog. The book "Prolog: The Standard" by Deransart, Ed-Dbali and +Cervoni gives a complete description of this standard. Development in +YAP from YAP4.1.6 onwards have striven at making YAP +compatible with ISO Prolog. As such: + + + YAP now supports all of the built-ins required by the +ISO-standard, and, + + Error-handling is as required by the standard. + + +YAP by default is not fully ISO standard compliant. You can set the +language flag to `iso` to obtain better +compatibility. Setting this flag changes the following: + + + + By default, YAP implements the +atom_chars/2 (see Testing Terms), and +number_chars/2, (see Testing Terms), +built-ins as per the original Quintus Prolog definition, and +not as per the ISO definition. + +Calling `set_prolog_flag(to_chars_mode,iso)` will switch +YAP to use the ISO definition for +atom_chars/2 and number_chars/2. + + + By default, YAP allows executable goals in directives. In ISO mode +most directives can only be called from top level (the exceptions are +set_prolog_flag/2 and op/3). + + + Error checking for meta-calls under ISO Prolog mode is stricter +than by default. + + + The strict_iso flag automatically enables the ISO Prolog +standard. This feature should disable all features not present in the +standard. + +The following incompatibilities between YAP and the ISO standard are +known to still exist (please check Ulrich Neumerkel's page for more details): + +
    + +
  • Currently, YAP does not handle overflow errors in integer +operations, and handles floating-point errors only in some +architectures. Otherwise, YAP follows IEEE arithmetic. + +Please inform the authors on other incompatibilities that may still +exist. diff --git a/docs/syntax.md b/docs/syntax.md index 1dd73cb2c..6c46eac77 100644 --- a/docs/syntax.md +++ b/docs/syntax.md @@ -1,6 +1,5 @@ - - -@file syntax.md +YAP Syntax (#YAPSyntax) +============ @defgroup YAPSyntax YAP Syntax @ingroup mainpage @@ -198,11 +197,11 @@ YAP supports four different textual elements: data-base. They are stored either in ISO-LATIN-1 (first 256 code points), or as UTF-32. + Strings are atomic representations of text. The back-quote character is used to identify these objects in the program. Strings exist as stack objects, in the same way as other Prolog terms. As Prolog unification cannot be used to manipulate strings, YAP includes built-ins such as string_arg/3, sub_string/5, or string_concat to manipulate them efficiently. Strings are stored as opaque objects containing a - + + Lists of codes represent text as a list of numbers, where each number is a character code. A string of _N_ bytes requires _N_ pairs, that is _2N_ cells, leading to a total of 16 bytes per character on 64 byte machines. Thus, they are a very expensive, but very flexible representation, as one can use unification to construct and access string elements. - + + Lists of atoms represent text as a list of atoms, where each number has a single character code. A string of _N_ bytes also requires _2N_ pairs. They have similar properties to lists of codes. - + The flags `double_quotes` and `backquoted_string` change the interpretation of text strings, they can take the values `atom`, `string`, `codes`, and `chars`. @@ -213,7 +212,7 @@ Examples: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The first string is an empty string, the last string shows the use of -double-quoting. +double-quoting. Escape sequences can be used to include the non-printable characters `a` (alert), `b` (backspace), `r` (carriage return), @@ -346,7 +345,7 @@ atoms. If the text fits in ISO Latin-1, it is represented as an array of 8-bit characters. Otherwise the text is represented as an array of wide chars, which may take 16 or 32 bits. This representational issue is completely transparent to the Prolog user. Users of the foreign -language interface sometimes need to be aware of these issues though. Notice that this will likely +language interface sometimes need to be aware of these issues though. Notice that this will likely change in the future, we probably will use an UTF-8 based representation. Character coding comes into view when characters of strings need to be @@ -359,7 +358,7 @@ as well as I/O through network sockets. @ingroup WideChars The UCS standard describes all possible characters (or code points, as they include -ideograms, ligatures, and other symbols). The current version, Unicode 8.0, allows +ideograms, ligatures, and other symbols). The current version, Unicode 8.0, allows code points up to 0x10FFFF, and thus allows for 1,114,112 code points. See [Unicode Charts](http://unicode.org/charts/) for the supported languages. Notice that most symbols are rarely used. Encodings represent the Unicode characters in a way @@ -367,23 +366,23 @@ that is more suited for communication. The most popular encoding, especially in UTF-8. UTF-8 is compact and as it uses bytes, does not have different endianesses. Bytes 0...127 represent simply the corresponding US-ASCII character, while bytes 128...255 are used for multi-byte -encoding of characters placed higher in the UCS space. +encoding of characters placed higher in the UCS space. Especially on MS-Windows and Java the 16-bit Unicode standard, represented by pairs of bytes is -also popular. Originally, Microsoft supported a UCS-2 with 16 bits that +also popular. Originally, Microsoft supported a UCS-2 with 16 bits that could represent only up to 64k characters. This was later extended to support the full Unicode, we will call the latter version UTF-16. The extension uses a hole in the first 64K code points. Characters above 0xFFFF are divided into two 2-byte words, each one in that hole. There are two versions of UTF-16: big and low endian. By default, UTF-16 is big endian, in practice most often it is used on Intel hardware that is naturally little endian. - - UTF-32, often called UCS-4, provides a natural interface where a code point is coded as + + UTF-32, often called UCS-4, provides a natural interface where a code point is coded as four octets. Unfortunately, it is also more expensive, so it is not as widely used. - + Last, other encodings are also commonly used. One such legacy encoding is ISO-LATIN-1, that supported latin based languages in western europe. YAP currently uses either ISO-LATIN-1 or UTF-32 internally. - + Prolog supports the default encoding used by the Operating System, Namely, YAP checks the variables LANG, LC_ALL and LC_TYPE. Say, if at boot YAP detects that the environment variable `LANG` ends in "UTF-8", this encoding is @@ -419,7 +418,7 @@ but generates errors and warnings on encountering values above 8-bit encoding supporting many western languages. This causes the stream to be read and written fully untranslated. - + `text` + + `text` C-library default locale encoding for text files. Files are read and written using the C-library functions `mbrtowc()` and `wcrtomb()`. This may be the same as one of the other locales, @@ -484,7 +483,7 @@ writing, writing a BOM can be requested using the option `bom(true)` with `open/4`. YAP will parse an UTF-8 file for a BOM only if explicitly required to do so. Do notice that YAP will write a BOM by default on UTF-16 (including UCS-2) and 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 diff --git a/docs/yap.md b/docs/yap.md index 5736afc26..e4d98d156 100644 --- a/docs/yap.md +++ b/docs/yap.md @@ -1,31 +1,31 @@ YAP 6-3.4 Manual {#mainpage} ==================== -This file documents the YAP Prolog System version 6.3.4, a high-performance Prolog compiler developed at LIACC, Universidade do Porto. YAP is based on David H. D. Warren's WAM (Warren Abstract Machine), with several optimizations for better performance. YAP follows the Edinburgh tradition, and is largely compatible with DEC-10 Prolog, Quintus Prolog, and especially with C-Prolog. +This file documents the YAP Prolog System version 6.3.4, a high-performance Prolog compiler developed at LIACC, Universidade do Porto. YAP is based on David H. D. Warren's WAM (Warren Abstract Machine), with several optimizations for better performance. YAP follows the Edinburgh tradition, and is largely compatible with DEC-10 Prolog, Quintus Prolog, and originally with C-Prolog. -+ @ref download +The manual is organised as follows: -+ @ref install -+ @ref run ++ @subpage download -+ @ref YAPSyntax ++ @subpage install -+ @ref consult ++ @subpage run -+ @ref builtins ++ @subpage builtins -+ @ref extensions ++ @subpage extensions -+ @ref library ++ @subpage library -+ @ref packages ++ @subpage swi -+ @ref swi ++ @subpage packages -+ @ref YAPProgramming ++ @subpage YAPProgramming + ++ @subpage Fli -+ @ref fli @@ -51,578 +51,3 @@ originally from the SWI-Prolog manual, with the gracious authorization from Jan Wielemaker. We would also like to gratefully acknowledge the contributions from Ashwin Srinivasian. - - - -Loading and Organising YAP Programs {#consult} -=================================== - - @ingroup main - - Next, we present the main predicates and directives available to load - files and to control the Prolog environment. - - + @ref YAPConsulting - - + @ref YAPModules - - +@ref YAPSaving - - - This chapter describes the predicates controlling the execution of - Prolog programs. - - In the description of the arguments of functors the following notation - will be used: - - + a preceding plus sign will denote an argument as an "input - argument" - 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. - -Running YAP {#run} -=========== - -We next describe how to invoke YAP in Unix systems. - -Running YAP Interactively -------------------------- - -Most often you will want to use YAP in interactive mode. Assuming that -YAP is in the user's search path, the top-level can be invoked under -Unix with the following command: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -yap [-s n] [-h n] [-a n] [-c IP_HOST port ] [filename] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -All the arguments and flags are optional and have the following meaning: - -+ -? -print a short error message. -+ -s _Size_ -allocate _Size_ KBytes for local and global stacks. The user may -specify M bytes. -+ -h _Size_ -allocate _Size_ KBytes for heap and auxiliary stacks -+ -t _Size_ -allocate _Size_ KBytes for the trail stack -+ -L _Size_ -SWI-compatible option to allocate _Size_ K bytes for local and global stacks, the local stack -cannot be expanded. To avoid confusion with the load option, _Size_ -must immediately follow the letter `L`. -+ -G _Size_ -SWI-compatible option to allocate _Size_ K bytes for local and global stacks; the global -stack cannot be expanded -+ -T _Size_ -SWI-compatible option to allocate _Size_ K bytes for the trail stack; the trail cannot be expanded. -+ -l _YAP_FILE_ -compile the Prolog file _YAP_FILE_ before entering the top-level. -+ -L _YAP_FILE_ -compile the Prolog file _YAP_FILE_ and then halt. This option is -useful for implementing scripts. -+ -g _Goal_ -run the goal _Goal_ before top-level. The goal is converted from -an atom to a Prolog term. -+ -z _Goal_ -run the goal _Goal_ as top-level. The goal is converted from -an atom to a Prolog term. -+ -b _BOOT_FILE_ -boot code is in Prolog file _BOOT_FILE_. The filename must define -the predicate `'$live'/0`. -+ -c IP_HOST port -connect standard streams to host IP_HOST at port port -+ filename -restore state saved in the given file -+ -f -do not consult initial files -+ -q -do not print informational messages -+ -- -separator for arguments to Prolog code. These arguments are visible -through the unix/1 built-in predicate. - - -Note that YAP will output an error message on the following conditions: - -+ -a file name was given but the file does not exist or is not a saved -YAP state; - -+ -the necessary amount of memory could not be allocated; - -+ -the allocated memory is not enough to restore the state. - - - When restoring a saved state, YAP will allocate the -same amount of memory as that in use when the state was saved, unless a -different amount is specified by flags in the command line. By default, -YAP restores the file startup.yss from the current directory or from -the YAP library. - -+ -YAP usually boots from a saved state. The saved state will use the default -installation directory to search for the YAP binary unless you define -the environment variable YAPBINDIR. - -+ -YAP always tries to find saved states from the current directory - first. If it cannot it will use the environment variable YAPLIBDIR, if - defined, or search the default library directory. - -+ -YAP will try to find library files from the YAPSHAREDIR/library -directory. - - -Prolog Scripts --------------- - -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 -that the shell comments are very important): - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -#!/usr/local/bin/yap -L -- -# -# Hello World script file using YAP -# -# put a dot because of syntax errors . - -:- write('Hello World'), nl. - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The `#!` characters specify that the script should call the binary -file YAP. Notice that many systems will require the complete path to the -YAP binary. The `-L` flag indicates that YAP should consult the -current file when booting and then halt. The remaining arguments are -then passed to YAP. Note that YAP will skip the first lines if they -start with `#` (the comment sign for Unix's shell). YAP will -consult the file and execute any commands. - -A slightly more sophisticated example is: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -#!/usr/bin/yap -L -- -# -# Hello World script file using YAP -# . - -:- initialization(main). - -main :- write('Hello World'), nl. - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The `initialization` directive tells YAP to execute the goal main -after consulting the file. Source code is thus compiled and `main` -executed at the end. The `.` is useful while debugging the script -as a Prolog program: it guarantees that the syntax error will not -propagate to the Prolog code. - -Notice that the `--` is required so that the shell passes the extra -arguments to YAP. As an example, consider the following script -`dump_args`: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -#!/usr/bin/yap -L -- -#. - -main( [] ). -main( [H|T] ) :- - write( H ), nl, - main( T ). - -:- unix( argv(AllArgs) ), main( AllArgs ). - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you this run this script with the arguments: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -./dump_args -s 10000 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -the script will start an YAP process with stack size `10MB`, and -the list of arguments to the process will be empty. - -Often one wants to run the script as any other program, and for this it -is convenient to ignore arguments to YAP. This is possible by using -`L --` as in the next version of `dump_args`: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -#!/usr/bin/yap -L -- - -main( [] ). -main( [H|T] ) :- - write( H ), nl, - main( T ). - -:- unix( argv(AllArgs) ), main( AllArgs ). - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The `--` indicates the next arguments are not for YAP. Instead, -they must be sent directly to the argv built-in. Hence, running - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -./dump_args test -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -will write `test` on the standard output. - -YAP Built-ins {#builtins} -============= - - + @ref YAPControl - - + @ref arithmetic - - + @ref YAPChars - - + @ref YAP_Terms - - + @ref InputOutput - - + @ref AbsoluteFileName - - + @ref YAPOS - - + @ref Internal_Database - - + @ref Sets - -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 AttributedVariables - - + @ref DepthLimited - - + @ref Tabling - - + @ref Threads - - + @ref Profiling - - + @ref YAPArrays - - + @ref Parallelism - -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. - -- @ref apply -- @ref apply_macros -- @ref arg -- @ref Association_Lists -- @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 swi_listing -- @ref lists -- @ref mapargs -- @ref maplist -- @ref matlab -- @ref matrix -- @ref nb -- @ref Ordered_Sets -- @ref parameters -- @ref queues -- @ref random -- @ref Pseudo_Random -- @ref rbtrees -- @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 wdgraphs -- @ref wdgraphs -- @ref wgraphs -- @ref wundgraphs -- @ref ypp -@} - -The YAP Packages {#packages} -================ - -@defgroup packages YAP packages files -@{ - -+ @ref real - -+ @ref BDDs - -+ @ref Gecode - -+ @ref MYDDAS - -+ @ref PFL - -+ @ref ProbLog1 - -+ @ref python - -+ @ref YAPRaptor - -+ @ref YAP-LBFGS - -+ @subpage yap-udi-indexers - -Leuven packages ported from SWI-Prolog: - -+ @subpage chr - -+ @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 -compatible with the ISO-Prolog standard\cite x , and with Jan -Wielemaker's SWI-Prolog\cite x . - -SWI-Prolog and YAP have collaborated at improved compatibility \cite x . This -resulted in Prolog extensions such as the `dialect` feature. YAP -currently supports most of the SWI-Prolog foreign interface. The following SWI -libraries have worked on YAP: - - + @ref aggregate - + @ref base64 - + @ref broadcast - + @ref ctypes - + @ref date - + @ref prolog_debug - + @ref prolog_edit - + @ref error - + @ref nb_set - + @ref prolog_operator - + @ref swi_option - + @ref pairs - + @ref pio - + @ref predicate_options, - + @ref predopts - + @ref prolog_clause - + @ref prolog_colour - + @ref prolog_source - + @ref prolog_xref - + @ref pure_input - + @ref quasi_quotations - + @ref read_util - + @ref record - + @ref settings - + @ref shlib - + @ref thread_pool - + @ref url - + @ref utf8 - + @ref win_menu - + @ref www_browser - - -Note that in general SWI code may be from an earlier version than the -one available with SWI-Prolog. SWI-Prolog are obviously not -responsible for any incompatibilities and/or bugs in the YAP port. - -Please do refer to the SWI-Prolog home page: - - - -for more information on SWI-Prolog and the SWI packages. - -Compatibility with the C-Prolog interpreter {#ChYProlog} -------------------------------------------- - -YAP was designed so that most C-Prolog programs should run under YAP -without changes. -The most important difference between YAP and C-Prolog is that, being -YAP a compiler, some changes should be made if predicates such as -assert/1, clause/1 and retract/1 are used. First -predicates which will change during execution should be declared as -`dynamic` by using commands like: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:- dynamic f/n. -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - where `f` is the predicate name and n is the arity of the -predicate. Note that several such predicates can be declared in a -single command: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - :- dynamic f/2, ..., g/1. -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Primitive predicates such as `retract` apply only to dynamic -predicates. Finally note that not all the C-Prolog primitive predicates -are implemented in YAP. They can easily be detected using the -`unknown` system predicate provided by YAP. - -Last, by default YAP enables character escapes in strings. You can -disable the special interpretation for the escape character by using: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:- yap_flag(character_escapes,off). -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -or by using: - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:- yap_flag(language,cprolog). -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - -Compatibility with the Quintus and SICStus Prolog systems ---------------------------------------------------------- - -The Quintus Prolog system was the first Prolog compiler to use Warren's -Abstract Machine. This system was very influential in the Prolog -community. Quintus Prolog implemented compilation into an abstract -machine code, which was then emulated. Quintus Prolog also included -several new built-ins, an extensive library, and in later releases a -garbage collector. The SICStus Prolog system, developed at SICS (Swedish -Institute of Computer Science), is an emulator based Prolog system -largely compatible with Quintus Prolog. SICStus Prolog has evolved -through several versions. The current version includes several -extensions, such as an object implementation, co-routining, and -constraints. - -Both YAP and SICStus Prolog obey the Edinburgh Syntax and are based on -the WAM. Even so, there are major important differences: - - + Differently from SICStus Prolog, both consulted and dynamic code in YAP - are compiled, not interpreted. All code in YAP is compiled. - - + The following SICStus Prolog v3 built-ins are not (currently) -implemented in YAP (note that this is only a partial list): -stream_interrupt/3, reinitialize/0, help/0, help/1, -trimcore/0, and require/1. - - + The consult/1 predicate in YAP follows C-Prolog -semantics. That is, it adds clauses to the data base, even for -preexisting procedures. This is different from consult/1 in -SICStus Prolog or SWI-Prolog. - - + This list is incomplete. - -Compatibility with the ISO Prolog standard ------------------------------------------- - -The Prolog standard was developed by ISO/IEC JTC1/SC22/WG17, the -international standardization working group for the programming language -Prolog. The book "Prolog: The Standard" by Deransart, Ed-Dbali and -Cervoni gives a complete description of this standard. Development in -YAP from YAP4.1.6 onwards have striven at making YAP -compatible with ISO Prolog. As such: - - + YAP now supports all of the built-ins required by the -ISO-standard, and, - + Error-handling is as required by the standard. - - -YAP by default is not fully ISO standard compliant. You can set the -language flag to `iso` to obtain better -compatibility. Setting this flag changes the following: - - - + By default, YAP implements the -atom_chars/2 (see Testing Terms), and -number_chars/2, (see Testing Terms), -built-ins as per the original Quintus Prolog definition, and -not as per the ISO definition. - -Calling `set_prolog_flag(to_chars_mode,iso)` will switch -YAP to use the ISO definition for -atom_chars/2 and number_chars/2. - - + By default, YAP allows executable goals in directives. In ISO mode -most directives can only be called from top level (the exceptions are -set_prolog_flag/2 and op/3). - - + Error checking for meta-calls under ISO Prolog mode is stricter -than by default. - - + The strict_iso flag automatically enables the ISO Prolog -standard. This feature should disable all features not present in the -standard. - -The following incompatibilities between YAP and the ISO standard are -known to still exist (please check Ulrich Neumerkel's page for more details): - -
      - -
    • Currently, YAP does not handle overflow errors in integer -operations, and handles floating-point errors only in some -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. -This gives portability with a number of SWI-Prolog packages and avoids garnage collection by using @ref slotInterface. Last, a new C++ based interface is -being designed to work with the swig (www.swig.orgv) interface compiler. - -+ The @ref c-interface exports the YAP engine. - -+ The @ref swi-c-interface emulates Jan Wielemaker's SWI foreign language interface. - -+ 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/library/atts.yap b/library/atts.yap index 8fe204cf8..bdffdf880 100644 --- a/library/atts.yap +++ b/library/atts.yap @@ -17,13 +17,13 @@ :- module(attributes, [op(1150, fx, attribute)]). -%% @{ - /** @addtogroup attributes -SICStus style attribute declarations are activated through loading the +%% @{ + + SICStus style attribute declarations are activated through loading the library atts. The command ~~~~~ diff --git a/misc/PROLOGCOMMONS.md b/misc/PROLOGCOMMONS.md index 4af3410a9..470b3c5fd 100644 --- a/misc/PROLOGCOMMONS.md +++ b/misc/PROLOGCOMMONS.md @@ -1,3 +1,5 @@ +Prolog Commons {#prolog_comons} +============= This directory should hold files from the Prolog Commons project. Please see diff --git a/os/readterm.c b/os/readterm.c index 34c63ae62..96cc0604a 100644 --- a/os/readterm.c +++ b/os/readterm.c @@ -219,15 +219,15 @@ static Term syntax_error(TokEntry *errtok, int sno, Term cmod) { CACHE_REGS Term startline, errline, endline; Term tf[3]; - Term tm; + Term tm; Term *tailp = tf + 2; CELL *Hi = HR; TokEntry *tok = LOCAL_tokptr; Int cline = tok->TokPos; startline = MkIntegerTerm(cline); - endline = MkIntegerTerm(cline); - if (errtok != LOCAL_toktide) { + endline = MkIntegerTerm(cline); + if (errtok != LOCAL_toktide) { errtok = LOCAL_toktide; } LOCAL_Error_TYPE = YAP_NO_ERROR; @@ -254,7 +254,7 @@ static Term syntax_error(TokEntry *errtok, int sno, Term cmod) { *tailp = MkPairTerm(MkAtomTerm(AtomError), TermNil); tailp = RepPair(*tailp) + 1; } - Term rep = Yap_tokRep(tok ); + Term rep = Yap_tokRep(tok); if (tok->TokNext) { tok = tok->TokNext; } else { @@ -262,7 +262,7 @@ static Term syntax_error(TokEntry *errtok, int sno, Term cmod) { tok = NULL; break; } - *tailp = MkPairTerm(rep , TermNil); + *tailp = MkPairTerm(rep, TermNil); tailp = RepPair(*tailp) + 1; } { @@ -280,8 +280,8 @@ static Term syntax_error(TokEntry *errtok, int sno, Term cmod) { clean_vars(LOCAL_AnonVarTable); Term terr = Yap_MkApplTerm(FunctorInfo3, 3, tf); Term tn[2]; - tn[0] = Yap_MkApplTerm(FunctorShortSyntaxError, 1, &tm); - tn[1] = terr; + tn[0] = Yap_MkApplTerm(FunctorShortSyntaxError, 1, &tm); + tn[1] = terr; terr = Yap_MkApplTerm(FunctorError, 2, tn); #if DEBUG if (Yap_ExecutionMode == YAP_BOOT_MODE) { @@ -643,7 +643,7 @@ static parser_state_t scan(REnv *re, FEnv *fe, int inp_stream); static parser_state_t scanEOF(FEnv *fe, int inp_stream) { CACHE_REGS // bool store_comments = false; - TokEntry *tokstart = LOCAL_tokptr; + TokEntry *tokstart = LOCAL_tokptr; // check for an user abort if (tokstart != NULL && tokstart->Tok != Ord(eot_tok)) { /* we got the end of file from an abort */ @@ -730,24 +730,23 @@ static parser_state_t scan(REnv *re, FEnv *fe, int inp_stream) { TokEntry *t = LOCAL_tokptr; int n = 0; while (t) { - fprintf(stderr, "[Token %d %s %d]", - Ord(t->Tok),Yap_tokText(t), n++); + fprintf(stderr, "[Token %d %s %d]", Ord(t->Tok), Yap_tokText(t), n++); t = t->TokNext; } fprintf(stderr, "\n"); } #endif -if (LOCAL_ErrorMessage) - return YAP_SCANNING_ERROR; -if (LOCAL_tokptr->Tok != Ord(eot_tok)) { - // next step - return YAP_PARSING; -} -if (LOCAL_tokptr->Tok == eot_tok && LOCAL_tokptr->TokInfo == TermNl) { - LOCAL_Error_TYPE = SYNTAX_ERROR; - return YAP_PARSING_ERROR; -} -return scanEOF(fe, inp_stream); + if (LOCAL_ErrorMessage) + return YAP_SCANNING_ERROR; + if (LOCAL_tokptr->Tok != Ord(eot_tok)) { + // next step + return YAP_PARSING; + } + if (LOCAL_tokptr->Tok == eot_tok && LOCAL_tokptr->TokInfo == TermNl) { + LOCAL_Error_TYPE = SYNTAX_ERROR; + return YAP_PARSING_ERROR; + } + return scanEOF(fe, inp_stream); } static parser_state_t scanError(REnv *re, FEnv *fe, int inp_stream) { @@ -807,7 +806,7 @@ static parser_state_t parseError(REnv *re, FEnv *fe, int inp_stream) { } else { Term t = syntax_error(fe->toklast, inp_stream, fe->cmod); if (ParserErrorStyle == TermError) { - LOCAL_ActiveError->errorTerm = Yap_StoreTermInDB( t, 4); + LOCAL_ActiveError->errorTerm = Yap_StoreTermInDB(t, 4); LOCAL_Error_TYPE = SYNTAX_ERROR; // dec-10 } else if (Yap_PrintWarning(t)) { @@ -1081,6 +1080,47 @@ static Int read_clause( return out && Yap_unify(tf, out); } +/** + * start input for a meta-clause. Should obtain: + * - predicate name + * - predicate arity + * - address for 256 cluses. + * + * @param ARG1 input stream + * @param ARG2 Adress of predicate. + * @param ARG3 Term read. + * @return [description] + */ +#if 0 +static Int start_mega(USES_REGS1) { + int inp_stream; + Term out; + Term t3 = Deref(ARG3); + yhandle_t h = Yap_InitSlot(ARG2); + TokENtry *tok; + arity_t srity = 0; + /* needs to change LOCAL_output_stream for write */ + inp_stream = Yap_CheckTextStream(ARG1, Input_Stream_f, "read_exo/3"); + if (inp_stream < 0) + return false; + /* preserve value of H after scanning: otherwise we may lose strings + and floats */ + LOCAL_tokptr = LOCAL_toktide = + x Yap_tokenizer(GLOBAL_Stream + inp_stream, false, &tpos); + if (tokptr->Tok == Name_tok && (next = tokptr->TokNext) != NULL && + next->Tok == Ponctuation_tok && next->TokInfo == TermOpenBracket) { + bool start = true; + while((tokptr = next->TokNext)) { + + if (IsAtomOrIntTerm(t=*tp)) { + ip->opc = Yap_opcode(get_atom); + ip->y_u.x_c.c = t. + ip->y_u.x_c.x = tp++; /() c */ + } else if (IsAtomOrIntTerm(t=*tp)) { + (IsAtom(tok->Tokt)||IsIntTerm(XREGS+(i+1)))extra[arity] + ] +} +#endif /** * @pred source_location( - _File_ , _Line_ ) * @@ -1094,6 +1134,8 @@ static Int read_clause( * @param - _File_ * @param - _Line_ * + * + * * @note SWI-Prolog built-in. */ static Int source_location(USES_REGS1) { @@ -1215,15 +1257,15 @@ X_API Term Yap_StringToTerm(const char *s, size_t len, encoding_t *encp, CACHE_REGS Term bvar = MkVarTerm(), ctl; yhandle_t sl; - int lvl = push_text_stack(); + int lvl = push_text_stack(); if (len == 0) { Term rval = TermEof; if (rval && bindings) { *bindings = TermNil; } - pop_text_stack(lvl); - return rval; + pop_text_stack(lvl); + return rval; } if (bindings) { ctl = Yap_MkApplTerm(Yap_MkFunctor(AtomVariableNames, 1), 1, &bvar); @@ -1242,7 +1284,7 @@ X_API Term Yap_StringToTerm(const char *s, size_t len, encoding_t *encp, if (rval && bindings) { *bindings = Yap_PopHandle(sl); } - pop_text_stack(lvl); + pop_text_stack(lvl); return rval; } diff --git a/packages/bdd/README b/packages/bdd/bdd.md similarity index 67% rename from packages/bdd/README rename to packages/bdd/bdd.md index 2eb20f2cd..689c259ff 100644 --- a/packages/bdd/README +++ b/packages/bdd/bdd.md @@ -1,5 +1,7 @@ +Boolean Decision Making in YAP (#BDDs) +============================== -This is an experimental interface to BDD libraries. It is not as +This is an experimental interface to BDD libraries. It is not as sophisticated as simplecudd, but it should be fun to play around with bdds. It currently works with cudd only, although it should be possible to @@ -9,10 +11,7 @@ with cudd binaries. This works: - in fedora with standard package - in osx with hand-compiled and ports package -In ubuntu, you may want to install the fedora rpm, or just contact me -for instructions. - -Good Luck! - -Vitor +In ubuntu, you may want to install the fedora rpm, or just download the package from the original + and compile it. + . diff --git a/docs/chr.md b/packages/chr/chr.md similarity index 99% rename from docs/chr.md rename to packages/chr/chr.md index d736e988a..9a674a047 100644 --- a/docs/chr.md +++ b/packages/chr/chr.md @@ -1,8 +1,6 @@ - CHR: Constraint Handling Rules {#chr} ============================== -@ingroup packages This chapter is written by Tom Schrijvers, K.U. Leuven for the hProlog system. Adjusted by Jan Wielemaker to fit the SWI-Prolog documentation @@ -528,5 +526,3 @@ share one or more variables. Provide mode and type declarations to get more efficient program execution. Make sure to disable debug (`-nodebug`) and enable optimization (`-O`). - - diff --git a/packages/chr/chr.yap b/packages/chr/chr.yap index fc0854697..d302ad81f 100644 --- a/packages/chr/chr.yap +++ b/packages/chr/chr.yap @@ -1,538 +1,2 @@ -% -% chr.pl is generated automatically. -% This package is just here to work as a stub for YAP analysis. -% - -/** - -@defgroup CHR CHR: Constraint Handling Rules - -@ingroup swi - -This chapter is written by Tom Schrijvers, K.U. Leuven for the hProlog -system. Adjusted by Jan Wielemaker to fit the SWI-Prolog documentation -infrastructure and remove hProlog specific references. - -The CHR system of SWI-Prolog is the K.U.Leuven CHR system. The runtime -environment is written by Christian Holzbaur and Tom Schrijvers while the -compiler is written by Tom Schrijvers. Both are integrated with SWI-Prolog -and licenced under compatible conditions with permission from the authors. - -The main reference for SWI-Prolog's CHR system is: - -+ T. Schrijvers, and B. Demoen, The K.U.Leuven CHR System: Implementation and Application, First Workshop on Constraint Handling Rules: Selected -Contributions (Fruwirth, T. and Meister, M., eds.), pp. 1--5, 2004. - -# Introduction - -Constraint Handling Rules (CHR) is a committed-choice bottom-up language -embedded in Prolog. It is designed for writing constraint solvers and is -particularily useful for providing application-specific constraints. -It has been used in many kinds of applications, like scheduling, -model checking, abduction, type checking among many others. - -CHR has previously been implemented in other Prolog systems (SICStus, -Eclipse, Yap), Haskell and Java. This CHR system is based on the -compilation scheme and runtime environment of CHR in SICStus. - -In this documentation we restrict ourselves to giving a short overview -of CHR in general and mainly focus on elements specific to this -implementation. For a more thorough review of CHR we refer the reader to -[Freuhwirth:98]. More background on CHR can be found at the CHR web site. - -### Syntax and Semantics - -We present informally the syntax and semantics of CHR. - - -#### CHR Syntax - -The syntax of CHR rules in hProlog is the following: - -~~~~~ -rules --> rule, rules. -rules --> []. - -rule --> name, actual_rule, pragma, [atom(`.`)]. - -name --> atom, [atom(`@`)]. -name --> []. - -actual_rule --> simplification_rule. -actual_rule --> propagation_rule. -actual_rule --> simpagation_rule. - -simplification_rule --> constraints, [atom(`<=>`)], guard, body. -propagation_rule --> constraints, [atom(`==>`)], guard, body. -simpagation_rule --> constraints, [atom(`\`)], constraints, [atom(`<=>`)], - guard, body. - -constraints --> constraint, constraint_id. -constraints --> constraint, [atom(`,`)], constraints. - -constraint --> compound_term. - -constraint_id --> []. -constraint_id --> [atom(`#`)], variable. - -guard --> []. -guard --> goal, [atom(`|`)]. - -body --> goal. - -pragma --> []. -pragma --> [atom(`pragma`)], actual_pragmas. - -actual_pragmas --> actual_pragma. -actual_pragmas --> actual_pragma, [atom(`,`)], actual_pragmas. - -actual_pragma --> [atom(`passive(`)], variable, [atom(`)`)]. - -~~~~~ - -Additional syntax-related terminology: - -+ *head:* the constraints in an `actual_rule` before -the arrow (either `<=>` or `==>`) - - -#### Semantics Semantics - -In this subsection the operational semantics of CHR in Prolog are presented -informally. They do not differ essentially from other CHR systems. - -When a constraint is called, it is considered an active constraint and -the system will try to apply the rules to it. Rules are tried and executed -sequentially in the order they are written. - -A rule is conceptually tried for an active constraint in the following -way. The active constraint is matched with a constraint in the head of -the rule. If more constraints appear in the head they are looked for -among the suspended constraints, which are called passive constraints in -this context. If the necessary passive constraints can be found and all -match with the head of the rule and the guard of the rule succeeds, then -the rule is committed and the body of the rule executed. If not all the -necessary passive constraint can be found, the matching fails or the -guard fails, then the body is not executed and the process of trying and -executing simply continues with the following rules. If for a rule, -there are multiple constraints in the head, the active constraint will -try the rule sequentially multiple times, each time trying to match with -another constraint. - -This process ends either when the active constraint disappears, i.e. it -is removed by some rule, or after the last rule has been processed. In -the latter case the active constraint becomes suspended. - -A suspended constraint is eligible as a passive constraint for an active -constraint. The other way it may interact again with the rules, is when -a variable appearing in the constraint becomes bound to either a nonvariable -or another variable involved in one or more constraints. In that case the -constraint is triggered, i.e. it becomes an active constraint and all -the rules are tried. - -### Rules - -There are three different kinds of rules, each with their specific semantics: - -+ simplification -The simplification rule removes the constraints in its head and calls its body. - -+ propagation -The propagation rule calls its body exactly once for the constraints in -its head. - -+ simpagation -The simpagation rule removes the constraints in its head after the -`\` and then calls its body. It is an optimization of -simplification rules of the form: \[constraints_1, constraints_2 <=> -constraints_1, body \] Namely, in the simpagation form: - -~~~~~ -constraints1 \ constraints2 <=> body -~~~~~ - _constraints1_ -constraints are not called in the body. - - - -#### Rule Names - -Naming a rule is optional and has no semantical meaning. It only functions -as documentation for the programmer. - -### Pragmas - -The semantics of the pragmas are: - -+ passive(Identifier) -The constraint in the head of a rule _Identifier_ can only act as a -passive constraint in that rule. - - -Additional pragmas may be released in the future. - -### CHR_Options Options - -It is possible to specify options that apply to all the CHR rules in the module. -Options are specified with the `option/2` declaration: - -~~~~~ - option(Option,Value). -~~~~~ - -Available options are: - -+ check_guard_bindings -This option controls whether guards should be checked for illegal -variable bindings or not. Possible values for this option are -`on`, to enable the checks, and `off`, to disable the -checks. - -+ optimize -This is an experimental option controlling the degree of optimization. -Possible values are `full`, to enable all available -optimizations, and `off` (default), to disable all optimizations. -The default is derived from the SWI-Prolog flag `optimise`, where -`true` is mapped to `full`. Therefore the commandline -option `-O` provides full CHR optimization. -If optimization is enabled, debugging should be disabled. - -+ debug -This options enables or disables the possibility to debug the CHR code. -Possible values are `on` (default) and `off`. See -`debugging` for more details on debugging. The default is -derived from the prolog flag `generate_debug_info`, which -is `true` by default. See `-nodebug`. -If debugging is enabled, optimization should be disabled. - -+ mode -This option specifies the mode for a particular constraint. The -value is a term with functor and arity equal to that of a constraint. -The arguments can be one of `-`, `+` or `?`. -The latter is the default. The meaning is the following: - -+ - -The corresponding argument of every occurrence -of the constraint is always unbound. -+ + -The corresponding argument of every occurrence -of the constraint is always ground. -+ ? -The corresponding argument of every occurrence -of the constraint can have any instantiation, which may change -over time. This is the default value. - -The declaration is used by the compiler for various optimizations. -Note that it is up to the user the ensure that the mode declaration -is correct with respect to the use of the constraint. -This option may occur once for each constraint. - -+ type_declaration -This option specifies the argument types for a particular constraint. The -value is a term with functor and arity equal to that of a constraint. -The arguments can be a user-defined type or one of -the built-in types: - -+ int -The corresponding argument of every occurrence -of the constraint is an integer number. -+ float -...{} a floating point number. -+ number -...{} a number. -+ natural -...{} a positive integer. -+ any -The corresponding argument of every occurrence -of the constraint can have any type. This is the default value. - - -Currently, type declarations are only used to improve certain -optimizations (guard simplification, occurrence subsumption, ...{}). - -+ type_definition -This option defines a new user-defined type which can be used in -type declarations. The value is a term of the form -`type(` _name_`,` _list_`)`, where - _name_ is a term and _list_ is a list of alternatives. -Variables can be used to define generic types. Recursive definitions -are allowed. Examples are - -~~~~~ -type(bool,[true,false]). -type(complex_number,[float + float * i]). -type(binary_tree(T),[ leaf(T) | node(binary_tree(T),binary_tree(T)) ]). -type(list(T),[ [] | [T | list(T)]). -~~~~~ - - - -The mode, type_declaration and type_definition options are provided -for backward compatibility. The new syntax is described below. - - - -### CHR in Prolog Programs - - -The CHR constraints defined in a particulary chr file are -associated with a module. The default module is `user`. One should -never load different chr files with the same CHR module name. - - - -#### Constraint Declarations - - -Every constraint used in CHR rules has to be declared. -There are two ways to do this. The old style is as follows: - -~~~~~ -option(type_definition,type(list(T),[ [] , [T|list(T)] ]). -option(mode,foo(+,?)). -option(type_declaration,foo(list(int),float)). -:- constraints foo/2, bar/0. -~~~~~ - -The new style is as follows: - -~~~~~ -:- chr_type list(T) ---> [] ; [T|list(T)]. -:- constraints foo(+list(int),?float), bar. -~~~~~ - - - -#### Compilation - -The - SWI-Prolog CHR compiler exploits term_expansion/2 rules to translate -the constraint handling rules to plain Prolog. These rules are loaded -from the library chr. They are activated if the compiled file -has the chr extension or after finding a declaration of the -format below. - -~~~~~ -:- constraints ... -~~~~~ - -It is adviced to define CHR rules in a module file, where the module -declaration is immediately followed by including the chr -library as examplified below: - -~~~~~ -:- module(zebra, [ zebra/0 ]). -:- use_module(library(chr)). - -:- constraints ... -~~~~~ - -Using this style CHR rules can be defined in ordinary Prolog -pl files and the operator definitions required by CHR do not -leak into modules where they might cause conflicts. - - - - - -#### CHR Debugging - -The CHR debugging facilities are currently rather limited. Only tracing -is currently available. To use the CHR debugging facilities for a CHR -file it must be compiled for debugging. Generating debug info is -controlled by the CHR option debug, whose default is derived -from the SWI-Prolog flag `generate_debug_info`. Therefore debug -info is provided unless the `-nodebug` is used. - -#### Ports - -For CHR constraints the four standard ports are defined: - -+ call -A new constraint is called and becomes active. -+ exit -An active constraint exits: it has either been inserted in the store after -trying all rules or has been removed from the constraint store. -+ fail -An active constraint fails. -+ redo -An active constraint starts looking for an alternative solution. - - -In addition to the above ports, CHR constraints have five additional -ports: - -+ wake -A suspended constraint is woken and becomes active. -+ insert -An active constraint has tried all rules and is suspended in -the constraint store. -+ remove -An active or passive constraint is removed from the constraint -store, if it had been inserted. -+ try -An active constraints tries a rule with possibly -some passive constraints. The try port is entered -just before committing to the rule. -+ apply -An active constraints commits to a rule with possibly -some passive constraints. The apply port is entered -just after committing to the rule. - -#### Tracing - -Tracing is enabled with the chr_trace/0 predicate -and disabled with the chr_notrace/0 predicate. - -When enabled the tracer will step through the `call`, -`exit`, `fail`, `wake` and `apply` ports, -accepting debug commands, and simply write out the other ports. - -The following debug commans are currently supported: - -~~~~~ - CHR debug options: - - creep c creep - s skip - g ancestors - n nodebug - b break - a abort - f fail - ? help h help -~~~~~ - -Their meaning is: - -+ creep -Step to the next port. -+ skip -Skip to exit port of this call or wake port. -+ ancestors -Print list of ancestor call and wake ports. -+ nodebug -Disable the tracer. -+ break -Enter a recursive Prolog toplevel. See break/0. -+ abort -Exit to the toplevel. See abort/0. -+ fail -Insert failure in execution. -+ help -Print the above available debug options. - - -#### CHR Debugging Predicates - - -The chr module contains several predicates that allow -inspecting and printing the content of the constraint store. - -+ chr_trace -Activate the CHR tracer. By default the CHR tracer is activated and -deactivated automatically by the Prolog predicates trace/0 and -notrace/0. - -### CHR_Examples Examples - -Here are two example constraint solvers written in CHR. - -+ -The program below defines a solver with one constraint, -`leq/2`, which is a less-than-or-equal constraint. - -~~~~~ -:- module(leq,[cycle/3, leq/2]). -:- use_module(library(chr)). - -:- constraints leq/2. -reflexivity @ leq(X,X) <=> true. -antisymmetry @ leq(X,Y), leq(Y,X) <=> X = Y. -idempotence @ leq(X,Y) \ leq(X,Y) <=> true. -transitivity @ leq(X,Y), leq(Y,Z) ==> leq(X,Z). - -cycle(X,Y,Z):- - leq(X,Y), - leq(Y,Z), - leq(Z,X). -~~~~~ - -+ -The program below implements a simple finite domain -constraint solver. - -~~~~~ -:- module(dom,[dom/2]). -:- use_module(library(chr)). - -:- constraints dom/2. - -dom(X,[]) <=> fail. -dom(X,[Y]) <=> X = Y. -dom(X,L1), dom(X,L2) <=> intersection(L1,L2,L3), dom(X,L3). - -intersection([],_,[]). -intersection([H|T],L2,[H|L3]) :- - member(H,L2), !, - intersection(T,L2,L3). -intersection([_|T],L2,L3) :- - intersection(T,L2,L3). -~~~~~ - - - -### Compatibility with SICStus CHR - - -There are small differences between CHR in SWI-Prolog and newer -YAPs and SICStus and older versions of YAP. Besides differences in -available options and pragmas, the following differences should be -noted: - -+ [The handler/1 declaration] -In SICStus every CHR module requires a `handler/1` -declaration declaring a unique handler name. This declaration is valid -syntax in SWI-Prolog, but will have no effect. A warning will be given -during compilation. - -+ [The rules/1 declaration] -In SICStus, for every CHR module it is possible to only enable a subset -of the available rules through the `rules/1` declaration. The -declaration is valid syntax in SWI-Prolog, but has no effect. A -warning is given during compilation. - -+ [Sourcefile naming] -SICStus uses a two-step compiler, where chr files are -first translated into pl files. For SWI-Prolog CHR -rules may be defined in a file with any extension. - -### Guidelines - -In this section we cover several guidelines on how to use CHR to write -constraint solvers and how to do so efficiently. - -+ [Set semantics] -The CHR system allows the presence of identical constraints, i.e. -multiple constraints with the same functor, arity and arguments. For -most constraint solvers, this is not desirable: it affects efficiency -and possibly termination. Hence appropriate simpagation rules should be -added of the form: - -~~~~~ -{constraint \ constraint <=> true}. -~~~~~ - -+ [Multi-headed rules] -Multi-headed rules are executed more efficiently when the constraints -share one or more variables. - -+ [Mode and type declarations] -Provide mode and type declarations to get more efficient program execution. -Make sure to disable debug (`-nodebug`) and enable optimization -(`-O`). - -*/ :- include(chr_op). - diff --git a/docs/clpqr.md b/packages/clpqr/clpqr.md similarity index 97% rename from docs/clpqr.md rename to packages/clpqr/clpqr.md index 073386784..db838adeb 100644 --- a/docs/clpqr.md +++ b/packages/clpqr/clpqr.md @@ -1,8 +1,6 @@ -Constraint Logic Programming over Rationals and Reals {#clpqr} + Constraint Logic Programming over Rationals and Reals {#clpqr} ===================================================== -@ingroup paackages - YAP now uses the CLP(R) package developed by Leslie De Koninck, K.U. Leuven as part of a thesis with supervisor Bart Demoen and daily advisor Tom Schrijvers, and distributed with SWI-Prolog. @@ -119,4 +117,3 @@ X = sin(Y) when X is ground or // 1 = sin(Y) X = cos(Y) Y is ground // X = sin(1.5707) X = tan(Y) ~~~~~ - diff --git a/packages/clpqr/clpr.pl b/packages/clpqr/clpr.pl index 1e9fb9b00..e065bb960 100644 --- a/packages/clpqr/clpr.pl +++ b/packages/clpqr/clpr.pl @@ -38,7 +38,10 @@ the GNU General Public License. */ - +/** @defgroup clpr_implementation CLP(QR) Predicates + @ingroup clpqr + + */ /** @pred bb_inf(+ _Ints_,+ _Expression_,- _Inf_) The same as bb_inf/5 but without returning the values of the integers diff --git a/packages/gecode/DOC.txt b/packages/gecode/gecode.md similarity index 91% rename from packages/gecode/DOC.txt rename to packages/gecode/gecode.md index 601934345..6c106f45a 100644 --- a/packages/gecode/DOC.txt +++ b/packages/gecode/gecode.md @@ -1,16 +1,24 @@ -USING THE GECODE MODULE +USING THE GECODE MODULE (#Gecode) ======================= +There are two ways to use the gecode interface from YAP. The original approach, +designed by Denys Duchier, requires loading the library: + :- use_module(library(gecode)). +A second approach is closer to CLP(FD), and is described in: + + - \ref Gecode_and_ClPbBFDbC + +In what follows, we refer the reader to the~\cite{gecode} manual for the necessary background. CREATING A SPACE -================ +---------------- Space := space CREATING VARIABLES -================== +----------------- Unlike in Gecode, variable objects are not bound to a specific Space. Each one actually contains an index with which it is possible to access a Space-bound @@ -49,7 +57,7 @@ kept. Thus marking variables as "kept" is purely an optimization. CONSTRAINTS AND BRANCHINGS -========================== +--------------------------- all constraint and branching posting functions are available just like in Gecode. Wherever a XXXArgs or YYYSharedArray is expected, simply use a list. @@ -68,7 +76,7 @@ represented by atoms with the same name as the Gecode constant (e.g. 'INT_VAR_SIZE_MIN'). SEARCHING FOR SOLUTIONS -======================= +-------------------- SolSpace := search(Space) @@ -90,7 +98,7 @@ a_d=N to set the adaptive distance for recomputation EXTRACTING INFO FROM A SOLUTION -=============================== +------------------------------ An advantage of non Space-bound variables, is that you can use them both to post constraints in the original space AND to consult their values in @@ -126,7 +134,7 @@ variables, and returns resp. either a value, or a list of values: Val := unknown_values(Space,V) DISJUNCTORS -=========== +----------- Disjunctors provide support for disjunctions of clauses, where each clause is a conjunction of constraints: diff --git a/packages/myddas/myddas.md b/packages/myddas/myddas.md new file mode 100644 index 000000000..056e514fa --- /dev/null +++ b/packages/myddas/myddas.md @@ -0,0 +1,574 @@ + The MYDDAS Data-base interface {#myddas} + ============================== + + The MYDDAS database project was developed within a FCT project aiming at + the development of a highly efficient deductive database system, based + on the coupling of the MySQL relational database system with the YAP + Prolog system. MYDDAS was later expanded to support the ODBC interface. + + + @defgroup Requirements_and_Installation_Guide Requirements and Installation Guide + ee + Next, we describe how to usen of the YAP with the MYDDAS System. The + use of this system is entirely depend of the MySQL development libraries + or the ODBC development libraries. At least one of the this development + libraries must be installed on the computer system, otherwise MYDDAS + will not compile. The MySQL development libraries from MySQL 3.23 an + above are know to work. We recommend the usage of MySQL versus ODBC, + but it is possible to have both options installed + + At the same time, without any problem. The MYDDAS system automatically + controls the two options. Currently, MYDDAS is know to compile without + problems in Linux. The usage of this system on Windows has not been + tested yet. MYDDAS must be enabled at configure time. This can be done + with the following options: + + + --enable-myddas + + This option will detect which development libraries are installed on the computer system, MySQL, ODBC or both, and will compile the Yap system with the support for which libraries it detects; + + + --enable-myddas-stats + + This option is only available in MySQL. It includes code to get + statistics from the MYDDAS system; + + + + --enable-top-level + + This option is only available in MySQL. It enables the option to interact with the MySQL server in + two different ways. As if we were on the MySQL Client Shell, and as if + we were using Datalog. + + @defgroup MYDDAS_Architecture MYDDAS Architecture + + The system includes four main blocks that are put together through the + MYDDAS interface: the Yap Prolog compiler, the MySQL database system, an + ODBC level and a Prolog to SQL compiler. Current effort is put on the + MySQL interface rather than on the ODBC interface. If you want to use + the full power of the MYDDAS interface we recommend you to use a MySQL + database. Other databases, such as Oracle, PostGres or Microsoft SQL + Server, can be interfaced through the ODBC layer, but with limited + performance and features support. + + The main structure of the MYDDAS interface is simple. Prolog queries + involving database goals are translated to SQL using the Prolog to SQL + compiler; then the SQL expression is sent to the database system, which + returns the set of tuples satisfying the query; and finally those tuples + are made available to the Prolog engine as terms. For recursive queries + involving database goals, the YapTab tabling engine provides the + necessary support for an efficient evaluation of such queries. + + An important aspect of the MYDDAS interface is that for the programmer + the use of predicates which are defined in database relations is + completely transparent. An example of this transparent support is the + Prolog cut operator, which has exactly the same behaviour from + predicates defined in the Prolog program source code, or from predicates + defined in database as relations. + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + Name = 'John Doe', + Number = 123456789 ? + yes + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Backtracking can then be used to retrieve the next row + of the relation phonebook. Records with particular field values may be + selected in the same way as in Prolog. (In particular, no mode + specification for database predicates is required). For instance: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ?- phonebook(Letter,'John Doe',Letter). + Letter = 'D', + Number = 123456789 ? + yes + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + generates the query + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + SELECT A.Letter , 'John Doe' , A.Number + FROM 'phonebook' A + WHERE A.Name = 'John Doe'; + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + + @defgroup View_Level_Interface View Level Interface + + @pred db view(+,+,+). + + + + @pred db view(+,+). + + + If we import a database relation, such as an edge relation representing the edges of a directed graph, through + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ?- db_import('Edge',edge). + yes + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + sqliand we then write a query to retrieve all the direct cycles in the + graph, such as + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ?- edge(A,B), edge(B,A). + A = 10, + B = 20 ? + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + this is clearly inefficient [3], because of relation-level + access. Relation-level access means that a separate SQL query will be + generated for every goal in the body of the clause. For the second + `edge/2` goal, a SQL query is generated using the variable bindings that + result from the first `edge/2` goal execution. If the second + `edge/2` goal + fails, or if alternative solutions are demanded, backtracking access the + next tuple for the first `edge/2` goal and another SQL query will be + generated for the second `edge/2` goal. The generation of this large + number of queries and the communication overhead with the database + system for each of them, makes the relation-level approach inefficient. + To solve this problem the view level interface can be used for the + definition of rules whose bodies includes only imported database + predicates. One can use the view level interface through the predicates + db_view/3 and `db_view/2`: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ?- db_view(Conn,PredName(Arg_1,...,Arg_n),DbGoal). + ?- db_view(PredName(Arg_1,...,Arg_n),DbGoal). + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + All arguments are standard Prolog terms. _Arg1_ through _Argn_ + define the attributes to be retrieved from the database, while + _DbGoal_ defines the selection restrictions and join + conditions. _Conn_ is the connection identifier, which again can be + dropped. Calling predicate `PredName/n` will retrieve database + tuples using a single SQL query generated for the _DbGoal_. We next show + an example of a view definition for the direct cycles discussed + above. Assuming the declaration: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ?- db_import('Edge',edge). + yes + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + we + write: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ?- db_view(direct_cycle(A,B),(edge(A,B), edge(B,A))). + yes + ?- direct_cycle(A,B)). + A = 10, + B = 20 ? + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + This call generates the SQL + statement: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + SELECT A.attr1 , A.attr2 + FROM Edge A , Edge B + WHERE B.attr1 = A.attr2 AND B.attr2 = A.attr1; + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + Backtracking, as in relational level interface, can be used to retrieve the next row of the view. + The view interface also supports aggregate function predicates such as + `sum`, `avg`, `count`, `min` and `max`. For + instance: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ?- db_view(count(X),(X is count(B, B^edge(10,B)))). + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + generates the query : + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + SELECT COUNT(A.attr2) + FROM Edge A WHERE A.attr1 = 10; + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + To know how to use db `view/3`, please refer to Draxler's Prolog to + SQL Compiler Manual. + + @defgroup Accessing_Tables_in_Data_Sources_Using_SQL Accessing Tables in Data Sources Using SQL + + + @pred db_sql(+,+,?). + + + + @pred db_sql(+,?). + + + + It is also possible to explicitly send a SQL query to the database server using + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ?- db_sql(Conn,SQL,List). + ?- db_sql(SQL,List). + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + where _SQL_ is an arbitrary SQL expression, and _List_ is a list + holding the first tuple of result set returned by the server. The result + set can also be navigated through backtracking. + + Example: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ?- db_sql('SELECT * FROM phonebook',LA). + LA = ['D','John Doe',123456789] ? + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +@defgroup Insertion_of_Rows Insertion of Rows + @ingroup MYDDAS + + @pred db_assert(+,+). + @pred db_assert(+). + + + + + Assuming you have imported the related base table using + `db_import/2` or db_import/3, you can insert to that table + by using db_assert/2 predicate any given fact. + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ?- db_assert(Conn,Fact). + ?- db_assert(Fact). + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + The second argument must be declared with all of its arguments bound to + constants. For example assuming `helloWorld` is imported through + `db_import/2`: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ?- db_import('Hello World',helloWorld). + yes + ?- db_assert(helloWorld('A' ,'Ana',31)). + yes + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + This, would generate the following query + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + INSERT INTO helloWorld + VALUES ('A','Ana',3) + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + which would insert into the helloWorld, the following row: + `A,Ana,31`. If we want to insert `NULL` values into the + relation, we call db_assert/2 with a uninstantiated variable in + the data base imported predicate. For example, the following query on + the YAP-prolog system: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ?- db_assert(helloWorld('A',NULL,31)). + yes + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + Would insert the row: `A,null value,31` into the relation + `Hello World`, assuming that the second row allows null values. + +*/ + +/** @pred db insert(+,+,+). + @pred db insert(+,+). + + + + This predicate would create a new database predicate, which will insert + any given tuple into the database. + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ?- db_insert(Conn,RelationName,PredName). + ?- db_insert(RelationName,PredName). + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + This would create a new predicate with name _PredName_, that will + insert tuples into the relation _RelationName_. is the connection + identifier. For example, if we wanted to insert the new tuple + `('A',null,31)` into the relation `Hello World`, we do: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ?- db_insert('Hello World',helloWorldInsert). + yes + ?- helloWorldInsert('A',NULL,31). + yes + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +@defgroup Types_of_Attributes Types of AttributesL + + + @pred db_get_attributes_types(+,+,?). + + + + @pred db_get_attributes_types(+,?). + + + + + The prototype for this predicate is the following: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ?- db_get_attributes_types(Conn,RelationName,ListOfFields). + ?- db_get_attributes_types(RelationName,ListOfFields). + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + You can use the + predicate `db_get_attributes types/2` or db_get_attributes_types/3, to + know what are the names and attributes types of the fields of a given + relation. For example: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ?- db_get_attributes_types(myddas,'Hello World',LA). + LA = ['Number',integer,'Name',string,'Letter',string] ? + yes + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + where Hello World is the name of the relation and myddas is the + connection identifier. + + @defgroup Number_of_Fields Number of Fields + + + @pred db_number_of_fields(+,?). + @pred db_number_of_fields(+,+,?). + + + + The prototype for this + predicate is the following: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ?- db_number_of_fields(Conn,RelationName,Arity). + ?- db_number_of_fields(RelationName,Arity). + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + You can use the predicate db_number_of_fields/2 or + `db_number_of_fields/3` to know what is the arity of a given + relation. Example: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ?- db_number_of_fields(myddas,'Hello World',Arity). + Arity = 3 ? + yes + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + where `Hello World` is the name of the + relation and `myddas` is the connection identifier. + + @defgroup Describing_a_Relation Describing a Relation + + @pred db_datalog_describe(+,+). + @pred db_datalog_describe(+). + + + + The db `datalog_describe/2` predicate does not really returns any + value. It simply prints to the screen the result of the MySQL describe + command, the same way as `DESCRIBE` in the MySQL prompt would. + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ?- db_datalog_describe(myddas,'Hello World'). + +----------+----------+------+-----+---------+-------+ + | Field | Type | Null | Key | Default | Extra | + +----------+----------+------+-----+---------+-------+ + + Number | int(11) | YES | | NULL | | + + Name | char(10) | YES | | NULL | | + + Letter | char(1) | YES | | NULL | | + +----------+----------+------+-----+---------+-------+ + yes + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + @pred db_describe(+,+). + + + + @pred db_describe(+) + + The `db_describe/3` predicate does the same action as + db_datalog_describe/2 predicate but with one major + difference. The results are returned by backtracking. For example, the + last query: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ?- db_describe(myddas,'Hello World',Term). + Term = tableInfo('Number',int(11),'YES','',null(0),'') ? ; + Term = tableInfo('Name',char(10),'YES','',null(1),'' ? ; + Term = tableInfo('Letter',char(1),'YES','',null(2),'') ? ; + no + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + @defgroup Enumerating_Relations Enumeration Relations Describing_a_Relation Describing a Relation + + +/@pred db_datalog_show_tables(+). + @pred db_datalog_show_tables + + + If we need to know what relations exists in a given MySQL Schema, we can use + the `db_datalog_show_tables/1` predicate. As db_datalog_describe/2, + it does not returns any value, but instead prints to the screen the result of the + `SHOW TABLES` command, the same way as it would be in the MySQL prompt. + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ?- db_datalog_show_tables(myddas). + +-----------------+ + | Tables_in_guest | + +-----------------+ + | Hello World | + +-----------------+ + yes + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + @pred db_show_tables(+, ?). + + + + @pred db_show_tables(?) + + + + + The db_show_tables/2 predicate does the same action as + `db_show_tables/1` predicate but with one major difference. The + results are returned by backtracking. For example, given the last query: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ?- db_show_tables(myddas,Table). + Table = table('Hello World') ? ; + no + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + @defgroup The_MYDDAS_MySQL_Top_Level The MYDDAS MySQL Top Level + + @pred db_top_level(+,+,+,+,+). + @pred db_top_level(+,+,+,+). + + + + + Through MYDDAS is also possible to access the MySQL Database Server, in + the same wthe mysql client. In this mode, is possible to query the + SQL server by just using the standard SQL language. This mode is exactly the same as + different from the standard mysql client. We can use this + mode, by invoking the db top level/5. as one of the following: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ?- db_top_level(mysql,Connection,Host/Database,User,Password). + ?- db_top_level(mysql,Connection,Host/Database/Port,User,Password). + ?- db_top_level(mysql,Connection,Host/Database/UnixSocket,User,Password). + ?- db_top_level(mysql,Connection,Host/Database/Port/UnixSocket,User,Password). + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + Usage is similar as the one described for the db_open/5 predicate + discussed above. If the login is successful, automatically the prompt of + the mysql client will be used. For example: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ?- db_top_level(mysql,con1,localhost/guest_db,guest,''). + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + opens a + connection identified by the `con1` atom, to an instance of a MySQL server + running on host `localhost`, using database guest `db` and user `guest` with + empty password. After this is possible to use MYDDAS as the mysql + client. + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ?- db_top_level(mysql,con1,localhost/guest_db,guest,''). + Reading table information for completion of table and column names + You can turn off this feature to get a quicker startup with -A + + Welcome to the MySQL monitor. + Commands end with ; or \g. + + Your MySQL connection id is 4468 to server version: 4.0.20 + Type 'help;' or '\h' for help. + Type '\c' to clear the buffer. + mysql> exit + Bye + yes + ?- + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + @defgroup Other_MYDDAS_Properties Other MYDDAS Properties + + @pred db_verbose(+). + + + When we ask a question to YAP, using a predicate asserted by + db_import/3, or by db_view/3, this will generate a SQL + `QUERY`. If we want to see that query, we must to this at a given + point in our session on YAP. + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ?- db_verbose(1). + yes + ?- + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + If we want to + disable this feature, we must call the `db_verbose/1` predicate with the value 0. + + @pred db_top_level(+,+,+,+). + + @pred db_module(?). + + + + + + When we create a new database predicate, by using db_import/3, + db_view/3 or db_insert/3, that predicate will be asserted + by default on the `user` module. If we want to change this value, we can + use the db_module/1 predicate to do so. + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ?- db_module(lists). + yes + ?- + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + By executing this predicate, all of the predicates asserted by the + predicates enumerated earlier will created in the lists module. + If we want to put back the value on default, we can manually put the + value user. Example: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ?- db_module(user). + yes + ?- + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + We can also see in what module the predicates are being asserted by doing: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ?- db_module(X). + X=user + yes + ?- + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + @pred db_my_result_set(?). + + The MySQL C API permits two modes for transferring the data generated by + a query to the client, in our case YAP. The first mode, and the default + mode used by the MYDDAS-MySQL, is to store the result. This mode copies all the + information generated to the client side. + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ?- db_my_result_set(X). + X=store_result + yes + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + The other mode that we can use is use result. This one uses the result + set created directly from the server. If we want to use this mode, he + simply do + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ?- db_my_result_set(use_result). + yes + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + After this command, all + of the database predicates will use use result by default. We can change + this by doing again `db_my_result_set(store_result)`. + + @pred db_my_sql_mode(+Conn,?SQL_Mode). + + + + @pred db_my_sql_mode(?SQL_Mode). + + + + + The MySQL server allows the user to change the SQL mode. This can be + very useful for debugging proposes. For example, if we want MySQL server + not to ignore the INSERT statement warnings and instead of taking + action, report an error, we could use the following SQL mode. + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ?-db_my_sql_mode(traditional). yes + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + You can see the available SQL Modes at the MySQL homepage at + . diff --git a/packages/myddas/pl/myddas.ypp b/packages/myddas/pl/myddas.ypp index 54019eabd..3d9a271c4 100644 --- a/packages/myddas/pl/myddas.ypp +++ b/packages/myddas/pl/myddas.ypp @@ -104,685 +104,6 @@ ]). -/** - - @defgroup MYDDAS The MYDDAS Data-base interface. - @ingroup YAPPackages - @{ - - The MYDDAS database project was developed within a FCT project aiming at - the development of a highly efficient deductive database system, based - on the coupling of the MySQL relational database system with the YAP - Prolog system. MYDDAS was later expanded to support the ODBC interface. - -*/ - -/** @defgroup Requirements_and_Installation_Guide Requirements and Installation Guide - ee - Next, we describe how to usen of the YAP with the MYDDAS System. The - use of this system is entirely depend of the MySQL development libraries - or the ODBC development libraries. At least one of the this development - libraries must be installed on the computer system, otherwise MYDDAS - will not compile. The MySQL development libraries from MySQL 3.23 an - above are know to work. We recommend the usage of MySQL versus ODBC, - but it is possible to have both options installed - - At the same time, without any problem. The MYDDAS system automatically - controls the two options. Currently, MYDDAS is know to compile without - problems in Linux. The usage of this system on Windows has not been - tested yet. MYDDAS must be enabled at configure time. This can be done - with the following options: - - + --enable-myddas - - This option will detect which development libraries are installed on the computer system, MySQL, ODBC or both, and will compile the Yap system with the support for which libraries it detects; - - + --enable-myddas-stats - - This option is only available in MySQL. It includes code to get - statistics from the MYDDAS system; - - - + --enable-top-level - - This option is only available in MySQL. It enables the option to interact with the MySQL server in - two different ways. As if we were on the MySQL Client Shell, and as if - we were using Datalog. - -*/ - -%% @} - -/** @defgroup MYDDAS_Architecture MYDDAS Architecture - @ingroup MYDDAS - @{ - - The system includes four main blocks that are put together through the - MYDDAS interface: the Yap Prolog compiler, the MySQL database system, an - ODBC level and a Prolog to SQL compiler. Current effort is put on the - MySQL interface rather than on the ODBC interface. If you want to use - the full power of the MYDDAS interface we recommend you to use a MySQL - database. Other databases, such as Oracle, PostGres or Microsoft SQL - Server, can be interfaced through the ODBC layer, but with limited - performance and features support. - - The main structure of the MYDDAS interface is simple. Prolog queries - involving database goals are translated to SQL using the Prolog to SQL - compiler; then the SQL expression is sent to the database system, which - returns the set of tuples satisfying the query; and finally those tuples - are made available to the Prolog engine as terms. For recursive queries - involving database goals, the YapTab tabling engine provides the - necessary support for an efficient evaluation of such queries. - - An important aspect of the MYDDAS interface is that for the programmer - the use of predicates which are defined in database relations is - completely transparent. An example of this transparent support is the - Prolog cut operator, which has exactly the same behaviour from - predicates defined in the Prolog program source code, or from predicates - defined in database as relations. - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - Name = 'John Doe', - Number = 123456789 ? - yes - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Backtracking can then be used to retrieve the next row - of the relation phonebook. Records with particular field values may be - selected in the same way as in Prolog. (In particular, no mode - specification for database predicates is required). For instance: - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ?- phonebook(Letter,'John Doe',Letter). - Letter = 'D', - Number = 123456789 ? - yes - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - generates the query - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - SELECT A.Letter , 'John Doe' , A.Number - FROM 'phonebook' A - WHERE A.Name = 'John Doe'; - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -*/ - -%% @} - - -/** @defgroup View_Level_Interface View Level Interface - @ingroup MYDDAS - @{ - -*/ - -/** - @pred db view(+,+,+). - - - - @pred db view(+,+). - - - If we import a database relation, such as an edge relation representing the edges of a directed graph, through - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ?- db_import('Edge',edge). - yes - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - sqliand we then write a query to retrieve all the direct cycles in the - graph, such as - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ?- edge(A,B), edge(B,A). - A = 10, - B = 20 ? - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - this is clearly inefficient [3], because of relation-level - access. Relation-level access means that a separate SQL query will be - generated for every goal in the body of the clause. For the second - `edge/2` goal, a SQL query is generated using the variable bindings that - result from the first `edge/2` goal execution. If the second - `edge/2` goal - fails, or if alternative solutions are demanded, backtracking access the - next tuple for the first `edge/2` goal and another SQL query will be - generated for the second `edge/2` goal. The generation of this large - number of queries and the communication overhead with the database - system for each of them, makes the relation-level approach inefficient. - To solve this problem the view level interface can be used for the - definition of rules whose bodies includes only imported database - predicates. One can use the view level interface through the predicates - db_view/3 and `db_view/2`: - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ?- db_view(Conn,PredName(Arg_1,...,Arg_n),DbGoal). - ?- db_view(PredName(Arg_1,...,Arg_n),DbGoal). - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - All arguments are standard Prolog terms. _Arg1_ through _Argn_ - define the attributes to be retrieved from the database, while - _DbGoal_ defines the selection restrictions and join - conditions. _Conn_ is the connection identifier, which again can be - dropped. Calling predicate `PredName/n` will retrieve database - tuples using a single SQL query generated for the _DbGoal_. We next show - an example of a view definition for the direct cycles discussed - above. Assuming the declaration: - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ?- db_import('Edge',edge). - yes - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - we - write: - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ?- db_view(direct_cycle(A,B),(edge(A,B), edge(B,A))). - yes - ?- direct_cycle(A,B)). - A = 10, - B = 20 ? - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - This call generates the SQL - statement: - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - SELECT A.attr1 , A.attr2 - FROM Edge A , Edge B - WHERE B.attr1 = A.attr2 AND B.attr2 = A.attr1; - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - Backtracking, as in relational level interface, can be used to retrieve the next row of the view. - The view interface also supports aggregate function predicates such as - `sum`, `avg`, `count`, `min` and `max`. For - instance: - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ?- db_view(count(X),(X is count(B, B^edge(10,B)))). - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - generates the query : - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - SELECT COUNT(A.attr2) - FROM Edge A WHERE A.attr1 = 10; - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - To know how to use db `view/3`, please refer to Draxler's Prolog to - SQL Compiler Manual. - -*/ - -%% @} - -/** @defgroup Accessing_Tables_in_Data_Sources_Using_SQL Accessing Tables in Data Sources Using SQL - @ingroup MYDDAS - @{ - -*/ - -/** @pred db_sql(+,+,?). - - - - @pred db_sql(+,?). - - - - It is also possible to explicitly send a SQL query to the database server using - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ?- db_sql(Conn,SQL,List). - ?- db_sql(SQL,List). - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - where _SQL_ is an arbitrary SQL expression, and _List_ is a list - holding the first tuple of result set returned by the server. The result - set can also be navigated through backtracking. - - Example: - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ?- db_sql('SELECT * FROM phonebook',LA). - LA = ['D','John Doe',123456789] ? - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -*/ - -%% @} - -/** @defgroup Insertion_of_Rows Insertion of Rows - @ingroup MYDDAS - @{ - -*/ - -/** @pred db_assert(+,+). - @pred db_assert(+). - - - - - Assuming you have imported the related base table using - `db_import/2` or db_import/3, you can insert to that table - by using db_assert/2 predicate any given fact. - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ?- db_assert(Conn,Fact). - ?- db_assert(Fact). - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - The second argument must be declared with all of its arguments bound to - constants. For example assuming `helloWorld` is imported through - `db_import/2`: - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ?- db_import('Hello World',helloWorld). - yes - ?- db_assert(helloWorld('A' ,'Ana',31)). - yes - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - This, would generate the following query - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - INSERT INTO helloWorld - VALUES ('A','Ana',3) - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - which would insert into the helloWorld, the following row: - `A,Ana,31`. If we want to insert `NULL` values into the - relation, we call db_assert/2 with a uninstantiated variable in - the data base imported predicate. For example, the following query on - the YAP-prolog system: - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ?- db_assert(helloWorld('A',NULL,31)). - yes - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - Would insert the row: `A,null value,31` into the relation - `Hello World`, assuming that the second row allows null values. - -*/ - -/** @pred db insert(+,+,+). - @pred db insert(+,+). - - - - This predicate would create a new database predicate, which will insert - any given tuple into the database. - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ?- db_insert(Conn,RelationName,PredName). - ?- db_insert(RelationName,PredName). - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - This would create a new predicate with name _PredName_, that will - insert tuples into the relation _RelationName_. is the connection - identifier. For example, if we wanted to insert the new tuple - `('A',null,31)` into the relation `Hello World`, we do: - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ?- db_insert('Hello World',helloWorldInsert). - yes - ?- helloWorldInsert('A',NULL,31). - yes - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -*/ - -%% @} - -/** @defgroup Types_of_Attributes Types of AttributesL - @ingroup MYDDAS - @{ - -*/ - -/** @pred db_get_attributes_types(+,+,?). - - - - @pred db_get_attributes_types(+,?). - - - - - The prototype for this predicate is the following: - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ?- db_get_attributes_types(Conn,RelationName,ListOfFields). - ?- db_get_attributes_types(RelationName,ListOfFields). - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - You can use the - predicate `db_get_attributes types/2` or db_get_attributes_types/3, to - know what are the names and attributes types of the fields of a given - relation. For example: - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ?- db_get_attributes_types(myddas,'Hello World',LA). - LA = ['Number',integer,'Name',string,'Letter',string] ? - yes - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - where Hello World is the name of the relation and myddas is the - connection identifier. -*/ - -%% @} - - -/** @defgroup Number_of_Fields Number of Fields - @ingroup MYDDAS - @{ - -*/ - -/** @pred db_number_of_fields(+,?). - @pred db_number_of_fields(+,+,?). - - - - The prototype for this - predicate is the following: - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ?- db_number_of_fields(Conn,RelationName,Arity). - ?- db_number_of_fields(RelationName,Arity). - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - You can use the predicate db_number_of_fields/2 or - `db_number_of_fields/3` to know what is the arity of a given - relation. Example: - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ?- db_number_of_fields(myddas,'Hello World',Arity). - Arity = 3 ? - yes - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - where `Hello World` is the name of the - relation and `myddas` is the connection identifier. - - -*/ - -%% @} - - -/** @defgroup Describing_a_Relation Describing a Relation - @ingroup MYDDAS - @{ - -*/ - -/** @pred db_datalog_describe(+,+). - @pred db_datalog_describe(+). - - - - The db `datalog_describe/2` predicate does not really returns any - value. It simply prints to the screen the result of the MySQL describe - command, the same way as `DESCRIBE` in the MySQL prompt would. - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ?- db_datalog_describe(myddas,'Hello World'). - +----------+----------+------+-----+---------+-------+ - | Field | Type | Null | Key | Default | Extra | - +----------+----------+------+-----+---------+-------+ - + Number | int(11) | YES | | NULL | | - + Name | char(10) | YES | | NULL | | - + Letter | char(1) | YES | | NULL | | - +----------+----------+------+-----+---------+-------+ - yes - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -*/ - -/** @pred db_describe(+,+). - - - - @pred db_describe(+) - - The `db_describe/3` predicate does the same action as - db_datalog_describe/2 predicate but with one major - difference. The results are returned by backtracking. For example, the - last query: - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ?- db_describe(myddas,'Hello World',Term). - Term = tableInfo('Number',int(11),'YES','',null(0),'') ? ; - Term = tableInfo('Name',char(10),'YES','',null(1),'' ? ; - Term = tableInfo('Letter',char(1),'YES','',null(2),'') ? ; - no - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - -*/ -%% @} - - -/** @defgroup Enumerating_Relations Enumeration Relations Describing_a_Relation Describing a Relation - @ingroup MYDDAS - @{ - -*/ - -/** @pred db_datalog_show_tables(+). - @pred db_datalog_show_tables - - - If we need to know what relations exists in a given MySQL Schema, we can use - the `db_datalog_show_tables/1` predicate. As db_datalog_describe/2, - it does not returns any value, but instead prints to the screen the result of the - `SHOW TABLES` command, the same way as it would be in the MySQL prompt. - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ?- db_datalog_show_tables(myddas). - +-----------------+ - | Tables_in_guest | - +-----------------+ - | Hello World | - +-----------------+ - yes - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -*/ - -/** @pred db_show_tables(+, ?). - - - - @pred db_show_tables(?) - - - - - The db_show_tables/2 predicate does the same action as - `db_show_tables/1` predicate but with one major difference. The - results are returned by backtracking. For example, given the last query: - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ?- db_show_tables(myddas,Table). - Table = table('Hello World') ? ; - no - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -*/ - -%%@} - - -/** @defgroup The_MYDDAS_MySQL_Top_Level The MYDDAS MySQL Top Level - @ingroup MYDDAS - @{ - -*/ - -/** - @pred db_top_level(+,+,+,+,+). - @pred db_top_level(+,+,+,+). - - - - - Through MYDDAS is also possible to access the MySQL Database Server, in - the same wthe mysql client. In this mode, is possible to query the - SQL server by just using the standard SQL language. This mode is exactly the same as - different from the standard mysql client. We can use this - mode, by invoking the db top level/5. as one of the following: - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ?- db_top_level(mysql,Connection,Host/Database,User,Password). - ?- db_top_level(mysql,Connection,Host/Database/Port,User,Password). - ?- db_top_level(mysql,Connection,Host/Database/UnixSocket,User,Password). - ?- db_top_level(mysql,Connection,Host/Database/Port/UnixSocket,User,Password). - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - Usage is similar as the one described for the db_open/5 predicate - discussed above. If the login is successful, automatically the prompt of - the mysql client will be used. For example: - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ?- db_top_level(mysql,con1,localhost/guest_db,guest,''). - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - opens a - connection identified by the `con1` atom, to an instance of a MySQL server - running on host `localhost`, using database guest `db` and user `guest` with - empty password. After this is possible to use MYDDAS as the mysql - client. - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ?- db_top_level(mysql,con1,localhost/guest_db,guest,''). - Reading table information for completion of table and column names - You can turn off this feature to get a quicker startup with -A - - Welcome to the MySQL monitor. - Commands end with ; or \g. - - Your MySQL connection id is 4468 to server version: 4.0.20 - Type 'help;' or '\h' for help. - Type '\c' to clear the buffer. - mysql> exit - Bye - yes - ?- - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -*/ - -%%@} - - -/** @defgroup Other_MYDDAS_Properties Other MYDDAS Properties - @ingroup MYDDAS - @{ - -*/ - -/** - @pred db_verbose(+). - - - When we ask a question to YAP, using a predicate asserted by - db_import/3, or by db_view/3, this will generate a SQL - `QUERY`. If we want to see that query, we must to this at a given - point in our session on YAP. - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ?- db_verbose(1). - yes - ?- - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - If we want to - disable this feature, we must call the `db_verbose/1` predicate with the value 0. - \ -*/ - -/** - @pred db_top_level(+,+,+,+). - - -*/ - -/** @pred db_module(?). - - - - - - When we create a new database predicate, by using db_import/3, - db_view/3 or db_insert/3, that predicate will be asserted - by default on the `user` module. If we want to change this value, we can - use the db_module/1 predicate to do so. - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ?- db_module(lists). - yes - ?- - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - By executing this predicate, all of the predicates asserted by the - predicates enumerated earlier will created in the lists module. - If we want to put back the value on default, we can manually put the - value user. Example: - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ?- db_module(user). - yes - ?- - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - We can also see in what module the predicates are being asserted by doing: - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ?- db_module(X). - X=user - yes - ?- - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -*/ - -/** @pred db_my_result_set(?). - - The MySQL C API permits two modes for transferring the data generated by - a query to the client, in our case YAP. The first mode, and the default - mode used by the MYDDAS-MySQL, is to store the result. This mode copies all the - information generated to the client side. - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ?- db_my_result_set(X). - X=store_result - yes - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - The other mode that we can use is use result. This one uses the result - set created directly from the server. If we want to use this mode, he - simply do - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ?- db_my_result_set(use_result). - yes - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - After this command, all - of the database predicates will use use result by default. We can change - this by doing again `db_my_result_set(store_result)`. - -*/ - -/** @pred db_my_sql_mode(+Conn,?SQL_Mode). - - - - @pred db_my_sql_mode(?SQL_Mode). - - - - - The MySQL server allows the user to change the SQL mode. This can be - very useful for debugging proposes. For example, if we want MySQL server - not to ignore the INSERT statement warnings and instead of taking - action, report an error, we could use the following SQL mode. - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ?-db_my_sql_mode(traditional). yes - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - You can see the available SQL Modes at the MySQL homepage at - . - -*/ %% @} @@ -837,7 +158,7 @@ c_sqlite3_query/5, sqlite3_result_set/1, c_sqlite3_number_of_fields/3 - + ]). #endif /* MYDDAS_MYSQL */ @@ -1089,7 +410,7 @@ db_open(odbc,Connection,ODBCEntry,User,Password) :- set_value(Connection,Con). #endif #ifdef MYDDAS_SQLITE3 -db_open(sqlite3,Connection,File,User,Password) :- +db_open(sqlite3,Connection,File,User,Password) :- '$error_checks'(db_open(sqlite3,Connection,File,User,Password)), c_sqlite3_connect(File,User,Password,Con), set_value(Connection,Con). @@ -1456,7 +777,7 @@ db_update(Connection,WherePred-SetPred):- ( ConType == mysql -> db_my_result_set(Mode), c_db_my_query(SQL,_,Conn,Mode,_) - ; + ; ConType == mysql -> postgres_result_set(Mode), c_postgres_query(SQL,_,Conn,Mode,_) diff --git a/packages/raptor/README.md b/packages/raptor/README.md index affb558ce..cd3086a95 100644 --- a/packages/raptor/README.md +++ b/packages/raptor/README.md @@ -1,7 +1,5 @@ -@defgroup YAPRaptor An RDF Reader for YAP. -@ingroup YAPPackages - -#YAP raptor Interface +WWW Reader/Writers for YAP. (#YAPRaptor) +########################### This provides YAP a rdf reader using [raptor](http://librdf.org/raptor/). The library is available for @@ -21,3 +19,5 @@ Predicate = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#type', Subject = 'http://www.example.org/law_and_order_ci' ? ~~~~{.prolog} + +The code also includes a library under developent to connect Yap and libXML2. diff --git a/packages/real/README.md b/packages/real/README.md index 2f96c15de..129f44ce8 100644 --- a/packages/real/README.md +++ b/packages/real/README.md @@ -1,10 +1,228 @@ +The R Prolog Progrmming Interface (#real) +=================================== -Real ---- +@file real.pl +@author Nicos Angelopoulos +@author Vitor Santos Costa +@version 1:0:4, 2013/12/25, sinter_class +@license Perl Artistic License + @defgroup libReal An interface to the R statistical software. +@ingroup packages -Real is a c-based interface for connecting R to Prolog. -YAP introduces a development version of real, developed to experiment +This library enables the communication with an R process started as a shared library. +It is the result of the efforts of two research groups that have worked in parallel. +The syntactic emphasis on a minimalistic interface. + +In the doc/ directory of the distribution there is user's guide, a published paper +and html documentation from PlDoc (doc/html/real.html). There is large number +of examples in `examples/for_real.pl`. + +A single predicate (<-/2,<-/1) channels +the bulk of the interactions. In addition to using R as a shared library, real uses +the c-interfaces of SWI/Yap and R to pass objects in both directions. +The usual mode of operation is to load Prolog values on to R variables and then call +R functions on these values. The return value of the called function can be either placed +on R variable or passed back to Prolog. It has been tested extensively on current +SWI and YAP on Linux machines but it should also compile and work on MS operating systems and Macs. + +The main modes for utilising the interface are +~~~~ + <- +Rexpr + <- +Rvar +~~~~ + + Print Rvar or evaluate expression Rexpr in R +~~~~ + +Rvar <- +PLdata + +Rexpr <- +PLdata + -PLvar <- +Rvar + -PLvar <- +Rexpr + +Rexpr1 <- +Rexpr2 +~~~~ + +Pass Prolog data to R, pass R data to Prolog or assign an R expression to +an assignable R expression. + +@defgroup TestingR Testing Real + +There is a raft of examples packed in a singl```e file that test the library. + +~~~~ + ?- [pack(real/examples/for_real)]. + + ?- for_real. + + ?- edit( pack(real/examples/for_real) ). +~~~~ + +@defgroup RSyntax Prolog and R Syntax + +There are syntactic conventions in R that make unparsable prolog code. +Notably function and variable names are allowed to contain dots, square brackets are used +to access parts of vectors and arrays and functions are allowed empty argument tuples. +We have introduced relevant syntax which allows for easy transition between prolog and R. +Prolog constructs are converted by the library as follows: + + +* =|..|= within atoms -> =|.|= (ex. =| as..integer(c(1,2,3)) -> as.integer(c(1,2,3))|= ) +* =|^[]|= after atoms -> =|[]|= (ex. =|a^[2] -> a[2] |=) +* =|(.)|= at the end of atoms that are known R functions -> =|()|= (ex. =|dev..off(.) -> dev.off()|= ) +* =|[]|= -> c() (which equal to R's NULL value) +* ( f(x) :- (..)) -> f(x) (...) +* Lists of lists are converted to matrices. All first level lists must have the same length. +* Filenames must be given as Prolog strings. +* R specific operators (eg. %*% should be quoted in Prolog. +* + prepends strings, for (Prolog) atoms: +'String' +* Expressions that pose difficulty in translation can always be passed as unquoted Prolog atoms or strings. + ]]* since 0:1:2 foo() is valid syntax: =|<- dev..off() |= works now (with no need for dev..off(.)) + * since 0:1:2 mat[1] is valid syntax: =|m[1] <- 4|= works now (with no need for m^[...]) + +@defgroup RDataTransfer Mapping Data betweenn Prolog and R + +R vectors are mapped to prolog lists and matrices are mapped to nested lists. +The convention works the other way around too. + +There are two ways to pass prolog data to R. The more efficient one is by using +~~~~ + Rvar <- PLdata +~~~~ + +Where Pldata is one of the basic data types (number,boolean) a list or a c/n term. +This transfers via C data between R and Prolog. In what follows atomic PLval data +are simply considered as singleton lists. +Flat Pldata lists are translated to R vectors and lists of one level of nesting to R matrices +(which are 2 dimensional arrays in R parlance). The type of values of the vector or matrice is +taken to be the type of the first data element of the Pldata according to the following : + + * integer -> integer + * float -> double + * atom -> char + * boolean -> logical + +Booleans are represented in prolog as true/false atoms. +Currently arrays of aribtrary dimensions are not supported in the low-level interface. +Note that in R a scalar is just a one element vector. When passing non-scalars the +interface will assume the type of the object is that of the first scalar until it encounters +something different. +Real will currently re-start and repopulate partial integers for floats as illustrated +below: + +~~~~ +r <- [1,2,3]. % pass 1,2,3 to an R vector r +R <- r. % pass contents of R vector r to Prolog variable R +R = [1, 2, 3]. + +i <- [1,2,3.1]. % r is now a vector of floats, rather than integers +I <- i. +I = [1.0, 2.0, 3.1]. + + +~~~~ + +However, not all possible "corrections" are currently supported. For instance, + +~~~~ +?- c <- [a,b,c,1]. +ERROR: real:set_R_variable/2: Type error: `boolean' expected, found `a' +~~~~ + +In the data passing mode we map Prolog atoms to R strings- + +~~~~ +?- x <- [abc,def]. +true. + +?- <- x. +[1] "abc" "def" +true. + +?- X <- x. +X = [abc, def]. + +~~~~ + +In addition, Prolog data can be passed through the expression mechanism. +That is, data appearing in an arbitrary R expression will be parsed and be part of the long +string that will be passed from Prolog to R for evaluation. +This is only advisable for short data structures. For instance, + +~~~~ + tut_4a :- + state <- c(+"tas", +"sa", +"qld", +"nsw", +"nsw"), + <- state. + + tut_4b :- + state <- c(+tas, +sa, +qld, +nsw, +nsw), + <- state. +~~~~ + +Through this interface it is more convenient to be explicit about R chars by Prolog prepending +atoms or codes with + as in the above example. + +@defgroup RealExamples Examples + +~~~~ + +?- e <- numeric(.). +yes +?- e^[3] <- 17. +yes +?- e[3] <- 17. +yes +?- Z <- e. +Z = ['$NaN','$NaN',17.0] +?- e^[10] <- 12. +yes +?- Z <- e. +Z = ['$NaN','$NaN',17.0,'$NaN','$NaN','$NaN','$NaN','$NaN','$NaN',12.0] + +rtest :- + y <- rnorm(50), % get 50 random samples from normal distribution + <- y, % print the values via R + x <- rnorm(y), % get an equal number of normal samples + <- x11(width=5,height=3.5), % create a plotting window + <- plot(x,y) % plot the two samples + r_wait, % wait for user to hit Enter + % <- dev..off(.). % old syntax, still supported + <- dev.off(). % close the plotting window. foo() now acceptable in supported Prologs + +tut6 :- + d <- outer(0:9, 0:9), + fr <- table(outer(d, d, "-")), + <- plot(as..numeric(names(fr)), fr, type="h", xlab="Determinant", ylab="Frequency"). + +tut4b :- + state <- [tas,sa,qld,nsw,nsw,nt,wa], + statef <- factor(state), + incmeans <- tapply( c(60, 49, 40, 61, 64, 60, 59), statef, mean ), + <- incmeans. + +logical :- + t <- [1,2,3,4,5,1], + s <- t~~~~1, + <- s, + S <- s, + write( s(S) ), nl. + +~~~~ + +#### Info + +@see http://stoics.org.uk/~nicos/sware/real +@see pack(real/examples/for_real) +@see pack(real/doc/real.html) +@see pack(real/doc/guide.pdf) +@see pack(real/doc/padl2013-real.pdf) +@see http://www.r-project.org/ + +Also @subpaage yap-real describes the YAP specfic details in real. + +*/Development of real in YAP (#yap-real) +--------------------------- + + +YAP includes a development version of real, designed to experiment with the internals of the implementation of R. It includes major changes and is likely to be much less stable than the version maintained by Nicos ANgelopoulos. We refer to the version herein as @@ -56,4 +274,3 @@ March, 2014 Updates: Vitor Santos Costa Dec. 2015 - diff --git a/packages/real/real.pl b/packages/real/real.pl index 19985c71d..972b8777f 100755 --- a/packages/real/real.pl +++ b/packages/real/real.pl @@ -10,15 +10,6 @@ % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -/** - -@file real.pl -@author Nicos Angelopoulos -@author Vitor Santos Costa -@version 1:0:4, 2013/12/25, sinter_class -@license Perl Artistic License - -*/ :- module(real, [ start_r/0, @@ -76,220 +67,6 @@ %:- set_prolog_flag(double_quotes, string ). -/** @defgroup libReal An interface to the R statistical software. -@ingroup packages - -#### Introduction - -This library enables the communication with an R process started as a shared library. -It is the result of the efforts of two research groups that have worked in parallel. -The syntactic emphasis on a minimalistic interface. - -In the doc/ directory of the distribution there is user's guide, a published paper -and html documentation from PlDoc (doc/html/real.html). There is large number -of examples in `examples/for_real.pl`. - -A single predicate (<-/2,<-/1) channels -the bulk of the interactions. In addition to using R as a shared library, real uses -the c-interfaces of SWI/Yap and R to pass objects in both directions. -The usual mode of operation is to load Prolog values on to R variables and then call -R functions on these values. The return value of the called function can be either placed -on R variable or passed back to Prolog. It has been tested extensively on current -SWI and YAP on Linux machines but it should also compile and work on MS operating systems and Macs. - -The main modes for utilising the interface are -~~~~ - <- +Rexpr - <- +Rvar -~~~~ - - Print Rvar or evaluate expression Rexpr in R -~~~~ - +Rvar <- +PLdata - +Rexpr <- +PLdata - -PLvar <- +Rvar - -PLvar <- +Rexpr - +Rexpr1 <- +Rexpr2 -~~~~ - -Pass Prolog data to R, pass R data to Prolog or assign an R expression to -an assignable R expression. - -#### Testing - -There is a raft of examples packed in a singl```e file that test the library. - -~~~~ - ?- [pack(real/examples/for_real)]. - - ?- for_real. - - ?- edit( pack(real/examples/for_real) ). -~~~~ - -#### Syntax - -There are syntactic conventions in R that make unparsable prolog code. -Notably function and variable names are allowed to contain dots, square brackets are used -to access parts of vectors and arrays and functions are allowed empty argument tuples. -We have introduced relevant syntax which allows for easy transition between prolog and R. -Prolog constructs are converted by the library as follows: - - -* =|..|= within atoms -> =|.|= (ex. =| as..integer(c(1,2,3)) -> as.integer(c(1,2,3))|= ) -* =|^[]|= after atoms -> =|[]|= (ex. =|a^[2] -> a[2] |=) -* =|(.)|= at the end of atoms that are known R functions -> =|()|= (ex. =|dev..off(.) -> dev.off()|= ) -* =|[]|= -> c() (which equal to R's NULL value) -* ( f(x) :- (..)) -> f(x) (...) -* Lists of lists are converted to matrices. All first level lists must have the same length. -* Filenames must be given as Prolog strings. -* R specific operators (eg. %*% should be quoted in Prolog. -* + prepends strings, for (Prolog) atoms: +'String' -* Expressions that pose difficulty in translation can always be passed as unquoted Prolog atoms or strings. - ]]* since 0:1:2 foo() is valid syntax: =|<- dev..off() |= works now (with no need for dev..off(.)) - * since 0:1:2 mat[1] is valid syntax: =|m[1] <- 4|= works now (with no need for m^[...]) - - -#### Data transfers - -R vectors are mapped to prolog lists and matrices are mapped to nested lists. -The convention works the other way around too. - -There are two ways to pass prolog data to R. The more efficient one is by using -~~~~ - Rvar <- PLdata -~~~~ - -Where Pldata is one of the basic data types (number,boolean) a list or a c/n term. -This transfers via C data between R and Prolog. In what follows atomic PLval data -are simply considered as singleton lists. -Flat Pldata lists are translated to R vectors and lists of one level of nesting to R matrices -(which are 2 dimensional arrays in R parlance). The type of values of the vector or matrice is -taken to be the type of the first data element of the Pldata according to the following : - - * integer -> integer - * float -> double - * atom -> char - * boolean -> logical - -Booleans are represented in prolog as true/false atoms. -Currently arrays of aribtrary dimensions are not supported in the low-level interface. -Note that in R a scalar is just a one element vector. When passing non-scalars the -interface will assume the type of the object is that of the first scalar until it encounters -something different. -Real will currently re-start and repopulate partial integers for floats as illustrated -below: - -~~~~ -r <- [1,2,3]. % pass 1,2,3 to an R vector r -R <- r. % pass contents of R vector r to Prolog variable R -R = [1, 2, 3]. - -i <- [1,2,3.1]. % r is now a vector of floats, rather than integers -I <- i. -I = [1.0, 2.0, 3.1]. - - -~~~~ - -However, not all possible "corrections" are currently supported. For instance, - -~~~~ -?- c <- [a,b,c,1]. -ERROR: real:set_R_variable/2: Type error: `boolean' expected, found `a' -~~~~ - -In the data passing mode we map Prolog atoms to R strings- - -~~~~ -?- x <- [abc,def]. -true. - -?- <- x. -[1] "abc" "def" -true. - -?- X <- x. -X = [abc, def]. - -~~~~ - -In addition, Prolog data can be passed through the expression mechanism. -That is, data appearing in an arbitrary R expression will be parsed and be part of the long -string that will be passed from Prolog to R for evaluation. -This is only advisable for short data structures. For instance, - -~~~~ - tut_4a :- - state <- c(+"tas", +"sa", +"qld", +"nsw", +"nsw"), - <- state. - - tut_4b :- - state <- c(+tas, +sa, +qld, +nsw, +nsw), - <- state. -~~~~ - -Through this interface it is more convenient to be explicit about R chars by Prolog prepending -atoms or codes with + as in the above example. - -#### Examples - -~~~~ - -?- e <- numeric(.). -yes -?- e^[3] <- 17. -yes -?- e[3] <- 17. -yes -?- Z <- e. -Z = ['$NaN','$NaN',17.0] -?- e^[10] <- 12. -yes -?- Z <- e. -Z = ['$NaN','$NaN',17.0,'$NaN','$NaN','$NaN','$NaN','$NaN','$NaN',12.0] - -rtest :- - y <- rnorm(50), % get 50 random samples from normal distribution - <- y, % print the values via R - x <- rnorm(y), % get an equal number of normal samples - <- x11(width=5,height=3.5), % create a plotting window - <- plot(x,y) % plot the two samples - r_wait, % wait for user to hit Enter - % <- dev..off(.). % old syntax, still supported - <- dev.off(). % close the plotting window. foo() now acceptable in supported Prologs - -tut6 :- - d <- outer(0:9, 0:9), - fr <- table(outer(d, d, "-")), - <- plot(as..numeric(names(fr)), fr, type="h", xlab="Determinant", ylab="Frequency"). - -tut4b :- - state <- [tas,sa,qld,nsw,nsw,nt,wa], - statef <- factor(state), - incmeans <- tapply( c(60, 49, 40, 61, 64, 60, 59), statef, mean ), - <- incmeans. - -logical :- - t <- [1,2,3,4,5,1], - s <- t~~~~1, - <- s, - S <- s, - write( s(S) ), nl. - -~~~~ - -#### Info - -@see http://stoics.org.uk/~nicos/sware/real -@see pack(real/examples/for_real) -@see pack(real/doc/real.html) -@see pack(real/doc/guide.pdf) -@see pack(real/doc/padl2013-real.pdf) -@see http://www.r-project.org/ - -*/ - %%% init_r_env :- diff --git a/packages/udi/udi.md b/packages/udi/udi.md index 459d88f65..25d5e1e4b 100644 --- a/packages/udi/udi.md +++ b/packages/udi/udi.md @@ -1,5 +1,4 @@ -User Defined Indexers. -====================== +User-Defined Indexing (#yap-udi-indexers) +===================== YAP UDI indexers. - diff --git a/pl/attributes.md b/pl/attributes.md index eb005c854..876ac1569 100644 --- a/pl/attributes.md +++ b/pl/attributes.md @@ -1,4 +1,5 @@ -@{ + Attributed Variables and Co-Routining {#AttributedVariables} +======================================= @defgroup AttributedVariables Attributed Variables and Co-Routining @ingroup extensions @@ -27,15 +28,12 @@ work with. Most packages included in YAP that use attributed variables, such as CHR, CLP(FD), and CLP(QR), rely on the SWI-Prolog interface. -+ @ref attributes ++ @ewd attributes + @ref New_Style_Attribute_Declarations + @ref CohYroutining + @ref AttributeVariables_Builtins -@{ - -@defgroup attributes SICStus Style attribute declarations. -@ingroup AttributedVariables +@section attributes SICStus Style attribute declarations. The YAP library `atts` implements attribute variables in the style of SICStus Prolog. Attributed variables work as follows: @@ -282,7 +280,6 @@ Module:get_atts/2`. @{ @defgroup New_Style_Attribute_Declarations hProlog and SWI-Prolog style Attribute Declarations -@ingroup AttributedVariables The following documentation is taken from the SWI-Prolog manual. @@ -305,7 +302,7 @@ Module:get_atts/2`. get_attr(X, domain, Dom). domain(X, List) :- list_to_ord_set(List, Domain), - put_attr(Y, domain, Domain), +v put_attr(Y, domain, Domain), X = Y. % An attributed variable with attribute value Domain has been % @@ -355,7 +352,6 @@ Module:get_atts/2`. @{ @defgroup CohYroutining Co-routining -@ingroup AttributedVariables 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 diff --git a/pl/modules.md b/pl/modules.md index 7c9cccacd..299d6d0ef 100644 --- a/pl/modules.md +++ b/pl/modules.md @@ -1,7 +1,8 @@ +# The YAP Module system -@defgroup YAPModules The YAP Module system + The YAP Module system (#YAPModules) + - -@ingroup consult The YAP module system is based on the Quintus/SISCtus module system ˜\cite quintus . In this design, modules are named collections of predicates, diff --git a/run.md b/run.md new file mode 100644 index 000000000..262859f4e --- /dev/null +++ b/run.md @@ -0,0 +1,193 @@ +Running YAP (#run) +============== + + +We next describe how to invoke YAP in Unix systems. + +Running YAP Interactively (#interactive_run) +------------------------- + +Most often you will want to use YAP in interactive mode. Assuming that +YAP is in the user's search path, the top-level can be invoked under +Unix with the following command: + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +yap [-s n] [-h n] [-a n] [-c IP_HOST port ] [filename] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +All the arguments and flags are optional and have the following meaning: + ++ -? +print a short error message. ++ -s _Size_ +allocate _Size_ KBytes for local and global stacks. The user may +specify M bytes. ++ -h _Size_ +allocate _Size_ KBytes for heap and auxiliary stacks ++ -t _Size_ +allocate _Size_ KBytes for the trail stack ++ -L _Size_ +SWI-compatible option to allocate _Size_ K bytes for local and global stacks, the local stack +cannot be expanded. To avoid confusion with the load option, _Size_ +must immediately follow the letter `L`. ++ -G _Size_ +SWI-compatible option to allocate _Size_ K bytes for local and global stacks; the global +stack cannot be expanded ++ -T _Size_ +SWI-compatible option to allocate _Size_ K bytes for the trail stack; the trail cannot be expanded. ++ -l _YAP_FILE_ +compile the Prolog file _YAP_FILE_ before entering the top-level. ++ -L _YAP_FILE_ +compile the Prolog file _YAP_FILE_ and then halt. This option is +useful for implementing scripts. ++ -g _Goal_ +run the goal _Goal_ before top-level. The goal is converted from +an atom to a Prolog term. ++ -z _Goal_ +run the goal _Goal_ as top-level. The goal is converted from +an atom to a Prolog term. ++ -b _BOOT_FILE_ +boot code is in Prolog file _BOOT_FILE_. The filename must define +the predicate `'$live'/0`. ++ -c IP_HOST port +connect standard streams to host IP_HOST at port port ++ filename +restore state saved in the given file ++ -f +do not consult initial files ++ -q +do not print informational messages ++ -- +separator for arguments to Prolog code. These arguments are visible +through the unix/1 built-in predicate. + + +Note that YAP will output an error message on the following conditions: + ++ +a file name was given but the file does not exist or is not a saved +YAP state; + ++ +the necessary amount of memory could not be allocated; + ++ +the allocated memory is not enough to restore the state. + + + When restoring a saved state, YAP will allocate the +same amount of memory as that in use when the state was saved, unless a +different amount is specified by flags in the command line. By default, +YAP restores the file startup.yss from the current directory or from +the YAP library. + ++ +YAP usually boots from a saved state. The saved state will use the default +installation directory to search for the YAP binary unless you define +the environment variable YAPBINDIR. + ++ +YAP always tries to find saved states from the current directory + first. If it cannot it will use the environment variable YAPLIBDIR, if + defined, or search the default library directory. + ++ +YAP will try to find library files from the YAPSHAREDIR/library +directory. + +Prolog Scripts +-------------- + +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 +that the shell comments are very important): + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +#!/usr/local/bin/yap -L -- +# +# Hello World script file using YAP +# +# put a dot because of syntax errors . + +:- write('Hello World'), nl. + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The `#!` characters specify that the script should call the binary +file YAP. Notice that many systems will require the complete path to the +YAP binary. The `-L` flag indicates that YAP should consult the +current file when booting and then halt. The remaining arguments are +then passed to YAP. Note that YAP will skip the first lines if they +start with `#` (the comment sign for Unix's shell). YAP will +consult the file and execute any commands. + +A slightly more sophisticated example is: + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +#!/usr/bin/yap -L -- +# +# Hello World script file using YAP +# . + +:- initialization(main). + +main :- write('Hello World'), nl. + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The `initialization` directive tells YAP to execute the goal main +after consulting the file. Source code is thus compiled and `main` +executed at the end. The `.` is useful while debugging the script +as a Prolog program: it guarantees that the syntax error will not +propagate to the Prolog code. + +Notice that the `--` is required so that the shell passes the extra +arguments to YAP. As an example, consider the following script +`dump_args`: + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +#!/usr/bin/yap -L -- +#. + +main( [] ). +main( [H|T] ) :- + write( H ), nl, + main( T ). + +:- unix( argv(AllArgs) ), main( AllArgs ). + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you this run this script with the arguments: + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +./dump_args -s 10000 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +the script will start an YAP process with stack size `10MB`, and +the list of arguments to the process will be empty. + +Often one wants to run the script as any other program, and for this it +is convenient to ignore arguments to YAP. This is possible by using +`L --` as in the next version of `dump_args`: + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +#!/usr/bin/yap -L -- + +main( [] ). +main( [H|T] ) :- + write( H ), nl, + main( T ). + +:- unix( argv(AllArgs) ), main( AllArgs ). + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The `--` indicates the next arguments are not for YAP. Instead, +they must be sent directly to the argv built-in. Hence, running + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +./dump_args test +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +will write `test` on the standard output. +@}