Using PceEmacs in Prolog mode

Activating Prolog mode

Prolog mode is activated by loading a file that ends in the right extension. The default extension for Prolog files is .pl and it is therefore strongly adviced to give your Prolog sourcefiles the extension .pl.

Alternatively the editor may always be switched to Prolog mode using the Mode submenu of the File menu or using M-x mode RET prolog RET. See also jargon.

Using Prolog Mode

PceEmacs Prolog mode provides support in the following areas

Layout (indentation)

Layout support is provided by automatic indentation and placement of comments. This is achieved using the following commands:

TAB
Indent the current line. If the system figures out your are typing arguments to a term or list the alignment is based on the opening brace. Otherwise it aligns clause-heads and bodies. The example below illustrates the typical layout for which automatic indentation is designed: 

head(Arg1, Arg2) :-
	subclause(with, arguments),
	(   if
	->  then
	;   else
	),
	subclause(with,
		  many,
		  arguments).
M-q
Meta-q formats a paragraph. If the caret is in a long comment, this behaviour is retained, but if the caret is in a clause all lines of the clause will re-indented using the same rules as used for TAB. See also jargon.

Syntax checking and colouring

After the user types a full-stop character not inside a string or comment, the system will parse the current clause and colourise it. If the syntax is not correct, the clause is not colourised and the Prolog warning is displayed in the PceEmacs status window. In addition, if the syntax is correct and the clause contains singleton variables a query-replace loop is started that allows the user to map each singleton to _ or _Name. A clause can be checked explictly using the \C-c\C-s command.

After a 2 seconds idle time, and if the file is shorter than the class-variable emacs_prolog_mode.auto_colourise_size_limit, PceEmacs performs a parsing, cross-referencing and colouring of the whole buffer. By default it will colour the following entities:

:- directive
Directives are displayed with a light-grey background to make them stand-out in the file.
normal head :-
The head of a `normal' clause is displayed in a bold font to make the clause stand-out.
exported head :-
The heads of clauses exported from the current file are bold-blue.
unused head :-
The heads of unused clauses are bold-red. Unused means the cross-referencer, only working on the current file does not find a reference. This might not be an error if the cross-referencer is not able to resolve the call or the file is not a module-file and the predicate is called from another file or directly by the user.
normal call
Calls to locally defined predicates are displayed in the current font.
built-in or imported call
Calls to built-in predicates or imported predicates (through use_module/1 and friends) are displayed in blue.
undefined call
Calls to predicates for which the system finds no definition are painted in red. If you work top-down, this nicely highlights the loose ends of your code. If you intended to call a built-in you know you made an error.
call
Call to a declared dynamic procedure are highlighted in purple.

In addition, the argument to the file-loading directives are displayed in underlined blue if the file was found and in red otherwise. Found files have an associated popup to open them.

Extending the colouring

Colouring may be extended by defining rules for the multifile predicates emacs_prolog_colours:term_colours/2 and emacs_prolog_colours:goal_classification/2. This interface is rather immature. Please check the library file emacs/prolog_colour.pl for more information.

Browsing

This section describes the most important commands for finding your way around. See also jargon.

M-.
Bound to find_definition and also available from the Prolog menu, this command locates predicate definitions. It also finds built-in predicates if they are defined in Prolog. It works by inspecting the Prolog database and therefore works best if PceEmacs is run from a Prolog with a copy of the program under development loaded. See also the tips section
Browse/Bookmark Line and Browse/Show bookmarks
Add a line to the bookmarks. This also opens the bookmark editor. Bookmarks are useful if development or debugging requires several pieces of the source from very different locations.
M-s and the pin at the bottom-left
Normally, switching to another file causes the same window to be used. You can toggle the pin at the bottom with the mouse or M-s command. With the pin `in', the window is not reused for another file.
\C-x2 and \C-x1 to split windows
\C-x2 makes a clone of the current window. Both windows operate on the same file. This often used to examine related code in the same file.
Prolog/Prolog manual
This menu option prompts for a topic (using completion) of the SWI-Prolog online manual also available through help/1. Without a specified topic it calls help/0.
Prolog/Explain
This menu option provides access to the `explain' facility of the online help system, forcing the system to tell anything it knows about an identifier. One of the useful things is to find references to an atom or calls to a predicate.

Loading files into Prolog

The Prolog menu has various entries for loading the current file or a part thereof. The most commonly used option is Make, updating all loaded and modified files.

Tips

Over the years we have developed a discipline for working with Prolog projects. We share this knowledge with you in this section.

The files for a project

Every file, possibly except for load.pl and run.pl is declared as a module file. Why? It provides documentation and hiding at practically no cost. The same information makes PceEmacs cross-referencing work efficiently and providing the most reliable information.

Projects generally have four files for project maintenance. These are normal Prolog source-files helping you to load, run and maintain the project.

load.pl
This file defines rules for file_search_path/2 that enable different parts of the program to find each other, possibly other path declarations and then loads the files required by the project. Modules needing each other do so using use_module/1, normally using the symbolic path defined with file_search_path/2 in load.pl. Here is an example. 
/* File load.pl */

:- multifile
	file_search_path/2.

file_search_path(rules, rules).
file_search_path(gui,   xpce).

:- use_module(infer).

/* File infer.pl */

:- module(infer,
	  [ infer/2			% +Key, -Value
	  ]).
:- use_module(rules(rules)).

...
run.pl
Normally simply loads load.pl and starts the toplevel goal. Having this file makes it clear how the application is started and allows you to start it just activating this file.
save.pl
Loads load.pl, defines the work to be done to create a saved-state and calls this.
debug.pl
In this file you stick whatever is needed to debug and develop the program. Traditionally this are clauses for portray/1 to redefine the printing of large or otherwise unreadable terms. You can add settings for the debugger, loading the graphical debugger, rules for syntax-colouring in PceEmacs, test and debug queries, etc.

Having all this basic stuff in a file on their own is especially handy on MS-Windows, where double-clicking the right file in the explorer now satisfies for running, saving or debugging/developing the program. The load-file contains the common ground for these three functions.

On Unix, the same is achieved using pl -f <file>.

Using PceEmacs

There are three reasonable options. The first, only applicable to Unix platforms, is to start a PceEmacs server as part of the X11 setup and use this as a server. The details are in the general help on PceEmacs. The second option is to run PceEmacs in a separate Prolog and the final option is to use the same Prolog as for debugging your application.

Running in the same process is attractive, as it provides PceEmacs access to all resources for optimal browsing and reliable cross-referencing. Unfortunately you cannot edit if your program is actively running and fatal crashes of your program bring your editor down, loosing unsaved work, undo-information, open buffers, bookmarks, etc.

A good alternative is to run PceEmacs is a separate Prolog that has your program loaded as well, but is not used to run it. This provides PceEmacs with all required information without the risk for losing information if you have to restart the Prolog holding your running program.

Which option is best depends on the nature of your program, your experience and discipline.

In any case, use the SWI-Prolog make/0 command to update the system after changing the sources.

PceEmacs jargon

On this page the following jargon is used:

M-<key>
Emacs-speak for a Meta command. There are two ways to activate the command. One is Alt-key (i.e. the Alt-key together with the named <key>) and the other is ESC followed by <key>. Many Meta commands require arguments. If this is the case PceEmacs displays a dialog for entering the values. Inside these dialogs, TAB tries to complete the current value. The left and right-arrows allow to re-use old values for this command. They are bound to M-p and M-n (previous/next).
\C-<key>
Emacs-speak for a Control command. In other systems also mentioned as ^<key> or Control-<key> or Ctrl-<key>.