Go to the first, previous, next, last section, table of contents.


Using Ciao inside GNU emacs

Author(s): Manuel Hermenegildo and the CLIP Group.

The Ciao/Prolog emacs interface (or mode in emacs terms) provides a rich, integrated user interface to the Ciao program development environment components, including the ciaosh interactive top level and the ciaopp preprocessor. While most features of the Ciao development environment are available from the command line of the preprocessor and the top-level shell, using Ciao inside emacs is highly recommended. The facilities that this mode provides include:

This chapter explains how to use the Ciao/Prolog emacs interface and how to set up your emacs environment for correct operation. The Ciao emacs interface can also be used to work with other Prolog or CLP systems.

Installation of the Ciao/Prolog emacs interface

It may be possible that a complete pre-installation of the Ciao/Prolog emacs interface was already completed during Ciao installation. To check this, open a file with a .pl ending. You should see that emacs enters Ciao/Prolog mode: the mode is identified in the status bar below the buffer and, if the emacs menu bar is enabled, you should see the Ciao/Prolog menu. You should be able from the menu-bar, for example, to go to the Ciao manuals in the info or load the .pl file that you just opened into a ciao top level.

If opening a file ending with .pl puts emacs in another mode (such as perl mode, which is the --arguably incorrect-- default setting in some emacs distributions), then you can set things so that the Ciao/Prolog mode is loaded by default in your system. This can be done by including in your .emacs file a line such as:

(load <CIAOLIBDIR>/DOTemacs)

This loads the above mentioned file from the Ciao library, which contains the following lines (except that the paths are changed during installation to appropriate values for your system):

;; Ciao / &-Prolog / Prolog mode
;; (can be used for SICStus, and coexist with SICStus Prolog prolog.el)
;; 
(setq load-path (cons "<CIAOLIBDIR>" load-path))
(autoload 'run-ciao-toplevel "ciao"
          "Start a Ciao / &-Prolog / Prolog top-level sub-process." t)
(autoload 'run-ciao-preprocessor "ciao"
          "Start a Ciao / &-Prolog / Prolog preprocessor sub-process." t)
(autoload 'ciao-mode "ciao"
          "Major mode for edit/run Ciao, Prolog, &-Prolog" t)
(autoload 'ciao-inferior-mode "ciao"
          "Major mode for running Ciao, Prolog, lpdoc, etc." t)
(setq auto-mode-alist (cons '("\\.pl$" . ciao-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.pls$" . ciao-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.lpdoc$" . ciao-mode) auto-mode-alist))
(setq completion-ignored-extensions
      (append '(".dep" ".itf" ".po" ".asr" ".cpx")
              completion-ignored-extensions))
;; ------------------------------------------------------------------------
;; In Un*x, the following (or similar) lines should be included in your
;; .cshrc or .profile to find the manuals (the Ciao installation leaves
;; in the Ciao library directory 'DOTcshrc' and 'DOTprofile' files with
;; the right paths which can be included directly in your startup scripts):
;; 
;; setenv INFOPATH /usr/local/info:/usr/info:<LPDOCDIR>
;; ------------------------------------------------------------------------

If you would like to configure things in a different way, you can also copy the contents of this file to your .emacs file and make the appropriate changes. For example, if you do not want .pl files to be put automatically in Ciao/Prolog mode, then comment out (or remove) the line:

(setq auto-mode-alist ... )

You will then need to switch manually to Ciao/Prolog mode by typing M-x ciao-mode after opening a Prolog file.

If you are able to open the Ciao/Prolog menu but the Ciao manuals are not found or the ciao command (the top-level) is not found when loading .pl files, the probable cause is that you do not have the Ciao paths in the INFOPATH and MANPATH environment variables (whether these variables are set automatically or not for users depends on how the Ciao system was installed). You can add these paths easily by including the line:

source <CIAOLIBDIR>/DOTcshrc

in your .login or .cshrc files if you are using csh (or tcsh, etc.), or, alternatively, the line:

. <CIAOLIBDIR>/DOTprofile

in your .login or .profile files if you are using sh (or bash, etc.). See the Ciao installation instructions (section Installing Ciao) for details.

Functionality and associated key sequences (bindings)

The following is a summary of the capabilities of the Ciao/Prolog emacs interface and the (default) key sequences used to access those capabilities. Most of these functions are accessible also from the menu bar.

Getting on-line help

The following commands are useful for getting on-line help. This is done by accessing the info version of the Ciao manuals or the emacs built-in help strings. Note also that the info standard search command (generally bound to s) can be used inside info buffers to search for a given string.

^C TAB
Find help for the symbol (e.g., predicate, directive, declaration, type, etc.) that is currently under the cursor. Opens a (hopefully) relevant part of the Ciao manuals in info mode. Requires that the Ciao manuals in info format be installed and that they accessible to emacs (i.e., they should appear somewhere in the info directory when typing M-x info). It also requires word-help.el, which is provided with Ciao.
^C /
Find a completion for the symbol (e.g., predicate, directive, declaration, type, etc.) that is currently under the cursor. Uses for completion the contents of the indices of the Ciao manuals. Same requirements as for finding help for the symbol.
^C ^M
Go to the part of the info directory containing the Ciao manuals.
^H m
Show a short description of the Ciao/Prolog emacs mode, including all key bindings.

Loading debugging and compiling programs

These commands allow loading programs, marking modules for debugging, creating executables, etc. by issuing the appropriate commands to a Ciao/Prolog top level shell, running in its own buffer as a subprocess. See section The interactive top-level shell for details. The following commands implement the communication with the Ciao/Prolog top level:

^C l
Load the current buffer (and any auxiliary files it may use) into the top level. The type of compilation performed ( compiling or consulting) is selected automatically depending on whether the buffer has been marked for debugging or not -- see below.
^C m
Mark the current buffer for debugging. Note that if the buffer has already been loaded while it was unmarked for debugging (and has therefore been loaded in "compile" mode) it has to be loaded again.
^C u
Unmarks the current buffer for debugging. Note that if the buffer has already been loaded while it was marked for debugging (and has therefore been loaded in "consult" mode) it has to be loaded again.
^C r
Load the current region (between the cursor and a previous mark) into the top level for debugging. Since loading a region of a file is typically done for debugging and/or testing purposes, this command always loads the region in debugging mode (consult).
^C p
Load the predicate around the cursor into the top level. Since loading a single predicate is typically done for debugging and/or testing purposes, this command always loads the predicate in debugging mode (consult).
^C x
Make an executable from the code in the current buffer. The buffer must contain a main/0 or main/1 predicate. Note that compiler options can be set to determine whether the libraries and auxiliary files used by the executable will be statically linked, dynamically linked, auto-loaded, etc.
^C o
Make a Prolog object (.po) file from the code in the current buffer. This is very useful during debugging or program development, when only one or a few files of a large application are modified. If the application executable is dynamically linked, i.e., the component .po files are loaded dynamically during startup of the application, then this command can be used to recompile only the file or files which have changed, and the correct version will be loaded dynamically the next time the application is started. However, note that this only works if the inter-module interfaces have not changed. A safer, but possibly slower way is to generate the executable again, letting the Ciao compiler, which is inherently incremental, determine what needs to be recompiled.
^C a
Make an active module executable from the code in the current buffer. An active module is a remote procedure call server (see the activemod library documentation for details).
^C t
Ensure that an inferior Ciao/Prolog top-level process is running. Normally, it is not necessary to use this function since execution of any of the other functions related to the top level ensures that a top level is started (starting one if required). This function is useful when one would like to start a top level in order to type a command directly by hand into it.

Locating errors and checking the syntax of assertions

These commands allow several syntactic checks of assertions, and locating quickly the point in the source code corresponding to errors flagged by the compiler or preprocessor:

^C `
Go to location in source file containing next error reported by the last Ciao/Prolog subprocess (preprocessor or toplevel) which was run.
^C E
Check the syntax of the code and assertions in the current buffer, as well as imports and exports. Note that full (semantic) assertion checking must be done with the preprocessor.

Commands which help in typing in programs

The following commands are intended to help in the process of writing programs:

^C I S
Insert a (Unix) header at the top of the current buffer so that the ciao script interpreter will be called on this file if run from the command line. It also makes the file 'executable' (e.g., 'chmod +x <file>' in Unix). See section The script interpreter for details.

Preprocessing programs

These commands allow preprocessing programs with ciaopp, the Ciao preprocessor.

ciaopp is the precompiler of the CIAO Prolog development environment. ciaopp can perform a number of program debugging, analysis and source-to-source transformation tasks on (CIAO) Prolog programs. These tasks include:

The information generated by analysis, the assertions in the system libraries, and the assertions optionally included in user programs as specifications are all written in the same assertion language, which is in turn also used by the CIAO system documentation generator, lpdoc.

ciaopp is distributed under the GNU general public license.

See the preprocessor manual for details. The following commands implement the communication with the Ciao preprocessor:

^C M
Preprocess the buffer, selecting options. Instructs the preprocessor to load the current buffer and start an interactive dialog in which the different options available in the preprocessor can be set.
^C P
Preprocess the buffer, using the previously selected options. If no options were set previously, then the preprocessor defaults are used.
^C ^V
Show last output file produced by Ciao preprocessor. The preprocessor works by producing a file which is a transformed and/or adorned (with assertions) version of the input file. This is often used after running the preprocessor in order to see such results.
^C V
Preprocess the buffer, selecting options. Instructs the preprocessor to load the current buffer and start an interactive dialog in which the different options available in the preprocessor can be set.
^C ^R
Ensure that an inferior Ciao preprocessor process is running

Version control

The following commands can be used to carry out a simple form of version control by keeping a log of changes on a file or a group of related files. This log is kept in a format that is understood by lpdoc, the Ciao documenter [Her99a]. As a result, if these version comments are present, then lpdoc will be able to automatically assign up to date version numbers to the manuals that it generates. This way it is always possible to identify to which version of the software a manual corresponds. Also, lpdoc can create automatically sections describing the changes made since previous versions, which are extracted from the comments in the changelog entries.

The main effect of these commands is automatically associate the following information to a set of changes performed in the file and/or in a set of related files:

The version numbering used can be local to a single file or common to a number of related files. A simple version numbering policy is implemented: when a relevant change is made, the user typically inserts a changelog entry for it, using the appropriate command (or selecting the corresponding option when prompted while saving a file). This will cause the patch number for the file (or for the whole system that the file is part of) to be incremented automatically and the corresponding machine-readable comment to be inserted in the file. Major and minor version numbers can also be changed, but this is always invoked by hand (see below).

The changelog entry is written in the form of a comment/2 declaration. As mentioned before, the advantage of using this kind of changelog entries is that these declarations can be processed by the lpdoc automatic documenter (see the lpdoc reference manual [Her99a] or the assertions library documentation for more details on these declarations).

Whether the user is asked or not to introduce such changelog entries, and how the patch and version numbers should be increased is controlled by the presence in the file of a comment/2 declaration of the type:

:- comment(version_maintenance,<type>).

(note that this requires including the assertions library in the source file). These declarations themselves are also typically introduced automatically when using this mode (see below).

The version maintenance mode can also be set alternatively by inserting a comment such as:

%% Local Variables: 
%% mode: Ciao/Prolog
%% update-version-comments: ""off""
%% End:

The lines above instruct emacs to put the buffer visiting the file in emacs Ciao/Prolog mode and to turn version maintenance off. Setting the version maintenance mode in this way has the disadvantage that lpdoc, the auto-documenter, and other related tools will not be aware of the type of version maintenance being performed (the lines above are comments for Prolog). However, this can be useful in fact for setting the version maintenance mode for packages and other files meant for inclusion in other files, since that way the settings will not affect the file in which the package is included.

The following commands implement the version control support:

^X ^S
This is the standard emacs command that saves a buffer by writing the contents into the associated .pl file. However, in Ciao/Prolog mode this command can be set to ask the user before saving whether to introduce a change log entry documenting the changes performed. If the buffer does not already contain a comment specifying the type of version control to be performed, and before saving the buffer, the Ciao/Prolog mode prompts the user to choose among the following options:
q
Turn off prompting for the introduction of change log entries for now. emacs will not ask again while the buffer is loaded, but it will ask again next time you load the buffer.
n
Turn off version control for this file. A version control comment such as: :- comment(version_maintenance,off). is added to the buffer and the file is saved. emacs will not perform any version control on this file until the line above is removed or modified (i.e., from now on C-x C-s simply saves the buffer).
y
Turn version control on for this file.
If y is selected, then the system prompts again regarding how and where the version and patch number information is to be maintained. The following options are available:
on
All version control information will be contained within this file. When saving a buffer (C-x C-s) emacs will ask if a change log entry should be added to the file before saving. If a comment is entered by the user, a new patch number is assigned to it and the comment is added to the file. This patch number will be the one that follows the most recent change log entry already in the file. This is obviously useful when maintaining version numbers individually for each file.
<directory_name>
Global version control will be performed coherently on several files. When saving a buffer (C-x C-s) emacs will ask if a change log entry should be added to the file before saving. If a comment is given, the global patch number (which will be kept in the file: <directory_name>/GlobalPatch) is atomically incremented and the change log entry is added to the current file, associated to that patch number. Also, a small entry is added to a file <directory_name>/GlobalChangeLog which points to the current file. This allows inspecting all changes sequentially by visiting all the files where the changes were made (see C-c `). This is obviously useful when maintaining a single thread of version and patch numbers for a set of files.
off
Turns off version control: C-x C-s then simply saves the file as usual.
Some useful tips:
^C ^S
Same as C-x C-s except that it forces prompting for inclusion of a changelog entry even if the buffer is unmodified.
^C n
Force a move to a new major/minor version number (the user will be prompted for the new numbers). Only applicable if using directory-based version maintenance. Note that otherwise it suffices with introducing a change log entry in the file and changing its version number by hand.
^C ^N
When a unique version numbering is being maintained across several files, this command allows inspecting all changes sequentially by visiting all the files in which the changes were made:

Setting the top-level and preprocessor executables

These commands allow changing the executables used when starting a Prolog top-level or the preprocessor, changing the arguments that these executables take, and changing the path where the Prolog libraries reside. This should be done only by users which understand the implications, but is very useful if several versions of Ciao/Prolog are available in the system:

^C S C
Change the Ciao/Prolog executable used to run the Prolog-like top level. It is set by default to ciao or, to the environment variable CIAO if it is defined.
^C S ^C
Change the arguments passed to the Ciao/Prolog executable. They are set by default to none or, to the environment variable CIAOARGS if it is defined.
^C S P
Change the executable used to run the Ciao Preprocessor toplevel. It is set by default to ciaopp or, to the environment variable CIAOPP if it is defined.
^C S ^P
Change the arguments parssed to the Ciao preprocessor executable. They are set by default to none or, to the environment variable CIAOPPARGS if it is defined.
^C S L
Change the location of the Ciao/Prolog library paths (changes the environment variable CIAOLIB).

Traditional Prolog Mode Commands

These commands provide some bindings and facilities for loading programs, which are present in emacs Prolog modes of other Prolog systems (e.g., SICStus). This is useful mainly if the Ciao/Prolog emacs mode is used with such Prolog systems. Note that the behavior of these commands in Ciao is slightly different from that of SICStus.

^C K
Compile the entire buffer.
^C k
Compile a given region.
^C ^K
Compile the predicate around point.
^C C
Consult the entire buffer.
^C c
Consult a given region.
^C ^C
Consult the predicate around point.

Other commands

Some other commands which are active in the Ciao/Prolog mode:

TAB
Indent current line as Ciao/Prolog code. With argument, indent any additional lines of the same clause rigidly along with this one.
^C ^L
Recenter the most recently used Ciao/Prolog inferior process buffer (top-level or preprocessor).

Getting the Ciao/Prolog mode version

^C v
Report the version of the emacs Ciao/Prolog mode.

Commands available in toplevel and preprocessor buffers

The interactive top level and the preprocessor both are typically run in an iteractive buffer, in which it is possible to communicate with them in the same way as is they had been started from a standard shell. In addition, the commands and key bindings available in buffers containing source code are also available in these interactive buffers, when applicable.

Using Ciao/Prolog mode capabilities in standard shells

The capabilities (commands, coloring, ...) which are active in the Ciao/Prolog "inferior" mode (the mode of the buffers in which the top level and the preprocessor run) can also be made available in any standard command line shell which is being run within emacs. This can be enabled by going to the buffer in which the shell is running and typing "M-x ciao-inferior-mode". This is very useful for example when running the stand-alone compiler, the lpdoc documenter, or even certain user applications (those that use the standard error message library) in an emacs sub-shell. Turning the Ciao/Prolog inferior mode on on that sub-shell will highlight and color the error messages (type ^L), and automatically find and visit the locations in the files in which the errors are reported.

Coexistence with other Prolog interfaces

As mentioned previously, the Ciao/Prolog emacs interface can also be used to work with other Prolog or CLP systems. Also, the Ciao/Prolog emacs interface (mode) can coexist with other Prolog-related emacs interfaces (modes) (such as, e.g., the SICStus Prolog interface). Only one of the interfaces can be active at a time for a given buffer (i.e., for each given file opened inside emacs). In order the change a buffer to a given interface, move the cursor to that buffer and type M-x ...-mode (e.g., for the Ciao/Prolog mode, M-x ciao-mode).

If several Prolog-related emacs interfaces are loaded, then typically the last one to be loaded takes precedence, in the sense that this will be the interface in which emacs will be set when opening files which have a .pl ending (this depends a bit on how things are set up in your .emacs file).

Version information

This documentation corresponds to Ciao/Prolog emacs mode version 5.55. This mode is currently being developed within GNU emacs version 20.2. It should also work with all other 20.XX and later 19.XX versions.

Acknowledgments (ciao.el)

This code is derived from the 1993 version of the emacs interface for &-Prolog, itself derived from the original prolog.el by Masanobu Umeda with changes by Johan Andersson, Peter Olin, Mats Carlsson, and Johan Bevemyr of SICS, Sweden. Other changes also by Daniel Cabeza.


Go to the first, previous, next, last section, table of contents.