Introduction

About this manual

This is the Reference Manual for the Ciao development system. It contains basic information on how to install Ciao and how to write, debug, and run Ciao programs from the command line, from inside GNU emacs, or from a windowing desktop. It also documents all the libraries available in the standard distribution.

This manual has been generated using the LPdoc semi-automatic documentation generator for LP/CLP programs [HC97,Her00]. lpdoc processes Ciao files (and files in Prolog and other CLP languages) adorned with assertions and machine-readable comments, which should be written in the Ciao assertion language [PBH97,PBH00]. From these, it generates manuals in many formats including postscript, pdf, texinfo, info, HTML, man, etc., as well as on-line help, ascii README files, entries for indices of manuals (info, WWW, ...), and maintains WWW distribution sites.

The big advantage of this approach is that it is easier to keep the on-line and printed documentation in sync with the source code [Knu84]. As a result, this manual changes continually as the source code is modified. Because of this, the manual has a version number. You should make sure the manual you are reading, whether it be printed or on-line, coincides with the version of the software that you are using.

The approach also implies that there is often a variability in the degree to which different libraries or system components are documented. Many libraries offer abundant documentation, but a few will offer little. The latter is due to the fact that we tend to include libraries in the manual if the code is found to be useful, even if they may still contain sparse documentation. This is because including a library in the manual will at the bare minimum provide formal information (such as the names of exported predicates and their arity, which other modules it loads, etc.), create index entries, pointers for on-line help in the electronic versions of the manuals, and command-line completion capabilities inside emacs. Again, the manual is being updated continuously as the different libraries (and machine-readable documentation in them) are improved.

About the Ciao development system

The Ciao system is a full programming environment for developing programs in the Prolog language and in several other languages which are extensions and modifications of Prolog and (Constraint) Logic Programming in several interesting and useful directions. The programming environment offers a number of tools such as the Ciao standalone compiler (ciaoc), a traditional-style top-level interactive shell (ciaosh or ciao), an interpreter of scripts written in Ciao (ciao-shell), a Ciao (and Prolog) emacs mode (which greatly helps the task of developing programs with support for editing, debugging, version/change tracking, etc.), numerous libraries, a powerful program preprocessor (ciaopp [BGH99,BLGPH04,HBPLG99], which supports static debugging and optimization from program analysis via source to source program transformation), and an automatic documentation generator (lpdoc) [HC97,Her00]. A number of execution visualization tools [CGH93,CH00d,CH00c] are also available.

This manual documents the first four of the tools mentioned above [see PART I - The program development environment], and the Ciao language and libraries. The ciaopp and lpdoc tools are documented in separate manuals.

The Ciao language [see PART II - The Ciao basic language (engine)] has been designed from the ground up to be small, but to also allow extensions and restrictions in a modular way. The first objective allows producing small executables (including only those builtins used by the program), providing basic support for pure logic programming, and being able to write scripts in Ciao. The second one allows supporting standard ISO-Prolog [see PART III - ISO-Prolog library (iso)], as well as powerful extensions such as constraint logic programming, functional logic programming, and object-oriented logic programming [see PART VII - Ciao extensions], and restrictions such as working with pure horn clauses.

The design of Ciao has also focused on allowing modular program development, as well as automatic program manipulation and optimization. Ciao includes a robust module system [CH00a], module-based automatic incremental compilation [CH99b], and modular global program analysis, debugging and optimization [PH99], based on a rich assertion language [see PART V - Assertions, Properties, Types, Modes, Comments (assertions)] for declaring (optional) program properties (including types and modes), which can be checked either statically or dynamically. The program analysis, static debugging and optimization tasks related to these assertions are performed by the ciaopp preprocessor, as mentioned above. These assertions (together with special comment-style declarations) are also the ones used by the lpdoc autodocumenter to generate documentation for programs (the comment-style declarations are documented in the lpdoc manual).

Ciao also includes several other features and utilities, such as support for several forms of executables, concurrency (threads), distributed and parallel execution, higher-order, WWW programming (PiLLoW [CHV96b]), interfaces to other languages like C and Java, database interfaces, graphical interfaces, etc., etc. [see PARTS VI to XI].

ISO-Prolog compliance versus extensibility

One of the innovative features of Ciao is that it has been designed to subsume ISO-Prolog (International Standard ISO/IEC 13211-1, PROLOG: Part 1--General Core [DEDC96]), while at the same time extending it in many important ways. The intention is to ensure that all ISO-compliant Prolog programs run correctly under Ciao. At the same time, the Ciao module system (see [PART II - The Ciao basic language (engine)] and [CH00a] for a discussion of the motivations behind the design) allows selectively avoiding the loading of most ISO-builtins (and changing some other ISO characteristics) when not needed, so that it is possible to work with purer subsets of Prolog and also to build small executables. Also, this module system makes it possible to develop extensions using these purer subsets (or even the full ISO-standard) as a starting point. Using these features, the Ciao distribution includes libraries which significantly extend the language both syntactically and semantically.

Compliance with ISO is still not complete: currently there are some minor deviations in, e.g., the treatment of characters, the syntax, some of the arithmetic functions, and part of the error system. On the other hand, Ciao has been reported by independent sources (members of the standarization body) to be one of the most conforming Prologs at the moment of this writing, and the first one to be able to compile all the standard-conforming test cases. Also, Ciao does not offer a strictly conforming mode which rejects uses of non-ISO features. However, in order to aid programmers who wish to write standard compliant programs, library predicates that correspond to those in the ISO-Prolog standard are marked specially in the manuals, and differences between the Ciao and the prescribed ISO-Prolog behaviours, if any, are commented appropriately.

The intention of the Ciao developers is to progressively complete the compliance of Ciao with the published parts of the ISO standard as well as with other reasonable extensions of the standard may be published in the future. However, since one of the design objectives of Ciao is to address some shortcomings of previous implementations of Prolog and logic programming in general, we also hope that some of the better ideas present in the system will make it eventually into other systems and the standards.

About the name of the System

Ciao is often referred to as “Ciao Prolog,” a name which has an interesting (and not unintended) interpretation. Ciao is an interesting word which means both hello and goodbye. 'Ciao Prolog' intends to be a really good, all-round, freely available ISO-Prolog system which can be used as a classical Prolog, in both academic and industrial environments (and, in particular, to introduce users to Prolog and to constraint and logic programming --the hello part). An indeed many programmers use it just that way. But Ciao is also a new-generation, multiparadigm programming language and program development system which goes well beyond Prolog and other classical logic programming languages. And it has the advantage (when compared to other new-generation LP systems) that it does so while keeping full Prolog compatibility when needed.

Referring to Ciao

If you find Ciao or any of its components useful, we would appreciate very much if you added a reference to this manual (i.e., the Ciao reference manual [BCC97]) in your work. The following is an appropriate BiBTeX entry with the relevant data:

@techreport{ciao-reference-manual-tr,
  author =       {F. Bueno and D. Cabeza and M. Carro and M. Hermenegildo 
                  and P. L\'{o}pez-Garc\'{\i}a and G. Puebla},
  title =        {The Ciao System. Reference Manual},
  institution =  {School of Computer Science, T. U. of Madrid (UPM) 
                  and IMDEA Software Institute},
  year =         1997,
  month =        {August},
  number =       {{CLIP}3/1997.2011},
  note =         {Available from http://www.cliplab.org/}
}

Syntax terminology and notational conventions

This manual assumes some familiarity with logic programming and the Prolog language. The reader is referred to standard textbooks on logic programming and Prolog (such as, e.g., [SS86,CM81,Apt97,Hog84]) for background. However, we would like to refresh herein some concepts for the sake of establishing terminology. Also, we will briefly introduce a few of the extensions that Ciao brings to the Prolog language.

Predicates and their components

Procedures are called predicates and predicate calls literals. They all have the classical syntax of procedures (and of logic predications and of mathematical functions). Predicates are identified in this manual by a keyword 'PREDICATE' at the right margin of the place where they are documented.

Program instructions are expressions made up of control constructs (Control constructs/predicates) and literals, and are called goals. Literals are also (atomic) goals.

A predicate definition is a sequence of clauses. A clause has the form “H :- B.” (ending in '.'), where H is syntactically the same as a literal and is called the clause head, and B is a goal and is called the clause body. A clause with no body is written “H.” and is called a fact. Clauses with body are also called rules. A program is a sequence of predicate definitions.

Characters and character strings

We adopt the following convention for delineating character strings in the text of this manual: when a string is being used as an atom it is written thus: user or 'user'; but in all other circumstances double quotes are used (as in "hello").

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.

Predicate specs

Predicates are distinguished by their name and their arity. We will call name/arity a predicate spec. The notation name/arity is therefore used when it is necessary to refer to a predicate unambiguously. For example, concatenate/3 specifies the predicate which is named “concatenate” and which takes 3 arguments.

(Note that different predicates may have the same name and different arity. Conversely, of course, they may have the same arity and different name.)

Modes

When documenting a predicate, we will often describe its usage with a mode spec which has the form name(Arg1, ..., ArgN) where each Arg may be preceded by a mode. A mode is a functor which is wrapped around an argument (or prepended if defined as an operator). Such a mode allows documenting in a compact way the instantiation state on call and exit of the argument to which it is applied. The set of modes which can be used in Ciao is not fixed. Instead, arbitrary modes can be defined by in programs using the modedef/1 declarations of the Ciao assertion language (The Ciao assertion package for details). Modes are identified in this manual by a keyword 'MODE'.

Herein, we will use the set of modes defined in the Ciao isomodes library, which is essentially the same as those used in the ISO-Prolog standard (ISO-Prolog modes).

Properties and types

Although Ciao is not a typed language, it allows writing (and using) types, as well as (more general) properties. There may be properties of the states and of the computation. Properties of the states allow expressing characteristics of the program variables during computation, like in sorted(X) (X is a sorted list). Properties of the computation allow expressing characteristics of a whole computation, like in is_det(p(X,Y)) (such calls yield only one solution). Properties are just a special form of predicates (Declaring regular types) and are identified in this manual by a keyword 'PROPERTY'.

Ciao types are regular types (Declaring regular types), which are a special form of properties themselves. They are identified in this manual by a keyword 'REGTYPE'.

Declarations

A declaration provides information to one of the Ciao environment tools. Declarations are interspersed in the code of a program. Usually the target tool is either the compiler (telling it that a predicate is dynamic, or a meta-predicate, etc.), the preprocessor (which understands declarations of properties and types, assertions, etc.), or the autodocumenter (which understands the previous declarations and also certain “comment” declarations).

A declaration has the form :- D. where D is syntactically the same as a literal. Declarations are identified in this manual by a keyword 'DECLARATION'.

In Ciao users can define (and document) new declarations. New declarations are typically useful when defining extensions to the language (which in Ciao are called packages). Such extensions are often implemented as expansions (see Extending the syntax). There are many such extensions in Ciao. The functions library, which provides fuctional syntax, is an example. The fact that in Ciao expansions are local to modules (as operators, see below) makes it possible to use a certain language extension in one module without affecting other modules.

Operators

An operator is a functor (or predicate name) which has been declared as such, thus allowing its use in a prefix, infix, or suffix fashion, instead of the standard procedure-like fashion. E.g., declaring + as an infix operator allows writing X+Y instead of '+'(X,Y) (which may still, of course, be written).

Operators in Ciao are local to the module/file where they are declared. However, some operators are standard and allowed in every program (see Defining operators). This manual documents the operator declarations in each (library) module where they are included. As with expansions, the fact that in Ciao operators are local to modules makes it possible to use a certain language extension in one module without affecting other modules.

A tour of the manual

The rest of the introductory chapters after this one provide a first “getting started” introduction for newcomers to the Ciao system. The rest of the chapters in the manual are organized into a sequence of major parts as follows:

PART I - The program development environment

This part documents the components of the basic Ciao program development environment. They include:

ciaoc:: the standalone compiler, which creates executables without having to enter the interactive top-level.
ciaosh:: (also invoked simply as ciao) is an interactive top-level shell, similar to the one found on most Prolog systems (with some enhancements).
debugger:: a Byrd box-type debugger, similar to the one found on most Prolog systems (also with some enhancements, such as source-level debugging). This is not a standalone application, but is rather included in ciaosh, as is done in other systems supporting the Prolog language. However, it is also embeddable, in the sense that it can be included as a library in executables, and activated dynamically and conditionally while such executables are running.
ciao-shell:: an interpreter/compiler for Ciao scripts (i.e., files containing Ciao code which run without needing explicit compilation).
Ciao emacs interface:: a complete program development enviroment, based on GNU emacs, with syntax coloring, direct access to all the tools described above (as well as the preprocessor and the documenter), atomatic location of errors, source-level debugging, context-sensitive access to on-line help/manuals, etc. The use of this environment is very highly recommended!

The Ciao program development environment also includes ciaopp, the preprocessor, and lpdoc, the documentation generator, which are described in separate manuals.

PART II - The Ciao basic language (engine)

This part documents the Ciao basic builtins. These predefined predicates and declarations are available in every program, unless the pure package is used (by using a :- module(_,_,[pure]). declaration or :- use_package(pure).). These predicates are contained in the engine directory within the lib library. The rest of the library predicates, including the packages that provide most of the ISO-Prolog builtins, are documented in subsequent parts.

PART III - ISO-Prolog library (iso)

This part documents the iso package which provides to Ciao programs (most of) the ISO-Prolog functionality, including the ISO-Prolog builtins not covered by the basic library.

PART IV - Classic Prolog library (classic)

This part documents some Ciao libraries which provide additional predicates and functionalities that, despite not being in the ISO standard, are present in many popular Prolog systems. This includes definite clause grammars (DCGs), “Quintus-style” internal database, list processing predicates, DEC-10 Prolog-style input/output, formatted output, dynamic loading of modules, activation of operators at run-time, etc.

PART V - Assertions, Properties, Types, Modes, Comments (assertions)

Ciao allows annotating the program code with assertions. Such assertions include type and instantiation mode declarations, but also more general properties as well as comments for autodocumentation in the literate programming style. These assertions document predicates (and modules and whole applications) and can be used by the Ciao preprocessor/compiler while debugging and optimizing the program or library, and by the Ciao documenter to build program or library reference manuals.

PART VI - Ciao library miscellanea

This part documents several Ciao libraries which provide different useful additional functionality. Such functionality includes performing operating system calls, gathering statistics from the Ciao engine, file and filename manipulation, error and exception handling, fast reading and writing of terms (marshalling and unmarshalling), file locking, issuing program and error messages, pretty-printing programs and assertions, a browser of the system libraries, additional expansion utilities, concurrent aggregates, graph visualization, etc.

PART VII - Ciao extensions

The libraries documented in this part extend the Ciao language in several different ways. The extensions include:

pure Prolog programming (well, this can be viewed more as a restriction than an extension);
feature terms or records (i.e., structures with names for each field);
parallel programming (e.g., &-Prolog style);
functional syntax;
higher-order;
global variables;
setarg and undo;
delaying predicate execution;
active modules;
breadth-first execution;
iterative deepening-based execution;
constraint logic programming;
object oriented programming.

PART VIII - Interfaces to other languages and systems

The following interfaces to/from Ciao are documented in this part:

External interface (e.g., to C).
Socket interface.
Tcl/tk interface.
Web interface (http, html, xml, etc.);
Persistent predicate databases (interface between the Ciao internal database and the external file system).
SQL-like database interface (interface between the Ciao internal database and external SQL/ODBC systems).
Java interface.
Calling emacs from Ciao.

PART IX - Abstract data types

This part includes libraries which implement some generic data structures (abstract data types) that are used frequently in programs or in the Ciao system itself.

PART X - Contributed libraries

This part includes a number of libraries which have contributed by users of the Ciao system. Over time, some of these libraries are moved to the main library directories of the system.

PART XI - Contributed standalone utilities

This is the documentation for a set of contributed standalone utilities contained in the etc_contrib directory of the Ciao distribution.

PART XII - Appendices

These appendices describe the installation of the Ciao environment on different systems and some other issues such as reporting bugs, signing up on the Ciao user's mailing list, downloading new versions, limitations, etc.

Acknowledgments

The Ciao system is a joint effort on one side of some present (Francisco Bueno, Manuel Carro, Manuel Hermenegildo, Pedro López, and Germán Puebla) and past (Daniel Cabeza, María José García de la Banda) members of the CLIP group at the School of Computer Science, Technical University of Madrid and at the IMDEA Software Institute, and on the other side of several colleagues and students that have collaborated with us over the years of its development. The following is an (inevitably incomplete) list of those that have contributed most significantly to the development of Ciao:

The Ciao engine, compiler, preprocessor, libraries, and documentation, although completely rewritten at this point, have their origins in the &-Prolog parallel Prolog engine and parallelizing compiler, developed by Manuel Hermenegildo, Kevin Greene, Kalyan Muthukumar, and Roger Nasr at MCC and later at UPM. The &-Prolog engine and low-level (WAM) compilers in turn were derived from early versions (0.5 to 0.7) of SICStus Prolog [Car88]. SICStus is an excellent, high performance Prolog system, developed by Mats Carlsson and colleagues at the Swedish Institute of Computer Science (SICS), that every user of Prolog should check out [Swe95,AAF91]. Very special thanks are due to Seif Haridi, Mats Carlsson, and colleagues at SICS for allowing the SICStus 0.5-0.7 components in &-Prolog and its successor, Ciao, to be distributed freely. Parts of the parallel abstract machine have been developed in collaboration with Gopal Gupta and Enrico Pontelli (New Mexico State University).
Many aspects of the analyzers in the Ciao preprocessor (ciaopp) have been developed in collaboration with Peter Stuckey (Melbourne U.), Kim Marriott (Monash U.), Maurice Bruynooghe, Gerda Janssens, Anne Mulkers, and Veroniek Dumortier (K.U. Leuven), and Saumya Debray (U. of Arizona). The assertion system has been developed in collaboration with Jan Maluzynski and Wlodek Drabent (Linkoping U.) and Pierre Deransart (INRIA). The core of type inference system derives from the system developed by John Gallagher [GdW94] (Bristol University) and later adapted to CLP(FD) by Pawel Pietrzak (Linkoping U.).
The constraint solvers for R and Q are derived from the code developed by Christian Holzbauer (Austrian Research Institute for AI in Vienna) [Hol94,Hol90,Hol92].
The Ciao manuals include material from the DECsystem-10 Prolog User's Manual by D.L. Bowen (editor), L. Byrd, F.C.N. Pereira, L.M. Pereira, and D.H.D. Warren [BBP81]. They also contain material from the SICStus Prolog user manuals for SICStus versions 0.5-0.7 by Mats Carlsson and Johan Widen [Car88], as well as from the Prolog ISO standard documentation [DEDC96].
Ciao is designed to be highly extendable in a modular way. Many of the libraries distributed with Ciao have been developed by other people all of which is impossible to mention here. Individual author names are included in the documentation of each library and appear in the indices.
The development of the Ciao system has been supported in part by European research projects PEPMA, ACCLAIM, PARFORCE, DISCIPL, AMOS, ASAP, MOBIUS, and SCUBE; by MICYT projects IPL-D, ELLA, EDIPIA, CUBICO, MERIT, and DOVES; and by CM projects PROMESAS and PROMETIDOS.

If you feel you have contributed to the development of Ciao and we have forgotten to add your name to this list or to the acknowledgements given in the different chapters and indices, please let us know and we will be glad to give proper credits.