Context Navigation

programming.html

Visit:

Revision 4621, 46.6 KB (checked in by pmoura, 6 weeks ago)
Improved navigation bar in the XHTML manual pages.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`

Line
1	<?xml version="1.0" encoding="utf-8"?>
2	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
3	"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
4
5	<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
6
7	<head>
8	<meta http-equiv="content-type" content="application/xml+xhtml; charset=utf-8" />
9	<title>Logtalk user manual: writing, running, and debugging programs</title>
10	<link rel="stylesheet" href="../screen.css" type="text/css" media="screen"/>
11	<link rel="stylesheet" href="../print.css" type="text/css" media="print"/>
12	</head>
13
14	<body>
15
16	<div class="top-left">Logtalk user manual</div>
17	<div class="top-right">Writing, running, and debugging programs</div>
18	<div class="bottom-left"><span class="page"/></div>
19	<div class="bottom-right"><span class="page"/></div>
20	<div class="navtop"><a href="../index.html">Contents</a> > <a href="index.html">User Manual</a> > Programming</div>
21
22	<h1 id="programming_programming">Writing, running, and debugging programs</h1>
23
24
25	<h2 id="programming_writing">Writing programs</h2>
26
27	<p>
28	For a successful programming in Logtalk, you need a good working knowledge of Prolog and an understanding of the principles of object-oriented programming. All guidelines for writing good Prolog code apply as well to Logtalk programming. To those guidelines, you should add the basics of good object-oriented design.
29	</p>
30	<p>
31	One of the advantages of a system like Logtalk is that it enable us to use the currently available object-oriented methodologies, tools, and metrics <a href="../bibliography.html#Champaux92">[Champaux 92]</a> in Prolog programming. That said, writing programs in Logtalk is similar to writing programs in Prolog: we define new predicates describing what is true about our domain objects, about our problem solution. We encapsulate our predicate directives and definitions inside new objects, categories and protocols that we create by hand with a text editor or by using the Logtalk built-in predicates. Some of the information collected during the analysis and design phases can be integrated in the objects, categories and protocols that we define by using the available entity and predicate documenting directives.
32	</p>
33
34	<h3 id="programming_source_files">Source files</h3>
35
36	<p>
37	Logtalk source files may contain any number of objects, categories, protocols, and plain Prolog code. If you prefer to define each entity in its own source file, then it is recommended that the source file be named after the entity identifier. For parametric objects, the identifier arity can be appended to the identifier functor. By default, all Logtalk source files use the extension <code>.lgt</code> but this is optional and can be set in the configuration files. Intermediate Prolog source files (generated by the Logtalk compiler) have, by default, a <code>.pl</code> extension. Again, this can be set to match the needs of a particular Prolog compiler in the corresponding configuration file. For example, we may define an object named <code>vehicle</code> and save it in a <code>vehicle.lgt</code> source file that will be compiled to a <code>vehicle.pl</code> Prolog file. If we have a <code>sort(_)</code> parametric object we can save it on a <code>sort_1.lgt</code> source file that will be compiled to a <code>sort_1.pl</code> Prolog file. This name scheme helps avoid file name conflicts (remember that all Logtalk entities share the same name space).
38	</p>
39	<p>
40	Logtalk source files may contain arbitrary Prolog directives and clauses interleaved with Logtalk entity definitions. These directives and clauses are be copied unchanged to the corresponding Prolog output file. This feature is included to help the integration of Logtalk with Prolog extensions such as, for example, constraint programming extensions. The following Prolog directives are processed when read (thus affecting the compilation of the source code that follows): <code>ensure_loaded/1</code>, <code>op/3</code>, and <code>set_prolog_flag/2</code>. The <code>initialization/1</code> directive may be used for defining an initialization goal to be executed when loading a source file.
41	</p>
42	<p>
43	The text encoding used in a source file may be declared using the <a title="Consult reference manual" href="../refman/directives/encoding1.html"><code>encoding/1</code></a> directive when running Logtalk with some back-end Prolog compilers that support multiple encodings (check the <code>encoding_directive</code> flag in the configuration file of your Prolog compiler). The encoding used (and, in the case of a Unicode encoding, any BOM present) in a source file will be used for the generated Prolog and XML files. Logtalk uses the encoding names specified by <a title="" href="http://www.iana.org/assignments/character-sets">IANA</a> (in those cases where a preferred MIME name alias is specified, the alias is used instead).
44	</p>
45
46	<h3 id="programming_portability">Portable programs</h3>
47
48	<p>
49	Logtalk is compatible with almost all modern Prolog compilers. However, this does not necessarily imply that your Logtalk programs will have the same level of portability. If possible, you should only use in your programs Logtalk built-in predicates and ISO Prolog specified built-in predicates and arithmetic functions. If you need to use built-in predicates (or built-in arithmetic functions) that may not be available in other Prolog compilers, you should try to encapsulate the non-portable code in a small number of objects and provide a portable <strong>interface</strong> for that code through the use of Logtalk protocols. An example will be code that access operating-system specific features. The Logtalk compiler can warn you of the use of non-ISO specified built-in predicates and arithmetic functions by using the <code>portability/1</code> compiler flag.
50	</p>
51
52	<h3 id="programming_cc">Conditional compilation</h3>
53
54	<p>
55	Logtalk supports conditional compilation within source files using the <a title="Consult reference manual" href="../refman/directives/if1.html"><code>if/1</code></a>, <a title="Consult reference manual" href="../refman/directives/elif1.html"><code>elif/1</code></a>, <a title="Consult reference manual" href="../refman/directives/else0.html"><code>else/0</code></a>, and <a title="Consult reference manual" href="../refman/directives/endif0.html"><code>endif/0</code></a> directives. This support is similar to the support found in some Prolog compilers such as ECLiPSe, SWI-Prolog, or YAP.
56	</p>
57
58	<h3 id="programming_errors">Avoiding common errors</h3>
59
60	<p>
61	Try to write objects and protocol documentation <strong>before</strong> writing any other code; if you are having trouble documenting a predicate perhaps we need to go back to the design stage.
62	</p>
63	<p>
64	Try to avoid lengthy hierarchies. Besides performance penalties, composition is often a better choice over inheritance for defining new objects (Logtalk supports component-based programming through the use of categories). In addition, prototype-based hierarchies are conceptually simpler and more efficient than class-based hierarchies.
65	</p>
66	<p>
67	Dynamic predicates or dynamic entities are sometimes needed, but we should always try to minimize the use of non-logical features like destructive assignment (asserts and retracts).
68	</p>
69	<p>
70	Since each Logtalk entity is independently compiled, if an object inherits a dynamic or a meta-predicate predicate, then we must repeat the respective directives in order to ensure a correct compilation.
71	</p>
72	<p>
73	In general, Logtalk does not verify if a user predicate call/return arguments comply with the declared modes. On the other hand, Logtalk built-in predicates, built-in methods, and message sending control structures are carefully checked for calling mode errors.
74	</p>
75	<p>
76	Logtalk error handling strongly depends on the ISO compliance of the chosen Prolog compiler. For instance, the error terms that are generated by some Logtalk built-in predicates assume that the Prolog built-in predicates behave as defined in the ISO standard regarding error conditions. In particular, if your Prolog compiler does not support a <code>read_term/3</code> built-in predicate compliant with the ISO Prolog Standard definition, then the current version of the Logtalk compiler may not be able to detect misspell variables in your source code.
77	</p>
78
79	<h3 id="programming_style">Coding style guidelines</h3>
80
81	<p>
82	It is suggested that all code between an entity opening and closing directives be indented by one tab stop. When defining entity code, both directives and predicates, Prolog coding style guidelines may be applied. All Logtalk source files, examples, and standard library entities use four-space tabs for laying out code. Closed related entities should be defined in the same source file. Entities that might be useful in different contexts (such as library entities) are best defined in their own source files.
83	</p>
84
85
86	<h2 id="programming_session">Running a Logtalk session</h2>
87
88	<p>
89	We run Logtalk inside a normal Prolog session, after loading the necessary files. Logtalk extends but does not modify your Prolog compiler. We can freely mix Prolog queries with the sending of messages and our programs can be made of both normal Prolog clauses and object definitions.
90	</p>
91
92	<h3 id="programming_starting">Starting Logtalk</h3>
93
94	<p>
95	Depending on your Logtalk installation, you may use a script or a shortcut to start Logtalk with your chosen Prolog compiler. On POSIX operating systems, the scripts should be available from the command-line; scripts are named upon the used Prolog compilers. On Windows, the shortcuts should be available from the Start Menu. If no scripts or shortcuts are available for your installation, operating-system, or Prolog compiler, you can always start a Logtalk session by performing the following steps:
96	</p>
97	<ol>
98	<li>Start your Prolog compiler.</li>
99	<li>Load the appropriate configuration file for your compiler. Configuration files for most common Prolog compilers can be found in the <code>configs</code> subdirectory.</li>
100	<li>Load the Logtalk compiler/runtime files contained in the <code>compiler</code> subdirectory.</li>
101	<li>Load the library paths configuration file corresponding to your Logtalk installation contained in the <code>libpaths</code> subdirectory.</li>
102	</ol>
103	<p>
104	Note that the configuration files, compiler/runtime files, and library paths file are Prolog source files. The predicate called to load (and compile) them depends on your Prolog compiler. In case of doubt, consult your Prolog compiler reference manual or take a look at the definition of the predicate <code>'$lgt_load_prolog_code'/3</code> in the corresponding configuration file.
105	</p>
106	<p>
107	Most Prolog compilers support automatic loading of an initialization file, which can include the necessary directives to load both the Prolog configuration file and the Logtalk compiler. This feature, when available, allows automatic loading of Logtalk when you start your Prolog compiler.
108	</p>
109
110	<h3 id="programming_compiling">Compiling and loading your programs</h3>
111
112	<p>
113	Your programs will be made of source files containing your objects, protocols, and categories. After changing the Prolog working directory to the one containing your files, you can compile them to disk by calling the Logtalk built-in predicate
114	<a title="Consult reference manual" href="../refman/builtins/logtalk_compile1.html"><code>logtalk_compile/1</code></a>:
115	</p>
116	<pre>\| ?- logtalk_compile([source_file1, source_file2, ...]).</pre>
117	<p>
118	This predicate runs the compiler on each argument file and, if no fatal errors are found, outputs Prolog source files that can then be consulted or compiled in the usual way by your Prolog compiler.
119	</p>
120	<p>
121	To compile to disk and also load into memory the source files we can use the Logtalk built-in predicate <a title="Consult reference manual" href="../refman/builtins/logtalk_load1.html"><code>logtalk_load/1</code></a>:
122	</p>
123	<pre>\| ?- logtalk_load([source_file1, source_file2, ...]).</pre>
124	<p>
125	This predicate works in the same way of the predicate <code>logtalk_compile/1</code> but also loads the compiled files to memory.
126	</p>
127	<p>
128	Both predicates expect a source name name or a list of source name names as an argument. The Logtalk source file name extension, as defined in the configuration file, must be omitted.
129	</p>
130	<p>
131	If you have more than a few source files then you may want to use a loader helper file containing the calls to the <code>logtalk_load/1-2</code> predicates. Consulting or compiling the loader file will then compile and load all your Logtalk entities into memory (see below for details).
132	</p>
133	<p>
134	With most Prolog back-end compilers, you can use the shorthand <code>{File}</code> for <code>logtalk_load(File)</code>. The use this shorthand should be restricted to the Logtak/Prolog top-level; do not use it from within source files.
135	</p>
136
137	<h3 id="programming_loaders">Loader utility files</h3>
138
139	<p>
140	Most examples directories contain a Logtalk utility file that can be used to load all included source files. These loader utility files are usually named <code>loader.lgt</code> or contain the word "loader" in their name. Loader files are compiled and loaded like any ordinary Logtalk source file. For an example loader file named <code>loader.lgt</code> we would type:
141	</p>
142	<pre>\| ?- logtalk_load(loader).</pre>
143	<p>
144	Usually these files contain a call to the Logtalk built-in predicates <a title="Consult reference manual" href="../refman/builtins/logtalk_load1.html"><code>logtalk_load/1</code></a> or <a title="Consult reference manual" href="../refman/builtins/logtalk_load2.html"><code>logtalk_load/2</code></a>, wrapped inside an <code>initialization/1</code> directive. For instance, if your code is split in three Logtalk source files named <code>source1.lgt</code>, <code>source2.lgt</code>, and <code>source3.lgt</code>, then the contents of your loader file could be:
145	</p>
146	<pre>:- initialization(
147	logtalk_load([
148	source1, source2, source3])). </pre>
149	<p>
150	Another example of directives that are often used in a loader file would be <code>op/3</code> directives declaring global operators needed by your application. Loader files are also often used for setting compiler options for the source files (this is useful even when you only have a single source file if you always load it with using the same set of compiler options). For example:
151	</p>
152	<pre>:- initialization(
153	logtalk_load(
154	[source1, source2, source3],
155	[underscore_variables(dont_care), portability(warning), xmlspec(xsd)])). </pre>
156	<p>
157	To take the best advantage of loader files, assert a clause to the dynamic predicate <code>logtalk_library_path/2</code> for the directory containing your source files, as explained in the next section.
158	</p>
159	<p>
160	A common mistake is to try to set compiler options using <code>logtalk_load/2</code> with a loader file. For example, by writing:
161	</p>
162	<pre>\| ?- logtalk_load(loader, [xmlspec(xsd), xslfile('lgtxhtml.xsl')]).</pre>
163	<p>
164	This will not work as you might expect as the compiler options will only be used in the compilation of the <code>loader.lgt</code> file itself and will not affect the compilation of files loaded through the <code>initialization/1</code> directive contained on the loader file.
165	</p>
166
167	<h3 id="programming_libraries">Libraries of source files</h3>
168
169	<p>
170	Logtalk defines a <em>library</em> simply as a directory containing source files. Library locations can be specified by defining or asserting clauses for the dynamic and multifile predicate <a title="Consult reference manual" href="../refman/builtins/logtalk_library_path2.html"><code>logtalk_library_path/2</code></a>. For example:
171	</p>
172	<pre>\| ?- assertz(logtalk_library_path(shapes, '$LOGTALKUSER/examples/shapes/')). </pre>
173	<p>
174	The first argument of the predicate is used as an alias for the path on the second argument. Library aliases may also be used on the second argument. For example:
175	</p>
176	<pre>\| ?- assertz(logtalk_library_path(lgtuser, '$LOGTALKUSER/')),
177	assertz(logtalk_library_path(examples, lgtuser('examples/'))),
178	assertz(logtalk_library_path(viewpoints, examples('viewpoints/'))).</pre>
179	<p>
180	This allows us to load a library source file without the need to first change the current working directory to the library directory and then back to the original directory. For example, in order to load a <code>loader.lgt</code> file, contained in a library named <code>shapes</code>, we just need to type:
181	</p>
182	<pre>\| ?- logtalk_load(viewpoints(loader)). </pre>
183	<p>
184	The best way to take advantage of this feature is to load at startup a source file containing an <code>initialization/1</code> directive which asserts all the <code>logtalk_library_path/2</code> clauses needed for all available libraries. This allows us to load library source files or entire libraries without worrying about libraries paths, improving code portability. The directory paths on the second argument must always end with the path directory separator character.
185	</p>
186	<p>
187	Unfortunately, a few Prolog compilers do not support the <code><library>(<source file>)</code> notation. In this case, you will need to set the working directory to be the one that contains the source file in order to load it. The library notation provides functionality similar to the <code>file_search_path/2</code> mechanism introduced by Quintus Prolog and later adopted by some other Prolog compilers.
188	</p>
189
190	<h3 id="programming_flags">Compiler flags</h3>
191
192	<p>
193	The <a title="Consult reference manual" href="../refman/builtins/logtalk_load1.html"><code>logtalk_load/1</code></a> and <a title="Consult reference manual" href="../refman/builtins/logtalk_compile1.html"><code>logtalk_compile/1</code></a> always use the current set of default compiler flags as specified in the Logtalk configuration files or changed for the current session using the built-in predicate <a title="Consult reference manual" href="../refman/builtins/set_logtalk_flag2.html"><code>set_logtalk_flag/2</code></a>. Although the default flag values cover the usual cases, you may want to use a different set of flag values while compiling or loading some of your Logtalk source files. This can be accomplished by using the <a title="Consult reference manual" href="../refman/builtins/logtalk_load2.html"><code>logtalk_load/2</code></a> or the <a title="Consult reference manual" href="../refman/builtins/logtalk_compile2.html"><code>logtalk_compile/2</code></a> built-in predicates. These two predicates accept a list of flag values affecting how a Logtalk source file is compiled and loaded:
194	</p>
195	<pre>\| ?- logtalk_compile(Files, Flags).</pre>
196	<p>
197	or:
198	</p>
199	<pre>\| ?- logtalk_load(Files, Flags).</pre>
200	<p>
201	In fact, the <code>logtalk_load/1</code> and <code>logtalk_compile/1</code> predicates are just shortcuts to the extended versions called with the default compiler flag values.
202	</p>
203	<p>
204	We may also change the default flag values from the ones loaded from the config file by using the <a title="Consult reference manual" href="../refman/builtins/set_logtalk_flag2.html"><code>set_logtalk_flag/2</code></a> built-in predicate. For example:
205	</p>
206	<pre>\| ?- set_logtalk_flag(xmldocs, off).</pre>
207	<p>
208	The current default flags values can be enumerated using the <a title="Consult reference manual" href="../refman/builtins/current_logtalk_flag2.html"><code>current_logtalk_flag/2</code></a> built-in predicate:
209	</p>
210	<pre>\| ?- current_logtalk_flag(xmldocs, Value).
211
212	Value = off
213	yes</pre>
214	<p>
215	Logtalk also implements a <a title="Consult reference manual" href="../refman/directives/set_logtalk_flag2.html"><code>set_logtalk_flag/2</code></a> directive, which can be used to set flags within a source file. For example, assuming a source file defining several entities, you may want to use different settings for compiling each entity. This can be easily accomplished by preceding each entity with the necessary <code>set_logtalk_flag/2</code> directives. Note that the scope of this directive is local to the source file containing it.
216	</p>
217
218	<h4>Lint flags</h4>
219
220	<dl>
221	<dt><code>unknown(Option)</code></dt>
222	<dd>Controls the unknown entity warnings, resulting from loading an entity that references some other entity that is not currently loaded. Possible option values are <code>warning</code> (the usual default) and <code>silent</code>. Note that these warnings are not always avoidable, specially when using reflective designs of class-based hierarchies.</dd>
223	</dl>
224	<dl>
225	<dt><code>misspelt(Option)</code></dt>
226	<dd>Controls the misspelt predicate call warnings. A misspelt call is a call to a predicate which is not defined in the object or category containing the call, is not declared as dynamic, and is not a Logtalk/Prolog built-in predicate. Possible option values are <code>error</code>, <code>warning</code> (the usual default), and <code>silent</code> (not recommended).</dd>
227	</dl>
228	<dl>
229	<dt><code>lgtredef(Option)</code></dt>
230	<dd>Controls the Logtalk built-in predicate redefinition warnings. Possible option values are <code>warning</code> (the usual default) and <code>silent</code>. These warnings are almost always programming errors.</dd>
231	</dl>
232	<dl>
233	<dt><code>plredef(Option)</code></dt>
234	<dd>Controls the Prolog built-in predicate redefinition warnings. Possible option values are <code>warning</code> (can be very verbose if your code redefines a lot of Prolog built-in predicates) and <code>silent</code> (the usual default). When running a Logtalk application on several Prolog compilers, is possible to get different sets of warnings due to different sets of built-in predicates implemented by each Prolog compiler.</dd>
235	</dl>
236	<dl>
237	<dt><code>portability(Option)</code></dt>
238	<dd>Controls the non-ISO specified built-in predicate and non-ISO specified built-in arithmetic function calls warnings. Possible option values are <code>warning</code> and <code>silent</code> (the usual default).</dd>
239	</dl>
240	<dl>
241	<dt><code>singletons(Option)</code></dt>
242	<dd>Controls the singleton variable warnings. Possible option values are <code>warning</code> (the usual default) and <code>silent</code> (not recommended).</dd>
243	</dl>
244	<dl>
245	<dt><code>underscore_variables(Option)</code></dt>
246	<dd>Controls the interpretation of variables that start with an underscore (excluding the anonymous variable) that occur once in a term as either don't care variables or singleton variables. Possible option values are <code>dont_care</code> and <code>singletons</code> (the usual default). Note that, depending on your Prolog compiler, the <code>read_term/3</code> built-in predicate may report variables that start with an underscore as singleton variables. There is no standard behavior, hence this option.</dd>
247	</dl>
248
249
250	<h4>Documenting flags</h4>
251
252	<dl>
253	<dt><code>xmldocs(Option)</code></dt>
254	<dd>Controls the automatic generation of documenting files in XML format. Possible option values are <code>on</code> (the usual default) and <code>off</code>.</dd>
255	</dl>
256	<dl>
257	<dt><code>xmldir(Directory)</code></dt>
258	<dd>Sets the directory to be used to store the automatically generated XML documenting files. The default value is <code>xml_docs</code>, a sub-directory of the source files directory. Use of this flag requires that the read-only flag <code>altdirs</code> be set to <code>on</code> (not supported in some back-end Prolog compilers).</dd>
259	</dl>
260	<dl>
261	<dt><code>xmlspec(Option)</code></dt>
262	<dd>Defines the XML documenting files specification format. Possible option values are <code>dtd</code> (for the DTD specification; the usual default) and <code>xsd</code> (for the XML Schema specification). Most XSL processors support DTDs but only some of them support XML Schemas.</dd>
263	</dl>
264	<dl>
265	<dt><code>xmlsref(Option)</code></dt>
266	<dd>Sets the reference to the XML specification file in the automatically generated XML documenting files. The default value is <code>local</code>, that is, the reference points to a local DTD or XSD file (respectively, <code>logtalk.dtd</code> or <code>logtalk.xsd</code>), residing in the same directory as the XML file. Other possible values are <code>web</code> (the reference points to an web location, either <code>http://logtalk.org/xml/1.3/logtalk.dtd</code> or <code>http://logtalk.org/xml/1.3/logtalk.xsd</code>), and <code>standalone</code> (no reference to specification files in the XML documenting files). The most appropriated option value depends on the XSL processor you intend to use. Some of them are buggy an may not work with the default option value.</dd>
267	</dl>
268	<dl>
269	<dt><code>xslfile(File)</code></dt>
270	<dd>Sets the XSLT file to be used with the automatically generated XML documenting files. The default value is <code>lgtxml.xsl</code>, which allows the XML files to be viewed by simply opening them with recent versions of web navigators which support XSLT transformations (after copying the <code>lgtxml.xsl</code> and of the <code>logtalk.css</code> files to the directory containing the XML files).</dd>
271	</dl>
272
273	<h4>Other flags</h4>
274
275	<dl>
276	<dt><code>report(Option)</code></dt>
277	<dd>Controls reporting of each compiled or loaded object, category, or protocol (including compilation and loading warnings). Possible option values are <code>on</code> (the usual default) and <code>off</code> (silent compilation and loading).</dd>
278	</dl>
279	<dl>
280	<dt><code>code_prefix(Option)</code></dt>
281	<dd>Enables the definition of prefix for all functors of Prolog code generated by the Logtalk compiler. The option value must be an atom; the default value is the empty atom (<code>''</code>). Specifying a code prefix provides a way to solve possible conflicts between Logtalk compiled code and other Prolog code. In addition, some Prolog compilers automatically hide predicates whose functor start with a specific prefix such as the character <code>$</code>.</dd>
282	</dl>
283	<dl>
284	<dt><code>debug(Option)</code></dt>
285	<dd>Controls the compilation of source files in debug mode (the Logtalk built-in debugger can only be used with files compiled in this mode). Possible option values are <code>on</code> and <code>off</code> (the usual default).</dd>
286	</dl>
287	<dl>
288	<dt><code>complements(Option)</code></dt>
289	<dd>Allows objects to be compiled with support for complementing categories turned off in order to improve performance and security. Possible option values are <code>on</code> and <code>off</code> (the usual default). This option can be used on a per-object basis. Note that changing this option is of no consequence for objects already compiled and loaded.</dd>
290	</dl>
291	<dl>
292	<dt><code>dynamic_declarations(Option)</code></dt>
293	<dd>Allows objects to be compiled with support for dynamic declaration of new predicates turned off in order to improve performance and security. Possible option values are <code>on</code> and <code>off</code> (the usual default). This option can be used on a per-object basis. Note that changing this option is of no consequence for objects already compiled and loaded.</dd>
294	</dl>
295	<dl>
296	<dt><code>events(Option)</code></dt>
297	<dd>Allows message sending calls to be compiled with event-driven programming support turned off in order to improve performance. Possible option values are <code>on</code> and <code>off</code> (the usual default). Objects (and categories) compiled with this option set to <code>off</code> use optimized code for message-sending calls that does not trigger events. As such, this option can be used on a per-object (or per-category) basis. Note that turning on this option is of no consequence for objects and categories already compiled and loaded.</dd>
298	</dl>
299	<dl>
300	<dt><code>reload(Option)</code></dt>
301	<dd>Defines the reloading behavior for source files. Possible option values are <code>skip</code> (skip loading of already loaded files) and <code>always</code> (always reload files; the usual default). This option must not be used when recompiling source files in debug mode (see <code>debug/1</code> option above).</dd>
302	</dl>
303	<dl>
304	<dt><code>smart_compilation(Option)</code></dt>
305	<dd>Controls the use of smart compilation of source files to avoid recompiling files that are unchanged since the last time they are compiled. Possible option values are <code>on</code> and <code>off</code> (the usual default). This option is only supported in some Prolog compilers. It must not be used when recompiling source files in debug mode (see <code>debug/1</code> option above).</dd>
306	</dl>
307	<dl>
308	<dt><code>hook(Object)</code></dt>
309	<dd>Allows the definition of compiler hooks that are called for each term read form a source file and for each compiled goal. This option specifies an object (which can be the pseudo-object <code>user</code>) implementing the <code>expanding</code> built-in protocol. The object is expected to define clauses for the <a title="Consult reference manual" href="../refman/methods/term_expansion2.html"><code>term_expansion/2</code></a> and <a title="Consult reference manual" href="../refman/methods/goal_expansion2.html"><code>goal_expansion/2</code></a> predicates. In the case of the <code>term_expansion/2</code> predicate, the first argument is the term read form the source file while the second argument returns a list of terms corresponding to the expansion of the first argument. In the case of the <code>goal_expansion/2</code> predicate, the second argument should be a goal resulting from the expansion of the goal in the first argument. The predicate <code>goal_expansion/2</code> is called on the expanded goals so care must be taken to avoid compilation loops.</dd>
310	</dl>
311	<dl>
312	<dt><code>tmpdir(Directory)</code></dt>
313	<dd>Sets the directory to be used to store the temporary files generated when compiling Logtalk source files. The default value is <code>lgt_tmp</code>, a sub-directory of the source files directory. Use of this flag requires that the read-only flag <code>altdirs</code> be set to <code>on</code> (not supported in some back-end Prolog compilers).</dd>
314	</dl>
315
316	<h3 id="programming_smart">Reloading and smart compilation of source files</h3>
317
318	<p>
319	As a general rule, reloading source files should never occur in production code and should be handled with care in development code. Reloading a Logtalk source file usually requires reloading the intermediate Prolog file that is generated by the Logtalk compiler. The problem is that there is no standard behavior for reloading Prolog files. For static predicates, almost all Prolog compilers replace the old definitions with the new ones. However, for dynamic predicates, the behavior depends on the Prolog compiler. Most compilers replace the old definitions but some of them simply append the new ones, which usually leads to trouble. See the compatibility notes for the back-end Prolog compiler you intend to use for more information. There is an additional potential problem when using multi-threading programming. Reloading a threaded object does not recreate from scratch its old message queue, which may still be in use (e.g. threads may be waiting on it).
320	</p>
321	<p>
322	When using library entities and stable code, you can avoid reloading the corresponding source files (and, therefore, recompiling them) by setting the compiler option <code>reload</code> to <code>skip</code>. For code under development, you can turn on smart compilation of source files to avoid recompiling files that have not been modified since last compilation (assuming that back-end Prolog compiler that you are using supports retrieving of file modification dates). Smart compilation of source files is usually off by default. You can enable it by changing the default flag value in the configuration file, by using the corresponding compiler flag with the compiling and loading built-in predicates, or, for the remaining of a working session, by using the call:
323	</p>
324	<pre>\| ?- set_logtalk_flag(smart_compilation, on).</pre>
325	<p>
326	Some caveats that you should be aware. First, some warnings that might be produced when compiling a source file will not show up if the corresponding object file is up-to-date because the source file is not being (re)compiled. Second, if you are using several Prolog compilers with Logtalk, be sure to perform the first compilation of your source files with smart compilation turned off: the intermediate Prolog files generated by the Logtalk compiler may be not compatible across Prolog compilers or even for the same Prolog compiler across operating systems (e.g. due to the use of different character encodings or end-of-line characters).
327	</p>
328
329	<h3 id="programming_batch">Using Logtalk for batch processing</h3>
330
331	<p>
332	If you use Logtalk for batch processing, you probably want to suppress most, if not all, banners, messages, and warnings that are normally printed by the system. To suppress printing of the Logtalk startup banner and default flags, set the option <code>startup_message</code> in the config file that you are using to <code>none</code>. To suppress printing of compiling and loading messages (including compiling warnings but not compiling error messages), turn off the option <code>report</code>.
333	</p>
334
335
336	<h2 id="programming_debugging">Debugging Logtalk programs</h2>
337
338	<p>
339	Logtalk defines a built-in pseudo-object named <code>debugger</code>, which implements debugging features similar to those found on most Prolog compilers. However, there are some differences between the usual implementation of Prolog debuggers and the current implementation of the Logtalk debugger that you should be aware. First, unlike some Prolog debuggers, the Logtalk debugger is not implemented as a meta-interpreter. This translates to a different, although similar, set of debugging features with some limitations when compared with some Prolog debuggers. Second, debugging is only possible for objects compiled in debug mode. When compiling an object in debug mode, Logtalk keeps each clause goal in both source form and compiled form in order to allow tracing of the goal execution. Third, implementation of spy points allows the user to specify the execution context for entering the debugger. This feature is a consequence of the encapsulation of predicates inside objects.
340	</p>
341
342	<h3 id="programming_debugmode">Compiling entities in debug mode</h3>
343
344	<p>
345	Compilation of source files in debug mode is controlled by the compiler flag <code>debug</code>. The default value for this flag, usually <code>off</code>, is defined in the config files. Its value may be changed at runtime by writing:
346	</p>
347	<pre>\| ?- set_logtalk_flag(debug, on).
348
349	yes</pre>
350	<p>
351	In alternative, if we want to compile only some entities in debug mode, we may instead write:
352	</p>
353	<pre>\| ?- logtalk_load([file1, file2, ...], [debug(on)]).</pre>
354	<p>
355	The compiler flag <code>smart_compilation</code> is automatically turned off whenever the debug flag is turned on at runtime. This is necessary because debug code would not be generated for files previously compiled in normal mode if there is no changes to the source files. However, note that you should be careful to not turn both flags on at the same time in a config file.
356	</p>
357	<p>We may check or enumerate, by backtracking, all loaded entities compiled in debug mode as follows:
358	</p>
359	<pre>\| ?- debugger::debugging(Entity).</pre>
360
361	<h3 id="programming_boxmodel">Logtalk Procedure Box model</h3>
362
363	<p>
364	Logtalk uses a <em>Procedure Box model</em> similar to those found on most Prolog compilers. The traditional Prolog procedure box model uses four ports (<em>call</em>, <em>exit</em>, <em>redo</em>, and <em>fail</em>) for describing control flow when a predicate clause is used during program execution:
365	</p>
366	<dl>
367	<dt><code>call</code></dt>
368	<dd>predicate call</dd>
369	<dt><code>exit</code></dt>
370	<dd>success of a predicate call</dd>
371	<dt><code>redo</code></dt>
372	<dd>backtracking into a predicate</dd>
373	<dt><code>fail</code></dt>
374	<dd>failure of a predicate call</dd>
375	</dl>
376	<p>
377	Logtalk, as found on some recent Prolog compilers, adds a port for dealing with exceptions thrown when calling a predicate:
378	</p>
379	<dl>
380	<dt><code>exception</code></dt>
381	<dd>predicate call throws an exception</dd>
382	</dl>
383	<p>
384	In addition to the ports described above, Logtalk adds two more ports, <em>fact</em> and <em>rule</em>, which show the result of the unification of a goal with, respectively, a fact and a rule head:
385	</p>
386	<dl>
387	<dt><code>fact</code></dt>
388	<dd>unification success between a goal and a fact</dd>
389	<dt><code>rule</code></dt>
390	<dd>unification success between a goal and a rule head</dd>
391	</dl>
392	<p>
393	For static predicates, the debugger prints the clause number at the unification ports: <code>Fact #N</code> or <code>Rule #N</code> indicates that clause <code>N</code> is being used for proving a goal.
394	</p>
395	<p>
396	The user may define for which ports the debugger should pause for user interaction by specifying a list of leashed ports. For example:
397	</p>
398	<pre>\| ?- debugger::leash([call, exit, fail]).</pre>
399	<p>
400	Alternatively, the user may use an atom abbreviation for a pre-defined set of ports. For example:
401	</p>
402	<pre>\| ?- debugger::leash(loose).</pre>
403	<p>
404	The abbreviations defined in Logtalk are similar to those defined on some Prolog compilers:
405	</p>
406	<dl>
407	<dt><code>none</code></dt>
408	<dd><code>[]</code></dd>
409	<dt><code>loose</code></dt>
410	<dd><code>[fact, rule, call]</code></dd>
411	<dt><code>half</code></dt>
412	<dd><code>[fact, rule, call, redo]</code></dd>
413	<dt><code>tight</code></dt>
414	<dd><code>[fact, rule, call, redo, fail, exception]</code></dd>
415	<dt><code>full</code></dt>
416	<dd><code>[fact, rule, call, exit, redo, fail, exception]</code></dd>
417	</dl>
418
419	<h3>Defining spy points<a id="programming_spypoints"></a></h3>
420
421	<p>
422	Logtalk spy points can be defined by simply stating which predicates should be spied, as in most Prolog debuggers, or by fully specifying the context for activating a spy point.
423	</p>
424
425	<h4>Defining predicate spy points<a id="programming_pspypoints"></a></h4>
426
427	<p>
428	Predicate spy points are specified using the method <code>spy/1</code>. The argument can be either a predicate indicator (<code>Functor/Arity</code>) or a list of predicate indicators. For example:
429	</p>
430	<pre>\| ?- debugger::spy(foo/2).
431
432	Spy points set.
433	yes
434
435	\| ?- debugger::spy([foo/4, bar/1]).
436
437	Spy points set.
438	yes</pre>
439	<p>
440	Predicate spy points can be removed by using the method <code>nospy/1</code>. The argument can be a predicate indicator, a list of predicate indicators, or a non-instantiated variable in which case all predicate spy points will be removed. For example:
441	</p>
442	<pre>\| ?- debugger::nospy(_).
443
444	All matching predicate spy points removed.
445	yes</pre>
446
447	<h4>Defining context spy points<a id="programming_cspypoints"></a></h4>
448
449	<p>
450	A context spy point is a term describing a message execution context and a goal:
451	</p>
452	<pre>(Sender, This, Self, Goal)</pre>
453	<p>
454	The debugger is evoked whenever the execution context is true and when the spy point goal unifies with the goal currently being executed. Variable bindings resulting from the unification between the current goal and the goal argument are discarded. The user may establish any number of context spy points as necessary. For example, in order to call the debugger whenever a predicate defined on an object named <code>foo</code> is called we may define the following spy point:
455	</p>
456	<pre>\| ?- debugger::spy(_, foo, _, _).
457
458	Spy point set.
459	yes</pre>
460	<p>
461	For example, we can spy all calls to a <code>foo/2</code> predicate by setting the condition:
462	</p>
463	<pre>\| ?- debugger::spy(_, _, _, foo(_, _)).
464
465	Spy point set.
466	yes</pre>
467	<p>
468	The method <code>nospy/4</code> may be used to remove all matching spy points. For example, the call:
469	</p>
470	<pre>\| ?- debugger::nospy(_, _, foo, _).
471
472	All matching context spy points removed.
473	yes</pre>
474	<p>
475	will remove all context spy points where the value of <em>Self</em> matches the name <code>foo</code>.
476	</p>
477
478	<h4>Removing all spy points<a id="programming_nospyall"></a></h4>
479
480	<p>
481	We may remove all predicate spy points and all context spy points by using the method <code>nospyall/0</code>:
482	</p>
483	<pre>\| ?- debugger::nospyall.
484
485	All predicate spy points removed.
486	All context spy points removed.
487	yes</pre>
488
489	<h3 id="programming_trace">Tracing program execution</h3>
490
491	<p>
492	Logtalk allows tracing of execution for all objects compiled in debug mode. To start the debugger in trace mode, write:
493	</p>
494	<pre>\| ?- debugger::trace.
495
496	yes</pre>
497	<p>
498	Note that, when tracing, spy points will be ignored. While tracing, the debugger will pause for user input at each leashed port, printing an informative message with the port name and the current goal. After the port name, the debugger prints the goal invocation number (except for the unification ports). This invocation number is unique and can be used to correlate the port trace messages.
499	</p>
500	<p>
501	To stop tracing and turning off the debugger, write:
502	</p>
503	<pre>\| ?- debugger::notrace.
504
505	yes</pre>
506
507
508	<h3 id="programming_debug">Debugging using spy points</h3>
509
510	<p>
511	Tracing a program execution may generate large amounts of debugging data. Debugging using spy points allows the user to concentrate its attention in specific points of its code. To start a debugging session using spy points, write:
512	</p>
513	<pre>\| ?- debugger::debug.
514
515	yes</pre>
516	<p>
517	At the beginning of a port description, the debugger will print a <code>+</code> or a <code>*</code> before the current goal if there is, respectively, a predicate spy point or a context spy point defined.
518	</p>
519	<p>
520	To stop the debugger, write:
521	</p>
522	<pre>\| ?- debugger::nodebug.
523
524	yes</pre>
525	<p>
526	Note that stopping the debugger does not remove any defined spy points.
527	</p>
528
529	<h3 id="programming_commands">Debugging commands</h3>
530
531	<p>
532	The debugger pauses at leashed posts when tracing or when finding a spy point for user interaction. The commands available are as follows:
533	</p>
534	<dl>
535	<dt><code>c</code> — creep</dt>
536	<dd>go on; you may use the spacebar, return, or enter keys in alternative</dd>
537	<dt><code>l</code> — leap</dt>
538	<dd>continues execution until the next spy point is found</dd>
539	<dt><code>s</code> — skip</dt>
540	<dd>skips debugging for the current goal; only meaningful at call and redo ports</dd>
541	<dt><code>i</code> — ignore</dt>
542	<dd>ignores goal, assumes that it succeeded; only valid at call and redo ports</dd>
543	<dt><code>f</code> — fail</dt>
544	<dd>forces backtracking; may also be used to convert an exception into a failure</dd>
545	<dt><code>n</code> — nodebug</dt>
546	<dd>turns off debugging</dd>
547	<dt><code>@</code> — command; <code>!</code> can be used in alternative</dt>
548	<dd>reads and executes a query</dd>
549	<dt><code>b</code> — break</dt>
550	<dd>suspends execution and starts new interpreter; type <code>end_of_file</code> to terminate</dd>
551	<dt><code>a</code> — abort</dt>
552	<dd>returns to top level interpreter</dd>
553	<dt><code>q</code> — quit</dt>
554	<dd>quits Logtalk</dd>
555	<dt><code>d</code> — display</dt>
556	<dd>writes current goal without using operator notation</dd>
557	<dt><code>x</code> — context</dt>
558	<dd>prints execution context</dd>
559	<dt><code>e</code> — exception</dt>
560	<dd>prints exception term thrown by the current goal</dd>
561	<dt><code>=</code> — debugging</dt>
562	<dd>prints debugging information</dd>
563	<dt><code>*</code> — add</dt>
564	<dd>adds a context spy point for the current goal</dd>
565	<dt><code>+</code> — add</dt>
566	<dd>adds a predicate spy point for the current goal</dd>
567	<dt><code>-</code> — remove</dt>
568	<dd>removes a predicate spy point for the current goal</dd>
569	<dt><code>h</code> — help</dt>
570	<dd>prints list of command options; <code>?</code> can be used in alternative</dd>
571	</dl>
572
573	<h3 id="programming_context">Context-switching calls</h3>
574
575	<p>
576	Logtalk provides a control construct, <a title="Consult reference manual" href="../refman/control/context2.html"><code><</2</code></a>, which allows the execution of a query within the context of an object. Common debugging uses include checking an object local predicates (e.g. predicates representing internal dynamic state) and sending a message from within an object. This control construct may also be used to write unit tests.
577	</p>
578	<p>
579	Consider the following toy example:
580	</p>
581	<pre>:- object(broken).
582
583	:- public(a/1).
584	:- private([b/2, c/1]).
585	:- dynamic(c/1).
586
587	a(A) :- b(A, B), c(B).
588	b(1, 2). b(2, 4). b(3, 6).
589	c(3). % in a real-life example, this would be a clause asserted at runtime
590
591	:- end_object.
592	</pre>
593	<p>
594	Something is wrong when we try the object public predicate, <code>a/1</code>:
595	</p>
596	<pre>\| ?- broken::a(A).
597
598	no</pre>
599	<p>
600	For helping diagnosing the problem, instead of compiling the object in debug mode and doing a <em>trace</em> of the query to check the clauses for the non-public predicates, we can instead simply type:
601	</p>
602	<pre>\| ?- broken << c(C).
603
604	C = 3
605	yes
606	</pre>
607	<p>
608	The <code><</2</code> control construct works by switching the execution context to the object in the first argument and then compiling and executing the second argument within that context:
609	</p>
610	<pre>\| ?- broken << (self(Self), sender(Sender), this(This)).
611
612	Self = broken
613	Sender = broken
614	This = broken
615
616	yes</pre>
617	<p>
618	As exemplified above, the <code>