   *Ciao* is a _public domain_, _next generation_ multi-paradigm
programming environment with a unique set of features:

   * Ciao offers a complete Prolog system, supporting _ISO-Prolog_,
     but its novel modular design allows both _restricting_ and
     _extending_ the language. As a result, it allows working with
     _fully declarative subsets_ of Prolog and also to _extend_ these
     subsets (or ISO-Prolog) both syntactically and semantically.
     Most importantly, these restrictions and extensions can be
     activated separately on each program module so that several
     extensions can coexist in the same application for different
     modules.

   * Ciao also supports (through such extensions) programming with
     functions, higher-order (with predicate abstractions),
     constraints, and objects, as well as feature terms (records),
     persistence, several control rules (breadth-first search,
     iterative deepening, ...), concurrency (threads/engines), a good
     base for distributed execution (agents), and parallel execution.
     Libraries also support WWW programming, sockets, external
     interfaces (C, Java, TclTk, relational databases, etc.), etc.

   * *Ciao* offers support for _programming in the large_ with a
     robust module/object system, module-based separate/incremental
     compilation (automatically -no need for makefiles), an assertion
     language for declaring (_optional_) program properties
     (including types and modes, but also determinacy, non-failure,
     cost, etc.), automatic static inference and static/dynamic
     checking of such assertions, etc.

   * *Ciao* also offers support for _programming in the small_
     producing small executables (including only those builtins used
     by the program) and support for writing scripts in Prolog.

   * The *Ciao* programming environment includes a classical
     top-level and a rich emacs interface with an embeddable
     source-level debugger and a number of execution visualization
     tools.

   * The *Ciao* compiler (which can be run outside the top level
     shell) generates several forms of architecture-independent and
     stand-alone executables, which run with speed, efficiency and
     executable size which are very competitive with other commercial
     and academic Prolog/CLP systems. Library modules can be compiled
     into compact bytecode or C source files, and linked statically,
     dynamically, or autoloaded.

   * The novel modular design of Ciao enables, in addition to modular
     program development, effective global program analysis and
     static debugging and optimization via source to source program
     transformation. These tasks are performed by the *Ciao
     preprocessor* ( `ciaopp', distributed separately).

   * The *Ciao* programming environment also includes `lpdoc', an
     automatic documentation generator for LP/CLP programs. It
     processes Prolog files adorned with (*Ciao*) assertions and
     machine-readable comments and 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.

   *Ciao* is distributed under the GNU Library General Public License
(LGPL).

   Copyright (C) F. Bueno, D. Cabeza, M. Carro, M. Hermenegildo, P.
Lo'pez, and G. Puebla

   This document may be freely read, stored, reproduced,
disseminated, translated or quoted by any means and on any medium
provided the following conditions are met:

  1. Every reader or user of this document acknowledges that is aware
     that no guarantee is given regarding its contents, on any
     account, and specifically concerning veracity, accuracy and
     fitness for any purpose.

  2. No modification is made other than cosmetic, change of
     representation format, translation, correction of obvious
     syntactic errors, or as permitted by the clauses below.

  3. Comments and other additions may be inserted, provided they
     clearly appear as such; translations or fragments must clearly
     refer to an original complete version, preferably one that is
     easily accessed whenever possible.

  4. Translations, comments and other additions or modifications must
     be dated and their author(s) must be identifiable (possibly via
     an alias).

  5. This licence is preserved and applies to the whole document with
     modifications and additions (except for brief quotes),
     independently of the representation format.

  6. Any reference to the "official version", "original version" or
     "how to obtain original versions" of the document is preserved
     verbatim. Any copyright notice in the document is preserved
     verbatim. Also, the title and author(s) of the original document
     should be clearly mentioned as such.

  7. In the case of translations, verbatim sentences mentioned in
     (6.) are preserved in the language of the original document
     accompanied by verbatim translations to the language of the
     traslated document. All translations state clearly that the
     author is not responsible for the translated work. This license
     is included, at least in the language in which it is referenced
     in the original version.

  8. Whatever the mode of storage, reproduction or dissemination,
     anyone able to access a digitized version of this document must
     be able to make a digitized copy in a format directly usable,
     and if possible editable, according to accepted, and publicly
     documented, public standards.

  9. Redistributing this document to a third party requires
     simultaneous redistribution of this licence, without
     modification, and in particular without any further condition or
     restriction, expressed or implied, related or not to this
     redistribution. In particular, in case of inclusion in a
     database or collection, the owner or the manager of the database
     or the collection renounces any right related to this inclusion
     and concerning the possible uses of the document after
     extraction from the database or the collection, whether alone or
     in relation with other documents.

   Any incompatibility of the above clauses with legal, contractual
or judiciary decisions or constraints implies a corresponding
limitation of reading, usage, or redistribution rights for this
document, verbatim or modified.

The Ciao Prolog System
**********************

   This documentation corresponds to version 1.10#8 (2007/1/28,
17:30:3 CEST).

Summary
*******

*Ciao* is a _public domain_, _next generation_ multi-paradigm
programming environment with a unique set of features:

   * Ciao offers a complete Prolog system, supporting _ISO-Prolog_,
     but its novel modular design allows both _restricting_ and
     _extending_ the language. As a result, it allows working with
     _fully declarative subsets_ of Prolog and also to _extend_ these
     subsets (or ISO-Prolog) both syntactically and semantically.
     Most importantly, these restrictions and extensions can be
     activated separately on each program module so that several
     extensions can coexist in the same application for different
     modules.

   * Ciao also supports (through such extensions) programming with
     functions, higher-order (with predicate abstractions),
     constraints, and objects, as well as feature terms (records),
     persistence, several control rules (breadth-first search,
     iterative deepening, ...), concurrency (threads/engines), a good
     base for distributed execution (agents), and parallel execution.
     Libraries also support WWW programming, sockets, external
     interfaces (C, Java, TclTk, relational databases, etc.), etc.

   * *Ciao* offers support for _programming in the large_ with a
     robust module/object system, module-based separate/incremental
     compilation (automatically -no need for makefiles), an assertion
     language for declaring (_optional_) program properties
     (including types and modes, but also determinacy, non-failure,
     cost, etc.), automatic static inference and static/dynamic
     checking of such assertions, etc.

   * *Ciao* also offers support for _programming in the small_
     producing small executables (including only those builtins used
     by the program) and support for writing scripts in Prolog.

   * The *Ciao* programming environment includes a classical
     top-level and a rich emacs interface with an embeddable
     source-level debugger and a number of execution visualization
     tools.

   * The *Ciao* compiler (which can be run outside the top level
     shell) generates several forms of architecture-independent and
     stand-alone executables, which run with speed, efficiency and
     executable size which are very competitive with other commercial
     and academic Prolog/CLP systems. Library modules can be compiled
     into compact bytecode or C source files, and linked statically,
     dynamically, or autoloaded.

   * The novel modular design of Ciao enables, in addition to modular
     program development, effective global program analysis and
     static debugging and optimization via source to source program
     transformation. These tasks are performed by the *Ciao
     preprocessor* ( `ciaopp', distributed separately).

   * The *Ciao* programming environment also includes `lpdoc', an
     automatic documentation generator for LP/CLP programs. It
     processes Prolog files adorned with (*Ciao*) assertions and
     machine-readable comments and 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.

   *Ciao* is distributed under the GNU Library General Public License
(LGPL).

1 Introduction
**************

1.1 About this manual
=====================

This is the _Reference Manual_ for the Ciao Prolog development
system. It contains basic information on how to install Ciao Prolog
and how to write, debug, and run Ciao Prolog 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 Prolog files (and files in 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.

1.2 About the Ciao Prolog 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 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 Prolog (`ciao-shell'), a 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'
[BdlBH99,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
Prolog 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 Prolog. 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 Prolog 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 [CH99], and modular
global program analysis, debugging and optimization [PH99], based on
a rich assertion language [see PART V - Annotated Prolog library
(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].

1.3 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
the standards.

1.4 About the name of the System
================================

After reading the previous sections the sharp reader may have already
seen the logic behind the 'Ciao Prolog' name. 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). 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 systems) that it does so while keeping full Prolog
compatibility when needed.

1.5 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 Prolog system. Reference manual},
       institution =  {School of Computer Science,
                       Technical University of Madrid (UPM)},
       year =         1997,
       month =        {August},
       number =       {{CLIP}3/97.1},
       note =         {Available from http://www.clip.dia.fi.upm.es/}
     }

1.6 Syntax terminology and notational conventions
=================================================

This manual is not meant to be an introduction to the Prolog
language. The reader is referred to standard textbooks on Prolog such
as [SS86,CM81,Apt97,Hog84]. 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.

1.6.1 Predicates and their components
-------------------------------------

In Prolog, 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.

   Prolog instructions are expressions made up of control constructs
(see 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 Prolog program is a sequence of predicate definitions.

1.6.2 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 a Prolog
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.

1.6.3 Predicate specs
---------------------

Predicates in Prolog 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.)

1.6.4 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_ (see 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 (see ISO-Prolog modes).

1.6.5 Properties and types
--------------------------

Although Ciao Prolog 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
(see Declaring regular types) and are identified in this manual
by a keyword 'PROPERTY'.

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

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

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

1.7 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:

1.7.1 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.pl:
     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 Prolog
     systems. 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 _Prolog scripts_ (i.e., files
     containing Prolog code which run without needing explicit
     compilation).

ciao.el:
     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.

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

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

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

1.7.5 PART V - Annotated Prolog library (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 in the style of the
_literate programming_. 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 the program or library
reference manual.

1.7.6 PART VI - Ciao Prolog library miscellanea
-----------------------------------------------

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

1.7.7 PART VII - Ciao Prolog 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 library;

   * global variables;

   * `setarg' and `undo';

   * delaying predicate execution;

   * active modules;

   * breadth-first execution;

   * iterative deepening-based execution;

   * constraint logic programming;

   * object oriented programming.

1.7.8 PART VIII - Interfaces to other languages and systems
-----------------------------------------------------------

The following interfaces to/from Ciao Prolog 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 Prolog
     internal database and the external file system).

   * SQL-like database interface (interface between the Prolog
     internal database and external SQL/ODBC systems).

   * Java interface.

   * Calling emacs from Prolog.

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

1.7.10 PART X - Miscellaneous standalone utilities
--------------------------------------------------

This is the documentation for a set of miscellaneous standalone
utilities contained in the `etc' directory of the Ciao distribution.

1.7.11 PART XI - 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.

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

1.8 Acknowledgments
===================

The Ciao system is a joint effort on one side of the present ( _Francisco
Bueno_, _Daniel Cabeza_, _Manuel Carro_, _Manuel Hermenegildo_, _Pedro
Lo'pez_, and _Germa'n Puebla_) and past ( _Mar'a Jose' Garc'a de la
Banda_) members of the _CLIP group_ at the School of Computer Science, _Technical
University of Madrid_ , 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 to the development of Ciao:

   * The _Ciao engine_, compiler, 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 ACCLAIM, PARFORCE, DISCIPL, AMOS, and ASAP
     and by MICYT projects ELLA, EDIPIA, and CUBICO.

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

1.9 Version/Change Log (`ciao')
===============================

*Version 1.10 (2004/7/29, 16:12:3 CEST)*
        * Classical prolog mode as default behavior.

        * Emacs-based environment improved.
             * Improved emacs inferior (interaction) mode for Ciao
               and CiaoPP.

             * Xemacs compatibility improved (thanks to A. Rigo).

             * New icons and modifications in the environment for the
               preprocessor.

             * Icons now installed in a separate dir.

             * Compatibility with newer versions of `Cygwin'.

             * Changes to programming environment:
                  * Double-click startup of programming environment.

                  * Reorganized menus: help and customization grouped
                    in separate menus.

                  * Error location extended.

                  * Automatic/Manual location of errors produced when
                    running Ciao tools now customizable.

                  * Presentation of CiaoPP preprocessor output
                    improved.

             * Faces and coloring improved:
                  * Faces for syntax-based highlighting more
                    customizable.

                  * Syntax-based coloring greatly improved.
                    Literal-level assertions also correctly colored
                    now.

                  * Syntax-based coloring now also working on ASCII
                    terminals (for newer versions of emacs).

                  * Listing user-defined directives allowed to be
                    colored in special face.

                  * Syntax errors now colored also in inferior
                    buffers.

                  * Customizable faces now appear in the
                    documentation.

                  * Added new tool bar button (and binding) to
                    refontify block/buffer.

                  * Error marks now cleared automatically also when
                    generating docs.

                  * Added some fixes to hooks in lpdoc buffer.

        * Bug fixes in compiler.
             * Replication of clauses in some cases (thanks to S.
               Craig).

        * Improvements related to supported platforms
             * Compilation and installation in different palatforms
               have been improved.

             * New Mac OS X kernels supported.

        * Improvement and bugs fixes in the engine:
             * Got rid of several segmentation violation problems.

             * Number of significant decimal digits to be printed now
               computed accurately.

             * Added support to test conversion of a Ciao integer
               into a machine int.

             * Unbound length atoms now always working.

             * C interface .h files reachable through a more standard
               location (thanks to R. Bagnara).

             * Compatibility with newer versions of gcc.

        * New libraries and utilities added to the system:
             * Factsdb: facts defined in external files can now be
               automatically cached on-demand.

             * Symfnames: File aliasing to internal streams added.

        * New libraries added (in beta state):
             * fd: clp(FD)

             * xml_path: XML querying and transformation to Prolog.

             * xdr_handle: XDR schema to HTML forms utility.

             * ddlist: Two-way traversal list library.

             * gnuplot: Interface to GnuPlot.

             * time_analyzer: Execution time profiling.

        * Some libraries greatly improved:
             * Interface to Tcl/Tk very improved.
                  * Corrected many bugs in both interaction Prolog to
                    Tcl/Tk and viceversa.

                  * Execution of Prolog goals from TclTk revamped.

                  * Treatment of Tcl events corrected.

                  * Predicate `tcl_eval/3' now allows the execution
                    of Tcl procedures running multiple Prolog goals.

                  * Documentation heavily reworked.

                  * Fixed unification of prolog goals run from the
                    Tcl side.

             * Pillow library improved in many senses.
                  * HTTP media type parameter values returned are
                    always strings now, not atoms.

                  * Changed verbatim() pillow term so that newlines
                    are translated to <br>.

                  * Changed management of cookies so that special
                    characters in values are correctly handled.

                  * Added predicate `url_query_values/2', reversible.
                    Predicate `url_query/2' now obsolete.

                  * Now attribute values in tags are escaped to
                    handle values which have double quotes.

                  * Improved `get_form_input/1' and `url_query/2' so
                    that names of parameters having unusual
                    characters are always correctly handled.

             * Fixed bug in tokenizer regarding non-terminated single
               or multiple-line comments. When the last line of a
               file has a single-line comment and does not end in a
               newline, it is accepted as correct. When an
               open-comment /* sequence is not terminated in a file,
               a syntax error exception is thrown.

        * Other libraries improved:
             * Added native_props to assertions package and included `nonground/1'.

             * In atom2terms, changed interpretation of double quoted
               strings so that they are not parsed to terms.

             * Control on exceptions improved.

             * Added `native/1,2' to basic_props.

             * Davinci error processing improved.

             * Foreign predicates are now automatically declared as
               implementation-defined.

             * In lists, added `cross_product/2' to compute the
               cartesian product of a list of lists. Also added `delete_non_ground/3',
               enabling deletion of nonground terms from a list.

             * In llists added `transpose/2' and changed `append/2'
               implementation with a much more efficient code.

             * The make library has been improved.

             * In persdb, added `pretractall_fact/1' and `retractall_fact/1'
               as persdb native capabilities.

             * Improved behavior with user environment from persdb.

             * In persdb, added support for `persistent_dir/4', which
               includes arguments to specify permission modes for
               persistent directory and files.

             * Some minor updates in persdb_sql.

             * Added treatment of operators and module:pred calls to
               pretty-printer.

             * Updated report of read of syntax errors.

             * File locking capabilities included in `open/3'.

             * Several improvements in library system.

             * New input/output facilities added to sockets.

             * Added `most_specific_generalization/3' and `most_general_instance/3'
               to terms_check.

             * Added `sort_dict/2' to library vndict.

             * The xref library now treats also empty references.

        * Miscellaneous updates:
             * Extended documentation in libraries actmods, arrays,
               foreign_interface, javall, persdb_mysql, prolog_sys,
               old_database, and terms_vars.

*Version 1.9 (2002/5/16, 23:17:34 CEST)*
     New development version after stable 1.8p0 (MCL, DCG)

*Version 1.8 (2002/5/16, 21:20:27 CEST)*
        * Improvements related to supported platforms:
             * Support for Mac OS X 10.1, based on the Darwin kernel.

             * Initial support for compilation on Linux for Power PC
               (contributed by _Paulo Moura_).

             * Workaround for incorrect C compilation while using
               newer (> 2.95) gcc compilers.

             * .bat files generated in Windows.

        * Changes in compiler behavior and user interface:
             * Corrected a bug which caused wrong code generation in
               some cases.

             * Changed execution of initialization directives. Now
               the initialization of a module/file never runs before
               the initializations of the modules from which the
               module/file imports (excluding circular dependences).

             * The engine is more intelligent when looking for an
               engine to execute bytecode; this caters for a variety
               of situations when setting explicitly the CIAOLIB
               environment variable.

             * Fixed bugs in the toplevel: behaviour of `module:main'
               calls and initialization of a module (now happens
               after related modules are loaded).

             * Layout char not needed any more to end Prolog files.

             * Syntax errors now disable .itf creation, so that they
               show next time the code is used without change.

             * Redefinition warnings now issued only when an
               unqualified call is seen.

             * Context menu in Windows can now load a file into the
               toplevel.

             * Updated Windows installation in order to run CGI
               executables under Windows: a new information item is
               added to the registry.

             * Added new directories found in recent Linux
               distributions to INFOPATH.

             * Emacs-based environment and debugger improved:
                  * Fixed some errors in embedded debugger.

                  * Errors located immediataly after code loading.

                  * Improved ciao-check-types-modes (preprocessor
                    progress now visible).

                  * Fixed loading regions repeatedly (no more
                    predicate redefinition warnings).

                  * Added entries in `ciaopp' menu to set verbosity
                    of output.

                  * Fixed some additional xemacs compatibility issues
                    (related to searches).

                  * Errors reported by inferior processes are now
                    explored in forward order (i.e., the first error
                    rewported is the first one highlighted). Improved
                    tracking of errors.

                  * Specific tool bar now available, with icons for
                    main fuctions (works from emacs 21.1 on). Also,
                    other minor adaptations for working with emacs
                    21.1 and later.

                  * Debugger faces are now locally defined (and
                    better customization). This also improves
                    comtability with xemacs (which has different
                    faces).

                  * Direct access to a common use of the preprocessor
                    (checking modes/types and locating errors) from
                    toolbar.

                  * Inferior modes for Ciao and CiaoPP improved:
                    contextual help turned on by default.

                  * Fixes to set-query. Also, previous query now
                    appears in prompt.

                  * Improved behaviour of stored query.

                  * Improved behaviour of recentering, finding
                    errors, etc.

                  * Wait for prompt has better termination
                    characteristics.

                  * Added new interactive entry points (M-x): ciao,
                    prolog, ciaopp.

                  * Better tracking of last inferior buffer used.

                  * Miscellanous bugs removed; some colors changed to
                    adapt to different Emacs versions.

                  * Fixed some remaining incompatibilities with
                    xemacs.

                  * `:- doc' now also supported and highlighted.

                  * Eliminated need for calendar.el

                  * Added some missing library directives to fontlock
                    list, organized this better.

        * New libraries added to the system:
             * hiord: new library which needs to be loaded in order
               to use higher-order call/N and P(X) syntax. Improved
               model for predicate abstractions.

             * fuzzy: allows representing fuzzy information in the
               form or Prolog rules.

             * use_url: allows loading a module remotely by using a
               WWW address of the module source code

             * andorra: alternative search method where goals which
               become deterministic at run time are executed before
               others.

             * iterative deepening (id): alternative search method
               which makes a depth-first search until a predetermined
               depth is reached. Complete but in general cheaper than
               breadth first.

             * det_hook: allows making actions when a deterministic
               situation is reached.

             * ProVRML: read VRML code and translate it into Prolog
               terms, and the other way around.

             * io_alias_redirection: change where stdin/stdout/stderr
               point to from within Ciao Prolog programs.

             * tcl_tk: an interface to Tcl/Tk programs.

             * tcl_tk_obj: object-based interface to Tcl/Tk graphical
               objects.

             * CiaoPP: options to interface with the CiaoPP Prolog
               preprocessor.

        * Some libraries greatly improved:
             * WebDB: utilities to create WWW-based database
               interfaces.

             * Improved java interface implementation (this forced
               renaming some interface primitives).

             * User-transparent persistent predicate database
               revamped:

                  * Implemented passerta_fact/1 (asserta_fact/1).

                  * Now it is never necessary to explicitly call
                    init_persdb, a call to initialize_db is only
                    needed after dynamically defining facts of
                    persistent_dir/2. Thus, pcurrent_fact/1 predicate
                    eliminated.

                  * Facts of persistent predicates included in the
                    program code are now included in the persistent
                    database when it is created. They are ignored in
                    successive executions.

                  * Files where persistent predicates reside are now
                    created inside a directory named as the module
                    where the persistent predicates are defined, and
                    are named as F_A* for predicate F/A.

                  * Now there are two packages: persdb and
                    'persdb/ll' (for low level). In the first, the
                    standard builtins asserta_fact/1, assertz_fact/1,
                    and retract_fact/1 are replaced by new versions
                    which handle persistent data predicates, behaving
                    as usual for normal data predicates. In the
                    second package, predicates with names starting
                    with 'p' are defined, so that there is not
                    overhead in calling the standard builtins.

                  * Needed declarations for persistent_dir/2 are now
                    included in the packages.

             * SQL now works with mysql.

             * system: expanded to contain more predicates which act
               as interface to the underlying system / operating
               system.

        * Other libraries improved:
             * xref: creates cross-references among Prolog files.

             * concurrency: new predicates to create new concurrent
               predicates on-the-fly.

             * sockets: bugs corrected.

             * objects: concurrent facts now properly recognized.

             * fast read/write: bugs corrected.

             * Added 'webbased' protocol for active modules:
               publication of active module address can now be made
               through WWW.

             * Predicates in library(dynmods) moved to
               library(compiler).

             * Expansion and meta predicates improved.

             * Pretty printing.

             * Assertion processing.

             * Module-qualified function calls expansion improved.

             * Module expansion calls goal expansion even at runtime.

        * Updates to builtins (there are a few more; these are the
          most relevant):
             * Added a prolog_flag to retrieve the version and patch.

             * current_predicate/1 in library(dynamic) now enumerates
               non-engine modules, prolog_sys:current_predicate/2 no
               longer exists.

             * exec/* bug fixed.

             * srandom/1 bug fixed.

        * Updates for C interface:
             * Fixed bugs in already existing code.

             * Added support for creation and traversing of Prolog
               data structures from C predicates.

             * Added support for raising Prolog exceptions from C
               predicates.

             * Preliminary support for calling Prolog from C.

        * Miscellaneous updates:
             * Installation made more robust.

             * Some pending documentation added.

             * 'ciao' script now adds (locally) to path the place
               where it has been installed, so that other programs
               can be located without being explicitly in the $PATH.

             * Loading programs is somewhat faster now.

             * Some improvement in printing path names in Windows.

*Version 1.7 (2000/7/12, 19:1:20 CEST)*
     Development version following even 1.6 distribution.

*Version 1.6 (2000/7/12, 18:55:50 CEST)*
        * Source-level debugger in emacs, breakpts.

        * Emacs environment improved, added menus for Ciaopp and
          LPDoc.

        * Debugger embeddable in executables.

        * Stand-alone executables available for UNIX-like operating
          systems.

        * Many improvements to emacs interface.

        * Menu-based interface to autodocumenter.

        * Threads now available in Win32.

        * Many improvements to threads.

        * Modular clp(R) / clp(Q).

        * Libraries implementing And-fair breadth-first and iterative
          deepening included.

        * Improved syntax for predicate abstractions.

        * Library of higher-order list predicates.

        * Better code expansion facilities (macros).

        * New delay predicates (when/2).

        * Compressed object code/executables on demand.

        * The size of atoms is now unbound.

        * Fast creation of new unique atoms.

        * Number of clauses/predicates essentially unbound.

        * Delayed goals with freeze restored.

        * Faster compilation and startup.

        * Much faster fast write/read.

        * Improved documentation.

        * Other new libraries.

        * Improved installation/deinstallation on all platforms.

        * Many improvements to autodocumenter.

        * Many bug fixes in libraries and engine.

*Version 1.5 (1999/11/29, 16:16:23 MEST)*
     Development version following even 1.4 distribution.

*Version 1.4 (1999/11/27, 19:0:0 MEST)*
        * Documentation greatly improved.

        * Automatic (re)compilation of foreign files.

        * Concurrency primitives revamped; restored &Prolog-like
          multiengine capability.

        * Windows installation and overall operation greatly improved.

        * New version of O'Ciao class/object library, with improved
          performance.

        * Added support for "predicate abstractions" in call/N.

        * Implemented reexportation through reexport declarations.

        * Changed precedence of importations, last one is now higher.

        * Modules can now implicitly export all predicates.

        * Many minor bugs fixed.

*Version 1.3 (1999/6/16, 17:5:58 MEST)*
     Development version following even 1.2 distribution.

*Version 1.2 (1999/6/14, 16:54:55 MEST)*
     Temporary version distributed locally for extensive testing of
     reexportation and other 1.3 features.

*Version 1.1 (1999/6/4, 13:30:37 MEST)*
     Development version following even 1.0 distribution.

*Version 1.0 (1999/6/4, 13:27:42 MEST)*
        * Added Tcl/Tk interface library to distribution.

        * Added push_prolog_flag/2 and pop_prolog_flag/1
          declarations/builtins.

        * Filename processing in Windows improved.

        * Added redefining/1 declaration to avoid redefining warnings.

        * Changed syntax/1 declaration to use_package/1.

        * Added add_clause_trans/1 declaration.

        * Changed format of .itf files such that a '+' stands for all
          the standard imports from engine, which are included in
          c_itf source internally (from engine(builtin_exports)).
          Further changes in itf data handling, so that once an .itf
          file is read in a session, the file is cached and next time
          it is needed no access to the file system is required.

        * Many bugs fixed.

*Version 0.9 (1999/3/10, 17:3:49 CET)*
        * Test version before 1.0 release. Many bugs fixed.

*Version 0.8 (1998/10/27, 13:12:36 MET)*
        * Changed compiler so that only one pass is done, eliminated
          `.dep' files.

        * New concurrency primitives.

        * Changed assertion comment operator to #.

        * Implemented higher-order with call/N.

        * Integrated SQL-interface to external databases with
          persistent predicate concept.

        * First implementation of object oriented programming package.

        * Some bugs fixed.

*Version 0.7 (1998/9/15, 12:12:33 MEST)*
        * Improved debugger capabilities and made easier to use.

        * Simplified assertion format.

        * New arithmetic functions added, which complete all ISO
          functions.

        * Some bugs fixed.

*Version 0.6 (1998/7/16, 21:12:7 MET DST)*
        * Defining other path aliases (in addition to 'library')
          which can be loaded dynamically in executables is now
          possible.

        * Added the posibility to define multifile predicates in the
          shell.

        * Added the posibility to define dynamic predicates
          dynamically.

        * Added addmodule meta-argument type.

        * Implemented persistent data predicates.

        * New version of PiLLoW WWW library (XML, templates, etc.).

        * Ported active modules from "distributed Ciao" (independent
          development version of Ciao).

        * Implemented lazy loading in executables.

        * Modularized engine(builtin).

        * Some bugs fixed.

*Version 0.5 (1998/3/23)*
        * First Windows version.

        * Integrated debugger in toplevel.

        * Implemented DCG's as (Ciao-style) expansions.

        * Builtins renamed to match ISO-Prolog.

        * Made ISO the default syntax/package.

*Version 0.4 (1998/2/24)*
        * First version with the new Ciao emacs mode.

        * Full integration of concurrent engine and compiler/library.

        * Added new_declaration/1 directive.

        * Added modular syntax enhancements.

        * Shell script interpreter separated from toplevel shell.

        * Added new compilation warnings.

*Version 0.3 (1997/8/20)*
        * Ciao builtins modularized.

        * New prolog flags can be defined by libraries.

        * Standalone comand-line compiler available, with automatic
          "make".

        * Added assertions and regular types.

        * First version using the automatic documentation generator.

*Version 0.2 (1997/4/16)*
        * First module system implemented.

        * Implemented exceptions using catch/3 and throw/1.

        * Added functional & record syntax.

        * Added modular sentence, term, and goal translations.

        * Implemented attributed variables.

        * First CLPQ/CLPR implementation.

        * Added the posibility of linking external .so files.

        * Changes in syntax to allow `P(X)' and `"string"||L'.

        * Changed to be more similar to ISO-Prolog.

        * Implemented Prolog shell scripts.

        * Implemented data predicates.

*Version 0.1 (1997/2/13)*
     First fully integrated, standalone Ciao distribution. Based on
     integrating into an evolution of the &-Prolog
     engine/libraries/preprocessor [Her86,HG91] many functionalities
     from several previous independent development versions of Ciao
     [HC93,HC94,HCC95,Bue95,CLI95,HBdlBP95,HBC96,CHV96b,HBC99].

2 Getting started on Un*x-like machines
***************************************

*Author(s):* M.Hermenegildo.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.7#133 (2001/11/1, 16:34:6 CET)

   This part guides you through some very basic first steps with Ciao
on a Un*x-like system. It assumes that Ciao is already installed
correctly on your Un*x system. If this is not the case, then follow
the instructions in Installing Ciao from the source distribution
first.

   We start with by describing the basics of using Ciao from a normal
command shell such as `sh/bash', `csh/tcsh', etc. We strongly
recommend reading also An introduction to the Ciao emacs environment (Un*x)
for the basics on using Ciao under `emacs',
which is a much simpler and much more powerful way of developing Ciao
programs, and has the advantage of offering an almost identical
environment under Un*x and Windows.

2.1 Testing your Ciao Un*x installation
=======================================

It is a good idea to start by performing some tests to check that
Ciao is installed correctly on your system (these are the same tests
that you are instructed to do during installation, so you can
obviously skip them if you have done them already at that time). If
any of these tests do not succeed either your environment variables
are not set properly (see Un*x user setup for how to fix
this):

   * Typing `ciao' (or `ciaosh') should start the typical Prolog
     top-level shell.

   * In the top-level shell, Prolog library modules should load
     correctly. Type for example `use_module(library(dec10_io))' -you
     should get back a prompt with no errors reported.

   * To exit the top level shell, type `halt.' as usual, or <^D>.

   * Typing `ciaoc' should produce the help message from the Ciao standalone
     compiler.

   * Typing `ciao-shell' should produce a message saying that no code
     was found. This is a Ciao application which can be used to write scripts
     written in Prolog, i.e., files which do not need any explicit
     compilation to be run.

Also, the following documentation-related actions should work:

   * If the `info' program is installed, typing `info' should produce
     a list of manuals which _should include Ciao manual(s) in a
     separate area_ (you may need to log out and back in so that your
     shell variables are reinitialized for this to work).

   * Opening with a WWW browser (e.g., `netscape') the directory or
     `URL' corresponding to the `DOCROOT' setting should show a
     series of Ciao-related manuals. Note that _style sheets_ should
     be activated for correct formatting of the manual.

   * Typing `man ciao' should produce a man page with some very basic
     general information on Ciao (and pointing to the on-line
     manuals).

   * The `DOCROOT' directory should contain the manual also in the
     other formats such as `postscript' or `pdf' which specially
     useful for printing. See Printing manuals (Un*x) for
     instructions.

2.2 Un*x user setup
===================

If the tests above have succeeded, the system is probably installed
correctly and your environment variables have been set already. In
that case you can skip to the next section.

   Otherwise, if you have not already done so, make the following
modifications in your startup scripts, so that these files are used
(`<LIBROOT>' must be replaced with the appropriate value, i.e., where
the Ciao library is installed):

   * For users a _csh-compatible shell_ ( `csh', `tcsh', ...), add to `~/.cshrc':

                  if ( -e <LIBROOT>/ciao/DOTcshrc ) then
                     source <LIBROOT>/ciao/DOTcshrc
                  endif

     `Mac OS X' users should add (or modify) the `path' file in the
     directory `~/Library/init/tcsh', adding the lines shown above.
     *Note:* while this is recognized by the terminal shell, and
     therefore by the text-mode Emacs which comes with Mac OS X, the
     Aqua native Emacs 21 does not recognize that initialization. It
     is thus necessary, at this moment, to set manually the Ciao
     shell (ciaosh) and Ciao library location by hand. This can be
     done from the Ciao menu within Emacs after a Ciao Prolog file
     has been loaded. We suppose that the reason is that Mac OS X
     does not actually consult the per-user initialization files on
     startup. It should also be possible to put the right
     initializations in the .emacs file using the `setenv' function
     of Emacs-lisp, as in

          (setenv "CIAOLIB" "<LIBROOT>/ciao")

     The same can be done for the rest of the variables initialized
     in `<LIBROOT>/ciao/DOTcshrc'

   * For users of an _sh-compatible shell_ ( `sh', `bash', ...), add
     to `~/.profile':

                  if [ -f <LIBROOT>/ciao/DOTprofile ]; then
                     . <LIBROOT>/ciao/DOTprofile
                  fi

     This will set up things so that the Ciao executables are found
     and you can access the Ciao system manuals using the `info'
     command. Note that, depending on your shell, _you may have to
     log out and back in_ for the changes to take effect.

   * Also, if you use `emacs' (highly recommended) add this line to
     your `~/.emacs' file:

                  (load-file "<LIBROOT>/ciao/DOTemacs.el")

   If after following these steps things do not work properly, then
the installation was probably not completed properly and you may want
to try reinstalling the system.

2.3 Using Ciao from a Un*x command shell
========================================

2.3.1 Starting/exiting the top-level shell (Un*x)
-------------------------------------------------

The basic methods for starting/exiting the top-level shell have been
discussed above. If upon typing `ciao' you get a "command not found"
error or you get a longer message from Ciao before starting, it means
that either Ciao was not installed correctly or you environment
variables are not set up properly. Follow the instructions on the
message printed by Ciao or refer to the installation instructions
regarding user-setup for details.

2.3.2 Getting help (Un*x)
-------------------------

The basic methods for accessing the manual on-line have also been
discussed above. Use the table of contents and the indices of
_predicates_, _libraries_, _concepts_, etc. to find what you are
looking for.  Context-sensitive help is available within the `emacs'
environment (see below).

2.3.3 Compiling and running programs (Un*x)
-------------------------------------------

Once the shell is started, you can compile and execute Prolog modules
inside the interactive top-level shell in the standard way. E.g.,
type `use_module(_file_).', `use_module(library(_file_)).' for
library modules, `ensure_loaded(_file_).' for files which are not
modules, and `use_package(_file_).' for library packages (these are
syntactic/semantic packages that extend the Ciao Prolog language in
many different ways). Note that the use of `compile/1' and `consult/1'
is discouraged in Ciao.

   For example, you may want to type `use_package(iso)' to ensure
Ciao has loaded all the ISO builtins (whether this is done by default
or not depends on your `.ciaorc' file). Do not worry about any
"module already in executable" messages -these are normal and simply
mean that a certain module is already pre-loaded in the top-level
shell. At this point, typing `write(hello).' should work.

   Note that some predicates that may be built-ins in other Prologs
are available through libraries in Ciao. This facilitates making
small executables.

   To change the working directory to, say, the `examples' directory
in the Ciao root directory, first do:

           ?- use_module(library(system)).

(loading the `system' library makes a number of system-related
predicates such as `cd/1' accessible) and then:

           ?- cd('$/examples').

(in Ciao the sequence `$/' _at the beginning of a path name_ is
replaced by the path of the Ciao root directory).

   For more information see The interactive top-level shell.

2.3.4 Generating executables (Un*x)
-----------------------------------

Executables can be generated from the top-level shell (using `make_exec/2')
or using the standalone compiler ( `ciaoc'). To be able to make an
executable, the file should define the predicate `main/1' (or `main/0'),
which will be called upon startup (see the corresponding manual
section for details). In its simplest use, given a top-level
_foo_`.pl' file for an application, the compilation process produces
an executable `foo', automatically detecting which other files used
by `foo.pl' need recompilation.

For example, within the `examples' directory, you can type:

         ?- make_exec(hw,_).

which should produce an executable. Typing `hw' in a shell (or
double-clicking on the icon from a graphical window) should execute
it.

   For more information see The interactive top-level shell
and The stand-alone command-line compiler.

2.3.5 Running Ciao scripts (Un*x)
---------------------------------

Ciao allows writing Prolog scripts. These are files containing Prolog
source but which get executed without having to explicitly compile
them (in the same way as, e.g., `.bat' files or programs in scripting
languages). As an example, you can run the file `hw' in the `examples'
directory of the Ciao distribution and look at the source with an
editor. You can try changing the `Hello world' message and running
the program again (no need to recompile!).

   As you can see, the file should define the predicate `main/1' (not `main/0'),
which will be called upon startup. The two header lines are necessary
in Un*x in. In Windows you can leave them in or you can take them
out, but you need to rename the script to `hw.pls'. Leaving the lines
in has the advantage that the script will also work in Un*x without
any change.

   For more information see The script interpreter.

2.3.6 The Ciao initialization file (Un*x)
-----------------------------------------

The Ciao toplevel can be made to execute upon startup a number of
commands (such as, e.g., loading certain files or setting certain
Prolog flags) contained in an initialization file. This file should
be called `.ciaorc' and placed in your _home_ directory (e.g., `~',
the same in which the `.emacs' file is put). You may need to set the
environment variable `HOME' to the path of this directory for the
Ciao toplevel shell to be able to locate this file on startup.

2.3.7 Printing manuals (Un*x)
-----------------------------

As mentioned before, the manual is available in several formats in
the `reference' directory within the `doc' directory in the Ciao
distribution, including `postscript' or `pdf', which are specially
useful for printing. These files are also available in the `DOCROOT'
directory specified during installation. Printing can be done using
an application such as `ghostview' (freely available from
`http://www.cs.wisc.edu/~ghost/index.html') or `acrobat reader'
(`http://www.adobe.com', only `pdf').

2.4 An introduction to the Ciao emacs environment (Un*x)
========================================================

While it is easy to use Ciao with any editor of your choice, using it
within the `emacs' editor/program development system is highly
recommended: Ciao includes an `emacs' _mode_ which provides a very
complete _application development environment_ which greatly
simplifies many program development tasks. See Using Ciao inside GNU emacs
for details on the capabilities of `ciao'/ `emacs'
combination.

   If the (freely available) `emacs' editor/environment is not
installed in your system, we highly recommend that you also install
it at this point (there are instructions for where to find `emacs'
and how to install it in the Ciao installation instructions). After
having done this you can try for example the following things:

   * A few basic things:

        * Typing <^H> <i> (or in the menus `Help->Manuals->Browse
          Manuals with Info') should open a list of manuals in info
          format in which the Ciao manual(s) should appear.

        * When opening a Prolog file, i.e., a file with `.pl' or
          `.pls' ending, using <^X><^F>`filename' (or using the
          menus) the code should appear highlighted according to
          syntax (e.g., comments in red), and `Ciao/Prolog' menus
          should appear in the menu bar on top of the `emacs' window.

        * Loading the file using the `Ciao/Prolog' menu (or typing
          <^C> <l>) should start in another emacs buffer the Ciao
          toplevel shell and load the file. You should now be able to
          switch the the toplevel shell and make queries from within `emacs'.

     *Note:* when using `emacs' it is _very convenient_ to swap the
     locations of the (normally not very useful) <Caps Lock> key and
     the (very useful in `emacs') <Ctrl> key on the keyboard. How to
     do this is explained in the `emacs' frequently asked questions
     FAQs (see the `emacs' download instructions for their location).

     (if these things do not work the system or emacs may not be
     installed properly).

   * You can go to the location of most of the errors that may be
     reported during compilation by typing <^C> <`>.

   * You can also, e.g., create executables from the `Ciao/Prolog'
     menu, as well as compile individual files, or generate active
     modules.

   * Loading a file for source-level debugging using the
     `Ciao/Prolog' menu (or typing <^C> <d>) and then issuing a query
     should start the source-level debugger and move a marker on the
     code in a window while execution is stepped through in the
     window running the Ciao top level.

   * You can add the lines needed in Un*x for turning any file
     defining `main/1' into a script from the Ciao/Prolog menu or by
     typing <^C> <I> <S>.

   * You can also work with the preprocessor and auto-documenter
     directly from emacs: see their manuals or browse through the
     corresponding menus that appear when editing `.pl' files.

   We encourage you once more to read Using Ciao inside GNU emacs
to discover the many other functionalities of this
environment.

2.5 Keeping up to date (Un*x)
=============================

You may want to read Beyond installation for instructions on
how to sign up on the Ciao user's mailing list, receive announcements
regarding new versions, download new versions, report bugs, etc.

3 Getting started on Windows machines
*************************************

*Author(s):* M.Hermenegildo.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#116 (2003/12/3, 13:35:35 CET)

   This part guides you through some very basic first steps with Ciao
on an MSWindows ("Win32") system. It assumes that Ciao is already
installed correctly on your Windows system. If this is not the case,
then follow the instructions in Installing Ciao from a Win32 binary distribution
(or Installing Ciao from the source distribution)
first.

   We start with by describing the basics of using Ciao from the
Windows explorer and/or a DOS command shell. We strongly recommend
reading also An introduction to the Ciao emacs environment (Win32)
for the basics on using Ciao under `emacs', which is a much
simpler and much more powerful way of developing Ciao programs, and
has the advantage of offering an almost identical environment under
Windows and Un*x.

3.1 Testing your Ciao Win32 installation
========================================

It is a good idea to start by performing some tests to check that
Ciao is installed correctly on your system (these are the same tests
that you are instructed to do during installation, so you can
obviously skip them if you have done them already at that time):

   * Ciao-related file types (`.pl' source files, `.cpx' executables,
     `.itf,.po,.asr' interface files, `.pls' scripts, etc.) should
     have specific icons associated with them (you can look at the
     files in the folders in the Ciao distribution to check).

   * Double-clicking on the shortcut to `ciaosh'(`.cpx') on the
     desktop should start the typical Prolog top-level shell in a
     window. If this shortcut has not been created on the desktop,
     then double-clicking on the `ciaosh'(`.cpx') icon inside the
     `shell' folder within the Ciao source folder should have the
     same effect.

   * In the top-level shell, Prolog library modules should load
     correctly. Type for example `use_module(library(dec10_io)).' at
     the Ciao top-level prompt -you should get back a prompt with no
     errors reported.

   * To exit the top level shell, type `halt.' as usual, or <^D>.

Also, the following documentation-related actions should work:

   * Double-clicking on the shortcut to `ciao'(`.html') which appears
     on the desktop should show the Ciao manual in your default WWW
     browser. If this shortcut has not been created you can
     double-click on the `ciao'(`.html') file in the
     `doc\reference\ciao_html' folder inside the Ciao source folder.
     Make sure you configure your browser to use _style sheets_ for
     correct formatting of the manual (note, however, that some older
     versions of Explorer did not support style sheets well and will
     give better results turning them off).

   * The `doc\reference' folder contains the manual also in the other
     formats present in the distribution, such as `info' (very
     convenient for users of the `emacs' editor/program development
     system) and `postscript' or `pdf', which are specially useful
     for printing. See Printing manuals (Win32) for
     instructions.

3.2 Using Ciao from the Windows explorer and command shell
==========================================================

3.2.1 Starting/exiting the top-level shell (Win32)
--------------------------------------------------

The basic methods for starting/exiting the top-level shell have been
discussed above. The installation script also leaves a
`ciaosh'(`.bat') file inside the `shell' folder of the Ciao
distribution which can be used to start the top-level shell from the
command line in Windows systems.

3.2.2 Getting help (Win32)
--------------------------

The basic methods for accessing the manual on-line have also been
discussed above. Use the table of contents and the indices of
_predicates_, _libraries_, _concepts_, etc. to find what you are
looking for.  Context-sensitive help is available within the `emacs'
environment (see below).

3.2.3 Compiling and running programs (Win32)
--------------------------------------------

Once the shell is started, you can compile and execute Prolog modules
inside the interactive toplevel shell in the standard way. E.g., type
`use_module(_file_).', `use_module(library(_file_)).' for library
modules, `ensure_loaded(_file_).' for files which are not modules,
and `use_package(_file_).' for library packages (these are
syntactic/semantic packages that extend the Ciao Prolog language in
many different ways). Note that the use of `compile/1' and `consult/1'
is discouraged in Ciao.

   For example, you may want to type `use_package(iso)' to ensure
Ciao has loaded all the ISO builtins (whether this is done by default
or not depends on your `.ciaorc' file). Do not worry about any
"module already in executable" messages -these are normal and simply
mean that a certain module is already pre-loaded in the toplevel
shell. At this point, typing `write(hello).' should work.

   Note that some predicates that may be built-ins in other Prologs
are available through libraries in Ciao. This facilitates making
small executables.

   To change the working directory to, say, the `examples' directory
in the Ciao source directory, first do:

           ?- use_module(library(system)).

(loading the `system' library makes a number of system-related
predicates such as `cd/1' accessible) and then:

           ?- cd('$/examples').

(in Ciao the sequence `$/' _at the beginning of a path name_ is
replaced by the path of the Ciao root directory).

   For more information see The interactive top-level shell.

3.2.4 Generating executables (Win32)
------------------------------------

Executables can be generated from the toplevel shell (using `make_exec/2')
or using the standalone compiler ( `ciaoc'(`.cpx'), located in the
`ciaoc' folder). To be able to make an executable, the file should
define the predicate `main/1' (or `main/0'), which will be called
upon startup (see the corresponding manual section for details).

For example, within the `examples' directory, you can type:

         ?- make_exec(hw,_).

which should produce an executable. Double-clicking on this
executable should execute it.

   Another way of creating Ciao executables from source files is by
right-clicking on `.pl' files and choosing "make executable". This
uses the standalone compiler (this has the disadvantage, however,
that it is sometimes difficult to see the error messages).

   For more information see The interactive top-level shell
and The stand-alone command-line compiler.

3.2.5 Running Ciao scripts (Win32)
----------------------------------

Double-clicking on files ending in `.pls', _Ciao Prolog scripts_,
will also execute them. These are files containing Prolog source but
which get executed without having to explicitly compile them (in the
same way as, e.g., `.bat' files or programs in scripting languages).
As an example, you can double-click on the file `hw.pls' in the `examples'
folder and look at the source with an editor. You can try changing
the `Hello world' message and double-clicking again (no need to
recompile!).

   As you can see, the file should define the predicate `main/1' (not `main/0'),
which will be called upon startup. The two header lines are only
necessary in Un*x. In Windows you can leave them in or you can take
them out, but leaving them in has the advantage that the script will
also work in Un*x without any change.

   For more information see The script interpreter.

3.2.6 The Ciao initialization file (Win32)
------------------------------------------

The Ciao toplevel can be made to execute upon startup a number of
commands (such as, e.g., loading certain files or setting certain
Prolog flags) contained in an initialization file. This file should
be called `.ciaorc' and placed in your _home_ folder (e.g., the same
in which the `.emacs' file is put). You may need to set the
environment variable `HOME' to the path of this folder for the Ciao
toplevel shell to be able to locate this file on startup.

3.2.7 Printing manuals (Win32)
------------------------------

As mentioned before, the manual is available in several formats in
the `reference' folder within Ciao's `doc' folder, including
`postscript' or `pdf', which are specially useful for printing. This
can be done using an application such as `ghostview' (freely
available from `http://www.cs.wisc.edu/~ghost/index.html') or `acrobat
reader' (`http://www.adobe.com', only `pdf').

3.3 An introduction to the Ciao emacs environment (Win32)
=========================================================

While it is easy to use Ciao with any editor of your choice, using it
within the `emacs' editor/program development system is highly
recommended: Ciao includes an `emacs' _mode_ which provides a very
complete _application development environment_ which greatly
simplifies many program development tasks. See Using Ciao inside GNU emacs
for details on the capabilities of `ciao'/ `emacs'
combination.

   If the (freely available) `emacs' editor/environment is not
installed in your system, we highly recommend that you also install
it at this point (there are instructions for where to find `emacs'
and how to install it in the Ciao installation instructions). After
having done this you can try for example the following things:

   * A few basic things:

        * Typing <^H> <i> (or in the menus `Help->Manuals->Browse
          Manuals with Info') should open a list of manuals in info
          format in which the Ciao manual(s) should appear.

        * When opening a Prolog file, i.e., a file with `.pl' or
          `.pls' ending, using <^X><^F>`filename' (or using the
          menus) the code should appear highlighted according to
          syntax (e.g., comments in red), and `Ciao/Prolog' menus
          should appear in the menu bar on top of the `emacs' window.

        * Loading the file using the `Ciao/Prolog' menu (or typing
          <^C> <l>) should start in another emacs buffer the Ciao
          toplevel shell and load the file. You should now be able to
          switch the the toplevel shell and make queries from within `emacs'.

     *Note:* when using `emacs' it is _very convenient_ to swap the
     locations of the (normally not very useful) <Caps Lock> key and
     the (very useful in `emacs') <Ctrl> key on the keyboard. How to
     do this is explained in the `emacs' frequently asked questions
     FAQs (see the `emacs' download instructions for their location).

     (if these things do not work the system or emacs may not be
     installed properly).

   * You can go to the location of most of the errors that may be
     reported during compilation by typing <^C> <`>.

   * You can also, e.g., create executables from the `Ciao/Prolog'
     menu, as well as compile individual files, or generate active
     modules.

   * Loading a file for source-level debugging using the
     `Ciao/Prolog' menu (or typing <^C> <d>) and then issuing a query
     should start the source-level debugger and move a marker on the
     code in a window while execution is stepped through in the
     window running the Ciao top level.

   * You can add the lines needed in Un*x for turning any file
     defining `main/1' into a script from the Ciao/Prolog menu or by
     typing <^C> <I> <S>.

   * You can also work with the preprocessor and auto-documenter
     directly from emacs: see their manuals or browse through the
     corresponding menus that appear when editing `.pl' files.

   We encourage you once more to read Using Ciao inside GNU emacs
to discover the many other functionalities of this
environment.

3.4 Keeping up to date (Win32)
==============================

You may want to read Beyond installation for instructions on
how to sign up on the Ciao user's mailing list, receive announcements
regarding new versions, download new versions, report bugs, etc.

PART I - The program development environment
********************************************

*Author(s):* Manuel Carro.

   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.pl:
     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 Prolog
     systems. 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 _Prolog scripts_ (i.e., files
     containing Prolog code which run without needing explicit
     compilation).

ciao.el:
     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.

4 The stand-alone command-line compiler
***************************************

*Author(s):* Daniel Cabeza and the CLIP Group.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#98 (2003/8/27, 12:39:15 CEST)

   `ciaoc' [CH00b] is the Ciao stand-alone command-line compiler.  `ciaoc'
can be used to create executables or to compile individual files to
object code (to be later linked with other files).  `ciaoc' is
specially useful when working from the command line. Also, it can be
called to compile Ciao programs from other tools such as, e.g., shell
scripts, `Makefile's, or project files. All the capabilities of `ciaoc'
are also available from the interactive top-level shell, which uses
the ciaoc modules as its components.

4.1 Introduction to building executables
========================================

An _executable_ can be built from a single file or from a collection
of inter-related files. In the case of only one file, this file must
define the predicate `main/0' or `main/1'. This predicate is the one
which will be called when the executable is started. As an example,
consider the following file, called `hello.pl':

     main :-
          write('Hello world'),
          nl.

To compile it from the command line using the `ciaoc' standalone
compiler it suffices to type "`ciaoc hello'" (in Win32 you may have
to put the complete path to the `ciaoc' folder of the Ciao
distribution, where the installation process leaves a `ciaoc.bat'
file):

     /herme@clip:/tmp
     [60]> ciaoc hello

     /herme@clip:/tmp
     [61]>

This produces an executable called `hello' in Un*x-like systems and
`hello.cpx' under Win32 systems. This executable can then be run in
Win32 by double-clicking on it and on Un*x systems by simply typing
its name (see for Running executables from the command line
for how to run executables from the command line in Win32):

     /herme@clip:/tmp
     [61]> hello
     Hello world

   If the application is composed of several files the process is
identical. Assume `hello.pl' is now:

     :- use_module(aux,[p/1]).

     main :-
          p(X),
          write(X),
          nl.

where the file `aux.pl' contains:

     :- module(aux,[p/1]).

     p('Hello world').

This can again be compiled using the `ciaoc' standalone compiler as
before:

     /herme@clip:/tmp
     [60]> ciaoc hello

     /herme@clip:/tmp
     [61]> hello
     Hello world

The invocation of `ciaoc hello' compiles the file `hello.pl' and all
connected files that may need recompilation - in this case the file
`aux.pl'. Also, if any library files used had not been compiled
previously they would be compiled at this point (See
Intermediate files in the compilation process). Also, if, say,
`hello.pl' is changed and recompiled, the object code resulting from
the previous compilation of `aux.pl' will be reused. This is all done
without any need for `Makefile's, and considerably accelerates the
development process for large applications. This process can be
observed by selecting the `-v' option when invoking `ciaoc' (which is
equivalent to setting the `verbose_compilation' Prolog flag to `on'
in the top-level interpreter).

   If `main/1' is defined instead of `main/0' then when the
executable is started the argument of `main/1' will be instantiated
to a list of atoms, each one of them corresponding to a command line
option. Consider the file `say.pl':

     main(Argv) :-
          write_list(Argv), nl.

     write_list([]).
     write_list([Arg|Args]) :-
          write(Arg),
          write(' '),
          write_list(Args).

Compiling this program and running it results in the following output:

     /herme@clip:/tmp
     [91]> ciaoc say

     /herme@clip:/tmp
     [91]> say hello dolly
     hello dolly

   The name of the generated executable can be controlled with the
`-o' option (See Usage (ciaoc)).

4.2 Paths used by the compiler during compilation
=================================================

The compiler will look for files mentioned in commands such as `use_module/1'
or `ensure_loaded/1' in the current directory. Other paths can be
added by including them in a file whose name is given to `ciaoc'
using the `-u' option. This file should contain facts of the
predicates `file_search_path/2' and `library_directory/1' (see the
documentation for these predicates and also Customizing library paths and path aliases
for details).

4.3 Running executables from the command line
=============================================

As mentioned before, what the `ciaoc' compiler generates and how it
is started varies somewhat from OS to OS. In general, the product of
compiling an application with `ciaoc' is a file that contains the
bytecode (the product of the compilation) and invokes the Ciao engine
on it.

   * Un Un*x this is a _script_ (see the first lines of the file)
     which invokes the ciao engine on this file. To run the generated
     executable from a Un*x shell, or from the `bash' shell that
     comes with the Cygwin libraries (see Installation and compilation under Windows)
     it suffices to type its name at the
     shell command line, as in the examples above.

   * In a Win32 system, the compiler produces a similar file with a
     `.cpx' ending. The Ciao installation process typically makes
     sure that the Windows registry contains the right entries so
     that this executable will run upon double-cliking on it.

     In you want to run the executable from the command line an
     additional `.bat' file is typically needed. To help in doing
     this, the Win32 installation process creates a `.bat' skeleton
     file called `bat_skel' in the `Win32' folder of the
     distribution) which allows running Ciao executables from the
     command line. If you want to run a Ciao executable `file.cpx'
     from the command line, you normally copy the skeleton file to
     the folder were the executable is and rename it to `file.bat',
     then change its contents as explained in a comment inside the
     file itself.

     Note that this `.bat' file is usually not necessary in NT, as
     its command shell understands file extension associations. I.e.,
     in windows NT it is possible to run the `file.cpx' executable
     directly. Due to limitations of `.bat' files in Windows 95/98,
     in those OSs no more than 9 command line arguments can be passed
     to the executable (in NT there is no such restriction).

     Finally, in a system in which Cygnus Win32 is installed
     executables can also be used directly from the `bash' shell
     command line, without any associated `.bat' files, by simply
     typing their name at the `bash' shell command line, in the same
     way as in Un*x. This only requires that the `bash' shell which
     comes with Cygnus Win32 be installed and accessible: simply,
     make sure that `/bin/sh.exe' exists.

   Except for a couple of header lines, the contents of executables
are almost identical under different OSs (except for self-contained
ones). The bytecode they contain is architecture-independent. In
fact, it is possible to create an executable under Un*x and run it on
Windows or viceversa, by making only minor modifications (e.g.,
creating the `.bat' file and/or setting environment variables or
editing the start of the file to point to the correct engine
location).

4.4 Types of executables generated
==================================

While the default options used by `ciaoc' are sufficient for normal
use, by selecting other options `ciaoc' can generate several
different types of executables, which offer interesting tradeoffs
among size of the generated executable, portability, and startup time
[CH00b]:

Dynamic executables:
     `ciaoc' produces by default _dynamic_ executables. In this case
     the executable produced is a platform-independent file which
     includes in compiled form all the user defined files. On the
     other hand, any system libraries used by the application are
     loaded dynamically at startup. More precisely, any files that
     appear as `library(...)' in `use_module/1' and `ensure_loaded/1'
     declarations will not be included explicitly in the executable
     and will instead be loaded dynamically. Is is also possible to
     mark other path aliases (see the documentation for `file_search_path/2')
     for dynamic loading by using the `-d' option. Files accessed
     through such aliases will also be loaded dynamically.

     Dynamic loading allows making smaller executables. Such
     executables may be used directly in the same machine in which
     they were compiled, since suitable paths to the location of the
     libraries will be included as default in the executable by `ciaoc'
     during compilation.

     The executable can also be used in another machine, even if the
     architecture and OS are different. The requirement is that the
     Ciao libraries (which will also include the appropriate Ciao
     engine for that architecture and OS) be installed in the target
     machine, and that the `CIAOLIB' and `CIAOENGINE' environment
     variables are set appropriately for the executable to be able to
     find them (see Environment variables used by Ciao executables).
     How to do this differs slightly from OS to OS.

Static executables:
     Selecting the `-s' option `ciaoc' produces a _static_
     executable. In this case the executable produced (again a platform-independent
     file) will include in it all the auxiliary files and any system
     libraries needed by the application. Thus, such an executable is
     almost complete, needing in order to run only the Ciao engine,
     which is platform-specific.(1) Again, if the executable is run
     in the same machine in which it was compiled then the engine is
     found automatically. If the executable is moved to another
     machine, the executable only needs access to a suitable engine
     (which can be done by setting the `CIAOENGINE' environment
     variable to point to this engine).

     This type of compilation produces larger executables, but has
     the advantage that these executables can be installed and run in
     a different machine, with different architecture and OS, even if
     Ciao is not installed on that machine. To install (or
     distribute) such an executable, one only needs to copy the
     executable file itself and the appropriate engine for the target
     platform (See Installing Ciao from the source distribution
     or Installing Ciao from a Win32 binary distribution
     and Multiarchitecture support), and to
     set things so that the executable can find the engine. (2)

Dynamic executables, with lazy loading:
     Selecting the `-l' option is very similar to the case of dynamic
     executables above, except that the code in the library modules
     is not loaded when the program is started but rather it is done
     during execution, the first time a predicate defined in that
     file is called. This is advantageous if a large application is
     composed of many parts but is such that typically only some of
     the parts are used in each invocation. The Ciao preprocessor, `ciaopp',
     is a good example of this: it has many capabilitites but
     typically only some of them are used in a given session. An
     executable with lazy load has the advantage that it starts fast,
     loading a minimal functionality on startup, and then loads the
     different modules automatically as needed. Please beware that
     initialization directives appearing in a module which is lazily
     loaded currently are not executed until the module is
     effectively loaded. Since this happens when the module is first
     required at runtime, the compiler cannot guarantee the exact
     time and order in which these directives are executed.

Self-contained executables:
     _Self-contained_ executables are static executables (i.e., this
     option also implies _static_ compilation) which include a Ciao
     engine along with the bytecode, so they do not depend on an
     external one for their execution. This is useful to create
     executables which run even if the machine where the program is
     to be executed does not have a Ciao engine installed and/or
     libraries. The disadvantage is that such execuatbles are platform-dependent
     (as well as larger than those that simply use an external
     library). This type of compilation is selected with the `-S'
     option. Cross-compilation is also possible with the `-SS'
     option, so you can specify the target OS and architecture (e.g.
     LINUXi86). To be able to use the latter option, it is necessary
     to have installed a ciaoengine for the target machine in the
     Ciao library (this requires compiling the engine in that
     OS/architecture and installing it, so that it is available in
     the library).

Compressed executables:
     In _compressed_ executables the bytecode is compressed. This
     allows producing smaller executables, at the cost of a slightly
     slower startup time. This is selected with the `-z' option. You
     can also produce compressed libraries if you use `-zl' along
     with the `-c' option. If you select `-zl' while generating an
     executable, any library which is compiled to accomplish this
     will be also compressed.

Active modules:
     The compiler can also compile (via the `-a' option) a given file
     into an _active module_ (see Active modules (high-level distributed execution)
     for a description of this).

   ---------- Footnotes ----------

   (1) Currently there is an exception to this related to libraries
which are written in languages other than Prolog, as, e.g., C. C
files are currently always compiled to dynamically loadable object
files (`.so' files), and they thus need to be included manually in a
distribution of an application. This will be automated in upcoming
versions of the Ciao system.

   (2) It is also possible to produce real standalone executables,
i.e., executables that do not need to have an engine around. However,
this is not automated yet, although it is planned for an upcoming
version of the compiler. In particular, the compiler can generate a
`.c' file for each `.pl' file. Then all the `.c' files can be
compiled together into a real executable (the engine is added one
more element during link time) producing a complete executable for a
given architecture. The downside of course is that such an executable
will not be portable to other architectures without recompilation.

4.5 Environment variables used by Ciao executables
==================================================

The executables generated by the Ciao compiler (including the ciao
development tools themselves) locate automatically where the Ciao
engine and libraries have been installed, since those paths are
stored as defaults in the engine and compiler at installation time.
Thus, there is no need for setting any environment variables in order
to _run_ Ciao executables (on a single architecture - see
Multiarchitecture support for running on multiple architectures).

   However, the default paths can be overridden by using the
environment variables `CIAOENGINE' and `CIAOLIB'. The first one will
tell the Ciao executables where to look for an engine, and the second
will tell them where to look for the libraries. Thus, it is possible
to actually use the Ciao system without installing it by setting
these variables to the following values:
   * `CIAOENGINE': `$(SRC)/bin/$(CIAOARCH)/ciaoengine'

   * `CIAOLIB': `$(SRC)'

   where `$(CIAOARCH)' is the string echoed by the command
`SRC/etc/ciao_get_arch' (or `BINROOT/ciao_get_arch', after
installation).

   This allows using alternate engines or libraries, which can be
very useful for system development and experimentation.

4.6 Intermediate files in the compilation process
=================================================

Compiling an individual source (i.e., `.pl') file produces a `.itf'
file and a `.po' file. The `.itf' file contains information of the _modular
interface_ of the file, such as information on exported and imported
predicates and on the other modules used by this module. This
information is used to know if a given file should be recompiled at a
given point in time and also to be able to detect more errors
statically including undefined predicates, mismatches on predicate
charaterictics across modules, etc. The `.po' file contains the
platform-independent object code for a file, ready for linking
(statically or dynamically).

   It is also possible to use `ciaoc' to explicitly generate the
`.po' file for one or more `.pl' files by using the `-c' option.

4.7 Usage (ciaoc)
=================

The following provides details on the different command line options
available when invoking `ciaoc':

     ciaoc <MiscOpts> <ExecOpts> [-o <execname>] <file> ...

       Make an executable from the listed files.  If there is
       more than one file, they must be non-module, and the
       first one must include the main predicate.  The -o
       option allows generating an arbitrary executable name.

     ciaoc <MiscOpts> <ExecOpts> -a <publishmod> <module>

       Make an active module executable from <module> with
       address publish module <publishmod>.

     ciaoc <MiscOpts> -c  <file> ...

       Compile listed files (make .po objects).

     <MiscOpts> can be: [-v] [-ri] [-u <file>]

     -v  verbose mode

     -ri generate human readable .itf files

     -u  use <file> for compilation

     <ExecOpts> can be: [-s|-S|-SS <target>|-z|-zl|-e|-l|(-ll <module>)*]
                        (-d <alias>)* [-x]

     -s  make a static executable (otherwise dynamic files are not included)

     -S  make standalone executable for the current OS and architecture

     -SS make standalone executable for <target> OS and architecture
         valid <target> values may be: LINUXi86, SolarisSparc...

         (both -S and -SS imply -s)

     -z  generate executables with compressed bytecode

     -zl generate libraries with compressed bytecode - any library (re)compiled
         as consequence of normal executable compilation will also be affected

     -e  make executable with eager load of dynamic files at startup (default)

     -l  idem with lazy load of dynamic files (except insecure cases)

     -ll force <module> to be loaded lazily,  implies -l

     -d  files using this path alias are dynamic (default: library)

     -x  Extended recompilation: only useful for Ciao standard library developers

     default extension for files is '.pl'

5 The interactive top-level shell
*********************************

*Author(s):* Daniel Cabeza and the CLIP Group.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.7#129 (2001/10/28, 15:38:52 CET)

   `ciaosh' is the Ciao interactive top-level shell. It provides the
user with an interactive programming environment with tools for
incrementally building programs, debugging programs by following
their executions, and modifying parts of programs without having to
start again from scratch. If available, it is strongly recommended to
use it with the emacs interface provided, as it greatly simplifies
the operation. This chapter documents general operation in the shell
itself. Other chapters document the

5.1 Shell invocation and startup
================================

When invoked, the shell responds with a message of identification and
the prompt `?- ' as soon as it is ready to accept input, thus:

     Ciao-Prolog X.Y #PP: Thu Mar 25 17:20:55 MET 1999
     ?-

   When the shell is initialized it looks for a file `.ciaorc' in the
HOME directory and makes an `include' of it, if it exists. This file
is useful for including `use_module/1' declarations for the modules
one wants to be loaded by default, changing prolog flags, etc. (Note
that the `.ciaorc' file can only contain directives, not actual code;
to load some code at startup put it in a separate file and load it
using e.g. a `use_module/1' declaration.) If the initialization file
does not exist, the default package `default' is included, to provide
more or less what other prologs define by default. Thus, if you want
to have available all builtins you had before adding the
initialization file, you have to include `:- use_package(default)' in
it. Two command-line options control the loading of the
initialization file:

`-f'
     Fast start, do not load any initialization file.

`-l' `File'
     Look for initialization file `File' instead of `~/.ciaorc'. If
     it does not exist, include the default package.

5.2 Shell interaction
=====================

After the shell outputs the prompt, it is expecting either an
internal command (see the following sections) or a _query_ (a goal or
sequence of goals). When typing in the input, which must be a valid
prolog term, if the term does not end in the first line, subsequent
lines are indented. For example:

     ?- X =
        f(a,
        b).

     X = f(a,b) ?

     yes
     ?-

   The queries are executed by the shell as if they appeared in the user
module. Thus, in addition to builtin predicates, predicates available
to be executed directly are all predicates defined by loaded user
files (files with no module declaration), and imported predicates
from modules by the use of `use_module'.

   The possible answers of the shell, after executing an internal
command or query, are:

   * If the execution failed (or produced an error), the answer is
     `no'.

   * If the execution was successful, and no answer variable (see
     below) was bound (or constraints where imposed on such
     variables), the answer is simply `yes'. This behavior can be
     changed by doing
     `set_prolog_flag(prompt_alternatives_no_bindings, on).', so that
     in any case the user will be consulted as explained in the next
     point (useful if the solutions produce side effects).

   * If the execution was successful and bindings where made (or
     constraints where imposed) on answer variables, then the shell
     outputs the values of answer variables, as a sequence of
     bindings (or constraints), and then prints a `?' as a prompt. At
     this point it is expecting an input line from the user. By
     entering a carriage-return (<RET>) or any line starting with
     `y', the query terminates and the shell answer `yes'. Entering a
     ``,'' the shell enters a recursive level (see below). Finally,
     any other answer forces the system to backtrack and look for the
     next solution (answering as with the first solution).

   To allow using connection variables in queries without having to
report their results, variables whose name starts with `_' are not
considered in answers, the rest being the _answer variable_s. This
example illustrates the previous points:

     ?- member(a, [b, c]).

     no
     ?- member(a, [a, b]).

     yes
     ?- member(X, [a|L]).

     X = a ? ;

     L = [X|_] ?

     yes
     ?- atom_codes(ciao, _C), member(L, _C).

     L = 99 ? ;

     L = 105 ? ;

     L = 97 ? ;

     L = 111 ? ;

     no
     ?-

5.3 Entering recursive (conjunctive) shell levels
=================================================

As stated before, when the user answers with ``,'' after a solution
is presented, the shell enters a _recursive level_, changing its
prompt to _N_ `?- ' (where _N_ is the recursion level) and keeping
the bindings or constraints of the solution (this is inspired by the _LogIn_
language developed by _H. Ait-Kaci_, _P. Lincoln_ and _Roger Nasr_
[AKNL86]). Thus, the following queries will be executed within that
context, and all variables in the lower level solutions will be
reported in subsequent solutions at this level. To exit a recursive
level, input an <EOF> character or the command `up'. The last
solution after entering the level is repeated, to allow asking for
more solutions. Use command `top' to exit all recursive levels and
return to the top level. Example interaction:

     ?- directory_files('.',_Fs), member(F,_Fs).

     F = 'file_utils.po' ? ,

     1 ?- file_property(F, mod_time(T)).

     F = 'file_utils.po',
     T = 923497679 ?

     yes
     1 ?- up.

     F = 'file_utils.po' ? ;

     F = 'file_utils.pl' ? ;

     F = 'file_utils.itf' ? ,

     1 ?- file_property(F, mod_time(T)).

     F = 'file_utils.itf',
     T = 923497679 ?

     yes
     1 ?- ^D
     F = 'file_utils.itf' ?

     yes
     ?-

5.4 Usage and interface (`ciaosh')
==================================

   * *Library usage:*

     The following predicates can be used at the top-level shell
     natively (but see also the commands available in The interactive debugger
     which are also available within the
     top-level shell).

   * *Exports:*
        - _Predicates:_

          `use_module/1', `use_module/2', `ensure_loaded/1', `make_exec/2', `include/1', `use_package/1', `consult/1', `compile/1', `./2', `make_po/1', `unload/1', `set_debug_mode/1', `set_nodebug_mode/1', `make_actmod/2', `force_lazy/1', `undo_force_lazy/1', `dynamic_search_path/1', `multifile/1'.

   * *Other modules used:*
        - _Application modules:_

          `library(ciaosh)'.

        - _System library modules:_

          `libpaths', `compiler/compiler', `compiler/exemaker', `compiler/c_itf', `debugger/debugger'.

5.5 Documentation on exports (`ciaosh')
=======================================

 -- PREDICATE: use_module/1:
     *Usage:* `use_module(Module)'
        - _Description:_ Load into the top-level the module defined
          in `Module', importing all the predicates it exports.

        - _The following properties should hold at call time:_

          `Module' is a source name.   (`streams_basic:sourcename/1')

 -- PREDICATE: use_module/2:
     *Usage:* `use_module(Module, Imports)'
        - _Description:_ Load into the top-level the module defined
          in `Module', importing the predicates in `Imports'.

        - _The following properties should hold at call time:_

          `Module' is a source name.   (`streams_basic:sourcename/1')

          `Imports' is a list of `predname's.   (`basic_props:list/2')

 -- PREDICATE: ensure_loaded/1:
     *Usage:* `ensure_loaded(File)'
        - _Description:_ Load into the top-level the code residing in
          file (or files) `File', which is user (i.e. non-module)
          code.

        - _The following properties should hold at call time:_

          `File' is a source name or a list of source names.
          (`ciaosh_doc:sourcenames/1')

 -- PREDICATE: make_exec/2:
     *Usage:* `make_exec(File, ExecName)'
        - _Description:_ Make a Ciao executable from file (or files)
          `File', giving it name `ExecName'. If `ExecName' is a
          variable, the compiler will choose a default name for the
          executable and will bind the variable `ExecName' to that
          name. The name is chosen as follows: if the main prolog
          file has no `.pl' extension or we are in Windows, the
          executable will have extension `.cpx'; else the executable
          will be named as the main prolog file without extension.

        - _The following properties should hold at call time:_

          `File' is a source name or a list of source names.
          (`ciaosh_doc:sourcenames/1')

        - _The following properties hold upon exit:_

          `ExecName' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: include/1:
     *Usage:* `include(File)'
        - _Description:_ The contents of the file `File' are included
          in the top-level shell. For the moment, it only works with
          some directives, which are interpreted by the shell, or
          with normal clauses (which are asserted), if
          library(dynamic) is loaded beforehand.

        - _The following properties should hold at call time:_

          `File' is a source name.   (`streams_basic:sourcename/1')

 -- PREDICATE: use_package/1:
     *Usage:* `use_package(Package)'
        - _Description:_ Equivalent to issuing an
          include(library(`Package')) for each listed file. By now
          some package contents cannot be handled.

        - _The following properties should hold at call time:_

          `Package' is a source name or a list of source names.
          (`ciaosh_doc:sourcenames/1')

 -- PREDICATE: consult/1:
     *Usage:* `consult(File)'
        - _Description:_ Provided for backward compatibility. Similar
          to `ensure_loaded/1', but ensuring each listed file is
          loaded in consult mode (see The interactive debugger).

        - _The following properties should hold at call time:_

          `File' is a source name or a list of source names.
          (`ciaosh_doc:sourcenames/1')

 -- PREDICATE: compile/1:
     *Usage:* `compile(File)'
        - _Description:_ Provided for backward compatibility. Similar
          to `ensure_loaded/1', but ensuring each listed file is
          loaded in compile mode (see The interactive debugger).

        - _The following properties should hold at call time:_

          `File' is a source name or a list of source names.
          (`ciaosh_doc:sourcenames/1')

 -- PREDICATE: ./2:
     *Usage:* `.(File, Files)'
        - _Description:_ Provided for backward compatibility,
          obsoleted by `ensure_loaded/1'.

        - _The following properties should hold at call time:_

          `File' is a source name.   (`streams_basic:sourcename/1')

          `Files' is a list of `sourcename's.   (`basic_props:list/2')

 -- PREDICATE: make_po/1:
     *Usage:* `make_po(Files)'
        - _Description:_ Make object (`.po') files from `Files'.
          Equivalent to executing "`ciaoc -c'" on the files.

        - _The following properties should hold at call time:_

          `Files' is a source name or a list of source names.
          (`ciaosh_doc:sourcenames/1')

 -- PREDICATE: unload/1:
     *Usage:* `unload(File)'
        - _Description:_ Unloads dynamically loaded file `File'.

        - _The following properties should hold at call time:_

          `File' is a source name.   (`streams_basic:sourcename/1')

 -- PREDICATE: set_debug_mode/1:
     *Usage:* `set_debug_mode(File)'
        - _Description:_ Set the loading mode of `File' to _consult_.
          See The interactive debugger.

        - _The following properties should hold at call time:_

          `File' is a source name.   (`streams_basic:sourcename/1')

 -- PREDICATE: set_nodebug_mode/1:
     *Usage:* `set_nodebug_mode(File)'
        - _Description:_ Set the loading mode of `File' to _compile_.
          See The interactive debugger.

        - _The following properties should hold at call time:_

          `File' is a source name.   (`streams_basic:sourcename/1')

 -- PREDICATE: make_actmod/2:
     *Usage:* `make_actmod(ModuleFile, PublishMod)'
        - _Description:_ Make an active module executable from the
          module residing in `ModuleFile', using address publish
          module of name `PublishMod' (which needs to be in the
          library paths).

        - _The following properties should hold at call time:_

          `ModuleFile' is a source name.
          (`streams_basic:sourcename/1')

          `PublishMod' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: force_lazy/1:
     *Usage:* `force_lazy(Module)'
        - _Description:_ Force module of name `Module' to be loaded
          lazily in the subsequent created executables.

        - _The following properties should hold at call time:_

          `Module' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: undo_force_lazy/1:
     *Usage:* `undo_force_lazy(Module)'
        - _Description:_ Disable a previous `force_lazy/1' on module
          `Module' (or, if it is uninstantiated, all previous `force_lazy/1').

        - _Calls should, and exit will be compatible with:_

          `Module' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: dynamic_search_path/1:
     *Usage:* `dynamic_search_path(Name)'
        - _Description:_ Asserting a fact to this data predicate,
          files using path alias `Name' will be treated as dynamic in
          the subsequent created executables.

        - _The following properties should hold at call time:_

          `Name' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: multifile/1:
     *Usage:* `multifile Pred'
        - _Description:_ Dynamically declare predicate `Pred' as
          multifile. This is useful at the top-level shell to be able
          to call multifile predicates of loaded files.

        - _The following properties should hold at call time:_

          `Pred' is a Name/Arity structure denoting a predicate name:
               predname(P/A) :-
                       atm(P),
                       nnegint(A).

          (`basic_props:predname/1')

5.6 Documentation on internals (`ciaosh')
=========================================

 -- PROPERTY: sourcenames/1:
     Is defined as follows:
          sourcenames(File) :-
                  sourcename(File).
          sourcenames(Files) :-
                  list(Files,sourcename).
     See `sourcename/1' in Basic file/stream handling

     *Usage:* `sourcenames(Files)'
        - _Description:_ `Files' is a source name or a list of source
          names.

6 The interactive debugger
**************************

*Author(s):* Daniel Cabeza, Manuel C. Rodriguez, (A. Ciepielewski, M.
Carlsson, T. Chikayama, K. Shen).

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#357 (2004/7/14, 12:59:59 CEST)

   The Ciao program development environment includes a number of
advanced debugging tools, such as a source-level debugger, the `ciaopp'
preprocessor, and some execution visualizers. Herein we discuss the
interactive debugger available in the standard top-level, which
allows tracing the control flow of programs, in a similar way to
other popular Prolog systems. This is a classical Byrd _box-type_ _debugger_ [Byr80,BBP81],
with some enhancements, most notably being able to track the
execution on the source program.

   We also discuss the embedded debugger, which is a version of the
debugger which can be embedded into executables. It allows triggering
an interactive debugging session at any time while running an
executable, without any need for the top-level shell.

   Byrd's Procedure Box model of debugging execution provides a
simple way of visualising control flow, including backtracking.
Control flow is in principle viewed at the predicate level, rather
than at the level of individual clauses. The Ciao debugger has the
ability to mark selected modules and/or files for debugging
(traditional and source debugging), rather than having to
exhaustively trace the program. It also allows to selectively set spy-points
and breakpoints. Spy-points allow the programmer to nominate
interesting predicates at which program execution is to pause so that
the programmer can interact with the debugger. Breakpoints are
similar to spy-points, but allow pausing at a specific line in the
code, corresponding to a particular literal. There is a wide choice
of control and information options available during debugging
interaction.

   *Note:* While the debugger described herein can be used in a
standalone way (i.e., from an operating system shell or terminal
window) in the same way as other Prolog debuggers, the most
convenient way of debugging Ciao programs is by using the programming
environment (see Using Ciao inside GNU emacs). This
environment has many debugging-related facilities, including
displaying the source code for the module(s) corresponding to the
procedure being executed, and higlighting dynamically the code
segments corresponding to the different execution steps.

6.1 Marking modules and files for debugging in the top-level debugger
=====================================================================

The Ciao debugger is module-based. This allows skipping during the
debugging process all files (including system library files) except
those in which a bug is suspected. This saves having to explictily
and repetitively skip predicates in unrelated files during the
debugging process. Also, there is an efficieny advantage: in order to
be able to run the debugger on a module, it must be loaded in _debug
(interpreted) mode_, which will execute slower than normal (compiled)
modules. Thus, it is interesting to compile in debug mode only those
modules that need to be traced. Instead of doing this (loading of
modules in one mode or another) by hand each time, in Ciao
(re)loading of modules in the appropriate mode is handled
automatically by the Ciao compiler. However, this requires the user
to _mark explicitly_ the modules in which debugging is to be
performed. The simplest way of achieving this is by executing in the
Ciao shell prompt, for each suspicious module `Module' in the
program, the command:

     ?- debug_module(Module).

or, alternatively:

     ?- debug_module_source(Module).

which in addition instructs the debugger to keep track of the line
numbers in the source file and to report them during debugging. This
is most useful when running the top-level inside the `emacs' editor
since in that case the Ciao emacs mode allows performing full source-level
debugging in each module marked as above, i.e., the source lines
being executed will be highlighted dynamically during debugging in a
window showing the source code of the module.

   Note that, since all files with no module declaration belong to
the pseudo-module `user', the command to be issued for debugging a
user file, say `foo.pl', is `debug_module(user)' or
`debug_module_source(user)', and not `debug_module(foo)'.

   The two ways of performing source-level debugging are fully
compatible between them, i.e., Ciao allows having some modules loaded
with `debug_module/1' and others with `debug_module_source/1'. To
change from one interpreted mode to the other mode it suffices to
select the module with the new interpreted mode (debugger mode),
using the appropiate command, and reload the module.

   The commands above perform in fact two related actions: first,
they let the compiler know that if a file containing a module with
this name is loaded, it should be loaded in interpreted mode (source
or traditional). In addition, they instruct the debugger to actually
prepare for debugging the code belonging to that module. After that,
the modules which are to be debugged have to be (re)loaded so that
they are compiled or loaded for interpretation in the appropriate
way. The nice thing is that, due to the modular behaviour of the
compiler/top-level, if the modules are part of a bigger application,
it suffices to load the main module of the application, since this
will automatically force the dependent modules which have changed to
be loaded in the appropriate way, including those whose _loading
mode_ has changed (i.e., changing the loading mode has the effect of
forcing the required re-loading of the module at the appropriate
time).

   Later in the debugging process, as the bug location is isolated,
typically one will want to restrict more and more the modules where
debugging takes place. To this end, and without the need for
reloading, one can tell the debugger to not consider a module for
debugging issuing a `nodebug_module/1' command, which counteracts a `debug_module/1'
or `debug_module_source/1' command with the same module name, and
reloading it (or the main file).

   There are also two top-level commands `set_debug_mode/1' and `set_nodebug_mode/1',
which accept as argument a file spec (i.e., `library(foo)' or `foo',
even if it is a user file) to be able to load a file in interpreted
mode without changing the set of modules that the debugger will try
to spy.

6.2 The debugging process
=========================

Once modules or user files are marked for debugging and reloaded, the
traditional debugging shell commands can be used (the documentation
of the `debugger' library following this chapter contains all the
commands and their description), with the same meaning as in other
classical Prolog systems. The differences in their behavior are:

   * Debugging takes place only in the modules in which it was
     activated,

   * `nospy/1' and `spy/1' accept sequences of predicate specs, and
     they will search for those predicates only in the modules marked
     for debugging (traditional or source-level debugging).

   * `breakpt/6' and `nobreakpt/6' allow setting breakpoints at
     selected clause literals and will search for those literals only
     in the modules marked for source-level debugging (modules marked
     with `debug_module_source/1').

   In particular, the system is initially in nodebug mode, in which
no tracing is performed. The system can be put in debug mode by a
call to `debug/0' in which execution of queries will proceed until
the first _spy-point_ or _breakpoint_. Alternatively, the system can
be put in trace mode by a call to `trace/0' in which all predicates
will be trace.

6.3 Marking modules and files for debugging with the embedded debugger
======================================================================

The embedded debugger, as the interpreted debugger, has three
different modes of operation: debug, trace or nodebug. These debugger
modes can be set by adding _one_ of the following package
declarations to the module:

     :- use_package(debug).
     :- use_package(trace).
     :- use_package(nodebug).

and recompiling the application. These declarations _must_ appear the
last ones of all `use_package' declarations used. Also it is
possible, as usual, to add the debugging package(s) in the module
declaration using the third argument of the `module/3' declaration
(and they should also be the last ones in the list), i.e., using one
of:

     :- module(..., ..., [..., debug]).
     :- module(..., ..., [..., trace]).
     :- module(..., ..., [..., nodebug]).

   The nodebug mode allows turning off any debugging (and also the
corresponding overhead) but keeping the spy-points and breakpoints in
the code. The trace mode will start the debugger for any predicate in
the file.

   The embedded debugger has limitations over the interpreted
debugger. The most important is that the "retry" option is not
available. But it is possible to add, and remove, spy-points and breakpoins
using the predicates `spy/1', `nospy/1', `breakpt/6' and `nobreakpt/6',
etc. These can be used in a clause declaration or as declarations.
Also it is possible to add in the code predicates for issuing the
debugger (i.e., use debug mode, and in a clause add the predicate `trace/1').
Finally, if a spy declaration is placed on the entry point of an
executable (`:- spy(main/1)') the debugger will not start the first
time `main/1' predicate is called, i.e., at the beginning of program
execution (however, it will if there are any subsequent calls to `main/1').
Starting the embedded debugger at the beginning of the execution of a
program can be done easily however by simply adding the in trace mode.

   Note that there is a particularly interesting way of using the embedded
debugger: 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.

   See the following as a general example of use of the embedded
debugger:
     :- module( foo,[main/1],[assertions, debug]).

     :- entry main/1.

     main(X) :-
              display(X),
              spy(foo),
              foo(X),
              notrace,
              nl.

     foo([]).
     foo([X|T]) :-
             trace,
             bar(X),
             foo(T).

     bar(X) :-
             display(X).

6.4 The procedure box control flow model
========================================

During debugging the interpreter prints out a sequence of goals in
various states of instantiation in order to show the state that the
program has reached in its execution. However, in order to understand
what is occurring it is necessary to understand when and why the
interpreter prints out goals. As in other programming languages, key
points of interest are procedure entry and return, but in Prolog
there is the additional complexity of backtracking. One of the major
confusions that novice Prolog programmers have to face is the
question of what actually happens when a goal fails and the system
suddenly starts backtracking. The Procedure Box model of Prolog
execution views program control flow in terms of movement about the
program text. This model provides a basis for the debugging mechanism
in the interpreter, and enables the user to view the behaviour of the
program in a consistent way. It also provides the basis for the
visualization performed on the source level program when source level
program when source-level debugging is activated within `emacs'.

   Let us look at an example Prolog procedure:

[Image file: autofigbyrdbox.eps]

   The first clause states that `Y' is a descendant of `X' if `Y' is
an offspring of `X', and the second clause states that `Y' is a
descendant of `X' if `Z' is an offspring of `X' and `Y' is a
descendant of `Z'. In the diagram a box has been drawn around the
whole procedure and labelled arrows indicate the control flow in and
out of this box. There are four such arrows which we shall look at in
turn.

   * *Call*

     This arrow represents initial invocation of the procedure. When
     a goal of the form `descendant(X,Y)' is required to be
     satisfied, control passes through the Call port of the
     descendant box with the intention of matching a component clause
     and then satisfying any subgoals in the body of that clause.
     Note that this is independent of whether such a match is
     possible; i.e. first the box is called, and then the attempt to
     match takes place. Textually we can imagine moving to the code
     for descendant when meeting a call to descendant in some other
     part of the code.

   * *Exit*

     This arrow represents a successful return from the procedure.
     This occurs when the initial goal has been unified with one of
     the component clauses and any subgoals have been satisfied.
     Control now passes out of the Exit port of the descendant box.
     Textually we stop following the code for descendant and go back
     to the place we came from.

   * *Redo*

     This arrow indicates that a subsequent goal has failed and that
     the system is backtracking in an attempt to find alternatives to
     previous solutions. Control passes through the Redo port of the
     descendant box. An attempt will now be made to resatisfy one of
     the component subgoals in the body of the clause that last
     succeeded; or, if that fails, to completely rematch the original
     goal with an alternative clause and then try to satisfy any
     subgoals in the body of this new clause. Textually we follow the
     code backwards up the way we came looking for new ways of
     succeeding, possibly dropping down on to another clause and
     following that if necessary.

   * *Fail*

     This arrow represents a failure of the initial goal, which might
     occur if no clause is matched, or if subgoals are never
     satisfied, or if any solution produced is always rejected by
     later processing. Control now passes out of the Fail port of the
     descendant box and the system continues to backtrack. Textually
     we move back to the code which called this procedure and keep
     moving backwards up the code looking for choice points.

   In terms of this model, the information we get about the procedure
box is only the control flow through these four ports. This means
that at this level we are not concerned with which clause matches,
and how any subgoals are satisfied, but rather we only wish to know
the initial goal and the final outcome. However, it can be seen that
whenever we are trying to satisfy subgoals, what we are actually
doing is passing through the ports of _their_ respective boxes. If we
were following this (e.g., activating source-level debugging), then
we would have complete information about the control flow inside the
procedure box.

   Note that the box we have drawn around the procedure should really
be seen as an invocation box. That is, there will be a different box
for each different invocation of the procedure. Obviously, with
something like a recursive procedure, there will be many different
Calls and Exits in the control flow, but these will be for different
invocations. Since this might get confusing each invocation box is
given a unique integer identifier in the messages, as described below.

   Note that not all procedure calls are traced; there are a few
basic predicates which have been made invisible since it is more
convenient not to trace them. These include debugging directives,
basic control structures, and some builtins. This means that messages
will never be printed for these predicates during debugging.

6.5 Format of debugging messages
================================

This section explains the two formats of the message output by the
debugger at a port. All trace messages are output to the terminal
regardless of where the current output stream is directed (which
allows tracing programs while they are performing file I/O). The
basic format, which will be shown in traditional debug and in
source-level debugging within Ciao `emacs' mode, is as follows:

     S  13  7  Call: T user:descendant(dani,_123) ?

   `S' is a spy-point or breakpoint indicator. It is printed as
'`+'', indicating that there is a spy-point on `descendant/2' in
module `user', as `'B'' denoting a breakpoint, or as ' ', denoting no
spy-point or breakpoint. If there is a spy-point and a breakpoint in
the same predicate the spy-point indicator takes preference over
breakpoint indicator.

   `T' is a subterm trace. This is used in conjunction with the `^'
command (set subterm), described below. If a subterm has been
selected, `T' is printed as the sequence of commands used to select
the subterm. Normally, however, `T' is printed as ' ', indicating
that no subterm has been selected.

   The first number is the unique invocation identifier. It is always
nondecreasing (provided that the debugger is switched on) regardless
of whether or not the invocations are being actually seen. This
number can be used to cross correlate the trace messages for the
various ports, since it is unique for every invocation. It will also
give an indication of the number of procedure calls made since the
start of the execution. The invocation counter starts again for every
fresh execution of a command, and it is also reset when retries (see
later) are performed.

   The number following this is the _current depth_; i.e., the number
of direct _ancestors_ this goal has. The next word specifies the
particular port (`Call', `Exit', `Redo' or `Fail'). The goal is then
printed so that its current instantiation state can be inspected. The
final `?' is the prompt indicating that the debugger is waiting for
user interaction. One of the option codes allowed (see below) can be
input at this point.

   The second format, quite similar to the format explained above, is
shown when using source-level debugging outside the Ciao `emacs'
mode, and it is as follows:

     	   In /home/mcarlos/ciao/foo.pl (5-9) descendant-1
     S  13  7  Call: T user:descendant(dani,_123) ?

   This format is identical to the format above except for the first
line, which contains the information for location of the point in the
source program text where execution is currently at. The first line
contains the name of the source file, the start and end lines where
the literal can be found, the substring to search for between those
lines and the number of substrings to locate. This information for
locating the point on the source file is not shown when executing the
source-level debugger from the Ciao `emacs' mode.

   Ports can be "unleashed" by calling the `leash/1' predicate
omiting that port in the argument. This means that the debugger will
stop but user interaction is not possible for an unleashed port.
Obviously, the `?' prompt will not be shown in such messages, since
the user has specified that no interaction is desired at this point.

6.6 Options available during debugging
======================================

This section describes the particular options that are available when
the debugger prompts after printing out a debugging message. All the
options are one letter mnemonics, some of which can be optionally
followed by a decimal integer. They are read from the terminal with
any blanks being completely ignored up to the next terminator
(carriage-return, line-feed, or escape). Some options only actually
require the terminator; e.g., the creep option, only requires <RET>.

   The only option which really needs to be remembered is '`h''
(followed by <RET>). This provides help in the form of the following
list of available options.

     <cr>   creep            c      creep
      l     leap             s      skip
      r     retry            r <i>  retry i
      f     fail             f <i>  fail i
      d     display          p      print
      w     write
      g     ancestors        g <n>  ancestors n
      n     nodebug          =      debugging
      +     spy this         -      nospy this
      a     abort
      @     command          u      unify
      <     reset printdepth < <n>  set printdepth
      ^     reset subterm    ^ <n>  set subterm
      ?     help             h      help

   * `c' ( _creep_)

     causes the debugger to single-step to the very next port and
     print a message. Then if the port is leashed the user is
     prompted for further interaction. Otherwise it continues
     creeping. If leashing is off, creep is the same as leap (see
     below) except that a complete trace is printed on the terminal.

   * `l' ( _leap_)

     causes the interpreter to resume running the program, only
     stopping when a spy-point or breakpoint is reached (or when the
     program terminates). Leaping can thus be used to follow the
     execution at a higher level than exhaustive tracing. All that is
     needed to do is to set spy-points and breakpoints on an evenly
     spread set of pertinent predicates or lines, and then follow the
     control flow through these by leaping from one to the other.

   * `s' ( _skip_)

     is only valid for Call and Redo ports, if it is issued in Exit
     or Fail ports it is equivalent to creep. It skips over the
     entire execution of the predicate. That is, no message will be
     seen until control comes back to this predicate (at either the
     Exit port or the Fail port). Skip is particularly useful while
     creeping since it guarantees that control will be returned after
     the (possibly complex) execution within the box. With skip then
     no message at all will appear until control returns to the Exit
     port or Fail port corresponding to this Call port or Redo port.
     This includes calls to predicates with spy-points and
     breakpoints set: they will be masked out during the skip. There
     is a way of overriding this: the `t' option after a <^C>
     interrupt will disable the masking. Normally, however, this
     masking is just what is required!

   * `r' ( _retry_)

     can be used at any of the four ports (although at the Call port
     it has no effect). It transfers control back to the Call port of
     the box. This allows restarting an invocation when, for example,
     it has left the programmer with some weird result. The state of
     execution is exactly the same as in the original call (unless
     the invocation has performed side effects, which will not be
     undone). When a retry is performed the invocation counter is
     reset so that counting will continue from the current invocation
     number regardless of what happened before the retry. This is in
     accord with the fact that execution has, in operational terms,
     returned to the state before anything else was called.

     If an integer is supplied after the retry command, then this is
     taken as specifying an invocation number and the system tries to
     get to the Call port, not of the current box, but of the
     invocation box specified. It does this by continuously failing
     until it reaches the right place. Unfortunately this process
     cannot be guaranteed: it may be the case that the invocation the
     programmer is looking for has been cut out of the search space
     by cuts in the program. In this case the system fails to the
     latest surviving Call port before the correct one.

   * `f' ( _fail_)

     can be used at any of the four ports (although at the Fail port
     it has no effect). It transfers control to the Fail port of the
     box, forcing the invocation to fail prematurely. If an integer
     is supplied after the command, then this is taken as specifying
     an invocation number and the system tries to get to the Fail
     port of the invocation box specified. It does this by
     continuously failing until it reaches the right place.
     Unfortunately, as before, this process cannot be guaranteed.

   * `d' ( _display_)

     displays the current goal using `display/1'. See `w' below.

   * `p' ( _print_)

     re-prints the current goal using `print/1'. Nested structures
     will be printed to the specified _printdepth_ (see below).

   * `w' ( _write_)

     writes the current goal on the terminal using `write/1'.

   * `g' ( _ancestors_)

     provides a list of ancestors to the current goal, i.e., all
     goals that are hierarchically above the current goal in the
     calling sequence. It is always possible to jump to any goal in
     the ancestor list (by using retry, etc.). If an integer `n' is
     supplied, then only `n' ancestors will be printed. That is to
     say, the last `n' ancestors will be printed counting back from
     the current goal. Each entry in the list is preceded by the
     invocation number followed by the depth number (as would be
     given in a trace message).

   * `n' ( _nodebug_)

     switches the debugger off. Note that this is the correct way to
     switch debugging off at a trace point. The `@' option cannot be
     used because it always returns to the debugger.

   * `=' ( _debugging_)

     outputs information concerning the status of the current
     debugging session.

   * `+' _spy_

     sets a spy-point on the current goal.

   * `-' ( _nospy_)

     removes the spy-point from the current goal.

   * `a' ( _abort_)

     causes an abort of the current execution. All the execution
     states built so far are destroyed and the system is put right
     back at the top-level of the interpreter. (This is the same as
     the built-in predicate `abort/0'.)

   * `@' ( _command_)

     allows calling arbitrary goals. The initial message `| ?- ' will
     be output on the terminal, and a command is then read from the
     terminal and executed as if it was at top-level.

   * `u' ( _unify_()

     is available at the Call port and gives the option of providing
     a solution to the goal from the terminal rather than executing
     the goal. This is convenient, e.g., for providing a "stub" for a
     predicate that has not yet been written. A prompt `|: ' will be
     output on the terminal, and the solution is then read from the
     terminal and unified with the goal.

   * `<' ( _printdepth_)

     sets a limit for the subterm nesting level that is printed in
     messages. While in the debugger, a printdepth is in effect for
     limiting the subterm nesting level when printing the current
     goal. When displaying or writing the current goal, all nesting
     levels are shown. The limit is initially 10. This command,
     without arguments, resets the limit to 10. With an argument of
     `n' the limit is set to `n'.

   * `^' ( _subterm_)

     sets the subterm to be printed in messages. While at a
     particular port, a current subterm of the current goal is
     maintained. It is the current subterm which is displayed,
     printed, or written when prompting for a debugger command. Used
     in combination with the printdepth, this provides a means for
     navigating in the current goal for focusing on the part which is
     of interest. The current subterm is set to the current goal when
     arriving at a new port. This command, without arguments, resets
     the current subterm to the current goal. With an argument of `n'
     (greater than 0 and less or equal to the number of subterms of
     the current subterm), the current subterm is replaced by its
     `n''th subterm. With an argument of `0', the current subterm is
     replaced by its parent term.

   * `?' or `h' ( _help_)

     displays the table of options given above.

6.7 Calling predicates that are not exported by a module
========================================================

The Ciao module system does not allow calling predicates which are
not exported during debugging. However, as an aid during debugging,
this is allowed (only from the top-level and for modules which are in
debug mode or source-level debug mode) using the `call_in_module/2'
predicate.

   Note that this does not affect analysis or optimization issues,
since it only works on modules which are loaded in debug mode or
source-level debug mode, i.e. unoptimized.

6.8 Acknowledgements
====================

Originally written by Andrzej Ciepielewski. Minor modifications by
Mats Carlsson. Later modifications (17 Dec 87) by Takashi Chikayama
(making tracer to use `print/1' rather than `write/1', temporarily
switching debugging flag off while writing trace message and within
"break" level). Additional modifications by Kish Shen (May 88):
subterm navigation, handle unbound args in `spy/1' and `nospy/1',
trapping arithmetics errors in debug mode. Adapted then to &-Prolog
and Ciao by D. Cabeza and included in the Ciao version control
system. Extended for source-level debugging by Manuel C. Rodr'guez.
(See changelog if included in the document for more detailed
documentation of the later changes.)

7 Predicates controlling the interactive debugger
*************************************************

*Author(s):* A. Ciepielewski, M. Carlsson, T. Chikayama, K. Shen, D.
Cabeza, M. Rodriguez.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.7#185 (2002/2/4, 18:45:52 CET)

   This library implements predicates which are normally used in the
interactive top-level shell to debug programs. A subset of them are
available in the embeddable debugger.

7.1 Usage and interface (`debugger')
====================================

   * *Library usage:*

     `:- use_module(library(debugger)).'

   * *Exports:*
        - _Predicates:_

          `debug_module/1', `nodebug_module/1', `debug_module_source/1', `debug/0', `nodebug/0', `trace/0', `notrace/0', `spy/1', `nospy/1', `nospyall/0', `breakpt/6', `nobreakpt/6', `nobreakall/0', `list_breakpt/0', `debugging/0', `leash/1', `maxdepth/1', `call_in_module/2'.

   * *Other modules used:*
        - _System library modules:_

          `debugger/debugger_lib', `format', `ttyout', `read', `system', `write', `aggregates', `sort'.

7.2 Documentation on exports (`debugger')
=========================================

 -- PREDICATE: debug_module/1:
     *Usage:* `debug_module(Module)'
        - _Description:_ The debugger will take into acount module
          `Module' (assuming it is loaded in interpreted mode). When
          issuing this command at the toplevel shell, the compiler is
          instructed also to set to _interpret_ the loading mode of
          files defining that module and also to mark it as
          'modified' so that (re)loading this file or a main file
          that uses this module will force it to be reloaded for
          source-level debugging.

        - _The following properties should hold at call time:_

          `Module' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: nodebug_module/1:
     *Usage:* `nodebug_module(Module)'
        - _Description:_ The debugger will not take into acount
          module `Module'. When issuing this command at the toplevel
          shell, the compiler is instructed also to set to _compile_
          the loading mode of files defining that module.

        - _The following properties should hold at call time:_

          `Module' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: debug_module_source/1:
     *Usage:* `debug_module_source(Module)'
        - _Description:_ The debugger will take into acount module
          `Module' (assuming it is is loaded in source-level debug
          mode). When issuing this command at the toplevel shell, the
          compiler is instructed also to set to _interpret_ the
          loading mode of files defining that module and also to mark
          it as 'modified' so that (re)loading this file or a main
          file that uses this module will force it to be reloaded for
          source-level debugging.

        - _The following properties should hold at call time:_

          `Module' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: debug/0:
     *Usage:*
        - _Description:_ Switches the debugger on. The interpreter
          will stop at all ports of procedure boxes of spied
          predicates.

 -- PREDICATE: nodebug/0:
     *Usage:*
        - _Description:_ Switches the debugger off. If there are any
          spy-points set then they will be kept but disabled.

 -- PREDICATE: trace/0:
     *Usage:*
        - _Description:_ Start tracing, switching the debugger on if
          needed. The interpreter will stop at all leashed ports of
          procedure boxes of predicates either belonging to debugged
          modules or called from clauses of debugged modules. A
          message is printed at each stop point, expecting input from
          the user (write `h' to see the available options).

 -- PREDICATE: notrace/0:
     *Usage:*
        - _Description:_ Equivalent to `nodebug/0'.

 -- PREDICATE: spy/1:
     *Usage:* `spy(PredSpec)'
        - _Description:_ Set spy-points on predicates belonging to
          debugged modules and which match `PredSpec', switching the
          debugger on if needed. This predicate is defined as a
          prefix operator by the toplevel.

        - _The following properties should hold at call time:_

          `PredSpec' is a sequence of `multpredspec's.
          (`basic_props:sequence/2')

 -- PREDICATE: nospy/1:
     *Usage:* `nospy(PredSpec)'
        - _Description:_ Remove spy-points on predicates belonging to
          debugged modules which match `PredSpec'. This predicate is
          defined as a prefix operator by the toplevel.

        - _The following properties should hold at call time:_

          `PredSpec' is a sequence of `multpredspec's.
          (`basic_props:sequence/2')

 -- PREDICATE: nospyall/0:
     *Usage:*
        - _Description:_ Remove all spy-points.

 -- PREDICATE: breakpt/6:
     *Usage:* `breakpt(Pred, Src, Ln0, Ln1, Number, RealLine)'
        - _Description:_ Set a _breakpoint_ in file `Src' between
          lines `Ln0' and `Ln1' at the literal corresponding to the
          `Number''th occurence of (predicate) name `Pred'. The pair
          `Ln0'-`Ln1' uniquely identifies a program clause and must
          correspond to the start and end line numbers for the
          clause. The rest of the arguments provide enough
          information to be able to locate the exact literal that the
          `RealLine' line refers to. This is normally not issued by
          users but rather by the `emacs' mode, which automatically
          computes the different argument after selecting a point in
          the source file.

        - _The following properties should hold at call time:_

          `Pred' is an atom.   (`basic_props:atm/1')

          `Src' is a source name.   (`streams_basic:sourcename/1')

          `Ln0' is an integer.   (`basic_props:int/1')

          `Ln1' is an integer.   (`basic_props:int/1')

          `Number' is an integer.   (`basic_props:int/1')

          `RealLine' is an integer.   (`basic_props:int/1')

 -- PREDICATE: nobreakpt/6:
     *Usage:* `nobreakpt(Pred, Src, Ln0, Ln1, Number, RealLine)'
        - _Description:_ Remove a breakpoint in file `Src' between
          lines `Ln0' and `Ln1' at the `Number''th occurence of
          (predicate) name `Pred' (see `breakpt/6'). Also normally
          used from de `emacs' mode.

        - _The following properties should hold at call time:_

          `Pred' is an atom.   (`basic_props:atm/1')

          `Src' is a source name.   (`streams_basic:sourcename/1')

          `Ln0' is an integer.   (`basic_props:int/1')

          `Ln1' is an integer.   (`basic_props:int/1')

          `Number' is an integer.   (`basic_props:int/1')

          `RealLine' is an integer.   (`basic_props:int/1')

 -- PREDICATE: nobreakall/0:
     *Usage:*
        - _Description:_ Remove all breakpoints.

 -- PREDICATE: list_breakpt/0:
     *Usage:*
        - _Description:_ Prints out the location of all breakpoints.
          The location of the breakpoints is showed usual by
          referring to the source file, the lines between which the
          predicate can be found, the predicate name and the number
          of ocurrence of the predicate name of the literal.

 -- PREDICATE: debugging/0:
     *Usage:*
        - _Description:_ Display debugger state.

 -- PREDICATE: leash/1:
     *Usage:* `leash(Ports)'
        - _Description:_ Leash on ports `Ports', some of `call',
          `exit', `redo', `fail'. By default, all ports are on leash.

        - _The following properties should hold at call time:_

          `Ports' is a list of `port's.   (`basic_props:list/2')

 -- PREDICATE: maxdepth/1:
     *Usage:* `maxdepth(MaxDepth)'
        - _Description:_ Set maximum invocation depth in debugging to
          `MaxDepth'. Calls to compiled predicates are not included
          in the computation of the depth.

        - _The following properties should hold at call time:_

          `MaxDepth' is an integer.   (`basic_props:int/1')

 -- PREDICATE: call_in_module/2:
     *Usage:* `call_in_module(Module, Predicate)'
        - _Description:_ Calls predicate `Predicate' belonging to
          module `Module', even if that module does not export the
          predicate. This only works for modules which are in debug
          (interpreted) mode (i.e., they are not optimized).

        - _The following properties should hold at call time:_

          `Module' is an atom.   (`basic_props:atm/1')

          `Predicate' is a term which represents a goal, i.e., an
          atom or a structure.   (`basic_props:callable/1')

7.3 Documentation on internals (`debugger')
===========================================

 -- PROPERTY: multpredspec/1:
     A property, defined as follows:
               multpredspec(Mod:Spec) :-
                       atm(Mod),
                       multpredspec(Spec).
               multpredspec(Name/Low-High) :-
                       atm(Name),
                       int(Low),
                       int(High).
               multpredspec(Name/(Low-High)) :-
                       atm(Name),
                       int(Low),
                       int(High).
               multpredspec(Name/Arity) :-
                       atm(Name),
                       int(Arity).
               multpredspec(Name) :-
                       atm(Name).

7.4 Known bugs and planned improvements (`debugger')
====================================================

   * Add an option to the emacs menu to automatically select all
     modules in a project.

   * Consider the possibility to show debugging messages directly in
     the source code emacs buffer.

8 The script interpreter
************************

*Author(s):* Daniel Cabeza, Manuel Hermenegildo.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.5#130 (2000/5/3, 20:19:4 CEST)

   `ciao-shell' is the Ciao script interpreter. It can be used to
write _Prolog shell scripts_ (see [Her96,CHV96b]), that is,
executable files containing source code, which are compiled on demand.

   Writing Prolog scripts can sometimes be advantageous with respect
to creating binary executables for small- to medium-sized programs
that are modified often and perform relatively simple tasks. The
advantage is that no explicit compilation is necessary, and thus
changes and updates to the program imply only editing the source
file. The disadvantage is that startup of the script (the first time
after it is modified) is slower than for an application that has been
compiled previously.

   An area of application is, for example, writing _CGI executables_:
the slow speed of the network connection in comparison with that of
executing a program makes program execution speed less important and
has made scripting languages very popular for writing these
applications. Logic languages are, a priori, excellent candidates to
be used as scripting languages. For example, the built-in grammars
and databases can sometimes greatly simplify many typical
script-based applications.

8.1 How it works
================

Essentially, `ciao-shell' is a smaller version of the Ciao top-level,
which starts by loading the file given to it as the first argument
and then starts execution at `main/1' (the argument is instantiated
to a list containing the command line options, in the usual way).
Note that the Prolog script cannot have a `module' declaration for
this to work. While loading the file, `ciao-shell' changes the prolog
flag `quiet' so that no informational or warning messages are printed
(error messages will be reported to `user_error', however). The
operation of `ciao-shell' in Unix-like systems is based in a special
compiler feature: when the first character of a file is '`#'', the
compiler skips the first lines until an empty line is found. In
Windows, its use is as easy as naming the file with a `.pls'
extension, which will launch `ciao-shell' appropriately.

   For example, in a Linux/Unix system, assume a file called `hello'
contains the following program:

     #!/bin/sh
     exec ciao-shell $0 "$@" # -*- mode: ciao; -*-

     main(_) :-
          write('Hello world'), nl.

   Then, the file `hello' can be _run_ by simply making it executable
and invoking it from the command line:

     /herme@clip:/tmp
     [86]> chmod +x hello

     /herme@clip:/tmp
     [87]> hello
     Hello world

   The line:
     #!/bin/sh
   invokes the `/bin/sh' shell which will interpret the following
line:
     exec ciao-shell $0 "$@" # -*- mode: ciao; -*-

and invoke `ciao-shell', instructing it to read this same file
(`$0'), passing it the rest of the arguments to `hello' as arguments
to the prolog program. The second part of the line `# -*- mode: ciao;
-*-' is simply a comment which is seen by `emacs' and instructs it to
edit this file in Ciao mode (this is needed because these script
files typically do not have a `.pl' ending). When `ciao-shell'
starts, if it is the first time, it compiles the program (skipping
the first lines, as explained above), or else at successive runs
loads the `.po' object file, and then calls `main/1'.

   Note that the process of creating Prolog scripts is made very
simple by the Ciao emacs mode, which automatically inserts the header
and makes the file executable (See Using Ciao inside GNU emacs).

8.2 Command line arguments in scripts
=====================================

The following example illustrates the use of command-line arguments
in scripts. Assume that a file called `say' contains the following
lines:

     #!/bin/sh
     exec ciao-shell $0 "$@" # -*- mode: ciao; -*-

     main(Argv) :-
          write_list(Argv), nl.

     write_list([]).
     write_list([Arg|Args]) :-
          write(Arg),
          write(' '),
          write_list(Args).

An example of use is:

     /herme@clip:/tmp
     [91]> say hello dolly
     hello dolly

9 Customizing library paths and path aliases
********************************************

*Author(s):* Daniel Cabeza.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#189 (2003/12/19, 16:8:47 CET)

   This library provides means for customizing, from environment
variables, the libraries and path aliases known by an executable.
Many applications of Ciao, including `ciaoc', `ciaosh', and `ciao-shell'
make use of this library. Note that if an executable is created
dynamic, it will try to load its components at startup, before the
procedures of this module can be invoked, so in this case all the
components should be in standard locations.

9.1 Usage and interface (`libpaths')
====================================

   * *Library usage:*

     `:- use_module(library(libpaths)).'

   * *Exports:*
        - _Predicates:_

          `get_alias_path/0'.

        - _Multifiles:_

          `file_search_path/2', `library_directory/1'.

   * *Other modules used:*
        - _System library modules:_

          `system', `lists'.

9.2 Documentation on exports (`libpaths')
=========================================

 -- PREDICATE: get_alias_path/0:
     `get_alias_path(get_alias_path'

     Consult the environment variable 'CIAOALIASPATH' and add facts
     to predicates `library_directory/1' and `file_search_path/2' to
     define new library paths and path aliases. The format of
     'CIAOALIASPATH' is a sequence of paths or alias assignments
     separated by colons, an alias assignment is the name of the
     alias, an '=' and the path represented by that alias (no blanks
     allowed). For example, given
             CIAOALIASPATH=/home/bardo/ciao:contrib=/usr/local/lib/ciao
     the predicate will define /home/bardo/ciao as a library path and
     /usr/local/lib/ciao as the path represented by 'contrib'.

9.3 Documentation on multifiles (`libpaths')
============================================

 -- PREDICATE: file_search_path/2:
     See Basic file/stream handling.

     The predicate is _multifile_.

     The predicate is of type _dynamic_.

 -- PREDICATE: library_directory/1:
     See Basic file/stream handling.

     The predicate is _multifile_.

     The predicate is of type _dynamic_.

10 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:

   * _Syntax-based highlighting_ (coloring), _auto-indentation_, _auto-fill_,
     etc. of code. This includes the assertions used by the
     preprocessor and the documentation strings used by the Ciao
     auto-documenter, `lpdoc'.

   * Providing automatic access to on-line help for all predicates by
     accessing the Ciao system manuals in `info' format.

   * Starting and communicating with `ciaopp', the _Ciao
     preprocessor_, running in its own sub-shell. This allows easily
     performing certain kinds of _static checks_ (useful for finding
     errors in programs before running them), program analysis tasks,
     and _program transformations_ on source programs.

   * Starting and communicating with the _Ciao top-level_, running in
     its own sub-shell. This facilitates loading programs, checking
     the _syntax_ of programs (and of _assertions_ within programs),
     marking and unmarking modules for interactive debugging, _tracing
     the source code_ during debugging, making stand-alone
     executables, compiling modules to dynamically linkable Prolog
     objects, compiling modules to active objects, etc.

   * Syntax highlighting and coloring of the error and warning
     messages produced by the top level, preprocessor, or any other
     tool using the same message format (such as the `lpdoc'
     auto-documenter), and _locating automatically the points in the
     source files where such errors occur_.

   * Performing automatic _version control_ and keeping a _changelog_
     of individual files or whole applications. This is done by
     automatically including changelog entries in source files, which
     can then be processed by the `lpdoc' auto-documenter.

   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.

10.1 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:

   * Clauses should begin on the first column (this is used to
     recognize the beginning of a clause).

   * C style comments should not be used in a clause, but can be used
     outside any clause.

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

   * Body literals should be indented. There should be not more than
     one literal per line. This allows more precision in the location
     of program points during source-level debugging, i.e., when
     marking breakpoints and during line tracing.

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

10.2 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 Installation of the Ciao/Prolog emacs interface
later in this chapter.

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

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

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

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

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

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

10.9 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 The script interpreter
     for details.

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

10.11 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:

   * _Inference of properties_ of the predicates and literals of the
     progam, including _types_, _modes_ and other _variable
     instantiation_ properties, _non-failure_, _determinacy_, bounds
     on _computational cost_, bounds on _sizes of terms_ in the
     program, etc.

   * Certain kinds of _static debugging_, finding errors before
     running the program. This includes checking the ways in which
     programs call the system library predicates and also _checking
     the assertions_ present in the program or in other modules used
     by the program. Such assertions essentially represent partial _specifications_
     of the program.

   * Several kinds of source to source _program transformations_ such
     as _program specialization_, _program parallelization_ (including _granularity
     control_), inclusion of _run-time tests_ for assertions which
     cannot be checked completely at compile-time, etc.

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

10.12 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:

   * a _version number_ (such as, e.g., `1.2', where `1' is the major
     version number and `2' is the minor version number),

   * a patch number (such as, e.g., the `4' in `1.2#4'),

   * a time stamp (such as, e.g., `1998/12/14,17:20*28+MET'),

   * the author of the change, and

   * a comment explaining the change.

   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:*

        * If a changelog entry is in fact introduced, the cursor is
          left at the point in the file where the comment was
          inserted and the mark is left at the original file point.
          This allows inspecting (and possibly modifying) the
          changelog entry, and then returning to the original point
          in the file by simply typing C-x C-x.

        * The first changelog entry is entered by default at the end
          of the buffer. Later, the changelog entries can be moved
          anywhere else in the file. New changelog entries are always
          inserted just above the first changelog entry which appears
          in the file.

        * The comments in changelog entries can be edited at any time.

        * If a changelog entry is moved to another file, and version
          numbers are shared by several files through a directory,
          the corresponding file pointer in the
          `<directory_name>/GlobalChangeLog' file needs to be changed
          also, for the entry to be locatable later using C-c C-n.

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

        * If in a source file, find the next changelog entry in the
          source file, open in another window the corresponding `GlobalChangeLog'
          file, and position the cursor at the corresponding entry.
          This allows browsing the previous and following changes
          made, which may perhaps reside in other files in the system.

        * If in a `GlobalChangeLog' file, look for the next entry in
          the file, and open in another window the source file in
          which the corresponding comment resides, positioning the
          corresponding comment at the top of the screen. This allows
          going through a section of the `GlobalChangeLog' file
          checking all the corresponding comments in the different
          files in which they occur.

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

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

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

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

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

10.18 Getting the Ciao/Prolog mode version
==========================================

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

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

10.20 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'.

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

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

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

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

10.21 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 (see Installing Ciao from the source distribution
or Installing Ciao from a Win32 binary distribution)
for details.

10.22 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'.

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

PART II - The Ciao basic language (engine)
******************************************

*Author(s):* The Clip Group.

   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.

11 The module system
********************

*Author(s):* Daniel Cabeza and the CLIP Group.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#28 (2002/11/20, 14:3:5 CET)

   Modularity is a basic notion in a modern computer language.
Modules allow dividing programs in several parts, which have its own
independent name spaces. The module system in Ciao [CH00a], as in
many other Prolog implementations, is procedure based. This means
that predicate names are local to a module, but functor/atom names in
data are shared.

   The predicates visible in a module are the predicates defined in
that module, plus the predicates imported from other modules. Only
predicates exported by a module can be imported from other modules.
The default module of a given predicate name is the local one if the
predicate is defined locally, else the last module from which the
predicate is imported, having explicit imports priority (that is, a
predicate imported by an `use_module/2' declaration is always
preferred above a predicate imported by an `use_module/1'
declaration). To refer to a predicate from a module which is not the
default for that predicate the name has to be module qualified. A
module qualified predicate name has the form `Module':`Predicate' as
in the call `debugger:debug_module(M)'. Note that this does not allow
having access to predicates not imported, nor defining clauses of
other modules.

   All predicates defined in files with no module declaration belong
to a special module called `user', and all are implicitly exported.
This allows dividing programs in several files without being aware of
the module system at all. Note that this feature is only supported
for compatibility reasons, being its use discouraged. Many attractive
compilation features of Ciao cannot be performed in `user' modules.

   The case of multifile predicates (defined with the declaration `multifile/1')
is also special. Multifile predicates can be defined by clauses
distributed in several modules, and all modules which define a
predicate as multifile can use that predicate. The name space of
multifile predicates is independent, as if they belonged to special
module `multifile'.

   Every `user' or module file imports implicitly a number of modules
called builtin modules. They are imported before all other
importations of the module, allowing thus redefining any of their
predicates (with the exception of `true/0') by defining local
versions or importing them from other modules. Importing explicitly
from a builtin module, however, disables the implicit importation of
the rest (this feature is used by package `library(pure)' to define
pure prolog code).

11.1 Usage and interface (`modules')
====================================

   * *Library usage:*

     Modules are an intrinsic feature of Ciao, so nothing special has
     to be done to use them.

11.2 Documentation on internals (`modules')
===========================================

 -- DECLARATION: module/3:
     *Usage:* :- `module(Name, Exports, Packages)'.
        - _Description:_ Declares a module of name `Name' which
          exports the predicates in `Exports', and uses the packages
          in `Packages'. `Name' must match with the name of the file
          where the module resides, without extension. For each
          source in `Packages', a package file is included, as if by
          an `include/1' declaration. If the source is specified with
          a path alias, this is the file included, if it is an atom,
          the library paths are searched. Package files provide
          functionalities by declaring imports from other modules,
          defining operators, new declarations, translations of code,
          etc.

          This directive must appear the first in the file.

          Also, if the compiler finds an unknown declaration as the
          first term in a file, the name of the declaration is
          regarded as a package library to be included, and the
          arguments of the declaration (if present) are interpreted
          like the arguments of `module/3'.

        - _The following properties hold at call time:_

          `Name' is a module name (an atom).
          (`modules:modulename/1')

          `Exports' is a list of `predname's.   (`basic_props:list/2')

          `Packages' is a list of `sourcename's.
          (`basic_props:list/2')

 -- DECLARATION: module/2:
     *Usage:* :- `module(Name, Exports)'.
        - _Description:_ Same as directive `module/3', with an
          implicit package `default'.

        - _The following properties hold at call time:_

          `Name' is a module name (an atom).
          (`modules:modulename/1')

          `Exports' is a list of `predname's.   (`basic_props:list/2')

 -- DECLARATION: export/1:
     *Usage 1:* :- `export(Pred)'.
        - _Description:_ Adds `Pred' to the set of exported
          predicates.

        - _The following properties hold at call time:_

          `Pred' is a Name/Arity structure denoting a predicate name:
               predname(P/A) :-
                       atm(P),
                       nnegint(A).

          (`basic_props:predname/1')

     *Usage 2:* :- `export(Exports)'.
        - _Description:_ Adds `Exports' to the set of exported
          predicates.

        - _The following properties hold at call time:_

          `Exports' is a list of `predname's.   (`basic_props:list/2')

 -- DECLARATION: use_module/2:
     *Usage:* :- `use_module(Module, Imports)'.
        - _Description:_ Specifies that this code imports from the
          module defined in `Module' the predicates in `Imports'. The
          imported predicates must be exported by the other module.

        - _The following properties hold at call time:_

          `Module' is a source name.   (`streams_basic:sourcename/1')

          `Imports' is a list of `predname's.   (`basic_props:list/2')

 -- DECLARATION: use_module/1:
     *Usage:* :- `use_module(Module)'.
        - _Description:_ Specifies that this code imports from the
          module defined in `Module' all the predicates exported by
          it. The previous version with the explicit import list is
          preferred to this as it minimizes the chances to have to
          recompile this code if the other module changes.

        - _The following properties hold at call time:_

          `Module' is a source name.   (`streams_basic:sourcename/1')

 -- DECLARATION: import/2:
     *Usage:* :- `import(Module, Imports)'.
        - _Description:_ Declares that this code imports from the
          module with name `Module' the predicates in `Imports'.

          *Important note:* this declaration is intended to be used
          when the current module or the imported module is going to
          be dynamically loaded, and so the compiler does not include
          the code of the imported module in the current executable
          (if only because the compiler cannot know the location of
          the module file at the time of compilation). For the same
          reason the predicates imported are not checked to be
          exported by `Module'. Its use in other cases is strongly
          discouraged, as it disallows many compiler optimizations.

        - _The following properties hold at call time:_

          `Module' is a module name (an atom).
          (`modules:modulename/1')

          `Imports' is a list of `predname's.   (`basic_props:list/2')

 -- DECLARATION: reexport/2:
     *Usage:* :- `reexport(Module, Preds)'.
        - _Description:_ Specifies that this code reexports from the
          module defined in `Module' the predicates in `Preds'. This
          implies that this module imports from the module defined in
          `Module' the predicates in `Preds', an also that this
          module exports the predicates in `Preds' .

        - _The following properties hold at call time:_

          `Module' is a source name.   (`streams_basic:sourcename/1')

          `Preds' is a list of `predname's.   (`basic_props:list/2')

 -- DECLARATION: reexport/1:
     *Usage:* :- `reexport(Module)'.
        - _Description:_ Specifies that this code reexports from the
          module defined in `Module' all the predicates exported by
          it. This implies that this module imports from the module
          defined in `Module' all the predicates exported by it, an
          also that this module exports all such predicates .

        - _The following properties hold at call time:_

          `Module' is a source name.   (`streams_basic:sourcename/1')

 -- DECLARATION: meta_predicate/1:
     *Usage:* :- `meta_predicate MetaSpecs'.
        - _Description:_ Specifies that the predicates in `MetaSpecs'
          have arguments which represent predicates and thus have to
          be module expanded. The directive is only mandatory for
          exported predicates (in modules). This directive is defined
          as a prefix operator in the compiler.

        - _The following properties hold at call time:_

          `MetaSpecs' is a sequence of `metaspec's.
          (`basic_props:sequence/2')

 -- REGTYPE: modulename/1:
     A module name is an atom, not containing characters `:' or `$'.
     Also, `user' and `multifile' are reserved, as well as the module
     names of all builtin modules (because in an executable all
     modules must have distinct names).

     *Usage:* `modulename(M)'
        - _Description:_ `M' is a module name (an atom).

 -- REGTYPE: metaspec/1:
     A meta-predicate specification for a predicate is the functor of
     that predicate applied to atoms which represent the kind of
     module expansion that should be done with the arguments.
     Possible contents are represented as:

    `goal'
          This argument will be a term denoting a goal (either a
          simple or complex one) which will be called. For
          commpatibility reasons it can be named as `:' as well.

    `clause'
          This argument will be a term denoting a clause.

    `fact'
          This argument should be instantiated to a term denoting a
          fact (head-only clause).

    `spec'
          This argument should be instantiated to a predicate name,
          as Functor/Arity.

    `pred(_N_)'
          This argument should be instantiated to a predicate
          construct to be called by means of a `call/_N_' predicate
          call (see `call/2').

    `addmodule'
          This is in fact is not a real meta-data specification. It
          specifies that in an argument added after this one will be
          passed the calling module, to allow handling more involved
          meta-data (e.g., lists of goals) by using conversion
          builtins.

    `?,+,-,_'
          These other values denote that this argument is not module
          expanded.

     *Usage:* `metaspec(M)'
        - _Description:_ `M' is a meta-predicate specification.

12 Directives for using code in other files
*******************************************

*Author(s):* Daniel Cabeza.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#30 (2002/11/20, 14:15:12 CET)

   Documentation for the directives used to load code into Ciao
Prolog (both from the toplevel shell and by other modules).

12.1 Usage and interface (`loading_code')
=========================================

   * *Library usage:*

     These directives are builtin in Ciao, so nothing special has to
     be done to use them.

12.2 Documentation on internals (`loading_code')
================================================

 -- DECLARATION: ensure_loaded/1:
     *Usage:* :- `ensure_loaded(File)'.  < * ISO * >
        - _Description:_ Specifies that the code present in `File'
          will be included in the executable being prepared, in the
          `user' module. The file `File' cannot have a module
          declaration. This directive is intended to be used by
          programs not divided in modules. Dividing programs into
          modules is however strongly encouraged, since most of the
          attractive features of Ciao (such as static debugging and
          global optimization) are only partially available for
          `user' modules.

        - _The following properties should hold at call time:_

          `File' is a source name.   (`streams_basic:sourcename/1')

 -- DECLARATION: include/1:
     *Usage:* :- `include(File)'.  < * ISO * >
        - _Description:_ The contents of the file `File' are included
          in the current program text exactly as if they had been
          written in place of this directive.

        - _The following properties should hold at call time:_

          `File' is a source name.   (`streams_basic:sourcename/1')

 -- DECLARATION: use_package/1:
     :- `use_package(Package)'.

     Specifies the use in this file of the packages defined in
     `Package'. See the description of the third argument of `module/3'
     for an explanation of package files.

     This directive must appear the first in the file, or just after a `module/3'
     declaration. A file with no module declaration, in the absence
     of this directive, uses an implicit package `default' (see
     Other predicates and features defined by default).

     *Usage 1:* :- `use_package(Package)'.
        - _The following properties should hold at call time:_

          `Package' is a source name.   (`streams_basic:sourcename/1')

     *Usage 2:* :- `use_package(Package)'.
        - _The following properties should hold at call time:_

          `Package' is a list of `sourcename's.
          (`basic_props:list/2')

13 Control constructs/predicates
********************************

*Author(s):* Daniel Cabeza, Manuel Hermenegildo.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#316 (2004/2/25, 19:16:1 CET)

   This module contains the set of basic control predicates, except
the predicates dealing with exceptions, which are in Exception handling.

13.1 Usage and interface (`basiccontrol')
=========================================

   * *Library usage:*

     These predicates/constructs are builtin in Ciao, so nothing
     special has to be done to use them. In fact, as they are
     hardwired in some parts of the system, most of them cannot be
     redefined.

   * *Exports:*
        - _Predicates:_

          `,/2', `;/2', `->/2', `!/0', `\+/1', `if/3', `true/0', `fail/0', `repeat/0', `call/1'.

13.2 Documentation on exports (`basiccontrol')
==============================================

 -- PREDICATE: ,/2:
     `P , Q'

     Conjunction (`P' _and_ `Q').

 -- PREDICATE: ;/2:
     `P ; Q'

     Disjunction (`P' _or_ `Q').

 -- PREDICATE: ->/2:
     `P -> Q'

     If `P' then `Q' else fail, using first solution of `P' only.
     Also, `('`P' `->' `Q' `;' `R'`)', if `P' then `Q' else `R',
     using first solution of `P' only. No cuts are allowed in `P'.

 -- PREDICATE: !/0:
     *Usage:* < * ISO * >
        - _Description:_ Commit to any choices taken in the current
          predicate.

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: \+/1:
     `\+ P'

     Goal `P' is not provable (negation by failure). Fails if `P' has
     a solution, and succeeds otherwise. No cuts are allowed in `P'.

     _Meta-predicate_ with arguments: `\+goal'.

     *General properties:* `\+ X'
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP as `not(X)'.
          (`basic_props:native/2')

 -- PREDICATE: if/3:
     `if(P, Q, R)'

     If `P' then `Q' else `R', exploring all solutions of `P'. No
     cuts are allowed in `P'.

 -- PREDICATE: true/0:
     *Usage:* < * ISO * >
        - _Description:_ Succeed (noop).

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: fail/0:
     *Usage:* < * ISO * >
        - _Description:_ Fail, backtrack immediately.

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: repeat/0:
     *Usage:* < * ISO * >
        - _Description:_ Generates an infinite sequence of
          backtracking choices.

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: call/1:
     `call(G)'

     Executes goal `G', restricting the scope of the cuts to the
     execution of `G'. Equivalent to writing a variable `G' in a goal
     position.

     _Meta-predicate_ with arguments: `call(goal)'.

13.3 Documentation on internals (`basiccontrol')
================================================

 -- PREDICATE: |/2:
     An alias for disjunction (when appearing outside a list). The
     alias is performed when terms are read in.

14 Basic builtin directives
***************************

*Author(s):* Daniel Cabeza.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#29 (2002/11/20, 14:4:17 CET)

   This chapter documents the basic builtin directives in Ciao,
additional to the documented in other chapters. These directives are
natively interpreted by the Ciao compiler ( `ciaoc').

   Unlike in other Prolog systems, directives in Ciao are not goals
to be _executed_ by the compiler or top level. Instead, they are
_read_ and acted upon by these programs. The advantage of this is
that the effect of the directives is consistent for executables, code
loaded in the top level, code analyzed by the preprocessor, etc.

   As a result, by default only the builtin directives or
declarations defined in this manual can be used in user programs.
However, it is possible to define new declarations using the `new_declaration/1'
and `new_declaration/2' directives (or using packages including
them). Also, packages may define new directives via code translations.

14.1 Usage and interface (`builtin_directives')
===============================================

   * *Library usage:*

     These directives are builtin in Ciao, so nothing special has to
     be done to use them.

14.2 Documentation on internals (`builtin_directives')
======================================================

 -- DECLARATION: multifile/1:
     *Usage:* :- `multifile Predicates'.  < * ISO * >
        - _Description:_ Specifies that each predicate in
          `Predicates' may have clauses in more than one file. Each
          file that contains clauses for a multifile predicate must
          contain a directive multifile for the predicate. The
          directive should precede all clauses of the affected
          predicates. This directive is defined as a prefix operator
          in the compiler.

        - _The following properties should hold at call time:_

          `Predicates' is a sequence or list of `predname's.
          (`basic_props:sequence_or_list/2')

 -- DECLARATION: discontiguous/1:
     *Usage:* :- `discontiguous Predicates'.  < * ISO * >
        - _Description:_ Specifies that each predicate in
          `Predicates' may be defined in this file by clauses which
          are not in consecutive order. Otherwise, a warning is
          signaled by the compiler when clauses of a predicate are
          not consecutive (this behavior is controllable by the prolog
          flag _discontiguous_warnings_). The directive should
          precede all clauses of the affected predicates. This
          directive is defined as a prefix operator in the compiler.

        - _The following properties should hold at call time:_

          `Predicates' is a sequence or list of `predname's.
          (`basic_props:sequence_or_list/2')

 -- DECLARATION: impl_defined/1:
     *Usage:* :- `impl_defined(Predicates)'.
        - _Description:_ Specifies that each predicate in
          `Predicates' is _impl_icitly _defined_ in the current
          prolog source, either because it is a builtin predicate or
          because it is defined in a C file. Otherwise, a warning is
          signaled by the compiler when an exported predicate is not
          defined in the module or imported from other module.

        - _The following properties should hold at call time:_

          `Predicates' is a sequence or list of `predname's.
          (`basic_props:sequence_or_list/2')

 -- DECLARATION: redefining/1:
     *Usage:* :- `redefining(Predicate)'.
        - _Description:_ Specifies that this module redefines
          predicate `Predicate', also imported from other module, or
          imports it from more than one module. This prevents the
          compiler giving warnings about redefinitions of that
          predicate. `Predicate' can be partially (or totally)
          uninstantiated, to allow disabling those warnings for
          several (or all) predicates at once.

        - _The following properties should hold at call time:_

          `Predicate' is _compatible_ with `predname'
          (`basic_props:compat/2')

 -- DECLARATION: initialization/1:
     *Usage:* :- `initialization(Goal)'.  < * ISO * >
        - _Description:_ `Goal' will be executed at the start of the
          execution of any program containing the current code. The
          initialization of a module/file never runs before the
          initializations of the modules from which the module/file
          imports (excluding circular dependences).

        - _The following properties should hold at call time:_

          `Goal' is a term which represents a goal, i.e., an atom or
          a structure.   (`basic_props:callable/1')

 -- DECLARATION: on_abort/1:
     *Usage:* :- `on_abort(Goal)'.
        - _Description:_ `Goal' will be executed after an abort of
          the execution of any program containing the current code.

        - _The following properties should hold at call time:_

          `Goal' is a term which represents a goal, i.e., an atom or
          a structure.   (`basic_props:callable/1')

15 Basic data types and properties
**********************************

*Author(s):* Daniel Cabeza, Manuel Hermenegildo.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#93 (2003/7/29, 17:53:15 CEST)

   This library contains the set of basic properties used by the
builtin predicates, and which constitute the basic data types and
properties of the language. They can be used both as type testing
builtins within programs (by calling them explicitly) and as
properties in assertions.

15.1 Usage and interface (`basic_props')
========================================

   * *Library usage:*

     These predicates are builtin in Ciao, so nothing special has to
     be done to use them.

   * *Exports:*
        - _Properties:_

          `member/2', `compat/2', `iso/1', `not_further_inst/2', `sideff/2', `regtype/1', `native/1', `native/2'.

        - _Regular Types:_

          `term/1', `int/1', `nnegint/1', `flt/1', `num/1', `atm/1', `struct/1', `gnd/1', `constant/1', `callable/1', `operator_specifier/1', `list/1', `list/2', `sequence/2', `sequence_or_list/2', `character_code/1', `string/1', `predname/1', `atm_or_atm_list/1'.

15.2 Documentation on exports (`basic_props')
=============================================

 -- REGTYPE: term/1:
     The most general type (includes all possible terms).

     *Usage:* `term(X)'
        - _Description:_ `X' is any term.

 -- REGTYPE: int/1:
     The type of integers. The range of integers is `[-2^2147483616,
     2^2147483616)'. Thus for all practical purposes, the range of
     integers can be considered infinite.

     *Usage:* `int(T)'
        - _Description:_ `T' is an integer.

 -- REGTYPE: nnegint/1:
     The type of non-negative integers, i.e., natural numbers.

     *Usage:* `nnegint(T)'
        - _Description:_ `T' is a non-negative integer.

 -- REGTYPE: flt/1:
     The type of floating-point numbers. The range of floats is the
     one provided by the C `double' type, typically `[4.9e-324,
     1.8e+308]' (plus or minus). There are also three special values:
     Infinity, either positive or negative, represented as `1.0e1000'
     and `-1.0e1000'; and Not-a-number, which arises as the result of
     indeterminate operations, represented as `0.Nan'

     *Usage:* `flt(T)'
        - _Description:_ `T' is a float.

 -- REGTYPE: num/1:
     The type of numbers, that is, integer or floating-point.

     *Usage:* `num(T)'
        - _Description:_ `T' is a number.

 -- REGTYPE: atm/1:
     The type of atoms, or non-numeric constants. The size of atoms
     is unbound.

     *Usage:* `atm(T)'
        - _Description:_ `T' is an atom.

 -- REGTYPE: struct/1:
     The type of compound terms, or terms with non-zeroary functors.
     By now there is a limit of 255 arguments.

     *Usage:* `struct(T)'
        - _Description:_ `T' is a compound term.

 -- REGTYPE: gnd/1:
     The type of all terms without variables.

     *Usage:* `gnd(T)'
        - _Description:_ `T' is ground.

 -- REGTYPE: constant/1:
     *Usage:* `constant(T)'
        - _Description:_ `T' is an atomic term (an atom or a number).

 -- REGTYPE: callable/1:
     *Usage:* `callable(T)'
        - _Description:_ `T' is a term which represents a goal, i.e.,
          an atom or a structure.

 -- REGTYPE: operator_specifier/1:
     The type and associativity of an operator is described by the
     following mnemonic atoms:

    `xfx'
          Infix, non-associative: it is a requirement that both of
          the two subexpressions which are the arguments of the
          operator must be of _lower_ precedence than the operator
          itself.

    `xfy'
          Infix, right-associative: only the first (left-hand)
          subexpression must be of lower precedence; the right-hand
          subexpression can be of the _same_ precedence as the main
          operator.

    `yfx'
          Infix, left-associative: same as above, but the other way
          around.

    `fx'
          Prefix, non-associative: the subexpression must be of
          _lower_ precedence than the operator.

    `fy'
          Prefix, associative: the subexpression can be of the _same_
          precedence as the operator.

    `xf'
          Postfix, non-associative: the subexpression must be of
          _lower_ precedence than the operator.

    `yf'
          Postfix, associative: the subexpression can be of the
          _same_ precedence as the operator.

     *Usage:* `operator_specifier(X)'
        - _Description:_ `X' specifies the type and associativity of
          an operator.

 -- REGTYPE: list/1:
     A list is formed with successive applications of the functor
     `'.'/2', and its end is the atom `[]'. Defined as
          list([]).
          list([_1|L]) :-
                  list(L).

     *Usage:* `list(L)'
        - _Description:_ `L' is a list.

 -- REGTYPE: list/2:
     `list(L, T)'

     `L' is a list, and for all its elements, `T' holds.

     _Meta-predicate_ with arguments: `list(?,pred(1))'.

     *Usage:* `list(L, T)'
        - _Description:_ `L' is a list of `T's.

 -- PROPERTY: member/2:
     *Usage:* `member(X, L)'
        - _Description:_ `X' is an element of `L'.

 -- REGTYPE: sequence/2:
     A sequence is formed with zero, one or more occurrences of the
     operator `','/2'. For example, `a, b, c' is a sequence of three
     atoms, `a' is a sequence of one atom.

     _Meta-predicate_ with arguments: `sequence(?,pred(1))'.

     *Usage:* `sequence(S, T)'
        - _Description:_ `S' is a sequence of `T's.

 -- REGTYPE: sequence_or_list/2:
     _Meta-predicate_ with arguments: `sequence_or_list(?,pred(1))'.

     *Usage:* `sequence_or_list(S, T)'
        - _Description:_ `S' is a sequence or list of `T's.

 -- REGTYPE: character_code/1:
     *Usage:* `character_code(T)'
        - _Description:_ `T' is an integer which is a character code.

        - _The following properties hold upon exit:_

          `T' is an integer.   (`basic_props:int/1')

 -- REGTYPE: string/1:
     A string is a list of character codes. The usual syntax for
     strings `"string"' is allowed, which is equivalent to
     `[0's,0't,0'r,0'i,0'n,0'g]' or `[115,116,114,105,110,103]'.
     There is also a special Ciao syntax when the list is not
     complete: `"st"||R' is equivalent to `[0's,0't|R]'.

     *Usage:* `string(T)'
        - _Description:_ `T' is a string (a list of character codes).

        - _The following properties hold upon exit:_

          `T' is a list of `character_code's.   (`basic_props:list/2')

 -- REGTYPE: predname/1:
     *Usage:* `predname(P)'
        - _Description:_ `P' is a Name/Arity structure denoting a
          predicate name:
               predname(P/A) :-
                       atm(P),
                       nnegint(A).

 -- REGTYPE: atm_or_atm_list/1:
     *Usage:* `atm_or_atm_list(T)'
        - _Description:_ `T' is an atom or a list of atoms.

 -- PROPERTY: compat/2:
     This property captures the notion of type or property
     compatibility. The instantiation or constraint state of the term
     is compatible with the given property, in the sense that
     assuming that imposing that property on the term does not render
     the store inconsistent. For example, terms `X' (i.e., a free
     variable), `[Y|Z]', and `[Y,Z]' are all compatible with the
     regular type `list/1', whereas the terms `f(a)' and `[1|2]' are
     not.

     _Meta-predicate_ with arguments: `compat(?,pred(1))'.

     *Usage:* `compat(Term, Prop)'
        - _Description:_ `Term' is _compatible_ with `Prop'

 -- PROPERTY: iso/1:
     *Usage:* `iso(G)'
        - _Description:_ _Complies with the ISO-Prolog standard._

 -- PROPERTY: not_further_inst/2:
     *Usage:* `not_further_inst(G, V)'
        - _Description:_ `V' is not further instantiated.

 -- PROPERTY: sideff/2:
     `sideff(G, X)'

     Declares that `G' is side-effect free, soft (do not affect
     execution, e.g., input/output), or hard (e.g., assert/retract).

     _Meta-predicate_ with arguments: `sideff(goal,?)'.

     *General properties:* `sideff(G, X)'
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP as
          `sideff(G,X)'.   (`basic_props:native/2')
     `sideff(G, X)'
        - _The following properties should hold at call time:_

          `X' is an element of `[free,soft,hard]'.
          (`basic_props:member/2')

     *Usage:* `sideff(G, X)'
        - _Description:_ `G' is side-effect `X'.

 -- PROPERTY: regtype/1:
     _Meta-predicate_ with arguments: `regtype(goal)'.

     *Usage:* `regtype(G)'
        - _Description:_ Defines a regular type.

 -- PROPERTY: native/1:
     _Meta-predicate_ with arguments: `native(goal)'.

     *Usage:* `native(Pred)'
        - _Description:_ This predicate is understood natively by
          CiaoPP.

 -- PROPERTY: native/2:
     _Meta-predicate_ with arguments: `native(goal,?)'.

     *Usage:* `native(Pred, Key)'
        - _Description:_ This predicate is understood natively by
          CiaoPP as `Key'.

16 Extra-logical properties for typing
**************************************

*Author(s):* Daniel Cabeza, Manuel Hermenegildo.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 0.7#8 (1998/9/23, 19:21:44 MEST)

   This library contains traditional Prolog predicates for testing
types. They depend on the state of instantiation of their arguments,
thus being of extra-logical nature.

16.1 Usage and interface (`term_typing')
========================================

   * *Library usage:*

     These predicates are builtin in Ciao, so nothing special has to
     be done to use them.

   * *Exports:*
        - _Properties:_

          `var/1', `nonvar/1', `atom/1', `integer/1', `float/1', `number/1', `atomic/1', `ground/1', `type/2'.

16.2 Documentation on exports (`term_typing')
=============================================

 -- PROPERTY: var/1:
     *General properties:* `var(X)'
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

          This predicate is understood natively by CiaoPP as
          `free(X)'.   (`basic_props:native/2')

          `var(X)' is side-effect `hard'.   (`basic_props:sideff/2')

     *Usage:* `var(X)'
        - _Description:_ `X' is a free variable.

        - _The following properties hold globally:_

          `X' is not further instantiated.
          (`basic_props:not_further_inst/2')

 -- PROPERTY: nonvar/1:
     *General properties:* `nonvar(X)'
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

          This predicate is understood natively by CiaoPP as
          `not_free(X)'.   (`basic_props:native/2')

     *Usage:* `nonvar(X)'
        - _Description:_ `X' is currently a term which is not a free
          variable.

        - _The following properties hold globally:_

          `X' is not further instantiated.
          (`basic_props:not_further_inst/2')

 -- PROPERTY: atom/1:
     *Usage:* `atom(X)'
        - _Description:_ `X' is currently instantiated to an atom.

        - _The following properties hold upon exit:_

          `X' is an atom.   (`basic_props:atm/1')

        - _The following properties hold globally:_

          `X' is not further instantiated.
          (`basic_props:not_further_inst/2')

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PROPERTY: integer/1:
     *Usage:* `integer(X)'
        - _Description:_ `X' is currently instantiated to an integer.

        - _The following properties hold upon exit:_

          `X' is an integer.   (`basic_props:int/1')

        - _The following properties hold globally:_

          `X' is not further instantiated.
          (`basic_props:not_further_inst/2')

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PROPERTY: float/1:
     *Usage:* `float(X)'
        - _Description:_ `X' is currently instantiated to a float.

        - _The following properties hold upon exit:_

          `X' is a float.   (`basic_props:flt/1')

        - _The following properties hold globally:_

          `X' is not further instantiated.
          (`basic_props:not_further_inst/2')

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PROPERTY: number/1:
     *Usage:* `number(X)'
        - _Description:_ `X' is currently instantiated to a number.

        - _The following properties hold upon exit:_

          `X' is a number.   (`basic_props:num/1')

        - _The following properties hold globally:_

          `X' is not further instantiated.
          (`basic_props:not_further_inst/2')

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PROPERTY: atomic/1:
     *Usage:* `atomic(X)'
        - _Description:_ `X' is currently instantiated to an atom or
          a number.

        - _The following properties hold globally:_

          `X' is not further instantiated.
          (`basic_props:not_further_inst/2')

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PROPERTY: ground/1:
     *Usage:* `ground(X)'
        - _Description:_ `X' is currently ground (it contains no
          variables).

        - _The following properties hold upon exit:_

          `X' is ground.   (`basic_props:gnd/1')

        - _The following properties hold globally:_

          `X' is not further instantiated.
          (`basic_props:not_further_inst/2')

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PROPERTY: type/2:
     *Usage:* `type(X, Y)'
        - _Description:_ `X' is internally of type `Y' (`var',
          `attv', `float', `integer', `structure', `atom' or `list').

        - _The following properties hold upon exit:_

          `Y' is an atom.   (`basic_props:atm/1')

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

17 Basic term manipulation
**************************

*Author(s):* Daniel Cabeza, Manuel Hermenegildo.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#191 (2003/12/19, 16:47:39 CET)

   This module provides basic term manipulation.

17.1 Usage and interface (`term_basic')
=======================================

   * *Library usage:*

     These predicates are builtin in Ciao, so nothing special has to
     be done to use them.

   * *Exports:*
        - _Predicates:_

          `arg/3', `functor/3', `=../2', `copy_term/2', `C/3'.

        - _Properties:_

          `=/2'.

17.2 Documentation on exports (`term_basic')
============================================

 -- PROPERTY: =/2:
     *Usage:* `X = Y' < * ISO * >
        - _Description:_ `X' and `Y' unify.

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: arg/3:
     *Usage:* `arg(+ArgNo, +Term, ?Arg)' < * ISO * >
        - _Description:_ Argument `ArgNo' of the term `Term' is `Arg'.

        - _The following properties should hold at call time:_

          `ArgNo' is an integer.   (`basic_props:int/1')

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: functor/3:
     *Usage:* `functor(?Term, ?Name, ?Arity)' < * ISO * >
        - _Description:_ The principal functor of the term `Term' has
          name `Name' and arity `Arity'.

        - _The following properties hold upon exit:_

          `Name' is an atom.   (`basic_props:atm/1')

          `Arity' is a number.   (`basic_props:num/1')

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: =../2:
     *Usage:* `?Term =.. ?List' < * ISO * >
        - _Description:_ The functor and arguments of the term `Term'
          comprise the list `List'.

        - _The following properties hold upon exit:_

          `List' is a list.   (`basic_props:list/1')

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: copy_term/2:
     *Usage:* `copy_term(Term, Copy)' < * ISO * >
        - _Description:_ `Copy' is a renaming of `Term', such that
          brand new variables have been substituted for all variables
          in `Term'. If any of the variables of `Term' have attributes,
          the copied variables will have copies of the attributes as
          well. It behaves as if defined by:

               :- data 'copy of'/1.

               copy_term(X, Y) :-
                       asserta_fact('copy of'(X)),
                       retract_fact('copy of'(Y)).

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: C/3:
     *Usage:* `C(?S1, ?Terminal, ?S2)'
        - _Description:_ `S1' is connected by the terminal `Terminal'
          to `S2'. Internally used in _DCG grammar rules_. Defined as
          if by the single clause: `'C'([X|S], X, S).'

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

18 Comparing terms
******************

*Author(s):* Daniel Cabeza, Manuel Hermenegildo.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#199 (2003/12/19, 18:18:33 CET)

   These built-in predicates are extra-logical. They treat
uninstantiated variables as objects with values which may be
compared, and they never instantiate those variables. They should
_not_ be used when what you really want is arithmetic comparison or
unification.

   The predicates make reference to a _standard total ordering_ of
terms, which is as follows:

   * Variables, by age (roughly, oldest first - the order is _not_
     related to the names of variables).

   * Floats, in numeric order (e.g. -1.0 is put before 1.0).

   * Integers, in numeric order (e.g. -1 is put before 1).

   * Atoms, in alphabetical (i.e. character code) order.

   * Compound terms, ordered first by arity, then by the name of the
     principal functor, then by the arguments in left-to-right order.
     Recall that lists are equivalent to compound terms with
     principal functor `'.'/2'.

   For example, here is a list of terms in standard order:

     [ X, -1.0, -9, 1, bar, foo, [1], X = Y, foo(0,2), bar(1,1,1) ]

18.1 Usage and interface (`term_compare')
=========================================

   * *Library usage:*

     These predicates are builtin in Ciao, so nothing special has to
     be done to use them.

   * *Exports:*
        - _Predicates:_

          `compare/3'.

        - _Properties:_

          `==/2', `\==/2', `@</2', `@=</2', `@>/2', `@>=/2'.

18.2 Documentation on exports (`term_compare')
==============================================

 -- PROPERTY: ==/2:
     *Usage:* `Term1 == Term2'
        - _Description:_ The terms `Term1' and `Term2' are strictly
          identical.

        - _The following properties should hold globally:_

          `Term1' is not further instantiated.
          (`basic_props:not_further_inst/2')

          `Term2' is not further instantiated.
          (`basic_props:not_further_inst/2')

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PROPERTY: \==/2:
     *Usage:* `Term1 \== Term2'
        - _Description:_ The terms `Term1' and `Term2' are not
          strictly identical.

        - _The following properties should hold globally:_

          `Term1' is not further instantiated.
          (`basic_props:not_further_inst/2')

          `Term2' is not further instantiated.
          (`basic_props:not_further_inst/2')

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PROPERTY: @</2:
     *Usage:* `@<(Term1, Term2)'
        - _Description:_ The term `Term1' precedes the term `Term2'
          in the standard order.

        - _The following properties should hold globally:_

          `Term1' is not further instantiated.
          (`basic_props:not_further_inst/2')

          `Term2' is not further instantiated.
          (`basic_props:not_further_inst/2')

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PROPERTY: @=</2:
     *Usage:* `@=<(Term1, Term2)'
        - _Description:_ The term `Term1' precedes or is identical to
          the term `Term2' in the standard order.

        - _The following properties should hold globally:_

          `Term1' is not further instantiated.
          (`basic_props:not_further_inst/2')

          `Term2' is not further instantiated.
          (`basic_props:not_further_inst/2')

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PROPERTY: @>/2:
     *Usage:* `@>(Term1, Term2)'
        - _Description:_ The term `Term1' follows the term `Term2' in
          the standard order.

        - _The following properties should hold globally:_

          `Term1' is not further instantiated.
          (`basic_props:not_further_inst/2')

          `Term2' is not further instantiated.
          (`basic_props:not_further_inst/2')

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PROPERTY: @>=/2:
     *Usage:* `@>=(Term1, Term2)'
        - _Description:_ The term `Term1' follows or is identical to
          the term `Term2' in the standard order.

        - _The following properties should hold globally:_

          `Term1' is not further instantiated.
          (`basic_props:not_further_inst/2')

          `Term2' is not further instantiated.
          (`basic_props:not_further_inst/2')

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: compare/3:
     `compare(Op, Term1, Term2)'

     `Op' is the result of comparing the terms `Term1' and `Term2'.

     *Usage:* `compare(?atm, @term, @term)'
        - _The following properties hold upon exit:_

          `?atm' is an element of `[=,>,<]'.
          (`basic_props:member/2')

          `@term' is any term.   (`basic_props:term/1')

          `@term' is any term.   (`basic_props:term/1')

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

19 Basic predicates handling names of constants
***********************************************

*Author(s):* The CLIP Group.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#334 (2004/4/13, 13:28:2 CEST)

   The Ciao system provides builtin predicates which allow dealing
with names of constants (atoms or numbers). Note that sometimes
strings (character code lists) are more suitable to handle sequences
of characters.

19.1 Usage and interface (`atomic_basic')
=========================================

   * *Library usage:*

     These predicates are builtin in Ciao, so nothing special has to
     be done to use them.

   * *Exports:*
        - _Predicates:_

          `name/2', `atom_codes/2', `number_codes/2', `number_codes/3', `atom_number/2', `atom_length/2', `atom_concat/3', `sub_atom/4'.

19.2 Documentation on exports (`atomic_basic')
==============================================

 -- PREDICATE: name/2:
     `name(Const, String)'

     `String' is the list of the ASCII codes of the characters
     comprising the name of `Const'. Note that if `Const' is an atom
     whose name can be interpreted as a number (e.g. '96'), the
     predicate is not reversible, as that atom will not be
     constructed when `Const' is uninstantiated. Thus it is
     recommended that new programs use the ISO-compliant predicates `atom_codes/2'
     or `number_codes/2', as these predicates do not have this
     inconsistency.

     *Usage 1:* `name(+constant, ?string)'
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

     *Usage 2:* `name(-constant, +string)'
        - _Description:_ If `String' can be interpreted as a number,
          `Const' is unified with that number, otherwise with the
          atom whose name is `String'.

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: atom_codes/2:
     `atom_codes(Atom, String)'

     `String' is the list of the ASCII codes of the characters
     comprising the name of `Atom'.

     *Usage 1:* `atom_codes(+atm, ?string)' < * ISO * >
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

     *Usage 2:* `atom_codes(-atm, +string)' < * ISO * >
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: number_codes/2:
     `number_codes(Number, String)'

     `String' is the list of the ASCII codes of the characters
     comprising a representation of `Number'.

     *Usage 1:* `number_codes(+num, ?string)' < * ISO * >
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

     *Usage 2:* `number_codes(-num, +string)' < * ISO * >
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: number_codes/3:
     `number_codes(Number, Base, String)'

     `String' is the list of the ASCII codes of the characters
     comprising a representation of `Number' in base `Base'.

     *Usage 1:* `number_codes(+num, +int, ?string)'
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

     *Usage 2:* `number_codes(-num, +int, +string)'
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: atom_number/2:
     `atom_number(Atom, Number)'

     `Atom' can be read as a representation of `Number'.

     *Usage 1:* `atom_number(+atm, ?num)'
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

     *Usage 2:* `atom_number(-atm, +num)'
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: atom_length/2:
     `atom_length(Atom, Length)'

     `Length' is the number of characters forming the name of `Atom'.

     *Usage:* `atom_length(+atm, ?int)' < * ISO * >
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: atom_concat/3:
     `atom_concat(Atom_1, Atom_2, Atom_12)'

     `Atom_12' is the result of concatenating `Atom_1' followed by
     `Atom_2'.

     *Usage 1:* `atom_concat(+atom, +atom, ?atom)' < * ISO * >
        - _Description:_ Concatenate two atoms.

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

     *Usage 2:* `atom_concat(-atom, -atom, +atom)' < * ISO * >
        - _Description:_ Non-deterministically split an atom.

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

     *Usage 3:* `atom_concat(-atom, +atom, +atom)' < * ISO * >
        - _Description:_ Take out of an atom a certain suffix (or
          fail if it cannot be done).

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

     *Usage 4:* `atom_concat(+atom, -atom, +atom)' < * ISO * >
        - _Description:_ Take out of an atom a certain prefix (or
          fail if it cannot be done).

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: sub_atom/4:
     `sub_atom(Atom, Before, Length, Sub_atom)'

     `Sub_atom' is formed with `Length' consecutive characters of
     `Atom' after the `Before' character. For example, the goal
     `sub_atom(summer,1,4,umme)' succeeds.

     *Usage:* `sub_atom(+atm, +int, +int, ?atm)'
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

20 Arithmetic
*************

*Author(s):* Daniel Cabeza, Manuel Hermenegildo.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 0.9#18 (1999/3/23, 21:6:13 MET)

   Arithmetic is performed by built-in predicates which take as
arguments arithmetic expressions (see `arithexpression/1') and
evaluate them. Terms representing arithmetic expressions can be
created dynamically, but at the time of evaluation, each variable in
an arithmetic expression must be bound to a non-variable expression
(the term must be ground). For example, given the code in the first
line a possible shell interaction follows:
     evaluate(Expression, Answer) :- Answer is Expression.

     ?- _X=24*9, evaluate(_X+6, Ans).

     Ans = 222 ?

     yes

20.1 Usage and interface (`arithmetic')
=======================================

   * *Library usage:*

     These predicates are builtin in Ciao, so nothing special has to
     be done to use them.

   * *Exports:*
        - _Predicates:_

          `is/2', `</2', `=</2', `>/2', `>=/2', `=:=/2', `=\=/2'.

        - _Regular Types:_

          `arithexpression/1'.

20.2 Documentation on exports (`arithmetic')
============================================

 -- PREDICATE: is/2:
     `Val is Exp'

     The arithmetic expression `Exp' is evaluated and the result is
     unified with `Val'

     *Usage:* `X is +arithexpression' < * ISO * >
        - _The following properties hold upon exit:_

          `X' is a number.   (`basic_props:num/1')

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: </2:
     `Exp1 < Exp2'

     The numeric value of `Exp1' is less than the numeric value of
     `Exp2' when both are evaluated as arithmetic expressions.

     *Usage:* `+arithexpression < +arithexpression' < * ISO * >
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: =</2:
     `Exp1 =< Exp2'

     The numeric value of `Exp1' is less than or equal to the numeric
     value of `Exp2' when both are evaluated as arithmetic
     expressions.

     *Usage:* `+arithexpression =< +arithexpression' < * ISO * >
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: >/2:
     `Exp1 > Exp2'

     The numeric value of `Exp1' is greater than the numeric value of
     `Exp2' when both are evaluated as arithmetic expressions.

     *Usage:* `+arithexpression > +arithexpression' < * ISO * >
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: >=/2:
     `Exp1 >= Exp2'

     The numeric value of `Exp1' is greater than or equal to the
     numeric value of `Exp2' when both are evaluated as arithmetic
     expressions.

     *Usage:* `+arithexpression >= +arithexpression' < * ISO * >
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: =:=/2:
     `Exp1 =:= Exp2'

     The numeric values of `Exp1' and `Exp2' are equal when both are
     evaluated as arithmetic expressions.

     *Usage:* `+arithexpression =:= +arithexpression' < * ISO * >
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: =\=/2:
     `Exp1 =\= Exp2'

     The numeric values of `Exp1' and `Exp2' are not equal when both
     are evaluated as arithmetic expressions.

     *Usage:* `+arithexpression =\= +arithexpression' < * ISO * >
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- REGTYPE: arithexpression/1:
     An arithmetic expression is a term built from numbers and evaluable
     functors that represent arithmetic functions. An arithmetic
     expression evaluates to a number, which may be an integer ( `int/1')
     or a float ( `flt/1'). The evaluable functors allowed in an
     arithmetic expression are listed below, together with an
     indication of the functions they represent. All evaluable
     functors defined in ISO-Prolog are implemented, as well as some
     other useful or traditional. Unless stated otherwise, an
     expression evaluates to a float if any of its arguments is a
     float, otherwise to an integer.

        * `- /1': sign reversal.  < * ISO * >

        * `+ /1': identity.

        * `-- /1': decrement by one.

        * `++ /1': increment by one.

        * `+ /2': addition.  < * ISO * >

        * `- /2': subtraction.  < * ISO * >

        * `* /2': multiplication.  < * ISO * >

        * `// /2': integer division. Float arguments are truncated to
          integers, result always integer.  < * ISO * >

        * `/ /2': division. Result always float.  < * ISO * >

        * `rem/2': integer remainder. The result is always an
          integer, its sign is the sign of the first argument.  < *
          ISO * >

        * `mod/2': modulo. The result is always a positive integer.
          < * ISO * >

        * `abs/1': absolute value.  < * ISO * >

        * `sign/1': sign of.  < * ISO * >

        * `float_integer_part/1': float integer part. Result always
          float.  < * ISO * >

        * `float_fractional_part/1': float fractional part. Result
          always float.  < * ISO * >

        * `truncate/1': The result is the integer equal to the
          integer part of the argument.  < * ISO * >

        * `integer/1': same as `truncate/1'.

        * `float/1': conversion to float.  < * ISO * >

        * `floor/1': largest integer not greater than.  < * ISO * >

        * `round/1': integer nearest to.  < * ISO * >

        * `ceiling/1': smallest integer not smaller than.  < * ISO * >

        * `** /2': exponentiation. Result always float.  < * ISO * >

        * `>> /2': integer bitwise right shift.  < * ISO * >

        * `<< /2': integer bitwise left shift.  < * ISO * >

        * `/\ /2': integer bitwise and.  < * ISO * >

        * `\/ /2': integer bitwise or.  < * ISO * >

        * `\ /1': integer bitwise complement.  < * ISO * >

        * `# /2': integer bitwise exclusive or (xor).

        * `exp/1': exponential (_e_ to the power of). Result always
          float.  < * ISO * >

        * `log/1': natural logarithm (base _e_). Result always float.
          < * ISO * >

        * `sqrt/1': square root. Result always float.  < * ISO * >

        * `sin/1': sine. Result always float.  < * ISO * >

        * `cos/1': cosine. Result always float.  < * ISO * >

        * `atan/1': arc tangent. Result always float.  < * ISO * >

        * `gcd/2': Greatest common divisor. Arguments must evaluate
          to integers, result always integer.

     In addition to these functors, a list of just a number evaluates
     to this number. Since a quoted string is just a list of
     integers, this allows a quoted character to be used in place of
     its ASCII code; e.g. `"A"' behaves within arithmetic expressions
     as the integer 65. Note that this is not ISO-compliant, and that
     can be achieved by using the ISO notation `0'A'.

     Arithmetic expressions, as described above, are just data
     structures. If you want one evaluated you must pass it as an
     argument to one of the arithmetic predicates defined in this
     library.

     *Usage:* `arithexpression(E)'
        - _Description:_ `E' is an arithmetic expression.

21 Basic file/stream handling
*****************************

*Author(s):* Daniel Cabeza, Mats Carlsson.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#247 (2003/12/29, 18:50:42 CET)

   This module provides basic predicates for handling files and
streams, in order to make input/output on them.

21.1 Usage and interface (`streams_basic')
==========================================

   * *Library usage:*

     These predicates are builtin in Ciao, so nothing special has to
     be done to use them.

   * *Exports:*
        - _Predicates:_

          `open/3', `open/4', `close/1', `set_input/1', `current_input/1', `set_output/1', `current_output/1', `character_count/2', `line_count/2', `line_position/2', `flush_output/1', `flush_output/0', `clearerr/1', `current_stream/3', `stream_code/2', `absolute_file_name/2', `absolute_file_name/7'.

        - _Regular Types:_

          `open_option_list/1', `sourcename/1', `stream/1', `stream_alias/1', `io_mode/1'.

        - _Multifiles:_

          `file_search_path/2', `library_directory/1'.

21.2 Documentation on exports (`streams_basic')
===============================================

 -- PREDICATE: open/3:
     `open(File, Mode, Stream)'

     Open `File' with mode `Mode' and return in `Stream' the stream
     associated with the file. No extension is implicit in `File'.

     *Usage 1:* `open(+sourcename, +io_mode, ?stream)' < * ISO * >
        - _Description:_ Normal use.

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

     *Usage 2:* `open(+int, +io_mode, ?stream)'
        - _Description:_ In the special case that `File' is an
          integer, it is assumed to be a file descriptor passed to
          Prolog from a foreign function call. The file descriptor is
          connected to a Prolog stream (invoking the UNIX function
          `fdopen') which is unified with `Stream'.

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: open/4:
     `open(File, Mode, Stream, Options)'

     Same as `open(`File', `Mode', `Stream')' with options `Options'.
     See the definition of `open_option_list/1' for details.

     *Usage:* `open(+sourcename, +io_mode, ?stream,
     +open_option_list)'
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- REGTYPE: open_option_list/1:
     A list of options for `open/4', currently the meaningful options
     are:

    `lock'
          Try to set an advisory lock for the file. If the open mode
          is `read', the lock is a read (shared) lock, else it is a
          write (exclusive) lock. If the lock cannot be acquired, the
          call waits until it is released (but can fail in
          exceptional cases).

    `lock_nb'
          Same as `lock', but the call immediately fails if the lock
          cannot be acquired.

    `lock(Lock_Mode)'
          Same as `lock', but specifying in `Lock_Mode' whether the
          lock is `read' (also `shared') or `write' (also
          `exclusive'). This option has be included for compatibility
          with the SWI-Prolog locking options, because in general the
          type of lock should match the open mode as in the `lock'
          option.

    `lock_nb(Lock_Mode)'
          Same as the previous option but with the `lock_nb' behavior.

     All file locking is implemented via the POSIX function fcntl().
     Please refer to its manual page for details.

     *Usage:* `open_option_list(L)'
        - _Description:_ `L' is a list of options for `open/4'.

 -- PREDICATE: close/1:
     `close(Stream)'

     Close the stream `Stream'.

     *Usage:* `close(+stream)' < * ISO * >
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: set_input/1:
     `set_input(Stream)'

     Set the current input stream to `Stream'. A notion of _current
     input stream_ is maintained by the system, so that input
     predicates with no explicit stream operate on the current input
     stream. Initially it is set to `user_input'.

     *Usage:* `set_input(+stream)' < * ISO * >
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: current_input/1:
     `current_input(Stream)'

     Unify `Stream' with the current input stream.

     *Usage:* `current_input(?stream)' < * ISO * >
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: set_output/1:
     `set_output(Stream)'

     Set the current output stream to `Stream'. A notion of _current
     output stream_ is maintained by the system, so that output
     predicates with no explicit stream operate on the current output
     stream. Initially it is set to `user_output'.

     *Usage:* `set_output(+stream)' < * ISO * >
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: current_output/1:
     `current_output(Stream)'

     Unify `Stream' with the current output stream.

     *Usage:* `current_output(?stream)' < * ISO * >
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: character_count/2:
     `character_count(Stream, Count)'

     `Count' characters have been read from or written to `Stream'.

     *Usage:* `character_count(+stream, ?int)'
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: line_count/2:
     `line_count(Stream, Count)'

     `Count' lines have been read from or written to `Stream'.

     *Usage:* `line_count(+stream, ?int)'
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: line_position/2:
     `line_position(Stream, Count)'

     `Count' characters have been read from or written to the current
     line of `Stream'.

     *Usage:* `line_position(+stream, ?int)'
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: flush_output/1:
     `flush_output(Stream)'

     Flush any buffered data to output stream `Stream'.

     *Usage:* `flush_output(+stream)' < * ISO * >
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: flush_output/0:
     `flush_output(flush_output'

     Behaves like `current_output(S), flush_output(S)'

     *Usage:* < * ISO * >
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: clearerr/1:
     `clearerr(Stream)'

     Clear the end-of-file and error indicators for input stream
     `Stream'.

 -- PREDICATE: current_stream/3:
     `current_stream(Filename, Mode, Stream)'

     `Stream' is a stream which was opened in mode `Mode' and which
     is connected to the absolute file name `Filename' (an atom) or
     to the file descriptor `Filename' (an integer). This predicate
     can be used for enumerating all currently open streams through
     backtracking.

     *General properties:*
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: stream_code/2:
     `stream_code(Stream, StreamCode)'

     `StreamCode' is the file descriptor (an integer) corresponding
     to the Prolog stream `Stream'.

 -- PREDICATE: absolute_file_name/2:
     `absolute_file_name(RelFileSpec, AbsFileSpec)'

     If `RelFileSpec' is an absolute pathname then do an absolute
     lookup. If `RelFileSpec' is a relative pathname then prefix the
     name with the name of the current directory and do an absolute
     lookup. If `RelFileSpec' is a path alias, perform the lookup
     following the path alias rules (see `sourcename/1'). In all
     cases: if a matching file with suffix `.pl' exists, then
     `AbsFileSpec' will be unified with this file. Failure to open a
     file normally causes an exception. The behaviour can be
     controlled by the `fileerrors' prolog flag.

     *Usage:* `absolute_file_name(+RelFileSpec, -AbsFileSpec)'
        - _Description:_ `AbsFileSpec' is the absolute name (with
          full path) of `RelFileSpec'.

        - _Calls should, and exit will be compatible with:_

          `+RelFileSpec' is a source name.
          (`streams_basic:sourcename/1')

          `-AbsFileSpec' is an atom.   (`basic_props:atm/1')

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: absolute_file_name/7:
     `absolute_file_name(Spec, Opt, Suffix, CurrDir, AbsFile,
     AbsBase, AbsDir)'

     `AbsFile' is the absolute name (with full path) of `Spec', which
     has an optional first suffix `Opt' and an optional second suffix
     `Suffix', when the current directory is `CurrDir'. `AbsBase' is
     the same as `AbsFile', but without the second suffix, and
     `AbsDir' is the absolute path of the directory where `AbsFile'
     is. The Ciao compiler invokes this predicate with `Opt'=`'_opt''
     and `Suffix'=`'.pl'' when searching source files.

     *Usage:* `absolute_file_name(+sourcename, +atm, +atm, +atm,
     -atm, -atm, -atm)'
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- REGTYPE: sourcename/1:
     A source name is a flexible way of referring to a concrete file.
     A source name is either a relative or absolute filename given as:

        * an atom, or

        * a unary functor (which represents a _path alias_, see
          below) applied to a _relative_ path, the latter being given
          as an atom.

     In all cases certain filename extensions (e.g., `.pl') can be
     implicit. In the first form above, file names can be relative to
     the current directory. Also, file names beginning with `~' or
     `$' are treated specially. For example,

    `'~/ciao/sample.pl''
          is equivalent to `'/home/staff/herme/ciao/sample.pl'', if
          `/home/staff/herme' is the user's home directory. (This is
          also equivalent to `'$HOME/ciao/sample.pl'' as explained
          below.)

    `'~bardo/prolog/sample.pl''
          is equivalent to `'/home/bardo/prolog/sample.pl'', if
          `/home/bardo' is bardo's home directory.

    `'$UTIL/sample.pl''
          is equivalent to `'/usr/local/src/utilities/sample.pl'', if
          `/usr/local/src/utilities' is the value of the environment
          variable `UTIL'.

     The second form allows using path aliases. Such aliases allow
     refering to files not with absolute file system paths but with
     paths which are relative to predefined (or user-defined)
     abstract names. For example, given the path alias `myutils'
     which has been defined to refer to path
     `'/home/bardo/utilities'', if that directory contains the file
     `stuff.pl' then the term `myutils(stuff)' in a `use_module/1'
     declaration would refer to the file
     `'/home/bardo/utilities/stuff.pl'' (the `.pl' extension is
     implicit in the `use_module/1' declaration). As a special case,
     if that directory contains a subdirectory named `stuff' which in
     turn contains the file `stuff.pl', the same term would refer to
     the file `'/home/bardo/utilities/stuff/stuff.pl''. If a path
     alias is related to several paths, all paths are scanned in
     sequence until a match is found. For information on predefined
     path aliases or how to define new path aliases, see `file_search_path/2'.

     *Usage:* `sourcename(F)'
        - _Description:_ `F' is a source name.

 -- REGTYPE: stream/1:
     Streams correspond to the file pointers used at the operating
     system level, and usually represent opened files. There are four
     special streams which correspond with the operating system
     standard streams:
    `user_input'
          The standard input stream, i.e. the terminal, usually.

    `user_output'
          The standard output stream, i.e. the terminal, usually.

    `user_error'
          The standard error stream.

    `user'
          The standard input or output stream, depending on context.

     *Usage:* `stream(S)'
        - _Description:_ `S' is an open stream.

 -- REGTYPE: stream_alias/1:
     *Usage:* `stream_alias(S)'
        - _Description:_ `S' is the alias of an open stream, i.e., an
          atom which represents a stream at Prolog level.

 -- REGTYPE: io_mode/1:
     Can have the following values:
    `read'
          Open the file for input.

    `write'
          Open the file for output. The file is created if it does
          not already exist, the file will otherwise be truncated.

    `append'
          Open the file for output. The file is created if it does
          not already exist, the file will otherwise be appended to.

     *Usage:* `io_mode(M)'
        - _Description:_ `M' is an opening mode ('read', 'write' or
          'append').

21.3 Documentation on multifiles (`streams_basic')
==================================================

 -- PREDICATE: file_search_path/2:
     `file_search_path(Alias, Path)'

     The path alias `Alias' is linked to path `Path'. Both arguments
     must be atoms. New facts (or clauses) of this predicate can be
     asserted to define new path aliases. Predefined path aliases in
     Ciao are:

    `library'
          Initially points to all Ciao library paths. See `library_directory/1'.

    `engine'
          The path of the Ciao engine builtins.

    `.'
          The current path (`'.'').

     The predicate is _multifile_.

     The predicate is of type _dynamic_.

 -- PREDICATE: library_directory/1:
     `library_directory(Path)'

     `Path' is a library path (a path represented by the path alias
     `library'). Predefined library paths in Ciao are
     `'$CIAOLIB/lib'', `'$CIAOLIB/library'', and
     `'$CIAOLIB/contrib'', given that `$CIAOLIB' is the path of the
     root ciao library directory. More library paths can be defined
     by asserting new facts (or clauses) of this predicate.

     The predicate is _multifile_.

     The predicate is of type _dynamic_.

22 Basic input/output
*********************

*Author(s):* Daniel Cabeza, Mats Carlsson.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#285 (2004/2/13, 17:36:9 CET)

   This module provides predicates for character input/output and for
canonical term output. From the ISO-Prolog predicates for character
input/output, only the `_code' versions are provided, the rest are
given by `library(iso_byte_char)', using these. Most predicates are
provided in two versions: one that specifies the input or output
stream as the first argument and a second which omits this argument
and uses the current input or output stream.

22.1 Usage and interface (`io_basic')
=====================================

   * *Library usage:*

     These predicates are builtin in Ciao, so nothing special has to
     be done to use them.

   * *Exports:*
        - _Predicates:_

          `get_code/2', `get_code/1', `get1_code/2', `get1_code/1', `peek_code/2', `peek_code/1', `skip_code/2', `skip_code/1', `skip_line/1', `skip_line/0', `put_code/2', `put_code/1', `nl/1', `nl/0', `tab/2', `tab/1', `code_class/2', `getct/2', `getct1/2', `display/2', `display/1', `displayq/2', `displayq/1'.

22.2 Documentation on exports (`io_basic')
==========================================

 -- PREDICATE: get_code/2:
     `get_code(Stream, Code)'

     Reads from `Stream' the next character and unifies `Code' with
     its character code. At end of stream, unifies `Code' with the
     integer -1.

     *Usage:* `get_code(+stream, ?int)' < * ISO * >
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: get_code/1:
     `get_code(Code)'

     Behaves like `current_input(S), get_code(S,Code)'.

     *Usage:* `get_code(?int)' < * ISO * >
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: get1_code/2:
     `get1_code(Stream, Code)'

     Reads from `Stream' the next non-layout character (see `code_class/2')
     and unifies `Code' with its character code. At end of stream,
     unifies `Code' with the integer -1.

     *Usage:* `get1_code(+stream, ?int)'
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: get1_code/1:
     `get1_code(Code)'

     Behaves like `current_input(S), get1_code(S,Code)'.

     *Usage:* `get1_code(?int)'
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: peek_code/2:
     `peek_code(Stream, Code)'

     Unifies `Code' with the character code of the next character of
     `Stream', leaving the stream position unaltered. At end of
     stream, unifies `Code' with the integer -1.

 -- PREDICATE: peek_code/1:
     `peek_code(Code)'

     Behaves like `current_input(S), peek_code(S,Code)'.

 -- PREDICATE: skip_code/2:
     `skip_code(Stream, Code)'

     Skips just past the next character code `Code' from `Stream'.

 -- PREDICATE: skip_code/1:
     `skip_code(Code)'

     Behaves like `current_input(S), skip_code(S,Code)'.

 -- PREDICATE: skip_line/1:
     `skip_line(Stream)'

     Skips from `Stream' the remaining input characters on the
     current line. If the end of the stream is reached, the stream
     will stay at its end. Portable among different operating systems.

 -- PREDICATE: skip_line/0:
     `skip_line(skip_line'

     Behaves like `current_input(S), skip_line(S)'.

 -- PREDICATE: put_code/2:
     `put_code(Stream, Code)'

     Outputs to `Stream' the character corresponding to character
     code `Code'.

     *Usage:* `put_code(+stream, +int)' < * ISO * >
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: put_code/1:
     `put_code(Code)'

     Behaves like `current_output(S), put_code(S,Code)'.

     *Usage:* `put_code(+int)' < * ISO * >
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: nl/1:
     `nl(Stream)'

     Outputs a newline character to `Stream'. Equivalent to
     `put_code(Stream, 0'\n)'.

     *Usage:* `nl(+stream)' < * ISO * >
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: nl/0:
     `nl(nl'

     Behaves like `current_output(S), nl(S)'.

     *Usage:* < * ISO * >
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: tab/2:
     `tab(Stream, Num)'

     Outputs `Num' spaces to `Stream'.

     *Usage:* `tab(+stream, +int)'
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: tab/1:
     `tab(Num)'

     Behaves like `current_output(S), tab(S,Num)'.

     *Usage:* `tab(+int)'
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: code_class/2:
     `code_class(Code, Class)'

     Unifies `Class' with an integer corresponding to the lexical
     class of the character whose code is `Code', with the following
     correspondence:
              0 - layout (includes space, newline, tab)
              1 - small letter
              2 - capital letter (including '_')
              3 - digit
              4 - graphic (includes #$&*+-./:<=>?@^\`~ )
              5 - punctuation (includes !;"'%(),[]{|} )
     Note that in ISO-Prolog the back quote ``' is a punctuation
     character, whereas in Ciao it is a graphic character. Thus, if
     compatibility with ISO-Prolog is desired, the programmer should
     not use this character in unquoted names.

 -- PREDICATE: getct/2:
     `getct(Code, Type)'

     Reads from the current input stream the next character, unifying
     `Code' with its character code, and `Type' with its lexical
     class. At end of stream, unifies both `Code' and `Type' with the
     integer -1. Equivalent to
             get(Code), (Code = -1 -> Type = -1 ; code_class(Code,Type))

 -- PREDICATE: getct1/2:
     `getct1(Code, Type)'

     Reads from the current input stream the next non-layout
     character, unifying `Code' with its character code, and `Type'
     with its lexical class (which will be nonzero). At end of
     stream, unifies both `Code' and `Type' with the integer -1.
     Equivalent to
             get1(Code), (Code = -1 -> Type = -1 ; code_class(Code,Type))

 -- PREDICATE: display/2:
     `display(Stream, Term)'

     Displays `Term' onto `Stream'. Lists are output using list
     notation, the other compound terms are output in functional
     notation. Similar to `write_term(Stream, Term,
     [ignore_ops(ops)])', except that curly bracketed notation is not
     used with `{}/1', and the `write_strings' flag is not honored.

     *Usage:* `display(+stream, @term)'
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: display/1:
     `display(Term)'

     Behaves like `current_output(S), display(S,Term)'.

     *Usage:* `display(@term)'
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: displayq/2:
     `displayq(Stream, Term)'

     Similar to `display(Stream, Term)', but atoms and functors that
     can't be read back by `read_term/3' are quoted. Thus, similar to
     `write_term(Stream, Term, [quoted(true), ignore_ops(ops)])',
     with the same exceptions as `display/2'.

 -- PREDICATE: displayq/1:
     `displayq(Term)'

     Behaves like `current_output(S), displayq(S,Term)'.

23 Exception handling
*********************

*Author(s):* The CLIP Group.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#344 (2004/4/29, 12:56:34 CEST)

   This module includes predicates related to exceptions, which alter
the normal flow of Prolog.

23.1 Usage and interface (`exceptions')
=======================================

   * *Library usage:*

     These predicates are builtin in Ciao, so nothing special has to
     be done to use them.

   * *Exports:*
        - _Predicates:_

          `catch/3', `intercept/3', `throw/1', `halt/0', `halt/1', `abort/0'.

23.2 Documentation on exports (`exceptions')
============================================

 -- PREDICATE: catch/3:
     `catch(Goal, Error, Handler)'

     Executes `Goal'. If an exception is raised during its execution,
     `Error' is unified with the exception, and if the unification
     succeeds, the entire execution derived from `Goal' is aborted,
     and `Handler' is executed. The execution resumes with the
     continuation of the catch/3 call. For example, given the code
          p(X) :- throw(error), display('---').
          p(X) :- display(X).
     the execution of "`catch(p(0), E, display(E)), display(.),
     fail.'" results in the output "`error.'".

     _Meta-predicate_ with arguments: `catch(goal,?,goal)'.

     *Usage:* `catch(+callable, ?term, +callable)' < * ISO * >
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: intercept/3:
     `intercept(Goal, Error, Handler)'

     Executes `Goal'. If an exception is raised during its execution,
     `Error' is unified with the exception, and if the unification
     succeeds, `Handler' is executed and then the execution resumes
     after the predicate which produced the exception. Note the
     difference with builtin `catch/3', given the same code defined
     there, the execution of "`intercept(p(0), E, display(E)),
     display(.), fail.'" results in the output "`error---.0.'".

     _Meta-predicate_ with arguments: `intercept(goal,?,goal)'.

 -- PREDICATE: throw/1:
     `throw(Ball)'

     Raises an error, throwing the exception `Ball', to be caught by
     an ancestor `catch/3' or `intercept/3'. The closest matching
     ancestor is chosen. Exceptions are also thrown by other builtins
     in case of error.

     *Usage:* < * ISO * >
        - _Calls should, and exit will be compatible with:_

          `Ball' is currently a term which is not a free variable.
          (`term_typing:nonvar/1')

 -- PREDICATE: halt/0:
     `halt(halt'

     Halt the system, exiting to the invoking shell.

     *Usage:* < * ISO * >
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: halt/1:
     `halt(Code)'

     Halt the system, exiting to the invoking shell, returning exit
     code `Code'.

 -- PREDICATE: abort/0:
     `abort(abort'

     Abort the current execution.

24 Changing system behaviour and various flags
**********************************************

*Author(s):* Daniel Cabeza, Mats Carlsson.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.7#213 (2002/5/14, 18:11:29 CEST)

   Flags define some parameters of the system and control the
behavior of system or library predicates. Each flag has a name and an
associated predefined value, and except some system flags which are
fixed in general their associated value is changeable. Predefined
flags in the system are:

`version'
     The Ciao version, as a term `ciao'(`Version',`Patch'). `Version'
     is a floating point number, `Patch' is an integer. Unchangeable.

`argv'
     Its value is a list of atoms representing the program arguments
     supplied when the current executable was invoked. This is the
     value to which is instantiated the argument of the `main/1'
     predicate at executable startup. Unchangeable.

`bounded'
     It is `false', to denote that the range of integers can be
     considered infinite (but see `int/1'). Unchangeable. < * ISO * >

`fileerrors'
     If `on', predicates handling files give errors (throw
     exceptions) when a file is inexistent or an operation is not
     allowed. If `off', fail in that conditions. Initially `on'.

`gc'
     Controls whether garbage collection is done. May be `on'
     (default) or `off'.

`gc_margin'
     An integer `Margin'. If less than `Margin' kilobytes are
     reclaimed in a garbage collection then the size of the garbage
     collected area should be increased. Also, no garbage collection
     is attempted unless the garbage collected area has at least
     `Margin' kilobytes. Initially 500.

`gc_trace'
     Governs garbage collection trace messages. An element off
     `[on,off,terse,verbose]'. Initially `off'.

`integer_rounding_function'
     It is `toward_zero', so that `-1 =:= -3//2' succeeds.
     Unchangeable. < * ISO * >

`max_arity'
     It is 255, so that no compound term (or predicate) can have more
     than this number of arguments. Unchangeable. < * ISO * >

`quiet'
     Controls which messages issued using `io_aux' are actually
     written. As the system uses that library to report its messages,
     this flag controls the _verbosity_ of the system. Possible
     states of the flag are:

    `on'
          No messages are reported.

    `error'
          Only error messages are reported.

    `warning'
          Only error and warning messages are reported.

    `off'
          All messages are reported, except debug messages. This is
          the default state.

    `debug'
          All messages, including debug messages, are reported. This
          is only intended for the system implementators.

`unknown'
     Controls action on calls to undefined predicates. The possible
     states of the flag are:

    `error'
          An error is thrown with the error term
          `existence_error(procedure, F/A)'.

    `fail'
          The call simply fails.

    `warning'
          A warning is written and the call fails.

     The state is initially `error'. < * ISO * >

24.1 Usage and interface (`prolog_flags')
=========================================

   * *Library usage:*

     These predicates are builtin in Ciao, so nothing special has to
     be done to use them.

   * *Exports:*
        - _Predicates:_

          `set_prolog_flag/2', `current_prolog_flag/2', `prolog_flag/3', `push_prolog_flag/2', `pop_prolog_flag/1', `prompt/2', `gc/0', `nogc/0', `fileerrors/0', `nofileerrors/0'.

        - _Multifiles:_

          `define_flag/3'.

24.2 Documentation on exports (`prolog_flags')
==============================================

 -- PREDICATE: set_prolog_flag/2:
     `set_prolog_flag(FlagName, Value)'

     Set existing flag `FlagName' to `Value'.

 -- PREDICATE: current_prolog_flag/2:
     `current_prolog_flag(FlagName, Value)'

     `FlagName' is an existing flag and `Value' is the value
     currently associated with it.

 -- PREDICATE: prolog_flag/3:
     `prolog_flag(FlagName, OldValue, NewValue)'

     `FlagName' is an existing flag, unify `OldValue' with the value
     associated with it, and set it to new value `NewValue'.

     *Usage 1:* `prolog_flag(?atm, ?term, +term)'
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

     *Usage 2:* `prolog_flag(?FlagName, -OldValue, -NewValue)'
        - _Description:_ Same as `current_prolog_flag(`FlagName',
          `OldValue')'

        - _The following properties should hold at call time:_

          `FlagName' is an atom.   (`basic_props:atm/1')

          The terms `OldValue' and `NewValue' are strictly identical.
          (`term_compare:== /2')

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: push_prolog_flag/2:
     `push_prolog_flag(Flag, NewValue)'

     Same as `set_prolog_flag/2', but storing current value of `Flag'
     to restore it with `pop_prolog_flag/1'.

 -- PREDICATE: pop_prolog_flag/1:
     `pop_prolog_flag(Flag)'

     Restore the value of `Flag' previous to the last non-canceled `push_prolog_flag/2'
     on it.

 -- PREDICATE: prompt/2:
     `prompt(Old, New)'

     Unify `Old' with the current prompt for reading, change it to
     `New'.

     *Usage 2:* `prompt(Old, New)'
        - _Description:_ Unify `Old' with the current prompt for
          reading without changing it.

        - _The following properties should hold at call time:_

          `Old' is a free variable.   (`term_typing:var/1')

          `New' is a free variable.   (`term_typing:var/1')

          The terms `Old' and `New' are strictly identical.
          (`term_compare:== /2')

        - _The following properties hold upon exit:_

          `Old' is an atom.   (`basic_props:atm/1')

          `New' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: gc/0:
     *Usage:*
        - _Description:_ Enable garbage collection. Equivalent to
          `set_prolog_flag(gc, on)'

 -- PREDICATE: nogc/0:
     *Usage:*
        - _Description:_ Disable garbage collection. Equivalent to
          `set_prolog_flag(gc, off)'

 -- PREDICATE: fileerrors/0:
     *Usage:*
        - _Description:_ Enable reporting of file errors. Equivalent
          to `set_prolog_flag(fileerrors, on)'

 -- PREDICATE: nofileerrors/0:
     *Usage:*
        - _Description:_ Disable reporting of file errors. Equivalent
          to `set_prolog_flag(fileerrors, off)'

24.3 Documentation on multifiles (`prolog_flags')
=================================================

 -- PREDICATE: define_flag/3:
     `define_flag(Flag, Values, Default)'

     New flags can be defined by writing facts of this predicate.
     `Flag' is the name of the new flag, `Values' defines the posible
     values for the flag (see below) and `Default' defines the
     predefined value associated with the flag (which should be
     compatible with `Values').

     The predicate is _multifile_.

     *Usage 1:* `define_flag(-atm, Values, -atm)'
        - _Description:_ Posible values for the flag are atoms.

          Example:
               :- multifile define_flag/3.
               define_flag(tmpdir, atom, '/tmp').

        - _Call and exit should be _compatible_ with:_

          The terms `Values' and `atom' are strictly identical.
          (`term_compare:== /2')

     *Usage 2:* `define_flag(-atm, Values, -int)'
        - _Description:_ Posible values for the flag are integers.

          Example:
               :- multifile define_flag/3.
               define_flag(max_connections, integer, 10).

        - _Call and exit should be _compatible_ with:_

          The terms `Values' and `integer' are strictly identical.
          (`term_compare:== /2')

     *Usage 3:* `define_flag(Flag, Values, Default)'
        - _Description:_ Posible values for the flag are the elements
          of `Values'.

          Example:
               :- multifile define_flag/3.
               define_flag(debug, [on,debug,trace,off], off).

        - _Call and exit should be _compatible_ with:_

          `Flag' is an atom.   (`basic_props:atm/1')

          `Values' is a list.   (`basic_props:list/1')

        - _The following properties should hold upon exit:_

          `Default' is an element of `Values'.
          (`basic_props:member/2')

25 Fast/concurrent update of facts
**********************************

*Author(s):* Daniel Cabeza, Manuel Carro.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.7#95 (2001/5/2, 12:18:6 CEST)

   Prolog implementations traditionally implement the concept of dynamic
predicates: predicates which can be inspected or modified at
run-time, adding or deleting individual clauses. The power of this
feature comes at a cost: as new clause bodies can be arbitrarily
added to the program, new predicate calls can arise which are not
'visible' at compile-time, thus complicating global analysis and
optimization of the code. But it is the case that most of the time
what the programmer wants is simply to store data, with the purpose
of sharing it between search branches, predicates, or even execution
threads. In Ciao the concept of data predicate serves this purpose: a
data predicate is a predicate composed exclusively by facts, which
can be inspected, and dynamically added or deleted, at run-time.
Using data predicates instead of normal dynamic predicates brings
benefits in terms of speed, but above all makes the code much easier
to analyze automatically and thus allows better optimization.

   Also, a special kind of data predicates exists, _concurrent
predicates_, which can be used to communicate/synchronize among
different execution threads (see Low-level concurrency/multithreading primitives).

   Data predicates must be declared through a `data/1' declaration.
Concurrent data predicates must be declared through a `concurrent/1'
declaration.

25.1 Usage and interface (`data_facts')
=======================================

   * *Library usage:*

     These predicates are builtin in Ciao, so nothing special has to
     be done to use them.

   * *Exports:*
        - _Predicates:_

          `asserta_fact/1', `asserta_fact/2', `assertz_fact/1', `assertz_fact/2', `current_fact/1', `current_fact/2', `retract_fact/1', `retractall_fact/1', `current_fact_nb/1', `retract_fact_nb/1', `close_predicate/1', `open_predicate/1', `set_fact/1', `erase/1'.

25.2 Documentation on exports (`data_facts')
============================================

 -- PREDICATE: asserta_fact/1:
     `asserta_fact(Fact)'

     `Fact' is added to the corresponding data predicate. The fact
     becomes the first clause of the predicate concerned.

     _Meta-predicate_ with arguments: `asserta_fact(fact)'.

 -- PREDICATE: asserta_fact/2:
     `asserta_fact(Fact, Ref)'

     Same as `asserta_fact/1', instantiating `Ref' to a unique
     identifier of the asserted fact.

     _Meta-predicate_ with arguments: `asserta_fact(fact,?)'.

 -- PREDICATE: assertz_fact/1:
     `assertz_fact(Fact)'

     `Fact' is added to the corresponding data predicate. The fact
     becomes the last clause of the predicate concerned.

     _Meta-predicate_ with arguments: `assertz_fact(fact)'.

 -- PREDICATE: assertz_fact/2:
     `assertz_fact(Fact, Ref)'

     Same as `assertz_fact/1', instantiating `Ref' to a unique
     identifier of the asserted fact.

     _Meta-predicate_ with arguments: `assertz_fact(fact,?)'.

 -- PREDICATE: current_fact/1:
     `current_fact(Fact)'

     Gives on backtracking all the facts defined as data or
     concurrent which unify with `Fact'. It is faster than calling
     the predicate explicitly, which do invoke the meta-interpreter.
     If the `Fact' has been defined as concurrent and has not been closed, `current_fact/1'
     will wait (instead of failing) for more clauses to appear after
     the last clause of `Fact' is returned.

     _Meta-predicate_ with arguments: `current_fact(fact)'.

 -- PREDICATE: current_fact/2:
     `current_fact(Fact, Ref)'

     `Fact' is a fact of a data predicate and `Ref' is its reference
     identifying it uniquely.

     _Meta-predicate_ with arguments: `current_fact(fact,?)'.

     *Usage 1:* `current_fact(+callable, -reference)'
        - _Description:_ Gives on backtracking all the facts defined
          as data which unify with `Fact', instantiating `Ref' to a
          unique identifier for each fact.

     *Usage 2:* `current_fact(?callable, +reference)'
        - _Description:_ Given `Ref', unifies `Fact' with the fact
          identified by it.

 -- PREDICATE: retract_fact/1:
     `retract_fact(Fact)'

     Unifies `Fact' with the first matching fact of a data predicate,
     and then erases it. On backtracking successively unifies with
     and erases new matching facts. If `Fact' is declared as concurrent
     and is non- closed, `retract_fact/1' will wait for more clauses
     or for the closing of the predicate after the last matching
     clause has been removed.

     _Meta-predicate_ with arguments: `retract_fact(fact)'.

 -- PREDICATE: retractall_fact/1:
     `retractall_fact(Fact)'

     Erase all the facts of a data predicate unifying with `Fact'.
     Even if all facts are removed, the predicate continues to exist.

     _Meta-predicate_ with arguments: `retractall_fact(fact)'.

 -- PREDICATE: current_fact_nb/1:
     `current_fact_nb(Fact)'

     Behaves as `current_fact/1' but a fact is never waited on even
     if it is concurrent and non-closed.

     _Meta-predicate_ with arguments: `current_fact_nb(fact)'.

 -- PREDICATE: retract_fact_nb/1:
     `retract_fact_nb(Fact)'

     Behaves as `retract_fact/1', but never waits on a fact, even if
     it has been declared as concurrent and is non- closed.

     _Meta-predicate_ with arguments: `retract_fact_nb(fact)'.

 -- PREDICATE: close_predicate/1:
     `close_predicate(Pred)'

     Changes the behavior of the predicate `Pred' if it has been
     declared as a concurrent predicate: calls to this predicate will
     fail (instead of wait) if no more clauses of `Pred' are
     available.

     _Meta-predicate_ with arguments: `close_predicate(fact)'.

 -- PREDICATE: open_predicate/1:
     `open_predicate(Pred)'

     Reverts the behavior of concurrent predicate `Pred' to waiting
     instead of failing if no more clauses of `Pred' are available.

     _Meta-predicate_ with arguments: `open_predicate(fact)'.

 -- PREDICATE: set_fact/1:
     `set_fact(Fact)'

     Sets `Fact' as the unique fact of the corresponding data
     predicate.

     _Meta-predicate_ with arguments: `set_fact(fact)'.

 -- PREDICATE: erase/1:
     `erase(Ref)'

     Deletes the clause referenced by `Ref'.

25.3 Documentation on internals (`data_facts')
==============================================

 -- DECLARATION: data/1:
     *Usage:* :- `data Predicates'.
        - _Description:_ Defines each predicate in `Predicates' as a data
          predicate. If a predicate is defined data in a file, it
          must be defined data in every file containing clauses for
          that predicate. The directive should precede all clauses of
          the affected predicates. This directive is defined as a
          prefix operator in the compiler.

        - _The following properties hold at call time:_

          `Predicates' is a sequence or list of `predname's.
          (`basic_props:sequence_or_list/2')

 -- DECLARATION: concurrent/1:
     *Usage:* :- `concurrent Predicates'.
        - _Description:_ Defines each predicate in `Predicates' as a concurrent
          predicate. If a predicate is defined concurrent in a file,
          it must be defined concurrent in every file containing
          clauses for that predicate. The directive should precede
          all clauses of the affected predicates. This directive is
          defined as a prefix operator in the compiler.

        - _The following properties hold at call time:_

          `Predicates' is a sequence or list of `predname's.
          (`basic_props:sequence_or_list/2')

 -- REGTYPE: reference/1:
     *Usage:* `reference(R)'
        - _Description:_ `R' is a reference of a dynamic or data
          clause.

26 Extending the syntax
***********************

*Author(s):* Daniel Cabeza.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#193 (2003/12/19, 16:54:6 CET)

   This chapter documents the builtin directives in Ciao for
extending the syntax of source files. Note that the ISO-Prolog
directive `char_conversion/2' is not implemented, since Ciao does not
(yet) have a character conversion table.

26.1 Usage and interface (`syntax_extensions')
==============================================

   * *Library usage:*

     These directives are builtin in Ciao, so nothing special has to
     be done to use them.

26.2 Documentation on internals (`syntax_extensions')
=====================================================

 -- DECLARATION: op/3:
     *Usage:* :- `op(Priority, Op_spec, Operator)'.  < * ISO * >
        - _Description:_ Updates the operator table for reading the
          terms in the rest of the current text, in the same way as
          the builtin `op/3' does. Its scope is local to the current
          text. Usually included in package files.

        - _The following properties hold at call time:_

          `Priority' is an integer.   (`basic_props:int/1')

          `Op_spec' specifies the type and associativity of an
          operator.   (`basic_props:operator_specifier/1')

          `Operator' is an atom or a list of atoms.
          (`basic_props:atm_or_atm_list/1')

 -- DECLARATION: new_declaration/1:
     *Usage:* :- `new_declaration(Predicate)'.
        - _Description:_ Declares `Predicate' to be a valid
          declaration in the rest of the current text. Such
          declarations are simply ignored by the compiler or top
          level, but can be used by other code processing programs
          such as an automatic documentator. Also, they can easily
          translated into standard code (a set of facts and/or rules)
          by defining a suitable expansion (e.g., by `add_sentence_trans/1',
          etc.). This is tipically done in package files.

          Equivalent to `new_declaration(Predicate, off)'.

        - _The following properties hold at call time:_

          `Predicate' is a Name/Arity structure denoting a predicate
          name:
               predname(P/A) :-
                       atm(P),
                       nnegint(A).

          (`basic_props:predname/1')

 -- DECLARATION: new_declaration/2:
     *Usage:* :- `new_declaration(Predicate, In_Itf)'.
        - _Description:_ Declares `Predicate' to be a valid
          declaration in the rest of the current text. Such
          declarations will be included in the interface file for
          this file if `In_Itf' is 'on', not if it is 'off'.
          Including such declarations in interface files makes them
          visible while processing other modules which make use of
          this one.

        - _The following properties hold at call time:_

          `Predicate' is a Name/Arity structure denoting a predicate
          name:
               predname(P/A) :-
                       atm(P),
                       nnegint(A).

          (`basic_props:predname/1')

          `In_Itf' is 'on' or 'off'  (`syntax_extensions:switch/1')

 -- DECLARATION: load_compilation_module/1:
     *Usage:* :- `load_compilation_module(File)'.
        - _Description:_ Loads code defined in `File' into the
          compiler, usually including predicates which define
          translations of terms, for use with the declarations `add_sentence_trans/1'
          and similar ones. Normally included in package files.

        - _The following properties hold at call time:_

          `File' is a source name.   (`streams_basic:sourcename/1')

 -- DECLARATION: add_sentence_trans/1:
     *Usage:* :- `add_sentence_trans(Predicate)'.
        - _Description:_ Starts a translation, defined by
          `Predicate', of the terms read by the compiler in the rest
          of the current text. For each subsequent term read by the
          compiler, the translation predicate is called to obtain a
          new term which will be used by the compiler as if it where
          the term present in the file. If the call fails, the term
          is used as such. A list may be returned also, to translate
          a single term into several terms. Before calling the
          translation predicate with actual program terms, it is
          called with an input of `0' to give an opportunity of
          making initializations for the module, discarding the
          result (note that normally a 0 could not be there).
          `Predicate' must be exported by a module previously loaded
          with a `load_compilation_module/1' declaration. Normally
          included in package files.

        - _The following properties hold at call time:_

          `Predicate' is a translation predicate spec (has arity 2 or
          3).   (`syntax_extensions:translation_predname/1')

 -- DECLARATION: add_term_trans/1:
     *Usage:* :- `add_term_trans(P)'.
        - _Description:_ Starts a translation, defined by
          `Predicate', of the terms and sub-terms read by the
          compiler in the rest of the current text. This translation
          is performed after all translations defined by `add_sentence_trans/1'
          are done. For each subsequent term read by the compiler,
          and recursively any subterm included, the translation
          predicate is called to possibly obtain a new term to
          replace the old one. Care must be taken of not introducing
          an endless loop of translations. `Predicate' must be
          exported by a module previously loaded with a `load_compilation_module/1'
          declaration. Normally included in package files.

        - _The following properties hold at call time:_

          `P' is a translation predicate spec (has arity 2 or 3).
          (`syntax_extensions:translation_predname/1')

 -- DECLARATION: add_goal_trans/1:
     *Usage:* :- `add_goal_trans(Predicate)'.
        - _Description:_ Declares a translation, defined by
          `Predicate', of the goals present in the clauses of the
          current text. This translation is performed after all
          translations defined by `add_sentence_trans/1' and `add_term_trans/1'
          are done. For each clause read by the compiler, the
          translation predicate is called with each goal present in
          the clause to possibly obtain other goal to substitute the
          original one, and the translation is subsequently applied
          to the resulting goal. Care must be taken of not
          introducing an endless loop of translations. `Predicate'
          must be exported by a module previously loaded with a `load_compilation_module/1'
          declaration. Bear in mind that this type of translation
          noticeably slows down compilation. Normally included in package
          files.

        - _The following properties hold at call time:_

          `Predicate' is a translation predicate spec (has arity 2 or
          3).   (`syntax_extensions:translation_predname/1')

 -- DECLARATION: add_clause_trans/1:
     *Usage:* :- `add_clause_trans(Predicate)'.
        - _Description:_ Declares a translation, defined by
          `Predicate', of the clauses of the current text. The
          translation is performed before `add_goal_trans/1'
          translations but after `add_sentence_trans/1' and `add_term_trans/1'
          translations. The usefulness of this translation is that
          information of the interface of related modules is
          available when it is performed. For each clause read by the
          compiler, the translation predicate is called with the
          first argument instantiated to a structure
          `clause(Head,Body)', and the predicate must return in the
          second argument a similar structure, without changing the
          functor in `Head' (or fail, in which case the clause is
          used as is). Before executing the translation predicate
          with actual clauses it is called with an input of
          `clause(0,0)', discarding the result.

        - _The following properties hold at call time:_

          `Predicate' is a translation predicate spec (has arity 2 or
          3).   (`syntax_extensions:translation_predname/1')

 -- REGTYPE: translation_predname/1:
     A translation predicate is a predicate of arity 2 or 3 used to
     make compile-time translations. The compiler invokes a
     translation predicate instantiating its first argument with the
     item to be translated, and if the predicate is of arity 3 its
     third argument with the name of the module where the translation
     is done. If the call is successful, the second argument is used
     as if that item were in the place of the original, else the
     original item is used.

     *Usage:* `translation_predname(P)'
        - _Description:_ `P' is a translation predicate spec (has
          arity 2 or 3).

27 Message printing primitives
******************************

*Author(s):* Daniel Cabeza.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#194 (2003/12/19, 16:56:0 CET)

   This module provides predicates for printing in a unified way
informational messages, and also for printing some terms in a
specific way.

27.1 Usage and interface (`io_aux')
===================================

   * *Library usage:*

     These predicates are builtin in Ciao, so nothing special has to
     be done to use them.

   * *Exports:*
        - _Predicates:_

          `message/2', `message_lns/4', `error/1', `warning/1', `note/1', `message/1', `debug/1', `inform_user/1', `display_string/1', `display_list/1', `display_term/1'.

27.2 Documentation on exports (`io_aux')
========================================

 -- PREDICATE: message/2:
     `message(Type, Message)'

     Output to standard error `Message', which is of type `Type'. The
     `quiet' _prolog flag_ (see Changing system behaviour and various flags)
     controls which messages are actually output,
     depending on its type. Also, for `error', `warning' and `note'
     messages, a prefix is output which denotes the severity of the
     message. `Message' is an item or a list of items from this list:
    `$$(String)'
          `String' is a string, which is output with `display_string/1'.

    `''(Term)'
          `Term' is output quoted. If the module `write' is loaded,
          the term is output with `writeq/1', else with `displayq/1'.

    `~~(Term)'
          `Term' is output unquoted. If the module `write' is loaded,
          the term is output with `write/1', else with `display/1'.

    `[](Term)'
          `Term' is recursively output as a message, can be an item
          or a list of items from this list.

    `Term'
          Any other term is output with `display/1'.

     *Usage:* `message(Type, Message)'
        - _The following properties should hold at call time:_

          `Type' is an atom.   (`basic_props:atm/1')

          `Type' is an element of
          `[error,warning,note,message,debug]'.
          (`basic_props:member/2')

 -- PREDICATE: message_lns/4:
     `message_lns(Type, L0, L1, Message)'

     Output to standard error `Message', which is of type `Type', and
     occurs between lines `L0' and `L1'. This is the same as `message/2',
     but printing the lines where the message occurs in a unified way
     (this is useful because automatic tools such as the emacs mode
     know how to parse them).

     *Usage:* `message_lns(Type, L0, L1, Message)'
        - _The following properties should hold at call time:_

          `Type' is an atom.   (`basic_props:atm/1')

          `Type' is an element of
          `[error,warning,note,message,debug]'.
          (`basic_props:member/2')

 -- PREDICATE: error/1:
     Defined as
          error(Message) :-
                  message(error,Message).
     .

 -- PREDICATE: warning/1:
     Defined as
          warning(Message) :-
                  message(warning,Message).
     .

 -- PREDICATE: note/1:
     Defined as
          note(Message) :-
                  message(note,Message).
     .

 -- PREDICATE: message/1:
     Defined as
          message(Message) :-
                  message(message,Message).
     .

 -- PREDICATE: debug/1:
     Defined as
          debug(Message) :-
                  message(debug,Message).
     .

 -- PREDICATE: inform_user/1:
     `inform_user(Message)'

     Similar to `message/1', but `Message' is output with `display_list/1'.
     This predicate is obsolete, and may disappear in future versions.

 -- PREDICATE: display_string/1:
     `display_string(String)'

     Output `String' as the sequence of characters it represents.

     *Usage:* `display_string(String)'
        - _The following properties should hold at call time:_

          `String' is a string (a list of character codes).
          (`basic_props:string/1')

 -- PREDICATE: display_list/1:
     `display_list(List)'

     Outputs `List'. If `List' is a list, do `display/1' on each of
     its elements, else do `display/1' on `List'.

 -- PREDICATE: display_term/1:
     `display_term(Term)'

     Output `Term' in a way that a `read/1' will be able to read it
     back, even if operators change.

27.3 Known bugs and planned improvements (`io_aux')
===================================================

   *  `message/2' assumes that a module with name 'write' is
     library(write).

28 Attributed variables
***********************

*Author(s):* Christian Holzbaur, Daniel Cabeza, Manuel Carro.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.5#157 (2000/5/30, 13:4:47 CEST)

   These predicates allow the manipulation of _attributed variables_.
Attributes are special terms which are attached to a (free) variable,
and are hidden from the normal Prolog computation. They can only be
treated by using the predicates below.

28.1 Usage and interface (`attributes')
=======================================

   * *Library usage:*

     These predicates are builtin in Ciao, so nothing special has to
     be done to use them.

   * *Exports:*
        - _Predicates:_

          `attach_attribute/2', `get_attribute/2', `update_attribute/2', `detach_attribute/1'.

        - _Multifiles:_

          `verify_attribute/2', `combine_attributes/2'.

28.2 Documentation on exports (`attributes')
============================================

 -- PREDICATE: attach_attribute/2:
     *Usage:* `attach_attribute(Var, Attr)'
        - _Description:_ Attach attribute `Attr' to `Var'.

        - _The following properties should hold at call time:_

          `Var' is a free variable.   (`term_typing:var/1')

          `Attr' is currently a term which is not a free variable.
          (`term_typing:nonvar/1')

 -- PREDICATE: get_attribute/2:
     *Usage:* `get_attribute(Var, Attr)'
        - _Description:_ Unify `Attr' with the attribute of `Var', or
          fail if `Var' has no attribute.

        - _The following properties should hold at call time:_

          `Var' is a free variable.   (`term_typing:var/1')

        - _The following properties should hold upon exit:_

          `Attr' is currently a term which is not a free variable.
          (`term_typing:nonvar/1')

 -- PREDICATE: update_attribute/2:
     *Usage:* `update_attribute(Var, Attr)'
        - _Description:_ Change the attribute of attributed variable
          `Var' to `Attr'.

        - _The following properties should hold at call time:_

          `Var' is a free variable.   (`term_typing:var/1')

          `Attr' is currently a term which is not a free variable.
          (`term_typing:nonvar/1')

 -- PREDICATE: detach_attribute/1:
     *Usage:* `detach_attribute(Var)'
        - _Description:_ Take out the attribute from the attributed
          variable `Var'.

        - _The following properties should hold at call time:_

          `Var' is a free variable.   (`term_typing:var/1')

28.3 Documentation on multifiles (`attributes')
===============================================

 -- PREDICATE: verify_attribute/2:
     The predicate is _multifile_.

     *Usage:* `verify_attribute(Attr, Term)'
        - _Description:_ _A user defined predicate._ This predicate
          is called when an attributed variable with attribute `Attr'
          is about to be unified with the non-variable term `Term'.
          The user should define this predicate (as multifile) in the
          modules implementing special unification.

        - _The following properties should hold at call time:_

          `Attr' is currently a term which is not a free variable.
          (`term_typing:nonvar/1')

          `Term' is currently a term which is not a free variable.
          (`term_typing:nonvar/1')

 -- PREDICATE: combine_attributes/2:
     The predicate is _multifile_.

     *Usage:* `combine_attributes(Var1, Var2)'
        - _Description:_ _A user defined predicate._ This predicate
          is called when two attributed variables with attributes
          `Var1' and `Var2' are about to be unified. The user should
          define this predicate (as multifile) in the modules
          implementing special unification.

        - _The following properties should hold at call time:_

          `Var1' is a free variable.   (`term_typing:var/1')

          `Var2' is a free variable.   (`term_typing:var/1')

28.4 Other information (`attributes')
=====================================

Note that `combine_attributes/2' and `verify_attribute/2' are not
called with the attributed variables involved, but with the
corresponding attributes instead. The reasons are:

   * There are simple applications which only refer to the attributes.

   * If the application wants to refer to the attributed variables
     themselves, they can be made part the attribute term. The
     implementation of `freeze/2' utilizes this technique. Note that
     this does not lead to cyclic structures, as the connection
     between an attributed variable and its attribute is invisible to
     the pure parts of the Prolog implementation.

   * If attributed variables were passed as arguments, the user code
     would have to refer to the attributes through an extra call to `get_attribute/2'.

   * As the/one attribute is the first argument to each of the two
     predicates, indexing applies. Note that attributed variables
     themselves look like variables to the indexing mechanism.

   However, future improvements may change or extend the interface to
attributed variables in order to provide a richer and more expressive
interface.

   For customized output of attributed variables, please refer to the
documentation of the predicate `portray_attribute/2'.

29 Gathering some basic internal info
*************************************

*Author(s):* Daniel Cabeza, Manuel Carro.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.3#13 (1999/7/2, 18:49:49 MEST)

   This module provides predicates which return basic internal info.

29.1 Usage and interface (`system_info')
========================================

   * *Library usage:*

     These predicates are builtin in Ciao, so nothing special has to
     be done to use them.

   * *Exports:*
        - _Predicates:_

          `get_arch/1', `get_os/1', `this_module/1', `current_module/1', `ciaolibdir/1'.

29.2 Documentation on exports (`system_info')
=============================================

 -- PREDICATE: get_arch/1:
     This predicate will describe the computer architecture wich is
     currently executing the predicate.

     Computer architectures are identified by a simple atom. This
     atom is implementation-defined, and may suffer any change from
     one Ciao Prolog version to another.

     For example,Ciao Prolog running on an Intel-based machine will
     retrieve:
          ?- get_arch(I).

          I = i86 ? ;

          no
          ?-

     *Usage:* `get_arch(?ArchDescriptor)'
        - _Description:_ Unifies `ArchDescriptor' with a simple atom
          which describes the computer architecture currently
          executing the predicate.

        - _Calls should, and exit will be compatible with:_

          `?ArchDescriptor' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: get_os/1:
     This predicate will describe the Operating System which is
     running on the machine currently executing the Prolog program.

     Operating Systems are identified by a simple atom. This atom is
     implementation-defined, and may suffer any change from one Ciao
     Prolog version to another.

     For example,Ciao Prolog running on Linux will retrieve:
          ?- get_os(I).

          I = 'LINUX' ? ;

          no
          ?-

     *Usage:* `get_os(?OsDescriptor)'
        - _Description:_ Unifies `OsDescriptor' with a simple atom
          which describes the running Operating System when predicate
          was called.

        - _Calls should, and exit will be compatible with:_

          `?OsDescriptor' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: this_module/1:
     _Meta-predicate_ with arguments: `this_module(addmodule)'.

     *Usage:* `this_module(Module)'
        - _Description:_ `Module' is the internal module identifier
          for current module.

        - _Call and exit should be _compatible_ with:_

          `Module' is an internal module identifier
          (`system_info:internal_module_id/1')

 -- PREDICATE: current_module/1:
     This predicate will successively unify its argument with all
     module names currently loaded. Module names will be simple atoms.

     When called using a free variable as argument, it will retrieve
     on backtracking all modules currently loaded. This is usefull
     when called from the Ciao `toplevel'.

     When called using a module name as argument it will check
     whether the given module is loaded or not. This is usefull when
     called from user programs.

     *Usage:* `current_module(Module)'
        - _Description:_ Retrieves (on backtracking) all currently
          loaded modules into your application.

        - _Call and exit should be _compatible_ with:_

          `Module' is an internal module identifier
          (`system_info:internal_module_id/1')

        - _The following properties should hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: ciaolibdir/1:
     *Usage:* `ciaolibdir(CiaoPath)'
        - _Description:_ `CiaoPath' is the path to the root of the
          Ciao libraries. Inside this directory, there are the
          directories 'lib', 'library' and 'contrib', which contain
          library modules.

        - _Call and exit should be _compatible_ with:_

          `CiaoPath' is an atom.   (`basic_props:atm/1')

29.3 Documentation on internals (`system_info')
===============================================

 -- PROPERTY: internal_module_id/1:
     For a user file it is a term user/1 with an argument different
     for each user file, for other modules is just the name of the
     module (as an atom).

     *Usage:* `internal_module_id(M)'
        - _Description:_ `M' is an internal module identifier

30 Other predicates and features defined by default
***************************************************

*Author(s):* Daniel Cabeza.

   To simplify the use of Ciao Prolog to the first-timers, some other
predicates and features are defined by default in normal cases, to
provide more or less what other prologs define by default. Here are
explicitly listed the predicates defined, coming from several
libraries. Apart from those, the features defined in Definite clause grammars
and Enabling operators at run-time are also
activated.

30.1 Usage and interface (`default_predicates')
===============================================

   * *Library usage:*

     No need of explicit loading. It is included by default in
     modules starting with a `module/2' declaration or user files
     without a starting `use_package/1' declaration. In the Ciao
     shell, it is loaded by default when no `~/.ciaorc' exists. Note
     that `:- module(_modulename_,_exports_)' is equivalent to `:-
     module(_modulename_,_exports_,[default])' If you do not want
     these predicates/features loaded for a given file (in order to
     make the executable smaller) you can ask for this explicitly
     using `:- module(_modulename_,_exports_,[])' or in a user file
     `:- use_package([])'.

   * *Other modules used:*
        - _System library modules:_

          `aggregates', `dynamic', `read', `write', `operators', `iso_byte_char', `iso_misc', `format', `lists', `sort', `between', `compiler/compiler', `system', `prolog_sys', `dec10_io', `old_database', `ttyout'.

30.2 Documentation on exports (`default_predicates')
====================================================

 -- (: UNDOC_REEXPORT) op/3:
     Imported from `operators' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) current_op/3:
     Imported from `operators' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) append/3:
     Imported from `lists' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) delete/3:
     Imported from `lists' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) select/3:
     Imported from `lists' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) nth/3:
     Imported from `lists' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) last/2:
     Imported from `lists' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) reverse/2:
     Imported from `lists' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) length/2:
     Imported from `lists' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) use_module/1:
     Imported from `compiler' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) use_module/2:
     Imported from `compiler' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) ensure_loaded/1:
     Imported from `compiler' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) ^/2:
     Imported from `aggregates' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) findnsols/5:
     Imported from `aggregates' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) findnsols/4:
     Imported from `aggregates' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) findall/4:
     Imported from `aggregates' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) findall/3:
     Imported from `aggregates' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) bagof/3:
     Imported from `aggregates' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) setof/3:
     Imported from `aggregates' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) wellformed_body/3:
     Imported from `dynamic' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) data/1:
     Imported from `dynamic' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) dynamic/1:
     Imported from `dynamic' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) current_predicate/2:
     Imported from `dynamic' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) current_predicate/1:
     Imported from `dynamic' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) clause/3:
     Imported from `dynamic' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) clause/2:
     Imported from `dynamic' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) abolish/1:
     Imported from `dynamic' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) retractall/1:
     Imported from `dynamic' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) retract/1:
     Imported from `dynamic' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) assert/2:
     Imported from `dynamic' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) assert/1:
     Imported from `dynamic' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) assertz/2:
     Imported from `dynamic' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) assertz/1:
     Imported from `dynamic' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) asserta/2:
     Imported from `dynamic' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) asserta/1:
     Imported from `dynamic' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) second_prompt/2:
     Imported from `read' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) read_top_level/3:
     Imported from `read' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) read_term/3:
     Imported from `read' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) read_term/2:
     Imported from `read' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) read/2:
     Imported from `read' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) read/1:
     Imported from `read' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) printable_char/1:
     Imported from `write' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) prettyvars/1:
     Imported from `write' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) numbervars/3:
     Imported from `write' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) portray_clause/1:
     Imported from `write' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) portray_clause/2:
     Imported from `write' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) write_list1/1:
     Imported from `write' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) print/1:
     Imported from `write' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) print/2:
     Imported from `write' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) write_canonical/1:
     Imported from `write' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) write_canonical/2:
     Imported from `write' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) writeq/1:
     Imported from `write' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) writeq/2:
     Imported from `write' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) write/1:
     Imported from `write' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) write/2:
     Imported from `write' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) write_option/1:
     Imported from `write' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) write_term/2:
     Imported from `write' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) write_term/3:
     Imported from `write' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) put_char/2:
     Imported from `iso_byte_char' (see the corresponding
     documentation for details).

 -- (: UNDOC_REEXPORT) put_char/1:
     Imported from `iso_byte_char' (see the corresponding
     documentation for details).

 -- (: UNDOC_REEXPORT) peek_char/2:
     Imported from `iso_byte_char' (see the corresponding
     documentation for details).

 -- (: UNDOC_REEXPORT) peek_char/1:
     Imported from `iso_byte_char' (see the corresponding
     documentation for details).

 -- (: UNDOC_REEXPORT) get_char/2:
     Imported from `iso_byte_char' (see the corresponding
     documentation for details).

 -- (: UNDOC_REEXPORT) get_char/1:
     Imported from `iso_byte_char' (see the corresponding
     documentation for details).

 -- (: UNDOC_REEXPORT) put_byte/2:
     Imported from `iso_byte_char' (see the corresponding
     documentation for details).

 -- (: UNDOC_REEXPORT) put_byte/1:
     Imported from `iso_byte_char' (see the corresponding
     documentation for details).

 -- (: UNDOC_REEXPORT) peek_byte/2:
     Imported from `iso_byte_char' (see the corresponding
     documentation for details).

 -- (: UNDOC_REEXPORT) peek_byte/1:
     Imported from `iso_byte_char' (see the corresponding
     documentation for details).

 -- (: UNDOC_REEXPORT) get_byte/2:
     Imported from `iso_byte_char' (see the corresponding
     documentation for details).

 -- (: UNDOC_REEXPORT) get_byte/1:
     Imported from `iso_byte_char' (see the corresponding
     documentation for details).

 -- (: UNDOC_REEXPORT) number_chars/2:
     Imported from `iso_byte_char' (see the corresponding
     documentation for details).

 -- (: UNDOC_REEXPORT) atom_chars/2:
     Imported from `iso_byte_char' (see the corresponding
     documentation for details).

 -- (: UNDOC_REEXPORT) char_code/2:
     Imported from `iso_byte_char' (see the corresponding
     documentation for details).

 -- (: UNDOC_REEXPORT) unify_with_occurs_check/2:
     Imported from `iso_misc' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) sub_atom/5:
     Imported from `iso_misc' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) compound/1:
     Imported from `iso_misc' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) once/1:
     Imported from `iso_misc' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) \=/2:
     Imported from `iso_misc' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) format_control/1:
     Imported from `format' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) format/3:
     Imported from `format' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) format/2:
     Imported from `format' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) keylist/1:
     Imported from `sort' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) keysort/2:
     Imported from `sort' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) sort/2:
     Imported from `sort' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) between/3:
     Imported from `between' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) cyg2win/3:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) rename_file/2:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) delete_directory/1:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) delete_file/1:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) chmod/3:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) chmod/2:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) fmode/2:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) modif_time0/2:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) modif_time/2:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) file_properties/6:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) file_property/2:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) file_exists/2:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) file_exists/1:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) mktemp/2:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) directory_files/2:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) wait/3:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) exec/8:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) exec/3:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) exec/4:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) popen_mode/1:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) popen/3:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) system/2:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) system/1:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) shell/2:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) shell/1:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) shell/0:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) cd/1:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) working_directory/2:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) make_dirpath/1:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) make_dirpath/2:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) make_directory/1:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) make_directory/2:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) umask/2:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) current_executable/1:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) current_host/1:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) get_pid/1:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) extract_paths/2:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) setenvstr/2:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) getenvstr/2:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) datime_struct/1:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) datime/9:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) datime/1:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) time/1:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) pause/1:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) new_atom/1:
     Imported from `prolog_sys' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) garbage_collect/0:
     Imported from `prolog_sys' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) current_atom/1:
     Imported from `prolog_sys' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) predicate_property/2:
     Imported from `prolog_sys' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) statistics/2:
     Imported from `prolog_sys' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) statistics/0:
     Imported from `prolog_sys' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) close_file/1:
     Imported from `dec10_io' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) told/0:
     Imported from `dec10_io' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) telling/1:
     Imported from `dec10_io' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) tell/1:
     Imported from `dec10_io' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) seen/0:
     Imported from `dec10_io' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) seeing/1:
     Imported from `dec10_io' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) see/1:
     Imported from `dec10_io' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) current_key/2:
     Imported from `old_database' (see the corresponding
     documentation for details).

 -- (: UNDOC_REEXPORT) recorded/3:
     Imported from `old_database' (see the corresponding
     documentation for details).

 -- (: UNDOC_REEXPORT) recordz/3:
     Imported from `old_database' (see the corresponding
     documentation for details).

 -- (: UNDOC_REEXPORT) recorda/3:
     Imported from `old_database' (see the corresponding
     documentation for details).

 -- (: UNDOC_REEXPORT) ttydisplay_string/1:
     Imported from `ttyout' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) ttyskipeol/0:
     Imported from `ttyout' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) ttydisplayq/1:
     Imported from `ttyout' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) ttydisplay/1:
     Imported from `ttyout' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) ttyflush/0:
     Imported from `ttyout' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) ttytab/1:
     Imported from `ttyout' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) ttyskip/1:
     Imported from `ttyout' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) ttyput/1:
     Imported from `ttyout' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) ttynl/0:
     Imported from `ttyout' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) ttyget1/1:
     Imported from `ttyout' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) ttyget/1:
     Imported from `ttyout' (see the corresponding documentation for
     details).

PART III - ISO-Prolog library (iso)
***********************************

*Author(s):* The CLIP Group.

   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.

31 ISO-Prolog package
*********************

*Author(s):* The CLIP Group.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#196 (2003/12/19, 17:2:41 CET)

   This library package allows the use of the ISO-Prolog predicates
in Ciao programs. The compatibility is not at 100% yet.

31.1 Usage and interface (`iso')
================================

   * *Library usage:*

     `:- use_package(iso).'

     or

     `:- module(...,...,[iso]).'

   * *Other modules used:*
        - _System library modules:_

          `aggregates', `dynamic', `iso_misc', `iso_byte_char', `iso_incomplete', `operators', `read', `write'.

32 All solutions predicates
***************************

*Author(s):* First version by Richard A. O'Keefe and David H.D.
Warren. Changes by Mats Carlsson, Daniel Cabeza, and Manuel
Hermenegildo.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.5#115 (2000/4/12, 12:17:22 CEST)

   This module implements the standard solution aggregation
predicates.

   When there are many solutions to a problem, and when all those
solutions are required to be collected together, this can be achieved
by repeatedly backtracking and gradually building up a list of the
solutions. The following built-in predicates are provided to automate
this process.

32.1 Usage and interface (`aggregates')
=======================================

   * *Library usage:*

     `:- use_module(library(aggregates)).'

   * *Exports:*
        - _Predicates:_

          `setof/3', `bagof/3', `findall/3', `findall/4', `findnsols/4', `findnsols/5', `^/2'.

   * *Other modules used:*
        - _System library modules:_

          `sort', `lists'.

32.2 Documentation on exports (`aggregates')
============================================

 -- PREDICATE: setof/3:
     `setof(Template, Generator, Set)'

     Finds the `Set' of instances of the `Template' satisfying
     `Generator'. The set is in ascending order (see Comparing terms
     for a definition of this order) without duplicates, and
     is non-empty. If there are no solutions, `setof' fails. `setof'
     may succeed in more than one way, binding free variables in
     `Generator' to different values. This can be avoided by using
     existential quantifiers on the free variables in front of
     `Generator', using `^/2'. For example, given the clauses:
          father(bill, tom).
          father(bill, ann).
          father(bill, john).
          father(harry, july).
          father(harry, daniel).

     The following query produces two alternative solutions via
     backtracking:
          ?- setof(X,father(F,X),Sons).

          F = bill,
          Sons = [ann,john,tom] ? ;

          F = harry,
          Sons = [daniel,july] ? ;

          no
          ?-

     _Meta-predicate_ with arguments: `setof(?,goal,?)'.

     *General properties:* `setof(X, Y, Z)'
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP as
          `findall(X,Y,Z)'.   (`basic_props:native/2')

 -- PREDICATE: bagof/3:
     `bagof(Template, Generator, Bag)'

     Finds all the instances of the `Template' produced by the
     `Generator', and returns them in the `Bag' in the order in which
     they were found. If the `Generator' contains free variables
     which are not bound in the `Template', it assumes that this is
     like any other Prolog question and that you want bindings for
     those variables. This can be avoided by using existential
     quantifiers on the free variables in front of the `Generator',
     using `^/2'.

     _Meta-predicate_ with arguments: `bagof(?,goal,?)'.

     *General properties:* `bagof(X, Y, Z)'
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP as
          `findall(X,Y,Z)'.   (`basic_props:native/2')

 -- PREDICATE: findall/3:
     `findall(Template, Generator, List)'

     A special case of bagof, where all free variables in the
     `Generator' are taken to be existentially quantified. Faster
     than the other aggregation predicates.

     _Meta-predicate_ with arguments: `findall(?,goal,?)'.

     *Usage:* `findall(@term, +callable, ?list)' < * ISO * >
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: findall/4:
     _Meta-predicate_ with arguments: `findall(?,goal,?,?)'.

     *Usage:* `findall(Template, Generator, List, Tail)'
        - _Description:_ As `findall/3', but returning in `Tail' the
          tail of `List'.

 -- PREDICATE: findnsols/4:
     `findnsols(N, Template, Generator, List)'

     As `findall/3', but generating at most `N' solutions of
     `Generator'. Thus, the length of `List' will not be greater than
     `N'. If `N'=<0, returns directly an empty list. This predicate
     is especially useful if `Generator' may have an infinite number
     of solutions.

     _Meta-predicate_ with arguments: `findnsols(?,?,goal,?)'.

 -- PREDICATE: findnsols/5:
     `findnsols(N, Template, Generator, List, Tail)'

     As `findnsols/4', but returning in `Tail' the tail of `List'.

     _Meta-predicate_ with arguments: `findnsols(?,?,goal,?,?)'.

 -- PREDICATE: ^/2:
     *General properties:* `_X ^ Y'
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP as
          `call(Y)'.   (`basic_props:native/2')

     *Usage:* `X ^ P'
        - _Description:_ Existential quantification: `X' is
          existentially quantified in `P'. E.g., in `A^p(A,B)', `A'
          is existentially quantified. Used only within aggregation
          predicates. In all other contexts, simply, execute the
          procedure call `P'.

33 Dynamic predicates
*********************

*Author(s):* The CLIP Group.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#197 (2003/12/19, 17:4:32 CET)

   This module implements the assert/retract family of predicates to
manipulate dynamic predicates.

   The predicates defined in this module allow modification of the
program as it is actually running. Clauses can be added to the
program (_asserted_) or removed from the program (_retracted_). For
these predicates, the argument which corresponds to the clause head
must be instantiated to an atom or a compound term. The argument
corresponding to the clause must be instantiated either to a term
`Head :- Body' or, if the body part is empty, to `Head'. An empty
body part is represented as `true'. Note that using this library is
very detrimental to global analysis, and that for most uses the
predicates listed in Fast/concurrent update of facts suffice.

33.1 Usage and interface (`dynamic')
====================================

   * *Library usage:*

     `:- use_module(library(dynamic)).'

   * *Exports:*
        - _Predicates:_

          `asserta/1', `asserta/2', `assertz/1', `assertz/2', `assert/1', `assert/2', `retract/1', `retractall/1', `abolish/1', `clause/2', `clause/3', `current_predicate/1', `current_predicate/2', `dynamic/1', `data/1', `wellformed_body/3'.

        - _Multifiles:_

          `do_on_abolish/1'.

   * *Other modules used:*
        - _System library modules:_

          `prolog_sys'.

33.2 Documentation on exports (`dynamic')
=========================================

 -- PREDICATE: asserta/1:
     _Meta-predicate_ with arguments: `asserta(clause)'.

     *Usage:* `asserta(+Clause)' < * ISO * >
        - _Description:_ The current instance of `Clause' is
          interpreted as a clause and is added to the current
          program. The predicate concerned must be dynamic. The new
          clause becomes the _first_ clause for the predicate
          concerned. Any uninstantiated variables in `Clause' will be
          replaced by new private variables.

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: asserta/2:
     _Meta-predicate_ with arguments: `asserta(clause,?)'.

     *Usage:* `asserta(+Clause, -Ref)'
        - _Description:_ Like `asserta/1'. `Ref' is a unique
          identifier of the asserted clause.

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: assertz/1:
     _Meta-predicate_ with arguments: `assertz(clause)'.

     *Usage:* `assertz(+Clause)' < * ISO * >
        - _Description:_ Like `asserta/1', except that the new clause
          becomes the _last_ clause for the predicate concerned.

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: assertz/2:
     _Meta-predicate_ with arguments: `assertz(clause,?)'.

     *Usage:* `assertz(+Clause, -Ref)'
        - _Description:_ Like `assertz/1'. `Ref' is a unique
          identifier of the asserted clause.

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: assert/1:
     _Meta-predicate_ with arguments: `assert(clause)'.

     *Usage:* `assert(+Clause)'
        - _Description:_ Identical to `assertz/1'. Included for
          compatibility.

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: assert/2:
     _Meta-predicate_ with arguments: `assert(clause,?)'.

     *Usage:* `assert(+Clause, -Ref)'
        - _Description:_ Identical to `assertz/2'. Included for
          compatibility.

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: retract/1:
     _Meta-predicate_ with arguments: `retract(clause)'.

     *Usage:* `retract(+Clause)' < * ISO * >
        - _Description:_ The first clause in the program that matches
          `Clause' is erased. The predicate concerned must be dynamic.

          The predicate `retract/1' may be used in a non-determinate
          fashion, i.e., it will successively retract clauses
          matching the argument through backtracking. If reactivated
          by backtracking, invocations of the predicate whose clauses
          are being retracted will proceed unaffected by the
          retracts. This is also true for invocations of `clause' for
          the same predicate. The space occupied by a retracted
          clause will be recovered when instances of the clause are
          no longer in use.

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: retractall/1:
     _Meta-predicate_ with arguments: `retractall(fact)'.

     *Usage:* `retractall(+Head)'
        - _Description:_ Erase all clauses whose head matches `Head',
          where `Head' must be instantiated to an atom or a compound
          term. The predicate concerned must be dynamic. The
          predicate definition is retained.

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: abolish/1:
     _Meta-predicate_ with arguments: `abolish(spec)'.

     *Usage:* `abolish(+Spec)' < * ISO * >
        - _Description:_ Erase all clauses of the predicate specified
          by the predicate spec `Spec'. The predicate definition
          itself is also erased (the predicate is deemed undefined
          after execution of the abolish). The predicates concerned
          must all be user defined.

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: clause/2:
     _Meta-predicate_ with arguments: `clause(fact,?)'.

     *Usage:* `clause(+Head, ?Body)' < * ISO * >
        - _Description:_ The clause '`Head' `:-' `Body'' exists in
          the current program. The predicate concerned must be
          dynamic.

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: clause/3:
     `clause(Head, Body, Ref)'

     Like `clause(Head,Body)', plus the clause is uniquely identified
     by `Ref'.

     _Meta-predicate_ with arguments: `clause(fact,?,?)'.

     *Usage 1:* `clause(+Head, ?Body, ?Ref)'
        - _Description:_ `Head' must be instantiated to an atom or a
          compound term.

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

     *Usage 2:* `clause(?Head, ?Body, +Ref)'
        - _Description:_ `Ref' must be instantiated to a valid
          identifier.

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: current_predicate/1:
     *Usage:* `current_predicate(?Spec)' < * ISO * >
        - _Description:_ A predicate in the current module is named
          `Spec'.

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: current_predicate/2:
     *Usage:* `current_predicate(?Spec, ?Module)'
        - _Description:_ A predicate in `Module' is named `Spec'.
          `Module' never is an engine module.

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: dynamic/1:
     `dynamic Spec'

     `Spec' is of the form `F'/`A'. The predicate named `F' with
     arity `A' is made dynamic in the current module at runtime
     (useful for predicate names generated on-the-fly). If the
     predicate functor name `F' is uninstatiated, a new, unique,
     predicate name is generated at runtime.

 -- PREDICATE: data/1:
     `data Spec'

     `Spec' is of the form `F'/`A'. The predicate named `F' with
     arity `A' is made data in the current module at runtime (useful
     for predicate names generated on-the-fly). If the predicate
     functor name `F' is uninstatiated, a new, unique, predicate name
     is generated at runtime.

 -- PREDICATE: wellformed_body/3:
     `wellformed_body(BodyIn, Env, BodyOut)'

     `BodyIn' is a well-formed clause body. `BodyOut' is its
     counterpart with no single-variable meta-goals (i.e., with
     `call(X)' for `X'). `Env' denotes if global cuts are admissible
     in `BodyIn' (`+' if they are, `-' if they are not).

33.3 Documentation on multifiles (`dynamic')
============================================

 -- PREDICATE: do_on_abolish/1:
     `do_on_abolish(Head)'

     A hook predicate which will be called when the definition of the
     predicate of `Head' is abolished.

     The predicate is _multifile_.

34 Term input
*************

*Author(s):* First versions from SICStus 0.6 code; additional changes
and documentation by Daniel Cabeza and Manuel Carro.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#289 (2004/2/13, 19:46:27 CET)

   This module provides falicities to read terms in Prolog syntax.
This is very convenient in many cases (and not only if you are
writing a Prolog compiler), because Prolog terms are easy to write
and can convey a lot of information in a human-readable fashion.

34.1 Usage and interface (`read')
=================================

   * *Library usage:*

     `:- use_module(library(read)).'

   * *Exports:*
        - _Predicates:_

          `read/1', `read/2', `read_term/2', `read_term/3', `read_top_level/3', `second_prompt/2'.

        - _Multifiles:_

          `define_flag/3'.

   * *Other modules used:*
        - _System library modules:_

          `tokenize', `operators', `lists'.

34.2 Documentation on exports (`read')
======================================

 -- PREDICATE: read/1:
     `read(Term)'

     Like `read(Stream,Term)' with `Stream' associated to the current
     input stream.

 -- PREDICATE: read/2:
     *Usage:* `read(+Stream, ?Term)' < * ISO * >
        - _Description:_ The next term, delimited by a full-stop
          (i.e., a `.' followed by either a space or a control
          character), is read from `Stream' and is unified with
          `Term'. The syntax of the term must agree with current
          operator declarations. If the end of `Stream' has been
          reached, `Term' is unified with the term `end_of_file'.
          Further calls to `read/2' for the same stream will then
          cause an error, unless the stream is connected to the
          terminal (in which case a prompt is opened on the terminal).

        - _The following properties hold upon exit:_

          `+Stream' is an open stream.   (`streams_basic:stream/1')

          `?Term' is any term.   (`basic_props:term/1')

 -- PREDICATE: read_term/2:
     *Usage:* `read_term(?Term, +Options)' < * ISO * >
        - _Description:_ Like `read_term/3', but reading from the current
          input

        - _The following properties hold upon exit:_

          `?Term' is any term.   (`basic_props:term/1')

          `+Options' is a list of `read_option's.
          (`basic_props:list/2')

 -- PREDICATE: read_term/3:
     *Usage:* `read_term(+Stream, ?Term, +Options)' < * ISO * >
        - _Description:_ Reads a `Term' from `Stream' with the
          ISO-Prolog `Options'. These options can control the
          behavior of read term (see `read_option/1').

        - _The following properties hold upon exit:_

          `+Stream' is an open stream.   (`streams_basic:stream/1')

          `?Term' is any term.   (`basic_props:term/1')

          `+Options' is a list of `read_option's.
          (`basic_props:list/2')

 -- PREDICATE: read_top_level/3:
     `read_top_level(Stream, Data, Variables)'

     Predicate used to read in the Top Level.

 -- PREDICATE: second_prompt/2:
     *Usage:* `second_prompt(?Old, ?New)'
        - _Description:_ Changes the prompt (the _second prompt_, as
          oposed to the first one, used by the toplevel) used by `read/2'
          and friends to `New', and returns the current one in `Old'.

        - _The following properties should hold upon exit:_

          `?Old' is currently instantiated to an atom.
          (`term_typing:atom/1')

          `?New' is currently instantiated to an atom.
          (`term_typing:atom/1')

34.3 Documentation on multifiles (`read')
=========================================

 -- PREDICATE: define_flag/3:
     Defines flags as follows:
          define_flag(read_hiord,[on,off],off).
     (See Changing system behaviour and various flags).

     If flag is `on' (it is `off' by default), a variable followed by
     a parenthesized lists of arguments is read as a `call/N' term,
     except if the variable is anonymous, in which case it is read as
     an anonymous predicate abstraction head. For example, `P(X)' is
     read as `call(P,X)' and `_(X,Y)' as `''(X,Y)'.

     The predicate is _multifile_.

34.4 Documentation on internals (`read')
========================================

 -- REGTYPE: read_option/1:
     *Usage:* `read_option(Option)'
        - _Description:_ `Option' is an allowed `read_term/[2,3]'
          option. These options are:
               read_option(variables(_V)).
               read_option(variable_names(_N)).
               read_option(singletons(_S)).
               read_option(lines(_StartLine,_EndLine)).
               read_option(dictionary(_Dict)).
          They can be used to return the singleton variables in the
          term, a list of variables, etc.

        - _The following properties should hold upon exit:_

          `Option' is currently instantiated to an atom.
          (`term_typing:atom/1')

34.5 Known bugs and planned improvements (`read')
=================================================

   * The comma cannot be redefined as an operator, it is defined in
     any case as op(1000, xfy,[',']).

35 Term output
**************

*Author(s):* Adapted from shared code written by Richard A. O'Keefe.
Changes by Mats Carlsson, Daniel Cabeza, Manuel Hermenegildo, and
Manuel Carro..

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#290 (2004/2/13, 20:20:3 CET)

   This library provides different predicates for term output,
additional to the kernel predicates `display/1'- `display/2' and
`displayq/1'-`displayq/2'. All the predicates defined in ISO-Prolog
are included, plus other traditionally provided by Prolog
Implementations. Output predicates are provided in two versions: one
that uses the current output stream and other in which the stream is
specified explicitly, as an additional first argument.

35.1 Usage and interface (`write')
==================================

   * *Library usage:*

     `:- use_module(library(write)).'

   * *Exports:*
        - _Predicates:_

          `write_term/3', `write_term/2', `write/2', `write/1', `writeq/2', `writeq/1', `write_canonical/2', `write_canonical/1', `print/2', `print/1', `write_list1/1', `portray_clause/2', `portray_clause/1', `numbervars/3', `prettyvars/1', `printable_char/1'.

        - _Properties:_

          `write_option/1'.

        - _Multifiles:_

          `define_flag/3', `portray_attribute/2', `portray/1'.

   * *Other modules used:*
        - _System library modules:_

          `operators', `sort'.

35.2 Documentation on exports (`write')
=======================================

 -- PREDICATE: write_term/3:
     *Usage:* `write_term(@Stream, ?Term, +OptList)' < * ISO * >
        - _Description:_ Outputs the term `Term' to the stream
          `Stream', with the list of write-options `OptList'. See `write_option/1'
          type for default options.

        - _The following properties hold upon exit:_

          `@Stream' is an open stream.   (`streams_basic:stream/1')

          `?Term' is any term.   (`basic_props:term/1')

          `+OptList' is a list of `write_option's.
          (`basic_props:list/2')

 -- PREDICATE: write_term/2:
     *Usage:* `write_term(?Term, +OptList)' < * ISO * >
        - _Description:_ Behaves like `current_output(S),
          write_term(S,Term,OptList)'.

        - _The following properties hold upon exit:_

          `?Term' is any term.   (`basic_props:term/1')

          `+OptList' is a list of `write_option's.
          (`basic_props:list/2')

 -- PROPERTY: write_option/1:
     `Opt' is a valid write option which affects the predicate
     `write_term/3' and similar ones. Possible write_options are:
        * *quoted(*_bool_*):* If _bool_ is `true', atoms and functors
          that can't be read back by `read_term/3' are quoted, if it
          is `false', each atom and functor is written as its name.
          Default value is `false'.

        * *ignore_ops(*_flag_*):* If _flag_ is `true', each compound
          term is output in functional notation, if it is `ops',
          curly bracketed notation and list notation is enabled when
          outputing compound terms, if it is `false', also operator
          notation is enabled when outputing compound terms. Default
          value is `false'.

        * *numbervars(*_bool_*):* If _bool_ is `true', a term of the
          form `'$VAR'(N)' where `N' is an integer, is output as a
          variable name consisting of a capital letter possibly
          followed by an integer, a term of the form `'$VAR'(Atom)'
          where `Atom' is an atom, as this atom (without quotes), and
          a term of the form `'$VAR'(String)' where `String' is a
          character string, as the atom corresponding to this
          character string. See predicates `numbervars/3' and
          `prettyvars/1'. If _bool_ is `false' this cases are not
          treated in any special way. Default value is `false'.

        * *portrayed(*_bool_*):* If _bool_ is `true', then call
          multifile predicates `portray/1' and `portray_attribute/2',
          to provide the user handlers for pretty printing some
          terms. `portray_attribute/2' is called whenever an
          attributed variable is to be printed, `portray/1' is called
          whenever a non-variable term is to be printed. If either
          call succeeds, then it is assumed that the term has been
          output, else it is printed as usual. If _bool_ is `false',
          these predicates are not called. Default value is `false'.
          This option is set by the toplevel when writting the final
          values of variables, and by the debugging package when
          writting the goals in the tracing messages. Thus you can
          vary the forms of these messages if you wish.

        * *max_depth(*_depth_*):* _depth_ is a positive integer or
          cero. If it is positive, it denotes the depth limit on
          printing compound terms. If it is cero, there is no limit.
          Default value is `0' (no limit).

        * *priority(*_prio_*):* _prio_ is an integer between 1 and
          1200. If the term to be printed has higher priority than
          _prio_, it will be printed parenthesized. Default value is
          1200 (no term parenthesized).

     .

     *Usage:* `write_option(Opt)'
        - _Description:_ `Opt' is a valid write option.

 -- PREDICATE: write/2:
     *Usage:* `write(@Stream, ?Term)' < * ISO * >
        - _Description:_ Behaves like `write_term(Stream, Term,
          [numbervars(true)])'.

        - _The following properties hold upon exit:_

          `@Stream' is an open stream.   (`streams_basic:stream/1')

          `?Term' is any term.   (`basic_props:term/1')

 -- PREDICATE: write/1:
     *Usage:* `write(?Term)' < * ISO * >
        - _Description:_ Behaves like `current_output(S),
          write(S,Term)'.

        - _The following properties hold upon exit:_

          `?Term' is any term.   (`basic_props:term/1')

 -- PREDICATE: writeq/2:
     *Usage:* `writeq(@Stream, ?Term)' < * ISO * >
        - _Description:_ Behaves like `write_term(Stream, Term,
          [quoted(true), numbervars(true)])'.

        - _The following properties hold upon exit:_

          `@Stream' is an open stream.   (`streams_basic:stream/1')

          `?Term' is any term.   (`basic_props:term/1')

 -- PREDICATE: writeq/1:
     *Usage:* `writeq(?Term)' < * ISO * >
        - _Description:_ Behaves like `current_output(S),
          writeq(S,Term)'.

        - _The following properties hold upon exit:_

          `?Term' is any term.   (`basic_props:term/1')

 -- PREDICATE: write_canonical/2:
     *Usage:* `write_canonical(@Stream, ?Term)' < * ISO * >
        - _Description:_ Behaves like `write_term(Stream, Term,
          [quoted(true), ignore_ops(true)])'. The output of this
          predicate can always be parsed by `read_term/2' even if the
          term contains special characters or if operator
          declarations have changed.

        - _The following properties hold upon exit:_

          `@Stream' is an open stream.   (`streams_basic:stream/1')

          `?Term' is any term.   (`basic_props:term/1')

 -- PREDICATE: write_canonical/1:
     *Usage:* `write_canonical(?Term)' < * ISO * >
        - _Description:_ Behaves like `current_output(S),
          write_canonical(S,Term)'.

        - _The following properties hold upon exit:_

          `?Term' is any term.   (`basic_props:term/1')

 -- PREDICATE: print/2:
     *Usage:* `print(@Stream, ?Term)'
        - _Description:_ Behaves like `write_term(Stream, Term,
          [numbervars(true), portrayed(true)])'.

        - _The following properties hold upon exit:_

          `@Stream' is an open stream.   (`streams_basic:stream/1')

          `?Term' is any term.   (`basic_props:term/1')

 -- PREDICATE: print/1:
     *Usage:* `print(?Term)'
        - _Description:_ Behaves like `current_output(S),
          print(S,Term)'.

        - _The following properties hold upon exit:_

          `?Term' is any term.   (`basic_props:term/1')

 -- PREDICATE: write_list1/1:
     *Usage:*
        - _Description:_ Writes a list to current output one element
          in each line.

        - _Calls should, and exit will be compatible with:_

          `Arg1' is a list.   (`basic_props:list/1')

 -- PREDICATE: portray_clause/2:
     *Usage:* `portray_clause(@Stream, ?Clause)'
        - _Description:_ Outputs the clause `Clause' onto `Stream',
          pretty printing its variables and using indentation,
          including a period at the end. This predicate is used by
          `listing/0'.

        - _The following properties hold upon exit:_

          `@Stream' is an open stream.   (`streams_basic:stream/1')

          `?Clause' is any term.   (`basic_props:term/1')

 -- PREDICATE: portray_clause/1:
     *Usage:* `portray_clause(?Clause)'
        - _Description:_ Behaves like `current_output(S),
          portray_clause(S,Term)'.

        - _The following properties hold upon exit:_

          `?Clause' is any term.   (`basic_props:term/1')

 -- PREDICATE: numbervars/3:
     *Usage:* `numbervars(?Term, +N, ?M)'
        - _Description:_ Unifies each of the variables in term `Term'
          with a term of the form `'$VAR'(I)' where `I' is an integer
          from `N' onwards. `M' is unified with the last integer used
          plus 1. If the resulting term is output with a write option
          `numbervars(true)', in the place of the variables in the
          original term will be printed a variable name consisting of
          a capital letter possibly followed by an integer. When `N'
          is 0 you will get the variable names A, B, ..., Z, A1, B1,
          etc.

        - _The following properties hold upon exit:_

          `?Term' is any term.   (`basic_props:term/1')

          `+N' is an integer.   (`basic_props:int/1')

          `?M' is an integer.   (`basic_props:int/1')

 -- PREDICATE: prettyvars/1:
     *Usage:* `prettyvars(?Term)'
        - _Description:_ Similar to `numbervars(Term,0,_)', except
          that singleton variables in `Term' are unified with
          `'$VAR'('_')', so that when the resulting term is output
          with a write option `numbervars(true)', in the place of
          singleton variables `_' is written. This predicate is used
          by `portray_clause/2'.

        - _The following properties hold upon exit:_

          `?Term' is any term.   (`basic_props:term/1')

 -- PREDICATE: printable_char/1:
     *Usage:* `printable_char(+Char)'
        - _Description:_ `Char' is the code of a character which can
          be printed.

        - _The following properties should hold upon exit:_

          `+Char' is currently instantiated to a number.
          (`term_typing:number/1')

35.3 Documentation on multifiles (`write')
==========================================

 -- PREDICATE: define_flag/3:
     Defines flags as follows:
          define_flag(write_strings,[on,off],off).
     (See Changing system behaviour and various flags).

     If flag is `on', lists which may be written as strings are.

     The predicate is _multifile_.

 -- PREDICATE: portray_attribute/2:
     The predicate is _multifile_.

     *Usage:* `portray_attribute(Attr, Var)'
        - _Description:_ _A user defined predicate._ When an
          attributed variable `Var' is about to be printed, this
          predicate receives the variable and its attribute `Attr'.
          The predicate should either print something based on `Attr'
          or `Var', or do nothing and fail. In the latter case, the
          default printer ( `write/1') will print the attributed
          variable like an unbound variable, e.g. `_673'.

        - _The following properties should hold at call time:_

          `Attr' is currently a term which is not a free variable.
          (`term_typing:nonvar/1')

          `Var' is a free variable.   (`term_typing:var/1')

 -- PREDICATE: portray/1:
     The predicate is _multifile_.

     *Usage:* `portray(?Term)'
        - _Description:_ _A user defined predicate._ This should
          either print the `Term' and succeed, or do nothing and
          fail. In the latter case, the default printer (`write/1')
          will print the `Term'.

36 Defining operators
*********************

*Author(s):* Adapted from SICStus 0.6 code; modifications and
documentation by Daniel Cabeza and Manuel Carro.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#287 (2004/2/13, 18:59:4 CET)

   Operators allow writting terms in a more clear way than the
standard functional notation. Standard operators in Ciao are defined
by this predicate (but note that the compiler itself defines more
operators at compile time):
     standard_ops :-
             op(1200,xfx,[:-]),
             op(1200,fx,[:-,?-]),
             op(1100,xfy,[;]),
             op(1050,xfy,[->]),
             op(1000,xfy,[',']),
             op(900,fy,[\+]),
             op(700,xfx,[=,\=,==,\==,@<,@>,@=<,@>=,=..,is,=:=,=\=,<,=<,>,>=]),
             op(550,xfx,[:]),
             op(500,yfx,[+,-,/\,\/,#]),
             op(500,fy,[++,--]),
             op(400,yfx,[*,/,//,rem,mod,<<,>>]),
             op(200,fy,[+,-,\]),
             op(200,xfx,[**]),
             op(200,xfy,[^]).

36.1 Usage and interface (`operators')
======================================

   * *Library usage:*

     `:- use_module(library(operators)).'

   * *Exports:*
        - _Predicates:_

          `op/3', `current_op/3', `current_prefixop/3', `current_infixop/4', `current_postfixop/3'.

36.2 Documentation on exports (`operators')
===========================================

 -- PREDICATE: op/3:
     `op(Precedence, Type, Name)'

     Declares the atom `Name' to be an operator of the stated `Type'
     and `Precedence' (0 =< `Precedence' =< 1200). `Name' may also be
     a list of atoms in which case all of them are declared to be
     operators. If `Precedence' is 0 then the operator properties of
     `Name' (if any) are cancelled. Note that, unlike in ISO-Prolog,
     it is allowed to define two operators with the same name, one
     infix and the other postfix.

     *Usage:* `op(+int, +operator_specifier, +atm_or_atm_list)' < *
     ISO * >
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: current_op/3:
     `current_op(Precedence, Type, Op)'

     The atom `Op' is currently an operator of type `Type' and
     precedence `Precedence'. Neither `Op' nor the other arguments
     need be instantiated at the time of the call; i.e., this
     predicate can be used to generate as well as to test.

     *Usage:* `current_op(?int, ?operator_specifier, ?atm)' < * ISO *
     >
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: current_prefixop/3:
     `current_prefixop(Op, Less, Precedence)'

     Similar to `current_op/3', but it concerns only the prefix
     operators. It returns *only one solution*. Not a predicate for
     general use.

 -- PREDICATE: current_infixop/4:
     `current_infixop(Op, LeftLess, Prec, RightLess)'

     Similar to `current_op/3', but it concerns only infix operators.
     It returns *only one solution*. Not a predicate for general use.

 -- PREDICATE: current_postfixop/3:
     `current_postfixop(Op, Less, Precedence)'

     Similar to `current_op/3', but it concerns only the postfix
     operators. It returns *only one solution*. Not a predicate for
     general use.

37 The Iso Byte Char module
***************************

*Author(s):* The CLIP Group, Daniel Cabeza, Documentation written by
Edison Mera, based on ISO Prolog standard. Minor mods by M.
Hermenegildo..

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#217 (2003/12/21, 15:33:54 CET)

   This module provides some basic predicates according to the ISO
specification of byte and char manipulation.

37.1 Usage and interface (`iso_byte_char')
==========================================

   * *Library usage:*

     `:- use_module(library(iso_byte_char)).'

   * *Exports:*
        - _Predicates:_

          `char_code/2', `atom_chars/2', `number_chars/2', `get_byte/1', `get_byte/2', `peek_byte/1', `peek_byte/2', `put_byte/1', `put_byte/2', `get_char/1', `get_char/2', `peek_char/1', `peek_char/2', `put_char/1', `put_char/2'.

37.2 Documentation on exports (`iso_byte_char')
===============================================

 -- PREDICATE: char_code/2:
     `char_code(Char, Code)'

     Succeeds iff the character code of the one char atom `Char' is
     `Code'.

 -- PREDICATE: atom_chars/2:
     `atom_chars(Atom, Chars)'

     Succeeds iff `Chars' is a list whose elements are the one-char
     atoms whose names are the successive characters of the name of
     atom `Atom'

 -- PREDICATE: number_chars/2:
     `number_chars(Number, Chars)'

     Success iff `Chars' is a list whose elements are the one-char
     atoms corresponding to a character sequence of `Number' which
     could be output

 -- PREDICATE: get_byte/1:
     *Usage:* `get_byte(?int)' < * ISO * >
        - _Description:_ Same as `get_byte/2', but use the current
          input.

 -- PREDICATE: get_byte/2:
     `get_byte(Stream, Byte)'

     Is true iff `Byte' unifies with the next byte to be input from
     the target `Stream'.

 -- PREDICATE: peek_byte/1:
     *Usage:* `peek_byte(?int)' < * ISO * >
        - _Description:_ Same as `peek_byte/2', but use the current
          input.

 -- PREDICATE: peek_byte/2:
     `peek_byte(Stream, Byte)'

     Is true iff `Byte' unifies with the next byte to be input from
     the target `Stream'.

 -- PREDICATE: put_byte/1:
     *Usage:* `put_byte(+int)' < * ISO * >
        - _Description:_ Same as `put_byte/2', but use the current
          input.

 -- PREDICATE: put_byte/2:
     `put_byte(Stream, Byte)'

     Is true. Procedurally, `putbyte/2' is executed as follows:

     a) Outputs the byte `Byte' to the target stream.

     b) Changes the stream position of the target stream to take
     account of the byte which has been output.

     c) The goal succeeds.

 -- PREDICATE: get_char/1:
     *Usage:* `get_char(?atm)' < * ISO * >
        - _Description:_ Same as `get_char/2', but use the current
          input.

 -- PREDICATE: get_char/2:
     `get_char(Stream, Char)'

     Is true iif `Char' unifies with the next character to be input
     from the target `Stream'.

 -- PREDICATE: peek_char/1:
     *Usage:* `peek_char(?atm)' < * ISO * >
        - _Description:_ Similar to `peek_code/1', but using char
          instead of code.

 -- PREDICATE: peek_char/2:
     *Usage:* `peek_char(@stream, ?atm)' < * ISO * >
        - _Description:_ Similar to `peek_code/2', but using char
          instead of code.

 -- PREDICATE: put_char/1:
     *Usage:* `put_char(+atm)' < * ISO * >
        - _Description:_ Similar to `put_code/1', but using char
          instead of code.

 -- PREDICATE: put_char/2:
     *Usage:* `put_char(@stream, +atm)' < * ISO * >
        - _Description:_ Similar to `put_code/2', but using char
          instead of code.

38 Miscellaneous ISO Prolog predicates
**************************************

*Author(s):* Daniel Cabeza.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#304 (2004/2/17, 17:20:4 CET)

   This module implements some miscellaneous ISO Prolog predicates.

38.1 Usage and interface (`iso_misc')
=====================================

   * *Library usage:*

     `:- use_module(library(iso_misc)).'

   * *Exports:*
        - _Predicates:_

          `\=/2', `once/1', `compound/1', `sub_atom/5', `unify_with_occurs_check/2'.

   * *Other modules used:*
        - _System library modules:_

          `between'.

38.2 Documentation on exports (`iso_misc')
==========================================

 -- PREDICATE: \=/2:
     `X \= Y'

     `X' and `Y' are not unifiable.

 -- PREDICATE: once/1:
     `once(G)'

     Finds the first solution of goal `G' (if any).  `once/1' behaves
     as `call/1', except that no further solutions are explored on
     backtracking.

     _Meta-predicate_ with arguments: `once(goal)'.

 -- PREDICATE: compound/1:
     `compound(T)'

     `T' is currently instantiated to a compound term.

 -- PREDICATE: sub_atom/5:
     `sub_atom(Atom, Before, Length, After, Sub_atom)'

     Is true iff atom `Atom' can be broken into three pieces,
     `AtomL', `Sub_atom' and `AtomR' such that `Before' is the number
     of characters of the name of `AtomL', `Length' is the number of
     characters of the name of `Sub_atom' and `After' is the number
     of characters of the name of `AtomR'

 -- PREDICATE: unify_with_occurs_check/2:
     `unify_with_occurs_check(X, Y)'

     Attempts to compute and apply a most general unifier of the two
     terms `X' and `Y'. Is true iff `X' and `Y' are unifiable.

39 Incomplete ISO Prolog predicates
***********************************

*Author(s):* The CLIP Group.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#263 (2003/12/31, 11:55:21 CET)

   This module implements some ISO Prolog predicates, but that are
not complete yet.

39.1 Usage and interface (`iso_incomplete')
===========================================

   * *Library usage:*

     `:- use_module(library(iso_incomplete)).'

   * *Exports:*
        - _Predicates:_

          `close/2', `stream_property/2'.

39.2 Documentation on exports (`iso_incomplete')
================================================

 -- PREDICATE: close/2:
     No further documentation available for this predicate.

 -- PREDICATE: stream_property/2:
     No further documentation available for this predicate.

PART IV - Classic Prolog library (classic)
******************************************

*Author(s):* The CLIP Group.

   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.

40 Definite clause grammars
***************************

*Author(s):* The CLIP Group.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#209 (2003/12/21, 2:5:22 CET)

   This library package allows the use of DCGs (Definite Clause
Grammars) [Col78,PW80] in a Ciao module/program.

   Definite clause grammars are an extension of the well-known
context-free grammars. Prolog's grammar rules provide a convenient
notation for expressing definite clause grammars. A DCG rule in
Prolog takes the general form

     `head' --> `body'.

meaning "a possible form for `head' is `body'". Both `body' and
`head' are sequences of one or more items linked by the standard
Prolog conjunction operator "`,'".

   Definite clause grammars extend context-free grammars in the
following ways:

  1. A non-terminal symbol may be any Prolog term (other than a
     variable or number).

  2. A terminal symbol may be any Prolog term. To distinguish
     terminals from non-terminals, a sequence of one or more terminal
     symbols is written within a grammar rule as a Prolog list. An
     empty sequence is written as the empty list `[]'. If the
     terminal symbols are ASCII character codes, such lists can be
     written (as elsewhere) as strings. An empty sequence is written
     as the empty list, `[]' or `""'.

  3. Extra conditions, in the form of Prolog procedure calls, may be
     included in the right-hand side of a grammar rule. Such
     procedure calls are written enclosed in `{}' brackets.

  4. The left-hand side of a grammar rule consists of a non-terminal,
     optionally followed by a sequence of terminals (again written as
     a Prolog list).

  5. Alternatives may be stated explicitly in the right-hand side of
     a grammar rule, using the disjunction operator `;', or, also, as
     traditionally in Prolog, using `|' (which is treated specially
     when this package is loaded).

  6. The cut symbol may be included in the right-hand side of a
     grammar rule, as in a Prolog clause. The cut symbol does not
     need to be enclosed in `{}' brackets.

   As an example, here is a simple grammar which parses an arithmetic
expression (made up of digits and operators) and computes its value.

     expr(Z) --> term(X), "+", expr(Y), {Z is X + Y}.
     expr(Z) --> term(X), "-", expr(Y), {Z is X - Y}.
     expr(X) --> term(X).

     term(Z) --> number(X), "*", term(Y), {Z is X * Y}.
     term(Z) --> number(X), "/", term(Y), {Z is X / Y}.
     term(Z) --> number(Z).

     number(C) --> "+", number(C).
     number(C) --> "-", number(X), {C is -X}.
     number(X) --> [C], {0'0=<C, C=<0'9, X is C - 0'0}.

   In the last rule, `C' is the ASCII code of some digit.

   The query

     ?- expr(Z, "-2+3*5+1", []).

will compute `Z'=14. The two extra arguments are explained below.

   Now, in fact, grammar rules are merely a convenient "syntactic
sugar" for ordinary Prolog clauses. Each grammar rule takes an input
string, analyses some initial portion, and produces the remaining
portion (possibly enlarged) as output for further analysis. The
arguments required for the input and output strings are not written
explicitly in a grammar rule, but the syntax implicitly defines them.
We now show how to translate grammar rules into ordinary clauses by
making explicit the extra arguments.

   A rule such as

     p(X) --> q(X).

translates into

     p(X, S0, S) :- q(X, S0, S).

   If there is more than one non-terminal on the right-hand side, as
in

     p(X, Y) -->
             q(X),
             r(X, Y),
             s(Y).

then corresponding input and output arguments are identified, as in

     p(X, Y, S0, S) :-
             q(X, S0, S1),
             r(X, Y, S1, S2),
             r(Y, S2, S).

   Terminals are translated using the built-in predicate `'C'/3'
(this predicate is not normally useful in itself; it has been given
the name `'C'' simply to avoid using up a more useful name). Then,
for instance

     p(X) --> [go,to], q(X), [stop].

is translated by

     p(X, S0, S) :-
             'C'(S0, go, S1),
             'C'(S1, to, S2),
             q(X, S2, S3),
             'C'(S3, stop, S).

   Extra conditions expressed as explicit procedure calls naturally
translate as themselves, e.g.

     p(X) --> [X], {integer(X), X>0}, q(X).

translates to

     p(X, S0, S) :-
             'C'(S0, X, S1),
             integer(X),
             X>0,
             q(X, S1, S).

   Similarly, a cut is translated literally.

   Terminals on the left-hand side of a rule translate into an
explicit list in the output argument of the main non-terminal, e.g.

     is(N), [not] --> [aint].

becomes

     is(N, S0, [not|S]) :- 'C'(S0, aint, S).

   Disjunction has a fairly obvious translation, e.g.

     args(X, Y) -->
             (   dir(X), [to], indir(Y)
             ;   indir(Y), dir(X)
             ).

translates to

     args(X, Y, S0, S) :-
             (   dir(X, S0, S1),
                 'C'(S1, to, S2),
                 indir(Y, S2, S)
             ;   indir(Y, S0, S1),
                 dir(X, S1, S)
             ).

40.1 Usage and interface (`dcg')
================================

   * *Library usage:*

     `:- use_package(dcg).'

     or

     `:- module(...,...,[dcg]).'

41 Definite clause grammars (expansion)
***************************************

*Author(s):* Daniel Cabeza.

   *Version:* 1.9#302 (2004/2/16, 18:48:1 CET)

   This module implements the Definite clause grammars (expansion).

41.1 Usage and interface (`dcg_expansion')
==========================================

   * *Library usage:*

     `:- use_module(library(dcg_expansion)).'

   * *Exports:*
        - _Predicates:_

          `phrase/2', `phrase/3', `dcg_translation/2'.

   * *Other modules used:*
        - _System library modules:_

          `terms', `assertions/doc_props'.

41.2 Documentation on exports (`dcg_expansion')
===============================================

 -- PREDICATE: phrase/2:
     `phrase(Phrase, List)'

     Like `phrase(Phrase,List,[])'.

     _Meta-predicate_ with arguments: `phrase(goal,?)'.

 -- PREDICATE: phrase/3:
     _Meta-predicate_ with arguments: `phrase(goal,?,?)'.

     *Usage:* `phrase(+Phrase, ?List, ?Remainder)'
        - _Description:_ The list `List' is a phrase of type `Phrase'
          (according to the current grammar rules), where `Phrase' is
          either a non-terminal or more generally a grammar rule
          body. `Remainder' is what remains of the list after a
          phrase has been found.

        - _The following properties should hold globally:_

          Documentation is still incomplete:
          `phrase(+Phrase,?List,?Remainder)' may not conform the
          functionality documented.   (`doc_props:doc_incomplete/1')

 -- PREDICATE: dcg_translation/2:
     Performs the code expansion of source clauses that use DCGs.

42 Formatted output
*******************

*Author(s):* The CLIP Group.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#212 (2003/12/21, 2:18:19 CET)

   The `format' family of predicates is due to Quintus Prolog. They
act as a Prolog interface to the C `stdio' function `printf()',
allowing formatted output.

   Output is formatted according to an output pattern which can have
either a format control sequence or any other character, which will
appear verbatim in the output. Control sequences act as place-holders
for the actual terms that will be output. Thus
             ?- format("Hello ~q!",world).
   will print `Hello world!'.

   If there is only one item to print it may be supplied alone. If
there are more they have to be given as a list. If there are none
then an empty list should be supplied. There has to be as many items
as control characters.

   The character `~' introduces a control sequence. To print a `~'
verbatim just repeat it:
             ?- format("Hello ~~world!", []).
   will result in `Hello ~world!'.

   A format may be spread over several lines. The control sequence
`\c' followed by a <LFD> will translate to the empty string:
             ?- format("Hello \c
             world!", []).
   will result in `Hello world!'.

42.1 Usage and interface (`format')
===================================

   * *Library usage:*

     `:- use_module(library(format)).'

   * *Exports:*
        - _Predicates:_

          `format/2', `format/3'.

        - _Regular Types:_

          `format_control/1'.

   * *Other modules used:*
        - _System library modules:_

          `write', `assertions/doc_props'.

42.2 Documentation on exports (`format')
========================================

 -- PREDICATE: format/2:
     *General properties:* `format(C, A)'
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP as
          `format(C,A)'.   (`basic_props:native/2')

     *Usage:* `format(Format, Arguments)'
        - _Description:_ Print `Arguments' onto current output stream
          according to format `Format'.

        - _Calls should, and exit will be compatible with:_

          `Format' is an atom or string describing how the arguments
          should be formatted. If it is an atom it will be converted
          into a string with `name/2'.   (`format:format_control/1')

 -- PREDICATE: format/3:
     *General properties:* `format(S, C, A)'
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP as
          `format(S,C,A)'.   (`basic_props:native/2')

     *Usage:* `format(+Stream, Format, Arguments)'
        - _Description:_ Print `Arguments' onto `Stream' according to
          format `Format'.

        - _Calls should, and exit will be compatible with:_

          `Format' is an atom or string describing how the arguments
          should be formatted. If it is an atom it will be converted
          into a string with `name/2'.   (`format:format_control/1')

 -- REGTYPE: format_control/1:
     The general format of a control sequence is `~`N'`C''. The
     character `C' determines the type of the control sequence. `N'
     is an optional numeric argument. An alternative form of `N' is
     `*'. `*' implies that the next argument in `Arguments' should be
     used as a numeric argument in the control sequence. Example:

          ?- format("Hello~4cworld!", [0'x]).

     and

          ?- format("Hello~*cworld!", [4,0'x]).

     both produce

          Helloxxxxworld!

     The following control sequences are available.

        * ~a The argument is an atom. The atom is printed without
          quoting.

        * ~`N'c (Print character.) The argument is a number that will
          be interpreted as an ASCII code. `N' defaults to one and is
          interpreted as the number of times to print the character.

        * ~`N'e

        * ~`N'E

        * ~`N'f

        * ~`N'g

        * ~`N'G (Print float). The argument is a float. The float and
          `N' will be passed to the C `printf()' function as

               printf("%.`N'e", `Arg')
               printf("%.`N'E", `Arg')
               printf("%.`N'f", `Arg')
               printf("%.`N'g", `Arg')
               printf("%.`N'G", `Arg')

          If `N' is not supplied the action defaults to

               printf("%e", `Arg')
               printf("%E", `Arg')
               printf("%f", `Arg')
               printf("%g", `Arg')
               printf("%G", `Arg')

        * ~`N'd (Print decimal.) The argument is an integer. `N' is
          interpreted as the number of digits after the decimal
          point. If `N' is 0 or missing, no decimal point will be
          printed. Example:

               ?- format("Hello ~1d world!", [42]).
               ?- format("Hello ~d world!", [42]).

          will print as

               Hello 4.2 world!
               Hello 42 world!

          respectively.

        * ~`N'D (Print decimal.) The argument is an integer.
          Identical to `~`N'd' except that `,' will separate groups
          of three digits to the left of the decimal point. Example:

               ?- format("Hello ~1D world!", [12345]).

          will print as

               Hello 1,234.5 world!

        * ~`N'r (Print radix.) The argument is an integer. `N' is
          interpreted as a radix. `N' should be >= 2 and <= 36. If
          `N' is missing the radix defaults to 8. The letters `a-z'
          will denote digits larger than 9. Example:

               ?- format("Hello ~2r world!", [15]).
               ?- format("Hello ~16r world!", [15]).

          will print as

               Hello 1111 world!
               Hello f world!

          respectively.

        * ~`N'R (Print radix.) The argument is an integer. Identical
          to `~`N'r' except that the letters `A-Z' will denote digits
          larger than 9. Example:

               ?- format("Hello ~16R world!", [15]).

          will print as

               Hello F world!

        * ~`N's (Print string.) The argument is a list of ASCII
          codes. Exactly `N' characters will be printed. `N' defaults
          to the length of the string. Example:

               ?- format("Hello ~4s ~4s!", ["new","world"]).
               ?- format("Hello ~s world!", ["new"]).

          will print as

               Hello new  worl!
               Hello new world!

          respectively.

        * ~i (Ignore argument.) The argument may be of any type. The
          argument will be ignored. Example:

               ?- format("Hello ~i~s world!", ["old","new"]).

          will print as

               Hello new world!

        * ~k (Print canonical.) The argument may be of any type. The
          argument will be passed to `write_canonical/2' (see Term output).
          Example:

               ?- format("Hello ~k world!", [[a,b,c]]).

          will print as

               Hello .(a,.(b,.(c,[]))) world!

        * ~p (print.) The argument may be of any type. The argument
          will be passed to `print/2' (see Term output). Example:

          suposing the user has defined the predicate

               :- multifile portray/1.
               portray([X|Y]) :- print(cons(X,Y)).

          then

               ?- format("Hello ~p world!", [[a,b,c]]).

          will print as

               Hello cons(a,cons(b,cons(c,[]))) world!

        * ~q (Print quoted.) The argument may be of any type. The
          argument will be passed to `writeq/2' (see Term output).
          Example:

               ?- format("Hello ~q world!", [['A','B']]).

          will print as

               Hello ['A','B'] world!

        * ~w (write.) The argument may be of any type. The argument
          will be passed to `write/2' (see Term output). Example:

               ?- format("Hello ~w world!", [['A','B']]).

          will print as

               Hello [A,B] world!

        * ~`N'n (Print newline.) Print `N' newlines. `N' defaults to
          1. Example:

               ?- format("Hello ~n world!", []).

          will print as

               Hello
                world!

        * ~N (Fresh line.) Print a newline, if not already at the
          beginning of a line.

        * ~~ (Print tilde.) Prints `~'

     The following control sequences are also available for
     compatibility, but do not perform any useful functions.

        * ~`N'| (Set tab.) Set a tab stop at position `N', where `N'
          defaults to the current position, and advance the current
          position there.

        * ~`N'+ (Advance tab.) Set a tab stop at `N' positions past
          the current position, where `N' defaults to 8, and advance
          the current position there.

        * ~`N't (Set fill character.) Set the fill character to be
          used in the next position movement to `N', where `N'
          defaults to <SPC>.

     *Usage:* `format_control(C)'
        - _Description:_ `C' is an atom or string describing how the
          arguments should be formatted. If it is an atom it will be
          converted into a string with `name/2'.

        - _The following properties should hold globally:_

          Documentation is still incomplete: `format_control(C)' may
          not conform the functionality documented.
          (`doc_props:doc_incomplete/1')

43 List processing
******************

*Author(s):* The CLIP Group.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#318 (2004/2/26, 15:46:54 CET)

   This module provides a set of predicates for list processing.

43.1 Usage and interface (`lists')
==================================

   * *Library usage:*

     `:- use_module(library(lists)).'

   * *Exports:*
        - _Predicates:_

          `nonsingle/1', `append/3', `reverse/2', `reverse/3', `delete/3', `delete_non_ground/3', `select/3', `length/2', `nth/3', `add_after/4', `add_before/4', `dlist/3', `list_concat/2', `list_insert/2', `insert_last/3', `contains_ro/2', `contains1/2', `nocontainsx/2', `last/2', `list_lookup/3', `list_lookup/4', `intset_insert/3', `intset_delete/3', `intset_in/2', `intset_sequence/3', `intersection/3', `union/3', `difference/3', `equal_lists/2', `list_to_list_of_lists/2', `powerset/2', `cross_product/2'.

        - _Properties:_

          `list1/2', `sublist/2', `subordlist/2'.

43.2 Documentation on exports (`lists')
=======================================

 -- PREDICATE: nonsingle/1:
     *Usage:* `nonsingle(X)'
        - _Description:_ `X' is not a singleton.

 -- PREDICATE: append/3:
     *Usage:* `append(Xs, Ys, Zs)'
        - _Description:_ `Zs' is `Ys' appended to `Xs'.

 -- PREDICATE: reverse/2:
     *Usage:* `reverse(Xs, Ys)'
        - _Description:_ Reverses the order of elements in `Xs'.

        - _The following properties should hold at call time:_

          `Xs' is a list.   (`basic_props:list/1')

          `Ys' is any term.   (`basic_props:term/1')

        - _The following properties should hold upon exit:_

          `Xs' is a list.   (`basic_props:list/1')

          `Ys' is a list.   (`basic_props:list/1')

 -- PREDICATE: reverse/3:
     *Usage:* `reverse(A, B, C)'
        - _Description:_ Reverse the order of elements in `A', and
          append it with `B'.

 -- PREDICATE: delete/3:
     *Usage:* `delete(L1, E, L2)'
        - _Description:_ `L2' is `L1' without the ocurrences of `E'.

 -- PREDICATE: delete_non_ground/3:
     *Usage:* `delete_non_ground(L1, E, L2)'
        - _Description:_ `L2' is `L1' without the ocurrences of `E'.
          `E' can be a nonground term so that all the elements in
          `L1' it unifies with will be deleted

 -- PREDICATE: select/3:
     *Usage:* `select(X, Xs, Ys)'
        - _Description:_ `Xs' and `Ys' have the same elements except
          for one occurrence of `X'.

 -- PREDICATE: length/2:
     *General properties:* `length(A, B)'
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

     *Usage 1:* `length(L, N)'
        - _Description:_ Computes the length of `L'.

        - _The following properties should hold at call time:_

          `L' is a list.   (`basic_props:list/1')

          `N' is a free variable.   (`term_typing:var/1')

        - _The following properties hold upon exit:_

          `L' is a list.   (`basic_props:list/1')

          `N' is an integer.   (`basic_props:int/1')

     *Usage 2:* `length(L, N)'
        - _Description:_ Outputs `L' of length `N'.

        - _The following properties should hold at call time:_

          `L' is a free variable.   (`term_typing:var/1')

          `N' is an integer.   (`basic_props:int/1')

        - _The following properties hold upon exit:_

          `L' is a list.   (`basic_props:list/1')

          `N' is an integer.   (`basic_props:int/1')

     *Usage 3:* `length(L, N)'
        - _Description:_ Checks that `L' is of length `N'.

        - _The following properties should hold at call time:_

          `L' is a list.   (`basic_props:list/1')

          `N' is an integer.   (`basic_props:int/1')

        - _The following properties hold upon exit:_

          `L' is a list.   (`basic_props:list/1')

          `N' is an integer.   (`basic_props:int/1')

 -- PREDICATE: nth/3:
     `nth(N, List, Elem)'

     `N' is the position in `List' of `Elem'. `N' counts from one.

     *Usage 1:* `nth(+int, ?list, ?term)'
        - _Description:_ Unifies `Elem' and the `N'th element of
          `List'.

     *Usage 2:* `nth(-int, ?list, ?term)'
        - _Description:_ Finds the positions where `Elem' is in
          `List'. Positions are found in ascending order.

 -- PREDICATE: add_after/4:
     *Usage:* `add_after(+L0, +E0, +E, -L)'
        - _Description:_ Adds element `E' after element `E0' (or at
          end) to list `L0' returning in `L' the new list (uses term
          comparison).

 -- PREDICATE: add_before/4:
     *Usage:* `add_before(+L0, +E0, +E, -L)'
        - _Description:_ Adds element E before element E0 (or at
          start) to list L0 returning in L the new list (uses term
          comparison).

 -- PROPERTY: list1/2:
     _Meta-predicate_ with arguments: `list1(?,pred(1))'.

     *Usage:* `list1(X, Y)'
        - _Description:_ `X' is a list of `Y's of at least one
          element.

 -- PREDICATE: dlist/3:
     *Usage:* `dlist(List, DList, Tail)'
        - _Description:_ `List' is the result of removing `Tail' from
          the end of `DList' (makes a difference list from a list).

 -- PREDICATE: list_concat/2:
     *Usage:* `list_concat(LL, L)'
        - _Description:_ `L' is the concatenation of all the lists in
          `LL'.

        - _Call and exit should be _compatible_ with:_

          `LL' is a list of `list's.   (`basic_props:list/2')

          `L' is a list.   (`basic_props:list/1')

 -- PREDICATE: list_insert/2:
     *Usage:* `list_insert(-List, +Term)'
        - _Description:_ Adds `Term' to the end of `List' if there is
          no element in `List' identical to `Term'.

 -- PREDICATE: insert_last/3:
     *Usage:* `insert_last(+L0, +E, -L)'
        - _Description:_ Adds element `E' at end of list `L0'
          returning `L'.

 -- PREDICATE: contains_ro/2:
     *Usage:*
        - _Description:_ Impure membership (does not instantiate a
          variable in its first argument.

 -- PREDICATE: contains1/2:
     *Usage:*
        - _Description:_ First membership.

 -- PREDICATE: nocontainsx/2:
     *Usage:* `nocontainsx(L, X)'
        - _Description:_ `X' is not identical to any element of `L'.

 -- PREDICATE: last/2:
     *Usage:* `last(L, X)'
        - _Description:_ `X' is the last element of list `L'.

 -- PREDICATE: list_lookup/3:
     *Usage:* `list_lookup(List, Key, Value)'
        - _Description:_ Same as `list_lookup/4', but use `-/2' as
          functor.

 -- PREDICATE: list_lookup/4:
     *Usage:* `list_lookup(List, Functor, Key, Value)'
        - _Description:_ Look up `Functor'(`Key',`Value') pair in
          variable ended key-value pair list `L' or else add it at
          the end.

 -- PREDICATE: intset_insert/3:
     *Usage:* `intset_insert(A, B, Set)'
        - _Description:_ Insert the element `B' in the ordered set of
          numbers `A'.

 -- PREDICATE: intset_delete/3:
     *Usage:* `intset_delete(A, B, Set)'
        - _Description:_ Delete from the ordered set `A' the element
          `B'.

 -- PREDICATE: intset_in/2:
     *Usage:* `intset_in(E, Set)'
        - _Description:_ Succeds iff `E' is element of `Set'

 -- PREDICATE: intset_sequence/3:
     *Usage:* `intset_sequence(N, L1, L2)'
        - _Description:_ Generates an ordered set of numbers from 0
          to `N'-1, and append it to `L1'.

 -- PREDICATE: intersection/3:
     *Usage:* `intersection(+List1, +List2, -List)'
        - _Description:_ `List' has the elements which are both in
          `List1' and `List2'.

 -- PREDICATE: union/3:
     *Usage:* `union(+List1, +List2, -List)'
        - _Description:_ `List' has the elements which are in `List1'
          followed by the elements which are in `List2' but not in
          `List1'.

 -- PREDICATE: difference/3:
     *Usage:* `difference(+List1, +List2, -List)'
        - _Description:_ `List' has the elements which are in `List1'
          but not in `List2'.

 -- PROPERTY: sublist/2:
     *Usage:* `sublist(List1, List2)'
        - _Description:_ `List2' contains all the elements of `List1'.

        - _If the following properties should hold at call time:_

          `List2' is currently a term which is not a free variable.
          (`term_typing:nonvar/1')

 -- PROPERTY: subordlist/2:
     *Usage:* `subordlist(List1, List2)'
        - _Description:_ `List2' contains all the elements of `List1'
          in the same order.

        - _If the following properties should hold at call time:_

          `List2' is currently a term which is not a free variable.
          (`term_typing:nonvar/1')

 -- PREDICATE: equal_lists/2:
     *Usage:* `equal_lists(+List1, +List2)'
        - _Description:_ `List1' has all the elements of `List2', and
          vice versa.

 -- PREDICATE: list_to_list_of_lists/2:
     *Usage:* `list_to_list_of_lists(+List, -LList)'
        - _Description:_ `LList' is the list of one element lists
          with elements of `List'.

 -- PREDICATE: powerset/2:
     *Usage:* `powerset(+List, -LList)'
        - _Description:_ `LList' is the powerset of `List', i.e., the
          list of all lists which have elements of `List'. If `List'
          is ordered, `LList' and all its elements are ordered.

 -- PREDICATE: cross_product/2:
     *Usage:* `cross_product(+LList, -List)'
        - _Description:_ `List' is the cartesian product of the lists
          in `LList', that is, the list of lists formed with one
          element of each list in `LList', in the same order.

44 Sorting lists
****************

*Author(s):* Richard A. O'Keefe. All changes by UPM CLIP Group..

   *Version:* 1.9#210 (2003/12/21, 2:12:13 CET)

   This module implements some sorting list predicates.

44.1 Usage and interface (`sort')
=================================

   * *Library usage:*

     `:- use_module(library(sort)).'

   * *Exports:*
        - _Predicates:_

          `sort/2', `keysort/2'.

        - _Regular Types:_

          `keylist/1'.

44.2 Documentation on exports (`sort')
======================================

 -- PREDICATE: sort/2:
     `sort(List1, List2)'

     The elements of `List1' are sorted into the standard order (see
     Comparing terms) and any identical elements are merged,
     yielding `List2'. The time and space complexity of this
     operation is at worst `O(N lg N)' where `N' is the length of
     `List1'.

     *Usage:* `sort(+list, ?list)'
        - _Description:_ `List2' is the sorted list corresponding to
          `List1'.

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: keysort/2:
     `keysort(List1, List2)'

     `List1' is sorted into order according to the value of the
     _keys_ of its elements, yielding the list `List2'. No merging
     takes place. This predicate is _stable_, i.e., if an element `A'
     occurs before another element `B' _with the same key_ in the
     input, then `A' will occur before `B' also in the output. The
     time and space complexity of this operation is at worst `O(N lg
     N)' where `N' is the length of `List1'.

     *Usage:* `keysort(+keylist, ?keylist)'
        - _Description:_ `List2' is the (key-)sorted list
          corresponding to `List1'.

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- REGTYPE: keylist/1:
     *Usage:* `keylist(L)'
        - _Description:_ `L' is a list of pairs of the form
          `Key-Value'.

44.3 Documentation on internals (`sort')
========================================

 -- REGTYPE: keypair/1:
     *Usage:* `keypair(P)'
        - _Description:_ `P' is a pair of the form "`K-_'", where `K'
          is considered the _key_.

45 compiler (library)
*********************

*Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#362 (2004/7/17, 20:41:30 CEST)

45.1 Usage and interface (`compiler')
=====================================

   * *Library usage:*

     `:- use_module(library(compiler)).'

   * *Exports:*
        - _Predicates:_

          `make_po/1', `ensure_loaded/1', `ensure_loaded/2', `use_module/1', `use_module/2', `use_module/3', `unload/1', `set_debug_mode/1', `set_nodebug_mode/1', `set_debug_module/1', `set_nodebug_module/1', `set_debug_module_source/1', `mode_of_module/2', `module_of/2'.

   * *Other modules used:*
        - _System library modules:_

          `compiler/c_itf'.

45.2 Documentation on exports (`compiler')
==========================================

 -- PREDICATE: make_po/1:
     No further documentation available for this predicate.

 -- PREDICATE: ensure_loaded/1:
     No further documentation available for this predicate.

 -- PREDICATE: ensure_loaded/2:
     No further documentation available for this predicate.

 -- PREDICATE: use_module/1:
     No further documentation available for this predicate.

 -- PREDICATE: use_module/2:
     No further documentation available for this predicate.

     _Meta-predicate_ with arguments: `use_module(?,addmodule)'.

 -- PREDICATE: use_module/3:
     No further documentation available for this predicate.

 -- PREDICATE: unload/1:
     No further documentation available for this predicate.

 -- PREDICATE: set_debug_mode/1:
     No further documentation available for this predicate.

 -- PREDICATE: set_nodebug_mode/1:
     No further documentation available for this predicate.

 -- PREDICATE: set_debug_module/1:
     No further documentation available for this predicate.

 -- PREDICATE: set_nodebug_module/1:
     No further documentation available for this predicate.

 -- PREDICATE: set_debug_module_source/1:
     No further documentation available for this predicate.

 -- PREDICATE: mode_of_module/2:
     No further documentation available for this predicate.

 -- PREDICATE: module_of/2:
     No further documentation available for this predicate.

46 Enumeration of integers inside a range
*****************************************

*Author(s):* The CLIP Group..

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#276 (2004/1/9, 16:37:11 CET)

   This modules enumerates integers between two numbers, or checks
that an integer lies within a range

46.1 Usage and interface (`between')
====================================

   * *Library usage:*

     `:- use_module(library(between)).'

   * *Exports:*
        - _Predicates:_

          `between/3'.

46.2 Documentation on exports (`between')
=========================================

 -- PREDICATE: between/3:
     *Usage:* `between(+Min, +Max, ?N)'
        - _Description:_ `N' is an integer which is greater than or
          equal to `Min' and smaller than or equal to `Max'. Both
          `Min' and `Max' can be either integer or real numbers.

        - _The following properties should hold at call time:_

          `+Min' is currently instantiated to a number.
          (`term_typing:number/1')

          `+Max' is currently instantiated to a number.
          (`term_typing:number/1')

          `?N' is an integer.   (`basic_props:int/1')

47 Operating system utilities
*****************************

*Author(s):* Daniel Cabeza, Manuel Carro.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#365 (2004/7/28, 1:10:31 CEST)

   This module contains predicates for invoking services which are
typically provided by the operating system. Note that the predicates
which take names of files or directories as arguments in this module
expect atoms, not path aliases. I.e., generally these predicates will
not call `absolute_file_name/2' on names of files or directories
taken as arguments.

47.1 Usage and interface (`system')
===================================

   * *Library usage:*

     `:- use_module(library(system)).'

   * *Exports:*
        - _Predicates:_

          `pause/1', `time/1', `datime/1', `datime/9', `getenvstr/2', `setenvstr/2', `extract_paths/2', `get_pid/1', `current_host/1', `current_executable/1', `umask/2', `make_directory/2', `make_directory/1', `make_dirpath/2', `make_dirpath/1', `working_directory/2', `cd/1', `shell/0', `shell/1', `shell/2', `system/1', `system/2', `popen/3', `exec/4', `exec/3', `exec/8', `wait/3', `directory_files/2', `mktemp/2', `file_exists/1', `file_exists/2', `file_property/2', `file_properties/6', `modif_time/2', `modif_time0/2', `fmode/2', `chmod/2', `chmod/3', `delete_file/1', `delete_directory/1', `rename_file/2', `cyg2win/3'.

        - _Regular Types:_

          `datime_struct/1', `popen_mode/1'.

        - _Multifiles:_

          `define_flag/3'.

   * *Other modules used:*
        - _System library modules:_

          `lists'.

47.2 Documentation on exports (`system')
========================================

 -- PREDICATE: pause/1:
     `pause(Seconds)'

     Make this thread sleep for some `Seconds'.

 -- PREDICATE: time/1:
     `time(Time)'

     `Time' is unified with the number of seconds elapsed since
     January, 1, 1970 (UTC).

 -- PREDICATE: datime/1:
     `datime(Datime)'

     `Datime' is unified with a term of the form
     `datime(Year,Month,Day,Hour,Minute,Second)' which contains the
     current date and time.

 -- PREDICATE: datime/9:
     `datime(Time, Year, Month, Day, Hour, Min, Sec, WeekDay,
     YearDay)'

     `Time' is as in `time/1'. `WeekDay' is the number of days since
     Sunday, in the range 0 to 6. `YearDay' is the number of days
     since January 1, in the range 0 to 365.

     *Usage 1:* `datime(+int, ?int, ?int, ?int, ?int, ?int, ?int,
     ?int, ?int)'
        - _Description:_ If `Time' is given, the rest of the
          arguments are unified with the date and time to which the
          `Time' argument refers.

     *Usage 2:* `datime(-int, ?int, ?int, ?int, ?int, ?int, ?int,
     ?int, ?int)'
        - _Description:_ Bound `Time' to current time and the rest of
          the arguments refer to current time.

 -- REGTYPE: datime_struct/1:
     A regular type, defined as follows:
               datime_struct(datime(Year,Month,Day,Hour,Min,Sec)) :-
                       int(Year),
                       int(Month),
                       int(Day),
                       int(Hour),
                       int(Min),
                       int(Sec).

 -- PREDICATE: getenvstr/2:
     `getenvstr(Name, Value)'

     The environment variable `Name' has `Value'. Fails if variable
     `Name' is not defined.

 -- PREDICATE: setenvstr/2:
     `setenvstr(Name, Value)'

     The environment variable `Name' is assigned `Value'.

 -- PREDICATE: extract_paths/2:
     `extract_paths(String, Paths)'

     Interpret `String' as the value of a UNIX environment variable
     holding a list of paths and return in `Paths' the list of the
     paths. Paths in `String' are separated by colons, and an empty
     path is considered a shorthand for '.' (current path). The most
     typical environment variable with this format is PATH. For
     example, this is a typical use:
          ?- set_prolog_flag(write_strings, on).

          yes
          ?- getenvstr('PATH', PATH), extract_paths(PATH, Paths).

          PATH = ":/home/bardo/bin:/home/clip/bin:/opt/bin/:/bin",
          Paths = [".","/home/bardo/bin","/home/clip/bin","/opt/bin/","/bin"] ?

          yes
          ?-

 -- PREDICATE: get_pid/1:
     `get_pid(Pid)'

     Unifies `Pid' with the process identificator of the current
     process or thread.

 -- PREDICATE: current_host/1:
     `current_host(Hostname)'

     `Hostname' is unified with the fully qualified name of the host.

 -- PREDICATE: current_executable/1:
     `current_executable(Path)'

     Unifies `Path' with the path to the current executable.

 -- PREDICATE: umask/2:
     `umask(OldMask, NewMask)'

     The process file creation mask was `OldMask', and it is changed
     to `NewMask'.

     *Usage 2:* `umask(OldMask, NewMask)'
        - _Description:_ Gets the process file creation mask without
          changing it.

        - _The following properties should hold at call time:_

          `OldMask' is a free variable.   (`term_typing:var/1')

          `NewMask' is a free variable.   (`term_typing:var/1')

          The terms `OldMask' and `NewMask' are strictly identical.
          (`term_compare:== /2')

        - _The following properties hold upon exit:_

          `OldMask' is an integer.   (`basic_props:int/1')

          `NewMask' is an integer.   (`basic_props:int/1')

 -- PREDICATE: make_directory/2:
     `make_directory(DirName, Mode)'

     Creates the directory `DirName' with a given `Mode'. This is, as
     usual, operated against the current umask value.

 -- PREDICATE: make_directory/1:
     `make_directory(DirName)'

     Equivalent to `make_directory(D,0o777)'.

 -- PREDICATE: make_dirpath/2:
     `make_dirpath(Path, Mode)'

     Creates the whole `Path' for a given directory with a given
     `Mode'. As an example, `make_dirpath('/tmp/var/mydir/otherdir')'.

 -- PREDICATE: make_dirpath/1:
     `make_dirpath(Path)'

     Equivalent to `make_dirpath(D,0o777)'.

 -- PREDICATE: working_directory/2:
     `working_directory(OldDir, NewDir)'

     Unifies current working directory with `OldDir', and then
     changes the working directory to `NewDir'. Calling
     `working_directory(Dir,Dir)' simply unifies `Dir' with the
     current working directory without changing anything else.

     *Usage 2:* `working_directory(OldDir, NewDir)'
        - _Description:_ Gets current working directory.

        - _The following properties should hold at call time:_

          `OldDir' is a free variable.   (`term_typing:var/1')

          `NewDir' is a free variable.   (`term_typing:var/1')

          The terms `OldDir' and `NewDir' are strictly identical.
          (`term_compare:== /2')

        - _The following properties hold upon exit:_

          `OldDir' is an atom.   (`basic_props:atm/1')

          `NewDir' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: cd/1:
     `cd(Path)'

     Changes working directory to `Path'.

 -- PREDICATE: shell/0:
     *Usage:*
        - _Description:_ Execs the shell specified by the environment
          variable `SHELL'. When the shell process terminates,
          control is returned to Prolog.

 -- PREDICATE: shell/1:
     `shell(Command)'

     `Command' is executed in the shell specified by the environment
     variable `SHELL'. It succeeds if the exit code is zero and fails
     otherwise.

 -- PREDICATE: shell/2:
     `shell(Command, ReturnCode)'

     Executes `Command' in the shell specified by the environment
     variable `SHELL' and stores the exit code in `ReturnCode'.

 -- PREDICATE: system/1:
     `system(Command)'

     Executes `Command' using the shell `/bin/sh'.

 -- PREDICATE: system/2:
     `system(Command, ReturnCode)'

     Executes `Command' in the `/bin/sh' shell and stores the exit
     code in `ReturnCode'.

 -- PREDICATE: popen/3:
     `popen(Command, Mode, Stream)'

     Open a pipe to process `Command' in a new shell with a given
     `Mode' and return a communication `Stream' (as in UNIX
     `popen(3)'). If `Mode' is `read' the output from the process is
     sent to `Stream'. If `Mode' is `write', `Stream' is sent as
     input to the process. `Stream' may be read from or written into
     using the ordinary stream I/O predicates. `Stream' must be
     closed explicitly using `close/1', i.e., it is not closed
     automatically when the process dies. Note that `popen/2' is
     defined in ***x as using `/bin/sh', which usually does not exist
     in Windows systems. In this case, a `sh' shell which comes with
     Windows is used.

 -- REGTYPE: popen_mode/1:
     *Usage:* `popen_mode(M)'
        - _Description:_ `M' is 'read' or 'write'.

 -- PREDICATE: exec/4:
     `exec(Command, StdIn, StdOut, StdErr)'

     Starts the process `Command' and returns the standart I/O
     streams of the process in `StdIn', `StdOut', and `StdErr'. If
     `Command' contains blank spaces, these are taken as separators
     between a program name (the first chunk of contiguous non-blank
     characters) and options for the program (the subsequent
     contiguous pieces of non-blank characters), as in `exec('ls -lRa
     ../sibling_dir', In, Out, Err)'.

 -- PREDICATE: exec/3:
     `exec(Command, StdIn, StdOut)'

     Starts the process `Command' and returns the standart I/O
     streams of the process in `StdIn' and `StdOut'. `Standard error'
     is connected to whichever the parent process had it connected
     to. `Command' is treated and split in components as in `exec/4'.

 -- PREDICATE: exec/8:
     *Usage:* `exec(+Command, +Arguments, ?StdIn, ?StdOut, ?StdErr,
     +Background, -PID, -ErrCode)'
        - _Description:_ `exec/8' gives a finer control for launching
          external processes. `Command' is the command to be executed
          and `Arguments' is a list of atoms to be passed as
          arguments to the command. When called with free variables,
          `StdIn', `StdOut', and `StdErr' are instantiated to streams
          connected to the standard output, input, and error of the
          created process. `Background' controls whether the caller
          waits for `Command' to finish, or if the process executing
          `Command' is completely detached (it can be waited for using `wait/3').
          `ErrCode' is the error code returned by the lower-level
          `exec()' system call (this return code is system-dependent,
          but a non-zero value usually means that something has gone
          wrong). If `Command' does not start by a slash, `exec/8'
          uses the environment variable `PATH' to search for it. If
          `PATH' is not set, `/bin' and `/usr/bin' are searched.

        - _The following properties should hold at call time:_

          `+Command' is an atom.   (`basic_props:atm/1')

          `+Arguments' is a list of `atm's.   (`basic_props:list/2')

          `?StdIn' is an open stream.   (`streams_basic:stream/1')

          `?StdOut' is an open stream.   (`streams_basic:stream/1')

          `?StdErr' is an open stream.   (`streams_basic:stream/1')

          `+Background' is an atom.   (`basic_props:atm/1')

          `-PID' is an integer.   (`basic_props:int/1')

          `-ErrCode' is an integer.   (`basic_props:int/1')

 -- PREDICATE: wait/3:
     *Usage:* `wait(+Pid, -RetCode, -Status)'
        - _Description:_ wait/3 waits for the process numbered `Pid'.
          If `PID' equals -1, it will wait for any children process.
          `RetCode' is usually the PID of the waited-for process, and
          -1 in case in case of error. `Status' is related to the
          exit value of the process in a system-dependent fashion.

        - _The following properties should hold at call time:_

          `+Pid' is an integer.   (`basic_props:int/1')

          `-RetCode' is an integer.   (`basic_props:int/1')

          `-Status' is an integer.   (`basic_props:int/1')

 -- PREDICATE: directory_files/2:
     `directory_files(Directory, FileList)'

     `FileList' is the unordered list of entries (files, directories,
     etc.) in `Directory'.

 -- PREDICATE: mktemp/2:
     `mktemp(Template, Filename)'

     Returns a unique `Filename' based on `Template': `Template' must
     be a valid file name with six trailing X, which are substituted
     to create a new file name.

 -- PREDICATE: file_exists/1:
     `file_exists(File)'

     Succeeds if `File' (a file or directory) exists (and is
     accessible).

 -- PREDICATE: file_exists/2:
     `file_exists(File, Mode)'

     `File' (a file or directory) exists and it is accessible with
     `Mode', as in the Unix call `access(2)'. Typically, `Mode' is 4
     for read permission, 2 for write permission and 1 for execute
     permission.

 -- PREDICATE: file_property/2:
     `file_property(File, Property)'

     `File' has the property `Property'. The possible properties are:

    type(`Type')
          `Type' is one of `regular', `directory', `symlink', `fifo',
          `socket' or `unknown'.

    linkto(`Linkto')
          If `File' is a symbolic link, `Linkto' is the file pointed
          to by the link (and the other properties come from that
          file, not from the link itself).

    mod_time(`ModTime')
          `ModTime' is the time of last modification (seconds since
          January, 1, 1970).

    mode(`Protection')
          `Protection' is the protection mode.

    size(`Size')
          `Size' is the size.

     If `Property' is uninstantiated, the predicate will enumerate
     the properties on backtracking.

 -- PREDICATE: file_properties/6:
     `file_properties(Path, Type, Linkto, Time, Protection, Size)'

     The file `Path' has the following properties:

        * File type `Type' (one of `regular', `directory', `symlink',
          `fifo', `socket' or `unknown').

        * If `Path' is a symbolic link, `Linkto' is the file pointed
          to. All other properties come from the file pointed, not
          the link. `Linkto' is " if `Path' is not a symbolic link.

        * Time of last modification `Time' (seconds since January, 1,
          1970).

        * Protection mode `Protection'.

        * Size in bytes `Size'.

 -- PREDICATE: modif_time/2:
     `modif_time(File, Time)'

     The file `File' was last modified at `Time', which is in seconds
     since January, 1, 1970. Fails if `File' does not exist.

 -- PREDICATE: modif_time0/2:
     `modif_time0(File, Time)'

     If `File' exists, `Time' is its latest modification time, as in `modif_time/2'.
     Otherwise, if `File' does not exist, `Time' is zero.

 -- PREDICATE: fmode/2:
     `fmode(File, Mode)'

     The file `File' has protection mode `Mode'.

 -- PREDICATE: chmod/2:
     `chmod(File, NewMode)'

     Change the protection mode of file `File' to `NewMode'.

 -- PREDICATE: chmod/3:
     `chmod(File, OldMode, NewMode)'

     The file `File' has protection mode `OldMode' and it is changed
     to `NewMode'.

     *Usage 2:* `chmod(File, OldMode, NewMode)'
        - _Description:_ Equivalent to fmode(`File',`OldMode')

        - _The following properties should hold at call time:_

          `File' is an atom.   (`basic_props:atm/1')

          `OldMode' is a free variable.   (`term_typing:var/1')

          `NewMode' is a free variable.   (`term_typing:var/1')

          The terms `OldMode' and `NewMode' are strictly identical.
          (`term_compare:== /2')

        - _The following properties hold upon exit:_

          `File' is an atom.   (`basic_props:atm/1')

          `OldMode' is an atom.   (`basic_props:atm/1')

          `NewMode' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: delete_file/1:
     `delete_file(File)'

     Delete the file `File'.

 -- PREDICATE: delete_directory/1:
     `delete_directory(File)'

     Delete the directory `Directory'.

 -- PREDICATE: rename_file/2:
     `rename_file(File1, File2)'

     Change the name of `File1' to `File2'.

 -- PREDICATE: cyg2win/3:
     *Usage:* `cyg2win(CygWinPath, WindowsPath, SwapSlash)'
        - _Description:_ Converts a path in the CygWin style to a
          Windows-style path, rewriting the driver part. If
          `SwapSlash' is `swap', slashes are converted in to
          backslash. If it is `noswap', they are preserved.

        - _The following properties should hold at call time:_

          `CygWinPath' is a string (a list of character codes).
          (`basic_props:string/1')

          `WindowsPath' is a free variable.   (`term_typing:var/1')

          `SwapSlash' is currently instantiated to an atom.
          (`term_typing:atom/1')

        - _The following properties should hold upon exit:_

          `CygWinPath' is a string (a list of character codes).
          (`basic_props:string/1')

          `WindowsPath' is a string (a list of character codes).
          (`basic_props:string/1')

          `SwapSlash' is currently instantiated to an atom.
          (`term_typing:atom/1')

47.3 Documentation on multifiles (`system')
===========================================

 -- PREDICATE: define_flag/3:
     No further documentation available for this predicate.

     The predicate is _multifile_.

47.4 Known bugs and planned improvements (`system')
===================================================

   *  `shell/n' commands have a bug in Windows: if the environment
     variable SHELL is instantiated to some Windows shell
     implementation, then it is very possible that shell/{1,2} will
     not work, as it is always called with the -c flag to start the
     user command. For example, COMMAND.COM *might* need the flag /C
     - but there is no way to know a priori which command line option
     is necessary for every shell! It does not seems usual that
     Windows sets the SHELL environment variable: if it is not set,
     we set it up at startup time to point to the `sh.exe' provided
     with Ciao, which is able to start Windows aplications.
     Therefore, `?- shell('command.com').' just works.

   * If `exec/4' does not find the command to be executed, there is
     no visible error message: it is sent to a error output which has
     already been assigned to a different stream, disconnected from
     the one the user sees.

   * If the arguments to cyg2win/3 are not strings, strange results
     appear, as a very mild type checking is performed.

48 Prolog system internal predicates
************************************

*Author(s):* Manuel Carro, Daniel Cabeza, Mats Carlsson.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#92 (2003/7/24, 8:4:39 CEST)

   This module implements some miscellaneous predicates which provide
access to some internal statistics, special properties of the
predicates, etc.

48.1 Usage and interface (`prolog_sys')
=======================================

   * *Library usage:*

     `:- use_module(library(prolog_sys)).'

   * *Exports:*
        - _Predicates:_

          `statistics/0', `statistics/2', `predicate_property/2', `current_atom/1', `garbage_collect/0', `new_atom/1'.

48.2 Documentation on exports (`prolog_sys')
============================================

 -- PREDICATE: statistics/0:
     *Usage:*
        - _Description:_ Prints statistics about the system.

 -- PREDICATE: statistics/2:
     *Usage 1:* `statistics(Time_option, Time_result)'
        - _Description:_ Gather information about time (either
          process time or wall time) since last consult or since
          start of program. Results are returned in milliseconds.

        - _The following properties should hold at call time:_

          Options to get information about execution time.
          `Time_option' must be one of `runtime', `walltime'.
          (`prolog_sys:time_option/1')

          `Time_result' is any term.   (`basic_props:term/1')

        - _The following properties hold upon exit:_

          Options to get information about execution time.
          `Time_option' must be one of `runtime', `walltime'.
          (`prolog_sys:time_option/1')

          `Time_result' is a two-element list of integers. The first
          integer is the time since the start of the execution; the
          second integer is the time since the previous consult to
          time.   (`prolog_sys:time_result/1')

     *Usage 2:* `statistics(Memory_option, Memory_result)'
        - _Description:_ Gather information about memory consumption.

        - _The following properties should hold at call time:_

          Options to get information about memory usage.
          (`prolog_sys:memory_option/1')

          `Memory_result' is any term.   (`basic_props:term/1')

        - _The following properties hold upon exit:_

          Options to get information about memory usage.
          (`prolog_sys:memory_option/1')

          Result is a two-element list of integers. The first element
          is the space taken up by the option selected, measured in
          bytes; the second integer is zero for program space (which
          grows as necessary), and the amount of free space otherwise.
          (`prolog_sys:memory_result/1')

     *Usage 3:* `statistics(Garbage_collection_option, Gc_result)'
        - _Description:_ Gather information about garbage collection.

        - _The following properties should hold at call time:_

          Options to get information about garbage collection.
          (`prolog_sys:garbage_collection_option/1')

          `Gc_result' is any term.   (`basic_props:term/1')

        - _The following properties hold upon exit:_

          Options to get information about garbage collection.
          (`prolog_sys:garbage_collection_option/1')

          `Gc_result' is a tree-element list of integers, related to garbage
          collection and memory management. When `stack_shifts' is
          selected, the first one is the number of shifts
          (reallocations) of the local stack; the second is the
          number of shifts of the trail, and the third is the time
          spent in these shifts. When `garbage_collection' is
          selected, the numbers are, respectively, the number of
          garbage collections performed, the number of bytes freed,
          and the time spent in garbage collection.
          (`prolog_sys:gc_result/1')

     *Usage 4:* `statistics(Symbol_option, Symbol_result)'
        - _Description:_ Gather information about number of symbols
          and predicates.

        - _The following properties should hold at call time:_

          Option to get information about the number of symbols in
          the program.   (`prolog_sys:symbol_option/1')

          `Symbol_result' is any term.   (`basic_props:term/1')

        - _The following properties hold upon exit:_

          Option to get information about the number of symbols in
          the program.   (`prolog_sys:symbol_option/1')

          `Symbol_result' is a two-element list of integers. The
          first one is the number of atom, functor, and predicate
          names in the symbol table. The second is the number of
          predicates known to be defined (although maybe without
          clauses).   (`prolog_sys:symbol_result/1')

     *Usage 5:* `statistics(Option, ?term)'
        - _Description:_ If `Option' is unbound, it is bound to the
          values on the other cases.

 -- PREDICATE: predicate_property/2:
     *Usage:* `predicate_property(Head, Property)'
        - _Description:_ The predicate with clause `Head' is
          `Property'.

        - _The following properties should hold at call time:_

          `Head' is any term.   (`basic_props:term/1')

          `Property' is any term.   (`basic_props:term/1')

        - _The following properties hold upon exit:_

          `Head' is a term which represents a goal, i.e., an atom or
          a structure.   (`basic_props:callable/1')

          `Property' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: current_atom/1:
     *Usage:* `current_atom(Atom)'
        - _Description:_ Enumerates on backtracking all the existing
          atoms in the system.

        - _The following properties should hold at call time:_

          `Atom' is a free variable.   (`term_typing:var/1')

        - _The following properties hold upon exit:_

          `Atom' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: garbage_collect/0:
     *Usage:*
        - _Description:_ Forces garbage collection when called.

 -- PREDICATE: new_atom/1:
     *Usage:* `new_atom(Atom)'
        - _Description:_ Returns, on success, a new atom, not
          existing before in the system. The entry argument must be a
          variable. The idea behind this atom generation is to
          provide a fast source of identifiers for new objects,
          concurrent predicates, etc. on the fly.

        - _The following properties should hold at call time:_

          `Atom' is a free variable.   (`term_typing:var/1')

        - _The following properties hold upon exit:_

          `Atom' is an atom.   (`basic_props:atm/1')

48.3 Documentation on internals (`prolog_sys')
==============================================

 -- REGTYPE: time_option/1:
     *Usage:* `time_option(M)'
        - _Description:_ Options to get information about execution
          time. `M' must be one of `runtime', `walltime'.

 -- REGTYPE: memory_option/1:
     *Usage:* `memory_option(M)'
        - _Description:_ Options to get information about memory
          usage.

 -- REGTYPE: garbage_collection_option/1:
     *Usage:* `garbage_collection_option(M)'
        - _Description:_ Options to get information about garbage
          collection.

 -- REGTYPE: symbol_option/1:
     *Usage:* `symbol_option(M)'
        - _Description:_ Option to get information about the number
          of symbols in the program.

 -- REGTYPE: time_result/1:
     *Usage:* `time_result(Result)'
        - _Description:_ `Result' is a two-element list of integers.
          The first integer is the time since the start of the
          execution; the second integer is the time since the
          previous consult to time.

 -- REGTYPE: memory_result/1:
     *Usage:* `memory_result(Result)'
        - _Description:_ Result is a two-element list of integers.
          The first element is the space taken up by the option
          selected, measured in bytes; the second integer is zero for
          program space (which grows as necessary), and the amount of
          free space otherwise.

 -- REGTYPE: gc_result/1:
     *Usage:* `gc_result(Result)'
        - _Description:_ `Result' is a tree-element list of integers,
          related to garbage collection and memory management. When
          `stack_shifts' is selected, the first one is the number of
          shifts (reallocations) of the local stack; the second is
          the number of shifts of the trail, and the third is the
          time spent in these shifts. When `garbage_collection' is
          selected, the numbers are, respectively, the number of
          garbage collections performed, the number of bytes freed,
          and the time spent in garbage collection.

 -- REGTYPE: symbol_result/1:
     *Usage:* `symbol_result(Result)'
        - _Description:_ `Result' is a two-element list of integers.
          The first one is the number of atom, functor, and predicate
          names in the symbol table. The second is the number of
          predicates known to be defined (although maybe without
          clauses).

48.4 Known bugs and planned improvements (`prolog_sys')
=======================================================

   * The space used by the process is not measured here: process
     data, code, and stack also take up memory. The memory reported
     for atoms is not what is actually used, but the space used up by
     the hash table (which is enlarged as needed).

49 DEC-10 Prolog file IO
************************

*Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#273 (2004/1/5, 20:14:41 CET)

   This module implements the support for DEC-10 Prolog style file
I/O.

49.1 Usage and interface (`dec10_io')
=====================================

   * *Library usage:*

     `:- use_module(library(dec10_io)).'

   * *Exports:*
        - _Predicates:_

          `see/1', `seeing/1', `seen/0', `tell/1', `telling/1', `told/0', `close_file/1'.

49.2 Documentation on exports (`dec10_io')
==========================================

 -- PREDICATE: see/1:
     No further documentation available for this predicate.

 -- PREDICATE: seeing/1:
     No further documentation available for this predicate.

 -- PREDICATE: seen/0:
     No further documentation available for this predicate.

 -- PREDICATE: tell/1:
     No further documentation available for this predicate.

 -- PREDICATE: telling/1:
     No further documentation available for this predicate.

 -- PREDICATE: told/0:
     No further documentation available for this predicate.

 -- PREDICATE: close_file/1:
     No further documentation available for this predicate.

50 Quintus-like internal database
*********************************

*Author(s):* The CLIP Group.

   *Version:* 1.9#213 (2003/12/21, 2:20:13 CET)

   The predicates described in this section were introduced in early
implementations of Prolog to provide efficient means of performing
operations on large quantities of data. The introduction of indexed
dynamic predicates have rendered these predicates obsolete, and the
sole purpose of providing them is to support existing code. There is
no reason whatsoever to use them in new code.

   These predicates store arbitrary terms in the database without
interfering with the clauses which make up the program. The terms
which are stored in this way can subsequently be retrieved via the
key on which they were stored. Many terms may be stored on the same
key, and they can be individually accessed by pattern matching.
Alternatively, access can be achieved via a special identifier which
uniquely identifies each recorded term and which is returned when the
term is stored.

50.1 Usage and interface (`old_database')
=========================================

   * *Library usage:*

     `:- use_module(library(old_database)).'

   * *Exports:*
        - _Predicates:_

          `recorda/3', `recordz/3', `recorded/3', `current_key/2'.

50.2 Documentation on exports (`old_database')
==============================================

 -- PREDICATE: recorda/3:
     `recorda(Key, Term, Ref)'

     The term `Term' is recorded in the internal database as the
     first item for the key `Key', where `Ref' is its
     implementation-defined identifier. The key must be given, and
     only its principal functor is significant. Any uninstantiated
     variables in the `Term' will be replaced by new private
     variables, along with copies of any subgoals blocked on these
     variables.

     *Usage:* `recorda(+Key, ?Term, -Ref)'
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: recordz/3:
     `recordz(Key, Term, Ref)'

     Like `recorda/3', except that the new term becomes the _last_
     item for the key `Key'.

     *Usage:* `recordz(+Key, ?Term, -Ref)'
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: recorded/3:
     `recorded(Key, Term, Ref)'

     The internal database is searched for terms recorded under the
     key `Key'. These terms are successively unified with `Term' in
     the order they occur in the database. At the same time, `Ref' is
     unified with the implementation-defined identifier uniquely
     identifying the recorded item. If the key is instantiated to a
     compound term, only its principal functor is significant. If the
     key is uninstantiated, all terms in the database are
     successively unified with `Term' in the order they occur.

     *Usage:* `recorded(?Key, ?Term, ?Ref)'
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: current_key/2:
     `current_key(KeyName, KeyTerm)'

     `KeyTerm' is the most general form of the key for a currently
     recorded term, and `KeyName' is the name of that key. This
     predicate can be used to enumerate in undefined order all keys
     for currently recorded terms through backtracking.

     *Usage:* `current_key(?Name, ?Key)'
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

51 ttyout (library)
*******************

*Version:* 0.4#5 (1998/2/24)

51.1 Usage and interface (`ttyout')
===================================

   * *Library usage:*

     `:- use_module(library(ttyout)).'

   * *Exports:*
        - _Predicates:_

          `ttyget/1', `ttyget1/1', `ttynl/0', `ttyput/1', `ttyskip/1', `ttytab/1', `ttyflush/0', `ttydisplay/1', `ttydisplayq/1', `ttyskipeol/0', `ttydisplay_string/1'.

51.2 Documentation on exports (`ttyout')
========================================

 -- PREDICATE: ttyget/1:
     No further documentation available for this predicate.

 -- PREDICATE: ttyget1/1:
     No further documentation available for this predicate.

 -- PREDICATE: ttynl/0:
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: ttyput/1:
     `ttyput(X)'
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: ttyskip/1:
     No further documentation available for this predicate.

 -- PREDICATE: ttytab/1:
     No further documentation available for this predicate.

 -- PREDICATE: ttyflush/0:
     No further documentation available for this predicate.

 -- PREDICATE: ttydisplay/1:
     No further documentation available for this predicate.

 -- PREDICATE: ttydisplayq/1:
     No further documentation available for this predicate.

 -- PREDICATE: ttyskipeol/0:
     No further documentation available for this predicate.

 -- PREDICATE: ttydisplay_string/1:
     No further documentation available for this predicate.

52 Enabling operators at run-time
*********************************

*Author(s):* Daniel Cabeza.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#203 (2003/12/20, 14:32:53 CET)

   This library package allows the use of the statically defined
operators of a module for the reading performed at run-time by the
program that uses the module. Simply by using this package the
operator definitions appearing in the module are enabled during the
execution of the program.

52.1 Usage and interface (`runtime_ops')
========================================

   * *Library usage:*

     `:- use_package(runtime_ops).'

     or

     `:- module(...,...,[runtime_ops]).'

   * *Other modules used:*
        - _System library modules:_

          `operators'.

PART V - Annotated Prolog library (assertions)
**********************************************

*Author(s):* The CLIP Group.

   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 in the style of the
_literate programming_. 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 the program or library
reference manual.

53 The Ciao assertion package
*****************************

*Author(s):* Manuel Hermenegildo, Francisco Bueno, German Puebla.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.5#8 (1999/12/9, 21:1:11 MET)

   The `assertions' package adds a number of new declaration
definitions and new operator definitions which allow including program
assertions in user programs. Such assertions can be used to describe
predicates, properties, modules, applications, etc. These
descriptions can be formal specifications (such as preconditions and
post-conditions) or machine-readable textual comments.

   This module is part of the `assertions' library. It defines the
basic code-related assertions, i.e., those intended to be used mainly
by compilation-related tools, such as the static analyzer or the
run-time test generator.

   Giving specifications for predicates and other program elements is
the main functionality documented here. The exact syntax of comments is
described in the autodocumenter ( `lpdoc' [Knu84,Her99]) manual,
although some support for adding machine-readable comments in
assertions is also mentioned here.

   There are two kinds of assertions: predicate assertions and
program point assertions. All predicate assertions are currently
placed as directives in the source code, i.e., preceded by "`:-'".
Program point assertions are placed as goals in clause bodies.

53.1 More info
==============

The facilities provided by the library are documented in the
description of its component modules. This documentation is intended
to provide information only at a "reference manual" level. For a more
tutorial introduction to the subject and some more examples please
see the document "An Assertion Language for Debugging of Constraint
Logic Programs (Technical Report CLIP2/97.1)". The assertion language
implemented in this library is modeled after this design document,
although, due to implementation issues, it may differ in some
details. The purpose of this manual is to document precisely what the
implementation of the library supports at any given point in time.

53.2 Some attention points
==========================

   * *Formatting commands within text strings:* many of the
     predicates defined in these modules include arguments intended
     for providing textual information. This includes titles,
     descriptions, comments, etc. The type of this argument is a
     character string. In order for the automatic generation of
     documentation to work correctly, this character string should
     adhere to certain conventions. See the description of the `docstring/1'
     type/grammar for details.

   * *Referring to variables:* In order for the automatic
     documentation system to work correctly, variable names (for
     example, when referring to arguments in the head patterns of
     _pred_ declarations) must be surrounded by an `@var' command.
     For example, `@var{VariableName}' should be used for referring
     to the variable "VariableName", which will appear then formatted
     as follows: `VariableName'. See the description of the `docstring/1'
     type/grammar for details.

53.3 Usage and interface (`assertions')
=======================================

   * *Library usage:*

     The recommended procedure in order to make use of assertions in
     user programs is to include the `assertions' syntax library,
     using one of the following declarations, as appropriate:

             :- module(...,...,[assertions]).
             :- include(library(assertions)).
             :- use_package([assertions]).

   * *Exports:*
        - _Predicates:_

          `check/1', `trust/1', `true/1', `false/1'.

   * *New operators defined:*

     `=>/2' [975,xfx], `::/2' [978,xfx], `decl/1' [1150,fx], `decl/2'
     [1150,xfx], `pred/1' [1150,fx], `pred/2' [1150,xfx], `prop/1'
     [1150,fx], `prop/2' [1150,xfx], `modedef/1' [1150,fx], `calls/1'
     [1150,fx], `calls/2' [1150,xfx], `success/1' [1150,fx], `success/2'
     [1150,xfx], `comp/1' [1150,fx], `comp/2' [1150,xfx], `entry/1'
     [1150,fx].

   * *New declarations defined:*

     `pred/1', `pred/2', `calls/1', `calls/2', `success/1', `success/2', `comp/1', `comp/2', `prop/1', `prop/2', `entry/1', `modedef/1', `decl/1', `decl/2', `comment/2'.

   * *Other modules used:*
        - _System library modules:_

          `assertions/assertions_props'.

53.4 Documentation on new declarations (`assertions')
=====================================================

 -- DECLARATION: pred/1:
     This assertion provides information on a predicate. The body of
     the assertion (its only argument) contains properties or
     comments in the formats defined by `assrt_body/1'.

     More than one of these assertions may appear per predicate, in
     which case each one represents a possible " mode" of use ( usage)
     of the predicate. The exact scope of the usage is defined by the
     properties given for calls in the body of each assertion (which
     should thus distinguish the different usages intended). All of
     them together cover all possible modes of usage.

     For example, the following assertions describe (all the and the
     only) modes of usage of predicate `length/2' (see `lists'):
          :- pred length(L,N) : list * var => list * integer
          	# "Computes the length of `L'.".
          :- pred length(L,N) : var * integer => list * integer
          	# "Outputs `L' of length `N'.".
          :- pred length(L,N) : list * integer => list * integer
          	# "Checks that `L' is of length `N'.".

     *Usage:* :- `pred(AssertionBody)'.
        - _The following properties should hold at call time:_

          `AssertionBody' is an assertion body.
          (`assertions_props:assrt_body/1')

 -- DECLARATION: pred/2:
     This assertion is similar to a `pred/1' assertion but it is
     explicitely qualified. Non-qualified `pred/1' assertions are
     assumed the qualifier `check'.

     *Usage:* :- `pred(AssertionStatus, AssertionBody)'.
        - _The following properties should hold at call time:_

          `AssertionStatus' is an acceptable status for an assertion.
          (`assertions_props:assrt_status/1')

          `AssertionBody' is an assertion body.
          (`assertions_props:assrt_body/1')

 -- DECLARATION: calls/1:
     This assertion is similar to a `pred/1' assertion but it only
     provides information about the calls to a predicate. If one or
     several calls assertions are given they are understood to
     describe all possible calls to the predicate.

     For example, the following assertion describes all possible
     calls to predicate `is/2' (see `arithmetic'):
          :- calls is(term,arithexpression).

     *Usage:* :- `calls(AssertionBody)'.
        - _The following properties should hold at call time:_

          `AssertionBody' is a call assertion body.
          (`assertions_props:c_assrt_body/1')

 -- DECLARATION: calls/2:
     This assertion is similar to a `calls/1' assertion but it is
     explicitely qualified. Non-qualified `calls/1' assertions are
     assumed the qualifier `check'.

     *Usage:* :- `calls(AssertionStatus, AssertionBody)'.
        - _The following properties should hold at call time:_

          `AssertionStatus' is an acceptable status for an assertion.
          (`assertions_props:assrt_status/1')

          `AssertionBody' is a call assertion body.
          (`assertions_props:c_assrt_body/1')

 -- DECLARATION: success/1:
     This assertion is similar to a `pred/1' assertion but it only
     provides information about the answers to a predicate. The
     described answers might be conditioned to a particular way of
     calling the predicate.

     For example, the following assertion specifies the answers of
     the `length/2' predicate _if_ it is called as in the first mode
     of usage above (note that the previous pred assertion already
     conveys such information, however it also compelled the
     predicate calls, while the success assertion does not):
          :- success length(L,N) : list * var => list * integer.

     *Usage:* :- `success(AssertionBody)'.
        - _The following properties should hold at call time:_

          `AssertionBody' is a predicate assertion body.
          (`assertions_props:s_assrt_body/1')

 -- DECLARATION: success/2:
     This assertion is similar to a `success/1' assertion but it is
     explicitely qualified. Non-qualified `success/1' assertions are
     assumed the qualifier `check'.

     *Usage:* :- `success(AssertionStatus, AssertionBody)'.
        - _The following properties should hold at call time:_

          `AssertionStatus' is an acceptable status for an assertion.
          (`assertions_props:assrt_status/1')

          `AssertionBody' is a predicate assertion body.
          (`assertions_props:s_assrt_body/1')

 -- DECLARATION: comp/1:
     This assertion is similar to a `pred/1' assertion but it only
     provides information about the global execution properties of a
     predicate (note that such kind of information is also conveyed
     by pred assertions). The described properties might be
     conditioned to a particular way of calling the predicate.

     For example, the following assertion specifies that the
     computation of `append/3' (see `lists') will not fail _if_ it is
     called as described (but does not compel the predicate to be
     called that way):
          :- comp append(Xs,Ys,Zs) : var * var * var + not_fail.

     *Usage:* :- `comp(AssertionBody)'.
        - _The following properties should hold at call time:_

          `AssertionBody' is a comp assertion body.
          (`assertions_props:g_assrt_body/1')

 -- DECLARATION: comp/2:
     This assertion is similar to a `comp/1' assertion but it is
     explicitely qualified. Non-qualified `comp/1' assertions are
     assumed the qualifier `check'.

     *Usage:* :- `comp(AssertionStatus, AssertionBody)'.
        - _The following properties should hold at call time:_

          `AssertionStatus' is an acceptable status for an assertion.
          (`assertions_props:assrt_status/1')

          `AssertionBody' is a comp assertion body.
          (`assertions_props:g_assrt_body/1')

 -- DECLARATION: prop/1:
     This assertion is similar to a `pred/1' assertion but it flags
     that the predicate being documented is also a " property."

     Properties are standard predicates, but which are _guaranteed to
     terminate for any possible instantiation state of their
     argument(s)_, do not perform side-effects which may interfere
     with the program behaviour, and do not further instantiate their
     arguments or add new constraints.

     Provided the above holds, properties can thus be safely used as run-time
     checks. The program transformation used in `ciaopp' for run-time
     checking guarantees the third requirement. It also performs some
     basic checks on properties which in most cases are enough for
     the second requirement. However, it is the user's responsibility
     to guarantee termination of the properties defined. (See also
     Declaring regular types for some considerations
     applicable to writing properties.)

     The set of properties is thus a strict subset of the set of
     predicates. Note that properties can be used to describe
     characteristics of arguments in assertions and they can also be
     executed (called) as any other predicates.

     *Usage:* :- `prop(AssertionBody)'.
        - _The following properties should hold at call time:_

          `AssertionBody' is an assertion body.
          (`assertions_props:assrt_body/1')

 -- DECLARATION: prop/2:
     This assertion is similar to a `prop/1' assertion but it is
     explicitely qualified. Non-qualified `prop/1' assertions are
     assumed the qualifier `check'.

     *Usage:* :- `prop(AssertionStatus, AssertionBody)'.
        - _The following properties should hold at call time:_

          `AssertionStatus' is an acceptable status for an assertion.
          (`assertions_props:assrt_status/1')

          `AssertionBody' is an assertion body.
          (`assertions_props:assrt_body/1')

 -- DECLARATION: entry/1:
     This assertion provides information about the _external_ calls
     to a predicate. It is identical syntactically to a `calls/1'
     assertion. However, they describe only external calls, i.e.,
     calls to the exported predicates of a module from outside the
     module, or calls to the predicates in a non-modular file from
     other files (or the user).

     These assertions are _trusted_ by the compiler. As a result, if
     their descriptions are erroneous they can introduce bugs in
     programs. Thus, `entry/1' assertions should be written with care.

     An important use of these assertions is in providing information
     to the compiler which it may not be able to infer from the
     program. The main use is in providing information on the ways in
     which exported predicates of a module will be called from
     outside the module. This will greatly improve the precision of
     the analyzer, which otherwise has to assume that the arguments
     that exported predicates receive are any arbitrary term.

     *Usage:* :- `entry(AssertionBody)'.
        - _The following properties should hold at call time:_

          `AssertionBody' is a call assertion body.
          (`assertions_props:c_assrt_body/1')

 -- DECLARATION: modedef/1:
     This assertion is used to define modes. A mode defines in a
     compact way a set of call and success properties. Once defined,
     modes can be applied to predicate arguments in assertions. The
     meaning of this application is that the call and success
     properties defined by the mode hold for the argument to which
     the mode is applied. Thus, a mode is conceptually a "property
     macro".

     The syntax of mode definitions is similar to that of pred
     declarations. For example, the following set of assertions:

          :- modedef +A : nonvar(A) # "`A' is bound upon predicate entry.".

          :- pred p(+A,B) : integer(A) =>  ground(B).

     is equivalent to:

          :- pred p(A,B) : (nonvar(A),integer(A)) =>  ground(B)
             # "`A' is bound upon predicate entry.".

     *Usage:* :- `modedef(AssertionBody)'.
        - _The following properties should hold at call time:_

          `AssertionBody' is an assertion body.
          (`assertions_props:assrt_body/1')

 -- DECLARATION: decl/1:
     This assertion is similar to a `pred/1' assertion but it is used
     for declarations instead than for predicates.

     *Usage:* :- `decl(AssertionBody)'.
        - _The following properties should hold at call time:_

          `AssertionBody' is an assertion body.
          (`assertions_props:assrt_body/1')

 -- DECLARATION: decl/2:
     This assertion is similar to a `decl/1' assertion but it is
     explicitely qualified. Non-qualified `decl/1' assertions are
     assumed the qualifier `check'.

     *Usage:* :- `decl(AssertionStatus, AssertionBody)'.
        - _The following properties should hold at call time:_

          `AssertionStatus' is an acceptable status for an assertion.
          (`assertions_props:assrt_status/1')

          `AssertionBody' is an assertion body.
          (`assertions_props:assrt_body/1')

 -- DECLARATION: comment/2:
     *Usage:* :- `comment(Pred, Comment)'.
        - _Description:_ This assertion gives a text `Comment' for a
          given predicate `Pred'.

        - _The following properties should hold at call time:_

          `Pred' is a head pattern.
          (`assertions_props:head_pattern/1')

          `Comment' is a text comment with admissible documentation
          commands. The usual formatting commands that are applicable
          in comment strings are defined by `stringcommand/1'. See the `lpdoc'
          manual for documentation on comments.
          (`assertions_props:docstring/1')

53.5 Documentation on exports (`assertions')
============================================

 -- PREDICATE: check/1:
     *Usage:* `check(PropertyConjunction)'
        - _Description:_ This assertion provides information on a
          clause program point (position in the body of a clause).
          Calls to a `check/1' assertion can appear in the body of a
          clause in any place where a literal can normally appear.
          The property defined by `PropertyConjunction' should hold
          in all the run-time stores corresponding to that program
          point. See also Run-time checking of assertions.

        - _The following properties should hold at call time:_

          `PropertyConjunction' is either a term or a _conjunction_
          of terms. The main functor and arity of each of those terms
          corresponds to the definition of a property. The first
          argument of each such term is a variable which appears as a
          head argument.   (`assertions_props:property_conjunction/1')

 -- PREDICATE: trust/1:
     *Usage:* `trust(PropertyConjunction)'
        - _Description:_ This assertion also provides information on
          a clause program point. It is identical syntactically to a `check/1'
          assertion. However, the properties stated are not taken as
          something to be checked but are instead _trusted_ by the
          compiler. While the compiler may in some cases detect an
          inconsistency between a `trust/1' assertion and the
          program, in all other cases the information given in the
          assertion will be taken to be true. As a result, if these
          assertions are erroneous they can introduce bugs in
          programs. Thus, `trust/1' assertions should be written with
          care.

          An important use of these assertions is in providing
          information to the compiler which it may not be able to
          infer from the program (either because the information is
          not present or because the analyzer being used is not
          precise enough). In particular, providing information on
          external predicates which may not be accessible at the time
          of compiling the module can greatly improve the precision
          of the analyzer. This can be easily done with trust
          assertion.

        - _The following properties should hold at call time:_

          `PropertyConjunction' is either a term or a _conjunction_
          of terms. The main functor and arity of each of those terms
          corresponds to the definition of a property. The first
          argument of each such term is a variable which appears as a
          head argument.   (`assertions_props:property_conjunction/1')

 -- PREDICATE: true/1:
     *Usage:* `true(PropertyConjunction)'
        - _Description:_ This assertion is identical syntactically to
          a `check/1' assertion. However, the properties stated have
          been proved to hold by the analyzer. Thus, these assertions
          often represent the analyzer output.

        - _The following properties should hold at call time:_

          `PropertyConjunction' is either a term or a _conjunction_
          of terms. The main functor and arity of each of those terms
          corresponds to the definition of a property. The first
          argument of each such term is a variable which appears as a
          head argument.   (`assertions_props:property_conjunction/1')

 -- PREDICATE: false/1:
     *Usage:* `false(PropertyConjunction)'
        - _Description:_ This assertion is identical syntactically to
          a `check/1' assertion. However, the properties stated have
          been proved not to hold by the analyzer. Thus, these
          assertions often represent the analyzer output.

        - _The following properties should hold at call time:_

          `PropertyConjunction' is either a term or a _conjunction_
          of terms. The main functor and arity of each of those terms
          corresponds to the definition of a property. The first
          argument of each such term is a variable which appears as a
          head argument.   (`assertions_props:property_conjunction/1')

54 Types and properties related to assertions
*********************************************

*Author(s):* Manuel Hermenegildo.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.7#156 (2001/11/24, 13:23:30 CET)

   This module is part of the `assertions' library. It provides the
formal definition of the syntax of several forms of assertions and
describes their meaning. It does so by defining types and properties
related to the assertions themselves. The text describes, for
example, the overall fields which are admissible in the bodies of
assertions, where properties can be used inside these bodies, how to
combine properties for a given predicate argument (e.g.,
conjunctions) , etc. and provides some examples.

54.1 Usage and interface (`assertions_props')
=============================================

   * *Library usage:*

     `:- use_module(library(assertions_props)).'

   * *Exports:*
        - _Properties:_

          `head_pattern/1', `nabody/1', `docstring/1'.

        - _Regular Types:_

          `assrt_body/1', `complex_arg_property/1', `property_conjunction/1', `property_starterm/1', `complex_goal_property/1', `dictionary/1', `c_assrt_body/1', `s_assrt_body/1', `g_assrt_body/1', `assrt_status/1', `assrt_type/1', `predfunctor/1', `propfunctor/1'.

   * *Other modules used:*
        - _System library modules:_

          `dcg_expansion'.

54.2 Documentation on exports (`assertions_props')
==================================================

 -- REGTYPE: assrt_body/1:
     This predicate defines the different types of syntax admissible
     in the bodies of `pred/1', `decl/1', etc. assertions. Such a
     body is of the form:

                Pr [:: DP] [: CP] [=> AP] [+ GP] [# CO]

     where (fields between [...] are optional):

        * `Pr' is a head pattern ( `head_pattern/1') which describes
          the predicate or property and possibly gives some implicit
          call/answer information.

        * `DP' is a (possibly empty) complex argument property ( `complex_arg_property/1')
          which expresses properties which are compatible with the
          predicate, i.e., instantiations made by the predicate are
          _compatible_ with the properties in the sense that applying
          the property at any point to would not make it fail.

        * `CP' is a (possibly empty) complex argument property ( `complex_arg_property/1')
          which applies to the _calls_ to the predicate.

        * `AP' is a (possibly empty) complex argument property ( `complex_arg_property/1')
          which applies to the _answers_ to the predicate (if the
          predicate succeeds). These only apply if the (possibly
          empty) properties given for calls in the assertion hold.

        * `GP' is a (possibly empty) complex goal property ( `complex_goal_property/1')
          which applies to the _whole execution_ of a call to the
          predicate. These only apply if the (possibly empty)
          properties given for calls in the assertion hold.

        * `CO' is a comment string ( `docstring/1'). This comment
          only applies if the (possibly empty) properties given for
          calls in the assertion hold. The usual formatting commands
          that are applicable in comment strings can be used (see `stringcommand/1').

          See the `lpdoc' manual for documentation on assertion
          comments.

     *Usage:* `assrt_body(X)'
        - _Description:_ `X' is an assertion body.

 -- PROPERTY: head_pattern/1:
     A head pattern can be a predicate name (functor/arity) ( `predname/1')
     or a term. Thus, both `p/3' and `p(A,B,C)' are valid head
     patterns. In the case in which the head pattern is a term, each
     argument of such a term can be:

        * A variable. This is useful in order to be able to refer to
          the corresponding argument positions by name within
          properties and in comments. Thus,
          `p(Input,Parameter,Output)' is a valid head pattern.

        * A ground term. In this case this term determines a property
          of the corresponding argument. The actual property referred
          to is that given by the term but with one more argument
          added at the beginning, which is a new variable which, in a
          rewriting of the head pattern, appears at the argument
          position occupied by the term. Unless otherwise stated (see
          below), the property built this way is understood to hold
          for both calls and answers. For example, the head pattern
          `p(Input,list(integer),Output)' is valid and equivalent for
          example to having the head pattern `p(Input,A,Output)' and
          stating that the property `list(A,integer)' holds for the
          calls and successes of the predicate.

        * Finally, it can also be a variable or a ground term, as
          above, but preceded by a " mode." This mode determines in a
          compact way certain call or answer properties. For example,
          the head pattern `p(Input,+list(integer),Output)' is valid,
          as long as `+/1' is declared as a mode.

          Acceptable modes are documented in `library(modes)'. User
          defined modes are documented in `modedef/1'.

     *Usage:* `head_pattern(Pr)'
        - _Description:_ `Pr' is a head pattern.

 -- REGTYPE: complex_arg_property/1:
     `complex_arg_property(Props)'

     `Props' is a (possibly empty) complex argument property. Such
     properties can appear in two formats, which are defined by `property_conjunction/1'
     and `property_starterm/1' respectively. The two formats can be
     mixed provided they are not in the same field of an assertion.
     I.e., the following is a valid assertion:

     `:- pred foo(X,Y) : nonvar * var => (ground(X),ground(Y)).'

     *Usage:* `complex_arg_property(Props)'
        - _Description:_ `Props' is a (possibly empty) complex
          argument property

 -- REGTYPE: property_conjunction/1:
     This type defines the first, unabridged format in which
     properties can be expressed in the bodies of assertions. It is
     essentially a conjunction of properties which refer to
     variables. The following is an example of a complex property in
     this format:

        * `(integer(X),list(Y,integer))': `X' has the property `integer/1'
          and `Y' has the property `list/2', with second argument
          `integer'.

     *Usage:* `property_conjunction(Props)'
        - _Description:_ `Props' is either a term or a _conjunction_
          of terms. The main functor and arity of each of those terms
          corresponds to the definition of a property. The first
          argument of each such term is a variable which appears as a
          head argument.

 -- REGTYPE: property_starterm/1:
     This type defines a second, compact format in which properties
     can be expressed in the bodies of assertions. A `property_starterm/1'
     is a term whose main functor is `*/2' and, when it appears in an
     assertion, the number of terms joined by `*/2' is exactly the
     arity of the predicate it refers to. A similar series of
     properties as in `property_conjunction/1' appears, but the arity
     of each property is one less: the argument position to which
     they refer (first argument) is left out and determined by the
     position of the property in the `property_starterm/1'. The idea
     is that each element of the `*/2' term corresponds to a head
     argument position. Several properties can be assigned to each
     argument position by grouping them in curly brackets. The
     following is an example of a complex property in this format:

        * ` integer * list(integer)': the first argument of the
          procedure (or function, or ...) has the property `integer/1'
          and the second one has the property `list/2', with second
          argument `integer'.

        * ` {integer,var} * list(integer)': the first argument of the
          procedure (or function, or ...) has the properties `integer/1'
          and `var/1' and the second one has the property `list/2',
          with second argument `integer'.

     *Usage:* `property_starterm(Props)'
        - _Description:_ `Props' is either a term or several terms
          separated by `*/2'. The main functor of each of those terms
          corresponds to that of the definition of a property, and
          the arity should be one less than in the definition of such
          property. All arguments of each such term are ground.

 -- REGTYPE: complex_goal_property/1:
     `complex_goal_property(Props)'

     `Props' is a (possibly empty) complex goal property. Such
     properties can be either a term or a _conjunction_ of terms. The
     main functor and arity of each of those terms corresponds to the
     definition of a property. Such properties apply to all
     executions of all goals of the predicate which comply with the
     assertion in which the `Props' appear.

     The arguments of the terms in `Props' are implicitely augmented
     with a first argument which corresponds to a goal of the
     predicate of the assertion in which the `Props' appear. For
     example, the assertion
               :- comp var(A) + not_further_inst(A).
     has property `not_further_inst/1' as goal property, and
     establishes that in all executions of `var(A)' it should hold
     that `not_further_inst(var(A),A)'.

     *Usage:* `complex_goal_property(Props)'
        - _Description:_ `Props' is either a term or a _conjunction_
          of terms. The main functor and arity of each of those terms
          corresponds to the definition of a property. A first
          implicit argument in such terms identifies goals to which
          the properties apply.

 -- PROPERTY: nabody/1:
     *Usage:* `nabody(ABody)'
        - _Description:_ `ABody' is a normalized assertion body.

 -- REGTYPE: dictionary/1:
     *Usage:* `dictionary(D)'
        - _Description:_ `D' is a dictionary of variable names.

 -- REGTYPE: c_assrt_body/1:
     This predicate defines the different types of syntax admissible
     in the bodies of `call/1', `entry/1', etc. assertions. The
     following are admissible:

                Pr : CP [# CO]

     where (fields between [...] are optional):

        * `CP' is a (possibly empty) complex argument property ( `complex_arg_property/1')
          which applies to the _calls_ to the predicate.

        * `CO' is a comment string ( `docstring/1'). This comment
          only applies if the (possibly empty) properties given for
          calls in the assertion hold. The usual formatting commands
          that are applicable in comment strings can be used (see `stringcommand/1').

     The format of the different parts of the assertion body are
     given by `n_assrt_body/5' and its auxiliary types.

     *Usage:* `c_assrt_body(X)'
        - _Description:_ `X' is a call assertion body.

 -- REGTYPE: s_assrt_body/1:
     This predicate defines the different types of syntax admissible
     in the bodies of `pred/1', `func/1', etc. assertions. The
     following are admissible:

                Pr : CP => AP # CO
                Pr : CP => AP
                Pr => AP # CO
                Pr => AP

     where:

        * `Pr' is a head pattern ( `head_pattern/1') which describes
          the predicate or property and possibly gives some implicit
          call/answer information.

        * `CP' is a (possibly empty) complex argument property ( `complex_arg_property/1')
          which applies to the _calls_ to the predicate.

        * `AP' is a (possibly empty) complex argument property ( `complex_arg_property/1')
          which applies to the _answers_ to the predicate (if the
          predicate succeeds). These only apply if the (possibly
          empty) properties given for calls in the assertion hold.

        * `CO' is a comment string ( `docstring/1'). This comment
          only applies if the (possibly empty) properties given for
          calls in the assertion hold. The usual formatting commands
          that are applicable in comment strings can be used (see `stringcommand/1').

     The format of the different parts of the assertion body are
     given by `n_assrt_body/5' and its auxiliary types.

     *Usage:* `s_assrt_body(X)'
        - _Description:_ `X' is a predicate assertion body.

 -- REGTYPE: g_assrt_body/1:
     This predicate defines the different types of syntax admissible
     in the bodies of `comp/1' assertions. The following are
     admissible:

                Pr : CP + GP # CO
                Pr : CP + GP
                Pr + GP # CO
                Pr + GP

     where:

        * `Pr' is a head pattern ( `head_pattern/1') which describes
          the predicate or property and possibly gives some implicit
          call/answer information.

        * `CP' is a (possibly empty) complex argument property ( `complex_arg_property/1')
          which applies to the _calls_ to the predicate.

        * `GP' contains (possibly empty) complex goal property ( `complex_goal_property/1')
          which applies to the _whole execution_ of a call to the
          predicate. These only apply if the (possibly empty)
          properties given for calls in the assertion hold.

        * `CO' is a comment string ( `docstring/1'). This comment
          only applies if the (possibly empty) properties given for
          calls in the assertion hold. The usual formatting commands
          that are applicable in comment strings can be used (see `stringcommand/1').

     The format of the different parts of the assertion body are
     given by `n_assrt_body/5' and its auxiliary types.

     *Usage:* `g_assrt_body(X)'
        - _Description:_ `X' is a comp assertion body.

 -- REGTYPE: assrt_status/1:
     The types of assertion status. They have the same meaning as the
     program-point assertions, and are as follows:
          assrt_status(true).
          assrt_status(false).
          assrt_status(check).
          assrt_status(checked).
          assrt_status(trust).

     *Usage:* `assrt_status(X)'
        - _Description:_ `X' is an acceptable status for an assertion.

 -- REGTYPE: assrt_type/1:
     The admissible kinds of assertions:
          assrt_type(pred).
          assrt_type(prop).
          assrt_type(decl).
          assrt_type(func).
          assrt_type(calls).
          assrt_type(success).
          assrt_type(comp).
          assrt_type(entry).
          assrt_type(modedef).

     *Usage:* `assrt_type(X)'
        - _Description:_ `X' is an admissible kind of assertion.

 -- REGTYPE: predfunctor/1:
     *Usage:* `predfunctor(X)'
        - _Description:_ `X' is a type of assertion which defines a
          predicate.

 -- REGTYPE: propfunctor/1:
     *Usage:* `propfunctor(X)'
        - _Description:_ `X' is a type of assertion which defines a
          _property_.

 -- PROPERTY: docstring/1:
     *Usage:* `docstring(String)'
        - _Description:_ `String' is a text comment with admissible
          documentation commands. The usual formatting commands that
          are applicable in comment strings are defined by `stringcommand/1'.
          See the `lpdoc' manual for documentation on comments.

55 Declaring regular types
**************************

*Author(s):* Manuel Hermenegildo, Pedro Lopez, Francisco Bueno.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.5#9 (1999/12/9, 21:57:42 MET)

   This library package adds some new declaration definitions and new
operator definitions to user programs. These new declarations and
operators provide some very simple syntactic sugar to support regular
type definitions in source code. Regular types are just properties
which have the additional characteristic of being regular types ( `basic_props:regtype/1').

   For example, this library package allows writing:
        :- regtype tree(X) # "`X' is a tree.".
   instead of the more combersome:
        :- prop tree(X) + regtype # "`X' is a tree.".

   Regular types can be used as properties to describe predicates and
play an essential role in program debugging (see the Ciao Prolog
preprocessor (`ciaopp') manual).

   In this chapter we explain some general considerations worth
taking into account when writing properties in general, not just
regular types. The exact syntax of regular types is also described.

55.1 Defining properties
========================

Given the classes of assertions in the Ciao assertion language, there
are two fundamental classes of properties. Properties used in
assertions which refer to execution states (i.e., `calls/1',
`success/1', and the like) are called _properties of execution
states_. Properties used in assertions related to computations (i.e.,
`comp/1') are called _properties of computations_. Different
considerations apply when writing a property of the former or of the
later kind.

   Consider a definition of the predicate `string_concat/3' which
concatenates two character strings (represented as lists of ASCII
codes):
     string_concat([],L,L).
     string_concat([X|Xs],L,[X|NL]):- string_concat(Xs,L,NL).

   Assume that we would like to state in an assertion that each
argument "is a list of integers." However, we must decide which one
of the following two possibilities we mean exactly: "the argument is
_instantiated_ to a list of integers" (let us call this property
`instantiated_to_intlist/1'), or "if any part of the argument is
instantiated, this instantiation must be compatible with the argument
being a list of integers" (we will call this property
`compatible_with_intlist/1'). For example,
`instantiated_to_intlist/1' should be true for the terms `[]' and
`[1,2]', but should not for `X', `[a,2]', and `[X,2]'. In turn,
`compatible_with_intlist/1' should be true for `[]', `X', `[1,2]',
and `[X,2]', but should not be for `[X|1]', `[a,2]', and `1'. We
refer to properties such as `instantiated_to_intlist/1' above as _instantiation
properties_ and to those such as `compatible_with_intlist/1' as _compatibility
properties_ (corresponding to the traditional notions of
"instantiation types" and "compatibility types").

   It turns out that both of these notions are quite useful in
practice. In the example above, we probably would like to use
`compatible_with_intlist/1' to state that on success of
`string_concat/3' all three argument must be compatible with lists of
integers in an assertion like:

     :- success string_concat(A,B,C) => ( compatible_with_intlist(A),
                                          compatible_with_intlist(B),
                                          compatible_with_intlist(C) ).

   With this assertion, no error will be flagged for a call to
`string_concat/3' such as `string_concat([20],L,R)', which on success
produces the resulting atom `string_concat([20],L,[20|L])', but a
call `string_concat([],a,R)' would indeed flag an error.

   On the other hand, and assuming that we are running on a Prolog
system, we would probably like to use `instantiated_to_intlist/1' for
`sumlist/2' as follows:

     :- calls sumlist(L,N) : instantiated_to_intlist(L).

     sumlist([],0).
     sumlist([X|R],S) :- sumlist(R,PS), S is PS+X.

to describe the type of calls for which the program has been
designed, i.e., those in which the first argument of `sumlist/2' is
indeed a list of integers.

   The property `instantiated_to_intlist/1' might be written as in
the following (Prolog) definition:

     :- prop instantiated_to_intlist/1.

     instantiated_to_intlist(X) :-
            nonvar(X), instantiated_to_intlist_aux(X).

     instantiated_to_intlist_aux([]).
     instantiated_to_intlist_aux([X|T]) :-
            integer(X), instantiated_to_intlist(T).

   (Recall that the Prolog builtin `integer/1' itself implements an
instantiation check, failing if called with a variable as the
argument.)

   The property `compatible_with_intlist/1' might in turn be written
as follows (also in Prolog):

     :- prop compatible_with_intlist/1.

     compatible_with_intlist(X) :- var(X).
     compatible_with_intlist(X) :-
            nonvar(X), compatible_with_intlist_aux(X).

     compatible_with_intlist_aux([]).
     compatible_with_intlist_aux([X|T]) :-
            int_compat(X), compatible_with_intlist(T).

     int_compat(X) :- var(X).
     int_compat(X) :- nonvar(X), integer(X).

   Note that these predicates meet the criteria for being properties
and thus the `prop/1' declaration is correct.

   Ensuring that a property meets the criteria for "not affecting the
computation" can sometimes make its coding somewhat tedious. In some
ways, one would like to be able to write simply:

     intlist([]).
     intlist([X|R]) :- int(X), intlist(R).

(Incidentally, note that the above definition, provided that it suits
the requirements for being a property and that `int/1' is a regular
type, meets the criteria for being a regular type. Thus, it could be
declared `:- regtype intlist/1'.)

   But note that (independently of the definition of `int/1') the
definition above is not the correct instantiation check, since it
would succeed for a call such as `intlist(X)'. In fact, it is not
strictly correct as a compatibility property either, because, while
it would fail or succeed as expected, it would perform instantiations
(e.g., if called with `intlist(X)' it would bind `X' to `[]'). In
practice, it is convenient to provide some run-time support to aid in
this task.

   The run-time support of the Ciao system (see Run-time checking of assertions)
ensures that the execution of properties is
performed in such a way that properties written as above can be used
directly as instantiation checks. Thus, writing:

     :- calls sumlist(L,N) : intlist(L).

has the desired effect. Also, the same properties can often be used
as compatibility checks by writing them in the assertions as
`compat(Property)' (`basic_props:compat/1'). Thus, writing:

     :- success string_concat(A,B,C) => ( compat(intlist(A)),
                                          compat(intlist(B)),
                                          compat(intlist(C)) ).

also has the desired effect.

   As a general rule, the properties that can be used directly for
checking for compatibility should be _downwards closed_, i.e., once
they hold they will keep on holding in every state accessible in
forwards execution. There are certain predicates which are inherently
_instantiation_ checks and should not be used as _compatibility_
properties nor appear in the definition of a property that is to be
used with `compat'. Examples of such predicates (for Prolog) are
`==', `ground', `nonvar', `integer', `atom', `>', etc. as they
require a certain instantiation degree of their arguments in order to
succeed.

   In contrast with properties of execution states, _properties of
computations_ refer to the entire execution of the call(s) that the
assertion relates to. One such property is, for example, `not_fail/1'
(note that although it has been used as in `:- comp append(Xs,Ys,Zs)
+ not_fail', it is in fact read as `not_fail(append(Xs,Ys,Zs))'; see
`assertions_props:complex_goal_property/1'). For this property, which
should be interpreted as "execution of the predicate either succeeds
at least once or loops," we can use the following predicate
`not_fail/1' for run-time checking:

     not_fail(Goal):-
           if( call(Goal),
               true,            %% then
               warning(Goal) ). %% else

where the `warning/1' (library) predicate simply prints a warning
message.

   In this simple case, implementation of the predicate is not very
difficult using the (non-standard) `if/3' builtin predicate present
in many Prolog systems.

   However, it is not so easy to code predicates which check other
properties of the computation and we may in general need to program a
meta-interpreter for this purpose.

55.2 Usage and interface (`regtypes')
=====================================

   * *Library usage:*

     `:- use_package(regtypes).'

     or

     `:- module(...,...,[regtypes]).'

   * *New operators defined:*

     `regtype/1' [1150,fx], `regtype/2' [1150,xfx].

   * *New declarations defined:*

     `regtype/1', `regtype/2'.

   * *Other modules used:*
        - _System library modules:_

          `assertions/assertions_props'.

55.3 Documentation on new declarations (`regtypes')
===================================================

 -- DECLARATION: regtype/1:
     This assertion is similar to a pred assertion but it flags that
     the predicate being documented is also a " regular type." This
     allows for example checking whether it is in the class of types
     supported by the type checking and inference modules. Currently,
     types are properties whose definitions are _regular programs_.

     A regular program is defined by a set of clauses, each of the
     form:
          p(x, v_1, ..., v_n)  :- body_1, ..., body_k.
     where:
       1. `x' is a term whose variables (which are called _term
          variables_) are unique, i.e., it is not allowed to
          introduce equality constraints between the variables of `x'.

          For example, `p(f(X, Y)) :- ...' is valid, but `p(f(X, X))
          :- ...' is not.

       2. in all clauses defining `p/n+1' the terms `x' do not unify
          except maybe for one single clause in which `x' is a
          variable.

       3. `n' >= 0 and `p/n' is a _parametric type functor_ (whereas
          the predicate defined by the clauses is `p/n'+1).

       4. `v_1', ..., `v_n' are unique variables, which are called
          _parametric variables_.

       5. Each `body_i' is of the form:

            1. `t(z)' where `z' is one of the _term variables_ and
               `t' is a _regular type expression_;

            2. `q(y, t_1, ..., t_m)' where `m' >= 0, `q/m' is a
               _parametric type functor_, not in the set of functors
               `=/2', `^/2', `./3'.

               `t_1, ..., t_m' are _regular type expressions_, and
               `y' is a _term variable_.

       6. Each term variable occurs at most once in the clause's body
          (and should be as the first argument of a literal).
          A _regular type expression_ is either a parametric variable
     or a parametric type functor applied to some of the parametric
     variables (but regular type abstractions might also be used in
     some cases, see Meta-properties).

     A parametric type functor is a regular type, defined by a
     regular program, or a basic type. Basic types are defined in
     Basic data types and properties.

     The set of types is thus a well defined subset of the set of
     properties. Note that types can be used to describe
     characteristics of arguments in assertions and they can also be
     executed (called) as any other predicates.

     *Usage:* :- `regtype(AssertionBody)'.
        - _The following properties should hold at call time:_

          `AssertionBody' is an assertion body.
          (`assertions_props:assrt_body/1')

 -- DECLARATION: regtype/2:
     This assertion is similar to a `regtype/1' assertion but it is
     explicitely qualified. Non-qualified `regtype/1' assertions are
     assumed the qualifier `check'. Note that checking regular type
     definitions should be done with the `ciaopp' preprocessor.

     *Usage:* :- `regtype(AssertionStatus, AssertionBody)'.
        - _The following properties should hold at call time:_

          `AssertionStatus' is an acceptable status for an assertion.
          (`assertions_props:assrt_status/1')

          `AssertionBody' is an assertion body.
          (`assertions_props:assrt_body/1')

56 Properties which are native to analyzers
*******************************************

*Author(s):* Francisco Bueno, Manuel Hermenegildo, Pedro Lopez.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#86 (2003/7/17, 16:59:29 CEST)

   This library contains a set of properties which are natively
understood by the different program analyzers of `ciaopp'. They are
used by `ciaopp' on output and they can also be used as properties in
assertions.

56.1 Usage and interface (`native_props')
=========================================

   * *Library usage:*

     `:- use_module(library('assertions/native_props'))'

     or also as a package `:- use_package(nativeprops)'.

     Note the different names of the library and the package.

   * *Exports:*
        - _Properties:_

          `covered/2', `linear/1', `mshare/1', `nonground/1', `fails/1', `not_fails/1', `possibly_fails/1', `covered/1', `not_covered/1', `is_det/1', `non_det/1', `possibly_nondet/1', `mut_exclusive/1', `not_mut_exclusive/1', `size_lb/2', `size_ub/2', `steps_lb/2', `steps_ub/2', `steps/2', `finite_solutions/1', `terminates/1'.

   * *Other modules used:*
        - _System library modules:_

          `andprolog/andprolog_rt', `terms_check', `terms_vars', `sort', `lists'.

56.2 Documentation on exports (`native_props')
==============================================

 -- PROPERTY: covered/2:
     `covered(X, Y)'

     All variables occuring in `X' occur also in `Y'.

     *Usage:* `covered(X, Y)'
        - _Description:_ `X' is covered by `Y'.

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PROPERTY: linear/1:
     `linear(X)'

     `X' is bound to a term which is linear, i.e., if it contains any
     variables, such variables appear only once in the term. For
     example, `[1,2,3]' and `f(A,B)' are linear terms, while `f(A,A)'
     is not.

     *Usage:* `linear(X)'
        - _Description:_ `X' is instantiated to a linear term.

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PROPERTY: mshare/1:
     `mshare(X)'

     `X' contains all _sharing sets_ [JL88,MH89] which specify the
     possible variable occurrences in the terms to which the
     variables involved in the clause may be bound. Sharing sets are
     a compact way of representing groundness of variables and
     dependencies between variables. This representation is however
     generally difficult to read for humans. For this reason, this
     information is often translated to `ground/1', `indep/1' and `indep/2'
     properties, which are easier to read.

     *Usage:* `mshare(X)'
        - _Description:_ The sharing pattern is ``X''.

        - _The following properties should hold globally:_

          This predicate is understood natively by CiaoPP as
          `sharing(X)'.   (`basic_props:native/2')

 -- PROPERTY: nonground/1:
     *Usage:* `nonground(X)'
        - _Description:_ ``X'' is not ground.

        - _The following properties should hold globally:_

          This predicate is understood natively by CiaoPP as
          `not_ground(X)'.   (`basic_props:native/2')

 -- PROPERTY: fails/1:
     `fails(X)'

     Calls of the form `X' fail.

     *Usage:* `fails(X)'
        - _Description:_ Calls of the form `X' fail.

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PROPERTY: not_fails/1:
     `not_fails(X)'

     Calls of the form `X' produce at least one solution, or not
     terminate [DLGH97].

     *Usage:* `not_fails(X)'
        - _Description:_ All the calls of the form `X' do not fail.

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PROPERTY: possibly_fails/1:
     `possibly_fails(X)'

     Non-failure is not ensured for any call of the form `X'
     [DLGH97]. In other words, nothing can be ensured about
     non-failure nor termination of such calls.

     *Usage:* `possibly_fails(X)'
        - _Description:_ Non-failure is not ensured for calls of the
          form `X'.

 -- PROPERTY: covered/1:
     `covered(X)'

     For any call of the form `X' there is at least one clause whose
     test succeeds (i.e. all the calls of the form `X' are covered.)
     [DLGH97].

     *Usage:* `covered(X)'
        - _Description:_ All the calls of the form `X' are covered.

 -- PROPERTY: not_covered/1:
     `not_covered(X)'

     There is some call of the form `X' for which there is not any
     clause whose test succeeds [DLGH97].

     *Usage:* `not_covered(X)'
        - _Description:_ Not all of the calls of the form `X' are
          covered.

 -- PROPERTY: is_det/1:
     `is_det(X)'

     All calls of the form `X' are deterministic, i.e. produce at
     most one solution, or not terminate.

     *Usage:* `is_det(X)'
        - _Description:_ All calls of the form `X' are deterministic.

 -- PROPERTY: non_det/1:
     `non_det(X)'

     All calls of the form `X' are not deterministic, i.e., produce
     several solutions.

     *Usage:* `non_det(X)'
        - _Description:_ All calls of the form `X' are not
          deterministic.

 -- PROPERTY: possibly_nondet/1:
     `possibly_nondet(X)'

     Non-determinism is not ensured for all calls of the form `X'. In
     other words, nothing can be ensured about determinacy nor
     termination of such calls.

     *Usage:* `possibly_nondet(X)'
        - _Description:_ Non-determinism is not ensured for calls of
          the form `X'.

 -- PROPERTY: mut_exclusive/1:
     `mut_exclusive(X)'

     For any call of the form `X' at most one clause succeeds, i.e.
     clauses are pairwise exclusive.

     *Usage:* `mut_exclusive(X)'
        - _Description:_ For any call of the form `X' at most one
          clause succeeds.

 -- PROPERTY: not_mut_exclusive/1:
     `not_mut_exclusive(X)'

     Not for all calls of the form `X' at most one clause succeeds.
     I.e. clauses are not disjoint for some call.

     *Usage:* `not_mut_exclusive(X)'
        - _Description:_ Not for all calls of the form `X' at most
          one clause succeeds.

 -- PROPERTY: size_lb/2:
     `size_lb(X, Y)'

     The minimum size of the terms to which the argument `Y' is bound
     to is given by the expression `Y'. Various measures can be used
     to determine the size of an argument, e.g., list-length,
     term-size, term-depth, integer-value, etc. [DL93].

     *Usage:* `size_lb(X, Y)'
        - _Description:_ `Y' is a lower bound on the size of argument
          `X'.

 -- PROPERTY: size_ub/2:
     `size_ub(X, Y)'

     The maximum size of the terms to which the argument `Y' is bound
     to is given by the expression `Y'. Various measures can be used
     to determine the size of an argument, e.g., list-length,
     term-size, term-depth, integer-value, etc. [DL93].

     *Usage:* `size_ub(X, Y)'
        - _Description:_ `Y' is a upper bound on the size of argument
          `X'.

 -- PROPERTY: steps_lb/2:
     `steps_lb(X, Y)'

     The minimum computation time (in resolution steps) spent by any
     call of the form `X' is given by the expression `Y'
     [DLGHL97,LGHD96]

     *Usage:* `steps_lb(X, Y)'
        - _Description:_ `Y' is a lower bound on the cost of any call
          of the form `X'.

 -- PROPERTY: steps_ub/2:
     `steps_ub(X, Y)'

     The maximum computation time (in resolution steps) spent by any
     call of the form `X' is given by the expression `Y' [DL93,LGHD96]

     *Usage:* `steps_ub(X, Y)'
        - _Description:_ `Y' is a upper bound on the cost of any call
          of the form `X'.

 -- PROPERTY: steps/2:
     `steps(X, Y)'

     The time (in resolution steps) spent by any call of the form `X'
     is given by the expression `Y'

     *Usage:* `steps(X, Y)'
        - _Description:_ `Y' is the cost (number of resolution steps)
          of any call of the form `X'.

 -- PROPERTY: finite_solutions/1:
     `finite_solutions(X)'

     Calls of the form `X' produce a finite number of solutions
     [DLGH97].

     *Usage:* `finite_solutions(X)'
        - _Description:_ All the calls of the form `X' have a finite
          number of solutions.

 -- PROPERTY: terminates/1:
     `terminates(X)'

     Calls of the form `X' always terminate [DLGH97].

     *Usage:* `terminates(X)'
        - _Description:_ All the calls of the form `X' terminate.

 -- PROPERTY: indep/1:
     *Usage:* `indep(X)'
        - _Description:_ The variables in pairs in ``X'' are pairwise
          independent.

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP as
          `indep(X)'.   (`basic_props:native/2')

 -- PROPERTY: indep/2:
     *Usage:* `indep(X, Y)'
        - _Description:_ `X' and `Y' do not have variables in common.

        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP as
          `indep([[X,Y]])'.   (`basic_props:native/2')

 -- PROPERTY: ground/1:
     *Usage:* `ground(X)'
        - _Description:_ `X' is currently ground (it contains no
          variables).

        - _The following properties hold upon exit:_

          `X' is ground.   (`basic_props:gnd/1')

        - _The following properties hold globally:_

          `X' is not further instantiated.
          (`basic_props:not_further_inst/2')

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PROPERTY: nonvar/1:
     *General properties:* `nonvar(X)'
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

          This predicate is understood natively by CiaoPP as
          `not_free(X)'.   (`basic_props:native/2')

     *Usage:* `nonvar(X)'
        - _Description:_ `X' is currently a term which is not a free
          variable.

        - _The following properties hold globally:_

          `X' is not further instantiated.
          (`basic_props:not_further_inst/2')

 -- PROPERTY: var/1:
     *General properties:* `var(X)'
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

          This predicate is understood natively by CiaoPP as
          `free(X)'.   (`basic_props:native/2')

          `var(X)' is side-effect `hard'.   (`basic_props:sideff/2')

     *Usage:* `var(X)'
        - _Description:_ `X' is a free variable.

        - _The following properties hold globally:_

          `X' is not further instantiated.
          (`basic_props:not_further_inst/2')

 -- (: UNDOC_REEXPORT) regtype/1:
     Imported from `basic_props' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) native/2:
     Imported from `basic_props' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) native/1:
     Imported from `basic_props' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) sideff/2:
     Imported from `basic_props' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) term/1:
     Imported from `basic_props' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) int/1:
     Imported from `basic_props' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) nnegint/1:
     Imported from `basic_props' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) flt/1:
     Imported from `basic_props' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) num/1:
     Imported from `basic_props' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) atm/1:
     Imported from `basic_props' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) struct/1:
     Imported from `basic_props' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) gnd/1:
     Imported from `basic_props' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) instance/2:
     Imported from `terms_check' (see the corresponding documentation
     for details).

57 ISO-Prolog modes
*******************

*Author(s):* Daniel Cabeza, Manuel Hermenegildo.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#292 (2004/2/16, 14:52:52 CET)

   This file defines the " modes" used in the documentation of the
ISO-Prolog standard. See also Classical Prolog modes for an
alternative set of modes.

57.1 Usage and interface (`isomodes')
=====================================

   * *Library usage:*

     `:- use_package([assertions,isomodes]).'

   * *New operators defined:*

     `?/1' [200,fy], `@/1' [200,fy].

   * *New modes defined:*

     `+/1', `@/1', `-/1', `?/1', `*/1', `+/2', `@/2', `-/2', `?/2', `*/2'.

57.2 Documentation on new modes (`isomodes')
============================================

 -- MODE: +/1:
     *Usage:* `+ A'
        - _The following properties are added at call time:_

          `A' is currently a term which is not a free variable.
          (`term_typing:nonvar/1')

 -- MODE: @/1:
     *Usage:* `@ A'
        - _The following properties are added globally:_

          `A' is not further instantiated.
          (`basic_props:not_further_inst/2')

 -- MODE: -/1:
     *Usage:* `- A'
        - _The following properties are added at call time:_

          `A' is a free variable.   (`term_typing:var/1')

 -- MODE: ?/1:
     Unspecified argument.

 -- MODE: */1:
     Unspecified argument.

 -- MODE: +/2:
     *Usage:* `A + X'
        - _The following properties are added at call time:_

          `undefined:call(X,A)'  (undefined property)

 -- MODE: @/2:
     *Usage:* `@(A, X)'
        - _The following properties are added at call time:_

          `undefined:call(X,A)'  (undefined property)

        - _The following properties are added upon exit:_

          `undefined:call(X,A)'  (undefined property)

        - _The following properties are added globally:_

          `A' is not further instantiated.
          (`basic_props:not_further_inst/2')

 -- MODE: -/2:
     *Usage:* `A - X'
        - _The following properties are added at call time:_

          `A' is a free variable.   (`term_typing:var/1')

        - _The following properties are added upon exit:_

          `undefined:call(X,A)'  (undefined property)

 -- MODE: ?/2:
     *Usage:* `?(A, X)'
        - _Call and exit are _compatible_ with:_

          `undefined:call(X,A)'  (undefined property)

        - _The following properties are added upon exit:_

          `undefined:call(X,A)'  (undefined property)

 -- MODE: */2:
     *Usage:* `A * X'
        - _Call and exit are _compatible_ with:_

          `undefined:call(X,A)'  (undefined property)

58 Classical Prolog modes
*************************

*Author(s):* Manuel Hermenegildo.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 0.8#43 (1999/3/6, 18:39:38 CET)

   This file defines a number of very simple " modes" which are
frequently useful in programs. These correspond to the modes used in
classical Prolog texts with some simple addtions. Note that some of
these modes use the same symbol as one of the ISO-modes (see
ISO-Prolog modes) but with subtly different meaning.

58.1 Usage and interface (`basicmodes')
=======================================

   * *Library usage:*

     :- use_package([assertions,basicmodes]).

   * *New operators defined:*

     `^/1' [25,fy], `?/1' [500,fx], `@/1' [500,fx].

   * *New modes defined:*

     `+/1', `-/1', `?/1', `@/1', `in/1', `out/1', `go/1', `+/2', `-/2', `?/2', `@/2', `in/2', `out/2', `go/2'.

58.2 Documentation on new modes (`basicmodes')
==============================================

 -- MODE: +/1:
     Input value in argument.

     *Usage:* `+ A'
        - _The following properties are added at call time:_

          `A' is currently a term which is not a free variable.
          (`term_typing:nonvar/1')

 -- MODE: -/1:
     No input value in argument.

     *Usage:* `- A'
        - _The following properties are added at call time:_

          `A' is a free variable.   (`term_typing:var/1')

 -- MODE: ?/1:
     Unspecified argument.

 -- MODE: @/1:
     No output value in argument.

     *Usage:* `@ A'
        - _The following properties are added globally:_

          `A' is not further instantiated.
          (`basic_props:not_further_inst/2')

 -- MODE: in/1:
     Input argument.

     *Usage:* `in(A)'
        - _The following properties are added at call time:_

          `A' is currently ground (it contains no variables).
          (`term_typing:ground/1')

        - _The following properties are added upon exit:_

          `A' is currently ground (it contains no variables).
          (`term_typing:ground/1')

 -- MODE: out/1:
     Output argument.

     *Usage:* `out(A)'
        - _The following properties are added at call time:_

          `A' is a free variable.   (`term_typing:var/1')

        - _The following properties are added upon exit:_

          `A' is currently ground (it contains no variables).
          (`term_typing:ground/1')

 -- MODE: go/1:
     Ground output (input/output argument).

     *Usage:* `go(A)'
        - _The following properties are added upon exit:_

          `A' is currently ground (it contains no variables).
          (`term_typing:ground/1')

 -- MODE: +/2:
     *Usage:* `A + X'
        - _Call and exit are _compatible_ with:_

          `undefined:call(X,A)'  (undefined property)

        - _The following properties are added at call time:_

          `A' is currently a term which is not a free variable.
          (`term_typing:nonvar/1')

 -- MODE: -/2:
     *Usage:* `A - X'
        - _Call and exit are _compatible_ with:_

          `undefined:call(X,A)'  (undefined property)

        - _The following properties are added at call time:_

          `A' is a free variable.   (`term_typing:var/1')

 -- MODE: ?/2:
     *Usage:* `?(A, X)'
        - _Call and exit are _compatible_ with:_

          `undefined:call(X,A)'  (undefined property)

 -- MODE: @/2:
     *Usage:* `@(A, X)'
        - _Call and exit are _compatible_ with:_

          `undefined:call(X,A)'  (undefined property)

        - _The following properties are added globally:_

          `A' is not further instantiated.
          (`basic_props:not_further_inst/2')

 -- MODE: in/2:
     *Usage:* `in(A, X)'
        - _Call and exit are _compatible_ with:_

          `undefined:call(X,A)'  (undefined property)

        - _The following properties are added at call time:_

          `A' is currently ground (it contains no variables).
          (`term_typing:ground/1')

        - _The following properties are added upon exit:_

          `A' is currently ground (it contains no variables).
          (`term_typing:ground/1')

 -- MODE: out/2:
     *Usage:* `out(A, X)'
        - _Call and exit are _compatible_ with:_

          `undefined:call(X,A)'  (undefined property)

        - _The following properties are added at call time:_

          `A' is a free variable.   (`term_typing:var/1')

        - _The following properties are added upon exit:_

          `A' is currently ground (it contains no variables).
          (`term_typing:ground/1')

 -- MODE: go/2:
     *Usage:* `go(A, X)'
        - _Call and exit are _compatible_ with:_

          `undefined:call(X,A)'  (undefined property)

        - _The following properties are added upon exit:_

          `A' is currently ground (it contains no variables).
          (`term_typing:ground/1')

59 Run-time checking of assertions
**********************************

*Author(s):* German Puebla.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#283 (2004/2/13, 15:39:33 CET)

   This library package allows the use of run-time checks for the
assertions introduced in a program.

   The recommended way of performing _run-time checks_ of predicate
assertions in a program is via the Ciao preprocessor (see `ciaopp'
manual), which performs the required program transformation. However,
this package can also be used to perform checking of program-point
assertions.

59.1 Usage and interface (`rtchecks')
=====================================

   * *Library usage:*

     `:- use_package(rtchecks).'

     or

     `:- module(...,...,[rtchecks]).'

   * *Exports:*
        - _Regular Types:_

          `expr/1'.

   * *Other modules used:*
        - _System library modules:_

          `rtchecks/rtchecks_sys'.

59.2 Documentation on exports (`rtchecks')
==========================================

 -- REGTYPE: expr/1:
     *Usage:*
        - _Description:_ A property formula.

59.3 Documentation on internals (`rtchecks')
============================================

 -- PREDICATE: check/1:
     `check(Property)'

     Checks whether the property defined by `Property' holds.
     Otherwise, a warning message is issued. It corresponds to a
     program-point check assertion (see The Ciao assertion package).

     *Usage:* `check(Property)'
        - _The following properties should hold at call time:_

          A property formula.   (`user(... /rtchecks_doc):expr/1')

59.4 Known bugs and planned improvements (`rtchecks')
=====================================================

   * All the code in this package is included in the user program
     when it is used, ant there is a lot of it! A module should be
     used instead.

   * `check/1' uses lists instead of "proper" properties.

PART VI - Ciao Prolog library miscellanea
*****************************************

*Author(s):* The CLIP Group.

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

60 Structured stream handling
*****************************

*Version:* 1.9#332 (2004/3/29, 19:20:32 CEST)

60.1 Usage and interface (`streams')
====================================

   * *Library usage:*

     `:- use_module(library(streams)).'

   * *Exports:*
        - _Predicates:_

          `open_null_stream/1', `open_input/2', `close_input/1', `open_output/2', `close_output/1'.

60.2 Documentation on exports (`streams')
=========================================

 -- PREDICATE: open_null_stream/1:
     No further documentation available for this predicate.

 -- PREDICATE: open_input/2:
     No further documentation available for this predicate.

 -- PREDICATE: close_input/1:
     No further documentation available for this predicate.

 -- PREDICATE: open_output/2:
     No further documentation available for this predicate.

 -- PREDICATE: close_output/1:
     No further documentation available for this predicate.

61 Dictionaries
***************

*Author(s):* The CLIP Group.

   *Version:* 1.9#240 (2003/12/22, 18:52:17 CET)

   This module provides predicates for implementing dictionaries.
Such dictionaries are currently implemented as ordered binary trees
of key-value pairs.

61.1 Usage and interface (`dict')
=================================

   * *Library usage:*

     `:- use_module(library(dict)).'

   * *Exports:*
        - _Predicates:_

          `dictionary/5', `dic_node/2', `dic_lookup/3', `dic_lookup/4', `dic_get/3', `dic_replace/4'.

        - _Properties:_

          `dictionary/1'.

61.2 Documentation on exports (`dict')
======================================

 -- PROPERTY: dictionary/1:
     *Usage:* `dictionary(D)'
        - _Description:_ `D' is a dictionary.

 -- PREDICATE: dictionary/5:
     *Usage:* `dictionary(D, K, V, L, R)'
        - _Description:_ The dictionary node `D' has key `K', value
          `V', left child `L', and right child `R'.

 -- PREDICATE: dic_node/2:
     *Usage:* `dic_node(D, N)'
        - _Description:_ `N' is a sub-dictionary of `D'.

        - _Calls should, and exit will be compatible with:_

          `D' is a dictionary.   (`dict:dictionary/1')

          `N' is a dictionary.   (`dict:dictionary/1')

 -- PREDICATE: dic_lookup/3:
     *Usage:* `dic_lookup(D, K, V)'
        - _Description:_ `D' contains value `V' at key `K'. If it was
          not already in `D' it is added.

        - _Calls should, and exit will be compatible with:_

          `D' is a dictionary.   (`dict:dictionary/1')

 -- PREDICATE: dic_lookup/4:
     *Usage:* `dic_lookup(D, K, V, O)'
        - _Description:_ Same as `dic_lookup(D,K,V)'. `O' indicates
          if it was already in `D' (`old') or not (`new').

        - _Calls should, and exit will be compatible with:_

          `D' is a dictionary.   (`dict:dictionary/1')

 -- PREDICATE: dic_get/3:
     *Usage:* `dic_get(D, K, V)'
        - _Description:_ `D' contains value `V' at key `K'. Fails if
          it is not already in `D'.

        - _Calls should, and exit will be compatible with:_

          `D' is a dictionary.   (`dict:dictionary/1')

 -- PREDICATE: dic_replace/4:
     *Usage:* `dic_replace(D, K, V, D1)'
        - _Description:_ `D' and `D1' are identical except for the
          element at key `K', which in `D1' contains value `V',
          whatever has (or whether it is) in `D'.

        - _Calls should, and exit will be compatible with:_

          `D' is a dictionary.   (`dict:dictionary/1')

          `D1' is a dictionary.   (`dict:dictionary/1')

62 String processing
********************

*Author(s):* Daniel Cabeza.

   *Version:* 0.4#5 (1998/2/24)

   This module provides predicates for doing input/output with
strings (character code lists) and for including in grammars defining
strings.

62.1 Usage and interface (`strings')
====================================

   * *Library usage:*

     `:- use_module(library(strings)).'

   * *Exports:*
        - _Predicates:_

          `get_line/2', `get_line/1', `write_string/2', `write_string/1', `whitespace/2', `whitespace0/2', `string/3'.

62.2 Documentation on exports (`strings')
=========================================

 -- PREDICATE: get_line/2:
     `get_line(Stream, Line)'

     Reads from `Stream' a line of text and unifies `Line' with it.
     The end of the line can have UNIX [10] or MS-DOS [13 10]
     termination, which is not included in `Line'. At EOF, the term
     end_of_file is returned.

 -- PREDICATE: get_line/1:
     `get_line(Line)'

     Behaves like `current_input(S), get_line(S,Line)'.

 -- PREDICATE: write_string/2:
     `write_string(Stream, String)'

     Writes `String' onto `Stream'.

 -- PREDICATE: write_string/1:
     `write_string(String)'

     Behaves like `current_input(S), write_string(S, String)'.

 -- PREDICATE: whitespace/2:
     `whitespace(String, Rest)'

     In a grammar rule, as `whitespace/0', represents whitespace (a
     positive number of space (32), tab (9), newline (10) or return
     (13) characters). Thus, `Rest' is a proper suffix of `String'
     with one or more whitespace characters removed. An example of
     use would be:
             attrs([]) --> ""
             attrs([N|Ns]) -->
                 whitespace,
                 attr(N),
                 attrs(Ns).

 -- PREDICATE: whitespace0/2:
     `whitespace0(String, Rest)'

     In a grammar rule, as `whitespace0/0', represents possible
     whitespace (any number of space (32), tab (9), newline (10) or
     return (13) characters). Thus, `Rest' is `String' or a proper
     suffix of `String' with one or more whitespace characters
     removed. An example of use would be:

             assignment(N,V) -->
                 variable_name(N), whitespace0, "=", whitespace0, value(V).

 -- PREDICATE: string/3:
     `string(String, Head, Tail)'

     In a grammar rule, as `string/1', represents literally `String'.
     An example of use would be:

          double(A) -->
                  string(A),
                  string(A).

62.3 Documentation on internals (`strings')
===========================================

 -- PROPERTY: line/1:
     A property, defined as follows:
               line(L) :-
                       string(L).
               line(end_of_file).

63 Printing status and error messages
*************************************

*Author(s):* The CLIP Group.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#282 (2004/2/13, 15:20:28 CET)

   This is a very simple library for printing status and error
messages to the console.

63.1 Usage and interface (`messages')
=====================================

   * *Library usage:*

     `:- use_module(library(messages)).'

   * *Exports:*
        - _Predicates:_

          `error_message/1', `error_message/2', `error_message/3', `warning_message/1', `warning_message/2', `warning_message/3', `note_message/1', `note_message/2', `note_message/3', `simple_message/1', `simple_message/2', `optional_message/2', `optional_message/3', `debug_message/1', `debug_message/2', `debug_goal/2', `debug_goal/3'.

        - _Multifiles:_

          `issue_debug_messages/1'.

   * *Other modules used:*
        - _System library modules:_

          `format', `lists', `filenames'.

63.2 Documentation on exports (`messages')
==========================================

 -- PREDICATE: error_message/1:
     _Meta-predicate_ with arguments: `error_message(addmodule)'.

     *Usage:* `error_message(Text)'
        - _Description:_ The text provided in `Text' is printed as an
          ERROR message.

        - _The following properties should hold at call time:_

          `Text' is a string (a list of character codes).
          (`basic_props:string/1')

 -- PREDICATE: error_message/2:
     _Meta-predicate_ with arguments: `error_message(?,addmodule)'.

     *Usage:* `error_message(Text, ArgList)'
        - _Description:_ The text provided in `Text' is printed as an
          ERROR message, using the arguments in `ArgList' to
          interpret any variable-related formatting commands embedded
          in `Text'.

        - _The following properties should hold at call time:_

          `Text' is an atom or string describing how the arguments
          should be formatted. If it is an atom it will be converted
          into a string with `name/2'.   (`format:format_control/1')

          `ArgList' is a list.   (`basic_props:list/1')

 -- PREDICATE: error_message/3:
     _Meta-predicate_ with arguments: `error_message(?,?,addmodule)'.

     *Usage:* `error_message(Lc, Text, ArgList)'
        - _Description:_ The text provided in `Text' is printed as an
          ERROR message, using the arguments in `ArgList' to
          interpret any variable-related formatting commands embedded
          in `Text', and reporting error location `Lc' (file and line
          numbers).

        - _The following properties should hold at call time:_

          Identifies a program source line.   (`messages:location/1')

          `Text' is an atom or string describing how the arguments
          should be formatted. If it is an atom it will be converted
          into a string with `name/2'.   (`format:format_control/1')

          `ArgList' is a list.   (`basic_props:list/1')

 -- PREDICATE: warning_message/1:
     _Meta-predicate_ with arguments: `warning_message(addmodule)'.

     *Usage:* `warning_message(Text)'
        - _Description:_ The text provided in `Text' is printed as a
          WARNING message.

        - _The following properties should hold at call time:_

          `Text' is a string (a list of character codes).
          (`basic_props:string/1')

 -- PREDICATE: warning_message/2:
     _Meta-predicate_ with arguments: `warning_message(?,addmodule)'.

     *Usage:* `warning_message(Text, ArgList)'
        - _Description:_ The text provided in `Text' is printed as a
          WARNING message, using the arguments in `ArgList' to
          interpret any variable-related formatting commands embedded
          in `Text'.

        - _The following properties should hold at call time:_

          `Text' is an atom or string describing how the arguments
          should be formatted. If it is an atom it will be converted
          into a string with `name/2'.   (`format:format_control/1')

          `ArgList' is a list.   (`basic_props:list/1')

 -- PREDICATE: warning_message/3:
     _Meta-predicate_ with arguments:
     `warning_message(?,?,addmodule)'.

     *Usage:* `warning_message(Lc, Text, ArgList)'
        - _Description:_ The text provided in `Text' is printed as a
          WARNING message, using the arguments in `ArgList' to
          interpret any variable-related formatting commands embedded
          in `Text', and reporting error location `Lc' (file and line
          numbers).

        - _The following properties should hold at call time:_

          Identifies a program source line.   (`messages:location/1')

          `Text' is an atom or string describing how the arguments
          should be formatted. If it is an atom it will be converted
          into a string with `name/2'.   (`format:format_control/1')

          `ArgList' is a list.   (`basic_props:list/1')

 -- PREDICATE: note_message/1:
     _Meta-predicate_ with arguments: `note_message(addmodule)'.

     *Usage:* `note_message(Text)'
        - _Description:_ The text provided in `Text' is printed as a
          NOTE.

        - _The following properties should hold at call time:_

          `Text' is a string (a list of character codes).
          (`basic_props:string/1')

 -- PREDICATE: note_message/2:
     _Meta-predicate_ with arguments: `note_message(?,addmodule)'.

     *Usage:* `note_message(Text, ArgList)'
        - _Description:_ The text provided in `Text' is printed as a
          NOTE, using the arguments in `ArgList' to interpret any
          variable-related formatting commands embedded in `Text'.

        - _The following properties should hold at call time:_

          `Text' is an atom or string describing how the arguments
          should be formatted. If it is an atom it will be converted
          into a string with `name/2'.   (`format:format_control/1')

          `ArgList' is a list.   (`basic_props:list/1')

 -- PREDICATE: note_message/3:
     _Meta-predicate_ with arguments: `note_message(?,?,addmodule)'.

     *Usage:* `note_message(Lc, Text, ArgList)'
        - _Description:_ The text provided in `Text' is printed as a
          NOTE, using the arguments in `ArgList' to interpret any
          variable-related formatting commands embedded in `Text',
          and reporting error location `Lc' (file and line numbers).

        - _The following properties should hold at call time:_

          Identifies a program source line.   (`messages:location/1')

          `Text' is an atom or string describing how the arguments
          should be formatted. If it is an atom it will be converted
          into a string with `name/2'.   (`format:format_control/1')

          `ArgList' is a list.   (`basic_props:list/1')

 -- PREDICATE: simple_message/1:
     *Usage:* `simple_message(Text)'
        - _Description:_ The text provided in `Text' is printed.

        - _The following properties should hold at call time:_

          `Text' is a string (a list of character codes).
          (`basic_props:string/1')

 -- PREDICATE: simple_message/2:
     *Usage:* `simple_message(Text, ArgList)'
        - _Description:_ The text provided in `Text' is printed as a
          message, using the arguments in `ArgList'.

        - _The following properties should hold at call time:_

          `Text' is an atom or string describing how the arguments
          should be formatted. If it is an atom it will be converted
          into a string with `name/2'.   (`format:format_control/1')

          `ArgList' is a list.   (`basic_props:list/1')

 -- PREDICATE: optional_message/2:
     *Usage:* `optional_message(Text, Opts)'
        - _Description:_ The text provided in `Text' is printed as a
          message, but only if the atom `-v' is a member of `Opts'.
          These predicates are meant to be used for optional
          messages, which are only to be printed when _verbose_
          output is requested explicitly.

        - _The following properties should hold at call time:_

          `Text' is a string (a list of character codes).
          (`basic_props:string/1')

          `Opts' is a list of `atm's.   (`basic_props:list/2')

 -- PREDICATE: optional_message/3:
     *Usage:* `optional_message(Text, ArgList, Opts)'
        - _Description:_ The text provided in `Text' is printed as a
          message, using the arguments in `ArgList', but only if the
          atom `-v' is a member of `Opts'. These predicates are meant
          to be used for optional messages, which are only to be
          printed when _verbose_ output is requested explicitly.

        - _The following properties should hold at call time:_

          `Text' is an atom or string describing how the arguments
          should be formatted. If it is an atom it will be converted
          into a string with `name/2'.   (`format:format_control/1')

          `ArgList' is a list.   (`basic_props:list/1')

          `Opts' is a list of `atm's.   (`basic_props:list/2')

 -- PREDICATE: debug_message/1:
     _Meta-predicate_ with arguments: `debug_message(addmodule)'.

     *Usage:* `debug_message(Text)'
        - _Description:_ The text provided in `Text' is printed as a
          debugging message. These messages are turned `on' by
          defining a fact of `issue_debug_messages/1' with the module
          name as argument.

        - _The following properties should hold at call time:_

          `Text' is an atom or string describing how the arguments
          should be formatted. If it is an atom it will be converted
          into a string with `name/2'.   (`format:format_control/1')

 -- PREDICATE: debug_message/2:
     _Meta-predicate_ with arguments: `debug_message(?,addmodule)'.

     *Usage:* `debug_message(Text, ArgList)'
        - _Description:_ The text provided in `Text' is printed as a
          debugging message, using the arguments in `ArgList' to
          interpret any variable-related formatting commands embedded
          in `Text'. These messages are turned `on' by defining a
          fact of `issue_debug_messages/1' which the module name as
          argument.

        - _The following properties should hold at call time:_

          `Text' is an atom or string describing how the arguments
          should be formatted. If it is an atom it will be converted
          into a string with `name/2'.   (`format:format_control/1')

          `ArgList' is a list.   (`basic_props:list/1')

 -- PREDICATE: debug_goal/2:
     _Meta-predicate_ with arguments: `debug_goal(goal,addmodule)'.

     *Usage:* `debug_goal(Goal, Text)'
        - _Description:_ `Goal' is called. The text provided in
          `Text' is then printed as a debugging message. The whole
          process (including running `Goal') is turned `on' by
          defining a fact of `issue_debug_messages/1' with the module
          name as argument.

 -- PREDICATE: debug_goal/3:
     _Meta-predicate_ with arguments: `debug_goal(goal,?,addmodule)'.

     *Usage:* `debug_goal(Goal, Text, ArgList)'
        - _Description:_ `Goal' is called. The text provided in
          `Text' is then printed as a debugging message, using the
          arguments in `ArgList' to interpret any variable-related
          formatting commands embedded in `Text'. Note that the
          variables in `ArgList' can be computed by `Goal'. The whole
          process (including running `Goal') is turned `on' by
          defining a fact of `issue_debug_messages/1' with the module
          name as argument.

63.3 Documentation on multifiles (`messages')
=============================================

 -- PREDICATE: issue_debug_messages/1:
     The predicate is _multifile_.

     The predicate is of type _data_.

     *Usage:* `issue_debug_messages(Module)'
        - _Description:_ Printing of debugging messages is enabled
          for module `Module'.

        - _The following properties should hold upon exit:_

          `Module' is currently instantiated to an atom.
          (`term_typing:atom/1')

63.4 Documentation on internals (`messages')
============================================

 -- REGTYPE: location/1:
     *Usage:*
        - _Description:_ Identifies a program source line.

63.5 Known bugs and planned improvements (`messages')
=====================================================

   * Debug message switching should really be done with an expansion,
     for performance.

64 Accessing and redirecting the stream aliases
***********************************************

*Author(s):* Manuel Carro.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.7#52 (2001/1/26, 15:34:13 CET)

   This library allows the redefinition of the files to which the
special streams `user_input', `user_output', and `user_error' point
to. On startup they point to the standard input, standard output, and
standard error, in Unix style (Windows users may find that standard
error stream does not work properly). Changing the file pointed to is
useful for, e.g., redirecting the place to which the Prolog's
standard error stream goes from within Prolog (e.g., to start a log
file).

64.1 Usage and interface (`io_alias_redirection')
=================================================

   * *Library usage:*

     `:- use_module(library(io_alias_redirection)).'

   * *Exports:*
        - _Predicates:_

          `set_stream/3', `get_stream/2'.

64.2 Documentation on exports (`io_alias_redirection')
======================================================

 -- PREDICATE: set_stream/3:
     *Usage:* `set_stream(+StreamAlias, +NewStream, ?OldStream)'
        - _Description:_ Associate `StreamAlias' with an open stream
          `newStream'. Returns in `OldStream' the stream previusly
          associated with the alias. The mode of `NewStream' must
          match the intended use of `StreamAlias'.

        - _The following properties should hold at call time:_

          `+StreamAlias' is the alias of an open stream, i.e., an
          atom which represents a stream at Prolog level.
          (`streams_basic:stream_alias/1')

          `+NewStream' is an open stream.   (`streams_basic:stream/1')

          `?OldStream' is an open stream.   (`streams_basic:stream/1')

 -- PREDICATE: get_stream/2:
     *Usage:* `get_stream(+StreamAlias, ?Stream)'
        - _Description:_ Return in `Stream' the stream associated
          with `StreamAlias'.

        - _The following properties should hold at call time:_

          `+StreamAlias' is the alias of an open stream, i.e., an
          atom which represents a stream at Prolog level.
          (`streams_basic:stream_alias/1')

          `?Stream' is an open stream.   (`streams_basic:stream/1')

65 Atom to term conversion
**************************

*Author(s):* Francisco Bueno, Daniel Cabeza.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#215 (2003/12/21, 2:27:2 CET)

   This module implements the predicates involved in the atom to term
conversion.

65.1 Usage and interface (`atom2term')
======================================

   * *Library usage:*

     `:- use_module(library(atom2term)).'

   * *Exports:*
        - _Predicates:_

          `atom2term/2', `string2term/2', `parse_term/3'.

65.2 Documentation on exports (`atom2term')
===========================================

 -- PREDICATE: atom2term/2:
     *Usage:* `atom2term(+Atom, -Term)'
        - _Description:_ Convert an atom into a term. `Atom' is an
          atom, but must have term syntax. `Term' is a term resulting
          from parsing `Atom' char by char.

 -- PREDICATE: string2term/2:
     *Usage:* `string2term(+String, -Term)'
        - _Description:_ Same as `atom2term/2' but first argument is
          a string (containing a term).

 -- PREDICATE: parse_term/3:
     *Usage:* `parse_term(+String, -Term, ?Dummy)'
        - _Description:_ `String' is parsed into `Term' upto `Dummy'
          (which is the non-parsed rest of the list).

65.3 Known bugs and planned improvements (`atom2term')
======================================================

   * This is just a quick hack written mainly for parsing daVinci's
     messages. There should be a call to the standard reader to do
     this!

66 ctrlcclean (library)
***********************

*Version:* 0.4#5 (1998/2/24)

66.1 Usage and interface (`ctrlcclean')
=======================================

   * *Library usage:*

     `:- use_module(library(ctrlcclean)).'

   * *Exports:*
        - _Predicates:_

          `ctrlc_clean/1', `delete_on_ctrlc/2', `ctrlcclean/0'.

   * *Other modules used:*
        - _System library modules:_

          `system'.

66.2 Documentation on exports (`ctrlcclean')
============================================

 -- PREDICATE: ctrlc_clean/1:
     No further documentation available for this predicate.

     _Meta-predicate_ with arguments: `ctrlc_clean(goal)'.

 -- PREDICATE: delete_on_ctrlc/2:
     No further documentation available for this predicate.

 -- PREDICATE: ctrlcclean/0:
     No further documentation available for this predicate.

67 errhandle (library)
**********************

*Version:* 0.4#5 (1998/2/24)

67.1 Usage and interface (`errhandle')
======================================

   * *Library usage:*

     `:- use_module(library(errhandle)).'

   * *Exports:*
        - _Predicates:_

          `error_protect/1', `handle_error/2'.

67.2 Documentation on exports (`errhandle')
===========================================

 -- PREDICATE: error_protect/1:
     No further documentation available for this predicate.

     _Meta-predicate_ with arguments: `error_protect(goal)'.

 -- PREDICATE: handle_error/2:
     No further documentation available for this predicate.

68 Fast reading and writing of terms
************************************

*Author(s):* Daniel Cabeza, Oscar Portela Arjona.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.7#16 (2000/8/29, 13:44:18 CEST)

   This library provides predicates to support reading / writing of
terms on a format designed to be handled on read faster than standard
representation.

68.1 Usage and interface (`fastrw')
===================================

   * *Library usage:*

     `:- use_module(library(fastrw)).'

   * *Exports:*
        - _Predicates:_

          `fast_read/1', `fast_write/1', `fast_read/2', `fast_write/2', `fast_write_to_string/3'.

   * *Other modules used:*
        - _System library modules:_

          `dict'.

68.2 Documentation on exports (`fastrw')
========================================

 -- PREDICATE: fast_read/1:
     `fast_read(Term)'

     The next term is read from current standard input and is unified
     with `Term'. The syntax of the term must agree with fast_read /
     fast_write format. If the end of the input has been reached,
     `Term' is unified with the term 'end_of_file'. Further calls to `fast_read/1'
     will then cause an error.

 -- PREDICATE: fast_write/1:
     `fast_write(Term)'

     Output `Term' in a way that `fast_read/1' and `fast_read/2' will
     be able to read it back.

 -- PREDICATE: fast_read/2:
     `fast_read(Stream, Term)'

     The next term is read from `Stream' and unified with `Term'. The
     syntax of the term must agree with fast_read / fast_write
     format. If the end of the input has been reached, `Term' is
     unified with the term 'end_of_file'. Further calls to `fast_read/2'
     will then cause an error.

 -- PREDICATE: fast_write/2:
     `fast_write(Stream, Term)'

     Output `Term' to `Stream' in a way that `fast_read/1' and `fast_read/2'
     will be able to read it back.

 -- PREDICATE: fast_write_to_string/3:
     No further documentation available for this predicate.

68.3 Known bugs and planned improvements (`fastrw')
===================================================

   * Both `fast_read/2' and `fast_write/2' simply set the current
     output/input and call `fast_read/1' and `fast_write/1'.
     Therefore, in the event an error hapens during its execution,
     the current input / output streams may be left pointing to the
     `Stream'

69 File name manipulation
*************************

*Author(s):* Daniel Cabeza, Angel Fernandez Pineda.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.3#51 (1999/9/9, 16:28:44 MEST)

   This library provides some small utilities to handle file name
syntax.

69.1 Usage and interface (`filenames')
======================================

   * *Library usage:*

     `:- use_module(library(filenames)).'

   * *Exports:*
        - _Predicates:_

          `no_path_file_name/2', `file_name_extension/3', `basename/2', `extension/2'.

   * *Other modules used:*
        - _System library modules:_

          `lists'.

69.2 Documentation on exports (`filenames')
===========================================

 -- PREDICATE: no_path_file_name/2:
     This predicate will extract the last item (usually the file
     name) from a given path.

     The first argument must be instantiated to a string or atom.
     Whenever the first argument is an atom, the second argument will
     be an atom. Whenever the first argument is a string, the second
     argument will be a string.

     This predicate will fail under any of the following conditions:
        * First argument is not an atom, nor a string.

        * Second argument is not the last given path item (given path
          is the first argument).

     Those are the most usual usages of no_path_file_name/2:
          ?- no_path_file_name_("/home/nexusV/somefile.txt",K).

          K = "somefile.txt" ?

          yes
          ?- no_path_file_name('/home/nexusV/somefile.txt',K).

          K = 'somefile.txt' ?

          yes
          ?-

     *Usage:* `no_path_file_name(Path, FileName)'
        - _Description:_ `FileName' is the file corresponding to the
          given `Path'.

        - _Call and exit should be _compatible_ with:_

          `Path' is an atom or a string  (`filenames:atom_or_str/1')

          `FileName' is an atom or a string
          (`filenames:atom_or_str/1')

 -- PREDICATE: file_name_extension/3:
     This predicate may be used in two ways:
        * To create a file name from its components: name and
          extension. For instance:

               ?- file_name_extension(File,mywork,'.txt').

               File = 'mywork.txt' ?

               yes
               ?-

        * To split a file name into its name and extension. For
          Instance:
               ?- file_name_extension('mywork.txt',A,B).

               A = mywork,
               B = '.txt' ?

               yes
               ?-

     Any other usage of file_name_extension/3 will cause the
     predicate to fail. Notice that valid arguments are accepted both
     as atoms or strings.

     *Usage:* `file_name_extension(FileName, BaseName, Extension)'
        - _Description:_ Splits a `FileName' into its `BaseName' and
          `Extension'.

        - _Call and exit should be _compatible_ with:_

          `FileName' is an atom or a string
          (`filenames:atom_or_str/1')

          `BaseName' is an atom or a string
          (`filenames:atom_or_str/1')

          `Extension' is an atom or a string
          (`filenames:atom_or_str/1')

 -- PREDICATE: basename/2:
     `basename(FileName, BaseName)'

     `BaseName' is `FileName' without extension. Equivalent to
     `file_name_extension(FileName,BaseName,_)'. Useful to extract
     the base name of a file using functional syntax.

     *Usage:*
        - _Calls should, and exit will be compatible with:_

          `FileName' is an atom or a string
          (`filenames:atom_or_str/1')

          `BaseName' is an atom or a string
          (`filenames:atom_or_str/1')

 -- PREDICATE: extension/2:
     `extension(FileName, Extension)'

     `Extension' is the extension (suffix) of `FileName'. Equivalent
     to `file_name_extension(FileName,_,Extension)'. Useful to
     extract the extension of a file using functional syntax.

     *Usage:*
        - _Calls should, and exit will be compatible with:_

          `FileName' is an atom or a string
          (`filenames:atom_or_str/1')

          `Extension' is an atom or a string
          (`filenames:atom_or_str/1')

70 Symbolic filenames
*********************

*Author(s):* Francisco Bueno.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#9 (2002/5/28, 19:11:29 CEST)

   This module provides a predicate for file opening which can use
any term as an alias for the filename (i.e., symbolic filenames)
instead of the usual constants which are file system path names of
the actual files.

   The correspondence between an alias and the actual file path is
done dynamically, without having to recompile the program. It is
possible to define the correspondence via facts for `file_alias/2' in
a file declared with `multifile:alias_file/1' in the program: those
facts will be dynamically loaded when running the program.
Alternatively, the correspondence can be defined via shell
environment variables, by defining the value of a variable by the
(symbolic) name of the file to be the path of the actual file.

70.1 Usage and interface (`symfnames')
======================================

   * *Library usage:*

     `:- use_module(library(symfnames)).'

   * *Exports:*
        - _Predicates:_

          `open/3'.

        - _Multifiles:_

          `alias_file/1', `file_alias/2'.

   * *Other modules used:*
        - _System library modules:_

          `read', `system'.

70.2 Documentation on exports (`symfnames')
===========================================

 -- PREDICATE: open/3:
     `open(File, Mode, Stream)'

     Open `File' with mode `Mode' and return in `Stream' the stream
     associated with the file. It is like `streams_basic:open/3', but
     `File' is considered a symbolic name: either defined by `user:file_alias/2'
     or as an environment variable. Predicate `user:file_alias/2' is
     inspected before the environment variables.

70.3 Documentation on multifiles (`symfnames')
==============================================

 -- PREDICATE: alias_file/1:
     `alias_file(File)'

     Declares `File' to be a file defining symbolic names via `file_alias/2'.
     Anything else in `File' is simply ignored.

     The predicate is _multifile_.

 -- PREDICATE: file_alias/2:
     `file_alias(Alias, File)'

     Declares `Alias' as a symbolic name for `File', the real name of
     an actual file (or directory).

     The predicate is _multifile_.

     The predicate is of type _data_.

70.4 Other information (`symfnames')
====================================

The example discussed here is included in the distribution files.
There is a main application file which uses module `mm'. This module
reads a line from a file; the main predicate in the main file then
prints this line. The important thing is that the file read is named
by a symbolic name "`file'". The main application file declares
another file where the symbolic names are assigned actual file names:

     :- use_module(mm).

     :- multifile alias_file/1.
     alias_file(myfiles).

     main :- p(X), display(X), nl.

   Now, the file `myfiles.pl' can be used to change the file you want
to read from without having to recompile the application. The current
assignment is:

     %:- use_package([]).
     file_alias(file,'mm.pl').

so the execution of the application will show the first line of
`mm.pl'. However, you can change to:

     file_alias(file,'main.pl').

and then execution of the same executable will show the first line of
`main.pl'.

71 File I/O utilities
*********************

*Author(s):* The CLIP Group.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#216 (2003/12/21, 2:30:59 CET)

   This module implements the file I/O utilities.

71.1 Usage and interface (`file_utils')
=======================================

   * *Library usage:*

     `:- use_module(library(file_utils)).'

   * *Exports:*
        - _Predicates:_

          `file_terms/2', `copy_stdout/1', `file_to_string/2', `stream_to_string/2'.

   * *Other modules used:*
        - _System library modules:_

          `read', `streams'.

71.2 Documentation on exports (`file_utils')
============================================

 -- PREDICATE: file_terms/2:
     *Usage 1:* `file_terms(@File, ?Terms)'
        - _Description:_ Transform a file `File' to/from a list of
          terms `Terms'.

        - _The following properties should hold upon exit:_

          `@File' is a source name.   (`streams_basic:sourcename/1')

          `?Terms' is a list.   (`basic_props:list/1')

     *Usage 2:* `file_terms(File, Terms)'
        - _Description:_ Unifies `Terms' with the list of all terms
          in `File'.

        - _The following properties should hold at call time:_

          `File' is a source name.   (`streams_basic:sourcename/1')

          `Terms' is a free variable.   (`term_typing:var/1')

        - _The following properties should hold upon exit:_

          `File' is a source name.   (`streams_basic:sourcename/1')

          `Terms' is a list.   (`basic_props:list/1')

     *Usage 3:* `file_terms(File, Terms)'
        - _Description:_ Writes the terms in list `Terms' (including
          the ending '.') onto file `File'.

        - _The following properties should hold at call time:_

          `File' is a source name.   (`streams_basic:sourcename/1')

          `Terms' is a list.   (`basic_props:list/1')

        - _The following properties should hold upon exit:_

          `File' is a source name.   (`streams_basic:sourcename/1')

          `Terms' is a list.   (`basic_props:list/1')

 -- PREDICATE: copy_stdout/1:
     *Usage:* `copy_stdout(+File)'
        - _Description:_ Copies file `File' to standard output.

        - _The following properties should hold upon exit:_

          `+File' is a source name.   (`streams_basic:sourcename/1')

 -- PREDICATE: file_to_string/2:
     *Usage:* `file_to_string(+FileName, -String)'
        - _Description:_ Reads all the characters from the file
          `FileName' and returns them in `String'.

        - _Call and exit should be _compatible_ with:_

          `+FileName' is a source name.
          (`streams_basic:sourcename/1')

          `-String' is a string (a list of character codes).
          (`basic_props:string/1')

 -- PREDICATE: stream_to_string/2:
     *Usage:* `stream_to_string(+Stream, -String)'
        - _Description:_ Reads all the characters from `Stream' and
          returns them in `String'.

        - _Call and exit should be _compatible_ with:_

          `+Stream' is an open stream.   (`streams_basic:stream/1')

          `-String' is a string (a list of character codes).
          (`basic_props:string/1')

72 File locks
*************

*Author(s):* J. Gomez, D. Cabeza, M. Carro.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.7#159 (2001/11/27, 11:58:24 CET)

   This module implements file locks: the ability to lock a fiel so
that other processes cannot access it until the file is unlocked. *It
is, however, not working.* The predicates do nothing. Proper
implementation is planned for a near future.

72.1 Usage and interface (`file_locks')
=======================================

   * *Library usage:*

     `:- use_module(library(file_locks)).'

   * *Exports:*
        - _Predicates:_

          `lock_file/3', `unlock_file/2'.

72.2 Documentation on exports (`file_locks')
============================================

 -- PREDICATE: lock_file/3:
     *Usage:* `lock_file(File, LockType, Result)'
        - _Description:_ Tries to lock `File' with `LockType' and
          returns the result (either `true' or `false') in `Result'.

        - _The following properties should hold at call time:_

          `File' is an atom.   (`basic_props:atm/1')

          `LockType' is an atom.   (`basic_props:atm/1')

          `Result' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: unlock_file/2:
     *Usage:* `unlock_file(File, Result)'
        - _Description:_ Tries to unlock `File' the result (either
          `true' or `false') in `Result'.

        - _The following properties should hold at call time:_

          `File' is an atom.   (`basic_props:atm/1')

          `Result' is an atom.   (`basic_props:atm/1')

72.3 Known bugs and planned improvements (`file_locks')
=======================================================

   * No doing anything helpful.

73 Term manipulation utilities
******************************

*Author(s):* The CLIP Group.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#218 (2003/12/21, 18:44:51 CET)

   This module implements some utils to do term manipulation.

73.1 Usage and interface (`terms')
==================================

   * *Library usage:*

     `:- use_module(library(terms)).'

   * *Exports:*
        - _Predicates:_

          `copy_args/3', `arg/2', `atom_concat/2'.

73.2 Documentation on exports (`terms')
=======================================

 -- PREDICATE: copy_args/3:
     *Usage:* `copy_args(N, Term, Copy)'
        - _Description:_ `Term' and `Copy' have the same first `N'
          arguments.

        - _The following properties should hold at call time:_

          `N' is a non-negative integer.   (`basic_props:nnegint/1')

 -- PREDICATE: arg/2:
     *Usage:* `arg(Term, Arg)'
        - _Description:_ `Arg' is an argument of `Term'. Gives each
          of the arguments on backtracking.

 -- PREDICATE: atom_concat/2:
     `atom_concat(Atms, Atm)'

     `Atm' is the atom resulting from concatenating all atoms in the
     list `Atms' in the order in which they appear.

74 Term checking utilities
**************************

*Author(s):* The CLIP Group.

   *Version:* 1.9#219 (2003/12/21, 18:51:46 CET)

   This module implements the term checking utilities.

74.1 Usage and interface (`terms_check')
========================================

   * *Library usage:*

     `:- use_module(library(terms_check)).'

   * *Exports:*
        - _Predicates:_

          `ask/2', `variant/2', `most_general_instance/3', `most_specific_generalization/3'.

        - _Properties:_

          `instance/2'.

74.2 Documentation on exports (`terms_check')
=============================================

 -- PREDICATE: ask/2:
     `ask(Term1, Term2)'

     `Term1' and `Term2' unify without producing bindings for the
     variables of `Term1'. I.e., `instance(`Term1',`Term2')' holds.

 -- PROPERTY: instance/2:
     `instance(Term1, Term2)'

     `Term1' is an instance of `Term2'.

     *Usage:* `instance(A, B)'
        - _The following properties hold globally:_

          This predicate is understood natively by CiaoPP.
          (`basic_props:native/1')

 -- PREDICATE: variant/2:
     `variant(Term1, Term2)'

     `Term1' and `Term2' are identical up to renaming.

 -- PREDICATE: most_general_instance/3:
     `most_general_instance(Term1, Term2, Term)'

     `Term' satisfies `instance(`Term',`Term1')' and
     `instance(`Term',`Term2')' and there is no term more general
     than `Term' (modulo variants) that satisfies it.

 -- PREDICATE: most_specific_generalization/3:
     `most_specific_generalization(Term1, Term2, Term)'

     `Term' satisfies `instance(`Term1',`Term')' and
     `instance(`Term2',`Term')' and there is no term less general
     than `Term' (modulo variants) that satisfies it.

74.3 Other information (`terms_check')
======================================

Currently, `ask/2' and `instance/2' are exactly the same. However,
`ask/2' is more general, since it is also applicable to constraint
domains (although not yet implemented): for the particular case of
Herbrand terms, it is just `instance/2' (which is the only ask check
currently implemented).

75 Sets of variables in terms
*****************************

*Author(s):* The CLIP Group.

   *Version:* 1.9#220 (2003/12/21, 18:58:25 CET)

   This module implements predicates to handle sets of variables in
terms.

75.1 Usage and interface (`terms_vars')
=======================================

   * *Library usage:*

     `:- use_module(library(terms_vars)).'

   * *Exports:*
        - _Predicates:_

          `varset/2', `varsbag/3', `varset_in_args/2'.

   * *Other modules used:*
        - _System library modules:_

          `idlists', `sort'.

75.2 Documentation on exports (`terms_vars')
============================================

 -- PREDICATE: varset/2:
     `varset(Term, Xs)'

     `Xs' is the sorted list of all the variables in `Term'.

 -- PREDICATE: varsbag/3:
     `varsbag(Term, Vs, Xs)'

     `Vs' is the list of all the variables in `Term' ordered as they
     appear in `Term' right-to-left depth-first (including
     duplicates) plus `Xs'.

 -- PREDICATE: varset_in_args/2:
     *Usage:* `varset_in_args(T, LL)'
        - _Description:_ Each list of `LL' contains the variables of
          an argument of `T', for each argument, and in left to right
          order.

        - _The following properties should hold at call time:_

          `T' is currently a term which is not a free variable.
          (`term_typing:nonvar/1')

        - _The following properties should hold upon exit:_

          `LL' is a list of `list(var)'s.   (`basic_props:list/2')

76 A simple pretty-printer for Ciao programs
********************************************

*Author(s):* The CLIP Group.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#248 (2003/12/30, 21:52:0 CET)

   This library module writes out to standard output a clause or a
list of clauses.

76.1 Usage and interface (`pretty_print')
=========================================

   * *Library usage:*

     `:- use_module(library(pretty_print)).'

   * *Exports:*
        - _Predicates:_

          `pretty_print/2', `pretty_print/3'.

   * *Other modules used:*
        - _System library modules:_

          `operators', `vndict', `write'.

76.2 Documentation on exports (`pretty_print')
==============================================

 -- PREDICATE: pretty_print/2:
     *Usage:* `pretty_print(Cls, Flags)'
        - _Description:_ Prints each clause in the list `Cls' after
          numbering its variables.

        - _The following properties should hold at call time:_

          `pretty_print:clauses(Cls)'  (`pretty_print:clauses/1')

          `Flags' is a list of `flag's.   (`basic_props:list/2')

 -- PREDICATE: pretty_print/3:
     *Usage:* `pretty_print(Cls, Flags, Ds)'
        - _Description:_ Prints each clause in the list `Cls' after
          using the corresponding variable names dictionary in `Ds'
          to name its variables.

        - _The following properties should hold at call time:_

          `pretty_print:clauses(Cls)'  (`pretty_print:clauses/1')

          `Flags' is a list of `flag's.   (`basic_props:list/2')

          `Ds' is a dictionary of variable names.
          (`vndict:varnamedict/1')

76.3 Documentation on internals (`pretty_print')
================================================

 -- REGTYPE: clauses/1:
     A regular type, defined as follows:
               clauses([]).
               clauses([_1|_2]) :-
                       clause(_1),
                       clauses(_2).
               clauses(_1) :-
                       clause(_1).

 -- REGTYPE: clause/1:
     A regular type, defined as follows:
               clause(_1) :-
                       clterm(_1).
               clause((_1,_2)) :-
                       clterm(_1),
                       term(_2).

 -- REGTYPE: clterm/1:
     A regular type, defined as follows:
               clterm(clause(_1,_2)) :-
                       callable(_1),
                       body(_2).
               clterm(directive(_1)) :-
                       body(_1).
               clterm((_1:-_2)) :-
                       callable(_1),
                       body(_2).
               clterm(_1) :-
                       callable(_1).

 -- REGTYPE: body/1:
     A well formed body, including cge expressions and &-concurrent
     expressions. The atomic goals may or may not have a key in the
     form `^(goal:any)', and may or may not be module qualified, but
     if they are it has to be in the form `^(^(moddesc:goal):any)'.

     *Usage:* `body(X)'
        - _Description:_ `X' is a printable body.

 -- REGTYPE: flag/1:
     A keyword `ask/1' flags whether to output _asks_ or _whens_ and
     `nl/1' whether to separate clauses with a blank line or not.

     *Usage:* `flag(X)'
        - _Description:_ `X' is a flag for the pretty-printer.

77 Pretty-printing assertions
*****************************

*Author(s):* Francisco Bueno Carrillo.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#320 (2004/3/3, 18:29:59 CET)

   This module defines some predicates which are useful for writing
assertions in a readable form.

77.1 Usage and interface (`assrt_write')
========================================

   * *Library usage:*

     `:- use_module(library(assrt_write)).'

   * *Exports:*
        - _Predicates:_

          `write_assertion/6', `write_assertion_as_comment/6'.

   * *Other modules used:*
        - _System library modules:_

          `format', `assertions/assrt_lib', `messages', `assertions/assertions_props'.

77.2 Documentation on exports (`assrt_write')
=============================================

 -- PREDICATE: write_assertion/6:
     *Usage:* `write_assertion(Goal, Status, Type, Body, Dict, Flag)'
        - _Description:_ Writes the (normalized) assertion to current
          output.

        - _Call and exit should be _compatible_ with:_

          `Status' is an acceptable status for an assertion.
          (`assertions_props:assrt_status/1')

          `Type' is an admissible kind of assertion.
          (`assertions_props:assrt_type/1')

          `Body' is a normalized assertion body.
          (`assertions_props:nabody/1')

          `Dict' is a dictionary of variable names.
          (`assertions_props:dictionary/1')

          `Flag' is `status' or `nostatus'.
          (`assrt_write:status_flag/1')

 -- PREDICATE: write_assertion_as_comment/6:
     *Usage:* `write_assertion_as_comment(Goal, Status, Type, Body,
     Dict, Flag)'
        - _Description:_ Writes the (normalized) assertion to current
          output as a Prolog comment.

        - _Call and exit should be _compatible_ with:_

          `Status' is an acceptable status for an assertion.
          (`assertions_props:assrt_status/1')

          `Type' is an admissible kind of assertion.
          (`assertions_props:assrt_type/1')

          `Body' is a normalized assertion body.
          (`assertions_props:nabody/1')

          `Dict' is a dictionary of variable names.
          (`assertions_props:dictionary/1')

          `Flag' is `status' or `nostatus'.
          (`assrt_write:status_flag/1')

78 The Ciao library browser
***************************

*Author(s):* Angel Fernandez Pineda.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.7#21 (2000/9/26, 13:37:17 CEST)

   `librowser' library provides a set of predicates wich enables the
user to interactively find Ciao/Prolog libraries and/or any predicate
exported by them.

   This is a simple example:

     ?- apropos('*find*').
     persdbrt_sql: dbfindall/4
     persdbrtsql: dbfindall/4
     conc_aggregates: findall/3
     linda: rd_findall/3
     vndict: find_name/4
     internals: $find_file/8
     aggregates: findall/4,findall/3

     yes
     ?-

   Librowser is specially usefull when using inside GNU Emacs, just
place the cursor over a librowser response and press C-cTAB in order
to get help on the related predicate. Refer to the *"Using Ciao
inside GNU Emacs"* chapter for further information.

78.1 Usage and interface (`librowser')
======================================

   * *Library usage:*

     It is not necesary to use this library at user programs. It was
     designed to be used at the Ciao _toplevel_ shell: `ciaosh'. In
     order to do so, just make use of `use_module/1' as follows:

     `use_module(library(librowser))'.

     Then, the library interface must be read. This is automatically
     done when calling any predicate at librowser, and the entire
     process will take a little moment.So, you should want to perform
     such a process after loading the Ciao toplevel:

          Ciao 0.9 #75: Fri Apr 30 19:04:24 MEST 1999
          ?- use_module(library(librowser)).

          yes
          ?- update.

     Whether you want this process to be automatically performed when
     loading `ciaosh', you may include those lines in your _.ciaorc_
     personal initialization file.

   * *Exports:*
        - _Predicates:_

          `update/0', `browse/2', `where/1', `describe/1', `system_lib/1', `apropos/1'.

   * *Other modules used:*
        - _System library modules:_

          `filenames', `read', `fastrw', `system', `streams', `patterns', `lists'.

78.2 Documentation on exports (`librowser')
===========================================

 -- PREDICATE: update/0:
     This predicate will scan the Ciao system libraries for predicate
     definitions. This may be done once time before calling any other
     predicate at this library.

     update/0 will also be automatically called (once) when calling
     any other predicate at librowser.

     *Usage:*
        - _Description:_ Creates an internal database of modules at
          Ciao system libraries.

 -- PREDICATE: browse/2:
     This predicate is fully reversible, and is provided to inspect
     concrete predicate specifications. For example:
          ?- browse(M,findall/A).

          A = 3,
          M = conc_aggregates ? ;

          A = 4,
          M = aggregates ? ;

          A = 3,
          M = aggregates ? ;

          no
          ?-

     *Usage:* `browse(Module, Spec)'
        - _Description:_ Asocciates the given `Spec' predicate
          specification with the `Module' which exports it.

        - _The following properties should hold at call time:_

          `Module' is a module name (an atom)
          (`librowser:module_name/1')

          `Spec' is a *Functor/Arity* predicate specification
          (`librowser:pred_spec/1')

 -- PREDICATE: where/1:
     This predicate will print at the screen the module needed in
     order to import a given predicate specification. For example:
          ?- where(findall/A).
          findall/3 exported at module conc_aggregates
          findall/4 exported at module aggregates
          findall/3 exported at module aggregates

          yes
          ?-

     *Usage:* `where(Spec)'
        - _Description:_ Display what module to load in order to
          import the given `Spec'.

        - _The following properties should hold at call time:_

          `Spec' is a *Functor/Arity* predicate specification
          (`librowser:pred_spec/1')

 -- PREDICATE: describe/1:
     This one is used to find out which predicates were exported by a
     given module. Very usefull when you know the library, but not
     the concrete predicate. For example:
          ?- describe(librowser).
          Predicates at library librowser :

          apropos/1
          system_lib/1
          describe/1
          where/1
          browse/2
          update/0

          yes
          ?-

     *Usage:* `describe(Module)'
        - _Description:_ Display a list of exported predicates at the
          given `Module'

        - _The following properties should hold at call time:_

          `Module' is a module name (an atom)
          (`librowser:module_name/1')

 -- PREDICATE: system_lib/1:
     It retrieves on backtracking all Ciao system libraries stored in
     the internal database. Certainly, those which were scanned at `update/0'
     calling.

     *Usage:* `system_lib(Module)'
        - _Description:_ `Module' variable will be successively
          instantiated to the system libaries stored in the internal
          database.

        - _The following properties should hold at call time:_

          `Module' is a module name (an atom)
          (`librowser:module_name/1')

 -- PREDICATE: apropos/1:
     This tool makes use of regular expresions in order to find
     predicate specifications. It is very usefull whether you can't
     remember the full name of a predicate. Regular expresions take
     the same format as described in library `patterns'. Example:
          ?- apropos('atom_*').

          terms: atom_concat/2
          concurrency: atom_lock_state/2
          atomic_basic: atom_concat/3,atom_length/2,atom_codes/2
          iso_byte_char: atom_chars/2

          yes
          ?-

     *Usage:* `apropos(RegSpec)'
        - _Description:_ This will search any predicate specification
          `Spec' which matches the given `RegSpec' incomplete
          predicate specification.

        - _The following properties should hold at call time:_

          `RegSpec' is a Pattern/Arity specification.
          (`librowser:apropos_spec/1')

78.3 Documentation on internals (`librowser')
=============================================

 -- REGTYPE: apropos_spec/1:
     Defined as:
          apropos_spec(_1).
          apropos_spec(Pattern/Arity) :-
                  pattern(Pattern),
                  int(Arity).

     *Usage:* `apropos_spec(S)'
        - _Description:_ `S' is a Pattern/Arity specification.

79 Code translation utilities
*****************************

*Author(s):* Angel Fernandez Pineda.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.7#40 (2001/1/5, 19:7:40 CET)

   This library offers a general way to perform clause body
expansions. Goal, fact and spec translation predicates are
authomatically called when needed, while this utility navigates
through the meta-argument specification of the body itself. All
predicates within this library must be called at _second-pass
expansions_, since it uses information stored at `c_itf' library.

79.1 Usage and interface (`expansion_tools')
============================================

   * *Library usage:*

     This library is provided as a tool for those modules which
     performs source-to-source code translation, usually known as
     _code expanders_. It may be loaded as other modules using a `use_module/1'.
     Nothing special needs to be done.

   * *Exports:*
        - _Predicates:_

          `imports_meta_pred/3', `body_expander/6', `arg_expander/6'.

   * *Other modules used:*
        - _System library modules:_

          `compiler/c_itf'.

79.2 Documentation on exports (`expansion_tools')
=================================================

 -- PREDICATE: imports_meta_pred/3:
     Macro provided in order to know meta-predicate specifications
     accessible from a module.

     *Usage:* `imports_meta_pred(Module, MetaSpec, AccessibleAt)'
        - _Description:_ Tells whether `MetaSpec' meta-predicate
          specification is accessible from `Module'. `AccessibleAt'
          will be binded to '-' whether meta-predicate is a builtin
          one. If not, it will be unified with the module which
          defines the meta-predicate.

        - _The following properties should hold at call time:_

          `Module' is an atom.   (`basic_props:atm/1')

          `MetaSpec' is any term.   (`basic_props:term/1')

          `AccessibleAt' is a free variable.   (`term_typing:var/1')

 -- PREDICATE: body_expander/6:
     This predicate is the main translation tool. It navigates
     through a clause body, when a single _goal_ appears, user-code
     is called in order to perform a translation. Whether user-code
     fails to translate the involved goal, it remains the same.
     Regardless that goal is translated or not, an argument expansion
     will be performed over all goals if applicable (see `arg_expander/6'
     predicate).

     Variable (unknown at compile time) goals will also be attempt to
     translate.

     _Meta-predicate_ with arguments:
     `body_expander(pred(3),pred(3),pred(3),?,?,?)'.

     *Usage:* `body_expander(GoalTrans, FactTrans, SpecTrans, Module,
     Body, ExpandedBody)'
        - _Description:_ Translates `Body' to `ExpandedBody' by the
          usage of user-defined translators `GoalTrans', `FactTrans'
          and `SpecTrans'. The module where the original body appears
          must be unified with `Module' argument.

        - _The following properties should hold at call time:_

          `GoalTrans' is a user-defined predicate which performs
          _goal_ meta-type translation
          (`expansion_tools:goal_expander/1')

          `FactTrans' is a user-defined predicate which performs
          _fact_ meta-type translation
          (`expansion_tools:fact_expander/1')

          `SpecTrans' is a user-defined predicate which performs
          _spec_ meta-type translation
          (`expansion_tools:spec_expander/1')

          `Module' is an atom.   (`basic_props:atm/1')

          `Body' is currently a term which is not a free variable.
          (`term_typing:nonvar/1')

          `ExpandedBody' is a free variable.   (`term_typing:var/1')

 -- PREDICATE: arg_expander/6:
     This predicate is an auxiliary translation tool, which is used by `body_expander/6'
     predicate. It remains exported as a macro. The predicate
     navigates through the _meta-argument specification_ of a goal.
     Whether a _goal,fact or spec_ argument appears, user-code is
     called in order to perform a translation. Whether user-code
     fails to translate the involved argument, it remains the same.
     Builtins as ','/2 or ';'/2 are treated as meta-predicates
     defining _goal_ meta-arguments. When a _goal_ meta-argument is
     located, `body_expander/6' will be called in order to navigate
     through it. Notice that a _goal_ meta-argument may be unified
     with another goal defining another meta-argument, so navigation
     is required. If arguments are not known to arg_expander/6,
     translation will not occur. This is posible whether goal or
     qualifing module are variables.

     _Meta-predicate_ with arguments:
     `arg_expander(pred(3),pred(3),pred(3),?,?,?)'.

     *Usage:* `arg_expander(GoalTrans, FactTrans, SpecTrans, Module,
     Goal, ExpandedGoal)'
        - _Description:_ Translates `Goal' to `ExpandedGoal' by
          applying user-defined translators (`GoalTrans', `FactTrans'
          and `SpecTrans') to each meta-argument present at such
          goal. The module where the original goal appears must be
          unified with `Module' argument.

        - _The following properties should hold at call time:_

          `GoalTrans' is a user-defined predicate which performs
          _goal_ meta-type translation
          (`expansion_tools:goal_expander/1')

          `FactTrans' is a user-defined predicate which performs
          _fact_ meta-type translation
          (`expansion_tools:fact_expander/1')

          `SpecTrans' is a user-defined predicate which performs
          _spec_ meta-type translation
          (`expansion_tools:spec_expander/1')

          `Module' is an atom.   (`basic_props:atm/1')

          `Goal' is currently a term which is not a free variable.
          (`term_typing:nonvar/1')

          `ExpandedBody' is a free variable.   (`term_typing:var/1')

79.3 Documentation on internals (`expansion_tools')
===================================================

 -- PROPERTY: expander_pred/1:
     *Usage:* `expander_pred(Pred)'
        - _Description:_ `Pred' is a user-defined predicate used to
          perform code translations. First argument will be binded to
          the corresponding term to be translated. Second argument
          must be binded to the corresponding translation. Third
          argument will be binded to the current module were first
          argument appears. Additional arguments will be user-defined.

79.4 Known bugs and planned improvements (`expansion_tools')
============================================================

   * _pred(N)_ meta-arguments are not supported at this moment.

80 Low-level concurrency/multithreading primitives
**************************************************

*Author(s):* Manuel Carro.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.7#138 (2001/11/8, 19:50:32 CET)

   This module provides basic mechanisms for using concurrency and
implementing multi-goal applications.  It provides a means for
arbitrary goals to be specified to be run in a separate stack set; in
that case, they are assigned a goal identifier with which further
accesses (e.g., asking for more solutions) to the goal can be made.
Additionally, in some architectures, these goals can be assigned an
O.S. thread, separate from the one which made the initial call, thus
providing concurrency and, in multiprocessors, parallelism
capabilities.

   As for now, the memory space of the threads (c.f., stack sets) is
separate in the sense that goals are copied to the new stack set, and
bindings of variables are not seen among stack sets which allows
forward and backward execution to proceed independently in each stack
set, at the cost of the initial goal copy. However, the program space
(including, specially, the concurrent predicates) are shared and seen
by all the goals and threads, and should be used as the primary means
of communication and synchronization. Higer level libraries can be
built using these basic blocks.

   Additionally, a small set of lock primitives are provided. Locks
are associated with atom names. Whereas the concurrent database
facilities are enough to implement locks, semaphores, messages, etc.,
the predicates implementing atom-based locks are faster than the ones
accessing the concurrent database (but they are less powerful).

80.1 Usage and interface (`concurrency')
========================================

   * *Library usage:*

     `:- use_module(library(concurrency)).'

   * *Exports:*
        - _Predicates:_

          `eng_call/4', `eng_call/3', `eng_backtrack/2', `eng_cut/1', `eng_release/1', `eng_wait/1', `eng_kill/1', `eng_killothers/0', `eng_self/1', `goal_id/1', `eng_goal_id/1', `eng_status/0', `lock_atom/1', `unlock_atom/1', `atom_lock_state/2', `concurrent/1'.

   * *Other modules used:*
        - _System library modules:_

          `prolog_sys'.

80.2 Documentation on exports (`concurrency')
=============================================

 -- PREDICATE: eng_call/4:
     _Meta-predicate_ with arguments: `eng_call(goal,?,?,?)'.

     *Usage:* `eng_call(+Goal, +EngineCreation, +ThreadCreation,
     -GoalId)'
        - _Description:_ Calls `Goal' in a new engine (stack set),
          possibly using a new thread, and returns a `GoalId' to
          designate this new goal henceforth. `EngineCreation' can be
          either `wait' or `create'; the distinction is not yet
          meaningful. `ThreadCreation' can be one of `self', `wait',
          or `create'. In the first case the creating thread is used
          to execute `Goal', and thus it has to wait until its first
          result or failure. The call will fail if `Goal' fails, and
          succeed otherwise. However, the call will always suceed
          when a remote thread is started. The space and identifiers
          reclaimed for the thread must be explicitly deallocated by
          calling `eng_release/1'. `GoalId's are unique in each
          execution of a Ciao Prolog program.

        - _The following properties should hold at call time:_

          `+Goal' is a term which represents a goal, i.e., an atom or
          a structure.   (`basic_props:callable/1')

          `+EngineCreation' is an atom.   (`basic_props:atm/1')

          `+ThreadCreation' is an atom.   (`basic_props:atm/1')

          `-GoalId' is an integer.   (`basic_props:int/1')

 -- PREDICATE: eng_call/3:
     _Meta-predicate_ with arguments: `eng_call(goal,?,?)'.

     *Usage:* `eng_call(+Goal, +EngineCreation, +ThreadCreation)'
        - _Description:_ Similar to `eng_call/4', but the thread (if
          created) and stack areas are automatically released upon
          success or failure of the goal. No `GoalId' is provided for
          further interaction with the goal.

        - _The following properties should hold at call time:_

          `+Goal' is a term which represents a goal, i.e., an atom or
          a structure.   (`basic_props:callable/1')

          `+EngineCreation' is an atom.   (`basic_props:atm/1')

          `+ThreadCreation' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: eng_backtrack/2:
     *Usage:* `eng_backtrack(+GoalId, +ThreadCreation)'
        - _Description:_ Performs backtracking on the goal designed
          by `GoalId'. A new thread can be used to perform
          backtracking, according to `ThreadCreation' (same as in `eng_call/4').
          Fails if the goal is backtracked over by the local thread,
          and there are no more solutions. Always succeeds if
          executed by a remote thread. The engine is *not*
          automatically released up upon failure: `eng_release/1'
          must be called to that end.

        - _The following properties should hold at call time:_

          `+GoalId' is an integer.   (`basic_props:int/1')

          `+ThreadCreation' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: eng_cut/1:
     *Usage:* `eng_cut(+GoalId)'
        - _Description:_ Performs a _cut_ in the execution of the
          goal `GoalId'. The next call to `eng_backtrack/2' will
          therefore backtrack all the way and fail.

        - _The following properties should hold at call time:_

          `+GoalId' is an integer.   (`basic_props:int/1')

 -- PREDICATE: eng_release/1:
     *Usage:* `eng_release(+GoalId)'
        - _Description:_ Cleans up and releases the engine executing
          the goal designed by `GoalId'. The engine must be idle,
          i.e., currently not exedcuting any goal.  `eng_wait/1' can
          be used to ensure this.

        - _The following properties should hold at call time:_

          `+GoalId' is an integer.   (`basic_props:int/1')

 -- PREDICATE: eng_wait/1:
     *Usage:* `eng_wait(+GoalId)'
        - _Description:_ Waits for the engine executing the goal
          denoted by `GoalId' to finish the computation (i.e., it has
          finished searching for a solution, either with success or
          failure).

        - _The following properties should hold at call time:_

          `+GoalId' is an integer.   (`basic_props:int/1')

 -- PREDICATE: eng_kill/1:
     *Usage:* `eng_kill(+GoalId)'
        - _Description:_ Kills the thread executing `GoalId' (if
          any), and frees the memory used up by the stack set.
          Usually one should wait ( `eng_wait/1') for a goal, and
          then release it, but killing the thread explicitly allows
          recovering from error states. A goal cannot kill itself.
          This feature should be used with caution, because there are
          situations where killing a thread might render the system
          in an unstable state. Threads should cooperate in their
          killing, but if the killed thread is blocked in a I/O
          operation, or inside an internal critical region, this
          cooperation is not possible and the system, although
          stopped, might very well end up in a incosistent state.

        - _The following properties should hold at call time:_

          `+GoalId' is an integer.   (`basic_props:int/1')

 -- PREDICATE: eng_killothers/0:
     *Usage:*
        - _Description:_ Kills threads and releases stack sets of all
          active goals, but the one calling `eng_killothers'. Again,
          a safety measure. The same cautions as with `eng_kill/1'
          should be taken.

 -- PREDICATE: eng_self/1:
     *Usage:* `eng_self(?GoalId)'
        - _Description:_ `GoalId' is unified with the identifier of
          the goal within which `eng_self/1' is executed.  `eng_self/1'
          is deprecated, and eng_goal_id/1 should be used instead.

        - _The following properties should hold at call time:_

          `?GoalId' is an integer.   (`basic_props:int/1')

 -- PREDICATE: goal_id/1:
     *Usage:* `goal_id(?GoalId)'
        - _Description:_ `GoalId' is unified with the identifier of
          the goal within which `goal_id/1' is executed.  `goal_id/1'
          is deprecated, and eng_goal_id/1 should be used instead.

        - _The following properties should hold at call time:_

          `?GoalId' is an integer.   (`basic_props:int/1')

 -- PREDICATE: eng_goal_id/1:
     *Usage:* `eng_goal_id(?GoalId)'
        - _Description:_ `GoalId' is unified with the identifier of
          the goal within which `eng_goal_id/1' is executed.

        - _The following properties should hold at call time:_

          `?GoalId' is an integer.   (`basic_props:int/1')

 -- PREDICATE: eng_status/0:
     *Usage:*
        - _Description:_ Prints to standard output the current status
          of the stack sets.

 -- PREDICATE: lock_atom/1:
     *Usage:* `lock_atom(+Atom)'
        - _Description:_ The semaphore associated to `Atom' is
          accessed; if its value is nonzero, it is atomically
          decremented and the execution of this thread proceeds.
          Otherwise, the goal waits until a nonzero value is reached.
          The semaphore is then atomically decremented and the
          execution of this thread proceeds.

        - _The following properties should hold at call time:_

          `+Atom' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: unlock_atom/1:
     *Usage:* `unlock_atom(+Atom)'
        - _Description:_ The semaphore associated to `Atom' is
          atomically incremented.

        - _The following properties should hold at call time:_

          `+Atom' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: atom_lock_state/2:
     *Usage 1:* `atom_lock_state(+Atom, +Value)'
        - _Description:_ Sets the semaphore associated to `Atom' to
          `Value'. This is usually done at the beginning of the
          execution, but can be executed at any time. If not called,
          semaphore associated to atoms are by default inited to 1.
          It should be used with caution: arbitrary use can transform
          programs using locks in a mess of internal relations. The
          change of a semaphore value in a place other than the
          initialization stage of a program is *not* among the
          allowed operations as defined by Dijkstra [Dij65,BA82].

        - _The following properties should hold at call time:_

          `+Atom' is an atom.   (`basic_props:atm/1')

          `+Value' is an integer.   (`basic_props:int/1')

     *Usage 2:* `atom_lock_state(+Atom, -Value)'
        - _Description:_ Consults the `Value' of the semaphore
          associated to `Atom'. Use sparingly and mainly as a medium
          to check state correctness. Not among the operations on
          semaphore by Djikstra.

        - _The following properties should hold at call time:_

          `+Atom' is an atom.   (`basic_props:atm/1')

          `-Value' is an integer.   (`basic_props:int/1')

 -- PREDICATE: concurrent/1:
     `concurrent F/A'

     The predicate named `F' with arity `A' is made concurrent in the
     current module at runtime (useful for predicate names generated
     on-the-fly). This difficults a better compile-time analysis, but
     in turn offers more flexibility to applications. It is also
     faster for some applications: if several agents have to share
     data in a stuctured fashion (e.g., the generator knows and wants
     to restrict the data generated to a set of other threads), a
     possibility is to use the same concurrent fact and emply a field
     within the fact to distinguish the receiver/sender. This can
     cause many threads to access and wait on the same fact, which in
     turns can create contention problems. It is much better to
     create a new concurrent fact and to use that new name as a
     channel to communicate the different threads.  `concurrent/1'
     can either be given a predicate spec in the form `Name/Arity',
     with `Name' and `Arity' bound, or to give a value only to
     `Arity', and let the system choose a new, unused `Name' for the
     fact.

80.3 Known bugs and planned improvements (`concurrency')
========================================================

   * Available only for Windows 32 environments and for architectures
     implementing POSIX threads.

   * Some implementation of threads have a limit on the total number
     of threads that can be created by a process. Thread creation, in
     this case, just hangs. A better solution is planned for the
     future.

   * Creating many concurrent facts may fill up the atom table,
     causing Ciao Prolog to abort.

81 All solutions concurrent predicates
**************************************

*Author(s):* Concurrent-safe (and incomplete) version of the
aggregates predicates, based on the regular versions by Richard A.
O'Keefe and David H.D. Warren. Concurrency-safeness provided by
Manuel Carro..

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#221 (2003/12/21, 20:6:33 CET)

   This module implements thread-safe aggregation predicates. Its use
and results should be the same as those in the aggregates library,
but several goals can use them concurrently without the interference
and wrong results (due to implementation reasons) aggregates might
lead to. This particular implementation is completely based on the
one used in the aggregates library.

81.1 Usage and interface (`conc_aggregates')
============================================

   * *Library usage:*

     `:- use_module(library(conc_aggregates)).'

   * *Exports:*
        - _Predicates:_

          `findall/3'.

   * *Other modules used:*
        - _System library modules:_

          `prolog_sys'.

81.2 Documentation on exports (`conc_aggregates')
=================================================

 -- PREDICATE: findall/3:
     _Meta-predicate_ with arguments: `findall(?,goal,?)'.

     *Usage:* `findall(?Template, +Generator, ?List)' < * ISO * >
        - _Description:_ A special case of bagof, where all free
          variables in the `Generator' are taken to be existentially
          quantified. Safe in concurrent applications.

        - _The following properties should hold upon exit:_

          `Template' is any term.   (`basic_props:term/1')

          `Goal' is a term which represents a goal, i.e., an atom or
          a structure.   (`basic_props:callable/1')

          `Set' is a list.   (`basic_props:list/1')

81.3 Known bugs and planned improvements (`conc_aggregates')
============================================================

   * Thread-safe `setof/3' is not yet implemented.

   * Thread-safe `bagof/3' is not yet implemented.

82 The socket interface
***********************

*Author(s):* Manuel Carro, Daniel Cabeza.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.7#58 (2001/2/8, 11:46:41 CET)

   This module defines primitives to open sockets, send, and receive
data from them. This allows communicating with other processes, on
the same machine or across the Internet. The reader should also
consult standard bibliography on the topic for a proper use of these
primitives.

82.1 Usage and interface (`sockets')
====================================

   * *Library usage:*

     `:- use_module(library(sockets)).'

   * *Exports:*
        - _Predicates:_

          `connect_to_socket/3', `socket_recv/2', `hostname_address/2', `socket_shutdown/2', `socket_recv_code/3', `socket_send/2', `select_socket/5', `socket_accept/2', `bind_socket/3', `connect_to_socket_type/4'.

        - _Regular Types:_

          `socket_type/1', `shutdown_type/1'.

   * *Other modules used:*
        - _System library modules:_

          `sockets/sockets_c'.

82.2 Documentation on exports (`sockets')
=========================================

 -- PREDICATE: connect_to_socket/3:
     *Usage:* `connect_to_socket(+Host, +Port, -Stream)'
        - _Description:_ Calls `connect_to_socket_type/4' with
          SOCK_STREAM connection type. This is the connection type
          you want in order to use the `write/2' and `read/2'
          predicates (and other stream IO related predicates).

        - _Call and exit should be _compatible_ with:_

          `+Host' is an atom.   (`basic_props:atm/1')

          `+Port' is an integer.   (`basic_props:int/1')

          `-Stream' is an open stream.   (`streams_basic:stream/1')

 -- PREDICATE: socket_recv/2:
     *Usage:* `socket_recv(+Stream, ?String)'
        - _Description:_ As `socket_recv_code/3', but the return code
          is ignored.

        - _Call and exit should be _compatible_ with:_

          `+Stream' is an open stream.   (`streams_basic:stream/1')

          `?String' is a string (a list of character codes).
          (`basic_props:string/1')

 -- REGTYPE: socket_type/1:
     Defines the atoms which can be used to specify the socket type
     recognized by `connect_to_socket_type/4'. Defined as follows:
          socket_type(stream).
          socket_type(dgram).
          socket_type(raw).
          socket_type(seqpacket).
          socket_type(rdm).

     *Usage:* `socket_type(T)'
        - _Description:_ `T' is a valid socket type.

 -- REGTYPE: shutdown_type/1:
     *Usage:* `shutdown_type(T)'
        - _Description:_ `T' is a valid shutdown type.

 -- PREDICATE: hostname_address/2:
     *Usage:* `hostname_address(+Hostname, ?Address)'
        - _Description:_ `Address' is unified with the atom
          representing the address (in AF_INET format) corresponding
          to `Hostname'.

        - _Call and exit should be _compatible_ with:_

          `+Hostname' is an atom.   (`basic_props:atm/1')

          `?Address' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: socket_shutdown/2:
     *Usage:* `socket_shutdown(+Stream, +How)'
        - _Description:_ Shut down a duplex communication socket with
          which `Stream' is associated. All or part of the
          communication can be shutdown, depending on the value of
          `How'. The atoms `read', `write', or `read_write' should be
          used to denote the type of closing required.

        - _Call and exit should be _compatible_ with:_

          `+Stream' is an open stream.   (`streams_basic:stream/1')

          `+How' is a valid shutdown type.
          (`sockets:shutdown_type/1')

 -- PREDICATE: socket_recv_code/3:
     *Usage:* `socket_recv_code(+Stream, ?String, ?Length)'
        - _Description:_ Receives a `String' from the socket
          associated to `Stream', and returns its `Length'. If
          `Length' is -1, no more data is available.

        - _Call and exit should be _compatible_ with:_

          `+Stream' is an open stream.   (`streams_basic:stream/1')

          `?String' is a string (a list of character codes).
          (`basic_props:string/1')

          `?Length' is an integer.   (`basic_props:int/1')

 -- PREDICATE: socket_send/2:
     *Usage:* `socket_send(+Stream, +String)'
        - _Description:_ Sends `String' to the socket associated to
          `Stream'. The socket has to be in connected state. `String'
          is not supposed to be NULL terminated, since it is a Prolog
          string. If a NULL terminated string is needed at the other
          side, it has to be explicitly created in Prolog.

        - _Call and exit should be _compatible_ with:_

          `+Stream' is an open stream.   (`streams_basic:stream/1')

          `+String' is a string (a list of character codes).
          (`basic_props:string/1')

 -- PREDICATE: select_socket/5:
     *Usage:* `select_socket(+Socket, -NewStream, +TO_ms, +Streams,
     -ReadStreams)'
        - _Description:_ Wait for data available in a list of
          `Streams' and in a `Socket'. `Streams' is a list of Prolog
          streams which will be tested for reading. `Socket' is a
          socket (i.e., an integer denoting the O.S. port number) or a free
          variable. `TO_ms' is a number denoting a timeout. Within
          this timeout the `Streams' and the `Socket' are checked for
          the availability of data to be read. `ReadStreams' is the
          list of streams belonging to `Streams' which have data
          pending to be read. If `Socket' was a free variable, it is
          ignored, and `NewStream' is not checked. If `Socket' was
          instantiated to a port number and there are connections
          pending, a connection is accepted and connected with the
          Prolog stream in `NewStream'.

        - _Call and exit should be _compatible_ with:_

          `+Socket' is an integer.   (`basic_props:int/1')

          `-NewStream' is an open stream.   (`streams_basic:stream/1')

          `+TO_ms' is an integer.   (`basic_props:int/1')

          `+Streams' is a list of `stream's.   (`basic_props:list/2')

          `-ReadStreams' is a list of `stream's.
          (`basic_props:list/2')

 -- PREDICATE: socket_accept/2:
     *Usage:* `socket_accept(+Sock, -Stream)'
        - _Description:_ Creates a new `Stream' connected to `Sock'.

        - _Call and exit should be _compatible_ with:_

          `+Sock' is an integer.   (`basic_props:int/1')

          `-Stream' is an open stream.   (`streams_basic:stream/1')

 -- PREDICATE: bind_socket/3:
     *Usage:* `bind_socket(?Port, +Length, -Socket)'
        - _Description:_ Returs an AF_INET `Socket' bound to `Port'
          (which may be assigned by the OS or defined by the caller),
          and listens to it (hence no listen call in this set of
          primitives). `Length' specifies the maximum number of
          pending connections.

        - _Call and exit should be _compatible_ with:_

          `?Port' is an integer.   (`basic_props:int/1')

          `+Length' is an integer.   (`basic_props:int/1')

          `-Socket' is an integer.   (`basic_props:int/1')

 -- PREDICATE: connect_to_socket_type/4:
     *Usage:* `connect_to_socket_type(+Host, +Port, +Type, -Stream)'
        - _Description:_ Returns a `Stream' which connects to `Host'.
          The `Type' of connection can be defined. A `Stream' is
          returned, which can be used to `write/2' to, to `read/2', to `socket_send/2'
          to, or to `socket_recv/2' from the socket.

        - _Call and exit should be _compatible_ with:_

          `+Host' is currently instantiated to an atom.
          (`term_typing:atom/1')

          `+Port' is an integer.   (`basic_props:int/1')

          `+Type' is a valid socket type.   (`sockets:socket_type/1')

          `-Stream' is an open stream.   (`streams_basic:stream/1')

83 Sockets I/O
**************

*Author(s):* Francisco Bueno.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#241 (2003/12/22, 18:56:7 CET)

   This module provides two useful predicates for programming with
sockets.

83.1 Usage and interface (`sockets_io')
=======================================

   * *Library usage:*

     `:- use_module(library(sockets_io)).'

   * *Exports:*
        - _Predicates:_

          `serve_socket/3', `safe_write/2'.

   * *Other modules used:*
        - _System library modules:_

          `lists', `file_utils', `sockets/sockets'.

83.2 Documentation on exports (`sockets_io')
============================================

 -- PREDICATE: serve_socket/3:
     _Meta-predicate_ with arguments:
     `serve_socket(?,pred(1),pred(1))'.

     *Usage:* `serve_socket(Socket, Server, Handler)'
        - _Description:_ Handles the streams associated to `Socket'
          calling `Server' on one request of each stream (as
          `Server(Stream)'), and `Handler(Stream)' if the stream is
          empty (connection closed).

        - _The following properties should hold at call time:_

          `Socket' is a socket id.   (`sockets_io:socket/1')

          `Server' is a term which represents a goal, i.e., an atom
          or a structure.   (`basic_props:callable/1')

          `Handler' is a term which represents a goal, i.e., an atom
          or a structure.   (`basic_props:callable/1')

 -- PREDICATE: safe_write/2:
     *Usage:* `safe_write(Stream, Term)'
        - _Description:_ Writes `Term' to `Stream' in a way that it
          is safe for a socket connection on `Stream'.

        - _The following properties should hold at call time:_

          `Stream' is an open stream.   (`streams_basic:stream/1')

          `Term' is any term.   (`basic_props:term/1')

84 The Ciao Make Package
************************

*Author(s):* Manuel Hermenegildo.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#222 (2003/12/21, 20:8:53 CET)

This package is used mainly in two main ways:

   * When writing `Makefile's for `lpmake'.

   * When writing _applications_ which use the `make' library.

In both cases, this is the package that defines the syntax and
meaning of the dependency rules used.

84.1 Usage and interface (`make')
=================================

   * *Library usage:*

        * When writing `Makefile's for `lpmake', such makefiles start
          with:

               :- module(_,_,[make]).

          or

               :- make(_,_).

          (The latter uses the feature that an undefined declaration
          at the beginning of a file is interpreted by Ciao as a `use_module/3'
          including as third argument a package with the same name,
          in this case `make'.)

        * When writing _applications_ which use the `make' package,
          then it is loaded as any other package within the
          application.

     *Note:* it is often useful to use the `functions' package inside
     a `Makefile' (or when when using the `make' library in other
     applications). If both `make' and `functions' are used, then `make'
     should appear *before* `functions' in the list of packages.

   * *New operators defined:*

     `::/2' [1050,xfy], `<=/2' [1050,xfy], `<-/2' [1050,xfy], `<-/1'
     [1050,yf].

   * *Other modules used:*
        - _System library modules:_

          `make/make_rt'.

84.2 Other information (`make')
===============================

84.2.1 The Dependency Rules
---------------------------

The package allows defining the following types of rules:

`_TargetSuffix_ <= _SourceSuffix_ :: _SourceRoot_ :- _BodyLiterals_.'
     A rule of this form declares that in order to produce the file
     with suffix _TargetSuffix_ from a source file with the suffix
     _SourceSuffix_ and root name _SourceRoot_ the commands in
     _BodyLiterals_ must be executed. _BodyLiterals_ is a standard
     Ciao Prolog clause body, i.e., a comma-separated conjunction of
     literals. When writing the script, _SourceRoot_ is typically
     left as a variable, to be instantiated by `lpmake' when the
     script is run to the root of name of the file to be processed.
     This allows using the value of _SourceRoot_ in _BodyLiterals_.
     For example, the following rule:

          :- use_module(library(terms),[atom_concat/2]).

          dvi <= tex :: FileRoot :-
                  atom_concat(['latex ',FileRoot,'.tex'],Command),
                  system(Command).

     states that we can generate a file _File_`.dvi' if we have a
     file named _File_`.tex' and that the command to do so is `latex
     '_File_`.tex'. Thus, if this rule appears in file `Makefile.pl'
     and we issue the command `lpmake paper.dvi' the following occurs:

        * If `paper.dvi' does not exist and `paper.tex' exists, then
          `paper.dvi' is generated from `paper.tex' by issuing the
          system command `latex paper.tex'.

        * If `paper.dvi' already exists, nothing is done.

        * If `paper.tex' does not exist, an error is reported.

`_Target_ <- :- _BodyLiterals_.'
     A rule of this form declares that in order to produce the file
     _Target_ the commands in _BodyLiterals_ must be executed.
     _Target_ need not be a real file: it can also be simply the name
     of the rule, which is used to invoke it (as a procedure name).
     For example, the following rule, when the command `lpmake
     realclean' is issued, deletes temporary files in the LaTeX
     application:

          :- use_module(library('make/system_extra')).

          clean <- :-
                  ls('*aux|*log|*~',Files)
                  delete_files(Files).

`_Target_ <- _Deps_ :- _BodyLiterals_.'
     A rule of this form declares that in order to produce the file
     _Target_, first targets _Deps_ will be called (i.e., the
     elements of _Deps_ are either other targets with rules defined
     for them, or a file or files which are already present or which
     can -and will be- generated from other available files using
     other rules). Then, the commands in _BodyLiterals_ will be
     executed. _Deps_ may be one target or a list of targets. For
     example, the following rule, when the command `lpmake realclean'
     is issued, cleans all the temporary files in the LaTeX
     application (including `.dvi' and `.ps' files). It requires that
     clean be executed first:

          :- use_package(functions).
          :- use_module(library('make/system_extra')).

          realclean <- clean :-
                  delete_files(~ls('*dvi|*ps')).

     The following rule states that in order to meet the target
     `view', target `paper.ps' must be available or generated. For
     example, `lpmake view' can be used to call the `ghostview'
     visualizer on `paper.ps'. Note the use of a globally defined
     _predicate_ `main' which is called in two places in the rule,
     and could be used in other rules in the same file (`main :=
     paper.' is equivalent to the fact `main(paper).' -see the `functions'
     library):

          :- use_package(functions).
          :- use_module(library('make/system_extra')).
          :- use_module(library(terms),[atom_concat/2]).

          main := paper.

          view <- ~atom_concat([~main,'.ps']) :-
                  system(~atom_concat(['ghostview ',~main,'.ps'])).

   In addition to these rules, the configuration file can define
normal predicates in the usual way, or import predicates from other
modules, all of which can be called from the bodies of the dependency
rules. For example, the `system_extra' library (an extension of the `system'
library) defines many system predicates in a form which makes them
very useful inside `Makefile's, specially if the `functions' package
is used (see the examples below).

   If `lpmake' is called without an explicit target as argument, then
the first target rule in the Makefile is used. This is useful in that
the first rule can be seen as the default rule.

84.2.2 Specifying Paths
-----------------------

Using the `vpath/1' predicate it is possible in configuration files
to define several paths in which files related to the rules can be
located. In this way, not all files need to be in the same directory
as the configuration file. For example:

     :- use_package(functions).

     vpath := '/home/clip/Systems/ciao/lib'.
     vpath := '/home/clip/Systems/ciao/library'.
     vpath := '/home/clip/Systems/lpdoc/lib'.

84.2.3 Documenting Rules
------------------------

It is also possible to define documentation for the rules:

`target_comment(_Target_) :- _BodyLiterals_.'
     A rule of this form allows documenting the actions related to
     the target. The body (_BodyLiterals_) will be called in two
     circumstances:

        * If _Target_ is called during execution of '`lpmake'
          _commands_'.

        * When calling '`lpmake -h''.

     Using noun forms (_generation of foo_ instead of _generating
     foo_) in comments helps this dual purpose. For example, the
     following rule:

          target_comment(realclean) :-
                  display('Cleanup of all generated files.').

     will produce output in the two cases pointed out above.

`dependency_comment(_SourceSuffix_,_TargetSuffix_,_SourceRoot_) :- _BodyLiterals_.'
     Same as the previous rule, but for suffix rules. See, for
     example, the following generic rule:

          :- use_module(library(terms),[atom_concat/2]).

          dependency_comment(SSuffix,TSuffix,FileBase) :-
                  display(~atom_concat(['Generation of ',FileBase,'.',TSuffix,
                                        ' from ',FileBase,'.',SSuffix])).

84.2.4 An Example of a Makefile
-------------------------------

The following is a simple example of a Makefile showing some basic
functionality (this is `MakefileExample.pl' in the `example_simple'
directory in the `make' library.):

     %% -------------------------------------------------------------------------
     :- module(_,_,[make,functions]).
     :- use_module(library('make/system_extra')).
     :- use_module(library(lists),[append/3,list_concat/2]).
     :- use_module(library(terms),[atom_concat/2]).

     :- discontiguous(comment/2).

     %% -------------------------------------------------------------------------
     %% A simple target. Defines how to produce file 'hw'.

     hw <-  []    :-
              writef("Hello world", hw).

     %% A comment describing this target (see below):
     comment(hw,['Generation of file hw']).

     %% -------------------------------------------------------------------------
     %% A target with a dependency. 'hwhw' requires 'hw'.

     hwhw <- [hw] :-
             readf(hw,Content),
             append(Content,[0'\n|Content],DoubleContent),
             writef(DoubleContent,hwhw).

     comment(hwhw,['Generation of file hwhw']).

     %% -------------------------------------------------------------------------
     %% A simple target. Defines how to produce file 'datafile.simple'.

     'datafile.simple' <-  :-
             writef("Hello world", 'datafile.simple').

     comment('datafile.simple',['Generation of file datafile.simple']).

     %% -------------------------------------------------------------------------
     %% A dependency based on suffixes:
     %% <file>.double is generated always from <file>.simple

     double <= simple :: Name :-
             readf(~atom_concat([Name,'.simple']),Content),
             append(Content,[0'\n|Content],DoubleContent),
             writef(DoubleContent,~atom_concat([Name,'.double'])).

     %% -------------------------------------------------------------------------
     %% A dependency based on suffixes with a precondition.
     %% <file>.double is generated always from <file>.simple, once precond is done

     boo <- :-
             display((double <= simple :: name <- precond :- body1, body2)).

     %% -------------------------------------------------------------------------
     %% Example using library predicates

     clean <-    :-
             delete_files(~ls('*~|*.asr|*.itf|*.po')).

     comment(clean,['Cleanup of temporary files']).

     realclean <- clean :-
             delete_files(~ls('hw|hwhw|*simple|*double')).

     comment(realclean,['Cleanup of all generated files']).

     %% -------------------------------------------------------------------------
     %% Reporting progress and documenting commands:
     %% If target_comment/1 is defined it can be used to produce user-defined
     %% output when targets are processed and/or documentation on what each
     %% target does (used for example when lpmake is called with -h). Using
     %% 'generation of foo' instead of 'generating foo' in comments helps in this
     %% dual purpose.
     %% -------------------------------------------------------------------------

     %% Make calls target_comment/1 for simple targets:
     target_comment(Target) :-
             comment(Target,Comment),
             display(~atom_concat([~atom_concat(Comment), '\n'])).

     %% Similarly, make calls dependency_comment/3 for dependencies (only
     %% during execution, not when documenting -h).
     dependency_comment(SSuffix,TSuffix,FileBase) :-
             display(~atom_concat(['Generation of ',FileBase,'.',TSuffix,
                                   ' from ',FileBase,'.',SSuffix])).

     %% -------------------------------------------------------------------------

   The following are a few commands that can be used on the previous
file (see file `CommandsToTry' in the `example_simple' directory in
the `make' library):

     lpmake -m MakefileExample.pl hwhw
     (Generate file hwhw --needs to generate file hw first)

     lpmake -m MakefileExample.pl datafile.double
     (Generate file datafile.double --needs to generate file datafile.simple first)

     lpmake -m MakefileExample.pl realclean
     (Cleanup)

     lpmake -h -m MakefileExample.pl
     (Help on general use of lpmake and commands available in MakefileExample.pl)

   See also the LaTeX example in the `example_latex' directory in the `make'
library.

85 Predicates Available When Using The Make Package
***************************************************

*Author(s):* Manuel Hermenegildo.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#251 (2003/12/30, 22:8:3 CET)

   This is the run-time module which implements the predicates which
are provided when using the `make' library package in a given
application. For example, they are used internally by `lpmake'.

85.1 Usage and interface (`make_rt')
====================================

   * *Library usage:*

     This module is loaded automatically when the `make' library
     package is used.

   * *Exports:*
        - _Predicates:_

          `make/1', `make_option/1', `verbose_message/2', `call_unknown/1', `dyn_load_cfg_module_into_make/1'.

        - _Regular Types:_

          `target/1'.

   * *Other modules used:*
        - _System library modules:_

          `compiler/compiler', `filenames', `terms', `system', `messages', `format'.

85.2 Documentation on exports (`make_rt')
=========================================

 -- PREDICATE: make/1:
     *Usage:* `make(TargetList)'
        - _Description:_ This is the main entry point to the make
          library. Makes the list of targets one by one and any
          needed intermediate targets as dictated by the dependency
          rules.

        - _The following properties should hold at call time:_

          `TargetList' is a list of `target's.
          (`basic_props:list/2')

 -- REGTYPE: target/1:
     *Usage:* `target(T)'
        - _Description:_ `T' is a Makefile target.

 -- PREDICATE: make_option/1:
     The predicate is of type _data_.

     *Usage:* `make_option(Option)'
        - _Description:_ Asserting/retracting facts of this predicate
          sets/clears library options. Default is no options (i.e.,
          the predicate is undefined). The following values are
          supported:
               make_option('-v'). % Verbose: prints progress messages (for debugging rules).

        - _The following properties should hold at call time:_

          `Option' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: verbose_message/2:
     *Usage:* `verbose_message(Text, ArgList)'
        - _Description:_ The text provided in `Text' is printed as a
          message, using the arguments in `ArgList', if
          `make_option('-v')' is defined. Otherwise nothing is
          printed.

        - _The following properties should hold at call time:_

          `Text' is an atom or string describing how the arguments
          should be formatted. If it is an atom it will be converted
          into a string with `name/2'.   (`format:format_control/1')

          `ArgList' is a list.   (`basic_props:list/1')

 -- PREDICATE: call_unknown/1:
     `call_unknown(G)'

     This is a local copy, to make package independent. Complication
     is so that flags are left as they were also upon failure.

 -- PREDICATE: dyn_load_cfg_module_into_make/1:
     *Usage:* `dyn_load_cfg_module_into_make(ConfigFile)'
        - _Description:_ Used to load dynamically a module
          (typically, a `Makefile') into the make library from the
          application using the library.

        - _The following properties should hold at call time:_

          `ConfigFile' is a source name.
          (`streams_basic:sourcename/1')

86 system_extra (library)
*************************

*Author(s):* M. Hermenegildo.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#329 (2004/3/25, 16:25:36 CET)

   This is a (temporary) extension to library `system' (which it
reexports). It implements functionality that is often convenient in `Makefile's.
Much of this should probably end up eventually in `system', but once
we have worked out the best interface and, in some cases, the proper
implementation (the implementations in here are in some cases just
calls to Un*x shell primitives or commands).

86.1 Usage and interface (`system_extra')
=========================================

   * *Library usage:*

     `:- use_module(library(system_extra)).'

   * *Exports:*
        - _Predicates:_

          `del_dir_if_empty/1', `move_files/2', `move_file/2', `copy_files/2', `copy_file/2', `cat/2', `cat_append/2', `convert_permissions/4', `symbolic_link/2', `symbolic_link/3', `delete_files/1', `del_file_nofail/1', `del_file_nofail/2', `del_endings_nofail/2', `ls/3', `ls/2', `filter_alist_pattern/3', `do/2', `set_perms/2', `readf/2', `datime_string/1', `datime_string/2', `all_values/2', `no_tr_nl/2', `call_unknown/1', `replace_strings_in_file/3', `writef/3', `writef/2'.

   * *Other modules used:*
        - _System library modules:_

          `system', `patterns', `filenames', `messages', `terms', `lists', `sort', `aggregates'.

86.2 Documentation on exports (`system_extra')
==============================================

 -- PREDICATE: del_dir_if_empty/1:
     No further documentation available for this predicate.

 -- PREDICATE: move_files/2:
     `move_files(Files, Dir)'

     Move `Files' to directory `Dir' (note that to move only one file
     to a directory, `rename_file/2' can be used).

 -- PREDICATE: move_file/2:
     No further documentation available for this predicate.

 -- PREDICATE: copy_files/2:
     `copy_files(Files, Dir)'

     Copy `Files' to directory `Dir' (note that to move only one file
     to a directory, `rename_file/2' can be used).

 -- PREDICATE: copy_file/2:
     No further documentation available for this predicate.

 -- PREDICATE: cat/2:
     No further documentation available for this predicate.

 -- PREDICATE: cat_append/2:
     No further documentation available for this predicate.

 -- PREDICATE: convert_permissions/4:
     No further documentation available for this predicate.

 -- PREDICATE: symbolic_link/2:
     *Usage:* `symbolic_link(Source, Dir)'
        - _Description:_ Create a symbolic link in `Dir' pointing to
          file or directory `Source' (performs a copy in Windows).

 -- PREDICATE: symbolic_link/3:
     *Usage:* `symbolic_link(Source, Dir, NewName)'
        - _Description:_ Create a symbolic link in `Dir' pointing to
          file or directory `Source' and give it name `NewName'
          (performs a copy in Windows).

 -- PREDICATE: delete_files/1:
     No further documentation available for this predicate.

 -- PREDICATE: del_file_nofail/1:
     No further documentation available for this predicate.

 -- PREDICATE: del_file_nofail/2:
     No further documentation available for this predicate.

 -- PREDICATE: del_endings_nofail/2:
     No further documentation available for this predicate.

 -- PREDICATE: ls/3:
     `ls(Directory, Pattern, FileList)'

     `FileList' is the unordered list of entries (files, directories,
     etc.) in `Directory' whose names match `Pattern'.If `Directory'
     does not exist `FileList' is empty.

 -- PREDICATE: ls/2:
     `ls(Pattern, FileList)'

     `FileList' is the unordered list of entries (files, directories,
     etc.) in the current directory whose names match `Pattern' (same
     as `ls('.',Pattern,FileList)').

 -- PREDICATE: filter_alist_pattern/3:
     `filter_alist_pattern(UnFiltered, Pattern, Filtered)'

     `Filtered' contains the elements of `UnFiltered' which match
     with `Pattern'.

 -- PREDICATE: -/1:
     No further documentation available for this predicate.

     _Meta-predicate_ with arguments: `-goal'.

 -- PREDICATE: do/2:
     No further documentation available for this predicate.

 -- PREDICATE: set_perms/2:
     No further documentation available for this predicate.

 -- PREDICATE: readf/2:
     No further documentation available for this predicate.

 -- PREDICATE: datime_string/1:
     No further documentation available for this predicate.

 -- PREDICATE: datime_string/2:
     No further documentation available for this predicate.

 -- PREDICATE: all_values/2:
     No further documentation available for this predicate.

     _Meta-predicate_ with arguments: `all_values(pred(1),?)'.

 -- PREDICATE: no_tr_nl/2:
     No further documentation available for this predicate.

 -- PREDICATE: call_unknown/1:
     No further documentation available for this predicate.

     _Meta-predicate_ with arguments: `call_unknown(goal)'.

 -- PREDICATE: replace_strings_in_file/3:
     No further documentation available for this predicate.

 -- PREDICATE: writef/3:
     No further documentation available for this predicate.

 -- PREDICATE: writef/2:
     No further documentation available for this predicate.

 -- (: UNDOC_REEXPORT) cyg2win/3:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) rename_file/2:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) delete_directory/1:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) delete_file/1:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) chmod/3:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) chmod/2:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) fmode/2:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) modif_time0/2:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) modif_time/2:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) file_properties/6:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) file_property/2:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) file_exists/2:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) file_exists/1:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) mktemp/2:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) directory_files/2:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) wait/3:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) exec/8:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) exec/3:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) exec/4:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) popen_mode/1:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) popen/3:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) system/2:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) system/1:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) shell/2:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) shell/1:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) shell/0:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) cd/1:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) working_directory/2:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) make_dirpath/1:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) make_dirpath/2:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) make_directory/1:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) make_directory/2:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) umask/2:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) current_executable/1:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) current_host/1:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) get_pid/1:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) extract_paths/2:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) setenvstr/2:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) getenvstr/2:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) datime_struct/1:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) datime/9:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) datime/1:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) time/1:
     Imported from `system' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) pause/1:
     Imported from `system' (see the corresponding documentation for
     details).

PART VII - Ciao Prolog extensions
*********************************

*Author(s):* The CLIP Group.

   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 library;

   * global variables;

   * `setarg' and `undo';

   * delaying predicate execution;

   * active modules;

   * breadth-first execution;

   * iterative deepening-based execution;

   * constraint logic programming;

   * object oriented programming.

87 Pure Prolog package
**********************

*Author(s):* The CLIP Group.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#224 (2003/12/21, 20:16:18 CET)

   This library package allows the use of _pure Prolog_ in a Ciao
module/program. It is based on the fact that if an _engine module_ is
imported explicitly then all of them have to be imported explicitly.
The engine modules are:
   * `engine(arithmetic)'

     See Arithmetic.

   * `engine(atomic_basic)'

     See Basic predicates handling names of constants.

   * `engine(attributes)'

     See Attributed variables.

   * `engine(basic_props)'

     See Basic data types and properties.

   * `engine(basiccontrol)'

     See Control constructs/predicates.

   * `engine(data_facts)'

     See Fast/concurrent update of facts.

   * `engine(exceptions)'

     See Exception handling.

   * `engine(io_aux)'

     See Message printing primitives.

   * `engine(io_basic)'

     See Basic input/output.

   * `engine(prolog_flags)'

     See Changing system behaviour and various flags.

   * `engine(streams_basic)'

     See Basic file/stream handling.

   * `engine(system_info)'

     See Gathering some basic internal info.

   * `engine(term_basic)'

     See Basic term manipulation.

   * `engine(term_compare)'

     See Comparing terms.

   * `engine(term_typing)'

     See Extra-logical properties for typing.

   Note that if any of these modules is explicitely imported in a
program then the language defaults to Pure Prolog, plus the
functionality added by the modules explicitely imported.

   It is recommended that if you explicitely import an engine module
you also use this package, which will guarantee that the predicate
`true/0' is defined (note that this is the only Ciao builtin which
cannot be redefined).

87.1 Usage and interface (`pure')
=================================

   * *Library usage:*

     `:- use_package(pure).'

     or

     `:- module(...,...,[pure]).'

87.2 Known bugs and planned improvements (`pure')
=================================================

   * Currently, the following builtin predicates/program constructs
     cannot be redefined, in addition to `true/0': `(->)/2' `(,)/2'
     `(+)/1' `if/3'

88 Multiple Argument Indexing
*****************************

*Author(s):* Tom Howland (http://home.pacbell.net/tomjdnh/pd.html),
derived from work by Anil Nair, F. Bueno (for the Ciao package).

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#225 (2003/12/21, 20:20:39 CET)

   This package is an extension of the idea of Prolog indexing,
usually performed, in a limited way, on the first argument. This
package provides more powerful indexing schemes. It lets you pick
different arguments to index on, and provides for different
combinations of arguments to index on. E.g., it will let you index on
the first and third argument or the second and the third argument of
a predicate.

88.1 Usage and interface (`indexer')
====================================

   * *Library usage:*

     This facility is used as a package, thus either including `indexer'
     in the package list of the module, or by using the `use_package/1'
     declaration. The facility predicate `hash_term/2', documented
     here, is defined in library module `hash'.

   * *Other modules used:*
        - _System library modules:_

          `assertions/native_props'.

88.2 Documentation on internals (`indexer')
===========================================

 -- DECLARATION: index/1:
     *Usage:* :- `index(IndexSpecs)'.
        - _Description:_ Declares an indexing scheme for a predicate.
          All specs of `IndexSpecs' must be terms for the same
          predicate. Each spec declares an indexing on a combination
          of the arguments. Indexing will be performed using any of
          the specs in `IndexSpecs' (being thus interpreted as an or).

          You should use a `*' in an argument position if you wish to
          hash on the entire term in that argument. If a `+' is used
          only one level of the term in the argument is used for
          hashing. An `i' is used to indicate that argument is
          already an integer, and therefore its own value will be
          used for hashing. The argspec `?' simply indicates not to
          use the argument for indexing.

          For example, the index specification:
               :- index foo(+,?,*,i), foo(?,?,?,i).
          declares indexing for `foo/4' either on a combination of
          the first, third, and fourht arguments, or only on the last
          argument, which is an integer. In the first case, only the
          principal functor of the first argument will be used for
          hashing; the third argument will be used in its entirety.

          The argspec `n' is a pragmatic extension and can not be
          used in conjunction with the other specifiers aside from
          `?'. It stands for "nonvar" and implies that the argument
          will not be used for hashing, since only ground terms can
          effectively be used in hashing. Thus, it can not be used in
          combination with other specifiers within a particular index
          specification. It is often the fastest thing to use.

        - _The following properties should hold upon exit:_

          `IndexSpecs' is an index specification.
          (`indexer_doc:indexspecs/1')

 -- REGTYPE: indexspecs/1:
     An index specification is defined as follows:
          indexspecs(Spec) :-
                  indexspec(Spec).
          indexspecs((Spec,Specs)) :-
                  indexspec(Spec),
                  indexspecs(Specs).

          indexspec(Spec) :-
                  Spec=..[_F|Args],
                  list(Args,argspec).

     *Usage:* `indexspecs(IndexSpecs)'
        - _Description:_ `IndexSpecs' is an index specification.

 -- REGTYPE: argspec/1:
     An argument hash specification is defined as follows:
          argspec(+).
          argspec(*).
          argspec(i).
          argspec(n).
          argspec(?).

     *Usage:* `argspec(Spec)'
        - _Description:_ `Spec' is an argument hash specification.

 -- PREDICATE: hash_term/2:
     `hash_term(Term, HashValue)'

     Provides an efficient way to calculate an integer `HashValue'
     for a ground `Term'.

     *Usage 1:* `hash_term(T, N)'
        - _Description:_ `N' is a hashing index for `T'.

        - _The following properties should hold at call time:_

          `T' is currently ground (it contains no variables).
          (`term_typing:ground/1')

          `N' is a free variable.   (`term_typing:var/1')

        - _The following properties should hold upon exit:_

          `N' is an integer.   (`basic_props:int/1')

     *Usage 2:* `hash_term(T, N)'
        - _The following properties should hold at call time:_

          ``T'' is not ground.   (`native_props:nonground/1')

          `N' is a free variable.   (`term_typing:var/1')

        - _The following properties should hold upon exit:_

          `N' is a free variable.   (`term_typing:var/1')

89 Higher-order
***************

*Author(s):* Daniel Cabeza Gras.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#226 (2003/12/22, 16:47:31 CET)

   This module is a wrapper to the implementation defined predicate `call/2'

89.1 Usage and interface (`hiord_rt')
=====================================

   * *Library usage:*

     `:- use_module(library(hiord_rt)).'

   * *Exports:*
        - _Predicates:_

          `call/2'.

89.2 Documentation on exports (`hiord_rt')
==========================================

 -- PREDICATE: call/2:
     `call(Pred, Arg1)'

     There exists a set of builtin predicates of the form `call/N'
     with `N > 1' which execute predicate `Pred' given arguments
     `Arg1' ... `ArgX'. If `Pred' has already arguments `Arg1' is
     added to the start, the rest to the end. This predicate, when
     `Pred' is a variable, can be written using the special Ciao
     syntax `Pred(Arg1,...,ArgX)'.

90 Higher-order predicates
**************************

*Author(s):* Daniel Cabeza, Manuel Carro.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.7#208 (2002/4/23, 19:9:14 CEST)

   This library implements a few basic higher-order predicates. These
add functionality to the basic higher-order functionality of Ciao.
Examples of the latter are:

   Using pred(1):

       list(L, functor(_,2))
       list(L, >(0))

   Using pred(2):

90.1 Usage and interface (`hiordlib')
=====================================

   * *Library usage:*

     `:- use_module(library(hiordlib)).'

   * *Exports:*
        - _Predicates:_

          `map/3', `foldl/4', `minimum/3'.

90.2 Documentation on exports (`hiordlib')
==========================================

 -- PREDICATE: map/3:
     _Meta-predicate_ with arguments: `map(?,pred(2),?)'.

     *Usage:* `map(LList, Op, RList)'
        - _Description:_ Examples of use:
                 map([1,3,2], arg(f(a,b,c,d)), [a,c,b]) or
                 map([1,3,2], nth([a,b,c,d]), [a,c,b])
                 map(["D","C"], append("."), ["D.","C."])

 -- PREDICATE: foldl/4:
     _Meta-predicate_ with arguments: `foldl(?,?,pred(3),?)'.

     *Usage:* `foldl(List, Seed, Op, Result)'
        - _Description:_ Example of use:
               ?- foldl(["daniel","cabeza","gras"], "",
                        (''(X,Y,Z) :- append(X, " "||Y, Z)), R).

               R = "daniel cabeza gras " ?

 -- PREDICATE: minimum/3:
     _Meta-predicate_ with arguments: `minimum(?,pred(2),?)'.

     *Usage:* `minimum(?List, +SmallerThan, ?Minimum)'
        - _Description:_ `Minimum' is the smaller in the nonempty
          list `List' according to the relation `SmallerThan': `SmallerThan(X,
          Y)' succeeds iff X is smaller than Y.

        - _The following properties should hold at call time:_

          `?List' is a list.   (`basic_props:list/1')

          `+SmallerThan' is a term which represents a goal, i.e., an
          atom or a structure.   (`basic_props:callable/1')

          `?Minimum' is any term.   (`basic_props:term/1')

91 Terms with named arguments -records/feature terms
****************************************************

*Author(s):* Daniel Cabeza and Manuel Hermenegildo.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.7#118 (2001/8/28, 15:7:22 CEST)

   This library package provides syntax which allows accessing term
arguments by name (these terms are sometimes also referred to as _records_,
and are also similar to _feature terms_ [AKPS92]).

91.1 Usage and interface (`argnames')
=====================================

   * *Library usage:*

     `:- use_package(argnames).'

     or

     `:- module(...,...,[argnames]).'

   * *New operators defined:*

     `$/2' [150,xfx], `=>/2' [950,xfx], `argnames/1' [1150,fx].

   * *New declarations defined:*

     `argnames/1'.

91.2 Documentation on new declarations (`argnames')
===================================================

 -- DECLARATION: argnames/1:
     *Usage:* :- `argnames(ArgNamedPredSpec)'.
        - _Description:_ An `argnames/1' declaration assigns names to
          the argument positions of terms (or literal/goals) which
          use a certain functor/arity. This allows referring to these
          arguments by their name rather than by their argument
          position. Sometimes, argument names may be clearer and
          easier to remember than argument positions, specially for
          predicates with many arguments. Also, in some cases this
          may allow adding arguments to certain predicates without
          having to change the code that uses them. These terms with
          named arguments are sometimes also referred to as records,
          and are also similar to feature terms [AKPS92]. For
          example, in order to write a program for the _zebra_ puzzle
          we might declare:

               :- use_package([argnames]).
               :- argnames house(color, nation, pet, drink, car).

          which first includes the package and then assigns a name to
          each of the arguments of any term (or literal/goal) with
          `house/5' as the main functor.

          For convenience the package extends the built-in `data/1'
          declaration so that names to arguments can be asigned as
          with the `argnames/1' declaration, as for example:

               :- data product(id, description, brand, quantity).

          Once an `argnames/1' is given, is possible to use the names
          to refer to the arguments of any term (or literal/goal)
          which has the same main functor as that of the term which
          appears in the `argnames/1' declaration. This is done by
          first writing the functor name, then the infix operator
          `$', and then, between curly brackets, zero, one, or more
          pairs _argument-name_`=>'_argument-value_, separated by
          commas (i.e., the infix operator `=>' is used between the
          name and the value). Again, argument names must be atomic.
          Argument values can be any term. Arguments which are not
          specified are assumed to have a value of "`_'" (i.e., they
          are left unconstrained).

          Thus, after the declaration for `house/5' in the example
          above, any ocurrence in that code of, for example,
          `house${nation=>Owns_zebra,pet=>zebra}' is exactly
          equivalent to `house(_,Owns_zebra,zebra,_,_)'. Also,
          `house${}' is equivalent to `house(_,_,_,_,_)'. The actual
          zebra puzzle specification might include a clause such as:

               zebra(Owns_zebra, Drinks_water, Street) :-
                  Street = [house${},house${},house${},house${},house${}],
                  member(house${nation=>Owns_zebra,pet=>zebra}, Street),
                  member(house${nation=>Drinks_water,drink=>water}, Street),
                  member(house${drink=>coffee,color=>green}, Street),
                  left_right(house${color=>ivory}, house${color=>green}, Street),
                  member(house${car=>porsche,pet=>snails}, Street),
                       ...

          Another syntax supported, useful mainly in declarations, to
          avoid specify the arity is `house${/}', which is equivalent
          in our example to `house/5' (but for data declarations
          there is a special syntax as we have seen).

          Any number of `argnames/1' declarations can appear in a
          file, one for each functor whose arguments are to be
          accessed by name. As with other packages, argument name
          declarations are _local to the file_ in which they appear.
          The `argnames/1' declarations affect only program text
          which appears after the declaration. It is easy to make a
          set of declarations affect several files for example by
          putting such declarations in a sepatate file which is
          included by all such files.

          An `argnames/1' declaration does not change in any way the
          internal representation of the associated terms and does
          not affect run-time efficiency. It is simply syntactic
          sugar.

91.3 Other information (`argnames')
===================================

Two simple examples of the use of the argnames library package follow.

91.3.1 Using argument names in a toy database
---------------------------------------------

     :- module(simple_db,_,[argnames,assertions,regtypes]).
     :- use_module(library(aggregates)).

     :- comment(title,"A simple database application using argument names").

     :- pred product/4 :: int * string * string * int.

     :- argnames
     product( id,    description,    brand,          quantity        ).
     %       ----------------------------------------------------------
     product(  1,    "Keyboard",     "Logitech",     6               ).
     product(  2,    "Mouse",        "Logitech",     5               ).
     product(  3,    "Monitor",      "Philips",      3               ).
     product(  4,    "Laptop",       "Dell",         4               ).

     % Compute the stock of products from a given brand.
     % Note call to findall is equivalent to: findall(Q,product(_,_,Brand,Q),L).
     brand_stock(Brand,Stock) :-
             findall(Q,product${brand=>Brand,quantity=>Q},L),
             sumlist(L,Stock).

     sumlist([],0).
     sumlist([X|T],S) :-
             sumlist(T,S1),
             S is X + S1.

91.3.2 Complete code for the zebra example
------------------------------------------

     :- module(_,zebra/3,[argnames]).

     /*     There are five consecutive houses, each of a different
     color and inhabited by men of different nationalities. They each
     own a different pet, have a different favorite drink, and drive a
     different car.

     1.   The Englishman lives in the red house.
     2.   The Spaniard owns the dog.
     3.   Coffee is drunk in the green house.
     4.   The Ukrainian drinks tea.
     5.   The green house is immediately to the right of the ivory
          house.
     6.   The Porsche driver owns snails.
     7.   The Masserati is driven by the man who lives in the yellow
          house.
     8.   Milk is drunk in the middle house.
     9.   The Norwegian lives in the first house on the left.
     10.  The man who drives a Saab lives in the house next to the man
          with the fox.
     11.  The Masserati is driven by the man in the house next to the
          house where the horse is kept.
     12.  The Honda driver drinks orange juice.
     13.  The Japanese drives a Jaguar.
     14.  The Norwegian lives next to the blue house.

     The problem is: Who owns the Zebra?  Who drinks water?
     */

     :- argnames house(color, nation, pet, drink, car).

     zebra(Owns_zebra, Drinks_water, Street) :-
             Street = [house${},house${},house${},house${},house${}],
             member(house${nation => Owns_zebra, pet => zebra}, Street),
             member(house${nation => Drinks_water, drink => water}, Street),
             member(house${nation => englishman, color => red}, Street),
             member(house${nation => spaniard, pet => dog}, Street),
             member(house${drink => coffee, color => green}, Street),
             member(house${nation => ukrainian, drink => tea}, Street),
             left_right(house${color => ivory}, house${color => green}, Street),
             member(house${car => porsche, pet => snails}, Street),
             member(house${car => masserati, color => yellow}, Street),
             Street = [_, _, house${drink => milk}, _, _],
             Street = [house${nation => norwegian}|_],
             next_to(house${car => saab}, house${pet => fox}, Street),
             next_to(house${car => masserati}, house${pet => horse}, Street),
             member(house${car => honda, drink => orange_juice}, Street),
             member(house${nation => japanese, car => jaguar}, Street),
             next_to(house${nation => norwegian}, house${color => blue}, Street).

     member(X,[X|_]).
     member(X,[_|Y]) :- member(X,Y).

     left_right(L,R,[L,R|_]).
     left_right(L,R,[_|T]) :- left_right(L,R,T).

     next_to(X,Y,L) :- left_right(X,Y,L).
     next_to(X,Y,L) :- left_right(Y,X,L).

91.4 Known bugs and planned improvements (`argnames')
=====================================================

   * It would be nice to add a mechanism to portray terms with named
     arguments in a special (user definable) way.

92 Functional notation
**********************

*Author(s):* Daniel Cabeza.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#291 (2004/2/13, 20:46:8 CET)

   This library package allows the use of functional notation in a
Ciao module/program.

   It should be made clear that this package just provides a kind of
syntactic sugar for defining and using predicates as if they were
functions, and thus any function definition is in fact defining a
predicate, and any predicate can be used as a function. The predicate
associated to a function has the same name and one more argument,
added to the right, to hold the result of the function.

   Any term preceded by the operator `~' is a function application,
as in `write(~arg(1,T))', which is equivalent to the sequence
`arg(1,T,A), write(A)'. Functors can be declared as evaluable by
using the declaration `function/1', and thus avoiding the need to use
the operator `~', as in
     :- function(arg/2).
   Note that this declaration, as is customary in Ciao Prolog, is
local to the source code where it is included. In addition, the
package defines several functors as evaluable by default, those being:
   * All the functors understood by `is/2'. This feature can be
     disabled by a declaration `:- function(arith(false))' (and
     reverted by using `true' instead of `false').

   * The functors used for disjunctive and conditional expressions,
     `(|)/2' and `(?)/2'. A disjunctive expression has the form
     `(V1|V2)', and its value when first evaluated is `V1', and on
     re-execution `V2'. A conditional expression has the form `(Cond
     ? V1)', or more commonly `(Cond ? V1 | V2)', and its value, if
     the execution of `Cond' as a goal succeeds, is `V1', otherwise
     in the first form it causes backtracking, and on the second form
     its value is `V2'. Note that due to the operator precedences,
     these expressions need normally to be surrounded by parenthesis.

   A functional clause is written using the binary operator `:=', as
in
     opposite(red) := green.
   Functional clauses can also have a body, which is executed before
the result value is computed. It can serve as a guard for the clause
or to provide the equivalent of a where-clause in a functional
language:
     fact(0) := 1.
     fact(N) := N * ~fact(--N) :- N > 0.
   Note that often a guard can be better defined using a conditional
expression:
     fact(N) := N = 0 ? 1
              | N > 0 ? N * ~fact(--N).

   In clause heads (either defined as predicates or functions)
functors can be prevented from being evaluated by using the `(^)/1'
prefix operator, as in
     pair(A,B) := ^(A-B).
   Note that this just prevents the evaluation of the principal
functor of the enclosed term, not the possible occurrences of other
evaluable functors inside. The operator is by now ignored outside
clause heads, due to the recurrent nature of the goal translations
used.

   When using function applications inside the goal arguments of
meta-predicates, there is an ambiguity as they could be evaluated
either in the scope of the outer execution or the in the scope of the
inner execution. The chosen behavior is by default to evaluate
function applications in the scope of the outer execution, and if
they should be evaluated in the inner scope, the goal containing the
function application needs to be escaped with the `(^^)/1' prefix
operator, as in `findall(X, (d(Y), ^^(X = Y+1)), L)' (which could
also be written as `findall(X, ^^ (d(Y), X = Y+1), L)').

92.1 Usage and interface (`functions')
======================================

   * *Library usage:*

     `:- use_package(functions).'

     or

     `:- module(...,...,[functions]).'

92.2 Known bugs and planned improvements (`functions')
======================================================

   * The `(^)/1' operator only works in clause heads.

   * Assumes that `is/2' is imported.

93 global (library)
*******************

*Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#185 (2003/12/9, 17:18:19 CET)

93.1 Usage and interface (`global')
===================================

   * *Library usage:*

     `:- use_module(library(global)).'

   * *Exports:*
        - _Predicates:_

          `set_global/2', `get_global/2', `push_global/2', `pop_global/2', `del_global/1'.

93.2 Documentation on exports (`global')
========================================

 -- PREDICATE: set_global/2:
     No further documentation available for this predicate.

 -- PREDICATE: get_global/2:
     No further documentation available for this predicate.

 -- PREDICATE: push_global/2:
     No further documentation available for this predicate.

 -- PREDICATE: pop_global/2:
     No further documentation available for this predicate.

 -- PREDICATE: del_global/1:
     No further documentation available for this predicate.

94 Independent and-parallel execution
*************************************

*Author(s):* Manuel Carro, Manuel Hermenegildo.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.7#160 (2001/11/27, 12:35:53 CET)

   *Note:* This is just a partial first shot. The real library still
needs to be written. Not difficult, just no time...

   This library will eventually allow and-parallel execution of goals
in (Herbrand-)independent fashion. It resembles the execution rules
of &-Prolog [HG90]. Basically, goals are run in and-parallel
_provided that their arguments do not share bindings_, i.e., are not
bound to terms which contain a common variable.

94.1 Usage and interface (`andprolog')
======================================

   * *Library usage:*

     `:- use_package(andprolog).'

     or

     `:- module(...,...,[andprolog]).'

   * *New operators defined:*

     `' [950,xfy].

94.2 Documentation on internals (`andprolog')
=============================================

 -- PREDICATE:
     ` GoalB)'

     `GoalA' and `GoalB' are run in independent and-parallel fashion.
     This is just a first sketch, and valid only for deterministic
     independent goals. The use is as

          q:- a & b.

     which would start `a' and `b' in separate threads (possibly in
     parallalel, if the machine architecture and operating system
     allows that), and continue when *both* have finished. This type
     of execution is safe only when `a' and `b' are independent in
     the sense of variable sharing. This condition can be tested with
     the `indep/2' predicate.

 -- PREDICATE: active_agents/1:
     `active_agents(NumberOfAgents)'

     Tests/sets the `NumberOfAgents' which are active looking for
     goals to execute. As for now, those agents are
     resource-consuming, even when they are just looking for work,
     and not executing any user goals.

 -- PREDICATE: indep/2:
     `indep(X, Y)'

     `X' and `Y' are _independent_, i.e., they are bound to terms
     which have no variables in common. For example, `indep(X,Y)'
     holds for `X=f(Z),Y=g(K)' and also for `X=f(a),Y=X' (since both
     `X' and `Y' are bound to ground terms). It does not hold for
     `X=f(Z),Y=g(Z)' and for `X=Y'.

 -- PREDICATE: indep/1:
     `indep(X)'

     `X' is a list of lists of length two, i.e., a list of the form
     `[[T1, T2], [T3, T4], ...]'. The variables in each pair of the
     list ``X'' are tested for independence using `indep/2'. This
     list-of-pairs format is the output of several independdnce
     analyzers for pair sharing.

94.3 Known bugs and planned improvements (`andprolog')
======================================================

   * *Beware:* the current code is just a partial first shot. It is
     provided for the sole purpose of experimentation and development.

   * The fact that only the first solution is returned for the
     conjunction is due to performance issues (and lack of time), and
     we expect to remove it in a near future.

   * CGEs (i.e., `=>') are not supported.

   * The `indep/1', `indep/2', and `ground/1' tests are not very
     efficient; they will be replaced by native versions (taken from
     the &-Prolog code) in the future.

95 Andorra execution
********************

*Author(s):* Claudio Vaucheret, Francisco Bueno.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.7#144 (2001/11/12, 17:57:47 CET)

   This package allows the execution under the Basic Andorra Model
[War88]. The model classifies goals as a _determinate goal_, if at
most one clause matches the goal, or nondeterminate goal, otherwise.
In this model a goal is delayed until either it becomes determinate
or it becomes the leftmost goal and no determinate goal is available.
The implementation of this selection rule is based on the use of
attributed variables [Hol92,Hol90].

   In order to test determinacy we verify only the heads of clauses
and builtins in the bodies of clauses before the first cut, if any.
By default, determinacy of a goal is detected dynamically: when
called, if at most one clause matches, it is executed; otherwise, it
is delayed. For goals delayed the test is repeated each time a
variable appearing in the goal is instantiated. In addition,
efficiency can be improved by using declarations that specify the
determinacy conditions. These will be considered for testing instead
of the generic test on all clauses that can match.

   As with any other Ciao package, the andorra computation rule
affects only the module that uses the package. If execution passes
across two modules that use the computation rule, determinate goals
are run in advance _within_ one module and also within the other
module. But determinate goals of one module do not run ahead of goals
of the other module.

   It is however possible to preserve the computation rule for calls
to predicates defined in other modules. These modules should
obviously also use this package. In addition _all_ predicates from
such modules should imported, i.e., the directive `:-
use_module(module)', should be used in this case instead of `:-
use_module(module,[...])'. Otherwise calls to predicates outside the
module will only be called when they became the leftmost goal.

95.1 Usage and interface (`andorra')
====================================

   * *Library usage:*

     `:- use_package(andorra).'

     or

     `:- module(...,...,[andorra]).'

   * *Exports:*
        - _Regular Types:_

          `detcond/1', `path/1'.

   * *New operators defined:*

     `?\=/2' [700,xfx], `?=/2' [700,xfx].

   * *New declarations defined:*

     `determinate/2'.

95.2 Documentation on new declarations (`andorra')
==================================================

 -- DECLARATION: determinate/2:
     :- `determinate(Pred, Cond)'.

     Declares determinacy conditions for a predicate. Conditions
     `Cond' are on variables of arguments of `Pred'. For example, in:
          :- determinate(member(A,B,C), ( A ?= term(B,[1])  ; C?=[_|_]) ).

          member(A,[A|B],B).
          member(A,[B|C],[B|D]) :-
                  A==B,
                  member(A,C,D).
     the declaration states that a call `member(A,B,C)' is
     determinate when either `A' doesn't unify with the first
     argument of `B' or `C' doesn't unify with `[_|_]'.

     *Usage:* :- `determinate(Pred, Cond)'.
        - _Description:_ States that the predicate `Pred' is
          determinate when `Cond' holds.

        - _The following properties should hold at call time:_

          `Pred' is a Name/Arity structure denoting a predicate name:
               predname(P/A) :-
                       atm(P),
                       nnegint(A).

          (`basic_props:predname/1')

          `Cond' is a determinacy condition.   (`user(...
          /andorra_doc):detcond/1')

95.3 Documentation on exports (`andorra')
=========================================

 -- REGTYPE: detcond/1:
     Defined by:
          detcond(ground(X)) :-
                  var(X).
          detcond(nonvar(X)) :-
                  var(X).
          detcond(instatiated(A,Path)) :-
                  var(A),
                  list(Path,int).
          detcond(?\=(Term1,Term2)) :-
                  path(Term1),
                  path(Term2).
          detcond(?=(Term1,Term2)) :-
                  path(Term1),
                  path(Term2).
          detcond(Test) :-
                  test(Test).

        * `ground/1' and `nonvar/1' have the usual meaning.

        * `instatiated(A,Path)' means that the subterm of `A'
          addressed by `Path' is not a variable. `Path' is a list of
          integer numbers describing a path to the subterm regarding
          the whole term A as a tree. For example,
          `instantiated(f(g(X),h(i(Z),Y)),[2,1])' tests whether
          `i(Z)' is not a variable.

        * `Term1 ?\= Term2' means "terms `Term1' and `Term2' do not
          unify (when instantiated)". `Term1' and `Term2' can be
          either an argument of the predicate or a term
          `term(V,Path)', which refers to the subterm of `V'
          addressed by `Path'.

        * `Term1 ?= Term2' means "terms `Term1' and `Term2' unify
          (when instantiated)". The same considerations above apply
          to `Term1' and `Term2'.

        * any other test that does not unify variables can also be
          used ( `==/2', `\==/2', `atomic/1').

     *Usage:* `detcond(X)'
        - _Description:_ `X' is a determinacy condition.

 -- REGTYPE: path/1:
     Defined by:
          path(X) :-
                  var(X).
          path(X) :-
                  list(X,int).

95.4 Other information (`andorra')
==================================

The andorra transformation will include the following predicates into
the code of the module that uses the package. Be careful not to
define predicates by these names:
   * `detcond_andorra/4'

   * `path_andorra/4'

   * `detcond_susp/4'

   * `path_susp/4'

   * `list_andorra2/5'

   * `test_andorra2/4'

96 Call on determinate
**********************

*Author(s):* Jose' Morales, Manuel Carro.

   *Version:* 1.7#149 (2001/11/19, 19:17:51 CET)

   Offers an enriched variant of call and cut `!!/0' which executes
pending goals when the computation has no more alternatives.

   This library is useful to, for example, get rid of external
connections once the necessary data has been obtained.

96.1 Usage and interface (`det_hook_rt')
========================================

   * *Library usage:*

          :- use_module(library(det_hook_rt)).
     in which case, `!!/0' is not available.

     Typically, this library is used as a package:
          :- use_package(det_hook).

   * *Exports:*
        - _Predicates:_

          `det_try/3'.

96.2 Documentation on exports (`det_hook_rt')
=============================================

 -- PREDICATE: det_try/3:
     _Meta-predicate_ with arguments: `det_try(goal,goal,goal)'.

     *Usage:* `det_try(Goal, OnCut, OnFail)'
        - _Description:_ `Action' is called, and `OnCut' and `OnFail'
          are goals to be executed when `Goal' is cut or when it
          finitely fails, respectively. In order for this to work,
          cutting must be performed in a special way, by using the `!!/0'
          predicate, also provided by this module.

        - _The following properties should hold at call time:_

          `Goal' is a term which represents a goal, i.e., an atom or
          a structure.   (`basic_props:callable/1')

          `OnCut' is a term which represents a goal, i.e., an atom or
          a structure.   (`basic_props:callable/1')

          `OnFail' is a term which represents a goal, i.e., an atom
          or a structure.   (`basic_props:callable/1')

96.3 Documentation on internals (`det_hook_rt')
===============================================

 -- PREDICATE: !!/0:
     *Usage:*
        - _Description:_ Performs a special cut which prunes
          alternatives away, as the usual cut, but which also
          executes the goals specified as `OnCut' for any call in the
          scope of the cut.

96.4 Other information (`det_hook_rt')
======================================

As an example, the program

     :- module(_, _, [det_hook]).

     enumerate(X):-
             display(enumerating), nl,
             OnCut = (display('goal cut'), nl),
             OnFail = (display('goal failed'), nl),
             det_try(enum(X), OnCut, OnFail).

     enum(1).
     enum(2).
     enum(3).

   behaves as follows:

     ?- enumerate(X).
     enumerating

     X = 1 ? ;

     X = 2 ? ;

     X = 3 ? ;
     goal failed

   (note the message inserted on failure). The execution can be cut
as follows:

     ?- use_package(det_hook).
     {Including /home/clip/lib/ciao/ciao-1.7/library/det_hook/det_hook.pl
     }

     yes
     ?- enumerate(X), '!!'.
     enumerating
     goal cut

     X = 1 ? ;

     no

96.5 Known bugs and planned improvements (`det_hook_rt')
========================================================

   * If the started goals do not exhaust their solutions, and '!!'/0
     is not used, the database will populate with facts which will be
     consulted the next time a '!!'/0 is used. This could cause
     incorrect executions.

97 Miscellaneous predicates
***************************

*Author(s):* Manuel Carro, Daniel Cabeza.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.3#95 (1999/11/8, 18:37:30 MET)

   This module implements some miscellaneous non-logical (but
sometimes very useful) predicates.

97.1 Usage and interface (`odd')
================================

   * *Library usage:*

     `:- use_module(library(odd)).'

   * *Exports:*
        - _Predicates:_

          `setarg/3', `undo/1'.

97.2 Documentation on exports (`odd')
=====================================

 -- PREDICATE: setarg/3:
     *Usage:* `setarg(Index, Term, NewArg)'
        - _Description:_ Replace destructively argument `Index' in
          `Term' by `NewArg'. The assignment is undone on
          backtracking. This is a major change to the normal behavior
          of data assignment in Ciao Prolog.

        - _The following properties should hold at call time:_

          `Index' is currently instantiated to an integer.
          (`term_typing:integer/1')

          `Term' is a compound term.   (`basic_props:struct/1')

          `NewArg' is any term.   (`basic_props:term/1')

        - _The following properties hold upon exit:_

          `Index' is currently instantiated to an integer.
          (`term_typing:integer/1')

          `Term' is a compound term.   (`basic_props:struct/1')

          `NewArg' is any term.   (`basic_props:term/1')

 -- PREDICATE: undo/1:
     _Meta-predicate_ with arguments: `undo(goal)'.

     *Usage:* `undo(Goal)'
        - _Description:_  `call(`Goal')' is executed on backtracking.
          This is a major change to the normal control of Ciao Prolog
          execution.

        - _The following properties should hold at call time:_

          `Goal' is a term which represents a goal, i.e., an atom or
          a structure.   (`basic_props:callable/1')

        - _The following properties hold upon exit:_

          `Goal' is a term which represents a goal, i.e., an atom or
          a structure.   (`basic_props:callable/1')

98 Delaying predicates (freeze)
*******************************

*Author(s):* Manuel Carro, Daniel Cabeza.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.5#72 (2000/3/19, 19:9:14 CET)

   This library offers a simple implementation of `freeze/2', `frozen/2',
etc. [Col82,Nai85,Nai91,Car87] based on the use of attributed
variables [Hol92,Hol90].

98.1 Usage and interface (`freeze')
===================================

   * *Library usage:*

     `:- use_module(library(freeze)).'

   * *Exports:*
        - _Predicates:_

          `freeze/2', `frozen/2'.

98.2 Documentation on exports (`freeze')
========================================

 -- PREDICATE: freeze/2:
     _Meta-predicate_ with arguments: `freeze(?,goal)'.

     *Usage:* `freeze(X, Goal)'
        - _Description:_ If `X' is free delay `Goal' until `X' is
          non-variable.

        - _The following properties should hold at call time:_

          `Goal' is a term which represents a goal, i.e., an atom or
          a structure.   (`basic_props:callable/1')

 -- PREDICATE: frozen/2:
     _Meta-predicate_ with arguments: `frozen(?,goal)'.

     *Usage:* `frozen(X, Goal)'
        - _Description:_ `Goal' is currently delayed until variable
          `X' becomes bound.

        - _The following properties should hold upon exit:_

          `Goal' is a term which represents a goal, i.e., an atom or
          a structure.   (`basic_props:callable/1')

99 Delaying predicates (when)
*****************************

*Author(s):* Manuel Carro.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.7#3 (2000/7/21, 11:54:59 CEST)

   `when/2' delays a predicate until some condition in its variable
is met. For example, we may want to find out the maximum of two
numbers, but we are not sure when they will be instantiated. We can
write the standard `max/3' predicate (but changing its name to `gmax/3'
to denote that the first and second arguments must be ground) as

     gmax(X, Y, X):- X > Y, !.
     gmax(X, Y, Y):- X =< Y.

   and then define a 'safe' `max/3' as

     max(X, Y, Z):-
             when((ground(X),ground(Y)), gmax(X, Y, Z)).

   which can be called as follows:

     ?- max(X, Y, Z) , Y = 0, X = 8.

     X = 8,
     Y = 0,
     Z = 8 ?

     yes

   Alternatively, `max/3' could have been defined as

     max(X, Y, Z):-
             when(ground((X, Y)), gmax(X, Y, Z)).

   with the same effects as above. More complex implementations are
possible. Look, for example, at the `max.pl' implementation under the
`when' library directory, where a `max/3' predicate is implemented
which waits on all the arguments until there is enough information to
determine their values:

     ?- use_module(library('when/max')).

     yes
     ?- max(X, Y, Z), Z = 5, Y = 4.

     X = 5,
     Y = 4,
     Z = 5 ?

     yes

99.1 Usage and interface (`when')
=================================

   * *Library usage:*

     `:- use_module(library(when)).'

   * *Exports:*
        - _Predicates:_

          `when/2'.

        - _Regular Types:_

          `wakeup_exp/1'.

   * *Other modules used:*
        - _System library modules:_

          `terms_vars', `sort', `sets'.

99.2 Documentation on exports (`when')
======================================

 -- PREDICATE: when/2:
     _Meta-predicate_ with arguments: `when(?,goal)'.

     *Usage:* `when(WakeupCond, Goal)'
        - _Description:_ Delays / executes `Goal' according to
          `WakeupCond' given. The `WakeupCond's now acceptable are
          `ground(T)' ( `Goal' is delayed until `T' is ground),
          `nonvar(T)' ( `Goal' is delayed until `T' is not a
          variable), and conjunctions and disjunctions of conditions:

               wakeup_exp(ground(_1)).
               wakeup_exp(nonvar(_1)).
               wakeup_exp((C1,C2)) :-
                       wakeup_exp(C1),
                       wakeup_exp(C2).
               wakeup_exp((C1;C2)) :-
                       wakeup_exp(C1),
                       wakeup_exp(C2).

          `when/2' only fails it the `WakeupCond' is not legally
          formed. If `WakeupCond' is met at the time of the call no
          delay mechanism is involved -- but there exists a time
          penalty in the condition checking.

          In case that an instantiation fires the execution of
          several predicates, the order in which these are executed
          is not defined.

        - _The following properties should hold at call time:_

          `WakeupCond' is a legal expression for delaying goals.
          (`when:wakeup_exp/1')

          `Goal' is a term which represents a goal, i.e., an atom or
          a structure.   (`basic_props:callable/1')

 -- REGTYPE: wakeup_exp/1:
     *Usage:* `wakeup_exp(T)'
        - _Description:_ `T' is a legal expression for delaying goals.

99.3 Known bugs and planned improvements (`when')
=================================================

   * Redundant conditions are not removed.

   * Floundered goals are not appropriately printed.

100 Active modules (high-level distributed execution)
*****************************************************

*Author(s):* Manuel Hermenegildo, Daniel Cabeza.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#2 (2002/5/23, 17:48:34 CEST)

   Active modules [CH95] provide a high-level model of inter-process
communication and distributed execution (note that this is also
possible using Ciao's communication and concurrency primitives, such
as sockets, concurrent predicates, etc., but at a lower level of
abstraction). An _active module_ (or an _active object_) is an
ordinary module to which computational resources are attached, and
which resides at a given location on the network. Compiling an active
module produces an executable which, when running, acts as a _server_
for a number of predicates: the predicates exported by the module.
Predicates exported by an active module can be accessed by a program
on the network by simply "using" the module, which then imports such
"remote predicates." The process of "using" an active module does not
involve transferring any code, but rather setting up things so that
calls in the module using the active module are executed as remote
procedure calls to the active module. This occurs in the same way
independently of whether the active module and the using module are
in the same machine or in different machines across the network.

   Except for having to compile it in a special way (see below), an
active module is identical from the programmer point of view to an
ordinary module. A program using an active module imports it and uses
it in the same way as any other module, except that it uses " `use_active_module'"
rather than " `use_module'" (see below). Also, an active module has
an address (network address) which must be known in order to use it.
In order to use an active module it is necessary to know its address:
different "protocols" are provided for this purpose (see below).

   (1)

   From the implementation point of view, active modules are
essentially daemons: executables which are started as independent
processes at the operating system level. Communication with active
modules is implemented using sockets (thus, the address of an active
module is an IP socket address in a particular machine). Requests to
execute goals in the module are sent through the socket by remote
programs. When such a request arrives, the process running the active
module takes it and executes it, returning through the socket the
computed answers. These results are then taken and used by the remote
processes. Backtracking over such remote calls works as usual and
transparently. The only limitation (this may change in the future,
but it is currently done for efficiency reasons) is that all
alternative answers are precomputed (and cached) upon the first call
to an active module and thus _an active module should not export a
predicate which has an infinite number of answers_.

   The first thing to do is to select a method whereby the client(s)
(the module(s) that will use the active module) can find out in which
machine/port (IP address/socket number) the server (i.e., the active
module) will be listening once started, i.e., a "protocol" to
communicate with the active module. The easiest way to do this is to
make use of the redezvous methods which are provided in the Ciao
distribution in the `library/actmods' directory; currently,
`tmpbased...', `filebased...', and `webbased...'.

   The first one is based on saving the IP address and socket number
of the server in a file in a predefined directory (generally `/tmp',
but this can be changed by changing `tmpbased_common.pl').

   The second one is similar but saves the info in the directory in
which the server is started (as _<module_name>_`.addr'), or in the
directory that a `.addr' file, if it exists, specifies. The clients
must be started in the same directory (or have access to a file
`.addr' specifying the same directory). However, they can be started
in different machines, provided this directory is shared (e.g., by
NFS or Samba), or the file can be moved to an appropriate directory
on a different machine -provided the full path is the same.

   The third one is based on a name server for active modules. When
an active module is started, it communicates its address to the name
server. When the client of the active module wants to communicate
with it, it asks the name server the active module address. This is
all done transparently to the user. The name server must be running
when the active module is started (and, of course, when the
application using it is executed). The location of the name server
for an application must be specified in an application file named
`webbased_common.pl' (see below).

   These rendezvous methods are encoded in two modules: a first one,
called `...publish.pl', is used by the server to publish its info.
The second one, called `...locate.pl', is used by the client(s) to
locate the server info. For efficiency, the client methods maintain a
cache of addresses, so that the server information only needs to be
read from the file system the first time the active module is
accessed.

   Active modules are compiled using the `-a' option of the Ciao
compiler (this can also be done from the interactive top-level shell
using `make_actmod/2'). For example, issuing the following command:

       ciaoc -a 'actmods/filebased_publish' simple_server

   compiles the simple server example that comes with the
distribution (in the `actmods/example' directory). The
`simple_client_with_main' example (in the same directory) can be
compiled as usual:

       ciaoc simple_client_with_main

   Note that the client uses the `actmods' package, specifies the
rendezvous method by importing `library('actmods/filebased_locate')',
and explicitely imports the "remote" predicates (_implicit imports
will not work_). Each module using the `actmods' package _should only
use one of the rendezvous methods_.

   Now, if the server is running (e.g., `simple_server &' in Un*x or
double-clicking on it in Win32) when the client is executed it will
connect with the server to access the predicate(s) that it imports
from it.

   A simpler even client `simple_client.pl' can be loaded into the
top level and its predicates called as usual (and they will connect
with the server if it is running).

   ---------- Footnotes ----------

   (1) It is also possible to provide active modules via a WWW
address. However, we find it more straightforward to simply use
socket addresses. In any case, this is generally hidden inside the
access method and can be thus made transparent to the user.

100.0.1 Active module name servers
----------------------------------

An application using a name server for active modules must have a
file named `webbased_common.pl' that specifies where the name server
resides. It must have the `URL' and the path which corresponds to
that `URL' in the file system of the server machine (the one that
hosts the `URL') of the file that will hold the name server address.

   The current distribution provides a file `webbased_common.pl' that
can be used (after proper setting of its contents) for a server of
active modules for a whole installation. Alternatively, particular
servers for each application can be set up (see below).

   The current distribution also provides a module that can be used
as name server by any application. It is in file `examples/webbased_server/webbased_server.pl'.

   To set up a name server edit `webbased_common.pl' to change its
contents appropriately as described above (`URL' and corresponding
complete file path). Then recompile this library module:
         ciaoc -c webbased_common
   The name server has to be compiled as an active module itself:
         ciaoc -a actmods/webserver_publish webbased_server
   It has to be started in the server machine before the application
and its active modules are compiled.

   Alternatively, you can copy `webbased_common.pl' and use it to set
up name servers for particular applications. Currently, this is a bit
complicated. You have to ensure that the name server, the application
program, and all its active modules are compiled and executed with
the same `webbased_common.pl' module. One way to do this is to create
a subdirectory `actmods' under the directory of your application,
copy `webbased_common.pl' to it, modify it, and then compile the name
server, the application program, and its active modules using a
library path that guarantees that your `actmods' directory is located
by the compiler before the standard Ciao library. The same applies
for when running all of them if the library loading is dynamic.

   One way to do the above is using the `-u' compiler option. Assume
the following file:
          :- module(paths,[],[]).
          :- multifile library_directory/1.
          :- dynamic library_directory/1.
          :- initialization(asserta_fact(
     	library_directory('/root/path/to/my/particular/application') )).
   then you have file `webbased_common.pl' in a subdirectory
`actmods' of the above cited path. You have to compile the name
server, the active modules, and the rest of the application with:
         ciaoc -u paths -s ...
   to use your particular `webbased_common.pl' and to make
executables statically link libraries. If they are dynamic, then you
have to provide for the above library_directory path to be set up
upon execution. This can be done, for example, by including module
`paths' into your executables.

   Addresses of active modules are saved by the name server in a
subdirectory `webbased_db' of the directory where you start it --see
`examples/webbased_server/webbased_db/webbased_server'). This allows
to restart the server right away if it dies (since it saves its
state). This directory should be cleaned up regularly of addresses of
active modules which are no more active. To do this, stop the server
--by killing it (its pid is in `PATH/FILE'), and restart it after
cleaning up the files in the above mentioned directory.

100.0.2 Active modules as agents
--------------------------------

It is rather easy to turn Ciao active modules into agents for some
kind of applications. The directory `examples/agents' contains a
(hopefully) self-explanatory example.

100.1 Usage and interface (`actmods')
=====================================

   * *Library usage:*

     `:- use_package(actmods).'

     or

     `:- module(...,...,[actmods]).'

   * *New declarations defined:*

     `use_active_module/2'.

100.2 Documentation on new declarations (`actmods')
===================================================

 -- DECLARATION: use_active_module/2:
     *Usage:* :- `use_active_module(AModule, Imports)'.
        - _Description:_ Specifies that this code imports from the
          _active module_ defined in `AModule' the predicates in
          `Imports'. The imported predicates must be exported by the
          active module.

        - _The following properties should hold at call time:_

          `AModule' is a source name.   (`streams_basic:sourcename/1')

          `Imports' is a list of `predname's.   (`basic_props:list/2')

100.3 Known bugs and planned improvements (`actmods')
=====================================================

   * The package provides no means for security: the accessing
     application must take care of this (?).

   * It can happen that there is a unique process for an active
     module serving calls from several different simultaneous
     executions of the same application. In this case, there might be
     unwanted interactions (e.g., if the active module has state).

   * Applications may fail if the name server or an active module is
     restarted during execution of the application (since they
     restart at a different port than the one cached by the
     application).

   * One may want name servers to reside at a fixed and known machine
     and port number (this is known as a _service_ and is defined in
     `/etc/services' in a Un*x machine). Currently, the port number
     changes in each invocation of the server.

   * One may want to have one name server dedicated to a single
     application. Currently, there is no easy way to do this.

101 Breadth-first execution
***************************

*Author(s):* Daniel Cabeza, Manuel Carro.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.5#143 (2000/5/12, 13:54:34 CEST)

   This package implements breadth-first execution of predicates.
Predicates written with operators `'<-'/1' (facts) and `'<-'/2'
(clauses) are executed using breadth-first search. This may be useful
in search problems when a complete proof procedure is needed. An
example of code would be:
     :- module(chain, _, [bf]).

     test(bf) :- bfchain(a,d).
     test(df) :- chain(a,d).   % loops!

     bfchain(X,X) <- .
     bfchain(X,Y) <- arc(X,Z), bfchain(Z,Y).

     chain(X,X).
     chain(X,Y) :- arc(X,Z), chain(Z,Y).

     arc(a,b).
     arc(a,d).
     arc(b,c).
     arc(c,a).

   There is another version, called `bf/af', which ensures
AND-fairness by goal shuffling. This version correctly says "`no'"
executing the following test:
     :- module(sublistapp, [test/0,sublistapp/2], ['bf/af']).

     test :- sublistapp([a],[b]).

     sublistapp(S,L) <- append(_,S,Y), append(Y,_,L).

     append([], L, L) <- .
     append([X|Xs], L, [X|Ys]) <- append(Xs, L, Ys).

101.1 Usage and interface (`bf')
================================

   * *Library usage:*

     `:- use_package(bf).'

     or

     `:- module(...,...,[bf]).'

   * *New operators defined:*

     `<-/2' [1200,xfx], `<-/1' [1200,xf].

101.2 Known bugs and planned improvements (`bf')
================================================

   * Does not correctly work in user files.

102 Iterative-deepening execution
*********************************

*Author(s):* Claudio Vaucheret, Manuel Hermenegildo.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.7#119 (2001/8/28, 15:39:1 CEST)

   This package applies a _compiling control_ technique to implement _depth
first iterative deepening_ execution [Kor85]. It changes the usual
_depth-first_ computation rule by _iterative-deepening_ on those
predicates specifically marked. This is very useful in search
problems when a complete proof procedure is needed.

   When this computation rule is used, first all goals are expanded
only up to a given depth. If no solution is found or more solutions
are needed by backtracking, the depth limit is incremented and the
whole goal is repeated. Although it might seem that this approach is
very inefficient because all higher levels are repeated for the
deeper ones, it has been shown that is performs only about b/(b - 1)
times as many operations than the corresponding breadth-first search,
(where b is the branching factor of the proof tree) while the waste
of memory is the same as depth first.

   The usage is by means of the following directive:

   `:- iterative(Name, FirstCut, Formula).'

   which states than the predicate 'Name' given in functor/arity form
will be executed using iterative deepening rule starting at the depth
'FirstCut' with depth being incremented by the predicate 'Formula'.
This predicate compute the new depth using the previous one. It must
implement a dilating function i.e. the new depth must be greater. For
example, to start with depth 5 and increment by 10 you can write:

   `:- iterative(p/1,5,f).'

   `f(X,Y) :- Y is X + 10.'

   or if you prefer,

   `:- iterative(p/1,5,(_(X,Y):- Y is X + 10)).'

   You can also use a fourth parameter to set a limiting depth. All
goals below the given depth limit simply fail. Thus, with the
following directive:

   `:- iterative(p/1,5,(_(X,Y):- Y is X + 10),100).'

   all goals deeper than 100 will fail.

   An example of code using this package would be:

     :- module(example_id, _,[id]).

     test(id) :-
             idchain(a,d).
     test(df) :-
             chain(a,d).   % loops!

     :- iterative(idchain/2, 3, ( _(X,Z) :- Z is X + 1) ).

     idchain(X,X).
     idchain(X,Y) :-
             arc(X,Z),
             idchain(Z,Y).

     chain(X,X).
     chain(X,Y) :-
             arc(X,Z),
             chain(Z,Y).

     arc(a,b).
     arc(a,d).
     arc(b,c).
     arc(c,a).

   The order of solutions are first the shallower and then the
deeper. Solutions which are between two cutoff are given in the usual
left to right order. For example,

     % OLD EXAMPLE - Won't work!

     :- module(_, _, [det_hook]).

     :- use_module(engine(internals)).

     pr(I, X, Y) :-
             display(open(I)), nl,
             '$metachoice'(C),
             det_try(pr2(X, Y, C), (display(close_done(I)), nl), (display(close_abort(I)), nl)).

     pr2(X, _, _) :- X =< 0, !, fail.
     pr2(2, 2, C) :- '$metacut'(C).
     pr2(X, Y, C) :- (X = Y ; X1 is X - 1, pr2(X1, Y, C)).

     test1 :-
             pr(x, 4, X), pr(y, 4, Y), display(X), display(Y), nl, X = 1, Y = 3, !.

   It is possible to preserve the iterative-deepening behavior for
calls to predicates defined in other modules. These modules should
obviously also use this package. In addition _all_ predicates from
such modules should imported, i.e., the directive `:-
use_module(module)', should be used in this case instead of `:-
use_module(module,[...])'. Otherwise calls to predicates outside the
module will be treated in the usual way i.e. by depth-first
computation.

   Another complete proof procedure implemented is the `bf' package ( breadth
first execution).

102.1 Usage and interface (`id')
================================

   * *Library usage:*

     `:- use_package(id).'

     or

     `:- module(...,...,[id]).'

103 Constraint programming over rationals
*****************************************

*Author(s):* Christian Holzbaur, Daniel Cabeza.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#184 (2003/12/5, 14:7:53 CET)

   *Note:* This package is currently being adapted to the new
characteristics of the Ciao module system. This new version now works
right now to some extent, but it is under further development at the
moment. Use with (lots of) caution.

103.1 Usage and interface (`clpq')
==================================

   * *Library usage:*

     `:- use_package(clpq).'

     or

     `:- module(...,...,[clpq]).'

103.2 Other information (`clpq')
================================

103.2.1 Some CLP(Q) examples
----------------------------

(Other examples can be found in the source and library directories.)

   * 'Reversible' Fibonacci (clpq):

     :- module(_, [fib/2], []).
     :- use_package(clpq).

     fib(X,Y):- X .=. 0, Y .=. 0.
     fib(X,Y):- X .=. 1, Y .=. 1.
     fib(N,F) :-
             N .>. 1,
             N1 .=. N - 1,
             N2 .=. N - 2,
             fib(N1, F1),
             fib(N2, F2),
             F .=. F1+F2.

   * Matrix multiplication (clpq):

     :- use_package(clpq).
     :- use_module(library(write)).

     mmultiply([],_,[]).
     mmultiply([V0|Rest], V1, [Result|Others]):-
                 mmultiply(Rest, V1, Others),
                     multiply(V1,V0,Result).

     multiply([],_,[]).
     multiply([V0|Rest], V1, [Result|Others]):-
                 multiply(Rest, V1, Others),
                     vmul(V0,V1,Result).

     vmul([],[],0).
     vmul([H1|T1], [H2|T2], Result):-
             vmul(T1,T2, Newresult),
             Result .=. H1*H2+Newresult.

     matrix(1,[[1,2,3,4,5],[4,0,-1,5,6],[7,1,-2,8,9],[-1,0,1,3,2],[1,5,-3,2,4]]).
     matrix(2,[[3,2,1,0,-1],[-2,1,3,0,2],[1,2,0,-1,5],[1,3,2,4,5],[-5,1,4,2,2]]).

     %% Call with: ?- go(M).

     go(M):-
             matrix(1,M1),
             matrix(2,M2),
             mmultiply(M1, M, M2).

   * Queens (clpq):

     :- use_package(clpq).

     queens(N, Qs) :- constrain_values(N, N, Qs), place_queens(N, Qs).

     constrain_values(0, _N, []).
     constrain_values(N, Range, [X|Xs]) :-
             N .>. 0, X .>. 0, X .=<. Range,
             N1 .=. N - 1,
             constrain_values(N1, Range, Xs), no_attack(Xs, X, 1).

     no_attack([], _Queen, _Nb).
     no_attack([Y|Ys], Queen, Nb) :-
             Queen .<>. Y+Nb,
             Queen .<>. Y-Nb,
             Nb1 .=. Nb + 1,
             no_attack(Ys, Queen, Nb1).

     place_queens(0, _).
     place_queens(N, Q) :-
             N > 0, member(N, Q), N1 is N-1, place_queens(N1, Q).

103.3 Known bugs and planned improvements (`clpq')
==================================================

   * clp(Q) and clp(R) cannot be used simultaneously in the same
     program, or even within the same toplevel session.

104 Constraint programming over reals
*************************************

*Author(s):* Christian Holzbaur, Daniel Cabeza.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#227 (2003/12/22, 16:55:52 CET)

   *Note:* This package is currently being adapted to the new
characteristics of the Ciao module system. This new version now works
right now to some extent, but it under further development at the
moment. Use with (lots of) caution.

104.1 Usage and interface (`clpr')
==================================

   * *Library usage:*

     `:- use_package(clpr).'

     or

     `:- module(...,...,[clpr]).'

104.2 Other information (`clpr')
================================

104.2.1 Some CLP(R) examples
----------------------------

(Other examples can be found in the source and library directories.)

   * 'Reversible' Fibonacci (clpr):

     :- module(_, [fib/2], []).
     :- use_package(clpr).

     fib(X,Y):- X .=. 0, Y .=. 0.
     fib(X,Y):- X .=. 1, Y .=. 1.
     fib(N,F) :-
             N .>. 1,
             N1 .=. N - 1,
             N2 .=. N - 2,
             fib(N1, F1),
             fib(N2, F2),
             F .=. F1+F2.

   * Dirichlet problem for Laplace's equation (clpr):

     %
     % Solve the Dirichlet problem for Laplace's equation using
     % Leibman's five-point finit-differenc approximation.
     % The goal ?- go1 is a normal example, while the goal ?- go2
     % shows output constraints for a small region where the boundary conditions
     % are not specified.
     %
     :- use_package(clpq).
     :- use_module(library(format)).

     laplace([_, _]).
     laplace([H1, H2, H3|T]):-
             laplace_vec(H1, H2, H3),
             laplace([H2, H3|T]).

     laplace_vec([_, _], [_, _], [_, _]).
     laplace_vec([_TL, T, TR|T1], [ML, M, MR|T2], [_BL, B, BR|T3]):-
             B + T + ML + MR - 4 * M .=. 0,
             laplace_vec([T, TR|T1], [M, MR|T2], [B, BR|T3]).

     printmat([]).
     printmat([H|T]):-
             printvec(H),
             printmat(T).

     printvec([]):- nl.
     printvec([H|T]):-
             printrat(H),
             printvec(T).

     printrat(rat(N,D)) :- !,
             X is N/D,
             format(" ~2f",X).
     printrat(N) :-
             X is N*100,
             format(" ~2d",X).

     go1:-
             X =  [
           [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
         [100, _, _, _, _, _, _, _, _, _, 100],
         [100, _, _, _, _, _, _, _, _, _, 100],
         [100, _, _, _, _, _, _, _, _, _, 100],
         [100, _, _, _, _, _, _, _, _, _, 100],
         [100, _, _, _, _, _, _, _, _, _, 100],
         [100, _, _, _, _, _, _, _, _, _, 100],
         [100, _, _, _, _, _, _, _, _, _, 100],
         [100, _, _, _, _, _, _, _, _, _, 100],
         [100, _, _, _, _, _, _, _, _, _, 100],
         [100, 100, 100, 100, 100, 100, 100, 100, 100, 100, 100]
         ],
             laplace(X),
             printmat(X).

     % Answer:
     % 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.00
     % 100.00 51.11 32.52 24.56 21.11 20.12 21.11 24.56 32.52 51.11 100.00
     % 100.00 71.91 54.41 44.63 39.74 38.26 39.74 44.63 54.41 71.91 100.00
     % 100.00 82.12 68.59 59.80 54.97 53.44 54.97 59.80 68.59 82.12 100.00
     % 100.00 87.97 78.03 71.00 66.90 65.56 66.90 71.00 78.03 87.97 100.00
     % 100.00 91.71 84.58 79.28 76.07 75.00 76.07 79.28 84.58 91.71 100.00
     % 100.00 94.30 89.29 85.47 83.10 82.30 83.10 85.47 89.29 94.30 100.00
     % 100.00 96.20 92.82 90.20 88.56 88.00 88.56 90.20 92.82 96.20 100.00
     % 100.00 97.67 95.59 93.96 92.93 92.58 92.93 93.96 95.59 97.67 100.00
     % 100.00 98.89 97.90 97.12 96.63 96.46 96.63 97.12 97.90 98.89 100.00
     % 100.00 100.00 100.00 100.00 100.00 100.00 100.00 100.00 100.00 100.00 100.00

     go2([B31, M32, M33, B34, B42, B43, B12, B13, B21, M22, M23, B24]) :-
             laplace([
                 [_B11, B12, B13, _B14],
                 [B21, M22, M23, B24],
                 [B31, M32, M33, B34],
                 [_B41, B42, B43, _B44]
         ]).

     % Answer:
     %
     % B34.=. -4*M22+B12+B21+4*M33-B43,
     % M23.=.4*M22-M32-B12-B21,
     % B31.=. -M22+4*M32-M33-B42,
     % B24.=.15*M22-4*M32-4*B12-4*B21-M33-B13 ?

104.3 Known bugs and planned improvements (`clpr')
==================================================

   * clp(Q) and clp(R) cannot be used simultaneously in the same
     program, or even within the same toplevel session.

105 Fuzzy Prolog
****************

*Author(s):* Claudio Vaucheret, Sergio Guadarrama, Francisco Bueno.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#339 (2004/4/22, 7:49:9 CEST)

   This package impements an extension of prolog to deal with
uncertainty. We implement a fuzzy prolog that models interval-valued
fuzzy logic. This approach is more general than other fuzzy prologs
in two aspects:

  1. Truth values are sub-intervals on [0,1]. In fact, it could be a
     finite union of sub-intervals, as we will see below. Having a
     unique truth value is a particular case modeled with a unitary
     interval.

  2. Truth values are propagated through the rules by means of a set
     of _aggregation operators_. The definition of an _aggregation
     operator_ is a generalization that subsumes conjunctive
     operators (triangular norms as min, prod, etc.), disjunctive
     operators (triangular co-norms as max, sum, etc.), average
     operators (averages as arithmetic average, cuasi-linear average,
     etc.) and hybrid operators (combinations of previous operators).

   We add uncertainty using CLP(R) instead of implementing a new
fuzzy resolution as other fuzzy prologs. In this way, we use the
original inference mechanism of Prolog, and we use the constraints
and its operations provided by CLP(R) to handle the concept of
partial truth. We represent intervals as constrains over real numbers
and _aggregation operators_ as operations with constraints.

   Each fuzzy predicate has an additional argument which represents
its truth value. We use ":~" instead of ":-" to distinguish fuzzy
clauses from prolog clauses. In fuzzy clauses, truth values are
obtained via an aggregation operator. There is also some syntactic
sugar for defining fuzzy predicates with certain membership
functions, the fuzzy counterparts of crisp predicates, and the fuzzy
negation of a fuzzy predicate.

105.1 Usage and interface (`fuzzy')
===================================

   * *Library usage:*

     `:- use_package(fuzzy).'

     or

     `:- module(...,...,[fuzzy]).'

   * *Exports:*
        - _Predicates:_

          `:#/2', `fuzzy_predicate/1', `fuzzy/1', `fnot/1', `:~/2', `=>/4'.

        - _Properties:_

          `fuzzybody/1'.

        - _Regular Types:_

          `faggregator/1'.

   * *New operators defined:*

     `:~/2' [1200,xfx], `:~/1' [1200,xf], `:=/2' [1200,xfx], `:=/1'
     [1200,xf], `:#/2' [1200,xfx], `=>/1' [1175,fx], `fnot/1'
     [1150,fx], `aggr/1' [1150,fx], `##/2' [1120,xfy], `<#/2'
     [1120,xfy], `#>/2' [1120,xfy], `fuzzy/1' [1150,fx], `fuzzy_predicate/1'
     [1190,fx], `fuzzy_discrete/1' [1190,fx].

   * *New declarations defined:*

     `aggr/1'.

105.2 Documentation on new declarations (`fuzzy')
=================================================

 -- DECLARATION: aggr/1:
     *Usage:* :- `aggr(Name)'.
        - _Description:_ Declares `Name' an aggregator. Its binary
          definition has to be provided. For example:
               :- aggr myaggr.

               myaggr(X,Y,Z):- Z .=. X*Y.
          defines an aggregator identical to `prod'.

        - _The following properties hold at call time:_

          `Name' is an atomic term (an atom or a number).
          (`basic_props:constant/1')

105.3 Documentation on exports (`fuzzy')
========================================

 -- PREDICATE: :#/2:
     *Usage:* `:#(Name, Decl)'
        - _Description:_ Defines fuzzy predicate `Name' from the
          declaration `Decl'.

        - _The following properties hold upon exit:_

          `Name' is a Name/Arity structure denoting a predicate name:
               predname(P/A) :-
                       atm(P),
                       nnegint(A).

          (`basic_props:predname/1')

          `Decl' is one of the following three:
               fuzzydecl(fuzzy_predicate(_1)).
               fuzzydecl(fuzzy(_1)).
               fuzzydecl(fnot(_1)).

          (`user(... /fuzzy_doc):fuzzydecl/1')

 -- PREDICATE: fuzzy_predicate/1:
     *Usage:* `fuzzy_predicate(Domain)'
        - _Description:_ Defines a fuzzy predicate with piecewise
          linear continuous membership function. This is given by
          `Domain', which is a list of pairs of domain-truth values,
          in increasing order and exhaustive. For example:
               young :# fuzzy_predicate([(0,1),(35,1),(45,0),(120,0)]).
          defines the predicate:
               young(X,1):- X .>=. 0, X .<. 35.
               young(X,M):- X .>=. 35, X .<. 45, 10*M .=. 45-X.
               young(X,0):- X .>=. 45, X .=<. 120.

        - _The following properties should hold at call time:_

          `Domain' is a list.   (`basic_props:list/1')

 -- PREDICATE: fuzzy/1:
     *Usage:* `fuzzy(Name)'
        - _Description:_ Defines a fuzzy predicate as the fuzzy
          counterpart of a crisp predicate `Name'. For example,
               p_f :# fuzzy p/2
          defines a new fuzzy predicate `p_f/3' (the last argument is
          the truth value) with truth value equal to 0 if `p/2' fails
          and 1 otherwise.

        - _The following properties should hold at call time:_

          `Name' is a Name/Arity structure denoting a predicate name:
               predname(P/A) :-
                       atm(P),
                       nnegint(A).

          (`basic_props:predname/1')

 -- PREDICATE: fnot/1:
     *Usage:* `fnot(Name)'
        - _Description:_ Defines a fuzzy predicate as the fuzzy
          negation of another fuzzy predicate `Name'. For example,
               notp_f :# fnot p_f/3
          defines the predicate:
               notp_f(X,Y,M) :-
                       p_f(X,Y,Mp),
                       M .=. 1 - Mp.

        - _The following properties should hold at call time:_

          `Name' is a Name/Arity structure denoting a predicate name:
               predname(P/A) :-
                       atm(P),
                       nnegint(A).

          (`basic_props:predname/1')

 -- PREDICATE: :~/2:
     *Usage:* `:~(Head, Body)'
        - _Description:_ Defines a fuzzy clause for a fuzzy
          predicate. The clause contains calls to either fuzzy or
          crisp predicates. Calls to crisp predicates are
          automatically fuzzified. The last argument of `Head' is the
          truth value of the clause, which is obtained as the
          aggregation of the truth values of the body goals. An
          example:
               :- module(young2,_,[fuzzy]).

               young_couple(X,Y,Mu) :~ min
                       age(X,X1),
                       age(Y,Y1),
                       young(X1,MuX),
                       young(Y1,MuY).

               age(john,37).
               age(rose,39).

               young :# fuzzy_predicate([(0,1),(35,1),(45,0),(120,0)]).
          so that:
               ?- young_couple(john,rose,M).

               M .=. 0.6 ?

        - _The following properties should hold at call time:_

          `Head' is a term which represents a goal, i.e., an atom or
          a structure.   (`basic_props:callable/1')

          `Body' is a clause body plus an optional aggregation
          operator.   (`user(... /fuzzy_doc):fuzzybody/1')

 -- PROPERTY: fuzzybody/1:
     A clause body, optionally prefixed by the name of an aggregation
     operator. The agregators currently provided are listed under
     `faggregator/1'. By default, the aggregator used is `min'.

     *Usage:* `fuzzybody(B)'
        - _Description:_ `B' is a clause body plus an optional
          aggregation operator.

 -- REGTYPE: faggregator/1:
     The first three are, respectively, the T-norms: minimum,
     product, and Lukasiewicz's. The last three are their
     corresponding T-conorms. Aggregators can be defined by the user,
     see `aggr/1'.
          faggregator(min).
          faggregator(prod).
          faggregator(luka).
          faggregator(max).
          faggregator(dprod).
          faggregator(dluka).

     *Usage:* `faggregator(Aggr)'
        - _Description:_ `Aggr' is an aggregator which is cumulative,
          i.e., its application to several values by iterating
          pairwise the binary operation is safe.

 -- PREDICATE: =>/4:
     *Usage:* `=>(Aggr, A, B, Truth)'
        - _Description:_ The fuzzy implication `A => B' defined by
          aggregator `Aggr', resulting in the truth value `Truth'.

        - _The following properties should hold at call time:_

          `Aggr' is an aggregator which is cumulative, i.e., its
          application to several values by iterating pairwise the
          binary operation is safe.   (`user(...
          /fuzzy_doc):faggregator/1')

          `A' is a term which represents a goal, i.e., an atom or a
          structure.   (`basic_props:callable/1')

          `B' is a term which represents a goal, i.e., an atom or a
          structure.   (`basic_props:callable/1')

          `Truth' is a free variable.   (`term_typing:var/1')

105.4 Other information (`fuzzy')
=================================

An example program:
     :- module(dicesum5,_,[fuzzy]).

     % this example tries to measure which is the possibility
     % that a couple of values, obtained throwing two loaded dice, sum 5. Let
     % us suppose we only know that one die is loaded to obtain a small value
     % and the other is loaded to obtain a large value.
     %
     % the query is  ? sum(5,M)
     %

     small :# fuzzy_predicate([(1,1),(2,1),(3,0.7),(4,0.3),(5,0),(6,0)]).
     large :# fuzzy_predicate([(1,0),(2,0),(3,0.3),(4,0.7),(5,1),(6,1)]).

     die1(X,M) :~
             small(X,M).

     die2(X,M) :~
             large(X,M).

     two_dice(X,Y,M):~ prod
             die1(X,M1),
             die2(Y,M2).

     sum(2,M) :~
             two_dice(1,1,M1).

     sum(5,M) :~ dprod
             two_dice(4,1,M1),
             two_dice(1,4,M2),
             two_dice(3,2,M3),
             two_dice(2,3,M4).
   There are more examples in the subdirectory `fuzzy/examples' of
the distribution.

105.5 Known bugs and planned improvements (`fuzzy')
===================================================

   * General aggregations defined by users.

   * Inconsistent behaviour of meta-calls in fuzzy clauses.

   * Some meta-predicate constructions need be added, specially for
     'disjunctive' fuzzy clauses, e.g., `sum/2' in the dice example.

106 Object oriented programming
*******************************

*Author(s):* Angel Fernandez Pineda.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.3#63 (1999/9/29, 19:54:17 MEST)

   O'Ciao is a set of libraries which allows object-oriented
programming in Ciao Prolog. It extends the Ciao Prolog module system
by introducing two new concepts:

   * Inheritance.

   * Instantiation.

   _Polymorphism_ is the third fundamental concept provided by object
oriented programming. This concept is not mentioned here since
*traditional PROLOG systems are polymorphic by nature*.

   Classes are declared in the same way as modules. However, they may
be enriched with inheritance declarations and other object-oriented
constructs. For an overview of the fundamentals of O'Ciao, see
`http://www.clip.dia.fi.upm.es/~clip/papers/ociao-tr.ps.gz'. However,
we will introduce the concepts in a tutorial way via examples.

106.1 Early examples
====================

The following one is a very simple example which declares a class - a
simple stack. Note that if you replace _class/1_ declaration with a
_module/1_ declaration, it will compile correctly, and can be used as
a normal Prolog module.

     %%----------------------------------------------%%
     %% A class for stacks.                          %%
     %%----------------------------------------------%%

     %% Class declaration: the current source defines a class.
     :- class(stack,[],[]).

     % State declaration: storage/1 is an attribute.
     :- dynamic storage/1.

     % Interface declaration: the following predicates will
     % be available at run-time.
     :- export(push/1).
     :- export(pop/1).
     :- export(top/1).
     :- export(is_empty/0).

     % Methods

     push(Item) :-
             nonvar(Item),
             asserta_fact(storage(Item)).

     pop(Item) :-
             var(Item),
             retract_fact(storage(Item)).

     top(Top) :-
             storage(Top), !.

     is_empty :-
             storage(_), !, fail.
     is_empty.

   If we load this code at the Ciao toplevel shell:

             ?- use_package(objects).

             yes
             ?- use_class(library('class/examples/stack')).

             yes
             ?-

   we can create two stack _instances_ :

             ?- St1 new stack,St2 new stack.

             St1 = stack('9254074093385163'),
             St2 = stack('9254074091') ? ,

   and then, we can operate on them separately:

             1 ?- St1:push(8),St2:push(9).

             St1 = stack('9254074093385163'),
             St2 = stack('9254074091') ?

             yes
             1 ?- St1:top(I),St2:top(K).

             I = 8,
             K = 9,
             St1 = stack('9254074093385163'),
             St2 = stack('9254074091') ?

             yes
             1 ?-

   The interesting point is that there are two stacks. If the
previous example had been a normal module, we would have a stack ,
but *only one* stack.

   The next example introduces the concepts of _inheritable_
predicate, _constructor_, _destructor_ and _virtual method_. Refer to
the following sections for further explanation.

     %%----------------------------------------------%%
     %% A generic class for item storage.            %%
     %%----------------------------------------------%%
     :- class(generic).

     % Public interface declaration:
     :- export([set/1,get/1,callme/0]).

     % An attribute
     :- data datum/1.

     % Inheritance declaration: datum/1 will be available to
     % descendant classes (if any).
     :- inheritable(datum/1).

     % Attribute initialization: attributes are easily initialized
     % by writing clauses for them.
     datum(none).

     % Methods

     set(X) :-
             type_check(X),
             set_fact(datum(X)).

     get(X) :-
             datum(X).

     callme :-
             a_virtual(IMPL),
             display(IMPL),
             display(' implementation of a_virtual/0 '),
             nl.

     % Constructor: in this case, every time an instance
     % of this class is created, it will display a message.
     generic :-
             display(' generic class constructor '),
             nl.

     % Destructor: analogous to the previous constructor,
     % it will display a message every time an instance
     % of this class is eliminated.
     destructor :-
             display(' generic class destructor '),
             nl.

     % Predicates:
     % cannot be called as messages (X:method)

     % Virtual declaration: tells the system to use the most
     % descendant implementation of a_virtual/1 when calling
     % it from inside this code (see callme/0).
     % If there is no descendant implementation for it,
     % the one defined bellow will be used.
     :- virtual a_virtual/1.

     a_virtual(generic).

     :- virtual type_check/1.

     type_check(X) :-
             nonvar(X).

   And the following example, is an extension of previous class. This
is performed by establishing an inheritance relationship:

     %%----------------------------------------------%%
     %% This class provides additional functionality %%
     %% to the "generic" class.                      %%
     %%----------------------------------------------%%
     :- class(specific).

     % Establish an inheritance relationship with class "generic".
     :- inherit_class(library('class/examples/generic')).

     % Override inherited datum/1.
     % datum/1 is said to be overriden because there are both an
     % inherited definition (from class "generic") and a local one,
     % which overrides the one inherited.
     :- data datum/1.
     :- inheritable datum/1.

     % Extend the public interface inherited from "generic".
     % note that set/1 and a_virtual/0 are also overriden.
     % undo/0 is a new functionality added.
     :- export([set/1,undo/0]).

     % Methods

     set(Value) :-
             inherited datum(OldValue),
             !,
             inherited set(Value),
             asserta_fact(datum(OldValue)).
     set(Value) :-
             inherited set(Value).

     undo :-
             retract_fact(datum(Last)), !,
             asserta_fact(inherited(datum(Last))).
     undo :-
             retractall_fact(inherited(datum(_))).

     % Constructor
     specific :-
             generic,
             retractall_fact(inherited(datum(_))),
             display(' specific class constructor '),
             nl.

     % Destructor
     destructor :-
             display(' specific class destructor '),
             nl.

     % Predicates

     % New implementation of a_virtual/1.
     % Since this predicate was declared virtual, the
     % implementation below will be called from the inherited
     % method callme/0 instead of the version defined at "generic".
     a_virtual(specific).

   *Additional examples* may be found on the _library/class/examples_
directory relative to your Ciao Prolog instalation.

106.2 Recommendations on when to use objects
============================================

We would like to give some advice in the use of object oriented
programming, in conjunction with the declarative paradigm.

   You should reconsider using O'Ciao in the following cases:

   * The pretended "objects" have no state,i.e., no data or dynamic
     predicates. In this case, a normal module will suffice.

   * There is state, but there will be only one instance of a
     pretended class. Again, a module suffices.

   * The "objects" are data structures (list,trees,etc) already
     supported by Prolog. However, it does make sense to model, using
     objects, data structures whose change implies a side-effect such
     as drawing a particular window on the screen.

   We recommend the usage of O'Ciao in the following cases:

   * You feel you will need to have several copies of a "module".

   * Local copies of a module are needed instead of a global module
     beeing modified by several ones.

   * The "classes" are a representation of external entities to
     Prolog. For example: the X-Window system.

   * There is state or code outside the Prolog system which needs to
     be manipulated. For example: interfaces to Java or Tcl/Tk code.

   * You are not familiar with Prolog, but you know about object
     oriented programming. O'Ciao may be used as a learning tool to
     introduce yourself on the declarative programming paradigm.

106.3 Limitations on object usage
=================================

O'Ciao run-time speed is limited by the usage of meta-programming
structures, for instance: `X = (Object:mymethod(25)), call(X)'.
O'Ciao will optimize static manipulation of objects (those that can
be determined at compile time).

107 Declaring classes and interfaces
************************************

*Author(s):* Angel Fernandez Pineda.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.7#162 (2001/12/4, 16:2:58 CET)

   O'Ciao classes are declared in the same way as traditional prolog
modules. The general mechanism of _source expansion_ will translate
object-oriented declarations to normal prolog code. This is done
transparently to the user.

   Abstract _interfaces_ are restricted classes which declare
exported predicates with no implementation. The implementation itselt
will be provided by some class using an `implements/1' declaration.
Only `export/1' and `data/1' declarations are allowed when declaring
an interface. Normal classes may treated as interfaces just ignoring
all exported predicate implementations.

107.1 Usage and interface (`class')
===================================

   * *Library usage:*

     To declare a class the compiler must be told to use the `class'
     _source expansion_. To do so, source code must start with a
     module declaration which loads the class package:
                     :- class(ClassName).
     or a `module/3' declaration, as follows:
                     :- module(ClassName,[],[class]).

     interfaces are declared in a similar way:
                     :- interface(InterfaceName).

     Please, do not use SICStus-like module declaration, with a
     non-empty export list. In other case, some non-sense errors will
     be reported by normal Ciao module system.

     Most of the regular Ciao declarations may be used when defining
     a class, such as `concurrent/1', `dynamic/1', `discontiguous/1', `multifile/1',
     and so on.

     However, there are some restrictions wich apply to those
     declarations:
        * `meta_predicate/1' declaration is not allowed to hold _addmodule
          and pred(N) meta-arguments_, except for previously declared
          multifiles.

        * Attribute and multifile predicates must be declared before
          any clause of the related predicate.

        * There is no sense in declaring an attribute as
          meta_predicate.

     It is a good practique to put all your declarations at the very
     begining of the file, just before the code itself.

   * *Exports:*
        - _Predicates:_

          `inherited/1', `self/1', `constructor/0', `destructor/0'.

   * *New declarations defined:*

     `export/1', `public/1', `inheritable/1', `data/1', `dynamic/1', `concurrent/1', `inherit_class/1', `implements/1', `virtual/1'.

   * *Other modules used:*
        - _System library modules:_

          `objects/objects_rt'.

107.2 Documentation on new declarations (`class')
=================================================

 -- DECLARATION: export/1:
     Declares a method or attribute to be part of the _public
     interface_.

     The public interface is the set of predicates wich will be
     accesible from any code establishing an usage relationship with
     this class (see `use_class/1' for further information).

     Publishing an attribute or method is very similar to _exporting_
     a predicate in a Prolog module.

     Whether an inherited and exported predicate is overriden, it
     must be explicitly exported again.

     An inherited (but not exported) predicate may become exported,
     without overriding it by the usage of this declaration.

     *Usage:* :- `export(Spec)'.
        - _Description:_ `Spec' will be part of the public (exported)
          interface.

        - _The following properties should hold at call time:_

          `Spec' is a method or attribute specification.
          (`objects_rt:method_spec/1')

 -- DECLARATION: public/1:
     Just an alias for `export/1'.

     *Usage:* :- `public(Spec)'.
        - _Description:_ This declaration may be used instead of `export/1'.

        - _The following properties should hold at call time:_

          `Spec' is a method or attribute specification.
          (`objects_rt:method_spec/1')

 -- DECLARATION: inheritable/1:
     Declares a method or attribute to be inherited by descendant
     classes. Notice that all *public predicates are inheritable by
     default*. There is no need to mark them as inheritable.

     Traditionaly, object oriented languages makes use of the _protected_
     concept. Inheritable/1 may be used as the same concept.

     The set of inheritable predicates is called the _inheritable
     interface_.

     *Usage:* :- `inheritable(MethodSpec)'.
        - _Description:_ `MethodSpec' is accessible to descendant
          classes.

        - _The following properties should hold at call time:_

          `MethodSpec' is a method or attribute specification.
          (`objects_rt:method_spec/1')

 -- DECLARATION: data/1:
     Declares an _attribute_ at current class. Attributes are used to
     build the internal state of instances. So, each instance will
     own a particular copy of those attribute definitions. In this
     way, one instance may have different state from another.

     O'Ciao attributes are restricted to hold simple facts. It is not
     possible to hold a Head :- Body clause at an instance attribute.

     Notice that attributes are _multi-evaluated_ by nature, and may
     be manipulated by the habitual *assert/retract* family of
     predicates.

     Attributes may also be initialized. In order to do so, simply
     put some clauses after the attribute definition. Each time an
     instance is created, its initial state will be built from those _initialization
     clauses_.

     Note: whether a data/1 declaration appears inside an interface,
     it will be automatically exported.

     *Usage:* :- `data Spec'.
        - _Description:_ `Spec' is an attribute.

        - _The following properties should hold at call time:_

          `Spec' is a method or attribute specification.
          (`objects_rt:method_spec/1')

 -- DECLARATION: dynamic/1:
     Just an alias for `data/1'.

     *Usage:* :- `dynamic Spec'.
        - _Description:_ You may use this declaration instead of `data/1'.

        - _The following properties should hold at call time:_

          `Spec' is a method or attribute specification.
          (`objects_rt:method_spec/1')

 -- DECLARATION: concurrent/1:
     Declares a _concurrent attribute_ at current class. Concurrent
     attributes are just the same as normal attributes, those
     declared using `data/1', except for they may freeze the calling
     thread instead of failing when no more choice points are
     remaining on the concurrent attribute.

     In order to get more information about concurrent behavior take
     a look to the concurrent/1 built-in declaration on Ciao Prolog
     module system.

     *Usage:* :- `concurrent Spec'.
        - _Description:_ Declares `Spec' to be a concurrent attribute.

        - _The following properties should hold at call time:_

          `Spec' is a method or attribute specification.
          (`objects_rt:method_spec/1')

 -- DECLARATION: inherit_class/1:
     Makes any public and/or inheritable predicate at inherited class
     to become accesible by any instance derived from current class.

     Inherited class is also called the _super class_.

     Only one inherit_class/1 declaration is allowed to be present at
     current source.

     Notice that inheritance is public by default. Any public and/or
     inheritable declaration will remain the same to descendant
     classes. However, any inherited predicate may be _overriden_
     (redefined).

     A predicate is said to be _overriden_ when it has been inherited
     from super class, but there are clauses (or a `data/1'
     declaration) present at current class for such a predicate.

     Whether a *public* predicate is overriden, the local definition
     must also be exported, otherwise an error is reported.

     Whether an *inheritable* predicate (not public) is overriden,
     the local definition must also be marked as inheritable or
     exported, otherwise an error is also reported.

     Note: whether inherit_class/1 appears inside an interface, it
     will be used as an `implements/1' declaration.

     *Usage:* :- `inherit_class(Source)'.
        - _Description:_ Establish an _inheritance relationship_
          between current class and the class defined at `Source'
          file.

        - _The following properties should hold at call time:_

          `Source' is a valid path to a prolog file containing a
          class declaration (without .pl extension).
          (`objects_rt:class_source/1')

 -- DECLARATION: implements/1:
     Forces current source to provide an implementation for the given
     interface file. Such interface file may declare another class or
     a specific interface.

     Every public predicate present at given interface file will be
     automatically declared as public at current source, so you
     *must* provide an implementation for such predicates.

     The effect of this declaration is called _interface
     inheritance_,and there is no restriction on the number of
     implements/1 declarations present at current code.

     *Usage:* :- `implements(Interface)'.
        - _Description:_ Current source is supposed to provide an
          implementation for `Interface'.

        - _The following properties should hold at call time:_

          `Interface' is a valid path to a prolog file containing a
          class declaration or an interface declaration (without .pl
          extension).   (`objects_rt:interface_source/1')

 -- DECLARATION: virtual/1:
     This declaration may be used whenever descendant classes are to
     implement different versions of a given predicate.

     _virtual_ predicates give a chance to handle, in an uniform way,
     different implementations of the same functionality.

     Whether a virtual predicate is declared as a method, there must
     be at least one clause of it present at current source. Whenever
     no special implementation is needed at current class, a
     never-fail/allways-fail clause may be defined (depending on your
     needs). For example:

             :- virtual([ test1/1 , test2/2 ]).
             test1(_).
             test2(_,_) :- fail.

     This kind of virtual methods are also known as _abstract
     methods_, since implementation is fully delegated to descendant
     classes.

     An attribute may be also declared as a virtual one, but there is
     no need to write clauses for it.

     *Usage:* :- `virtual(VirtualMethodSpec)'.
        - _Description:_ All calls to `VirtualMethodSpec' predicate
          in current source will use the most descendant
          implementation of it.

        - _The following properties should hold at call time:_

          `VirtualMethodSpec' is a method specification.
          (`objects_rt:virtual_method_spec/1')

107.3 Documentation on exports (`class')
========================================

 -- PREDICATE: inherited/1:
     This predicate qualificator may be used whenever you need to
     reference an attribute or method on the super class.

     Since methods and attributes may be redefined, this qualificator
     is need to distinguish between a locally declared predicate and
     the inherited one, which has the same name.

     There is no need to use inherited/1 if a particular inherited
     predicate has not been redefined at current class.

     *Usage:* `inherited(Goal)'
        - _Description:_ References a given `Goal' at the super class

        - _The following properties should hold at call time:_

          `Goal' is a term which represents a goal, i.e., an atom or
          a structure.   (`basic_props:callable/1')

 -- PREDICATE: self/1:
     Determines which instance is currently executing self/1 goal.

     Predicate will fail if argument is not a free variable.
     Otherwise, it will allways succeed, retrieving the instance
     identifier which is executing current code.

     This functionality is very usefull since an object must have
     knowledge of other object's identifier in order to send messages
     to it.For example:

     :- concurrent ack/0.

     send_data_to_object(Data,Obj) :- self(X), Obj:take_this(Data,X),
     current_fact(ack).

     acknowledge :- asserta_fact(ack).

     take_this(Data,Sender) :- validate_data(Data),
     Sender:acknowledge.

     *Usage:* `self(Variable)'
        - _Description:_ Retrieves current instance identifier in
          `Variable'

        - _The following properties should hold at call time:_

          `Variable' is a free variable.   (`term_typing:var/1')

        - _The following properties should hold upon exit:_

          `Variable' is an unique term which identifies an object.
          (`objects_rt:instance_id/1')

 -- PREDICATE: constructor/0:
     A _constructor_ is a special case of method which complains the
     following conditions:

        * The constructor functor matches the current class name.

        * A constructor may hold any number of arguments.

        * If an inheritance relationship was defined, an inherited
          constructor must be manually called (see below).

        * When instance creation takes place, any of the declared
          constructors are implicitly called. The actual constructor
          called depends on the `new/2' goal specified by the user.

     This is a simple example of constructor declaration for the foo
     class:

                     foo :-
                         display('an instance was born').

     Constructor declaration is not mandatory, and there may be more
     than one constructor declarations (with different arity) at the
     source code.

     This functionality is usefull when some computation is needed at
     instance creation. For example: opening a socket, clearing the
     screen, etc.

     Whenever an inheritance relationship is established, and there
     is any constructor defined at the super class, you must call
     manually an inherited constructor. Here is an example:

                     :- class(foo).
                     :- inherit_class(myclass).

                     foo :-
                         myclass(0),
                         display('an instance was born').

                     foo(N) :- myclass(N).

     Consequences may be unpredictable, if you forget to call an
     inherited constructor. You should also take care not to call an
     inherited constructor twice.

     All defined constructors are inheritable by default. A
     constructor may also be declared as public (by the user), but it
     is not mandatory.

     *Usage:*
        - _Description:_ Constructors are implicitly declared

 -- PREDICATE: destructor/0:
     A _destructor_ is a special case of method which will be
     automatically called when instance destruction takes place.

     A destructor will never be wanted to be part of the public
     interface, and there is no need to mark them as inheritable,
     since all inherited destructors are called by O'Ciao just before
     yours.

     This is a simple example of destructor declaration:

                     destructor :-
                         display('goodbye, cruel world!!!').

     Destructor declaration is not mandatory. Failure or sucess of
     destructors will be ignored by O'Ciao, and they will be called
     only once.

     This functionality is useful when some computation is need at
     instance destruction. For example: closing an open file.

     *Usage:*
        - _Description:_ Destructors are implicitly declared

107.4 Other information (`class')
=================================

This describes the errors reported when declaring a class or an
interface. The first section will explain compile-time errors, this
is, any semantic error which may be determined at compile time. The
second section will explain run-time errors, this is, any exception
that may be raisen by the incorrect usage of O'Ciao. Some of those
errors may be not reported at compile time, due to the use of
meta-programational structures. For example:

   `functor(X,my_method,0),call(X).'

   O'Ciao is not able to check whether my_method/0 is a valid method
or not. So, this kind of checking is left to run time.

107.4.1 Class and Interface error reporting at compile time
-----------------------------------------------------------

   * *ERROR : multiple inheritance not allowed.*

     There are two or more inherit_class/1 declarations found at your
     code. Only one declaration is allowed, since there is no
     multiple code inheritance support.

   * *ERROR : invalid inheritance declaration.*

     The given parameter to inherit_class/1 declaration is not a
     valid path to a Prolog source.

   * *ERROR : sorry, addmodule meta-arg is not allowed at _F/A_. *

     You are trying to declare _F/A_ as meta-predicate, and one of
     the meta-arguments is _addmodule_. This is not allowed in O'Ciao
     due to implementation restrictions. For example:

     `:- meta_predicate example(addmodule).'

     `example(X,FromModule) :- call(FromModule:X).'

   * *ERROR : invalid attribute declaration for _Arg_. *

     Argument to data/1 or dynamic/1 declaration is not a valid
     predicate specification of the form _Functor/Arity_. For example:

     `:- data attr.'

     `:- dynamic attr(_).'

     `:- data attr/m.'

     etc,etc...

   * *ERROR : pretended attribute _F/A_ was assumed to be a method.*

     You put some clauses of _F/A_ before the corresponding data/1 or
     dynamic/1 declaration. For example:

     `attr(initial_value).'

     `:- data attr/1.'

     It is a must to declare attributes before any clause of the
     given predicate.

   * *ERROR : destructor/0 is not allowed to be an attribute.*

     There is a :- data(destructor/0) or :- dynamic(destructor/0).
     declaration in your code. This is not allowed since destructor/0
     is a reserved predicate, and must be allways a method.

   * *ERROR : _Constructor_ is not allowed to be an attribute.*

     As the previos error, you are trying to declare a constructor as
     an attribute. A constructor must be allways a method.

   * *ERROR : invalid multifile: destructor/0 is a reserved
     predicate.*

     There is a :- multifile(destructor/0). declaration in your code.
     This is not allowed since destructor/0 is a reserved predicate,
     and must be allways a method.

   * *ERROR : invalid multifile: _Constructor_ is a reserved
     predicate.*

     As the previos error, you are trying to declare a constructor as
     a multifile. Any constructor must allways be a method.

   * *ERROR : multifile declaration of _F/A_ ignored: it was assumed
     to be a method.*

     You put some clauses of _F/A_ before the corresponding
     multifile/1 declaration. For example:

     example(a,b).

     `:- multifile example/2.'

     Multifile predicates must be declared before any clause of the
     given predicate.

   * *ERROR : invalid multifile declaration: multifile(_Arg_). *

     Given argument to multifile/1 declaration is not a valid
     predicate specification, of the form _Functor/Arity_.

   * *ERROR : invalid public declaration: _Arg_. *

     Given argument _Arg_ to public/1 or export/1 declaration is not
     a valid predicate specification, of the form _Functor/Arity_.

   * *ERROR : invalid inheritable declaration: inheritable(_Arg_). *

     Given argument _Arg_ to inheritable/1 declaration is not a valid
     predicate specification, of the form _Functor/Arity_.

   * *ERROR : destructor/0 is not allowed to be virtual.*

     There is a :- virtual(destructor/0) declaration present at your
     code. Destructors and/or constructors are not allowed to be
     virtual.

   * *ERROR : _Constructor_ is not allowed to be virtual.*

     As the previous error, you are trying to declare a constructor
     as virtual. This is not allowed.

   * *ERROR : invalid virtual declaration: virtual(_Arg_). *

     Given argument to virtual/1 declaration is not a valid predicate
     specification, of the form _Functor/Arity_.

   * *ERROR : clause of _F/A_ ignored : only facts are allowed as
     initial state.*

     You declared _F/A_ as an attribute, then you put some clauses of
     that predicate in the form _Head :- Body_. For example:

     `:- data my_attribute/1.'

     `my_attribute(X) :- X>=0 , X<=2.'

     This is not allowed since attributes are assumed to hold simple
     facts. The correct usage for those _initialization clauses_ is:

     `:- data my_attribute/1.'

     `my_attribute(0).'

     `my_attribute(1).'

     `my_attribute(2).'

   * *ERROR : multifile _F/A_ is not allowed to be public.*

     The given _F/A_ predicate is both present at multifile/1 and
     public/1 declarations. For example:

     `:- public(p/1).'

     `:- multifile(p/1).'

     This is not allowed since multifile predicates are not related
     to Object Oriented Programming.

   * *ERROR : multifile _F/A_ is not allowed to be inheritable.*

     Analogous to previous error.

   * *ERROR : multifile _F/A_ is not allowed to be virtual.*

     Analogous to previous error.

   * *ERROR : virtual _F/A_ must be a method or attribute defined at
     this class.*

     There is a virtual/1 declaration for _F/A_, but there is not any
     clause of that predicate nor a `data/1' declaration. You must
     declare at least one clause for every virtual method. Virtual
     attributes does not require any clause but a `data/1'
     declaration must be present.

   * *ERROR : implemented interface _Module_ is not a valid
     interface.*

     There is an `implements/1' declaration present at your code
     where given _Module_ is not declared as class nor interface.

   * *ERROR : predicate _F/A_ is required both as method (at _Itf1_
     interface) and attribute (at _Itf2_ interface).*

     There is no chance to give a correct implementation for _F/A_
     predicate since _Itf1_ and _Itf2_ interfaces require different
     definitions. To avoid this error, you must remove one of the
     related `implements/1' declaration.

   * *ERROR : inherited _Source_ must be a class.*

     There is an :- inherit_class(_Source_) declaration, but that
     source was not declared as a class.

   * *ERROR : circular inheritance: _Source_ is not a valid
     super-class.*

     Establishing an inheritance relationship with _Source_ will
     cause current class to be present twice in the inheritance line.
     This is not allowed. The cause of this is error is simple :
     There is some inherited class from _Source_ which also
     establishes an inheritance relationship with current source.

   * *ERROR : method/attribute _F/A_ must be implemented.*

     Some of the implemented interfaces requires _F/A_ to be defined,
     but there is no definition for such predicate, even an inherited
     one.

   * *ERROR : local implementation of _F/A_ hides inheritable/public
     definition.*

     There is an inherited definition for _F/A_ which is been
     redefined at current class, but there is no valid
     inheritable/public declaration for the last one. Overriden
     public predicates must be also declared as public. Overriden
     inheritable predicates must be declared either as public or
     inheritable.

   * *ERROR : public predicate _F/A_ was not defined nor inherited.*

     There is a `public/1' declaration for _F/A_, but there is no
     definition for it at current class nor an inherited one.

   * *ERROR : argument to self/1 must be a free variable.*

     Argument to self/1 is not a variable, for example: `self(abc)'.

   * *ERROR : unknown inherited attribute in _Goal_.*

     _Goal_ belongs to assert/retract family of predicates, and given
     argument is not a valid inherited attribute. The most probable
     causes of this error are:

        * The given predicate is defined at super-class, but you
          forgot to mark it as inheritable (or public), at such class.

        * The given predicate was not defined (at super-class) as an
          attribute, just as a method.

   * *ERROR : unknown inherited goal: _Goal_.*

     The given _Goal_ was not found at super-class, or it is not
     accessible. Check whether _Goal_ was marked as inheritable (or
     public) at super-class.

   * *ERROR : invalid argument: _F/A_ is not an attribute.*

     You are trying to pass a method as an argument to any predicate
     which expect a _fact_ predicate.

   * *ERROR : unknown inherited fact: _Fact_.*

     There is a call to any predicate which expects a _fact_ argument
     (those declared as data or dynamic),but the actual argument is
     not an inherited attribute.For example:

     `asserta_fact(inherited(not_an_attribute(8)))'

     where not_an_attribute/1 was not declared as data or dynamic by
     the super-class (or corresponding ascendant).

   * *ERROR : unknown inherited spec: _F/A_.*

     There is a reference to an inherited predicate specification,
     but the involved predicate has not been inherited.

   * *WARNING : meta-predicate specification of _F/A_ ignored since
     this is an attribute.*

     You declared _F/A_ both as an attribute and a meta-predicate.
     For example:

     `:- meta_predicate attr(goal).'

     `:- data attr/1.'

     There is no sense in declaring an attribute as meta-predicate.

   * *WARNING : class destructor is public*

     There is a :- public(destructor/0) declaration present at your
     code. Marking a destructor as public is a very bad idea since
     anybody may destroy or corrupt an instance before the proper
     time.

   * *WARNING : class destructor is inheritable*

     Analogous to previous error.

   * *WARNING : There is no call to inherited constructor/s*

     You have not declared any constructor at your class, but there
     is any inherited constructor that should be called. Whenever you
     do not need constructors, but there is an inheritance
     relationship (where super-class declares a constructor), you
     should write a simple constructor as the following example:
             :- class(myclass).
             :- inherit_class(other_class).

             myclass :-
                     other_class.

   * *WARNING : multifile _F/A_ hides inherited predicate.*

     You declared as multifle a predicate which matches an inherited
     predicate name. Any reference to the inherited predicate must be
     done by the ways of the inherited/1 qualificator.

107.4.2 Class and Interface error reporting at run time
-------------------------------------------------------

   * *EXCEPTION : error(existence_error(object_goal,_Goal_),_Mod_).*

     Called _Goal_ from module (or class) _Mod_ is unknown or has not
     been published.

107.4.3 Normal Prolog module system interaction
-----------------------------------------------

O'Ciao works in conjunction with the Ciao Prolog module system, which
also reports its own error messages. This will cause Ciao to report a
little criptic error messages due to the general mechanism of
source-to-source expansion. Those are some tips you must consider
when compiling a class:

   * Any error relative to method 'm' with arity A will be reported
     for predicate 'obj$m'/A+1. For example :

     `WARNING: (lns 28-30) [Item,Itema] - singleton variables in
     obj$remove/2'

     This error is relative to method remove/1.

   * `set_prolog_flag/1' declaration will be usefull when declaring
     multiple constructors. It will avoid some awful warnings.
     Example:

             :- class(myclass).

             %% Use this declaration whenever several constructors are needed.

             :- set_prolog_flag(multi_arity_warnings,off).

             myclass(_).

             myclass(_,_).

             :- set_prolog_flag(multi_arity_warnings,on).

107.5 Known bugs and planned improvements (`class')
===================================================

   * addmodule and pred(N) meta-arguments are not allowed on
     meta-predicates.

108 Compile-time usage of objects
*********************************

*Author(s):* Angel Fernandez Pineda.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.7#32 (2000/11/14, 13:13:15 CET)

   This package is required to enable user code to create objects and
manipulate them, as well as loading any needed class.

108.1 Usage and interface (`objects')
=====================================

   * *Library usage:*

     Any code which needs to use objects must include the objects
     package:
              :- module(_ModuleName_,_Exports_,[objects]).
     You can use objects even if your code is a class. Note that
     declaring a class does not automatically enables the code to
     create instances.
              :- class(_ModuleName_,[],[objects]).

     This package enables both static and dynamic usage of objects.

   * *New declarations defined:*

     ` use_class/1', ` instance_of/2', ` new/2'.

   * *Other modules used:*
        - _System library modules:_

          `objects/objects_rt'.

108.2 Documentation on new declarations (`objects')
===================================================

 -- DECLARATION: use_class/1:
     It establishes an usage relationship between the given file
     (which is supposed to declare a class) and current source. Usage
     relationships are needed in order to enable code to create
     instances of the given class, and to make calls to instances
     derived from such class.

     Since an interface is some kind of class, they may be used
     within this declaration but only for semantic checking
     porpouses. Instances will not be derived from interfaces.

     use_class/1 is used in the same way as `use_module/1'.

     *Usage:* :- ` use_class(ClassSource)'.
        - _Description:_ Establish usage relationship with
          `ClassSource'.

        - _The following properties should hold at call time:_

          `ClassSource' is a valid path to a prolog file containing a
          class declaration (without .pl extension).
          (`objects_rt:class_source/1')

 -- DECLARATION: instance_of/2:
     Statically declares an identifier to be an instance of a given
     class.

     It may be used as `new/2' predicate except for:
        * The instance identifier will not be a variable, it must be
          provided by the user, and must be unique.

        * Instance creation will never fail, even if the constructor
          fails.

     For every statically declared object the given constructor will
     be called at program startup. Those instances may be destroyed
     manually, but it is not recommended.

     When reloading the involved class from the Ciao toplevel shell.
     It may destroy statically declared instances, and create them
     again.

     Statically declared instances must be called using a
     specifically designed module-qualification:
     `ClassName(Object):Goal'. For example:
              :- module(example,[main/0],[objects]).
              :- use_class(library(counter)).
              :- cnt instance_of counter(10).

              main :-
                   counter(cnt):decrease(1),
                   counter(cnt):current_value(X),
                   display(X).
     But *statically written code* (only) is allowed to use
     module-style qualifications as a macro:
              main :-
                   cnt:decrease(1),
                   cnt:current_value(X),
                   display(X).
     Notice that dynamically expanded goals such as
     `X=cnt,X:decrease(1)' will not work, use
     `X=counter(cnt),X:decrease(1)' instead.

     *Usage:* :- ` instance_of(Object, Constructor)'.
        - _Description:_ Declares `Object' to be an instance of the
          class denoted by `Constructor'.

        - _The following properties should hold at call time:_

          `Object' is an unique term which identifies an object.
          (`objects_rt:instance_id/1')

          `Constructor' is a term whose functor matches a class name.
          (`objects_rt:constructor/1')

 -- DECLARATION: new/2:
     This declaration has the same effect as ` instance_of/2'.

     *Usage:* :- ` new(Object, Constructor)'.
        - _Description:_ Just an alias for ` instance_of/2'.

        - _The following properties should hold at call time:_

          `Object' is an unique term which identifies an object.
          (`objects_rt:instance_id/1')

          `Constructor' is a term whose functor matches a class name.
          (`objects_rt:constructor/1')

108.3 Other information (`objects')
===================================

Compile-time errors are restricted to some local analysis. Since
there is no type declaration in the Prolog language, there is no
posibility to determine whenever a given variable will hold an
instance of any class.

   However, little semantic analysis is performed. User may aid to
perform such an analysis by the usage of run time checks (which are
also detected at compile time), or static declarations. For example:

   `clause(Obj) :- Obj:a_method(334).'

   O'Ciao may be not able to determine whenever a_method/1 is a valid
method for instance Obj, unless some help is provided:

   `clause(Obj) :- Obj instance_of myclass,Obj:a_method(334).'

   In such case, O'Ciao will report any semantic error at
compile-time.

   Most of the run-time errors are related to normal Ciao Prolog
module system. Since objects are treated as normal Prolog modules at
run time, there is no further documentation here about that stuff.

108.3.1 Error reporting at compile time (objects)
-------------------------------------------------

   * *ERROR : invalid instance identifier _ID_: must be an atom*

     There is a `instance_of/2' or `new/2' declaration where first
     argument _ID_ must be an unique atom, but currently it is not.
     Statically declared instances needs an identifier to be provided
     by the user.

   * *ERROR : instance identifier _ID_ already in use*

     There are two or more `instance_of/2' declarations with the same
     first argument _ID_. Instance identifiers must be unique.

   * *ERROR : invalid use_class/1 declaration: _SourceFile_ is not a
     class*

     Those are the causes for this error:

        * The given _SourceFile_ does not exist, or is not accesible.

        * The given _SourceFile_ is not a Prolog source.

        * The given _SourceFile_ is a valid Prolog source, but it
          does not declare a class.

   * *ERROR : unknown class on _ID_ instance declaration*

     The class defined on the `instance_of/2' declaration for _ID_
     instance has not been loaded by a `use_class/1' declaration.

   * *ERROR : instance identifier _ID_ is an exisisting Prolog module*

     There is an statically declared instance whose identifier may
     cause interference with the Ciao Prolog module system. Use
     another instance identifier.

   * *ERROR : unknown constructor on _ID_ instance declaration*

     The given constructor on the `instance_of/2' declaration for
     _ID_ has not been defined at the corresponding class.

   * *ERROR : constructor is needed on _ID_ instance declaration*

     No constructor was defined on the `instance_of/2' declaration
     for _ID_ and default constructor is not allowed. You must
     provide a constructor.

   * *ERROR : static instance _ID_ was derived from a different
     constructor at _AnotherModule_*

     _ID_ has been declared to be an static instance both on
     _AnotherModule_ and current source, but different constructors
     were used. The most probable causes for this error are:

        * Occasionally, there is another module using the same
          instance identifier and it was not noticed by you. Another
          different identifier may be used instead.

        * It was you intention to use the same object as declared by
          the other module. In this case, the same constructor must
          be used.

   * *ERROR : invalid first argument in call to new(_Arg_,_)*

     There is a new/1 goal in your code where first argument is not a
     free variable. For example:

     `myobj new myclass'

     First argument must be a variable in order to receive a run-time
     generated object identifier.

   * *ERROR : unknown class in call to new(?,_Constructor_) *

     The given _Constructor_ in call to new/2 does not correspond to
     any used class at current code. The most probable cause of this
     may be:

        * You forgot to include a `use_class/1' declaration in your
          code.

        * There is a spelling mistake in the constructor.For example:

          :- use_class(myclass).

          foo(X) :- X new mclass.

   * *ERROR : can not create an instance from an interface:
     new(?,_Constructor_) *

     Given _Constructor_ references an interface rather than a class.
     Instances can not be derived from interface-expanded code.

   * *ERROR : unknown constructor in call to new(?,_Constructor_) *

     As the previous error, there is a mistake in the given
     _Constructor_. This error is reported when you are trying to
     call a constructor which was not defined at the corresponding
     class. Check the class definition to find what is going on.

     Another cause for this error is the incorrect usage of the default
     constructor. Whenever there are one or more constructors defined
     at the involved class, you are restricted to chose one of them.
     This seems that default constructor will be available, if and
     only if, there are no constructors defined at the involved class.

   * *ERROR : call to non-public _ID:Goal_*

     You are trying to call a method which was not declared as public
     by the class specified in `instance_of/2' declaration for _ID_.

   * *ERROR : call to inaccessible predicate at instance _ID:Goal_*

     There is a call to _Goal_ at statically declared instance _ID_
     which is unknown or was not declared as public.

   * *ERROR : unknown instance _ID_ of class _Class_ at _Goal_*

     There is a call to _Goal_ where involved statically declared
     instance _ID_ is unknown or is not derived from _Class_. Check
     whether it was declared by a `instance_of/2' declaration.

   * *ERROR : inaccessible attribute _Fact_ at instance _ID_*

     There is an attempt to use _ID:Fact_ but it was not declared as
     public.

   * *ERROR : unknown attribute _Fact_ at instance _ID_*

     There is an attempt to use _ID:Fact_ but it is unknown or it is
     not an attribute (may be a method).

   * *WARNING : invalid call to new(?,_)*

     There is a call to new/2 in you code where first argument
     variable has been determined to hold any other instance. For
     example:

     `foo :- X new myclass,X new otherclass.'

     or

     `foo(X) :- X instance_of myclass, X new myclass.'

     The related call to new/2 will allways fail.

   * *WARNING : called _Goal_ is not public at any used class*

     There is a call to _Var_:_Goal_ where _Var_ has not been
     determined to be compatible with any class. However, _Goal_ is
     not public at any class specified by the `use_class/1'
     declaration.

     This is a warning (not an error) since _Var_:_Goal_ may be not
     related to Object Oriented Programing.

108.3.2 Error reporting at run time (objects)
---------------------------------------------

   * *EXCEPTION : instantiation_error( '1st argument must be free
     variable')*

     Calling to new/1 requieres first argument to be a free variable.
     For example:

     `X = this_will_raise_an_exception,X new myclass.'

   * *EXCEPTION : instantiation_error('class not given')*

     You called new/2 using a free variable as second argument.

   * *EXCEPTION : instantiation_error(inaccesible_class(_Class_),
     from(_Module_)) *

     _Module_ tried to create an instance of _Class_ by the ways of
     new/2, but there is no usage relationship between _Module_ and
     _Class_.

   * *EXCEPTION : instantiation_error(invalid_constructor(
     _Constructor_)) *

     _Constructor_ was not defined by the corresponding class.

109 Run time usage of objects
*****************************

*Author(s):* Angel Fernandez Pineda, Angel Fernandez Pineda.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.7#51 (2001/1/25, 21:33:0 CET)

   This library provides run-time support for object creation and
manipulation. Objects are also called class instances, or simply instances.

   Objects in Ciao are treated as normal modules. This is, an object
is a run-time generated Prolog module, which may be identified by an
unique term across the whole application.

   This is a very simple example of how to create an instance, and
how to make calls to it:

                 AnObj new myclass,
                 AnObj:mymethod.

   In order to make any object accessible from code, an usage
relationship must be established between the class (from which
instances are derived) and the code itself. Refer to `use_class/1'
predicate or `use_class/1' declaration in order to do so.

109.1 Usage and interface (`objects_rt')
========================================

   * *Library usage:*

     This library is automatically loaded when using the _objects_
     package:
              :- module(_ModuleName_,_Exports_,[objects]).
     Nothing special needs to be done.

   * *Exports:*
        - _Predicates:_

          `new/2', `instance_of/2', `derived_from/2', `interface/2', `instance_codes/2', `destroy/1', `use_class/1'.

        - _Properties:_

          `constructor/1', `class_name/1', `interface_name/1', `instance_id/1', `class_source/1', `interface_source/1', `method_spec/1', `virtual_method_spec/1'.

   * *Other modules used:*
        - _System library modules:_

          `operators', `default_predicates', `compiler/compiler', `prolog_sys', `system'.

109.2 Documentation on exports (`objects_rt')
=============================================

 -- PREDICATE: new/2:
     Dynamic instance creation takes place by the ways of this
     predicate.

     It takes a free variable as first argument which will be
     instantiated to an internal object identifier.

     Second argument must be instantiated to a class constructor.
     Class constructors are designed to perform an initialization on
     the new created instance. Notice that instance initialization
     may involve some kind of computation, not only _state
     initialization_.

     A class constructor is made by a functor, which must match the
     intended class name, and any number of parameters. For example:

                      Obj new myclass(1500,'hello, world!!!')

     Those parameters depends (obviously) on the constructors defined
     at the class source. If no constructors where defined, no
     parameters are needed. This is called the default constructor.
     An example:

                      Obj new myclass

     The default constructor can not be called if there is any
     constructor available at the class source.

     Instantiation will raise an exception and fail whenever any of
     this conditions occur:
        * First argument is not a free variable.

        * Second argument functor is a class, but there is no usage
          relationship with it.

        * Second argument functor is not a class.

        * The given constructor is unknown.

        * The given constructor fails (notice that default
          constructor never fails).

     Objects may also be statically declared, refer to `instance_of/2'
     declaration.

     *Usage:* `new(InstanceVar, Constructor)'
        - _Description:_ Creates a new instance of the class
          specified by `Constructor' returning its identifier in
          `InstanceVar'

        - _The following properties should hold at call time:_

          `InstanceVar' is a free variable.   (`term_typing:var/1')

          `Constructor' is a term whose functor matches a class name.
          (`objects_rt:constructor/1')

        - _The following properties should hold upon exit:_

          `InstanceVar' is an unique term which identifies an object.
          (`objects_rt:instance_id/1')

 -- PREDICATE: instance_of/2:
     This predicate is used to perform dynamic type checking. You may
     check whether a particular instance belongs to a particular
     class or related descendants.

     instance_of/2 is used to perform static semantic analisys over
     object oriented code constructions.

     By the use of instance_of/2 you may help to perform such
     analisys.

     *Usage 1:* `instance_of(Instance, Class)'
        - _Description:_ Test whether `Instance' was derived from any
          descendant of `Class', or that class itself

        - _The following properties should hold at call time:_

          `Instance' is an unique term which identifies an object.
          (`objects_rt:instance_id/1')

          `Class' is an atom denoting a class.
          (`objects_rt:class_name/1')

     *Usage 2:* `instance_of(Instance, Class)'
        - _Description:_ Retrieves, on backtracking, the inheritance
          line of `Instance' commencing on the creation class (that
          specified on call to `new/2') and continuing on the rest of
          ascendant classes, if any.

        - _The following properties should hold at call time:_

          `Instance' is an unique term which identifies an object.
          (`objects_rt:instance_id/1')

          `Class' is a free variable.   (`term_typing:var/1')

        - _The following properties should hold upon exit:_

          `Class' is an atom denoting a class.
          (`objects_rt:class_name/1')

 -- PREDICATE: derived_from/2:
     Test whether an object identifier was derived directly from a
     class, by the usage of `new/2' or a static instance declaration ( `instance_of/2').

     *Usage 1:* `derived_from(Instance, Class)'
        - _Description:_ Test derivation of `Instance' from `Class'

        - _The following properties should hold at call time:_

          `Instance' is an unique term which identifies an object.
          (`objects_rt:instance_id/1')

          `Class' is an atom denoting a class.
          (`objects_rt:class_name/1')

     *Usage 2:* `derived_from(Instance, Class)'
        - _Description:_ Retrieves the `Class' responsable of the
          derivation of `Instance'.

        - _The following properties should hold at call time:_

          `Instance' is an unique term which identifies an object.
          (`objects_rt:instance_id/1')

          `Class' is a free variable.   (`term_typing:var/1')

        - _The following properties should hold upon exit:_

          `Class' is an atom denoting a class.
          (`objects_rt:class_name/1')

 -- PREDICATE: interface/2:
     This predicate is used to ensure a given interface to be
     implemented by a given instance.

     *Usage 1:* `interface(Instance, Interface)'
        - _Description:_ Check whether `Instance' implements the
          given `Interface'.

        - _The following properties should hold at call time:_

          `Instance' is an unique term which identifies an object.
          (`objects_rt:instance_id/1')

          `Interface' is an unique atom which identifies a public
          interface.   (`objects_rt:interface_name/1')

     *Usage 2:* `interface(Instance, Interfaces)'
        - _Description:_ Retrieves on backtracking all the
          implemented `Interfaces' of `Instance'.

        - _The following properties should hold at call time:_

          `Instance' is an unique term which identifies an object.
          (`objects_rt:instance_id/1')

          `Interfaces' is a free variable.   (`term_typing:var/1')

        - _The following properties should hold upon exit:_

          `Interfaces' is an unique atom which identifies a public
          interface.   (`objects_rt:interface_name/1')

 -- PREDICATE: instance_codes/2:
     Retrieves a character string representation from an object
     identifier and vice-versa.

     *Usage 1:* `instance_codes(Instance, String)'
        - _Description:_ Retrieves a `String' representation of given
          `Instance'.

        - _The following properties should hold at call time:_

          `Instance' is an unique term which identifies an object.
          (`objects_rt:instance_id/1')

          `String' is a free variable.   (`term_typing:var/1')

        - _The following properties should hold upon exit:_

          `String' is a string (a list of character codes).
          (`basic_props:string/1')

     *Usage 2:* `instance_codes(Instance, String)'
        - _Description:_ Reproduces an `Instance' from its `String'
          representation. Such an instance must be alive across the
          application: this predicate will fail whether the involved
          instance has been destroyed.

        - _The following properties should hold at call time:_

          `Instance' is a free variable.   (`term_typing:var/1')

          `String' is a string (a list of character codes).
          (`basic_props:string/1')

        - _The following properties should hold upon exit:_

          `Instance' is an unique term which identifies an object.
          (`objects_rt:instance_id/1')

 -- PREDICATE: destroy/1:
     As well as instances are created, they must be destroyed when no
     longer needed in order to release system resources.

     Unfortunately, current O'Ciao implementation does not support
     automatic instance destruction, so user must manually call
     _destroy/1_ in order to do so.

     The programmer *must ensure* that no other references to the
     involved object are left in memory when destroy/1 is called. If
     not, unexpected results may be obtained.

     *Usage:* `destroy(Instance)'
        - _Description:_ Destroys the object identified by `Instance'.

        - _The following properties should hold at call time:_

          `Instance' is an unique term which identifies an object.
          (`objects_rt:instance_id/1')

 -- PREDICATE: use_class/1:
     The behaviour of this predicate is identical to that provided by
     the declaration of the same name `use_class/1'. It allows user
     programs to dynamically load classes. Whether the given source
     is not a class it will perform a `use_module/1' predicate call.

     *Usage:* `use_class(ClassSource)'
        - _Description:_ Dynamically loads the given `ClassSource'

        - _The following properties should hold at call time:_

          `ClassSource' is a valid path to a prolog file containing a
          class declaration (without .pl extension).
          (`objects_rt:class_source/1')

 -- PROPERTY: constructor/1:
     *Usage:* `constructor(Cons)'
        - _Description:_ `Cons' is a term whose functor matches a
          class name.

 -- PROPERTY: class_name/1:
     *Usage:* `class_name(ClassName)'
        - _Description:_ `ClassName' is an atom denoting a class.

 -- PROPERTY: interface_name/1:
     *Usage:* `interface_name(Interface)'
        - _Description:_ `Interface' is an unique atom which
          identifies a public interface.

 -- PROPERTY: instance_id/1:
     *Usage:* `instance_id(ID)'
        - _Description:_ `ID' is an unique term which identifies an
          object.

 -- PROPERTY: class_source/1:
     *Usage:* `class_source(Source)'
        - _Description:_ `Source' is a valid path to a prolog file
          containing a class declaration (without .pl extension).

 -- PROPERTY: interface_source/1:
     *Usage:* `interface_source(Source)'
        - _Description:_ `Source' is a valid path to a prolog file
          containing a class declaration or an interface declaration
          (without .pl extension).

 -- PROPERTY: method_spec/1:
     There is no difference between method or attribute
     specifications, and habitual predicate specifications. It is
     just a Functor/Arity term.

     *Usage:* `method_spec(Spec)'
        - _Description:_ `Spec' is a method or attribute
          specification.

 -- PROPERTY: virtual_method_spec/1:
     *Usage:* `virtual_method_spec(Spec)'
        - _Description:_ `Spec' is a method specification.

109.3 Known bugs and planned improvements (`objects_rt')
========================================================

   * Usage of objects from the `user' module does not work properly.
     It is better to use the `objects' package in a (proper) module.

   * Not really a bug: when loading code which declares static
     instances from the toplevel shell, predicate `use_module/1')
     will not work properly: those instances may be not correctly
     created, and predicates will fail whenever they are not supposed
     to do. This may be avoided by reloading again the involved
     module, but make sure it is modified and saved to disk before
     doing so.

110 The Ciao Remote Services Package
************************************

*Author(s):* Manuel Carro.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#228 (2003/12/22, 17:9:36 CET)

   Module for The Ciao Remote Services Package

110.1 Usage and interface (`remote')
====================================

   * *Library usage:*

     `:- use_module(library(remote)).'

   * *Other modules used:*
        - _System library modules:_

          `remote/ciao_client_rt'.

110.2 Documentation on exports (`remote')
=========================================

 -- (: UNDOC_REEXPORT) @/2:
     Imported from `ciao_client_rt' (see the corresponding
     documentation for details).

 -- (: UNDOC_REEXPORT) @/2:
     Imported from `ciao_client_rt' (see the corresponding
     documentation for details).

 -- (: UNDOC_REEXPORT) server_stop/1:
     Imported from `ciao_client_rt' (see the corresponding
     documentation for details).

 -- (: UNDOC_REEXPORT) server_stop/1:
     Imported from `ciao_client_rt' (see the corresponding
     documentation for details).

 -- (: UNDOC_REEXPORT) server_trace/1:
     Imported from `ciao_client_rt' (see the corresponding
     documentation for details).

 -- (: UNDOC_REEXPORT) server_trace/1:
     Imported from `ciao_client_rt' (see the corresponding
     documentation for details).

 -- (: UNDOC_REEXPORT) server_notrace/1:
     Imported from `ciao_client_rt' (see the corresponding
     documentation for details).

 -- (: UNDOC_REEXPORT) server_notrace/1:
     Imported from `ciao_client_rt' (see the corresponding
     documentation for details).

110.3 Known bugs and planned improvements (`remote')
====================================================

   * Dynamic loading of code not yet implemented.

   * :- remote/1 predicate declaration not yet implemented.

   * Remote use of modules (http, ftp, ciaotp) not yet implemented.

   * Remote creation of objects not yet implemented.

   * Code migration not yet implemented (several algorithms possible).

   * Evaluation of impact of marshalling and/or attribute encoding
     not yet done.

   * Secure transactions not yet implemented.

PART VIII - Interfaces to other languages and systems
*****************************************************

*Author(s):* The CLIP Group.

   The following interfaces to/from Ciao Prolog 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 Prolog
     internal database and the external file system).

   * SQL-like database interface (interface between the Prolog
     internal database and external SQL/ODBC systems).

   * Java interface.

   * Calling emacs from Prolog.

111 Foreign Language Interface
******************************

*Author(s):* Jose Morales, Manuel Carro.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#47 (2003/1/7, 14:22:36 CET)

   Ciao Prolog includes a high-level, flexible way to interface C and
Prolog, based on the use of assertions to declare what are the
expected types and modes of the arguments of a Prolog predicate, and
which C files contain the corresponding code. To this end, the user
provides:

   * A set of C files, or a precompiled shared library,

   * A Ciao Prolog module defining whith predicates are implemented
     in the C files and the types and modes of their arguments, and

   * an (optional) set of flags required for the compilation of the
     files.

   The Ciao Prolog compiler analyzes the Prolog code written by the
user and gathers this information in order to generate automatically
C "glue" code implementing the data translation between Prolog and C,
and to compile the C code into dynamically loadable C object files,
which are linked automatically when needed.

111.1 Declaration of Types
==========================

Each predicate implemented as a foreign C function must have
accompanying declarations in the Ciao Prolog associated file stating
the types and modes of the C function. A sample declaration for
`prolog_predicate' which is implemented as `foreign_function_name' is:

          :- true pred prolog_predicate(m1(Arg1), ... mN(ArgN)) ::
                       type1 * ... * typeN +
                       (foreign(foreign_function_name), returns(ArgR)).

   where `m1', ..., `mN' and `type1', ..., `typeN' are respectively
the modes and types of the arguments. `foreign_function_name' is the
name of the C function implementing `prolog_predicate/N', and the
result of this function is unified with `ArgR', which must be one of
`Arg1' ... `ArgN'.

   This notation can be simplified in several ways. If the name of
the foreign function is the same as the name of the Ciao Prolog
predicate, `foreign(foreign_function_name)' can be replaced by
`foreign/0'. `returns(ArgR)' specifies that the result of the
function corresponds to the `ArgR' argument of the Ciao Prolog
predicate. If the foreign function does not return anything (or if
its value is ignored), then `returns(ArgR)' must be removed. Note
that `returns' cannot be used without `foreign'. A simplified,
minimal form is thus:

          :- true pred prolog_predicate(m1(Arg1), ... mN(ArgN)) ::
                       type1 * ... * typeN + foreign.

111.2 Equivalence between Ciao Prolog and C types
=================================================

The automatic translation between Ciao Prolog and C types is defined
(at the moment) only for some simple but useful types. The
translation to be performed is solely defined by the types of the
arguments in the Ciao Prolog file (i.e., no inspection of the
corresponding C file is done). The names (and meaning) of the types
known for performing that translation are to be found in
Foreign Language Interface Properties; they are also summarized
below (Prolog types are on the left, and the corresponding C types on
the right):

   * num <-> double

   * int <-> int

   * atm <-> char *

   * string <-> char * (with trailing zero)

   * byte_list <-> char * (a buffer of bytes, with associated length)

   * int_list <-> int * (a buffer of integers, with associated length)

   * address <-> void *

   Strings, atoms, and lists of bytes are passed to (and from) C as
dynamically (`ciao_malloc') created arrays of characters (bytes).
Those arrays are freed by Ciao Prolog upon return of the foreign
function unless the property `do_not_free/2' is specified (see
examples below). This caters for the case in which the C files save
in a private state (either by themselves, or by a library function
being called by them) the values passed on from Prolog. The type `byte_list/1'
requires an additional property, `size_of/2', to indicate which
argument represents its size.

   Empty lists of bytes and integers are converted into C `NULL'
pointers, and vice versa. Empty strings (`[]') and null atoms (") are
converted into zero-length, zero-ended C strings (_""_). C `NULL'
strings and empty buffers (i.e., buffers with zero length) are
transformed into the empty list or the null atom (`''').

   Most of the work is performed by the predicates in the
Foreign Language Interface Builder, which can be called explicitly
by the user. Doing that is not usually needed, since the Ciao Prolog
Compiler takes care of building glue code files an of compiling and
linking whatever is necessary.

111.3 Equivalence between Ciao Prolog and C modes
=================================================

The (prefix) `+/1' ISO mode (or, equivalently, the in/1 mode) states
that the corresponding Prolog argument is ground at the time of the
call, and therefore it is an input argument in the C part; this
groundness is automatically checked upon entry. The (prefix) `-/1'
ISO mode (or, equivalently, the go/1 mode) states that Prolog expects
the C side to generate a (ground) value for that argument. Arguments
with output mode should appear in C functions as pointers to the
corresponding base type (as it is usual with C), i.e., an argument
which is an integer generated by the C file, declared as

     :- true pred get_int(go(ThisInt)) :: int + foreign

   or as

     :- true pred get_int(-ThisInt) :: int + foreign

   should appear in the C code as

     void get_int(int *thisint)
     {
             ....
     }

   Note the type of the (single) argument of the function. Besides,
the return value of a function can always be used as an output
argument, just by specifying to which Prolog arguments it
corresponds, using the `foreing/1' property. The examples below
illustrate this point, and the use of several assertions to guide the
compilation.

111.4 Custom access to Prolog from C
====================================

Automatic type conversions does not cover all the possible cases.
When the automatic type conversion is not enough (or if the user, for
any reason, does not want to go through the automatic conversion), it
is possible to instruct Ciao Prolog not to make implicit type
conversion. The strategy in that case is to pass the relevant
argument(s) with a special type (a `ciao_term') which can represent
any term which can be built in Prolog. Operations to construct,
traverse, and test this data abstraction from C are provided. The
prototypes of these operations are placed on the `"ciao_prolog.h"'
file, under the `include' subdirectory of the installation directory
(the Ciao Prolog compiler knowns where it has been installed, and
gives the C compiler the appropriate flags). This _non direct
correspondence_ mode is activated whenever a Ciao Prolog type unknown
to the foreign interface (i.e., none of these in Foreign Language Interface Properties)
or the type `any_term' (which is
explicitly recognised by the foreign language interface) is found.
The latter is preferred, as it is much more informative, and external
tools, as the the CiaoPP preprocessor, can take advantage of them.

111.4.1 Term construction
-------------------------

All term construction primitives return an argument of type
`ciao_term', which is the result of constructing a term. All Ciao
Prolog terms can be built using the interface operations
`ciao_var()', `ciao_structure()', `ciao_integer()', and
`ciao_float()'. There are, however, variants and specialized versions
of these operations which can be freely intermixed. Using one version
or another is a matter of taste and convenience. We list below the
prototypes of the primitives in order of complexity.

   Throughout this section, *true*, when referred to a boolean value,
correspond to the integer value `1', and *false* correspond to the
integer value `0', as is customary in C boolean expressions. These
values also available as the (predefined) constants `ciao_true' and
`ciao_false', both of type `ciao_bool'.

   * `ciao_term ciao_var();'

     Returns a fresh, unbound variable.

   * `ciao_term ciao_integer(int i);'

     Creates a term, representing an integer from the Prolog point of
     view, from a C integer.

   * `ciao_term ciao_float(double i);'

     Creates a term, representing a floating point number, from a
     floating point number.

   * `ciao_term ciao_put_number_chars(char *number_string);'

     It converts `number_string' (which must a string representing a
     syntactically valid number) into a `ciao_term'.

   * `ciao_term ciao_atom(char *name);'

     Creates an atom whose printable name is given as a C string.

   * `ciao_term ciao_structure_a(char *name, int arity, ciao_term
     *args);'

     Creates a structure with name 'name' (i.e., the functor name ),
     arity 'arity' and the components of the array 'args' as
     arguments: `args[0]' will be the first argument, `args[1]' the
     second, and so on. The 'args' array itself is not needed after
     the term is created, and can thus be a variable local to a
     procedure. An atom can be represented as a 0-arity structure
     (with `ciao_structure(name, 0)'), and a list cell can be
     constructed using the '.'/2 structure name. The `_a' suffix
     stands for _array_.

   * `ciao_term ciao_structure(char *name, int arity, ...);'

     Similar to ciao_structure_a, but the C arguments after the arity
     are used to fill in the arguments of the structure.

   * `ciao_term ciao_list(ciao_term head, ciao_term tail);'

     Creates a list from a `head' and a `tail'. It is equivalent to
     `ciao_structure(".", 2, head, tail)'.

   * `ciao_term ciao_empty_list();'

     Creates an empty list. It is equivalent to `ciao_atom("[]")'.

   * `ciao_term ciao_listn_a(int len, ciao_term *args);'

     Creates a list with 'len' elements from the array `args'. The
     _nth_ element of the list (starting at 1) is `args[n-1]'
     (starting at zero).

   * `ciao_term ciao_listn(int length, ...);'

     Like `ciao_listn_a()', but the list elements appear explicitly
     as arguments in the call.

   * `ciao_term ciao_dlist_a(int len, ciao_term *args, ciao_term
     base);'

     Like `ciao_listn_a', but a difference list is created. `base'
     whill be used as the tail of the list, instead of the empty list.

   * `ciao_term ciao_dlist(int length, ...);'

     Similar to `ciao_dlist_a()' with a variable number of arguments.
     The last one is the tail of the list.

   * `ciao_term ciao_copy_term(ciao_term src_term);'

     Returns a new copy of the `term', with fresh variables (as
     `copy_term/2' does).

111.4.2 Testing the Type of a Term
----------------------------------

A `ciao_term' can contain _any_ Prolog term, and its implementation
is opaque to the C code. Therefore the only way to know reliably what
data is passed on is using explicit functions to test term types.
Below, `ciao_bool' is a type defined in `"ciao_prolog.h"' which can
take the values 1 (for *true*) and 0 (for *false*).

   * `ciao_bool ciao_is_variable(ciao_term term);'

     Returns true if `term' is currently an uninstantiated variable.

   * `ciao_bool ciao_is_number(ciao_term term);'

     Returns true if `term' is an integer (of any length) or a
     floating point number.

   * `ciao_bool ciao_is_integer(ciao_term term);'

     Returns true if `term' is instantiated to an integer.

   * `ciao_bool ciao_fits_in_int(ciao_term term);'

     Returns true if `term' is instantiated to an integer which can
     be stored in an `int', and false otherwise.

   * `ciao_bool ciao_is_atom(ciao_term atom);'

     Returns true if `term' is an atom.

   * `ciao_bool ciao_is_list(ciao_term term);'

     Returns true if `term' is a list (actually, a `cons' cell).

   * `ciao_bool ciao_is_empty_list(ciao_term term);'

     Returns true if `term' is the atom which represents the empty
     list (i.e., `[]').

   * `ciao_bool ciao_is_structure(ciao_term term);'

     Returns true if `term' is a structure of any arity. This
     includes atoms (i.e., structures of arity zero) and lists, but
     excludes variables and numbers.

111.4.3 Term navigation
-----------------------

The functions below can be used to recover the value of a `ciao_term'
into C variables, or to inspect Prolog structures.

   * `int ciao_to_integer(ciao_term term); '

     Converts `term' to an integer. `ciao_is_integer(term)' must hold.

   * `ciao_bool ciao_to_integer_check(ciao_term term, int *result); '

     Checks whether `term' fits into the size of an integer. If so,
     true is returned and `*result' is unified with the integer
     `term' represents. Otherwise, false is returned and `*result' is
     not touched.

   * `double ciao_to_float(ciao_term term);'

     Converts `term' to a float value. `ciao_is_number(term)' must
     hold.

   * `char *ciao_get_number_chars(ciao_term term);'

     It converts `ciao_term' (which must be instantiated to a number)
     into a C string representing the number in the current radix.
     The string returned is a copy, which must (eventually) be
     explicitly deallocated by the user C code using the operation
     `ciao_free()'

   * `char *ciao_atom_name(ciao_term atom);'

     Returns the name of the atom. The returned string _is the one
     internally used by Ciao Prolog_, and should not be deallocated,
     changed or altered in any form. The advantage of using it is
     that it is fast, as no data copying is needed.

   * `char *ciao_atom_name_dup(ciao_term atom);'

     Obtains a *copy* of the name of the atom. The string can be
     modified, and the programmer has the responsibility of
     deallocating it after being used. Due to the copy, it is slower
     than calling `char *ciao_atom_name()'.

   * `ciao_term ciao_list_head(ciao_term term);'

     Extracts the head of the list `term'. Requires `term' to be a
     list.

   * `ciao_term ciao_list_tail(ciao_term term);'

     Extracts the tail of the list `term'. Requires `term' to be a
     list.

   * `char *ciao_structure_name(ciao_term term);'

     Extracts the name of the structure `term'. Requires `term' to be
     a structure.

   * `int ciao_structure_arity(ciao_term term);'

     Extracts the arity of the structure `term'.

     Requires `term' to be a structure.

   * `ciao_term ciao_structure_arg(ciao_term term, int n);'

     Extracts the _nth_ argument of the structure `term'. It behaves
     like `arg/3', so the first argument has index 1. Requires `term'
     to be a structure.

111.4.4 Testing for Equality and Performing Unification
-------------------------------------------------------

Variables of type `ciao_term' cannot be tested directly for equality:
they are (currently) implemented as a sort of pointers which may be
aliased (two different pointers may refer to the same object). The
interface provides helper functions for testing term equality and to
perform unification of terms.

   * `ciao_bool ciao_unify(ciao_term x, ciao_term y);'

     Performs the unification of the terms `x' and `y', and returns
     true if the unification was successful. This is equivalent to
     calling the (infix) Prolog predicate `=/2'. The bindings are
     trailed and undone on backtracking.

   * `ciao_bool ciao_equal(ciao_term x, ciao_term y);'

     Performs equality testing of terms, and returns true if the test
     was successful. This is equivalent to calling the (infix) Prolog
     predicate `==/2'. Equality testing does not modify the terms
     compared.

111.4.5 Raising Exceptions
--------------------------

The following functions offers a way of throwing exceptions from C
that can be caught in Prolog with `catch/3'. The term that reaches
Prolog is exactly the same which was thrown by C. The execution flow
is broken at the point where `ciao_raise_exception()' is executed,
and it returns to Prolog.

   * `void ciao_raise_exception(ciao_term ball);'

     Raises an exception an throws the term `ball'.

111.4.6 Creating and disposing of memory chunks
-----------------------------------------------

Memory to be used solely by the user C code can be reserved/disposed
of using, e.g., the well-known `malloc()'/`free()' functions (or
whatever other functions the user may have available). However,
memory explicitly allocated by Ciao Prolog and passed to C code, or
allocated by C code and passed on to Ciao Prolog (and subject to
garbage collection by it) should be allotted and freed (when
necessary) by using the functions:

   * `void *ciao_malloc(int size);'

   * `void ciao_free(void *pointer);'

whose behavior is similar to `malloc()'/`free()', but which will
cooordinate properly with Ciao Prolog's internal memory management.

111.4.7 Calling Prolog from C
-----------------------------

It is also possible to make arbitraty calls to Prolog predicates from
C. There are two basic ways of make a query, depending on whether
only one solution is needed (or if the predicate to be called is
known to generate only one solution), or if several solutions are
required.

   When only one solution is needed `ciao_commit_call' obtains it
(the solution obtained will obviously be the first one) and discards
the resources used for finding it:

   * `ciao_bool ciao_commit_call(char *name, int arity, ...);'

     Makes a call to a predicate and returns true or false depending
     on whether the query has succedeed or not. In case of success,
     the (possibly) instantiated variables are reachable from C.

   * `ciao_bool ciao_commit_call_term(ciao_term goal);'

     Like `ciao_commit_call()' but uses the previously built term
     `goal' as goal.

   If more than one solution is needed, it is necessary to use the
`ciao_query' operations. A consult begins with a `ciao_query_begin'
which returns a `ciao_query' object. Whenever an additional solution
is required, the `ciao_query_next' function can be called. The query
ends by calling `ciao_query_end' and all pending search branches are
pruned.

   * `ciao_query *ciao_query_begin(char *name, int arity, ...);'

     The predicate with the given name, arity and arguments (similar
     to the `ciao_structure()' operation) is transformed into a
     `ciao_query' object which can be used to make the actual query.

   * `ciao_query *ciao_query_begin_term(ciao_term goal);'

     Like ciao_query_begin but using the term `goal' instead.

   * `ciao_bool ciao_query_ok(ciao_query *query);'

     Determines whether the query may have pending solutions. A false
     return value means that there are no more solutions; a true
     return value means that there are more possible solutions.

   * `void ciao_query_next(ciao_query *query);'

     Ask for a new solution.

   * `void ciao_query_end(ciao_query *query);'

     Ends the query and frees the used resources.

111.5 Examples
==============

111.5.1 Mathematical functions
------------------------------

In this example, the standard mathematical library is accessed to
provide the _sin_, _cos_, and _fabs_ functions. Note that the library
is specified simply as

     :- use_foreign_library([m]).

   The foreign interface adds the `-lm' at compile time. Note also
how some additional options are added to optimize the compiled code
(only glue code, in this case) and mathematics (only in the case of
Linux in an Intel processor).

   *File* _math.pl_:

   :- module(math, [sin/2, cos/2, fabs/2], [foreign_interface]).

   :- true pred sin(in(X),go(Y)) :: num * num + (foreign,returns(Y)).
:- true pred cos(in(X),go(Y)) :: num * num + (foreign,returns(Y)).
:- true pred fabs(in(X),go(Y)) :: num * num + (foreign,returns(Y)).

   :- extra_compiler_opts(['-O2']).  :-
extra_compiler_opts('LINUXi86',['-ffast-math']).  :-
use_foreign_library('LINUXi86', m).

111.5.2 Addresses and C pointers
--------------------------------

The `address' type designates any pointer, and provides a means to
deal with C pointers in Prolog without interpreting them whatsoever.
The C source file which implements the operations accessed from
Prolog is declared with the

     :- use_foreign_source(objects_c).

   directive.

   *File* _objects.pl_:

   :- module(objects, [object/2, show_object/1], [foreign_interface]).

   :- true pred object(in(N),go(Object)) ::         int * address +
(foreign,returns(Object)).

   :- true pred show_object(in(Object)) ::         address + foreign.

   :- use_foreign_source(objects_c).  :- extra_compiler_opts('-O2').

   *File* _objects_c.c_:

   #include <stdio.h>

   struct object {   char *name;   char *colour; };

   #define OBJECTS 3

   struct object objects[OBJECTS] = { {"ring","golden"},
{"table","brown"},   {"bottle","green"} };

   struct object *object(int n) {   return  % OBJECTS]; }

   void show_object(struct object *o) {   printf("I show you a %s
%s\n", o->colour, o->name); }

111.5.3 Lists of bytes and buffers
----------------------------------

A list of bytes (c.f., a list of ints) corresponds to a byte buffer
in C. The length of the buffer is associated to that of the list
using the property `size_of/2'. The returned buffer *is freed by Ciao
Prolog* upon its recepction, unless the `do_not_free/1' property is
specified (see later). Conversely, a list of natural numbers in the
range 0 to 255 can be passed to C as a buffer.

   *File* _byte_lists.pl_:

   :- module(byte_lists, [obtain_list/3, show_list/2],
[foreign_interface]).

   :- true pred obtain_list(in(N),go(Length),go(List)) :: int * int *
byte_list         + (foreign,size_of(List,Length)).  :- true pred
show_list(in(Length),in(List)) :: int * byte_list         +
(foreign,size_of(List,Length)).

   :- use_foreign_source(bytes_op).

   *File* _bytes_op.c_:

   #include <stdlib.h> #include <stdio.h>

   void obtain_list(int n, int *l, char **s) {   int i;   int c;   if
(n < 0) n = 0;   *l = n;   *s = (char *)malloc(*l);   for (i = 0; i <
*l; i++) {     (*s)[i] = i;   } }

   void show_list(int l, char *s) {   if (s) {     int n;
printf("From C:");     for (n = 0; n < l; n++) {       printf(" %d",
s[n]);     }     printf(".\n");   } else {     printf("From C: []\n");
 } }

111.5.4 Lists of integers
-------------------------

*File* _int_lists.pl_:

   :- module(int_lists, [obtain_list/3, show_list/2],
[foreign_interface]).

   :- true pred obtain_list(in(N),go(Length),go(List)) :: int * int *
int_list         + (foreign,size_of(List,Length)).  :- true pred
show_list(in(Length),in(List)) :: int * int_list         +
(foreign,size_of(List,Length)).

   :- use_foreign_source(ints_op).

   *File* _ints_op.c_:

   #include <stdlib.h> #include <stdio.h>

   void obtain_list(int n, int *l, int **s) {   int i;   int c;   if
(n < 0) n = 0;   *l = n;   *s = (int *)malloc((*l) * sizeof(int));
for (i = 0; i < *l; i++) {     (*s)[i] = i;   } }

   void show_list(int l, int *s) {   if (s) {     int n;
printf("From C:");     for (n = 0; n < l; n++) {       printf(" %d",
s[n]);     }     printf(".\n");   } else {     printf("From C: []\n");
 } }

111.5.5 Strings and atoms
-------------------------

A C string can be seen as a buffer whose end is denoted by the
trailing zero, and therefore stating its length is not needed. Two
translations are possible into Ciao Prolog: as a Prolog string (list
of bytes, with no trailing zero) and as an atom. These are selected
automatically just by choosing the corresponding type (look at the
examples below).

   Note how the `do_not_free/1' property is specified in the `a_string/1'
predicate: the string returned by C is static, and therefore it
should not be freed by Prolog.

   *File* _strings_and_atoms.pl_:

   :- module(strings_and_atoms,         [ lookup_string/2,
lookup_atom/2,           a_string/1,           show_string/1,
 show_atom/1         ],         [foreign_interface]).

   :- true pred a_string(go(S)) ::         string +
(foreign(get_static_str),returns(S),do_not_free(S)).

   :- true pred lookup_string(in(N),go(S)) ::         int * string +
(foreign(get_str),returns(S)).  :- true pred lookup_atom(in(N),go(S))
::         int * atm + (foreign(get_str),returns(S)).

   :- true pred show_string(in(S)) :: string + foreign(put_str).  :-
true pred show_atom(in(S)) :: atm + foreign(put_str).

   :- use_foreign_source(str_op).

   *File* _str_op.c_:

   #include <stdlib.h> #include <stdio.h>

   char *get_static_str() {   return "this is a string Prolog should
not free"; }

   char *get_str(int n) {   char *s;   int size;   int i;   int c;
if (n < 0) n = -n;   size = (n%4) + 5;   s = (char *)malloc(size+1);
for (i = 0, c = ((i + n) % ('z' - 'a' + 1)) + 'a'; i < size;
i++,c++) {     if (c > 'z') c = 'a';     s[i] = c;   }   s[i] = 0;
return s; }

   void put_str(char *s) {   if (s) {     printf("From C: \"%s\"\n",
s);   } else {     printf("From C: null\n");   } }

111.5.6 Arbitrary Terms
-----------------------

This example shows how data Prolog can be passed untouched to C code,
and how it can be manipulated there.

   *File* _any_term.pl_:

   :- module(any_term,         [custom_display_term/1,
custom_create_term/2         ],         [foreign_interface]).

   :- true pred custom_display_term(in(X)) :: any_term + foreign.  :-
true pred custom_create_term(in(L), go(X)) :: int * any_term +
(foreign,returns(X)).

   :- use_foreign_source(any_term_c).  :- extra_compiler_opts('-O2').

   *File* _any_term_c.c_:

   #include <stdio.h> #include "ciao_prolog.h"

   ciao_term custom_create_term(int n) {   ciao_term t;   t =
ciao_empty_list();   while (n > 0) {     t =
ciao_list(ciao_integer(n), t);     n-;   }   return t; }

   void custom_display_term(ciao_term term) {   if
(ciao_is_atom(term)) {     printf("<atom name=\"%s\"/>",
ciao_atom_name(term));   } else if (ciao_is_structure(term)) {
int i;     int a;     a = ciao_structure_arity(term);
printf("<structure name=\"%s\" arity=\"%d\">",
ciao_structure_name(term), a);     for (i = 1; i <= a; i++) {
printf("<argument number=\"%d\">", i);
custom_display_term(ciao_structure_arg(term, i));
printf("</argument>");     }     printf("</structure>");   } else if
(ciao_is_list(term)) {     printf("<list>");     printf("<head>");
custom_display_term(ciao_list_head(term));     printf("</head>");
printf("<tail>");     custom_display_term(ciao_list_tail(term));
printf("</tail>");     printf("</list>");   } else if
(ciao_is_empty_list(term)) {     printf("<empty_list/>");   } else if
(ciao_is_integer(term)) {     printf("<integer value=\"%d\"/>",
ciao_to_integer(term));   } else if (ciao_is_number(term)) {
printf("<float value=\"%f\"/>", ciao_to_float(term));   } else {
printf("<unknown/>");   } }

111.5.7 Exceptions
------------------

The following example defines a predicate in C that converts a list
of codes into a number using `strtol()'. If this conversion fails,
then a exception is raised.

   *File* _exceptions_example.pl_:

   :- module(exceptions_example,         [codes_to_number_c/2,
 safe_codes_to_number/2         ],         [foreign_interface]).

   :- use_module(library(format)).

   % If the string is not a number raises an exception.  :- true pred
codes_to_number_c(in(X), go(Y)) :: string * int + (foreign,
returns(Y)).

   safe_codes_to_number(X, Y) :-         catch(codes_to_number_c(X,
Y), Error, handle_exception(Error)).

   handle_exception(Error) :- format("Exception caught ~w~n",
[Error]).

   :- use_foreign_source(exceptions_c).  :-
extra_compiler_opts('-O2').

   *File* _exceptions_c.c_:

   #include <string.h> #include "ciao_prolog.h"

   int codes_to_number_c(char *s) {   char *endptr;   int n;   n =
strtol(s,  10);   if (endptr == NULL || *endptr != '\0') {
ciao_raise_exception(ciao_structure("codes_to_number_exception",
                                  1,
       ciao_atom(s)));   }   return n; }

111.5.8 Testing number types and using unbound length integers
--------------------------------------------------------------

Unbound length integers (and, in general, any number) can be
converted to/from `ciao_terms' by using strings. The following
examples show two possibilities: one which tries to be as smart as
possible (checking whether numbers fit into a machine int or not),
and being lazy and simpler -and probably slower.

   *File* _bigints.pl_:

   :- module(bigints,         [           make_smart_conversion/3, %
Checks and uses convenient format           force_string_conversion/2
% Passes around using strings         ],
[foreign_interface]).

   :- true pred make_smart_conversion_c(in(X), go(Y), go(How))::
  any_term * any_term * any_term + foreign # "Given a number
@var{X}, it is unified with @var{Y} by using the most specific
internal representation (short integer, float, or long integer).
@var{How} returns how the conversion was done.  It behaves
unpredictably if @var{X} is not a number.".

   :- true pred force_string_conversion_c(in(X), go(Y))::
any_term * any_term + foreign # "Given a number @var{X}, it is
unified with @var{Y} by using the most general internal
representation (a string of characters). It behaves unpredictably if
@var{X} is not a number.".

   :- use_foreign_source(bigints_c).

   make_smart_conversion(A, B, C):-         number(A),
             % Safety test         make_smart_conversion_c(A, B, C).

   force_string_conversion(A, B):-         number(A),
            % Safety test         force_string_conversion_c(A, B).

   *File* _bigints_c.c_:

   #include "ciao_prolog.h"

   void make_smart_conversion_c(ciao_term  number_in,
            ciao_term *number_out,
ciao_term *how_converted) {   int    inter_int;   double inter_float;
 char * inter_str;

   if (ciao_fits_in_int(number_in)) {/* Includes the case of being a
float */     inter_int = ciao_to_integer(number_in);     *number_out
= ciao_integer(inter_int);     *how_converted =
ciao_atom("machine_integer");   } else     if
(ciao_is_integer(number_in)) { /* Big number */       inter_str   =
ciao_get_number_chars(number_in);       *number_out =
ciao_put_number_chars(inter_str);       ciao_free(inter_str);
*how_converted = ciao_atom("string");     } else { /* Must be a float
*/       inter_float = ciao_to_float(number_in);       *number_out =
ciao_float(inter_float);       *how_converted = ciao_atom("float");
 } }

   void force_string_conversion_c(ciao_term  number_in,
                ciao_term *number_out) {   char *inter_str;
inter_str  = ciao_get_number_chars(number_in);   *number_out =
ciao_put_number_chars(inter_str);   ciao_free(inter_str); }

111.6 Usage and interface (`foreign_interface')
===============================================

   * *Library usage:*

     The foreign interface is used by including `foreign_interface'
     in the include list of a module, or by means of an explicit `:-
     use_package(foreign_interface)'.

112 Foreign Language Interface Properties
*****************************************

*Author(s):* Jose Morales, Manuel Carro.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#229 (2003/12/22, 17:34:59 CET)

   The foreign language interface uses some properties to specify
linking regimes, foreign files to be compiled, types of data
available, memory allocation policies, etc.

112.1 Usage and interface (`foreign_interface_properties')
==========================================================

   * *Library usage:*

     `:- use_module(library(foreign_interface_properties)).'

   * *Exports:*
        - _Properties:_

          `native/1', `native/2', `size_of/3', `foreign/1', `foreign/2', `returns/2', `do_not_free/2'.

        - _Regular Types:_

          `int_list/1', `byte_list/1', `byte/1', `null/1', `address/1', `any_term/1'.

112.2 Documentation on exports (`foreign_interface_properties')
===============================================================

 -- REGTYPE: int_list/1:
     *Usage:* `int_list(List)'
        - _Description:_ `List' is a list of integers.

 -- REGTYPE: byte_list/1:
     *Usage:* `byte_list(List)'
        - _Description:_ `List' is a list of bytes.

 -- REGTYPE: byte/1:
     *Usage:* `byte(Byte)'
        - _Description:_ `Byte' is a byte.

 -- REGTYPE: null/1:
     *Usage:* `null(Address)'
        - _Description:_ `Address' is a null adress.

 -- REGTYPE: address/1:
     *Usage:* `address(Address)'
        - _Description:_ `Address' is a memory address.

 -- REGTYPE: any_term/1:
     *Usage:* `any_term(X)'
        - _Description:_ `X' is any term. The foreign interface
          passes it to C functions as a general term.

 -- PROPERTY: native/1:
     *Usage:* `native(Name)'
        - _Description:_ The Prolog predicate `Name' is implemented
          using the function `Name'. The implementation is not a
          common C one, but it accesses directly the internal Ciao
          Prolog data structures and functions, and therefore no glue
          code is generated for it.

 -- PROPERTY: native/2:
     *Usage:* `native(PrologName, ForeignName)'
        - _Description:_ The Prolog predicate `PrologName' is
          implemented using the function `ForeignName'. The same
          considerations as above example are to be applied.

 -- PROPERTY: size_of/3:
     *Usage:* `size_of(Name, ListVar, SizeVar)'
        - _Description:_ For predicate `Name', the size of the
          argument of type `byte_list/1', `ListVar', is given by the
          argument of type integer `SizeVar'.

 -- PROPERTY: foreign/1:
     *Usage:* `foreign(Name)'
        - _Description:_ The Prolog predicate `Name' is implemented
          using the foreign function `Name'.

 -- PROPERTY: foreign/2:
     *Usage:* `foreign(PrologName, ForeignName)'
        - _Description:_ The Prolog predicate `PrologName' is
          implemented using the foreign function `ForeignName'.

 -- PROPERTY: returns/2:
     *Usage:* `returns(Name, Var)'
        - _Description:_ The result of the foreign function that
          implements the Prolog predicate `Name' is unified with the
          Prolog variable `Var'. Cannot be used without `foreign/1' or `foreign/2'.

 -- PROPERTY: do_not_free/2:
     *Usage:* `do_not_free(Name, Var)'
        - _Description:_ For predicate `Name', the C argument passed
          to (returned from) the foreign function will not be freed
          after calling the foreign function.

112.3 Documentation on internals (`foreign_interface_properties')
=================================================================

 -- DECLARATION: use_foreign_source/1:
     *Usage:* :- `use_foreign_source(Files)'.
        - _Description:_ `Files' is the (list of) foreign file(s)
          that will be linked with the glue-code file.

        - _The following properties hold at call time:_

          `Files' is an atom or a list of atoms.
          (`basic_props:atm_or_atm_list/1')

 -- DECLARATION: use_foreign_source/2:
     *Usage:* :- `use_foreign_source(OsArch, Files)'.
        - _Description:_ `Files' are the OS and architecture
          dependant foreign files. This allows compiling and linking
          different files depending on the O.S. and architecture.

        - _The following properties hold at call time:_

          `OsArch' is an atom.   (`basic_props:atm/1')

          `Files' is an atom or a list of atoms.
          (`basic_props:atm_or_atm_list/1')

 -- DECLARATION: use_foreign_library/1:
     *Usage:* :- `use_foreign_library(Libs)'.
        - _Description:_ `Libs' is the (list of) external library(es)
          needed to link the C files. Only the short name of the
          library (i.e., what would follow the `-l' in the linker is
          needed.

        - _The following properties hold at call time:_

          `Libs' is an atom or a list of atoms.
          (`basic_props:atm_or_atm_list/1')

 -- DECLARATION: use_foreign_library/2:
     *Usage:* :- `use_foreign_library(OsArch, Libs)'.
        - _Description:_ `Libs' are the OS and architecture dependant
          libraries.

        - _The following properties hold at call time:_

          `OsArch' is an atom.   (`basic_props:atm/1')

          `Libs' is an atom or a list of atoms.
          (`basic_props:atm_or_atm_list/1')

 -- DECLARATION: extra_compiler_opts/1:
     *Usage:* :- `extra_compiler_opts(Opts)'.
        - _Description:_ `Opts' is the list of additional compiler
          options (e.g., optimization options) that will be used
          during the compilation.

        - _The following properties hold at call time:_

          `Opts' is an atom or a list of atoms.
          (`basic_props:atm_or_atm_list/1')

 -- DECLARATION: extra_compiler_opts/2:
     *Usage:* :- `extra_compiler_opts(OsArch, Opts)'.
        - _Description:_ `Opts' are the OS and architecture dependant
          additional compiler options.

        - _The following properties hold at call time:_

          `OsArch' is an atom.   (`basic_props:atm/1')

          `Opts' is an atom or a list of atoms.
          (`basic_props:atm_or_atm_list/1')

 -- DECLARATION: use_compiler/1:
     *Usage:* :- `use_compiler(Compiler)'.
        - _Description:_ `Compiler' is the compiler to use in this
          file. When this option is used, the default (Ciao-provided)
          compiler options are not used; those specified in `extra_compiler_options'
          are used instead.

        - _The following properties hold at call time:_

          `Compiler' is an atom.   (`basic_props:atm/1')

 -- DECLARATION: use_compiler/2:
     *Usage:* :- `use_compiler(OsArch, Compiler)'.
        - _Description:_ `Compiler' is the compiler to use in this
          file when compiling for the architecture `OsArch'. The
          option management is the same as in `use_compiler/2'.

        - _The following properties hold at call time:_

          `OsArch' is an atom.   (`basic_props:atm/1')

          `Compiler' is an atom.   (`basic_props:atm/1')

 -- DECLARATION: extra_linker_opts/1:
     *Usage:* :- `extra_linker_opts(Opts)'.
        - _Description:_ `Opts' is the list of additional linker
          options that will be used during the linkage.

        - _The following properties hold at call time:_

          `Opts' is an atom or a list of atoms.
          (`basic_props:atm_or_atm_list/1')

 -- DECLARATION: extra_linker_opts/2:
     *Usage:* :- `extra_linker_opts(OsArch, Opts)'.
        - _Description:_ `Opts' are the OS and architecture dependant
          additional linker options.

        - _The following properties hold at call time:_

          `OsArch' is an atom.   (`basic_props:atm/1')

          `Opts' is an atom or a list of atoms.
          (`basic_props:atm_or_atm_list/1')

 -- DECLARATION: use_linker/1:
     *Usage:* :- `use_linker(Linker)'.
        - _Description:_ `Linker' is the linker to use in this file.
          When this option is used, the default (Ciao-provided)
          linker options are not used; those specified in `extra_linker_options/1'
          are used instead.

        - _The following properties hold at call time:_

          `Linker' is an atom.   (`basic_props:atm/1')

 -- DECLARATION: use_linker/2:
     *Usage:* :- `use_linker(OsArch, Linker)'.
        - _Description:_ `Compiler' is the linker to use in this file
          when compiling for the architecture `OsArch'. The option
          management is the same as in `use_compiler/2'.

        - _The following properties hold at call time:_

          `OsArch' is an atom.   (`basic_props:atm/1')

          `Linker' is an atom.   (`basic_props:atm/1')

112.4 Known bugs and planned improvements (`foreign_interface_properties')
==========================================================================

   * The `size_of/3' property has an empty definition

113 Utilities for on-demand compilation of foreign files
********************************************************

*Author(s):* Manuel Carro, Jose Morales.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.3#36 (1999/7/20, 10:37:31 MEST)

   This module provides two predicates which give the user
information regarding how to compile external (C) files in order to
link them with the Ciao Prolog engine at runtime.

   These predicates are not intended to be called directly by the
end-user. Instead, a tool or module whose aim is generating
dynamically loadable files from source files should use the
predicates in this file in order to find out what are the proper
compiler and linker to use, and which options must be passed to them
in the current architecture.

113.1 Usage and interface (`foreign_compilation')
=================================================

   * *Library usage:*

     `:- use_module(library(foreign_compilation)).'

   * *Exports:*
        - _Predicates:_

          `compiler_and_opts/2', `linker_and_opts/2'.

   * *Other modules used:*
        - _System library modules:_

          `system'.

113.2 Documentation on exports (`foreign_compilation')
======================================================

 -- PREDICATE: compiler_and_opts/2:
     *Usage:* `compiler_and_opts(?Compiler, ?Opts)'
        - _Description:_ If you want to compile a foreign language
          file for dynamic linking in the current operating system
          and architecture, you have to use the compiler `Compiler'
          and give it the options `Opts'. A variable in `Opts' means
          that no special option is needed.

        - _The following properties should hold at call time:_

          `?Compiler' is currently instantiated to an atom.
          (`term_typing:atom/1')

          `?Opts' is a list of `atom's.   (`basic_props:list/2')

 -- PREDICATE: linker_and_opts/2:
     *Usage:* `linker_and_opts(?Linker, ?Options)'
        - _Description:_ If you want to link a foreign language file
          for dynamic linking in the current operating system and
          architecture, you have to use the linker `Compiler' and
          gite it the options `Opts'. A variable in `Opts' means that
          no special option is needed.

        - _The following properties should hold at call time:_

          `?Linker' is currently instantiated to an atom.
          (`term_typing:atom/1')

          `?Options' is a list of `atom's.   (`basic_props:list/2')

114 Foreign Language Interface Builder
**************************************

*Author(s):* Jose Morales, Manuel Carro.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#252 (2003/12/30, 22:15:50 CET)

   Low-level utilities for building foreign interfaces. End-users
should not need to use them, as the Ciao Prolog Compiler reads the
user assertions and calls appropriately the predicates in this module.

114.1 Usage and interface (`build_foreign_interface')
=====================================================

   * *Library usage:*

     `:- use_module(library(build_foreign_interface)).'

   * *Exports:*
        - _Predicates:_

          `build_foreign_interface/1', `rebuild_foreign_interface/1', `build_foreign_interface_explicit_decls/2', `rebuild_foreign_interface_explicit_decls/2', `build_foreign_interface_object/1', `rebuild_foreign_interface_object/1', `do_interface/1'.

   * *Other modules used:*
        - _System library modules:_

          `write_c/write_c', `streams', `terms', `lists', `llists', `aggregates', `system', `format', `messages', `assertions/assrt_lib', `foreign_compilation', `compiler/c_itf', `ctrlcclean', `errhandle'.

114.2 Documentation on exports (`build_foreign_interface')
==========================================================

 -- PREDICATE: build_foreign_interface/1:
     *Usage:* `build_foreign_interface(in(File))'
        - _Description:_ Reads assertions from `File', generates the
          gluecode for the Ciao Prolog interface, compiles the
          foreign files and the gluecode file, and links everything
          in a shared object. Checks modification times to determine
          automatically which files must be generated/compiled/linked.

        - _Call and exit should be _compatible_ with:_

          `in(File)' is a source name.
          (`streams_basic:sourcename/1')

 -- PREDICATE: rebuild_foreign_interface/1:
     *Usage:* `rebuild_foreign_interface(in(File))'
        - _Description:_ Like `build_foreign_interface/1', but it
          does not check the modification time of any file.

        - _Call and exit should be _compatible_ with:_

          `in(File)' is a source name.
          (`streams_basic:sourcename/1')

 -- PREDICATE: build_foreign_interface_explicit_decls/2:
     *Usage:* `build_foreign_interface_explicit_decls(in(File),
     in(Decls))'
        - _Description:_ Like `build_foreign_interface/1', but use
          declarations in `Decls' instead of reading the declarations
          from `File'.

        - _Call and exit should be _compatible_ with:_

          `in(File)' is a source name.
          (`streams_basic:sourcename/1')

          `in(Decls)' is a list of `term's.   (`basic_props:list/2')

 -- PREDICATE: rebuild_foreign_interface_explicit_decls/2:
     *Usage:* `rebuild_foreign_interface_explicit_decls(in(File),
     in(Decls))'
        - _Description:_ Like `build_foreign_interface_explicit_decls/1',
          but it does not check the modification time of any file.

        - _Call and exit should be _compatible_ with:_

          `in(File)' is a source name.
          (`streams_basic:sourcename/1')

          `in(Decls)' is a list of `term's.   (`basic_props:list/2')

 -- PREDICATE: build_foreign_interface_object/1:
     *Usage:* `build_foreign_interface_object(in(File))'
        - _Description:_ Compiles the gluecode file with the foreign
          source files producing an unique object file.

        - _Call and exit should be _compatible_ with:_

          `in(File)' is a source name.
          (`streams_basic:sourcename/1')

 -- PREDICATE: rebuild_foreign_interface_object/1:
     *Usage:* `rebuild_foreign_interface_object(in(File))'
        - _Description:_ Compiles (again) the gluecode file with the
          foreign source files producing an unique object file.

        - _Call and exit should be _compatible_ with:_

          `in(File)' is a source name.
          (`streams_basic:sourcename/1')

 -- PREDICATE: do_interface/1:
     *Usage:* `do_interface(in(Decls))'
        - _Description:_ Given the declarations in `Decls', this
          predicate succeeds if these declarations involve the
          creation of the foreign interface

        - _Call and exit should be _compatible_ with:_

          `in(Decls)' is a list of `term's.   (`basic_props:list/2')

115 Interface to daVinci
************************

*Author(s):* Francisco Bueno.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#76 (2003/4/14, 18:31:46 CEST)

   This library allows connecting a Ciao Prolog application with
daVinci V2.X.

   The communication is based on a two-way channel: after daVinci is
started, messages are sent in to it and read in from it on demand by
different Prolog predicates. Messages are sent via writing the term
as text; messages are received by reading text and returning an atom.
Commands sent and answers received are treated as terms from the
Prolog side, since for daVinci they are text but have term syntax;
the only difficulty lies in strings, for which special Prolog syntax
is provided.

   See accompanying file `library('davinci/commands')' for examples
on the use of this library.

   daVinci is developed by U. of Bremen, Germany.

115.1 Usage and interface (`davinci')
=====================================

   * *Library usage:*

     `:- use_module(library(davinci)).'

   * *Exports:*
        - _Predicates:_

          `davinci/0', `topd/0', `davinci_get/1', `davinci_get_all/1', `davinci_put/1', `davinci_quit/0', `davinci_ugraph/1', `davinci_lgraph/1', `ugraph2term/2', `formatting/2'.

   * *Other modules used:*
        - _System library modules:_

          `aggregates', `prompt', `errhandle', `format', `read', `graphs/ugraphs', `write', `system', `sets', `sort'.

115.2 Documentation on exports (`davinci')
==========================================

 -- PREDICATE: davinci/0:
     Start up a daVinci process.

 -- PREDICATE: topd/0:
     A toplevel to send to daVinci commands from standard input.

 -- PREDICATE: davinci_get/1:
     *Usage:* `davinci_get(Term)'
        - _Description:_ Get a message from daVinci. `Term' is a term
          corresponding to daVinci's message.

 -- PREDICATE: davinci_get_all/1:
     *Usage:* `davinci_get_all(List)'
        - _Description:_ Get all pending messages. `List' is a list
          of terms as in `davinci_get/1'.

        - _The following properties should hold upon exit:_

          `List' is a list.   (`basic_props:list/1')

 -- PREDICATE: davinci_put/1:
     *Usage:* `davinci_put(Term)'
        - _Description:_ Send a command to daVinci.

        - _The following properties should hold at call time:_

          `davinci:davinci_command(Term)'
          (`davinci:davinci_command/1')

 -- PREDICATE: davinci_quit/0:
     Exit daVinci process. All pending answers are lost!

 -- PREDICATE: davinci_ugraph/1:
     *Usage:* `davinci_ugraph(Graph)'
        - _Description:_ Send a graph to daVinci.

        - _The following properties should hold at call time:_

          `davinci:ugraph(Graph)'  (`davinci:ugraph/1')

 -- PREDICATE: davinci_lgraph/1:
     *Usage:* `davinci_lgraph(Graph)'
        - _Description:_ Send a labeled graph to daVinci.

        - _The following properties should hold at call time:_

          `davinci:lgraph(Graph)'  (`davinci:lgraph/1')

 -- PREDICATE: ugraph2term/2:
     No further documentation available for this predicate.

 -- PREDICATE: formatting/2:
     No further documentation available for this predicate.

115.3 Documentation on internals (`davinci')
============================================

 -- PROPERTY: davinci_command/1:
     Syntactically, a command is a term. Semantically, it has to
     correspond to a command understood by daVinci. Two terms are
     interpreted in a special way: `string/1' and `text/1':
     `string(Term)' is given to daVinci as `"Term"'; `text(List)' is
     given as `"Term1 Term2 ...Term "' for each `Term' in `List'. If
     your term has functors `string/1' and `text/1' that you don't
     want to be interpreted this way, use it twice, i.e.,
     `string(string(Term))' is given to daVinci as `string(Term')'
     where `Term'' is the interpretation of `Term'.

 -- PROPERTY: ugraph/1:
     `ugraph(Graph)'

     `Graph' is a term which denotes an ugraph as in
     `library(ugraphs)'. Vertices of the form `node/2' are
     interpreted in a special way: `node(Term,List)' is interpreted
     as a vertex `Term' with attributes `List'. `List' is a list of
     terms conforming the syntax of `davinci_put/1' and corresponding
     to daVinci's graph nodes attributes. If your vertex has functor
     `node/2' and you don't want it to be interpreted this way, use
     it twice, i.e., `node(node(T1,T2),[])' is given to daVinci as
     vertex `node(T1,T2)'. A vertex is used both as label and name of
     daVinci's graph node. daVinci's graph edges have label `V1-V2'
     where `V1' is the source and `V2' the sink of the edge. There is
     no support for multiple edges between the same two vertices.

 -- PROPERTY: lgraph/1:
     `lgraph(Graph)'

     `Graph' is a term which denotes a wgraph as in
     `library('graphs/wgraphs')', except that the weights are labels,
     i.e., they do not need to be integers. Vertices of the form
     `node/2' are interpreted in a special way. Edge labels are
     converted into special intermediate vertices. Duplicated labels
     are solved by adding dummy atoms `'''. There is no support for
     multiple edges between the same two vertices.

116 The Tcl/Tk interface
************************

*Author(s):* Montse Iglesias Urraca,
`http://www.clip.dia.fi.upm.es/', The CLIP Group, Facultad de
Informa'tica, Universidad Polite'cnica de Madrid.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#314 (2004/2/25, 18:27:47 CET)

   The `tcltk' library package is a bidirectional interface to the
_Tcl_ language and the _Tk_ toolkit. Tcl is an interpreted scripting
language with many extension packages, particularly the graphical
interface toolkit, Tk. The interaction between both languages is
expressed in terms of an interface between the Tcl/Tk process and the
Prolog process. This approach allows the development of mixed
applications where both sides, Tcl/Tk and Prolog, can be combined in
order to exploit their respective capabilities.

   This library uses two sockets to connect both the Tcl and the
Prolog processes: _event_socket_ and _term_socket_. There are also
two Tcl global variables: _prolog_variables_ and _terms_. The value
of any of the bound variables in a goal will be stored in the array
`prolog_variables' with the variable name as index. _Terms_ is the
string which contains the printed representation of prolog _terms_.

*Prolog to Tcl*

   The Tcl/Tk side waits for requests from the Prolog side, and
executes the Tcl/Tk code received. Also, the Tcl/Tk side handles the
events and exceptions which may be raised on its side, passing on
control to the Prolog side in case it is necessary.

   To use Tcl, you must create a _Tcl interpreter_ object and send
commands to it. A _Tcl_ command is specified as follows:

           Command         --> Atom  { other than [] }
                             | Number
                             | chars(PrologString)
                             | write(Term)
                             | format(Fmt,Args)
                             | dq(Command)
                             | br(Command)
                             | sqb(Command)
                             | min(Command)
                             | ListOfCommands
           ListOfCommands  --> []
                             |[Command|ListOfCommands]

   where:

`Atom'
     denotes the printed representation of the atom.

`Number'
     denotes their printed representations.

`chars(PrologString)'
     denotes the string represented by _PrologString_ (a list of
     character codes).

`write(Term)'
     denotes the string that is printed by the corresponding built-in
     predicate.

`format(Term)'
     denotes the string that is printed by the corresponding built-in
     predicate.

`dq(Command)'
     denotes the string specified by _Command_, enclosed in double
     quotes.

`br(Command)'
     denotes the string specified by _Command_, enclosed in braces.

`sqb(Command)'
     denotes the string specified by _Command_, enclosed in square
     brackets.

`min(Command)'
     denotes the string specified by _Command_, immediately preceded
     by a hyphen.

`ListOfCommands'
     denotes the strings denoted by each element, separated by spaces.

   The predicates to use Tcl from Prolog are `tcl_new/1', `tcl_delete/1', `tcl_eval/3',
and `tcl_event/3'.

An example of use with Prolog as master and Tcl as slave, consisting
of a GUI to a program which calculates the factorial of a number:

     :- use_module(library(tcltk)).

     go :-
             tcl_new(X),
             tcl_eval(X,[button,'.b',min(text),dq('Compute!')],_),
             tcl_eval(X,[button,'.c','-text',dq('Quit')],_),
             tcl_eval(X,[entry,'.e1',min(textvariable),'inputval'],_),
             tcl_eval(X,[label,'.l1',min(text),dq('The factorial of ')],_),
             tcl_eval(X,[pack, '.l1','.e1'],_),
             tcl_eval(X,[entry,'.e2',min(textvariable),'outputval'],_),
             tcl_eval(X,[label,'.l2',min(text),dq('is  ')],_),
             tcl_eval(X,[pack, '.l2','.e2'],_),
             tcl_eval(X,[pack,'.b','.c',min(side),'left'],_),
             tcl_eval(X,[bind,'.b','<ButtonPress-1>',
                         br([set,'inputval','$inputval','\n',
                         prolog_one_event,dq(write(execute(tk_test_aux:factorial('$inputval','Outputval')))),'\n',
                         set, 'outputval','$prolog_variables(Outputval)'])],_),
             tcl_eval(X,[bind,'.c','<ButtonPress-1>',
                         br([prolog_one_event,dq(write(execute(exit_tk_event_loop)))])],_),
             tk_event_loop(X).

*Tcl to Prolog*

   This is the usual way to build a GUI application. The slave,
Prolog, behaves as a server that fulfills eventual requests from the
master side, Tcl. At some point, during the user interaction with the
GUI, an action may take place that triggers the execution of some
procedure on the slave side (a form submit, for example). Thus, the
slave is invoked, performs a service, and returns the result to the
GUI through the socket connection.

   This library includes two main specific Tcl commands:

`prolog' _Goal_
     _Goal_ is a string containing the printed representation of a
     Prolog goal. The goal will be called in the user module unless
     it is prefixed with another module name. The call is always
     deterministic and its can be either of the following:

    _1_, in case of success
          The value of any of the variables in the goal that is bound
          to a term will be returned to Tcl in the array
          prolog_variables with the variable name as index.

    _0_, if the execution fails
          The Prolog exception Tcl exception is raised. The error
          message will be "Prolog Exception: " appended with a string
          representation of such exception.

`prolog_event' _Term_
     Adds the new _term_ to the _terms_ queue. These can be later
     retrieved through predicates `tcl_event/3' and `tk_next_event/2'.

   Additionally, seven extra Tcl commands are defined.

`prolog_delete_event'
     Deletes the first _term_ of the _terms_ queue.

`prolog_list_events'
     Sends all the _terms_ of the _terms_ queue through the
     _event_socket_. The last element is _end_of_event_list_.

`prolog_cmd' _Command_
     Receives as an argument the Tcl/Tk code, evaluates it and
     returns through the _term_socket_ the term _tcl_error_ in case
     of error or the term _tcl_result_ with the result of the command
     executed. If the command is _prolog_, upon return, the goal run
     on the prolog side is received. In order to get the value of the
     variables, predicates are compared using the _unify_term_
     command. Returns 0 when the sript runs without errors, and 1 if
     there is an error.

`prolog_one_event' _Term_
     Receives as an argument the _term_ associated to one of the Tk
     events. Sends the _term_ through the _event_socket_ and waits
     for its unification. Then _unify_term_ command is called to
     update the _prolog_variables_ array.

`prolog_thread_event' _Term_
     Receives as an argument the _term_ associated to one of the Tk
     events. Sends the _term_ through the _event_socket_ and waits
     for its unification. Then _unify_term_ command is called to
     update the _prolog_variables_ array. In this case the
     _term_socket_ is non blocking.

`convert_variables' _String_
     Its argument is a string containing symbols that can not be sent
     through the sockets. This procedure deletes them from the input
     string and returns the new string.

`unify_term' _Term1_ _Term2_
     Unifies _Term1_ and _Term2_ and updates the the
     _prolog_variables_ array.

   The predicates to use Prolog from Tcl are `tk_event_loop/1', `tk_main_loop/1', `tk_new/2',
and `tk_next_event/2'.

An example of use with Tcl as master and Prolog as slave,
implementing the well known "Hello, world!" dummy program (more can
be seen in directory examples):

   Prolog side:

     :- use_module(library(tcltk)).
     :- use_package(classic).

     hello('Hello, world!').

     go :-
             tk_new([name('Simple')], Tcl),
             tcl_eval(Tcl, 'source simple.tcl', _),
             tk_main_loop(Tcl),
             tcl_delete(Tcl).

   Tcl side (simple.tcl):

     label .l -textvariable tvar
     button .b -text "Go!" -command {run}
     pack .l .b -side top

     proc run {} {

         global prolog_variables
         global tvar

         prolog hello(X)
         set tvar $prolog_variables(X)
     }

116.1 Usage and interface (`tcltk')
===================================

   * *Library usage:*

     `:- use_module(library(tcltk)).'

   * *Exports:*
        - _Predicates:_

          `tcl_new/1', `tcl_eval/3', `tcl_delete/1', `tcl_event/3', `tk_event_loop/1', `tk_main_loop/1', `tk_new/2', `tk_next_event/2'.

        - _Regular Types:_

          `tclInterpreter/1', `tclCommand/1'.

   * *Other modules used:*
        - _System library modules:_

          `tcltk/tcltk_low_level', `iso_misc', `write', `strings', `lists'.

116.2 Documentation on exports (`tcltk')
========================================

 -- PREDICATE: tcl_new/1:
     *Usage:* `tcl_new(-TclInterpreter)'
        - _Description:_ Creates a new interpreter, initializes it,
          and returns a handle to it in `TclInterpreter'.

        - _Call and exit should be _compatible_ with:_

          `-TclInterpreter' is a reference to a _Tcl_ interpreter.
          (`tcltk:tclInterpreter/1')

 -- PREDICATE: tcl_eval/3:
     _Meta-predicate_ with arguments: `tcl_eval(?,?,addmodule)'.

     *Usage:* `tcl_eval(+TclInterpreter, +Command, -Result)'
        - _Description:_ Evaluates the commands given in `Command' in
          the Tcl interpreter `TclInterpreter'. The result will be
          stored as a string in `Result'. If there is an error in
          _Command_ an exception is raised. The error messages will
          be _Tcl Exception:_ if the error is in the syntax of the
          Tcl/Tk code or _Prolog Exception:_, if the error is in the
          prolog term.

        - _Call and exit should be _compatible_ with:_

          `+TclInterpreter' is a reference to a _Tcl_ interpreter.
          (`tcltk:tclInterpreter/1')

          `+Command' is a _Tcl_ command.   (`tcltk:tclCommand/1')

          `-Result' is a string (a list of character codes).
          (`basic_props:string/1')

 -- PREDICATE: tcl_delete/1:
     *Usage:* `tcl_delete(+TclInterpreter)'
        - _Description:_ Given a handle to a Tcl interpreter in
          variable `TclInterpreter', it deletes the interpreter from
          the system.

        - _Call and exit should be _compatible_ with:_

          `+TclInterpreter' is a reference to a _Tcl_ interpreter.
          (`tcltk:tclInterpreter/1')

 -- PREDICATE: tcl_event/3:
     *Usage:* `tcl_event(+TclInterpreter, +Command, -Events)'
        - _Description:_ Evaluates the commands given in `Command' in
          the Tcl interpreter whose handle is provided in
          `TclInterpreter'. `Events' is a list of terms stored from
          Tcl by _prolog_event_. Blocks until there is something on
          the event queue

        - _Call and exit should be _compatible_ with:_

          `+TclInterpreter' is a reference to a _Tcl_ interpreter.
          (`tcltk:tclInterpreter/1')

          `+Command' is a _Tcl_ command.   (`tcltk:tclCommand/1')

          `-Events' is a list.   (`basic_props:list/1')

 -- REGTYPE: tclInterpreter/1:
     *Usage:* `tclInterpreter(I)'
        - _Description:_ `I' is a reference to a _Tcl_ interpreter.

 -- REGTYPE: tclCommand/1:
     *Usage:* `tclCommand(C)'
        - _Description:_ `C' is a _Tcl_ command.

 -- PREDICATE: tk_event_loop/1:
     *Usage:* `tk_event_loop(+TclInterpreter)'
        - _Description:_ Waits for an event and executes the goal
          associated to it. Events are stored from Tcl with the
          _prolog_ command. The unified term is sent to the Tcl
          interpreter in order to obtain the value of the tcl array
          of _prolog_variables_. If the term received does not have
          the form `execute(Goal)', the predicate silently exits. If
          the execution of `Goal' raises a Prolog error, the
          interpreter is deleted and an error message is given.

        - _Call and exit should be _compatible_ with:_

          `+TclInterpreter' is a reference to a _Tcl_ interpreter.
          (`tcltk:tclInterpreter/1')

 -- PREDICATE: tk_main_loop/1:
     *Usage:* `tk_main_loop(+TclInterpreter)'
        - _Description:_ Passes control to Tk until all windows are
          gone.

        - _Call and exit should be _compatible_ with:_

          `+TclInterpreter' is a reference to a _Tcl_ interpreter.
          (`tcltk:tclInterpreter/1')

 -- PREDICATE: tk_new/2:
     *Usage:* `tk_new(+Options, -TclInterpreter)'
        - _Description:_ Performs basic Tcl and Tk initialization and
          creates the main window of a Tk application.`Options' is a
          list of optional elements according to:

         `name(+ApplicationName)'
               Sets the Tk main window title to `ApplicationName'. It
               is also used for communicating between Tcl/Tk
               applications via the Tcl _send_ command. Default name
               is an empty string.

         `display(+Display)'
               Gives the name of the screen on which to create the
               main window. Default is normally determined by the
               `DISPLAY' environment variable.

         `file'
               Opens the sript `file'. Commands will not be read from
               standard input and the execution returns back to
               Prolog only after all windows (and the interpreter)
               have been deleted.

        - _Call and exit should be _compatible_ with:_

          `+Options' is a list.   (`basic_props:list/1')

          `-TclInterpreter' is a reference to a _Tcl_ interpreter.
          (`tcltk:tclInterpreter/1')

 -- PREDICATE: tk_next_event/2:
     *Usage:* `tk_next_event(+TclInterpreter, -Event)'
        - _Description:_ Processes events until there is at least one
          Prolog event associated with `TclInterpreter'. `Event' is
          the term correspondig to the head of a queue of events
          stored from Tcl with the _prolog_event_ command.

        - _Call and exit should be _compatible_ with:_

          `+TclInterpreter' is a reference to a _Tcl_ interpreter.
          (`tcltk:tclInterpreter/1')

          `-Event' is a string (a list of character codes).
          (`basic_props:string/1')

117 Low level interface library to Tcl/Tk
*****************************************

*Author(s):* Montse Iglesias Urraca.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#348 (2004/6/8, 12:6:40 CEST)

   The `tcltk_low_level' library defines the low level interface used
by the `tcltk' library. Essentially it includes all the code related
directly to the handling of sockets and processes. This library
should normally not be used directly by user programs, which use `tcltk'
instead. On the other hand in some cases it may be useful to
undertand how this library works in order to understand possible
problems in programs that use the `tcltk' library.

117.1 Usage and interface (`tcltk_low_level')
=============================================

   * *Library usage:*

     `:- use_module(library(tcltk_low_level)).'

   * *Exports:*
        - _Predicates:_

          `new_interp/1', `new_interp/2', `new_interp_file/2', `tcltk/2', `tcltk_raw_code/2', `receive_result/2', `send_term/2', `receive_event/2', `receive_list/2', `receive_confirm/2', `delete/1'.

   * *Other modules used:*
        - _System library modules:_

          `terms', `sockets/sockets', `system', `write', `read', `strings', `lists', `format'.

117.2 Documentation on exports (`tcltk_low_level')
==================================================

 -- PREDICATE: new_interp/1:
     *Usage:* `new_interp(-TclInterpreter)'
        - _Description:_ Creates two sockets to connect to the _wish_
          process, the term socket and the event socket, and opens a
          pipe to process _wish_ in a new shell.

        - _Call and exit should be _compatible_ with:_

          `-TclInterpreter' is a reference to a _Tcl_ interpreter.
          (`tcltk_low_level:tclInterpreter/1')

 -- PREDICATE: new_interp/2:
     *Usage:* `new_interp(-TclInterpreter, +Options)'
        - _Description:_ Creates two sockets, the term socket and the
          event socket, and opens a pipe to process _wish_ in a new
          shell invoked with the `Options'.

        - _Call and exit should be _compatible_ with:_

          `-TclInterpreter' is a reference to a _Tcl_ interpreter.
          (`tcltk_low_level:tclInterpreter/1')

          `+Options' is currently instantiated to an atom.
          (`term_typing:atom/1')

 -- PREDICATE: new_interp_file/2:
     *Usage:* `new_interp_file(+FileName, -TclInterpreter)'
        - _Description:_ Creates two sockets, the term socket and the
          event socket, and opens a pipe to process _wish_ in a new
          shell invoked with a `FileName'. `FileName' is treated as a
          name of a sript file

        - _Call and exit should be _compatible_ with:_

          `+FileName' is a string (a list of character codes).
          (`basic_props:string/1')

          `-TclInterpreter' is a reference to a _Tcl_ interpreter.
          (`tcltk_low_level:tclInterpreter/1')

 -- PREDICATE: tcltk/2:
     *Usage:* `tcltk(+Code, +TclInterpreter)'
        - _Description:_ Sends the `Code' converted to string to the
          `TclInterpreter'

        - _Call and exit should be _compatible_ with:_

          `+Code' is a _Tcl_ command.
          (`tcltk_low_level:tclCommand/1')

          `+TclInterpreter' is a reference to a _Tcl_ interpreter.
          (`tcltk_low_level:tclInterpreter/1')

 -- PREDICATE: tcltk_raw_code/2:
     *Usage:* `tcltk_raw_code(+String, +TclInterpreter)'
        - _Description:_ Sends the tcltk code items of the `Stream'
          to the `TclInterpreter'

        - _Call and exit should be _compatible_ with:_

          `+String' is a string (a list of character codes).
          (`basic_props:string/1')

          `+TclInterpreter' is a reference to a _Tcl_ interpreter.
          (`tcltk_low_level:tclInterpreter/1')

 -- PREDICATE: receive_result/2:
     *Usage:* `receive_result(-Result, +TclInterpreter)'
        - _Description:_ Receives the `Result' of the last
          _TclCommand_ into the `TclInterpreter'. If the _TclCommand_
          is not correct the _wish_ process is terminated and a
          message appears showing the error

        - _Call and exit should be _compatible_ with:_

          `-Result' is a string (a list of character codes).
          (`basic_props:string/1')

          `+TclInterpreter' is a reference to a _Tcl_ interpreter.
          (`tcltk_low_level:tclInterpreter/1')

 -- PREDICATE: send_term/2:
     *Usage:* `send_term(+String, +TclInterpreter)'
        - _Description:_ Sends the goal executed to the
          `TclInterpreter'. `String' has the predicate with unified
          variables

        - _Call and exit should be _compatible_ with:_

          `+String' is a string (a list of character codes).
          (`basic_props:string/1')

          `+TclInterpreter' is a reference to a _Tcl_ interpreter.
          (`tcltk_low_level:tclInterpreter/1')

 -- PREDICATE: receive_event/2:
     *Usage:* `receive_event(-Event, +TclInterpreter)'
        - _Description:_ Receives the `Event' from the event socket
          of the `TclInterpreter'.

        - _Call and exit should be _compatible_ with:_

          `-Event' is a list.   (`basic_props:list/1')

          `+TclInterpreter' is a reference to a _Tcl_ interpreter.
          (`tcltk_low_level:tclInterpreter/1')

 -- PREDICATE: receive_list/2:
     *Usage:* `receive_list(-List, +TclInterpreter)'
        - _Description:_ Receives the `List' from the event socket of
          the `TclInterpreter'.The `List' has all the predicates that
          have been inserted from Tcl/Tk with the command
          prolog_event. It is a list of terms.

        - _Call and exit should be _compatible_ with:_

          `-List' is a list.   (`basic_props:list/1')

          `+TclInterpreter' is a reference to a _Tcl_ interpreter.
          (`tcltk_low_level:tclInterpreter/1')

 -- PREDICATE: receive_confirm/2:
     *Usage:* `receive_confirm(-String, +TclInterpreter)'
        - _Description:_ Receives the `String' from the event socket
          of the `TclInterpreter' when a term inserted into the event
          queue is managed.

        - _Call and exit should be _compatible_ with:_

          `-String' is a string (a list of character codes).
          (`basic_props:string/1')

          `+TclInterpreter' is a reference to a _Tcl_ interpreter.
          (`tcltk_low_level:tclInterpreter/1')

 -- PREDICATE: delete/1:
     *Usage:* `delete(+TclInterpreter)'
        - _Description:_ Terminates the _wish_ process and closes the
          pipe, term socket and event socket. Deletes the interpreter
          `TclInterpreter' from the system

        - _Call and exit should be _compatible_ with:_

          `+TclInterpreter' is a reference to a _Tcl_ interpreter.
          (`tcltk_low_level:tclInterpreter/1')

117.3 Documentation on internals (`tcltk_low_level')
====================================================

 -- PREDICATE: core/1:
     *Usage:* `core(+String)'
        - _Description:_ `core/1' is a set of facts which contain
          `String's to be sent to the Tcl/Tk interpreter on startup.
          They implement miscelaneous Tcl/Tk procedures which are
          used by the Tcl/Tk interface.

        - _Call and exit should be _compatible_ with:_

          `+String' is a string (a list of character codes).
          (`basic_props:string/1')

118 The Tcl/Tk Class Interface
******************************

*Author(s):* Montserrat Urraca, Montserrat Iglesias Urraca,
`http://www.clip.dia.fi.upm.es/', The CLIP Group, Facultad de
Informa'tica, Universidad Polite'cnica de Madrid.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#152 (2003/12/4, 17:35:17 CET)

   This library implements an object-orented graphical library with a
number of predefined objects, using the Prolog Tcl/Tk interface. This
interface allows creating and destroying objects and modifying their
properties. The `window_class' contains three clases: widget class,
menu class, and canvas class. The constructor class is window_class.

   *Note:* This library (and the documentation) are still under
development.

118.1 Usage and interface (`window_class')
==========================================

   * *Library usage:*

     `:- use_module(library(window_class)).'

   * *Exports:*
        - _Predicates:_

          `window_class/0', `window_class/3', `destructor/0', `show/0', `hide_/0', `title/1', `maxsize/2', `minsize/2', `withdraw/0', `event_loop/0'.

        - _Regular Types:_

          `widget/1', `option/1', `menu/1', `canvas/1'.

   * *Other modules used:*
        - _System library modules:_

          `objects/objects_rt', `system', `strings', `lists', `tcltk/tcltk', `tcltk/tcltk_low_level', `aggregates'.

118.2 Documentation on exports (`window_class')
===============================================

 -- REGTYPE: widget/1:
     Each `Widget' type is characterized in two ways: first, the form
     of the create command used to create instances of the type; and
     second, a set of configuration options for items of that type,
     which may be used in the create and itemconfigure widget
     commands.

     *Usage:* `widget(W)'
        - _Description:_ `W' is a reference to one type of the widget
          widgets.

 -- REGTYPE: option/1:
     *Usage:* `option(O)'
        - _Description:_ `O' is _hidden_ if the Widget is not visible
          or _shown_ if its visible.

 -- REGTYPE: menu/1:
     *Usage:* `menu(M)'
        - _Description:_ `M' is a reference to one type of the menu.

 -- REGTYPE: canvas/1:
     *Usage:* `canvas(C)'
        - _Description:_ `C' is a reference to one type of the canvas.

 -- PREDICATE: window_class/0:
     *Usage:*
        - _Description:_ Creates a new interpreter, asserting the
          predicate _interp(I)_, and the widgets, menus and canvases
          objects.

 -- PREDICATE: window_class/3:
     *Usage:* `window_class(+WidgetList, +MenusList, +CanvasList)'
        - _Description:_ Adds the widgets, menus and canvases in the
          list to the window object.

        - _Call and exit should be _compatible_ with:_

          `+WidgetList' is a list.   (`basic_props:list/1')

          `+MenusList' is a list.   (`basic_props:list/1')

          `+CanvasList' is a list.   (`basic_props:list/1')

 -- PREDICATE: destructor/0:
     *Usage:*
        - _Description:_ Deletes the widgets, menus and canvases of
          the window object and the window object.

 -- PREDICATE: show/0:
     *Usage:*
        - _Description:_ Adds widgets, menus and canvas to the window
          object.

 -- PREDICATE: hide_/0:
     *Usage:*
        - _Description:_ Removes widgets, menus and canvas from the
          window object.

 -- PREDICATE: title/1:
     *Usage:* `title(+X)'
        - _Description:_ `X' specifies the title for window. The
          default window title is the name of the window.

        - _Call and exit should be _compatible_ with:_

          `+X' is a string (a list of character codes).
          (`basic_props:string/1')

 -- PREDICATE: maxsize/2:
     *Usage:* `maxsize(+X, +Y)'
        - _Description:_ `X' specifies the maximum width and `Y' the
          maximum height for the window.

        - _Call and exit should be _compatible_ with:_

          `+X' is an integer.   (`basic_props:int/1')

          `+Y' is an integer.   (`basic_props:int/1')

 -- PREDICATE: minsize/2:
     *Usage:* `minsize(+X, +Y)'
        - _Description:_ `X' specifies the minimum width and `Y' the
          minimum height for the window.

        - _Call and exit should be _compatible_ with:_

          `+X' is an integer.   (`basic_props:int/1')

          `+Y' is an integer.   (`basic_props:int/1')

 -- PREDICATE: withdraw/0:
     *Usage:*
        - _Description:_ Arranges for window to be withdrawn from the
          screen.

 -- PREDICATE: event_loop/0:
     *Usage:*
        - _Description:_ Waits for a _Tcl/Tk_ event.

119 widget_class (library)
**************************

*Author(s):* Montserrat Urraca.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#150 (2003/12/4, 17:35:4 CET)

119.1 Usage and interface (`widget_class')
==========================================

   * *Library usage:*

     `:- use_module(library(widget_class)).'

   * *Exports:*
        - _Predicates:_

          `text_characters/1', `font_type/1', `background_color/1', `borderwidth_value/1', `foreground_color/1', `highlightbackground_color/1', `highlight_color/1', `width_value/1', `relief_type/1', `side_type/1', `expand_value/1', `fill_type/1', `padx_value/1', `pady_value/1', `row_value/1', `rowspan_value/1', `column_value/1', `columnspan_value/1', `event_type_widget/1', `action_widget/3', `action_widget/1', `creation_options/1', `creation_position/1', `creation_position_grid/1', `creation_bind/1'.

   * *Other modules used:*
        - _System library modules:_

          `objects/objects_rt'.

119.2 Documentation on exports (`widget_class')
===============================================

 -- PREDICATE: text_characters/1:
     *Usage 1:* `text_characters(+Text)'
        - _Description:_ Indicates the `Text' to be displayed in the
          widget.

        - _Call and exit should be _compatible_ with:_

          `+Text' is currently instantiated to an atom.
          (`term_typing:atom/1')

     *Usage 2:* `text_characters(-Text)'
        - _Description:_ `Text' which is displayed in the widget.

        - _Call and exit should be _compatible_ with:_

          `-Text' is currently instantiated to an atom.
          (`term_typing:atom/1')

 -- PREDICATE: font_type/1:
     *Usage 1:* `font_type(+Font)'
        - _Description:_ Indicates the `Font' of the widget's text.

        - _Call and exit should be _compatible_ with:_

          `+Font' is currently instantiated to an atom.
          (`term_typing:atom/1')

     *Usage 2:* `font_type(-Font)'
        - _Description:_ Gets the `Font' of the widget's text.

        - _Call and exit should be _compatible_ with:_

          `-Font' is currently instantiated to an atom.
          (`term_typing:atom/1')

 -- PREDICATE: background_color/1:
     *Usage 1:* `background_color(+Background)'
        - _Description:_ Indicates the `Background' color. Default to
          gray.

        - _Call and exit should be _compatible_ with:_

          `+Background' is currently instantiated to an atom.
          (`term_typing:atom/1')

     *Usage 2:* `background_color(-Background)'
        - _Description:_ Returns the `Background' color.

        - _Call and exit should be _compatible_ with:_

          `-Background' is currently instantiated to an atom.
          (`term_typing:atom/1')

 -- PREDICATE: borderwidth_value/1:
     *Usage 1:* `borderwidth_value(+BorderWidth)'
        - _Description:_ Indicates the width's border. Default to 2.

        - _Call and exit should be _compatible_ with:_

          `+BorderWidth' is a number.   (`basic_props:num/1')

     *Usage 2:* `borderwidth_value(-BorderWidth)'
        - _Description:_ Gets the width's border.

        - _Call and exit should be _compatible_ with:_

          `-BorderWidth' is currently instantiated to an atom.
          (`term_typing:atom/1')

 -- PREDICATE: foreground_color/1:
     *Usage 1:* `foreground_color(+Foreground)'
        - _Description:_ Indicates the `Foreground' color. Default to
          black

        - _Call and exit should be _compatible_ with:_

          `+Foreground' is currently instantiated to an atom.
          (`term_typing:atom/1')

     *Usage 2:* `foreground_color(-Foreground)'
        - _Description:_ Gets the `Foreground' color.

        - _Call and exit should be _compatible_ with:_

          `-Foreground' is currently instantiated to an atom.
          (`term_typing:atom/1')

 -- PREDICATE: highlightbackground_color/1:
     *Usage 1:* `highlightbackground_color(+Color)'
        - _Description:_ `Color' specifies the highlight background
          color. Default to white

        - _Call and exit should be _compatible_ with:_

          `+Color' is currently instantiated to an atom.
          (`term_typing:atom/1')

     *Usage 2:* `highlightbackground_color(-Color)'
        - _Description:_ Gets the `Color' of the highlight background.

        - _Call and exit should be _compatible_ with:_

          `-Color' is currently instantiated to an atom.
          (`term_typing:atom/1')

 -- PREDICATE: highlight_color/1:
     *Usage 1:* `highlight_color(+Color)'
        - _Description:_ `Color' specifies the highlight color.
          Default to white

        - _Call and exit should be _compatible_ with:_

          `+Color' is currently instantiated to an atom.
          (`term_typing:atom/1')

     *Usage 2:* `highlight_color(-Color)'
        - _Description:_ Gets the `Color' of the highlight.

        - _Call and exit should be _compatible_ with:_

          `-Color' is currently instantiated to an atom.
          (`term_typing:atom/1')

 -- PREDICATE: width_value/1:
     *Usage 1:* `width_value(+Width)'
        - _Description:_ Specifies the `Width' for the widget.
          Default to 0

        - _Call and exit should be _compatible_ with:_

          `+Width' is an integer.   (`basic_props:int/1')

     *Usage 2:* `width_value(+Width)'
        - _Description:_ Gets the `Width' specified for the widget.

        - _Call and exit should be _compatible_ with:_

          `+Width' is an integer.   (`basic_props:int/1')

 -- PREDICATE: relief_type/1:
     *Usage 1:* `relief_type(+Relief)'
        - _Description:_ Specifies a desired `Relief' for the widget.
          Default to sunken

        - _Call and exit should be _compatible_ with:_

          `+Relief' is currently instantiated to an atom.
          (`term_typing:atom/1')

     *Usage 2:* `relief_type(-Relief)'
        - _Description:_ Gets the `Relief' of the widget.

        - _Call and exit should be _compatible_ with:_

          `-Relief' is currently instantiated to an atom.
          (`term_typing:atom/1')

 -- PREDICATE: side_type/1:
     *Usage 1:* `side_type(+Side)'
        - _Description:_ Specifies which `Side' of the master, the
          slave(s) will be packed against. Must be left, right, top
          or bottom. Defaults to top

        - _Call and exit should be _compatible_ with:_

          `+Side' is currently instantiated to an atom.
          (`term_typing:atom/1')

     *Usage 2:* `side_type(-Side)'
        - _Description:_ Gets the position of the canvas.

        - _Call and exit should be _compatible_ with:_

          `-Side' is currently instantiated to an atom.
          (`term_typing:atom/1')

 -- PREDICATE: expand_value/1:
     *Usage 1:* `expand_value(+Value)'
        - _Description:_ Specifies whether the slaves should be
          expanded to consume extra space in their master. `Value'
          may have any proper boolean value, such as 1 or 0. Defaults
          to 0

        - _Call and exit should be _compatible_ with:_

          `+Value' is an integer.   (`basic_props:int/1')

     *Usage 2:* `expand_value(-Value)'
        - _Description:_ Gets the boolean value which indicates if
          the slaves should be expanded or no.

        - _Call and exit should be _compatible_ with:_

          `-Value' is an integer.   (`basic_props:int/1')

 -- PREDICATE: fill_type/1:
     *Usage 1:* `fill_type(+Option)'
        - _Description:_ If a slave's parcel is larger than its
          requested dimensions, this option may be used to stretch
          the slave. `Option' must have one of the following values:
          none ( this is the default), x, y, both

        - _Call and exit should be _compatible_ with:_

          `+Option' is currently instantiated to an atom.
          (`term_typing:atom/1')

     *Usage 2:* `fill_type(-Option)'
        - _Description:_ Gets the fill value of the canvas

        - _Call and exit should be _compatible_ with:_

          `-Option' is currently instantiated to an atom.
          (`term_typing:atom/1')

 -- PREDICATE: padx_value/1:
     *Usage 1:* `padx_value(+Amount)'
        - _Description:_ `Amount' specifies how much horizontal
          external padding to leave on each side of the slave(s).
          Amount defaults to 0

        - _Call and exit should be _compatible_ with:_

          `+Amount' is an integer.   (`basic_props:int/1')

     *Usage 2:* `padx_value(-Amount)'
        - _Description:_ Gets the `Amount' which specifies how much
          horizontal external padding to leave on each side of the
          slaves.

        - _Call and exit should be _compatible_ with:_

          `-Amount' is an integer.   (`basic_props:int/1')

 -- PREDICATE: pady_value/1:
     *Usage 1:* `pady_value(+Amount)'
        - _Description:_ `Amount' specifies how much vertical
          external padding to leave on each side of the slave(s).
          Amount defaults to 0

        - _Call and exit should be _compatible_ with:_

          `+Amount' is an integer.   (`basic_props:int/1')

     *Usage 2:* `pady_value(-Amount)'
        - _Description:_ Gets the `Amount' which specifies how much
          vertical external padding to leave on each side of the
          slaves.

        - _Call and exit should be _compatible_ with:_

          `-Amount' is an integer.   (`basic_props:int/1')

 -- PREDICATE: row_value/1:
     *Usage 1:* `row_value(+Row)'
        - _Description:_ Indicates the `Row' in which the widget
          should be allocated.

        - _Call and exit should be _compatible_ with:_

          `+Row' is an integer.   (`basic_props:int/1')

     *Usage 2:* `row_value(-Row)'
        - _Description:_ Gets the `Row' in which the widget is
          allocated.

        - _Call and exit should be _compatible_ with:_

          `-Row' is an integer.   (`basic_props:int/1')

 -- PREDICATE: rowspan_value/1:
     *Usage 1:* `rowspan_value(+Row)'
        - _Description:_ Indicates the number of `Row' which are
          going to be occupied in the grid.

        - _Call and exit should be _compatible_ with:_

          `+Row' is an integer.   (`basic_props:int/1')

     *Usage 2:* `rowspan_value(-Row)'
        - _Description:_ Gets the number of `Row' which are occupied
          by the widget in the grid.

        - _Call and exit should be _compatible_ with:_

          `-Row' is an integer.   (`basic_props:int/1')

 -- PREDICATE: column_value/1:
     *Usage 1:* `column_value(+Column)'
        - _Description:_ Indicates the `Column' in which the widget
          should be allocated.

        - _Call and exit should be _compatible_ with:_

          `+Column' is an integer.   (`basic_props:int/1')

     *Usage 2:* `column_value(-Column)'
        - _Description:_ Gets the `Column' in which the widget is
          allocated.

        - _Call and exit should be _compatible_ with:_

          `-Column' is an integer.   (`basic_props:int/1')

 -- PREDICATE: columnspan_value/1:
     *Usage 1:* `columnspan_value(+Column)'
        - _Description:_ Indicates the number of `Column' which are
          going to be occupied in the grid.

        - _Call and exit should be _compatible_ with:_

          `+Column' is an integer.   (`basic_props:int/1')

     *Usage 2:* `columnspan_value(-Column)'
        - _Description:_ Gets the number of `Column' which are
          occupied by the widget in the grid.

        - _Call and exit should be _compatible_ with:_

          `-Column' is an integer.   (`basic_props:int/1')

 -- PREDICATE: event_type_widget/1:
     *Usage 1:* `event_type_widget(+EventType)'
        - _Description:_ The event `EventType' is going to be manage
          by the interface.

        - _Call and exit should be _compatible_ with:_

          `+EventType' is currently instantiated to an atom.
          (`term_typing:atom/1')

     *Usage 2:* `event_type_widget(-EventType)'
        - _Description:_ Gets the event `EventType' which is going to
          be manage by the interface.

        - _Call and exit should be _compatible_ with:_

          `-EventType' is currently instantiated to an atom.
          (`term_typing:atom/1')

 -- PREDICATE: action_widget/3:
     *Usage 1:* `action_widget(+Input, +Output, +Term)'
        - _Description:_ Executes `Term' with `Input' value and
          `Output' variable.

        - _Call and exit should be _compatible_ with:_

          `+Input' is currently instantiated to an atom.
          (`term_typing:atom/1')

          `+Output' is currently instantiated to an atom.
          (`term_typing:atom/1')

          `+Term' is currently instantiated to an atom.
          (`term_typing:atom/1')

     *Usage 2:* `action_widget(+Input, +Output, -Term)'
        - _Description:_ `Term' is associated to the action of the
          object indicated with the operacion _event_type_widget_.

        - _Call and exit should be _compatible_ with:_

          `+Input' is currently instantiated to an atom.
          (`term_typing:atom/1')

          `+Output' is currently instantiated to an atom.
          (`term_typing:atom/1')

          `-Term' is currently instantiated to an atom.
          (`term_typing:atom/1')

 -- PREDICATE: action_widget/1:
     *Usage 1:* `action_widget(+Term)'
        - _Description:_ `Term' is going to be associated to the
          action of the object indicated with the operacion
          _event_type_widget_.

        - _Call and exit should be _compatible_ with:_

          `+Term' is currently instantiated to an atom.
          (`term_typing:atom/1')

     *Usage 2:* `action_widget(-Term)'
        - _Description:_ `Term' is associated to the action of the
          object indicated with the operacion _event_type_widget_.

        - _Call and exit should be _compatible_ with:_

          `-Term' is currently instantiated to an atom.
          (`term_typing:atom/1')

 -- PREDICATE: creation_options/1:
     *Usage:* `creation_options(-OptionsList)'
        - _Description:_ Creates a list with the options supported by
          the widget.

        - _Call and exit should be _compatible_ with:_

          `-OptionsList' is a list.   (`basic_props:list/1')

 -- PREDICATE: creation_position/1:
     *Usage:* `creation_position(-OptionsList)'
        - _Description:_ Creates a list with the options supported by
          the pack command.

        - _Call and exit should be _compatible_ with:_

          `-OptionsList' is a list.   (`basic_props:list/1')

 -- PREDICATE: creation_position_grid/1:
     *Usage:* `creation_position_grid(-OptionsList)'
        - _Description:_ Creates a list with the options supported by
          the grid command.

        - _Call and exit should be _compatible_ with:_

          `-OptionsList' is a list.   (`basic_props:list/1')

 -- PREDICATE: creation_bind/1:
     *Usage:* `creation_bind(-BindList)'
        - _Description:_ Creates a list with the event to be manage
          and the action associated to this event.

        - _Call and exit should be _compatible_ with:_

          `-BindList' is a list.   (`basic_props:list/1')

120 menu_class (library)
************************

*Author(s):* Montserrat Urraca.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#133 (2003/12/4, 17:33:46 CET)

120.1 Usage and interface (`menu_class')
========================================

   * *Library usage:*

     `:- use_module(library(menu_class)).'

   * *Exports:*
        - _Predicates:_

          `name_menu/1', `menu_data/1', `label_value/1', `tearoff_value/1', `tcl_name/1', `creation_options/1', `creation_options_entry/1', `creation_menu_name/1'.

   * *Other modules used:*
        - _System library modules:_

          `objects/objects_rt', `tcltk_obj/window_class', `tcltk_obj/menu_entry_class', `tcltk/tcltk', `tcltk/tcltk_low_level', `lists'.

120.2 Documentation on exports (`menu_class')
=============================================

 -- PREDICATE: name_menu/1:
     *Usage:* `name_menu(+Name)'
        - _Description:_ Indicates the `Name' of the menubutton
          associated.

        - _Call and exit should be _compatible_ with:_

          `+Name' is currently instantiated to an atom.
          (`term_typing:atom/1')

 -- PREDICATE: menu_data/1:
     *Usage 1:* `menu_data(+Menu)'
        - _Description:_ `Menu' posted when cascade entry is invoked.

        - _Call and exit should be _compatible_ with:_

          `+Menu' is currently instantiated to an atom.
          (`term_typing:atom/1')

     *Usage 2:* `menu_data(-Menu)'
        - _Description:_ Gets the `Menu' asociated to the cascade
          entry.

        - _Call and exit should be _compatible_ with:_

          `-Menu' is currently instantiated to an atom.
          (`term_typing:atom/1')

 -- PREDICATE: label_value/1:
     *Usage 1:* `label_value(+Value)'
        - _Description:_ `Value' specifies a string to be displayed
          as an identifying label in the menu entry.

        - _Call and exit should be _compatible_ with:_

          `+Value' is currently instantiated to an atom.
          (`term_typing:atom/1')

     *Usage 2:* `label_value(-Value)'
        - _Description:_ Gets the string which identify the menu
          entry.

        - _Call and exit should be _compatible_ with:_

          `-Value' is currently instantiated to an atom.
          (`term_typing:atom/1')

 -- PREDICATE: tearoff_value/1:
     *Usage 1:* `tearoff_value(+Tearoff)'
        - _Description:_ `Tearoff' must have a proper boolean value,
          which specifies wheter or not the menu should include a
          tear-off entry at the top. Defaults to 1.

        - _Call and exit should be _compatible_ with:_

          `+Tearoff' is currently instantiated to an atom.
          (`term_typing:atom/1')

     *Usage 2:* `tearoff_value(-Tearoff)'
        - _Description:_ Gets the `Tearoff' value

        - _Call and exit should be _compatible_ with:_

          `-Tearoff' is currently instantiated to an atom.
          (`term_typing:atom/1')

 -- PREDICATE: tcl_name/1:
     *Usage:* `tcl_name(-Widget)'
        - _Description:_ Specifies the name of the `Widget'. In this
          case is menu.

        - _Call and exit should be _compatible_ with:_

          `-Widget' is currently instantiated to an atom.
          (`term_typing:atom/1')

 -- PREDICATE: creation_options/1:
     *Usage:* `creation_options(-OptionsList)'
        - _Description:_ Creates a list with the options supported by
          the menu.

        - _Call and exit should be _compatible_ with:_

          `-OptionsList' is a list.   (`basic_props:list/1')

 -- PREDICATE: creation_options_entry/1:
     *Usage:* `creation_options_entry(-OptionsList)'
        - _Description:_ Creates a list with the options of the menu
          entry.

        - _Call and exit should be _compatible_ with:_

          `-OptionsList' is a list.   (`basic_props:list/1')

 -- PREDICATE: creation_menu_name/1:
     *Usage:* `creation_menu_name(-OptionsList)'
        - _Description:_ Creates a list with the name of the menu.

        - _Call and exit should be _compatible_ with:_

          `-OptionsList' is a list.   (`basic_props:list/1')

121 canvas_class (library)
**************************

*Author(s):* Montserrat Urraca.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#123 (2003/12/4, 17:32:57 CET)

121.1 Usage and interface (`canvas_class')
==========================================

   * *Library usage:*

     `:- use_module(library(canvas_class)).'

   * *Other modules used:*
        - _System library modules:_

          `class/class_rt', `class/virtual', `objects/objects_rt', `tcltk_obj/window_class', `tcltk_obj/shape_class', `system', `strings', `lists', `tcltk/tcltk', `tcltk/tcltk_low_level'.

121.2 Documentation on multifiles (`canvas_class')
==================================================

 -- PREDICATE: $class$/1:
     No further documentation available for this predicate.

     The predicate is _multifile_.

 -- PREDICATE: class$super/2:
     No further documentation available for this predicate.

     The predicate is _multifile_.

 -- PREDICATE: class$initial_state/3:
     No further documentation available for this predicate.

     The predicate is _multifile_.

 -- PREDICATE: class$virtual/6:
     No further documentation available for this predicate.

     The predicate is _multifile_.

 -- PREDICATE: class$attr_template/4:
     No further documentation available for this predicate.

     The predicate is _multifile_.

 -- PREDICATE: class$default_cons/1:
     No further documentation available for this predicate.

     The predicate is _multifile_.

 -- PREDICATE: class$constructor/4:
     No further documentation available for this predicate.

     The predicate is _multifile_.

 -- PREDICATE: class$destructor/3:
     No further documentation available for this predicate.

     The predicate is _multifile_.

 -- PREDICATE: class$implements/2:
     No further documentation available for this predicate.

     The predicate is _multifile_.

122 button_class (library)
**************************

*Author(s):* Montserrat Urraca.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#122 (2003/12/4, 17:32:36 CET)

122.1 Usage and interface (`button_class')
==========================================

   * *Library usage:*

     `:- use_module(library(button_class)).'

   * *Exports:*
        - _Predicates:_

          `command_button/1'.

   * *Other modules used:*
        - _System library modules:_

          `objects/objects_rt'.

122.2 Documentation on exports (`button_class')
===============================================

 -- PREDICATE: command_button/1:
     *Usage 1:* `command_button(+Command)'
        - _Description:_ Sets a Tcl `Command' to be associated with
          the button. This `Command' is typically invoked when mouse
          button 1 is released over the button window.

        - _Call and exit should be _compatible_ with:_

          `+Command' is currently instantiated to an atom.
          (`term_typing:atom/1')

     *Usage 2:* `command_button(-Command)'
        - _Description:_ Gets the Tcl `Command' associated with the
          button.

        - _Call and exit should be _compatible_ with:_

          `-Command' is currently instantiated to an atom.
          (`term_typing:atom/1')

123 checkbutton_class (library)
*******************************

*Author(s):* Montserrat Urraca.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#125 (2003/12/4, 17:33:7 CET)

123.1 Usage and interface (`checkbutton_class')
===============================================

   * *Library usage:*

     `:- use_module(library(checkbutton_class)).'

   * *Exports:*
        - _Predicates:_

          `variable_value/1'.

   * *Other modules used:*
        - _System library modules:_

          `objects/objects_rt'.

123.2 Documentation on exports (`checkbutton_class')
====================================================

 -- PREDICATE: variable_value/1:
     *Usage 1:* `variable_value(+Variable)'
        - _Description:_ Sets the value of global `Variable' to
          indicate whether or not this button is selected.

        - _Call and exit should be _compatible_ with:_

          `+Variable' is currently instantiated to an atom.
          (`term_typing:atom/1')

     *Usage 2:* `variable_value(-Variable)'
        - _Description:_ Gets the value of global `Variable' which
          indicates if the button is selected.

        - _Call and exit should be _compatible_ with:_

          `-Variable' is currently instantiated to an atom.
          (`term_typing:atom/1')

124 radiobutton_class (library)
*******************************

*Author(s):* Montserrat Urraca.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#143 (2003/12/4, 17:34:38 CET)

124.1 Usage and interface (`radiobutton_class')
===============================================

   * *Library usage:*

     `:- use_module(library(radiobutton_class)).'

   * *Exports:*
        - _Predicates:_

          `variable_value/1'.

   * *Other modules used:*
        - _System library modules:_

          `objects/objects_rt'.

124.2 Documentation on exports (`radiobutton_class')
====================================================

 -- PREDICATE: variable_value/1:
     *Usage 1:* `variable_value(+Variable)'
        - _Description:_ Specifies the value of global `Variable' to
          set whenever this button is selected.

        - _Call and exit should be _compatible_ with:_

          `+Variable' is currently instantiated to an atom.
          (`term_typing:atom/1')

     *Usage 2:* `variable_value(-Variable)'
        - _Description:_ Gets the value of global `Variable' which
          indicates if this button is selected.

        - _Call and exit should be _compatible_ with:_

          `-Variable' is currently instantiated to an atom.
          (`term_typing:atom/1')

125 entry_class (library)
*************************

*Author(s):* Montserrat Urraca.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#127 (2003/12/4, 17:33:22 CET)

125.1 Usage and interface (`entry_class')
=========================================

   * *Library usage:*

     `:- use_module(library(entry_class)).'

   * *Exports:*
        - _Predicates:_

          `textvariable_entry/1', `textvariablevalue_string/1', `textvariablevalue_number/1', `justify_entry/1'.

   * *Other modules used:*
        - _System library modules:_

          `objects/objects_rt', `lists', `tcltk/examples/tk_test_aux', `tcltk/tcltk'.

125.2 Documentation on exports (`entry_class')
==============================================

 -- PREDICATE: textvariable_entry/1:
     *Usage 1:* `textvariable_entry(+Variable)'
        - _Description:_ `Variable' specifies the name of the Tcl
          variable

        - _Call and exit should be _compatible_ with:_

          `+Variable' is currently instantiated to an atom.
          (`term_typing:atom/1')

     *Usage 2:* `textvariable_entry(-Variable)'
        - _Description:_ Gets the name of the Tcl `Variable'
          associated to the entry

        - _Call and exit should be _compatible_ with:_

          `-Variable' is currently instantiated to an atom.
          (`term_typing:atom/1')

 -- PREDICATE: textvariablevalue_string/1:
     *Usage 1:* `textvariablevalue_string(+Value)'
        - _Description:_ Specifies the `Value' of the Tcl variable
          associated to the entry.

        - _Call and exit should be _compatible_ with:_

          `+Value' is a number.   (`basic_props:num/1')

     *Usage 2:* `textvariablevalue_string(-Value)'
        - _Description:_ `Value' is the value of the Tcl variable
          associated to the entry.

        - _Call and exit should be _compatible_ with:_

          `-Value' is a number.   (`basic_props:num/1')

 -- PREDICATE: textvariablevalue_number/1:
     *Usage 1:* `textvariablevalue_number(+Value)'
        - _Description:_ Specifies the `Value' of the Tcl variable
          associated to the entry.

        - _Call and exit should be _compatible_ with:_

          `+Value' is a number.   (`basic_props:num/1')

     *Usage 2:* `textvariablevalue_number(-Value)'
        - _Description:_ `Value' is the value of the Tcl variable
          associated to the entry.

        - _Call and exit should be _compatible_ with:_

          `-Value' is a number.   (`basic_props:num/1')

 -- PREDICATE: justify_entry/1:
     *Usage 1:* `justify_entry(+How)'
        - _Description:_ `How' specifies how to justify the text in
          the entry. `How' must be one of the values left, right or
          center. This option defaluts to left.

        - _Call and exit should be _compatible_ with:_

          `+How' is currently instantiated to an atom.
          (`term_typing:atom/1')

     *Usage 2:* `justify_entry(-How)'
        - _Description:_ Gets `How' is justified the text.

        - _Call and exit should be _compatible_ with:_

          `-How' is currently instantiated to an atom.
          (`term_typing:atom/1')

126 label_class (library)
*************************

*Author(s):* Montserrat Urraca.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#129 (2003/12/4, 17:33:30 CET)

126.1 Usage and interface (`label_class')
=========================================

   * *Library usage:*

     `:- use_module(library(label_class)).'

   * *Exports:*
        - _Predicates:_

          `textvariable_label/1'.

   * *Other modules used:*
        - _System library modules:_

          `objects/objects_rt'.

126.2 Documentation on exports (`label_class')
==============================================

 -- PREDICATE: textvariable_label/1:
     No further documentation available for this predicate.

127 menubutton_class (library)
******************************

*Author(s):* Montserrat Urraca.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#137 (2003/12/4, 17:34:7 CET)

127.1 Usage and interface (`menubutton_class')
==============================================

   * *Library usage:*

     `:- use_module(library(menubutton_class)).'

   * *Exports:*
        - _Predicates:_

          `menu_name/1'.

   * *Other modules used:*
        - _System library modules:_

          `objects/objects_rt', `lists'.

127.2 Documentation on exports (`menubutton_class')
===================================================

 -- PREDICATE: menu_name/1:
     *Usage 1:* `menu_name(+Menu)'
        - _Description:_ `Menu' posted when menubutton is clicked.

        - _Call and exit should be _compatible_ with:_

          `+Menu' is currently instantiated to an atom.
          (`term_typing:atom/1')

     *Usage 2:* `menu_name(-Menu)'
        - _Description:_ Gets the name of the `Menu' asociated to the
          menubutton.

        - _Call and exit should be _compatible_ with:_

          `-Menu' is currently instantiated to an atom.
          (`term_typing:atom/1')

128 menu_entry_class (library)
******************************

*Author(s):* Montserrat Urraca.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#135 (2003/12/4, 17:33:57 CET)

128.1 Usage and interface (`menu_entry_class')
==============================================

   * *Library usage:*

     `:- use_module(library(menu_entry_class)).'

   * *Exports:*
        - _Predicates:_

          `set_name/1', `set_action/1', `label_value/1', `menu_name/1'.

   * *Other modules used:*
        - _System library modules:_

          `objects/objects_rt', `tcltk_obj/menu_class', `lists'.

128.2 Documentation on exports (`menu_entry_class')
===================================================

 -- PREDICATE: set_name/1:
     *Usage:* `set_name(+Name)'
        - _Description:_ `Name' of the menubutton associated.

        - _Call and exit should be _compatible_ with:_

          `+Name' is currently instantiated to an atom.
          (`term_typing:atom/1')

 -- PREDICATE: set_action/1:
     *Usage:* `set_action(+Predicate)'
        - _Description:_ Specifies `Predicate' asociated to the menu
          entry.

        - _Call and exit should be _compatible_ with:_

          `+Predicate' is currently instantiated to an atom.
          (`term_typing:atom/1')

 -- PREDICATE: label_value/1:
     *Usage 1:* `label_value(+Value)'
        - _Description:_ `Value' specifies a value to be displayed as
          an identifying label in the menu entry.

        - _Call and exit should be _compatible_ with:_

          `+Value' is currently instantiated to an atom.
          (`term_typing:atom/1')

     *Usage 2:* `label_value(-Value)'
        - _Description:_ Gets the string which identify label in the
          menu entry.

        - _Call and exit should be _compatible_ with:_

          `-Value' is currently instantiated to an atom.
          (`term_typing:atom/1')

 -- PREDICATE: menu_name/1:
     *Usage 1:* `menu_name(+Menu)'
        - _Description:_ `Menu' posted when cascade entry is invoked.

        - _Call and exit should be _compatible_ with:_

          `+Menu' is currently instantiated to an atom.
          (`term_typing:atom/1')

     *Usage 2:* `menu_name(-Menu)'
        - _Description:_ Gets the `Menu' asociated to the cascade
          entry.

        - _Call and exit should be _compatible_ with:_

          `-Menu' is currently instantiated to an atom.
          (`term_typing:atom/1')

129 shape_class (library)
*************************

*Author(s):* Montserrat Urraca.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#146 (2003/12/4, 17:34:49 CET)

129.1 Usage and interface (`shape_class')
=========================================

   * *Library usage:*

     `:- use_module(library(shape_class)).'

   * *Exports:*
        - _Predicates:_

          `bg_color/1', `border_width/1', `shape_class/0', `shape_class/1'.

   * *Other modules used:*
        - _System library modules:_

          `objects/objects_rt', `tcltk_obj/canvas_class'.

129.2 Documentation on exports (`shape_class')
==============================================

 -- PREDICATE: bg_color/1:
     *Usage 1:* `bg_color(+BackgroundColor)'
        - _Description:_ `Background Color' specifies the color to
          use for drawing the shape's outline. This option defaults
          to black.

        - _Call and exit should be _compatible_ with:_

          `+BackgroundColor' is currently instantiated to an atom.
          (`term_typing:atom/1')

     *Usage 2:* `bg_color(-BackgroundColor)'
        - _Description:_ Gets the shape `Background Color'.

        - _Call and exit should be _compatible_ with:_

          `-BackgroundColor' is currently instantiated to an atom.
          (`term_typing:atom/1')

 -- PREDICATE: border_width/1:
     *Usage 1:* `border_width(+Width)'
        - _Description:_ Specifies the `Width' that the canvas widget
          should request from its geometry manager.

        - _Call and exit should be _compatible_ with:_

          `+Width' is a number.   (`basic_props:num/1')

     *Usage 2:* `border_width(-Width)'
        - _Description:_ Gets the `Width' of the canvas widget.

        - _Call and exit should be _compatible_ with:_

          `-Width' is a number.   (`basic_props:num/1')

 -- PREDICATE: shape_class/0:
     *Usage:*
        - _Description:_  Creates a new shape object.

 -- PREDICATE: shape_class/1:
     *Usage:* `shape_class(+ShapeList)'
        - _Description:_ Adds shapes of the list to the canvas object.

        - _Call and exit should be _compatible_ with:_

          `+ShapeList' is a list.   (`basic_props:list/1')

130 arc_class (library)
***********************

*Author(s):* Montserrat Urraca.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#120 (2003/12/4, 17:32:15 CET)

130.1 Usage and interface (`arc_class')
=======================================

   * *Library usage:*

     `:- use_module(library(arc_class)).'

   * *Exports:*
        - _Predicates:_

          `coord/4', `width/1', `height/1', `center/2', `angle_start/1', `style_type/1', `outline_color/1'.

   * *Other modules used:*
        - _System library modules:_

          `objects/objects_rt'.

130.2 Documentation on exports (`arc_class')
============================================

 -- PREDICATE: coord/4:
     *Usage:* `coord(+X1, +Y1, +X2, +Y2)'
        - _Description:_ `X1', `Y1', `X2', and `Y2' give the
          coordinates of two diagonally opposite corners of a
          rectangular region enclosing the oval that defines the arc.

        - _Call and exit should be _compatible_ with:_

          `+X1' is an integer.   (`basic_props:int/1')

          `+Y1' is an integer.   (`basic_props:int/1')

          `+X2' is an integer.   (`basic_props:int/1')

          `+Y2' is an integer.   (`basic_props:int/1')

 -- PREDICATE: width/1:
     *Usage 1:* `width(+Width)'
        - _Description:_ Specifies shape's `Width'.

        - _Call and exit should be _compatible_ with:_

          `+Width' is an integer.   (`basic_props:int/1')

     *Usage 2:* `width(-Width)'
        - _Description:_ Gets shape's `Width'.

        - _Call and exit should be _compatible_ with:_

          `-Width' is an integer.   (`basic_props:int/1')

 -- PREDICATE: height/1:
     *Usage 1:* `height(+Height)'
        - _Description:_ Specifies shape's `Height'.

        - _Call and exit should be _compatible_ with:_

          `+Height' is an integer.   (`basic_props:int/1')

     *Usage 2:* `height(-Height)'
        - _Description:_ Gets shape's `Height'.

        - _Call and exit should be _compatible_ with:_

          `-Height' is an integer.   (`basic_props:int/1')

 -- PREDICATE: center/2:
     *Usage 1:* `center(+X, +Y)'
        - _Description:_ Specifies shape's center with `X' and `Y'.

        - _Call and exit should be _compatible_ with:_

          `+X' is an integer.   (`basic_props:int/1')

          `+Y' is an integer.   (`basic_props:int/1')

     *Usage 2:* `center(-X, -Y)'
        - _Description:_ Gets shape's center with `X' and `Y'.

        - _Call and exit should be _compatible_ with:_

          `-X' is an integer.   (`basic_props:int/1')

          `-Y' is an integer.   (`basic_props:int/1')

 -- PREDICATE: angle_start/1:
     *Usage 1:* `angle_start(+Angle)'
        - _Description:_ `Angle' specifies the beginning of the
          angular range occupied by the arc. Degrees are given in
          units of degrees measured counter-clockwise from the
          3-o'clock position; it may be either positive or negative.

        - _Call and exit should be _compatible_ with:_

          `+Angle' is an integer.   (`basic_props:int/1')

     *Usage 2:* `angle_start(-Angle)'
        - _Description:_ Gets the value of the `Angle'.

        - _Call and exit should be _compatible_ with:_

          `-Angle' is an integer.   (`basic_props:int/1')

 -- PREDICATE: style_type/1:
     *Usage 1:* `style_type(+Style)'
        - _Description:_ `Style' specifies how to draw the arc. If
          type is pieslice (the default) then the arc's region is
          defined by a section of the oval's perimeter plus two line
          segments, one between the center of the oval and each end
          of the perimeter section. If type is chord then the arc's
          region is defined by a section of the oval's perimeter plus
          a single line segment connecting the two end points of the
          perimeter section. If type is arc then the arc's region
          consists of a section of the perimeter alone. In this last
          case the -fill option is ignored.

        - _Call and exit should be _compatible_ with:_

          `+Style' is currently instantiated to an atom.
          (`term_typing:atom/1')

     *Usage 2:* `style_type(-Style)'
        - _Description:_ Gets the `Style' of the arc.

        - _Call and exit should be _compatible_ with:_

          `-Style' is currently instantiated to an atom.
          (`term_typing:atom/1')

 -- PREDICATE: outline_color/1:
     *Usage 1:* `outline_color(+Color)'
        - _Description:_ `Color' specifies the color used for drawing
          the arc's outline. This option defaults to black.

        - _Call and exit should be _compatible_ with:_

          `+Color' is currently instantiated to an atom.
          (`term_typing:atom/1')

     *Usage 2:* `outline_color(-Color)'
        - _Description:_ It gets arc's outline `Color'.

        - _Call and exit should be _compatible_ with:_

          `-Color' is currently instantiated to an atom.
          (`term_typing:atom/1')

131 oval_class (library)
************************

*Author(s):* Montserrat Urraca.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#139 (2003/12/4, 17:34:21 CET)

131.1 Usage and interface (`oval_class')
========================================

   * *Library usage:*

     `:- use_module(library(oval_class)).'

   * *Exports:*
        - _Predicates:_

          `coord/4', `width/1', `height/1', `center/2', `outline_color/1'.

   * *Other modules used:*
        - _System library modules:_

          `objects/objects_rt'.

131.2 Documentation on exports (`oval_class')
=============================================

 -- PREDICATE: coord/4:
     *Usage:* `coord(+X1, +Y1, +X2, +Y2)'
        - _Description:_ `X1', `Y1', `X2', and `Y2' give the
          coordinates of two diagonally opposite corners of a
          rectangular region enclosing the oval.

        - _Call and exit should be _compatible_ with:_

          `+X1' is an integer.   (`basic_props:int/1')

          `+Y1' is an integer.   (`basic_props:int/1')

          `+X2' is an integer.   (`basic_props:int/1')

          `+Y2' is an integer.   (`basic_props:int/1')

 -- PREDICATE: width/1:
     *Usage 1:* `width(+Width)'
        - _Description:_ Specifies shape's `Width'.

        - _Call and exit should be _compatible_ with:_

          `+Width' is an integer.   (`basic_props:int/1')

     *Usage 2:* `width(-Width)'
        - _Description:_ Gets shape's `Width'.

        - _Call and exit should be _compatible_ with:_

          `-Width' is an integer.   (`basic_props:int/1')

 -- PREDICATE: height/1:
     *Usage 1:* `height(+Height)'
        - _Description:_ Specifies shape's `Heigh'.

        - _Call and exit should be _compatible_ with:_

          `+Height' is an integer.   (`basic_props:int/1')

     *Usage 2:* `height(-Height)'
        - _Description:_ Gets shape's `Height'.

        - _Call and exit should be _compatible_ with:_

          `-Height' is an integer.   (`basic_props:int/1')

 -- PREDICATE: center/2:
     *Usage 1:* `center(+X, +Y)'
        - _Description:_ Specifies shape's center with `X' and `Y'.

        - _Call and exit should be _compatible_ with:_

          `+X' is an integer.   (`basic_props:int/1')

          `+Y' is an integer.   (`basic_props:int/1')

     *Usage 2:* `center(-X, -Y)'
        - _Description:_ Gets shape's center with `X' and `Y'.

        - _Call and exit should be _compatible_ with:_

          `-X' is an integer.   (`basic_props:int/1')

          `-Y' is an integer.   (`basic_props:int/1')

 -- PREDICATE: outline_color/1:
     *Usage 1:* `outline_color(+Color)'
        - _Description:_ `Color' specifies the color to be used for
          drawing the oval's outline. This option defaults to black.

        - _Call and exit should be _compatible_ with:_

          `+Color' is currently instantiated to an atom.
          (`term_typing:atom/1')

     *Usage 2:* `outline_color(-Color)'
        - _Description:_ Gets oval's outline `Color'.

        - _Call and exit should be _compatible_ with:_

          `-Color' is currently instantiated to an atom.
          (`term_typing:atom/1')

132 poly_class (library)
************************

*Author(s):* Montserrat Urraca.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#187 (2003/12/10, 21:19:39 CET)

132.1 Usage and interface (`poly_class')
========================================

   * *Library usage:*

     `:- use_module(library(poly_class)).'

   * *Exports:*
        - _Predicates:_

          `vertices/1', `outline_color/1'.

   * *Other modules used:*
        - _System library modules:_

          `objects/objects_rt', `lists'.

132.2 Documentation on exports (`poly_class')
=============================================

 -- PREDICATE: vertices/1:
     *Usage 1:* `vertices(+ListofPoints)'
        - _Description:_ The arguments of the list specify the
          coordinates for three or more points that define a closed
          polygon. The first and last points may be the same. After
          the coordinates there may be any number of option-value
          pairs, each of which sets one of the configu- ration
          options for the item.

        - _Call and exit should be _compatible_ with:_

          `+ListofPoints' is a list.   (`basic_props:list/1')

     *Usage 2:* `vertices(-ListofPoints)'
        - _Description:_ Gets the list of vertices of the polygon.

        - _Call and exit should be _compatible_ with:_

          `-ListofPoints' is a list.   (`basic_props:list/1')

 -- PREDICATE: outline_color/1:
     *Usage 1:* `outline_color(+Color)'
        - _Description:_ `Color' specifies the color to be used for
          drawing the polygon's outline. This option defaults to
          black.

        - _Call and exit should be _compatible_ with:_

          `+Color' is currently instantiated to an atom.
          (`term_typing:atom/1')

     *Usage 2:* `outline_color(-Color)'
        - _Description:_ Gets poly's outline `Color'.

        - _Call and exit should be _compatible_ with:_

          `-Color' is currently instantiated to an atom.
          (`term_typing:atom/1')

133 line_class (library)
************************

*Author(s):* Montserrat Urraca.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#131 (2003/12/4, 17:33:38 CET)

133.1 Usage and interface (`line_class')
========================================

   * *Library usage:*

     `:- use_module(library(line_class)).'

   * *Exports:*
        - _Predicates:_

          `vertices/1', `arrowheads/1'.

   * *Other modules used:*
        - _System library modules:_

          `objects/objects_rt', `lists'.

133.2 Documentation on exports (`line_class')
=============================================

 -- PREDICATE: vertices/1:
     *Usage 1:* `vertices(+ListofPoints)'
        - _Description:_ The arguments of the list specify the
          coordinates for two or more points that describe a serie of
          connected line segments.

        - _Call and exit should be _compatible_ with:_

          `+ListofPoints' is a list.   (`basic_props:list/1')

     *Usage 2:* `vertices(-ListofPoints)'
        - _Description:_ Gets the list of points of the line.

        - _Call and exit should be _compatible_ with:_

          `-ListofPoints' is a list.   (`basic_props:list/1')

 -- PREDICATE: arrowheads/1:
     *Usage 1:* `arrowheads(+Where)'
        - _Description:_ `Where' indicates whether or not arrowheads
          are to be drawn at one or both ends of the line. `Where'
          must have one of the next values: none ( for no arrowheads
          ), first (for an arrowhead at the first point of the line),
          last (for an arrowhead at the last point of the line), or
          both (for arrowheads at both ends). This option defaults to
          none.

        - _Call and exit should be _compatible_ with:_

          `+Where' is currently instantiated to an atom.
          (`term_typing:atom/1')

     *Usage 2:* `arrowheads(-Where)'
        - _Description:_ Gets position of the arrowheads.

        - _Call and exit should be _compatible_ with:_

          `-Where' is currently instantiated to an atom.
          (`term_typing:atom/1')

134 text_class (library)
************************

*Author(s):* Montserrat Urraca.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#148 (2003/12/4, 17:34:58 CET)

134.1 Usage and interface (`text_class')
========================================

   * *Library usage:*

     `:- use_module(library(text_class)).'

   * *Exports:*
        - _Predicates:_

          `coord/2', `point/2', `text_characters/1', `anchor/1', `font_type/1', `justify_text/1'.

   * *Other modules used:*
        - _System library modules:_

          `objects/objects_rt'.

134.2 Documentation on exports (`text_class')
=============================================

 -- PREDICATE: coord/2:
     *Usage:* `coord(+X, +Y)'
        - _Description:_ `X' and `Y' specify the coordinates of a
          point used to position the text on the display.

        - _Call and exit should be _compatible_ with:_

          `+X' is an integer.   (`basic_props:int/1')

          `+Y' is an integer.   (`basic_props:int/1')

 -- PREDICATE: point/2:
     *Usage:* `point(+X, +Y)'
        - _Description:_ `X' and `Y' change the coordinates of a
          point used to position the text on the display.

        - _Call and exit should be _compatible_ with:_

          `+X' is an integer.   (`basic_props:int/1')

          `+Y' is an integer.   (`basic_props:int/1')

 -- PREDICATE: text_characters/1:
     *Usage 1:* `text_characters(+Text)'
        - _Description:_ `Text' specifies the characters to be
          displayed in the text item. This option defaults to an
          empty string.

        - _Call and exit should be _compatible_ with:_

          `+Text' is currently instantiated to an atom.
          (`term_typing:atom/1')

     *Usage 2:* `text_characters(-Text)'
        - _Description:_ Gets the text displayed in the text item.

        - _Call and exit should be _compatible_ with:_

          `-Text' is currently instantiated to an atom.
          (`term_typing:atom/1')

 -- PREDICATE: anchor/1:
     *Usage 1:* `anchor(+AnchorPos)'
        - _Description:_ `AnchorPos' tells how to position the text
          relative to the positioning point for the text. This option
          defaluts to center.

        - _Call and exit should be _compatible_ with:_

          `+AnchorPos' is currently instantiated to an atom.
          (`term_typing:atom/1')

     *Usage 2:* `anchor(-AnchorPos)'
        - _Description:_ Gets the position of the text relative to
          the positioning point.

        - _Call and exit should be _compatible_ with:_

          `-AnchorPos' is currently instantiated to an atom.
          (`term_typing:atom/1')

 -- PREDICATE: font_type/1:
     *Usage 1:* `font_type(+Font)'
        - _Description:_ `Font' specifies the font to use for the
          text item. This option defaluts to arial.

        - _Call and exit should be _compatible_ with:_

          `+Font' is currently instantiated to an atom.
          (`term_typing:atom/1')

     *Usage 2:* `font_type(-Font)'
        - _Description:_ Gets the value of the `Font' used for the
          text item.

        - _Call and exit should be _compatible_ with:_

          `-Font' is currently instantiated to an atom.
          (`term_typing:atom/1')

 -- PREDICATE: justify_text/1:
     *Usage 1:* `justify_text(+How)'
        - _Description:_ `How' specifies how to justify the text
          within its bounding region. `How' must be one of the values
          left, right or center. This option defaluts to left.

        - _Call and exit should be _compatible_ with:_

          `+How' is currently instantiated to an atom.
          (`term_typing:atom/1')

     *Usage 2:* `justify_text(-How)'
        - _Description:_ Gets `How' is justified the text.

        - _Call and exit should be _compatible_ with:_

          `-How' is currently instantiated to an atom.
          (`term_typing:atom/1')

135 The PiLLoW Web programming library
**************************************

*Author(s):* Daniel Cabeza, Manuel Hermenegildo,  , 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#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#231 (2003/12/22, 17:58:8 CET)

   This package implements the PiLLoW library [CHV96a]. The following
three chapters document, respectively, the predicates for
HTML/XML/CGI programming, the predicate for HTTP conectivity, and the
types used in the definition of the predicates (key for fully
understanding the other predicates). You can find a paper and some
additional information in the `library/pillow/doc' directory of the
distribution, and in the WWW at
`http://clip.dia.fi.upm.es/Software/pillow/pillow.html'. There is
also a _PiLLoW on-line tutorial_ (slides) at
`http://clip.dia.fi.upm.es/logalg/slides/C_pillow/C_pillow.html'
which illustrates the basic features and provides a number of
examples of PiLLoW use.

135.1 Installing PiLLoW
=======================

To correctly install PiLLoW, first, make sure you downloaded the
right version of PiLLoW (there are different versions for different
LP/CLP systems; the version that comes with Ciao is of course the
right one for Ciao). Then, please follow these steps:

  1. Copy the files in the `images' directory to a WWW accessible
     directory in your server.

  2. Edit the file `icon_address.pl' and change the fact to point to
     the URL to be used to access the images above.

  3. In the Ciao system the files are in the correct place, in other
     systems copy the files `pillow.pl' and `icon_address.pl' to a
     suitable directory so that your Prolog system will find them.

135.2 Usage and interface (`pillow')
====================================

   * *Library usage:*

     `:- use_package(pillow).'

     or

     `:- module(...,...,[pillow]).'

   * *New operators defined:*

     `$/2' [150,xfx], `$/1' [150,fx].

   * *Other modules used:*
        - _System library modules:_

          `pillow/http', `pillow/html'.

136 HTML/XML/CGI programming
****************************

*Author(s):* Daniel Cabeza, Manuel Hermenegildo, Sacha Varma.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#351 (2004/6/23, 18:37:20 CEST)

   This module implements the predicates of the PiLLoW package
related to HTML/ XML generation and parsing, CGI and form handlers
programming, and in general all the predicates which do not imply the
use of the HTTP protocol.

136.1 Usage and interface (`html')
==================================

   * *Library usage:*

     `:- use_module(library(html)).'

   * *Exports:*
        - _Predicates:_

          `output_html/1', `html2terms/2', `xml2terms/2', `html_template/3', `html_report_error/1', `get_form_input/1', `get_form_value/3', `form_empty_value/1', `form_default/3', `set_cookie/2', `get_cookies/1', `url_query/2', `url_query_amp/2', `url_query_values/2', `my_url/1', `url_info/2', `url_info_relative/3', `form_request_method/1', `icon_address/2', `html_protect/1', `http_lines/3'.

        - _Multifiles:_

          `define_flag/3', `html_expansion/2'.

   * *Other modules used:*
        - _System library modules:_

          `strings', `lists', `system', `pillow/pillow_aux', `pillow/pillow_types'.

136.2 Documentation on exports (`html')
=======================================

 -- PREDICATE: output_html/1:
     `output_html(HTMLTerm)'

     Outputs `HTMLTerm', interpreted as an `html_term/1', to current
     output stream.

 -- PREDICATE: html2terms/2:
     `html2terms(String, Terms)'

     `String' is a character list containing HTML code and `Terms' is
     its prolog structured representation.

     *Usage 1:* `html2terms(-string, +html_term)'
        - _Description:_ Translates an HTML-term into the HTML code
          it represents.

     *Usage 2:* `html2terms(+string, ?canonic_html_term)'
        - _Description:_ Translates HTML code into a structured
          HTML-term.

 -- PREDICATE: xml2terms/2:
     `xml2terms(String, Terms)'

     `String' is a character list containing XML code and `Terms' is
     its prolog structured representation.

     *Usage 1:* `xml2terms(-string, +html_term)'
        - _Description:_ Translates a XML-term into the XML code it
          represents.

     *Usage 2:* `xml2terms(+string, ?canonic_xml_term)'
        - _Description:_ Translates XML code into a structured
          XML-term.

 -- PREDICATE: html_template/3:
     `html_template(Chars, Terms, Dict)'

     Interprets `Chars' as an HTML template returning in `Terms' the
     corresponding structured HTML-term, which includes variables,
     and unifying `Dict' with a dictionary of those variables (an
     incomplete list of _name_`='_Var_ pairs). An HTML template is
     standard HTML code, but in which "slots" can be defined and
     given an identifier. These slots represent parts of the HTML
     code in which other HTML code can be inserted, and are
     represented in the HTML-term as free variables. There are two
     kinds of variables in templates:
        * Variables representing page contents. A variable with name
          _name_ is defined with the special tag `<V>'_name_`</V>'.

        * Variables representing tag attributes. They occur as an
          attribute or an attribute value starting with `_', followed
          by its name, which must be formed by alphabetic characters.

     As an example, suposse the following HTML template:
          <html>
          <body bgcolor=_bgcolor>
          <v>content</v>
          </body>
          </html>
     The following query in the Ciao toplevel shows how the template
     is parsed, and the dictionary returned:
          ?- file_to_string('template.html',_S), html_template(_S,Terms,Dict).

          Dict = [bgcolor=_A,content=_B|_],
          Terms = [env(html,[],["
          ",env(body,[bgcolor=_A],["
          ",_B,"
          "]),"
          "]),"
          "] ?

          yes
     If a dictionary with values is supplied at call time, then
     variables are unified accordingly inside the template:
          ?- file_to_string('template.html',_S),
             html_template(_S,Terms,[content=b("hello world!"),bgcolor="white"]).

          Terms = [env(html,[],["
          ",env(body,[bgcolor="white"],["
          ",b("hello world!"),"
          "]),"
          "]),"
          "] ?

          yes

 -- PREDICATE: html_report_error/1:
     *Usage:* `html_report_error(Error)'
        - _Description:_ Outputs error `Error' as a standard HTML
          page.

 -- PREDICATE: get_form_input/1:
     `get_form_input(Dict)'

     Translates input from the form (with either the POST or GET
     methods, and even with CONTENT_TYPE multipart/form-data) to a
     dictionary `Dict' of _attribute_=_value_ pairs. If the flag
     `raw_form_values' is `off' (which is the default state), it
     translates empty values (which indicate only the presence of an
     attribute) to the atom `'$empty'', values with more than one
     line (from text areas or files) to a list of lines as strings,
     the rest to atoms or numbers (using `name/2'). If the flag `on',
     it gives all values as atoms, without translations.

 -- PREDICATE: get_form_value/3:
     `get_form_value(Dict, Var, Val)'

     Unifies `Val' with the value for attribute `Var' in dictionary
     `Dict'. Does not fail: value is `''' if not found (this
     simplifies the programming of form handlers when they can be
     accessed directly).

 -- PREDICATE: form_empty_value/1:
     *Usage:* `form_empty_value(Term)'
        - _Description:_ Checks that `Term', a value comming from a
          text area is empty (can have spaces, newlines and
          linefeeds).

 -- PREDICATE: form_default/3:
     *Usage:* `form_default(+Val, +Default, -NewVal)'
        - _Description:_ Useful when a form is only partially filled,
          or when the executable can be invoked either by a link or
          by a form, to set form defaults. If the value of `Val' is
          empty then `NewVal'=`Default', else `NewVal'=`Val'.

 -- PREDICATE: set_cookie/2:
     `set_cookie(Name, Value)'

     Sets a cookie of name `Name' and value `Value'. Must be invoked
     before outputting any data, including the `cgi_reply' html-term.

 -- PREDICATE: get_cookies/1:
     `get_cookies(Cookies)'

     Unifies `Cookies' with a dictionary of _attribute_=_value_ pairs
     of the active cookies for this URL. If the flag
     `raw_form_values' is `on', _value_s are always atoms even if
     they could be interpreted as numbers.

 -- PREDICATE: url_query/2:
     `url_query(Dict, URLArgs)'

     (Deprecated, see `url_query_values/2') Translates a dictionary
     `Dict' of parameter values into a string `URLArgs' for appending
     to a URL pointing to a form handler.

 -- PREDICATE: url_query_amp/2:
     `url_query_amp(Dict, URLArgs)'

     Translates a dictionary `Dict' of parameter values into a string
     `URLArgs' for appending to a URL pointing to a form handler to
     be used in the href of a link (uses &amp; instead of &).

 -- PREDICATE: url_query_values/2:
     `url_query_values(Dict, URLArgs)'

     `Dict' is a dictionary of parameter values and `URLArgs' is the
     URL-encoded string of those assignments, which may appear after
     an URL pointing to a CGI script preceded by a '?'. `Dict' is
     computed according to the `raw_form_values' flag. The use of
     this predicate is reversible.

 -- PREDICATE: my_url/1:
     `my_url(URL)'

     Unifies `URL' with the Uniform Resource Locator (WWW address) of
     this cgi executable.

 -- PREDICATE: url_info/2:
     `url_info(URL, URLTerm)'

     Translates a URL `URL' to a Prolog structure `URLTerm' which
     details its various components, and vice-versa. For now non-HTTP
     URLs make the predicate fail.

 -- PREDICATE: url_info_relative/3:
     `url_info_relative(URL, BaseURLTerm, URLTerm)'

     Translates a relative URL `URL' which appears in the HTML page
     refered to by `BaseURLTerm' into `URLTerm', a Prolog structure
     containing its absolute parameters. Absolute URLs are translated
     as with `url_info/2'. E.g.
          url_info_relative("dadu.html",
                            http('www.foo.com',80,"/bar/scoob.html"), Info)
     gives `Info = http('www.foo.com',80,"/bar/dadu.html")'.

 -- PREDICATE: form_request_method/1:
     *Usage:* `form_request_method(Method)'
        - _Description:_ Unifies `Method' with the method of
          invocation of the form handler (`GET' or `POST').

        - _The following properties hold upon exit:_

          `Method' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: icon_address/2:
     `icon_address(Img, IAddress)'

     The PiLLoW image `Img' has URL `IAddress'.

 -- PREDICATE: html_protect/1:
     `html_protect(Goal)'

     Calls `Goal'. If an error occurs during its execution, or it
     fails, an HTML page is output informing about the incident.
     Normaly the whole execution of a CGI is protected thus.

     _Meta-predicate_ with arguments: `html_protect(goal)'.

     *Usage:*
        - _Calls should, and exit will be compatible with:_

          `Goal' is a term which represents a goal, i.e., an atom or
          a structure.   (`basic_props:callable/1')

 -- PREDICATE: http_lines/3:
     *Usage:* `http_lines(Lines, String, Tail)'
        - _Description:_ `Lines' is a list of the lines with occur in
          `String' until `Tail'. The lines may end UNIX-style or
          DOS-style in `String', in `Lines' they have not end of line
          characters. Suitable to be used in DCGs.

        - _Calls should, and exit will be compatible with:_

          `Lines' is a list of `string's.   (`basic_props:list/2')

          `String' is a string (a list of character codes).
          (`basic_props:string/1')

          `Tail' is a string (a list of character codes).
          (`basic_props:string/1')

136.3 Documentation on multifiles (`html')
==========================================

 -- PREDICATE: define_flag/3:
     Defines a flag as follows:
          define_flag(raw_form_values,[on,off],off).
     (See Changing system behaviour and various flags).

     If flag is `on', values returned by `get_form_input/1' are
     always atoms, unchanged from its original value.

     The predicate is _multifile_.

 -- PREDICATE: html_expansion/2:
     The predicate is _multifile_.

     *Usage:* `html_expansion(Term, Expansion)'
        - _Description:_ Hook predicate to define macros. Expand
          occurrences of `Term' into `Expansion', in `output_html/1'.
          Take care to not transform something into itself!

136.4 Other information (`html')
================================

The code uses input from from L. Naish's forms and F. Bueno's
previous Chat interface. Other people who have contributed are
(please inform us if we leave out anybody): Markus Fromherz, Samir
Genaim.

137 HTTP conectivity
********************

*Author(s):* Daniel Cabeza.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.3#114 (1999/11/24, 0:57:16 MET)

   This module implements the HTTP protocol, which allows retrieving
data from HTTP servers.

137.1 Usage and interface (`http')
==================================

   * *Library usage:*

     `:- use_module(library(http)).'

   * *Exports:*
        - _Predicates:_

          `fetch_url/3'.

   * *Other modules used:*
        - _System library modules:_

          `strings', `lists', `pillow/pillow_aux', `pillow/pillow_types', `pillow/http_ll'.

137.2 Documentation on exports (`http')
=======================================

 -- PREDICATE: fetch_url/3:
     `fetch_url(URL, Request, Response)'

     Fetches the document pointed to by `URL' from Internet, using
     request parameters `Request', and unifies `Response' with the
     parameters of the response. Fails on timeout. Note that
     redirections are not handled automatically, that is, if
     `Response' contains terms of the form
     `status(redirection,301,_)' and `location(NewURL)', the program
     should in most cases access location `NewURL'.

     *Usage:* `fetch_url(URL, Request, Response)'
        - _The following properties should hold at call time:_

          `URL' specifies a URL.   (`pillow_types:url_term/1')

          `Request' is a list of `http_request_param's.
          (`basic_props:list/2')

        - _The following properties hold upon exit:_

          `Response' is a list of `http_response_param's.
          (`basic_props:list/2')

138 PiLLoW types
****************

*Author(s):* Daniel Cabeza.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#253 (2003/12/30, 22:44:55 CET)

   Here are defined the regular types used in the documentation of
the predicates of the PiLLoW package.

138.1 Usage and interface (`pillow_types')
==========================================

   * *Library usage:*

     `:- use_module(library(pillow_types)).'

   * *Exports:*
        - _Regular Types:_

          `canonic_html_term/1', `canonic_xml_term/1', `html_term/1', `form_dict/1', `form_assignment/1', `form_value/1', `value_dict/1', `url_term/1', `http_request_param/1', `http_response_param/1', `http_date/1', `weekday/1', `month/1', `hms_time/1'.

138.2 Documentation on exports (`pillow_types')
===============================================

 -- REGTYPE: canonic_html_term/1:
     A term representing HTML code in canonical, structured way. It
     is a list of terms defined by the following predicate:
          canonic_html_item(comment(S)) :-
                  string(S).
          canonic_html_item(declare(S)) :-
                  string(S).
          canonic_html_item(env(Tag,Atts,Terms)) :-
                  atm(Tag),
                  list(Atts,tag_attrib),
                  canonic_html_term(Terms).
          canonic_html_item($(Tag,Atts)) :-
                  atm(Tag),
                  list(Atts,tag_attrib).
          canonic_html_item(S) :-
                  string(S).

          tag_attrib(Att) :-
                  atm(Att).
          tag_attrib(Att=Val) :-
                  atm(Att),
                  string(Val).
     Each structure represents one HTML construction:
    *env(*_tag_*,*_attribs_*,*_terms_*)*
          An HTML environment, with name _tag_, list of attributes
          _attribs_ and contents _terms_.

    *$(*_tag_*,*_attribs_*)*
          An HTML element of name _tag_ and list of attributes
          _attribs_. `($)/2' is defined by the pillow package as an
          infix, binary operator.

    *comment(*_string_*)*
          An HTML comment (translates to/from `<!--'_string_`-->').

    *declare(*_string_*)*
          An HTML declaration, they are used only in the header
          (translates to/from `<!'_string_`>').

    _string_
          Normal text is represented as a list of character codes.

     For example, the term
          env(a,[href="www.therainforestsite.com"],
                ["Visit ",img$[src="TRFS.gif"]])
     is output to (or parsed from):
          <a href="www.therainforestsite.com">Visit <img src="TRFS.gif"></a>

     *Usage:* `canonic_html_term(HTMLTerm)'
        - _Description:_ `HTMLTerm' is a term representing HTML code
          in canonical form.

 -- REGTYPE: canonic_xml_term/1:
     A term representing XML code in canonical, structured way. It is
     a list of terms defined by the following predicate (see `tag_attrib/1'
     definition in `canonic_html_term/1'):
          canonic_xml_item(Term) :-
                  canonic_html_item(Term).
          canonic_xml_item(xmldecl(Atts)) :-
                  list(Atts,tag_attrib).
          canonic_xml_item(env(Tag,Atts,Terms)) :-
                  atm(Tag),
                  list(Atts,tag_attrib),
                  canonic_xml_term(Terms).
          canonic_xml_item(elem(Tag,Atts)) :-
                  atm(Tag),
                  list(Atts,tag_attrib).
     In addition to the structures defined by `canonic_html_term/1'
     (the `($)/2' structure appears only in malformed XML code), the
     following structures can be used:
    *elem(*_tag_*,*_atts_*)*
          Specifies an XML empty element of name _tag_ and list of
          attributes _atts_. For example, the term
               elem(arc,[weigh="3",begin="n1",end="n2"])
          is output to (or parsed from):
               <arc weigh="3" begin="n1" end="n2"/>

    *xmldecl(*_atts_*)*
          Specifies an XML declaration with attributes _atts_
          (translates to/from `<?xml '_atts_`?>')

     *Usage:* `canonic_xml_term(XMLTerm)'
        - _Description:_ `XMLTerm' is a term representing XML code in
          canonical form.

 -- REGTYPE: html_term/1:
     A term which represents HTML or XML code in a structured way. In
     addition to the structures defined by `canonic_html_term/1' or `canonic_xml_term/1',
     the following structures can be used:
    *begin(*_tag_*,*_atts_*)*
          It translates to the start of an HTML environment of name
          _tag_ and attributes _atts_. There exists also a
          *begin(_tag_)* structure. Useful, in conjunction with the
          next structure, when including in a document output
          generated by an existing piece of code (e.g. _tag_ =
          `pre'). Its use is otherwise discouraged.

    *end(*_tag_*)*
          Translates to the end of an HTML environment of name _tag_.

    *start*
          Used at the beginning of a document (translates to
          `<html>').

    *end*
          Used at the end of a document (translates to `</html>').

    `--'
          Produces a horizontal rule (translates to `<hr>').

    *\\*
          Produces a line break (translates to `<br>').

    *$*
          Produces a paragraph break (translates to `<p>').

    *image(*_address_*)*
          Used to include an image of address (URL) _address_
          (equivalent to `img$[src='_address_`]').

    *image(*_address_*,*_atts_*)*
          As above with the list of attributes _atts_.

    *ref(*_address_*,*_text_*)*
          Produces a hypertext link, _address_ is the URL of the
          referenced resource, _text_ is the text of the reference
          (equivalent to `a([href='_address_`],'_text_`)').

    *label(*_name_*,*_text_*)*
          Labels _text_ as a target destination with label _name_
          (equivalent to `a([name='_name_`],'_text_`)').

    *heading(*_n_*,*_text_*)*
          Produces a heading of level _n_ (between 1 and 6), _text_
          is the text to be used as heading. Useful when one wants a
          heading level relative to another heading (equivalent to
          `h'_n_`('_text_`)').

    *itemize(*_items_*)*
          Produces a list of bulleted items, _items_ is a list of
          corresponding HTML terms (translates to a `<ul>'
          environment).

    *enumerate(*_items_*)*
          Produces a list of numbered items, _items_ is a list of
          corresponding HTML terms (translates to a `<ol>'
          environment).

    *description(*_defs_*)*
          Produces a list of defined items, _defs_ is a list whose
          elements are definitions, each of them being a Prolog
          sequence (composed by `','/2' operators). The last element
          of the sequence is the definition, the other (if any) are
          the defined terms (translates to a `<dl>' environment).

    *nice_itemize(*_img_*,*_items_*)*
          Produces a list of bulleted items, using the image _img_ as
          bullet. The predicate `icon_address/2' provides a colored
          bullet.

    *preformatted(*_text_*)*
          Used to include preformatted text, _text_ is a list of HTML
          terms, each element of the list being a line of the
          resulting document (translates to a `<pre>' environment).

    *verbatim(*_text_*)*
          Used to include text verbatim, special HTML characters
          (`<,>,&,"' and space) are translated into its quoted HTML
          equivalent.

    *prolog_term(*_term_*)*
          Includes any prolog term _term_, represented in functional
          notation. Variables are output as `_'.

    *nl*
          Used to include a newline in the HTML source (just to
          improve human readability).

    *entity(*_name_*)*
          Includes the entity of name _name_ (ISO-8859-1 special
          character).

    *start_form(*_addr_*,*_atts_*)*
          Specifies the beginning of a form. _addr_ is the address
          (URL) of the program that will handle the form, and _atts_
          other attributes of the form, as the method used to invoke
          it. If _atts_ is not present (there is only one argument)
          the method defaults to POST.

    *start_form*
          Specifies the beginning of a form without assigning address
          to the handler, so that the form handler will be the
          cgi-bin executable producing the form.

    *end_form*
          Specifies the end of a form.

    *checkbox(*_name_*,*_state_*)*
          Specifies an input of type `checkbox' with name _name_,
          _state_ is `on' if the checkbox is initially checked.

    *radio(*_name_*,*_value_*,*_selected_*)*
          Specifies an input of type `radio' with name _name_
          (several radio buttons which are interlocked must share
          their name), _value_ is the the value returned by the
          button, if _selected_=_value_ the button is initially
          checked.

    *input(*_type_*,*_atts_*)*
          Specifies an input of type _type_ with a list of attributes
          _atts_. Possible values of _type_ are `text', `hidden',
          `submit', `reset', ldots

    *textinput(*_name_*,*_atts_*,*_text_*)*
          Specifies an input text area of name _name_. _text_
          provides the default text to be shown in the area, _atts_ a
          list of attributes.

    *option(*_name_*,*_val_*,*_options_*)*
          Specifies a simple option selector of name _name_,
          _options_ is the list of available options and _val_ is the
          initial selected option (if _val_ is not in _options_ the
          first item is selected by default) (translates to a
          `<select>' environment).

    *menu(*_name_*,*_atts_*,*_items_*)*
          Specifies a menu of name _name_, list of attributes _atts_
          and list of options _items_. The elements of the list
          _items_ are marked with the prefix operator `$' to indicate
          that they are selected (translates to a `<select>'
          environment).

    *form_reply*

    *cgi_reply*
          This two are equivalent, they do not generate HTML, rather,
          the CGI protocol requires this content descriptor to be
          used at the beginning by CGI executables (including form
          handlers) when replying (translates to `Content-type:
          text/html').

    *pr*
          Includes in the page a graphical logo with the message
          "Developed using the PiLLoW Web programming library", which
          points to the manual and library source.

    _name_*(*_text_*)*
          A term with functor _name_/1, different from the special
          functors defined herein, represents an HTML environment of
          name _name_ and included text _text_. For example, the term
                  address('clip@clip.dia.fi.upm.es')
          is translated into the HTML source
                  <address>clip@clip.dia.fi.upm.es</address>

    _name_*(*_atts_*,*_text_*)*
          A term with functor _name_/2, different from the special
          functors defined herein, represents an HTML environment of
          name _name_, attributes _atts_ and included text _text_.
          For example, the term

                  a([href='http://www.clip.dia.fi.upm.es/'],"Clip home")
          represents the HTML source
                  <a href="http://www.clip.dia.fi.upm.es/">Clip home</a>

     *Usage:* `html_term(HTMLTerm)'
        - _Description:_ `HTMLTerm' is a term representing HTML code.

 -- REGTYPE: form_dict/1:
     *Usage:* `form_dict(Dict)'
        - _Description:_ `Dict' is a dictionary of values of the
          attributes of a form. It is a list of `form_assignment'

 -- REGTYPE: form_assignment/1:
     *Usage:* `form_assignment(Eq)'
        - _Description:_ `Eq' is an assignment of value of an
          attribute of a form. It is defined by:
               form_assignment(A=V) :-
                       atm(A),
                       form_value(V).

               form_value(A) :-
                       atm(A).
               form_value(N) :-
                       num(N).
               form_value(L) :-
                       list(L,string).

 -- REGTYPE: form_value/1:
     *Usage:* `form_value(V)'
        - _Description:_ `V' is a value of an attribute of a form.

 -- REGTYPE: value_dict/1:
     *Usage:* `value_dict(Dict)'
        - _Description:_ `Dict' is a dictionary of values. It is a
          list of pairs _atom_=_constant_.

 -- REGTYPE: url_term/1:
     A term specifying an Internet Uniform Resource Locator.
     Currently only HTTP URLs are supported. Example:
     `http('www.clip.dia.fi.upm.es',80,"/Software/Ciao/")'. Defined as
          url_term(http(Host,Port,Document)) :-
                  atm(Host),
                  int(Port),
                  string(Document).

     *Usage:* `url_term(URL)'
        - _Description:_ `URL' specifies a URL.

 -- REGTYPE: http_request_param/1:
     A parameter of an HTTP request:
        * *head:* Specify that the document content is not wanted.

        * *timeout(*_T_*):* _T_ specifies the time in seconds to wait
          for the response. Default is 300 seconds.

        * *if_modified_since(*_Date_*):* Get document only if newer
          than _Date_. _Date_ has the format defined by `http_date/1'.

        * *user_agent(*_Agent_*):* Provides a user-agent field,
          _Agent_ is an atom. The string `"PiLLoW/1.1"' (or whatever
          version of PiLLoW is used) is appended.

        * *authorization(*_Scheme_,_Params_*):* To provide
          credentials. See RFC 1945 for details.

        * *_option_(*_Value_*):* Any unary term, being _Value_ an
          atom, can be used to provide another valid option (e.g.
          `from('user@machine')').

     *Usage:* `http_request_param(Request)'
        - _Description:_ `Request' is a parameter of an HTTP request.

 -- REGTYPE: http_response_param/1:
     A parameter of an HTTP response:
        * *content(*_String_*):* _String_ is the document content
          (list of bytes). If the `head' parameter of the HTTP
          request is used, an empty list is get here.

        * *status(*_Type,Code,Reason_*):* _Type_ is an atom denoting
          the response type, _Code_ is the status code (an integer),
          and _Reason_ is a string holding the reason phrase.

        * *message_date(*_Date_*):* _Date_ is the date of the
          response, with format defined by `http_date/1'.

        * *location(*_Loc_*):* This parameter appears when the
          document has moved, _Loc_ is an atom holding the new
          location.

        * *http_server(*_Server_*):* _Server_ is the server
          responding, as a string.

        * *authenticate(*_Params_*):* Returned if document is
          protected, _Params_ is a list of chagenges. See RFC 1945
          for details.

        * *allow(*_Methods_*):* _Methods_ are the methods allowed by
          the server, as a list of atoms.

        * *content_encoding(*_Encoding_*):* _Encoding_ is an atom
          defining the encoding.

        * *content_length(*_Length_*):* _Length_ is the length of the
          document (an integer).

        * *content_type(*_Type,Subtype,Params_*):* Specifies the
          document content type, _Type_ and _Subtype_ are atoms,
          _Params_ a list of parameters (e.g.
          `content_type(text,html,[])').

        * *expires(*_Date_*):* _Date_ is the date after which the
          entity should be considered stale. Format defined by `http_date/1'.

        * *last_modified(*_Date_*):* _Date_ is the date at which the
          sender believes the resource was last modified. Format
          defined by `http_date/1'.

        * *pragma(*_String_*):* Miscellaneous data.

        * *_header_(*_String_*):* Any other functor _header_/1 is an
          extension header.

     *Usage:* `http_response_param(Response)'
        - _Description:_ `Response' is a parameter of an HTTP
          response.

 -- REGTYPE: http_date/1:
     `http_date(Date)'

     `Date' is a term defined as
          http_date(date(WeekDay,Day,Month,Year,Time)) :-
                  weekday(WeekDay),
                  int(Day),
                  month(Month),
                  int(Year),
                  hms_time(Time).
     .

     *Usage:* `http_date(Date)'
        - _Description:_ `Date' is a term denoting a date.

 -- REGTYPE: weekday/1:
     *Usage:* `weekday(WeekDay)'
        - _Description:_ `WeekDay' is a term denoting a weekday.

 -- REGTYPE: month/1:
     *Usage:* `month(Month)'
        - _Description:_ `Month' is a term denoting a month.

 -- REGTYPE: hms_time/1:
     *Usage:* `hms_time(Time)'
        - _Description:_ `Time' is an atom of the form `hh:mm:ss'

139 Persistent predicate database
*********************************

*Author(s):* J.M. Gomez, D. Cabeza, and M. Hermenegildo,
`clip@dia.fi.upm.es', `http://www.clip.dia.fi.upm.es/', The CLIP
Group, Facultad de Informa'tica, Universidad Polite'cnica de Madrid.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#346 (2004/5/17, 13:35:59 CEST)

139.1 Introduction to persistent predicates
===========================================

This library implements a _generic persistent predicate database_.
The basic notion implemented by the library is that of a persistent
predicate. The persistent predicate concept provides a simple, yet
powerful generic persistent data access method [CHGT98,Par97]. A
persistent predicate is a special kind of dynamic, data predicate
that "resides" in some persistent medium (such as a set of files, a
database, etc.) that is typically external to the program using such
predicates. The main effect is that any changes made to a persistent
predicate from a program "survive" across executions. I.e., if the
program is halted and restarted the predicate that the new process
sees is in precisely the same state as it was when the old process
was halted (provided no change was made in the meantime to the
storage by other processes or the user).

   Persistent predicates appear to a program as ordinary predicates,
and calls to these predicates can appear in clause bodies in the
usual way. However, the definitions of these predicates do not appear
in the program. Instead, the library maintains automatically the
definitions of predicates which have been declared as persistent in
the persistent storage.

   Updates to persistent predicates can be made using enhanced
versions of `asserta_fact/1', `assertz_fact/1' and `retract_fact/1'.
The library makes sure that each update is a transactional update, in
the sense that if the update terminates, then the permanent storage
has definitely been modified. For example, if the program making the
updates is halted just after the update and then restarted, then the
updated state of the predicate will be seen. This provides security
against possible data loss due to, for example, a system crash. Also,
due to the atomicity of the transactions, persistent predicates allow concurrent
updates from several programs.

139.2 Persistent predicates, files, and relational databases
============================================================

The concept of persistent predicates provided by this library
essentially implements a light-weight, simple, and at the same time
powerful form of relational database (a deductive database), and
which is standalone, in the sense that it does not require external
support, other than the file management capabilities provided by the
operating system. This is due to the fact that the persistent
predicates are in fact stored in one or more auxiliary files below a
given directory.

   This type of database is specially useful when building small to
medium-sized standalone applications in Prolog which require
persistent storage. In many cases it provides a much easier way of
implementing such storage than using files under direct program
control. For example, interactive applications can use persistent
predicates to represent their internal state in a way that is close
to the application. The persistence of such predicates then allows
automatically restoring the state to that at the end of a previous
session. Using persistent predicates amounts to simply declaring some
predicates as such and eliminates having to worry about opening
files, closing them, recovering from system crashes, etc.

   In other cases, however, it may be convenient to use a relational
database as persistent storage. This may be the case, for example,
when the data already resides in such a database (where it is perhaps
accessed also by other applications) or the volume of data is very
large.  `persdb_sql' [CCG98] is a companion library which implements
the same notion of persistent predicates used herein, but keeping the
storage in a relational database. This provides a very natural and
transparent way to access SQL database relations from a Prolog
program. In that library, facilities are also provided for reflecting
more complex _views_ of the database relations as predicates. Such
views can be constructed as conjunctions, disjunctions, projections,
etc. of database relations, and may include SQL-like aggregation
operations.

   A nice characteristic of the notion of persistent predicates used
in both of these libraries is that it abstracts away how the
predicate is actually stored. Thus, a program can use persistent
predicates stored in files or in external relational databases
interchangeably, and the type of storage used for a given predicate
can be changed without having to modify the program (except for
replacing the corresponding `persistent/2' declarations).

   An example application of the `persdb' and `persdb_sql' libraries
(and also the `pillow' library [CH97]), is `WebDB' [GCH98].  `WebDB'
is a generic, highly customizable _deductive database engine_ with an
_html interface_.  `WebDB' allows creating and maintaining
Prolog-based databases as well as relational databases (residing in
conventional relational database engines) using any standard WWW
browser.

139.3 Using file-based persistent predicates
============================================

Persistent predicates can be declared statically, using `persistent/2'
declarations (which is the preferred method, when possible), or
dynamically via calls to `make_persistent/2'. Currently, persistent
predicates may only contain facts, i.e., they are _dynamic_
predicates of type `data/1'.

   Predicates declared as persistent are linked to directory, and the
persistent state of the predicate will be kept in several files below
that directory. The files in which the persistent predicates are
stored are in readable, plain ASCII format, and in Prolog syntax. One
advantage of this approach is that such files can also be created or
edited by hand, in a text editor, or even by other applications.

   An example definition of a persistent predicate implemented by
files follows:

     :- persistent(p/3,dbdir).

     persistent_dir(dbdir, '/home/clip/public_html/db').

   The first line declares the predicate `p/3' persistent. The
argument `dbdir' is a key used to index into a fact of the relation `persistent_dir/2-4',
which specifies the directory where the corresponding files will be
kept. The effect of the declaration, together with the `persistent_dir/2-4'
fact, is that, although the predicate is handled in the same way as a
normal data predicate, in addition the system will create and
maintain efficiently a persistent version of `p/3' via files in the
directory `/home/clip/public_html/db'.

   The level of indirection provided by the `dbdir' argument makes it
easy to place the storage of several persistent predicates in a
common directory, by specifying the same key for all of them. It also
allows changing the directory for several such persistent predicates
by modifying only one fact in the program. Furthermore, the `persistent_dir/2-4'
predicate can even be dynamic and specified at run-time.

139.4 Implementation Issues
===========================

We outline the current implementation approach. This implementation
attempts to provide at the same time efficiency and security. To this
end, up to three files are used for each predicate (the persistence
set): the data file, the operations file, and the backup file. In the updated
state the facts (tuples) that define the predicate are stored in the
data file and the operations file is empty (the backup file, which
contains a security copy of the data file, may or may not exist).

   While a program using a persistent predicate is running, any
insertion (assert) or deletion (retract) operations on the predicate
are performed on both the program memory and on the persistence set.
However, in order to incurr only a small overhead in the execution,
rather than changing the data file directly, a record of each of the
insertion and deletion operations is _appended_ to the operations
file. The predicate is then in a transient state, in that the
contents of the data file do not reflect exactly the current state of
the corresponding predicate. However, the complete persistence set
does.

   When a program starts, all pending operations in the operations
file are performed on the data file. A backup of the data file is
created first to prevent data loss if the system crashes during this
operation. The order in which this updating of files is done ensures
that, if at any point the process dies, on restart the data will be
completely recovered. This process of updating the persistence set
can also be triggered at any point in the execution of the program
(for example, when halting) by calling `update_files'.

139.5 Defining an initial database
==================================

It is possible to define an initial database by simply including in
the program code facts of persistent predicates. They will be
included in the persistent database when it is created. They are
ignored in successive executions.

139.6 Using persistent predicates from the top level
====================================================

Special care must be taken when loading into the top level modules or
user files which use persistent predicates. Beforehand, a goal
`use_module(library('persdb/persdbrt'))' must be issued. Furthermore,
since persistent predicates defined by the loaded files are in this
way defined dynamically, a call to `initialize_db/0' is commonly
needed after loading and before calling predicates of these files.

139.7 Usage and interface (`persdbrt')
======================================

   * *Library usage:*

     There are two packages which implement persistence: `persdb' and `'persdb/ll''
     (for low level). In the first, the standard builtins `asserta_fact/1', `assertz_fact/1',
     and `retract_fact/1' are replaced by new versions which handle
     persistent data predicates, behaving as usual for normal data
     predicates. In the second package, predicates with names
     starting with `p' are defined, so that there is no overhead in
     calling the standard builtins. In any case, each package is used
     as usual: including it in the package list of the module, or
     using the `use_package/1' declaration.

   * *Exports:*
        - _Predicates:_

          `passerta_fact/1', `passertz_fact/1', `pretract_fact/1', `pretractall_fact/1', `asserta_fact/1', `assertz_fact/1', `retract_fact/1', `retractall_fact/1', `initialize_db/0', `make_persistent/2', `update_files/0', `update_files/1', `create/2'.

        - _Multifiles:_

          `persistent_dir/2', `persistent_dir/4', `$is_persistent/2'.

   * *Other modules used:*
        - _System library modules:_

          `lists', `streams', `read', `aggregates', `system', `file_locks/file_locks', `persdb/persdbcache'.

139.8 Documentation on exports (`persdbrt')
===========================================

 -- PREDICATE: passerta_fact/1:
     _Meta-predicate_ with arguments: `passerta_fact(fact)'.

     *Usage:* `passerta_fact(Fact)'
        - _Description:_ Persistent version of `asserta_fact/1': the
          current instance of `Fact' is interpreted as a fact (i.e.,
          a relation tuple) and is added at the beginning of the
          definition of the corresponding predicate. The predicate
          concerned must be declared `persistent'. Any uninstantiated
          variables in the `Fact' will be replaced by new, private
          variables. Defined in the `'persdb/ll'' package.

        - _The following properties should hold at call time:_

          `Fact' is a term which represents a goal, i.e., an atom or
          a structure.   (`basic_props:callable/1')

 -- PREDICATE: passertz_fact/1:
     _Meta-predicate_ with arguments: `passertz_fact(fact)'.

     *Usage:* `passertz_fact(Fact)'
        - _Description:_ Persistent version of `assertz_fact/1': the
          current instance of `Fact' is interpreted as a fact (i.e.,
          a relation tuple) and is added at the end of the definition
          of the corresponding predicate. The predicate concerned
          must be declared `persistent'. Any uninstantiated variables
          in the `Fact' will be replaced by new, private variables.
          Defined in the `'persdb/ll'' package.

        - _The following properties should hold at call time:_

          `Fact' is a term which represents a goal, i.e., an atom or
          a structure.   (`basic_props:callable/1')

 -- PREDICATE: pretract_fact/1:
     `pretract_fact(P)'

     Retracts a predicate in both, the dynamic and the persistent
     databases.

     _Meta-predicate_ with arguments: `pretract_fact(fact)'.

     *Usage:* `pretract_fact(Fact)'
        - _Description:_ Persistent version of `retract_fact/1':
          deletes on backtracking all the facts which unify with
          `Fact'. The predicate concerned must be declared `persistent'.
          Defined in the `'persdb/ll'' package.

        - _The following properties should hold at call time:_

          `Fact' is a term which represents a goal, i.e., an atom or
          a structure.   (`basic_props:callable/1')

 -- PREDICATE: pretractall_fact/1:
     `pretractall_fact(P)'

     Retracts all the instances of a predicate in both, the dynamic
     and the persistent databases.

     _Meta-predicate_ with arguments: `pretractall_fact(fact)'.

 -- PREDICATE: asserta_fact/1:
     _Meta-predicate_ with arguments: `asserta_fact(fact)'.

     *Usage:* `asserta_fact(Fact)'
        - _Description:_ Same as `passerta_fact/1', but if the
          predicate concerned is not persistent then behaves as the
          builtin of the same name. Defined in the `persdb' package.

        - _The following properties should hold at call time:_

          `Fact' is a term which represents a goal, i.e., an atom or
          a structure.   (`basic_props:callable/1')

 -- PREDICATE: assertz_fact/1:
     _Meta-predicate_ with arguments: `assertz_fact(fact)'.

     *Usage:* `assertz_fact(Fact)'
        - _Description:_ Same as `passertz_fact/1', but if the
          predicate concerned is not persistent then behaves as the
          builtin of the same name. Defined in the `persdb' package.

        - _The following properties should hold at call time:_

          `Fact' is a term which represents a goal, i.e., an atom or
          a structure.   (`basic_props:callable/1')

 -- PREDICATE: retract_fact/1:
     _Meta-predicate_ with arguments: `retract_fact(fact)'.

     *Usage:* `retract_fact(Fact)'
        - _Description:_ Same as `pretract_fact/1', but if the
          predicate concerned is not persistent then behaves as the
          builtin of the same name. Defined in the `persdb' package.

        - _The following properties should hold at call time:_

          `Fact' is a term which represents a goal, i.e., an atom or
          a structure.   (`basic_props:callable/1')

 -- PREDICATE: retractall_fact/1:
     _Meta-predicate_ with arguments: `retractall_fact(fact)'.

     *Usage:* `retractall_fact(Fact)'
        - _Description:_ Same as `pretractall_fact/1', but if the
          predicate concerned is not persistent then behaves as the
          builtin of the same name. Defined in the `persdb' package.

        - _The following properties should hold at call time:_

          `Fact' is a term which represents a goal, i.e., an atom or
          a structure.   (`basic_props:callable/1')

 -- PREDICATE: initialize_db/0:
     *Usage:*
        - _Description:_ Initializes the whole database, updating the
          state of the declared persistent predicates. Must be called
          explicitly after dynamically defining clauses for `persistent_dir/2'.

 -- PREDICATE: make_persistent/2:
     _Meta-predicate_ with arguments: `make_persistent(spec,?)'.

     *Usage:* `make_persistent(PredDesc, Keyword)'
        - _Description:_ Dynamic version of the `persistent'
          declaration.

        - _The following properties should hold at call time:_

          `PredDesc' is a Name/Arity structure denoting a predicate
          name:
               predname(P/A) :-
                       atm(P),
                       nnegint(A).

          (`basic_props:predname/1')

          `Keyword' is an atom corresponding to a directory
          identifier.   (`persdbcache:keyword/1')

 -- PREDICATE: update_files/0:
     *Usage:*
        - _Description:_ Updates the files comprising the persistence
          set of all persistent predicates defined in the application.

 -- PREDICATE: update_files/1:
     _Meta-predicate_ with arguments: `update_files(list(spec))'.

     *Usage:* `update_files(PredSpecList)'
        - _Description:_ Updates the files comprising the persistence
          set of the persistent predicates in `PredSpecList'.

        - _Call and exit should be _compatible_ with:_

          `PredSpecList' is a list of `predname's.
          (`basic_props:list/2')

 -- PREDICATE: create/2:
     No further documentation available for this predicate.

139.9 Documentation on multifiles (`persdbrt')
==============================================

 -- PREDICATE: persistent_dir/2:
     The predicate is _multifile_.

     The predicate is of type _data_.

     *Usage:* `persistent_dir(Keyword, Location_Path)'
        - _Description:_ Relates identifiers of locations (the
          `Keyword's) with descriptions of such locations
          (`Location_Path's). `Location_Path' is *a directory* and it
          means that the definition for the persistent predicates
          associated with `Keyword' is kept in files below that
          directory (which must previously exist). These files, in
          the updated state, contain the actual definition of the
          predicate in Prolog syntax (but with module names resolved).

        - _The following properties should hold at call time:_

          `Keyword' is an atom corresponding to a directory
          identifier.   (`persdbcache:keyword/1')

          `Location_Path' is an atom, the name of a directory.
          (`persdbrt:directoryname/1')

 -- PREDICATE: persistent_dir/4:
     The predicate is _multifile_.

     The predicate is of type _data_.

     *Usage:* `persistent_dir(Keyword, Location_Path, DirPerms,
     FilePerms)'
        - _Description:_ The same as `persistent_dir/2', but
          including also the permission modes for persistent
          directories and files.

        - _The following properties should hold at call time:_

          `Keyword' is an atom corresponding to a directory
          identifier.   (`persdbcache:keyword/1')

          `Location_Path' is an atom, the name of a directory.
          (`persdbrt:directoryname/1')

          `DirPerms' is an integer.   (`basic_props:int/1')

          `FilePerms' is an integer.   (`basic_props:int/1')

 -- PREDICATE: $is_persistent/2:
     `$is_persistent(Spec, Key)'

     Predicate `Spec' persists within database `Key'. Programmers
     should not define this predicate directly in the program.

     The predicate is _multifile_.

     The predicate is of type _data_.

139.10 Documentation on internals (`persdbrt')
==============================================

 -- DECLARATION: persistent/2:
     *Usage:* :- `persistent(PredDesc, Keyword)'.
        - _Description:_ Declares the predicate `PredDesc' as
          persistent. `Keyword' is the identifier of a location where
          the persistent storage for the predicate is kept. The
          location `Keyword' is described in the `persistent_dir'
          predicate, which must contain a fact in which the first
          argument unifies with `Keyword'.

        - _The following properties should hold upon exit:_

          `PredDesc' is a Name/Arity structure denoting a predicate
          name:
               predname(P/A) :-
                       atm(P),
                       nnegint(A).

          (`basic_props:predname/1')

          `Keyword' is an atom corresponding to a directory
          identifier.   (`persdbcache:keyword/1')

 -- PREDICATE: keyword/1:
     An atom which identifies a fact of the `persistent_dir/2'
     relation. This fact relates this atom to a directory in which
     the persistent storage for one or more persistent predicates is
     kept. Storage is expected under a subdirectory by the name of
     the module and in a file by the name of the predicate.

 -- REGTYPE: directoryname/1:
     *Usage:* `directoryname(X)'
        - _Description:_ `X' is an atom, the name of a directory.

139.11 Known bugs and planned improvements (`persdbrt')
=======================================================

   * To load in the toplevel a file which uses this package, module
     `library('persdb/persdbrt')' has to be previously loaded.

140 Using the persdb library
****************************

*Author(s):* The CLIP Group.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#232 (2003/12/22, 18:4:0 CET)

   Through the following examples we will try to illustrate the two
mains ways of declaring and using persistent predicates: statically
(the preferred method) and dynamically (necessary when the new
persistent predicates have to be defined at run-time). The final
example is a small application implementing a simple persistent queue.

140.1 An example of persistent predicates (static version)
==========================================================

     :- use_package(iso).
     :- use_package(persdb).

     %% Declare the directory associated to the key "db" where the
     %% persistence sets of the persistent predicates are stored:
     persistent_dir(db,'./').

     %% Declare a persistent predicate:
     :- persistent(bar/1, db).

     %% Read a term, storing it in a new fact of the persistent predicate
     %% and list all the current facts of that predicate
     main:-
              read(X),
              assertz_fact(bar(X)),
              findall(Y,bar(Y),L),
              write(L).

     erase_one :-
             retract_fact(bar(_)).
     erase_all :-
             retractall_fact(bar(_)).

     u(X) :- update_files(X).

140.2 An example of persistent predicates (dynamic version)
===========================================================

     :- use_package(iso).
     :- use_package(persdb).

     main([X]):-
     %%   Declare the directory associated to the key "db"
          asserta_fact(persistent_dir(db,'./')),
     %%   Declare the predicate bar/1 as dynamic (and data) at run-time
          data(bar/1),
     %%   Declare the predicate bar/1 as persistent at run-time
          make_persistent(bar/1, db),
          assertz_fact(bar(X)),
          findall(Y, bar(Y), L),
          write(L).

140.3 A simple application / a persistent queue
===============================================

     :- module(queue, [main/0],[persdb]).

     :- use_package(iso).

     :- use_module(library(read)).
     :- use_module(library(write)).
     :- use_module(library(aggregates)).

     persistent_dir(queue_dir,'./pers').

     :- persistent(queue/1, queue_dir).

     queue(first).
     queue(second).

     main:-
          write('Action ( in(Term). | slip(Term) | out. | list. | halt. ): '),
          read(A),
          (  handle_action(A)
          -> true
          ;  write('Unknown command.'), nl ),
          main.

     handle_action(end_of_file) :-
          halt.
     handle_action(halt) :-
          halt.
     handle_action(in(Term)) :-
          assertz_fact(queue(Term)),
          main.
     handle_action(slip(Term)) :-
          asserta_fact(queue(Term)),
          main.
     handle_action(out) :-
          (  retract_fact(queue(Term))
          -> write('Out '), write(Term)
          ;  write('FIFO empty.') ),
          nl,
          main.
     handle_action(list) :-
          findall(Term,queue(Term),Terms),
          write('Contents: '), write(Terms), nl,
          main.

141 Filed predicates
********************

*Author(s):* Francisco Bueno.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.10#3 (2004/8/4, 11:52:38 CEST)

   This package allows using files as a " cache" for predicates
defined by facts. This is useful for huge tables of facts that may
push the memory limits of the system too far. Goals of a filed
predicate are executed simply by reading from the corresponding file.

   Anything in the DB file used for the predicate that is different
from a fact for the corresponding predicate is ignored. Each call to
a filed predicate forces opening the file, so the use of this package
is subject to the limit on the number of open files that the system
can support.

   Dynamic modification of the filed predicates is also allowed
during execution of the program. Thus filed predicates are regarded
as dynamic, data predicates residing in a file. However, dynamic
modifications to the predicates do not affect the file, unless the
predicate is also declared persistent.

   The package is compatible with `persdb' in the sense that a
predicate can be made both filed and persistent. In this way, the
predicate can be used in programs, but it will not be loaded (saving
memory), can also be modified during execution, and modifications
will persist in the file. Thus, the user interface to both packages
is the same (so the DB file must be one for both filing and
persistency).

141.1 Usage and interface (`factsdb_rt')
========================================

   * *Library usage:*

     This facility is used as a package, thus either including `factsdb'
     in the package list of the module, or by using the `use_package/1'
     declaration. The facility predicates are defined in library
     module `factsdb_rt'.

   * *Exports:*
        - _Predicates:_

          `asserta_fact/1', `assertz_fact/1', `call/1', `current_fact/1', `retract_fact/1'.

        - _Multifiles:_

          `$factsdb$cached_goal/3', `persistent_dir/2', `file_alias/2'.

   * *Other modules used:*
        - _System library modules:_

          `counters', `read', `persdb/persdbcache'.

141.2 Documentation on exports (`factsdb_rt')
=============================================

 -- PREDICATE: asserta_fact/1:
     _Meta-predicate_ with arguments: `asserta_fact(fact)'.

     *Usage:* `asserta_fact(Fact)'
        - _Description:_ Version of `data_facts:asserta_fact/1' for
          filed predicates. The current instance of `Fact' is
          interpreted as a fact and is added at the beginning of the
          definition of the corresponding predicate. Therefore,
          before all the facts filed in the DB file for the
          predicate. The predicate concerned must be declared as `facts';
          if it is not, then `data_facts:asserta_fact/1' is used.

        - _The following properties should hold at call time:_

          `Fact' is a term which represents a goal, i.e., an atom or
          a structure.   (`basic_props:callable/1')

 -- PREDICATE: assertz_fact/1:
     _Meta-predicate_ with arguments: `assertz_fact(fact)'.

     *Usage:* `assertz_fact(Fact)'
        - _Description:_ Version of `data_facts:assertz_fact/1' for
          filed predicates. The current instance of `Fact' is
          interpreted as a fact and is added at the end of the
          definition of the corresponding predicate. Therefore, after
          all the facts filed in the DB file for the predicate. The
          predicate concerned must be declared as `facts'; if it is
          not, then `data_facts:assertz_fact/1' is used.

        - _The following properties should hold at call time:_

          `Fact' is a term which represents a goal, i.e., an atom or
          a structure.   (`basic_props:callable/1')

 -- PREDICATE: call/1:
     _Meta-predicate_ with arguments: `call(fact)'.

     *Usage:* `call(Fact)'
        - _Description:_ Same as `current_fact/1' if the predicate
          concerned is declared as `facts'. If it is not, an
          exception is raised.

        - _The following properties should hold at call time:_

          `Fact' is a term which represents a goal, i.e., an atom or
          a structure.   (`basic_props:callable/1')

 -- PREDICATE: current_fact/1:
     _Meta-predicate_ with arguments: `current_fact(fact)'.

     *Usage:* `current_fact(Fact)'
        - _Description:_ Version of `data_facts:current_fact/1' for
          filed predicates. The current instance of `Fact' is
          interpreted as a fact and is unified with an actual fact in
          the current definition of the corresponding predicate.
          Therefore, with a fact previously asserted or filed in the
          DB file for the predicate, if it has not been retracted.
          The predicate concerned must be declared as `facts'; if it
          is not, then `data_facts:current_fact/1' is used.

        - _The following properties should hold at call time:_

          `Fact' is a term which represents a goal, i.e., an atom or
          a structure.   (`basic_props:callable/1')

 -- PREDICATE: retract_fact/1:
     _Meta-predicate_ with arguments: `retract_fact(fact)'.

     *Usage:* `retract_fact(Fact)'
        - _Description:_ Version of `data_facts:retract_fact/1' for
          filed predicates. The current instance of `Fact' is
          interpreted as a fact and is unified with an actual fact in
          the current definition of the corresponding predicate; such
          a fact is deleted from the predicate definition. This is
          true even for the facts filed in the DB file for the
          predicate; but these are NOT deleted from the file (unless
          the predicate is persistent). The predicate concerned must
          be declared as `facts'; if it is not, then `data_facts:retract_fact/1'
          is used.

        - _The following properties should hold at call time:_

          `Fact' is a term which represents a goal, i.e., an atom or
          a structure.   (`basic_props:callable/1')

141.3 Documentation on multifiles (`factsdb_rt')
================================================

 -- PREDICATE: $factsdb$cached_goal/3:
     `$factsdb$cached_goal(Spec, Spec, Key)'

     Predicate `Spec' is filed within database `Key'. Programmers
     should not define this predicate directly in the program.

     The predicate is _multifile_.

 -- PREDICATE: persistent_dir/2:
     See `persdb'.

     The predicate is _multifile_.

     The predicate is of type _data_.

 -- PREDICATE: file_alias/2:
     See `symfnames'. This predicate is used only if `persistent_dir/2'
     fails.

     The predicate is _multifile_.

     The predicate is of type _data_.

141.4 Documentation on internals (`factsdb_rt')
===============================================

 -- DECLARATION: facts/2:
     *Usage:* :- `facts(PredDesc, Keyword)'.
        - _Description:_ Declares the predicate `PredDesc' as filed.
          `Keyword' is the identifier of a location where the file DB
          for the predicate is kept. The location `Keyword' is
          described in the `file_alias' predicate, which must contain
          a fact in which the first argument unifies with `Keyword'.

        - _The following properties should hold upon exit:_

          `PredDesc' is a Name/Arity structure denoting a predicate
          name:
               predname(P/A) :-
                       atm(P),
                       nnegint(A).

          (`basic_props:predname/1')

          `Keyword' is an atom corresponding to a directory
          identifier.   (`persdbcache:keyword/1')

 -- PREDICATE: keyword/1:
     See `persdbrt'. The same conventions for location of DB files
     apply in both packages.

141.5 Known bugs and planned improvements (`factsdb_rt')
========================================================

   * The DB files for persistent predicates have to be used as such
     from the beginning. Using a DB file for a filed predicate first,
     and then using it also when making the predicate persistent
     won't work. Nor the other way around: using a DB file for a
     persistent predicate first, and then using it also when making
     the predicate filed.

142 SQL persistent database interface
*************************************

*Author(s):* I. Caballero, D. Cabeza, J.M. Go'mez, M. Hermenegildo,
J. F. Morales, and M. Carro, `clip@dia.fi.upm.es',
`http://www.clip.dia.fi.upm.es/', The CLIP Group, Facultad de
Informa'tica, Universidad Polite'cnica de Madrid.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#113 (2003/11/27, 20:56:6 CET)

   The purpose of this library is to implement an instance of the
generic concept of persistent predicates, where external relational
databases are used for storage (see the documentation of the `persdb'
library and [CHGT98,Par97] for details). To this end, this library
exports SQL persistent versions of the `assertz_fact/1', `retract_fact/1'
and `retractall_fact/1' builtin predicates. Persistent predicates
also allow concurrent updates from several programs, since each
update is atomic.

   The notion of persistence provides a very natural and transparent
way to access database relations from a Prolog program. Stub
definitions are provided for such predicates which access the
database when the predicate is called (using the `db_client'
library). A Prolog to SQL translator is used to generate the required SQL
code dynamically (see library `pl2sql').

   This library also provides facilities for reflecting more complex views
of the database relations as Prolog predicates. Such views can be
constructed as conjunctions, disjunctions, projections, etc. of
database relations. Also, SQL-like aggregation operations are
supported.

142.1 Implementation of the Database Interface
==============================================

The architecture of the low-level implementation of the database
interface was defined with two goals in mind:

   * to simplify the communication between the Prolog system and the
     relational database engines as much as possible, and

   * to give as much flexibility as possible to the overall system.
     This includes simultaneous access to several databases, allowing
     both the databases and clients to reside on the same physical
     machine or different machines, and allowing the clients to
     reside in Win95/NT or Unix machines.

   In order to allow the flexibility mentioned above, a client-sever
architecture was chosen. At the server side, a MySQL server connects
to the databases using the MySQL. At the client side, a MySQL client
interface connects to this server. The server daemon (mysqld) should
be running in the server machine; check your MySQL documentation on
how to do that.

   After the connection is established a client can send commands to
the mediator server which will pass them to the corresponding
database server, and then the data will traverse in the opposite
direction. These messages include logging on and off from the
database, sending SQL queries, and receiving the responses.

   The low level implementation of the current library is
accomplished by providing abstraction levels over the MySQL interface
library. These layers of abstraction implement the persistent
predicate view, build the appropriate commands for the database using
a translator of Prolog goals to SQL commands, issue such commands
using the mediator send/receive procedures, parse the responses, and
present such responses to the Prolog engine via backtracking.

142.2 Example(s)
================

142.3 Usage and interface (`persdbrt_mysql')
============================================

   * *Library usage:*

     Typically, this library is used including the 'persdb_mysql'
     package into the package list of the module, or using the `use_package/1'
     declaration:
    In a module:
               	:- module(bar, [main/1], [persdb_mysql]).
          or
                       :- module(bar, [main/1]).
                       :- include(library(persdb_mysql)).

    In a _user_ file:
               	:- use_package([persdb_mysql]).
          or
                       :- include(library(persdb_mysql)).
     This loads the run-time and compile-time versions of the
     library (`persdbtr_mysql.pl' and `persdbrt_mysql.pl') and
     includes some needed declarations.

   * *Exports:*
        - _Predicates:_

          `init_sql_persdb/0', `dbassertz_fact/1', `dbretract_fact/1', `dbcurrent_fact/1', `dbretractall_fact/1', `make_sql_persistent/3', `dbfindall/4', `dbcall/2', `sql_query/3', `sql_get_tables/2', `sql_table_types/3'.

        - _Multifiles:_

          `sql_persistent_location/2'.

   * *Other modules used:*
        - _System library modules:_

          `det_hook/det_hook_rt', `persdb_mysql/db_client_types', `persdb_mysql/pl2sql', `persdb_sql_common/sqltypes', `dynamic', `terms', `terms_vars', `messages', `lists', `aggregates', `persdb_mysql/mysql_client', `persdb_sql_common/pl2sqlinsert', `persdb_mysql/delete_compiler/pl2sqldelete'.

142.4 Documentation on exports (`persdbrt_mysql')
=================================================

 -- PREDICATE: init_sql_persdb/0:
     *Usage:*
        - _Description:_ Internal predicate, used to transform
          predicates statically declared as persistent (see `sql_persistent/3')
          into real persistent predicates.

 -- PREDICATE: dbassertz_fact/1:
     *Usage:* `dbassertz_fact(+Fact)'
        - _Description:_ Persistent extension of `assertz_fact/1':
          the current instance of `Fact' is interpreted as a fact
          (i.e., a relation tuple) and is added to the end of the
          definition of the corresponding predicate. If any integrity
          constraint violation is done (database stored predicates),
          an error will be displayed. The predicate concerned must be
          statically ( `sql_persistent/3') or dinamically ( `make_sql_persistent/3')
          declared. Any uninstantiated variables in the `Fact' will
          be replaced by new, private variables. *Note:* _assertion
          of facts with uninstantiated variables not implemented at
          this time._

        - _Call and exit should be _compatible_ with:_

          `+Fact' is a fact (a term whose main functor is not
          `':-'/2').   (`persdbrt_mysql:fact/1')

 -- PREDICATE: dbretract_fact/1:
     *Usage:* `dbretract_fact(+Fact)'
        - _Description:_ Persistent extension of `retract_fact/1':
          deletes on backtracking all the facts which unify with
          `Fact'. The predicate concerned must be statically ( `sql_persistent/3')
          or dinamically ( `make_sql_persistent/3') declared.

        - _Call and exit should be _compatible_ with:_

          `+Fact' is a fact (a term whose main functor is not
          `':-'/2').   (`persdbrt_mysql:fact/1')

 -- PREDICATE: dbcurrent_fact/1:
     *Usage:* `dbcurrent_fact(+Fact)'
        - _Description:_ Persistent extension of `current_fact/1':
          the fact `Fact' exists in the current database. The
          predicate concerned must be declared `sql_persistent/3'.
          Provides on backtracking all the facts (tuples) which unify
          with `Fact'.

        - _Call and exit should be _compatible_ with:_

          `+Fact' is a fact (a term whose main functor is not
          `':-'/2').   (`persdbrt_mysql:fact/1')

 -- PREDICATE: dbretractall_fact/1:
     *Usage:* `dbretractall_fact(+Fact)'
        - _Description:_ Persistent extension of `retractall_fact/1':
          when called deletes all the facts which unify with `Fact'.
          The predicate concerned must be statically ( `sql_persistent/3')
          or dinamically ( `make_sql_persistent/3') declared.

        - _Call and exit should be _compatible_ with:_

          `+Fact' is a fact (a term whose main functor is not
          `':-'/2').   (`persdbrt_mysql:fact/1')

 -- PREDICATE: make_sql_persistent/3:
     _Meta-predicate_ with arguments:
     `make_sql_persistent(addmodule,?,?)'.

     *Usage:* `make_sql_persistent(PrologPredTypes, TableAttributes,
     Keyword)'
        - _Description:_ Dynamic version of the `sql_persistent/3'
          declaration.

        - _The following properties should hold upon exit:_

          `PrologPredTypes' is a structure describing a Prolog
          predicate name with its types.
          (`persdbrt_mysql:prologPredTypes/1')

          `TableAttributes' is a structure describing a table name
          and some attributes.   (`persdbrt_mysql:tableAttributes/1')

          `Keyword' is the name of a persistent storage location.
          (`persdbrt_mysql:persLocId/1')

 -- PREDICATE: dbfindall/4:
     _Meta-predicate_ with arguments: `dbfindall(?,?,goal,?)'.

     *Usage:* `dbfindall(+DBId, +Pattern, +ComplexGoal, -Results)'
        - _Description:_ Similar to `findall/3', but `Goal' is
          executed in database `DBId'. Certain restrictions and
          extensions apply to both `Pattern' and `ComplexGoal'
          stemming from the Prolog to SQL translation involved (see
          the corresponding type definitions for details).

        - _Call and exit should be _compatible_ with:_

          `+DBId' a unique identifier of a database session
          connection.   (`mysql_client:dbconnection/1')

          `+Pattern' is a database projection term.
          (`pl2sql:projterm/1')

          `+ComplexGoal' is a database query goal.
          (`pl2sql:querybody/1')

          `-Results' is a list.   (`basic_props:list/1')

 -- PREDICATE: dbcall/2:
     *Usage:* `dbcall(+DBId, +ComplexGoal)'
        - _Description:_ Internal predicate, used by the transformed
          versions of the persistent predicates. Not meant to be
          called directly by users. It is exported by the library so
          that it can be used by the transformed versions of the
          persistent predicates in the modules in which they reside.
          Sends `ComplexGoal' to database `DBId' for evaluation.
          `ComplexGoal' must be a call to a persistent predicate
          which resides in database `DBId'.

        - _Call and exit should be _compatible_ with:_

          `+DBId' a unique identifier of a database session
          connection.   (`mysql_client:dbconnection/1')

          `+ComplexGoal' is a database query goal.
          (`pl2sql:querybody/1')

 -- PREDICATE: sql_query/3:
     *Usage:* `sql_query(+DBId, +SQLString, AnswerTableTerm)'
        - _Description:_ `ResultTerm' is the response from database
          `DBId' to the SQL query in `SQLString' to database `DBId'.
          `AnswerTableTerm' can express a set of tuples, an error
          answer or a 'ok' response (see `answertableterm/1' for
          details). At the moment, `sql_query/3' log in and out for
          each query. This should be changed to log in only the first
          time and log out on exit and/or via a timer in the standard
          way.

        - _Call and exit should be _compatible_ with:_

          `+DBId' a unique identifier of a database session
          connection.   (`mysql_client:dbconnection/1')

          `+SQLString' is a string containing SQL code.
          (`pl2sql:sqlstring/1')

          `AnswerTableTerm' is a response from the ODBC database
          interface.   (`persdbrt_mysql:answertableterm/1')

 -- PREDICATE: sql_get_tables/2:
     *Usage 1:* `sql_get_tables(+Location, -Tables)'
        - _Description:_ `Tables' contains the tables available in
          `Location'.

        - _Call and exit should be _compatible_ with:_

          `+Location' is a structure describing a database.
          (`persdbrt_mysql:database_desc/1')

          `-Tables' is a list of `atm's.   (`basic_props:list/2')

     *Usage 2:* `sql_get_tables(+DbConnection, -Tables)'
        - _Description:_ `Tables' contains the tables available in
          `DbConnection'.

        - _Call and exit should be _compatible_ with:_

          `+DbConnection' a unique identifier of a database session
          connection.   (`mysql_client:dbconnection/1')

          `-Tables' is a list of `atm's.   (`basic_props:list/2')

 -- PREDICATE: sql_table_types/3:
     *Usage 1:* `sql_table_types(+Location, +Table, -AttrTypes)'
        - _Description:_ `AttrTypes' are the attributes and types of
          `Table' in `Location'.

        - _Call and exit should be _compatible_ with:_

          `+Location' is a structure describing a database.
          (`persdbrt_mysql:database_desc/1')

          `+Table' is an atom.   (`basic_props:atm/1')

          `-AttrTypes' is a list.   (`basic_props:list/1')

     *Usage 2:* `sql_table_types(+DbConnection, +Table, -AttrTypes)'
        - _Description:_ `AttrTypes' are the attributes and types of
          `Table' in `DbConnection'.

        - _Call and exit should be _compatible_ with:_

          `+DbConnection' a unique identifier of a database session
          connection.   (`mysql_client:dbconnection/1')

          `+Table' is an atom.   (`basic_props:atm/1')

          `-AttrTypes' is a list.   (`basic_props:list/1')

 -- REGTYPE: socketname/1:
     *Usage:* `socketname(IPP)'
        - _Description:_ `IPP' is a structure describing a complete
          TCP/IP port address.

 -- REGTYPE: dbname/1:
     *Usage:* `dbname(DBId)'
        - _Description:_ `DBId' is the identifier of an database.

 -- REGTYPE: user/1:
     *Usage:* `user(User)'
        - _Description:_ `User' is a user name in the database.

 -- REGTYPE: passwd/1:
     *Usage:* `passwd(Passwd)'
        - _Description:_ `Passwd' is the password for the user name
          in the database.

 -- REGTYPE: projterm/1:
     *Usage:* `projterm(DBProjTerm)'
        - _Description:_ `DBProjTerm' is a database projection term.

 -- REGTYPE: querybody/1:
     *Usage:* `querybody(DBGoal)'
        - _Description:_ `DBGoal' is a database query goal.

 -- (: UNDOC_REEXPORT) sqltype/1:
     Imported from `sqltypes' (see the corresponding documentation
     for details).

142.5 Documentation on multifiles (`persdbrt_mysql')
====================================================

 -- PREDICATE: sql_persistent_location/2:
     Relates names of locations (the `Keyword's) with descriptions of
     such locations (`Location's).

     The predicate is _multifile_.

     The predicate is of type _dynamic_.

     *Usage:* `sql_persistent_location(Keyword, DBLocation)'
        - _Description:_ In this usage, `DBLocation' is a _relational
          database_, in which case the predicate is stored as tuples
          in the database.

        - _The following properties should hold upon exit:_

          `Keyword' is the name of a persistent storage location.
          (`persdbrt_mysql:persLocId/1')

          `DBLocation' is a structure describing a database.
          (`persdbrt_mysql:database_desc/1')

142.6 Documentation on internals (`persdbrt_mysql')
===================================================

 -- REGTYPE: tuple/1:
          tuple(T) :-
                  list(T,atm).
          tuple(T) :-
                  list(T,atm).

     *Usage:* `tuple(T)'
        - _Description:_ `T' is a tuple of values from the ODBC
          database interface.

 -- REGTYPE: dbconnection/1:
     *Usage:* `dbconnection(H)'
        - _Description:_ `H' a unique identifier of a database
          session connection.

 -- DECLARATION: sql_persistent/3:
     *Usage:* :- `sql_persistent(PrologPredTypes, TableAttributes,
     Keyword)'.
        - _Description:_ Declares the predicate corresponding to the
          main functor of `PrologPredTypes' as SQL persistent.
          `Keyword' is the name of a location where the persistent
          storage for the predicate is kept, which in this case must
          be an external relational database. The description of this
          database is given through the `sql_persistent_location'
          predicate, which must contain a fact in which the first
          argument unifies with `Keyword'. `TableAttributes' provides
          the table name and attributes in the database corresponding
          respectively to the predicate name and arguments of the
          (virtual) Prolog predicate.

          Although a predicate may be persistent, other usual clauses
          can be defined in the source code. When querying a
          persistent predicate with non-persistent clauses,
          persistent and non-persisten clauses will be evaluated in
          turn; the order of evaluation is the usual Prolog order,
          considering that persistent clauses are defined in the
          program point where the `sql_persistent/3' declaration is.

          *Example:*

               :- sql_persistent(product( integer,    integer, string, string ),
                             product( quantity,   id,      name,   size   ),
                             radiowebdb).

               sql_persistent_location(radiowebdb,
                  db('SQL Anywhere 5.0 Sample', user, pass,
                     'r2d5.dia.fi.upm.es':2020)).

        - _The following properties should hold upon exit:_

          `PrologPredTypes' is a structure describing a Prolog
          predicate name with its types.
          (`persdbrt_mysql:prologPredTypes/1')

          `TableAttributes' is a structure describing a table name
          and some attributes.   (`persdbrt_mysql:tableAttributes/1')

          `Keyword' is the name of a persistent storage location.
          (`persdbrt_mysql:persLocId/1')

 -- PREDICATE: db_query/4:
     *Usage:* `db_query(+DBId, +ProjTerm, +Goal, ResultTerm)'
        - _Description:_ `ResultTerm' contains all the tuples which
          are the response from database `DBId' to the Prolog query
          `Goal', projected onto `ProjTerm'. Uses `pl2sqlstring/3'
          for the Prolog to SQL translation and `sql_query/3' for
          posing the actual query.

        - _Call and exit should be _compatible_ with:_

          `+DBId' a unique identifier of a database session
          connection.   (`mysql_client:dbconnection/1')

          `+ProjTerm' is a database projection term.
          (`pl2sql:projterm/1')

          `+Goal' is a database query goal.   (`pl2sql:querybody/1')

          `ResultTerm' is a tuple of values from the ODBC database
          interface.   (`persdbrt_mysql:tuple/1')

 -- PREDICATE: db_query_one_tuple/4:
     *Usage:* `db_query_one_tuple(+DBId, +ProjTerm, +Goal,
     ResultTerm)'
        - _Description:_ `ResultTerm' is one of the tuples which are
          the response from database `DBId' to the Prolog query
          `Goal', projected onto `ProjTerm'. Uses `pl2sqlstring/3'
          for the Prolog to SQL translation and `sql_query_one_tuple/3'
          for posing the actual query. After last tuple has been
          reached, a null tuple is unified with ResultTerm, and the
          connection to the database finishes.

        - _Call and exit should be _compatible_ with:_

          `+DBId' a unique identifier of a database session
          connection.   (`mysql_client:dbconnection/1')

          `+ProjTerm' is a database projection term.
          (`pl2sql:projterm/1')

          `+Goal' is a database query goal.   (`pl2sql:querybody/1')

          `ResultTerm' is a predicate containing a tuple.
          (`persdbrt_mysql:answertupleterm/1')

 -- PREDICATE: sql_query_one_tuple/3:
     *Usage:* `sql_query_one_tuple(+DBId, +SQLString, ResultTuple)'
        - _Description:_ `ResultTuple' contains an element from the
          set of tuples which represents the response in `DBId' to the SQL
          query `SQLString'. If the connection is kept, succesive
          calls return consecutive tuples, until the last tuple is
          reached. Then a null tuple is unified with `ResultTuple'
          and the connection is finished (calls to `mysql_disconnect/1').

        - _Call and exit should be _compatible_ with:_

          `+DBId' a unique identifier of a database session
          connection.   (`mysql_client:dbconnection/1')

          `+SQLString' is a string containing SQL code.
          (`pl2sql:sqlstring/1')

          `ResultTuple' is a tuple of values from the ODBC database
          interface.   (`persdbrt_mysql:tuple/1')

142.7 Known bugs and planned improvements (`persdbrt_mysql')
============================================================

   * At least in the shell, reloading a file after changing the
     definition of a persistent predicate does not eliminate the old
     definition...

   * Functionality missing: some questions need to be debugged.

   * Warning: still using kludgey string2term and still using some
     non-uniquified temp files.

   * Needs to be unified with the file-based library.

143 Prolog to SQL translator
****************************

*Author(s):* C. Draxler. Adapted by M. Hermenegildo and I. Caballero.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#112 (2003/11/27, 20:54:19 CET)

   This library performs translation of Prolog queries into SQL. The
code is an adaptation for Ciao of the Prolog to SQL compiler written
by Christoph Draxler, CIS Centre for Information and Speech
Processing, Ludwig-Maximilians-University Munich,
`draxler@cis.uni-muenchen.de', Version 1.1. Many thanks to Christoph
for allowing us to include this adaptation of his code with Ciao.

   The translator needs to know the correspondence between Prolog
predicates and the SQL tables in the database. To this end this
module exports two multifile predicates, `sql__relation/3' and `sql__attribute/4'.
See the description of these predicates for details on how such
correspondance is specified.

   The main entry points to the translator are `pl2sqlstring/3' and `pl2sqlterm/3'.
Details on the types of queries allowed can be found in the
description of these predicates.

   *Example:* the following program would print out a term
representing the SQL query corresponding to the given Prolog query:

   *Note:* while the translator can be used directly in programs, it
is more convenient to use a higher-level abstraction: persistent
predicates (implemented in the `persdb' library). The notion of
persistent predicates provides a completely transparent interface
between Prolog and relational databases. When using this library, the
Prolog to SQL translation is called automatically as needed.

143.1 Usage and interface (`pl2sql')
====================================

   * *Library usage:*

     `:- use_module(library(pl2sql)).'

   * *Exports:*
        - _Predicates:_

          `pl2sqlstring/3', `pl2sqlterm/3', `sqlterm2string/2'.

        - _Regular Types:_

          `querybody/1', `projterm/1', `sqlstring/1'.

        - _Multifiles:_

          `sql__relation/3', `sql__attribute/4'.

   * *Other modules used:*
        - _System library modules:_

          `persdb_sql_common/sqltypes', `iso_misc', `lists', `aggregates', `messages'.

143.2 Documentation on exports (`pl2sql')
=========================================

 -- PREDICATE: pl2sqlstring/3:
     *Usage:* `pl2sqlstring(+ProjectionTerm, +DatabaseGoal,
     -SQLQueryString)'
        - _Description:_ This is the top level predicate which
          translates complex Prolog goals into the corresponding SQL
          code.

          The query code is prepared in such a way that the result is
          projected onto the term `ProjectionTerm' (also in a similar
          way to the first argument of `setof/3')). See the predicate `translate_projection/3'
          for restrictions on this term.

          `SQLQueryString' contains the code of the SQL query, ready
          to be sent to an SQL server.

        - _Call and exit should be _compatible_ with:_

          `+ProjectionTerm' is a database projection term.
          (`pl2sql:projterm/1')

          `+DatabaseGoal' is a database query goal.
          (`pl2sql:querybody/1')

          `-SQLQueryString' is a string containing SQL code.
          (`pl2sql:sqlstring/1')

 -- REGTYPE: querybody/1:
     `DBGoal' is a goal meant to be executed in the external
     database. It can be a complex term containing conjunctions, disjunctions,
     and negations, of:

        * Atomic goals, which must have been defined via `sql__relation/3'
          and `sql__attribute/4' and reside in the (same) database.
          Their arguments must be either ground or free variables. If
          they are ground, they must be bound to constants of the
          type declared for that argument. If an argument is a free
          variable, it may _share_ with (i.e., be the same variable
          as) other free variables in other goal arguments.

        * Database comparison goals, whose main functor must be a database
          comparison operator (see `pl2sql': `comparison/2') and
          whose arguments must be _database arithmetic expressions_.

        * Database calls to is/2. The left side of such a call may be
          either unbound, in which case it is bound to the result of
          evaluating the right side, or bound in which case an
          equality condition is tested. The right side must be a
          _database arithmetic expression_.

     The binding of variables follows Prolog rules:

        * variables are bound by positive base goals and on the left
          side of the `is/2' predicate.

        * Comparison operations, negated goals, and right sides of the `is/2'
          predicate do not return variable bindings and may even
          require all arguments to be bound for a safe evaluation.

     Database arithmetic expressions may contain:

        * Numeric constants (i.e., integers, reals, etc.).

        * Bound variables, i.e., variables which will be bound during
          execution through occurrence within a positive database
          goal, or by a preceding arithmetic function.

        * Database arithmetic functions, which are a subset of those
          typically accepted within `is/2' (see `pl2sql': `arithmetic_functor/2').

        * Database aggregation functions, each of which has two
          arguments: a variable indicating the argument over which
          the function is to be computed, and a goal argument which
          must contain in at least one argument position the variable
          (e.g. `avg(Seats, plane(Type, Seats))'). The goal argument
          may only be a conjunction of (positive or negative) base
          goals. See `pl2sql': `aggregate_functor/2' for the
          admissible aggregate functions.

     In addition, variables can be existentially quantified using `^/2'
     (in a similar way to how it is done in `setof/3').

     Note that it is assumed that the arithmetic operators in Prolog
     and SQL are the same, i.e., `+' is addition in Prolog and in
     SQL, etc.

     *Usage:* `querybody(DBGoal)'
        - _Description:_ `DBGoal' is a database query goal.

 -- REGTYPE: projterm/1:
     `DBProjTerm' is a term onto which the result of a database query
     code is (in a similar way to the first argument of `setof/3')).

     A `ProjectionTerm' must meet the following restrictions:

        * The functor of `ProjectionTerm' may not be one of the
          built-in predicates, i.e. ',', ';', etc. are not allowed.

        * Only variables and constants are allowed as arguments,
          i.e., no structured terms may appear.

     *Usage:* `projterm(DBProjTerm)'
        - _Description:_ `DBProjTerm' is a database projection term.

 -- REGTYPE: sqlstring/1:
          sqlstring(S) :-
                  string(S).

     *Usage:* `sqlstring(S)'
        - _Description:_ `S' is a string containing SQL code.

 -- PREDICATE: pl2sqlterm/3:
     *Usage:* `pl2sqlterm(+ProjectionTerm, +DatabaseGoal,
     -SQLQueryTerm)'
        - _Description:_ Similar to `pl2sqlstring/3' except that
          `SQLQueryTerm' is a representation of the SQL query as a
          Prolog term.

        - _Call and exit should be _compatible_ with:_

          `+ProjectionTerm' is a database projection term.
          (`pl2sql:projterm/1')

          `+DatabaseGoal' is a database query goal.
          (`pl2sql:querybody/1')

          `-SQLQueryTerm' is a list of `sqlterm's.
          (`basic_props:list/2')

 -- PREDICATE: sqlterm2string/2:
     *Usage:* `sqlterm2string(+Queries, -QueryString)'
        - _Description:_ `QueryString' is a string representation of
          the list of queries in Prolog-term format in `Queries'.

        - _Call and exit should be _compatible_ with:_

          `+Queries' is a list of `sqlterm's.   (`basic_props:list/2')

          `-QueryString' is a string containing SQL code.
          (`pl2sql:sqlstring/1')

 -- (: UNDOC_REEXPORT) sqltype/1:
     Imported from `sqltypes' (see the corresponding documentation
     for details).

143.3 Documentation on multifiles (`pl2sql')
============================================

 -- PREDICATE: sql__relation/3:
     The predicate is _multifile_.

     The predicate is of type _data_.

     *Usage:* `sql__relation(PredName, Arity, TableName)'
        - _Description:_ This predicate, together with `sql__attribute/4',
          defines the correspondence between Prolog predicates and the SQL
          tables in the database. These two relations constitute an
          extensible meta-database which maps Prolog predicate names
          to SQL table names, and Prolog predicate argument positions
          to SQL attributes.

          `PredName' is the chosen Prolog name for an SQL table.
          `Arity' is the number of arguments of the predicate.
          `TableName' is the name of the SQL table in the Database
          Management System.

        - _Call and exit should be _compatible_ with:_

          `PredName' is an atom.   (`basic_props:atm/1')

          `Arity' is an integer.   (`basic_props:int/1')

          `TableName' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: sql__attribute/4:
     The predicate is _multifile_.

     The predicate is of type _data_.

     *Usage:* `sql__attribute(ANumber, TblName, AName, AType)'
        - _Description:_ This predicate maps the argument positions
          of a Prolog predicate to the SQL attributes of its
          corresponding table. The types of the arguments need to be
          specified, and this information is used for consistency
          checking during the translation and for output formatting.
          A minimal type system is provided to this end. The
          allowable types are given by `sqltype/1'.

          `ANumber' is the argument number in the Prolog relation.
          `TblName' is the name of the SQL table in the Database
          Management System. `AName' is the name of the corresponding
          attribute in the table. `AType' is the (translator) data
          type of the attribute.

        - _Call and exit should be _compatible_ with:_

          `ANumber' is an integer.   (`basic_props:int/1')

          `TblName' is an atom.   (`basic_props:atm/1')

          `AName' is an atom.   (`basic_props:atm/1')

          `AType' is an SQL data type supported by the translator.
          (`sqltypes:sqltype/1')

143.4 Documentation on internals (`pl2sql')
===========================================

 -- PREDICATE: query_generation/3:
     *Usage:* `query_generation(+ListOfConjunctions, +ProjectionTerm,
     -ListOfQueries)'
        - _Description:_ For each Conjunction in
          `ListOfConjunctions', translate the pair `(ProjectionTerm,
          Conjunction)' to an SQL query and connect each such query
          through a UNION-operator to result in the `ListOfQueries'.

          A Conjunction consists of positive or negative subgoals.
          Each subgoal is translated as follows:

             * the functor of a goal that is not a comparison
               operation is translated to a relation name with a range
               variable,

             * negated goals are translated to NOT EXISTS-subqueries
               with * projection,

             * comparison operations are translated to comparison
               operations in the WHERE-clause,

             * aggregate function terms are translated to aggregate
               function (sub)queries.

          The arguments of a goal are translated as follows:

             * `variables of a goal' are translated to qualified
               attributes,

             * variables occurring in several goals are translated to
               equality comparisons (equi join) in the WHERE-clause,

             * constant arguments are translated to equality
               comparisons in the WHERE-clause.

          Arithmetic functions are treated specially ( `translate_arithmetic_function/5').
          See also `querybody/1' for details on the syntax accepted
          and restrictions.

 -- PREDICATE: translate_conjunction/5:
     *Usage:* `translate_conjunction(Conjunction, SQLFrom, SQLWhere,
     Dict, NewDict)'
        - _Description:_ Translates a conjunction of goals
          (represented as a list of goals preceeded by existentially
          quantified variables) to FROM-clauses and WHERE-clauses of
          an SQL query. A dictionary containing the associated SQL
          table and attribute names is built up as an accumulator
          pair (arguments `Dict' and `NewDict').

 -- PREDICATE: translate_goal/5:
     *Usage:* `translate_goal(Goal, SQLFrom, SQLWhere, Dict, NewDict)'
        - _Description:_ Translates:

             * a positive database goal to the associated FROM- and
               WHERE clause of an SQL query,

             * a negated database goal to a negated existential
               subquery,

             * an arithmetic goal to an arithmetic expression or an
               aggregate function query,

             * a comparison goal to a comparison expression, and

             * a negated comparison goal to a comparison expression
               with the opposite comparison operator.

 -- PREDICATE: translate_arithmetic_function/5:
     *Usage:* `translate_arithmetic_function(Result, Expression,
     SQLWhere, Dict, NewDict)'
        - _Description:_ Arithmetic functions (left side of is/2
          operator is bound to value of expression on right side) may
          be called with either:

             * `Result' unbound: then `Result' is bound to the value
               of the evaluation of `Expression',

             * `Result' bound: then an equality condition is returned
               between the value of `Result' and the value of the
               evaluation of `Expression'.

               Only the equality test shows up in the WHERE clause of
               an SQLquery.

 -- PREDICATE: translate_comparison/5:
     *Usage:* `translate_comparison(LeftArg, RightArg, CompOp, Dict,
     SQLComparison)'
        - _Description:_ Translates the left and right arguments of a
          comparison term into the appropriate comparison operation
          in SQL. The result type of each argument expression is
          checked for type compatibility.

 -- PREDICATE: aggregate_function/3:
     *Usage:* `aggregate_function(AggregateFunctionTerm, Dict,
     AggregateFunctionQuery)'
        - _Description:_ Supports the Prolog aggregate function terms
          listed in `aggregate_functor/2' within arithmetic
          expressions. Aggregate functions are translated to the
          corresponding SQL built-in aggregate functions.

 -- PREDICATE: comparison/2:
     *Usage:* `comparison(PrologOperator, SQLOperator)'
        - _Description:_ Defines the mapping between Prolog operators
          and SQL operators:
               comparison(=,=).
               comparison(<,<).
               comparison(>,>).
               comparison(@<,<).
               comparison(@>,>).

        - _Call and exit should be _compatible_ with:_

          `PrologOperator' is an atom.   (`basic_props:atm/1')

          `SQLOperator' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: negated_comparison/2:
     *Usage:* `negated_comparison(PrologOperator, SQLOperator)'
        - _Description:_ Defines the mapping between Prolog operators
          and the complementary SQL operators:
               negated_comparison(=,<>).
               negated_comparison(\==,=).
               negated_comparison(>,=<).
               negated_comparison(=<,>).
               negated_comparison(<,>=).
               negated_comparison(>=,<).

        - _Call and exit should be _compatible_ with:_

          `PrologOperator' is an atom.   (`basic_props:atm/1')

          `SQLOperator' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: arithmetic_functor/2:
     *Usage:* `arithmetic_functor(PrologFunctor, SQLFunction)'
        - _Description:_ Defines the admissible arithmetic functions
          on the Prolog side and their correspondence on the SQL side:
               arithmetic_functor(+,+).
               arithmetic_functor(-,-).
               arithmetic_functor(*,*).
               arithmetic_functor(/,/).

        - _Call and exit should be _compatible_ with:_

          `PrologFunctor' is an atom.   (`basic_props:atm/1')

          `SQLFunction' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: aggregate_functor/2:
     *Usage:* `aggregate_functor(PrologFunctor, SQLFunction)'
        - _Description:_ Defines the admissible aggregate functions
          on the Prolog side and their correspondence on the SQL side:
               aggregate_functor(avg,'AVG').
               aggregate_functor(min,'MIN').
               aggregate_functor(max,'MAX').
               aggregate_functor(sum,'SUM').
               aggregate_functor(count,'COUNT').

        - _Call and exit should be _compatible_ with:_

          `PrologFunctor' is an atom.   (`basic_props:atm/1')

          `SQLFunction' is an atom.   (`basic_props:atm/1')

143.5 Known bugs and planned improvements (`pl2sql')
====================================================

   * Need to separate db predicate names by module.

144 Low-level socket interface to SQL/ODBC databases
****************************************************

*Author(s):* Jose Morales.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.11#155 (2004/1/7, 20:9:58 CET)

   This library provides a low-level interface to MySQL using the
MySQL C API and the Ciao foreign interface to C.

144.1 Usage and interface (`mysql_client')
==========================================

   * *Library usage:*

     `:- use_module(library(mysql_client)).'

   * *Exports:*
        - _Predicates:_

          `mysql_connect/5', `mysql_query/3', `mysql_query_one_tuple/3', `mysql_free_query_connection/1', `mysql_fetch/2', `mysql_get_tables/2', `mysql_table_types/3', `mysql_disconnect/1'.

        - _Regular Types:_

          `dbconnection/1', `dbqueryconnection/1'.

   * *Other modules used:*
        - _System library modules:_

          `foreign_interface/foreign_interface_properties', `persdb_mysql/db_client_types'.

144.2 Documentation on exports (`mysql_client')
===============================================

 -- PREDICATE: mysql_connect/5:
     No further documentation available for this predicate.

 -- REGTYPE: dbconnection/1:
          dbconnection(_1) :-
                  address(_1).

     *Usage:* `dbconnection(H)'
        - _Description:_ `H' a unique identifier of a database
          session connection.

 -- PREDICATE: mysql_query/3:
     No further documentation available for this predicate.

 -- PREDICATE: mysql_query_one_tuple/3:
     No further documentation available for this predicate.

 -- REGTYPE: dbqueryconnection/1:
          dbqueryconnection(_1) :-
                  address(_1).

     *Usage:* `dbqueryconnection(H)'
        - _Description:_ `H' is a unique identifier of a query answer
          in a database session connection.

 -- PREDICATE: mysql_free_query_connection/1:
     No further documentation available for this predicate.

 -- PREDICATE: mysql_fetch/2:
     No further documentation available for this predicate.

 -- PREDICATE: mysql_get_tables/2:
     No further documentation available for this predicate.

 -- PREDICATE: mysql_table_types/3:
     No further documentation available for this predicate.

 -- PREDICATE: mysql_disconnect/1:
     No further documentation available for this predicate.

145 Types for the Low-level interface to SQL databases
******************************************************

*Author(s):* D. Cabeza, M. Carro, I. Caballero, and M. Hermenegildo..

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#233 (2003/12/22, 18:8:26 CET)

   This module implement the types for the low level interface to SQL
databases

145.1 Usage and interface (`db_client_types')
=============================================

   * *Library usage:*

     `:- use_module(library(db_client_types)).'

   * *Exports:*
        - _Regular Types:_

          `socketname/1', `dbname/1', `user/1', `passwd/1', `answertableterm/1', `tuple/1', `answertupleterm/1', `sqlstring/1'.

145.2 Documentation on exports (`db_client_types')
==================================================

 -- REGTYPE: socketname/1:
          socketname(IPAddress:PortNumber) :-
                  atm(IPAddress),
                  int(PortNumber).

     *Usage:* `socketname(IPP)'
        - _Description:_ `IPP' is a structure describing a complete
          TCP/IP port address.

 -- REGTYPE: dbname/1:
          dbname(DBId) :-
                  atm(DBId).

     *Usage:* `dbname(DBId)'
        - _Description:_ `DBId' is the identifier of an database.

 -- REGTYPE: user/1:
          user(User) :-
                  atm(User).

     *Usage:* `user(User)'
        - _Description:_ `User' is a user name in the database.

 -- REGTYPE: passwd/1:
          passwd(Passwd) :-
                  atm(Passwd).

     *Usage:* `passwd(Passwd)'
        - _Description:_ `Passwd' is the password for the user name
          in the database.

 -- REGTYPE: answertableterm/1:
     Represents the types of responses that will be returned from the
     database interface. These can be a set of answer tuples, or the
     atom `ok' in case of a successful addition or deletion.

     *Usage:* `answertableterm(AT)'
        - _Description:_ `AT' is a response from the database
          interface.

 -- REGTYPE: tuple/1:
          tuple(T) :-
                  list(T,atm).

     *Usage:* `tuple(T)'
        - _Description:_ `T' is a tuple of values from the database
          interface.

 -- REGTYPE: answertupleterm/1:
          answertupleterm([]).
          answertupleterm(tup(T)) :-
                  tuple(T).

     *Usage:* `answertupleterm(X)'
        - _Description:_ `X' is a predicate containing a tuple.

 -- REGTYPE: sqlstring/1:
          sqlstring(S) :-
                  string(S).

     *Usage:* `sqlstring(S)'
        - _Description:_ `S' is a string of SQL code.

146 sqltypes (library)
**********************

*Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.7#127 (2001/10/26, 14:52:5 CEST)

146.1 Usage and interface (`sqltypes')
======================================

   * *Library usage:*

     `:- use_module(library(sqltypes)).'

   * *Exports:*
        - _Predicates:_

          `accepted_type/2', `get_type/2', `type_compatible/2', `type_union/3', `sybase2sqltypes_list/2', `sybase2sqltype/2', `postgres2sqltypes_list/2', `postgres2sqltype/2'.

        - _Regular Types:_

          `sqltype/1', `sybasetype/1', `postgrestype/1'.

146.2 Documentation on exports (`sqltypes')
===========================================

 -- REGTYPE: sqltype/1:
          sqltype(int).
          sqltype(flt).
          sqltype(num).
          sqltype(string).
          sqltype(date).
          sqltype(time).
          sqltype(datetime).

     These types have the same meaning as the corresponding standard
     types in the `basictypes' library.

     *Usage:* `sqltype(Type)'
        - _Description:_ `Type' is an SQL data type supported by the
          translator.

 -- PREDICATE: accepted_type/2:
     *Usage:* `accepted_type(SystemType, NativeType)'
        - _Description:_ For the moment, tests wether the
          `SystemType' received is a sybase or a postgres type (in
          the future other systems should be supported) and obtains
          its equivalent `NativeType' sqltype.

        - _Call and exit should be _compatible_ with:_

          `SystemType' is an SQL data type supported by Sybase.
          (`sqltypes:sybasetype/1')

          `NativeType' is an SQL data type supported by the
          translator.   (`sqltypes:sqltype/1')

 -- PREDICATE: get_type/2:
     *Usage:* `get_type(+Constant, Type)'
        - _Description:_ Prolog implementation-specific definition of
          type retrievals. CIAO Prolog version given here (ISO).

        - _Call and exit should be _compatible_ with:_

          `+Constant' is any term.   (`basic_props:term/1')

          `Type' is an SQL data type supported by the translator.
          (`sqltypes:sqltype/1')

 -- PREDICATE: type_compatible/2:
     *Usage:* `type_compatible(TypeA, TypeB)'
        - _Description:_ Checks if `TypeA' and `TypeB' are compatible
          types, i.e., they are the same or one is a subtype of the
          other.

        - _Call and exit should be _compatible_ with:_

          `TypeA' is an SQL data type supported by the translator.
          (`sqltypes:sqltype/1')

          `TypeB' is an SQL data type supported by the translator.
          (`sqltypes:sqltype/1')

 -- PREDICATE: type_union/3:
     *Usage:* `type_union(TypeA, TypeB, Union)'
        - _Description:_ `Union' is the union type of `TypeA' and
          `TypeB'.

        - _Call and exit should be _compatible_ with:_

          `TypeA' is an SQL data type supported by the translator.
          (`sqltypes:sqltype/1')

          `TypeB' is an SQL data type supported by the translator.
          (`sqltypes:sqltype/1')

          `Union' is an SQL data type supported by the translator.
          (`sqltypes:sqltype/1')

 -- REGTYPE: sybasetype/1:
     SQL datatypes supported by Sybase for which a translation is
     defined:

          sybasetype(integer).
          sybasetype(numeric).
          sybasetype(float).
          sybasetype(double).
          sybasetype(date).
          sybasetype(char).
          sybasetype(varchar).
          sybasetype('long varchar').
          sybasetype(binary).
          sybasetype('long binary').
          sybasetype(timestamp).
          sybasetype(time).
          sybasetype(tinyint).

     *Usage:* `sybasetype(Type)'
        - _Description:_ `Type' is an SQL data type supported by
          Sybase.

 -- PREDICATE: sybase2sqltypes_list/2:
     *Usage:* `sybase2sqltypes_list(SybaseTypesList, SQLTypesList)'
        - _Description:_  `SybaseTypesList' is a list of Sybase SQL
          types. `PrologTypesList' contains their equivalent SQL-type
          names in CIAO.

        - _The following properties should hold upon exit:_

          `SybaseTypesList' is a list.   (`basic_props:list/1')

          `SQLTypesList' is a list.   (`basic_props:list/1')

 -- PREDICATE: sybase2sqltype/2:
     *Usage:* `sybase2sqltype(SybaseType, SQLType)'
        - _Description:_  `SybaseType' is a Sybase SQL type name, and
          `SQLType' is its equivalent SQL-type name in CIAO.

        - _The following properties should hold upon exit:_

          `SybaseType' is an SQL data type supported by Sybase.
          (`sqltypes:sybasetype/1')

          `SQLType' is an SQL data type supported by the translator.
          (`sqltypes:sqltype/1')

 -- REGTYPE: postgrestype/1:
     SQL datatypes supported by postgreSQL for which a translation is
     defined:

          postgrestype(int2).
          postgrestype(int4).
          postgrestype(int8).
          postgrestype(float4).
          postgrestype(float8).
          postgrestype(date).
          postgrestype(timestamp).
          postgrestype(time).
          postgrestype(char).
          postgrestype(varchar).
          postgrestype(text).
          postgrestype(bool).

     *Usage:* `postgrestype(Type)'
        - _Description:_ `Type' is an SQL data type supported by
          postgres.

 -- PREDICATE: postgres2sqltypes_list/2:
     *Usage:* `postgres2sqltypes_list(PostgresTypesList,
     SQLTypesList)'
        - _Description:_  `PostgresTypesList' is a list of postgres
          SQL types. `PrologTypesList' contains their equivalent
          SQL-type names in CIAO.

        - _The following properties should hold upon exit:_

          `PostgresTypesList' is a list.   (`basic_props:list/1')

          `SQLTypesList' is a list.   (`basic_props:list/1')

 -- PREDICATE: postgres2sqltype/2:
     *Usage:* `postgres2sqltype(PostgresType, SQLType)'
        - _Description:_  `PostgresType' is a postgres SQL type name,
          and `SQLType' is its equivalent SQL-type name in CIAO.

        - _The following properties should hold upon exit:_

          `PostgresType' is an SQL data type supported by postgres.
          (`sqltypes:postgrestype/1')

          `SQLType' is an SQL data type supported by the translator.
          (`sqltypes:sqltype/1')

147 persdbtr_sql (library)
**************************

*Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#42 (2002/12/13, 17:55:42 CET)

147.1 Usage and interface (`persdbtr_sql')
==========================================

   * *Library usage:*

     `:- use_module(library(persdbtr_sql)).'

   * *Exports:*
        - _Predicates:_

          `sql_persistent_tr/2', `dbId/2'.

   * *Other modules used:*
        - _System library modules:_

          `dynamic'.

147.2 Documentation on exports (`persdbtr_sql')
===============================================

 -- PREDICATE: sql_persistent_tr/2:
     No further documentation available for this predicate.

 -- PREDICATE: dbId/2:
     No further documentation available for this predicate.

     The predicate is of type _data_.

148 pl2sqlinsert (library)
**************************

*Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#345 (2004/5/4, 15:31:0 CEST)

148.1 Usage and interface (`pl2sqlinsert')
==========================================

   * *Library usage:*

     `:- use_module(library(pl2sqlinsert)).'

   * *Exports:*
        - _Predicates:_

          `pl2sqlInsert/2'.

        - _Multifiles:_

          `sql__relation/3', `sql__attribute/4'.

   * *Other modules used:*
        - _System library modules:_

          `operators', `default_predicates', `lists'.

148.2 Documentation on exports (`pl2sqlinsert')
===============================================

 -- PREDICATE: pl2sqlInsert/2:
     No further documentation available for this predicate.

148.3 Documentation on multifiles (`pl2sqlinsert')
==================================================

 -- PREDICATE: sql__relation/3:
     No further documentation available for this predicate.

     The predicate is _multifile_.

     The predicate is of type _data_.

 -- PREDICATE: sql__attribute/4:
     No further documentation available for this predicate.

     The predicate is _multifile_.

     The predicate is of type _data_.

149 Prolog to Java interface
****************************

*Author(s):* Jesu's Correas.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#67 (2003/3/14, 12:48:36 CET)

   This module defines the Ciao Prolog to Java interface. This
interface allows a Prolog program to start a Java process, create
Java objects, invoke methods, set/get attributes (fields), and handle
Java events.

   This interface only works with JDK version 1.2 or higher.

   Although the Java side interface is explained in Javadoc format
(it is available at `library/javall/javadoc/' in your Ciao
installation), the general interface structure is detailed here.

149.1 Prolog to Java Interface Structure
========================================

This interface is made up of two parts: a Prolog side and a Java
side, running in separate processes. The Prolog side receives
requests from a Prolog program and sends them to the Java side
through a socket. The Java side receives requests from the socket and
performs the actions included in the requests.

   If an event is thrown in the Java side, an asynchronous message
must be sent away to the Prolog side, in order to launch a Prolog
goal to handle the event. This asynchronous communication is
performed using a separate socket. The nature of this communication
needs the use of threads both in Java and Prolog: to deal with the
'sequential program flow,' and other threads for event handling.

   In both sides the threads are automatically created by the context
of the objects we use. The user must be aware that different requests
to the other side of the interface could run concurrently.

149.1.1 Prolog side of the Java interface
-----------------------------------------

The Prolog side receives the actions to do in the Java side from the
user program, and sends them to the Java process through the socket
connection. When the action is done in the Java side, the result is
returned to the user Prolog program, or the action fails if there is
any problem in the Java side.

   Prolog data representation of Java elements is very simple in this
interface. Java primitive types such as integers and characters are
translated into the Prolog corresponding terms, and even some Java
objects are translated in the same way (e. g. Java strings). Java
objects are represented in Prolog as compound terms with a reference
id to identify the corresponding Java object. Data conversion is made
automatically when the interface is used, so the Prolog user programs
do not have to deal with the complexity of this tasks.

149.1.2 Java side
-----------------

The Java side of this layer is more complex than the Prolog side. The
tasks this part has to deal to are the following:

   * Wait for requests from the Prolog side.

   * Translate the Prolog terms received in the Prolog 'serialized'
     form to a more useful Java representation (see the Java
     interface documentation available at `library/javall/javadoc/'
     in your Ciao installation for details regarding Java
     representation of Prolog terms).

   * Interpret the requests received from the Prolog side, and
     execute them.

   * Handle the set of objects created by or derived from the
     requests received from de prolog side.

   * Handle the events raised in the Java side, and launch the
     listeners added in the prolog side.

   * Handle the exceptions raised in the Java side, and send them to
     the Prolog side.

   In the implementation of the Java side, two items must be
carefully designed: the handling of Java objects, and the
representation of prolog data structures. The last item is specially
important because all the interactions between Prolog and Java are
made using Prolog structures, an easy way to standardize the
different data management in both sides. Even the requests themselves
are encapsulated using Prolog structures. The overload of this
encapsulation is not significant in terms of socket traffic, due to
the optimal implementation of the prolog serialized term.

   The java side must handle the objects created from the Prolog side
dinamically, and these objects must be accessed as fast as possible
from the set of objects. The Java API provides a powerful
implementation of Hash tables that achieves all the requirements of
our implementation.

   On the other hand, the java representation of prolog terms is made
using the inheritance of java classes. In the java side exists a
representation of a generic prolog term, implemented as an abstract
class in java. Variables, atoms, compound terms, lists, and numeric
terms are classes in the java side which inherit from the term class.
Java objects can be seen also under the prolog representation as
compound terms, where the single argument corresponds to the Hash key
of the actual java object in the Hash table referred to before. This
behaviour makes the handling of mixed java and prolog elements easy.
Prolog goals are represented in the java side as objects which
contain a prolog compound term with the term representing the goal.
This case will be seen more in depth next, when the java to prolog is
explained.

149.2 Java event handling from Prolog
=====================================

Java event handling is based on a delegation model since version
1.1.x. This approach to event handling is very powerful and elegant,
but a user program cannot handle all the events that can arise on a
given object: for each kind of event, a listener must be implemented
and added specifically. However, the Java 2 API includes a special
listener (`AWTEventListener') that can manage the internal java event
queue.

   The prolog to java interface has been designed to emulate the java
event handler, and is also based on event objects and listeners. The
prolog to java interface implements its own event manager, to handle
those events that have prolog listeners associated to the object that
raises the event. From the prolog side can be added listeners to
objects for specific events. The java side includes a list of goals
to launch from the object and event type.

   Due to the events nature, the event handler must work in a
separate thread to manage the events asynchronously. The java side
has its own mechanisms to work this way. The prolog side must be
implemented specially for event handling using threads. The
communication between java and prolog is also asynchronous, and an
additional socket stream is used to avoid interferences with the main
socket stream. The event stream will work in this implementation only
in one way: from java to prolog. If an event handler needs to send
back requests to java, it will use the main socket stream, just like
the requests sent directly from a prolog program.

   The internal process of register a Prolog event handler to a Java
event is shown in the next figure:

[Image file: autofigip2jbn-events-pl-reg.eps]

   When an event raises, the Prolog to Java interface has to send to
the Prolog user program the goal to evaluate. Graphically, the
complete process takes the tasks involved in the following figure:

[Image file: autofigip2jbn-events-pl-fire.eps]

149.3 Java exception handling from Prolog
=========================================

Java exception handling is very similar to the peer prolog handling:
it includes some specific statements to trap exceptions from user
code. In the java side, the exceptions can be originated from an
incorrect request, or can be originated in the code called from the
request. Both exception types will be sent to prolog using the main
socket stream, allowing the prolog program manage the exception.
However, the first kind of exceptions are prefixed, so the user
program can distinguish them from the second type of exceptions.

   In order to handle exceptions properly using the prolog to java
and java to prolog interfaces simultaneously, in both sides of the
interface will be filtered those exceptions coming from their own
side: this avoids an endless loop of exceptions bouncing from one
side to another.

149.4 Usage and interface (`javart')
====================================

   * *Library usage:*

     `:- use_module(library(javart)).'

   * *Exports:*
        - _Predicates:_

          `java_start/0', `java_start/1', `java_start/2', `java_stop/0', `java_connect/2', `java_disconnect/0', `java_use_module/1', `java_create_object/2', `java_delete_object/1', `java_invoke_method/2', `java_get_value/2', `java_set_value/2', `java_add_listener/3', `java_remove_listener/3'.

        - _Regular Types:_

          `machine_name/1', `java_constructor/1', `java_object/1', `java_event/1', `prolog_goal/1', `java_field/1', `java_method/1'.

   * *Other modules used:*
        - _System library modules:_

          `concurrency/concurrency', `iso_byte_char', `format', `lists', `read', `write', `javall/javasock', `system'.

149.5 Documentation on exports (`javart')
=========================================

 -- PREDICATE: java_start/0:
     *Usage:*
        - _Description:_ Starts the Java server on the local machine,
          connects to it, and starts the event handling thread.

 -- PREDICATE: java_start/1:
     *Usage:* `java_start(+Classpath)'
        - _Description:_ Starts the Java server on the local machine,
          connects to it, and starts the event handling thread. The
          Java server is started using the classpath received as
          argument.

        - _Call and exit should be _compatible_ with:_

          `+Classpath' is a string (a list of character codes).
          (`basic_props:string/1')

 -- PREDICATE: java_start/2:
     *Usage:* `java_start(+machine_name, +classpath)'
        - _Description:_ Starts the Java server in machine_name
          (using rsh!), connects to it, and starts the event handling
          thread. The Java server is started using the classpath
          received as argument.

        - _Call and exit should be _compatible_ with:_

          `+machine_name' is currently instantiated to an atom.
          (`term_typing:atom/1')

          `+classpath' is a string (a list of character codes).
          (`basic_props:string/1')

 -- PREDICATE: java_stop/0:
     *Usage:*
        - _Description:_ Stops the interface terminating the threads
          that handle the socket connection, and finishing the Java
          interface server if it was started using java_start/n.

 -- PREDICATE: java_connect/2:
     *Usage:* `java_connect(+machine_name, +port_number)'
        - _Description:_ Connects to an existing Java interface
          server running in machine_name and listening at port
          port_number. To connect to a Java server located in the
          local machine, use 'localhost' as machine_name.

        - _Call and exit should be _compatible_ with:_

          `+machine_name' is the network name of a machine.
          (`javart:machine_name/1')

          `+port_number' is an integer.   (`basic_props:int/1')

 -- PREDICATE: java_disconnect/0:
     *Usage:*
        - _Description:_ Closes the connection with the java process,
          terminating the threads that handle the connection to Java.
          This predicate does not terminate the Java process (this is
          the disconnection procedure for Java servers not started
          from Prolog). This predicate should be used when the
          communication is established with java_connect/2.

 -- REGTYPE: machine_name/1:
     *Usage:* `machine_name(X)'
        - _Description:_ `X' is the network name of a machine.

 -- REGTYPE: java_constructor/1:
     *Usage:* `java_constructor(X)'
        - _Description:_ `X' is a java constructor (structure with
          functor as constructor full name, and arguments as
          constructor arguments).

 -- REGTYPE: java_object/1:
     *Usage:* `java_object(X)'
        - _Description:_ `X' is a java object (a structure with
          functor '$java_object', and argument an integer given by
          the java side).

 -- REGTYPE: java_event/1:
     *Usage:* `java_event(X)'
        - _Description:_ `X' is a java event represented as an atom
          with the full event constructor name (e.g.,
          'java.awt.event.ActionListener').

 -- REGTYPE: prolog_goal/1:
     *Usage:* `prolog_goal(X)'
        - _Description:_ `X' is a prolog predicate. Prolog term that
          represents the goal that must be invoked when the event
          raises on the object. The predicate arguments can be java
          objects, or even the result of java methods. These java
          objects will be evaluated when the event raises (instead of
          when the listener is added). The arguments that represent
          java objects must be instantiated to already created
          objects. The variables will be kept uninstantiated when the
          event raises and the predicate is called.

 -- REGTYPE: java_field/1:
     *Usage:* `java_field(X)'
        - _Description:_ `X' is a java field (structure on which the
          functor name is the field name, and the single argument is
          the field value).

 -- PREDICATE: java_use_module/1:
     *Usage:* `java_use_module(+Module)'
        - _Description:_ Loads a module and makes it available from
          Java.

        - _Call and exit should be _compatible_ with:_

          `+Module' is any term.   (`basic_props:term/1')

 -- PREDICATE: java_create_object/2:
     *Usage:* `java_create_object(+java_constructor, -java_object)'
        - _Description:_ New java object creation. The constructor
          must be a compound term as defined by its type, with the
          full class name as functor (e.g., 'java.lang.String'), and
          the parameters passed to the constructor as arguments of
          the structure.

        - _Call and exit should be _compatible_ with:_

          `+java_constructor' is a java constructor (structure with
          functor as constructor full name, and arguments as
          constructor arguments).   (`javart:java_constructor/1')

          `-java_object' is a java object (a structure with functor
          '$java_object', and argument an integer given by the java
          side).   (`javart:java_object/1')

 -- PREDICATE: java_delete_object/1:
     *Usage:* `java_delete_object(+java_object)'
        - _Description:_ Java object deletion. It removes the object
          given as argument from the Java object table.

        - _Call and exit should be _compatible_ with:_

          `+java_object' is a java object (a structure with functor
          '$java_object', and argument an integer given by the java
          side).   (`javart:java_object/1')

 -- PREDICATE: java_invoke_method/2:
     *Usage:* `java_invoke_method(+java_object, +java_method)'
        - _Description:_ Invokes a java method on an object. Given a
          Java object reference, invokes the method represented with
          the second argument.

        - _Call and exit should be _compatible_ with:_

          `+java_object' is a java object (a structure with functor
          '$java_object', and argument an integer given by the java
          side).   (`javart:java_object/1')

          `+java_method' is a java method (structure with functor as
          method name, and arguments as method ones, plus a result
          argument. This result argument is unified with the atom
          'Yes' if the java method returns void).
          (`javart:java_method/1')

 -- REGTYPE: java_method/1:
     *Usage:* `java_method(X)'
        - _Description:_ `X' is a java method (structure with functor
          as method name, and arguments as method ones, plus a result
          argument. This result argument is unified with the atom
          'Yes' if the java method returns void).

 -- PREDICATE: java_get_value/2:
     *Usage:* `java_get_value(+java_object, +java_field)'
        - _Description:_ Gets the value of a field. Given a Java
          object as first argument, it instantiates the variable
          given as second argument. This field must be uninstantiated
          in the java_field functor, or this predicate will fail.

        - _Call and exit should be _compatible_ with:_

          `+java_object' is a java object (a structure with functor
          '$java_object', and argument an integer given by the java
          side).   (`javart:java_object/1')

          `+java_field' is a java field (structure on which the
          functor name is the field name, and the single argument is
          the field value).   (`javart:java_field/1')

 -- PREDICATE: java_set_value/2:
     *Usage:* `java_set_value(+java_object, +java_field)'
        - _Description:_ Sets the value of a Java object field. Given
          a Java object reference, it assigns the value included in
          the java_field compound term. The field value in the
          java_field structure must be instantiated.

        - _Call and exit should be _compatible_ with:_

          `+java_object' is a java object (a structure with functor
          '$java_object', and argument an integer given by the java
          side).   (`javart:java_object/1')

          `+java_field' is a java field (structure on which the
          functor name is the field name, and the single argument is
          the field value).   (`javart:java_field/1')

 -- PREDICATE: java_add_listener/3:
     _Meta-predicate_ with arguments: `java_add_listener(?,?,goal)'.

     *Usage:* `java_add_listener(+java_object, +java_event,
     +prolog_goal)'
        - _Description:_ Adds a listener to an event on an object.
          Given a Java object reference, it registers the goal
          received as third argument to be launched when the Java
          event raises.

        - _Call and exit should be _compatible_ with:_

          `+java_object' is a java object (a structure with functor
          '$java_object', and argument an integer given by the java
          side).   (`javart:java_object/1')

          `+java_event' is a java event represented as an atom with
          the full event constructor name (e.g.,
          'java.awt.event.ActionListener').   (`javart:java_event/1')

          `+prolog_goal' is a prolog predicate. Prolog term that
          represents the goal that must be invoked when the event
          raises on the object. The predicate arguments can be java
          objects, or even the result of java methods. These java
          objects will be evaluated when the event raises (instead of
          when the listener is added). The arguments that represent
          java objects must be instantiated to already created
          objects. The variables will be kept uninstantiated when the
          event raises and the predicate is called.
          (`javart:prolog_goal/1')

 -- PREDICATE: java_remove_listener/3:
     *Usage:* `java_remove_listener(+java_object, +java_event,
     +prolog_goal)'
        - _Description:_ It removes a listener from an object event
          queue. Given a Java object reference, goal registered for
          the given event is removed.

        - _Call and exit should be _compatible_ with:_

          `+java_object' is a java object (a structure with functor
          '$java_object', and argument an integer given by the java
          side).   (`javart:java_object/1')

          `+java_event' is a java event represented as an atom with
          the full event constructor name (e.g.,
          'java.awt.event.ActionListener').   (`javart:java_event/1')

          `+prolog_goal' is a prolog predicate. Prolog term that
          represents the goal that must be invoked when the event
          raises on the object. The predicate arguments can be java
          objects, or even the result of java methods. These java
          objects will be evaluated when the event raises (instead of
          when the listener is added). The arguments that represent
          java objects must be instantiated to already created
          objects. The variables will be kept uninstantiated when the
          event raises and the predicate is called.
          (`javart:prolog_goal/1')

150 Java to Prolog interface
****************************

*Author(s):* Jesu's Correas.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#65 (2003/3/14, 12:48:10 CET)

   This module defines the Prolog side of the Java to Prolog
interface. This side of the interface only has one public predicate:
a server that listens at the socket connection with Java, and
executes the commands received from the Java side.

   In order to evaluate the goals received from the Java side, this
module can work in two ways: executing them in the same engine, or
starting a thread for each goal. The easiest way is to launch them in
the same engine, but the goals must be evaluated sequentially: once a
goal provides the first solution, all the subsequent goals must be
finished before this goal can backtrack to provide another solution.
The Prolog side of this interface works as a top-level, and the goals
partially evaluated are not independent.

   The solution of this goal dependence is to evaluate the goals in a
different prolog engine. Although Ciao includes a mechanism to
evaluate goals in different engines, the approach used in this
interface is to launch each goal in a different thread.

   The decision of what kind of goal evaluation is selected is done
by the Java side. Each evaluation type has its own command terms, so
the Java side can choose the type it needs.

   A Prolog server starts by calling the `prolog_server/0' predicate,
or by calling `prolog_server/1' predicate and providing the port
number as argument. The user predicates and libraries to be called
from Java must be included in the executable file, or be accesible
using the built-in predicates dealing with code loading.

150.1 Usage and interface (`jtopl')
===================================

   * *Library usage:*

     `:- use_module(library(jtopl)).'

   * *Exports:*
        - _Predicates:_

          `prolog_server/0', `prolog_server/1', `prolog_server/2', `shell_s/0', `query_solutions/2', `query_requests/2', `running_queries/2'.

   * *Other modules used:*
        - _System library modules:_

          `concurrency/concurrency', `system', `read', `write', `dynamic', `lists', `format', `compiler/compiler', `atom2term', `javall/javasock', `prolog_sys'.

150.2 Documentation on exports (`jtopl')
========================================

 -- PREDICATE: prolog_server/0:
     *Usage:*
        - _Description:_ Prolog server entry point. Reads from the
          standard input the node name and port number where the java
          client resides, and starts the prolog server listening at
          the jp socket. This predicate acts as a server: it includes
          an endless read-process loop until the `prolog_halt'
          command is received.

          However, from the low-level communication point of view,
          this Prolog server actually works as a client of the Java
          side. This means that Java side waits at the given port to
          a Prolog server trying to create a socket; Prolog side
          connects to that port, and then waits for Java requests
          (acting as a 'logical' server). To use this Prolog server
          as a real server waiting for connections at a given port,
          use `prolog_server/1'.

 -- PREDICATE: prolog_server/1:
     *Usage:*
        - _Description:_ Waits for incoming Java connections to act
          as a Prolog goal server for Java requests.This is the only
          `prolog_server/*' predicate that works as a true server:
          given a port number, waits for a connection from Java and
          then serves Java requests. When a termination request is
          received, finishes the connection to Java and waits next
          Java connection request. This behaviour is different with
          respect to previous versions of this library. To work as
          before, use `prolog_server/2'.

          Although it currently does not support simultaneous Java
          connections, some work is being done in that direction.

        - _Call and exit should be _compatible_ with:_

          `Arg1' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: prolog_server/2:
     *Usage:*
        - _Description:_ Prolog server entry point. Given a network
          `node' and a `port' number, starts the prolog server trying
          to connect to Java side at that `node:port' address, and
          then waits for Java requests. This predicate acts as a
          server: it includes an endless read-process loop until the
          `prolog_halt' command is received.

          However, from the low-level communication point of view,
          this Prolog server actually works as a client of the Java
          side. This means that Java side waits at the given port to
          a Prolog server trying to create a socket; Prolog side
          connects to that port, and then waits for Java requests
          (acting as a 'logical' server). To use this Prolog server
          as a real server waiting for connections at a given port,
          use `prolog_server/1'.

        - _Call and exit should be _compatible_ with:_

          `Arg1' is an atom.   (`basic_props:atm/1')

          `Arg2' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: shell_s/0:
     *Usage:*
        - _Description:_ Command execution loop. This predicate is
          called when the connection to Java is established, and
          performs an endless loop processing the commands received.
          This predicate is only intended to be used by the Prolog to
          Java interface and it should not be used by a user program.

 -- PREDICATE: query_solutions/2:
     No further documentation available for this predicate.

     The predicate is of type _concurrent_.

 -- PREDICATE: query_requests/2:
     No further documentation available for this predicate.

     The predicate is of type _concurrent_.

 -- PREDICATE: running_queries/2:
     No further documentation available for this predicate.

     The predicate is of type _concurrent_.

151 Low-level Prolog to Java socket connection
**********************************************

*Author(s):* Jesu's Correas.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#66 (2003/3/14, 12:48:24 CET)

   This module defines a low-level socket interface, to be used by
javart and jtopl. Includes all the code related directly to the
handling of sockets. This library should not be used by any user
program, because is a very low-level connection to Java. Use `javart'
(Prolog to Java interface) or `jtopl' (Java to Prolog interface)
libraries instead.

151.1 Usage and interface (`javasock')
======================================

   * *Library usage:*

     `:- use_module(library(javasock)).'

   * *Exports:*
        - _Predicates:_

          `bind_socket_interface/1', `start_socket_interface/2', `stop_socket_interface/0', `join_socket_interface/0', `java_query/2', `java_response/2', `prolog_query/2', `prolog_response/2', `is_connected_to_java/0', `java_debug/1', `java_debug_redo/1', `start_threads/0'.

   * *Other modules used:*
        - _System library modules:_

          `fastrw', `read', `sockets/sockets', `dynamic', `format', `concurrency/concurrency', `javall/jtopl', `sockets/sockets_io'.

151.2 Documentation on exports (`javasock')
===========================================

 -- PREDICATE: bind_socket_interface/1:
     *Usage:* `bind_socket_interface(+Port)'
        - _Description:_ Given an port number, waits for a connection
          request from the Java side, creates the sockets to connect
          to the java process, and starts the threads needed to
          handle the connection.

        - _Call and exit should be _compatible_ with:_

          `+Port' is an integer.   (`basic_props:int/1')

 -- PREDICATE: start_socket_interface/2:
     *Usage:* `start_socket_interface(+Address, +Stream)'
        - _Description:_ Given an address in format 'node:port',
          creates the sockets to connect to the java process, and
          starts the threads needed to handle the connection.

        - _Call and exit should be _compatible_ with:_

          `+Address' is any term.   (`basic_props:term/1')

          `+Stream' is an open stream.   (`streams_basic:stream/1')

 -- PREDICATE: stop_socket_interface/0:
     *Usage:*
        - _Description:_ Closes the sockets to disconnect from the
          java process, and waits until the threads that handle the
          connection terminate.

 -- PREDICATE: join_socket_interface/0:
     *Usage:*
        - _Description:_ Waits until the threads that handle the
          connection terminate.

 -- PREDICATE: java_query/2:
     The predicate is of type _concurrent_.

     *Usage:* `java_query(ThreadId, Query)'
        - _Description:_ Data predicate containing the queries to be
          sent to Java. First argument is the Prolog thread Id, and
          second argument is the query to send to Java.

        - _Call and exit should be _compatible_ with:_

          `ThreadId' is an atom.   (`basic_props:atm/1')

          `Query' is any term.   (`basic_props:term/1')

 -- PREDICATE: java_response/2:
     The predicate is of type _concurrent_.

     *Usage:* `java_response(Id, Response)'
        - _Description:_ Data predicate that stores the responses to
          requests received from Java. First argument corresponds to
          the Prolog thread Id; second argument corresponds to the
          response itself.

        - _Call and exit should be _compatible_ with:_

          `Id' is an atom.   (`basic_props:atm/1')

          `Response' is any term.   (`basic_props:term/1')

 -- PREDICATE: prolog_query/2:
     The predicate is of type _concurrent_.

     *Usage:* `prolog_query(Id, Query)'
        - _Description:_ Data predicate that keeps a queue of the
          queries requested to Prolog side from Java side.

        - _Call and exit should be _compatible_ with:_

          `Id' is an integer.   (`basic_props:int/1')

          `Query' is any term.   (`basic_props:term/1')

 -- PREDICATE: prolog_response/2:
     The predicate is of type _concurrent_.

     *Usage:* `prolog_response(Id, Response)'
        - _Description:_ Data predicate that keeps a queue of the
          responses to queries requested to Prolog side from Java
          side.

        - _Call and exit should be _compatible_ with:_

          `Id' is an integer.   (`basic_props:int/1')

          `Response' is any term.   (`basic_props:term/1')

 -- PREDICATE: is_connected_to_java/0:
     *Usage:*
        - _Description:_ Checks if the connection to Java is
          established.

 -- PREDICATE: java_debug/1:
     No further documentation available for this predicate.

 -- PREDICATE: java_debug_redo/1:
     No further documentation available for this predicate.

 -- PREDICATE: start_threads/0:
     *Usage:*
        - _Description:_ Starts the threads that will handle the
          connection to Java. This predicate is declared public for
          internal purposes, and it is not intended to be used by a
          user program.

152 Calling emacs from Prolog
*****************************

*Author(s):* The CLIP Group.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#234 (2003/12/22, 18:14:10 CET)

   This library provides a _prolog-emacs interface_. This interface
is complementary to (and independent from) the emacs mode, which is
used to develop programs from within the `emacs' editor/environment.
Instead, this library allows calling `emacs' from a running Prolog
program. This facilitates the use of `emacs' as a "user interface"
for a Prolog program. Emacs can be made to:

   * Visit a file, which can then be edited.

   * Execute arbitrary _emacs lisp_ code, sent from Prolog.

In order for this library to work correctly, the following is needed:

   * You should be running the `emacs' editor on the same machine
     where the executable calling this library is executing.

   * This `emacs' should be running the _emacs server_. This can be
     done by including the following line in your `.emacs' file:

          ;; Start a server that emacsclient can connect to.
          (server-start)

     Or typing `M-x server-start' within `emacs'.

This suffices for using `emacs' to edit files. For running arbitrary
code the following also needs to be added to the `.emacs' file:

`(setq enable-local-eval t)'
     Allows executing lisp code without asking.

`(setq enable-local-eval nil)'
     Does not allow executing lisp code without asking.

`(setq enable-local-eval 'maybe)'
     Allows executing lisp code only if user agrees after asking
     (asks interactively for every invocation).

*Examples:*

Assuming that a `.pl' file loads this library, then:

`..., emacs_edit('foo'), ...'
     Opens file `foo' for editing in `emacs'.

`..., emacs_eval_nowait("(run-ciao-toplevel)"), ...'
     Starts execution of a Ciao top-level within `emacs'.

152.1 Usage and interface (`emacs')
===================================

   * *Library usage:*

     `:- use_module(library(emacs)).'

   * *Exports:*
        - _Predicates:_

          `emacs_edit/1', `emacs_edit_nowait/1', `emacs_eval/1', `emacs_eval_nowait/1'.

        - _Regular Types:_

          `elisp_string/1'.

   * *Other modules used:*
        - _System library modules:_

          `terms_check', `lists', `terms', `system'.

152.2 Documentation on exports (`emacs')
========================================

 -- PREDICATE: emacs_edit/1:
     *Usage:* `emacs_edit(+filename)'
        - _Description:_ Opens the given file for editing in `emacs'.
          Waits for editing to finish before continuing.

 -- PREDICATE: emacs_edit_nowait/1:
     *Usage:* `emacs_edit_nowait(+filename)'
        - _Description:_ Opens the given file for editing in `emacs'
          and continues without waiting for editing to finish.

 -- PREDICATE: emacs_eval/1:
     *Usage:* `emacs_eval(+elisp_string)'
        - _Description:_ Executes in emacs the lisp code given as
          argument. Waits for the command to finish before continuing.

 -- PREDICATE: emacs_eval_nowait/1:
     *Usage:* `emacs_eval_nowait(+elisp_string)'
        - _Description:_ Executes in emacs the lisp code given as
          argument and continues without waiting for it to finish.

 -- REGTYPE: elisp_string/1:
     *Usage:* `elisp_string(L)'
        - _Description:_ `L' is a string containing `emacs' lisp code.

153 linda (library)
*******************

*Version:* 0.9#66 (1999/4/29, 12:28:0 MEST)

   This is a SICStus-like linda package. Note that this is
essentially quite obsolete, and provided mostly in case it is needed
for compatibility, since Ciao now supports all Linda functionality
(and more) through the concurrent fact database.

153.1 Usage and interface (`linda')
===================================

   * *Library usage:*

     `:- use_module(library(linda)).'

   * *Exports:*
        - _Predicates:_

          `linda_client/1', `close_client/0', `in/1', `in/2', `in_noblock/1', `out/1', `rd/1', `rd/2', `rd_noblock/1', `rd_findall/3', `linda_timeout/2', `halt_server/0', `open_client/2', `in_stream/2', `out_stream/2'.

   * *Other modules used:*
        - _System library modules:_

          `read', `fastrw', `sockets/sockets'.

153.2 Documentation on exports (`linda')
========================================

 -- PREDICATE: linda_client/1:
     No further documentation available for this predicate.

 -- PREDICATE: close_client/0:
     No further documentation available for this predicate.

 -- PREDICATE: in/1:
     No further documentation available for this predicate.

 -- PREDICATE: in/2:
     No further documentation available for this predicate.

 -- PREDICATE: in_noblock/1:
     No further documentation available for this predicate.

 -- PREDICATE: out/1:
     No further documentation available for this predicate.

 -- PREDICATE: rd/1:
     No further documentation available for this predicate.

 -- PREDICATE: rd/2:
     No further documentation available for this predicate.

 -- PREDICATE: rd_noblock/1:
     No further documentation available for this predicate.

 -- PREDICATE: rd_findall/3:
     No further documentation available for this predicate.

 -- PREDICATE: linda_timeout/2:
     No further documentation available for this predicate.

 -- PREDICATE: halt_server/0:
     No further documentation available for this predicate.

 -- PREDICATE: open_client/2:
     No further documentation available for this predicate.

 -- PREDICATE: in_stream/2:
     No further documentation available for this predicate.

 -- PREDICATE: out_stream/2:
     No further documentation available for this predicate.

PART IX - Abstract data types
*****************************

*Author(s):* The CLIP Group.

   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.

154 Extendable arrays with logarithmic access time
**************************************************

*Author(s):* Lena Flood.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#236 (2003/12/22, 18:18:14 CET)

   This module implements extendable arrays with logarithmic access
time. It has been adapted from shared code written by David Warren
and Fernando Pereira.

154.1 Usage and interface (`arrays')
====================================

   * *Library usage:*

     `:- use_module(library(arrays)).'

   * *Exports:*
        - _Predicates:_

          `new_array/1', `is_array/1', `aref/3', `arefa/3', `arefl/3', `aset/4', `array_to_list/2'.

154.2 Documentation on exports (`arrays')
=========================================

 -- PREDICATE: new_array/1:
     *Usage:* `new_array(-Array)'
        - _Description:_ returns an empty new array `Array'.

 -- PREDICATE: is_array/1:
     *Usage:* `is_array(+Array)'
        - _Description:_ `Array' actually is an array.

 -- PREDICATE: aref/3:
     *Usage:* `aref(+Index, +Array, ?Element)'
        - _Description:_ unifies `Element' to `Array'[`Index'], or
          fails if `Array'[`Index'] has not been set.

 -- PREDICATE: arefa/3:
     *Usage:* `arefa(+Index, +Array, ?Element)'
        - _Description:_ is as `aref/3', except that it unifies
          `Element' with a new array if `Array'[`Index'] is
          undefined. This is useful for multidimensional arrays
          implemented as arrays of arrays.

 -- PREDICATE: arefl/3:
     *Usage:* `arefl(+Index, +Array, ?Element)'
        - _Description:_ is as `aref/3', except that `Element'
          appears as `[]' for undefined cells. Thus, `arefl(_,_,[])'
          always succeeds no matter what you give in the first or
          second args.

 -- PREDICATE: aset/4:
     *Usage:* `aset(+Index, +Array, Element, -NewArray)'
        - _Description:_ unifies `NewArray' with the result of
          setting `Array'[`Index'] to `Element'.

 -- PREDICATE: array_to_list/2:
     *Usage:* `array_to_list(+Array, -List)'
        - _Description:_ returns a `List' of pairs Index-Element of
          all the elements of `Array' that have been set.

155 counters (library)
**********************

*Version:* 0.4#5 (1998/2/24)

155.1 Usage and interface (`counters')
======================================

   * *Library usage:*

     `:- use_module(library(counters)).'

   * *Exports:*
        - _Predicates:_

          `setcounter/2', `getcounter/2', `inccounter/2'.

155.2 Documentation on exports (`counters')
===========================================

 -- PREDICATE: setcounter/2:
     No further documentation available for this predicate.

 -- PREDICATE: getcounter/2:
     No further documentation available for this predicate.

 -- PREDICATE: inccounter/2:
     No further documentation available for this predicate.

156 Identity lists
******************

*Author(s):* Francisco Bueno.

   *Version:* 1.9#266 (2004/1/1, 14:1:7 CET)

   The operations in this module handle lists by performing equality
checks via identity instead of unification.

156.1 Usage and interface (`idlists')
=====================================

   * *Library usage:*

     `:- use_module(library(idlists)).'

   * *Exports:*
        - _Predicates:_

          `member_0/2', `memberchk/2', `list_insert/2', `add_after/4', `add_before/4', `delete/3', `subtract/3', `union_idlists/3'.

156.2 Documentation on exports (`idlists')
==========================================

 -- PREDICATE: member_0/2:
     `member_0(X, Xs)'

     True iff memberchk/2 is true.

 -- PREDICATE: memberchk/2:
     `memberchk(X, Xs)'

     Checks that `X' is an element of (list) `Xs'.

 -- PREDICATE: list_insert/2:
     *Usage:* `list_insert(-List, +Term)'
        - _Description:_ Adds `Term' to the end of (tail-opened)
          `List' if there is not an element in `List' identical to
          `Term'.

 -- PREDICATE: add_after/4:
     *Usage:* `add_after(+L0, +E0, +E, -L)'
        - _Description:_ Adds element `E' after the first element
          identical to `E0' (or at end) of list `L0', returning in
          `L' the new list.

 -- PREDICATE: add_before/4:
     *Usage:* `add_before(+L0, +E0, +E, -L)'
        - _Description:_ Adds element `E' before the first element
          identical to `E0' (or at start) of list `L0', returning in
          `L' the new list.

 -- PREDICATE: delete/3:
     *Usage:* `delete(+List, +Element, -Rest)'
        - _Description:_ `Rest' has the same elements of `List'
          except for all the occurrences of elements identical to
          `Element'.

 -- PREDICATE: subtract/3:
     *Usage:* `subtract(+Set, +Set0, -Difference)'
        - _Description:_ `Difference' has the same elements of `Set'
          except those which have an identical occurrence in `Set0'.

 -- PREDICATE: union_idlists/3:
     *Usage:* `union_idlists(+List1, +List2, -List)'
        - _Description:_ `List' has the elements which are in `List1'
          but are not identical to an element in `List2' followed by
          the elements in `List2'.

157 Lists of numbers
********************

*Author(s):* The CLIP Group.

   *Version:* 1.9#237 (2003/12/22, 18:23:36 CET)

   This module implements some kinds of lists of numbers.

157.1 Usage and interface (`numlists')
======================================

   * *Library usage:*

     `:- use_module(library(numlists)).'

   * *Exports:*
        - _Predicates:_

          `get_primes/2', `sum_list/2', `sum_list/3', `sum_list_of_lists/2', `sum_list_of_lists/3'.

        - _Regular Types:_

          `intlist/1', `numlist/1'.

   * *Other modules used:*
        - _System library modules:_

          `lists'.

157.2 Documentation on exports (`numlists')
===========================================

 -- PREDICATE: get_primes/2:
     *Usage:* `get_primes(N, Primes)'
        - _Description:_ Computes the `N'th first prime numbers in
          ascending order.

        - _The following properties should hold at call time:_

          `N' is an integer.   (`basic_props:int/1')

        - _The following properties should hold upon exit:_

          `Primes' is a list of integers.   (`numlists:intlist/1')

 -- REGTYPE: intlist/1:
     *Usage:* `intlist(X)'
        - _Description:_ `X' is a list of integers.

 -- REGTYPE: numlist/1:
     *Usage:* `numlist(X)'
        - _Description:_ `X' is a list of numbers.

 -- PREDICATE: sum_list/2:
     *Usage:* `sum_list(List, N)'
        - _Description:_ `N' is the total sum of the elements of
          `List'.

        - _The following properties should hold at call time:_

          `List' is a list of numbers.   (`numlists:numlist/1')

        - _The following properties should hold upon exit:_

          `N' is a number.   (`basic_props:num/1')

 -- PREDICATE: sum_list/3:
     *Usage:* `sum_list(List, N0, N)'
        - _Description:_ `N' is the total sum of the elements of
          `List' plus `N0'.

        - _The following properties should hold at call time:_

          `List' is a list of numbers.   (`numlists:numlist/1')

          `N0' is a number.   (`basic_props:num/1')

        - _The following properties should hold upon exit:_

          `N' is a number.   (`basic_props:num/1')

 -- PREDICATE: sum_list_of_lists/2:
     *Usage:* `sum_list_of_lists(Lists, N)'
        - _Description:_ `N' is the total sum of the elements of the
          lists of `Lists'.

        - _The following properties should hold at call time:_

          `List' is a list of `numlist's.   (`basic_props:list/2')

        - _The following properties should hold upon exit:_

          `N' is a number.   (`basic_props:num/1')

 -- PREDICATE: sum_list_of_lists/3:
     *Usage:* `sum_list_of_lists(Lists, N0, N)'
        - _Description:_ `N' is the total sum of the elements of the
          lists of `Lists' plus `N0'.

        - _The following properties should hold at call time:_

          `List' is a list of `numlist's.   (`basic_props:list/2')

          `N0' is a number.   (`basic_props:num/1')

        - _The following properties should hold upon exit:_

          `N' is a number.   (`basic_props:num/1')

158 Pattern (regular expression) matching
*****************************************

*Author(s):* The CLIP Group.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#255 (2003/12/30, 23:32:38 CET)

   This library provides facilities for matching strings and terms
against _patterns_ (i.e., _regular expressions_).

158.1 Usage and interface (`patterns')
======================================

   * *Library usage:*

     `:- use_module(library(patterns)).'

   * *Exports:*
        - _Predicates:_

          `match_pattern/2', `match_pattern/3', `case_insensitive_match/2', `letter_match/2', `match_pattern_pred/2'.

        - _Regular Types:_

          `pattern/1'.

   * *Other modules used:*
        - _System library modules:_

          `lists'.

158.2 Documentation on exports (`patterns')
===========================================

 -- PREDICATE: match_pattern/2:
     *Usage:* `match_pattern(Pattern, String)'
        - _Description:_ Matches `String' against `Pattern'. For
          example, `match_pattern("*.pl","foo.pl")' succeeds.

        - _The following properties should hold at call time:_

          `Pattern' is a pattern to match against.
          (`patterns:pattern/1')

          `String' is a string (a list of character codes).
          (`basic_props:string/1')

 -- PREDICATE: match_pattern/3:
     *Usage:* `match_pattern(Pattern, String, Tail)'
        - _Description:_ Matches `String' against `Pattern'. `Tail'
          is the remainder of the string after the match. For
          example, `match_pattern("??*","foo.pl",Tail)' succeeds,
          instantiating `Tail' to `"o.pl"'.

        - _The following properties should hold at call time:_

          `Pattern' is a pattern to match against.
          (`patterns:pattern/1')

          `String' is a string (a list of character codes).
          (`basic_props:string/1')

          `Tail' is a string (a list of character codes).
          (`basic_props:string/1')

 -- PREDICATE: case_insensitive_match/2:
     *Usage:* `case_insensitive_match(Pred1, Pred2)'
        - _Description:_ Tests if two predicates `Pred1' and `Pred2'
          match in a case-insensitive way.

 -- PREDICATE: letter_match/2:
     *Usage:* `letter_match(X, Y)'
        - _Description:_ True iff `X' and `Y' represents the same
          letter

 -- REGTYPE: pattern/1:
     Special characters for `Pattern' are:
    *
          Matches any string, including the null string.

    ?
          Matches any single character.

    [...]
          Matches any one of the enclosed characters. A pair of
          characters separated by a minus sign denotes a range; any
          character lexically between those two characters,
          inclusive, is matched. If the first character following the
          [ is a ^ then any character not enclosed is matched. No
          other character is special inside this construct. To
          include a ] in a character set, you must make it the first
          character. To include a `-', you must use it in a context
          where it cannot possibly indicate a range: that is, as the
          first character, or immediately after a range.

    |
          Specifies an alternative. Two patterns A and B with | in
          between form an expression that matches anything that
          either A or B will match.

    {...}
          Groups alternatives inside larger patterns.

    \
          Quotes a special character (including itself).

     *Usage:* `pattern(P)'
        - _Description:_ `P' is a pattern to match against.

 -- PREDICATE: match_pattern_pred/2:
     *Usage:* `match_pattern_pred(Pred1, Pred2)'
        - _Description:_ Tests if two predicates `Pred1' and `Pred2'
          match using regular expressions.

159 Graphs
**********

*Author(s):* Francisco Bueno.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#238 (2003/12/22, 18:25:58 CET)

   This module implements utilities for work with graphs

159.1 Usage and interface (`graphs')
====================================

   * *Library usage:*

     `:- use_module(library(graphs)).'

   * *Exports:*
        - _Predicates:_

          `dgraph_to_ugraph/2', `dlgraph_to_lgraph/2', `edges_to_ugraph/2', `edges_to_lgraph/2'.

        - _Regular Types:_

          `dgraph/1', `dlgraph/1'.

   * *Other modules used:*
        - _System library modules:_

          `sort', `graphs/ugraphs', `graphs/lgraphs'.

159.2 Documentation on exports (`graphs')
=========================================

 -- REGTYPE: dgraph/1:
     `dgraph(Graph)'

     A directed graph is a term `graph(V,E)' where `V' is a list of
     vertices and `E' is a list of edges (none necessarily sorted).
     Edges are pairs of vertices which are directed, i.e., `(a,b)'
     represents `a->b'. Two vertices `a' and `b' are equal only if
     `a==b'.

     *Usage:* `dgraph(Graph)'
        - _Description:_ `Graph' is a directed graph.

 -- REGTYPE: dlgraph/1:
     `dlgraph(Graph)'

     A labeled directed graph is a directed graph where edges are
     triples of the form `(a,l,b)' where `l' is the label of the edge
     `(a,b)'.

     *Usage:* `dlgraph(Graph)'
        - _Description:_ `Graph' is a directed labeled graph.

 -- PREDICATE: dgraph_to_ugraph/2:
     *Usage:* `dgraph_to_ugraph(+Graph, -UGraph)'
        - _Description:_ Converts `Graph' to `UGraph'.

        - _The following properties should hold at call time:_

          `+Graph' is a directed graph.   (`graphs:dgraph/1')

          `-UGraph' is a free variable.   (`term_typing:var/1')

        - _The following properties should hold upon exit:_

          `+Graph' is a directed graph.   (`graphs:dgraph/1')

          `-UGraph' is an ugraph.   (`ugraphs:ugraph/1')

 -- PREDICATE: dlgraph_to_lgraph/2:
     *Usage:* `dlgraph_to_lgraph(+Graph, -LGraph)'
        - _Description:_ Converts `Edges' to `LGraph'.

        - _The following properties should hold at call time:_

          `+Graph' is a directed labeled graph.   (`graphs:dlgraph/1')

          `-LGraph' is a free variable.   (`term_typing:var/1')

        - _The following properties should hold upon exit:_

          `+Graph' is a directed labeled graph.   (`graphs:dlgraph/1')

          `-LGraph' is a labeled graph of `term' terms.
          (`lgraphs:lgraph/2')

 -- PREDICATE: edges_to_ugraph/2:
     *Usage:* `edges_to_ugraph(+Edges, -UGraph)'
        - _Description:_ Converts `Graph' to `UGraph'.

        - _The following properties should hold at call time:_

          `+Edges' is a list of `pair's.   (`basic_props:list/2')

          `-UGraph' is a free variable.   (`term_typing:var/1')

        - _The following properties should hold upon exit:_

          `+Edges' is a list of `pair's.   (`basic_props:list/2')

          `-UGraph' is an ugraph.   (`ugraphs:ugraph/1')

 -- PREDICATE: edges_to_lgraph/2:
     *Usage:* `edges_to_lgraph(+Edges, -LGraph)'
        - _Description:_ Converts `Edges' to `LGraph'.

        - _The following properties should hold at call time:_

          `+Edges' is a list of `triple's.   (`basic_props:list/2')

          `-LGraph' is a free variable.   (`term_typing:var/1')

        - _The following properties should hold upon exit:_

          `+Edges' is a list of `triple's.   (`basic_props:list/2')

          `-LGraph' is a labeled graph of `term' terms.
          (`lgraphs:lgraph/2')

159.3 Documentation on internals (`graphs')
===========================================

 -- REGTYPE: pair/1:
     *Usage:* `pair(P)'
        - _Description:_ `P' is a pair `(_,_)'.

 -- REGTYPE: triple/1:
     *Usage:* `triple(P)'
        - _Description:_ `P' is a triple `(_,_,_)'.

160 Unweighted graph-processing utilities
*****************************************

*Author(s):* M. Carlsson, adapted from shared code written by Richard
A O'Keefe. Mods by F.Bueno and M.Carro..

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 0.9#105 (1999/6/4, 12:24:49 MEST)

   An unweighted directed graph (ugraph) is represented as a list of
(vertex-neighbors) pairs, where the pairs are in standard order (as
produced by keysort with unique keys) and the neighbors of each
vertex are also in standard order (as produced by sort), and every
neighbor appears as a vertex even if it has no neighbors itself.

   An undirected graph is represented as a directed graph where for
each edge `(U,V)' there is a symmetric edge `(V,U)'.

   An edge `(U,V)' is represented as the term `U-V'.

   A vertex can be any term. Two vertices are distinct iff they are
not identical ( `==/2').

   A path is represented as a list of vertices. No vertex can appear
twice in a path.

160.1 Usage and interface (`ugraphs')
=====================================

   * *Library usage:*

     `:- use_module(library(ugraphs)).'

   * *Exports:*
        - _Predicates:_

          `vertices_edges_to_ugraph/3', `neighbors/3', `edges/2', `del_vertices/3', `vertices/2', `add_vertices/3', `add_edges/3', `transpose/2', `point_to/3'.

        - _Regular Types:_

          `ugraph/1'.

   * *Other modules used:*
        - _System library modules:_

          `sets', `sort'.

160.2 Documentation on exports (`ugraphs')
==========================================

 -- PREDICATE: vertices_edges_to_ugraph/3:
     No further documentation available for this predicate.

 -- PREDICATE: neighbors/3:
     *Usage:* `neighbors(+Vertex, +Graph, -Neighbors)'
        - _Description:_ Is true if `Vertex' is a vertex in `Graph'
          and `Neighbors' are its neighbors.

 -- PREDICATE: edges/2:
     *Usage:* `edges(+Graph, -Edges)'
        - _Description:_ Unifies `Edges' with the edges in `Graph'.

 -- PREDICATE: del_vertices/3:
     *Usage:* `del_vertices(+Graph1, +Vertices, -Graph2)'
        - _Description:_ Is true if `Graph2' is `Graph1' with
          `Vertices' and all edges to and from `Vertices' removed
          from it.

 -- PREDICATE: vertices/2:
     *Usage:* `vertices(+Graph, -Vertices)'
        - _Description:_ Unifies `Vertices' with the vertices in
          `Graph'.

 -- PREDICATE: add_vertices/3:
     *Usage:* `add_vertices(+Graph1, +Vertices, -Graph2)'
        - _Description:_ Is true if `Graph2' is `Graph1' with
          `Vertices' added to it.

 -- PREDICATE: add_edges/3:
     *Usage:* `add_edges(+Graph1, +Edges, -Graph2)'
        - _Description:_ Is true if `Graph2' is `Graph1' with `Edges'
          and their 'to' and 'from' vertices added to it.

 -- PREDICATE: transpose/2:
     *Usage:* `transpose(+Graph, -Transpose)'
        - _Description:_ Is true if `Transpose' is the graph computed
          by replacing each edge `(u,v)' in `Graph' by its symmetric
          edge `(v,u)'. It can only be used one way around. The cost
          is O(N^2).

 -- PREDICATE: point_to/3:
     *Usage:* `point_to(+Vertex, +Graph, -Point_to)'
        - _Description:_ Is true if `Point_to' is the list of nodes
          which go directly to `Vertex' in `Graph'.

 -- REGTYPE: ugraph/1:
     *Usage:* `ugraph(Graph)'
        - _Description:_ `Graph' is an ugraph.

161 wgraphs (library)
*********************

*Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 0.4#5 (1998/2/24)

161.1 Usage and interface (`wgraphs')
=====================================

   * *Library usage:*

     `:- use_module(library(wgraphs)).'

   * *Exports:*
        - _Predicates:_

          `vertices_edges_to_wgraph/3'.

   * *Other modules used:*
        - _System library modules:_

          `sets', `sort'.

161.2 Documentation on exports (`wgraphs')
==========================================

 -- PREDICATE: vertices_edges_to_wgraph/3:
     No further documentation available for this predicate.

162 Labeled graph-processing utilities
**************************************

*Author(s):* Francisco Bueno.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#256 (2003/12/30, 23:45:1 CET)

   See the comments for the `ugraphs' library.

162.1 Usage and interface (`lgraphs')
=====================================

   * *Library usage:*

     `:- use_module(library(lgraphs)).'

   * *Exports:*
        - _Predicates:_

          `vertices_edges_to_lgraph/3'.

        - _Regular Types:_

          `lgraph/2'.

   * *Other modules used:*
        - _System library modules:_

          `sort', `sets'.

162.2 Documentation on exports (`lgraphs')
==========================================

 -- REGTYPE: lgraph/2:
     *Usage:* `lgraph(Graph, Type)'
        - _Description:_ `Graph' is a labeled graph of `Type' terms.

 -- PREDICATE: vertices_edges_to_lgraph/3:
     `vertices_edges_to_lgraph(Vertices0, Edges, Graph)'

     This one is a copy of the same procedure in library(wgraphs)
     except for the definition of min/3 (ah! - the polimorphism!).

     It would only be needed if there are multi-edges, i.e., several
     edges between the same two vertices.

163 queues (library)
********************

*Version:* 0.4#5 (1998/2/24)

163.1 Usage and interface (`queues')
====================================

   * *Library usage:*

     `:- use_module(library(queues)).'

   * *Exports:*
        - _Predicates:_

          `q_empty/1', `q_insert/3', `q_member/2', `q_delete/3'.

163.2 Documentation on exports (`queues')
=========================================

 -- PREDICATE: q_empty/1:
     No further documentation available for this predicate.

 -- PREDICATE: q_insert/3:
     No further documentation available for this predicate.

 -- PREDICATE: q_member/2:
     No further documentation available for this predicate.

 -- PREDICATE: q_delete/3:
     No further documentation available for this predicate.

164 Random numbers
******************

*Author(s):* Daniel Cabeza.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#275 (2004/1/9, 16:25:9 CET)

   This module provides predicates for generating pseudo-random
numbers

164.1 Usage and interface (`random')
====================================

   * *Library usage:*

     `:- use_module(library(random)).'

   * *Exports:*
        - _Predicates:_

          `random/1', `random/3', `srandom/1'.

164.2 Documentation on exports (`random')
=========================================

 -- PREDICATE: random/1:
     `random(Number)'

     `Number' is a (pseudo-) random number in the range [0.0,1.0]

 -- PREDICATE: random/3:
     `random(Low, Up, Number)'

     `Number' is a (pseudo-) random number in the range [`Low', `Up']

     *Usage 1:* `random(+int, +int, -int)'
        - _Description:_ If `Low' and `Up' are integers, `Number' is
          an integer.

 -- PREDICATE: srandom/1:
     `srandom(Seed)'

     Changes the sequence of pseudo-random numbers according to
     `Seed'. The stating sequence of numbers generated can be
     duplicated by calling the predicate with `Seed' unbound (the
     sequence depends on the OS).

165 Set Operations
******************

*Author(s):* Lena Flood.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#239 (2003/12/22, 18:32:52 CET)

   This module implements set operations. Sets are just ordered lists.

165.1 Usage and interface (`sets')
==================================

   * *Library usage:*

     `:- use_module(library(sets)).'

   * *Exports:*
        - _Predicates:_

          `insert/3', `ord_delete/3', `ord_member/2', `ord_test_member/3', `ord_subtract/3', `ord_intersection/3', `ord_intersection_diff/4', `ord_intersect/2', `ord_subset/2', `ord_subset_diff/3', `ord_union/3', `ord_union_diff/4', `ord_union_symdiff/4', `ord_union_change/3', `merge/3', `ord_disjoint/2', `setproduct/3'.

   * *Other modules used:*
        - _System library modules:_

          `sort'.

165.2 Documentation on exports (`sets')
=======================================

 -- PREDICATE: insert/3:
     *Usage:* `insert(+Set1, +Element, -Set2)'
        - _Description:_ It is true when `Set2' is `Set1' with
          `Element' inserted in it, preserving the order.

 -- PREDICATE: ord_delete/3:
     *Usage:* `ord_delete(+Set0, +X, -Set)'
        - _Description:_ It succeeds if `Set' is `Set0' without
          element `X'.

 -- PREDICATE: ord_member/2:
     *Usage:* `ord_member(+X, +Set)'
        - _Description:_ It succeeds if `X' is member of `Set'.

 -- PREDICATE: ord_test_member/3:
     *Usage:* `ord_test_member(+Set, +X, -Result)'
        - _Description:_ If `X' is member of `Set' then
          `Result'=`yes'. Otherwise `Result'=`no'.

 -- PREDICATE: ord_subtract/3:
     *Usage:* `ord_subtract(+Set1, +Set2, ?Difference)'
        - _Description:_ It is true when `Difference' contains all
          and only the elements of `Set1' which are not also in
          `Set2'.

 -- PREDICATE: ord_intersection/3:
     *Usage:* `ord_intersection(+Set1, +Set2, ?Intersection)'
        - _Description:_ It is true when `Intersection' is the
          ordered representation of `Set1' and `Set2', provided that
          `Set1' and `Set2' are ordered lists.

 -- PREDICATE: ord_intersection_diff/4:
     *Usage:* `ord_intersection_diff(+Set1, +Set2, -Intersect,
     -NotIntersect)'
        - _Description:_ `Intersect' contains those elements which
          are both in `Set1' and `Set2', and `NotIntersect' those
          which are in `Set1' but not in `Set2'.

 -- PREDICATE: ord_intersect/2:
     *Usage:* `ord_intersect(+Xs, +Ys)'
        - _Description:_ Succeeds when the two ordered lists have at
          least one element in common.

 -- PREDICATE: ord_subset/2:
     *Usage:* `ord_subset(+Xs, +Ys)'
        - _Description:_ Succeeds when every element of `Xs' appears
          in `Ys'.

 -- PREDICATE: ord_subset_diff/3:
     *Usage:* `ord_subset_diff(+Set1, +Set2, -Difference)'
        - _Description:_ It succeeds when every element of `Set1'
          appears in `Set2' and `Difference' has the elements of
          `Set2' which are not in `Set1'.

 -- PREDICATE: ord_union/3:
     *Usage:* `ord_union(+Set1, +Set2, ?Union)'
        - _Description:_ It is true when `Union' is the union of
          `Set1' and `Set2'. When some element occurs in both sets,
          `Union' retains only one copy.

 -- PREDICATE: ord_union_diff/4:
     *Usage:* `ord_union_diff(+Set1, +Set2, -Union, -Difference)'
        - _Description:_ It succeeds when `Union' is the union of
          `Set1' and `Set2', and `Difference' is `Set2' set-minus
          `Set1'.

 -- PREDICATE: ord_union_symdiff/4:
     *Usage:* `ord_union_symdiff(+Set1, +Set2, -Union, -Diff)'
        - _Description:_ It is true when Diff is the symmetric
          difference of Set1 and Set2, and Union is the union of Set1
          and Set2.

 -- PREDICATE: ord_union_change/3:
     *Usage:* `ord_union_change(+Set1, +Set2, -Union)'
        - _Description:_ `Union' is the union of `Set1' and `Set2'
          and `Union' is different from `Set2'.

 -- PREDICATE: merge/3:
     *Usage:* `merge(+Set1, +Set2, ?Union)'
        - _Description:_ See `ord_union/3'.

 -- PREDICATE: ord_disjoint/2:
     *Usage:* `ord_disjoint(+Set1, +Set2)'
        - _Description:_ `Set1' and `Set2' have no element in common.

 -- PREDICATE: setproduct/3:
     *Usage:* `setproduct(+Set1, +Set2, -Product)'
        - _Description:_ `Product' has all two element sets such that
          one element is in `Set1' and the other in `set2', except
          that if the same element belongs to both, then the
          corresponding one element set is in `Product'.

166 Variable name dictionaries
******************************

*Author(s):* Francisco Bueno.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#99 (2003/8/27, 17:56:12 CEST)

166.1 Usage and interface (`vndict')
====================================

   * *Library usage:*

     `:- use_module(library(vndict)).'

   * *Exports:*
        - _Predicates:_

          `create_dict/2', `complete_dict/3', `complete_vars_dict/3', `prune_dict/3', `sort_dict/2', `dict2varnamesl/2', `varnamesl2dict/2', `find_name/4', `rename/2', `vars_names_dict/3'.

        - _Regular Types:_

          `null_dict/1', `varname/1', `varnamesl/1', `varnamedict/1'.

   * *Other modules used:*
        - _System library modules:_

          `idlists', `terms_vars', `sets', `sort'.

166.2 Documentation on exports (`vndict')
=========================================

 -- REGTYPE: null_dict/1:
     *Usage:* `null_dict(D)'
        - _Description:_ `D' is an empty dictionary.

 -- PREDICATE: create_dict/2:
     *Usage:* `create_dict(Term, Dict)'
        - _Description:_ `Dict' has names for all variables in `Term'.

        - _The following properties should hold at call time:_

          `Term' is any term.   (`basic_props:term/1')

        - _The following properties should hold upon exit:_

          `Dict' is a dictionary of variable names.
          (`vndict:varnamedict/1')

 -- PREDICATE: complete_dict/3:
     *Usage:* `complete_dict(+Dict, +Term, -NewDict)'
        - _Description:_ `NewDict' is `Dict' augmented with the
          variables of `Term' not yet in `Dict'.

 -- PREDICATE: complete_vars_dict/3:
     *Usage:* `complete_vars_dict(+Dict, +Vars, -NewDict)'
        - _Description:_ `NewDict' is `Dict' augmented with the
          variables of the list `Vars' not yet in `Dict'.

 -- PREDICATE: prune_dict/3:
     *Usage:* `prune_dict(+Term, +Dict, -NewDict)'
        - _Description:_ `NewDict' is `Dict' reduced to just the
          variables of `Term'.

 -- PREDICATE: sort_dict/2:
     *Usage:* `sort_dict(D, Dict)'
        - _Description:_ `D' is sorted into `Dict'.

        - _The following properties should hold at call time:_

          `D' is a dictionary of variable names.
          (`vndict:varnamedict/1')

        - _The following properties should hold upon exit:_

          `Dict' is a dictionary of variable names.
          (`vndict:varnamedict/1')

 -- PREDICATE: dict2varnamesl/2:
     *Usage:* `dict2varnamesl(Dict, VNs)'
        - _Description:_ Translates `Dict' to `VNs'.

        - _The following properties should hold at call time:_

          `Dict' is a dictionary of variable names.
          (`vndict:varnamedict/1')

        - _The following properties should hold upon exit:_

          `VNs' is a list of `Name=Var', for a variable `Var' and its
          name `Name'.   (`vndict:varnamesl/1')

 -- PREDICATE: varnamesl2dict/2:
     *Usage:* `varnamesl2dict(VNs, Dict)'
        - _Description:_ Translates `VNs' to `Dict'.

        - _The following properties should hold at call time:_

          `VNs' is a list of `Name=Var', for a variable `Var' and its
          name `Name'.   (`vndict:varnamesl/1')

        - _The following properties should hold upon exit:_

          `Dict' is a dictionary of variable names.
          (`vndict:varnamedict/1')

 -- PREDICATE: find_name/4:
     `find_name(Vars, Names, V, Name)'

     Given that `vars_names_dict(Dict,Vars,Names)' holds, it acts as
     `rename(X,Dict)', but the name of `X' is given as `Name' instead
     of unified with it.

 -- PREDICATE: rename/2:
     *Usage:* `rename(Term, Dict)'
        - _Description:_ Unifies each variable in `Term' with its
          name in `Dict'. If no name is found, a new name is created.

        - _The following properties should hold at call time:_

          `Dict' is a dictionary of variable names.
          (`vndict:varnamedict/1')

 -- REGTYPE: varname/1:
     *Usage:* `varname(N)'
        - _Description:_ `N' is a term representing a variable name.

 -- REGTYPE: varnamesl/1:
     *Usage:* `varnamesl(D)'
        - _Description:_ `D' is a list of `Name=Var', for a variable
          `Var' and its name `Name'.

 -- REGTYPE: varnamedict/1:
     *Usage:* `varnamedict(D)'
        - _Description:_ `D' is a dictionary of variable names.

 -- PREDICATE: vars_names_dict/3:
     *Usage:* `vars_names_dict(Dict, Vars, Names)'
        - _Description:_ `Varss' is a sorted list of variables, and
          `Names' is a list of their names, which correspond in the
          same order.

        - _Call and exit should be _compatible_ with:_

          `Dict' is a dictionary of variable names.
          (`vndict:varnamedict/1')

          `Vars' is a list.   (`basic_props:list/1')

          `Names' is a list.   (`basic_props:list/1')

PART X - Miscellaneous standalone utilities
*******************************************

*Author(s):*  , 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.

   This is the documentation for a set of miscellaneous standalone
utilities contained in the `etc' directory of the Ciao distribution.

167 A Program to Help Cleaning your Directories
***********************************************

*Author(s):* Manuel Carro.

   *Version:* 0.1#3 (2001/10/25, 14:31:59 CEST)

   A simple program for traversing a directory tree and deciding
which files may be deleted in order to save space and not to loose
information.

167.1 Usage (cleandirs)
=======================

     cleandirs [--silent] <initial_dir> <delete_options> <backup_options>
     cleandirs explores <initial_dir> (which should be an absolute path)
     and looks for backup files and files which can be generated from other
     files, using a plausible heuristic aimed at retaining the same amount
     of information while recovering some disk space.  The heuristic is
     based on the extension of the filename.

     Delete options is one of:
        --list: just list the files/directories which are amenable to be deleted,
                but do not delete them. SAFE.
         --ask: list the files/directories and ask for deletion. UNSAFE if you
                make a mistake.
      --delete: just delete the files/directories without asking.  I envy your
                brave soul if you choose this option.

     Backup options is one of:
      --includebackups: include backup files in the list of files to check.
      --excludebackups: do not include backup files in the list of files to check.
         --onlybackups: include only backup files in the list of files to check.

     Symbolic links are not traversed.  Special files are not checked.

   Invoking the program with no arguments will return an up-to-date
information on the options.

167.2 Known bugs and planned improvements (`cleandirs')
=======================================================

   * Recursive removal of subdirectories relies on the existence of a
     recursive /bin/rm command in your system.

168 Printing the declarations and code in a file
************************************************

*Author(s):* Manuel Hermenegildo.

   *Version:* 0.5#6 (1999/4/15, 20:33:6 MEST)

   A simple program for printing assertion information ( predicate
declarations, property declarations, type declarations, etc.) and printing
code-related information ( imports, exports, libraries used, etc.) on
a file. The file should be a single Ciao or Prolog source file. It
uses the Ciao compiler's pass one to do it. This program is specially
useful for example for checking what assertions the assertion
normalizer is producing from the original assertions in the file or
to check what the compiler is actually seeing after some of the
syntactic expansions (but before goal translations).

168.1 Usage (fileinfo)
======================

         fileinfo -asr <filename.asr>
            : pretty prints the contents of <filename.asr>

         fileinfo [-v] [-m] <-a|-f|-c|-e> <filename> [libdir1] ... [libdirN]
         -v : verbose output (e.g., lists all files read)
         -m : restrict info to current module
         -a : print assertions
         -f : print code and interface (imports/exports, etc.)
         -c : print code only
         -e : print only errors - useful to check syntax of assertions in file

         fileinfo -h
            : print this information

         Note that system lib paths *must* be given explicitly, e.g. :

         fileinfo -m -c foo.pl \
                  /home/clip/System/ciao/lib \
                  /home/clip/System/ciao/library \

168.2 More detailed explanation of options (fileinfo)
=====================================================

   * If the `-a' option is selected, `fileinfo' prints the assertions
     (only code-oriented assertions - not comment-oriented
     assertions) in the file _after normalization_. If the `-f'
     option is selected `fileinfo' prints the file interface, the
     declarations contained in the file, and the actual code. The
     `-c' option prints only the code. If the `-e' option is selected
     `fileinfo' prints only any sintactic and import-export errors
     found in the file, including the assertions.

   * `filename' must be the name of a Prolog or Ciao source file.

   * This filename can be followed by other arguments which will be
     taken to be library directory paths in which to look for files
     used by the file being analyzed.

   * If the `-m' option is selected, only the information related to
     the current module is printed.

   * The `-v' option produces verbose output. This is very useful for
     debugging, since all the files accessed during assertion
     normalization are listed.

   * In the `-asr' usage, `fileinfo' can be used to print the
     contents of a `.asr' file in human-readable form.

169 Printing the contents of a bytecode file
********************************************

*Author(s):* Daniel Cabeza.

   *Version:* 0.5#2 (1999/11/11, 19:20:50 MET)

   This simple program takes as an argument a bytecode (.po) file and
prints out in symbolic form the information contained in the file. It
uses compiler and engine builtins to do so, so that it keeps track
with changes in bytecode format.

169.1 Usage (viewpo)
====================

     	viewpo <file1>.po
     	   : print .po contents in symbolic form

     	viewpo -h
     	   : print this information

170 Crossed-references of a program
***********************************

*Author(s):* Francisco Bueno.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#257 (2003/12/30, 23:49:22 CET)

   The `xrefs' crossed-references Ciao library includes several
modules which allow displaying crossed-references of the code in a
program. Crossed-references identify modules which import code from
other modules, or files (be them modules or not) which use code in
other files. Crossed-references can be obtained as a term
representing a graph, displayed graphically (using daVinci, a graph
displayer developed by U. of Bremen, Germany), or printed as a list.

   The libraries involved are as follows:
   * `etc(xmrefs)' displays a graph of crossed-references between
     modules using daVinci,

   * `etc(xfrefs)' displays a graph of crossed-references between
     files using daVinci,

   * `library(xrefs)' obtains a graph of crossed-references between
     files,

   * `library('xrefs/mrefs')' obtains a graph of crossed-references
     between modules,

   * `library('xrefs/pxrefs')' prints a list of crossed-references
     between files.
   The first two are intended to be used by loading in `ciaosh'. The
other three are intended to be used as modules within an application.

   The following is an example graph of the library modules involved
in the crossed-references application. It has been obtained with:
     [ciao/etc]> ciaosh
     Ciao-Prolog 1.5 #24: Tue Dec 28 14:12:11 CET 1999
     ?- use_module(xmrefs).

     yes
     ?- set_flag(X).

     X = 3 ?

     yes
     ?- set_files([xfrefs, xmrefs,
                   library(xrefs),
                   library('xrefs/mrefs'),
                   library('xrefs/pxrefs'),
                   library('xrefs/xrefs2graph'),
                   library('xrefs/xrefsbuild'),
                   library('xrefs/xrefsread')
     	     ]).

     yes
     ?- xmrefs.
   so that it is displayed by daVinci as:

[Image file: autofigxmgraph.eps]

   The following is an example graph of the same module files, where
crossed-references have been obtained with `xfrefs:xfrefs(whodefs)'
instead of `xmrefs:xmrefs':

[Image file: autofigxfgraph.eps]

   For more information refer to the xrefs documentation
(`xrefs_doc.dvi') in the source library of the Ciao distribution.

171 Gathering the dependent files for a file
********************************************

*Author(s):* Daniel Cabeza, Manuel Hermenegildo.

   *Version:* 1.0#6 (1998/11/5, 13:56:58 MET)

   This simple program takes a single Ciao or Prolog source filename
(which is typically the main file of an application). It prints out
the list of all the dependent files, i.e., all files needed in order
to build the application, including those which reside in libraries.
This is particularly useful in Makefiles, for building standalone
distributions (e.g., .tar files) automatically.

   The filename should be followed by other arguments which will be
taken to be library directory paths in which to look for files used
by the file being analyzed.

171.1 Usage (get_deps)
======================

     	get_deps [-u <filename>] <filename> [lib_dir1] ... [lib_dirN]
                : return dependent files for <filename>
                  found in [lib_dir1] ... [lib_dirN]

     	get_deps -h
                : print this information

172 Finding differences between two Prolog files
************************************************

*Author(s):* Francisco Bueno.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#258 (2003/12/30, 23:52:10 CET)

   This simple program works like the good old diff but for files
that contain Prolog code. It prints out the clauses that it finds are
different in the files. Its use avoids textual differences such as
different variable names and different formatting of the code in the
files.

172.1 Usage (pldiff)
====================

     	pldiff <file1> <file2>
     	   : find differences

     	pldiff -h
     	   : print this information

   but you can also use the program as a library and invoke the
predicate:

        pldiff( <filename> , <filename> )

172.2 Known bugs and planned improvements (`pldiff')
====================================================

   * Currently uses variant/2 to compare clauses. This is useful, but
     there should be an option to select the way clauses are
     compared, e.g., some form of equivalence defined by the user.

173 The Ciao lpmake scripting facility
**************************************

*Author(s):* Manuel Hermenegildo, `clip@dia.fi.upm.es',
`http://www.clip.dia.fi.upm.es/', The CLIP Group, Facultad de
Informa'tica, Universidad Polite'cnica de Madrid.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#27 (2002/11/20, 13:4:12 CET)

   *Note:* `lpmake' and the `make' library are still under
development, and they may change in future releases.

   `lpmake' is a Ciao application which uses the Ciao `make' library
to implement a dependency-driven scripts in a similar way to the Un*x `make'
facility.

   The original purpose of the Un*x `make' utility is to determine
automatically which pieces of a large program needed to be
recompiled, and issue the commands to recompile them. In practice, `make'
is often used for many other purposes: it can be used to describe any
task where some files must be updated automatically from others
whenever these change.  `lpmake' can be used for the same types of
applications as `make', and also for some new ones, and, while being
simpler, it offers a number of advantages over `make'. The first one
is _portability_. When compiled to a bytecode executable `lpmake'
runs on any platform where a Ciao engine is available. Also, the fact
that typically many of the operations are programmed in Prolog within
the makefile, not needing external applications, improves portability
further. The second advantage of `lpmake' is _improved programming
capabilities_. While `lpmake' is simpler than `make', `lpmake' allows
using the Ciao Prolog language within the scripts. This allows
establising more complex dependencies and programming powerful
operations within the make file, and without resorting to external
packages (e.g., operating system commands), which also helps
portability. A final advantage of `lpmake' is that it supports a form
of _autodocumentation_: comments associated to targets can be
included in the configuration files. Calling `lpmake' in a directory
which has such a configuration file explains what commands the
configuration file support and what these commands will do.

173.1 General operation
=======================

To prepare to use `lpmake', and in a similar way to `make', you must
write a _configuration file_: a module (typically called `Makefile.pl')
that describes the relationships among files in your program or
application, and states the commands for updating each file. In a
program, typically the executable file is updated from object files,
which are in turn made by compiling source files. Another example is
running `latex' and `dvips' on a set of source `.tex' files to
generate a document in `dvi' and `postscript' formats. Once a
suitable makefile exists, each time you change some source files,
simply typing `lpmake' suffices to perform all necessary operations
(recompilations, processing text files, etc.). The `lpmake' program
uses the dependency rules in the makefile and the last modification
times of the files to decide which of the files need to be updated.
For each of those files, it issues the commands recorded in the
makefile. For example, in the `latex'/ `dvips' case one rule states
that the `.dvi' file whould be updated from the `.tex' files whenever
one of them changes and another rule states that the `.ps' file needs
to be updated from a `.dvi' file every time it changes. The rules
also describe the commands to be issued to update the files.

   So, the general process is as follows: `lpmake' executes commands
in the configuration file to update one or more target _names_, where
_name_ is often a program, but can also be a file to be generated or
even a "virtual" target.  `lpmake' updates a target if it depends on
prerequisite files that have been modified since the target was last
modified, or if the target does not exist. You can provide command
line arguments to `lpmake' to control which files should be
regenerated, or how.

173.2 Format of the Configuration File
======================================

`lpmake' uses as default configuration file the file `Makefile.pl',
if it is present in the current directory. This can be overridden and
another file used by means of the `-m' option. The configuration file
must a _module_ that uses the `make' package. This package provides
syntax for defining the dependency rules and functionality for
correctly interpreting these rules. The configuration files can
contain such rules and also arbitrary Ciao Prolog predicates. The
syntax of the rules is described in The Ciao Make Package,
together with some examples.

173.3 lpmake usage
==================

     Supported command line options:

     lpmake [-v] <command1> ... <commandn>

       Process commands <command1> ... <commandn>, using
       file 'Makefile.pl' in the current directory as
       configuration file. The configuration file must
       be a module. This is useful to implement
       inherintance across diferent configuration files,
       i.e., the values declared in a configuration file
       can be easily made to override those defined in
       another.

       The optional argument '-v' produces verbose output,
       reporting on the processing of the dependency rules.
       Very useful for debugging Makefiles.

     lpmake [-v] [-m <.../Configfile.pl>] <command1> ... <commandn>

       Same as above, but using file <.../Configfile.pl>
       as configuration file.

     lpmake -h     [ -m <.../Configfile.pl> ]
     lpmake -help  [ -m <.../Configfile.pl> ]

       Print this help message. If a configuration file is given,
       and the commands in it are commented, then information on
       these commands is also printed.

173.4 Acknowledgments (`lpmake')
================================

Some parts of the documentation are taken from the documentation of
GNU's `gmake'.

174 Find out which architecture we are running on
*************************************************

*Author(s):* Manuel Carro, Robert Manchek.

   *Version:* 0.0#6 (2001/3/26, 13:56:52 CEST)

   The architecure and operating system the engine is compiled for
determines whether we can use or not certain libraries. This script,
taken from a PVM distribution, uses a heuristic (which may need to be
tuned from time to time) to find out the platform. It returns a
string which is used throughout the engine (in #ifdefs) to
enable/disable certain characteristics.

174.1 Usage (ciao_get_arch)
===========================

        Usage: ciao_get_arch

174.2 More details
==================

Look at the script itself...

175 Print out WAM code
**********************

*Author(s):* Manuel Carro.

   *Version:* 0.5 (2003/1/20, 17:12:6 CET)

   This program prints to standard output a symbolic form of the
(modified) Wam code the compiler generates for a given source file.
Directives are ignored.

175.1 Usage (compiler_output)
=============================

             Print (modified, partial) WAM code for a .pl file

             Usage: compiler_output <file.pl>

PART XI - Contributed libraries
*******************************

*Author(s):* The CLIP Group.

   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.

176 Programming MYCIN rules
***************************

*Author(s):* Angel Fernandez Pineda.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.5#59 (2000/2/29, 14:51:54 CET)

   MYCIN databases are declared as Prolog modules containing mycin
rules. Those rules are given a _certainty factor_ (_CF_) which
denotates an expert's credibility on that rule:
   * A value of -1 stands for _surely not_.

   * A value of 1 stands for _certainly_.

   * A value of 0 stands for _I don't know_.

   Intermediate values are allowed.

   Mycin rules work on a different way as Prolog clauses: a rule will
never fail (in the Prolog sense), it will return a certainty value
instead. As a consequence *all* mycin rules will be explored during
inference, so the order in which rules are written is not
significant. For this reason, the usage of the Prolog _cut_ (!) is
discouraged.

176.1 Usage and interface (`mycin')
===================================

   * *Library usage:*

     In order to declare a mycin database you must include the
     following declaration as the first one in your file:
                     :- mycin(MycinDataBaseName).

   * *New declarations defined:*

     `export/1'.

176.2 Documentation on new declarations (`mycin')
=================================================

 -- DECLARATION: export/1:
     This directive allows a given mycin predicate to be called from
     Prolog programs. The way in which mycin rules are called departs
     from Prolog ones. For instance, the followin mycin predicate:
          :- export p/1.

     must be called from Prolog Programs as: `mycin(p(X),CF)', where
     CF will be binded to the resulting certainty factor. Obviously,
     the variables on _P/1_ may be instantiated as you wish. Since
     the Prolog predicate _mycin/2_ may be imported from several
     mycin databases, it is recommended to fully qualify those
     predicate goals. For example : `mydatabase:mycin(p(X),CF)'.

     *Usage:* :- `export(Spec)'.
        - _Description:_ `Spec' will be a callable mycin predicate.

176.3 Known bugs and planned improvements (`mycin')
===================================================

   * Not fully implemented.

   * Dynamic mycin predicates not implemented: open question.

   * Importation of user-defined mycin predicates requires further
     design. This includes importation of mycin databases from
     another mycin database.

177 Constraint programming over finite domains
**********************************************

*Author(s):* J.M. Gomez, M. Carro.

   This package allows to write and evaluate constraint programming
expressions over finite domains in a Ciao program. It is based upon
the indexicals concept.

   The syntax of this constraint system is described below:

   * _c ::= X in r_ (_r_ is the range of variable _X_).

   * _c ::= E1 .=. E2_ (eventual value of expression _E1_ equals _E2_)

   * _c ::= E1 .<>. E2_ (_E1_ differs from _E2_)

   * _c ::= E1 .<. E2_ (_E1_ is lower than _E2_)

   * _c ::= E1 .>. E2_ (_E1_ is greater than _E2_)

   * _c ::= E1 .=<. E2_ (_E1_ is lower or equal than _E2_)

   * _c ::= E1 .>=. E2_ (_E1_ is greater or equal than _E2_)

   * _r ::= r1_ (one interval range).

   * _r ::= r1 .&. r_ (multi interval range).

   * _r1 ::= t..t_ (interval range).

   * _r1 ::= dom(X)_ (indexical domain, e.g., _X in dom(Y)_ means _"X
     in the domain of Y"_).

   * _t::= n_ (integer).

   * _t::= min(X)_ (indexical min).

   * _t::= max(X)_ (indexical max).

Some examples of this constraints package (more can be found in the
source and library directories):

   * SEND + MORE = MONEY:

     :- use_package(fd).
     :- use_module(library(prolog_sys), [statistics/2]).
     :- use_module(library(format)).

     smm(SMM) :-
             statistics(runtime,_),
             do_smm(SMM),
             statistics(runtime,[_, Time]),
             format("Used ~d milliseconds~n", Time).

     do_smm(X) :-
             X = [S,E,N,D,M,O,R,Y],
             X in 0 .. 9,
             all_different(X),
             M .>. 0,
             S .>. 0,
             1000*S + 100*E + 10*N + D + 1000*M + 100*O + 10*R + E .=. 10000*M + 1000*O + 100*N + 10*E + Y,
            labeling(X).

   * Queens:

     :- use_package(fd).
     :- use_module(library(prolog_sys), [statistics/2]).
     :- use_module(library(format)).
     :- use_module(library(aggregates)).
     :- use_module(library(lists),[length/2]).

     queens(N, Qs) :-
             statistics(runtime,_),
             do_queens(N, Qs),
             statistics(runtime,[_, Time]),
             format("Used ~d milliseconds~n", Time).

     do_queens(N, Qs):-
             constrain_values(N, N, Qs),
             all_different(Qs),!,
             labeling(Qs).

     constrain_values(0, _N, []).
     constrain_values(N, Range, [X|Xs]):-
             N > 0,
             X in 1 .. Range,
             N1 is N - 1,
             constrain_values(N1, Range, Xs),
             no_attack(Xs, X, 1).

     no_attack([], _Queen, _Nb).
     no_attack([Y|Ys], Queen, Nb):-
             Nb1 is Nb + 1,
             no_attack(Ys, Queen, Nb1),
             Queen .<>. Y + Nb,
             Queen .<>. Y - Nb.

177.1 Usage and interface (`fd')
================================

   * *Library usage:*

     `:- use_package(fd).'

     or

     `:- module(...,...,[fd]).'

   * *Exports:*
        - _Predicates:_

          `labeling/1', `pitm/2', `choose_var/3', `choose_free_var/2', `choose_var_nd/2', `choose_value/2', `retrieve_range/2', `retrieve_store/2', `glb/2', `lub/2', `bounds/3', `retrieve_list_of_values/2'.

        - _Regular Types:_

          `fd_item/1', `fd_range/1', `fd_subrange/1', `fd_store/1', `fd_store_entity/1'.

   * *New operators defined:*

     `.=./2' [700,xfx], `.<>./2' [700,xfx], `.<./2' [700,xfx], `.=<./2'
     [700,xfx], `.>./2' [700,xfx], `.>=./2' [700,xfx], `../2'
     [500,yfx], `.' [600,xfy], `in/2' [700,xfy].

177.2 Documentation on exports (`fd')
=====================================

 -- REGTYPE: fd_item/1:
     *Usage:* `fd_item(FD_item)'
        - _Description:_ `FD_item' is a finite domain entity, i.e.
          either a finite domains variable or an integer.

 -- REGTYPE: fd_range/1:
     *Usage:* `fd_range(FD_range)'
        - _Description:_ `FD_range' is the range of a finite domain
          entity.

 -- REGTYPE: fd_subrange/1:
     *Usage:*
        - _Description:_ A subrange is a pair representing a single
          interval.

 -- REGTYPE: fd_store/1:
     *Usage:* `fd_store(FD_store)'
        - _Description:_ `FD_store' is a representation of the
          constraint store of a finite domain entity.

 -- REGTYPE: fd_store_entity/1:
     *Usage:*
        - _Description:_ Representation of primitive constraints.

 -- PREDICATE: labeling/1:
     *Usage:* `labeling(Vars)'
        - _Description:_ Implements the labeling process. Assigns
          values to the input variables `Vars'. On exit all variables
          are instantiated to a consistent value. On backtracking,
          the predicate returns all possible assignments. No labeling
          heuristics implemented so far, i.e. variables are
          instantiated in their order of appearance.

        - _The following properties should hold at call time:_

          `Vars' is a list of `fd_item's.   (`basic_props:list/2')

 -- PREDICATE: pitm/2:
     *Usage:* `pitm(+V, -MiddlePoint)'
        - _Description:_ Returns in `MiddlePoint' the intermediate
          value of the range of `V'. In case `V' is a ground integer
          value the returned value is `V' itself.

        - _The following properties should hold at call time:_

          `+V' is a finite domain entity, i.e. either a finite
          domains variable or an integer.   (`user(...
          /fd_doc):fd_item/1')

          `-MiddlePoint' is an integer.   (`basic_props:int/1')

 -- PREDICATE: choose_var/3:
     *Usage:* `choose_var(+ListOfVars, -Var, -RestOfVars)'
        - _Description:_ Returns a finite domain item `Var' from a
          list of fd items `ListOfVars' and the rest of the list
          `RestOfVars'in a deterministic way. Currently it always
          returns the first item of the list.

        - _The following properties should hold at call time:_

          `+ListOfVars' is a list of `fd_item's.
          (`basic_props:list/2')

          `-Var' is a finite domain entity, i.e. either a finite
          domains variable or an integer.   (`user(...
          /fd_doc):fd_item/1')

          `-RestOfVars' is a list of `fd_item's.
          (`basic_props:list/2')

 -- PREDICATE: choose_free_var/2:
     *Usage:* `choose_free_var(+ListOfVars, -Var)'
        - _Description:_ Returns a free variable `Var' from a list of
          fd items `ListOfVars'. Currently it always returns the
          first free variable of the list.

        - _The following properties should hold at call time:_

          `+ListOfVars' is a list of `fd_item's.
          (`basic_props:list/2')

          `-Var' is a free variable.   (`term_typing:var/1')

 -- PREDICATE: choose_var_nd/2:
     *Usage:* `choose_var_nd(+ListOfVars, -Var)'
        - _Description:_ Returns non deterministically an fd item
          `Var' from a list of fd items `ListOfVars' .

        - _The following properties should hold at call time:_

          `+ListOfVars' is a list of `fd_item's.
          (`basic_props:list/2')

          `-Var' is a finite domain entity, i.e. either a finite
          domains variable or an integer.   (`user(...
          /fd_doc):fd_item/1')

 -- PREDICATE: choose_value/2:
     *Usage:* `choose_value(+Var, -Value)'
        - _Description:_ Produces an integer value `Value' from the
          domain of `Var'. On backtracking returns all possible
          values for `Var'.

        - _The following properties should hold at call time:_

          `+Var' is a finite domain entity, i.e. either a finite
          domains variable or an integer.   (`user(...
          /fd_doc):fd_item/1')

          `-Value' is an integer.   (`basic_props:int/1')

 -- PREDICATE: retrieve_range/2:
     *Usage:* `retrieve_range(+Var, -Range)'
        - _Description:_ Returns in `Range' the range of an fd item
          `Var'.

        - _The following properties should hold at call time:_

          `+Var' is a free variable.   (`term_typing:var/1')

          `-Range' is the range of a finite domain entity.
          (`user(... /fd_doc):fd_range/1')

 -- PREDICATE: retrieve_store/2:
     *Usage:* `retrieve_store(+Var, -Store)'
        - _Description:_ Returns in `Store' a representation of the
          constraint store of an fd item `Var'.

        - _The following properties should hold at call time:_

          `+Var' is a free variable.   (`term_typing:var/1')

          `-Store' is a representation of the constraint store of a
          finite domain entity.   (`user(... /fd_doc):fd_store/1')

 -- PREDICATE: glb/2:
     *Usage:* `glb(+Var, -LowerBound)'
        - _Description:_ Returns in `LowerBound' the lower bound of
          the range of `Var'.

        - _The following properties should hold at call time:_

          `+Var' is a finite domain entity, i.e. either a finite
          domains variable or an integer.   (`user(...
          /fd_doc):fd_item/1')

          `-LowerBound' is an integer.   (`basic_props:int/1')

 -- PREDICATE: lub/2:
     *Usage:* `lub(+Var, -UpperBound)'
        - _Description:_ Returns in `UpperBound' the upper bound of
          the range of `Var'.

        - _The following properties should hold at call time:_

          `+Var' is a finite domain entity, i.e. either a finite
          domains variable or an integer.   (`user(...
          /fd_doc):fd_item/1')

          `-UpperBound' is an integer.   (`basic_props:int/1')

 -- PREDICATE: bounds/3:
     *Usage:* `bounds(+Var, -LowerBound, -UpperBound)'
        - _Description:_ Returns in `LowerBound' and `UpperBound' the
          lower and upper bounds of the range of `Var'.

        - _The following properties should hold at call time:_

          `+Var' is a finite domain entity, i.e. either a finite
          domains variable or an integer.   (`user(...
          /fd_doc):fd_item/1')

          `-LowerBound' is an integer.   (`basic_props:int/1')

          `-UpperBound' is an integer.   (`basic_props:int/1')

 -- PREDICATE: retrieve_list_of_values/2:
     *Usage:* `retrieve_list_of_values(+Var, -ListOfValues)'
        - _Description:_ Returns in `ListOfValues' an enumeration of
          al the values in the range of `Var'

        - _The following properties should hold at call time:_

          `+Var' is a finite domain entity, i.e. either a finite
          domains variable or an integer.   (`user(...
          /fd_doc):fd_item/1')

          `-ListOfValues' is a list of `int's.
          (`basic_props:list/2')

178 XDR handle library
**********************

*Author(s):* José Manuel Gómez Pérez.

   This library offers facilities to enable users to setup
preferences on the values an eventual XML document may take. XML
documents are specified by XDR documents (eXternal Data
Representation standard), in a way conceptually similar to that of
objects and classes in object oriented programming. These facilities
allow to take as input an XDR Schema defining the class of documents
of interest, and establish a dialogue with the user via an HTML form
that allows the user to setup preferences to select sub-classes of
documents (those which satisfy the preferences). The preferences are
the output of the process and may be in the form of XPath
expressions, for example, as can be seen in the example attached in
the "examples" directory.

178.1 Usage and interface (`xdr_handle')
========================================

   * *Library usage:*

     `:- use_module(library(xdr_handle)).'

   * *Exports:*
        - _Predicates:_

          `xdr_tree/3', `xdr_tree/1', `xdr2html/4', `xdr2html/2', `unfold_tree/2', `unfold_tree_dic/3', `xdr_xpath/2'.

        - _Regular Types:_

          `xdr_node/1'.

   * *Other modules used:*
        - _System library modules:_

          `pillow/http', `pillow/html', `pillow/pillow_types', `xdr_handle/xdr_types', `aggregates', `lists', `terms'.

178.2 Documentation on exports (`xdr_handle')
=============================================

 -- PREDICATE: xdr_tree/3:
     *Usage:* `xdr_tree(+XDR_url, -XDR_tree, -XDR_id)'
        - _Description:_ Parses an XDR (External Data Representation
          Standard) located at an url `XDR_url' into a tree
          structured Prolog term `XDR_tree'. It also returns an
          identifier of the XDR_tree `XDR_id' corresponding to the
          sequence of nodes in the tree (this is intended to be a
          hook to use in CGI applications).

        - _The following properties should hold at call time:_

          `+XDR_url' specifies a URL.   (`pillow_types:url_term/1')

          `-XDR_tree' specifies an XDR document.   (`xdr_types:xdr/1')

          `-XDR_id' is an integer.   (`basic_props:int/1')

 -- PREDICATE: xdr_tree/1:
     *Usage:* `xdr_tree(XDR_tree)'
        - _Description:_ Checks the correctness of an XDR tree
          `XDR_tree'.

        - _The following properties should hold at call time:_

          `XDR_tree' specifies an XDR document.   (`xdr_types:xdr/1')

 -- REGTYPE: xdr_node/1:
     *Usage:* `xdr_node(XDR_node)'
        - _Description:_ `XDR_node' is a XDR tree node.

 -- PREDICATE: xdr2html/4:
     *Usage:* `xdr2html(+XDRTree, -HTMLOutput, -UnfoldedTree, -Dic)'
        - _Description:_ Receives an XDR tree `XDRTree' and produces
          the corresponding HTML code `HTMLOutput', an equivalente
          unfolded plain tree `UnfoldedTree' and a control dictionary
          `Dic' to hold a reference the evenutal fom objects.

        - _The following properties should hold at call time:_

          `+XDRTree' specifies an XDR document.   (`xdr_types:xdr/1')

          `-HTMLOutput' is a term representing HTML code.
          (`pillow_types:html_term/1')

          `-UnfoldedTree' specifies an XDR document.
          (`xdr_types:xdr/1')

          `-Dic' is a dictionary of values of the attributes of a
          form. It is a list of `form_assignment'
          (`pillow_types:form_dict/1')

 -- PREDICATE: xdr2html/2:
     *Usage:* `xdr2html(+XDRTree, -HTMLOutput)'
        - _Description:_ Receives an XDR tree `XDRTree' and produces
          the corresponding HTML code `HTMLOutput'. This html code is
          intended to be part of a form used as a means by which an
          eventual user can give value to an instance of the XDR,
          i.e. an XML element.

        - _The following properties should hold at call time:_

          `+XDRTree' specifies an XDR document.   (`xdr_types:xdr/1')

          `-HTMLOutput' is a term representing HTML code.
          (`pillow_types:html_term/1')

 -- PREDICATE: unfold_tree/2:
     *Usage:* `unfold_tree(+XDRTree, -UFT)'
        - _Description:_ Obtains an unfolded XDR tree `UFT' from a
          standard XDR tree `XDRTree', i.e. an XDR tree where all
          references to XDR elements have been substituted with the
          elements themselves. Especially useful for eventual
          generation of equivalent XPATH expressions, (see example).

        - _The following properties should hold at call time:_

          `+XDRTree' specifies an XDR document.   (`xdr_types:xdr/1')

          `-UFT' specifies an XDR document.   (`xdr_types:xdr/1')

 -- PREDICATE: unfold_tree_dic/3:
     *Usage:* `unfold_tree_dic(+XDRTree, -UFT, -Dic)'
        - _Description:_ Obtains an unfolded XDR tree `UFT' and a
          form dictionary `Dic' from a standard XDR tree `XDRTree'.
          Especially useful for HTML form data exchange (see example).

        - _The following properties should hold at call time:_

          `+XDRTree' specifies an XDR document.   (`xdr_types:xdr/1')

          `-UFT' specifies an XDR document.   (`xdr_types:xdr/1')

          `-Dic' is a dictionary of values of the attributes of a
          form. It is a list of `form_assignment'
          (`pillow_types:form_dict/1')

 -- PREDICATE: xdr_xpath/2:
     *Usage:* `xdr_xpath(+XDRTree, -XPath)'
        - _Description:_ Produces an XPATH expression `XPath' from an
          XDR tree `XDRTree'. If the given XDR tree has no definite
          value the xpath expression produced will be empty

        - _The following properties should hold at call time:_

          `+XDRTree' specifies an XDR document.   (`xdr_types:xdr/1')

          `-XPath' is an atom.   (`basic_props:atm/1')

179 XML query library
*********************

*Author(s):* José Manuel Gómez Pérez.

   *Version:* 0.1 (2003/12/1, 13:24:9 CET)

   This package provides a language suitable for querying XML
documents from a Prolog program. Constraint programming expresions
can be included in order to prune search as soon as possible, i.e.
upon constraint unsatisfability, improving efficiency. Also,
facilities are offerd to improve search speed by transforming XML
documents into Prolog programs, hence reducing search to just running
the program and taking advantage of Prolog's indexing capabilities.

   Queries in an XML document have a recursive tree structructure
that permits to detail the search on the XML element sought, its
attributes, and its children. As a suffix, a constraint programming
expression can be added. Queries return value for the free variables
included (in case of success), and checks whether the XML document
structure matches that depicted by the query itself.

   The operators introduced are described below:

   * _@_ Delimits a subquery on an elment's attribute, such as
     `product@val(product_name, "car")', the first argument being the
     attribute name and the second its value. Any of them can be free
     variables, being possible to write queries like
     `product@val(Name, "car")', intended to find the 'Name' of
     attributes of element product whose value is the string "car".

   * _::_ The right-hand side of the subexpression delimited by this
     operator is a query on the children elements of the element
     described on its left-hand side.

   * _with_ Declares the constraints the items sought must satisfy.

   Some examples of this query language (more can be found in the
examples directory):

   * Example A:

     product@val(product_name,"car")::(quantity(X),
                                       'time-left'(Y),
                                       negotiation::preference::price(Z))
            with X * Z .>. Y

   * Example B:

     nitf::head::docdata::'doc-id'@val('id-string',"020918050")::(Y),
                          body::'body.head'::abstract::p(X)

179.1 Usage and interface (`xml_path')
======================================

   * *Library usage:*

     `:- use_package(xml_path).'

     or

     `:- module(...,...,[xml_path]).'

   * *Exports:*
        - _Predicates:_

          `xml_search/3', `xml_parse/3', `xml_parse_match/3', `xml_search_match/3', `xml_index_query/3', `xml_index_to_file/2', `xml_index/1', `xml_query/3'.

   * *New operators defined:*

     `@/2' [200,yfx], `::/2' [300,xfy], `with/2' [800,yfx].

   * *Other modules used:*
        - _System library modules:_

          `xml_path/xml_path_types'.

179.2 Documentation on exports (`xml_path')
===========================================

 -- PREDICATE: xml_search/3:
     *Usage:* `xml_search(+Query, +Source, -Doc)'
        - _Description:_ Checks a high level query `Query' against an
          XML document `Source'. If the query is successful it retuns
          in `Doc' the whole xml element(s) of the document that
          matched it.

        - _The following properties should hold at call time:_

          `+Query' is a primitive XML query.
          (`xml_path_types:canonic_xml_query/1')

          `+Source' is either a XML attribute, a XML element or a
          line break.   (`xml_path_types:canonic_xml_item/1')

          `-Doc' is either a XML attribute, a XML element or a line
          break.   (`xml_path_types:canonic_xml_item/1')

 -- PREDICATE: xml_parse/3:
     *Usage:* `xml_parse(+Query, +Source, -Doc)'
        - _Description:_ Checks a high level query `Query' against an
          XML document `Source'. If the query is successful it retuns
          in `Doc' the whole xml element(s) of the document that
          matched it. On the contrary as `xml_search/3', the query
          can start at any level of the XML document, not necessarily
          at the root node.

        - _The following properties should hold at call time:_

          `+Query' is a primitive XML query.
          (`xml_path_types:canonic_xml_query/1')

          `+Source' is either a XML attribute, a XML element or a
          line break.   (`xml_path_types:canonic_xml_item/1')

          `-Doc' is either a XML attribute, a XML element or a line
          break.   (`xml_path_types:canonic_xml_item/1')

 -- PREDICATE: xml_parse_match/3:
     *Usage:* `xml_parse_match(+Query, +Source, -Match)'
        - _Description:_ Checks a high level query `Query' against an
          XML document `Source'. If the query is successful it retuns
          in `Doc' the exact subtree of the xml document that matched
          it. On the contrary as `'$xml_search_match/3', the query
          can start at any level of the XML document, not necessarily
          at the root node.

        - _The following properties should hold at call time:_

          `+Query' is a primitive XML query.
          (`xml_path_types:canonic_xml_query/1')

          `+Source' is either a XML attribute, a XML element or a
          line break.   (`xml_path_types:canonic_xml_item/1')

          `-Match' is either a XML attribute, a XML element or a line
          break.   (`xml_path_types:canonic_xml_item/1')

 -- PREDICATE: xml_search_match/3:
     *Usage:* `xml_search_match(+BasicQuery, +SourceDoc, -Match)'
        - _Description:_ Checks query `Query' against an XML document
          `Source'. If the query is successful it retuns in `Doc' the
          exact subtree of the xml document that matched it.

        - _The following properties should hold at call time:_

          `+BasicQuery' is a primitive XML query.
          (`xml_path_types:canonic_xml_query/1')

          `+SourceDoc' is either a XML attribute, a XML element or a
          line break.   (`xml_path_types:canonic_xml_item/1')

          `-Match' is either a XML attribute, a XML element or a line
          break.   (`xml_path_types:canonic_xml_item/1')

 -- PREDICATE: xml_index_query/3:
     *Usage:* `xml_index_query(+Query, -Id, -Match)'
        - _Description:_  Matches a high level query `Query' against
          an XML document previously transformed into a Prolog
          program. `Id' identifies the resulting document `Match',
          which is the exact match of the query against the XML
          document.

        - _The following properties should hold at call time:_

          `+Query' is a primitive XML query.
          (`xml_path_types:canonic_xml_query/1')

          `-Id' is an atom.   (`basic_props:atm/1')

          `-Match' is either a XML attribute, a XML element or a line
          break.   (`xml_path_types:canonic_xml_item/1')

 -- PREDICATE: xml_index_to_file/2:
     *Usage:* `xml_index_to_file(SourceDoc, File)'
        - _Description:_ Transforms the XML document `SourceDoc' in a
          Prolog program which is output to file `File'.

        - _The following properties should hold at call time:_

          `SourceDoc' is either a XML attribute, a XML element or a
          line break.   (`xml_path_types:canonic_xml_item/1')

          `File' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: xml_index/1:
     *Usage:* `xml_index(SourceDoc)'
        - _Description:_ Transforms the XML document `SourceDoc' in a
          Prolog program, generating the associated clauses, which
          are stored dynamically into the current process memory
          space.

        - _The following properties should hold at call time:_

          `SourceDoc' is either a XML attribute, a XML element or a
          line break.   (`xml_path_types:canonic_xml_item/1')

 -- PREDICATE: xml_query/3:
     *Usage:* `xml_query(+Query, +Doc, -Match)'
        - _Description:_ Checks that XML document `Doc' is compliant
          with respect to the query `Query' expressed in the low
          level query language. The exact mapping of the query over
          the document is returned in `Match'

        - _The following properties should hold at call time:_

          `+Query' is a primitive XML query.
          (`xml_path_types:canonic_xml_query/1')

          `+Doc' is either a XML attribute, a XML element or a line
          break.   (`xml_path_types:canonic_xml_item/1')

          `-Match' is either a XML attribute, a XML element or a line
          break.   (`xml_path_types:canonic_xml_item/1')

179.3 Documentation on internals (`xml_path')
=============================================

 -- REGTYPE: canonic_xml_term/1:
     *Usage:* `canonic_xml_term(XMLTerm)'
        - _Description:_ `XMLTerm' is a term representing XML code in
          canonical form.

 -- REGTYPE: canonic_xml_item/1:
     *Usage:* `canonic_xml_item(XMLItem)'
        - _Description:_ `XMLItem' is either a XML attribute, a XML
          element or a line break.

 -- REGTYPE: tag_attrib/1:
     *Usage:* `tag_attrib(Att)'
        - _Description:_ `Att' is a XML attribute.

 -- REGTYPE: canonic_xml_query/1:
     *Usage:* `canonic_xml_query(Query)'
        - _Description:_ `Query' is a primitive XML query.

 -- REGTYPE: canonic_xml_subquery/1:
     *Usage:* `canonic_xml_subquery(SQuery)'
        - _Description:_ `SQuery' defines a XML subquery.

180 A Chart Library
*******************

*Author(s):* Isabel Mart'n Garc'a.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#154 (2003/12/4, 17:39:3 CET)

   This library is intended to eaose the task of displaying some
graphical results. This library allows the programmer to visualize
different graphs and tables without knowing anything about specific
graphical packages.

   You need to install the BLT package in your computer. BLT is an
extension to the Tk toolkit and it does not require any patching of
the Tcl or Tk source files. You can find it in
`http://www.tcltk.com/blt/index.html'

   Basically, when the user invokes a predicate, the library
(internally) creates a bltwish interpreter and passes the information
through a socket to display the required widget. The interpreter
parses the received commands and executes them.

   The predicates exported by this library can be classified in four
main groups, according to the types of representation they provide.

   * bar charts

   * line graphs

   * scatter graphs

   * tables

   To represent graphs, the Cartesian coordinate system is used. I
have tried to show simple samples for every library exported
predicate in order to indicate how to call them.

180.1 Bar charts
================

In this section we shall introduce the general issues about the set
of barchart predicates. By calling the predicates that pertain to
this group a bar chart for plotting two-dimensional data (X-Y
coordinates) can be created. A bar chart is a graphic means of
comparing numbers by displaying bars of lengths proportional to the
y-coordinates they represented. The barchart widget has many
configurable options such as title, header text, legend and so on.
You can configure the appearance of the bars as well. The bar chart
widget has the following components:

Header text
     The text displayed at the top of the window. If it is `''' no
     text will be displayed.

Save button
     The button placed below the header text. Pops up a dialog box
     for the user to select a file to save the graphic in PostScript
     format.(1)

Bar chart title
     The title of the graph. It is displayed at the top of the bar
     chart graph. If text is `''' no title will be displayed.

X axis title
     X axis title. If text is `''' no x axis title will be displayed.

Y axis title
     Y axis title. If text is `''' no y axis title will be displayed.

X axis
     X coordinate axis. The x axis is drawn at the bottom margin of
     the bar chart graph. The x axis consists of the axis line, ticks
     and tick labels. Tick labels can be numbers or plain text. If
     the labels are numbers, they could be displayed at uniform
     intervals (the numbers are treated as normal text) or depending
     on its x-coodinate value. You can also set limits (maximum and
     minimum) for the x axis, but only if the tick labels are numeric.

Y axis
     Y coordinate axis. You can set limits (maximum and minimum) for
     the y axis. The y axis is drawn at the right margin of the bar
     chart graph.The y axis consists of the axis line, ticks and tick
     labels. The tick labels are numeric values determined from the
     data and are drawn at uniform intervals.

Bar chart graph
     This is the plotting area, placed in the center of the window
     and surrounded by the axes, the axis titles and the legend (if
     any). The range of the axes controls what region of the data is
     plotted. By default, the minimum and maximum limits are
     determined from the data, but you can set them (as mentioned
     before). Data points outside the minimum and maximum value of
     the axes are not plotted.

Legend
     The legend displays the name and symbol of each bar. The legend
     is placed in the right margin of the Bar chart graph.

Footer text
     Text displayed at the lower part of the window. If text is `'''
     no header text will be displayed.

Quit button
     Button placed below the footer text. Click it to close the
     window.

   All of them are arranged in a window. However you can, for
example, show a bar chart window without legend or header text. Other
configuration options will be explained later.

   In addition to the window appearance there is another important
issue about the bar chart window, namely its behaviour in response to
user actions. The association user actions to response is called
_bindings_. The main bindings currently specified are the following:

Default bindings
     Those are well known by most users. They are related to the
     frame displayed around the window. As you know, you can
     interactively move, resize, close, iconify, deiconify, send to
     another desktop etc. a window.

Bindings related to bar chart graph and its legend
     Clicking the left mouse key over a legend element, the
     corresponding bar turns out into red. After clicking again, the
     bar toggles to its original look. In addition, you can do
     zoom-in by pressing the left mouse key over the bar chart graph
     and dragging to select an area. To zoom out simply press the
     right mouse button.

     When the pointer passes over the plotting area the cross hairs
     are drawn. The cross hairs consists of two intersecting lines
     (one vertical and one horizontal). Besides, if the pointer is
     over a legend element, its background changes.

Bindings related to buttons
     There are two buttons in the main widget. Clicking the mouse on
     the Save button a "Save as" dialog box is popped up. The user
     can select a file to save the graph. If the user choose a file
     that already exists, the dialog box prompts the user for
     confirmation on whether the existing file should be overwritten
     or not. Furthermore, you can close the widget by clicking on the
     Quit button.

     When the pointer passes over a button the button color changes.

   The predicates that belong to this group are those whose names
begin with *barchart* and *genmultibar*. If you take a look at the
predicate names that pertain to this group, you will notice that they
are not self-explanatory. It would have been better to name the
predicates in a way that allows the user to identify the predicate
features by its name, but it would bring about very long names (i.e
barchart_WithoutLegend_BarsAtUniformIntervals_RandomBarsColors). For
this reason I decided to simply add a number after barchart to name
them.

   ---------- Footnotes ----------

   (1) Limitation: Some printers can have problems if the PostScript
file is too complex (i.e. too many points/lines appear in the
picture).

180.2 Line graphs
=================

It is frequently the case that several datasets need to be displayed
on the same plot. If so, you may wish to distinguish the points in
different datasets by joining them by lines of different color, or by
plotting with symbols of different types. This set of predicates
allows the programmer to represent two-dimensional data (X-Y
coordinates). Each dataset contains x and y vectors containing the
coordinates of the data. You can configure the appearance of the
points and the lines which the points are connected with. The
configurable line graph components are:

line graph
     This is the plotting area, placed in the center of the window
     and surrounded by the axes, the axes titles and the legend (if
     any). The range of the axes controls what region of the data is
     plotted. By default, the minimum and maximum limits are
     determined from the data, but you can set them. Data points
     outside the minimum and maximum value of the axes are not
     plotted. You can specify how connecting line segments joining
     successive datapoints are drawn by setting the `Smooth'
     argument. Smooth can be either linear, step, natural and
     quadratic. Furthermore, you can select the appearance of the
     points and lines.

Legend
     The legend displays the name and symbol of each line. The legend
     is placed in the right margin of the graph.

   The elements header, footer, quit and save buttons, the titles and
the axes are quite similar to those in barchart graphs, except in
that the tick labels will be numbers. All of them are arranged in a
window by the geometry manager. However you can, as we mentioned in
the above paragraphs, show a line graph window without any titles or
footer text. Other configuration options will be explained later in
this section or in the corresponding modules.

   Related to the behaviour of the widgets in response to user
actions (bindings) we will remark the following features:

Bindings related to line graph and its legend
     Clicking the left mouse key over a legend element, the
     corresponding line turns out into blue. Repeating the action
     reverts the line to its original color. Moreover, you can do
     zoom-in by clicking the left mouse key over the bar chart graph
     and dragging a rectangle defining the area you want to zoom in.
     To zoom out simply press the right mouse button.

     When the pointer passes over the plotting area the cross hairs
     are drawn. The cross hairs consists of two intersecting lines
     (one vertical and one horizontal). Besides, if the pointer is
     over a legend element, its background changes.

Other bindings
     The default bindings and the bindings related to the save and
     quit buttons are similar to those in the bar chart graphs.

   The predicates that belong to this group are those whose names
begin with *graph_*.

180.3 Scatter graphs
====================

The challenge of this section is to introduce some general aspects
about the scatter graph predicates group. By invoking the scatter
graph predicates the user can represent two-dimensional point
datasets. Often you need to display one or several point datasets on
the same plot. If so, you may wish to distinguish the points that
pertain to different datasets by using plotting symbols of different
types, or by displaying them in different colors. This set of
predicates allows you to represent two-dimensional data (X-Y
coordinates). Each dataset contains x and y vectors containing the
coordinates of the data. You can configure the appearance of the
points. The configurable scatter graph components are:

scatter graph
     This is the plotting area, placed in the center of the window
     and surrounded by the axes, the axes titles and the legend (if
     any). The range of the axes controls what region of the data is
     plotted. By default, the minimum and maximum limits are
     determined from the data, but you can set them (as we mentioned
     before). Data points outside the minimum and maximum value of
     the axes are not plotted. The user can select the appearance of
     the points.

Legend
     The legend displays the name and symbol of each point dataset.
     The legend is drawn in the right margin of the graph.

   The elements header, footer, quit and save buttons, the titles and
the axes are similar to those in barchart graphs except for that, as
in line graphs, the tick labels will be numbers. All of them are
arranged in a window by the geometry manager. However you can, for
example, show a scatter graph window without titles or footer text,
as we mentioned before. Other configuration options will be explained
later, in the corresponding modules.

   Related to the behaviour of the widgets in response to user
actions (bindings) the following features are:

Bindings related to scatter graph and its legend
     Clicking the left mouse key over a legend element, the points
     which belong to the corresponding dataset turn out into blue.
     Repeating the action toggles the point dataset to its original
     color. Moreover, you can do zoom-in by clicking the left mouse
     key over the bar chart graph and dragging a rectangle defining
     the area you want to zoom-in on. To do zoom-out simply press the
     right mouse button.

     When the pointer passes over the plotting area the cross hairs
     are drawn. The cross hairs consists of two intersecting lines
     (one vertical and one horizontal). Besides, if the pointer is
     over a legend element, its background changes.

Other bindings
     The default bindings and the bindings related to the save and
     quit buttons are similar to those in the bar chart graphs.

   The predicates that belong to this group are those whose names
began with *scattergraph_*.

180.4 Tables
============

The purpose of this section is to allow the user to display results
in a table. A table is a regular structure in which:

   * Every row has the same number of columns, or

   * Every column has the same number of rows.

   The widget configurable components are as follows:

Title
     Title of the widget, it is displayed centered at the top of the
     canvas. If text is `''' no title will be displayed.

Header text
     Left centered text displayed bellow the title. If text is `'''
     no header text will be displayed.

Table
     Is placed in the center of the window. The table is composed by
     cells ordered in rows and columns. The cell values can be either
     any kind of text or numbers and they can be empty as well (see
     the type definition in the corresponding chapter module). A
     table is a list of lists. Each sublist is a row, so every
     sublist in the table must contain the same number of alements.

Footer text
     Left centered text displayed at the lower part of the window. If
     text is `''' no header text will be displayed.

Quit button
     Button placed below the footer text. You can click it to close
     the window.

   If the arguments are not in a correct format an exception will be
thrown. Moreover, these widgets have the default bindings and the
binding related to the quit button:

   The set of predicates that belongs to this group are those which
names begin with *table_widget*.

180.5 Overview of widgets
=========================

Although you don't have to worry about how to arrange the widgets,
here is an overview of how Tcl-tk, the underlying graphical system
currently used by chartlib, performs this task. Quoting from the book
_Tcl and Tk toolkit_, John K. Ousterhout.

   The X Window System provides many facilities for manipulating
windows in displays. The root window may have any number of child
windows, each of wich is called a top-level window. Top-level windows
may have children of their own, wich may have also children, and so
on. The descendants of top-level windows are called internal windows.
Internal windows are usedfor individual controls such as buttons,
text entries, and for grouping controls together. An X-application
tipically manages several top-level windows. Tk uses X to implement a
set of controls with the Motif look and feel. These controls are
called widgets. Each widget is implemented using one X window, and
the terms "window" and "widget" will be used interchangeably in this
document. As with windows, widgets are nested in hierarchical
structures. In this library top-level widgets (nonleaf or main) are
just containers for organizing and arranging the leaf widgets
(components). Thereby, the barchart widget is a top-level window wich
contains some widget components.

   Probably the most painstaking aspect of building a graphical
application is getting the placement and size of the widgets just
right. It usually takes many iterations to align widgets and adjust
their spacing. That's because managing the geometry of widgets is
simply not a packing problem, but also graphical design problem.
Attributes such as alignment, symmetry, and balance are more
important than minimizing the amount of space used for packing. Tk is
similar to other X toolkits in that it does not allow widgets to
determine their own geometries. A widget will not even appeared
unless it is managed by a geometry manager. This separation of
geometry management from internal widget behaviour allows multiple
geometry managers to exist simultaneously and permits any widget to
be used with any geometry manager. A geometry manager's job is to
arrange one or more _slave_ widgets relative to a _master_ widgets.
There are some geometry managers in Tk such as pack, place and canvas
widget. We will use another one call table.

   The table geometry manager arranges widgets in a table. It's easy
to align widgets (horizontally and vertically) or to create empty
space to balance the arrangement of the widgets. Widgets (called
slaves in the Tk parlance) are arranged inside a containing widget
(called the master). Widgets are positioned at row,column locations
and may span any number of rows or columns. More than one widget can
occupy a single location. The placement of widget windows determines
both the size and arrangement of the table. The table queries the
requested size of each widget. The requested size of a widget is the
natural size of the widget (before the widget is shrunk or expanded).
The height of each row and the width of each column is the largest
widget spanning that row or column. The size of the table is in turn
the sum of the row and column sizes. This is the table's normal size.
The total number of rows and columns in a table is determined from
the indices specified. The table grows dynamically as windows are
added at larger indices.

180.6 Usage and interface (`chartlib')
======================================

   * *Library usage:*

     `:- use_module(library(chartlib)).'

   * *Other modules used:*
        - _System library modules:_

          `chartlib/genbar1', `chartlib/genbar2', `chartlib/genbar3', `chartlib/genbar4', `chartlib/genmultibar', `chartlib/table_widget1', `chartlib/table_widget2', `chartlib/table_widget3', `chartlib/table_widget4', `chartlib/gengraph1', `chartlib/gengraph2', `chartlib/chartlib_errhandle'.

180.7 Documentation on exports (`chartlib')
===========================================

 -- (: UNDOC_REEXPORT) barchart1/7:
     Imported from `genbar1' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) barchart1/9:
     Imported from `genbar1' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) percentbarchart1/7:
     Imported from `genbar1' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) barchart2/7:
     Imported from `genbar2' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) barchart2/11:
     Imported from `genbar2' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) percentbarchart2/7:
     Imported from `genbar2' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) barchart3/7:
     Imported from `genbar3' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) barchart3/9:
     Imported from `genbar3' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) percentbarchart3/7:
     Imported from `genbar3' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) barchart4/7:
     Imported from `genbar4' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) barchart4/11:
     Imported from `genbar4' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) percentbarchart4/7:
     Imported from `genbar4' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) multibarchart/8:
     Imported from `genmultibar' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) multibarchart/10:
     Imported from `genmultibar' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) tablewidget1/4:
     Imported from `table_widget1' (see the corresponding
     documentation for details).

 -- (: UNDOC_REEXPORT) tablewidget1/5:
     Imported from `table_widget1' (see the corresponding
     documentation for details).

 -- (: UNDOC_REEXPORT) tablewidget2/4:
     Imported from `table_widget2' (see the corresponding
     documentation for details).

 -- (: UNDOC_REEXPORT) tablewidget2/5:
     Imported from `table_widget2' (see the corresponding
     documentation for details).

 -- (: UNDOC_REEXPORT) tablewidget3/4:
     Imported from `table_widget3' (see the corresponding
     documentation for details).

 -- (: UNDOC_REEXPORT) tablewidget3/5:
     Imported from `table_widget3' (see the corresponding
     documentation for details).

 -- (: UNDOC_REEXPORT) tablewidget4/4:
     Imported from `table_widget4' (see the corresponding
     documentation for details).

 -- (: UNDOC_REEXPORT) tablewidget4/5:
     Imported from `table_widget4' (see the corresponding
     documentation for details).

 -- (: UNDOC_REEXPORT) graph_b1/9:
     Imported from `gengraph1' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) graph_b1/13:
     Imported from `gengraph1' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) graph_w1/9:
     Imported from `gengraph1' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) graph_w1/13:
     Imported from `gengraph1' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) scattergraph_b1/8:
     Imported from `gengraph1' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) scattergraph_b1/12:
     Imported from `gengraph1' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) scattergraph_w1/8:
     Imported from `gengraph1' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) scattergraph_w1/12:
     Imported from `gengraph1' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) graph_b2/9:
     Imported from `gengraph2' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) graph_b2/13:
     Imported from `gengraph2' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) graph_w2/9:
     Imported from `gengraph2' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) graph_w2/13:
     Imported from `gengraph2' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) scattergraph_b2/8:
     Imported from `gengraph2' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) scattergraph_b2/12:
     Imported from `gengraph2' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) scattergraph_w2/8:
     Imported from `gengraph2' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) scattergraph_w2/12:
     Imported from `gengraph2' (see the corresponding documentation
     for details).

 -- (: UNDOC_REEXPORT) chartlib_text_error_protect/1:
     Imported from `chartlib_errhandle' (see the corresponding
     documentation for details).

 -- (: UNDOC_REEXPORT) chartlib_visual_error_protect/1:
     Imported from `chartlib_errhandle' (see the corresponding
     documentation for details).

181 Low level Interface between Prolog and blt
**********************************************

*Author(s):* Isabel Martín.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#153 (2003/12/4, 17:38:53 CET)

   This module exports some predicates to interact with Tcl-tk,
particularly with the bltwish program. Bltwish is a windowing shell
consisting of the Tcl command languaje, the Tk toolkit plus the
additional commands that comes with the BLT library and a main
program that reads commands. It creates a main window and then
processes Tcl commands.

181.1 Usage and interface (`bltclass')
======================================

   * *Library usage:*

     `:- use_module(library(bltclass)).'

   * *Exports:*
        - _Predicates:_

          `new_interp/1', `tcltk_raw_code/2', `interp_file/2'.

        - _Regular Types:_

          `bltwish_interp/1'.

   * *Other modules used:*
        - _System library modules:_

          `sockets/sockets', `system', `write', `read', `strings', `format', `terms'.

181.2 Documentation on exports (`bltclass')
===========================================

 -- PREDICATE: new_interp/1:
     `new_interp(Interp)'

     Creates a bltwish interprter and returns a socket. The socket
     allows the comunication between Prolog and Tcl-tk. Thus, bltwish
     receives the commands through the socket.

 -- PREDICATE: tcltk_raw_code/2:
     `tcltk_raw_code(Command_Line, Interp)'

     Sends a command line to the interpreter. Tcl-tk parses and
     executes it.

 -- REGTYPE: bltwish_interp/1:
     `bltwish_interp(Interp)'

     This type defines a bltwish interpreter. In fact, the bltwish
     interpreter receives the commands through the socket created.
          bltwish_interp(Interp) :-
                  stream(Interp).

 -- PREDICATE: interp_file/2:
     `interp_file(File, Interp)'

     Sends the script file (File) to the interpreter through the
     socket. A script file is a file that contains commands that
     Tcl-tk can execute.

182 Error Handler for Chartlib
******************************

*Author(s):* Isabel Martín.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#259 (2003/12/30, 23:55:26 CET)

   This module is an error handler. If the format of the arguments is
not correct in a call to a chartlib predicate an exception will be
thrown . You can wrap the chartlib predicates with the predicates
exported by this module to handle automatically the errors if any.

182.1 Usage and interface (`chartlib_errhandle')
================================================

   * *Library usage:*

     `:- use_module(library(chartlib_errhandle)).'

   * *Exports:*
        - _Predicates:_

          `chartlib_text_error_protect/1', `chartlib_visual_error_protect/1'.

   * *Other modules used:*
        - _System library modules:_

          `chartlib/bltclass', `chartlib/install_utils'.

182.2 Documentation on exports (`chartlib_errhandle')
=====================================================

 -- PREDICATE: chartlib_text_error_protect/1:
     `chartlib_text_error_protect(G)'

     This predicate catches the thrown exception and sends it to the
     appropiate handler. The handler will show the error message in
     the standard output.

     _Meta-predicate_ with arguments:
     `chartlib_text_error_protect(goal)'.

 -- PREDICATE: chartlib_visual_error_protect/1:
     `chartlib_visual_error_protect(G)'

     This predicate catches the thrown exception and sends it to the
     appropiate handler. The handler will pop up a message box.

     _Meta-predicate_ with arguments:
     `chartlib_visual_error_protect(goal)'.

182.3 Documentation on internals (`chartlib_errhandle')
=======================================================

 -- REGTYPE: handler_type/1:
     `handler_type(X)'

     The library chartlib includes two error handlers already
     programmed.
          handler_type(text).
          handler_type(visual).

 -- PREDICATE: error_message/2:
     `error_message(ErrorCode, ErrorMessage)'

     Binds the error code with its corresponding text message.

 -- PREDICATE: error_file/2:
     `error_file(ErrorCode, ErrorFile)'

     Binds the error code with its corresponding script error file.

183 Color and Pattern Library
*****************************

*Author(s):* Isabel Martín.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#156 (2003/12/4, 17:39:13 CET)

   This module contains predicates to access and check conformance to
the available colors and patterns.

183.1 Usage and interface (`color_pattern')
===========================================

   * *Library usage:*

     `:- use_module(library(color_pattern)).'

   * *Exports:*
        - _Predicates:_

          `color/2', `pattern/2', `random_color/1', `random_lightcolor/1', `random_darkcolor/1', `random_pattern/1'.

        - _Regular Types:_

          `color/1', `pattern/1'.

   * *Other modules used:*
        - _System library modules:_

          `lists', `random/random'.

183.2 Documentation on exports (`color_pattern')
================================================

 -- REGTYPE: color/1:
     `color(Color)'

          color('GreenYellow').
          color('Yellow').
          color('White').
          color('Wheat').
          color('BlueViolet').
          color('Violet').
          color('MediumTurquoise').
          color('DarkTurquoise').
          color('Turquoise').
          color('Thistle').
          color('Tan').
          color('Sienna').
          color('Salmon').
          color('VioletRed').
          color('OrangeRed').
          color('MediumVioletRed').
          color('IndianRed').
          color('Red').
          color('Plum').
          color('Pink').
          color('MediumOrchid').
          color('DarkOrchid').
          color('Orchid').
          color('Orange').
          color('Maroon').
          color('Magenta').
          color('Khaki').
          color('Grey').
          color('LightGray').
          color('DimGray').
          color('DarkSlateGray').
          color('YellowGreen').
          color('SpringGreen').
          color('SeaGreen').
          color('PaleGreen').
          color('MediumSpringGreen').
          color('MediumSeaGreen').
          color('LimeGreen').
          color('ForestGreen').
          color('DarkOliveGreen').
          color('DarkGreen').
          color('Green').
          color('Goldenrod').
          color('Gold').
          color('Brown').
          color('Firebrick').
          color('Cyan').
          color('Coral').
          color('SteelBlue').
          color('SlateBlue').
          color('SkyBlue').
          color('Navy').
          color('MidnightBlue').
          color('MediumSlateBlue').
          color('MediumBlue').
          color('LightSteelBlue').
          color('LightBlue').
          color('DarkSlateBlue').
          color('CornflowerBlue').
          color('CadetBlue').
          color('Blue').
          color('Black').
          color('MediumAquamarine').
          color('Aquamarine').
     Defines available colors for elements such as points, lines or
     bars.

 -- PREDICATE: color/2:
     *Usage:* `color(C1, C2)'
        - _Description:_ Test whether the color `C1' is a valid color
          or not. If `C1' is a variable the predicate will choose a
          valid color randomly. If `C1' is a ground term that is not
          a valid color an exception (error9) will be thrown

        - _The following properties should hold at call time:_

          `color_pattern:color(C1)'  (`color_pattern:color/1')

        - _The following properties should hold upon exit:_

          `color_pattern:color(C2)'  (`color_pattern:color/1')

 -- REGTYPE: pattern/1:
     `pattern(Pattern)'

          pattern(pattern1).
          pattern(pattern2).
          pattern(pattern3).
          pattern(pattern4).
          pattern(pattern5).
          pattern(pattern6).
          pattern(pattern7).
          pattern(pattern8).
          pattern(pattern9).
     Defines valid patterns used in the stipple style bar attribute.

 -- PREDICATE: pattern/2:
     *Usage:* `pattern(P1, P2)'
        - _Description:_ Test whether the pattern `P1' is a valid
          pattern or not. If `P1' is a variable the predicate will
          choose a valid pattern randomly. If `P1' is a ground term
          that is not a valid pattern an exception (error10) will be
          thrown.

        - _The following properties should hold at call time:_

          `color_pattern:pattern(P1)'  (`color_pattern:pattern/1')

        - _The following properties should hold upon exit:_

          `color_pattern:pattern(P2)'  (`color_pattern:pattern/1')

 -- PREDICATE: random_color/1:
     `random_color(Color)'

     This predicate choose a valid color among the availables
     randomly.

 -- PREDICATE: random_lightcolor/1:
     `random_lightcolor(Color)'

     This predicate choose a valid light color among the availables
     randomly.

 -- PREDICATE: random_darkcolor/1:
     `random_darkcolor(Color)'

     This predicate choose a valid dark color among the availables
     randomly.

 -- PREDICATE: random_pattern/1:
     `random_pattern(Pattern)'

     This predicate choose a valid pattern among the availables
     randomly.

184 Barchart widgets - 1
************************

*Author(s):* Isabel Martín.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#260 (2003/12/31, 0:13:52 CET)

   This module defines predicates to show barchart widgets. The three
predicates exported by this module plot two-variable data as regular
bars in a window. They all share the following features:

   * No numeric values for the `x' axis are needed because they will
     be interpreted as labels. See `xbarelement1/1' definition type.

   * The bars will be displayed at uniform intervals.

   * The user can either select the appearance of the bars
     (background color, foreground color and stipple style) or not.
     See the `xbarelement1' type definition. Thus, the user can call
     each predicate in two ways.

   * The bar chart has a legend. One entry (symbol and label) per bar.

   * If you don't want to display text in the elements header,
     barchart title, x axis title, y axis title or footer, simply
     type `''' as the value of the argument.

   * The predicates test whether the format of the arguments is
     correct. If one or both vectors are empty, the exception
     `error2' will be thrown. If the vectors contains elements but
     are not correct, the exception `error1' or `error3' will be
     thrown, depending on the error type. `error1' means that
     `XVector' and `YVector' do not contain the same number of
     elements and `error3' indicates that not all the `XVector'
     elements contain a correct number of attributes .

Particular features will be pointed out in the corresponding
predicate.

184.1 Usage and interface (`genbar1')
=====================================

   * *Library usage:*

     `:- use_module(library(genbar1)).'

   * *Exports:*
        - _Predicates:_

          `barchart1/7', `barchart1/9', `percentbarchart1/7'.

        - _Regular Types:_

          `yelement/1', `axis_limit/1', `header/1', `title/1', `footer/1'.

   * *Other modules used:*
        - _System library modules:_

          `chartlib/bltclass', `chartlib/test_format', `chartlib/color_pattern', `chartlib/install_utils', `lists', `random/random'.

184.2 Documentation on exports (`genbar1')
==========================================

 -- PREDICATE: barchart1/7:
     `barchart1(Header, BarchartTitle, XTitle, XVector, YTitle,
     YVector, Footer)'

     The `y' axis range is determined from the limits of the data.
     Two examples are given to demonstrate clearly how to call the
     predicates. In the first example the user sets the bar
     appearance, in the second one the appearance features will be
     chosen by the system and the colors that have been assigned to
     the variables Color1, Color2 and Pattern will be shown also.

     Example 1:

          barchart1('This is the header text',
            'Barchart title',
            'xaxistitle',
            [ ['bar1','legend_element1','Blue','Yellow','pattern1'],
                     ['bar2','legend_element2','Plum','SeaGreen','pattern2'],
                     ['bar3','legend_element3','Turquoise','Yellow','pattern5'] ],
            'yaxixtitle',
            [20,10,59],
            'footer').

     Example 2:

          barchart1('This is the header text',
            'Barchart title',
            'xaxistitle',
            [ ['element1','legend_element1',Color1,Color2,Pattern],
                      ['element2','legend_element2'],
                      ['element3','legend_element3'] ],
            'yaxixtitle',
            [20,10,59],
            'footer').

 -- PREDICATE: barchart1/9:
     `barchart1(Header, BTitle, XTitle, XVector, YTitle, YVector,
     YMax, YMin, Footer)'

     You can set the minimum and maximum limits of the `y' axis. Data
     outside the limits will not be plotted. Each limit, as you can
     check by looking at the `axis_limit/1' definition, is a number.
     If the argument is a variable the limit will be calculated from
     the data (i.e., if `YMax' value is YValueMax the maximum y axis
     limit will calculated using the largest data value).

     Example:

          barchart1('This is the header text',
            'Barchart title',
            'xaxistitle',
            [ ['element1','e1','Blue','Yellow','pattern1'],
                ['element2','e2','Turquoise','Plum','pattern5'],
                ['element3','e3','Turquoise','Green','pattern5'] ],
            'yaxixtitle',
            [20,10,59],
            70,
            _,
            'footer').

 -- PREDICATE: percentbarchart1/7:
     `percentbarchart1(Header, BTitle, XTitle, XVector, YTitle,
     YVector, Footer)'

     The y axis maximum coordinate value is 100. The `x' axis limits
     are automatically worked out.

     Example:

          percentbarchart1('This is a special barchart to represent percentages',
            'Barchart with legend',
            'My xaxistitle',
            [ [1,'bar1','Blue','Yellow','pattern1'],
                 [8,'bar2','MediumTurquoise','Plum','pattern5'] ],
            'My yaxixtitle',
            [80,10],
            'This is the footer text').

 -- REGTYPE: yelement/1:
          yelement(Y) :-
                  number(Y).

     Y is the bar lenght, so it must be a numeric value.

     Both Prolog and Tcl-Tk support integers and floats. Integers are
     usually specified in decimal, but if the first character is 0
     the number is read in octal (base 8), and if the first two
     characters are 0x, the number is read in hexadecimal (base16).
     Float numbers may be specified using most of the forms defined
     for ANSI C, including the following examples:

        * 9.56

        * 5.88e-2

        * 5.1E2

     Note: Be careful when using floats. While 8. or 7.e4 is
     interpreted by Tcl-tk as 8.0 and 7.0e4, Prolog will not read
     them as float numbers. Example:
                  ?- number(8.e+5).
                  {SYNTAX ERROR: (lns 130-130) , or ) expected in arguments
                  number ( 8
                  ** here **
                  . e + 5 ) .
                  }

                  no
                  ?- number(8.).
                  {SYNTAX ERROR: (lns 138-138) , or ) expected in arguments
                  number ( 8
                  ** here **
                  . ) .
                  }

                  no

                  ?- number(8.0e+5).

                  yes
                  ?- number(8.0).

                  yes

     Precision: Tcl-tk internally represents integers with the C type
     `int', which provides at least 32 bits of precision on most
     machines. Since Prolog integers can (in some implementations)
     exceed 32 bits but the precision in Tcl-tk depends on the
     machine, it is up to the progammer to ensure that the values fit
     into the maximum precision of the machine for integers. Real
     numbers are represented with the C type `double', which is
     usually represented with 64-bit values (about 15 decimal digits
     of precision) using the IEEE Floating Point Standard.

     Conversion: If the list is composed by integers and floats,
     Tcl-tk will convert integers to floats.

 -- REGTYPE: axis_limit/1:
          axis_limit(X) :-
                  number(X).
          axis_limit(_1).

     This type is defined in order to set the minimum and maximum
     limits of the axes. Data outside the limits will not be plotted.
     Each limit, is a number or a variable. If the argument is not a
     number the limit will be calculated from the data (i.e., if YMax
     value is `Var' the maximum y axis limit will be calculated using
     the largest data value).

 -- REGTYPE: header/1:
     *Usage:* `header(X)'
        - _Description:_ `X' is a text (an atom) describing the
          header of the graph.

 -- REGTYPE: title/1:
     *Usage:* `title(X)'
        - _Description:_ `X' is a text (an atom) to be used as label,
          usually not very long.

 -- REGTYPE: footer/1:
     *Usage:* `footer(X)'
        - _Description:_ `X' is a text (an atom) describing the
          footer of the graph.

184.3 Documentation on internals (`genbar1')
============================================

 -- REGTYPE: xbarelement1/1:
          xbarelement1([XValue,LegendElement]) :-
                  atomic(XValue),
                  atomic(LegendElement).
          xbarelement1([XValue,LegendElement,ForegColor,BackgColor,SPattern]) :-
                  atomic(XValue),
                  atomic(LegendElement),
                  color(ForegColor),
                  color(BackgColor),
                  pattern(SPattern).

     Defines the attributes of the bar.
    `XValue'
          bar label. Although `XValue' values may be numbers, the
          will be treated as labels. Different elements with the same
          label will produce different bars.

    `LegendElement'
          Legend element name. It may be a number or an atom and
          equal or different to the XValue. Every `LegendElement'
          value of the list must be unique.

    `ForegColor'
          It sets the Foreground color of the bar. Its value must be
          a valid color, otherwise the system will throw an
          exception. If the argument value is a variable, it gets
          instantiated to a color chosen by the library.

    `BackgColor'
          It sets the Background color of the bar. Its value must be
          a valid color, otherwise the system will throw an
          exception. If the argument value is a variable, it gets
          instantiated to a color chosen by the library.

    `SPattern'
          It sets the stipple of the bar. Its value must be a valid
          pattern, otherwise the system will throw an exception. If
          the argument value is a variable, it gets instantiated to a
          pattern chosen by the library.

185 Barchart widgets - 2
************************

*Author(s):* Isabel Martín.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#265 (2003/12/31, 16:47:45 CET)

   This module defines predicates which show barchart widgets. The
three predicates exported by this module plot two-variable data as
regular bars in a window. They all share the following features:

   * Numeric values for the x axis are needed, otherwise it does not
     work properly. See `xbarelement2/1' definition type.

   * The bar position is proportional to the x-coordinate value.

   * The user can either select the appearance of the bars
     (background color, foreground color and stipple style) or not.
     See the `xbarelement2/1' type definition. Thus, the user can
     call each predicate in two ways.

   * The bar chart has a legend and one entry (symbol and label) per
     bar.

   * If you do not want to display text in the elements header,
     barchart title, x axis title, y axis title or footer, simply
     type `''' as the value of the argument.

   * The predicates test whether the format of the arguments is
     correct. If one or both vectors are empty, the exception
     `error2' will be thrown. If the vectors contain elements but are
     not correct, the exception `error1' or `error3' will be thrown,
     depending on the error type. `error1' means that `XVector' and
     `YVector' does not contain the same number of elements and
     `error3' indicates that not all the `XVector' elements contain a
     correct number of attributes .

   Particular features will be pointed out in the corresponding
predicate.

185.1 Usage and interface (`genbar2')
=====================================

   * *Library usage:*

     `:- use_module(library(genbar2)).'

   * *Exports:*
        - _Predicates:_

          `barchart2/7', `barchart2/11', `percentbarchart2/7'.

        - _Regular Types:_

          `xbarelement2/1'.

   * *Other modules used:*
        - _System library modules:_

          `chartlib/genbar1', `chartlib/bltclass', `chartlib/color_pattern', `chartlib/test_format', `chartlib/install_utils', `lists', `random/random'.

185.2 Documentation on exports (`genbar2')
==========================================

 -- PREDICATE: barchart2/7:
     `barchart2(Header, BarchartTitle, XTitle, XVector, YTitle,
     YVector, Footer)'

     The maximum and minimum limits for axes are determined from the
     data.

     Example:

          barchart2('This is the header text',
            'Barchart with legend',
            'My xaxistitle',
            [ [1,'bar1','Blue','Yellow','pattern1'],
                 [2,'bar2','MediumTurquoise','Plum','pattern5'] ],
            'My yaxixtitle',
            [20,10],
            'This is the footer text').

 -- PREDICATE: barchart2/11:
     `barchart2(Header, BT, XT, XVector, XMax, XMin, YT, YVector,
     YMax, YMin, Footer)'

     You can set the minimum and maximum limits of the axes. Data
     outside the limits will not be plotted. Each limit, as you can
     check looking at the `axis_limit/1' definition, is a number. If
     the argument is a variable the limit will be calculated from the
     data (i.e., if `YMax' value is YValueMax the maximum y axis
     limit will calculated using the largest data value).

     Example:

          barchart2('This is the header text',
            'Barchart with legend',
            'My xaxistitle',
            [ [1,'bar1',Color1,Color2,Pattern1],
                   [2,'bar2',Color3,Color4,Pattern2] ],
            10,
            -10,
            'My yaxixtitle',
            [20,10],
            100,
            -10,
            'The limits for the axes are set by the user').

 -- PREDICATE: percentbarchart2/7:
     `percentbarchart2(Header, BTitle, XTitle, XVector, YTitle,
     YVector, Footer)'

     The y axis maximum coordinate value is 100. The x axis limits
     are autoarrange.

     Example:

          percentbarchart2('This is a special barchart to represent percentages',
            'Barchart with legend',
            'My xaxistitle',
            [ [1,'bar1','Blue','Yellow','pattern1'],
                    [2,'bar2','MediumTurquoise','Plum','pattern5'] ],
            'My yaxixtitle',
            [80,10],
            'This is the footer text').

 -- REGTYPE: xbarelement2/1:
          xbarelement2([XValue,LegendElement]) :-
                  number(XValue),
                  atomic(LegendElement).
          xbarelement2([XValue,LegendElement,ForegColor,BackgColor,SPattern]) :-
                  number(XValue),
                  atomic(LegendElement),
                  color(ForegColor),
                  color(BackgColor),
                  pattern(SPattern).
     Defines the attributes of the bar.

    `XValue'
          x-coordinate position of the bar. Different elements with
          the same abscissas will produce overlapped bars.

    `LegendElement'
          Element legend name. It may be a number or an atom and
          equal or different to the XValue. Every `LegendElement'
          value of the list must be unique.

    `ForegColor'
          Is the Foreground color of the bar. Its value must be a
          valid color, otherwise the system will throw an exception.
          If the argument value is a variable, it gets instantiated
          to a color chosen by the library.

    `BackgColor'
          Is the Background color of the bar. Its value must be a
          valid color, otherwise the system will throw an exception.
          If the argument value is a variable, it gets instantiated
          to a color chosen by the library.

    `SPattern'
          Is the stipple of the bar. Its value must be a valid
          pattern, otherwise the system will throw an exception. If
          the argument value is a variable, it gets instantiated to a
          pattern chosen by the library.

186 Depict barchart widgets - 3
*******************************

*Author(s):* Isabel Martín.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#267 (2004/1/1, 14:9:7 CET)

   This module defines predicates which depict barchart widgets. The
three predicates exported by this module plot two-variable data as
regular bars in a window and are similar to those exported in the
genbar1 module except in that these defined in this module do not
display a legend. Thus, not all the argument types are equal.

   The predicates test whether the format of the arguments is
correct. If one or both vectors are empty, the exception `error2'
will be thrown. If the vectors contain elements but are not correct,
the exception `error1' or `error3' will be thrown, depending on the
error type. `error1' means that `XVector' and `YVector' do not
contain the same number of elements and `error3' indicates that not
all the `XVector' elements contain a correct number of attributes .

186.1 Usage and interface (`genbar3')
=====================================

   * *Library usage:*

     `:- use_module(library(genbar3)).'

   * *Exports:*
        - _Predicates:_

          `barchart3/7', `barchart3/9', `percentbarchart3/7'.

   * *Other modules used:*
        - _System library modules:_

          `chartlib/genbar1', `chartlib/bltclass', `chartlib/color_pattern', `chartlib/test_format', `chartlib/install_utils', `lists', `random/random'.

186.2 Documentation on exports (`genbar3')
==========================================

 -- PREDICATE: barchart3/7:
     `barchart3(Header, BarchartTitle, XTitle, XVector, YTitle,
     YVector, Footer)'

     As we mentioned in the above paragraph, this predicate is
     comparable to `barchart1/8' except in the `XVector' argument
     type.

     Example:
          barchart3('This is the header text',
            'Barchart without legend',
            'My xaxistitle',
            [['bar1'],['bar2']],
            'My yaxixtitle',
            [20,10],
            'This is the footer text').

 -- PREDICATE: barchart3/9:
     `barchart3(Header, BTitle, XTitle, XVector, YTitle, YVector,
     YMax, YMin, Footer)'

     As we mentioned, this predicate is quite similar to the `barchart1/10'
     except in the `XVector' argument type, because the yielded bar
     chart lacks of legend.

     Example:
          barchart3('This is the header text',
            'Barchart without legend',
            'My xaxistitle',
            [['bar1'],['bar2']],
            'My yaxixtitle',
            30,
            5,
            [20,10],
            'This is the footer text').

 -- PREDICATE: percentbarchart3/7:
     `percentbarchart3(Header, BTitle, XTitle, XVector, YTitle,
     YVector, Footer)'

     The `y' axis maximum coordinate value is 100. The x axis limits
     are autoarrange.

     Example:

          percentbarchart3('This is a special barchart to represent percentages',
                    'Barchart without legend',
                    'My xaxistitle',
                    [ ['pr1','Blue','Yellow','pattern1'],
                      ['pr2','MediumTurquoise','Plum','pattern5'] ],
                    'My yaxixtitle',
                    [80,10],
                    'This is the footer text').

186.3 Documentation on internals (`genbar3')
============================================

 -- REGTYPE: xbarelement3/1:
          xbarelement3([XValue]) :-
                  atomic(XValue).
          xbarelement3([XValue,ForegColor,BackgColor,StipplePattern]) :-
                  atomic(XValue),
                  color(ForegColor),
                  color(BackgColor),
                  pattern(StipplePattern).

     Defines the attributes of the bar.
    `XValue'
          bar label. Although `XValue' values may be numbers, the
          will be treated as labels. Different elements with the same
          label will produce different bars.

    `ForegColor'
          It sets the Foreground color of the bar. Its value must be
          a valid color, otherwise the system will throw an
          exception. If the argument value is a variable, it gets
          instantiated to a color chosen by the library.

    `BackgColor'
          It sets the Background color of the bar. Its value must be
          a valid color, otherwise the system will throw an
          exception. If the argument value is a variable, it gets
          instantiated to a color chosen by the library.

    `SPattern'
          It sets the stipple of the bar. Its value must be a valid
          pattern, otherwise the system will throw an exception. If
          the argument value is a variable, it gets instantiated to a
          pattern chosen by the library.

187 Depict barchart widgets - 4
*******************************

*Author(s):* Isabel Martín.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#268 (2004/1/1, 14:15:51 CET)

   This module defines predicates which depict barchart widgets. The
three predicates exported by this module plot two-variable data as
regular bars in a window and are similar to those exported in genbar2
module except in that those defined in this module doesn't display a
legend. Thus, the user does not have to define legend element names.

   The predicates test whether the format of the arguments is
correct. If one or both vectors are empty, the exception `error2'
will be thrown. If the vectors contains elements but are not correct,
the exception `error1' or `error3' will be thrown, depending on the
error type. `error1' means that `XVector' and `YVector' do not
contain the same number of elements and `error3' indicates that not
all the `XVector' elements contain a correct number of attributes .

187.1 Usage and interface (`genbar4')
=====================================

   * *Library usage:*

     `:- use_module(library(genbar4)).'

   * *Exports:*
        - _Predicates:_

          `barchart4/7', `barchart4/11', `percentbarchart4/7'.

   * *Other modules used:*
        - _System library modules:_

          `chartlib/genbar1', `chartlib/bltclass', `chartlib/color_pattern', `chartlib/test_format', `chartlib/install_utils', `lists', `random/random'.

187.2 Documentation on exports (`genbar4')
==========================================

 -- PREDICATE: barchart4/7:
     `barchart4(Header, BarchartTitle, XTitle, XVector, YTitle,
     YVector, Footer)'

     As we mentioned in the above paragraph, this predicate is
     comparable to `barchart2/8' except in the `XVector' argument
     type.

     Example:
          barchart4('This is the header text',
            'Barchart without legend',
            'My xaxistitle',
            [[2],[5],[6]],
            'My yaxixtitle',
            [20,10,59],
            'Numeric values in the xaxis').

 -- PREDICATE: barchart4/11:
     `barchart4(Hder, BT, XT, XVector, XMax, XMin, YT, YVector, YMax,
     YMin, Fter)'

     As we stated before, this predicate is quite similar to `barchart2/10'
     except in the following aspects:

        * The `XVector' argument type, because the yielded bar chart
          lacks the legend.

        * The user can set limits for both `x' axis and `y' axis.

     Example:
          barchart4('This is the header text, you can write a graph description',
            'Barchart without legend',
            'My xaxistitle',
            [[2,'Blue','Yellow','pattern1'],
                 [20,'MediumTurquoise','Plum','pattern5'],
                 [30,'MediumTurquoise','Green','pattern5']],
            50,
            -10,
            'My yaxixtitle',
            [20,10,59],
            100,
            -10,
            'Numeric values in the xaxis').

 -- PREDICATE: percentbarchart4/7:
     `percentbarchart4(Header, BTitle, XTitle, XVector, YTitle,
     YVector, Footer)'

     The y axis maximum coordinate value is 100. The x axis limits
     are automatically worked out. This predicate is useful when the
     bar height represents percentages.

     Example:

          percentbarchart4('This is the header text',
            'Barchart without legend',
            'My xaxistitle',
            [[2,'Blue','Yellow','pattern1'],[5,'Yellow','Plum','pattern5'],
                 [6,'MediumTurquoise','Green','pattern5']],
            'My yaxixtitle',
            [20,10,59],
            'Numeric values in the xaxis').

187.3 Documentation on internals (`genbar4')
============================================

 -- REGTYPE: xbarelement4/1:
     Defines the attributes of the bar.
    `XValue'
          x-coordinate position of the bar. Different elements with
          the same abscissas will produce overlapped bars.

    `ForegColor'
          It sets the Foreground color of the bar. Its value must be
          a valid color, otherwise the system will throw an
          exception. If the argument value is a variable, it gets
          instantiated to a color chosen by the library.

    `BackgColor'
          It sets the Background color of the bar. Its value must be
          a valid color, otherwise the system will throw an
          exception. If the argument value is a variable, it gets
          instantiated to a color chosen by the library.

    `SPattern'
          It sets the stipple of the bar. Its value must be a valid
          pattern, otherwise the system will throw an exception. If
          the argument value is a variable, it gets instantiated to a
          pattern chosen by the library.

188 Depic line graph
********************

*Author(s):* Isabel Martín.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#269 (2004/1/1, 14:17:43 CET)

   This module defines predicates which depict line graph and scatter
graph widgets. All eigth predicates exported by this module plot
two-variable data. Each point is defined by its X-Y coordinate
values. A dataset is defined by two lists xvector and yvector, which
contain the points coordinates. As you might guess, the values placed
in the the same position in both lists are the coordinates of a
point. They both share the following features:

   * Numeric values for vector elements are needed. We'll use two
     vectors to represent the X-Y coordinates of each set of plotted
     data, but in this case every dataset shares the X-vector, i.e.,
     x-coordinate of points with the same index (1) in different
     datasets is the same. Thus, the numbers of points in each
     yvector must be equal to the number of points in the xvector.

   * The active element color is navyblue, which means that when you
     select a legend element, the corresponding line or point dataset
     turns into navyblue.

   * The user can either select the appearance of the lines and/or
     points of each dataset or not. If not, the system will choose
     the colors for the lines and the points among the available ones
     in accordance with the plot background color and it will also
     set the points size and symbol to the default. If the plot
     background color is black, the system will choose a lighter
     color, and the system will select a darker color when the plot
     background color is white. Thus, the user can define the
     appearanse attributes of each dataset in four different ways.
     Take a look at the `attributes/1' type definition and see the
     examples to understand it clearly.

   * The graph has a legend and one entry (symbol and label) per
     dataset.

   * If you do not want to display text in the element header,
     barchart title, xaxis title, yaxis title or footer, simply give
     `''' as the value of the argument.

   * The predicates check whether the format of the arguments is
     correct as well. The testing process involves some
     verifications. If one or both vectors are empty, the exception
     `error2' will be thrown. If the vectors contains elements but
     are not correct, the exception `error4' will be thrown.

   The names of the line graph predicates begin with *graph_* and
those corresponding to the scatter graph group begin with
*scattergraph_*.

   ---------- Footnotes ----------

   (1) It should be pointed out that I am refering to an index as the
position of an element in a list.

188.1 Usage and interface (`gengraph1')
=======================================

   * *Library usage:*

     `:- use_module(library(gengraph1)).'

   * *Exports:*
        - _Predicates:_

          `graph_b1/9', `graph_b1/13', `graph_w1/9', `graph_w1/13', `scattergraph_b1/8', `scattergraph_b1/12', `scattergraph_w1/8', `scattergraph_w1/12'.

        - _Regular Types:_

          `vector/1', `smooth/1', `attributes/1', `symbol/1', `size/1'.

   * *Other modules used:*
        - _System library modules:_

          `chartlib/bltclass', `chartlib/genbar1', `chartlib/color_pattern', `chartlib/test_format', `chartlib/install_utils', `lists', `random/random'.

188.2 Documentation on exports (`gengraph1')
============================================

 -- PREDICATE: graph_b1/9:
     `graph_b1(Header, GTitle, XTitle, XVector, YTitle, YVectors,
     LAtts, Footer, Smooth)'

     Besides the features mentioned at the begining of the chapter,
     the displayed graph generated when calling this predicate has
     the following distinguishing characteristics:

        * The plotting area background color is black.

        * The cross hairs color is white.

        * The axes limits are determined from the data.

     Example:

          graph_b1('This is the header text',
            'Graph_title',
            'xaxistitle',
            [20,10,59],
            'yaxixtitle',
            [ [10,35,40],[25,50,60] ],
            [ ['element1','Blue','Yellow','plus',6],['element2',Outline,Color] ],
            'footer',
            'linear').

 -- PREDICATE: graph_b1/13:
     `graph_b1(Header, GT, XT, XV, XMax, XMin, YT, YVs, YMax, YMin,
     LAtts, Footer, Smooth)'

     The particular features related to this predicate are described
     below:

        * The plotting area background color is black.

        * The cross hairs color is white.

        * You can set the minimum and maximum limits of the axes.
          Data outside the limits will not be plotted.

     Example:
          graph_b1('This is the header text',
            'Graph_title',
            'xaxistitle',
            [20,10,59],
            50,
            _,
            'yaxixtitle',
            [[10,35,40],[25,50,60]],
            50,
            _,
            [['line1','circle',4],['line2',OutlineColor,Color]],
            'footer',
            'step').

 -- PREDICATE: graph_w1/9:
     `graph_w1(Header, GTitle, XTitle, XVector, YTitle, YVectors,
     LAtts, Footer, Smooth)'

     This predicate is quite similar to `graph_b1/9'. The differences
     lies in the plot background color and in the cross hairs color,
     which are white and black respectively.

     Example:
          graph_w1('This is the header text',
            'Graph_title',
            'xaxistitle',
            [20,10,40,50],
            'yaxixtitle',
            [ [10,35,40,50],[25,20,60,40] ],
            [['line1','Blue','DarkOrchid'],['line2','circle',3]],
            'footer',
            'quadratic').

 -- PREDICATE: graph_w1/13:
     `graph_w1(Header, GT, XT, XV, XMax, XMin, YT, YVs, YMax, YMin,
     LAtts, Footer, Smooth)'

     This predicate is quite similar to `graph_b1/13', the
     differences between them are listed below:

        * The plotting area background color is white.

        * The cross hairs color is black.

     Example:
          graph_w1('This is the header text',
            'Graph_title',
            'xaxistitle',
            [20,10,59],
            100,
            10,
            'yaxixtitle',
            [[10,35,40],[25,20,60]],
            _,
            _,
            [['element1','Blue','Yellow'],['element2','Turquoise','Plum']],
            'footer',
            'quadratic').

 -- PREDICATE: scattergraph_b1/8:
     `scattergraph_b1(Header, GTitle, XTitle, XVector, YTitle,
     YVectors, PAtts, Footer)'

     Apart from the features brought up at the beginning of the
     chapter, the scatter graph displayed invoking this predicate has
     the following characteristics:

        * The plotting area background color is black.

        * The cross hairs color is white.

        * The axes limits are determined from the data.

     Example:
          scattergraph_b1('This is the header text',
            'Graph_title',
            'xaxistitle',
            [10,15,20],
            'yaxixtitle',
            [[10,35,20],[15,11,21]],
            [['element1','Blue','Yellow'],['element2','Turquoise','Plum']],
            'footer').

 -- PREDICATE: scattergraph_b1/12:
     `scattergraph_b1(Header, GT, XT, XV, XMax, XMin, YT, YVs, YMax,
     YMin, PAtts, Footer)'

     The particular features related to this predicate are described
     below:

        * The plotting area background color is black.

        * The cross hairs color is white.

        * You can set the minimum and maximum limits of the axes.
          Data outside the limits will not be plotted.

     Example:
          scattergraph_b1('This is the header text',
            'Graph_title',
            'xaxistitle',
            [20,10,59],
            50,
            _,
            'yaxixtitle',
            [[10,35,40],[25,50,60]],
            50,
            _,
            [['point dataset1','Blue','Yellow'],['point dataset2']],
            'footer').

 -- PREDICATE: scattergraph_w1/8:
     `scattergraph_w1(Header, GT, XT, XVector, YT, YVectors, PAtts,
     Footer)'

     This predicate is quite similar to `scattergraph_b1/8' except in
     the following:

        * The plotting area background color is black.

        * The cross hairs color is white.

        * If the user does not fix the points colors, they will be
          chosen among the lighter ones.

     Example:
          scattergraph_w1('This is the header text',
            'Graph_title',
            'xaxistitle',
            [20,10,59],
            'yaxixtitle',
            [[10,35,40],[25,20,60]],
            [['e1','Blue','Green'],['e2','MediumVioletRed','Plum']],
            'footer').

 -- PREDICATE: scattergraph_w1/12:
     `scattergraph_w1(Header, GT, XT, XV, XMax, XMin, YT, YVs, YMax,
     YMin, PAtts, Footer)'

     This predicate is quite similar to `scattergraph1_b1/13', the
     differences between them are listed below:

        * The plotting area background color is white.

        * The cross hairs color is black.

     Example:
          scattergraph_w1('This is the header text',
            'Graph_title',
            'xaxistitle',
            [20,10,59],
            150,
            5,
            'yaxixtitle',
            [[10,35,40],[25,20,60]],
            _,
            -10,
            [['e1','Blue','Yellow'],['e2','MediumTurquoise','Plum']],
            'footer').

 -- REGTYPE: vector/1:
          vector(X) :-
                  list(X,number).
     The type vector defines a list of numbers (integers or floats).

 -- REGTYPE: smooth/1:
     `smooth(Smooth)'

          smooth(linear).
          smooth(cubic).
          smooth(quadratic).
          smooth(step).

     Specifies how connecting segments are drawn between data points.
     If `Smooth' is `linear', a single line segment is drawn,
     connecting both data points. When `Smooth' is `step', two line
     segments will be drawn, the first line is a horizontal line
     segment that steps the next X-coordinate and the second one is a
     vertical line, moving to the next Y-coordinate. Both `cubic' and
     `quadratic' generate multiple segments between data points. If
     `cubic'is used, the segments are generated using a cubic spline.
     If `quadratic', a quadratic spline is used. The default is
     linear.

 -- REGTYPE: attributes/1:
          attributes([ElementName]) :-
                  atomic(ElementName).
          attributes([ElementName,OutLine,Color]) :-
                  atomic(ElementName),
                  color(OutLine),
                  color(Color).
          attributes([ElementName,Symbol,Size]) :-
                  atomic(ElementName),
                  symbol(Symbol),
                  size(Size).
          attributes([ElementName,OutLine,Color,Symbol,Size]) :-
                  atomic(ElementName),
                  color(OutLine),
                  color(Color),
                  symbol(Symbol),
                  size(Size).

     Each line or point dataset in the graph has its own attributes,
     which are defined by this type. The name of the dataset,
     specified in the `ElementName' argument, may be either a number
     or an atom. The second argument is the color of a thin line
     around each point in the dataset and the Color argument is the
     points and lines color. Both `OutLine' and `Color' must be a
     valid color (see available values in `color/1'), otherwise a
     random color according to the plot background color will be
     selected. The `Symbol' must be a valid symbol and the `Size'
     must be a number. Be careful if you want to especify the
     `Symbol' and the `Size', otherwise the predicate will not work
     as you expect. If you don't select a symbol and a size for a
     dataset the default values will be square and 1 pixel.

 -- REGTYPE: symbol/1:
     `symbol(Symbol)'

          symbol(square).
          symbol(circle).
          symbol(diamond).
          symbol(plus).
          symbol(cross).
          symbol(splus).
          symbol(scross).
          symbol(triangle).
     `Symbol' stands for the shape of the points whether in scatter
     graphs or in line graphs.

 -- REGTYPE: size/1:
     `size(Size)'

          size(Size) :-
                  number(Size).
     `Size' stands for the size in pixels of the points whether in
     scatter graphs or in line graphs.

189 Line graph widgets
**********************

*Author(s):* Isabel Martín.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#270 (2004/1/1, 14:19:56 CET)

   This module defines predicates which show line graph widgets. All
eight predicates exported by this module plot two-variable data. Each
point is defined by its X-Y coordinate values. Every predicate share
the following features:

   * A dataset is defined by three lists xvector, yvector and
     attributes. The arguments named `XVectors' (or `XVs'),
     `YVectors' (or `YVs') and `LAtts'(1) contain this information.
     Those arguments must be lists whose elements are also lists. The
     first dataset is defined by the firts element of the three
     lists, the second dataset is defined by the second element of
     the three lists and so on.

   * Numeric values for the vector elements are needed. We will use
     two vectors to represent the X-Y coordinates of each set of data
     plotted. In these predicates the vectors can have different
     number of points. However, the number of elements in xvector and
     yvector that pertain to a certain dataset must be, obviously,
     equal.

   * The active line color is blue, which means that when you select
     a legend element, the corresponding line turns into navyblue.

   * The user can either select the appearance for the lines and the
     points or not. See the `attributes/1' type definition. Thus, the
     user can call each predicate in different ways ways.

   * The graph has a legend and one entry (symbol and label) per
     dataset.

   * If you do not want to display text in the elements header,
     barchart title, xaxis title, yaxis title or footer, simply give
     `''' as the value of the argument.

   * The predicates check whether the format of the arguments is
     correct as well. The testing process involves some
     verifications. If one or both vectors are empty, the exception
     `error2' will be thrown. If the vectors contains elements but
     are not correct, the exception `error4' will be thrown.

   ---------- Footnotes ----------

   (1) In scatter graphs the attibute that contains the features of a
point dataset is `PAtts'.

189.1 Usage and interface (`gengraph2')
=======================================

   * *Library usage:*

     `:- use_module(library(gengraph2)).'

   * *Exports:*
        - _Predicates:_

          `graph_b2/9', `graph_b2/13', `graph_w2/9', `graph_w2/13', `scattergraph_b2/8', `scattergraph_b2/12', `scattergraph_w2/8', `scattergraph_w2/12'.

   * *Other modules used:*
        - _System library modules:_

          `chartlib/gengraph1', `chartlib/genbar1', `chartlib/bltclass', `chartlib/color_pattern', `chartlib/test_format', `chartlib/install_utils', `lists', `random/random'.

189.2 Documentation on exports (`gengraph2')
============================================

 -- PREDICATE: graph_b2/9:
     `graph_b2(Header, GTitle, XTitle, XVectors, YTitle, YVectors,
     LAtts, Footer, Sm)'

     Besides the features mentioned at the begining of the module
     chapter, the displayed graph generated calling this predicate
     has the following distinguish characteristics:

        * The plotting area background color is black.

        * The cross hairs color is white.

        * The axis limits are determined from the data.

     Example:

          graph_b2('This is the header text',
            'Graph_title',
            'xaxistitle',
            [[20,30,59],[25,50]],
            'yaxixtitle',
            [[10,35,40],[25,50]],
            [['line1','Blue','Yellow'],['line2']],
            'footer',
            'natural').

 -- PREDICATE: graph_b2/13:
     `graph_b2(Header, GT, XT, XVs, XMax, XMin, YT, YVs, YMax, YMin,
     LAtts, Footer, Smooth)'

     In addition to the features brought up at the begining of the
     module chapter, this graph has the following:

        * The plotting area background color is black.

        * The cross hairs color is white.

        * You can set the maximum and minimum values for the graph
          axes.

     Example:

          graph_b2('This is the header text',
            'Graph_title',
            'xaxistitle',
            [[20,10,59],[15,30,35]],
            50,
            _,
            'yaxixtitle',
            [[10,35,40],[25,50,60]],
            50.5,
            _,
            [['line1','Blue','Yellow'],['line','MediumTurquoise','Plum']],
            'footer',
            'step').

 -- PREDICATE: graph_w2/9:
     `graph_w2(Header, GT, XT, XVectors, YTitle, YVectors, LAtts,
     Footer, Smooth)'

     This predicate is quite similar to `graph_b2/9'. The difference
     lies in the graph appearance, as you can see below.

        * The plotting area background color is white.

        * The cross hairs color is black.

     Example:

          graph_w2('This is the header text',
            'Graph_title',
            'xaxistitle',
            [[10,30,59],[25,50]],
            'yaxixtitle',
            [[10,35,40],[25,40]],
            [['element1','Blue','DarkOrchid'],['element2','DarkOliveGreen',
              'Firebrick']],
            'footer',
            'natural').

 -- PREDICATE: graph_w2/13:
     `graph_w2(Header, GT, XT, XV, XMax, XMin, YT, YVs, YMax, YMin,
     LAtts, Footer, Smooth)'

     This predicate is comparable to `graph_b2/13'. The differences
     lie in the plot background color and in the cross hairs color,
     wich are white and black respectively.

     Example:
          graph_w2('This is the header text',
            'Graph_title',
            'xaxistitle',
            [[10,30,59],[10,35,40]],
            80,
            _,
            'yaxixtitle',
            [[10,35,40],[25,50,60]],
            50,
            _,
            [['element1','Blue','Green'],['element2','Turquoise','Black']],
            'footer',
            'linear').

 -- PREDICATE: scattergraph_b2/8:
     `scattergraph_b2(Header, GT, XT, XVectors, YT, YVectors, PAtts,
     Footer)'

     Apart from the features brought up at the beginning of the
     chapter, the scatter graph displayed when invoking this
     predicate has the following features:

        * The plotting area background color is black.

        * The cross hairs color is white.

        * The axis limits are determined from the data.

     Example:
          scattergraph_b2('This is the header text',
            'Graph_title',
            'xaxistitle',
            [[10,15,20],[8,30,40]],
            'yaxixtitle',
            [[10,35,20],[15,11,21]],
            [['element1','Blue','Yellow'],['element2','MediumTurquoise','Plum']],
            'footer').

 -- PREDICATE: scattergraph_b2/12:
     `scattergraph_b2(Header, GT, XT, XVs, XMax, XMin, YT, YVs, YMax,
     YMin, PAtts, Footer)'

     The particular features related to this predicate are described
     below:

        * The plotting area background color is black.

        * The cross hairs color is white.

        * You can set the minimum and maximum limits of the axes.
          Data outside the limits will not be plotted.

     Example:
          scattergraph_b2('This is the header text',
            'Graph_title',
            'xaxistitle',
            [[20,30,50],[18,40,59]],
            50,
            _,
            'yaxixtitle',
            [[10,35,40],[25,50,60]],
            50,
            _,
            [['point dataset1'],['point dataset2']],
            'footer').

 -- PREDICATE: scattergraph_w2/8:
     `scattergraph_w2(Header, GTitle, XTitle, XVs, YTitle, YVs,
     PAtts, Footer)'

     This predicate is quite similar to `scattergraph_w1/8' except in
     the following:

        * The plotting area background color is black.

        * The cross hairs color is white.

        * If the user do not provide the colors of the points, they
          will be chosen among the lighter ones.

     Example:
          scattergraph_w2('This is the header text',
            'Graph_title',
            'xaxistitle',
            [[20,30,40,15,30,35,20,30]],
            'yaxixtitle',
            [[10,30,40,25,20,25,20,25]],
            [['set1','cross',4]],
            'footer').

 -- PREDICATE: scattergraph_w2/12:
     `scattergraph_w2(Header, GT, XT, XVs, XMax, XMin, YT, YVs, YMax,
     YMin, PAtts, Footer)'

     This predicate is comparable to `scattergraph_w2/13', the
     differences between them are listed below:

        * The plotting area background color is white.

        * The cross hairs color is black.

     Example:
          scattergraph_w2('This is the header text',
            'Graph_title',
            'xaxistitle',
            [[20,10,59],[15,30,50]],
            150,
            5,
            'yaxixtitle',
            [[10,35,40],[25,20,60]],
            _,
            -10,
            [['e1','Blue','Yellow'],['e2','MediumTurquoise','Plum']],
            'footer').

190 Multi barchart widgets
**************************

*Author(s):* Isabel Martín.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#271 (2004/1/1, 14:21:46 CET)

   This module defines predicates which show barchart widgets. These
bar charts are somewhat different from the bar charts generated by
the predicates in modules genbar1, genbar2, genbar3 and genbar4.
Predicates in the present module show different features of each
dataset element in one chart at the same time. Each bar chart element
is a group of bars, and the element features involve three vectors
defined as follows:

   * xvector is a list containing the names (atoms) of the bars (n
     elements). Each bar group will be displayed at uniform intervals.

   * yvector is a list that contains m sublists, each one is composed
     of n elements. The i-sublist contains the y-values of the
     i-BarAttribute element for all of the XVector elements.

   * bar_attributtes is a list containing the appearance features of
     the bars (m elements). Each element of the list can be partial
     or complete, which means that you can define as bar attributes
     only the element name or by setting the element name, its
     background and foreground color and its stipple pattern.

   Other relevant aspects about this widgets are:

   * If you don't want to display text in the elements header,
     barchart title, xaxis title, yaxis title or footer, simply type
     `''' as the value of the argument.

   * The bar chart has a legend, and one entry (symbol and label) per
     feature group bar.

   * The user can either select the appearance of the bars
     (background color, foreground color and stipple style) or not.
     See the multibar_attribute type definition.

   * Data points can have their bar segments displayed in one of the
     following modes: stacked, aligned, overlapped or overlayed. They
     user can change the mode clicking in the checkboxes associated
     to each mode.

   * The predicates test whether the format of the arguments is
     correct. If one or both vectors are empty, the exception
     `error2' will be thrown. If the vectors contains elements but
     are not correct, the exception `error5' or `error6' will be
     thrown, depending on what is incorrect. `error5' means that
     `XVector' and each element of `YVector' do not contain the same
     number of elements or that `YVector' and `BarsAtt' do not
     contain the same number of elements, while `error6' indicates
     that not all the `BarsAtt' elements contain a correct number of
     attributes.

   The examples will help you to understand how these predicates
should be called.

190.1 Usage and interface (`genmultibar')
=========================================

   * *Library usage:*

     `:- use_module(library(genmultibar)).'

   * *Exports:*
        - _Predicates:_

          `multibarchart/8', `multibarchart/10'.

   * *Other modules used:*
        - _System library modules:_

          `chartlib/genbar1', `chartlib/bltclass', `chartlib/color_pattern', `chartlib/test_format', `chartlib/install_utils', `lists', `random/random'.

190.2 Documentation on exports (`genmultibar')
==============================================

 -- PREDICATE: multibarchart/8:
     `multibarchart(Header, BTitle, XTitle, XVector, YTitle,
     BarsAtts, YVector, Footer)'

     The x axis limits are autoarrange. The user can call the
     predicate in two ways. In the first example the user sets the
     appearance of the bars, in the second one the appearance
     features will be chosen by the library.

     Example1:
          multibarchart('This is the Header text',
          	'My BarchartTitle',
          	'Processors',
          	['processor1','processor2','processor3','processor4'],
          	'Time (seconds)',
          	[['setup time','MediumTurquoise','Plum','pattern2'],
          	    ['sleep time','Blue','Green','pattern5'],
          	    ['running time','Yellow','Plum','pattern1']],
          	[[20,30,40,50],[10,8,5,35],[60,100,20,50]],
          	'This is the Footer text').
     Example2:
          multibarchart('This is the Header text',
          	'My BarchartTitle',
          	'Processors',
          	['processor1','processor2','processor3','processor4'],
          	'Time (seconds)',
          	[['setup time'],['sleep time'],['running time']],
          	[[20,30,40,50],[10,8,5,35],[60,100,20,50]],
          	'This is the Footer text').

 -- PREDICATE: multibarchart/10:
     `multibarchart(Header, BT, XT, XVector, YT, BAtts, YVector,
     YMax, YMin, Footer)'

     This predicate is quite similar to `multibarchart/8', except in
     that you can choose limits in the y axis. The part of the bars
     placed outside the limits will not be plotted.

     Example2:
          multibarchart('This is the Header text',
          	'My BarchartTitle',
          	'Processors',
          	['processor1','processor2','processor3','processor4'],
          	'Time (seconds)',
          	[['setup time'],['sleep time'],['running time']],
          	[[20,30,40,50],[10,8,5,35],[60,100,20,50]],
          	[80],
          	[0],
          	'This is the Footer text').

190.3 Documentation on internals (`genmultibar')
================================================

 -- REGTYPE: multibar_attribute/1:
          multibar_attribute([LegendElement]) :-
                  atomic(LegendElement).
          multibar_attribute([LegendElement,ForegroundColor,BackgroundColor,StipplePattern]) :-
                  atom(LegendElement),
                  color(ForegroundColor),
                  color(BackgroundColor),
                  pattern(StipplePattern).

     Defines the attributes of each feature bar along the different
     datasets.

    LegendElement
          Legend element name. It may be a number or an atom. Every
          `LegendElement' value of the list must be unique.

    `ForegColor'
          It sets the Foreground color of the bar. Its value must be
          a valid color, otherwise the system will throw an
          exception. If the argument value is a variable, it gets
          instantiated to a color chosen by the library.

    `BackgColor'
          It sets the Background color of the bar. Its value must be
          a valid color, otherwise the system will throw an
          exception. If the argument value is a variable, it gets
          instantiated to a color chosen by the library.

    `SPattern'
          It sets the stipple of the bar. Its value must be a valid
          pattern, otherwise the system will throw an exception. If
          the argument value is a variable, it gets instantiated to a
          pattern chosen by the library.

 -- REGTYPE: xelement/1:
          xelement(Label) :-
                  atomic(Label).
     This type defines a dataset label. Although `Label' values may
     be numbers, the will be treated as atoms, So it will be
     displayed at uniform intervals along the x axis.

191 table_widget1 (library)
***************************

*Author(s):* Isabel Martín.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#166 (2003/12/4, 17:39:45 CET)

   In addition to the features explained in the introduction, the
predicates exported by this module depict tables in which the font
weight for the table elements is bold.

   If the arguments are not in a correct format the exception
`error8' will be thrown.

191.1 Usage and interface (`table_widget1')
===========================================

   * *Library usage:*

     `:- use_module(library(table_widget1)).'

   * *Exports:*
        - _Predicates:_

          `tablewidget1/4', `tablewidget1/5'.

        - _Regular Types:_

          `table/1', `image/1'.

   * *Other modules used:*
        - _System library modules:_

          `chartlib/genbar1', `chartlib/bltclass', `chartlib/test_format', `chartlib/install_utils', `lists'.

191.2 Documentation on exports (`table_widget1')
================================================

 -- PREDICATE: tablewidget1/4:
     `tablewidget1(Title, Header, ElementTable, Footer)'

     Shows a regular table in a window. The user does not choose a
     background image.

     Example:
          tablewidget1('This is the title',
          	     'Header text',
          	     [['Number of processors','8'],['Average processors','95'],
          	         ['Average Tasks per fork','7.5']],
          	     'Footer text').

 -- PREDICATE: tablewidget1/5:
     `tablewidget1(Title, Header, ElementTable, Footer,
     BackgroundImage)'

     Shows a regular table in a window. The user must set a
     background image. See the `image/1' type definition.

     Example:
          tablewidget1('This is the title',
          	     'Header text',
          	     [['Number of processors','8'],['Average processors','95'],
          	         ['Average Tasks per fork','7.5']],
          	     'Footer text',
          	     './images/rain.gif')

 -- REGTYPE: table/1:
     A table is a list of rows, each row must contain the same number
     of elements, otherwise the table wouldn't be regular and an
     exception will be thrown by the library. The rows list may not
     be empty.
          table([X]) :-
                  row(X).
          table([X|Xs]) :-
                  row(X),
                  table(Xs).

 -- REGTYPE: image/1:
     Some predicates allow the user to set the widget background
     image, whose is what this type is intended for. The user has to
     take into account the following restrictions:

        * The image must be in gif format.

        * The file path must be absolute.

191.3 Documentation on internals (`table_widget1')
==================================================

 -- REGTYPE: row/1:
          row([X]) :-
                  cell_value(X).
          row([X|Xs]) :-
                  cell_value(X),
                  row(Xs).
     Each row is a list of elements whose type is `cell_value/1'. A
     row cannot be an empty list, as you can see in the definition
     type.

 -- REGTYPE: row/1:
          row([X]) :-
                  cell_value(X).
          row([X|Xs]) :-
                  cell_value(X),
                  row(Xs).
     Each row is a list of elements whose type is `cell_value/1'. A
     row cannot be an empty list, as you can see in the definition
     type.

 -- REGTYPE: cell_value/1:
     This type defines the possible values that a table element have.
     If any cell value is `''', the cell will be displayed empty.
          cell_value(X) :-
                  atomic(X).

192 table_widget2 (library)
***************************

*Author(s):* Isabel Martín.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#167 (2003/12/4, 17:39:48 CET)

   In addition to the features explained in the introduction,
predicates exported by this module display tables in which the font
weight for the elements placed in the first row is bold. The
remaining elements are in medium weight font.

   If the arguments are not in a correct format the exception
`error8' will be thrown.

192.1 Usage and interface (`table_widget2')
===========================================

   * *Library usage:*

     `:- use_module(library(table_widget2)).'

   * *Exports:*
        - _Predicates:_

          `tablewidget2/4', `tablewidget2/5'.

   * *Other modules used:*
        - _System library modules:_

          `chartlib/genbar1', `chartlib/bltclass', `chartlib/table_widget1', `chartlib/test_format', `chartlib/install_utils', `lists'.

192.2 Documentation on exports (`table_widget2')
================================================

 -- PREDICATE: tablewidget2/4:
     `tablewidget2(Title, Header, ElementTable, Footer)'

     Shows a regular table in a window. The system sets a default
     background image for the widget.

     Example:
          tablewidget2('COM Features',
          	     'Extracted from "Inside COM" book ',
          	     [['Feature','Rich people','Bean Plants','C++','COM'],
          	       ['Edible','Yes','Yes','No','No'],
          	       ['Supports inheritance','Yes','Yes','Yes','Yes and No'],
          	       ['Can run for President','Yes','No','No','No']],
          	     'What do you think about COM?').

 -- PREDICATE: tablewidget2/5:
     `tablewidget2(Title, Header, ElementTable, Footer,
     BackgroundImage)'

     This predicate and `tablewidget2/4' are quite similar, except
     that in the already one defined you must set the background
     image.

     Example:
          tablewidget2('COM Features',
          	     'Extracted from "Inside COM" book ',
          	     [['Feature','Rich people','Bean Plants','C++','COM'],
          	       ['Edible','Yes','Yes','No','No'],
          	       ['Supports inheritance','Yes','Yes','Yes','Yes and No'],
          	       ['Can run for President','Yes','No','No','No']],
          	     'What do you think about COM?',
          	     './images/rain.gif').

193 table_widget3 (library)
***************************

*Author(s):* Isabel Martín.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#168 (2003/12/4, 17:39:51 CET)

   The predicates exported by this module display data in a regular
table, as we brought up in the introduction. Both predicates have in
common that the font weight for the elements placed in the first
column is bold and the remaining elements are in medium font weight.

   If the arguments are not in a correct format the exception
`error8' will be thrown.

193.1 Usage and interface (`table_widget3')
===========================================

   * *Library usage:*

     `:- use_module(library(table_widget3)).'

   * *Exports:*
        - _Predicates:_

          `tablewidget3/4', `tablewidget3/5'.

   * *Other modules used:*
        - _System library modules:_

          `chartlib/genbar1', `chartlib/bltclass', `chartlib/table_widget1', `chartlib/test_format', `chartlib/install_utils', `lists'.

193.2 Documentation on exports (`table_widget3')
================================================

 -- PREDICATE: tablewidget3/4:
     `tablewidget3(Title, Header, ElementTable, Footer)'

     Shows a regular table in a window. The user does not choose a
     background image.

     Example:
          tablewidget3('This is the title',
          	     'Header text',
          	     [['Number of processors','8'],['Average processors','95'],
          	       ['Tasks per fork','7.5']],
          	     'Footer text').

 -- PREDICATE: tablewidget3/5:
     `tablewidget3(Title, Header, ElementTable, Footer,
     BackgroundImage)'

     Shows a regular table in a window. The user must set a
     background image.

     Example:
          tablewidget3('This is the title',
          	     'Header text',
          	     [['Number of processors','8'],['Average processors','95'],
          	         ['Average Tasks per fork','7.5']],
          	     'Footer text',
          	     './images/rain.gif')

194 table_widget4 (library)
***************************

*Author(s):* Isabel Martín.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#169 (2003/12/4, 17:39:54 CET)

   In addition to the features explained in the introduction,
predicates exported by this module display tables in which the font
weight for the elements placed in the first row and column is bold.
The remaining elements are in medium weight font.

   If the arguments are not in a correct format the exception
`error8' will be thrown.

194.1 Usage and interface (`table_widget4')
===========================================

   * *Library usage:*

     `:- use_module(library(table_widget4)).'

   * *Exports:*
        - _Predicates:_

          `tablewidget4/4', `tablewidget4/5'.

   * *Other modules used:*
        - _System library modules:_

          `chartlib/genbar1', `chartlib/bltclass', `chartlib/table_widget1', `chartlib/test_format', `chartlib/install_utils', `lists'.

194.2 Documentation on exports (`table_widget4')
================================================

 -- PREDICATE: tablewidget4/4:
     `tablewidget4(Title, Header, ElementTable, Footer)'

     Shows a regular table in a window. The system sets a default
     background image for the widget.

     Example:
          tablewidget4('Some sterEUtypes',
            'Source: Eurostat yearbook, 1999',
            [['Country','Adult alcohol intake per year (litres)',
                 'Cigarettes smoked per day per adult',
                       'Suicides per 100000 people'],
                ['Finland','8.4','2.2','26.3'],['Spain','11.4','5.3','7.5'],
                ['Austria','11.9','4.6','20.7'],['Britain','9.4','4.2','7.1'],
                ['USA','4.7','4.9','13'],['European Union','11.1','4.5','11.9']],
            'This is part of the published table').

 -- PREDICATE: tablewidget4/5:
     `tablewidget4(Title, Header, ElementTable, Footer,
     BackgroundImage)'

     This predicate and `tablewidget4/4' are comparable, except that
     in the already defined you must set the background image.

     Example:
          tablewidget4('Some sterEUtypes',
            'Source: Eurostat yearbook, 1999',
            [['Country','Adult alcohol intake per year (litres)',
                 'Cigarettes smoked per day per adult',
                     'Suicides per 100000 people'],
                ['Finland','8.4','2.2','26.3'],['Spain','11.4','5.3','7.5'],
                ['Austria','11.9','4.6','20.7'],['Britain','9.4','4.2','7.1'],
                ['USA','4.7','4.9','13'],['European Union','11.1','4.5','11.9']],
            'This is part of the published table',
            './images/rain.gif').

195 test_format (library)
*************************

*Author(s):* Isabel Martín.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#170 (2003/12/4, 17:39:57 CET)

   Most of the predicates exported by this module perform some checks
to determine whether the arguments attain some conditions or not. In
the second case an exception will be thrown. To catch the exceptions
you can use the following metapredicates when invoking chartlib
exported predicates:

   * `chartlib_text_error_protect/1'

   * `chartlib_text_error_protect/1'

   Both metapredicates are defined in the chartlib_errhandle module
that comes with this library. Some of the predicates have a
`Predicate' argument which will be used in case of error to show
which chartlib predicate causes the error.

195.1 Usage and interface (`test_format')
=========================================

   * *Library usage:*

     `:- use_module(library(test_format)).'

   * *Exports:*
        - _Predicates:_

          `equalnumber/3', `not_empty/4', `not_empty/3', `check_sublist/4', `valid_format/4', `vectors_format/4', `valid_vectors/4', `valid_attributes/2', `valid_table/2'.

   * *Other modules used:*
        - _System library modules:_

          `chartlib/bltclass', `lists'.

195.2 Documentation on exports (`test_format')
==============================================

 -- PREDICATE: equalnumber/3:
     `equalnumber(X, Y, Predicate)'

     Test whether the list `X' and the list `Y' contain the same
     number of elements.

 -- PREDICATE: not_empty/4:
     `not_empty(X, Y, Z, Predicate)'

     Tests whether at least one the lists `X', `Y' or `Z' are empty.

 -- PREDICATE: not_empty/3:
     `not_empty(X, Y, Predicate)'

     Tests whether the lists `X' or `Y' are empty.

 -- PREDICATE: check_sublist/4:
     `check_sublist(List, Number, Number, Predicate)'

     Tests if the number of elements in each sublist of `List' is
     `Number1' or `Number2'.

 -- PREDICATE: valid_format/4:
     `valid_format(XVector, YVector, BarsAttributes, Predicate)'

     Tests the following restrictions:

        * The `XVector' number of elements is the same as each
          `YVector' sublist number of elements.

        * The `YVector' length is equal to `BarsAttributes' length.

 -- PREDICATE: vectors_format/4:
     `vectors_format(XVector, YVectors, LinesAttributes, Predicate)'

     Tests the following conditions:

        * `YVectors' list and `LinesAttributes' list have the same
          number of elements.

        * `XVector' list and each `YVectors' element have the same
          number of elements.

        * Each sublist of `LinesAttributes' is composed of 5, 3 or 1
          elements.

 -- PREDICATE: valid_vectors/4:
     `valid_vectors(XVector, YVectors, LinesAttributes, Predicate)'

     Tests the following conditions:

        * `XVector' list, `YVectors' list and `LinesAttributes' list
          have the same number of elements.

        * Each sublist of `LinesAttributes' is composed of 5, 3 or 1
          element.

 -- PREDICATE: valid_attributes/2:
     `valid_attributes(BarsAttibuttes, Predicate)'

     Check if each `BarsAttibuttes' element is a list composed of one
     or four elements.

 -- PREDICATE: valid_table/2:
     `valid_table(ElementTable, Predicate)'

     All of the `ElementTable' sublists have the same number of
     elements and are not empty.

196 ProVRML - a Prolog interface for VRML
*****************************************

*Author(s):* Go"ran Smedba"ck, (Some changes by MCL),
`clip@dia.fi.upm.es', `http://www.clip.dia.fi.upm.es/', The CLIP
Group, Facultad de Informa'tica, Universidad Polite'cnica de Madrid.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 0.1#1 (1998/12/10, 16:19:45 MET)

   `ProVRML' is Prolog library to handle VRML code. The library
consists of modules to handle the tokenising, that is breaking the
VRML code into smaller parts that can be analysed further. The
further analysis will be the parsing. This is a complex part of the
library and consists of several modules to handle errors and value
check. When the parsing is done we have the Prolog terms of the VRML
code. The terms are quite similar to the origin VRML code and can
easily be read if you recognise that syntax.

   This Prolog terms of the VRML code is then possible to use for
analysis, reconstruction, reverse enginering, building blocks for
automatic generation of VRML code. There are several possibilities
and these are only some of them.

   When you are done with the Prolog terms for the code, you would
probably want to reverse the action and return to VRML code. This is
done with the code generation modules. These are built up in more or
less the same manner as the parser modules.

196.1 Usage and interface (`provrml')
=====================================

   * *Library usage:*

     `:- use_module(library(provrml)).'

   * *Exports:*
        - _Predicates:_

          `vrml_web_to_terms/2', `vrml_file_to_terms/2', `vrml_web_to_terms_file/2', `vrml_file_to_terms_file/2', `terms_file_to_vrml/2', `terms_file_to_vrml_file/2', `terms_to_vrml_file/2', `terms_to_vrml/2', `vrml_to_terms/2', `vrml_in_out/2', `vrml_http_access/2'.

   * *Other modules used:*
        - _System library modules:_

          `pillow/http', `pillow/html', `provrml/io', `provrml/parser', `provrml/generator', `lists'.

196.2 Documentation on exports (`provrml')
==========================================

 -- PREDICATE: vrml_web_to_terms/2:
     *Usage:* `vrml_web_to_terms(+WEBAddress, -Terms)'
        - _Description:_ Given a address to a VRML-document on the
          Internet, the predicate will return the prolog-terms.

        - _Call and exit should be _compatible_ with:_

          `+WEBAddress' is an atom.   (`basic_props:atm/1')

          `-Terms' is a string (a list of character codes).
          (`basic_props:string/1')

 -- PREDICATE: vrml_file_to_terms/2:
     *Usage 1:* `vrml_file_to_terms(+FileName, -Term)'
        - _Description:_ Given a filename containing a VRML-file the
          predicate returns the prolog terms corresponding.

        - _Call and exit should be _compatible_ with:_

          `+FileName' is an atom.   (`basic_props:atm/1')

          `-Term' is an atom.   (`basic_props:atm/1')

     *Usage 2:* `vrml_file_to_terms(+FileName, +Terms)'
        - _Description:_ Given a filename containing a VRML-file and
          a filename, the predicate write the prolog terms
          corresponding to the filename.

        - _Call and exit should be _compatible_ with:_

          `+FileName' is an atom.   (`basic_props:atm/1')

          `+Terms' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: vrml_web_to_terms_file/2:
     *Usage:* `vrml_web_to_terms_file(+WEBAddress, +FileName)'
        - _Description:_ Given a address to a VRML-document on the
          Internet and a filename, the predicate will write the
          prolog_terms to the file.

        - _Call and exit should be _compatible_ with:_

          `+WEBAddress' is an atom.   (`basic_props:atm/1')

          `+FileName' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: vrml_file_to_terms_file/2:
     No further documentation available for this predicate.

 -- PREDICATE: terms_file_to_vrml/2:
     *Usage:* `terms_file_to_vrml(+FileName, -List)'
        - _Description:_ From a given filename with prologterms on
          the special format, the predicate returns the corresponding
          VRML-code.

        - _Call and exit should be _compatible_ with:_

          `+FileName' is an atom.   (`basic_props:atm/1')

          `-List' is a string (a list of character codes).
          (`basic_props:string/1')

 -- PREDICATE: terms_file_to_vrml_file/2:
     *Usage:* `terms_file_to_vrml_file(+Atom, +Atom)'
        - _Description:_ From a given filename with prologterms on
          the special format, the predicate writes the corresponding
          VRML-code to second filename.

        - _Call and exit should be _compatible_ with:_

          `+Atom' is an atom.   (`basic_props:atm/1')

          `+Atom' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: terms_to_vrml_file/2:
     *Usage:* `terms_to_vrml_file(+Term, +FileName)'
        - _Description:_ Given prolog-terms the predicate writes the
          corresponding VRML-code to the given file.

        - _Call and exit should be _compatible_ with:_

          `+Term' is an atom.   (`basic_props:atm/1')

          `+FileName' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: terms_to_vrml/2:
     *Usage:* `terms_to_vrml(+Term, -VRMLCode)'
        - _Description:_ Given prolog-terms the predicate returns a
          list with the corresponding VRML-code.

        - _Call and exit should be _compatible_ with:_

          `+Term' is an atom.   (`basic_props:atm/1')

          `-VRMLCode' is a string (a list of character codes).
          (`basic_props:string/1')

 -- PREDICATE: vrml_to_terms/2:
     *Usage:* `vrml_to_terms(+VRMLCode, -Terms)'
        - _Description:_ Given a list with VRML-code the predicate
          will return the corresponding prolog-terms.

        - _Call and exit should be _compatible_ with:_

          `+VRMLCode' is a string (a list of character codes).
          (`basic_props:string/1')

          `-Terms' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: vrml_in_out/2:
     *Usage:* `vrml_in_out(+FileName, +FileName)'
        - _Description:_ This is a controll-predicate that given a
          filename to a VRML-file and a filename, the predicate will
          read the VRML-code. Transform it to prolog-terms and then
          transform it back to VRRML-code and write it to the latter
          file.

        - _Call and exit should be _compatible_ with:_

          `+FileName' is an atom.   (`basic_props:atm/1')

          `+FileName' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: vrml_http_access/2:
     *Usage:* `vrml_http_access(+ReadFilename, +BaseFilename)'
        - _Description:_ Given a web-address to a VRML-file the
          predicate will load the code, write it first to the second
          argument with extension '_first.wrl'. Then it transform the
          code to prolog terms and write it with the extension
          '.term'. Transform it back to VRML-code and write it to the
          filename with '.wrl. A good test-predicate.

        - _Call and exit should be _compatible_ with:_

          `+ReadFilename' is an atom.   (`basic_props:atm/1')

          `+BaseFilename' is an atom.   (`basic_props:atm/1')

196.3 Documentation on internals (`provrml')
============================================

 -- PREDICATE: read_page/2:
     *Usage:* `read_page(+WEBAddress, -Data)'
        - _Description:_ This routine reads a page on the web using
          pillow routines.

        - _Call and exit should be _compatible_ with:_

          `+WEBAddress' is an atom.   (`basic_props:atm/1')

          `-Data' is a string (a list of character codes).
          (`basic_props:string/1')

197 boundary (library)
**********************

*Author(s):* Go"ran Smedba"ck.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#171 (2003/12/4, 17:46:50 CET)

   This module offers predicate to check values according to their
boundaries and offers lists of possible node ascendents.

197.1 Usage and interface (`boundary')
======================================

   * *Library usage:*

     `:- use_module(library(boundary)).'

   * *Exports:*
        - _Predicates:_

          `boundary_check/3', `boundary_rotation_first/2', `boundary_rotation_last/2', `reserved_words/1', `children_nodes/1'.

   * *Other modules used:*
        - _System library modules:_

          `aggregates', `dynamic', `iso_misc', `iso_byte_char', `iso_incomplete', `operators', `read', `write', `provrml/internal_types', `provrml/error'.

197.2 Documentation on exports (`boundary')
===========================================

 -- PREDICATE: boundary_check/3:
     *Usage:* `boundary_check(+Value_to_check, +Init_value, +Bound)'
        - _Description:_ This predicate check the boundaries of the
          given value according to the boudary values. If the value
          is wrong according to the boundaries, the value is checked
          according to the initial value given. If the value
          continues to be wrong, an error will be raised accordingly.

        - _Call and exit should be _compatible_ with:_

          `+Value_to_check' is an atom.   (`basic_props:atm/1')

          `+Init_value' is a list of `atm's.   (`basic_props:list/2')

          `+Bound' is a variable interval.
          (`internal_types:bound/1')

 -- PREDICATE: boundary_rotation_first/2:
     *Usage:* `boundary_rotation_first(+Bound_double, -Bound)'
        - _Description:_ The predicate will extract the first bounds
          from a double bound.

        - _Call and exit should be _compatible_ with:_

          `+Bound_double' is a variable interval.
          (`internal_types:bound_double/1')

          `-Bound' is a variable interval.
          (`internal_types:bound/1')

 -- PREDICATE: boundary_rotation_last/2:
     *Usage:* `boundary_rotation_last(+Bound_double, -Bound)'
        - _Description:_ The predicate will extract the last bounds
          from a double bound.

        - _Call and exit should be _compatible_ with:_

          `+Bound_double' is a variable interval.
          (`internal_types:bound_double/1')

          `-Bound' is a variable interval.
          (`internal_types:bound/1')

 -- PREDICATE: reserved_words/1:
     *Usage:* `reserved_words(-List)'
        - _Description:_ Returns a list with the reserved words,
          words prohibited to use in cases not appropiated.

        - _Call and exit should be _compatible_ with:_

          `-List' is a list of `atm's.   (`basic_props:list/2')

 -- PREDICATE: children_nodes/1:
     *Usage:* `children_nodes(-List)'
        - _Description:_ Returns a list of all nodes possible as
          children nodes.

        - _Call and exit should be _compatible_ with:_

          `-List' is a list of `atm's.   (`basic_props:list/2')

198 dictionary (library)
************************

*Author(s):* Go"ran Smedba"ck.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#172 (2003/12/4, 17:47:7 CET)

   This module contains the fixed dictionary. All the nodes in VRML
with their associated fields.

198.1 Usage and interface (`dictionary')
========================================

   * *Library usage:*

     `:- use_module(library(dictionary)).'

   * *Exports:*
        - _Predicates:_

          `dictionary/6'.

   * *Other modules used:*
        - _System library modules:_

          `aggregates', `dynamic', `iso_misc', `iso_byte_char', `iso_incomplete', `operators', `read', `write', `lists', `provrml/internal_types'.

198.2 Documentation on exports (`dictionary')
=============================================

 -- PREDICATE: dictionary/6:
     *Usage 1:* `dictionary(?NodeTypeId, ?AccessType, ?FieldTypeId,
     ?FieldId, -Init_value, -Boundary)'
        - _Description:_ To lookup information about the nodes,
          getting their properties. Note that the type returned for
          the bound can be of two different types bound or
          bound_double. The rotation type have one bound for the
          directions and one for the degree of rotation.

        - _Call and exit should be _compatible_ with:_

          `?NodeTypeId' is an atom.   (`basic_props:atm/1')

          `?AccessType' is an atom.   (`basic_props:atm/1')

          `?FieldTypeId' is an atom.   (`basic_props:atm/1')

          `?FieldId' is an atom.   (`basic_props:atm/1')

          `-Init_value' is a list of `atm's.   (`basic_props:list/2')

          `-Boundary' is a variable interval.
          (`internal_types:bound/1')

     *Usage 2:* `dictionary(?NodeTypeId, ?AccessType, ?FieldTypeId,
     ?FieldId, -Init_value, -Boundary)'
        - _Description:_ To lookup information about the nodes,
          getting their properties. Note that the type returned for
          the bound can be of two different types bound or
          bound_double. The rotation type have one bound for the
          directions and one for the degree of rotation.

        - _Call and exit should be _compatible_ with:_

          `?NodeTypeId' is an atom.   (`basic_props:atm/1')

          `?AccessType' is an atom.   (`basic_props:atm/1')

          `?FieldTypeId' is an atom.   (`basic_props:atm/1')

          `?FieldId' is an atom.   (`basic_props:atm/1')

          `-Init_value' is a list of `atm's.   (`basic_props:list/2')

          `-Boundary' is a variable interval.
          (`internal_types:bound_double/1')

199 dictionary_tree (library)
*****************************

*Author(s):* Go"ran Smedba"ck.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#173 (2003/12/4, 17:47:16 CET)

   This module offers a dynamic tree structured dictionary a bit
combined with predicates that gives it the useability to be the
dictionary for the parser.

199.1 Usage and interface (`dictionary_tree')
=============================================

   * *Library usage:*

     `:- use_module(library(dictionary_tree)).'

   * *Exports:*
        - _Predicates:_

          `create_dictionaries/1', `is_dictionaries/1', `get_definition_dictionary/2', `get_prototype_dictionary/2', `dictionary_insert/5', `dictionary_lookup/5', `merge_tree/2'.

   * *Other modules used:*
        - _System library modules:_

          `aggregates', `dynamic', `iso_misc', `iso_byte_char', `iso_incomplete', `operators', `read', `write', `lists', `provrml/internal_types'.

199.2 Documentation on exports (`dictionary_tree')
==================================================

 -- PREDICATE: create_dictionaries/1:
     *Usage:* `create_dictionaries(-Dictionary)'
        - _Description:_ Returns a dictionary. A general name was
          used if the user would like to change the code to include
          more dictionaries.

        - _Call and exit should be _compatible_ with:_

          `-Dictionary' is a dictionary.
          (`internal_types:dictionary/1')

 -- PREDICATE: is_dictionaries/1:
     *Usage:* `is_dictionaries(?Dictionary)'
        - _Description:_ Is the argument a dictionary is solved by
          this predicate.

        - _Call and exit should be _compatible_ with:_

          `?Dictionary' is a dictionary.
          (`internal_types:dictionary/1')

 -- PREDICATE: get_definition_dictionary/2:
     *Usage:* `get_definition_dictionary(+Dictionary, -Tree)'
        - _Description:_ Returns the definition dictionary (for the
          moment there is only one dictionary), which is a tree
          representation.

        - _Call and exit should be _compatible_ with:_

          `+Dictionary' is a dictionary.
          (`internal_types:dictionary/1')

          `-Tree' is a tree structure.   (`internal_types:tree/1')

 -- PREDICATE: get_prototype_dictionary/2:
     *Usage:* `get_prototype_dictionary(+Dictionary, -Tree)'
        - _Description:_ Returns the prototype dictionary (for the
          moment there is only one dictionary), which is a tree
          representation.

        - _Call and exit should be _compatible_ with:_

          `+Dictionary' is a dictionary.
          (`internal_types:dictionary/1')

          `-Tree' is a tree structure.   (`internal_types:tree/1')

 -- PREDICATE: dictionary_insert/5:
     *Usage:* `dictionary_insert(+Key, +Type, +Field, +Dictionary,
     ?Info)'
        - _Description:_ The predicate will search for the place for
          the Key and return Info, if the element inserted had a post
          before (same key value) multiple else new. The dictionary
          is dynamic and do not need output because of using unbinded
          variables.

        - _Call and exit should be _compatible_ with:_

          `+Key' is an atom.   (`basic_props:atm/1')

          `+Type' is an atom.   (`basic_props:atm/1')

          `+Field' is any term.   (`basic_props:term/1')

          `+Dictionary' is a tree structure.
          (`internal_types:tree/1')

          `?Info' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: dictionary_lookup/5:
     *Usage:* `dictionary_lookup(+Key, ?Type, ?Field, +Dictionary,
     -Info)'
        - _Description:_ The predicate will search for the Key and
          return Info;defined or undefined accordingly. If defined
          the fields will be filled as well. The predicate do not
          insert the element.

        - _Call and exit should be _compatible_ with:_

          `+Key' is an atom.   (`basic_props:atm/1')

          `?Type' is an atom.   (`basic_props:atm/1')

          `?Field' is any term.   (`basic_props:term/1')

          `+Dictionary' is a dictionary.
          (`internal_types:dictionary/1')

          `-Info' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: merge_tree/2:
     *Usage:* `merge_tree(+Tree, +Tree)'
        - _Description:_ The predicate can be used for adding a tree
          dictionary to another one (the second). It will remove
          equal posts but posts with a slight difference will be
          inserted. The resulting tree will be the second tree.

        - _Call and exit should be _compatible_ with:_

          `+Tree' is a tree structure.   (`internal_types:tree/1')

          `+Tree' is a tree structure.   (`internal_types:tree/1')

200 error (library)
*******************

*Author(s):* Go"ran Smedba"ck.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#179 (2003/12/4, 19:25:17 CET)

   This file implements error predicates of different types.

200.1 Usage and interface (`error')
===================================

   * *Library usage:*

     `:- use_module(library(error)).'

   * *Exports:*
        - _Predicates:_

          `error_vrml/1', `output_error/1'.

   * *Other modules used:*
        - _System library modules:_

          `write'.

200.2 Documentation on exports (`error')
========================================

 -- PREDICATE: error_vrml/1:
     *Usage:* `error_vrml(+Structure)'
        - _Description:_ Given a structure with the error type as its
          head with possible arguments, it will write the associated
          error-text.

        - _Call and exit should be _compatible_ with:_

          `+Structure' is any term.   (`basic_props:term/1')

 -- PREDICATE: output_error/1:
     *Usage:* `output_error(+Message)'
        - _Description:_ This predicate will print the error message
          given as the argument. This predicate is used for warnings
          that only needs to be given as information and not
          necessarily give an error by the VRML browser.

        - _Call and exit should be _compatible_ with:_

          `+Message' is a list of `atm's.   (`basic_props:list/2')

201 field_type (library)
************************

*Author(s):* Go"ran Smedba"ck.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#174 (2003/12/4, 17:47:35 CET)

201.1 Usage and interface (`field_type')
========================================

   * *Library usage:*

     `:- use_module(library(field_type)).'

   * *Exports:*
        - _Predicates:_

          `fieldType/1'.

201.2 Documentation on exports (`field_type')
=============================================

 -- PREDICATE: fieldType/1:
     *Usage:* `fieldType(+FieldTypeId)'
        - _Description:_ Boolean predicate used to check the
          fieldTypeId with the defiened.

        - _Call and exit should be _compatible_ with:_

          `+FieldTypeId' is an atom.   (`basic_props:atm/1')

202 field_value (library)
*************************

*Author(s):* Go"ran Smedba"ck.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#175 (2003/12/4, 17:47:48 CET)

202.1 Usage and interface (`field_value')
=========================================

   * *Library usage:*

     `:- use_module(library(field_value)).'

   * *Exports:*
        - _Predicates:_

          `fieldValue/6', `mfstringValue/5'.

        - _Properties:_

          `parse/1'.

   * *Other modules used:*
        - _System library modules:_

          `lists', `provrml/parser', `provrml/parser_util', `provrml/error'.

202.2 Documentation on exports (`field_value')
==============================================

 -- PREDICATE: fieldValue/6:
     No further documentation available for this predicate.

 -- PREDICATE: mfstringValue/5:
     No further documentation available for this predicate.

 -- PROPERTY: parse/1:
     A property, defined as follows:
               parse(_1).
               parse(parse(In,Out,Env,Dic)) :-
                       list(In),
                       list(Out),
                       environment(Env),
                       dictionary(Dic).

203 field_value_check (library)
*******************************

*Author(s):* Go"ran Smedba"ck.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#176 (2003/12/4, 17:47:53 CET)

203.1 Usage and interface (`field_value_check')
===============================================

   * *Library usage:*

     `:- use_module(library(field_value_check)).'

   * *Exports:*
        - _Predicates:_

          `fieldValue_check/8', `mfstringValue/7'.

   * *Other modules used:*
        - _System library modules:_

          `lists', `provrml/io', `provrml/generator_util', `provrml/boundary', `provrml/tokeniser', `provrml/generator', `provrml/parser_util'.

203.2 Documentation on exports (`field_value_check')
====================================================

 -- PREDICATE: fieldValue_check/8:
     No further documentation available for this predicate.

 -- PREDICATE: mfstringValue/7:
     No further documentation available for this predicate.

204 generator (library)
***********************

*Author(s):* Go"ran Smedba"ck.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

204.1 Usage and interface (`generator')
=======================================

   * *Library usage:*

     `:- use_module(library(generator)).'

   * *Exports:*
        - _Predicates:_

          `generator/2', `nodeDeclaration/4'.

   * *Other modules used:*
        - _System library modules:_

          `aggregates', `dynamic', `iso_misc', `iso_byte_char', `iso_incomplete', `operators', `read', `write', `provrml/lookup', `provrml/io', `provrml/generator_util', `provrml/parser_util', `provrml/error', `provrml/internal_types'.

204.2 Documentation on exports (`generator')
============================================

 -- PREDICATE: generator/2:
     *Usage:* `generator(+Terms, -VRML)'
        - _Description:_ This predicate is the generator of VRML
          code. It accepts a list of terms that is correct VRML code,
          other kind of terms will be rejected will errormessage
          accordingly. The output is a string of correct VRML code,
          acceptable for VRML browsers.

        - _Call and exit should be _compatible_ with:_

          `+Terms' is a list of `terms's.   (`basic_props:list/2')

          `-VRML' is a string (a list of character codes).
          (`basic_props:string/1')

 -- PREDICATE: nodeDeclaration/4:
     No further documentation available for this predicate.

205 generator_util (library)
****************************

*Author(s):* Go"ran Smedba"ck.

205.1 Usage and interface (`generator_util')
============================================

   * *Library usage:*

     `:- use_module(library(generator_util)).'

   * *Exports:*
        - _Predicates:_

          `reading/4', `reading/5', `reading/6', `open_node/6', `close_node/5', `close_nodeGut/4', `open_PROTO/4', `close_PROTO/6', `open_EXTERNPROTO/5', `close_EXTERNPROTO/6', `open_DEF/5', `close_DEF/5', `open_Script/5', `close_Script/5', `decompose_field/3', `indentation_list/2', `start_vrmlScene/4', `remove_comments/4'.

   * *Other modules used:*
        - _System library modules:_

          `provrml/error', `lists', `provrml/io', `provrml/field_value', `provrml/field_value_check', `provrml/lookup', `provrml/parser_util'.

205.2 Documentation on exports (`generator_util')
=================================================

 -- PREDICATE: reading/4:
     *Usage 1:* `reading(+IS, +NodeTypeId, +ParseIn, -ParseOut)'
        - _Description:_ This predicate will refer to a formerly
          introduced interface. We do a checkup of the access type
          and output the values.

        - _Call and exit should be _compatible_ with:_

          `+IS' is an atom.   (`basic_props:atm/1')

          `+NodeTypeId' is an atom.   (`basic_props:atm/1')

          `+ParseIn' is a parse structure.
          (`internal_types:parse/1')

          `-ParseOut' is a parse structure.
          (`internal_types:parse/1')

     *Usage 2:* `reading(+NodeGut, +NodeName, +ParseIn, -ParseOut)'
        - _Description:_ This predicate will read a node gut and will
          check the field according to the name.

        - _Call and exit should be _compatible_ with:_

          `+NodeGut' is an atom.   (`basic_props:atm/1')

          `+NodeName' is an atom.   (`basic_props:atm/1')

          `+ParseIn' is a parse structure.
          (`internal_types:parse/1')

          `-ParseOut' is a parse structure.
          (`internal_types:parse/1')

 -- PREDICATE: reading/5:
     No further documentation available for this predicate.

 -- PREDICATE: reading/6:
     No further documentation available for this predicate.

 -- PREDICATE: open_node/6:
     No further documentation available for this predicate.

 -- PREDICATE: close_node/5:
     No further documentation available for this predicate.

 -- PREDICATE: close_nodeGut/4:
     No further documentation available for this predicate.

 -- PREDICATE: open_PROTO/4:
     No further documentation available for this predicate.

 -- PREDICATE: close_PROTO/6:
     No further documentation available for this predicate.

 -- PREDICATE: open_EXTERNPROTO/5:
     No further documentation available for this predicate.

 -- PREDICATE: close_EXTERNPROTO/6:
     No further documentation available for this predicate.

 -- PREDICATE: open_DEF/5:
     No further documentation available for this predicate.

 -- PREDICATE: close_DEF/5:
     No further documentation available for this predicate.

 -- PREDICATE: open_Script/5:
     No further documentation available for this predicate.

 -- PREDICATE: close_Script/5:
     No further documentation available for this predicate.

 -- PREDICATE: decompose_field/3:
     No further documentation available for this predicate.

 -- PREDICATE: indentation_list/2:
     *Usage:* `indentation_list(+Parse, -IndList)'
        - _Description:_ This predcate will construct a list with
          indentations to be output before text. The information of
          the indentations is inside the parse structure.

        - _Call and exit should be _compatible_ with:_

          `+Parse' is a parse structure.   (`internal_types:parse/1')

          `-IndList' is a list of `atm's.   (`basic_props:list/2')

 -- PREDICATE: start_vrmlScene/4:
     No further documentation available for this predicate.

 -- PREDICATE: remove_comments/4:
     *Usage:* `remove_comments(+Value, -CommentsBefore, -ValueClean,
     -CommentsAfter)'
        - _Description:_ The predicate will remove comments and
          return the comments before and after the pure value.

        - _Call and exit should be _compatible_ with:_

          `+Value' is a list of `atm's.   (`basic_props:list/2')

          `-CommentsBefore' is a list of `atm's.
          (`basic_props:list/2')

          `-ValueClean' is an atom.   (`basic_props:atm/1')

          `-CommentsAfter' is a list of `atm's.
          (`basic_props:list/2')

206 internal_types (library)
****************************

*Author(s):* Go"ran Smedba"ck.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#177 (2003/12/4, 17:48:37 CET)

   These are the internal data types used in the predicates. They are
only used to simplify this documentation and make it more
understandable.

   Implemented by Go"ran Smedba"ck

206.1 Usage and interface (`internal_types')
============================================

   * *Library usage:*

     `:- use_module(library(internal_types)).'

   * *Exports:*
        - _Regular Types:_

          `bound/1', `bound_double/1', `dictionary/1', `environment/1', `parse/1', `tree/1', `whitespace/1'.

206.2 Documentation on exports (`internal_types')
=================================================

 -- REGTYPE: bound/1:
     Min is a number or an atom that indicates the minimal value, Max
     indicates the maximal.
          bound(bound(Min,Max)) :-
                  atm(Min),
                  atm(Max).

     *Usage:* `bound(Bound)'
        - _Description:_ `Bound' is a variable interval.

 -- REGTYPE: bound_double/1:
     Min is a number or an atom that indicates the minimal value, Max
     indicates the maximal. The first two for some value and the
     second pair for some other. Typically used for types that are
     compound, e.g., rotationvalue.
          bound_double(bound(Min0,Max0,Min1,Max1)) :-
                  atm(Min0),
                  atm(Max0),
                  atm(Min1),
                  atm(Max1).

     *Usage:* `bound_double(Bound)'
        - _Description:_ `Bound' is a variable interval.

 -- REGTYPE: dictionary/1:
     Dic is a tree structure and is used as the internal
     representation of the dictionary.
          dictionary(dic(Dic)) :-
                  tree(Dic).

     *Usage:* `dictionary(Dictionary)'
        - _Description:_ `Dictionary' is a dictionary.

 -- REGTYPE: environment/1:
     EnvironmentType one of 'DEF','PROTO','EXTERNPROTO' with the name
     Name. Whitespace is a structure with whitespace information.
          environment(env(Env,Name,WhiteSpace)) :-
                  atm(Env),
                  atm(Name),
                  whitespace(WhiteSpace).

     *Usage:* `environment(Environment)'
        - _Description:_ `Environment' is an environment structure.

 -- REGTYPE: parse/1:
     In is the list of tokens to parse and Out is the resulting list
     after the parsing. Env is of type env and is the
     environment-structure.The dictinonary Dic contains created
     information and structures.
          parse(parse(In,Out,Env,Dic)) :-
                  list(In),
                  list(Out),
                  environment(Env),
                  dictionary(Dic).

     *Usage:* `parse(Parse)'
        - _Description:_ `Parse' is a parse structure.

 -- REGTYPE: tree/1:
     Key is the search-key, Leaf is the information, Left and Right
     are more dictionary posts, where Left have less Key-value.
          tree(tree(Key,Leaf,Left,Right)) :-
                  atm(Key),
                  leaf(Leaf),
                  tree(Left),
                  tree(Right).

     *Usage:* `tree(Tree)'
        - _Description:_ `Tree' is a tree structure.

 -- REGTYPE: whitespace/1:
     The Row and Indentation information. The row information used
     when parsing the VRML code to give accurate error position and
     the indentation is used when generating VRML code from terms.
          whitespace(w(Row,Indentation)) :-
                  number(Row),
                  number(Indentation).

     *Usage:* `whitespace(Whitespace)'
        - _Description:_ `Whitespace' is a whitespace structure.

207 io (library)
****************

*Author(s):* Go"ran Smedba"ck.

   *Version:* 0.1#2 (1998/12/2)

   This file implements I/O predicates of different types.

   Implemented by Go"ran Smedba"ck

207.1 Usage and interface (`io')
================================

   * *Library usage:*

     `:- use_module(library(io)).'

   * *Exports:*
        - _Predicates:_

          `out/1', `out/3', `convert_atoms_to_string/2', `read_terms_file/2', `write_terms_file/2', `read_vrml_file/2', `write_vrml_file/2'.

   * *Other modules used:*
        - _System library modules:_

          `aggregates', `dynamic', `iso_misc', `iso_byte_char', `iso_incomplete', `operators', `read', `write', `lists', `format'.

207.2 Documentation on exports (`io')
=====================================

 -- PREDICATE: out/1:
     *Usage:* `out(+ListOfOutput)'
        - _Description:_ The predicate used is out/3 (DCG) where we
          will 'save' the output in the second argument. The tird
          argument is the rest, nil.

        - _Call and exit should be _compatible_ with:_

          `+ListOfOutput' is a list of `atm's.
          (`basic_props:list/2')

 -- PREDICATE: out/3:
     No further documentation available for this predicate.

 -- PREDICATE: convert_atoms_to_string/2:
     *Usage:* `convert_atoms_to_string(+Atoms, -String)'
        - _Description:_ The predicate transforms a list of atoms to
          a string.

        - _Call and exit should be _compatible_ with:_

          `+Atoms' is a list of `atm's.   (`basic_props:list/2')

          `-String' is a list of `num's.   (`basic_props:list/2')

 -- PREDICATE: read_terms_file/2:
     *Usage:* `read_terms_file(+Filename, -Term)'
        - _Description:_ Given a filename to a file with terms, the
          predicate reads the terms and are returned in the second
          argument. `Filename' is an atom and `Term' is the read
          prolog terms.

        - _Call and exit should be _compatible_ with:_

          `+Filename' is an atom.   (`basic_props:atm/1')

          `-Term' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: write_terms_file/2:
     *Usage:* `write_terms_file(+FileName, +List)'
        - _Description:_ Given a filename and a list of terms the
          predicate will write them down to the file.

        - _Call and exit should be _compatible_ with:_

          `+FileName' is an atom.   (`basic_props:atm/1')

          `+List' is a list of `atm's.   (`basic_props:list/2')

 -- PREDICATE: read_vrml_file/2:
     *Usage:* `read_vrml_file(+FileName, -Data)'
        - _Description:_ Given a filename, the predicate returns the
          substance.

        - _Call and exit should be _compatible_ with:_

          `+FileName' is an atom.   (`basic_props:atm/1')

          `-Data' is a string (a list of character codes).
          (`basic_props:string/1')

 -- PREDICATE: write_vrml_file/2:
     *Usage:* `write_vrml_file(+FileName, +Data)'
        - _Description:_ Given a filename and data in form of a
          string, the predicate will write the data to the named file.

        - _Call and exit should be _compatible_ with:_

          `+FileName' is an atom.   (`basic_props:atm/1')

          `+Data' is a string (a list of character codes).
          (`basic_props:string/1')

208 lookup (library)
********************

*Author(s):* Go"ran Smedba"ck.

   *Version:* 0.1 (1999/1/14, 13:30:46 MET)

208.1 Usage and interface (`lookup')
====================================

   * *Library usage:*

     `:- use_module(library(lookup)).'

   * *Exports:*
        - _Predicates:_

          `create_proto_element/3', `get_prototype_interface/2', `get_prototype_definition/2', `lookup_check_node/4', `lookup_check_field/6', `lookup_check_interface_fieldValue/8', `lookup_field/4', `lookup_route/5', `lookup_fieldTypeId/1', `lookup_get_fieldType/4', `lookup_field_access/4', `lookup_set_def/3', `lookup_set_prototype/4', `lookup_set_extern_prototype/4'.

   * *Other modules used:*
        - _System library modules:_

          `aggregates', `dynamic', `iso_misc', `iso_byte_char', `iso_incomplete', `operators', `read', `write', `lists', `provrml/error', `provrml/internal_types', `provrml/io', `provrml/parser_util', `provrml/parser', `provrml/dictionary', `provrml/dictionary_tree', `provrml/field_value_check', `provrml/boundary', `provrml/generator_util', `provrml/field_type', `provrml/field_value'.

208.2 Documentation on exports (`lookup')
=========================================

 -- PREDICATE: create_proto_element/3:
     *Usage:* `create_proto_element(+Interface, +Definition, -Proto)'
        - _Description:_ The predicate will construct a proto
          structure containing the interface and the definition.

        - _Call and exit should be _compatible_ with:_

          `+Interface' is any term.   (`basic_props:term/1')

          `+Definition' is any term.   (`basic_props:term/1')

          `-Proto' is any term.   (`basic_props:term/1')

 -- PREDICATE: get_prototype_interface/2:
     *Usage:* `get_prototype_interface(+Proto, -Interface)'
        - _Description:_ The predicate will return the interface from
          a proto structure.

        - _Call and exit should be _compatible_ with:_

          `+Proto' is any term.   (`basic_props:term/1')

          `-Interface' is any term.   (`basic_props:term/1')

 -- PREDICATE: get_prototype_definition/2:
     *Usage:* `get_prototype_definition(+Proto, -Definition)'
        - _Description:_ The predicate will return the definition
          from a proto structure.

        - _Call and exit should be _compatible_ with:_

          `+Proto' is any term.   (`basic_props:term/1')

          `-Definition' is any term.   (`basic_props:term/1')

 -- PREDICATE: lookup_check_node/4:
     No further documentation available for this predicate.

 -- PREDICATE: lookup_check_field/6:
     No further documentation available for this predicate.

 -- PREDICATE: lookup_check_interface_fieldValue/8:
     *Usage:* `lookup_check_interface_fieldValue(+ParseIn, -ParseOut,
     +AccessType, +FieldType, +Id, +FieldValue, DCGIn, DCGOut)'
        - _Description:_ The predicate formats the output for the
          interface part of the prototype. It also checks the values
          for the fields.

        - _Call and exit should be _compatible_ with:_

          `field_value:parse(+ParseIn)'  (`field_value:parse/1')

          `field_value:parse(-ParseOut)'  (`field_value:parse/1')

          `+AccessType' is an atom.   (`basic_props:atm/1')

          `+FieldType' is any term.   (`basic_props:term/1')

          `+Id' is an atom.   (`basic_props:atm/1')

          `+FieldValue' is any term.   (`basic_props:term/1')

          `DCGIn' is a string (a list of character codes).
          (`basic_props:string/1')

          `DCGOut' is a string (a list of character codes).
          (`basic_props:string/1')

 -- PREDICATE: lookup_field/4:
     *Usage:* `lookup_field(+Parse, +FieldTypeId, +FieldId0,
     +FieldId1)'
        - _Description:_ The predicate will control that the two
          connected Fields are of the same type, e.g., SFColor -
          SFColor, MFVec3f - MFVec3f.

        - _Call and exit should be _compatible_ with:_

          `field_value:parse(+Parse)'  (`field_value:parse/1')

          `+FieldTypeId' is an atom.   (`basic_props:atm/1')

          `+FieldId0' is an atom.   (`basic_props:atm/1')

          `+FieldId1' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: lookup_route/5:
     *Usage:* `lookup_route(+Parse, +NodeTypeId0, +FieldId0,
     +NodeTypeId1, +FieldId1)'
        - _Description:_ The predicate will check the routing
          behaviour for two given fields. They will be checked
          according to the binding rules, like name changes access
          proporties. The node types for the field must of course be
          given for the identification.

        - _Call and exit should be _compatible_ with:_

          `field_value:parse(+Parse)'  (`field_value:parse/1')

          `+NodeTypeId0' is an atom.   (`basic_props:atm/1')

          `+FieldId0' is an atom.   (`basic_props:atm/1')

          `+NodeTypeId1' is an atom.   (`basic_props:atm/1')

          `+FieldId1' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: lookup_fieldTypeId/1:
     *Usage:* `lookup_fieldTypeId(+FieldTypeId)'
        - _Description:_ The predicate just make a check to see if
          the given FieldType id is among the allowed. You can not
          construct own ones and the check is mearly a spellcheck.

        - _Call and exit should be _compatible_ with:_

          `+FieldTypeId' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: lookup_get_fieldType/4:
     *Usage:* `lookup_get_fieldType(+Parse, +NodeTypeId, +field_Id,
     -FieldType)'
        - _Description:_ The predicate will return the given field's
          type. It will start the search in the ordinar dictionary
          and then to the personal dictionary sarting off with
          'PROTO'. After it will go for 'DEF' and 'EXTERNPROTO'.

        - _Call and exit should be _compatible_ with:_

          `field_value:parse(+Parse)'  (`field_value:parse/1')

          `+NodeTypeId' is an atom.   (`basic_props:atm/1')

          `+field_Id' is an atom.   (`basic_props:atm/1')

          `-FieldType' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: lookup_field_access/4:
     *Usage:* `lookup_field_access(+Parse, +NodenameId, +FieldId,
     +FieldId)'
        - _Description:_ The predicate will control that the access
          proporties are correct according to the certain rules that
          we have. It makes a check to see if the fields are of the
          same access type or if one of them is an exposedField. It
          is not doing a route check up to control that behaviour
          entirely.

        - _Call and exit should be _compatible_ with:_

          `field_value:parse(+Parse)'  (`field_value:parse/1')

          `+NodenameId' is an atom.   (`basic_props:atm/1')

          `+FieldId' is an atom.   (`basic_props:atm/1')

          `+FieldId' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: lookup_set_def/3:
     *Usage:* `lookup_set_def(+Parse, +Name, +Node)'
        - _Description:_ The predicate will enter a new post in the
          personal dictionary for the node definition.

        - _Call and exit should be _compatible_ with:_

          `field_value:parse(+Parse)'  (`field_value:parse/1')

          `+Name' is an atom.   (`basic_props:atm/1')

          `+Node' is any term.   (`basic_props:term/1')

 -- PREDICATE: lookup_set_prototype/4:
     *Usage:* `lookup_set_prototype(+Parse, +Name, +Interface,
     +Definition)'
        - _Description:_ The predicate will insert the prototype
          definition in the personal dictionary and will give a
          warning if there is a multiple name given.

        - _Call and exit should be _compatible_ with:_

          `field_value:parse(+Parse)'  (`field_value:parse/1')

          `+Name' is an atom.   (`basic_props:atm/1')

          `+Interface' is any term.   (`basic_props:term/1')

          `+Definition' is any term.   (`basic_props:term/1')

 -- PREDICATE: lookup_set_extern_prototype/4:
     *Usage:* `lookup_set_extern_prototype(+Parse, +Name, +Interface,
     +Strings)'
        - _Description:_ The predicate will insert the external
          prototype definition in the personal dictionary and will
          give a warning if there is a multiple name given.

        - _Call and exit should be _compatible_ with:_

          `field_value:parse(+Parse)'  (`field_value:parse/1')

          `+Name' is an atom.   (`basic_props:atm/1')

          `+Interface' is any term.   (`basic_props:term/1')

          `+Strings' is any term.   (`basic_props:term/1')

209 parser (library)
********************

*Author(s):* Go"ran Smedba"ck.

209.1 Usage and interface (`parser')
====================================

   * *Library usage:*

     `:- use_module(library(parser)).'

   * *Exports:*
        - _Predicates:_

          `parser/2', `nodeDeclaration/4'.

        - _Properties:_

          `field_Id/1'.

   * *Other modules used:*
        - _System library modules:_

          `aggregates', `dynamic', `iso_misc', `iso_byte_char', `iso_incomplete', `operators', `read', `write', `lists', `provrml/lookup', `provrml/field_value', `provrml/tokeniser', `provrml/parser_util', `provrml/possible', `provrml/error'.

209.2 Documentation on exports (`parser')
=========================================

 -- PREDICATE: parser/2:
     *Usage:* `parser(+VRML, -Terms)'
        - _Description:_ The parser uses a tokeniser to read the
          input text string of VRML code and returns a list with the
          corresponding terms. The tokens will be read in this parser
          as the grammar says. The parser is according to the
          specification of the VRML grammar, accept that it is
          performed over tokens in sted of the actual code.

        - _Call and exit should be _compatible_ with:_

          `+VRML' is a string (a list of character codes).
          (`basic_props:string/1')

          `-Terms' is a list of `terms's.   (`basic_props:list/2')

 -- PREDICATE: nodeDeclaration/4:
     No further documentation available for this predicate.

 -- PROPERTY: field_Id/1:
     A property, defined as follows:
               field_Id(_1).

210 parser_util (library)
*************************

*Author(s):* Go"ran Smedba"ck.

210.1 Usage and interface (`parser_util')
=========================================

   * *Library usage:*

     `:- use_module(library(parser_util)).'

   * *Exports:*
        - _Predicates:_

          `at_least_one/4', `at_least_one/5', `fillout/4', `fillout/5', `create_node/3', `create_field/3', `create_field/4', `create_field/5', `create_directed_field/5', `correct_commenting/4', `create_parse_structure/1', `create_parse_structure/2', `create_parse_structure/3', `create_environment/4', `insert_comments_in_beginning/3', `get_environment_name/2', `get_environment_type/2', `get_row_number/2', `add_environment_whitespace/3', `get_indentation/2', `inc_indentation/2', `dec_indentation/2', `add_indentation/3', `reduce_indentation/3', `push_whitespace/3', `push_dictionaries/3', `get_parsed/2', `get_environment/2', `inside_proto/1', `get_dictionaries/2', `strip_from_list/2', `strip_from_term/2', `strip_clean/2', `strip_exposed/2', `strip_restricted/2', `strip_interface/2', `set_parsed/3', `set_environment/3', `insert_parsed/3', `reverse_parsed/2', `stop_parse/2', `look_first_parsed/2', `get_first_parsed/3', `remove_code/3', `look_ahead/3'.

   * *Other modules used:*
        - _System library modules:_

          `aggregates', `dynamic', `iso_misc', `iso_byte_char', `iso_incomplete', `operators', `read', `write', `lists', `provrml/dictionary_tree', `provrml/internal_types'.

210.2 Documentation on exports (`parser_util')
==============================================

 -- PREDICATE: at_least_one/4:
     No further documentation available for this predicate.

 -- PREDICATE: at_least_one/5:
     No further documentation available for this predicate.

 -- PREDICATE: fillout/4:
     No further documentation available for this predicate.

 -- PREDICATE: fillout/5:
     No further documentation available for this predicate.

 -- PREDICATE: create_node/3:
     *Usage:* `create_node(+NodeTypeId, +Parse, -Node)'
        - _Description:_ The predicate will construct a node term
          with the read guts which is inside the parse structure. A
          node consists of its name and one argument, a list of its
          fields.

        - _Call and exit should be _compatible_ with:_

          `+NodeTypeId' is an atom.   (`basic_props:atm/1')

          `+Parse' is a parse structure.   (`internal_types:parse/1')

          `-Node' is any term.   (`basic_props:term/1')

 -- PREDICATE: create_field/3:
     *Usage:* `create_field(+FieldNameId, +Arguments, -Field)'
        - _Description:_ The predicate will construct a field with
          the Id as the fieldname and the arguments as they are, in a
          double list, which results in a single list or a single
          list which will result in free arguments.

        - _Call and exit should be _compatible_ with:_

          `+FieldNameId' is an atom.   (`basic_props:atm/1')

          `+Arguments' is any term.   (`basic_props:term/1')

          `-Field' is any term.   (`basic_props:term/1')

 -- PREDICATE: create_field/4:
     *Usage:* `create_field(+FieldAccess, +FieldType, +FieldId,
     -Field)'
        - _Description:_ The predicate will construct a field with
          its access type as the name with type and id as arguments.

        - _Call and exit should be _compatible_ with:_

          `+FieldAccess' is an atom.   (`basic_props:atm/1')

          `+FieldType' is an atom.   (`basic_props:atm/1')

          `+FieldId' is an atom.   (`basic_props:atm/1')

          `-Field' is any term.   (`basic_props:term/1')

 -- PREDICATE: create_field/5:
     *Usage:* `create_field(+FieldAccess, +FieldType, +FieldId,
     +Fieldvalue, -Field)'
        - _Description:_ The predicate will construct a field with
          its access type as the name with type, id and value as
          arguments.

        - _Call and exit should be _compatible_ with:_

          `+FieldAccess' is an atom.   (`basic_props:atm/1')

          `+FieldType' is an atom.   (`basic_props:atm/1')

          `+FieldId' is an atom.   (`basic_props:atm/1')

          `+Fieldvalue' is any term.   (`basic_props:term/1')

          `-Field' is any term.   (`basic_props:term/1')

 -- PREDICATE: create_directed_field/5:
     *Usage:* `create_directed_field(+Access, +Type, +Id0, +Id1,
     -Field)'
        - _Description:_ The predicate will construct a directed
          field with the key word IS in the middle. Its access type
          as the name with type, from id0 and to id1 as arguments.

        - _Call and exit should be _compatible_ with:_

          `+Access' is an atom.   (`basic_props:atm/1')

          `+Type' is an atom.   (`basic_props:atm/1')

          `+Id0' is an atom.   (`basic_props:atm/1')

          `+Id1' is an atom.   (`basic_props:atm/1')

          `-Field' is any term.   (`basic_props:term/1')

 -- PREDICATE: correct_commenting/4:
     *Usage:* `correct_commenting(+Place, +Comment, +ParsedIn,
     -ParsedOut)'
        - _Description:_ The predicate places the comment 'before' or
          'after' the parsed term. This results in a list with the
          term and the comment or in just returning the term.

        - _Call and exit should be _compatible_ with:_

          `+Place' is an atom.   (`basic_props:atm/1')

          `+Comment' is a compound term.   (`basic_props:struct/1')

          `+ParsedIn' is any term.   (`basic_props:term/1')

          `-ParsedOut' is any term.   (`basic_props:term/1')

 -- PREDICATE: create_parse_structure/1:
     *Usage:* `create_parse_structure(-Parse)'
        - _Description:_ The predicate will construct the parse
          structure with its three fields: the parsing list, the
          environment structure, and the dictionaries.

        - _Call and exit should be _compatible_ with:_

          `-Parse' is a parse structure.   (`internal_types:parse/1')

 -- PREDICATE: create_parse_structure/2:
     *Usage 1:* `create_parse_structure(+ParseIn, -ParseOut)'
        - _Description:_ The predicate will construct a parse
          structure with its three fields: the parsing list, the
          environment structure, and the dictionaries. It will reuse
          the environment and the dictionaries from the input.

        - _Call and exit should be _compatible_ with:_

          `+ParseIn' is a parse structure.
          (`internal_types:parse/1')

          `-ParseOut' is a parse structure.
          (`internal_types:parse/1')

     *Usage 2:* `create_parse_structure(+ParsedList, -ParseOut)'
        - _Description:_ The predicate will construct a parse
          structure with its three fields: the parsing list, the
          environment structure, and the dictionaries. It will use
          the list of parsed items in its structure.

        - _Call and exit should be _compatible_ with:_

          `+ParsedList' is a list of `term's.   (`basic_props:list/2')

          `-ParseOut' is a parse structure.
          (`internal_types:parse/1')

 -- PREDICATE: create_parse_structure/3:
     *Usage:* `create_parse_structure(+ParsedList, +ParseIn,
     -ParseOut)'
        - _Description:_ The predicate will construct a parse
          structure with its three fields: the parsing list, the
          environment structure, and the dictionaries. It will use
          the list of parsed items in its structure and the
          environment and the dictionary from the parse structure
          given.

        - _Call and exit should be _compatible_ with:_

          `+ParsedList' is a list of `term's.   (`basic_props:list/2')

          `+ParseIn' is a parse structure.
          (`internal_types:parse/1')

          `-ParseOut' is a parse structure.
          (`internal_types:parse/1')

 -- PREDICATE: create_environment/4:
     *Usage:* `create_environment(+Parse, +EnvType, +Name,
     -EnvStruct)'
        - _Description:_ The predicate will construct an environment
          structure based on the information in the parse structure.
          Well only the white- space information will be reused. The
          are three types of environments 'PROTO', 'EXTERNPROTO', and
          'DEF'.

        - _Call and exit should be _compatible_ with:_

          `+Parse' is a parse structure.   (`internal_types:parse/1')

          `+EnvType' is an atom.   (`basic_props:atm/1')

          `+Name' is an atom.   (`basic_props:atm/1')

          `-EnvStruct' is an environment structure.
          (`internal_types:environment/1')

 -- PREDICATE: insert_comments_in_beginning/3:
     *Usage:* `insert_comments_in_beginning(+Comment, +ParseIn,
     -ParseOut)'
        - _Description:_ We add the comment in the beginneing of the
          parsed, to get the proper look.

        - _Call and exit should be _compatible_ with:_

          `+Comment' is a compound term.   (`basic_props:struct/1')

          `+ParseIn' is a parse structure.
          (`internal_types:parse/1')

          `-ParseOut' is a parse structure.
          (`internal_types:parse/1')

 -- PREDICATE: get_environment_name/2:
     *Usage:* `get_environment_name(+Environment, -Name)'
        - _Description:_ The predicate will return the enviroment
          name.

        - _Call and exit should be _compatible_ with:_

          `+Environment' is an environment structure.
          (`internal_types:environment/1')

          `-Name' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: get_environment_type/2:
     *Usage:* `get_environment_type(+Environment, -Type)'
        - _Description:_ The predicate will return the enviroment
          type, one of the three: 'PROTO', 'EXTERNPROTO', and 'DEF'.

        - _Call and exit should be _compatible_ with:_

          `+Environment' is an environment structure.
          (`internal_types:environment/1')

          `-Type' is an atom.   (`basic_props:atm/1')

 -- PREDICATE: get_row_number/2:
     *Usage:* `get_row_number(+Parse, -Row)'
        - _Description:_ The predicate will return the row number
          from the parse structure. The row number is not fully
          implemented.

        - _Call and exit should be _compatible_ with:_

          `+Parse' is a parse structure.   (`internal_types:parse/1')

          `-Row' is a number.   (`basic_props:num/1')

 -- PREDICATE: add_environment_whitespace/3:
     *Usage:* `add_environment_whitespace(+EnvIn, +WhiteSpaceList,
     -EnvOut)'
        - _Description:_ The predicate will add the new whitespace
          that is collected in a list of whitespaces to the
          environment.

        - _Call and exit should be _compatible_ with:_

          `+EnvIn' is an environment structure.
          (`internal_types:environment/1')

          `+WhiteSpaceList' is a list of `atm's.
          (`basic_props:list/2')

          `-EnvOut' is an environment structure.
          (`internal_types:environment/1')

 -- PREDICATE: get_indentation/2:
     *Usage 1:* `get_indentation(+Whitespace, -Indentation)'
        - _Description:_ The predicate will return the indentation
          depth from a whitespace structure.

        - _Call and exit should be _compatible_ with:_

          `+Whitespace' is a whitespace structure.
          (`internal_types:whitespace/1')

          `-Indentation' is a number.   (`basic_props:num/1')

     *Usage 2:* `get_indentation(+Parse, -Indentation)'
        - _Description:_ The predicate will return the indentation
          depth from a parse structure.

        - _Call and exit should be _compatible_ with:_

          `+Parse' is a parse structure.   (`internal_types:parse/1')

          `-Indentation' is a number.   (`basic_props:num/1')

 -- PREDICATE: inc_indentation/2:
     *Usage:* `inc_indentation(+ParseIn, -ParseOut)'
        - _Description:_ Will increase the indentation with one step
          to a parse structure.

        - _Call and exit should be _compatible_ with:_

          `+ParseIn' is a parse structure.
          (`internal_types:parse/1')

          `-ParseOut' is a parse structure.
          (`internal_types:parse/1')

 -- PREDICATE: dec_indentation/2:
     *Usage:* `dec_indentation(+ParseIn, -ParseOut)'
        - _Description:_ Will decrease the indentation with one step
          to a parse structure.

        - _Call and exit should be _compatible_ with:_

          `+ParseIn' is a parse structure.
          (`internal_types:parse/1')

          `-ParseOut' is a parse structure.
          (`internal_types:parse/1')

 -- PREDICATE: add_indentation/3:
     No further documentation available for this predicate.

 -- PREDICATE: reduce_indentation/3:
     No further documentation available for this predicate.

 -- PREDICATE: push_whitespace/3:
     *Usage:* `push_whitespace(+ParseWithWhitespace, +ParseIn,
     -ParseOut)'
        - _Description:_ The predicate will add the whitespace values
          from one parse structure to another one, resultin in the
          output, with the values from the second parse structure
          with the whitespace from the first added.

        - _Call and exit should be _compatible_ with:_

          `+ParseWithWhitespace' is a parse structure.
          (`internal_types:parse/1')

          `+ParseIn' is a parse structure.
          (`internal_types:parse/1')

          `-ParseOut' is a parse structure.
          (`internal_types:parse/1')

 -- PREDICATE: push_dictionaries/3:
     *Usage:* `push_dictionaries(+Parse, +Parse, -Parse)'
        - _Description:_ The predicate will set the first parse
          structure's directory to the second parsing structure
          argument. The resulting parsing structure will be returned.

        - _Call and exit should be _compatible_ with:_

          `+Parse' is a parse structure.   (`internal_types:parse/1')

          `+Parse' is a parse structure.   (`internal_types:parse/1')

          `-Parse' is a parse structure.   (`internal_types:parse/1')

 -- PREDICATE: get_parsed/2:
     *Usage 1:* `get_parsed(+ParseStructure, -ListOfParsed)'
        - _Description:_ The predicate will return a list of the
          parsed terms that is inside the parse structure.

        - _Call and exit should be _compatible_ with:_

          `+ParseStructure' is a parse structure.
          (`internal_types:parse/1')

          `-ListOfParsed' is a list of `term's.
          (`basic_props:list/2')

     *Usage 2:* `get_parsed(+ParseStructure, -EnvironmentStructure)'
        - _Description:_ The predicate will return the environment of
          the parse structure.

        - _Call and exit should be _compatible_ with:_

          `+ParseStructure' is a parse structure.
          (`internal_types:parse/1')

          `-EnvironmentStructure' is an environment structure.
          (`internal_types:environment/1')

     *Usage 3:* `get_parsed(+ParseStructure, -Dictionaries)'
        - _Description:_ The predicate will return dictionary used
          within the parse structure.

        - _Call and exit should be _compatible_ with:_

          `+ParseStructure' is a parse structure.
          (`internal_types:parse/1')

          `-Dictionaries' is a dictionary.
          (`internal_types:dictionary/1')

 -- PREDICATE: get_environment/2:
     No further documentation available for this predicate.

 -- PREDICATE: inside_proto/1:
     *Usage:* `inside_proto(+Parse)'
        - _Description:_ The predicate will answer to the question:
          are we parsing inside a PROTO/EXTERNPROTO.

        - _Call and exit should be _compatible_ with:_

          `+Parse' is a parse structure.   (`internal_types:parse/1')

 -- PREDICATE: get_dictionaries/2:
     No further documentation available for this predicate.

 -- PREDICATE: strip_from_list/2:
     *Usage:* `strip_from_list(+ListWithComments, -CleanList)'
        - _Description:_ The predicate will strip the list from
          comments and return a list without any comments.

        - _Call and exit should be _compatible_ with:_

          `+ListWithComments' is a list of `term's.
          (`basic_props:list/2')

          `-CleanList' is a list of `term's.   (`basic_props:list/2')

 -- PREDICATE: strip_from_term/2:
     *Usage:* `strip_from_term(+Term, -Stripped)'
        - _Description:_ The predicate will remove comments from a
          term, it will reduce its arguments if there are comments as
          arguments.

        - _Call and exit should be _compatible_ with:_

          `+Term' is any term.   (`basic_props:term/1')

          `-Stripped' is any term.   (`basic_props:term/1')

 -- PREDICATE: strip_clean/2:
     *Usage:* `strip_clean(+ParsedIn, -ParsedOut)'
        - _Description:_ The predicate will return a striped list or
          a single atom if there was no comments and no more items in
          the list. It will also return a atom if there is comments
          and only one other element.

        - _Call and exit should be _compatible_ with:_

          `+ParsedIn' is any term.   (`basic_props:term/1')

          `-ParsedOut' is any term.   (`basic_props:term/1')

 -- PREDICATE: strip_exposed/2:
     No further documentation available for this predicate.

 -- PREDICATE: strip_restricted/2:
     No further documentation available for this predicate.

 -- PREDICATE: strip_interface/2:
     *Usage:* `strip_interface(+Interface, -StrippedInterface)'
        - _Description:_ The predicate will remove comments from the
          interface that we read for the PROTOtype. This will help us
          when setting the properties.

        - _Call and exit should be _compatible_ with:_

          `+Interface' is a list of `term's.   (`basic_props:list/2')

          `-StrippedInterface' is a list of `term's.
          (`basic_props:list/2')

 -- PREDICATE: set_parsed/3:
     *Usage:* `set_parsed(+ParseIn, +NewParseList, -ParseOut)'
        - _Description:_ The predicate will create a new parse
          structure from the first parse structure with the parse
          list from the second argument.

        - _Call and exit should be _compatible_ with:_

          `+ParseIn' is a parse structure.
          (`internal_types:parse/1')

          `+NewParseList' is a list of `term's.
          (`basic_props:list/2')

          `-ParseOut' is a parse structure.
          (`internal_types:parse/1')

 -- PREDICATE: set_environment/3:
     *Usage:* `set_environment(+Environment, +ParseIn, -ParseOut)'
        - _Description:_ The modificator will return a parse
          structure with the environment given with the other
          properties from the first parse structure.

        - _Call and exit should be _compatible_ with:_

          `+Environment' is an environment structure.
          (`internal_types:environment/1')

          `+ParseIn' is a parse structure.
          (`internal_types:parse/1')

          `-ParseOut' is a parse structure.
          (`internal_types:parse/1')

 -- PREDICATE: insert_parsed/3:
     No further documentation available for this predicate.

 -- PREDICATE: reverse_parsed/2:
     No further documentation available for this predicate.

 -- PREDICATE: stop_parse/2:
     *Usage:* `stop_parse(+TermIn, -TermOut)'
        - _Description:_ The predicate will bind the invalue to the
          outvalue, used to terminate a parsing.

        - _Call and exit should be _compatible_ with:_

          `+TermIn' is any term.   (`basic_props:term/1')

          `-TermOut' is any term.   (`basic_props:term/1')

 -- PREDICATE: look_first_parsed/2:
     *Usage:* `look_first_parsed(+Parse, -First)'
        - _Description:_ Look at the first item in the parse
          structure.

        - _Call and exit should be _compatible_ with:_

          `+Parse' is a parse structure.   (`internal_types:parse/1')

          `-First' is any term.   (`basic_props:term/1')

 -- PREDICATE: get_first_parsed/3:
     *Usage:* `get_first_parsed(+ParseIn, -ParseOut, -First)'
        - _Description:_ Get the first item in the parse structure
          and return the parse structure with the item removed.

        - _Call and exit should be _compatible_ with:_

          `+ParseIn' is a parse structure.
          (`internal_types:parse/1')

          `-ParseOut' is a parse structure.
          (`internal_types:parse/1')

          `-First' is any term.   (`basic_props:term/1')

 -- PREDICATE: remove_code/3:
     No further documentation available for this predicate.

 -- PREDICATE: look_ahead/3:
     *Usage:* `look_ahead(+Name, +Parsed, -Parsed)'
        - _Description:_ This predicate is used normally by the CDG
          and the two last arguments will therefore be the same
          because we don't remove the parsed. The name is the name
          inside a term, the first argument.

        - _Call and exit should be _compatible_ with:_

          `+Name' is an atom.   (`basic_props:atm/1')

          `+Parsed' is a list of `term's.   (`basic_props:list/2')

          `-Parsed' is a list of `term's.   (`basic_props:list/2')

211 possible (library)
**********************

*Author(s):* Go"ran Smedba"ck.

   *Version:* 0.1 (1999/2/19, 6:32:46 MET)

211.1 Usage and interface (`possible')
======================================

   * *Library usage:*

     `:- use_module(library(possible)).'

   * *Exports:*
        - _Predicates:_

          `continue/3'.

   * *Other modules used:*
        - _System library modules:_

          `lists'.

211.2 Documentation on exports (`possible')
===========================================

 -- PREDICATE: continue/3:
     No further documentation available for this predicate.

212 tokeniser (library)
***********************

*Author(s):* Go"ran Smedba"ck.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#178 (2003/12/4, 17:49:33 CET)

212.1 Usage and interface (`tokeniser')
=======================================

   * *Library usage:*

     `:- use_module(library(tokeniser)).'

   * *Exports:*
        - _Predicates:_

          `tokeniser/2', `token_read/3'.

   * *Other modules used:*
        - _System library modules:_

          `iso_byte_char', `lists', `write', `provrml/error'.

212.2 Documentation on exports (`tokeniser')
============================================

 -- PREDICATE: tokeniser/2:
     *Usage:* `tokeniser(+VRML, -Tokens)'
        - _Description:_ This predicate will perform the parsing of
          the VRML code. The result will be tokens that will be the
          source for producing the Prolog terms of the VRML code.
          This is done in the parser module. From these terms
          analysis, changing, and any thing that you want to do with
          VRML code from Prolog programming language. We perform the
          predicate with a catch call to be able to output error
          messages if encountered.

        - _Call and exit should be _compatible_ with:_

          `+VRML' is a list of `atm's.   (`basic_props:list/2')

          `-Tokens' is a list of `term's.   (`basic_props:list/2')

 -- PREDICATE: token_read/3:
     No further documentation available for this predicate.

213 Double linked list
**********************

*Author(s):* David Trallero Mena.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.9#116 (2003/12/1, 22:4:57 CET)

   This library allows the user to work with double linked lists. An
index is used for referencing the current element in the list. Such
index can be modified by _next_ and _prev_ predicated. The value of
the current index can be obtained with _top_ predicate

213.1 Usage and interface (`ddlist')
====================================

   * *Library usage:*

     `:- use_module(library(ddlist)).'

   * *Exports:*
        - _Predicates:_

          `null_list/1', `next/2', `prev/2', `insert/3', `insert_top/3', `insert_after/3', `delete/2', `delete_top/2', `delete_after/2', `top/2', `rewind/2', `forward/2', `length/2', `length_next/2', `length_prev/2'.

        - _Regular Types:_

          `ddlist/1'.

   * *Other modules used:*
        - _System library modules:_

          `lists'.

213.2 Documentation on exports (`ddlist')
=========================================

 -- PREDICATE: null_list/1:
     *Usage:* `null_list(?NullList)'
        - _Description:_ `NullList' is an empty list

        - _The following properties should hold at call time:_

          `A' is a free variable.   (`term_typing:var/1')

        - _The following properties should hold upon exit:_

          `A' is double linked list  (`ddlist:ddlist/1')

 -- PREDICATE: next/2:
     *Usage:* `next(OldList, NewList)'
        - _Description:_ `NewList' is `OldList' but index is set to
          next element of current element of OldList. It satisfies
          next(A,B),prev(B,A)

        - _Call and exit should be _compatible_ with:_

          `OldList' is double linked list  (`ddlist:ddlist/1')

          `NewList' is double linked list  (`ddlist:ddlist/1')

 -- PREDICATE: prev/2:
     *Usage:* `prev(OldList, NewList)'
        - _Description:_ `NewList' is `OldList' but index is set to
          previous element of current element of `OldList'op) of
          `OldList'

        - _Call and exit should be _compatible_ with:_

          `OldList' is double linked list  (`ddlist:ddlist/1')

          `NewList' is double linked list  (`ddlist:ddlist/1')

 -- PREDICATE: insert/3:
     *Usage:* `insert(List, Element, NewList)'
        - _Description:_ `NewList' is like `List' but with `Element'
          inserted _BEFORE_ the current index It satisfies insert( X
          , A , Xp ) , delete( Xp , X ).

        - _Call and exit should be _compatible_ with:_

          `List' is double linked list  (`ddlist:ddlist/1')

          `NewList' is double linked list  (`ddlist:ddlist/1')

 -- PREDICATE: insert_top/3:
     *Usage:* `insert_top(List, Element, NewList)'
        - _Description:_ Put `Element' as new top of `NewList' and
          push the rest of elements after it. It satisfies top(
          NewList , element )

        - _Call and exit should be _compatible_ with:_

          `List' is double linked list  (`ddlist:ddlist/1')

          `NewList' is double linked list  (`ddlist:ddlist/1')

 -- PREDICATE: insert_after/3:
     *Usage:* `insert_after(List, Element, NewList)'
        - _Description:_ `NewList' is like `List' but with `Element'
          inserted _AFTER_ the current index It satisfies
          insert_after( X , A , Xp ) , delete_after( Xp , X ).

        - _Call and exit should be _compatible_ with:_

          `List' is double linked list  (`ddlist:ddlist/1')

          `NewList' is double linked list  (`ddlist:ddlist/1')

 -- PREDICATE: delete/2:
     *Usage:* `delete(OldList, NewList)'
        - _Description:_ `NewList' does not have the previous element
          (top(prev)) of `OldList'

        - _Call and exit should be _compatible_ with:_

          `OldList' is double linked list  (`ddlist:ddlist/1')

          `NewList' is double linked list  (`ddlist:ddlist/1')

 -- PREDICATE: delete_top/2:
     *Usage:* `delete_top(OldList, NewList)'
        - _Description:_ `NewList' does not have the current element
          (top) of `OldList'

        - _Call and exit should be _compatible_ with:_

          `OldList' is double linked list  (`ddlist:ddlist/1')

          `NewList' is double linked list  (`ddlist:ddlist/1')

 -- PREDICATE: delete_after/2:
     *Usage:* `delete_after(OldList, NewList)'
        - _Description:_ `NewList' does not have next element to
          current element (top) of `OldList'

        - _Call and exit should be _compatible_ with:_

          `OldList' is double linked list  (`ddlist:ddlist/1')

          `NewList' is double linked list  (`ddlist:ddlist/1')

 -- PREDICATE: top/2:
     *Usage:* `top(List, Element)'
        - _Description:_ `Element' is the element pointed by index

        - _Call and exit should be _compatible_ with:_

          `List' is double linked list  (`ddlist:ddlist/1')

 -- PREDICATE: rewind/2:
     *Usage:* `rewind(OldList, NewList)'
        - _Description:_ `NewList' is the `OldList' but index is set
          to 0

        - _Call and exit should be _compatible_ with:_

          `OldList' is double linked list  (`ddlist:ddlist/1')

          `NewList' is double linked list  (`ddlist:ddlist/1')

 -- PREDICATE: forward/2:
     *Usage:* `forward(OldList, NewList)'
        - _Description:_ `NewList' is the `OldList' but index is set
          to lentgh of `NewList'

        - _Call and exit should be _compatible_ with:_

          `OldList' is double linked list  (`ddlist:ddlist/1')

          `NewList' is double linked list  (`ddlist:ddlist/1')

 -- PREDICATE: length/2:
     *Usage:* `length(List, Len)'
        - _Description:_ `Len' is the length of the `List'

        - _Call and exit should be _compatible_ with:_

          `List' is double linked list  (`ddlist:ddlist/1')

 -- PREDICATE: length_next/2:
     *Usage:* `length_next(List, Len)'
        - _Description:_ `Len' is the length from the current index
          till the end

        - _Call and exit should be _compatible_ with:_

          `List' is double linked list  (`ddlist:ddlist/1')

 -- PREDICATE: length_prev/2:
     *Usage:* `length_prev(List, Len)'
        - _Description:_ `Len' is the length from the beginning till
          the current index

        - _Call and exit should be _compatible_ with:_

          `List' is double linked list  (`ddlist:ddlist/1')

 -- REGTYPE: ddlist/1:
     *Usage:* `ddlist(X)'
        - _Description:_ `X' is double linked list

213.3 Other information (`ddlist')
==================================

Two simple examples of the use of the ddlist library package follow.

213.3.1 Using insert_after
--------------------------

     :- module( ddl1 , _ , [] ).

     :- use_module( library(ddlist) ).

     main(A,B):-
             % L = []
             null_list( L ),
             % L = [1]
             insert_after( L  , 1 , L1 ),
             % L = [1,2]
             insert_after( L1 , 2 , L2 ),
             % L = [1,3,2]
             insert_after( L2 , 3 , L3 ),
             % L = [1,3,2] => A = [1]
             top( L3 , A ),
             % L = [3,2]
             next( L3 , PL3 ),
             % L = [3,2] => A = [3]
             top( PL3 , B ).

213.3.2 More Complex example
----------------------------

     :- module( ddl2 , _ , [] ).

     :- use_module( library(ddlist) ).

     main(A,B):-
             % L = []
             null_list( L ),
             % L = [1]
             insert_after( L  , 1 , L1 ),
             % L = [1,2]
             insert_after( L1 , 2 , L2 ),
             % L = [1,2]
             insert( L2 , 3 , L3 ),
             % L = [3,1,2]
             prev( L3 , PL3 ),
             % L = [],
             forward( PL3 , FOR ),
             % L = [2]
             prev( FOR , FOR1 ),
             % L = [2] => A = 2
             top( FOR1 , A ),
             % L = [1,2]
             prev( FOR1 , FOR2 ),
             % L = [2]
             delete_after( FOR2 , FOR3 ),
             % L = [3,2]
             prev( FOR3, FOR4 ),
             % L = [3,2] => B = 3
             top( FOR4 , B ).

214 Measuring features from predicates (time cost or memory used...)
********************************************************************

*Author(s):* David Trallero Mena.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.0#2 (2003/12/3, 0:10:32 CET)

   This library has been done for measuring or compare execution
features (currently only time) of predicates. This module relies on
gnuplot, an auxiliary module which use the tool `gnuplot', for
representing results graphically

214.1 Usage and interface (`time_analyzer')
===========================================

   * *Library usage:*

     `:- use_module(library(time_analyzer)).'

   * *Exports:*
        - _Predicates:_

          `performance/3', `benchmark/6', `compare_benchmark/7', `benchmark2/6', `compare_benchmark2/7', `sub_times/3', `div_times/2', `cost/3'.

   * *Other modules used:*
        - _System library modules:_

          `gnuplot/gnuplot', `prolog_sys', `lists', `write', `system', `hiordlib'.

214.2 Documentation on exports (`time_analyzer')
================================================

 -- PREDICATE: performance/3:
     _Meta-predicate_ with arguments: `performance(goal,?,?)'.

     *Usage:* `performance(P, M, Times)'
        - _Description:_ performance accepts a goal, `P', as a first
          argument. The aim of this predicate is to call `P' several
          times and meassure some feature (in this version, only
          time, that is because no extra parameter has been added).
          `M' defines how many times `P' should be called. Usually,
          calling the predicate in some succesion (10,100,1000) and
          dividing by the number of times it is executed we can
          obtain the "execution time" of the predicate (if we are
          measuring time).

          The result of executions are returned in the list `Times'

          The diferent modes are:
             * graph( Start , End , Increment ). It defines
               arithmetic succesion starting in Start and ending in
               End, by increment of Increment. So `P' is called Start
               times on the first time, Start+Increment on the
               second, etc.

             * graph The same as graph/3 but with default options

             * graph_exp( Start , End , Exp ). It defines geometric
               succesion. Start is multiplied by Exp till it gets
               End. So `P' is called Start times on the first time,
               Start*Exp on the second, etc.

             * graph_exp The same as graph_exp/3 but with default
               options

        - _The following properties should hold at call time:_

          `P' is a term which represents a goal, i.e., an atom or a
          structure.   (`basic_props:callable/1')

          `M' is any term.   (`basic_props:term/1')

          `Times' is a free variable.   (`term_typing:var/1')

        - _The following properties should hold upon exit:_

          `P' is a term which represents a goal, i.e., an atom or a
          structure.   (`basic_props:callable/1')

          `M' is any term.   (`basic_props:term/1')

          `Times' is a list of `num's.   (`basic_props:list/2')

 -- PREDICATE: benchmark/6:
     *Usage:* `benchmark(P, BenchList, NumTimes, Method, Reserved,
     OutList)'
        - _Description:_ The predicate `P', which accepts ONE
          argument, is called with the first member of each pair of
          the `BenchList' list `NumTimes'. The entry list have pairs
          because the second member of the pair express the meaning
          of the first one in the X-Axis. For example, if we are
          doing a benchmark of qsort function, the first member will
          be a list for being ordered and the second one will be the
          length of the unordered list. The output is a list of (X,Y)
          points where Y means the time needed for its entry of
          "cost" X. `OutList' can be used as TimeList in predicate
          generate_plot. `Reserved' is reserved for future
          implementations (it will take the value of runtime,
          memory_used...)

        - _The following properties should hold at call time:_

          `P' is a term which represents a goal, i.e., an atom or a
          structure.   (`basic_props:callable/1')

          `BenchList' is a list of `pair's.   (`basic_props:list/2')

          `NumTimes' is an integer.   (`basic_props:int/1')

          `time_analyzer:average_mode(Method)'
          (`time_analyzer:average_mode/1')

          `Reserved' is any term.   (`basic_props:term/1')

          `OutList' is a free variable.   (`term_typing:var/1')

        - _The following properties should hold upon exit:_

          `P' is a term which represents a goal, i.e., an atom or a
          structure.   (`basic_props:callable/1')

          `BenchList' is a list of `pair's.   (`basic_props:list/2')

          `NumTimes' is an integer.   (`basic_props:int/1')

          `time_analyzer:average_mode(Method)'
          (`time_analyzer:average_mode/1')

          `Reserved' is any term.   (`basic_props:term/1')

          `OutList' is a list of `pair's.   (`basic_props:list/2')

 -- PREDICATE: compare_benchmark/7:
     *Usage:* `compare_benchmark(ListPred, BenchList, Method,
     NumTimes, BaseName, Reserved, GeneralOptions)'
        - _Description:_ It is the generalization of execute predicate `benchmark/6'
          with several predicates.  `benchmark/6' predicate is called
          with each predicate in `ListPred', and `BaseName' is used
          for the temporaries basename file. `GeneralOptions' are
          aplied to the plot

        - _The following properties should hold at call time:_

          `ListPred' is a list of `pred's.   (`basic_props:list/2')

          `BenchList' is a list.   (`basic_props:list/1')

          `time_analyzer:average_mode(Method)'
          (`time_analyzer:average_mode/1')

          `NumTimes' is an integer.   (`basic_props:int/1')

          `BaseName' is currently instantiated to an atom.
          (`term_typing:atom/1')

          `Reserved' is any term.   (`basic_props:term/1')

          `GeneralOptions' is a free variable.   (`term_typing:var/1')

        - _The following properties should hold upon exit:_

          `ListPred' is a list of `pred's.   (`basic_props:list/2')

          `BenchList' is a list.   (`basic_props:list/1')

          `time_analyzer:average_mode(Method)'
          (`time_analyzer:average_mode/1')

          `NumTimes' is an integer.   (`basic_props:int/1')

          `BaseName' is currently instantiated to an atom.
          (`term_typing:atom/1')

          `Reserved' is any term.   (`basic_props:term/1')

          `GeneralOptions' is a list.   (`basic_props:list/1')

 -- PREDICATE: benchmark2/6:
     *Usage:* `benchmark2(P, BenchList, Method, NumTimes, What,
     OutList)'
        - _Description:_ The predicate `P', which accepts TWO
          arguments, is called `NumTimes' with the first member of
          each pair of the `BenchList' list and a free variable as
          the second. The time of execution (in the future, the
          desired featured for be measured) is expected to be the
          second argument, that is because it is a variable. The
          entry list, `BenchList' have pairs because the second
          member of the pair express the cost of the first (in
          X-Axis). For example, if we are doing a benchmark of qsort
          function, the first member will be a list for being ordered
          and the second one will represent the lenght of the
          unordered list. The output is a list of (X,Y) points where
          Y express the time needed for they entry of "cost" X.
          `OutList' can be used as TimeList in predicate
          generate_plot. `What' is reserved for future use

        - _The following properties should hold at call time:_

          `P' is a term which represents a goal, i.e., an atom or a
          structure.   (`basic_props:callable/1')

          `BenchList' is a list of `pair's.   (`basic_props:list/2')

          `time_analyzer:average_mode(Method)'
          (`time_analyzer:average_mode/1')

          `NumTimes' is an integer.   (`basic_props:int/1')

          `What' is currently instantiated to an atom.
          (`term_typing:atom/1')

          `OutList' is a free variable.   (`term_typing:var/1')

        - _The following properties should hold upon exit:_

          `P' is a term which represents a goal, i.e., an atom or a
          structure.   (`basic_props:callable/1')

          `BenchList' is a list of `pair's.   (`basic_props:list/2')

          `time_analyzer:average_mode(Method)'
          (`time_analyzer:average_mode/1')

          `NumTimes' is an integer.   (`basic_props:int/1')

          `What' is currently instantiated to an atom.
          (`term_typing:atom/1')

          `OutList' is a list of `pair's.   (`basic_props:list/2')

 -- PREDICATE: compare_benchmark2/7:
     *Usage:* `compare_benchmark2(ListPred, BenchList, Method,
     NumTimes, BaseName, Reserved, GeneralOptions)'
        - _Description:_ It is the generalization of execute predicate `benchmark2/6'
          with several predicates.  `benchmark2/6' is called with
          each predicate in `ListPred' and `BaseName' is used for the
          temporaries basename file. `GeneralOptions' are applied to
          the plot ('default' can be used for default General options)

        - _The following properties should hold at call time:_

          `ListPred' is a list of `pred's.   (`basic_props:list/2')

          `BenchList' is a list.   (`basic_props:list/1')

          `time_analyzer:average_mode(Method)'
          (`time_analyzer:average_mode/1')

          `NumTimes' is an integer.   (`basic_props:int/1')

          `BaseName' is currently instantiated to an atom.
          (`term_typing:atom/1')

          `Reserved' is currently instantiated to an atom.
          (`term_typing:atom/1')

          `GeneralOptions' is a list.   (`basic_props:list/1')

        - _The following properties should hold upon exit:_

          `ListPred' is a list of `pred's.   (`basic_props:list/2')

          `BenchList' is a list.   (`basic_props:list/1')

          `time_analyzer:average_mode(Method)'
          (`time_analyzer:average_mode/1')

          `NumTimes' is an integer.   (`basic_props:int/1')

          `BaseName' is currently instantiated to an atom.
          (`term_typing:atom/1')

          `Reserved' is currently instantiated to an atom.
          (`term_typing:atom/1')

          `GeneralOptions' is a list.   (`basic_props:list/1')

 -- PREDICATE: sub_times/3:
     *Usage:* `sub_times(A, B, C)'
        - _Description:_ C is the result of doing A - B, where A, B,
          C are a list of pairs as (Time,_)

        - _Call and exit should be _compatible_ with:_

          `A' is a list of `pair's.   (`basic_props:list/2')

          `B' is a list of `pair's.   (`basic_props:list/2')

          `C' is a list of `pair's.   (`basic_props:list/2')

 -- PREDICATE: div_times/2:
     *Usage:* `div_times(A, B)'
        - _Description:_ `A' is a list of pairs (P1,P2). `B' is a
          list of pairs with the form (P1,P2/P1) for each (P1,P2)
          that belongs to `A'

        - _Call and exit should be _compatible_ with:_

          `A' is a list of `pair's.   (`basic_props:list/2')

          `B' is a list of `pair's.   (`basic_props:list/2')

 -- PREDICATE: cost/3:
     _Meta-predicate_ with arguments: `cost(goal,?,?)'.

     *Usage:* `cost(A, T, What)'
        - _Description:_ This pred is thought for measuring constant
          complexity predicates. `T' is the expected measured
          feature. `What' is reserved for future implementations,
          just put 'runtime'

        - _Call and exit should be _compatible_ with:_

          `A' is a term which represents a goal, i.e., an atom or a
          structure.   (`basic_props:callable/1')

          `T' is an integer.   (`basic_props:int/1')

          `What' is any term.   (`basic_props:term/1')

 -- (: UNDOC_REEXPORT) generate_plot/3:
     Imported from `gnuplot' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) generate_plot/2:
     Imported from `gnuplot' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) set_general_options/1:
     Imported from `gnuplot' (see the corresponding documentation for
     details).

 -- (: UNDOC_REEXPORT) get_general_options/1:
     Imported from `gnuplot' (see the corresponding documentation for
     details).

215 Printing graph using gnuplot as auxiliary tool.
***************************************************

*Author(s):* David Trallero Mena.

   This library uses `gnuplot' for printing graphs.

   User-friendly predicates to generate data plots are provided, as
well as predicates to set the general options which govern the
generation of such plots. If no options is specified, global ones are
used for data plots generation.

   Several files can be generated as temporary files. A BaseName is
required for generating the temporaries files. Data files name will
be created from BaseName + number + .dat. The BaseName + ".plot" will
be the name used for `gnuplot' tool.

   A list of pairs of list of pairs of the from (X,Y) and Local
Option value is provided to the main predicate as data. In other
words DataList = [(CurveDataList,LocalOptions),
(CurveDataList1,LocalOptions1) ...]. Additionaly (function( String )
, LocalOptions) can be used for adding a curve to the plot (imagine
you want to compare your result with 'x=y').

   LocalOptions of the DataList are options that are applied to the
curve, as for example, if we print the curve with lines, or the title
in the legend, etc. GlobalOptions are referred to the plot options,
like title in x or y axis, etc.

215.1 Usage and interface (`gnuplot')
=====================================

   * *Library usage:*

     `:- use_module(library(gnuplot)).'

   * *Exports:*
        - _Predicates:_

          `get_general_options/1', `set_general_options/1', `generate_plot/2', `generate_plot/3'.

   * *Other modules used:*
        - _System library modules:_

          `lists', `write', `system'.

215.2 Documentation on exports (`gnuplot')
==========================================

 -- PREDICATE: get_general_options/1:
     *Usage:* `get_general_options(X)'
        - _Description:_ Get the general options of the graphic that
          will be plotted

        - _The following properties should hold at call time:_

          `X' is a free variable.   (`term_typing:var/1')

        - _The following properties should hold upon exit:_

          `X' is a list.   (`basic_props:list/1')

 -- PREDICATE: set_general_options/1:
     *Usage:* `set_general_options(X)'
        - _Description:_ Get the general options of the graphic that
          will be plotted. Possible options are:
             * format(A) Specify the format of points

             * nokey Legend is no represented

             * nogrid No grid

             * grid An smooth grid is shown

             * label(L , (X,Y)) Put Label L at point (X,Y)

             * xlabel(A) Label of X-Axis

             * ylabel(A) Label of Y-Axis

             * xrange(A,B) Define the X range representation

             * yrange(A,B) Define the Y range representation

             * title(A) Title of the plot

             * key(A) define the key (for example [left,box], left is
               the position, box indicates that a box should be
               around)

             * term_post(A) define the postscript terminal. A is a
               list of atoms.

             * size(A,B) specify the size of the plot (A,B float
               numbers)

             * autoscale autoscale the size of the plot

             * autoscale(A) autoscale the argument (for example:
               autoscale(x))

        - _Call and exit should be _compatible_ with:_

          `X' is a list.   (`basic_props:list/1')

 -- PREDICATE: generate_plot/2:
     *Usage:* `generate_plot(BaseName, DataList)'
        - _Description:_ This predicates generate a '`BaseName' +
          .ps' postscript file using each element of `DataList' as
          pair of list of pairs and local options, i.e., (
          list((X,Y)), LocalOptions), in which X is the position in
          X-Axis and Y is the position in Y-Axis. Nevertheless, each
          element of `DataList' can be a list of pairs instead of a
          pair for commodity. `gnuplot' is used as auxiliary tool.
          Temporary files '`BaseName' + N.dat' are generated for for
          every list of pairs, and '`BaseName' + .plot' is de file
          used by gnuplot. The local options can be:
             * with(Option) Tells how the curve will be represented.
               Option can b line, dots, boxes, impulses, linespoints.
               This option HAVE TO BE the last one

             * title(T) Put the name of the curve in the legend to T

        - _The following properties should hold at call time:_

          `BaseName' is currently instantiated to an atom.
          (`term_typing:atom/1')

          `DataList' is a list of `pair's.   (`basic_props:list/2')

        - _The following properties should hold upon exit:_

          `BaseName' is currently instantiated to an atom.
          (`term_typing:atom/1')

          `DataList' is a list of `pair's.   (`basic_props:list/2')

 -- PREDICATE: generate_plot/3:
     *Usage:* `generate_plot(BaseName, DataList, GeneralOptions)'
        - _Description:_ It is the same as generate_plot/2 but
          `GeneralOptions' are used as the general options of the
          plot. Look at predicate set_general_options for detailed
          description of possible options

        - _The following properties should hold at call time:_

          `BaseName' is currently instantiated to an atom.
          (`term_typing:atom/1')

          `DataList' is a list of `pair's.   (`basic_props:list/2')

          `GeneralOptions' is a list.   (`basic_props:list/1')

        - _The following properties should hold upon exit:_

          `BaseName' is currently instantiated to an atom.
          (`term_typing:atom/1')

          `DataList' is a list of `pair's.   (`basic_props:list/2')

          `GeneralOptions' is a list.   (`basic_props:list/1')

216 Automatic modules caller tester
***********************************

*Author(s):* David Trallero Mena.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.0#6 (2004/2/24, 17:12:13 CET)

   This module is intended to agilizy the work of calling several
modules as prove cases of some program. Usually when you are
developing a program you have several auto-test program cases that
you would like to execute whenever you do some modification in your
program/system. The predicate `mod_tester/2' was created with the
propouse of execute this test an report to you which of them were
correctly executed and which one were not.

216.1 Usage and interface (`modtester')
=======================================

   * *Library usage:*

     `:- use_module(library(modtester)).'

   * *Exports:*
        - _Predicates:_

          `tester_func/1', `modules_tester/2', `pred_tester/2'.

   * *Other modules used:*
        - _System library modules:_

          `tester/tester', `lists', `write', `filenames', `compiler/compiler', `terms_check', `conc_aggregates', `system'.

216.2 Documentation on exports (`modtester')
============================================

 -- PREDICATE: tester_func/1:
     No further documentation available for this predicate.

 -- PREDICATE: modules_tester/2:
     *Usage 1:* `modules_tester(BaseName, ModulesList)'
        - _Description:_ modules_tester accepts an atom as basename
          of the two generated files. For each module in
          `ModulesList' an output and report is saved in
          'basename_test_output.log' and 'basename_test_summary.log'
          respectevely

        - _The following properties should hold at call time:_

          `BaseName' is currently instantiated to an atom.
          (`term_typing:atom/1')

          `ModulesList' is a list.   (`basic_props:list/1')

     *Usage 2:* `modules_tester(BaseName, PredList)'
        - _Description:_ pred_tester accepts an atom as basename of
          the two generated files. For each element with the pattern
          (FindPatter, precidate, [results]), module in `PredList' an
          output and report is saved in 'basename_test_output.log'
          and 'basename_test_summary.log' respectevely. For example,
          you can call this predicate as: pred_tester( test ,
          [(X,mypred(X),[1,2,3]),( (X,Y),mypred2( X, aa , Y ),
          [(1,2),(2,3)])] ).

        - _The following properties should hold at call time:_

          `BaseName' is currently instantiated to an atom.
          (`term_typing:atom/1')

          `PredList' is a list.   (`basic_props:list/1')

 -- PREDICATE: pred_tester/2:
     No further documentation available for this predicate.

217 Automatic tester
********************

*Author(s):* David Trallero Mena.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.0 (2003/10/16, 11:52:43 CEST)

   This module have been created to automatizate the test that a
predicate should pass hopefully. With that intention we have to
provide a set of test and its correct answers. The predicate `run_tester/10'
will execute every test and compare it with its answer, generating
two traces, one with detailed information, and another with the
summary of executions of the tests.

217.1 Usage and interface (`tester')
====================================

   * *Library usage:*

     `:- use_module(library(tester)).'

   * *Exports:*
        - _Predicates:_

          `run_tester/10'.

   * *Other modules used:*
        - _System library modules:_

          `lists', `write', `io_alias_redirection'.

217.2 Documentation on exports (`tester')
=========================================

 -- PREDICATE: run_tester/10:
     _Meta-predicate_ with arguments:
     `run_tester(?,?,pred(0),pred(1),?,pred(1),?,pred(0),?,?)'.

     *Usage:* `run_tester(LogFile, ResultFile, Begin, Test, TestList,
     Check, CheckList, End, GoodExamples, Slider)'
        - _Description:_ run_tester is a predicate for automatizate
          testers. It get 2 file names as entry (`LogFile' and
          `ResultFile') for saving the trace and the short result
          scheme respectevely. `Being' and `End' are called at the
          beginning and at the end of the test. `Test' is called
          which each element of `TestList' and after, `Check' is
          called with the corresponding element in `CheckList' for
          checking the results of `Test' predicate. `GoodExample' is
          ground(int) at the exit and tells the number of examples
          that passed the test correctly. `Slider' can take the
          values slider(no) or slider(Title) and slider will be shown
          everytime a new test is called

        - _The following properties should hold at call time:_

          `LogFile' is a string (a list of character codes).
          (`basic_props:string/1')

          `ResultFile' is a string (a list of character codes).
          (`basic_props:string/1')

          `Begin' is a term which represents a goal, i.e., an atom or
          a structure.   (`basic_props:callable/1')

          `Test' is a term which represents a goal, i.e., an atom or
          a structure.   (`basic_props:callable/1')

          `TestList' is a list.   (`basic_props:list/1')

          `Check' is a term which represents a goal, i.e., an atom or
          a structure.   (`basic_props:callable/1')

          `CheckList' is a list.   (`basic_props:list/1')

          `End' is a term which represents a goal, i.e., an atom or a
          structure.   (`basic_props:callable/1')

          `GoodExamples' is a free variable.   (`term_typing:var/1')

          `Slider' is any term.   (`basic_props:term/1')

217.3 Other information (`tester')
==================================

Two simple examples of the use of the run_tester are provided.

217.3.1 Understanding run_test predicate
----------------------------------------

     :- module( tester_test2 , _ , _ ).

     :- use_module( '../tester' ).
     %:- use_module( library(tester) ).
     :- use_module( library(lists) ).
     :- use_module( library(write) ).

     init_func :-
             write( 'Starting the test\n' ).

     tester_func( (X,X,_) ) :-
             write( 'The argument is correct ' ),
             write( X ) , nl.

     checker_func( (_,X,X) ) :-
             write( 'check is fine\n\n' ).

     end_func :-
             write( 'Test ended\n' ).

     main :-
             L = [ (1,1,1),   % CORRECT
                   (2,2,1),   % Test CORRECT , CHECK FALSE
                   (1,2,2)    % Test FALSE
                 ],

              run_tester(
                           'test.log',
                           'result.log',
                           init_func ,
                           tester_func ,
                           L,
                           checker_func,
                           L,
                           end_func,
                           Res,
                           slider( 'Tester2: ' )
                       ),

              length( L , LL ),
              Op is (Res / LL) * 100,
              message( note , [ 'Analysis result: ' , Op , '%' ] ).

217.3.2 More complex example
----------------------------

In this example we just want to test if the output of Ciaopp is
readable by CIAO.

   Tester function succeds if it is able to write the output file.

   Checker function succeds if it is able to load the written file.

     :- module( tester_test1 , _ , [] ).

     %:- use_module( library(tester) , [run_tester/10] ).
     :- use_module( '../tester' , [run_tester/10] ).

     :- use_module( library(ciaopp) ).
     :- use_module( library(compiler) ).

     :- use_module(library(filenames)).

     :- use_module( library( write ) ).

     :- use_module( library( lists ) ).

     init_func.

     test_files( '/home/dtm/Ciaopp/Benchmarks/ciaopp/modes/' ).

     tester_func( FileArg ) :-
             test_files( Path ),
             atom_concat( Path , FileArg , File0 ),

             message( note ,
              [ '+++++++++++++++++++++++++++++++++++++++++++++++\n' ] ),
             (unload( File0 )->true;true),
             module( File0 ),

             atom_concat( TFile , '.pl', File0 ),
             atom_concat( TFile , '_test.pl' , TestFile ),

             output( TestFile ).

     get_module( Path , Module ) :-
             no_path_file_name( Path , File ),
             (atom_concat( Module , '.pl' , File )
             -> true ; Module = File ).

     checker_func( FileArg ) :-
             get_module( FileArg , Module ),
             (unload( Module )->true;true),

             atom_concat(RawFile, '.pl'     , FileArg ),
             atom_concat(RawFile, '_test.pl' , OptFile ),

             test_files( Path ),
             atom_concat( Path , OptFile, OptFilePath ),

             message( note , [ 'Cargando ' , OptFilePath ] ),
             use_module( OptFilePath ).

     end_func.

     main :-
             L = [
                     'aiakl.pl',
                     'query.pl',
                     'mmatrix.pl',
                     'ann.pl',
                     'bid.pl',
                     'rdtok.pl',
                     'myread.pl',
                     'boyer.pl',
                     'read.pl',
                     'occur.pl',
                     'serialize.pl',
                     'browse.pl',
                     'peephole.pl',
                     'tak.pl',
                     'deriv.pl',
                     'progeom.pl',
                     'warplan.pl',
                     'fib.pl',
                     'qplan.pl',
                     'witt.pl',
                     'grammar.pl',
                     'zebra.pl',
                     'qsortapp.pl',
                     'hanoiapp.pl'
                   ],

             run_tester(
                           'test.log',
                           'result.log',
                           init_func ,
                           tester_func ,
                           L,
                           checker_func,
                           L,
                           end_func,
                           Res,
                           slider( 'Tester1: ' )
                       ),
              length( L , LL ),
              Op is (Res / LL) * 100,
              message( note , [ 'Analysis result: ' , Op , '%' ] ).

PART XII - Appendices
*********************

*Author(s):* The CLIP Group.

   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.

218 Installing Ciao from the source distribution
************************************************

*Author(s):* Manuel Carro, Daniel Cabeza, Manuel Hermenegildo.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.10#2 (2004/8/2, 19:25:49 CEST)

   This describes the installation procedure for the Ciao Prolog
system, including libraries and manuals, from a _source_
distribution. This applies primarily to Unix-type systems (Linux, Mac
OS X, Solaris, SunOS, etc.). However, the sources can also be
compiled if so desired on Windows systems - see Installation and compilation under Windows
for details.

   If you find any problems during installation, please refer to
Troubleshooting (nasty messages and nifty workarounds).  See
also Downloading new versions and Reporting bugs.

218.1 Un*x installation summary
===============================

*Note:* it is recommended that you read the full installation
instructions (specially if the installation will be shared by
different architectures). However, in many cases it suffices to
follow this summary:

  1. Uncompress and unpackage (using `gunzip' and `tar -xpf') the
     distribution. This will put everything in a new directory whose
     name reflects the Ciao version.

  2. Enter the newly created directory (`SRC'). Edit `SETTINGS' and
     check/set the variables `SRC', `CIAOROOT' (this defines where
     the installation will hang from) and `DOCROOT' (where the
     documentation will go, preferably a directory _accessible via_ WWW).
     `CIAOROOT' is used to give values to `BINROOT', `LIBROOT', and
     `INCLUDEROOT'. You can give different values to these if you
     want.

  3. Type `gmake install'. This will build executables, compile
     libraries, and install everything in a directory `LIBROOT/ciao'
     and in `BINROOT'.

     Note that `gmake' refers to the GNU implementation of the make
     Un*x command, which is available in many systems (including all
     Linux systems and Mac OS X) simply as `make'. I.e., you can try
     simply typing `make install' if `gmake install' does not work.
     If typing `make' stops right away with error messages it is
     probably an older version and you need to install `gmake'.

  4. Make the following modifications in your startup scripts. This
     will make the documentation accessible, set the correct mode
     when opening Ciao source files in `emacs', etc. Note that
     `<LIBROOT>' must be replaced with the appropriate value:

        * For users a _csh-compatible shell_ ( `csh', `tcsh', ...),
          add to `~/.cshrc':

                       if ( -e <LIBROOT>/ciao/DOTcshrc ) then
                          source <LIBROOT>/ciao/DOTcshrc
                       endif

          `Mac OS X' users should add (or modify) the `path' file in
          the directory `~/Library/init/tcsh', adding the lines shown
          above. *Note:* while this is recognized by the terminal
          shell, and therefore by the text-mode Emacs which comes
          with Mac OS X, the Aqua native Emacs 21 does not recognize
          that initialization. It is thus necessary, at this moment,
          to set manually the Ciao shell (ciaosh) and Ciao library
          location by hand. This can be done from the Ciao menu
          within Emacs after a Ciao Prolog file has been loaded. We
          suppose that the reason is that Mac OS X does not actually
          consult the per-user initialization files on startup. It
          should also be possible to put the right initializations in
          the .emacs file using the `setenv' function of Emacs-lisp,
          as in

               (setenv "CIAOLIB" "<LIBROOT>/ciao")

          The same can be done for the rest of the variables
          initialized in `<LIBROOT>/ciao/DOTcshrc'

        * For users of an _sh-compatible shell_ ( `sh', `bash', ...),
          add to `~/.profile':

                       if [ -f <LIBROOT>/ciao/DOTprofile ]; then
                          . <LIBROOT>/ciao/DOTprofile
                       fi

          This will set up things so that the Ciao executables are
          found and you can access the Ciao system manuals using the `info'
          command. Note that, depending on your shell, _you may have
          to log out and back in_ for the changes to take effect.

        * Also, if you use `emacs' (highly recommended) add this line
          to your `~/.emacs' file:

                       (load-file "<LIBROOT>/ciao/DOTemacs.el")

     If you are installing Ciao globally in a multi-user machine,
     make sure that you instruct all users to do the same. If you are
     the system administrator, the previous steps can be done once
     and for all, and globally for all users by including the lines
     above in the central startup scripts (e.g., in Linux `/etc/bashrc', `/etc/csh.login', `/etc/csh.cshrc', `/etc/skel', `/usr/share/emacs/.../lisp/site-init.pl',
     etc.).

  5. Finally, if the (freely available) `emacs' editor/environment is
     not installed in your system, we _highly recommend_ that you
     also install it at this point (see Un*x full installation instructions
     for instructions). While it is easy to use Ciao
     with any editor of your choice, the Ciao distribution includes a
     very powerful _application development environment_ which is
     based on `emacs' and which enables, e.g., source-level
     debugging, syntax coloring, context-sensitive on-line help, etc.

  6. You may want now want to check your installation (see
     Checking for correct installation on Un*x) and read the
     documentation, which is stored in `DOCROOT' (copied from
     `SRC/doc/reference') and can be easily accessed as explained in
     that same section. There are special "getting started" sections
     at the beginning of the manual.

  7. If you have any problems you may want to check the rest of the
     instructions. The system can be _uninstalled_ by typing `gmake
     uninstall'.

218.2 Un*x full installation instructions
=========================================

  1. *Uncompress and unpackage:* (using `gunzip' and `tar -xpf') the
     distribution in a suitable directory. This will create a new
     directory called `ciao-X.Y', where `X.Y' is the version number
     of the distribution. The `-p' option in the `tar' command
     ensures that the relative dates of the files in the package are
     preserved, which is needed for correct operation of the
     Makefiles.

  2. *Select installation options:* Edit the file `SETTINGS' and set
     the following variables:

        * `SRC': directory where the sources are stored.

        * `BINROOT': directory where the Ciao executables will go.
          For example, if `BINROOT=/usr/local/bin', then the Ciao compiler
          ( `ciaoc') will be stored at `/usr/local/bin/ciaoc'.
          Actually, it will be a link to `ciaoc-'_VersionNumber_.
          This applies also to other executables below and is done so
          that several versions of Ciao can coexist on the same
          machine. Note that the _version installed latest_ will be
          the one started by default when typing `ciao', `ciaoc', etc.

        * `LIBROOT': directory where the run-time libraries will be
          installed.  The Ciao installation procedure will create a
          new subdirectory `ciao' below `LIBROOT' and a subdirectory
          below this one for each Ciao version installed. For
          example, if `LIBROOT=/usr/local/lib' and you have Ciao
          version `x.y', then the libraries will be installed under
          `/usr/local/lib/ciao/ciao-x.y'. This allows you to install site-specific
          programs under `/usr/local/lib/ciao' and they will not be
          overwritten if a new version of Ciao is installed. It also
          again allows having several Ciao versions installed
          simultaneously.

        * `DOCROOT': directory where the manuals will be installed.
          It is often convenient if this directory is accessible via WWW
          (`DOCROOT=/home/httpd/html/ciao', or something like that).

     For network-based installations, it is of _utmost importance_
     that the paths given be reachable in all the networked machines.
     Different machines with different architectures can share the
     same physical `SRC' directory during installation, since
     compilations for different architectures take place in dedicated
     subdirectories. Also, different machines/architectures can share
     the same `LIBROOT' directory. This saves space since the
     architecture-independent libraries will be shared. See
     Multiarchitecture support below.

  3. *Compile Ciao:* At the ciao top level directory type `gmake all'.

     _Important:_ use GNU make ( `gmake'), not the standard UNIX
     make, as the latter does not support some features used during
     the compilation. It does not matter if the name of the
     executable is `make' or `gmake': only make sure that it is GNU
     make.

     This will:

        * Build an engine in `$(SRC)/bin/$(CIAOARCH)', where
          `$(CIAOARCH)' depends on the architecture. The engine is
          the actual interpreter of the low level code into which
          Ciao Prolog programs are compiled.

        * Build a new Ciao standalone compiler ( `ciaoc'), with the
          default paths set for your local configuration
          (nonetheless, these can be overridden by environment
          variables, as described below).

        * Precompile all the libraries under `$(SRC)/lib' and
          `$(SRC)/library' using this compiler.

        * Compile a toplevel Prolog shell and a shell for Prolog
          scripts, under the `$(SRC)/shell' directory.

        * Compile some small, auxiliary applications (contained in the `etc'
          directory, and documented in the part of the manual on
          'Miscellaneous Standalone Utilities').

     This step can be repeated successively for several architectures
     in the same source directory. Only the engine and some small
     parts of the libraries (those written in C) differ from one
     architecture to the other. Standard Ciao Prolog code compiles
     into bytecode object files (`.po') and/or executables which are
     portable among machines of different architecture, provided
     there is an executable engine accessible in every such machine.
     See more details below under Multiarchitecture support.

  4. *Check compilation:* If the above steps have been satisfactorily
     finished, the compiler has compiled itself and all the
     distribution modules, and very probably everything is fine.

  5. *Install Ciao:* To install Ciao in the directories selected in
     the file `SETTINGS' during step 2 above, type `gmake
     justinstall'. This will:

        * Install the executables of the Ciao program development
          tools (i.e., the general driver/top-level `ciao', the
          standalone compiler `ciaoc', the script interpreter `ciao-shell',
          miscellaneous utilities, etc.) in `BINROOT' (see below). In
          order to use these tools, the `PATH' environment variable
          of users needs to contain the path `BINROOT'.

        * Install the Ciao libraries under `LIBROOT/ciao' (these will
          be automatically found).

        * Install under `DOCROOT' the Ciao manuals in several formats
          (such as GNU `info', `html', `postscript', etc.), depending
          on the distribution. In order for these manuals to be found
          when typing `M-x info' within `emacs', or by the standalone `info'
          and `man' commands, the `MANPATH' and `INFOPATH' environment
          variables of users both need to contain the path `DOCROOT'.

        * Install under `LIBROOT/ciao' the Ciao GNU `emacs' interface
          ( `ciao.el', which provides an interactive interface to the
          Ciao program development tools, as well as some other
          auxiliary files) and a file `DOTemacs' containing the `emacs'
          initialization commands which are needed in order to use
          the Ciao `emacs' interface.

  6. *Set up user environments:* In order to automate the process of
     setting the variables above, the installation process leaves the
     files `LIBROOT/ciao/DOTcshrc' (for `csh'-like shells),
     `LIBROOT/ciao/DOTprofile' (for `sh'-like shells), and
     `LIBROOT/ciao/DOTemacs' (for emacs) with appropriate definitions
     which will take care of all needed environment variable
     definitions and emacs mode setup. Make the following
     modifications in your startup scripts, so that these files are
     used (`<LIBROOT>' must be replaced with the appropriate value):

        * For users a _csh-compatible shell_ ( `csh', `tcsh', ...),
          add to `~/.cshrc':

                       if ( -e <LIBROOT>/ciao/DOTcshrc ) then
                          source <LIBROOT>/ciao/DOTcshrc
                       endif

          `Mac OS X' users should add (or modify) the `path' file in
          the directory `~/Library/init/tcsh', adding the lines shown
          above. *Note:* while this is recognized by the terminal
          shell, and therefore by the text-mode Emacs which comes
          with Mac OS X, the Aqua native Emacs 21 does not recognize
          that initialization. It is thus necessary, at this moment,
          to set manually the Ciao shell (ciaosh) and Ciao library
          location by hand. This can be done from the Ciao menu
          within Emacs after a Ciao Prolog file has been loaded. We
          suppose that the reason is that Mac OS X does not actually
          consult the per-user initialization files on startup. It
          should also be possible to put the right initializations in
          the .emacs file using the `setenv' function of Emacs-lisp,
          as in

               (setenv "CIAOLIB" "<LIBROOT>/ciao")

          The same can be done for the rest of the variables
          initialized in `<LIBROOT>/ciao/DOTcshrc'

        * For users of an _sh-compatible shell_ ( `sh', `bash', ...),
          add to `~/.profile':

                       if [ -f <LIBROOT>/ciao/DOTprofile ]; then
                          . <LIBROOT>/ciao/DOTprofile
                       fi

          This will set up things so that the Ciao executables are
          found and you can access the Ciao system manuals using the `info'
          command. Note that, depending on your shell, _you may have
          to log out and back in_ for the changes to take effect.

        * Also, if you use `emacs' (highly recommended) add this line
          to your `~/.emacs' file:

                       (load-file "<LIBROOT>/ciao/DOTemacs.el")

     If you are installing Ciao globally in a multi-user machine,
     make sure that you instruct all users to do the same. If you are
     the system administrator, the previous steps can be done once
     and for all, and globally for all users by including the lines
     above in the central startup scripts (e.g., in Linux `/etc/bashrc', `/etc/csh.login', `/etc/csh.cshrc', `/etc/skel', `/usr/share/emacs/.../lisp/site-init.pl',
     etc.).

  7. *Download and install Emacs (highly recommended):* If the
     (freely available) `emacs' editor is not installed in your
     system, its installation is _highly recommended_ (if you are
     installing in a multi-user machine, you may want to do it in a
     general area so that it is available for other users, even if
     you do not use it yourself). While it is easy to use Ciao with
     any editor of your choice, the Ciao distribution includes a very
     powerful _application development environment_ which is based on `emacs'
     and which enables, e.g., source-level debugging, syntax
     coloring, context-sensitive on-line help, etc.

     The emacs editor (in all its versions: Un*x, Windows, etc.) can
     be downloaded from, for example, `http://www.emacs.org/', and
     also from the many GNU mirror sites worldwide (See
     `http://www.gnu.org/' for a list), in the `gnu/emacs' and
     `gnu/windows/emacs' directories. You can find answers to
     frequently asked questions (FAQ) about `emacs' in general at
     `http://www.gnu.org/software/emacs/emacs-faq.text' and about the
     Windows version at
     `http://www.gnu.org/software/emacs/windows/ntemacs.html'
     (despite the `ntemacs' name it runs fine also as is on Win9X and
     Win2000 machines).

  8. *Check installation / read documentation:* You may now want to
     check your installation (see Checking for correct installation on Un*x)
     and read the documentation, which is
     stored in `DOCROOT' (copied from `SRC/doc/reference') and can be
     easily accessed as explained that same section. There are
     special "getting started" sections at the beginning of the
     manual.

   Other useful `make' targets are listed at the beginning of
`$(SRC)/Makefile'.

   If you have any problems you may want to check
Troubleshooting (nasty messages and nifty workarounds).

   The system can be _uninstalled_ by typing `gmake uninstall' in the
top directory (the variables in `SETTINGS' should have the same value
as when the install was performed, so that the same directories are
cleaned).

218.3 Checking for correct installation on Un*x
===============================================

If everything has gone well, several applications and tools should be
available to a normal user. Try the following while logged in as a
_normal user_ (important in order to check that permissions are set
up correctly):

   * Typing `ciao' (or `ciaosh') should start the typical Prolog
     top-level shell.

   * In the top-level shell, Prolog library modules should load
     correctly. Type for example `use_module(library(dec10_io))' -you
     should get back a prompt with no errors reported.

   * To exit the top level shell, type `halt.' as usual, or <^D>.

   * Typing `ciaoc' should produce the help message from the Ciao standalone
     compiler.

   * Typing `ciao-shell' should produce a message saying that no code
     was found. This is a Ciao application which can be used to write scripts
     written in Prolog, i.e., files which do not need any explicit
     compilation to be run.

Also, the following documentation-related actions should work:

   * If the `info' program is installed, typing `info' should produce
     a list of manuals which _should include Ciao manual(s) in a
     separate area_ (you may need to log out and back in so that your
     shell variables are reinitialized for this to work).

   * Opening with a WWW browser (e.g., `netscape') the directory or
     `URL' corresponding to the `DOCROOT' setting should show a
     series of Ciao-related manuals. Note that _style sheets_ should
     be activated for correct formatting of the manual.

   * Typing `man ciao' should produce a man page with some very basic
     general information on Ciao (and pointing to the on-line
     manuals).

   * The `DOCROOT' directory should contain the manual also in the
     other formats such as `postscript' or `pdf' which specially
     useful for printing. See Printing manuals (Un*x) for
     instructions.

   Finally, if `emacs' is installed, after starting it (typing
`emacs') the following should work:

   * Typing <^H> <i> (or in the menus `Help->Manuals->Browse Manuals
     with Info') should open a list of manuals in info format in
     which the Ciao manual(s) should appear.

   * When opening a Prolog file, i.e., a file with `.pl' or `.pls'
     ending, using <^X><^F>`filename' (or using the menus) the code
     should appear highlighted according to syntax (e.g., comments in
     red), and `Ciao/Prolog' menus should appear in the menu bar on
     top of the `emacs' window.

   * Loading the file using the `Ciao/Prolog' menu (or typing <^C>
     <l>) should start in another emacs buffer the Ciao toplevel
     shell and load the file. You should now be able to switch the
     the toplevel shell and make queries from within `emacs'.

*Note:* when using `emacs' it is _very convenient_ to swap the
locations of the (normally not very useful) <Caps Lock> key and the
(very useful in `emacs') <Ctrl> key on the keyboard. How to do this
is explained in the `emacs' frequently asked questions FAQs (see the `emacs'
download instructions for their location).

218.4 Cleaning up the source directory
======================================

After installation, the source directory can be cleaned up in several
ways:

   * `gmake uninstall' removes the installation but does not touch
     the source directories.

   * `gmake totalclean' leaves the distribution is its original form,
     throwing away any intermediate files (as well as any unneeded
     files left behind by the Ciao developers), while still allowing
     recompilation.

   Other useful `make' targets are listed at the beginning of
`$(SRC)/Makefile'.

218.5 Multiarchitecture support
===============================

As mentioned before, Ciao applications (including the compiler and
the top level) can run on several machines with different
architectures without any need for recompiling, provided there is one
Ciao engine (compiled for the corresponding architecture) accessible
in each machine. Also, the Ciao libraries (installed in `LIBROOT',
which contain also the engines) and the actual binaries (installed in
`BINROOT') can themselves be shared on several machines with
different architectures, saving disk space.

   For example, assume that the compiler is installed as:

   `/usr/local/share/bin/ciaoc'

   and the libraries are installed under

   `/usr/local/share/lib'

   Assume also that the `/usr/local/share' directory is mounted on,
say, a number of Linux and a number of Solaris boxes. In order for
`ciaoc' to run correctly on both types of machines, the following is
needed:

  1. Make sure you that have done `gmake install' on one machine of
     each architecture (once for Linux and once for Solaris in our
     example). This recompiles and installs a new engine and any
     architecture-dependent parts of the libraries for each
     architecture. The engines will have names such as
     `ciaoengine.LINUXi86', `ciaoengine.SolarisSparc', and so on.

  2. In multi-architecture environments it is even more important to
     make sure that users make the modifications to their startup
     scripts using `<LIBROOT>/ciao/DOTcshrc' etc. The selection of
     the engine (and architecture-dependent parts of libraries) is
     done in these scripts by setting the environment variable
     `CIAOARCH', using the `ciao_get_arch' command, which is
     installed automatically when installing Ciao. This will set
     `CIAOARCH' to, say, `LINUXi86', `SolarisSparc', respectively,
     and `CIAOENGINE' will be set to `ciaoengine.'_CIAOARCH_.

     However, note that this is not strictly necessary if running on
     only one architecture: if `CIAOARCH' is not set (i.e.,
     undefined), the Ciao executables will look simply for
     `ciaoengine', which is always a link to the latest engine
     installed in the libraries. But including the initialization
     files provided has the advantage of setting also paths for the
     manuals, etc.

218.6 Installation and compilation under Windows
================================================

There are two possibilities in order to install Ciao Prolog on
Windows machines:

   * Installing from the Windows _precompiled_ distribution. This is
     the easiest since it requires no compilation and is highly
     recommended. This is described in Installing Ciao from a Win32 binary distribution.

   * Installing the standard Ciao Prolog (Un*x) system source
     distribution and compiling it under Windows. This is somewhat
     more complex and currently requires the (freely available)
     Cygnus Win32 development libraries -described below.

   In order to compile Ciao Prolog for Win32 environments you need to
have the (public domain) _Cygnus Win32_ and development libraries
installed in your system. Compilation should be performed preferably
under Windows NT-type systems.

   * Thus, the first step, if Cygnus Win32 is not installed in your
     system, is to download it (from, e.g.,
     `http://www.cygnus.com/misc/gnu-win32') and install it. The
     compilation process also requires that the executables `rm.exe',
     `sh.exe', and `uname.exe' from the Cygnus distribution be copied
     under `/bin' prior to starting the process (if these executables
     are not available under `/bin' the compilation process will
     produce a number of errors and eventually stop prematurely).

   * Assuming all of the above is installed, type `make allwin32'.
     This will compile both the engine and the Prolog libraries. In
     this process, system libraries that are normally linked
     dynamically under Un*x (i.e., those for which `.so' dynamically
     loadable files are generated) are linked statically into the
     engine (this is done instead of generating `.dll's because of a
     limitation in the current version of the Cygnus Win32
     environment). No actual installation is made at this point,
     i.e., this process leaves things in a similar state as if you
     had just downloaded and uncompressed the precompiled
     distribution. Thus, in order to complete the installation you
     should now:

   * Follow now the instructions in Installing Ciao from a Win32 binary distribution.

   A further note regarding the executables generated by the Ciao
compiler and top-level: the same considerations given in
Installing Ciao from a Win32 binary distribution apply regarding
`.bat' files, etc. However, in a system in which Cygnus Win32 is
installed these executables can also be used in a very simple way. In
fact, the executables can be run as in Un*x by simply typing their
name at the `bash' shell command line without any associated `.bat'
files. This only requires that the `bash' shell which comes with
Cygnus Win32 be installed and accessible: simply, make sure that `/bin/sh.exe'
exists.

218.7 Porting to currently unsupported operating systems
========================================================

If you would like to port Ciao to a currently unsupported platform,
there are several issues to take into account. The main one is to get
the _engine_ to compile in that platform, i.e., the C code under the
`engine' directory. The procedure currently followed by Ciao to
decide the various flags needed to compile is as follows:

   * The shell script `$(SRC)/etc/ciao_get_arch' is executed; it
     returns a string describing the operating system and the
     processor architecture (e.g., LINUXi86, SolarisSparc,
     SolarisAlpha, etc.). You should make sure it returns a correct
     (and meaningful) string for your setup. This string is used
     trhoughout the compilation to create several
     architecture-dependant flags.

   * In the directory `$(SRC)/makefile-sysdep' there are files called
     mkf-<OS><ARCH> for every combination of operating system and
     architecture in which Ciao is know to (and how to) compile. They
     set several flags regarding, for example, whether to use or not
     threads, which threads library to use, the optimization flags to
     use, the compiler, linker, and it also sets separately the
     architecture name (ARCHNAME variable) and the operating system
     (OSNAME). You should create a new mkf file for your machine,
     starting from the one which is closest to you.

   * Most times the porting problems happen in the use of locks and
     threads. You can either disable them, or have a look at the
     files `$(SRC)/engine/locks.h' and `$(SRC)/engine/threads.h'. If
     you know how to implement native (assembler) locks for your
     architecture, enable HAVE_NATIVE_SLOCKS for your architecture
     and add the definitions. Otherwise, if you have library-based
     locks, enable them. The mechanism in `threads.h' is similar.

   Once a working engine is achieved, it should be possible to
continue with the standard installation procedure, which will try to
use a completely static version of the standalone compiler
(`ciaoc.sta' in the `ciaoc' directory) to compile the interactive
top-level ( `ciaosh') and a new version of the standalone compiler ( `ciaoc').
These in turn should be able to compile the Prolog libraries. You may
also need to look at some libraries (such as, for example, `sockets')
which contain C code. If you do succeed in porting to a platform that
is currently unsupported please send the `mkf-CIAOARCH' and any
patches to <ciao@clip.dia.fi.upm.es>, and we will include them (with
due credit, of course) in the next distribution.

218.8 Troubleshooting (nasty messages and nifty workarounds)
============================================================

The following a list of common installation problems reported by
users:

   * *Problem:* Compilation errors appear when trying a new
     installation/compilation after the previous one was aborted
     (e.g., because of errors).

     *Possible reason and solution:* It is a good idea to clean up
     any leftovers from the previous compilation using `make
     engclean' before restarting the installation or compilation
     process.

   * *Problem:*

     During engine compilation, messages such as the following
     appear: `tasks.c:102:PTHREAD_CANCEL_ASYNCHRONOUS undeclared
     (first use of this function)'.

     *Possible reason and solution:*

     Your (Linux?) system does not have (yet) the Posix threads
     library installed. You can upgrade to one which does have it, or
     download the library from

     `http://pauillac.inria.fr/~xleroy/linuxthreads/index.html'

     and install it, or disable the use of threads in Linux: for
     this, edit the `SETTINGS' file and specify `USE_THREADS=no',
     which will avoid linking against thread libraries (it will
     disable the use of thread-related primitives as well). Clean the
     engine with `make engclean' and restart compilation.

     If you have any alternative threads library available, you can
     tinker with `engine/threads.h' and the files under
     `makefile-sysdep' in order to get the task managing macros right
     for your system. Be sure to link the right library. If you
     succeed, we (<ciao@clip.dia.fi.upm.es>) will be happy of knowing
     about what you have done.

   * *Problem:*

     `-lpthread: library not found' (or similar)

     *Possible reason and solution:*

     Your (Linux?) system seems to have Posix threads installed, but
     there is no threads library in the system. In newer releases
     (e.g., RedHat 5.0), the Posix threads system calls have been
     included in `glibc.so', so specifying `-lpthread' in
     `makefile-sysdep/mkf-LINUX' is not needed; remove it. `make
     engclean' and restart installation.

     Alternatively, you may have made a custom installation of Posix
     threads in a non-standard location: be sure to include the flag
     `-L/this/is/where/the/posix/libraries/are' *before* `-lpthread',
     and to update `/etc/ld.so.conf' (see `man ldconfig').

   * *Problem:*

     `Segmentation Violation' (when starting the first executable)

     *Possible reason and solution:*

     This has been observed with certain older versions of `gcc'
     which generated erroneous code under full optimization. The best
     solution is to upgrade to a newer version of `gcc'.
     Alternatively, lowering the level of optimization (by editing the `SETTINGS'
     file in the main directory of the distribution) normally solves
     the problem, at the cost of reduced execution speed.

   * *Problem:* `ciaoc:
     /home/clip/lib/ciao/ciao-X.Y/engine/ciaoengine: not found'

     *Possible reason and solution:*

        * The system was not fully installed and the variable
          `CIAOENGINE' was not set.

        * The system was installed, the variable `CIAOENGINE' is set,
          but it is does not point to a valid ciaoengine.

     See the file `LIBROOT/ciao/DOTcshrc' for user settings for
     environment variables.

   * *Problem:*

     `ERROR: File library(compiler) not found - aborting...' (or any
     other library is not found)

     *Possible reason and solution:*

        * The system was not installed and the variable `CIAOLIB' was
          not set.

        * The system is installed and the variable `CIAOLIB' is wrong.

     See the file `LIBROOT/ciao/DOTcshrc' for user settings for
     environment variables.

   * *Problem:*

     `ERROR: File <some_directory>/<some_file>.itf not found -
     aborting...'

     *Possible reason and solution:*

     Can appear when compiling `.pl' files. The file to compile
     (<some_file>.pl) is not in the directory <some_directory>. You
     gave a wrong file name or you are in the wrong directory.

   * *Problem:*

     `*ERROR*: /(write_option,1) is not a regular type' (and similar
     ones)

     *Possible reason and solution:*

     This is not a problem, but rather the type checker catching some
     minor inconsistencies which may appear while compiling the
     libraries. Bug us to remove it, but ignore it for now.

   * *Problem:*

     `WARNING: Predicate <some_predicate>/<N> undefined in module
     <some_module>'

     *Possible reason and solution:*

     It can appear when the compiler is compiling Ciao library
     modules. If so, ignore it (we will fix it). If it appears when
     compiling user programs or modules, you may want to check your
     program for those undefined predicates.

   * *Problem:*

     `gmake[1]: execve:
     /home/clip/mcarro/ciao-0.7p2/etc/collect_modules: No such file
     or directory'

     *Possible reason and solution:*

     Check if collect_modules is in $(SRC)/etc and is executable. If
     it is not here, your distribution is incorrect: please let us
     know.

   * *Problem:*

     `make: Fatal error in reader: SHARED, line 12: Unexpected end of
     line seen'

     *Possible reason and solution:*

     You are using standard Un*x make, not GNU's make implementation
     (gmake).

   * *Problem:*

     `WARNING's or `ERROR's while compiling the Ciao libraries during
     installation.

     *Possible reason and solution:*

     It is possible that you will see some such errors while
     compiling the Ciao libraries during installation. This is
     specially the case if you are installing a Beta or Alpha release
     of Ciao. These releases (which have "odd" version numbers such
     as 1.5 or 2.1) are typically snapshots of the development
     directories, on which many developers are working
     simultaneously, which may include libraries which have typically
     not been tested yet as much as the "official" distributions
     (those with "even" version numbers such as 1.6 or 2.8). Thus,
     minor warnings may not have been eliminated yet or even errors
     can sneak in. These warnings and errors should not affect the
     overall operation of the system (e.g., if you do not use the
     affected library).

219 Installing Ciao from a Win32 binary distribution
****************************************************

*Author(s):* Daniel Cabeza, Manuel Carro, Manuel Hermenegildo.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.5#92 (2000/3/28, 17:41:25 CEST)

   This describes the installation of Ciao after downloading the
Windows _binary_ (i.e., _precompiled_) distribution. It includes the
installation of libraries and manuals and applies to Windows
95/98/NT/2000/XP systems. This is the simplest Windows installation,
since it requires no compilation and is highly recommended. However,
it is also possible to compile Ciao from the source distribution on
these systems (please refer to Installing Ciao from the source distribution
for details).

   If you find any problems during installation, please refer to
Troubleshooting (nasty messages and nifty workarounds).  See
also Downloading new versions and Reporting bugs.

219.1 Win32 binary installation summary
=======================================

Please follow these steps (below we use the terms _folder_ and
_directory_ interchangeably):

  1. Download the precompiled distribution and unpack it into any
     suitable folder, such as, e.g., `C:\Program Files'.

     This will create there a folder whose name reflects the Ciao
     version. Due to limitations of Windows related to file
     associations, do not put Ciao too deep in the folder hierarchy.
     For unpacking you will need a recent version of a zip archive
     manager - there are many freely available such as `WinZip', `unzip', `pkunzip',
     etc. (see for example `www.winzip.com'). Some users have
     reported some problems with version 6.2 of WinZip, but no
     problems with, e.g., version 7. With WinZip, simply click on
     "Extract" and select the extraction folder as indicated above.

  2. Stop any Ciao-related applications.

     If you have a previous version of Ciao installed, make sure you
     do not have any Ciao applications (including, e.g., a toplevel
     shell) running, or the extraction process may not be able to
     complete. You may also want to delete the entire folder of the
     previous installation to save space.

  3. Open the Ciao source directory created during extraction and run
     (e.g. by double-clicking on it) the `install'(`.bat') script.
     Answer "yes" to the dialog that pops up and type any character
     in the installation window to finish the process. You may need
     to reboot for the changes in the registry to take effect.

     This will update the windows registry (the file `ciao'(`.reg')
     lists the additions) and also create some `.bat' files which may
     be useful for running Ciao executables from the command line. It
     also creates initialization scripts for the `emacs' editor. The
     actions performed by the installation script are reported in the
     installation window.

  4. You may want to add a _windows shortcut_ in a convenient place,
     such as the desktop, to `ciaosh.cpx', the standard interactive
     toplevel shell. It is located inside the `shell' folder (e.g.,
     click on the file `ciaosh.cpx' with the right mouse button and
     select the appropriate option, `Send to->Desktop as shortcut').

  5. You may also want to add another shortcut to the file `ciao'(`.html')
     located inside `doc\reference\ciao_html' so that you can open
     the Ciao manual by simply double-clicking on this shortcut.

  6. Finally, if the (freely available) `emacs' editor/environment is
     not installed in your system, we _highly recommend_ that you
     also install it at this point. While it is easy to use Ciao with
     any editor of your choice, the Ciao distribution includes a very
     powerful _application development environment_ which is based on `emacs'
     and which enables, e.g., source-level debugging, syntax
     coloring, context-sensitive on-line help, etc. If you are not
     convinced, consider that many programmers inside Micros*ft use
     `emacs' for developing their programs.

     The emacs editor (in all its versions: Un*x, Windows, etc.) can
     be downloaded from, for example, `http://www.emacs.org/', and
     also from the many GNU mirror sites worldwide (See
     `http://www.gnu.org/' for a list), in the `gnu/emacs' and
     `gnu/windows/emacs' directories. You can find answers to
     frequently asked questions (FAQ) about `emacs' in general at
     `http://www.gnu.org/software/emacs/emacs-faq.text' and about the
     Windows version at
     `http://www.gnu.org/software/emacs/windows/ntemacs.html'
     (despite the `ntemacs' name it runs fine also as is on Win9X and
     Win2000 machines).

     You need to tell `emacs' how to load the Ciao mode automatically
     when editing and how to access the on-line documentation:

        * Start `emacs' (double click on the icon or from the `Start'
          menu). Open (menu `Files->Open File' or simply <^X><^F>)
          the file `ForEmacs.txt' that the installation script has
          created in directory where you installed the Ciao
          distribution.

        * Copy the lines in the file (select with the mouse and then
          menu `Edit->Copy'). Open/Create using `emacs' (menu
          `Files->Open File' or simply <^X><^F>) the file `~/.emacs'
          (or, if this fails, `c:/.emacs').

        * Paste the two lines (menu `Edit->Paste' or simply <^Y>)
          into the file and save (menu `Files->Save Buffer' or simply
          <^X><^S>).

        * Exit `emacs' and start it again.

     `emacs' should not report any errors (at least related to Ciao)
     on startup. At this point the `emacs' checks in the following
     section should work.

219.2 Checking for correct installation on Win32
================================================

After the actions and registry changes performed by the installation
procedure, you should check that the following should work correctly:

   * Ciao-related file types (`.pl' source files, `.cpx' executables,
     `.itf,.po,.asr' interface files, `.pls' scripts, etc.) should
     have specific icons associated with them (you can look at the
     files in the folders in the Ciao distribution to check).

   * Double-clicking on the shortcut to `ciaosh'(`.cpx') on the
     desktop should start the typical Prolog top-level shell in a
     window. If this shortcut has not been created on the desktop,
     then double-clicking on the `ciaosh'(`.cpx') icon inside the
     `shell' folder within the Ciao source folder should have the
     same effect.

   * In the top-level shell, Prolog library modules should load
     correctly. Type for example `use_module(library(dec10_io)).' at
     the Ciao top-level prompt -you should get back a prompt with no
     errors reported.

   * To exit the top level shell, type `halt.' as usual, or <^D>.

Also, the following documentation-related actions should work:

   * Double-clicking on the shortcut to `ciao'(`.html') which appears
     on the desktop should show the Ciao manual in your default WWW
     browser. If this shortcut has not been created you can
     double-click on the `ciao'(`.html') file in the
     `doc\reference\ciao_html' folder inside the Ciao source folder.
     Make sure you configure your browser to use _style sheets_ for
     correct formatting of the manual (note, however, that some older
     versions of Explorer did not support style sheets well and will
     give better results turning them off).

   * The `doc\reference' folder contains the manual also in the other
     formats present in the distribution, such as `info' (very
     convenient for users of the `emacs' editor/program development
     system) and `postscript' or `pdf', which are specially useful
     for printing. See Printing manuals (Win32) for
     instructions.

Finally, if `emacs' is installed, after starting it (double-clicking
on the `emacs' icon or from the `Start' menu) the following should
work:

   * Typing <^H> <i> (or in the menus `Help->Manuals->Browse Manuals
     with Info') should open a list of manuals in info format in
     which the Ciao manual(s) should appear.

   * When opening a Prolog file, i.e., a file with `.pl' or `.pls'
     ending, using <^X><^F>`filename' (or using the menus) the code
     should appear highlighted according to syntax (e.g., comments in
     red), and `Ciao/Prolog' menus should appear in the menu bar on
     top of the `emacs' window.

   * Loading the file using the `Ciao/Prolog' menu (or typing <^C>
     <l>) should start in another emacs buffer the Ciao toplevel
     shell and load the file. You should now be able to switch the
     the toplevel shell and make queries from within `emacs'.

*Note:* when using `emacs' it is _very convenient_ to swap the
locations of the (normally not very useful) <Caps Lock> key and the
(very useful in `emacs') <Ctrl> key on the keyboard. How to do this
is explained in the `emacs' frequently asked questions FAQs (see the `emacs'
download instructions for their location).

   If you find that everything works but `emacs' cannot start the
Ciao toplevel you may want to check if you can open a normal Windows
shell within `emacs' (just do <M-x> `shell'). If you cannot, it is
possible that you are using some anti-virus software which is causing
problems. See
`http://www.gnu.org/software/emacs/windows/faq3.html#anti-virus' for
a workaround.

   In some Windows versions it is possible that you had to change the
_first_ backslashes in the DOTemacs.el file in the Ciao Directory.
E.g., assuming you have installed in drive `c:', instances of `c:\'
need to be changed to `c:/'. For example:
`c:\prolog/ciao-1.7p30Win32/shell/ciaosh.bat' should be changed to
`c:/prolog/ciao-1.7p30Win32/shell/ciaosh.bat'.

219.3 Compiling the miscellaneous utilities under Windows
=========================================================

The `etc' folder contains a number of utilities, documented in the
manual in _PART V - Miscellaneous Standalone Utilities_. In the Win32
distribution these utilities are not compiled by the installation
process. You can create the executable for each of them when needed
by compiling the corresponding `.pl' file.

219.4 Server installation under Windows
=======================================

If you would like to install Ciao on a server machine, used by
several clients, the following steps are recommended:

   * Follow the standard installation procedure on the server. When
     selecting the folder in which Ciao is installed make sure you
     select a folder that is visible by the client machines. Also
     make sure that the functionality specified in the previous
     sections is now available on the server.

   * Perform a _client installation_ on each client, by running
     (e.g., double-click on it) the `client.bat' script. This should
     update the registry of each client. At this point all the
     functionality should also be available on the clients.

219.5 CGI execution under IIS
=============================

The standard installation procedure updates the windows registry so
that Ciao executables (ending in `.cpx') are directly executable as
CGIs under Microsoft's IIS, i.e., so that you make applications
written in Ciao available on the WWW (see the `pillow' library for
specific support for this task). In the event you re-install IIS, you
probably would lose the entries in the registry which allow this. In
that case, processing the file `ciao.reg' produced during the
installation (or simply reinstalling Ciao) will add those entries
again.

219.6 Uninstallation under Windows
==================================

To uninstall Ciao under Windows, simply delete the directory in which
you put the Ciao distribution. If you also want to delete the
registry entries created by the Ciao installation (not strictly
needed) this must currently be done by hand. The installation leaves
a list of these entries in the file `ciao.reg' to aid in this task.
Also, all the register entries contain the word _ciao_. Thus, to
delete all Ciao entries, run the application `regedit' (for example,
by selecting `Run' from the Windows `Start' menu), search (<^F>) for
_ciao_ in all registry entries (i.e., select all of `Keys', `Values',
and `Data' in the `Edit->Find' dialog), and delete each matching key
(click on the left window to find the matching key for each entry
found).

   %% Local Variables: %% mode: CIAO %% update-version-comments:
"off" %% End:

220 Beyond installation
***********************

*Author(s):* Manuel Carro, Daniel Cabeza, Manuel Hermenegildo.

   *Version:* 1.10#7 (2006/4/26, 19:22:13 CEST)

   *Version of last change:* 1.7#55 (2001/1/26, 17:36:30 CET)

220.1 Architecture-specific notes and limitations
=================================================

Ciao makes use of advanced characteristics of modern architectures
and operating systems such as multithreading, shared memory, sockets,
locks, dynamic load libraries, etc., some of which are sometimes not
present in a given system and others may be implemented in very
different ways across the different systems. As a result, currently
not all Ciao features are available in all supported operating
systems. Sometimes this is because not all the required features are
present in all the OS flavors supported and sometimes because we
simply have not had the time to port them yet.

   The current state of matters is as follows:

LINUX:
     multithreading, shared DB access, and locking working.

Solaris:
     multithreading, shared DB access, and locking working.

IRIX:
     multithreading, shared DB access, and locking working.

SunOS 4:
     multithreading, shared DB access, and locking NOT working.

Win 95/98/NT/2000/XP:
     multithreading, shared DB access, and locking working. Dynamic
     linking of object code (C) libraries NOT working.

Mac OS X (Darwin):
     multithreading, shared DB access, and locking working.

   The features that do not work are disabled at compile time.

220.2 Keeping up to date with the Ciao users mailing list
=========================================================

We recommend that you join the Ciao _users mailing list_
(`ciao-users@clip.dia.fi.upm.es'), in order to receive information on
new versions and solutions to problems. Simply send a message to
<ciao-users-request@clip.dia.fi.upm.es>, containing in the body only
the word:

   `subscribe'

alone in one line. Messages in the list are strictly limited to
issues directly related to Ciao Prolog and your email address will of
course be kept strictly confidential. You mail also want to subscribe
to the `comp.lang.prolog' newsgroup.

   There is additional info available on the Ciao system, other CLIP
group software, publications on the technology underlying these
systems, etc. in the CLIP group's WWW site
`http://clip.dia.fi.upm.es'.

220.3 Downloading new versions
==============================

Ciao and its related libraries and utilities are under constant
improvement, so you should make sure that you have the latest
versions of the different components, which can be dowloaded from:

   `http://clip.dia.fi.upm.es/Software'

220.4 Reporting bugs
====================

If you still have problems after downloading the latest version and
reading the installation instructions you can send a message to
<ciao-bug@clip.dia.fi.upm.es>. Please be as informative as possible
in your messages, so that we can reproduce the bug.

   * For _installation problems_ we typically need to have the
     version and patch number of the Ciao package (e.g., the name of
     the file downloaded), the output produced by the installation
     process (you can capture it by redirecting the output into a
     file or cutting and pasting with the mouse), and the exact
     version of the Operating System you are using (as well as the C
     compiler, if you took a source distribution).

   * For _problems during use_ we also need the Ciao and OS versions
     and a small example of code which we can run to reproduce the
     bug.

References
**********

*[AAF91]*
     J. Almgren, S. Andersson, L. Flood, C. Frisk, H. Nilsson, and J.
     Sundberg.
     _Sicstus Prolog Library Manual_.
     Po Box 1263, S-16313 Spanga, Sweden, October 1991.

*[AKNL86]*
     Hassan Ait-Kaci, Roger Nasr, and Pat Lincoln.
     E An Overview.
     Technical Report AI-420-86-P, Microelectronics and Computer
     Technology   Corporation, 9430 Research Boulevard, Austin, TX
     78759, December 1986.

*[AKPS92]*
     H. A\"\it-Kaci, A. Podelski, and G. Smolka.
     A feature-based constraint system for logic programming with
     entailment.
     In _Proc. Fifth Generation Computer Systems 1992_, pages
     1012-1021,   1992.

*[Apt97]*
     K. Apt, editor.
     _From Logic Programming to Prolog_.
     Prentice-Hall, Hemel Hempstead, Hertfordshire, England, 1997.

*[BA82]*
     M. Ben-Ari.
     _Principles of Concurrent Programming_.
     Prentice Hall International, 1982.

*[BBP81]*
     D.L. Bowen, L. Byrd, L.M. Pereira, F.C.N. Pereira, and D.H.D.
     Warren.
     Decsystem-10 prolog user's manual.
     Technical report, Department of Artificial Intelligence,
     University of   Edinburgh, October 1981.

*[BCC97]*
     F. Bueno, D. Cabeza, M. Carro, M. Hermenegildo, P.
     L\'opez-Garc\'\ia, and   G. Puebla.
     The Ciao Prolog System. Reference Manual.
     The Ciao System Documentation Series-TR CLIP3/97.1, School of
     Computer   Science, Technical University of Madrid (UPM), August
     1997.
     System and on-line version of the manual available at
     \htmladdnormallink\tt http://www.ciaohome.org
     http://www.ciaohome.org.

*[BdlBH99]*
     F. Bueno, M.~Garc\'\ia de~la Banda, and M. Hermenegildo.
     Effectiveness of Abstract Interpretation in Automatic
     Parallelization: A Case Study in Logic Programming.
     _ACM Transactions on Programming Languages and Systems_,
     21(2):189-238, March 1999.

*[BLGPH04]*
     F. Bueno, P. L\'opez-Garc\'\ia, G. Puebla, and M. Hermenegildo.
     The Ciao Prolog Preprocessor.
     Technical Report CLIP1/04, Technical University of Madrid (UPM),
     Facultad de   Inform\'atica, 28660 Boadilla del Monte, Madrid,
     Spain, January 2004.

*[Bue95]*
     F. Bueno.
     The CIAO Multiparadigm Compiler: A User's Manual.
     Technical Report CLIP8/95.0, Facultad de Inform\'atica, UPM, June
      1995.

*[Byr80]*
     L. Byrd.
     Understanding the Control Flow of Prolog Programs.
     In S.-A. T\"arnlund, editor, _Workshop on Logic Programming_,
     Debrecen, 1980.

*[Car87]*
     M. Carlsson.
     Freeze, Indexing, and Other Implementation Issues in the Wam.
     In _Fourth International Conference on Logic Programming_, pages
      40-58. University of Melbourne, MIT Press, May 1987.

*[Car88]*
     M. Carlsson.
     _Sicstus Prolog User's Manual_.
     Po Box 1263, S-16313 Spanga, Sweden, February 1988.

*[CCG98]*
     I. Caballero, D. Cabeza, S. Genaim, J.M. Gomez, and M.
     Hermenegildo.
     persdb\_sql: SQL Persistent Database Interface.
     Technical Report D3.1.M2-A2 CLIP10/98.0, RADIOWEB Project,
     December   1998.

*[CGH93]*
     M. Carro, L. G\'omez, and M. Hermenegildo.
     Some Paradigms for Visualizing Parallel Execution of Logic
     Programs.
     In _1993 International Conference on Logic Programming_, pages
     184-201. MIT Press, June 1993.

*[CH95]*
     D. Cabeza and M. Hermenegildo.
     Distributed Concurrent Constraint Execution in the CIAO System.
     In _Proc. of the 1995 COMPULOG-NET Workshop on Parallelism and
     Implementation Technologies_, Utrecht, NL, September 1995. U.
     Utrecht / T.U.    Madrid.
     Available from http://www.cliplab.org/.

*[CH97]*
     D. Cabeza and M. Hermenegildo.
     WWW Programming using Computational Logic Systems (and the
     PiLLoW/Ciao Library).
     In _Proceedings of the Workshop on Logic Programming and the WWW
     at   WWW6_, San Francisco, CA, April 1997.

*[CH99]*
     D. Cabeza and M. Hermenegildo.
     The Ciao Modular Compiler and Its Generic Program Processing
     Library.
     In _ICLP'99 WS on Parallelism and Implementation of (C)LP
     Systems_,   pages 147-164. N.M. State U., December 1999.

*[CH00a]*
     D. Cabeza and M. Hermenegildo.
     A New Module System for Prolog.
     In _International Conference on Computational Logic, CL2000_,
     number   1861 in LNAI, pages 131-148. Springer-Verlag, July 2000.

*[CH00b]*
     D. Cabeza and M. Hermenegildo.
     The Ciao Modular, Standalone Compiler and Its Generic   Program
     Processing Library.
     In _Special Issue on Parallelism and Implementation of (C)LP
     Systems_,   volume 30(3) of _Electronic Notes in Theoretical
     Computer Science_.    Elsevier - North Holland, March 2000.

*[CH00c]*
     M. Carro and M. Hermenegildo.
     Tools for Constraint Visualization: The VIFID/TRIFID Tool.
     In P. Deransart, M. Hermenegildo, and J. Maluszynski, editors,
     _Analysis and Visualization Tools for Constraint Programming_,
     number 1870 in LNCS, pages 253-272. Springer-Verlag, September
     2000.

*[CH00d]*
     M. Carro and M. Hermenegildo.
     Tools for Search Tree Visualization: The APT Tool.
     In P. Deransart, M. Hermenegildo, and J. Maluszynski, editors,
     _Analysis and Visualization Tools for Constraint Programming_,
     number 1870 in LNCS, pages 237-252. Springer-Verlag, September
     2000.

*[CHGT98]*
     D. Cabeza, M. Hermenegildo, S. Genaim, and C. Taboch.
     Design of a Generic, Homogeneous Interface to Relational
     Databases.
     Technical Report D3.1.M1-A1, CLIP7/98.0, RADIOWEB Project,
     September   1998.

*[CHV96a]*
     D. Cabeza, M. Hermenegildo, and S. Varma.
     The PiLLoW/Ciao Library for INTERNET/WWW Programming using
     Computational Logic Systems.
     In _Proceedings of the 1st Workshop on Logic Programming Tools
     for   INTERNET Applications_, pages 72-90, JICSLP'96, Bonn,
     September 1996.

*[CHV96b]*
     D. Cabeza, M. Hermenegildo, and S. Varma.
     The \sf P\em i\sf LL\em o\sf W/Ciao Library for   INTERNET/WWW
     Programming using Computational Logic Systems.
     In _Proceedings of the 1st Workshop on Logic Programming Tools
     for   INTERNET Applications_, JICSLP'96, Bonn, September 1996.
     Available from \htmladdnormallink\tt
     http://clement.info.umoncton.ca/\~lpnet
     http://clement.info.umoncton.ca/\~lpnet.

*[CLI95]*
     The CLIP Group.
     CIAO Compiler: Distributed Execution and Low Level Support
     Subsystem.
     Public Software, ACCLAIM Deliverable D4.3/2-A3, Facultad de
     Inform\'atica, UPM, June 1995.

*[CM81]*
     W.F. Clocksin and C.S. Mellish.
     _Programming in Prolog_.
     Springer-Verlag, 1981.

*[Col78]*
     A. Colmerauer.
     Metamorphosis grammars.
     In _Natural language communication with computers_, pages
     133-189.    Springer LNCS 63, 1978.

*[Col82]*
     A. Colmerauer et al.
     _Prolog II: Reference Manual and Theoretical Model_.
     Groupe D'intelligence Artificielle, Facult\'e Des Sciences De
     Luminy,   Marseille, 1982.

*[DEDC96]*
     P. Deransart, A. Ed-Dbali, and L. Cervoni.
     _Prolog: The Standard_.
     Springer-Verlag, 1996.

*[Dij65]*
     E.W. Dijkstra.
     Co-operating sequential processes.
     In F. Genuys, editor, _Programming Languages_. Academic Press,
     London,   1965.

*[DL93]*
     S.~K. Debray and N.~W. Lin.
     Cost analysis of logic programs.
     _ACM Transactions on Programming Languages and Systems_,
     15(5):826-875, November 1993.

*[DLGH97]*
     S.K. Debray, P. L\'opez-Garc\'\ia, and M. Hermenegildo.
     Non-Failure Analysis for Logic Programs.
     In _1997 International Conference on Logic Programming_, pages
     48-62,   Cambridge, MA, June 1997. MIT Press, Cambridge, MA.

*[DLGHL97]*
     S.~K. Debray, P. L\'opez-Garc\'\ia, M. Hermenegildo, and N.-W.
     Lin.
     Lower Bound Cost Estimation for Logic Programs.
     In _1997 International Logic Programming Symposium_, pages
     291-305.    MIT Press, Cambridge, MA, October 1997.

*[GCH98]*
     J.M. Gomez, D. Cabeza, and M. Hermenegildo.
     WebDB: A Database WWW Interface.
     Technical Report D3.1.M2-A3 CLIP11/98.0, RADIOWEB Project,
     December   1998.

*[GdW94]*
     J.P. Gallagher and D.A. de Waal.
     Fast and precise regular approximations of logic programs.
     In Pascal Van~Hentenryck, editor, _Proc.~of the 11th
     International   Conference on Logic Programming_, pages 599-613.
     MIT Press, 1994.

*[HBC96]*
     M. Hermenegildo, F. Bueno, D. Cabeza, M. Carro, M.~Garc\'\ia
     de~la Banda, P.    L\'opez-Garc\'\ia, and G. Puebla.
     The CIAO Multi-Dialect Compiler and System: A Demo and   Status
     Report.
     In _Proceedings of the JICSLP'96 Workshop on Parallelism and
     Implementation Technology_. Computer Science Department,
     Technical University   of Madrid, September 1996.
     Available from \htmladdnormallink\tt
     http://www.cliplab.org/Projects/COMPULOG/meeting96/papers/PS/clip.ps.gz
     http://www.cliplab.org/Projects/COMPULOG/meeting96/papers/PS/clip.ps.gz.

*[HBC99]*
     M. Hermenegildo, F. Bueno, D. Cabeza, M. Carro, M.~Garc\'\ia de
     la Banda,   P. L\'opez-Garc\'\ia, and G. Puebla.
     The CIAO Multi-Dialect Compiler and System: An   Experimentation
     Workbench for Future (C)LP Systems.
     In _Parallelism and Implementation of Logic and Constraint
     Logic Programming_, pages 65-85. Nova Science, Commack, NY, USA,
     April   1999.

*[HBdlBP95]*
     M. Hermenegildo, F. Bueno, M.~Garc\'\ia de~la Banda, and G.
     Puebla.
     The CIAO Multi-Dialect Compiler and System: An   Experimentation
     Workbench for Future (C)LP Systems.
     In _Proceedings of the ILPS'95 Workshop on Visions for the
     Future of   Logic Programming_, Portland, Oregon, USA, December
     1995.
     Available from \htmladdnormallink\tt http://www.cliplab.org/
     http://www.cliplab.org/.

*[HBPLG99]*
     M. Hermenegildo, F. Bueno, G. Puebla, and P. L\'opez-Garc\'\ia.
     Program Analysis, Debugging and Optimization Using the Ciao
     System Preprocessor.
     In _1999 Int'l. Conference on Logic Programming_, pages 52-66,
     Cambridge, MA, November 1999. MIT Press.

*[HC93]*
     M. Hermenegildo and The CLIP Group.
     Towards CIAO-Prolog - A Parallel Concurrent Constraint   System.
     In _Proc. of the Compulog Net Area Workshop on Parallelism and
     Implementation Technologies_. FIM/UPM, Madrid, Spain, June 1993.

*[HC94]*
     M. Hermenegildo and The CLIP Group.
     Some Methodological Issues in the Design of CIAO - A Generic,
     Parallel, Concurrent Constraint System.
     In _Principles and Practice of Constraint Programming_, number
     874 in   LNCS, pages 123-133. Springer-Verlag, May 1994.

*[HC97]*
     M. Hermenegildo and The CLIP Group.
     An Automatic Documentation Generator for (C)LP - Reference
     Manual.
     The Ciao System Documentation Series-TR CLIP5/97.3, Facultad de
     Inform\'atica, UPM, August 1997.
     Online at \tt http://www.ciaohome.org.

*[HCC95]*
     M. Hermenegildo, D. Cabeza, and M. Carro.
     Using Attributed Variables in the Implementation of Concurrent
     and   Parallel Logic Programming Systems.
     In _Proc. of the Twelfth International Conference on Logic
     Programming_, pages 631-645. MIT Press, June 1995.

*[Her86]*
     M. Hermenegildo.
     An Abstract Machine for Restricted AND-parallel Execution of
     Logic Programs.
     In _Third International Conference on Logic Programming_, number
     225 in   Lecture Notes in Computer Science, pages 25-40.
     Imperial College,   Springer-Verlag, July 1986.

*[Her96]*
     M. Hermenegildo.
     Writing "Shell Scripts" in SICStus Prolog, April 1996.
     Posting in \tt comp.lang.prolog. Available from
     \htmladdnormallink\tt   http://www.cliplab.org/
     http://www.cliplab.org/.

*[Her99]*
     M. Hermenegildo.
     A Documentation Generator for Logic Programming Systems.
     Technical Report CLIP10/99.0, Facultad de Inform\'atica, UPM,
     September 1999.

*[Her00]*
     M. Hermenegildo.
     A Documentation Generator for (C)LP Systems.
     In _International Conference on Computational Logic, CL2000_,
     number   1861 in LNAI, pages 1345-1361. Springer-Verlag, July
     2000.

*[HG90]*
     M. Hermenegildo and K. Greene.
     \&-Prolog and its Performance: Exploiting Independent
     And-Parallelism.
     In _1990 International Conference on Logic Programming_, pages
     253-268. MIT Press, June 1990.

*[HG91]*
     M. Hermenegildo and K. Greene.
     The \&-Prolog System: Exploiting Independent And-Parallelism.
     _New Generation Computing_, 9(3,4):233-257, 1991.

*[Hog84]*
     C.~J. Hogger.
     _Introduction to Logic Programming_.
     Academic Press, London, 1984.

*[Hol90]*
     C. Holzbaur.
     _Specification of Constraint Based Inference Mechanisms
     through Extended Unification_.
     PhD thesis, University of Vienna, 1990.

*[Hol92]*
     C. Holzbaur.
     Metastructures vs. Attributed Variables in the Context of
     Extensible Unification.
     In _1992 International Symposium on Programming Language
     Implementation   and Logic Programming_, pages 260-268. LNCS631,
     Springer Verlag, August   1992.

*[Hol94]*
     C. Holzbaur.
     _SICStus 2.1/DMCAI Clp 2.1.1 User's Manual_.
     University of Vienna, 1994.

*[JL88]*
     D. Jacobs and A. Langen.
     Compilation of Logic Programs for Restricted And-Parallelism.
     In _European Symposium on Programming_, pages 284-297, 1988.

*[Knu84]*
     D. Knuth.
     Literate programming.
     _Computer Journal_, 27:97-111, 1984.

*[Kor85]*
     R. Korf.
     Depth-first iterative deepening: an optimal admissible tree
     search.
     _Artificial Intelligence_, 27:97-109, 1985.

*[LGHD96]*
     P. L\'opez-Garc\'\ia, M. Hermenegildo, and S.~K. Debray.
     A Methodology for Granularity Based Control of Parallelism in
     Logic Programs.
     _Journal of Symbolic Computation, Special Issue on Parallel
     Symbolic   Computation_, 22:715-734, 1996.

*[MH89]*
     K. Muthukumar and M. Hermenegildo.
     Determination of Variable Dependence Information at Compile-Time
      Through Abstract Interpretation.
     In _1989 North American Conference on Logic Programming_, pages
     166-189. MIT Press, October 1989.

*[Nai85]*
     L.\ Naish.
     _The MU-Prolog 3.2 Reference Manual_.
     TR 85/11, Dept. of Computer Science, U. of Melbourne, October
     1985.

*[Nai91]*
     Lee Naish.
     Adding equations to NU-Prolog.
     In _Proceedings of The Third International Symposium on
     Programming   Language Implementation and Logic Programming
     (PLILP'91)_, number 528 in   Lecture Notes in Computer Science,
     pages 15-26, Passau, Germany, August   1991. Springer-Verlag.

*[Par97]*
     The RADIOWEB~Project Partners.
     RADIOWEB EP25562: Automatic Generation of Web Sites for the
     Radio Brodcasting Industry - Project Description / Technical
     Annex.
     Technical Report, RADIOWEB Project, July 1997.

*[PBH97]*
     G. Puebla, F. Bueno, and M. Hermenegildo.
     An Assertion Language for Debugging of Constraint Logic
     Programs.
     In _Proceedings of the ILPS'97 Workshop on Tools and
     Environments for   (Constraint) Logic Programming_, October 1997.
     Available from \htmladdnormallink\tt
     ftp://clip.dia.fi.upm.es/pub/papers/assert\_lang\_tr\_discipldeliv.ps.gz
     ftp://clip.dia.fi.upm.es/pub/papers/assert\_lang\_tr\_discipldeliv.ps.gz
     as   technical report CLIP2/97.1.

*[PBH00]*
     G. Puebla, F. Bueno, and M. Hermenegildo.
     An Assertion Language for Constraint Logic Programs.
     In P. Deransart, M. Hermenegildo, and J. Maluszynski, editors,
     _Analysis and Visualization Tools for Constraint Programming_,
     number 1870 in LNCS, pages 23-61. Springer-Verlag, September
     2000.

*[PH99]*
     G. Puebla and M. Hermenegildo.
     Some Issues in Analysis and Specialization of Modular
     Ciao-Prolog Programs.
     In _ICLP'99 Workshop on Optimization and Implementation of
     Declarative   Languages_, pages 45-61. U. of Southampton, U.K,
     November 1999.

*[PW80]*
     F.C.N. Pereira and D.H.D. Warren.
     Definite clause grammars for language analysis - a survey of the
     formalism   and a comparison with augmented transition networks.
     _Artificial Intelligence_, 13:231-278, 1980.

*[SS86]*
     L. Sterling and E. Shapiro.
     _The Art of Prolog_.
     MIT Press, 1986.

*[Swe95]*
     Swedish Institute of Computer Science, P.O. Box 1263, S-16313
     Spanga, Sweden.
     _Sicstus Prolog V3.0 User's Manual_, 1995.

*[War88]*
     D.H.D. Warren.
     The Andorra Model.
     Presented at Gigalips Project workshop. U. of Manchester, March
     1988.

Global Index
************

This is a global index containing pointers to places where concepts,
predicates, modes, properties, types, applications, etc., are
referred to  in the text of the document. Note that due to
limitations of the  `info' format unfortunately only the first
reference will appear in  online versions of the document.