module fixes plus add better docs
This commit is contained in:
Vítor Santos Costa
@@ -776,11 +776,13 @@ WARN_LOGFILE =
|
||||
# spaces.
|
||||
# Note: If this tag is empty the current directory is searched.
|
||||
|
||||
INPUT = /Users/vsc/git/yap-6.3/pl/modules.yap
|
||||
# INPUT = /Users/vsc/git/yap-6.3/pl/absf.yap
|
||||
# INPUT = /Users/vsc/git/yap-6.3/packages/ProbLog/problog_learning_lbdd.yap
|
||||
# INPUT = /Users/vsc/git/yap-6.3/packages/cplint/mcintyre.pl
|
||||
#INPUT = /Users/vsc/git/yap-6.3/packages/R/R.pl
|
||||
|
||||
INPUT = docs/yap.md \
|
||||
INPUTX = docs/yap.md \
|
||||
pl \
|
||||
C \
|
||||
H \
|
||||
@@ -868,7 +870,7 @@ RECURSIVE = YES
|
||||
# Note that relative paths are relative to the directory from which doxygen is
|
||||
# run.
|
||||
|
||||
EXCLUDE = *pltotex.pl
|
||||
EXCLUDE = *pltotex.pl packages/swig/android
|
||||
|
||||
# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
|
||||
# directories that are symbolic links (a Unix file system feature) are excluded
|
||||
|
||||
318
docs/yap.md
318
docs/yap.md
@@ -10,8 +10,10 @@ This file documents the YAP Prolog System version 6.3.4, a high-performance Prol
|
||||
+ @subpage Run describes how to invoke YAP
|
||||
|
||||
+ @subpage Loading_Programs presents the main predicates and
|
||||
directives available to load files and to control the Prolog environment.
|
||||
+ @subpage abs_file_name explains how to find a file full path.
|
||||
directives available to load files and to control the Prolog environment.
|
||||
+ @ref yapmodules introduces the YAP module system and meta-predicates.
|
||||
|
||||
+ @ref absf0 explains how to find a file full path.
|
||||
|
||||
+ @subpage BuilthYins describes predicates providing core YAP
|
||||
functionality. Examples include
|
||||
@@ -1510,7 +1512,7 @@ if it is `source` clauses are compiled and source code is stored;
|
||||
if it is `assert_all` clauses are asserted into the data-base.
|
||||
|
||||
</li>
|
||||
<li>comnsult(+ _Mode_)
|
||||
<li>consult(+ _Mode_)
|
||||
This extension controls the type of file to load. If _Mode_
|
||||
is `consult`, clauses are added to the data-base,
|
||||
is `reconsult`, clauses are recompiled,
|
||||
@@ -1986,7 +1988,7 @@ defined, or search the default library directory.
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
@section Modules The Module System
|
||||
@section old_Modules The Module System
|
||||
|
||||
Module systems are quite important for the development of large
|
||||
applications. YAP implements a module system compatible with the Quintus
|
||||
@@ -2006,314 +2008,6 @@ YAP allows one to ignore the module system if one does not want to use
|
||||
it. Last note that using the module system does not introduce any
|
||||
significant overheads.
|
||||
|
||||
@subsection Module_Concepts Module Concepts
|
||||
|
||||
The YAP module system applies to predicates. All predicates belong to a
|
||||
module. System predicates belong to the module `primitives`, and by
|
||||
default new predicates belong to the module `user`. Predicates from
|
||||
the module `primitives` are automatically visible to every module.
|
||||
|
||||
Every predicate must belong to a module. This module is called its
|
||||
<em>source module</em>.
|
||||
|
||||
By default, the source module for a clause occurring in a source file
|
||||
with a module declaration is the declared module. For goals typed in
|
||||
a source file without module declarations, their module is the module
|
||||
the file is being loaded into. If no module declarations exist, this is
|
||||
the current <em>type-in module</em>. The default type-in module is
|
||||
`user`, but one can set the current module by using the built-in
|
||||
`module/1`.
|
||||
|
||||
Note that in this module system one can explicitly specify the source
|
||||
mode for a clause by prefixing a clause with its module, say:
|
||||
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
user:(a :- b).
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
In fact, to specify the source module for a clause it is sufficient to
|
||||
specify the source mode for the clause's head:
|
||||
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
user:a :- b.
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The rules for goals are similar. If a goal appears in a text file with a
|
||||
module declaration, the goal's source module is the declared
|
||||
module. Otherwise, it is the module the file is being loaded into or the
|
||||
type-in module.
|
||||
|
||||
One can override this rule by prefixing a goal with the module it is
|
||||
supposed to be executed in, say:
|
||||
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
nasa:launch(apollo,13).
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
will execute the goal `launch(apollo,13)` as if the current source
|
||||
module was `nasa`.
|
||||
|
||||
Note that this rule breaks encapsulation and should be used with care.
|
||||
|
||||
@subsection Defining_Modules Defining a New Module
|
||||
|
||||
A new module is defined by a `module` declaration:
|
||||
|
||||
<ul>
|
||||
|
||||
<li>module(+ _M_,+ _L_) @anchor module
|
||||
|
||||
|
||||
This directive defines the file where it appears 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 public predicates of a module file can be made accessible by other
|
||||
files through the directives [use_module/1](@ref use_module), `use_module/2`,
|
||||
[ensure_loaded/1](@ref ensure_loaded) and the predicates [consult/1](@ref consult) or
|
||||
[reconsult/1](@ref reconsult). The non-public predicates
|
||||
of a module file are not visible by other files; they can, however, be
|
||||
accessed by prefixing the module name with the
|
||||
`:/2` operator.
|
||||
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
The built-in `module/1` sets the current source module:
|
||||
|
||||
<ul>
|
||||
|
||||
<li>module(+ _M_,+ _L_, + _Options_)
|
||||
|
||||
Similar to [module/2](@ref module), 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:
|
||||
|
||||
<ul>
|
||||
<li>filename
|
||||
the filename for a module to import into the current module.
|
||||
|
||||
</li>
|
||||
<li>library(file)
|
||||
a library file to import into the current module.
|
||||
|
||||
</li>
|
||||
<li>hide( _Opt_)
|
||||
if _Opt_ is `false`, keep source code for current module, if
|
||||
`true`, disable.
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
</li>
|
||||
<li>module(+ _M_)
|
||||
|
||||
Defines _M_ to be the current working or type-in module. All files
|
||||
which are not bound to a module are assumed to belong to the working
|
||||
module (also referred to as type-in module). To compile a non-module
|
||||
file into a module which is not the working one, prefix the file name
|
||||
with the module name, in the form ` _Module_: _File_`, when
|
||||
loading the file.
|
||||
|
||||
</li>
|
||||
<li>export(+ _PredicateIndicator_) @anchor export
|
||||
|
||||
|
||||
|
||||
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,2]`. Note that predicates are normally
|
||||
exported using the directive [module/2](@ref module). [export/1](@ref export) is meant
|
||||
to handle export from dynamically created modules. The directive argument
|
||||
may also be a list of predicates.
|
||||
|
||||
</li>
|
||||
<li>export_list(? _Mod_,? _ListOfPredicateIndicator_) @anchor export_list
|
||||
|
||||
|
||||
|
||||
The list _ListOfPredicateIndicator_ contains all predicates exported
|
||||
by module _Mod_.
|
||||
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
@subsection Using_Modules Using Modules
|
||||
|
||||
By default, all procedures to consult a file will load the modules
|
||||
defined therein. The two following declarations allow one to import a
|
||||
module explicitly. They differ on whether one imports all predicate
|
||||
declared in the module or not.
|
||||
|
||||
<ul>
|
||||
|
||||
<li>use_module(+ _F_) @anchor use_module
|
||||
|
||||
|
||||
Loads the files specified by _F_, importing all their public
|
||||
predicates. Predicate name clashes are resolved by asking the user about
|
||||
importing or not the predicate. A warning is displayed when _F_ is
|
||||
not a module file.
|
||||
|
||||
</li>
|
||||
<li>use_module(+ _F_,+ _L_)
|
||||
|
||||
Loads the files specified by _F_, importing the predicates specified
|
||||
in the list _L_. Predicate name clashes are resolved by asking the
|
||||
user about importing or not the predicate. A warning is displayed when
|
||||
_F_ is not a module file.
|
||||
|
||||
</li>
|
||||
<li>use_module(? _M_,? _F_,+ _L_)
|
||||
|
||||
If module _M_ has been defined, import the procedures in _L_ to
|
||||
the current module. Otherwise, load the files specified by _F_,
|
||||
importing the predicates specified in the list _L_.
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
@subsection MetahYPredicates_in_Modules Meta-Predicates and Modules
|
||||
|
||||
The module system must know whether predicates operate on goals or
|
||||
clauses. Otherwise, such predicates would call a goal in the module they
|
||||
were defined, instead of calling it in the module they are currently
|
||||
executing. So, for instance, consider a file example.pl:
|
||||
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
:- module(example,[a/1]).
|
||||
|
||||
a(G) :- call(G)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
We import this module with `use_module(example)` into module
|
||||
`user`. The expected behavior for a goal `a(p)` is to
|
||||
execute goal `p` within the module `user`. However,
|
||||
`a/1` will call `p` within module `example`.
|
||||
|
||||
The [meta_predicate/1](@ref meta_predicate) declaration informs the system that some
|
||||
arguments of a predicate are goals, clauses, clauses heads or other
|
||||
terms related to a module, and that these arguments must be prefixed
|
||||
with the current source module:
|
||||
|
||||
<ul>
|
||||
|
||||
<li>meta_predicate _G1_,...., _Gn_ @anchor meta_predicate
|
||||
|
||||
|
||||
Each _Gi_ is a mode specification.
|
||||
|
||||
If the argument is `:`, it does not refer directly to a predicate
|
||||
but must be module expanded. If the argument is an integer, the argument
|
||||
is a goal or a closure and must be expanded. Otherwise, the argument is
|
||||
not expanded. Note that the system already includes declarations for all
|
||||
built-ins.
|
||||
|
||||
For example, the declaration for [call/1](@ref call) and [setof/3](@ref setof) are:
|
||||
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
:- meta_predicate call(0), setof(?,0,?).
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
The previous example is expanded to the following code which explains,
|
||||
why the goal `a(p)` calls `p` in `example` and not in
|
||||
`user`. The goal `call(G)` is expanded because of the
|
||||
meta-predicate declaration for [call/1](@ref call).
|
||||
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
:- module(example,[a/1]).
|
||||
|
||||
a(G) :- call(example:G)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
By adding a meta-predicate declaration for `a/1`, the goal
|
||||
`a(p)` in module user will be expanded to `a(user:p)`
|
||||
thereby preserving the module information.
|
||||
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
:- module(example,[a/1]).
|
||||
|
||||
:- meta_predicate a(:).
|
||||
a(G) :- call(G)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
An alternate mechanism is the directive [module_transparent/1](@ref module_transparent)
|
||||
offered for compatibility with SWI-Prolog.
|
||||
|
||||
<ul>
|
||||
|
||||
<li>module_transparent + _Preds_ @anchor module_transparent
|
||||
|
||||
|
||||
_Preds_ is a comma separated sequence of name/arity predicate
|
||||
indicators (like
|
||||
[dynamic/1](@ref dynamic)). Each goal associated with a transparent declared
|
||||
predicate will inherit the context module from its parent goal.
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
@subsection RehYExporting_Modules Re-Exporting Predicates From Other Modules
|
||||
|
||||
It is sometimes convenient to re-export predicates originally defined in
|
||||
a different module. This is often useful if you are adding to the
|
||||
functionality of a module, or if you are composing a large module with
|
||||
several small modules. The following declarations can be used for that purpose:
|
||||
|
||||
<ul>
|
||||
|
||||
<li>reexport(+ _F_) @anchor reexport
|
||||
|
||||
|
||||
Export all predicates defined in file _F_ as if they were defined in
|
||||
the current module.
|
||||
|
||||
</li>
|
||||
<li>reexport(+ _F_,+ _Decls_)
|
||||
|
||||
Export predicates defined in file _F_ according to _Decls_. The
|
||||
declarations may be of the form:
|
||||
|
||||
<ul>
|
||||
<li>A list of predicate declarations to be exported. Each declaration
|
||||
may be a predicate indicator or of the form `` _PI_ `as`
|
||||
_NewName_'', meaning that the predicate with indicator _PI_ is
|
||||
to be exported under name _NewName_.
|
||||
</li>
|
||||
<li>`except`( _List_)
|
||||
In this case, all predicates not in _List_ are exported. Moreover,
|
||||
if ` _PI_ `as` _NewName_` is found, the predicate with
|
||||
indicator _PI_ is to be exported under name _NewName_ as
|
||||
before.
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
Re-exporting predicates must be used with some care. Please, take into
|
||||
account the following observations:
|
||||
|
||||
<ul>
|
||||
<li>
|
||||
The `reexport` declarations must be the first declarations to
|
||||
follow the `module` declaration.
|
||||
</li>
|
||||
<li>
|
||||
It is possible to use both `reexport` and `use_module`, but
|
||||
all predicates reexported are automatically available for use in the
|
||||
current module.
|
||||
</li>
|
||||
<li>
|
||||
In order to obtain efficient execution, YAP compiles dependencies
|
||||
between re-exported predicates. In practice, this means that changing a
|
||||
`reexport` declaration and then *just* recompiling the file
|
||||
may result in incorrect execution.
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
@page BuilthYins Built-In Predicates Library
|
||||
|
||||
|
||||
Reference in New Issue
Block a user