@ciao-lang/ts-ciao-interface

Version:

Simple Ciao interface for node.

7 lines • 87 kB

HTML

<!DOCTYPE HTML><html><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1"/><meta name="theme-color" content="#273f79"/><link rel="stylesheet" href="lpdoc.css" type="text/css"/><script type="text/javascript" src="lpdoc.js"></script><title>Using Ciao inside GNU emacs — The Ciao System v1.22</title></head><body><div class="lpdoc-page fixleftbar"><a href="#" id="sidebar-toggle-button" class="lpdoc-navbutton">☰</a><div id="sidebar" class="lpdoc-sidebar"><div style="height: 40px; margin-left: auto; margin-right: auto"><img src="ciao-logo_autofig.png" width=auto height=100%></div><div class="lpdoc-nav"><a class="lpdoc-navbutton" href="DevEnv.html">↑</a><a class="lpdoc-navbutton" href="pldiff.html">←</a><a class="lpdoc-navbutton" href="AdvCiaoEmacs.html">→</a><a class="lpdoc-navbutton" href="ciaosearch.html">🔍</a><a href="ciaofulltoc.html">TOC</a></div><hr></hr><ul class="lpdoc-itemize-sectpath"><li><a href="ciao.html">The Ciao System</a> » </li><li><a href="DevEnv.html">PART I - The program development environment</a> » </li><li><a href="">Using Ciao inside GNU emacs</a></li></ul><hr></hr>ON THIS PAGE<ul><li><a href="#Conventions for writing Ciao programs under Emacs">Conventions for writing Ciao programs under Emacs</a></li><li><a href="#Checking the installation">Checking the installation</a></li><li><a href="#Functionality and associated key sequences (bindings)">Functionality and associated key sequences (bindings)</a></li><li><a href="#Syntax coloring and syntax-based editing">Syntax coloring and syntax-based editing</a></li><li><a href="#Getting on-line help">Getting on-line help</a></li><li><a href="#Loading and compiling programs">Loading and compiling programs</a></li><li><a href="#Commands available in toplevel and preprocessor buffers">Commands available in toplevel and preprocessor buffers</a></li><li><a href="#Locating errors and checking the syntax of assertions">Locating errors and checking the syntax of assertions</a></li><li><a href="#Commands which help typing in programs">Commands which help typing in programs</a></li><li><a href="#Debugging programs">Debugging programs</a></li><li><a href="#Testing programs">Testing programs</a></li><li><a href="#Preprocessing programs">Preprocessing programs</a></li><li><a href="#Version control">Version control</a></li><li><a href="#Generating program documentation">Generating program documentation</a></li><li><a href="#Setting top level preprocessor and documenter executables">Setting top level preprocessor and documenter executables</a></li><li><a href="#Other commands">Other commands</a></li><li><a href="#Traditional Prolog Mode Commands">Traditional Prolog Mode Commands</a></li><li><a href="#Coexistence with other Prolog-like interfaces">Coexistence with other Prolog-like interfaces</a></li><li><a href="#Getting the Ciao mode version">Getting the Ciao mode version</a></li><li><a href="#Using Ciao mode capabilities in standard shells">Using Ciao mode capabilities in standard shells</a></li><li><a href="#Customization">Customization</a></li><ul><li><a href="#Ciao general variables">Ciao general variables</a></li><li><a href="#CiaoPP variables">CiaoPP variables</a></li><li><a href="#LPdoc variables">LPdoc variables</a></li><li><a href="#Faces used in syntax-based highlighting (coloring)">Faces used in syntax-based highlighting (coloring)</a></li></ul><li><a href="#Installation of the Ciao emacs interface">Installation of the Ciao emacs interface</a></li><li><a href="#Emacs version compatibility">Emacs version compatibility</a></li><li><a href="#Acknowledgments (ciao.el)">Acknowledgments (ciao.el)</a></li></ul></div><div class="lpdoc-main"><div id=""><h1>Using Ciao inside GNU emacs</h1><a class="lpdoc-idx-anchor" href="ciaosearch.html#CiaoMode"></a> Author(s): <a class="lpdoc-idx-anchor" id="Manuel Hermenegildo" href="ciaosearch.html#Manuel Hermenegildo">Manuel Hermenegildo</a>, <a class="lpdoc-idx-anchor" id="Manuel C. Rodriguez" href="ciaosearch.html#Manuel C. Rodriguez">Manuel C. Rodriguez</a>, <a class="lpdoc-idx-anchor" id="Daniel Cabeza" href="ciaosearch.html#Daniel Cabeza">Daniel Cabeza</a>. The Ciao <a class="lpdoc-idx-anchor" id="0" href="ciaosearch.html#emacs interface">emacs interface</a> (or mode <a class="lpdoc-idx-anchor" id="1" href="ciaosearch.html#emacs mode"></a> in <a class="lpdoc-idx-anchor" id="2" href="emacs.html"><tt>emacs</tt></a> terms) provides a rich, integrated user interface to the Ciao <a class="lpdoc-idx-anchor" id="3" href="ciaosearch.html#program development environment">program development environment</a> components, including the <a class="lpdoc-idx-anchor" id="4" href="ciaosearch.html#ciaosh"><tt>ciaosh</tt></a> interactive top level, the <a class="lpdoc-idx-anchor" id="5" href="ciaosearch.html#lpdoc"><tt>lpdoc</tt></a> documentation generator, the testing system, and the <a class="lpdoc-idx-anchor" id="6" href="ciaosearch.html#ciaopp"><tt>ciaopp</tt></a> preprocessor. Most features of these Ciao development environment components are available from the command line of the top-level shell and the preprocessor and as standalone tools. However, using Ciao from inside <a class="lpdoc-idx-anchor" id="7" href="emacs.html"><tt>emacs</tt></a> is highly recommended. The facilities that this mode provides include:<ul> <li><a class="lpdoc-idx-anchor" id="8" href="ciaosearch.html#Syntax-based highlighting">Syntax-based highlighting</a> (coloring), <a class="lpdoc-idx-anchor" id="9" href="ciaosearch.html#coloring, syntax"></a> <a class="lpdoc-idx-anchor" id="10" href="ciaosearch.html#auto-indentation">auto-indentation</a>, <a class="lpdoc-idx-anchor" id="11" href="ciaosearch.html#auto-fill">auto-fill</a>, etc. of code. This includes the assertions used by the preprocessor and the documentation strings used by the Ciao auto-documenter, <a class="lpdoc-idx-anchor" id="12" href="ciaosearch.html#lpdoc"><tt>lpdoc</tt></a>.<li>Providing automatic access to <a class="lpdoc-idx-anchor" id="13" href="ciaosearch.html#on-line help">on-line help</a> for all predicates by accessing the Ciao system manuals in <a class="lpdoc-idx-anchor" id="14" href="ciaosearch.html#info"><tt>info</tt></a> format.<li>Starting and communicating with the <a class="lpdoc-idx-anchor" id="15" href="ciaosearch.html#Ciao top-level">Ciao top-level</a>, running in its own <a class="lpdoc-idx-anchor" id="16" href="ciaosearch.html#sub-shell">sub-shell</a>. This facilitates loading programs, checking the syntax of programs (and of <a class="lpdoc-idx-anchor" id="17" href="ciaosearch.html#assertions">assertions</a> within programs), marking and unmarking modules for interactive debugging, <a class="lpdoc-idx-anchor" id="18" href="ciaosearch.html#tracing the source code">tracing the source code</a> <a class="lpdoc-idx-anchor" id="19" href="ciaosearch.html#source-level debugging"></a> <a class="lpdoc-idx-anchor" id="20" href="ciaosearch.html#debugging, source-level"></a> during debugging, making standalone executables, compiling modules to dynamically linkable Ciao objects, compiling modules to active objects, etc.<li>Starting and communicating with <a class="lpdoc-idx-anchor" id="21" href="ciaosearch.html#lpdoc"><tt>lpdoc</tt></a>, the <a class="lpdoc-idx-anchor" id="22" href="ciaosearch.html#Ciao auto-documenter">Ciao auto-documenter</a>, running in its own <a class="lpdoc-idx-anchor" id="23" href="ciaosearch.html#sub-shell">sub-shell</a>. This allows generating in a very convenient way manuals for any file(s) being edited, in a variety of output formats, and is very useful for quickly checking how the auto-generated documentation will look.<li>Running unit tests on files or applications.<li>Starting and communicating with <a class="lpdoc-idx-anchor" id="24" href="ciaosearch.html#ciaopp"><tt>ciaopp</tt></a>, the <a class="lpdoc-idx-anchor" id="25" href="ciaosearch.html#Ciao preprocessor">Ciao preprocessor</a>, running in its own <a class="lpdoc-idx-anchor" id="26" href="ciaosearch.html#sub-shell">sub-shell</a>. This allows easily performing certain kinds of <a class="lpdoc-idx-anchor" id="27" href="ciaosearch.html#static checks">static checks</a> (useful for finding errors in programs before running them), program analysis tasks, and <a class="lpdoc-idx-anchor" id="28" href="ciaosearch.html#program transformations">program transformations</a> on source programs.<li>Syntax highlighting and coloring of the error and warning messages produced by the top level, unit testing, preprocessor, or any other tool using the same message format (such as the <a class="lpdoc-idx-anchor" id="29" href="ciaosearch.html#lpdoc"><tt>lpdoc</tt></a> auto-documenter), and locating automatically the points in the source files where such errors occur.<li>This mode also includes a very simple automatic <a class="lpdoc-idx-anchor" id="30" href="ciaosearch.html#version control">version control</a> system which allows keeping a <a class="lpdoc-idx-anchor" id="31" href="ciaosearch.html#changelog">changelog</a> for individual files or for whole applications. This is done by automatically including changelog entries in source files, which can then be processed by the <a class="lpdoc-idx-anchor" id="32" href="ciaosearch.html#lpdoc"><tt>lpdoc</tt></a> auto-documenter. This is useful for smaller projects that are not stored in a repository and can also be used for maintaining changelogs even for projects that are repository-based.</ul> This chapter explains how to use the Ciao <a class="lpdoc-idx-anchor" id="33" href="emacs.html"><tt>emacs</tt></a> interface (and how to set up your <a class="lpdoc-idx-anchor" id="34" href="emacs.html"><tt>emacs</tt></a> environment for correct operation, even though this is normally done automatically by the installation process). The Ciao <a class="lpdoc-idx-anchor" id="35" href="emacs.html"><tt>emacs</tt></a> interface can also be used to work with traditional Prolog or CLP systems.<div id="Conventions for writing Ciao programs under Emacs"><h2>Conventions for writing Ciao programs under Emacs</h2> <a class="lpdoc-idx-anchor" id="36" href="ciaosearch.html#formatting conventions, for emacs"></a> There are currently a number of syntactic conventions for Ciao programs which greatly help operation of the Emacs development environment. These conventions are particularly important for the <a class="lpdoc-idx-anchor" id="37" href="ciaosearch.html#source-level debugger">source-level debugger</a> and the <a class="lpdoc-idx-anchor" id="38" href="ciaosearch.html#syntax-based coloring">syntax-based coloring</a> capabilities. The need for such conventions comes from the fact that it would be unrealistic to write a complete Ciao parser in Emacs lisp. These conventions are the following, more or less in order of importance:<ul> <li>Clauses should begin on the first column (this is used to recognize the beginning of a clause).<li>C style comments should not be used in a clause, but can be used outside any clause.</ul> The following suggestions are not strictly necessary but can improve operation. In particular, they allow much greater precision in the location of program points during source-level debugging (for line by line tracing, when marking breakpoints, etc.):<ul> <li>Body literals should be indented.<li>There should be no more than one literal per line.</ul> Other issues:<ul> <li>Comments which start with <tt>%</tt>s are indented to the right if indentation is requested.<li>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 <a class="lpdoc-idx-anchor" id="39" href="ciaosearch.html#.emacs"><tt>.emacs</tt></a> file).</ul> </div><div id="Checking the installation"><h2>Checking the installation</h2> Typically, a complete pre-installation of the Ciao <a class="lpdoc-idx-anchor" id="40" href="emacs.html"><tt>emacs</tt></a> interface is performed during Ciao installation. To check that installation was completed sucessfully, open a file with a <tt>.pl</tt> ending. You should see that <a class="lpdoc-idx-anchor" id="41" href="emacs.html"><tt>emacs</tt></a> enters Ciao mode: the mode is identified in the <a class="lpdoc-idx-anchor" id="42" href="ciaosearch.html#status bar">status bar</a> below the <a class="lpdoc-idx-anchor" id="43" href="ciaosearch.html#buffer">buffer</a> and, if the <a class="lpdoc-idx-anchor" id="44" href="ciaosearch.html#emacs menu bar">emacs menu bar</a> is enabled, you should see the Ciao menus. You should be able from the menu-bar, for example, to go to the Ciao manuals in the info or load the <tt>.pl</tt> file that you just opened into a Ciao top level.If things don't work properly, see the section <a href="#Installation of the Ciao emacs interface">Installation of the Ciao emacs interface</a> later in this chapter.</div><div id="Functionality and associated key sequences (bindings)"><h2>Functionality and associated key sequences (bindings)</h2> The following sections summarize the capabilities of the Ciao emacs interface and the (default) <a class="lpdoc-idx-anchor" id="45" href="ciaosearch.html#key sequences">key sequences</a> used to access those capabilities. Note however that most of these functions are also accessible from the menu bar, so learning these key combinations is not necessary: the list is provided mainly for illustration of the capabilities available, as well as completeness and documentation.<a class="lpdoc-idx-anchor" id="46" href="ciaosearch.html#keyboard"></a> When referring to keyboard characters, printing characters are written thus: a, while control characters are written like this: ^A. Thus ^C is the character you get by holding down the CTL key while you type c. Finally, the special control characters carriage-return, line-feed and space are often abbreviated to RET, LFD and SPC respectively.</div><div id="Syntax coloring and syntax-based editing"><h2>Syntax coloring and syntax-based editing</h2> Syntax-based highlighting (coloring) of code is provided automatically when opening Ciao files. This includes also the assertions used by the preprocessor and the documentation strings used by the Ciao auto-documenter, <a class="lpdoc-idx-anchor" id="47" href="ciaosearch.html#lpdoc"><tt>lpdoc</tt></a>. The mode should be set to Ciao and the Ciao mode menus should appear on the menu bar. The colors and fonts used can be changed through the <a class="lpdoc-idx-anchor" id="48" href="ciaosearch.html#customize">customize</a> options in the help menu (see <a href="#Customization">Customization</a>).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:<dl> <dt>TAB <dd> Indent current line as Ciao code. With argument, indent any additional lines of the same clause rigidly along with this one. </dl> </div><div id="Getting on-line help"><h2>Getting on-line help</h2> The following commands are useful for getting on-line help. This is done by accessing the <a class="lpdoc-idx-anchor" id="49" href="ciaosearch.html#info"><tt>info</tt></a> version of the Ciao manuals or the <a class="lpdoc-idx-anchor" id="50" href="emacs.html"><tt>emacs</tt></a> built-in help strings. Note also that the <a class="lpdoc-idx-anchor" id="51" href="ciaosearch.html#info"><tt>info</tt></a> standard <tt>search</tt> command (generally bound to s) can be used inside <a class="lpdoc-idx-anchor" id="52" href="ciaosearch.html#info"><tt>info</tt></a> buffers to search for a given string.<dl> <dt>C-h S <dd> Display the definition of a Ciao SYMBOL, as found in the relevant manual. </dl> <dl> <dt>C-h M-s <dd> Grovel indices from Ciao manuals for STRING. Build a menu of the possible matches. </dl> <dl> <dt>C-h TAB <dd> Completions at point for ‘ciao-mode’ using ‘info-look’. </dl> <dl> <dt>C-c RET <dd> Go to the part of the info directory containing the Ciao manuals. </dl> <dl> <dt>C-h m <dd> Show a short description of the Ciao Emacs mode, including all key bindings. </dl> </div><div id="Loading and compiling programs"><h2>Loading and compiling programs</h2> These commands allow <a class="lpdoc-idx-anchor" id="53" href="ciaosearch.html#loading programs">loading programs</a>, <a class="lpdoc-idx-anchor" id="54" href="ciaosearch.html#creating executables">creating executables</a>, etc. by issuing the appropriate commands to a Ciao top level shell, running in its own buffer as a subprocess. See <a href="toplevel_doc.html">The interactive top-level shell</a> for details. The following commands implement the communication with the Ciao top level:<dl> <dt>C-c t <dd> Ensure that an inferior Ciao top-level process is running.This opens a top-level window (if one did not exist already) where queries can be input directly. 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 <a href="#Commands available in toplevel and preprocessor buffers">Commands available in toplevel and preprocessor buffers</a>).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). </dl> <dl> <dt>C-c l <dd> Load the current buffer (and any auxiliary files it may use) into the top level.The type of compilation performed (<a class="lpdoc-idx-anchor" id="55" href="ciaosearch.html#compiling">compiling</a> or <a class="lpdoc-idx-anchor" id="56" href="ciaosearch.html#interpreting">interpreting</a>) 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. </dl> <dl> <dt>C-c f <dd> Load CiaoPP and then the current buffer (and any auxiliary files it may use) into the top level. Use CiaoPP auto_check_assrt predicate to check current buffer assertions and then load the buffer if there was no error. </dl> <dl> <dt>C-c x <dd> Make an executable from the code in the current buffer. The buffer must contain a <a class="lpdoc-idx-anchor" id="57" href="ciaosearch.html#main/0"><tt>main/0</tt></a> or <a class="lpdoc-idx-anchor" id="58" href="ciaosearch.html#main/1"><tt>main/1</tt></a> 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. </dl> <dl> <dt>C-c o <dd> Make a Ciao 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. </dl> <dl> <dt>C-c s <dd> Set the current buffer as the principal file in a multiple module programming environment. </dl> <dl> <dt>C-c L <dd> Load the module designated as <a class="lpdoc-idx-anchor" id="59" href="ciaosearch.html#main module">main module</a> (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 (<a class="lpdoc-idx-anchor" id="60" href="ciaosearch.html#compiling">compiling</a> or <a class="lpdoc-idx-anchor" id="61" href="ciaosearch.html#interpreting">interpreting</a>) 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. </dl> </div><div id="Commands available in toplevel and preprocessor buffers"><h2>Commands available in toplevel and preprocessor buffers</h2> 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 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-specific commands available include:<dl> <dt>C-h S <dd> Display the definition of a Ciao SYMBOL, as found in the relevant manual. </dl> <dl> <dt>C-h M-s <dd> Grovel indices from Ciao manuals for STRING. Build a menu of the possible matches. </dl> <dl> <dt>C-c TAB <dd> Completions at point for ‘ciao-mode’ using ‘info-look’. </dl> <dl> <dt>M-] <dd> Go to the location in the source file containing the next error reported by the last Ciao subprocess (preprocessor or toplevel) which was run. </dl> <dl> <dt>M-[ <dd> Go to the location in the source file containing the previous error reported by the last Ciao subprocess (preprocessor or toplevel) which was run. </dl> <dl> <dt>C-c ` <dd> Go to the location in the source file containing the next error reported by the last Ciao subprocess (preprocessor or toplevel) which was run. </dl> <dl> <dt>C-c e <dd> Remove error marks from last run (and also debugging marks if present). This finish the error finding session. </dl> <dl> <dt>C-g <dd> Same as keyboard-quit (i.e., the normal Emacs quit, typically bound to C-g) but also clears the error markings from the last Ciao-related inferior process run. </dl> <dl> <dt>C-c q <dd> Set a default query. This may be useful specially during debugging or testing 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. </dl> <dl> <dt>C-c Q <dd> Issue predefined query. </dl> <dl> <dt>C-c C-v <dd> Show last output file produced by CiaoPP. 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. </dl> <dl> <dt>C-c v <dd> Report the version of the emacs Ciao mode. </dl> The following are some of the commands from the comint shell package which may be specially useful (type <tt><f1> m</tt> while in a Ciao interactive buffer for a complete list of commands):<dl> <dt>M-p <dd> Cycle backwards through input history, saving input.(fn ARG) </dl> <dl> <dt>M-n <dd> Cycle forwards through input history.(fn ARG) </dl> <dl> <dt>M-r <dd> Search for a regular expression backward in input history using Isearch. </dl> <dl> <dt>TAB <dd> 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). </dl> <dl> <dt>M-? <dd> List all (filename) completions of the item at point. </dl> <dl> <dt>RET <dd> 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. </dl> <dl> <dt>^D <dd> 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.(fn ARG) </dl> <dl> <dt>^C ^U <dd> Kill all text from last stuff output by interpreter to point. </dl> <dl> <dt>^C ^W <dd> Kill characters backward until encountering the beginning of a word. With argument ARG, do this that many times.(fn ARG) </dl> <dl> <dt>^C ^C <dd> Interrupt the current subjob. </dl> <dl> <dt>^C ^Z <dd> Stop the current subjob.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.) </dl> <dl> <dt>^C ^\ <dd> Send quit signal to the current subjob. </dl> </div><div id="Locating errors and checking the syntax of assertions"><h2>Locating errors and checking the syntax of assertions</h2> 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: <a class="lpdoc-idx-anchor" id="62" href="ciaosearch.html#locating errors"></a> <dl> <dt>M-] <dd> Go to the location in the source file containing the next error reported by the last Ciao subprocess (preprocessor or toplevel) which was run. </dl> <dl> <dt>M-[ <dd> Go to the location in the source file containing the previous error reported by the last Ciao subprocess (preprocessor or toplevel) which was run. </dl> <dl> <dt>C-c ` <dd> Go to the location in the source file containing the next error reported by the last Ciao subprocess (preprocessor or toplevel) which was run. </dl> <dl> <dt>C-c e <dd> Remove error marks from last run (and also debugging marks if present). This finish the error finding session. </dl> <dl> <dt>C-g <dd> Same as keyboard-quit (i.e., the normal Emacs quit, typically bound to C-g) but also clears the error markings from the last Ciao-related inferior process run. </dl> </div><div id="Commands which help typing in programs"><h2>Commands which help typing in programs</h2> The following commands are intended to help in the process of writing programs: <a class="lpdoc-idx-anchor" id="63" href="ciaosearch.html#script header, inserting automatically"></a> <dl> <dt>C-c I S <dd> 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., ’<tt>chmod +x <file></tt>’ in Unix). See <a href="ciao-shell.html">The script interpreter</a> for details. </dl> <dl> <dt>C-c C-f <dd> Format a Ciao program using ‘ciaofmt’. </dl> </div><div id="Debugging programs"><h2>Debugging programs</h2> These commands allow marking modules for <a class="lpdoc-idx-anchor" id="64" href="ciaosearch.html#debugging">debugging</a> by issuing the appropiate commands to a Ciao top level shell, running in its own buffer as a subprocess. There are two differents types of debugging: traditional debugging (using the <a class="lpdoc-idx-anchor" id="65" href="ciaosearch.html#byrd-box model">byrd-box model</a> and <a class="lpdoc-idx-anchor" id="66" href="ciaosearch.html#spy-points">spy-points</a>) and <a class="lpdoc-idx-anchor" id="67" href="ciaosearch.html#source-level debugging">source-level debugging</a> (same as traditional debugging plus source tracing and <a class="lpdoc-idx-anchor" id="68" href="ciaosearch.html#breakpoints">breakpoints</a>). <a class="lpdoc-idx-anchor" id="69" href="ciaosearch.html#debugging, source-level"></a> In order to use <a class="lpdoc-idx-anchor" id="70" href="ciaosearch.html#breakpoints">breakpoints</a>, source debugging must be on. The following commands implement comunication with the Ciao top level:<dl> <dt>C-c d <dd> 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 <tt>trace.</tt> 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. </dl> <dl> <dt>C-c m <dd> Mark, or unmark, 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. </dl> <dl> <dt>C-c M-m <dd> Visits all Ciao 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 files and select the debug mode for each of them (same as doing C-c m for each). </dl> <dl> <dt>C-c S b <dd> 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. </dl> <dl> <dt>C-c S v <dd> 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. </dl> <dl> <dt>C-c S n <dd> Remove all breakpoints. This can be done at any time (while debugging or not). </dl> <dl> <dt>C-c S l <dd> Redisplay breakpoints in all Ciao buffers. This ensures that the marks in the source files and the Ciao toplevel are synchronized. </dl> <dl> <dt>C-c S r <dd> Remove breakpoint coloring in all Ciao files. </dl> <dl> <dt>C-c S t <dd> Set the debugger to the trace state. In this state, the program is executed step by step. </dl> <dl> <dt>C-c S d <dd> Set the debugger to the debug state. In this state, the program will only stop in breakpoints and spypoints. Breakpoints are specially supported in <a class="lpdoc-idx-anchor" id="71" href="emacs.html"><tt>emacs</tt></a> and using source debug. </dl> <dl> <dt>C-c r <dd> 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). </dl> <dl> <dt>C-c p <dd> 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). </dl> </div><div id="Testing programs"><h2>Testing programs</h2> These commands allow testing predicates and modules, based on interactively defined queryies or more sophisticated tests specified within the source code. <dl> <dt>C-c q <dd> Set a default query. This may be useful specially during debugging or testing 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. </dl> <dl> <dt>C-c Q <dd> Issue predefined query. </dl> <dl> <dt>C-c u <dd> Run the tests in the current buffer.The tests should be specified using test assertions in the module. </dl> <dl> <dt>C-c U <dd> Run the tests in the current buffer and check the assertions of exported predicates.The tests should be specified using test assertions in the module. </dl> </div><div id="Preprocessing programs"><h2>Preprocessing programs</h2> These commands allow <a class="lpdoc-idx-anchor" id="72" href="ciaosearch.html#preprocessing programs">preprocessing programs</a> with <a class="lpdoc-idx-anchor" id="73" href="ciaosearch.html#ciaopp"><tt>ciaopp</tt></a>, the <a class="lpdoc-idx-anchor" id="74" href="ciaosearch.html#CiaoPP Program Processor">CiaoPP Program Processor</a>.See the preprocessor manual for details. The following commands implement the communication with CiaoPP:<dl> <dt>C-c A <dd> Call the preprocessor to perform a number of pre-selected analyses on the current buffer (and related modules). </dl> <dl> <dt>C-c V <dd> Call the preprocessor to perform compile-time checking of the assertions (types, modes, determinacy, nonfailure, cost, ...) in the current buffer (and against those in related modules). </dl> <dl> <dt>C-c O <dd> Uses the preprocessor to perform optimizations (partial evaluation, abstract specialization, parallelization, ...) on the current buffer (and related modules). </dl> <dl> <dt>C-c M <dd> Browse and select (using the preprocessor menus) the actions to be performed by the preprocessor when performing analisys used by M-x ciao- C-c A, C-c V, C-c O, and the corresponding toolbar buttons. </dl> <dl> <dt>C-c C-v <dd> Show last output file produced by CiaoPP. 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. </dl> <dl> <dt>C-c C-r <dd> Ensure that an inferior CiaoPP 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 A, C-c V, C-c O, or C-c M) 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 <a href="#Commands available in toplevel and preprocessor buffers">Commands available in toplevel and preprocessor buffers</a>).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). </dl> </div><div id="Version control"><h2>Version control</h2> The following commands can be used to carry out a simple but effective form of <a class="lpdoc-idx-anchor" id="75" href="ciaosearch.html#version control">version control</a> by keeping a <a class="lpdoc-idx-anchor" id="76" href="ciaosearch.html#log of changes">log of changes</a> on a file or a group of related files. Interestingly, this log is kept in a format that is understood by <a class="lpdoc-idx-anchor" id="77" href="ciaosearch.html#lpdoc"><tt>lpdoc</tt></a>, the Ciao documenter [<a class="lpdoc-idx-anchor" id="78" href="ciaorefs.html#lpdoc-tr">Her99</a>]. As a result, if these version comments are present, then <a class="lpdoc-idx-anchor" id="79" href="ciaosearch.html#lpdoc"><tt>lpdoc</tt></a> 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, <a class="lpdoc-idx-anchor" id="80" href="ciaosearch.html#lpdoc"><tt>lpdoc</tt></a> 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:<ul> <li>a <a class="lpdoc-idx-anchor" id="81" href="ciaosearch.html#version number">version number</a> (such as, e.g., <tt>1.2</tt>, where <tt>1</tt> is the <a class="lpdoc-idx-anchor" id="82" href="ciaosearch.html#major version number">major version number</a> and <tt>2</tt> is the <a class="lpdoc-idx-anchor" id="83" href="ciaosearch.html#minor version number">minor version number</a>),<li>a <a class="lpdoc-idx-anchor" id="84" href="ciaosearch.html#patch number">patch number</a> (such as, e.g., the <tt>4</tt> in <tt>1.2#4</tt>),<li>a <a class="lpdoc-idx-anchor" id="85" href="ciaosearch.html#time stamp">time stamp</a> (such as, e.g., <tt>1998/12/14,17:20*28+MET</tt>),<li>the author of the change, <a class="lpdoc-idx-anchor" id="86" href="ciaosearch.html#change, author"></a> and<li>a comment explaining the change. <a class="lpdoc-idx-anchor" id="87" href="ciaosearch.html#change, comment"></a> </ul> The <a class="lpdoc-idx-anchor" id="88" href="ciaosearch.html#version numbering">version numbering</a> 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 <a class="lpdoc-idx-anchor" id="89" href="ciaosearch.html#changelog entry">changelog entry</a> 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 <a class="lpdoc-idx-anchor" id="90" href="assertions_doc.html#comment/2"><tt>comment/2</tt></a> declaration. As mentioned before, the advantage of using this kind of changelog entries is that these declarations can be processed by the <a class="lpdoc-idx-anchor" id="91" href="ciaosearch.html#lpdoc"><tt>lpdoc</tt></a> automatic documenter (see the <a class="lpdoc-idx-anchor" id="92" href="ciaosearch.html#lpdoc"><tt>lpdoc</tt></a> reference manual [<a class="lpdoc-idx-anchor" id="93" href="ciaorefs.html#lpdoc-tr">Her99</a>] or the <a class="lpdoc-idx-anchor" id="94" href="assertions_doc.html"><tt>assertions</tt></a> 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 <a class="lpdoc-idx-anchor" id="95" href="assertions_doc.html#comment/2"><tt>comment/2</tt></a> declaration of the type:<tt>:- doc(version_maintenance,<type>).</tt> (note that this requires including the <a class="lpdoc-idx-anchor" id="96" href="assertions_doc.html"><tt>assertions</tt></a> 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:<pre class="lpdoc-codeblock">%% Local Variables: %% mode: ciao %% update-version-comments: "off" %% End: </pre> The lines above instruct emacs to put the buffer visiting the file in <a class="lpdoc-idx-anchor" id="97" href="ciaosearch.html#emacs Ciao mode">emacs Ciao mode</a> and to turn version maintenance off. Setting the version maintenance mode in this way has the disadvantage that <a class="lpdoc-idx-anchor" id="98" href="ciaosearch.html#lpdoc"><tt>lpdoc</tt></a>, 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 Ciao). However, this can be useful in fact for setting the <a class="lpdoc-idx-anchor" id="99" href="ciaosearch.html#version maintenance mode for packages">version maintenance mode for packages</a> 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:<dl> <dt>C-c C-a <dd> Used to turn on or off version control for the file being visited in the current buffer. The user will be prompted to choose among the following options:<dl> <dt>y<dd> Turn version control on for this file.<dt>n<dd> Turn version control off for this file. A version control comment such as:<tt>:- doc(version_maintenance,off).</tt> will be added to the buffer and the file saved. No version control will be performed on this file until the line above is removed or modified (i.e., from now on C-x C-s simply saves the buffer).<dt>q<dd> Turn off prompting for the introduction of changelog entries for now. <a class="lpdoc-idx-anchor" id="100" href="emacs.html"><tt>emacs</tt></a> will not ask again while the buffer is loaded, but it may ask again when saving after the next time you load the buffer (if <tt>ciao-ask-for-version-maintenance-type</tt> is set to <tt>yes</tt>).