This repository has been archived on 2023-08-20. You can view files and clone it, but cannot push or open issues or pull requests.
yap-6.3/docs/load.tex
Vítor Santos Costa 137f69ed22 doc support
2014-04-21 11:14:18 +01:00

1033 lines
34 KiB
TeX

@c -*- mode: texinfo; coding: utf-8; -*-
@node Loading Programs, Modules, Syntax, Top
@chapter Loading and Manipulating Programs
@menu
Loading Programs
* Compiling:: Program Loading and Updating
* Setting the Compiler:: Changing the compiler's parameters
* Conditional Compilation:: Compiling program fragments
* Saving:: Saving and Restoring Programs
@end menu
Next, we present the main predicates and directives available to load
files and to control the Prolog environment.
@node Compiling, Setting the Compiler, , Loading Programs
@section Program loading and updating
@table @code
@item consult(+@var{F})
@findex consult/1
@snindex consult/1
@cyindex consult/1
Adds the clauses written in file @var{F} or in the list of files @var{F}
to the program.
In YAP @code{consult/1} does not remove previous clauses for
the procedures defined in @var{F}. Moreover, note that all code in YAP
is compiled.
@item reconsult(+@var{F})
@findex reconsult/1
@snindex reconsult/1
@cyindex reconsult/1
Updates the program replacing the
previous definitions for the predicates defined in @var{F}.
@item [+@var{F}]
@findex nil/1
@saindex []/1
@cyindex []/1
The same as @code{consult(F)}.
@item [-+@var{F}]
@findex dash_nil/1
@saindex [-]/1
@cyindex [-]/1
The same as @code{reconsult(F)}
Example:
@example
?- [file1, -file2, -file3, file4].
@end example
@noindent
will consult @code{file1} @code{file4} and reconsult @code{file2} and
@code{file3}.
@item compile(+@var{F})
@findex compile/1
@syindex compile/1
@cnindex compile/1
@noindent
In YAP, the same as @code{reconsult/1}.
@item load_files(+@var{Files}, +@var{Options})
@findex load_files/2
@syindex load_files/2
@cnindex load_files/2
@noindent
General implementation of @code{consult}. Execution is controlled by the
following flags:
@table @code
@item autoload(+@var{Autoload})
SWI-compatible option where if @var{Autoload} is @code{true} predicates
are loaded on first call. Currently
not supported.
@item derived_from(+@var{File})
SWI-compatible option to control make. Currently
not supported.
@item encoding(+@var{Encoding})
Character encoding used in consulting files. Please @pxref{Encoding} for
supported encodings.
@item expand(+@var{Bool})
Not yet implemented. In SWI-Prolog, if @code{true}, run the
filenames through @code{expand_file_name/2} and load the returned
files. Default is false, except for @code{consult/1} which is
intended for interactive use.
@item if(+@var{Condition})
Load the file only if the specified @var{Condition} is
satisfied. The value @code{true} the file unconditionally,
@code{changed} loads the file if it was not loaded before, or has
been modified since it was loaded the last time, @code{not_loaded}
loads the file if it was not loaded before.
@item imports(+@var{ListOrAll})
If @code{all} and the file is a module file, import all public
predicates. Otherwise import only the named predicates. Each
predicate is referred to as @code{<name>/<arity>}. This option has
no effect if the file is not a module file.
@item must_be_module(+@var{Bool})
If true, raise an error if the file is not a module file. Used by
@code{use_module/[1,2]}.
@c qcompile(Bool)
@c If this call appears in a directive of a file that is compiled into Quick Load Format using qcompile/1 and this flag is true, the contents of the argument files are included in the .qlf file instead of the loading directive.
@item silent(+@var{Bool})
If true, load the file without printing a message. The specified value is the default for all files loaded as a result of loading the specified files.
@item stream(+@var{Input})
This SWI-Prolog extension compiles the data from the stream
@var{Input}. If this option is used, @var{Files} must be a single
atom which is used to identify the source-location of the loaded
clauses as well as remove all clauses if the data is re-consulted.
This option is added to allow compiling from non-file locations such as databases, the web, the user (see consult/1) or other servers.
@item compilation_mode(+@var{Mode})
This extension controls how procedures are compiled. If @var{Mode}
is @code{compact} clauses are compiled and no source code is stored;
if it is @code{source} clauses are compiled and source code is stored;
if it is @code{assert_all} clauses are asserted into the data-base.
@item comnsult(+@var{Mode})
This extension controls the type of file to load. If @var{Mode}
is @code{consult}, clauses are added to the data-base,
is @code{reconsult}, clauses are recompiled,
is @code{db}, these are facts that need to be added to the data-base,
is @code{exo}, these are facts with atoms and integers that need a very compact representation.
@end table
@item ensure_loaded(+@var{F}) [ISO]
@findex ensure_loaded/1
@syindex compile/1
@cnindex compile/1
When the files specified by @var{F} are module files,
@code{ensure_loaded/1} loads them if they have note been previously
loaded, otherwise advertises the user about the existing name clashes
and prompts about importing or not those predicates. Predicates which
are not public remain invisible.
When the files are not module files, @code{ensure_loaded/1} loads them
if they have not been loaded before, does nothing otherwise.
@var{F} must be a list containing the names of the files to load.
@item load_db(+@var{Files})
@findex load_db/1
@syindex load_db/1
@cnindex load_db/1
@noindent
Load a database of facts with equal structure.
@item exo_files(+@var{Files})
@findex exo_files/1
@syindex exo_files/1
@cnindex exo_files/1
@noindent
Load compactly a database of facts with equal structure. Useful when wanting to
read in a very compact way database tables.
@item make
@findex make/0
@snindex make/0
@cnindex make/0
SWI-Prolog built-in to consult all source files that have been
changed since they were consulted. It checks all loaded source
files. make/0 can be combined with the compiler to speed up the
development of large packages. In this case compile the package
using
@example
sun% pl -g make -o my_program -c file ...
@end example
If `my_program' is started it will first reconsult all source files
that have changed since the compilation.
@item include(+@var{F}) [ISO]
@findex include/1 (directive)
@snindex compile/1 (directive)
@cnindex compile/1 (directive)
The @code{include} directive includes the text files or sequence of text
files specified by @var{F} into the file being currently consulted.
@end table
@node Setting the Compiler, Conditional Compilation, Compiling, Loading Programs
@section Looking for Files
@ifplaintext
@ref abs_file_name
@end ifplaintext
@section Changing the Compiler's Behavior
This section presents a set of built-ins predicates designed to set the
environment for the compiler.
@table @code
@item source_mode(-@var{O},+@var{N})
@findex source_mode/2
@snindex source_mode/2
@cnindex source_mode/2
The state of source mode can either be on or off. When the source mode
is on, all clauses are kept both as compiled code and in a "hidden"
database. @var{O} is unified with the previous state and the mode is set
according to @var{N}.
@item source
@findex source/0
@snindex source/0
@cnindex source/0
After executing this goal, YAP keeps information on the source
of the predicates that will be consulted. This enables the use of
@code{listing/0}, @code{listing/1} and @code{clause/2} for those
clauses.
The same as @code{source_mode(_,on)} or as declaring all newly defined
static procedures as @code{public}.
@item no_source
@findex no_source/0
@snindex no_source/0
@cnindex no_source/0
The opposite to @code{source}.
The same as @code{source_mode(_,off)}.
@item compile_expressions
@findex compile_expressions/0
@snindex compile_expressions/0
@cnindex compile_expressions/0
After a call to this predicate, arithmetical expressions will be compiled.
(see example below). This is the default behavior.
@item do_not_compile_expressions
@findex do_not_compile_expressions/0
@snindex do_not_compile_expressions/0
@cnindex do_not_compile_expressions/0
After a call to this predicate, arithmetical expressions will not be compiled.
@example
?- source, do_not_compile_expressions.
yes
?- [user].
| p(X) :- X is 2 * (3 + 8).
| :- end_of_file.
?- compile_expressions.
yes
?- [user].
| q(X) :- X is 2 * (3 + 8).
| :- end_of_file.
:- listing.
p(A):-
A is 2 * (3 + 8).
q(A):-
A is 22.
@end example
@item hide(+@var{Atom})
@findex hide/1
@snindex hide/1
@cnindex hide/1
Make atom @var{Atom} invisible.
@item unhide(+@var{Atom})
@findex unhide/1
@snindex unhide/1
@cnindex unhide/1
Make hidden atom @var{Atom} visible.
@item hide_predicate(+@var{Pred})
@findex hide_predicate/1
@snindex hide_predicate/1
@cnindex hide_predicate/1
Make predicate @var{Pred} invisible to @code{current_predicate/2},
@code{listing}, and friends.
@item stash_predicate(+@var{Pred})
@findex stash_predicate/1
@snindex stash_predicate/1
@cnindex stash_predicate/1
Make predicate @var{Pred} invisible to new code, and to @code{current_predicate/2},
@code{listing}, and friends. New predicates with the same name and
functor can be declared.
@item expand_exprs(-@var{O},+@var{N})
@findex expand_exprs/2
@snindex expand_exprs/2
@cyindex expand_exprs/2
Puts YAP in state @var{N} (@code{on} or @code{off}) and unify
@var{O} with the previous state, where @var{On} is equivalent to
@code{compile_expressions} and @code{off} is equivalent to
@code{do_not_compile_expressions}. This predicate was kept to maintain
compatibility with C-Prolog.
@texinfo
@item path(-@var{D})
@findex path/1
@snindex path/1
@cnindex path/1
Unifies @var{D} with the current directory search-path of YAP.
Note that this search-path is only used by YAP to find the
files for @code{consult/1}, @code{reconsult/1} and @code{restore/1} and
should not be taken for the system search path.
@item add_to_path(+@var{D})
@findex add_to_path/1
@snindex path/1
@cnindex path/1
Adds @var{D} to the end of YAP's directory search path.
@item add_to_path(+@var{D},+@var{N})
@findex add_to_path/2
@snindex path/1
@cnindex path/1
Inserts @var{D} in the position, of the directory search path of
YAP, specified by @var{N}. @var{N} must be either of
@code{first} or @code{last}.
@item remove_from_path(+@var{D})
@findex remove_from_path/1
@snindex remove_from_path/1
@cnindex remove_from_path/1
Remove @var{D} from YAP's directory search path.
@end texinfo
@item style_check(+@var{X})
@findex style_check/1
@snindex style_check/1
@cnindex style_check/1
Turns on style checking according to the attribute specified by @var{X},
which must be one of the following:
@table @code
@item single_var
Checks single occurrences of named variables in a clause.
@item discontiguous
Checks non-contiguous clauses for the same predicate in a file.
@item multiple
Checks the presence of clauses for the same predicate in more than one
file when the predicate has not been declared as @code{multifile}
@item all
Performs style checking for all the cases mentioned above.
@end table
By default, style checking is disabled in YAP unless we are in
@code{sicstus} or @code{iso} language mode.
The @code{style_check/1} built-in is now deprecated. Please use the
@code{set_prolog_flag/1} instead.
@item no_style_check(+@var{X})
@findex no_style_check/1
@snindex style_check/1
@cnindex style_check/1
Turns off style checking according to the attribute specified by
@var{X}, which has the same meaning as in @code{style_check/1}.
The @code{no_style_check/1} built-in is now deprecated. Please use the
@code{set_prolog_flag/1} instead.
@item multifile @var{P} [ISO]
@findex multifile/1 (directive)
@syindex multifile/1 (directive)
@cnindex multifile/1 (directive)
Instructs the compiler about the declaration of a predicate @var{P} in
more than one file. It must appear in the first of the loaded files
where the predicate is declared, and before declaration of any of its
clauses.
Multifile declarations affect @code{reconsult/1} and @code{compile/1}:
when a multifile predicate is reconsulted, only the clauses from the
same file are removed.
Since YAP4.3.0 multifile procedures can be static or dynamic.
@item discontiguous(+@var{G}) [ISO]
@findex discontiguous/1 (directive)
@syindex discontiguous/1 (directive)
@cnindex discontiguous/1 (directive)
Declare that the arguments are discontiguous procedures, that is,
clauses for discontigous procedures may be separated by clauses from
other procedures.
@item initialization(+@var{G}) [ISO]
@findex initialization/1 (directive)
@snindex initialization/1 (directive)
@cnindex initialization/1 (directive)
The compiler will execute goals @var{G} after consulting the current
file.
@item initialization(+@var{Goal},+@var{When})
@findex initialization/2 (directive)
@snindex initialization/2 (directive)
@cnindex initialization/2 (directive)
Similar to @code{initialization/1}, but allows for specifying when
@var{Goal} is executed while loading the program-text:
@table @code
@item now
Execute @var{Goal} immediately.
@item after_load
Execute @var{Goal} after loading program-text. This is the same as initialization/1.
@item restore
Do not execute @var{Goal} while loading the program, but only when
restoring a state (not implemented yet).
@end table
@texinfo
@item library_directory(+@var{D})
@findex library_directory/1
@snindex library_directory/1
@cnindex library_directory/1
Succeeds when @var{D} is a current library directory name. Library
directories are the places where files specified in the form
@code{library(@var{File})} are searched by the predicates
@code{consult/1}, @code{reconsult/1}, @code{use_module/1} or
@code{ensure_loaded/1}.
@item file_search_path(+@var{NAME},-@var{DIRECTORY})
@findex file_search_path/2
@syindex file_search_path/2
@cnindex file_search_path/2
Allows writing file names as compound terms. The @var{NAME} and
@var{DIRECTORY} must be atoms. The predicate may generate multiple
solutions. The predicate is originally defined as follows:
@example
file_search_path(library,A) :-
library_directory(A).
file_search_path(system,A) :-
prolog_flag(host_type,A).
@end example
Thus, @code{[library(A)]} will search for a file using
@code{library_directory/1} to obtain the prefix.
@item prolog_file_name(+@var{Name},-@var{FullPath})
@findex prolog_file_name/2
@syindex prolog_file_name/1
@cnindex prolog_file_name/2
Unify @var{FullPath} with the absolute path YAP would use to consult
file @var{Name}.
@end texinfo
@item prolog_to_os_filename(+@var{PrologPath},-@var{OsPath})
@findex prolog_to_os_filename/2
@snindex prolog_to_os_filename/2
@cnindex prolog_to_os_filename/2
This is an SWI-Prolog built-in. Converts between the internal Prolog
pathname conventions and the operating-system pathname conventions. The
internal conventions are Unix and this predicates is equivalent to =/2
(unify) on Unix systems. On DOS systems it will change the
directory-separator, limit the filename length map dots, except for the
last one, onto underscores.
@item expand_file_name(+@var{WildCard},-@var{List})
@findex expand_file_name/2
@snindex expand_file_name/2
@cnindex expand_file_name/2
This is an SWI-Prolog built-in. Unify @var{List} with a sorted list of
files or directories matching @var{WildCard}. The normal Unix wildcard
constructs @t{?}, @t{*}, @t{[ ... ]} and @t{@{...@}} are recognised. The
interpretation of @t{@{...@}} is interpreted slightly different from the
C shell (csh(1)). The comma separated argument can be arbitrary
patterns, including @t{@{...@}} patterns. The empty pattern is legal as
well: @t{@{.pl,@}} matches either @t{.pl} or the empty string.
If the pattern contains wildcard characters, only existing files and
directories are returned. Expanding a @emph{pattern'} without wildcard
characters returns the argument, regardless on whether or not it exists.
Before expanding wildcards, the construct $var is expanded to the value
of the environment variable var and a possible leading ~ character is
expanded to the user's home directory. In Windows, the home directory is
determined as follows: if the environment variable @code{HOME} exists,
this is used. If the variables @code{HOMEDRIVE} and @code{HOMEPATH}
exist (Windows-NT), these are used. At initialisation, the system will
set the environment variable @code{HOME} to point to the YAP home
directory if neither @code{HOME} nor @code{HOMEPATH} and
@code{HOMEDRIVE} are defined.
@item public @var{P} [ISO extension]
@findex public/1 (directive)
@snindex public/1 (directive)
@cnindex public/1 (directive)
Instructs the compiler that the source of a predicate of a list of
predicates @var{P} must be kept. This source is then accessible through
the @code{clause/2} procedure and through the @code{listing} family of
built-ins.
Note that all dynamic procedures are public. The @code{source} directive
defines all new or redefined predicates to be public.
Since YAP4.3.0 multifile procedures can be static or dynamic.
@end table
@node Conditional Compilation, Saving, Setting the Compiler, Loading Programs
@section Conditional Compilation
@c \index{if, directive}%
Conditional compilation builds on the same principle as
@code{term_expansion/2}, @code{goal_expansion/2} and the expansion of
grammar rules to compile sections of the source-code
conditionally. One of the reasons for introducing conditional
compilation is to simplify writing portable code.
@c See \secref{dialect}
@c for more information. Here is a simple example:
@c @table code
@c :- if(\+source_exports(library(lists), suffix/2)).
@c suffix(Suffix, List) :-
@c append(_, Suffix, List).
@c :- endif.
@c \end{code}
Note that these directives can only be appear as separate terms in the
input. Typical usage scenarios include:
@itemize @bullet
@item Load different libraries on different dialects
@item Define a predicate if it is missing as a system predicate
@item Realise totally different implementations for a particular
part of the code due to different capabilities.
@item Realise different configuration options for your software.
@end itemize
@table @code
@item if(+@var{Goal})
@findex if/1 directive
@snindex if/1
@cnindex if/1
Compile subsequent code only if @var{Goal} succeeds. For enhanced
portability, @var{Goal} is processed by @code{expand_goal/2} before execution.
If an error occurs, the error is printed and processing proceeds as if
@var{Goal} has failed.
@item else
@findex else/0 directive
@snindex else/0
@cnindex else/0
Start `else' branch.
@item endif
@findex endif/0 directive
@snindex endif/0
@cnindex endif/0
End of conditional compilation.
@item elif(+@var{Goal})
@findex elif/1 directive
@snindex elif/1
@cnindex elif/1
Equivalent to @code{:- else. :-if(Goal) ... :- endif.} In a sequence
as below, the section below the first matching elif is processed, If
no test succeeds the else branch is processed.
@example
:- if(test1).
section_1.
:- elif(test2).
section_2.
:- elif(test3).
section_3.
:- else.
section_else.
:- endif.
@end example
@end table
@node Saving, , Conditional Compilation, Loading Programs
@section Saving and Loading Prolog States
@table @code
@item save(+@var{F})
@findex save/1
@snindex save/1
@cyindex save/1
Saves an image of the current state of YAP in file @var{F}. From
@strong{YAP4.1.3} onwards, YAP saved states are executable
files in the Unix ports.
@item save(+@var{F},-@var{OUT})
@findex save/2
@snindex save/2
@cnindex save/2
Saves an image of the current state of YAP in file @var{F}. From
@strong{YAP4.1.3} onwards, YAP saved states are executable
files in the Unix ports.
Unify @var{OUT} with 1 when saving the file and @var{OUT} with 0 when
restoring the saved state.
@item save_program(+@var{F})
@findex save_program/1
@syindex save_program/1
@cnindex save_program/1
Saves an image of the current state of the YAP database in file
@var{F}.
@item save_program(+@var{F}, :@var{G})
@findex save_program/2
@syindex save_program/2
@cnindex save_program/2
Saves an image of the current state of the YAP database in file
@var{F}, and guarantee that execution of the restored code will start by
trying goal @var{G}.
@item qsave_program(+@var{F}, +@var{ListOfOpts})
@findex qsave_program/2
@syindex qsave_program/2
@cnindex qsave_program/2
Saves the current state of the program to the file @var{File}. The
result is a resource archive containing a saved state that expresses
all Prolog data from the running program and all user-defined
resources. Depending on the stand_alone option, the resource is headed
by the emulator, a Unix shell script or nothing. Options is a list of
additional options:
@table @code
@item stack(+@var{KBytes})
Limit for the local and global stack.
@item trail(+@var{KBytes})
Limit for the trail stack.
@item goal(:@var{Callable})
Initialization goal for the new executable (see -g).
@c @item toplevel(:@var{Callable})
@c Top-level goal for the new executable (see -t).
@item init_file(+@var{Atom})
Default initialization file for the new executable. See -f.
@c class(+Class)
@c If runtime, only read resources from the state (default). If kernel, lock all predicates as system predicates. If development, save the predicates in their current state and keep reading resources from their source (if present). See also resource/3.
@c autoload(+Boolean)
@c If true (default), run autoload/0 first.
@c map(+File)
@c Dump a human-readable trace of what has been saved in File.
@c op(+Action)
@c One of save (default) to save the current operator table or standard to use the initial table of the emulator.
@c stand_alone(+Boolean)
@c If true, the emulator is the first part of the state. If the emulator is started it will test whether a boot-file (state) is attached to the emulator itself and load this state. Provided the application has all libraries loaded, the resulting executable is completely independent of the runtime environment or location where it was built. See also section 2.10.2.4.
@c emulator(+File)
@c File to use for the emulator. Default is the running Prolog image.
@c foreign(+Action)
@c If save, include shared objects (DLLs) into the saved state. See current_foreign_library/2. If the program strip is available, this is first used to reduce the size of the shared object. If a state is started, use_foreign_library/1 first tries to locate the foreign resource in the executable. When found it copies the content of the resource to a temporary file and loads it. If possible (Unix), the temporary object is deleted immediately after opening.106
@end table
@item restore(+@var{F})
@findex restore/1
@syindex restore/1
@cnindex restore/1
Restores a previously saved state of YAP from file @var{F}.
YAP always tries to find saved states from the current directory
first. If it cannot it will use the environment variable @code{YAPLIBDIR}, if
defined, or search the default library directory.
@end table
@node Modules, Built-ins, Loading Programs, Top
@section The Module System
Module systems are quite important for the development of large
applications. YAP implements a module system compatible with the Quintus
Prolog module system.
The YAP module system is predicate-based. This means a module consists
of a set of predicates (or procedures), such that some predicates are
public and the others are local to a module. Atoms and terms in general
are global to the system. Moreover, the module system is flat, meaning
that we do not support a hierarchy of modules. Modules can
automatically import other modules, though. For compatibility with other
module systems the YAP module system is non-strict, meaning both that
there is a way to access predicates private to a module and that it
is possible to declare predicates for a module from some other module.
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.
@menu
* Module Concepts:: The Key Ideas in Modules
* Defining Modules:: How To Define a New Module
* Using Modules:: How to Use a Module
* Meta-Predicates in Modules:: How to Handle New Meta-Predicates
* Re-Exporting Modules:: How to Re-export Predicates From Other Modules
@end menu
@node Module Concepts, Defining Modules, , Modules
@subsection Module Concepts
The YAP module system applies to predicates. All predicates belong to a
module. System predicates belong to the module @code{primitives}, and by
default new predicates belong to the module @code{user}. Predicates from
the module @code{primitives} are automatically visible to every module.
Every predicate must belong to a module. This module is called its
@emph{source module}.
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 @emph{type-in module}. The default type-in module is
@code{user}, but one can set the current module by using the built-in
@code{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:
@example
user:(a :- b).
@end example
@noindent
In fact, to specify the source module for a clause it is sufficient to
specify the source mode for the clause's head:
@example
user:a :- b.
@end example
@noindent
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:
@example
nasa:launch(apollo,13).
@end example
will execute the goal @code{launch(apollo,13)} as if the current source
module was @code{nasa}.
Note that this rule breaks encapsulation and should be used with care.
@node Defining Modules, Using Modules, Module Concepts, Modules
@subsection Defining a New Module
A new module is defined by a @code{module} declaration:
@table @code
@item module(+@var{M},+@var{L})
@findex module/2 (directive)
@syindex module/2 (directive)
@cnindex module/2 (directive)
This directive defines the file where it appears as a module file; it
must be the first declaration in the file.
@var{M} must be an atom specifying the module name; @var{L} must be a list
containing the module's public predicates specification, in the form
@code{[predicate_name/arity,...]}.
The public predicates of a module file can be made accessible by other
files through the directives @code{use_module/1}, @code{use_module/2},
@code{ensure_loaded/1} and the predicates @code{consult/1} or
@code{reconsult/1}. 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
@code{:/2} operator.
@end table
The built-in @code{module/1} sets the current source module:
@table @code
@item module(+@var{M},+@var{L}, +@var{Options})
@findex module/3 (directive)
@syindex module/3 (directive)
@cnindex module/3 (directive)
Similar to @code{module/2}, this directive defines the file where it
appears in as a module file; it must be the first declaration in the file.
@var{M} must be an atom specifying the module name; @var{L} must be a
list containing the module's public predicates specification, in the
form @code{[predicate_name/arity,...]}.
The last argument @var{Options} must be a list of options, which can be:
@table @code
@item filename
the filename for a module to import into the current module.
@item library(file)
a library file to import into the current module.
@item hide(@var{Opt})
if @var{Opt} is @code{false}, keep source code for current module, if
@code{true}, disable.
@end table
@item module(+@var{M})
@findex module/1
@syindex module/1
@cnindex module/1
Defines @var{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 @code{@var{Module}:@var{File}}, when
loading the file.
@item export(+@var{PredicateIndicator})
@findex export/1
@snindex export/1
@cnindex export/1
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 @code{use_module/[1,2]}. Note that predicates are normally
exported using the directive @code{module/2}. @code{export/1} is meant
to handle export from dynamically created modules. The directive argument
may also be a list of predicates.
@item export_list(?@var{Mod},?@var{ListOfPredicateIndicator})
@findex export_list/2
@snindex export_list/2
@cnindex export_list/2
The list @var{ListOfPredicateIndicator} contains all predicates exported
by module @var{Mod}.
@end table
@node Using Modules, Meta-Predicates in Modules, Defining Modules, Modules
@subsection 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.
@table @code
@item use_module(+@var{F})
@findex use_module/1
@syindex use_module/1
@cnindex use_module/1
Loads the files specified by @var{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 @var{F} is
not a module file.
@item use_module(+@var{F},+@var{L})
@findex use_module/2
@syindex use_module/2
@cnindex use_module/2
Loads the files specified by @var{F}, importing the predicates specified
in the list @var{L}. Predicate name clashes are resolved by asking the
user about importing or not the predicate. A warning is displayed when
@var{F} is not a module file.
@item use_module(?@var{M},?@var{F},+@var{L})
@findex use_module/3
@syindex use_module/3
@cnindex use_module/3
If module @var{M} has been defined, import the procedures in @var{L} to
the current module. Otherwise, load the files specified by @var{F},
importing the predicates specified in the list @var{L}.
@end table
@node Meta-Predicates in Modules, Re-Exporting Modules, Using Modules, Modules
@subsection 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:
@example
:- module(example,[a/1]).
a(G) :- call(G)
@end example
We import this module with @code{use_module(example)} into module
@code{user}. The expected behavior for a goal @code{a(p)} is to
execute goal @code{p} within the module @code{user}. However,
@code{a/1} will call @code{p} within module @code{example}.
The @code{meta_predicate/1} 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:
@table @code
@item meta_predicate @var{G1},....,@var{Gn}
@findex meta_predicate/1 (directive)
@syindex meta_predicate/1 (directive)
@cnindex meta_predicate/1 (directive)
Each @var{Gi} is a mode specification.
If the argument is @code{:}, 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 @code{call/1} and @code{setof/3} are:
@example
:- meta_predicate call(0), setof(?,0,?).
@end example
@end table
The previous example is expanded to the following code which explains,
why the goal @code{a(p)} calls @code{p} in @code{example} and not in
@code{user}. The goal @code{call(G)} is expanded because of the
meta-predicate declaration for @code{call/1}.
@example
:- module(example,[a/1]).
a(G) :- call(example:G)
@end example
By adding a meta-predicate declaration for @code{a/1}, the goal
@code{a(p)} in module user will be expanded to @code{a(user:p)}
thereby preserving the module information.
@example
:- module(example,[a/1]).
:- meta_predicate a(:).
a(G) :- call(G)
@end example
An alternate mechanism is the directive @code{module_transparent/1}
offered for compatibility with SWI-Prolog.
@table @code
@item module_transparent +@var{Preds}
@findex module_transparent/1 (directive)
@syindex module_transparent/1 (directive)
@cnindex module_transparent/1 (directive)
@var{Preds} is a comma separated sequence of name/arity predicate
indicators (like
@code{dynamic/1}). Each goal associated with a transparent declared
predicate will inherit the context module from its parent goal.
@end table
@node Re-Exporting Modules, , Meta-Predicates in Modules, Modules
@subsection 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:
@table @code
@item reexport(+@var{F})
@findex reexport/1
@snindex reexport/1
@cnindex reexport/1
Export all predicates defined in file @var{F} as if they were defined in
the current module.
@item reexport(+@var{F},+@var{Decls})
@findex reexport/2
@snindex reexport/2
@cnindex reexport/2
Export predicates defined in file @var{F} according to @var{Decls}. The
declarations may be of the form:
@itemize @bullet
@item A list of predicate declarations to be exported. Each declaration
may be a predicate indicator or of the form ``@var{PI} @code{as}
@var{NewName}'', meaning that the predicate with indicator @var{PI} is
to be exported under name @var{NewName}.
@item @code{except}(@var{List})
In this case, all predicates not in @var{List} are exported. Moreover,
if @code{@var{PI} @code{as} @var{NewName}} is found, the predicate with
indicator @var{PI} is to be exported under name @var{NewName} as
before.
@end itemize
@end table
Re-exporting predicates must be used with some care. Please, take into
account the following observations:
@itemize @bullet
@item
The @code{reexport} declarations must be the first declarations to
follow the @code{module} declaration.
@item
It is possible to use both @code{reexport} and @code{use_module}, but
all predicates reexported are automatically available for use in the
current module.
@item
In order to obtain efficient execution, YAP compiles dependencies
between re-exported predicates. In practice, this means that changing a
@code{reexport} declaration and then @strong{just} recompiling the file
may result in incorrect execution.
@end itemize