document stream stuff (Nicos request).
git-svn-id: https://yap.svn.sf.net/svnroot/yap/trunk@2139 b08c6af1-5177-4d33-ba66-4b1c6b8b522a
This commit is contained in:
vsc
parent
fc22f62eb7
commit
8498d60233
219
docs/yap.tex
219
docs/yap.tex
@ -4326,6 +4326,54 @@ The initial mode is @code{prolog} for the user streams and
|
|||||||
|
|
||||||
@end table
|
@end table
|
||||||
|
|
||||||
|
@item current_line_number(-@var{LineNumber})
|
||||||
|
@findex current_line_number/1
|
||||||
|
@saindex current_line_number/1
|
||||||
|
@cnindex current_line_number/1
|
||||||
|
Unify @var{LineNumber} with the line number for the current stream.
|
||||||
|
|
||||||
|
@item current_line_number(+@var{Stream},-@var{LineNumber})
|
||||||
|
@findex current_line_number/2
|
||||||
|
@saindex current_line_number/2
|
||||||
|
@cnindex current_line_number/2
|
||||||
|
Unify @var{LineNumber} with the line number for the @var{Stream}.
|
||||||
|
|
||||||
|
@item line_count(+@var{Stream},-@var{LineNumber})
|
||||||
|
@findex line_count/2
|
||||||
|
@syindex line_count/2
|
||||||
|
@cnindex line_count/2
|
||||||
|
Unify @var{LineNumber} with the line number for the @var{Stream}.
|
||||||
|
|
||||||
|
@item character_count(+@var{Stream},-@var{CharacterCount})
|
||||||
|
@findex character_count/2
|
||||||
|
@syindex character_count/2
|
||||||
|
@cnindex character_count/2
|
||||||
|
Unify @var{CharacterCount} with the number of characters written to or
|
||||||
|
read to @var{Stream}.
|
||||||
|
|
||||||
|
@item line_position(+@var{Stream},-@var{LinePosition})
|
||||||
|
@findex line_position/2
|
||||||
|
@syindex line_position/2
|
||||||
|
@cnindex line_position/2
|
||||||
|
Unify @var{LinePosition} with the position on current text stream
|
||||||
|
@var{Stream}.
|
||||||
|
|
||||||
|
@item stream_position(+@var{Stream},-@var{StreamPosition})
|
||||||
|
@findex stream_position/2
|
||||||
|
@syindex stream_position/2
|
||||||
|
@cnindex stream_position/2
|
||||||
|
Unify @var{StreamPosition} with the packaged information of position on
|
||||||
|
current stream @var{Stream}. Use @code{stream_position_data/3} to
|
||||||
|
retrieve information on charater or line count.
|
||||||
|
|
||||||
|
@item stream_position_data(+@var{Field},+@var{StreamPsition},-@var{Info})
|
||||||
|
@findex stream_position_data/3
|
||||||
|
@syindex stream_position_data/3
|
||||||
|
@cnindex stream_position_data/3
|
||||||
|
Given the packaged stream position term @var{StreamPosition}, unify
|
||||||
|
@var{Info} with @var{Field} @code{line_count}, @code{byte_count}, or
|
||||||
|
@code{char_count}.
|
||||||
|
|
||||||
@end table
|
@end table
|
||||||
|
|
||||||
@node C-Prolog File Handling, I/O of Terms, Streams and Files, I/O
|
@node C-Prolog File Handling, I/O of Terms, Streams and Files, I/O
|
||||||
@ -4421,6 +4469,12 @@ controlled by the following options:
|
|||||||
|
|
||||||
@table @code
|
@table @code
|
||||||
|
|
||||||
|
@item term_position(-@var{Position})
|
||||||
|
@findex term_position/1 (read_term/2 option)
|
||||||
|
Unify @var{Position} with a term describing the position of the stream
|
||||||
|
at the start of parse. Use @code{stream_position_data/3} to obtain extra
|
||||||
|
information.
|
||||||
|
|
||||||
@item singletons(-@var{Names})
|
@item singletons(-@var{Names})
|
||||||
@findex singletons/1 (read_term/2 option)
|
@findex singletons/1 (read_term/2 option)
|
||||||
Unify @var{Names} with a list of the form @var{Name=Var}, where
|
Unify @var{Names} with a list of the form @var{Name=Var}, where
|
||||||
@ -6474,161 +6528,6 @@ Unify the current value of mutable term @var{M} with term @var{D}.
|
|||||||
Set the current value of mutable term @var{M} to term @var{D}.
|
Set the current value of mutable term @var{M} to term @var{D}.
|
||||||
@end table
|
@end table
|
||||||
|
|
||||||
@node Global Variables, Profiling, Profiling, Term Modification, Top
|
|
||||||
@section Global Variables
|
|
||||||
|
|
||||||
@cindex global variables
|
|
||||||
|
|
||||||
Global variables are associations between names (atoms) and
|
|
||||||
terms. They differ in various ways from storing information using
|
|
||||||
@node{assert/1} or @node{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
|
|
||||||
particularly interesting for large data structures such as parsed XML
|
|
||||||
documents or the CHR global constraint store.
|
|
||||||
|
|
||||||
@item They support both global assignment using nb_setval/2 and
|
|
||||||
backtrackable assignment using 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.
|
|
||||||
@end itemize
|
|
||||||
|
|
||||||
Currently global variables are scoped globally. We may consider module
|
|
||||||
scoping in future versions. 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_initialization/1} to define a global
|
|
||||||
variable it will be defined, restored after reloading a saved state
|
|
||||||
and created in all threads that are created after the
|
|
||||||
registration. Finally, global variables can be initialised using the
|
|
||||||
exception hook called @code{exception/3}. The latter technique is by
|
|
||||||
CHR.
|
|
||||||
|
|
||||||
@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
|
|
||||||
[] 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 @var{copy_term/2}) must be
|
|
||||||
taken. The @var{b_getval/2} predicate generates errors if @var{Name} is not
|
|
||||||
an atom or the requested variable does not exist.
|
|
||||||
|
|
||||||
@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 @var{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 @code{b_getval/2},
|
|
||||||
introduced for compatibility and symmetry. As most scenarios will use
|
|
||||||
a particular global variable either using non-backtracable or
|
|
||||||
backtrackable assignment, using @code{nb_getval/2} can be used to
|
|
||||||
document that the variable is used non-backtracable.
|
|
||||||
|
|
||||||
@item nb_linkval(+@var{Name}, +@var{Value})
|
|
||||||
@findex nb_linkval/2
|
|
||||||
@snindex nb_linkval/2
|
|
||||||
@cnindex nb_linkval/2
|
|
||||||
Associates the term @var{Value} with the atom @var{Name} without
|
|
||||||
copying it. This is a fast special-purpose variation of @code{nb_setval/2}
|
|
||||||
intended for expert users only because the semantics on backtracking
|
|
||||||
to a point before creating the link are poorly defined for compound
|
|
||||||
terms. The principal term is always left untouched, but backtracking
|
|
||||||
behaviour on arguments is undone if the original assignment was
|
|
||||||
trailed and left alone otherwise, which implies that the history that
|
|
||||||
created the term affects the behaviour on backtracking. Please
|
|
||||||
consider the following example:
|
|
||||||
|
|
||||||
@example
|
|
||||||
demo_nb_linkval :-
|
|
||||||
T = nice(N),
|
|
||||||
( N = world,
|
|
||||||
nb_linkval(myvar, T),
|
|
||||||
fail
|
|
||||||
; nb_getval(myvar, V),
|
|
||||||
writeln(V)
|
|
||||||
).
|
|
||||||
@end example
|
|
||||||
|
|
||||||
@item nb_set_shared_val(+@var{Name}, +@var{Value})
|
|
||||||
@findex nb_set_shared_val/2
|
|
||||||
@snindex nb_set_shared_val/2
|
|
||||||
@cnindex nb_set_shared_val/2
|
|
||||||
Associates the term @var{Value} with the atom @var{Name}, but sharing
|
|
||||||
non-backtrackable terms. This may be useful if you want to rewrite a
|
|
||||||
global variable so that the new copy will survive backtracking, but
|
|
||||||
you want to share structure with the previous term.
|
|
||||||
|
|
||||||
The next example shows the differences between the three built-ins:
|
|
||||||
@example
|
|
||||||
demo_nb_linkval :-
|
|
||||||
T = nice(N),
|
|
||||||
( N = world,
|
|
||||||
nb_linkval(myvar, T),
|
|
||||||
fail
|
|
||||||
; nb_getval(myvar, V),
|
|
||||||
writeln(V)
|
|
||||||
).
|
|
||||||
@end example
|
|
||||||
|
|
||||||
|
|
||||||
@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/2
|
|
||||||
@snindex nb_delete/2
|
|
||||||
@cnindex nb_delete/2
|
|
||||||
Delete the named global variable.
|
|
||||||
@end table
|
|
||||||
|
|
||||||
Global variables have been introduced by various Prolog
|
|
||||||
implementations recently. We follow the implementation of them in
|
|
||||||
SWI-Prolog, itself based on hProlog by Bart Demoen.
|
|
||||||
|
|
||||||
GNU-Prolog provides a rich set of global variables, including
|
|
||||||
arrays. Arrays can be implemented easily in YAP and SWI-Prolog using
|
|
||||||
@code{functor/3} and @code{setarg/3} due to the unrestricted arity of
|
|
||||||
compound terms.
|
|
||||||
|
|
||||||
|
|
||||||
@node Profiling, Call Counting, Global Variables, Top
|
|
||||||
=======
|
|
||||||
@node Global Variables, Profiling, Term Modification, Top
|
@node Global Variables, Profiling, Term Modification, Top
|
||||||
@section Global Variables
|
@section Global Variables
|
||||||
|
|
||||||
@ -13198,8 +13097,18 @@ If defined by the user, this predicate will be used to print goals by
|
|||||||
the debugger instead of @code{write/2}.
|
the debugger instead of @code{write/2}.
|
||||||
|
|
||||||
@item trace
|
@item trace
|
||||||
|
@findex trace/0
|
||||||
|
@syindex trace/0
|
||||||
|
@cyindex trace/0
|
||||||
Switches on the debugger and starts tracing.
|
Switches on the debugger and starts tracing.
|
||||||
|
|
||||||
|
@item notrace
|
||||||
|
@findex notrace/0
|
||||||
|
@syindex notrace/0
|
||||||
|
@cyindex notrace/0
|
||||||
|
Ends tracing and exits the debugger. This is the same as
|
||||||
|
@code{nodebug/0}.
|
||||||
|
|
||||||
@end table
|
@end table
|
||||||
|
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user