1033 lines
34 KiB
TeX
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
|
|
|