This module started life as part of the GUI tracer. As it is generally
useful for debugging purposes it has moved to the general Prolog
The tracer library library(trace/clause) adds caching and dealing with
dynamic predicates using listing to XPCE objects to this. Note that
clause_info/4 as below can be slow.
- clause_info(+ClauseRef, -File, -TermPos, -VarOffsets) is semidet
- clause_info(+ClauseRef, -File, -TermPos, -VarOffsets, +Options) is semidet
- Fetches source information for the given clause. File is the
file from which the clause was loaded. TermPos describes the
source layout in a format compatible to the subterm_positions
option of read_term/2. VarOffsets provides access to the
variable allocation in a stack-frame. See make_varnames/5 for
Note that positions are character positions, i.e., not
bytes. Line endings count as a single character, regardless of
whether the actual ending is
\n or =|\r\n|_.
Defined options are:
- Unify Names with the variable names list (Name=Var) as
returned by read_term/3. This argument is intended for
reporting source locations and refactoring based on
analysis of the compiled code.
- unify_term(+T1, +T2)
- Unify the two terms, where T2 is created by writing the term and
reading it back in, but be aware that rounding problems may
cause floating point numbers not to unify. Also, if the initial
term has a string object, it is written as "..." and read as a
code-list. We compensate for that.
NOTE: Called directly from library(trace/clause) for the GUI
- read_term_at_line(+File, +Line, +Module, -Clause, -TermPos, -VarNames) is semidet[private]
- Read a term from File at Line.
- open_source(+File, -Stream) is semidet[multifile]
- Hook into clause_info/5 that opens the stream holding the source
for a specific clause. Thus, the query must succeed. The default
implementation calls open/3 on the File property.
- make_varnames(+ReadClause, +DecompiledClause, +Offsets, +Names, -Term) is det
- Create a Term
varnames(...) where each argument contains the name
of the variable at that offset. If the read Clause is a DCG rule,
name the two last arguments <DCG_list> and <DCG_tail>
This predicate calles the multifile predicate
make_varnames_hook/5 with the same arguments to allow for user
extensions. Extending this predicate is needed if a compiler
adds additional arguments to the clause head that must be made
visible in the GUI tracer.
|Offsets||- List of Offset=Var|
|Names||- List of Name=Var|
- unify_clause(+Read, +Decompiled, +Module, +ReadTermPos, -RecompiledTermPos)[private]
- What you read isn't always what goes into the database. The task
of this predicate is to establish the relation between the term
read from the file and the result from decompiling the clause.
This predicate calls the multifile predicate unify_clause_hook/5
with the same arguments to support user extensions.
|Module||- is the source module that was active when loading this
clause, which is the same as prolog_load_context/2 using the
module context. If this cannot be established it is the module to
which the clause itself is associated. The argument may be used to
determine whether or not a specific user transformation is in scope.
See also term_expansion/2,4 and goal_expansion/2,4.
- To be done
- - This really must be more flexible, dealing with much
more complex source-translations, falling back to a
heuristic method locating as much as possible.
- unify_clause2(+Read, +Decompiled, +Module, +TermPosIn, -TermPosOut)[private]
- Stratified version to be used after the first match
- inlined_unification(+BodyRead, +BodyCompiled, -BodyReadOut, -BodyCompiledOut, +HeadRead, +BodyPosIn, -BodyPosOut) is det[private]
- inlineable_head_var(+Head, -Var) is nondet[private]
- True when Var is a variable in Head that may be used for inline
unification. Currently we only inline direct arguments to the head.
- expand_failed(+Exception, +Term)[private]
- When debugging, indicate that expansion of the term failed.
- unify_body(+Read, +Decompiled, +Module, +Pos0, -Pos)[private]
- Deal with translations implied by the compiler. For example,
compiling (a,b),c yields the same code as compiling a,b,c.
Pos0 and Pos still include the term-position of the head.
- does_not_dcg_after_binding(+ReadBody, +ReadPos) is semidet[private]
- True if ReadPos/ReadPos does not contain DCG delayed
- To be done
- - We should pass that we are in a DCG; if we are not there
is no reason for this test.
- unify_goal(+Read, +Decompiled, +Module, +TermPosRead, -TermPosDecompiled) is semidet[multifile]
- This hook is called to fix up source code manipulations that
result from goal expansions.
- ubody(+Read, +Decompiled, +Module, +TermPosRead, -TermPosForDecompiled)[private]
|Read||- Clause read after expand_term/2|
|Decompiled||- Decompiled clause|
|Module||- Load module|
|TermPosRead||- Sub-term positions of source|
- conj(+GoalTerm, +PositionTerm, -GoalList, -PositionList)[private]
- Turn a conjunctive body into a list of goals and their positions,
i.e., removing the positions of the (,)/2 terms.
- mkconj(+Decompiled, +Module, -Position, +ReadGoals, +ReadPositions)[private]
- argpos(+N, +PositionTerm, -ArgPositionTerm) is det[private]
- Get the position for the nth argument of PositionTerm.
- initialization_layout(+SourceLocation, ?InitGoal, -ReadGoal, -TermPos) is semidet
- Find term-layout of :- initialization directives.
- predicate_name(:Head, -PredName:string) is det
- Describe a predicate as [Module:]Name/Arity.
- clause_name(+Ref, -Name)
- Provide a suitable description of the indicated clause.
The following predicates are exported, but not or incorrectly documented.
- clause_info(Arg1, Arg2, Arg3, Arg4, Arg5)