Did you know ... Search Documentation:
prolog_clause.pl -- Get detailed source-information about a clause
PublicShow source

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 library.

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.

Source clause_info(+ClauseRef, -File, -TermPos, -VarOffsets) is semidet
Source 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 details.

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:

variable_names(-Names)
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.
head(-Head)
body(-Body)
Get the head and body as terms. This is similar to clause/3, but a seperate call would break the variable identity.
Source 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 tracer.

Source read_term_at_line(+File, +Line, +Module, -Clause, -TermPos, -VarNames) is semidet[private]
Read a term from File at Line.
Source 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. 
clause_property(ClauseRef, file(File)),
prolog_clause:open_source(File, Stream)
Source 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.

Arguments:
Offsets- List of Offset=Var
Names- List of Name=Var
Source 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.

Arguments:
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.
Source unify_clause2(+Read, +Decompiled, +Module, +TermPosIn, -TermPosOut)[private]
Stratified version to be used after the first match
Source inlined_unification(+BodyRead, +BodyCompiled, -BodyReadOut, -BodyCompiledOut, +HeadRead, +BodyPosIn, -BodyPosOut) is det[private]
Source 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.
Source expand_failed(+Exception, +Term)[private]
When debugging, indicate that expansion of the term failed.
Source 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.

Source does_not_dcg_after_binding(+ReadBody, +ReadPos) is semidet[private]
True if ReadPos/ReadPos does not contain DCG delayed unifications.
To be done
- We should pass that we are in a DCG; if we are not there is no reason for this test.
Source 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.
Source ubody(+Read, +Decompiled, +Module, +TermPosRead, -TermPosForDecompiled)[private]
Arguments:
Read- Clause read after expand_term/2
Decompiled- Decompiled clause
Module- Load module
TermPosRead- Sub-term positions of source
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.
Source mkconj(+Decompiled, +Module, -Position, +ReadGoals, +ReadPositions)[private]
Source argpos(+N, +PositionTerm, -ArgPositionTerm) is det[private]
Get the position for the nth argument of PositionTerm.
Source initialization_layout(+SourceLocation, ?InitGoal, -ReadGoal, -TermPos) is semidet
Find term-layout of :- initialization directives.
Source predicate_name(:Head, -PredName:string) is det
Describe a predicate as [Module:]Name/Arity.
Source clause_name(+Ref, -Name)
Provide a suitable description of the indicated clause.

Re-exported predicates

The following predicates are exported from this file while their implementation is defined in imported modules or non-module files loaded by this module.

Source clause_info(+ClauseRef, -File, -TermPos, -VarOffsets) is semidet
Source 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 details.

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:

variable_names(-Names)
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.
head(-Head)
body(-Body)
Get the head and body as terms. This is similar to clause/3, but a seperate call would break the variable identity.