trace.pl --

Allow tracing pengine execution under SWISH.

If true, trace in the browser. If false, use the default tracer. This allows for debugging pengine issues using the graphical tracer from the Prolog environment using:

?- retractall(swish_trace:trace_pengines).
?- tspy(<some predicate>).

add_context(+Port, +Frame, +Prompt0, -Prompt) is det[private]

Add additional information about the context to the debug prompt.

$swish wrapper(:Goal, ?ContextVars)

Wrap a SWISH goal in '$swish wrapper'. This has two advantages: we can detect that the tracer is operating on a SWISH goal by inspecting the stack and we can save/restore the debug state to deal with debugging next solutions.

ContextVars is a list of variables that have a reserved name. The hooks pre_context/3 and post_context/3 can be used to give these variables a value extracted from the environment. This allows passing more information than just the query answers.

The binding _residuals = '$residuals'(Residuals) is added to the residual goals by pengines:event_to_json/3 from pengines_io.pl.

pre_context(Name, Goal, Var) is semidet[multifile]

post_context(Name, Goal, Var) is semidet[multifile]

Multifile hooks to extract additional information from the Pengine, either just before Goal is started or after an answer was produced. Extracting the information is triggered by introducing a variable with a reserved name.

call_post_context(+Dict)[private]

call_post_context(+Goal, +Bindings, +Delays, +Var)[private]

Hook to allow filling Var from the context. I.e., there is a binding Name=Var in Bindings that gives us the name of what is expected in Var.

residuals(+PengineModule, -Goals:list(callable)) is det[private]

Find residual goals that are not bound to the projection variables. We must do so while we are in the Pengine as the goals typically live in global variables that are not visible when formulating the answer from the projection variables as done in library(pengines_io).

source_location(+Frame, +Port, -Location) is semidet[private]

Determine the appropriate location to show for Frame at Port.

If we have a PC (integer), we have a concrete clause-location, so use it if it is in the current file.
If we have a port, but the parent is not associated with our file, use it. This ensures that the initial query is shown in the source window.

parent_frame(+FrameIn, +PCOrPortIn, -Steps, -FrameOut, -PCOrPortOut) is nondet[private]

True when FrameOut/PCOrPortOut is a parent environment of FrameIn/PCOrPortIn. Backtracking yields higher frames.

frame_file(+Frame, -File) is semidet[private]

True when Frame is associated with a predicate that is defined in File.

pengine_file(+File) is semidet[private]

True if File is a Pengine controlled file. This is currently the main file (pengine://) and (swish://) for included files.

clause_position(+PC) is semidet[private]

True if the position can be related to a clause.

subgoal_position(+Clause, +PortOrPC, -File, -CharA, -CharZ) is semidet[private]

Character range CharA..CharZ in File is the location to highlight for the given clause at the given location.

source_position(Frame, PCOrPort, -Position)[private]

Get the source location for Frame at PCOrPort. Position is a dict.

pengines:prepare_goal(+GoalIn, -GoalOut, +Options) is semidet[multifile]

Handle the breakpoints(List) option to set breakpoints prior to execution of the query. If breakpoints are present and enabled, the goal is executed in debug mode. List is a list, holding a dict for each source that has breakpoints. The dict contains these keys:

file is the source file. For the current Pengine source this is pengine://<pengine>/src.
breakpoints is a list of lines (integers) where to put break points.

swish:tty_size(-Rows, -Cols)[private]

Emulate obtaining the screen size. Note that the reported number of columns is the height of the container as the height of answer pane itself is determined by the content.

swish:tty_size(-Rows, -Cols) is det[private]

Find the size of the output window. This is only registered when running ask. Notably during compilation it is not known. We provided dummy values to avoid failing.

set_file_breakpoints(+Pengine, +File, +Text, +Dict)[private]

Set breakpoints for included files.

set_pengine_breakpoint(+Pengine, +File, +Text, +Dict)[private]

Set breakpoints on the main Pengine source

update_breakpoints(+Breakpoints)[private]

Update the active breakpoint by comparing with the set of currently active breakpoints.

current_pengine_source_breakpoints(+PengineFile, -Pairs) is det[private]

Find the currently set breakpoints for the Pengine with the given source file PengineFile. Pairs is a list File-BreakPoints, where BreakPoints is a list of breakpoint-ID - Line pairs.

prolog_clause:open_source(+File, -Stream) is semidet[multifile]

Open SWISH non-file sources.

install_exception_hook[private]

Make sure our handler is the first of the hook predicate.