Working with PDT (all-in-one version)

The Prolog Editor

Awareness

 
Editing

 
Navigation & Search

 
Debugging

Syntax Highlighting

Depending on their properties, predicates, quoted atoms and comments are highlighted with a specific colours. These colours can be modified in the preferences.

Highlighting Indicated Property
Dynamic predicate
Built-in predicate
Meta predicate
Module transparent predicate
Normal predicate
Quoted atom
Comment

Name Highlighting

Occurences of atom and variable names are highlighted in the current clause. The highlighting is updated instantly, upon typing.

Highlighting in the editor Description
All occurences of the variable touched by the cursor are highlighted with a grey background.
All occurences of the atom touched by the cursor are highlighted with a grey background.
Singleton variables are highlighted with a red background.
Variables that start with “_” but occur multiply in the current clause are highlighted with a light ivory background.

Warnings and Errors

All SWI-Prolog errors and warnings that occur while consulting a file are displayed in the Prolog Editor:

  • Warnings are highlighted by a yellow underline and warning markers in the sidebars of the editor.
  • Syntax errors are highlighted by a red underline and error markers in the sidebars of the editor.

These errors and warnings are also displayed in the Eclipse Package Explorer and Eclipse Problems View:

Prolog Editor Package Explorer Problems View
Warnings
Errors

Saving and consulting files

The file which is opened in the editor can be consulted to the current process by pressing F9.

Whenever you save a file in the editor it is automatically (re)consulted. If you don't want a file to be consulted after saving you can save the file by pressing Ctrl+Alt+S or by selecting the menu item “Save without consult”. 1)

Furthermore you have the possibility to deactivate the reconsult on save in the Preferences. This means, that files will only be consulted manually.

Outline

The Outline view displays an outline of all predicates defined in the Prolog file opened in the editor. The Outline supports multi-file awareness, that is, it shows all the clauses of a predicate, also for multifile predicates:

  • First level: Modules.
  • Second level: Predicate indicators of predicates defined in this file and total number of clauses of each predicate (in this and in other files). Dynamic predicates are emphasized with blue text colour. The icon to the left of the predicate indicator represents the visibility of the predicate: A green icon indicates exported predicates and predicates in non-module files. A yellow icon indicates non-exported predicates of a module.
  • Third level:
    • Top: Clauses of the predicate defined in the local file (each clause with its first line number and its first argument. If the argument is a function term it is presented as Functor/Arity.
    • Rest: Other files that contain multifile contributions to the predicate.
  • Fourth level: Clauses in each file listed at the third level (= multifile contributions from other files). Each clause is displayed with its first line number and its first argument. If the argument is a function term it is presented as Functor/Arity.

In the outline, multifile predicates are shown either as “for” or “from” contributions:

  • For: If the local file contains predicates for remote modules the remote modules are displayed in the outline with a black arrow overlay on the module icon. Below each remote module icon, its local predicates are displayed with all their clauses: The local clauses at the top, followed by the other files that contribute clauses (at the third level) and the contributed contributed clauses (at the fourth level).
  • From: If local predicates from other files are listed below a file icon. The local clauses are displayed immediately below the predicate icon, no matter whether they are for the local module or another module.

A single click on the icon of a local predicate or clause selects the first line of that predicate / clause in the associated editor. A single click on the icon of remote clause has no effect. Double clicking a remote clause shows its first line in another editor. Single click is equivalent to navigating via the arrow keys, double click is equivalent to hitting <Return>.

The order of modules in the outline is

  1. local module first
  2. then remote modules in alphabetic order

Within each module's section, predicates are displayed by default according to the textual order in the local file. However, the predicates can also be sorted alphabetically using the corresponding icon in the outline's tool bar. The order of modules cannot be changed.

Quick Outline

In the Prolog Editor a quick outline is available via Ctrl+O or via the context menu.

When nothing is typed into the input field, the quick outline shows the same content as the outline view. Typing retains only the predicates whose name contains the typed string. Hitting Return when there is just one choice left jumps to that predicate.

Code Completion

The Prolog Editor supports code completion dependent on the current file and the loaded code in the currently selected Prolog process. Code completion in the Prolog editor uses the default Eclipse key binding (<Ctrl><Space>). The following elements are shown in the completion:

  • Predicates (, , , ): All matching predicates that are visible in the module of the current file.
    • If the prefix is qualified with a module, all matching predicates visible in the qualifying module are listed.
    • If a documentation of a predicate is availabe, it is shown in the right window.
    • The icon shows the visibility of the predicate.
    • The text inserted as completion depends on the key mask when accepting a proposal:
      • No key mask: A predicate head is inserted. It is possible to navigate through the arguments with <TAB>. If a documentation is available, the argument names defined in the documentation will be used as variables for the inserted head.
      • CTRL: A predicate indicator (Functor / Arity) is inserted.
  • Modules (): all matching modules.
  • atoms (): all matching atoms currently known in the prolog system.
  • logtalk templates (): all matching logtalk templates for entities, directives, etc. only available in logtalk files.

the following table shows some examples for the completion (click on the images to enlarge).

predicates and atoms modules and atoms logtalk templates Code completion in the Prolog Editor Code completion in the Prolog Editor Code completion in the Prolog Editor

Open Primary Declaration

Select a predicate call and run Open Primary Definition or Declaration The cursor goes to line 17 Suggested alternatives if a non-existing or locally invisible predicate is searched

Open Primary Definition or Declaration offers the possibility to easily jump to the first clause of a selected predicate, similar to the “Open Declaration” command in the Java editor. In the example above the declaration is contained in the same file and therefore the cursor will jump to line 17. If the declaration of the predicate is contained in another file, the other file will be opened in new editor.

  • In case of multifile predicates the first clause which is found will be opened in the editor. Additionally the find definitions and declarations search will be started to display all clauses.
  • If the selected predicate exists but there is no source for it, a message will be displayed.
  • If the selected predicate does not exist or is not visible locally, the editor will offer a list of similar predicates or show a warning if there are no similar predicates.

Find Definitions and Declarations

Search for all declarations and definitions of the currently selected predicate in the editor. This search is done using the currently selected prolog process in the Prolog Console. The resulting modules get a visibility depending on the context of the selected goal. Possible values for visibility are local, super, sub and invisible.

Find References

Search for all references to the currently selected predicate in the editor. This search is done using the currently selected prolog process in the Prolog Console. Each result represents one clause that contains a call to the selected predicate.

Breakpoints

SWI Prolog offers the possibility of setting breakpoints in the prolog code. These breakpoints are visible in the SWI GUI Tracer and they can be set and removed within the GUI Tracer.
The PDT Prolog Editor also displays these breakpoints. These breakpoints are those from the currently selected prolog process in the Prolog Console. In the PDT Prolog Editor, one line in the editor can only have one breakpoint. It is possible to set and remove breakpoints directly from the editor. This can be done by double-clicking at the required location on the bar at the left edge of the editor or by using the context menu at the same location (see the screenshots below).
Setting a breakpoint in the editor means setting the breakpoint in the currently selected prolog process in the Prolog Console. Therefore the file in the editor must be consulted in this prolog process, otherwise setting of breakpoints is not possible.

Breakpoint in the SWI GUI Tracer The same breakpoint in the PDT Prolog Editor Context menu of the bar at the left edge of the editor

External files

Files which are not contained in any project in the workspace are called external files. For example the prolog code of SWI Prolog is usually not contained in any project in the workspace. To emphasize that a file in the Prolog Editor is an external file the editor uses a different icon in the editor title bar and the background colour of the editor is different (light gray).

Open a file with edit/1

The SWI-Prolog predicate edit/1 can be used in the Prolog Console to open a Prolog editor for any currently loaded predicate that has attached source code. This applies also to predicates residing in external files.

E. g. the query ”?- edit(member).” will open the library file “lists.pl” and position the cursor in the first clause of member/2 (see screenshots).

Even system files, that is, libraries that are part of the PDT or your Prolog system can be edited this way. However, this is something for experts. You should be very sure you know what you are doing.

Even then, please be aware that the default behaviour of saving an edited file includes reconsulting the file. So it is very easy to break a running system if you edit a system file and save it before editing another file that would need a consistent change.

If you want to perform a set of related changes in different system files use <Ctrl> <Alt> S for saving, disabling the auto-consult for that particular action. You can also change the default behaviour of <Ctrl> S in the PDT preferences.

1) Note that the file icon in the Project Explorer will become yellow to illustrate that an older version of the file is consulted
· %2012/%04/%13 %13:%Apr

The Prolog Console

The Prolog Console View lets you

  • Control Prolog processes
  • Query Prolog predicates
  • Generate load files
  • Run the debugger, profiler and other SWI-Prolog tools
  • Use some special editing features
  • Jump to error lines in editors

Prolog Console

Processes

The Prolog Console offers a unified entry point for interacting with different Prolog processes. The name of the current Prolog process is always displayed in the top left corner of the Console. If no current Prolog Process is selected, the process selector (first button in the Prolog Console's toolbar) displays a yellow warning triangle:

Console with current Prolog Process Console without current Prolog Process
Console with current Prolog Process Console without current Prolog Process

With the Process Control Buttons buttons in the toolbar of the Prolog Console you can:

  • Switch process Select the current Prolog process.
  • New process Start a new Prolog process and name it as you like. If you open the drop down menu you will see a list of all defined configurations for Prolog processes.

    Selecting a configuration in this list will start a new process using the selected configuration. The default configuration is emphasized with an icon. If you use the button and not the drop down menu to start a process, this process will use the default configuration.
  • Restart process Restart the current process, reconsulting all currently consulted files after the restart. All active breakpoints will be preserved. WARNING: All non-persistent information (in particular, dynamically modified clauses) will be lost after restart :!: The automatical reconsult can be disabled in the preferences.
  • Stop process Stop and Remove (kill) the current process. WARNING: The whole information of this process (breakpoints, dynamic facts, etc) will be lost after this action :!: If there is a “Default Console” the Console View will switch to this.
Restarting a process

If you want to restart a process there are three possible ways to handle the reconsulting of files.

  • no reconsult: no additional files will be consulted, you have to consult everything manually
  • reconsult entry points: of all the currently consulted files, only those which are marked as entry points will be reconsulted. This is the default behaviour.
  • reconsult all files: all files which are currentyl consulted will be reconsulted

Queries and Results

A query is typed at the Console's prompt and terminated with a full-stop ('.'). Hitting <enter> after the full stop issues the query to the Prolog system and displays the results (if any). If there are multiple resultes, the Console background will turn yellow to indicate that the Console is waiting for user directives as whether to continue or terminate the query. Typing semicolon(';') or simply hitting the space bar displays the next result or 'false', if there are no more results. Hitting <enter> or typing 'a' aborts the query.

Backtracking in the console

Tracing or Aborting Long Running Queries

If you started a query that does not seem to stop you can try one of the following:

  • Pause the query and continue it under the control of the GUI tracer to see what is happening behind the scenes.
  • Abort the query

To trace a query from the very start, just prepend ”trace, ” to your query (e.g. type ”trace, p(X,Y).”). This will open by default the GUI tracer.

On Windows windows opened from the console sometimes start in iconified mode. So if your tracer, profiler, process monitor, etc. do not appear, check the bar at the bottom of the screen for new Prolog Process icons.

Auto-Completion

The Prolog Console supports code completion using the key binding <Ctrl><Space> or <TAB>. The following elements are shown in the completion:

  • Predicates (, ): all matching predicates that are visible in ::user::.
    • if the prefix is qualified with a module, all matching predicates visible in the qualifying module are listed.
    • if a documentation of a predicate is availabe, it is shown in the right window.
    • the icon shows the visibility of the predicate.
    • the text inserted as completion depends on the key mask when accepting a proposal:
      • no key mask: a predicate head is inserted. if a documentation is available, the argument names defined in the documentation will be used as variables for the inserted head.
      • ctrl: a predicate indicator (::functor:: : ::arity::) is inserted.
      • shift: a predicate name is inserted.
  • modules (): all matching modules.
  • atoms (): all matching atoms currently known in the prolog system.

the following table shows some examples for the completion (click on the images to enlarge).

predicates modules and atoms
Code completion in the Prolog Console Code completion in the Prolog Console

Console History

The Prolog Console View supports a history mechanism (see keyboard shortcuts).

Loadfile Creation

If you manually consulted multiple files into a Prolog process you can click the button on the right-hand-side of the Console's toolbar to create a file that will load all manually consulted files. Of course, you can edit it manually afterwards. Load file creation is handy if you want to consult the same set of files in a different process or after restarting Eclipse. It avoids errors otherwise caused by forgetting to (re)load certain recently created files.

Generate load file

By default, the created load file will be marked as an entry point.

SWI-Prolog Tools

If you click the arrow on the right side of the toolbar you can use some of the graphical tools of SWI-Prolog:

Menu for starting graphical tools of SWI-Prolog

  • Activates and deactivates the SWI-Prolog GUI tracer (activated by default): If active, show graphical trace information at source level. If deactivated, sue console tracing.
  • SWI-Prolog thread monitor: Open a graphical window showing Prolog threads and their status.
  • SWI-Prolog debug message monitor: Open a graphical overview of current 'debug topics' and shows accumulated debug messages for each topic.

Context Menu

In addition to the usual editing operations (Select All, Copy, Cut, Paste) the context menu of the Prolog Console lets you paste the complete path of the file that is open in the currently active Prolog Editor. This is very helpful if you want to set breakpoints manually, for example.

Open Search Dialog from Console

Sometimes you find a predicate name in the console and you want to use it in a search query. This happens for example if you have some undefined predicate and you want to find all references to it. For this you can mark the predicate name in the console and select “Open Search Dialog” from the context menu. The Prolog Search dialog will be opened and it will get the current selection of the console as input.

Open Search Dialog from Console Search Dialog
The highlighted text… …is the input for the search dialog.

Go to error location

SWI-Prolog reports warnings and errors while consulting a file. If the location is given, the prolog console links the message to the location, where the problem occurs.

A click on the linked error message … … opens an editor at the blamed line

Colored Output

  • Colored output is triggered by special keywords at the beginnig of each line: "***", “INFO:” , “WARNING:” , “ERROR:”, “DEBUG:”. The keywords are case-insensitive.
  • Each line indented with tabs or (at least) two spaces is colored like the preceeding line.
  • By default, "***" is treated like “INFO:”. Defaults can be overridden and output color can be (de)activated in the PDT preferences.
Colored output on the console definition of the predicate

Console Preferences

The Prolog Console appearance can be configured in the PDT Preferences:

GUI Tracer

This is the documentation for the PDT 1.0 beta. The documentation for the previous versions is here.

The GUI Tracer Window

If GUI tracing is enabled, the query

 ?- trace, p(X,Y,Z).

opens the SWI-Prolog GUI tracer as a new window ( A note to Windows users ) that

  1. Shows bindings of variables
  2. Shows the call stack of the running Prolog process
  3. Shows the contents of the prolog source file and the executed goal.
  4. Shows the type of call: initial call (green), redo (yellow), fail (red) and success (blue).

The SWI-Prolog GUI tracer window

The tool bar of the SWI-Prolog GUI tracer offers some useful shortcuts

The SWI-Prolog GUI tracer toolbar.

The buttons in (1) provide - from left to right - the option to show the unifier for the current goal, step into the current goal's execution, step over it or finish the selected goal. The buttons in (2) provide - from left to right – the option to step to the next spy point, add spy points, set a stop at the caret and to remove spy points. For details on other buttons see the respective tool tip.

Inspecting Variable Bindings

If a variable's value is too long to fit in the bindings frame (1) you can view it in full in a separate window by double clicking the variable in (1)

Viewing large variable bindings in the SWI-Prolog GUI-Tracer

Setting Breakpoints

It is also possible to set breakpoints in the Editor. See breakpoints.

ViaEdit > Breakpoints you can define spy points on predicates occurring in the program (by entering the predicate's name/arity and then pressing the left-most button – see red arrow).

Setting breakpoints in the SWI-Prolog GUI-Tracer

· %2012/%04/%13 %13:%Apr
Last modified: 2017/08/29 16:22
*