Tips and Tricks

Tips on using SPIDER.

Code Structure

SPIDER works best when each file defines a module and where no module spans multiple files.
SPIDER works best with self-contained code. That is, code that defines one module per file and that brings in all its dependencies using use_module/[1,2] etc.
SPIDER cannot expand code with goal_expansion or term_expansion except for special cases like Definite Clause Grammars.
Do not use conjunctions of directives, e.g. do not use:
```
:- op(foo,xfy,800), op(bar, fx, 10).
```
instead use separate directives, like:
```
:- op(foo,xfy,800).
:- op(bar, fx, 10).
```
This is required also for ISO compliance.

SPIDER knows about conditional compilation directives but has limited knowledge about whether a condition is true or not. It will warn if it encounters a condition it can not evaluate. In the context of a conditional directive the Prolog editor will handle the following goals:

current_prolog_flag(dialect, spider) is treated as true. This can be used to wrap code that should only be seen by the Prolog editor since this will never be true at runtime.
current_prolog_flag(dialect, sicstus) is treated as true. Other atomic values than spider and sicstus for the second argument are considered false.
In addition SPIDER handles true, false and some other simple built-ins and control structures.

Note that this restricted language is only used by SPIDER, whereas SICStus itself uses the full Prolog language when evaluating conditional directives.

The following example shows how conditional compilation can be used to supply SPIDER with special definitions of predicates etc.

:- if(current_prolog_flag(dialect,spider)).
%% Dummy definitions for SPIDER. SICStus will not see these.
foo(_,_). 
bar(_,_).
:- elif(current_prolog_flag(dialect,sicstus)).
%% SICStus, but not SPIDER, will see this code
foo(X,Y) :- some_goal(X,Y).
%% include some code that is not available in SPIDER
%% Presumably it defines bar/2.
:- include(generated_code).
:- else.
%% This code is for Prolog dialects other than SICStus.
foo(X,Y) :- throw(unsupported(foo(X,Y))).
bar(X,Y) :- throw(unsupported(bar(X,Y))).
:- endif.

SPIDER-specific code is useful with pseudo-directives, e.g. det/1 and nondet/1, that you only want SPIDER to see. For instance,

:- module(animals, [mybird/0, set_bird/1]).

:- if(current_prolog_flag(dialect,spider)).
%% Dummy definitions for SPIDER. SICStus will not see these.
%% These prevent SPIDER from complaing about undefined predicates
%% When they are used in directives.
det(_). 
nondet(_).
:- endif. % SPIDER

mybird :-
   animals(bird(Bird)),
   selected_bird(Bird),
   !,
   format('The selected bird was ~w~n', [Bird]).

:- if(current_prolog_flag(dialect,spider)).
% The SPIDER determinacy analyzer understands these.
:- nondet(animals/1).
:- det(selected_bird/1).
:- endif. % SPIDER

% SPIDER will infer that this predicate is not
% determinate in its first argument. The nondet-declaration above will
% ensure that SPIDER does not complain about this at higher warning
% levels.
animals(bird(penguin)).
animals(bird(pigeon).
animals(mammal(horse)).

% SPIDER would normally assume that a dynamic predicate is
(potentially) non-determinate but we know that this particular
predicate will always have at most one solution.
:- dynamic selected_bird/1.

% Set the bird.
% Usage example: set_bird(pigeon)
set_bird(Bird) :-
   retractall(selected_bird(_)),
   assert(selected_bird(Bird)).

Note: SICStus Prolog 4.2.1 provides an improved syntax for declaring determinacy that does not require conditional compilation, see the documentation for the determinacy analyzer.

Useful Commands

Right-click in a Prolog editor brings up a menu with commands. Additional commands are available from the menu bar.
CTRL-mouse click (CMD-mouse click on Mac OS X) on a predicate name will go to its definition. This also works for symbolic paths, e.g. the first argument to use_module/2 and variables. Alternatively you can use the F3 keyboard command.
CTRL-ALT-SHIFT-H when in a clause will go to the closest caller of the current predicate. Repeated invocations thus navigates backwards through the call hierarchy.
“Compile Prolog Source” (ALT-K) will ask to save any modified files and then compile the edited file in the running SICStus.
“Open Call Hierarchy” (CTRL-ALT-H) will open a tree of callers and other references to the predicate. This also works for symbolic paths and will tell you who loads a particular file.
“Open Prolog Toplevel” (CMD-ALT-Q C) (also available from the “SICStus” menu) will open the SICStus top-level view.
“Correct Indendation” (CTRL-I) will adjust the indent of the current line.
To start or re-start SICStus in the top-level view, click on the the “Restart Prolog” () button.
Double click in the left margin will create a spy-point or a line breakpoint. Adding a breakpoint to the first line of a predicate will create a spy-point if the module is known.
Note that line breakpoints only work if source info is enabled, i.e. with set_prolog_flag(source_info, on).
Breakpoints are persisted and automatically installed in any Prolog started from within SPIDER. You can temporarily disable all breakpoints from the Breakpoints view.
Right click in the left margin of a Prolog editor will bring up a menu with some useful commands.
It is possible to add key bindings for commands. This is a Eclipse feature, available from the Preferences. This way you can add a key binding for e.g. the “Consult Prolog Source” command, if desired.
“Open Profile”, available from the “SICStus” menu, will open the Profile view showing profiling info. Use set_prolog_flag(profiling, on) (new in SICStus 4.2) in Prolog to make Prolog collect profiling information. (In SICStus 4.1 you would use set_prolog_flag(compiling, profiledcode) before compiling the code to be profiled.)
“Open Coverage”, available from the “SICStus” menu, will open the Coverage view showing source code coverage information (requires SICStus Prolog 4.2). Source code coverage information is collected whenever profiling information is collected, i.e. when set_prolog_flag(profiling, on) is in effect. When SPIDER presents source code coverate in the Coverage view it will also show coverage information in the left margin of any affected source files.

The Indexer

The automatic source code indexer, will by default process all files in the project(s). This can lead to unneeded work and irrelevant warnings if there are files that should not be processed, e.g. data files or files written for other dialects of Prolog.

You can select a file, folder or Project in the Eclipse Project Explorer and select Properties from the context menu. There is a Prolog properties page with the following choices:

Index. -- If you uncheck it then the Indexer will not process the file or the folder contents except for files loaded by indexed files.
It may be worthwhile to uncheck this for some example folders in the SICStus library tree.
Note that the Indexer will skip non-Prolog files even if Index is checked so you do not need to uncheck this option for non-Prolog files.
Preferred -- Marks a file as the preferred root in a tree of load dependencies. This is useful when the load dependencies form a graph without a unique root. Typically you do not need to explicitly use this as the Indexer will figure out the load tree automatically.
Ignore -- Try to avoid processing the file or folder contents. This is not fully implemented in SPIDER 0.0.37.

It is possible to put these properties in a file located with the affected files. This ensures the properties are set whenever a new project is created and allows version control etc. The details are currently not documented and may change without notice. The curious can deduce the file format from the .spider_data files present below the SICStus Prolog library folder since SICStus Prolog 4.1.3.

There are also some Indexer-related preferences.

Suppress problem reporting for reference projects -- default checked. This avoids some work and distractions from computing problems in the SICStus libraries.
Source Indexing -- turn on or off the Indexer completely. Please report if you ever feel the need to turn off the indexer.
Show problems while editing -- some problems are expensive to detect. Unchecking this option will postpone expensive problem detection until files are saved.

Send feedback on SPIDER.