From c04a63d61babf7d2b33a61bf6b9b8635f9129814 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADtor=20Santos=20Costa?= Date: Tue, 15 Dec 2015 08:24:11 +0000 Subject: [PATCH] move big doc chunks to md files also moe icons to docs/ --- {misc => docs}/icons/favicon_16x16.ico | Bin {misc => docs}/icons/favicon_32x32.ico | Bin {misc => docs}/icons/favicon_64x64.ico | Bin {misc => docs}/icons/yap.hqx | 0 {misc => docs}/icons/yap.icns | Bin {misc => docs}/icons/yap.ico | Bin {misc => docs}/icons/yap_128x128x32.png | Bin {misc => docs}/icons/yap_16x16x32.png | Bin {misc => docs}/icons/yap_24x24x32.png | Bin {misc => docs}/icons/yap_256x256x32.png | Bin {misc => docs}/icons/yap_256x56x32.png | Bin {misc => docs}/icons/yap_32x32x32.png | Bin {misc => docs}/icons/yap_48x48x32.png | Bin {misc => docs}/icons/yap_512x512x32.png | Bin {misc => docs}/icons/yap_64x64x32.png | Bin {misc => docs}/icons/yap_96x96x32.png | Bin {misc => docs}/icons/yapsmall.png | Bin pl/absf.md | 107 ++++++++ pl/attributes.md | 19 +- pl/modules.md | 337 ++++++++++++++++++++++++ 20 files changed, 454 insertions(+), 9 deletions(-) rename {misc => docs}/icons/favicon_16x16.ico (100%) rename {misc => docs}/icons/favicon_32x32.ico (100%) rename {misc => docs}/icons/favicon_64x64.ico (100%) rename {misc => docs}/icons/yap.hqx (100%) rename {misc => docs}/icons/yap.icns (100%) rename {misc => docs}/icons/yap.ico (100%) rename {misc => docs}/icons/yap_128x128x32.png (100%) rename {misc => docs}/icons/yap_16x16x32.png (100%) rename {misc => docs}/icons/yap_24x24x32.png (100%) rename {misc => docs}/icons/yap_256x256x32.png (100%) rename {misc => docs}/icons/yap_256x56x32.png (100%) rename {misc => docs}/icons/yap_32x32x32.png (100%) rename {misc => docs}/icons/yap_48x48x32.png (100%) rename {misc => docs}/icons/yap_512x512x32.png (100%) rename {misc => docs}/icons/yap_64x64x32.png (100%) rename {misc => docs}/icons/yap_96x96x32.png (100%) rename {misc => docs}/icons/yapsmall.png (100%) create mode 100644 pl/absf.md create mode 100644 pl/modules.md diff --git a/misc/icons/favicon_16x16.ico b/docs/icons/favicon_16x16.ico similarity index 100% rename from misc/icons/favicon_16x16.ico rename to docs/icons/favicon_16x16.ico diff --git a/misc/icons/favicon_32x32.ico b/docs/icons/favicon_32x32.ico similarity index 100% rename from misc/icons/favicon_32x32.ico rename to docs/icons/favicon_32x32.ico diff --git a/misc/icons/favicon_64x64.ico b/docs/icons/favicon_64x64.ico similarity index 100% rename from misc/icons/favicon_64x64.ico rename to docs/icons/favicon_64x64.ico diff --git a/misc/icons/yap.hqx b/docs/icons/yap.hqx similarity index 100% rename from misc/icons/yap.hqx rename to docs/icons/yap.hqx diff --git a/misc/icons/yap.icns b/docs/icons/yap.icns similarity index 100% rename from misc/icons/yap.icns rename to docs/icons/yap.icns diff --git a/misc/icons/yap.ico b/docs/icons/yap.ico similarity index 100% rename from misc/icons/yap.ico rename to docs/icons/yap.ico diff --git a/misc/icons/yap_128x128x32.png b/docs/icons/yap_128x128x32.png similarity index 100% rename from misc/icons/yap_128x128x32.png rename to docs/icons/yap_128x128x32.png diff --git a/misc/icons/yap_16x16x32.png b/docs/icons/yap_16x16x32.png similarity index 100% rename from misc/icons/yap_16x16x32.png rename to docs/icons/yap_16x16x32.png diff --git a/misc/icons/yap_24x24x32.png b/docs/icons/yap_24x24x32.png similarity index 100% rename from misc/icons/yap_24x24x32.png rename to docs/icons/yap_24x24x32.png diff --git a/misc/icons/yap_256x256x32.png b/docs/icons/yap_256x256x32.png similarity index 100% rename from misc/icons/yap_256x256x32.png rename to docs/icons/yap_256x256x32.png diff --git a/misc/icons/yap_256x56x32.png b/docs/icons/yap_256x56x32.png similarity index 100% rename from misc/icons/yap_256x56x32.png rename to docs/icons/yap_256x56x32.png diff --git a/misc/icons/yap_32x32x32.png b/docs/icons/yap_32x32x32.png similarity index 100% rename from misc/icons/yap_32x32x32.png rename to docs/icons/yap_32x32x32.png diff --git a/misc/icons/yap_48x48x32.png b/docs/icons/yap_48x48x32.png similarity index 100% rename from misc/icons/yap_48x48x32.png rename to docs/icons/yap_48x48x32.png diff --git a/misc/icons/yap_512x512x32.png b/docs/icons/yap_512x512x32.png similarity index 100% rename from misc/icons/yap_512x512x32.png rename to docs/icons/yap_512x512x32.png diff --git a/misc/icons/yap_64x64x32.png b/docs/icons/yap_64x64x32.png similarity index 100% rename from misc/icons/yap_64x64x32.png rename to docs/icons/yap_64x64x32.png diff --git a/misc/icons/yap_96x96x32.png b/docs/icons/yap_96x96x32.png similarity index 100% rename from misc/icons/yap_96x96x32.png rename to docs/icons/yap_96x96x32.png diff --git a/misc/icons/yapsmall.png b/docs/icons/yapsmall.png similarity index 100% rename from misc/icons/yapsmall.png rename to docs/icons/yapsmall.png diff --git a/pl/absf.md b/pl/absf.md new file mode 100644 index 000000000..1f589108d --- /dev/null +++ b/pl/absf.md @@ -0,0 +1,107 @@ + +@addtogroup absolute_file_name + +@pred absolute_file_name(+File:atom, +Options:list, +Path:atom) is nondet +@pred absolute_file_name(-File:atom, +Path:atom, +Options:list) is nondet + + _Options_ is a list of options to guide the conversion: + + - extensions(+ _ListOfExtensions_) + + List of file-name suffixes to add to try adding to the file. The + Default is the empty suffix, `''`. For each extension, + absolute_file_name/3 will first add the extension and then verify + the conditions imposed by the other options. If the condition + fails, the next extension of the list is tried. Extensions may + be specified both with dot, as `.ext`, or without, as plain + `ext`. + + - relative_to(+ _FileOrDir_ ) + + Resolve the path relative to the given directory or directory the + holding the given file. Without this option, paths are resolved + relative to the working directory (see working_directory/2) or, + if _Spec_ is atomic and absolute_file_name/3 is executed + in a directive, it uses the current source-file as reference. + + - access(+ _Mode_ ) + + Imposes the condition access_file( _File_ , _Mode_ ). _Mode_ is one of `read`, `write`, `append`, `exist` or + `none` (default). + + See also access_file/2. + + - file_type(+ _Type_ ) + + Defines suffixes matching one of several pre-specified type of files. Default mapping is as follows: + + 1. `txt` implies `[ '' ]`, + + 2. `prolog` implies `['.yap', '.pl', '.prolog', '']`, + + 3. `executable` implies `['.so', ',dylib', '.dll']` depending on the Operating system, + + 4. `qly` implies `['.qly', '']`, + + 5. `directory` implies `['']`, + + 6. The file-type `source` is an alias for `prolog` designed to support compatibility with SICStus Prolog. See also prolog_file_type/2. + + Notice that this predicate only + returns non-directories, unless the option `file_type(directory)` is + specified, or unless `access(none)`. + + - file_errors(`fail`/`error`) + + If `error` (default), throw `existence_error` exception + if the file cannot be found. If `fail`, stay silent. + + - solutions(`first`/`all`) + + If `first` (default), commit to the first solution. Otherwise + absolute_file_name will enumerate all solutions via backtracking. + + - expand(`true`/`false`) + + If `true` (default is `false`) and _Spec_ is atomic, call + expand_file_name/2 followed by member/2 on _Spec_ before + proceeding. This is originally a SWI-Prolog extension, but + whereas SWI-Prolog implements its own conventions, YAP uses the + shell's `glob` primitive. + + - glob(`Pattern`) + + If _Pattern_ is atomic, add the pattern as a suffix to the current expansion, and call + expand_file_name/2 followed by member/2 on the result. This is originally a SICStus Prolog exception. + + Both `glob` and `expand` rely on the same underlying + mechanism. YAP gives preference to `glob`. + + - verbose_file_search(`true`/`false`) + + If `true` (default is `false`) output messages during + search. This is often helpful when debugging. Corresponds to the + SWI-Prolog flag `verbose_file_search` (also available in YAP). + + +Compatibility considerations to common argument-order in ISO as well +as SICStus absolute_file_name/3 forced us to be flexible here. +If the last argument is a list and the second not, the arguments are +swapped, making the call +~~~~~~~~~~~prolog + absolute_file_name(+ _Spec_ , - _Path_ ,+ _Options_ ) +~~~~~~~~~~~ + valid as well. + + +@pred user:library_directory(?Directory:atom) is nondet, dynamic + +Dynamic, multi-file predicate that succeeds when _Directory_ is a +current library directory name. Asserted in the user module. + +Library directories are the places where files specified in the form +`library( _File_ )` are searched by the predicates consult/1, +reconsult/1, use_module/1, ensure_loaded/1, and load_files/2. + +This directory is initialized by a rule that calls the system predicate +system_library/1. diff --git a/pl/attributes.md b/pl/attributes.md index 8e73af4a8..eb005c854 100644 --- a/pl/attributes.md +++ b/pl/attributes.md @@ -27,14 +27,15 @@ 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 Old_Style_Attribute_Declarations ++ @ref attributes + @ref New_Style_Attribute_Declarations + @ref CohYroutining ++ @ref AttributeVariables_Builtins @{ -@defgroup Old_Style_Attribute_Declarations SICStus Style attribute declarations. -@ingroup AttributeDeclarations +@defgroup 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: @@ -98,17 +99,17 @@ these built-ins are rewritten by the system into internal built-ins, and that the rewriting process depends on the module on which the built-ins have been invoked. - + The user-predicate predicate verify_attributes/3 is called when attempting to unify an attributed variable which might have attributes in some _Module_. - + Attributes are usually presented as goals. The following routines are used by built-in predicates such as call_residue/2 and by the Prolog top-level to display attributes: - + Constraint solvers must be able to project a set of constraints to a set of variables. This is useful when displaying the solution to a goal, but may also be used to manipulate computations. The user-defined @@ -199,15 +200,15 @@ Let's test it: domain(X,[1,5,6,7]), domain(Y,[3,4,5,6]), -domain(Z,[1,6,7,8]) ? +domain(Z,[1,6,7,8]) ? yes -| ?- domain(X,[5,6,7,1]), domain(Y,[3,4,5,6]), domain(Z,[1,6,7,8]), +| ?- domain(X,[5,6,7,1]), domain(Y,[3,4,5,6]), domain(Z,[1,6,7,8]), X=Y. Y = X, domain(X,[5,6]), -domain(Z,[1,6,7,8]) ? +domain(Z,[1,6,7,8]) ? yes | ?- domain(X,[5,6,7,1]), domain(Y,[3,4,5,6]), domain(Z,[1,6,7,8]), diff --git a/pl/modules.md b/pl/modules.md new file mode 100644 index 000000000..7c9cccacd --- /dev/null +++ b/pl/modules.md @@ -0,0 +1,337 @@ + +@defgroup YAPModules The YAP Module system + +@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, +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`. + +\subsection Explicit Naming + +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. + +@\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.