How do I use eclipse?

Getting started

To start ECLiPSe, type the command eclipse at an operating system command-line prompt. This will display something like this:

% eclipse
ECLiPSe Constraint Logic Programming System [kernel]
Copyright Imperial College London and ICL
Certain libraries copyright Parc Technologies Ltd
GMP library copyright Free Software Foundation
Version X.Y.Z, DAY MONTH DD HH:MM YYYY
[eclipse 1]:

The list in square brackets on the first line specifies the configuration of the running system, i.e. the language extensions that are present. The copyright and version information is followed by the prompt [eclipse 1]:, which tells the user that the top-level loop is waiting for a user query in the module eclipse. The predicate help/0 gives general help and help/1 gives help about specific built-in predicates.

Interacting with the top level loop

The ECLiPSe prompt [eclipse 1]: indicates that ECLiPSe is at the top level and the opened module is eclipse. The top level loop is a procedure which repetitively prompts the user for a query, executes it and reports its result, i.e. either the answer variable bindings or the failure message. There is always exactly one module opened in the top level and its name is printed in the prompt. From this point it is possible to enter ECLiPSe goals, e.g. to pose queries, to enter an ECLiPSe program from the keyboard or to compile a program from a file. Goals are entered after the prompt and are terminated by full stop and newline.

The ECLiPSe system may be exited by typing CTRL-D (UNIX) or CTRL-Z + RETURN (Windows) at the top level prompt, or by calling either the halt/0 or the exit/1 predicates.

Compiling a program

The square brackets [...] or the compile/1 predicate are used to compile ECLiPSe source from a file. If the goal

compile(myfile).

or the short-hand notation

[myfile].

is called, either as a query at the top level or within another goal, the system looks for the file myfile or for a file called myfile.pl or myfile.ecl and compiles it. The short-hand notation may also be used to compile several files in sequence:

[ file_1, file_2, ..., file_n ]

The compile/2 predicate may be used to compile a file or list of files into a module specified in the second argument.

If a file has been modified since it was compiled, it may be recompiled by invoking the make/0 predicate. This recompiles any files which have become out-of-date.

For more information on program compilation and the compiler, please see chapter 6.

Entering a program from the terminal

Programs can be entered directly from the terminal, as well as being read from files. To do this, simply compile the special file user. That is, [user]. or compile(user). at a top level prompt. The system then displays the compiler prompt (which is a blank by default) and waits for a sequence of clauses. Each of the clauses is terminated by a full stop. (If the fullstop is omitted the system just sits waiting, because it supposes the clause is not terminated. If you omit the stop by accident simply type it in on the following line, and then proceed to type in the program clauses, each followed by a full stop and carriage return.) To return to the top level prompt, type CTRL-D (UNIX), CTRL-Z + RETURN (Windows) or enter the atom end_of_file followed by fullstop and RETURN.

For example:

[eclipse 1]: [user].
 father(abraham, isaac).
 father(isaac, jacob).
 father(jacob, joseph).
 ancestor(X, Y) :- father(X, Y).
 ancestor(X, Y) :- ancestor(X, Z), ancestor(Z, Y).
 ^D
  user       compiled traceable 516 bytes in 0.00 seconds

yes.
[eclipse 2]:

The two predicates father/2 and ancestor/2 are now compiled and can be used.

Executing a query

Once a set of clauses has been compiled, it may be queried in the usual Prolog manner. If there are no uninstantiated variables in the query, the system replies 'yes' or 'no' and prompts for another query, for example:

[eclipse 1]: father(jacob, joseph).
yes.
[eclipse 2]:

If there are uninstantiated variables in the query, the system will attempt to find an instantiation of them which will satisfy the query, and if successful it will display one such instantiation. It will then wait for a further instruction: either a <CR> (``newline'' or ``return'') or a semi-colon ';'. A return will end the query successfully. A semi-colon will initiate backtracking in an attempt to find another solution to the query. Note that it is not necessary to type a new line after the semicolon -- one keystroke is enough. When the top level loop can detect that there are no further solutions, it does not wait for the semicolon or newline, but it displays directly the next prompt. For example in a query on a family database:

[eclipse 2]: father(X, Y).
X = abraham
Y = isaac   More? (;)   (';' typed)

X = isaac
Y = jacob

yes.
[eclipse 3]:

Queries may be extended over more than one line. When this is done the prompt changes to a tabulation character, i.e. the input is indented to indicate that the query is not yet completed. The fullstop marks the end of the input.

Interrupting the execution

If a program is executing, it may be interrupted by typing CTRL-C (interrupt in the UNIX environment). This will invoke the corresponding interrupt handler (see section 13.3). By default, the system prints a menu offering some alternatives:

^C
interruption: type a, b, c, e, or h for help : ? help
        a : abort
        b : break level
        c : continue
        e : exit
        h : help

interruption: type a, b, c, e, or h for help : ?

The a option returns to the toplevel, b starts a nested toplevel, c continues the interrupted execution, d switches the debugger to creep mode (provided it is running), and e is an emergency exit of the whole ECLiPSe session.

The execution of ECLiPSe may be suspended by typing CTRL-Z (suspend) or by calling pause/0. This will suspend the ECLiPSe process and return the UNIX prompt. Entering the shell command fg will return to ECLiPSe. Note that this feature may not be available on all systems.

Debugging a program

Please see the chapters on debugging in the tutorial and user manuals for more details. The tutorial chapter covers the TkECLiPSe debugging in a tutorial style tour, and the user manual chapter covers debugging in general and the command-line debugger in particular.

The history mechanism

The ECLiPSe toplevel loop provides a simple history mechanism which allows the examination and repetition of previous queries. The history list is printed with the command h. A previous query is invoked by typing either its absolute number or its relative negative offset from the current query number (i.e. -1 will execute the previous query). The current query number is displayed in the toplevel prompt.

The history is initialized from the file .eclipse_history in the current directory or in the home directory. This file contains the history goals, each ended by a fullstop. The current history can be written using the predicate write_history/0 from the util library.

Getting help

Detailed documentation about all the predicates in the ECLiPSe libraries can be obtained online through the help facility. It has two modes of operation. First, when a fragment of a built-in name is specified, a list of short descriptions of all built-ins whose name contains the specified string is printed. For example,

:- help(write).

will print one-line descriptions about write/1, writeclause/2, etc. When a unique specification is given, the full description of the specified built-in is displayed, e.g. in

:- help(write/1).