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

Using Ciao inside GNU emacs

Author(s): Manuel Hermenegildo, Manuel C. Rodriguez, Daniel Cabeza, , The Computational logic, Languages, , Implementation, and Parallelism (CLIP) Group, webmaster@clip.dia.fi.upm.es, http://www.cliplab.org/, School of CS, Technical University of Madrid, CS and ECE Departments, University of New Mexico.

Version: 1.10#8 (2007/1/28, 17:30:3 CEST)

Version of last change: 1.9#323 (2004/3/8, 18:37:17 CET)

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.

Conventions for writing Ciao programs under Emacs

This is particularly important for the source-level debugger and the syntax-based coloring capabilities. This is due to the fact that it would be unrealistic to write a complete Prolog parser in Emacs lisp. These conventions are the following, in order of importance:

The following suggestion is not strictly necessary but can improve operation:

Comments which start with %s are indented to the right if indentation is asked for.

For syntax-based highlighting to be performed font-lock must be available and not disabled (the Ciao mode enables it but it may be disabled elsewhere in, e.g., the .emacs file).

Checking the installation

Typically, a complete pre-installation of the Ciao/Prolog emacs interface is completed during Ciao installation. To check that installation was done and sucessful, 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 menus. 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 things don't work properly, see the section section Installation of the Ciao/Prolog emacs interface later in this chapter.

Functionality and associated key sequences (bindings)

The following sections summarize 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.

Syntax coloring and syntax-based editing

Syntax-based highlighting (coloring) of code is provided automatically when opening Ciao/Prolog files. This includes also the assertions used by the preprocessor and the documentation strings used by the Ciao auto-documenter, lpdoc. The mode should be set to Ciao/Prolog and the Ciao mode menus should appear on the menu bar. The colors and fonts used can be changed through the customize options in the help menu (see section Customization).

During editing this coloring may be refreshed by calling the appropriate function (see below).

Limited syntax-based auto-indentation and auto-fill of code and comments is also provided. Syntax highlighting and coloring is also available for the error and warning messages produced by the top level, preprocessor, and auto-documenter, and, in general, for the output produced by these tools.

Commands:

^C h
Undate (recompute) syntax-based highlighting (coloring).
TAB
Indent current line as Ciao/Prolog code. With argument, indent any additional lines of the same clause rigidly along with this one.

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 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. Refer to the installation instructions if this is not the case.
^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 and compiling programs

These commands allow loading programs, 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 t
Ensure that an inferior Ciao/Prolog top-level process is running. This opens a top-level window (if one did not exist already) where queries can be input directly as in any normal Prolog top level. Programs can be loaded into this top level by typing the corresponding commands in this window (such as use_module, etc.), or, more typically, by opening the file to be loaded in an emacs window (where it can be edited) and issuing a load command (such as C-c l or C-c L) directly from there (see the loading commands of this mode and their bindings). Note that many useful commands (e.g., to repeat and edit previous commands, interrupt jobs, locate errors, automatic completions, etc.) are available in this top-level window (see section Commands available in toplevel and preprocessor buffers). Often, it is not necessary to use this function since execution of any of the other functions related to the top level (e.g., loading buffers into the top level) ensures that a top level is started (starting one if required).
^C l
Load the current buffer (and any auxiliary files it may use) into the top level. The type of compilation performed ( compiling or interpreting) is selected automatically depending on whether the buffer has been marked for debugging or not -- see below. In case you try to load a file while in the middle of the debugging process the debugger is first aborted and then the buffer is loaded. Also, if there is a defined query, the user is asked whether it should be called.
^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 useful for example while debugging during development of a very large application which is compiled into an excutable, and only one or a few files 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 must be done with care since it only works if the inter-module interfaces have not changed. The recommended, much safer 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 s
Set the current buffer as the principal file in a multiple module programming environment.
^C L
Load the module designated as main module (and all related files that it uses) into the top level. If no main module is defined it will load the current buffer. The type of compilation performed ( compiling or interpreting) is selected automatically depending on whether the buffer has been marked for debugging or not -- see below. In case you try to load a file while in the middle of the debugging process the debugger is first aborted and then the buffer is loaded. Also, if there is a defined query, the user is asked whether is should be called.
^C q
Set a default query. This may be useful specially during debugging sessions. However, as mentioned elsewhere, note that commands that repeat previous queries are also available. This query can be recalled at any time using C-c Q. It is also possible to set things up so that this query will be issued automatically any time a program is (re)loaded. The functionality is available in the major mode (i.e., from a buffer containing a source file) and in the inferior mode (i.e., from the buffer running the top-level shell). When called from the major mode (i.e., from window containing a source file) then the user is prompted in the minibuffer for the query. When called from the inferior mode (i.e., from a top-level window) then the query on the current line, following the Ciao prompt, is taken as the default query. To clear the default query use M-x ciao-clear-query or simply set it to an empty query: i.e., in a source buffer select C-c q and enter an empty query. In an inferior mode simply select C-c q on a line that contains only the system prompt.
^C Q
Issue predefined query.

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 if they had been started from a standard shell. These interactive buffers run in the so-called Ciao/Prolog inferior mode. This is a particular version of the standard emacs shell package (comint) and thus all the commands typically available when running shells inside emacs also work in these buffers. In addition, many of the commands and key bindings available in buffers containing Ciao source code are also available in these interactive buffers, when applicable. The Ciao/Prolog-specific commands available include:

^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 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. Refer to the installation instructions if this is not the case.
^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 `
Go to the location in the source file containing the next error reported by the last Ciao/Prolog subprocess (preprocessor or toplevel) which was run.
^C e
Remove error marks from last run (and also debugging marks if present).
^C q
Set a default query. This may be useful specially during debugging sessions. However, as mentioned elsewhere, note that commands that repeat previous queries are also available. This query can be recalled at any time using C-c Q. It is also possible to set things up so that this query will be issued automatically any time a program is (re)loaded. The functionality is available in the major mode (i.e., from a buffer containing a source file) and in the inferior mode (i.e., from the buffer running the top-level shell). When called from the major mode (i.e., from window containing a source file) then the user is prompted in the minibuffer for the query. When called from the inferior mode (i.e., from a top-level window) then the query on the current line, following the Ciao prompt, is taken as the default query. To clear the default query use M-x ciao-clear-query or simply set it to an empty query: i.e., in a source buffer select C-c q and enter an empty query. In an inferior mode simply select C-c q on a line that contains only the system prompt.
^C Q
Issue predefined query.
^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 command is often used after running the preprocessor in order to visit the output file and see the results from running the preprocessor.
^C v
Report the version of the emacs Ciao/Prolog mode.

The following are some of the commands from the comint shell package which may be specially useful (type <f1> m while in a Ciao interactive buffer for a complete list of commands):

M-p
Cycle backwards through input history, saving input.
M-n
Cycle forwards through input history.
M-r
Search backwards through input history for match for REGEXP. (Previous history elements are earlier commands.) With prefix argument N, search for Nth previous match. If N is negative, find the next or Nth next match.
TAB
Dynamically find completion of the item at point. Note that this completion command refers generally to filenames (rather than, e.g., predicate names, as in the previous functions).
M-?
List all (filename) completions of the item at point.
RET
Return at any point of the a line at the end of a buffer sends that line as input. Return not at end copies the rest of the current line to the end of the buffer and sends it as input.
^D
Delete ARG characters forward or send an EOF to subprocess. Sends an EOF only if point is at the end of the buffer and there is no input.
^C ^U
Kill all text from last stuff output by interpreter to point.
^C ^W
Kill characters backward until encountering the end of a word. With argument, do this that many times.
^C ^C
Interrupt the current subjob. This command also kills the pending input between the process mark and point.
^C ^Z
Stop the current subjob. This command also kills the pending input between the process mark and point. WARNING: if there is no current subjob, you can end up suspending the top-level process running in the buffer. If you accidentally do this, use M-x comint-continue-subjob to resume the process. (This is not a problem with most shells, since they ignore this signal.)
^C ^\
Send quit signal to the current subjob. This command also kills the pending input between the process mark and point.

Locating errors and checking the syntax of assertions

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

^C `
Go to the location in the source file containing the next error reported by the last Ciao/Prolog subprocess (preprocessor or toplevel) which was run.
^C e
Remove error marks from last run (and also debugging marks if present).
^C E
Check the syntax of the code and assertions in the current buffer, as well as imports and exports. This uses the standard top level (i.e., does not call the preprocessor and thus does not require the preprocessor to be installed). Note that full (semantic) assertion checking must be done with the preprocessor.

Commands which help 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.

Debugging programs

These commands allow marking modules for debugging by issuing the appropiate commands to a Ciao/Prolog top level shell, running in its own buffer as a subprocess. There are two differents types of debugging: traditional Prolog debugging (using the byrd-box model and spy-points) and source-level debugging (same as traditional debugging plus source tracing and breakpoints). In order to use breakpoints, source debugging must be on. The following commands implement comunication with the Ciao/Prolog top level:

^C d
Debug (or stop debugging) buffer source. This is a shortcut which is particularly useful when using the source debugger on a single module. It corresponds to several lower-level actions. Those lower-level actions depend on how the module was selected for debugging. In case the module was not marked for source-level debugging, it marks the module corresponding to the current buffer for source-level debugging, reloads it to make sure that it is loaded in the correct way for debugging (same as C-c l), and sets the debugger in trace mode (i.e., issues the trace. command to the top-level shell). Conversely, if the module was already marked for source-level debugging then it will take the opposite actions, i.e., it unmarks the module for source-level debugging, reloads it, and sets the debugger to non-debug mode.
^C m
Mark, or unmkark, the current buffer for debugging (traditional debugging or source 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. The minibuffer shows how the module is loaded now and allows selecting another mode for it. There are three posibilities: N for no debug, S for source debug and D for traditional debug.
^C M-m
Visits all Ciao/Prolog files which are currently open in a buffer allowing selecting for each of them whether to debug them or not and the type of debugging performed. When working on a multiple module program, it is possible to have many modules open at a time. In this case, you will navigate through all open Ciao/Prolog files and select the debug mode for each of them (same as doing C-c m for each).
^C S b
Set a breakpoint on the current literal (goal). This can be done at any time (while debugging or not). The cursor must be on the predicate symbol of the literal. Breakpoints are only useful when using source-level debugging.
^C S v
Remove a breakpoint from the current literal (goal). This can be done at any time (while debugging or not). The cursor must be on the predicate symbol of the literal.
^C S n
Remove all breakpoints. This can be done at any time (while debugging or not).
^C S l
Redisplay breakpoints in all Ciao buffers. This ensures that the marks in the source files and the Ciao/Prolog toplevel are synchronized.
^C S r
Remove breakpoints color in all Ciao/Prolog files.
^C S t
Set the debugger to the trace state. In this state, the program is executed step by step.
^C S d
Set the debugger to the debug state. In this state, the program will only stop in breakpoints and spypoints. Breakpoints are specially supported in emacs and using source debug.
^C r
Load the current region (between the cursor and a previous mark) into the top level. 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 (interpreted).
^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 (interpreted).

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 T
Uses the preprocessor to perform compile-time checking of types and modes (pptypesfd and shfr analyses).
^C ^P
Make ciaopp output only predicate-level analysis information.
^C ^F
Make ciaopp output both literal- and predicate-level analysis information.
^C ^X
Make ciaopp output no analysis information.
^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 command is often used after running the preprocessor in order to visit the output file and see the results from running the preprocessor.
^C V
Preprocess the buffer, using the previously selected (or default) options, waits for preprocessing to finish and displays the preprocessor output (leaving the cursor at the same point if already on a preprocessor output file). This allows running the preprocessor over and over and watching the output while modifying the source code.
^C ^R
Ensure that an inferior Ciao preprocessor process is running. This opens a preprocessor top-level window (if one did not exist already) where preprocessing commands and preprocessing menu options can be input directly. Programs can be preprocessed by typing commands in this window, or, more typically, by opening the file to be preprocessed in an emacs window (where it can be edited) and issuing a command (such as C-c M or C-c P) directly from there (see the preprocessing commands of this mode and their bindings). Note that many useful commands (e.g., to repeat and edit previous commands, interrupt jobs, locate errors, automatic completions, etc.) are available in this top-level window (see section Commands available in toplevel and preprocessor buffers). Often, it is not necessary to use this function since execution of any of the other functions related to the top level (e.g., loading buffers into the top level) ensures that a top level is started (starting one if required).

Version control

The following commands can be used to carry out a simple but effective form of version control by keeping a log of changes on a file or a group of related files. Interestingly, this log is kept in a format that is understood by lpdoc, the Ciao documenter [Her99]. 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 to 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 [Her99] 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
%% 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 changelog 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 changelog 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 changelog 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 changelog 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 changelog 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 changelog 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 C-n). 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 changelog 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:

Generating program documentation

These commands provide some bindings and facilities for generating and viewing the documentation corresponding to the current buffer. The documentation is generated in a temporary directory, which is created automatically. This is quite useful while modifying the documentation for a file, in order to check the output that will be produced, whithout having to set up a documentation directory by hand or to regenerate a large manual of which the file may be a part.

^C D B
Generate the documentation for the current buffer in the default format. This allows generating a simple document for the current buffer. Basically, it creates a SETTINGS file, sets MAIN in SETTINGS to the current buffer and then generates the documentation in a temporary directory. Note that for generating complex manuals the best approach is to set up a permanent documentation directory with the appropriate SETTINGS and Makefile files (see the LPdoc manual).
^C D F
Change the default output format used by the LPdoc auto-documenter. It is set by default to dvi or to the environment variable LPDOCFORMAT if it is defined.
^C D S
Visit, or create, the SETTINGS file (which controls all auto-documenter options).
^C D G
Generate the documentation according to SETTINGS in the default format. This allows generating complex documents but it assumes that SETTINGS exists and that the options that it contains (main file, component files, paths, etc.) have been set properly. Documentation is generated in a temporary directory. Note however that for generating complex manuals the best approach is to set up a permanent documentation directory with the appropriate SETTINGS and Makefile files (see the LPdoc manual).
^C D V
Start a viewer on the documentation for the current buffer in the default format.
^C D W
Change the root working dir used by the LPdoc auto-documenter. It is set by default to a new dir under /tmp or to the environment variable LPDOCWDIR if it is defined.

Setting top level preprocessor and documenter executables

These commands allow changing the executables used when starting a Prolog top-level, the preprocessor, or the auto-documenter. They also allow changing the arguments that these executables take, and changing the path where the libraries reside. In the case of the top-level and preprocessor, this should be done only by users which understand the implications, but it is very useful if several versions of Ciao/Prolog or the preprocessor are available in the system. All these settings can be changed through the customize options in the help menu (see section Customization).

^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 passed 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).
^C S D
Change the executable used to run the LPdoc auto-documenter. It is set by default to lpdoc or to the environment variable LPDOC if it is defined.
^C S ^D
Change the arguments passed to the LPdoc auto-documenter. They are set by default to none or to the environment variable LPDOCARGS if it is defined.
^C S ^L
Change the path in which the LPdoc library is installed. It is set by default to /home/clip/lib or to the environment variable LPDOCLIB if it is defined.

Other commands

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

^C ^L
Recenter the most recently used Ciao/Prolog inferior process buffer (top level or preprocessor).

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 these commands ( compile/1 and consult/1) are deprecated in Ciao (due to the more advanced, separate compilation model in Ciao) and their use in the Ciao top-level is not recommended.

^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.

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).

Getting the Ciao/Prolog mode version

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

Using Ciao/Prolog mode capabilities in standard shells

The capabilities (commands, coloring, error location, ...) which are active in the Ciao/Prolog inferior mode 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 auto-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, and automatically find and visit the locations in the files in which the errors are reported.

Finally, one the most useful applications of this is when using the embedded debugger (a version of the debugger which can be embedded into executables so that an interactive debugging session can be triggered at any time while running that executable without needing the top-level shell). If an application is run in a shell buffer which has been set with Ciao inferior mode (M-x ciao-inferior-mode) and this application starts emitting output from the embedded debugger (i.e., which contains the embedded debugger and is debugging its code) then the Ciao emacs mode will be able to follow these messages, for example tracking execution in the source level code. This also works if the application is written in a combination of languages, provided the parts written in Ciao are compiled with the embedded debugger package and is thus a covenient way of debugging multi-language applications. The only thing needed is to make sure that the output messages appear in a shell buffer that is in Ciao inferior mode.

Customization

This section explains all variables used in the Ciao/Prolog emacs mode which can be customized by users. Such customization can be performed (in later versions of emacs) from the emacs menus (Help -> Customize -> Top-level Customization Group), or also by adding a setq expression in the .emacs file. Such setq expression should be similar to:

(setq <variable> <new_value>)

The following sections list the different variables which can be customized for ciao, ciaopp and lpdoc.

Ciao general variables

ciao-clip-logo (file)
CLIP logo image.
ciao-create-sample-file-on-startup (boolean)
When starting the ciao environment using ciao-startup two buffers are opened: one with a Prolog toplevel and another with a sample file. This toggle controls whether the sample file, meant for novice users, is created or not. Set by default, non-novice users will probably want to turn it off.
ciao-indent-width (integer)
Indentation for a new goal.
ciao-library-path (string)
Path to the Ciao/Prolog System libraries (reads/sets the CIAOLIB environment variable ). Typically left empty, since ciao executables know which library to use.
ciao-locate-also-note-messages (boolean)
If set, also when errors of type NOTE are detected the corresponding file is visited and the location marked. It is set to nil by default because sometimes the user prefers not to take any action with respect to these messages (for example, many come from the documenter, indicating that adding certain declarations the documentation would be improved).
ciao-locate-errors-after-run (boolean)
If set, location of any errors produced when running Ciao tools (loading or preprocessing code, running the documenter, etc.) will be initiated automatically. I.e., after running a command, the system will automatically highlight any error messages and the corresponding areas in source files if possible. If set to nil this location will only happen after typing C-c ` or accessing the corresponding menu or tool bar button.
ciao-logo (file)
Ciao logo image.
ciao-main-filename (string)
Name of main file in a multiple module program. Setting thsi is very useful when working on a multi-module program because it allows issuing a load command after working on an inferior module which will reload from the main module, thus also reloading automatically all dependent modules.
ciao-os-shell-prompt-pattern (string)
Regular expression used to describe the shell prompt pattern, so that error location works in inferior shells. This is useful for example so that errors are located when generating documentation (for lpdoc versions up to 1.9), and also when using the embedded debugger or any other application in a shell. It is best to be as precise as possible when defining this so that the standard ciao error location does not get confused.
ciao-query (string)
Query to use in Ciao. Setting this is useful when using a long or complicated query because it saves from having to type it over and over again. It is possible to set that this query will be issued any time a program is (re)loaded.
ciao-system (string)
Name of Ciao or Prolog executable which runs the classical Prolog-like top level.
ciao-system-args (string)
Arguments passed to Ciao/Prolog toplevel executable.
ciao-toplevel-buffer-name (string)
Basic name of the buffer running the Ciao/Prolog toplevel inferior process.
ciao-user-directives (list)
List of identifiers of any directives defined by users which you would like highlighted (colored). Be careful, since wrong entries may affect other syntax highlighting.

CiaoPP variables

ciao-ciaopp-buffer-name (string)
Basic name of the buffer running the Ciao preprocessor inferior process.
ciao-ciaopp-system (string)
Name of Ciao preprocessor executable.
ciao-ciaopp-system-args (string)
Arguments passed to Ciao preprocessor executable.

LPdoc variables

ciao-lpdoc-buffer-name (string)
Basic name of the buffer running the auto-documenter inferior process.
ciao-lpdoc-docformat (symbol)
Name of default output format used by LPdoc.
ciao-lpdoc-libpath (directory)
Path in which the LPdoc library is installed.
ciao-lpdoc-system (string)
Name of LPdoc auto-documenter executable.
ciao-lpdoc-system-args (string)
Arguments passed to LPdoc executable.
ciao-lpdoc-wdir-root (directory)
Name of root working dir used by LPdoc.

Faces used in syntax-based highlighting (coloring)

ciao-face-answer-val (face)
Face to use for answer values in top level.
ciao-face-answer-var (face)
Face to use for answer variables in top level.
ciao-face-builtin-directive (face)
Face to use for the standard directives.
ciao-face-check-assrt (face)
Face to use for check assertions.
ciao-face-checked-assrt (face)
Face to use for checked assertions.
ciao-face-ciaopp-option (face)
Face to use for CiaoPP option menus.
ciao-face-clauseheadname (face)
Face to use for clause head functors.
ciao-face-comment (face)
Face to use for code comments using fixed pitch (double %).
ciao-face-comment-variable-pitch (face)
Face to use for code comments using variable pitch (single %).
ciao-face-concurrency-op (face)
Face to use for concurrency operators.
ciao-face-cut (face)
Face to use for cuts.
ciao-face-debug-breakpoint (face)
Face to use with breakpoints in source debugger.
ciao-face-debug-call (face)
Face to use when at call port in source debugger.
ciao-face-debug-exit (face)
Face to use when at exit port in source debugger.
ciao-face-debug-expansion (face)
Face to use in source debugger when source literal not located.
ciao-face-debug-fail (face)
Face to use when at fail port in source debugger.
ciao-face-debug-mess (face)
Face to use for debug messages.
ciao-face-debug-redo (face)
Face to use when at redo port in source debugger.
ciao-face-entry-assrt (face)
Face to use for entry assertions.
ciao-face-error-mess (face)
Face to use for error messages.
ciao-face-false-assrt (face)
Face to use for false assertions.
ciao-face-highlight-code (face)
Face to use for highlighting code areas (e.g., when locating the code area that an error message refers to).
ciao-face-library-directive (face)
Face to use for directives defined in the library.
ciao-face-lpdoc-bug-comment (face)
Face to use for LPdoc bug comments.
ciao-face-lpdoc-command (face)
Face to use LPdoc commands inserted in documentation text.
ciao-face-lpdoc-comment (face)
Face to use for LPdoc textual comments.
ciao-face-lpdoc-comment-variable-pitch (face)
Face to use for LPdoc textual comments in variable pitch.
ciao-face-lpdoc-crossref (face)
Face to use for LPdoc cross-references.
ciao-face-lpdoc-include (face)
Face to use for LPdoc include commands.
ciao-face-lpdoc-verbatim (face)
Face to use for LPdoc verbatim text.
ciao-face-lpdoc-version-comment (face)
Face to use for LPdoc version comments.
ciao-face-modedef-assrt (face)
Face to use for modedef definitions.
ciao-face-module-directive (face)
Face to use for the module-related directives.
ciao-face-no-answer (face)
Face to use for no answer in top level.
ciao-face-note-mess (face)
Face to use for note messages.
ciao-face-other-mess (face)
Face to use for other messages.
ciao-face-predicate-directive (face)
Face to use for the predicate-related directives.
ciao-face-prompt (face)
Face to use for prompts in top-level and shells.
ciao-face-prop-assrt (face)
Face to use for property definitions.
ciao-face-quoted-atom (face)
Face to use for quoted atoms.
ciao-face-regtype-assrt (face)
Face to use for regtype definitions.
ciao-face-script-header (face)
Face to use for script headers.
ciao-face-startup-mess (face)
Face to use for system splash message.
ciao-face-string (face)
Face to use for strings.
ciao-face-true-assrt (face)
Face to use for true assertions.
ciao-face-trust-assrt (face)
Face to use for trust assertions.
ciao-face-user-directive (face)
Face to use for directives defined by the user (see ciao-user-directives custom variable to add new ones).
ciao-face-variable (face)
Face to use for variables.
ciao-face-warning-mess (face)
Face to use for warning messages.
ciao-face-yes-answer (face)
Face to use for yes answer in top level.
ciao-faces-use-variable-pitch-in-comments (boolean)
Controls whether variable pitch fonts are used when highlighting comments. Unset by default. After changing this you must exit and reinitialize for the change to take effect.

Installation of the Ciao/Prolog emacs interface

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 either the emacs mode was not installed or the installation settings are being overwritten by other settings in your .emacs file or in some library. In any case, you can set things manually 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 mode initialization
;; -------------------------------
;; (can normally be used with other Prolog modes and the default prolog.el)
;; 
(setq load-path (cons "<CIAOLIBDIR>" load-path))
(autoload 'run-ciao-toplevel "ciao"
          "Start a Ciao/Prolog top-level sub-process." t)
(autoload 'ciao-startup "ciao"
          "The Ciao/Prolog program development system startup screens." t)
(autoload 'ciao "ciao"
          "Start a Ciao/Prolog top-level sub-process." t)
(autoload 'prolog "ciao"
          "Start a Ciao/Prolog top-level sub-process." t)
(autoload 'run-ciao-preprocessor "ciao"
          "Start a Ciao/Prolog preprocessor sub-process." t)
(autoload 'ciaopp "ciao"
          "Start a Ciao/Prolog preprocessor sub-process." t)
(autoload 'ciao-mode "ciao"
          "Major mode for editing and running Ciao/Prolog" t)
(autoload 'ciao-inferior-mode "ciao"
          "Major mode for running Ciao/Prolog, CiaoPP, 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). Under Un*x, 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 from the source distribution or section Installing Ciao from a Win32 binary distribution) for details.

Emacs version compatibility

This mode is currently being developed within GNU emacs version 21.2. It should also (hopefully) work with all other 21.XX, 20.XX, and later 19.XX versions. We also try our best to keep things working under xemacs.

Acknowledgments (ciao.el)

This code is derived from the 1993 version of the emacs interface for &-Prolog by M. Hermenegildo, 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 and Manuel C. Rodriguez. See the changelog for details.

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