328 lines
11 KiB
TeX
328 lines
11 KiB
TeX
@chapter SWI-Prolog Emulation
|
|
|
|
This library provides a number of SWI-Prolog builtins that are not by
|
|
default in YAP. This support is loaded with the
|
|
@code{expects_dialect(swi)} command.
|
|
|
|
@table @code
|
|
|
|
@item append(?@var{List1},?@var{List2},?@var{List3})
|
|
@findex append/3
|
|
@snindex append/3
|
|
@cnindex append/3
|
|
Succeeds when @var{List3} unifies with the concatenation of @var{List1}
|
|
and @var{List2}. The predicate can be used with any instantiation
|
|
pattern (even three variables).
|
|
|
|
@item between(+@var{Low},+@var{High},?@var{Value})
|
|
@findex between/3
|
|
@snindex between/3
|
|
@cnindex between/3
|
|
|
|
@var{Low} and @var{High} are integers, @var{High} less or equal than
|
|
@var{Low}. If @var{Value} is an integer, @var{Low} less or equal than
|
|
@var{Value} less or equal than @var{High}. When @var{Value} is a
|
|
variable it is successively bound to all integers between @var{Low} and
|
|
@var{High}. If @var{High} is @code{inf}, @code{between/3} is true iff
|
|
@var{Value} less or equal than @var{Low}, a feature that is particularly
|
|
interesting for generating integers from a certain value.
|
|
|
|
@item chdir(+@var{Dir})
|
|
@findex chdir/1
|
|
@snindex chdir/1
|
|
@cnindex chdir/1
|
|
|
|
Compatibility predicate. New code should use @code{working_directory/2}.
|
|
|
|
@item concat_atom(+@var{List},-@var{Atom})
|
|
@findex concat_atom/2
|
|
@snindex concat_atom/2
|
|
@cnindex concat_atom/2
|
|
|
|
@var{List} is a list of atoms, integers or floating point numbers. Succeeds
|
|
if @var{Atom} can be unified with the concatenated elements of @var{List}. If
|
|
@var{List} has exactly 2 elements it is equivalent to @code{atom_concat/3},
|
|
allowing for variables in the list.
|
|
|
|
@item concat_atom(?@var{List},+@var{Separator},?@var{Atom})
|
|
@findex concat_atom/3
|
|
@snindex concat_atom/3
|
|
@cnindex concat_atom/3
|
|
|
|
Creates an atom just like concat_atom/2, but inserts @var{Separator}
|
|
between each pair of atoms. For example:
|
|
\@example
|
|
?- concat_atom([gnu, gnat], ', ', A).
|
|
|
|
A = 'gnu, gnat'
|
|
@end example
|
|
|
|
(Unimplemented) This predicate can also be used to split atoms by
|
|
instantiating @var{Separator} and @var{Atom}:
|
|
|
|
@example
|
|
?- concat_atom(L, -, 'gnu-gnat').
|
|
|
|
L = [gnu, gnat]
|
|
@end example
|
|
|
|
@item nth1(+@var{Index},?@var{List},?@var{Elem})
|
|
@findex nth1/3
|
|
@snindex nth1/3
|
|
@cnindex nth1/3
|
|
Succeeds when the @var{Index}-th element of @var{List} unifies with
|
|
@var{Elem}. Counting starts at 1.
|
|
|
|
Set environment variable. @var{Name} and @var{Value} should be
|
|
instantiated to atoms or integers. The environment variable will be
|
|
passed to @code{shell/[0-2]} and can be requested using @code{getenv/2}.
|
|
They also influence @code{expand_file_name/2}.
|
|
|
|
@item setenv(+@var{Name},+@var{Value})
|
|
@findex setenv/2
|
|
@snindex setenv/2
|
|
@cnindex setenv/2
|
|
Set environment variable. @var{Name} and @var{Value} should be
|
|
instantiated to atoms or integers. The environment variable will be
|
|
passed to @code{shell/[0-2]} and can be requested using @code{getenv/2}.
|
|
They also influence @code{expand_file_name/2}.
|
|
|
|
@item term_to_atom(?@var{Term},?@var{Atom})
|
|
@findex term_to_atom/2
|
|
@snindex term_to_atom/2
|
|
@cnindex term_to_atom/2
|
|
Succeeds if @var{Atom} describes a term that unifies with @var{Term}. When
|
|
@var{Atom} is instantiated @var{Atom} is converted and then unified with
|
|
@var{Term}. If @var{Atom} has no valid syntax, a @code{syntax_error}
|
|
exception is raised. Otherwise @var{Term} is ``written'' on @var{Atom}
|
|
using @code{write/1}.
|
|
|
|
@item working_directory(-@var{Old},+@var{New})
|
|
@findex working_directory/2
|
|
@snindex working_directory/2
|
|
@cnindex working_directory/2
|
|
|
|
Unify @var{Old} with an absolute path to the current working directory
|
|
and change working directory to @var{New}. Use the pattern
|
|
@code{working_directory(CWD, CWD)} to get the current directory. See
|
|
also @code{absolute_file_name/2} and @code{chdir/1}.
|
|
|
|
@item @@@var{Term1} =@@= @@@var{Term2}
|
|
@findex =@@=/2
|
|
@snindex =@@=/2
|
|
@cnindex =@@=/2
|
|
|
|
True iff @var{Term1} and @var{Term2} are structurally equivalent. I.e. if @var{Term1} and @var{Term2} are variants of each other.
|
|
|
|
@end table
|
|
|
|
@node Invoking Predicates on all Members of a List,Forall, , SWI-Prolog
|
|
@section Invoking Predicates on all Members of a List
|
|
@c \label{sec:applylist}
|
|
|
|
All the predicates in this section call a predicate on all members of a
|
|
list or until the predicate called fails. The predicate is called via
|
|
@code{call/[2..]}, which implies common arguments can be put in
|
|
front of the arguments obtained from the list(s). For example:
|
|
|
|
@example
|
|
?- maplist(plus(1), [0, 1, 2], X).
|
|
|
|
X = [1, 2, 3]
|
|
@end example
|
|
|
|
we will phrase this as ``@var{Predicate} is applied on ...''
|
|
|
|
@table @code
|
|
|
|
@item maplist(+@var{Pred},+@var{List})
|
|
@findex maplist/2
|
|
@snindex maplist/2
|
|
@cnindex maplist/2
|
|
@var{Pred} is applied successively on each element of @var{List} until
|
|
the end of the list or @var{Pred} fails. In the latter case
|
|
@code{maplist/2} fails.
|
|
|
|
@item maplist(+@var{Pred},+@var{List1},+@var{List2})
|
|
@findex maplist/3
|
|
@snindex maplist/3
|
|
@cnindex maplist/3
|
|
Apply @var{Pred} on all successive pairs of elements from
|
|
@var{List1} and
|
|
@var{List2}. Fails if @var{Pred} can not be applied to a
|
|
pair. See the example above.
|
|
|
|
@item maplist(+@var{Pred},+@var{List1},+@var{List2},+@var{List4})
|
|
@findex maplist/4
|
|
@snindex maplist/4
|
|
@cnindex maplist/4
|
|
Apply @var{Pred} on all successive triples of elements from @var{List1},
|
|
@var{List2} and @var{List3}. Fails if @var{Pred} can not be applied to a
|
|
triple. See the example above.
|
|
|
|
@c @item findlist(+@var{Pred},+@var{List1},?@var{List2})
|
|
@c @findex findlist/3
|
|
@c @snindex findlist/3
|
|
@c @cnindex findlist/3
|
|
@c Unify @var{List2} with a list of all elements of @var{List1} to which
|
|
@c @var{Pred} applies.
|
|
@end table
|
|
|
|
@node Forall, ,Invoking Predicates on all Members of a List, SWI-Prolog
|
|
@section Forall
|
|
@c \label{sec:forall2}
|
|
|
|
@table @code
|
|
@item forall(+@var{Cond},+@var{Action})
|
|
@findex forall/2
|
|
@snindex forall/2
|
|
@cnindex forall/2
|
|
|
|
For all alternative bindings of @var{Cond} @var{Action} can be proven.
|
|
The next example verifies that all arithmetic statements in the list
|
|
@var{L} are correct. It does not say which is wrong if one proves wrong.
|
|
|
|
@example
|
|
?- forall(member(Result = Formula, [2 = 1 + 1, 4 = 2 * 2]),
|
|
Result =:= Formula).
|
|
@end example
|
|
|
|
@end table
|
|
|
|
@node SWI-Prolog Global Variables, Extensions, SWI-Prolog, Top
|
|
@chapter SWI Global variables
|
|
@c \label{sec:gvar}
|
|
|
|
SWI-Prolog global variables are associations between names (atoms) and
|
|
terms. They differ in various ways from storing information using
|
|
@code{assert/1} or @code{recorda/3}.
|
|
|
|
@itemize @bullet
|
|
@item The value lives on the Prolog (global) stack. This implies
|
|
that lookup time is independent from the size of the term.
|
|
This is particulary interesting for large data structures
|
|
such as parsed XML documents or the CHR global constraint
|
|
store.
|
|
|
|
@item They support both global assignment using @code{nb_setval/2} and
|
|
backtrackable assignment using @code{b_setval/2}.
|
|
|
|
@item Only one value (which can be an arbitrary complex Prolog
|
|
term) can be associated to a variable at a time.
|
|
|
|
@item Their value cannot be shared among threads. Each thread
|
|
has its own namespace and values for global variables.
|
|
|
|
@item Currently global variables are scoped globally. We may
|
|
consider module scoping in future versions.
|
|
@end itemize
|
|
|
|
Both @code{b_setval/2} and @code{nb_setval/2} implicitly create a variable if the
|
|
referenced name does not already refer to a variable.
|
|
|
|
Global variables may be initialised from directives to make them
|
|
available during the program lifetime, but some considerations are
|
|
necessary for saved-states and threads. Saved-states to not store global
|
|
variables, which implies they have to be declared with @code{initialization/1}
|
|
to recreate them after loading the saved state. Each thread has
|
|
its own set of global variables, starting with an empty set. Using
|
|
@code{thread_inititialization/1} to define a global variable it will be
|
|
defined, restored after reloading a saved state and created in all
|
|
threads that are created @emph{after} the registration.
|
|
|
|
|
|
@table @code
|
|
@item b_setval(+@var{Name},+@var{Value})
|
|
@findex b_setval/2
|
|
@snindex b_setval/2
|
|
@cnindex b_setval/2
|
|
Associate the term @var{Value} with the atom @var{Name} or replaces
|
|
the currently associated value with @var{Value}. If @var{Name} does
|
|
not refer to an existing global variable a variable with initial value
|
|
@code{[]} is created (the empty list). On backtracking the
|
|
assignment is reversed.
|
|
|
|
@item b_getval(+@var{Name},-@var{Value})
|
|
@findex b_getval/2
|
|
@snindex b_getval/2
|
|
@cnindex b_getval/2
|
|
Get the value associated with the global variable @var{Name} and unify
|
|
it with @var{Value}. Note that this unification may further instantiate
|
|
the value of the global variable. If this is undesirable the normal
|
|
precautions (double negation or @code{copy_term/2}) must be taken. The
|
|
@code{b_getval/2} predicate generates errors if @var{Name} is not an atom or
|
|
the requested variable does not exist.
|
|
@end table
|
|
|
|
@table @code
|
|
|
|
@item nb_setval(+@var{Name},+@var{Value})
|
|
@findex nb_setval/2
|
|
@snindex nb_setval/2
|
|
@cnindex nb_setval/2
|
|
Associates a copy of @var{Value} created with @code{duplicate_term/2}
|
|
with the atom @var{Name}. Note that this can be used to set an
|
|
initial value other than @code{[]} prior to backtrackable assignment.
|
|
|
|
@item nb_getval(+@var{Name},-@var{Value})
|
|
@findex nb_getval/2
|
|
@snindex nb_getval/2
|
|
@cnindex nb_getval/2
|
|
The @code{nb_getval/2} predicate is a synonym for b_getval/2, introduced for
|
|
compatibility and symmetry. As most scenarios will use a particular
|
|
global variable either using non-backtrackable or backtrackable
|
|
assignment, using @code{nb_getval/2} can be used to document that the
|
|
variable is used non-backtrackable.
|
|
|
|
@c \predicate{nb_linkval}{2}{+Name, +Value}
|
|
@c Associates the term @var{Value} with the atom @var{Name} without copying
|
|
@c it. This is a fast special-purpose variation of nb_setval/2 intended for
|
|
@c expert users only because the semantics on backtracking to a point
|
|
@c before creating the link are poorly defined for compound terms. The
|
|
@c principal term is always left untouched, but backtracking behaviour on
|
|
@c arguments is undone if the original assignment was \jargon{trailed} and
|
|
@c left alone otherwise, which implies that the history that created the
|
|
@c term affects the behaviour on backtracking. Please consider the
|
|
@c following example:
|
|
|
|
@c \begin{code}
|
|
@c demo_nb_linkval :-
|
|
@c T = nice(N),
|
|
@c ( N = world,
|
|
@c nb_linkval(myvar, T),
|
|
@c fail
|
|
@c ; nb_getval(myvar, V),
|
|
@c writeln(V)
|
|
@c ).
|
|
@c \end{code}
|
|
|
|
@item nb_current(?@var{Name},?@var{Value})
|
|
@findex nb_current/2
|
|
@snindex nb_current/2
|
|
@cnindex nb_current/2
|
|
Enumerate all defined variables with their value. The order of
|
|
enumeration is undefined.
|
|
|
|
@item nb_delete(?@var{Name})
|
|
@findex nb_delete/1
|
|
@snindex nb_delete/1
|
|
@cnindex nb_delete/1
|
|
Delete the named global variable.
|
|
@end table
|
|
|
|
@section Compatibility of Global Variables
|
|
|
|
Global variables have been introduced by various Prolog
|
|
implementations recently. YAP follows their implementation in SWI-Prolog, itself
|
|
based on hProlog by Bart Demoen. Jan and Bart
|
|
decided that the semantics if hProlog @code{nb_setval/2}, which is
|
|
equivalent to @code{nb_linkval/2} is not acceptable for normal Prolog
|
|
users as the behaviour is influenced by how builtin predicates
|
|
constructing terms (@code{read/1}, @code{=../2}, etc.) are implemented.
|
|
|
|
GNU-Prolog provides a rich set of global variables, including arrays.
|
|
Arrays can be implemented easily in SWI-Prolog using @code{functor/3} and
|
|
@code{setarg/3} due to the unrestricted arity of compound terms.
|
|
|
|
|