diff --git a/docs/md/INSTALL.md b/docs/md/INSTALL.md index 971c2a974..e02de2c66 100644 --- a/docs/md/INSTALL.md +++ b/docs/md/INSTALL.md @@ -1,20 +1,21 @@ -Downloading and Installing YAP {#INSTALL} +lDownloading and Installing YAP {#INSTALL} =========================== - + This text includes instructions to download and install YAP. [TOC] -## Downloading YAP {#Download} +Downloading YAP {#Download} +---------------- The latest development version of Yap-6 is available source-only through GIT repositories. The main reference repository is at - + [github](https://github.com/vscosta/yap-6.3) ++ development branch: [github](https://github.com/vscosta/yap-6.3) We store an older version of YAP at: - + [sourceforge](http://sourceforge.net/p/yap/yap-6.3) ++ snapshots: [sourceforge](http://sourceforge.net/p/yap/yap-6.3) Please just use `git clone` to obtain the distribution. Ie, to download YAP from the command line please type: @@ -26,22 +27,23 @@ The first argument is the repository, the last argument is the (optional) target There are a variety of graphical interfaces to `git`, including GitHub's own [GitHub Desktop](https://desktop.github.com/) that supports Microsoft Windows and Apple OSX. A list with GUI applications, editor integration, and much more can be found at the [git Wiki](https://git.wiki.kernel.org/index.php/InterfacesFrontendsAndTools), -## Download Options +### Download Options It may be useful to know: - + If you are have limited bandwith or disk spaceq, consider using ++ If you are have limited bandwith or disk spaceq, consider using `git clone --depth XX` to only include the last `XX` commits. - + Older versions of YAP were distributed with modules. YAP-6.3.5 is ++ Older versions of YAP were distributed with modules. YAP-6.3.5 is a single package, and it does not need `git submodule`. - + The GitHub site includes a number of companion packages for YAP, ++ The GitHub site includes a number of companion packages for YAP, including [doxygen-yap](https://github.com/vscosta/doxygen-yap), a version of doxygen adapted to Prolog that was used to generate these documents. -## Compiling YAP {#CompilingYAP} +Compiling YAP {#CompilingYAP} +---------------- YAP-6.3.4 is a [cmake](www.cmake.org) based system. We use `cmake` because it supports mosts popular software, can @@ -49,12 +51,12 @@ generate Makefiles, Ninja, Apple's XCode, VisualStudio and ANdroid Studio, and because it includes packaging suppport, The steps required to install core YAP under `cmake`: -#### The compiler +### The compiler *Status as of early 2017* YAP should compile well under the [GNU-CC](https://gcc.gnu.org/) - and the [C-LANG]https://clang.llvm.org/() families, that are + and the [C-LANG](https://clang.llvm.org/) families, that are available across most configurations. It sshould also compile well undder Intel `icc`. @@ -66,7 +68,7 @@ to install core YAP under `cmake`: YAP compiles cleanly under cross-compilers, and we have used the crosss-compilation system [mxe](http://mxe.cc/) system with good results. -## cmake +### cmake All Linux and BSD distributions include `cmake`, so does [Homebrew](https://brew.sh/) @@ -76,33 +78,33 @@ and [cygwin](http://www.cygwin.org/) for WIN32. Android Studio has native support for `cmake`since 2.1, although we advise to use 2.2. Last, there are excellent plugins for the Visual Codes. In case you need a recent version, consider using pre-compiled binaries at -the [CMake site](https://www.cmake.org). +the [CMake site](https://www.cmake.org). If you have an older Linux you may need to compile from source, available at GitHub. -## Ensure that you have other necessary packages installed: +### Ensure that you have other necessary packages installed: + YAP requires [gmp]{https://gmplib.org/} for infinite precision integer and rational. Please ensure the development pacakage is installed in Linux: `(lib)gmp-dev(el). In the Mac and WIN32, you can obtain GMPlib from the pakage collections mentioned above. - + The [MPIR]{http://mpir.org} library is compatible with GMPlib, and has good support for VC++. - + + The [readline]() library provides line-editing and command history. In Linux, make sure you have the development package. - + Readline is disabled by default in WIN32. OSX is distributed with a line editing library that includes a subset of readline. We advise against using that library. - + - To use YAP as a library in [Python]() you need the [SWIG]() interface generator and python3-dev. SWIG and Python binaries can be easily obtained for all these platfors - + make sure to install Python-3, and not Python-2, - -## Compile and Install + + make sure to install Python-3, and not Python-2, + +### Compile and Install 1: Create a directory, say `Build` and `cd` to the directory (`cd Build`). *YAP should not be compiled at its rootxo directory, some packages do not allow for that. @@ -116,7 +118,7 @@ available at GitHub. 5: If you feel satisfied with the result, do `make install`. * In most systems you will need to be superuser in order to do `make install` and `make info` on the standard directories. -### Tuning the Functionality of YAP +#### Tuning the Functionality of YAP By default, YAP supports tabling, depth first search, and most features found in modern Prologs. In some cases, you may want to suport extra features, or reduce system size. @@ -177,53 +179,53 @@ You can also use `xcodebuild` from the command line. Bext follow instructions to fully compile YAP: -## Compilation Notes for OSX/Brew +### Compilation Notes for OSX/Brew Next follows a detailed description of a full install of YAP, including all the packages that YAP can use: - 1. Install the XCode toolkit from the Apple App Store (you may have to register as a developer). + 1. Install the XCode toolkit from the Apple App Store (you may have to register as a developer). - 2. Install a package manager, such as [brew](http://brew.sh), + 2. Install a package manager, such as [brew](http://brew.sh), - 3. You will need `cmake` and `gmp`: both are available in brew. + 3. You will need `cmake` and `gmp`: both are available in brew. - 4. other brew packages you may want to install: `gecode`, `libxml2`, `openssl`, + 4. other brew packages you may want to install: `gecode`, `libxml2`, `openssl`, `mariadb`, `openmpi`, `postgresql`, `raptor`, `sqlite3`, `swig`, `unixodbc`. Note that some of them may be preconditions to other packages. - 5. to install [cudd](http://vlsi.colorado.edu/~fabio/CUDD), a package used by ProbLog and cplint, just use: + 5. to install [cudd](http://vlsi.colorado.edu/~fabio/CUDD), a package used by ProbLog and cplint, just use: ~~~~~ brew tap mht208/formal brew install cudd ~~~~~ - 6. To use [R](https://www.r-project.org), you must download the `R` distribution from one of the many `R` mirrors. + 6. To use [R](https://www.r-project.org), you must download the `R` distribution from one of the many `R` mirrors. - 6. To use [Java](https://www.java.com), you should download the Oracle distributed JDK. + 6. To use [Java](https://www.java.com), you should download the Oracle distributed JDK. - 6. When installing [Python](https://www.python.org), verify which python you + 6. When installing [Python](https://www.python.org), verify which python you are using. - 7. There may be conflict between original OSX and the brew packages (eg, `openssl`, `python`, and `sqlite3`. If you prefer leaning on brew: + 7. There may be conflict between original OSX and the brew packages (eg, `openssl`, `python`, and `sqlite3`. If you prefer leaning on brew: ~~~~~ cmake -DOPENSSL_ROOT_DIR=/usr/local/opt/openssl .. ~~~~~ -## Compilation Notes for Android +### Compilation Notes for Android Next we present the compilation process for Android. The environment is an OSX, but steps should be similar for Linux machines. We assume you have downloaded both the Android NDK and the Android SDK. - 1. Reserve a directory for compilation: +1. Reserve a directory for compilation: ~~~~~ mkdir android cd android ~~~~~ - 2. Get the [GMP-android](https://github.com/Rupan/gmp) port. +2. Get the [GMP-android](https://github.com/Rupan/gmp) port. - 2. Call `cmake`: +2. Call `cmake`: ~~~~~ export ANDROID_NDK=/Volumes/Transcend/vsc/android-ndk-r11c; \ export ANDROID_SDK=/Volumes/Transcend/vsc/AndroidSDK;\ diff --git a/docs/md/attributes.md b/docs/md/attributes.md index 82c6f1334..2d38a970a 100644 --- a/docs/md/attributes.md +++ b/docs/md/attributes.md @@ -1,9 +1,11 @@ -@defgroup AttributedVariables Attributed Variables and Co-Routining -@ingroup extensions +@defgroup AttributedVariables Attributed Variables @{ + + +@ingroup extensions YAP supports attributed variables, originally developed at OFAI by Christian Holzbaur. Attributes are a means of declaring that an @@ -28,8 +30,10 @@ work with. Most packages included in YAP that use attributed variables, such as CHR, CLP(FD), and CLP(QR), rely on the SWI-Prolog awi interface. -@defgroup SICS_attributes SICStus Style attribute declarations. +@defgroup SICS_attributes SICStus Style attribute declarations. +@{ +@ingroup AttributedVariables The YAP library `atts` implements attribute variables in the style of SICStus Prolog. Attributed variables work as follows: @@ -82,10 +86,9 @@ mechanism is used for this purpose. The attribute manipulation predicates always work as follows: - + The first argument is the unbound variable associated with ++ The first argument is the unbound variable associated with attributes, - - + The second argument is a list of attributes. Each attribute will ++ The second argument is a list of attributes. Each attribute will be a Prolog term or a constant, prefixed with the + and - unary operators. The prefix + may be dropped for convenience. @@ -100,9 +103,9 @@ attempting to unify an attributed variable which might have attributes in some _Module_. -At execution conclusion, attributes still unsatisfied are presented as -goals. The following routines are used by built-in predicates such as -call_residue/2 and by the Prolog top-level to display attributes: +Attributes are usually presented as goals. The following routines are +used by built-in predicates such as call_residue/2 and by the +Prolog top-level to display attributes: Constraint solvers must be able to project a set of constraints to a set @@ -270,11 +273,15 @@ variables only. More complicated interactions are likely to be found in more sophisticated solvers. The corresponding verify_attributes/3 predicates would typically refer to the attributes from other known solvers/modules via the module prefix in -Module:get_atts/2. +Module:get_atts/2`. + +@} -hProlog and SWI-Prolog style Attribute Declarations {#New_Style_Attribute_Declarations} ------------------------------------------------- +@defgroup New_Style_Attribute_Declarations hProlog and SWI-Prolog style Attribute Declarations + +@{ + @ingroup AttributedVariables The following documentation is taken from the SWI-Prolog manual. @@ -288,26 +295,23 @@ hProlog and SWI-Prolog style Attribute Declarations {#New_Style_Att ~~~~~ :- module(domain, -[ domain/2 % Var, ?Domain % -]). + [ domain/2 % Var, ?Domain % + ]). :- use_module(library(ordsets)). - + domain(X, Dom) :- - var(Dom), !, - get_attr(X, domain, Dom). - domain(X, List) :- - list_to_ord_set(List, Domain), - put_attr(Y, domain, Domain), - X = Y. - + var(Dom), !, + get_attr(X, domain, Dom). +domain(X, List) :- + list_to_ord_set(List, Domain), + put_attr(Y, domain, Domain), + X = Y. ~~~~~ -The next predicate is called *after* _X_, the attributed variable with attribute value _Domain_ has been -assigned the value Y. - + An attributed variable with attribute value Domain has been assigned the value Y. ~~~~~ -attr_unify_hook(Domain, Y) :- + attr_unify_hook(Domain, Y) :- ( get_attr(Y, domain, Dom2) -> ord_intersection(Domain, Dom2, NewDomain), ( NewDomain == [] @@ -322,7 +326,7 @@ attr_unify_hook(Domain, Y) :- ). ~~~~~ -The user defined attribute_goals/1 attributes from this module to residual goals +Translate attributes from this module to residual goals: ~~~~~ attribute_goals(X) --> @@ -330,7 +334,7 @@ attribute_goals(X) --> [domain(X, List)]. ~~~~~ - Before explaining the code in detail we give some example queries: + Before explaining the code we give some example queries: The predicate `domain/2` fetches (first clause) or assigns (second clause) the variable a domain, a set of values it can @@ -348,8 +352,12 @@ attribute_goals(X) --> remaining attributes to user-readable goals that, when executed, reinstate these attributes. -Co-routining {#CohYroutining} ------------- +@} + +@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 @@ -362,27 +370,31 @@ attributed variables to implement co-routining. Two declarations are supported: - + block/1 - The argument to `block/1` is a condition on a goal or a conjunction - of conditions, with each element separated by commas. Each condition is - of the form `predname( _C1_,..., _CN_)`, where _N_ is the - arity of the goal, and each _CI_ is of the form `-`, if the - argument must suspend until the first such variable is bound, or - `?`, otherwise. ++ block/1 +The argument to `block/1` is a condition on a goal or a conjunction +of conditions, with each element separated by commas. Each condition is +of the form `predname( _C1_,..., _CN_)`, where _N_ is the +arity of the goal, and each _CI_ is of the form `-`, if the +argument must suspend until the first such variable is bound, or +`?`, otherwise. - + wait/1 - The argument to `wait/1` is a predicate descriptor or a conjunction - of these predicates. These predicates will suspend until their first - argument is bound. ++ wait/1 +The argument to `wait/1` is a predicate descriptor or a conjunction +of these predicates. These predicates will suspend until their first +argument is bound. The following primitives can be used: - - freeze/2 +- freeze/2 - - dif/2 +- dif/2 - - when/2 +- when/2 - - frozen/2 +- frozen/2 + +@} + +@} diff --git a/docs/md/extensions.md b/docs/md/extensions.md index 05f00531c..670ea02b0 100644 --- a/docs/md/extensions.md +++ b/docs/md/extensions.md @@ -1,34 +1,25 @@ -Extensions to core Prolog. {#extensions} -========================= +@defgroup extensions Extensions to core Prolog. + +@{ + YAP includes a number of extensions over the original Prolog language. Next, we discuss how to use the most important ones. - + @ref Rational_Trees + + @ref Rational_Trees - + @ref AttributedVariables + + @ref AttributedVariables - + @ref DepthLimited + + @ref DepthLimited - + @ref Tabling + + @ref Tabling - + @ref Threads + + @ref Threads - + @ref Profiling + + @ref Profiling - + @ref YAPArrays - - + @ref Parallelism - -In the description of the arguments of predicates the following -notation will be used: - - + a preceding plus sign will denote an argument as an "input -argument": the argument is read, not written, and it cannot be a free -variable at the time of the call. - - + a preceding minus sign will denote an "output argument"; - - + an argument with no preceding symbol can be used in both ways. + + @ref YAPArrays + + @ref Parallelism +@} diff --git a/docs/md/library.md b/docs/md/library.md index e0103e5a8..0523ef553 100644 --- a/docs/md/library.md +++ b/docs/md/library.md @@ -1,27 +1,9 @@ - -YAP Prolog Library {#LibraryPage} -=================== - - -YAP provides a collection of Prolog utilities, that extend core Prolog -with data-structures such as balanced trees and hash tables, extend -Input Output, or use the `C`-interface to interact with the -Operating System or to implement arrays. - -These programs are stored at the library_directory path (set by the -`LIBDIR` variable in the Makefile for YAP). - -The files have different sources. Many were part of the public-domain -Edinburgh Prolog library. Other Prolog systems such as SWI-Prolog -were kind enough to allow using files from their distributions. - - -@copydoc library - - +@defgroup library YAP Prolog Library + @{ -@defgroup library The YAP Library + the library_directory path (set by the + `LIBDIR` variable in the Makefile for YAP). Several files in the + library are originally from the public-domain Edinburgh Prolog library. @} - diff --git a/docs/md/programming.md b/docs/md/programming.md index b1f1e7518..e454649b7 100644 --- a/docs/md/programming.md +++ b/docs/md/programming.md @@ -1,10 +1,361 @@ Programming in YAP {#YAPProgramming} ==================== - + @subpage YAPSyntax ++ @ref load_files - + @ref YAPCompilerSettings ++ @ref YAPSyntax - + @ref Indexing ++ @ref YAPCompilerSettings - + @ref Deb_Interaction ++ @ref Indexing + ++ @ref Deb_Interaction + + +@defgroup load_files Loading and Organizing YAP Programs +@{ + +We present the main predicates and directives available to load + files and to control the Prolog environment. + +@} + +@defgroup YAPModules The YAP Module system + +@{ + The YAP module system is based on the Quintus/SISCtus module + system @cite quintus . In this design, modules are named collections of predicates, + and all predicates belong to a single module. By default, predicates are only + visible within a module, or _private_ to that module. The module + may also define a list of predicates that are + _exported_, that is, visible to other modules. + + The main predicates in the module system are: + + * module/2 associates a source file to a module. It has two arguments: the name of the new module, and a list of predicates exported by the module. + + * use_module/1 and use_module/2 can be used to load a module. They take as first argument the source file for the module. Whereas use_module/1 loads all exported predicates, use_module/2 only takes the ones given by the second argument. + + YAP pre-defines a number of modules. Most system predicates belong to + the module `prolog`. Predicates from the module `prolog` are + automatically visible to every module. The `system` module was + introduced for SWI-Prolog compatibility, and in YAP mostly acts as an + alias to `prolog`. The `user` module is also visible to all other modules. + + The YAP engine is always associated to a module, the current source + module or type-in module. By default, all predicates + read-in and all calls to a goal will be made to predicates visible to + the current source module, Initially, the source module for YAP is the + module `user`. Thus Prolog programs that do not define modules will + operate within the `user` module. In this case, all predicates will be + visible to all source files. + + YAP includes a number of libraries and packages, most of them + defining their own modules. Note that there is no system mechanism to + avoid clashes between module names, so it is up to the programmer to + carefully choose the names for her own program modules. + + The main mechanism to change the current type-in module is by using + the module/2 declaration.This declaration sets the source module when + it starts consulting a file, and resets it at the end. One can set + the type-in module permanently by using the built-in `module/1`. + + ### Explicit Naming {#ExplicitNaming} + + The module system allows one to _explicitly_ specify the source mode for + a clause by prefixing a clause with its module, say: + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.prolog} + user:(a :- b). + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + it is also possible to type + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.prolog} + + user:a :- user:b. + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + both formulations describe the same clause, independently of the + current type-in module. + + In fact, it is sufficient to specify the source mode for the clause's + head: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.prolog} + user:a :- b. + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + if the current type-in module is `m`, the clause could also be written as: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.prolog} + user:a :- m:b. + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + The compiler rewrites the source clauses to ensure that explicit calls + are respected, and that implicit calls are made to the current source + module. + + A goal should refer to a predicate visible within the current type-in + module. Thus, if a goal appears in a text file with a module + declaration, the goal refers to that module's context (but see the + initialization/1 directive for more details). + + Again, one can override this rule by prefixing a goal with a module to + be consulted. The following query: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.prolog} + ?- nasa:launch(apollo,13). + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + invokes the goal `launch(apollo,13)` as if the current source + module was `nasa`. + + YAP and other Prolog systems allow the module prefix to see all + predicates visible in the module, including predicates private to the + module. This rule allows maximum flexibility, but it also breaks + encapsulation and should be used with care. The ciao language proposes + a different approach to this problem, see \cite DBLP:conf/cl/GrasH00 . + + Modules are not always associated with a source-file. They + may range over several files, by using the + `include`directive. Moreover, they may not be associated to any source + file. As an example, + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.prolog} + ?- assert( nasa:launch(apollo,13) ). + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + will create a module `nasa`, if does not already exist. In fact it is + sufficient to call a predicate from a module to implicitly create the + module. Hence after this call: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.prolog} + ?- nasa:launch(apollo,13). + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + there will be a `nasa`module in the system, even if nasa:launch/2 is + not at all defined. + + \pred use_module( +Files ) is directive + loads a module file + + This predicate loads the file specified by _Files_, importing all + their public predicates into the current type-in module. It is + implemented as if by: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.prolog} + use_module(F) :- + load_files(F, [if(not_loaded),must_be_module(true)]). + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + Notice that _Files_ may be a single file, or a list with a number + files. The _Files_ are loaded in YAP only once, even if they have been + updated meanwhile. YAP should also verify whether the files actually + define modules. Please consult load_files/3 for other options when + loading a file. + + Predicate name clashes between two different modules may arise, either + when trying to import predicates that are also defined in the current + type-in module, or by trying to import the same predicate from two + different modules. + + In the first case, the local predicate is considered to have priority + and use_module/1 simply gives a warning. As an example, if the file + `a.pl` contains: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.prolog} + :- module( a, [a/1] ). + + :- use_module(b). + + a(1). + a(X) :- b(X). + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + and the file `b.pl` contains: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.prolog} + :- module( b, [a/1,b/1] ). + + a(2). + + b(1). + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + YAP will execute as follows: + + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.prolog} + ?- [a]. + % consulting .../a.pl... + % consulting .../b.pl... + % consulted .../b.pl in module b, 0 msec 0 bytes + % consulted .../a.pl in module a, 1 msec 0 bytes + true. + ?- a(X). + X = 1 ? ; + X = 1. + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + The example shows that the query `a(X)`has a single answer, the one + defined in `a.pl`. Calls to `a(X)`succeed in the top-level, because + the module `a` was loaded into `user`. On the other hand, `b(X)`is not + exported by `a.pl`, and is not available to calls, although it can be + accessed as a predicate in the module 'a' by using the `:` operator. + + Next, consider the three files `c.pl`, `d1.pl`, and `d2.pl`: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.prolog} + % c.pl + :- module( c, [a/1] ). + + :- use_module([d1, d2]). + + a(X) :- + b(X). + a(X) :- + c(X). + a(X) :- + d(X). + + % d1.pl + :- module( d1, [b/1,c/1] ). + + b(2). + c(3). + + + % d2.pl + :- module( d2, [b/1,d/1] ). + + b(1). + d(4). + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + The result is as follows: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.prolog} + ./yap -l c + YAP 6.3.4 (x86_64-darwin13.3.0): Tue Jul 15 10:42:11 CDT 2014 + + ERROR!! + at line 3 in o/d2.pl, + PERMISSION ERROR- loading .../c.pl: modules d1 and d2 both define b/1 + ?- a(X). + X = 2 ? ; + ERROR!! + EXISTENCE ERROR- procedure c/1 is undefined, called from context prolog:$user_call/2 + Goal was c:c(_131290) + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + The state of the module system after this error is undefined. + + ### Built-In predicates {#ModuleBuiltins) + + @\pred module(+ M:atom,+ L:list ) is directive + the current file defines module _M_ with exports _L_. The list may include + + + predicate indicators + + + operator definitions that look like calls to op/3. + + The list _L_ may include predicates imported from other modules. If + you want to fully reexport a module, or a sub-set, also consider reexport/1. + + Similar to module/2, this directive defines the file where it + appears in as a module file; it must be the first declaration in the file. + _M_ must be an atom specifying the module name; _L_ must be a + list containing the module's public predicates specification, in the + form `[predicate_name/arity,...]`. + + The last argument _Options_ must be a list of options, which can be: + + filename + the filename for a module to import into the current module. + + + library( +File ) + a library file to import into the current module. + + + hide( +Opt) + if _Opt_ is `false`, keep source code for current module, if `true`, disable. + + + export(+PredicateIndicator ) + Add predicates to the public list of the context module. This implies + the predicate will be imported into another module if this module + is imported with use_module/1 and use_module/2. + + + export_list(? _Mod_,? _ListOfPredicateIndicator_) + The list _ListOfPredicateIndicator_ contains all predicates + exported by module _Mod_ + + Note that predicates are normally exported using the directive + `module/2`. The `export/1` argumwnt is meant to allow export from + dynamically created modules. The directive argument may also be a list + of predicates. + + @pred use_module(+Files, +Imports) + loads a module file but only imports the named predicates + + + This predicate loads the file specified by _Files_, importing their + public predicates specified by _Imports_ into the current type-in + module. It is implemented as if by: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.prolog} + use_module(Files, Imports) :- + load_files(Files, [if(not_loaded),must_be_module(true),imports(Imports)]). + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + The _Imports_ argument may be use to specify which predicates one + wants to load. It can also be used to give the predicates a different name. As an example, + the graphs library is implemented on top of the red-black trees library, and some predicates are just aliases: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.prolog} + :- use_module(library(rbtrees), [ + rb_min/3 as min_assoc, + rb_max/3 as max_assoc, + + ...]). + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + Unfortunately it is still not possible to change argument order. + + + \pred module(+ M:atom,+ L:list ) is directive + the current file defines module _M_ with exports _L_. The list may include + + + predicate indicators + + + operator definitions that look like calls to op/3. + + The list _L_ may include predicates imported from other modules. If + you want to fully reexport a module, or a sub-set, also consider reexport/1. + + Similar to module/2, this directive defines the file where it + appears in as a module file; it must be the first declaration in the file. + _M_ must be an atom specifying the module name; _L_ must be a + list containing the module's public predicates specification, in the + form `[predicate_name/arity,...]`. + + The last argument _Options_ must be a list of options, which can be: + +filename + the filename for a module to import into the current module. + + + library( +File ) + a library file to import into the current module. + + + hide( +Opt) + if _Opt_ is `false`, keep source code for current module, if `true`, disable. + + + export(+PredicateIndicator ) + Add predicates to the public list of the context module. This implies + the predicate will be imported into another module if this module + is imported with use_module/1 and use_module/2. + + + export_list(? _Mod_,? _ListOfPredicateIndicator_) + The list _ListOfPredicateIndicator_ contains all predicates + exported by module _Mod_ + + Note that predicates are normally exported using the directive + `module/2`. The `export/1` argument is meant to allow export from + dynamically created modules. The directive argument may also be a list + of predicates. + + @} diff --git a/docs/md/run.md b/docs/md/run.md index 17f8e9acc..d382dc6be 100644 --- a/docs/md/run.md +++ b/docs/md/run.md @@ -7,8 +7,8 @@ We next describe how to invoke YAP in Unix systems. [TOC] -### Running YAP Interactively {#Running_YAP_Interactively} - +Running YAP Interactively {#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 @@ -54,7 +54,7 @@ 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 ++ filename restore state saved in the given file + -f do not consult initial files @@ -67,38 +67,28 @@ 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 ++ 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 necessary amount of memory could not be allocated; -+ -the allocated memory is not enough to restore the state. ++ 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. - 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 ++ 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 ++ 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. -YAP will try to find library files from the YAPSHAREDIR/library -directory. - -## Running Prolog Files {#Running_Prolog_Files} +Running Prolog Files {#Running_Prolog_Files} +-------------------- YAP can also be used to run Prolog files as scripts, at least in Unix-like environments. A simple example is shown next (do not forget diff --git a/docs/md/yap.md b/docs/md/yap.md index eff0609d2..c773e7bb7 100644 --- a/docs/md/yap.md +++ b/docs/md/yap.md @@ -17,13 +17,11 @@ Porto. The manual is organised as follows: -+ @subpage INSTALL ++ @ref INSTALL -+ @subpage run ++ @ref run -+ @subpage load_files - -+ @subpage builtins ++ @ref builtins + @subpage extensions @@ -60,6 +58,40 @@ Jan Wielemaker. We would also like to gratefully acknowledge the contributions from Ashwin Srinivasian. +@page Library YAP Library - + the library_directory path (set by the + `LIBDIR` variable in the Makefile for YAP). Several files in the + library are originally from the public-domain Edinburgh Prolog library. + + + +@page Extensions YAP Extensions + +YAP includes a number of extensions over the original Prolog +language. + + + @subpage attributes.md + + + @ref Rational_Trees + + + @ref CohYroutining + + + @ref DepthLimited + + + @ref Tabling + + + @ref Threads + + + @ref Profiling + + + @ref YAPArrays + + + @ref Parallelism + + +@page YAPProgramming Programming in YAP + + +@page packages Packages for YAP