1% BEGIN LICENSE BLOCK
2% Version: CMPL 1.1
3%
4% The contents of this file are subject to the Cisco-style Mozilla Public
5% License Version 1.1 (the "License"); you may not use this file except
6% in compliance with the License.  You may obtain a copy of the License
7% at www.eclipse-clp.org/license.
8% 
9% Software distributed under the License is distributed on an "AS IS"
10% basis, WITHOUT WARRANTY OF ANY KIND, either express or implied.  See
11% the License for the specific language governing rights and limitations
12% under the License. 
13% 
14% The Original Code is  The ECLiPSe Constraint Logic Programming System. 
15% The Initial Developer of the Original Code is  Cisco Systems, Inc. 
16% Portions created by the Initial Developer are
17% Copyright (C) 2006 Cisco Systems, Inc.  All Rights Reserved.
18% 
19% Contributor(s): 
20% 
21% END LICENSE BLOCK
22
23
24\section{All Solutions }
25     Built-ins to collect all solutions to nondeterministic goals.
26     The implementation is in
27     \begin{itemize}
28     \item setof.pl
29     \end{itemize}
30     and is based on
31     public domain code by Richard O'Keefe. The main change is the
32     use of {\eclipse} bag-predicates to collect the solutions.
33
34\section{Arithmetic }
35Built-ins for arithmetic computations. Related code is in
36     \begin{itemize}
37     \item emu.c
38     \item bip_arith.c
39     \item bigrat.c
40     \item intervals.c
41     \end{itemize}
42The actual arithmetic operations are implemented in functions that are
43accessed via tag-index function tables, as described in section
44\ref{secarith}.
45The compiler (actually inlining transformations for is/2, >/2, etc)
46flattens arithmetic expressions in sequences of predicate
47calls, e.g.\ R is X+3*Y becomes
48\begin{verbatim}
49    *(3,Y,T), +(X,T,R)
50\end{verbatim}
51where T is a compiler-generated auxiliary variable. These predicates
52are implemented in C via the function tables.  Expressions that are not
53flattened by the compiler are interpreted by the predicate eval/2.
54
55
56\section{Non-logical Variables, Arrays, Bags, Shelves and Stores }
57Built-ins to store data across backtracking. All these relay on a single heap
58copying routine to copy terms from the global stack (where they would be
59discarded on backtracking) to the heap, where the memory is managed explicitly.
60     \begin{itemize}
61     \item bip_array.c - nonlogical variables and arrays, references
62     \item bip_bag.c - bag built-ins
63     \item bip_record.c - record built-ins
64     \item bip_shelf.c - shelf built-ins
65     \item bip_store.c - store built-ins
66     \item property.c - heap copying routines
67     \end{itemize}
68
69\section{Control}
70Built-ins and language constructs to control execution are mostly
71recognised by the compiler and translated into specific abstract machine
72instructions. Some of them employ auxiliary hand-written abstract machine
73code sequences that are part of the runtime system. Files:
74     \begin{itemize}
75     \item emu.c (instructions)
76     \item code.c (hand written code sequences)
77     \end{itemize}
78
79\section{Predicate Database and Compiler }
80Built-ins for creation of handling of executable code (up to {\eclipse} 5.X).
81     \begin{itemize}
82     \item bip_db.c
83     \item procedure.c
84     \item section.c
85     \item pass[234].c
86     \item head.c
87     \item body.c
88     \end{itemize}
89
90\section{Debugging }
91Built-ins and commands related to debugging are implemented in
92     \begin{itemize}
93     \item emu.c
94     \item bip_control.c
95     \item tracer_tty.pl (console variant) and tracer_tcl.pl (gui variant)
96     \end{itemize}
97
98\section{Dynamic Predicates }
99Built-ins to create and manipulate dynamic procedures are implemented in
100     \begin{itemize}
101     \item bip_db.c
102     \item dynamic.c
103     \end{itemize}
104
105\section{Development Environment and Global Settings }
106     Built-ins related to the development environment are implemented in
107     \begin{itemize}
108     \item bip_control.c
109     \item bip_misc.c
110     \end{itemize}
111
112\section{Event Handling }
113     Built-ins to handle events and interrupts are implemented in
114     \begin{itemize}
115     \item emu.c
116     \item handlers.c
117     \item error.c
118     \end{itemize}
119
120\section{External Interface }
121     Built-ins to access functions and data from foreign languages are implemented in
122     \begin{itemize}
123     \item external.c
124     \item embed.c
125     \end{itemize}
126
127\section{Character and Stream I/O }
128Built-ins to open, manipulate and close I/O streams, and to
129input and output characters or byte strings are found in
130     \begin{itemize}
131     \item io.c
132     \item bip_io.c
133     \end{itemize}
134
135\section{Term I/O }
136Built-ins for input/output of complex terms.
137     \begin{itemize}
138     \item bip_io.c
139     \item lex.c (lexical analyser)
140     \item read.c (parser)
141     \item write.c (term writer)
142     \end{itemize}
143
144\section{Modules }
145Directives and built-ins related to the module system.
146     \begin{itemize}
147     \item bip_module.c
148     \item proc_desc.c
149     \item property.c
150     \end{itemize}
151
152\section{Operating System }
153Built-ins to access operating-system services.
154Note the differences between UNIX and Windows style variants.
155     \begin{itemize}
156     \item bip_misc.c
157     \item bip_io.c
158     \item os_support.c
159     \end{itemize}
160
161\section{Strings and Atoms }
162     Built-ins to create, convert and decompose strings and atoms.
163     \begin{itemize}
164     \item bip_strings.c
165     \item bip_tconv.c
166     \end{itemize}
167
168\section{Advanced Control and Suspensions }
169     Everything related to suspensions, priority- and data-driven control.
170     \begin{itemize}
171     \item emu.c
172     \item bip_delay.c
173     \end{itemize}
174
175\section{Syntax Settings }
176The setting that affect syntax are operators, structures, macros,
177character classes.  Operators and macros are stored as functor
178properties in the dictionary.  Structures are implemented on the
179Prolog level and definition stored in a table. Character classes and
180an number of option flags are part of a syntax descriptor that is stored
181with each module.
182     \begin{itemize}
183     \item lex.c
184     \item read.c
185     \end{itemize}
186
187\section{Comparing and Sorting }
188Built-ins for symbolic term comparison and sorting. Files:
189     \begin{itemize}
190     \item bip_comp.c
191     \end{itemize}
192A central item is the routine compare_terms() which implements the standard
193term order, a total order on all terms, including variables (as documented
194for the compare/3 built-in). Order is primarily on term type, then on value.
195Note that numbers of different types are therefore not in their numerical order.
196
197As the core of all the sorting related builtins, a single implementation of
198mergesort for lists is provided. The algorithm is natural merge, and
199it takes advantage of preexisting order in the input list: subsequences
200that are either in the correct order or in reverse order are detected.
201
202
203\section{Term Manipulation }
204     Built-ins to convert, compose, decompose and modify terms.
205     \begin{itemize}
206     \item bip_tconv.c
207     \end{itemize}
208
209\section{Type Testing }
210     Meta-logical built-ins to test the type of terms.
211     Most of these map to simple tag tests and are implemented
212     inside the emulator.
213     \begin{itemize}
214     \item emu.c
215     \end{itemize}
216