diogo/yap-6.3
Archived
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Christian patches for call_cleanup and documentation.

Browse Source 
git-svn-id: https://yap.svn.sf.net/svnroot/yap/trunk@633 b08c6af1-5177-4d33-ba66-4b1c6b8b522a
This commit is contained in:
vsc 2002-10-11 03:39:11 +00:00
parent 523fae9544
commit efc7c1c5a6
3 changed files with 197 additions and 99 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

178
docs/yap.tex
View File

@ -1,4 +1,4 @@
<\input texinfo @c -*- mode: texinfo; coding: latin-1; -*- \input texinfo @c -*- mode: texinfo; coding: latin-1; -*-
@c %**start of header @c %**start of header
@setfilename yap.info @setfilename yap.info
@ -93,7 +93,7 @@ manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a entire resulting derived work is distributed under the terms of a
permission notice identical to this one. permission notice identical to this one.
Permission is granted qto copy and distribute translations of this Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a versions, except that this permission notice may be stated in a
translation approved by the OFAI. translation approved by the OFAI.
@ -226,6 +226,7 @@ Subnodes of Library
* String I/O:: Writing To and Reading From Strings * String I/O:: Writing To and Reading From Strings
* System:: System Utilities * System:: System Utilities
* Terms:: Utilities on Terms * Terms:: Utilities on Terms
* Cleanup:: Call With registered Cleanup Calls
* Timeout:: Call With Timeout * Timeout:: Call With Timeout
* Trees:: Updatable Binary Trees * Trees:: Updatable Binary Trees
* UGraphs:: Unweighted Graphs * UGraphs:: Unweighted Graphs
@ -393,7 +394,7 @@ acknowledge the contributions from Ashwin Srinivasian.
We are happy to include in YAP several excellent packages developed We are happy to include in YAP several excellent packages developed
under separate licenses. Our thanks to the authors for their kind under separate licenses. Our thanks to the authors for their kind
authorisation to include these packages. authorization to include these packages.
The packages are, in alphabetical order: The packages are, in alphabetical order:
@ -434,7 +435,7 @@ manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a entire resulting derived work is distributed under the terms of a
permission notice identical to this one. permission notice identical to this one.
Permission is granted qto copy and distribute translations of this Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a versions, except that this permission notice may be stated in a
translation approved by the OFAI. translation approved by the OFAI.
@ -501,7 +502,7 @@ conventions on where to place software.
actually a script that calls the Prolog engine, stored at @code{LIBDIR}. actually a script that calls the Prolog engine, stored at @code{LIBDIR}.
@item @code{LIBDIR} is the directory where libraries are stored. YAPLIBDIR is a @item @code{LIBDIR} is the directory where libraries are stored. YAPLIBDIR is a
subsdirectory that contains the Prolog engine and a Prolog library. subdirectory that contains the Prolog engine and a Prolog library.
@item @code{INCLUDEDIR} is used if you want to use Yap as a library. @item @code{INCLUDEDIR} is used if you want to use Yap as a library.
@ -582,7 +583,7 @@ Sun's cc compiler, IBM's xlc, SGI's cc, and Microsoft's Visual C++
6.0. 6.0.
@menu @menu
* Tuning for GCC:: Using the GNUCC ncompiler * Tuning for GCC:: Using the GNUCC compiler
* Compiling Under Visual C++:: Using Microsoft's Visual C++ environment * Compiling Under Visual C++:: Using Microsoft's Visual C++ environment
* Tuning for SGI cc:: Compiling Under SGI's @code{cc} * Tuning for SGI cc:: Compiling Under SGI's @code{cc}
@end menu @end menu
@ -599,7 +600,7 @@ YAP is set by default to compile with the best compilation flags we
know. Even so, a few specific options reduce portability. The option know. Even so, a few specific options reduce portability. The option
@itemize @bullet @itemize @bullet
@item @code{--enable-max-performance=yes} will try to support the best @item @code{--enable-max-performance=yes} will try to support the best
available flags for a specific architecural model. Currently, the option available flags for a specific architectural model. Currently, the option
assumes a recent version of @code{GCC}. assumes a recent version of @code{GCC}.
@item @code{--enable-debug-yap} compiles Yap so that it can be debugged @item @code{--enable-debug-yap} compiles Yap so that it can be debugged
by tools such as @code{dbx} or @code{gdb}. by tools such as @code{dbx} or @code{gdb}.
@ -625,7 +626,7 @@ YAP_EXTRAS= ... -mno-app-regs -DOPTIMISE_ALL_REGS_FOR_SPARC=1
and YAP will get two extra registers! This trick does not work on and YAP will get two extra registers! This trick does not work on
SunOS 4 machines. SunOS 4 machines.
Note that versions of GCC can be tweaked to recognise different Note that versions of GCC can be tweaked to recognize different
processors within the same instruction set, eg, 486, Pentium, and processors within the same instruction set, eg, 486, Pentium, and
PentiumPro for the x86; or Ultrasparc, and Supersparc for PentiumPro for the x86; or Ultrasparc, and Supersparc for
Sparc. Unfortunately, some of these tweaks do may make Yap run slower or Sparc. Unfortunately, some of these tweaks do may make Yap run slower or
@ -641,7 +642,7 @@ GCC"/"Submodel Options". Specifically, you should check
@table @code @table @code
@item 486: @item 486:
In order to take advantage of 486 specific optimisations in GCC 2.7.*: In order to take advantage of 486 specific optimizations in GCC 2.7.*:
@example @example
YAP_EXTRAS= ... -m486 -DBP_FREE=1 YAP_EXTRAS= ... -m486 -DBP_FREE=1
@ -701,7 +702,7 @@ You should check the default installation path which is set to
@code{/PROGRA~1/Yap} in the standard Makefile. This string will usually @code{/PROGRA~1/Yap} in the standard Makefile. This string will usually
be expanded into @code{c:\Program Files\Yap} by Windows. be expanded into @code{c:\Program Files\Yap} by Windows.
The cygwin environment does not provide @t{gm}. You can fecth a dll for The cygwin environment does not provide @t{gm}. You can fetch a dll for
the @t{gmp} library from @url{http://www.sf.net/projects/mingwrep}. the @t{gmp} library from @url{http://www.sf.net/projects/mingwrep}.
It is also possible to configure Yap to be a part of the cygwin It is also possible to configure Yap to be a part of the cygwin
@ -735,7 +736,7 @@ First, it is a good idea to build Yap as a DLL:
DLL project, initially empty. DLL project, initially empty.
Notice that either the project is named yapdll or you must replace the Notice that either the project is named yapdll or you must replace the
preprocessor's variable @var{YAPDLL_EXPORTS} to match your project names preprocessors variable @var{YAPDLL_EXPORTS} to match your project names
in the files @code{YapInterface.h} and @code{c_interface.c}. in the files @code{YapInterface.h} and @code{c_interface.c}.
@item add all .c files in the @var{$YAPSRC/C} directory and in the @item add all .c files in the @var{$YAPSRC/C} directory and in the
@ -1276,7 +1277,7 @@ The next examples demonstrates the use of escape sequences in YAP:
The first three examples return a list including only character 12 (form The first three examples return a list including only character 12 (form
feed). The last example escapes the escape character. feed). The last example escapes the escape character.
Escape sequences were not available in C-Prolog and in origional Escape sequences were not available in C-Prolog and in original
versions of YAP up to 4.2.0. Escape sequences can be disable by using: versions of YAP up to 4.2.0. Escape sequences can be disable by using:
@example @example
@code{:- yap_flag(character_escapes,off).} @code{:- yap_flag(character_escapes,off).}
@ -1471,7 +1472,7 @@ files specified by @var{F} into the file being currently consulted.
@end table @end table
@node Setting the Compiler, Saving, Compiling, Loading Programs @node Setting the Compiler, Saving, Compiling, Loading Programs
@section Changing the Compiler's Behaviour @section Changing the Compiler's Behavior
This section presents a set of built-ins predicates designed to set the This section presents a set of built-ins predicates designed to set the
environment for the compiler. environment for the compiler.
@ -1512,7 +1513,7 @@ The same as @code{source_mode(_,off)}.
@snindex compile_expressions/0 @snindex compile_expressions/0
@cnindex compile_expressions/0 @cnindex compile_expressions/0
After a call to this predicate, arithmetical expressions will be compiled. After a call to this predicate, arithmetical expressions will be compiled.
(see example below). This is the default behaviour. (see example below). This is the default behavior.
@item do_not_compile_expressions @item do_not_compile_expressions
@findex do_not_compile_expressions/0 @findex do_not_compile_expressions/0
@ -1588,7 +1589,7 @@ Adds @var{D} to the end of YAP's directory search path.
@findex add_to_path/2 @findex add_to_path/2
@snindex path/1 @snindex path/1
@cnindex path/1 @cnindex path/1
Inserts @var{D} in thgoe position, of the directory search path of Inserts @var{D} in the position, of the directory search path of
YAP, specified by @var{N}. @var{N} must be either of YAP, specified by @var{N}. @var{N} must be either of
@code{first} or @code{last}. @code{first} or @code{last}.
@ -1971,7 +1972,7 @@ a(G) :- call(G)
... ...
@end example @end example
The expected behaviour for this procedure is to execute goal @var{G} The expected behavior for this procedure is to execute goal @var{G}
within the current module, that is, within @code{example}. within the current module, that is, within @code{example}.
On the other hand, when executing @code{call/1} the system only knows On the other hand, when executing @code{call/1} the system only knows
where @code{call/1} was defined, that is, it only knows of where @code{call/1} was defined, that is, it only knows of
@ -2460,7 +2461,7 @@ dynamic. What YAP does when trying to execute undefined predicates can
be specified through three different ways: be specified through three different ways:
@itemize @bullet @itemize @bullet
@item By setting an YAP flag, through the @code{yap_flag/2} or @item By setting an YAP flag, through the @code{yap_flag/2} or
@code{set_prolog_flag/2} built-ins. This solution generalises the @code{set_prolog_flag/2} built-ins. This solution generalizes the
ISO standard. ISO standard.
@item By using the @code{unknown/2} built-in (this solution is @item By using the @code{unknown/2} built-in (this solution is
compatible with previous releases of YAP). compatible with previous releases of YAP).
@ -3408,7 +3409,7 @@ YAP currently ignores these options.
@findex absolute_file_name/2 @findex absolute_file_name/2
@syindex absolute_file_name/2 @syindex absolute_file_name/2
@cnindex absolute_file_name/2 @cnindex absolute_file_name/2
Give the path a full path @var{FullPath} Yap would use to consule a file Give the path a full path @var{FullPath} Yap would use to consult a file
named @var{Name}. Unify @var{FullPath} with @code{user} if the file named @var{Name}. Unify @var{FullPath} with @code{user} if the file
name is @code{user}. name is @code{user}.
@ -3506,7 +3507,7 @@ unbound, the procedure will backtrack through all open
streams. Otherwise, the first argument must be a stream term (you may streams. Otherwise, the first argument must be a stream term (you may
use @code{current_stream} to obtain a current stream given a file name). use @code{current_stream} to obtain a current stream given a file name).
The following properties are recognised: The following properties are recognized:
@table @code @table @code
@ -3727,7 +3728,7 @@ following options:
@table @code @table @code
@item quoted(+@var{Bool}) @item quoted(+@var{Bool})
If @code{true}, quote atoms if this would be necessary for the atom to If @code{true}, quote atoms if this would be necessary for the atom to
be recognised as an atom by YAP's parser. The default value is be recognized as an atom by YAP's parser. The default value is
@code{false}. @code{false}.
@item ignore_ops(+@var{Bool}) @item ignore_ops(+@var{Bool})
@ -3989,7 +3990,7 @@ We next show how to do centering:
The two @code{~t} escape sequence force filling both before and after The two @code{~t} escape sequence force filling both before and after
@code{Hello}. Space is then evenly divided bewteen the right and the @code{Hello}. Space is then evenly divided between the right and the
left sides. left sides.
@item format(+@var{S},+@var{T},+@var{L}) @item format(+@var{S},+@var{T},+@var{L})
@ -4438,7 +4439,7 @@ Call @code{socket/4} with @var{TYPE} bound to @code{'SOCK_STREAM'} and
@cnindex socket_close/1 @cnindex socket_close/1
Close socket @var{SOCKET}. Note that sockets used in Close socket @var{SOCKET}. Note that sockets used in
@code{socket_connet} (that is, client sockets) should not be closed with @code{socket_connect} (that is, client sockets) should not be closed with
@code{socket_close}, as they will be automatically closed when the @code{socket_close}, as they will be automatically closed when the
corresponding stream is closed with @code{close/1} or @code{close/2}. corresponding stream is closed with @code{close/1} or @code{close/2}.
@ -4706,7 +4707,7 @@ undefined results.
@cnindex assertz_static/1 @cnindex assertz_static/1
Adds clause @var{C} to the end of a static procedure. Asserting a Adds clause @var{C} to the end of a static procedure. Asserting a
static clause for a predicate while choice-points for the predicate are static clause for a predicate while choice-points for the predicate are
availabe has undefined results. available has undefined results.
@end table @end table
@ -5456,7 +5457,7 @@ Arranges for YAP to be interrupted in @var{Seconds}
seconds. When interrupted, YAP will execute @var{Callable} and seconds. When interrupted, YAP will execute @var{Callable} and
then return to the previous execution. If @var{Seconds} is @code{0}, no then return to the previous execution. If @var{Seconds} is @code{0}, no
new alarm is scheduled. In any event, any previously set alarm is new alarm is scheduled. In any event, any previously set alarm is
cancelled. canceled.
The variable @var{OldAlarm} unifies with the number of seconds remaining The variable @var{OldAlarm} unifies with the number of seconds remaining
until any previously scheduled alarm was due to be delivered, or with until any previously scheduled alarm was due to be delivered, or with
@ -5525,8 +5526,8 @@ Set the interrupt handler for soft interrupt @var{Signal} to be
@var{Callable}. @var{OldAction} is unified with the previous handler. @var{Callable}. @var{OldAction} is unified with the previous handler.
Only a subset of the software interrupts (signals) can have their Only a subset of the software interrupts (signals) can have their
handlers maniputated through @code{on_signal/3}. handlers manipulated through @code{on_signal/3}.
Their POSIX names, YAP names and default behaviour is given below. Their POSIX names, YAP names and default behavior is given below.
The "YAP name" of the signal is the atom that is associated with The "YAP name" of the signal is the atom that is associated with
each signal, and should be used as the first argument to each signal, and should be used as the first argument to
@code{on_signal/3}. It is chosen so that it matches the signal's POSIX @code{on_signal/3}. It is chosen so that it matches the signal's POSIX
@ -5538,7 +5539,7 @@ are made on the handler provided by the user.
@table @code @table @code
@item SIGHUP (Hangup) @item SIGHUP (Hangup)
sig_hup in YAP; Reconsult the initialisation files sig_hup in YAP; Reconsult the initialization files
~/.yaprc, ~/.prologrc and ~/prolog.ini. ~/.yaprc, ~/.prologrc and ~/prolog.ini.
@item SIGUSR1 and SIGUSR2 (User signals) @item SIGUSR1 and SIGUSR2 (User signals)
sig_usr1 and sig_usr2 in YAP; Print a message and halt. sig_usr1 and sig_usr2 in YAP; Print a message and halt.
@ -5669,7 +5670,7 @@ write_profile_data([D-P|SLP]) :-
These are the current predicates to access and clear profiling data: These are the current predicates to access and clear profiling data:
@table @code @table @code
@item profile_data(?@var{Na/Ar}, ?@var{Paramater}, -@var{Data}) @item profile_data(?@var{Na/Ar}, ?@var{Parameter}, -@var{Data})
@findex profile_data/3 @findex profile_data/3
@snindex profile_data/3 @snindex profile_data/3
@cnindex profile_data/3 @cnindex profile_data/3
@ -5873,7 +5874,7 @@ previously.
@snindex static_array/3 @snindex static_array/3
@cnindex static_array/3 @cnindex static_array/3
Similar to @code{static_array/3}, but the array is memory mapped to file Similar to @code{static_array/3}, but the array is memory mapped to file
@var{File}. This means that the array is initialised from the file, and @var{File}. This means that the array is initialized from the file, and
that any changes to the array will also be stored in the file. that any changes to the array will also be stored in the file.
This built-in is only available in operating systems that support the This built-in is only available in operating systems that support the
@ -6108,7 +6109,7 @@ reading terms. The default value for this flag is @code{off} except in
@c @code{iso} mode, which corresponds to @code{on}, and @code{sicstus} @c @code{iso} mode, which corresponds to @code{on}, and @code{sicstus}
@c mode, which corresponds to the mode traditionally used in SICStus @c mode, which corresponds to the mode traditionally used in SICStus
@c Prolog. In this mode back-quoted escape sequences should not close with @c Prolog. In this mode back-quoted escape sequences should not close with
@c a backquote and unrecognised escape codes do not result in error. @c a backquote and unrecognized escape codes do not result in error.
@item debug [ISO] @item debug [ISO]
@findex debug (yap_flag/2 option) @findex debug (yap_flag/2 option)
@ -6138,7 +6139,7 @@ If @code{off} (default) consider the character '$' a control character, if
If @var{Value} is unbound, tell whether a double quoted list of characters If @var{Value} is unbound, tell whether a double quoted list of characters
token is converted to a list of atoms, @code{chars}, to a list of integers, token is converted to a list of atoms, @code{chars}, to a list of integers,
@code{codes}, or to a single atom, @code{atom}. If @var{Value} is bound, set to @code{codes}, or to a single atom, @code{atom}. If @var{Value} is bound, set to
the corresponding behaviour. The default value is @code{codes}. the corresponding behavior. The default value is @code{codes}.
@item fast @item fast
@findex fast (yap_flag/2 option) @findex fast (yap_flag/2 option)
@ -6218,7 +6219,7 @@ Read-only flag telling the maximum arity of a functor. Takes the value
Read-only flag telling the maximum integer in the Read-only flag telling the maximum integer in the
implementation. Depends on machine and Operating System implementation. Depends on machine and Operating System
architecture, and on whether YAP uses the @code{GMP} multiprecision architecture, and on whether YAP uses the @code{GMP} multiprecision
library. If @code{bounded} is false, requestes for @code{max_integer} library. If @code{bounded} is false, requests for @code{max_integer}
will fail. will fail.
@item min_integer [ISO] @item min_integer [ISO]
@ -6226,7 +6227,7 @@ will fail.
@* Read-only flag telling the minimum integer in the @* Read-only flag telling the minimum integer in the
implementation. Depends on machine and Operating System architecture, implementation. Depends on machine and Operating System architecture,
and on whether YAP uses the @code{GMP} multiprecision library. If and on whether YAP uses the @code{GMP} multiprecision library. If
@code{bounded} is false, requestes for @code{min_integer} will fail. @code{bounded} is false, requests for @code{min_integer} will fail.
@item n_of_integer_keys_in_bb @item n_of_integer_keys_in_bb
@findex n_of_integer_keys_in_bb (yap_flag/2 option) @findex n_of_integer_keys_in_bb (yap_flag/2 option)
@ -6285,7 +6286,7 @@ from a modern Prolog system. Moreover, because most Prolog
implementations do not fully implement the standard and because the implementations do not fully implement the standard and because the
standard itself gives the implementor latitude in a few important standard itself gives the implementor latitude in a few important
questions, such as the unification algorithm and maximum size for questions, such as the unification algorithm and maximum size for
numbers there is not guarantee that prolograms compliant with this mode numbers there is not guarantee that programs compliant with this mode
will work the same way in every Prolog and in every platform. We thus will work the same way in every Prolog and in every platform. We thus
believe this mode is mostly useful when investigating how a program believe this mode is mostly useful when investigating how a program
depends on a Prolog's platform specific features. depends on a Prolog's platform specific features.
@ -6456,7 +6457,7 @@ Defines the operator @var{A} or the list of operators @var{A} with type
Note that if there is a preexisting operator with the same name and Note that if there is a preexisting operator with the same name and
type, this operator will be discarded. Also, @code{','} may not be defined type, this operator will be discarded. Also, @code{','} may not be defined
as an operator, and it is not allowed to have the same for an infix and as an operator, and it is not allowed to have the same for an infix and
a posfix operator. a postfix operator.
@item current_op(@var{P},@var{T},@var{F}) [ISO] @item current_op(@var{P},@var{T},@var{F}) [ISO]
@findex current_op/3 @findex current_op/3
@ -6571,6 +6572,7 @@ Library, Extensions, Builtins, Top
* String I/O:: Writing To and Reading From Strings * String I/O:: Writing To and Reading From Strings
* System:: System Utilities * System:: System Utilities
* Terms:: Utilities on Terms * Terms:: Utilities on Terms
* Cleanup:: Call With registered Cleanup Calls
* Timeout:: Call With Timeout * Timeout:: Call With Timeout
* Trees:: Updatable Binary Trees * Trees:: Updatable Binary Trees
* UGraphs:: Unweighted Graphs * UGraphs:: Unweighted Graphs
@ -7101,7 +7103,7 @@ ordered sets will not necessarily result in an ordered set. Use
@findex ord_add_element/3 @findex ord_add_element/3
@syindex ord_add_element/3 @syindex ord_add_element/3
@cnindex ord_add_element/3 @cnindex ord_add_element/3
Insering @var{Element} in @var{Set1} returns @var{Set2}. It should give Inserting @var{Element} in @var{Set1} returns @var{Set2}. It should give
exactly the same result as @code{merge(Set1, [Element], Set2)}, but a exactly the same result as @code{merge(Set1, [Element], Set2)}, but a
bit faster, and certainly more clearly. The same as @code{ord_insert/3}. bit faster, and certainly more clearly. The same as @code{ord_insert/3}.
@ -7127,7 +7129,7 @@ Holds when @var{Element} is a member of @var{Set}.
@findex ord_insert/3 @findex ord_insert/3
@syindex ord_insert/3 @syindex ord_insert/3
@cnindex ord_insert/3 @cnindex ord_insert/3
Insering @var{Element} in @var{Set1} returns @var{Set2}. It should give Inserting @var{Element} in @var{Set1} returns @var{Set2}. It should give
exactly the same result as @code{merge(Set1, [Element], Set2)}, but a exactly the same result as @code{merge(Set1, [Element], Set2)}, but a
bit faster, and certainly more clearly. The same as @code{ord_add_element/3}. bit faster, and certainly more clearly. The same as @code{ord_add_element/3}.
@ -7226,7 +7228,7 @@ to obtain a floating point number uniformly distributed between 0 and 1.
@findex ranstart/0 @findex ranstart/0
@snindex ranstart/0 @snindex ranstart/0
@cnindex ranstart/0 @cnindex ranstart/0
Initialise the random number generator using a built-in seed. The Initialize the random number generator using a built-in seed. The
@code{ranstart/0} built-in is always called by the system when loading @code{ranstart/0} built-in is always called by the system when loading
the package. the package.
@ -7234,7 +7236,7 @@ the package.
@findex ranstart/1 @findex ranstart/1
@snindex ranstart/1 @snindex ranstart/1
@cnindex ranstart/1 @cnindex ranstart/1
Initialise the random number generator with user-defined @var{Seed}. The Initialize the random number generator with user-defined @var{Seed}. The
same @var{Seed} always produces the same sequence of numbers. same @var{Seed} always produces the same sequence of numbers.
@item ranunif(+@var{Range},-@var{I}) @item ranunif(+@var{Range},-@var{I})
@ -7593,7 +7595,7 @@ will fail if @var{Key} is not present.
@findex splay_init/3 @findex splay_init/3
@snindex splay_init/3 @snindex splay_init/3
@cnindex splay_init/3 @cnindex splay_init/3
Initialise a new splay tree. Initialize a new splay tree.
@item splay_insert(+@var{Key},?@var{Val},+@var{Tree},-@var{NewTree}) @item splay_insert(+@var{Key},?@var{Val},+@var{Tree},-@var{NewTree})
@findex splay_insert/4 @findex splay_insert/4
@ -7773,7 +7775,7 @@ difference list of character codes @var{L-L0}.
@end table @end table
@noindent @noindent
These builtins are initialised to belong to the module @code{charsio} in These builtins are initialized to belong to the module @code{charsio} in
@code{init.yap}. Novel procedures for manipulating strings by explicitly @code{init.yap}. Novel procedures for manipulating strings by explicitly
importing these built-ins. importing these built-ins.
@ -7869,7 +7871,7 @@ number is Operating System dependent.
@syindex file_property/2 @syindex file_property/2
@cnindex file_property/2 @cnindex file_property/2
The atom @var{File} corresponds to an existing file, and @var{Property} The atom @var{File} corresponds to an existing file, and @var{Property}
will be unified with a property of this file. The poperties are of the will be unified with a property of this file. The properties are of the
form @code{type(@var{Type})}, which gives whether the file is a regular form @code{type(@var{Type})}, which gives whether the file is a regular
file, a directory, a fifo file, or of unknown type; file, a directory, a fifo file, or of unknown type;
@code{size(@var{Size})}, with gives the size for a file, and @code{size(@var{Size})}, with gives the size for a file, and
@ -8087,7 +8089,7 @@ Wait until process @var{PID} terminates, and return its exits @var{Status}.
@end table @end table
@node Terms, Timeout, System, Library @node Terms, Cleanup, System, Library
@section Utilities On Terms @section Utilities On Terms
@cindex utilities on terms @cindex utilities on terms
@ -8170,11 +8172,61 @@ variable in @var{Term1}.
Succeed if the second argument @var{Var} is a variable and occurs in Succeed if the second argument @var{Var} is a variable and occurs in
term @var{Term}. term @var{Term}.
@end table
@node Cleanup, Timeout, Terms, Library
@section Call With registered Cleanup Calls
@cindex cleanup
@t{call_cleanup/1} and @t{call_cleanup/2} allow predicates to register
code for execution after the call is finished. This library is loaded
with the @code{use_module(library(cleanup))} command.
@table @code
@item call_cleanup(+@var{Goal})
@findex call_cleanup/1
@syindex call_cleanup/1
@cnindex call_cleanup/1
Execute goal @var{Goal} within a cleanup-context. Called predicates
might register cleanup Goals which are called right after the end of
the call to @var{Goal}. Cuts and exceptions inside Goal do not prevent the
execution of the cleanup calls. @t{call_cleanup} might be nested.
@item call_cleanup(+@var{Goal}, +@var{CleanUpGoal})
@findex call_cleanup/2
@syindex call_cleanup/2
@cnindex call_cleanup/2
This is similar to @t{call_cleanup/1} with an additional
@var{CleanUpGoal} which gets called after @var{Goal} is finished.
@item on_cleanup(+@var{CleanUpGoal})
@findex on_cleanup/1
@syindex on_cleanup/1
@cnindex on_cleanup/1
Any Predicate might registers a @var{CleanUpGoal}. The
@var{CleanUpGoal} is put onto the current cleanup context. All such
CleanUpGoals are executed in reverse order of their registration when
the surrounding cleanup-context ends. This call will throw an exception
if a predicate tries to register a @var{CleanUpGoal} outside of any
cleanup-context.
@item cleanup_all
@findex cleanup_all/0
@syindex cleanup_all/0
@cnindex cleanup_all/0
Calls all pending CleanUpGoals and resets the cleanup-system to an
initial state. Should only be used as one of the last calls in the
main program.
@end table @end table
@node Timeout, Trees, Terms, Library There are some private predicates which could be used in special
cases, such as manually setting up cleanup-contexts and registering
CleanUpGoals for other than the current cleanup-context.
Read the Source Luke.
@node Timeout, Trees, Cleanup, Library
@section Calls With Timeout @section Calls With Timeout
@cindex timeout @cindex timeout
@ -8188,7 +8240,7 @@ available with the @code{use_module(library(timeout))} command.
@findex time_out/3 @findex time_out/3
@syindex time_out/3 @syindex time_out/3
@cnindex time_out/3 @cnindex time_out/3
Execute goal @var{Goal} with time limite @var{Timeout}, where Execute goal @var{Goal} with time limited @var{Timeout}, where
@var{Timeout} is measured in milliseconds. If the goal succeeds, unify @var{Timeout} is measured in milliseconds. If the goal succeeds, unify
@var{Result} with success. If the timer expires before the goal @var{Result} with success. If the timer expires before the goal
terminates, unify @var{Result} with @t{timeout}. terminates, unify @var{Result} with @t{timeout}.
@ -8275,9 +8327,9 @@ are represented in one of two ways:
pairs, where the pairs can be in any old order. This form is pairs, where the pairs can be in any old order. This form is
convenient for input/output. convenient for input/output.
@item The S-representation of a graph is a list of (vertex-neighbours) @item The S-representation of a graph is a list of (vertex-neighbors)
pairs, where the pairs are in standard order (as produced by keysort) pairs, where the pairs are in standard order (as produced by keysort)
and the neighbours of each vertex are also in standard order (as and the neighbors of each vertex are also in standard order (as
produced by sort). This form is convenient for many calculations. produced by sort). This form is convenient for many calculations.
@end itemize @end itemize
@ -8439,7 +8491,7 @@ NL = [1,2,7,5]
@findex complement/2 @findex complement/2
@syindex complement/2 @syindex complement/2
@cnindex complement/2 @cnindex complement/2
Unify @var{NewGraph} with the graph complementar to @var{Graph}. Unify @var{NewGraph} with the graph complementary to @var{Graph}.
In the next example: In the next example:
@example @example
?- complement([1-[3,5],2-[4],3-[], ?- complement([1-[3,5],2-[4],3-[],
@ -8462,7 +8514,7 @@ Compose the graphs @var{LeftGraph} and @var{RightGraph} to form @var{NewGraph}.
L = [1-[4],2-[1,2,4],3-[]] L = [1-[4],2-[1,2,4],3-[]]
@end example @end example
@item top_sort(+@var{Graph}, +@var{Sort}) @item top_sort(+@var{Graph}, -@var{Sort})
@findex top_sort/2 @findex top_sort/2
@syindex top_sort/2 @syindex top_sort/2
@cnindex top_sort/2 @cnindex top_sort/2
@ -8699,7 +8751,7 @@ variable. In the latter case, YAP discards previous values for the
attributes. attributes.
@item The built-in @code{get_atts/2} can be used to check the values of @item The built-in @code{get_atts/2} can be used to check the values of
an attribute associated with a variable. an attribute associated with a variable.
@item The unification algorit mcalls the user-defined predicate @item The unification algoritm calls the user-defined predicate
@t{verify_attributes/3} before trying to bind an attributed @t{verify_attributes/3} before trying to bind an attributed
variable. Unification will resume after this call. variable. Unification will resume after this call.
@item The user-defined predicate @item The user-defined predicate
@ -9099,7 +9151,7 @@ manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a entire resulting derived work is distributed under the terms of a
permission notice identical to this one. permission notice identical to this one.
Permission is granted qto copy and distribute translations of this Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a versions, except that this permission notice may be stated in a
translation approved by the OFAI. translation approved by the OFAI.
@ -11992,7 +12044,7 @@ internals, or to system debuggers.
@findex reset_op_counters/0 @findex reset_op_counters/0
@snindex reset_op_counters/0 @snindex reset_op_counters/0
@cnindex reset_op_counters/0 @cnindex reset_op_counters/0
Reinitialise all counters. Reinitialize all counters.
@item show_op_counters(+@var{A}) @item show_op_counters(+@var{A})
@findex show_op_counters/1 @findex show_op_counters/1
@ -12005,7 +12057,7 @@ label must be an atom.
@findex show_ops_by_group/1 @findex show_ops_by_group/1
@snindex show_ops_by_group/1 @snindex show_ops_by_group/1
@cnindex show_ops_by_group/1 @cnindex show_ops_by_group/1
Display the current value for the counters, organised by groups, using Display the current value for the counters, organized by groups, using
label @var{A}. The label must be an atom. label @var{A}. The label must be an atom.
@end table @end table
@ -12734,7 +12786,7 @@ then allow one to construct functors, and to obtain their name and arity.
@end example @end example
@noindent @noindent
Note that the functor is essencially a pair formed by an atom, and Note that the functor is essentially a pair formed by an atom, and
arity. arity.
@node Unifying Terms, Manipulating Strings, Manipulating Terms, C-Interface @node Unifying Terms, Manipulating Strings, Manipulating Terms, C-Interface
@ -12771,7 +12823,7 @@ fails and generates an exception if @var{String} is not a valid string.
@findex YAP_BufferToAtomList (C-Interface function) @findex YAP_BufferToAtomList (C-Interface function)
The C-interface also includes utility routines to do the reverse, that The C-interface also includes utility routines to do the reverse, that
is, to copy a from a buffer to a list of character codes or to a list of is, to copy a from a buffer to a list of character codes or to a list of
character atomsr character atoms
@example @example
YAP_Term YAP_BufferToString(char *@var{buf}) YAP_Term YAP_BufferToString(char *@var{buf})
YAP_Term YAP_BufferToAtomList(char *@var{buf}) YAP_Term YAP_BufferToAtomList(char *@var{buf})
@ -12833,7 +12885,7 @@ streams. It is most useful if you are doing @code{fork()}.
@findex YAP_OpenStream (C-Interface function) @findex YAP_OpenStream (C-Interface function)
The next routine allows a currently open file to become a stream. The The next routine allows a currently open file to become a stream. The
routine receives as arguments a file descriptor, the true file name as a routine receives as arguments a file descriptor, the true file name as a
string, an atom with the yser name, and a set of flags: string, an atom with the user name, and a set of flags:
@example @example
void YAP_OpenStream(void *@var{FD}, char *@var{name}, YAP_Term @var{t}, int @var{flags}) void YAP_OpenStream(void *@var{FD}, char *@var{name}, YAP_Term @var{t}, int @var{flags})
@end example @end example
@ -12998,7 +13050,7 @@ case exits with @code{YAP_cut_succeed} in order to cut any further
backtracking. If this is not the last solution then we save the value backtracking. If this is not the last solution then we save the value
for the next solution in the data structure and exit normally with 1 for the next solution in the data structure and exit normally with 1
denoting success. Note also that in any of the two cases we use the denoting success. Note also that in any of the two cases we use the
function @code{YAP_nify} to bind the argument of the call to the value function @code{YAP_unify} to bind the argument of the call to the value
saved in @code{ n100_state->next_solution}. saved in @code{ n100_state->next_solution}.
@ -13110,7 +13162,7 @@ To actually use this library you must follow a five step process:
@enumerate @enumerate
@item @item
You must initialise the YAP environment. A single function, You must initialize the YAP environment. A single function,
@code{YAP_FastInit} asks for a contiguous chunk in your memory space, fills @code{YAP_FastInit} asks for a contiguous chunk in your memory space, fills
it in with the data-base, and sets up YAP's stacks and it in with the data-base, and sets up YAP's stacks and
execution registers. You can use a saved space from a standard system by execution registers. You can use a saved space from a standard system by
@ -13155,7 +13207,7 @@ main(int argc, char *argv[]) @{
@end cartouche @end cartouche
@end example @end example
The program first initialises YAP, calls the query for the The program first initializes YAP, calls the query for the
first time and succeeds, and then backtracks twice. The first time first time and succeeds, and then backtracks twice. The first time
backtracking succeeds, the second it fails and exits. backtracking succeeds, the second it fails and exits.
@ -13201,7 +13253,7 @@ such term exists the function will return the empty list.
@item YapFastInit(@code{char *} @var{SavedState}) @item YapFastInit(@code{char *} @var{SavedState})
@findex YapFastInit/1 @findex YapFastInit/1
Initialise a copy of YAP from @var{SavedState}. The copy is Initialize a copy of YAP from @var{SavedState}. The copy is
monolithic and currently must be loaded at the same address where it was monolithic and currently must be loaded at the same address where it was
saved. @code{YapFastInit} is a simpler version of @code{YapInit}. saved. @code{YapFastInit} is a simpler version of @code{YapInit}.
@ -13211,7 +13263,7 @@ saved. @code{YapFastInit} is a simpler version of @code{YapInit}.
@var{SchedulerLoop}, @code{int} @var{DelayedReleaseLoad}, @code{int} @var{SchedulerLoop}, @code{int} @var{DelayedReleaseLoad}, @code{int}
@var{argc}, @code{char **} @var{argv}) @var{argc}, @code{char **} @var{argv})
@findex YapInit/9 @findex YapInit/9
Initialise YAP. In the future the arguments as a single @code{C} Initialize YAP. In the future the arguments as a single @code{C}
structure. structure.
If @var{SavedState} is not NULL, try to open and restore the file If @var{SavedState} is not NULL, try to open and restore the file
@ -13270,12 +13322,12 @@ flags in the @code{flag} argument: @code{YAP_WRITE_QUOTED},
@item @code{void} YapInitConsult(@code{int} @var{mode}, @code{char *} @var{filename}) @item @code{void} YapInitConsult(@code{int} @var{mode}, @code{char *} @var{filename})
@findex YapInitConsult/2 @findex YapInitConsult/2
Enter consult mode on file @var{filename}. This mode maintains a few Enter consult mode on file @var{filename}. This mode maintains a few
data-structures internally, for instanc to know whether a predicate data-structures internally, for instance to know whether a predicate
before or not. It is still possible to execute goals in consult mode. before or not. It is still possible to execute goals in consult mode.
If @var{mode} is @code{TRUE} the file will be reconsulted, otherwise If @var{mode} is @code{TRUE} the file will be reconsulted, otherwise
just consulted. In practice, this function is most useful for just consulted. In practice, this function is most useful for
bootstraping Prolog, as otherwise one may call the Prolog predicate bootstrapping Prolog, as otherwise one may call the Prolog predicate
@code{compile/1} or @code{consult/1} to do compilation. @code{compile/1} or @code{consult/1} to do compilation.
Note that it is up to the user to open the file @var{filename}. The Note that it is up to the user to open the file @var{filename}. The

1
library/Makefile.in
View File

@ -28,6 +28,7 @@ PROGRAMS= $(srcdir)/apply_macros.yap \
$(srcdir)/atts.yap \ $(srcdir)/atts.yap \
$(srcdir)/avl.yap \ $(srcdir)/avl.yap \
$(srcdir)/charsio.yap \ $(srcdir)/charsio.yap \
$(srcdir)/cleanup.yap \
$(srcdir)/heaps.yap \ $(srcdir)/heaps.yap \
$(srcdir)/lists.yap \ $(srcdir)/lists.yap \
$(srcdir)/logtalk.yap \ $(srcdir)/logtalk.yap \

115
library/cleanup.yap
View File

@ -1,3 +1,33 @@
% cleanup.yap
% Copyright (C) 2002 by Christian Thaeter
%
% public interface:
%
% :- fragile name/arity.
% declares the predicate denoted by name/arity as fragile predicate.
% Whenever such a fragile predicate is used in a query it will be
% called through call_cleanup/1.
%
% call_cleanup(Goal).
% call_cleanup(Goal,CleanUpGoal).
% Goal will be called in a cleanup-context, where any registered
% CleanUpGoal inside of that context will be called when Goal is left,
% either by a fail, cut or exeption.
% It is possible to nest cleanup contexts.
%
% on_cleanup(CleanUpGoal).
% registers CleanUpGoal to the current cleanup context.
% CleanUpGoal's are executed in reverse order of their registration.
% throws an exception if called outside of any cleanup-context.
%
% cleanup_all.
% calls all pending CleanUpGoals and resets the cleanup-system to an initial state.
% should only be used as one of the last calls in the main program.
%
% hidden predicates:
% most private predicates could also be used in special cases, such as manually setting up cleanup-contexts.
% Read the Source.
:- module( cleanup, [ :- module( cleanup, [
call_cleanup/2, call_cleanup/2,
call_cleanup/1, call_cleanup/1,
@ -5,31 +35,11 @@
cleanup_all/0 cleanup_all/0
]). ]).
/*
public interface:
call_cleanup(Goal). :- multifile user:goal_expansion/3.
call_cleanup(Goal,CleanUpGoal).
Goal will be called in a cleanup-context, where any registered
CleanUpGoal inside of that context will be called when Goal is left,
either by a fail, cut or exeption.
It is possible to nest cleanup contexts.
on_cleanup(CleanUpGoal).
registers CleanUpGoal to the current cleanup context.
CleanUpGoal's are executed in reverse order of their registration.
throws an exception if called outside of any cleanup-context.
cleanup_all.
calls all pending CleanUpGoals and resets the cleanup-system to an initial state.
should only be used as one of the last calls in the main program.
hidden predicates:
most private predicates could also be used in special cases, such as manually setting up cleanup-contexts.
Read the Source.
*/
:- user_defined_directive(fragile(G), cleanup:cleanup_expansion(G)).
:- op(1150, fx,fragile).
:- meta_predicate :- meta_predicate
call_cleanup(:,:), call_cleanup(:,:),
@ -42,11 +52,13 @@ Read the Source.
:- initialization(init_cleanup). :- initialization(init_cleanup).
init_cleanup :- init_cleanup :-
get_value('cleanup:level',[]), bb_put(expansion_toggle,1),
set_value('cleanup:level',0). \+ bb_get(cleanup_level,_),
bb_put(cleanup_level,0).
% TODO: would be nice to register cleanup_all into the
% toplevel to be called after each query is finished
init_cleanup. init_cleanup.
% call goal G with a cleanup CL in a cleanup context % call goal G with a cleanup CL in a cleanup context
call_cleanup(G,CL) :- call_cleanup(G,CL) :-
needs_cleanup(L), needs_cleanup(L),
@ -70,15 +82,19 @@ call_cleanup(G) :-
% begin cleanup level % begin cleanup level
needs_cleanup(CL) :- needs_cleanup(CL) :-
get_value('cleanup:level',L), bb_get(cleanup_level,L),
CL is L + 1, CL is L + 1,
set_value('cleanup:level',CL). bb_put(cleanup_level,CL).
cleanup_context(CL) :-
bb_get(cleanup_level,CL).
% leave cleanup level, call all registred cleanup predicates within % leave cleanup level, call all registred cleanup predicates within
do_cleanup(CL) :- do_cleanup(CL) :-
CN is CL - 1, CN is CL - 1,
set_value('cleanup:level',CN), bb_put(cleanup_level,CN),
next_cleanup(CL). next_cleanup(CL).
next_cleanup(CL) :- next_cleanup(CL) :-
@ -88,19 +104,19 @@ next_cleanup(CL) :-
(call(G);true), (call(G);true),
next_cleanup(CL). next_cleanup(CL).
% clean up all remaining stuff / reinitialize cleanup-module % clean up all remaining stuff / reinitialize cleanup-module
cleanup_all :- do_cleanup(1). cleanup_all :-
do_cleanup(1).
cleanup_all.
% register a cleanup predicate (normal reverse-order cleanup) % register a cleanup predicate (normal reverse-order cleanup)
on_cleanup(G) :- on_cleanup(G) :-
get_value('cleanup:level',L), bb_get(cleanup_level,L),
on_cleanup(L,G). on_cleanup(L,G).
on_cleanup(L,G) :- on_cleanup(L,G) :-
L =< 0, L =< 0,
throw(no_cleanup_context(G)). throw(error(instantiation_error,no_cleanup_context(G))).
on_cleanup(L,G) :- on_cleanup(L,G) :-
callable(G), callable(G),
recorda(cleanup:handle,(L,G),_). recorda(cleanup:handle,(L,G),_).
@ -108,7 +124,7 @@ on_cleanup(L,G) :-
% register a cleanup predicate (reverse-reverse-order cleanup) % register a cleanup predicate (reverse-reverse-order cleanup)
on_cleanupz(G) :- on_cleanupz(G) :-
get_value('cleanup:level',L), bb_get(cleanup_level,L),
on_cleanupz(L,G). on_cleanupz(L,G).
on_cleanupz(L,G) :- on_cleanupz(L,G) :-
@ -118,3 +134,32 @@ on_cleanupz(L,G) :-
callable(G), callable(G),
recordz(cleanup:handle,(L,G),_). recordz(cleanup:handle,(L,G),_).
% helpers
cleanup_expansion(X) :-
var(X),!,throw(error(instantiation_error,fragile(X))).
cleanup_expansion((H,T)) :- cleanup_expansion(H),cleanup_expansion(T).
cleanup_expansion([H,T]) :- cleanup_expansion(H),cleanup_expansion(T).
cleanup_expansion(G/A) :-
atom(G),integer(A),!,
compose_var_goal(G/A,GG),
\+ clause(user:goal_expansion(GG,M,NG),_), % TODO: match body too
assert(( user:goal_expansion(GG,M,NG)
:- bb_get(expansion_toggle,1)
-> bb_put(expansion_toggle,0),
NG=call_cleanup(M:GG)
; bb_put(expansion_toggle,1),
NG=M:GG )).
cleanup_expansion(X) :-
!,throw(error(instantiation_error,fragile(X))).
compose_var_goal(G/A,NG) :-
arity_to_vars(A,L), NG =.. [G|L].
arity_to_vars(N,L) :-
arity_to_vars(N,[],L).
arity_to_vars(N,L1,L2) :-
N > 0,
NN is N-1,
LT = [L|L1],
arity_to_vars(NN,LT,L2).
arity_to_vars(0,L,L).