1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html>
<head>
<title>PceEmacs Prolog mode</title>
</head>
<body>
<h1 align=center>Using PceEmacs in Prolog mode</h1>
<h2>Activating Prolog mode</h2>
<p>
Prolog mode is activated by loading a file that ends in the right
extension. The default extension for Prolog files is <b>.pl</b> and it
is therefore strongly adviced to give your Prolog sourcefiles the
extension <b>.pl</b>.
<p>
Alternatively the editor may always be switched to Prolog mode using the
<b>Mode</b> submenu of the <b>File</b> menu or using <b>M-x mode RET
prolog RET</b>. See also <a href="#jargon">jargon</a>.
<h2>Using Prolog Mode</h2>
<p>
PceEmacs Prolog mode provides support in the following areas
<ul>
<li><a href="#layout">Layout (indentation)</a>
<li><a href="#syntax">Syntax colouring based on parsing and cross-referencing</a>
<li><a href="#browsing">Browsing by jumping to definitions and showing help</a>
<li><a href="#loading">Loading files into Prolog</a>
</ul>
<h3><a name=layout>Layout (indentation)</a></h3>
<p>
Layout support is provided by automatic indentation and placement of
comments. This is achieved using the following commands:
<dl>
<dt><b>TAB</b><dd>
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:
<p>
<PRE>
head(Arg1, Arg2) :-
subclause(with, arguments),
( if
-> then
; else
),
subclause(with,
many,
arguments).
</PRE>
<dt><b>M-q</b><dd>
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 <b>TAB</b>.
See also <a href="#jargon">jargon</a>.
</dl>
<h3><a name=syntax>Syntax checking and colouring</a></h3>
<p>
After the user types a <b>full-stop</b> 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 <b>singleton</b>
variables a query-replace loop is started that allows the user to map
each singleton to <tt>_</tt> or <tt>_Name</tt>. A clause can be checked
explictly using the <b>\C-c\C-s</b> command.
<p>
After a 2 seconds <b>idle</b> time, and if the file is shorter than the
class-variable <tt>emacs_prolog_mode.auto_colourise_size_limit</tt>,
PceEmacs performs a parsing, cross-referencing and colouring of the
whole buffer. By default it will colour the following entities:
<dl>
<dt><table bgcolor="#e8e8e8"><tr><td><tt>:- directive</tt></table><dd>
Directives are displayed with a light-grey background to make them
stand-out in the file.
<dt><b><tt>normal head :-</tt></b><dd>
The head of a `normal' clause is displayed in a bold font to make the
clause stand-out.
<dt><font color=blue><b><tt>exported head :-</tt></b></font><dd>
The heads of clauses exported from the current file are bold-blue.
<dt><font color=red><b><tt>unused head :-</tt></b></font><dd>
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.
<dt><font color=black><tt>normal call</tt></font><dd>
Calls to locally defined predicates are displayed in the current font.
<dt><font color=blue><tt>built-in or imported call</tt></font><dd>
Calls to built-in predicates or imported predicates (through
<b>use_module/1</b> and friends) are displayed in blue.
<dt><font color=red><tt>undefined call</tt></font><dd>
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.
<dt><font color=purple><tt>call</tt></font><dd>
Call to a declared dynamic procedure are highlighted in purple.
</dl>
<p>
In addition, the argument to the <b>file-loading</b> directives
are displayed in <font color=blue><u>underlined blue</u></font> if
the file was found and in <font color=red>red</font> otherwise. Found
files have an associated <b>popup</b> to open them.
<h4>Extending the colouring</h4>
<p>
Colouring may be extended by defining rules for the multifile predicates
<b>emacs_prolog_colours:term_colours/2</b> and
<b>emacs_prolog_colours:goal_classification/2</b>. This interface is
rather immature. Please check the library file
<tt>emacs/prolog_colour.pl</tt> for more information.
<h3><a name=browsing>Browsing</a></h3>
<p>
This section describes the most important commands for finding your way
around. See also <a href="#jargon">jargon</a>.
<dl>
<dt><b>M-.</b><dd>
Bound to <b>find_definition</b> 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
<a href="#tips">the tips section</a>
<dt><b>Browse/Bookmark Line</b> and <b>Browse/Show bookmarks</b><dd>
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.
<dt><b>M-s</b> and the <b>pin</b> at the bottom-left<dd>
Normally, switching to another file causes the same window to be used.
You can toggle the pin at the bottom with the mouse or <b>M-s</b>
command. With the pin `in', the window is not reused for another
file.
<dt><b>\C-x2</b> and <b>\C-x1</b> to split windows<dd>
<b>\C-x2</b> 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.
<dt><b>Prolog/Prolog manual</b><dd>
This menu option prompts for a topic (using completion) of the
SWI-Prolog online manual also available through <b>help/1</b>. Without
a specified topic it calls <b>help/0</b>.
<dt><b>Prolog/Explain</b><dd>
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 <b>find references</b> to an
atom or <b>calls to a predicate</b>.
</dl>
<h3><a name=loading>Loading files into Prolog</a></h3>
<p>
The <b>Prolog menu</b> has various entries for loading the current file
or a part thereof. The most commonly used option is <b>Make</b>,
updating all loaded and modified files.
<h3><a name=tips>Tips</a></h3>
<p>
Over the years we have developed a discipline for working with Prolog
projects. We share this knowledge with you in this section.
<h4>The files for a project</h4>
<p>
Every file, possibly except for <tt>load.pl</tt> and <tt>run.pl</tt> is
declared as a <b>module file</b>. Why? It provides <em>documentation</em>
and <em>hiding</em> at practically no cost. The same information makes
PceEmacs cross-referencing work efficiently and providing the most
reliable information.
<p>
Projects generally have four files for project maintenance. These are
normal Prolog source-files helping you to load, run and maintain the
project.
<dl>
<dt><b>load.pl</b><dd>
This file defines rules for <b>file_search_path/2</b> 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 <b>use_module/1</b>, normally using the
symbolic path defined with <b>file_search_path/2</b> in
<tt>load.pl</tt>. Here is an example.
<pre>
/* File load.pl */
:- multifile
file_search_path/2.
file_search_path(rules, rules).
file_search_path(gui, xpce).
:- use_module(infer).
</pre>
<pre>
/* File infer.pl */
:- module(infer,
[ infer/2 % +Key, -Value
]).
:- use_module(rules(rules)).
...
</pre>
<dt><b>run.pl</b><dd>
Normally simply loads <b>load.pl</b> 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.
<dt><b>save.pl</b><dd>
Loads <b>load.pl</b>, defines the work to be done to create a
saved-state and calls this.
<dt><b>debug.pl</b><dd>
In this file you stick whatever is needed to debug and develop the
program. Traditionally this are clauses for <b>portray/1</b> 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.
</dl>
<p>
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.
<p>
On Unix, the same is achieved using <tt>pl -f <file></tt>.
<h4>Using PceEmacs</h4>
<p>
There are three reasonable options. The first, only applicable to
Unix platforms, is to start a <b>PceEmacs server</b> 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 <b>PceEmacs in a separate
Prolog</b> and the final option is to use the <b>same Prolog</b> as for
debugging your application.
<p>
Running in the <b>same process</b> 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.
<p>
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.
<p>
Which option is best depends on the nature of your program, your
experience and discipline.
<p>
In any case, use the SWI-Prolog <b>make/0</b> command to update the
system after changing the sources.
<h4><a name=jargon>PceEmacs jargon</a></h4>
<p>
On this page the following jargon is used:
<dl>
<dt><b>M-<key></b><dd>
Emacs-speak for a <em>Meta</em> command. There are two ways to activate
the command. One is <tt>Alt</tt>-<i>key</i> (i.e. the Alt-key together
with the named <i><key></i>) and the other is <tt>ESC</tt> followed
by <i><key></i>. Many Meta commands require arguments. If this is
the case PceEmacs displays a dialog for entering the values. Inside
these dialogs, <tt>TAB</tt> tries to complete the current value. The
left and right-arrows allow to re-use old values for this command. They
are bound to <b>M-p</b> and <b>M-n</b> (previous/next).
<dt><b>\C-<key></b><dd>
Emacs-speak for a <em>Control</em> command. In other systems also mentioned
as <b>^<key></b> or <b>Control-<key></b> or
<b>Ctrl-<key></b>.
</dl>
</body>
</html>
|
