How do I write an ECLiPSe program?

## 2.5 How do I write an ECLiPSe program?

- Compiling a program
- Executing a query
- Editing a file
- Debugging a program
- File menu
- Getting help
- Other tools

You need to use an editor to write your programs. ECLiPSe does not come with an editor, but any editor that can save plain text files can be used. Save your program as a plain text file, and you can then compile the program into ECLiPSe and run it.
Extra support for editing ECLiPSe programs with common editors are available. An eclipse mode for the GNU emacs editor is bundled with the ECLiPSe package. This mode provides syntax highlighting, automatic indentation and many other features. To use this mode, you need to load the `eclipse.el` file into emacs. This is done by adding the following line to your `.emacs` file:

    (autoload 'eclipse-mode "<eclipsedir>/lib_public/eclipse.el" "ECLIPSE editing mode" t)

where `<eclipsedir>` is the path to your ECLiPSe installation directory.
With TkECLiPSe, you can specify the editor you want to use, and this editor will be started by TkECLiPSe, e.g. when you select a file in the `Edit' option under the File menu. The default values are the value of the VISUAL environment variable under Unix, or Wordpad under Windows. This can be changed with the Preference Editor under the Tools menu.

### 2.5.1 Compiling a program

From the `File` menu, select the `Compile ...` option. This will bring up a file selection dialogue. Select the file you wish to compile, and click on the `Open` button. This will compile the file and any others it depends on. Messages indicating which files have been compiled and describing any errors encountered will be displayed in the bottom portion of the TkECLiPSe window (`Output and Error Messages`).
If a file has been modified since it was compiled, it may be recompiled by clicking on the `make` button. This recompiles any files which have become out-of-date.

⊙
  For more information on program compilation and the compiler, please see The Compiler chapter in the user manual.

### 2.5.2 Executing a query

To execute a query, first enter it into the `Query Entry` text field. You will also need to specify which module the query should be run from, by selecting the appropriate entry from the drop-down list to the left of the `Query Entry` field. Normally, the default selection of `eclipse` will be fine; this will allow access to all ECLiPSe built-ins and all predicates that have not explicitly been compiled into a different module. Selecting another module for the query is only needed if you wish to call a predicate which is not visible from the `eclipse` module, in which case you need to select that module.

⊙
  For more information about the module system, please see the Module System chapter in the user manual.

To actually execute the query, either hit the `Enter` key while editing the query, or click on the `run` button. TkECLiPSe maintains a history of commands entered during the session, and these may be recalled either by using the drop-down list to the right of the `Query Entry` field, or by using the up and down arrow keys while editing the `Query Entry` field.
If ECLiPSe cannot find a solution to the query, it will print `No` in the `Results` section of the TkECLiPSe window. If it finds a solution and knows there are no more, it will print it in the `Results` section, and then print `Yes`. If it finds a solution and there may be more, it will print the solution found as before, print `More`, and enable the `more` button. Clicking on the `more` button tells ECLiPSe to try to find another solution. In all cases it also prints the total time taken to execute the query.
From `Query` menu, you can run the query with various analysis tools (see chapter 6): `Time Profile` option will run the query with the profiler tool; `Port Profile` option will run the query with the port profiler tool.
Note that a query can be interrupted during execution by clicking on the `interrupt` button.

### 2.5.3 Editing a file

If you wish to edit a file (e.g. a program source file), then you may do so by selecting the `Edit ...` option from the `File` menu (or use the `Edit new ...` option if the file does not yet exist). This will bring up a file selection dialogue. Select the file you wish to edit, and click on the `Open` button.
When you have finished editing the file, save it. After you've saved it, if you wish to update the version compiled into ECLiPSe (assuming it had been compiled previously), simply click on the `make` button.
You can change which program is used to edit your file by using the TkECLiPSe Preference Editor, available from the `Tools` menu. Alternatively you can use your editor separately from ECLiPSe.

### 2.5.4 Debugging a program

To help diagnose problems in ECLiPSe programs, TkECLiPSe provides the tracer. It is activated by selecting the `Tracer` option from the `Tools` menu. The next time a goal is executed, the tracer window will become active, allowing you to step through the program's execution and examine the program's state as it executes. A full example is given in chapter 5.

### 2.5.5 File menu

The `File` menu of TkECLiPSe provides various options to manipulate files:

#### Compile

Allows the user to select a file to compile into ECLiPSe.

#### Use module

Allows the user to select and load an ECLiPSe module file into ECLiPSe.

#### Edit

Allows the user to select a file to edit using the default text editor

⊙
  See section 2.5.3 for more information on editors.

.

#### Edit new

Allows the user to specify a new file that will be opened with the default text editor.

#### Cross referencer

Allows the user to select an ECLiPSe source file and produce a cross reference over it, and display the resulting graph in a new window.

#### Change directory

Allows the user to change the current working directory.

#### Change to example directory

Change the current working directory to the example directory in the ECLiPSe distribution.

#### New module

Allows the user to specify a new module that will be created. The new module becomes the current toplevel module.

#### Clear toplevel module

Allows the user to clear the current toplevel module, i.e. to erase it and start with a fresh, empty module.

#### Exit

Leave ECLiPSe

### 2.5.6 Getting help

More detailed help than is provided here can be obtained online for all the features of TkECLiPSe. Simply select the entry from the `Help` menu on TkECLiPSe's top-level window which corresponds to the topic or tool you are interested in.
Detailed documentation about all the predicates in the ECLiPSe libraries can be obtained through the `Library Browser and Help` tool. This tool allows you to browse the online help for the ECLiPSe libraries. On the left is a tree display of the libraries available and the predicates they provide.

- Double clicking on a node in this tree either expands it or collapses it again.
- Clicking on an entry displays help for that entry to the right.
- Double clicking on a word in the right-hand pane searches for help entries containing that string.

You can also enter a search string or a predicate specification manually in the text entry box at the top right. If there is only one match, detailed help for that predicate is displayed. If there are multiple matches, only very brief help is displayed for each; to get detailed help, try specifying the module and/or the arity of the predicate in the text field.
Alternatively, you can call the help/1 predicate in the query window (which contains the same information as the HTML Reference Manual). 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).

or

>     ?- help(ic:alldifferent/1).

### 2.5.7 Other tools

TkECLiPSe comes with a number of useful tools. Some have been mentioned above, but here is a more complete list. Note that we only provide brief descriptions here; for more details, please see the online help for the tool in question.

#### Compile scratch-pad

This tool allows you to enter small amounts of program code and have it compiled. This is useful for quick experimentation, but not for larger examples or programs you wish to keep, since the source code is lost when the session is exited.

#### Source File Manager

This tool allows you to keep track of and manage which source files have been compiled in the current ECLiPSe session. You can select files to edit them, or compile them individually, as well as adding new files.

#### Predicate Browser

This tool allows you to browse through the modules and predicates which have been compiled in the current session. It also lets you alter some properties of compiled predicates.

#### Source Viewer

This tool attempts to display the source code for predicates selected in other tools.

#### Delayed Goals

This tool displays the current delayed goals, as well as allowing a spy point to be placed on the predicate and the source code viewed.

#### Inspector

This tool provides a graphical browser for inspecting terms. Goals and data terms are displayed as a tree structure. Sub-trees can be collapsed and expanded by double-clicking. A navigation panel can be launched which provides arrow buttons as an alternative way to navigate the tree.
Note that while the inspector window is open, interaction with other TkECLiPSe windows is disallowed. This prevents the term from changing while being inspected. To continue TkECLiPSe, the inspector window must be closed.

#### Visualisation Client

This starts a new Java visualisation client that allows ECLiPSe programs to be visualised with the visualisation tools. See the Visualisation manual for details on the visualisation tools.

#### Global Settings

This tool allows the setting of some global flags governing the way ECLiPSe behaves. See also the documentation for the set_flag/2 and get_flag/2 predicates.

#### Statistics

This tool displays some statistics about memory and CPU usage of the ECLiPSe system, updated at regular intervals. See also the documentation for the statistics/0 and statistics/2 predicates.

#### Preference Editor

This tool allows you to edit and set various user preferences. This include parameters for how TkECLiPSe will start up, e.g. the amount of memory it will be able to use, and a initial query to execute; and parameters which affects the appearance of TkECLiPSe, such as the fonts TkECLiPSe uses and which editor it launches.