annotate man/internals/internals.texi @ 771:943eaba38521

[xemacs-hg @ 2002-03-13 08:51:24 by ben] The big ben-mule-21-5 check-in! Various files were added and deleted. See CHANGES-ben-mule. There are still some test suite failures. No crashes, though. Many of the failures have to do with problems in the test suite itself rather than in the actual code. I'll be addressing these in the next day or so -- none of the test suite failures are at all critical. Meanwhile I'll be trying to address the biggest issues -- i.e. build or run failures, which will almost certainly happen on various platforms. All comments should be sent to ben@xemacs.org -- use a Cc: if necessary when sending to mailing lists. There will be pre- and post- tags, something like pre-ben-mule-21-5-merge-in, and post-ben-mule-21-5-merge-in.
author ben
date Wed, 13 Mar 2002 08:54:06 +0000
parents 33f0f28b945c
children 19dfb459d51a
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1 \input texinfo @c -*-texinfo-*-
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2 @c %**start of header
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3 @setfilename ../../info/internals.info
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4 @settitle XEmacs Internals Manual
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5 @c %**end of header
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7 @ifinfo
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8 @dircategory XEmacs Editor
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9 @direntry
440
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 438
diff changeset
10 * Internals: (internals). XEmacs Internals Manual.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
11 @end direntry
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
12
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
13 Copyright @copyright{} 1992 - 1996 Ben Wing.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
14 Copyright @copyright{} 1996, 1997 Sun Microsystems.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
15 Copyright @copyright{} 1994 - 1998 Free Software Foundation.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
16 Copyright @copyright{} 1994, 1995 Board of Trustees, University of Illinois.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
17
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
18
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
19 Permission is granted to make and distribute verbatim copies of this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
20 manual provided the copyright notice and this permission notice are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
21 preserved on all copies.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
22
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
23 @ignore
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
24 Permission is granted to process this file through TeX and print the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
25 results, provided the printed document carries copying permission notice
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
26 identical to this one except for the removal of this paragraph (this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
27 paragraph not being relevant to the printed manual).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
28
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
29 @end ignore
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
30 Permission is granted to copy and distribute modified versions of this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
31 manual under the conditions for verbatim copying, provided that the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
32 entire resulting derived work is distributed under the terms of a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
33 permission notice identical to this one.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
34
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
35 Permission is granted to copy and distribute translations of this manual
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
36 into another language, under the above conditions for modified versions,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
37 except that this permission notice may be stated in a translation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
38 approved by the Foundation.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
39
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
40 Permission is granted to copy and distribute modified versions of this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
41 manual under the conditions for verbatim copying, provided also that the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
42 section entitled ``GNU General Public License'' is included exactly as
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
43 in the original, and provided that the entire resulting derived work is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
44 distributed under the terms of a permission notice identical to this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
45 one.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
46
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
47 Permission is granted to copy and distribute translations of this manual
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
48 into another language, under the above conditions for modified versions,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
49 except that the section entitled ``GNU General Public License'' may be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
50 included in a translation approved by the Free Software Foundation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
51 instead of in the original English.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
52 @end ifinfo
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
53
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
54 @c Combine indices.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
55 @synindex cp fn
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
56 @syncodeindex vr fn
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
57 @syncodeindex ky fn
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
58 @syncodeindex pg fn
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
59 @syncodeindex tp fn
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
60
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
61 @setchapternewpage odd
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
62 @finalout
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
63
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
64 @titlepage
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
65 @title XEmacs Internals Manual
464
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
66 @subtitle Version 1.4, March 2001
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
67
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
68 @author Ben Wing
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
69 @author Martin Buchholz
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
70 @author Hrvoje Niksic
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
71 @author Matthias Neubauer
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
72 @author Olivier Galibert
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
73 @page
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
74 @vskip 0pt plus 1fill
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
75
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
76 @noindent
464
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
77 Copyright @copyright{} 1992 - 1996, 2001 Ben Wing. @*
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
78 Copyright @copyright{} 1996, 1997 Sun Microsystems, Inc. @*
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
79 Copyright @copyright{} 1994 - 1998 Free Software Foundation. @*
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
80 Copyright @copyright{} 1994, 1995 Board of Trustees, University of Illinois.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
81
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
82 @sp 2
464
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
83 Version 1.4 @*
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
84 March 2001.@*
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
85
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
86 Permission is granted to make and distribute verbatim copies of this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
87 manual provided the copyright notice and this permission notice are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
88 preserved on all copies.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
89
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
90 Permission is granted to copy and distribute modified versions of this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
91 manual under the conditions for verbatim copying, provided also that the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
92 section entitled ``GNU General Public License'' is included
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
93 exactly as in the original, and provided that the entire resulting
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
94 derived work is distributed under the terms of a permission notice
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
95 identical to this one.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
96
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
97 Permission is granted to copy and distribute translations of this manual
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
98 into another language, under the above conditions for modified versions,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
99 except that the section entitled ``GNU General Public License'' may be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
100 included in a translation approved by the Free Software Foundation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
101 instead of in the original English.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
102 @end titlepage
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
103 @page
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
104
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
105 @node Top, A History of Emacs, (dir), (dir)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
106
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
107 @ifinfo
464
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
108 This Info file contains v1.4 of the XEmacs Internals Manual, March 2001.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
109 @end ifinfo
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
110
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
111 @menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
112 * A History of Emacs:: Times, dates, important events.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
113 * XEmacs From the Outside:: A broad conceptual overview.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
114 * The Lisp Language:: An overview.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
115 * XEmacs From the Perspective of Building::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
116 * XEmacs From the Inside::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
117 * The XEmacs Object System (Abstractly Speaking)::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
118 * How Lisp Objects Are Represented in C::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
119 * Rules When Writing New C Code::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
120 * A Summary of the Various XEmacs Modules::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
121 * Allocation of Objects in XEmacs Lisp::
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
122 * Dumping::
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
123 * Events and the Event Loop::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
124 * Evaluation; Stack Frames; Bindings::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
125 * Symbols and Variables::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
126 * Buffers and Textual Representation::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
127 * MULE Character Sets and Encodings::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
128 * The Lisp Reader and Compiler::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
129 * Lstreams::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
130 * Consoles; Devices; Frames; Windows::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
131 * The Redisplay Mechanism::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
132 * Extents::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
133 * Faces::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
134 * Glyphs::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
135 * Specifiers::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
136 * Menus::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
137 * Subprocesses::
446
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
138 * Interface to the X Window System::
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
139 * Index::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
140
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
141 @detailmenu
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
142
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
143 --- The Detailed Node Listing ---
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
144
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
145 A History of Emacs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
146
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
147 * Through Version 18:: Unification prevails.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
148 * Lucid Emacs:: One version 19 Emacs.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
149 * GNU Emacs 19:: The other version 19 Emacs.
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
150 * GNU Emacs 20:: The other version 20 Emacs.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
151 * XEmacs:: The continuation of Lucid Emacs.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
152
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
153 Rules When Writing New C Code
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
154
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
155 * General Coding Rules::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
156 * Writing Lisp Primitives::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
157 * Adding Global Lisp Variables::
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
158 * Coding for Mule::
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
159 * Techniques for XEmacs Developers::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
160
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
161 Coding for Mule
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
162
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
163 * Character-Related Data Types::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
164 * Working With Character and Byte Positions::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
165 * Conversion to and from External Data::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
166 * General Guidelines for Writing Mule-Aware Code::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
167 * An Example of Mule-Aware Code::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
168
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
169 A Summary of the Various XEmacs Modules
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
170
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
171 * Low-Level Modules::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
172 * Basic Lisp Modules::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
173 * Modules for Standard Editing Operations::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
174 * Editor-Level Control Flow Modules::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
175 * Modules for the Basic Displayable Lisp Objects::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
176 * Modules for other Display-Related Lisp Objects::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
177 * Modules for the Redisplay Mechanism::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
178 * Modules for Interfacing with the File System::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
179 * Modules for Other Aspects of the Lisp Interpreter and Object System::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
180 * Modules for Interfacing with the Operating System::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
181 * Modules for Interfacing with X Windows::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
182 * Modules for Internationalization::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
183
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
184 Allocation of Objects in XEmacs Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
185
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
186 * Introduction to Allocation::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
187 * Garbage Collection::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
188 * GCPROing::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
189 * Garbage Collection - Step by Step::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
190 * Integers and Characters::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
191 * Allocation from Frob Blocks::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
192 * lrecords::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
193 * Low-level allocation::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
194 * Cons::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
195 * Vector::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
196 * Bit Vector::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
197 * Symbol::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
198 * Marker::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
199 * String::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
200 * Compiled Function::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
201
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
202 Garbage Collection - Step by Step
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
203
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
204 * Invocation::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
205 * garbage_collect_1::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
206 * mark_object::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
207 * gc_sweep::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
208 * sweep_lcrecords_1::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
209 * compact_string_chars::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
210 * sweep_strings::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
211 * sweep_bit_vectors_1::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
212
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
213 Dumping
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
214
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
215 * Overview::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
216 * Data descriptions::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
217 * Dumping phase::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
218 * Reloading phase::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
219
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
220 Dumping phase
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
221
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
222 * Object inventory::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
223 * Address allocation::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
224 * The header::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
225 * Data dumping::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
226 * Pointers dumping::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
227
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
228 Events and the Event Loop
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
229
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
230 * Introduction to Events::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
231 * Main Loop::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
232 * Specifics of the Event Gathering Mechanism::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
233 * Specifics About the Emacs Event::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
234 * The Event Stream Callback Routines::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
235 * Other Event Loop Functions::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
236 * Converting Events::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
237 * Dispatching Events; The Command Builder::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
238
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
239 Evaluation; Stack Frames; Bindings
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
240
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
241 * Evaluation::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
242 * Dynamic Binding; The specbinding Stack; Unwind-Protects::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
243 * Simple Special Forms::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
244 * Catch and Throw::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
245
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
246 Symbols and Variables
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
247
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
248 * Introduction to Symbols::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
249 * Obarrays::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
250 * Symbol Values::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
251
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
252 Buffers and Textual Representation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
253
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
254 * Introduction to Buffers:: A buffer holds a block of text such as a file.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
255 * The Text in a Buffer:: Representation of the text in a buffer.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
256 * Buffer Lists:: Keeping track of all buffers.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
257 * Markers and Extents:: Tagging locations within a buffer.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
258 * Bufbytes and Emchars:: Representation of individual characters.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
259 * The Buffer Object:: The Lisp object corresponding to a buffer.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
260
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
261 MULE Character Sets and Encodings
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
262
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
263 * Character Sets::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
264 * Encodings::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
265 * Internal Mule Encodings::
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
266 * CCL::
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
267
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
268 Encodings
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
269
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
270 * Japanese EUC (Extended Unix Code)::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
271 * JIS7::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
272
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
273 Internal Mule Encodings
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
274
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
275 * Internal String Encoding::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
276 * Internal Character Encoding::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
277
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
278 Lstreams
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
279
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
280 * Creating an Lstream:: Creating an lstream object.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
281 * Lstream Types:: Different sorts of things that are streamed.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
282 * Lstream Functions:: Functions for working with lstreams.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
283 * Lstream Methods:: Creating new lstream types.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
284
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
285 Consoles; Devices; Frames; Windows
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
286
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
287 * Introduction to Consoles; Devices; Frames; Windows::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
288 * Point::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
289 * Window Hierarchy::
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
290 * The Window Object::
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
291
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
292 The Redisplay Mechanism
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
293
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
294 * Critical Redisplay Sections::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
295 * Line Start Cache::
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
296 * Redisplay Piece by Piece::
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
297
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
298 Extents
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
299
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
300 * Introduction to Extents:: Extents are ranges over text, with properties.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
301 * Extent Ordering:: How extents are ordered internally.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
302 * Format of the Extent Info:: The extent information in a buffer or string.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
303 * Zero-Length Extents:: A weird special case.
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
304 * Mathematics of Extent Ordering:: A rigorous foundation.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
305 * Extent Fragments:: Cached information useful for redisplay.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
306
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
307 @end detailmenu
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
308 @end menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
309
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
310 @node A History of Emacs, XEmacs From the Outside, Top, Top
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
311 @chapter A History of Emacs
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
312 @cindex history of Emacs, a
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
313 @cindex Emacs, a history of
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
314 @cindex Hackers (Steven Levy)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
315 @cindex Levy, Steven
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
316 @cindex ITS (Incompatible Timesharing System)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
317 @cindex Stallman, Richard
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
318 @cindex RMS
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
319 @cindex MIT
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
320 @cindex TECO
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
321 @cindex FSF
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
322 @cindex Free Software Foundation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
323
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
324 XEmacs is a powerful, customizable text editor and development
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
325 environment. It began as Lucid Emacs, which was in turn derived from
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
326 GNU Emacs, a program written by Richard Stallman of the Free Software
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
327 Foundation. GNU Emacs dates back to the 1970's, and was modelled
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
328 after a package called ``Emacs'', written in 1976, that was a set of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
329 macros on top of TECO, an old, old text editor written at MIT on the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
330 DEC PDP 10 under one of the earliest time-sharing operating systems,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
331 ITS (Incompatible Timesharing System). (ITS dates back well before
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
332 Unix.) ITS, TECO, and Emacs were products of a group of people at MIT
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
333 who called themselves ``hackers'', who shared an idealistic belief
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
334 system about the free exchange of information and were fanatical in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
335 their devotion to and time spent with computers. (The hacker
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
336 subculture dates back to the late 1950's at MIT and is described in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
337 detail in Steven Levy's book @cite{Hackers}. This book also includes
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
338 a lot of information about Stallman himself and the development of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
339 Lisp, a programming language developed at MIT that underlies Emacs.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
340
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
341 @menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
342 * Through Version 18:: Unification prevails.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
343 * Lucid Emacs:: One version 19 Emacs.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
344 * GNU Emacs 19:: The other version 19 Emacs.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
345 * GNU Emacs 20:: The other version 20 Emacs.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
346 * XEmacs:: The continuation of Lucid Emacs.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
347 @end menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
348
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
349 @node Through Version 18
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
350 @section Through Version 18
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
351 @cindex version 18, through
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
352 @cindex Gosling, James
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
353 @cindex Great Usenet Renaming
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
354
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
355 Although the history of the early versions of GNU Emacs is unclear,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
356 the history is well-known from the middle of 1985. A time line is:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
357
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
358 @itemize @bullet
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
359 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
360 GNU Emacs version 15 (15.34) was released sometime in 1984 or 1985 and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
361 shared some code with a version of Emacs written by James Gosling (the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
362 same James Gosling who later created the Java language).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
363 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
364 GNU Emacs version 16 (first released version was 16.56) was released on
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
365 July 15, 1985. All Gosling code was removed due to potential copyright
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
366 problems with the code.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
367 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
368 version 16.57: released on September 16, 1985.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
369 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
370 versions 16.58, 16.59: released on September 17, 1985.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
371 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
372 version 16.60: released on September 19, 1985. These later version 16's
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
373 incorporated patches from the net, esp. for getting Emacs to work under
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
374 System V.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
375 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
376 version 17.36 (first official v17 release) released on December 20,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
377 1985. Included a TeX-able user manual. First official unpatched
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
378 version that worked on vanilla System V machines.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
379 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
380 version 17.43 (second official v17 release) released on January 25,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
381 1986.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
382 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
383 version 17.45 released on January 30, 1986.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
384 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
385 version 17.46 released on February 4, 1986.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
386 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
387 version 17.48 released on February 10, 1986.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
388 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
389 version 17.49 released on February 12, 1986.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
390 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
391 version 17.55 released on March 18, 1986.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
392 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
393 version 17.57 released on March 27, 1986.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
394 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
395 version 17.58 released on April 4, 1986.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
396 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
397 version 17.61 released on April 12, 1986.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
398 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
399 version 17.63 released on May 7, 1986.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
400 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
401 version 17.64 released on May 12, 1986.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
402 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
403 version 18.24 (a beta version) released on October 2, 1986.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
404 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
405 version 18.30 (a beta version) released on November 15, 1986.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
406 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
407 version 18.31 (a beta version) released on November 23, 1986.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
408 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
409 version 18.32 (a beta version) released on December 7, 1986.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
410 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
411 version 18.33 (a beta version) released on December 12, 1986.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
412 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
413 version 18.35 (a beta version) released on January 5, 1987.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
414 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
415 version 18.36 (a beta version) released on January 21, 1987.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
416 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
417 January 27, 1987: The Great Usenet Renaming. net.emacs is now
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
418 comp.emacs.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
419 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
420 version 18.37 (a beta version) released on February 12, 1987.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
421 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
422 version 18.38 (a beta version) released on March 3, 1987.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
423 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
424 version 18.39 (a beta version) released on March 14, 1987.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
425 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
426 version 18.40 (a beta version) released on March 18, 1987.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
427 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
428 version 18.41 (the first ``official'' release) released on March 22,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
429 1987.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
430 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
431 version 18.45 released on June 2, 1987.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
432 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
433 version 18.46 released on June 9, 1987.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
434 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
435 version 18.47 released on June 18, 1987.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
436 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
437 version 18.48 released on September 3, 1987.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
438 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
439 version 18.49 released on September 18, 1987.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
440 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
441 version 18.50 released on February 13, 1988.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
442 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
443 version 18.51 released on May 7, 1988.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
444 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
445 version 18.52 released on September 1, 1988.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
446 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
447 version 18.53 released on February 24, 1989.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
448 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
449 version 18.54 released on April 26, 1989.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
450 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
451 version 18.55 released on August 23, 1989. This is the earliest version
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
452 that is still available by FTP.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
453 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
454 version 18.56 released on January 17, 1991.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
455 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
456 version 18.57 released late January, 1991.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
457 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
458 version 18.58 released ?????.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
459 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
460 version 18.59 released October 31, 1992.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
461 @end itemize
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
462
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
463 @node Lucid Emacs
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
464 @section Lucid Emacs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
465 @cindex Lucid Emacs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
466 @cindex Lucid Inc.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
467 @cindex Energize
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
468 @cindex Epoch
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
469
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
470 Lucid Emacs was developed by the (now-defunct) Lucid Inc., a maker of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
471 C++ and Lisp development environments. It began when Lucid decided they
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
472 wanted to use Emacs as the editor and cornerstone of their C++
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
473 development environment (called ``Energize''). They needed many features
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
474 that were not available in the existing version of GNU Emacs (version
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
475 18.5something), in particular good and integrated support for GUI
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
476 elements such as mouse support, multiple fonts, multiple window-system
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
477 windows, etc. A branch of GNU Emacs called Epoch, written at the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
478 University of Illinois, existed that supplied many of these features;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
479 however, Lucid needed more than what existed in Epoch. At the time, the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
480 Free Software Foundation was working on version 19 of Emacs (this was
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
481 sometime around 1991), which was planned to have similar features, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
482 so Lucid decided to work with the Free Software Foundation. Their plan
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
483 was to add features that they needed, and coordinate with the FSF so
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
484 that the features would get included back into Emacs version 19.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
485
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
486 Delays in the release of version 19 occurred, however (resulting in it
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
487 finally being released more than a year after what was initially
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
488 planned), and Lucid encountered unexpected technical resistance in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
489 getting their changes merged back into version 19, so they decided to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
490 release their own version of Emacs, which became Lucid Emacs 19.0.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
491
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
492 @cindex Zawinski, Jamie
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
493 @cindex Sexton, Harlan
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
494 @cindex Benson, Eric
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
495 @cindex Devin, Matthieu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
496 The initial authors of Lucid Emacs were Matthieu Devin, Harlan Sexton,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
497 and Eric Benson, and the work was later taken over by Jamie Zawinski,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
498 who became ``Mr. Lucid Emacs'' for many releases.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
499
464
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
500 A time line for Lucid Emacs is
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
501
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
502 @itemize @bullet
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
503 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
504 version 19.0 shipped with Energize 1.0, April 1992.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
505 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
506 version 19.1 released June 4, 1992.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
507 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
508 version 19.2 released June 19, 1992.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
509 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
510 version 19.3 released September 9, 1992.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
511 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
512 version 19.4 released January 21, 1993.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
513 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
514 version 19.5 was a repackaging of 19.4 with a few bug fixes and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
515 shipped with Energize 2.0. Never released to the net.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
516 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
517 version 19.6 released April 9, 1993.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
518 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
519 version 19.7 was a repackaging of 19.6 with a few bug fixes and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
520 shipped with Energize 2.1. Never released to the net.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
521 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
522 version 19.8 released September 6, 1993.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
523 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
524 version 19.9 released January 12, 1994.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
525 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
526 version 19.10 released May 27, 1994.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
527 @end itemize
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
528
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
529 @node GNU Emacs 19
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
530 @section GNU Emacs 19
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
531 @cindex GNU Emacs 19
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
532 @cindex Emacs 19, GNU
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
533 @cindex version 19, GNU Emacs
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
534 @cindex FSF Emacs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
535
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
536 About a year after the initial release of Lucid Emacs, the FSF
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
537 released a beta of their version of Emacs 19 (referred to here as ``GNU
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
538 Emacs''). By this time, the current version of Lucid Emacs was
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
539 19.6. (Strangely, the first released beta from the FSF was GNU Emacs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
540 19.7.) A time line for GNU Emacs version 19 is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
541
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
542 @itemize @bullet
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
543 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
544 version 19.8 (beta) released May 27, 1993.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
545 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
546 version 19.9 (beta) released May 27, 1993.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
547 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
548 version 19.10 (beta) released May 30, 1993.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
549 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
550 version 19.11 (beta) released June 1, 1993.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
551 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
552 version 19.12 (beta) released June 2, 1993.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
553 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
554 version 19.13 (beta) released June 8, 1993.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
555 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
556 version 19.14 (beta) released June 17, 1993.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
557 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
558 version 19.15 (beta) released June 19, 1993.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
559 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
560 version 19.16 (beta) released July 6, 1993.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
561 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
562 version 19.17 (beta) released late July, 1993.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
563 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
564 version 19.18 (beta) released August 9, 1993.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
565 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
566 version 19.19 (beta) released August 15, 1993.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
567 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
568 version 19.20 (beta) released November 17, 1993.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
569 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
570 version 19.21 (beta) released November 17, 1993.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
571 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
572 version 19.22 (beta) released November 28, 1993.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
573 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
574 version 19.23 (beta) released May 17, 1994.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
575 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
576 version 19.24 (beta) released May 16, 1994.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
577 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
578 version 19.25 (beta) released June 3, 1994.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
579 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
580 version 19.26 (beta) released September 11, 1994.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
581 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
582 version 19.27 (beta) released September 14, 1994.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
583 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
584 version 19.28 (first ``official'' release) released November 1, 1994.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
585 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
586 version 19.29 released June 21, 1995.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
587 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
588 version 19.30 released November 24, 1995.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
589 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
590 version 19.31 released May 25, 1996.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
591 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
592 version 19.32 released July 31, 1996.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
593 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
594 version 19.33 released August 11, 1996.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
595 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
596 version 19.34 released August 21, 1996.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
597 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
598 version 19.34b released September 6, 1996.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
599 @end itemize
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
600
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
601 @cindex Mlynarik, Richard
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
602 In some ways, GNU Emacs 19 was better than Lucid Emacs; in some ways,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
603 worse. Lucid soon began incorporating features from GNU Emacs 19 into
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
604 Lucid Emacs; the work was mostly done by Richard Mlynarik, who had been
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
605 working on and using GNU Emacs for a long time (back as far as version
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
606 16 or 17).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
607
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
608 @node GNU Emacs 20
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
609 @section GNU Emacs 20
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
610 @cindex GNU Emacs 20
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
611 @cindex Emacs 20, GNU
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
612 @cindex version 20, GNU Emacs
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
613 @cindex FSF Emacs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
614
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
615 On February 2, 1997 work began on GNU Emacs to integrate Mule. The first
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
616 release was made in September of that year.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
617
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
618 A timeline for Emacs 20 is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
619
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
620 @itemize @bullet
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
621 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
622 version 20.1 released September 17, 1997.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
623 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
624 version 20.2 released September 20, 1997.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
625 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
626 version 20.3 released August 19, 1998.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
627 @end itemize
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
628
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
629 @node XEmacs
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
630 @section XEmacs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
631 @cindex XEmacs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
632
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
633 @cindex Sun Microsystems
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
634 @cindex University of Illinois
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
635 @cindex Illinois, University of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
636 @cindex SPARCWorks
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
637 @cindex Andreessen, Marc
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
638 @cindex Baur, Steve
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
639 @cindex Buchholz, Martin
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
640 @cindex Kaplan, Simon
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
641 @cindex Wing, Ben
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
642 @cindex Thompson, Chuck
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
643 @cindex Win-Emacs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
644 @cindex Epoch
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
645 @cindex Amdahl Corporation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
646 Around the time that Lucid was developing Energize, Sun Microsystems
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
647 was developing their own development environment (called ``SPARCWorks'')
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
648 and also decided to use Emacs. They joined forces with the Epoch team
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
649 at the University of Illinois and later with Lucid. The maintainer of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
650 the last-released version of Epoch was Marc Andreessen, but he dropped
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
651 out and the Epoch project, headed by Simon Kaplan, lured Chuck Thompson
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
652 away from a system administration job to become the primary Lucid Emacs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
653 author for Epoch and Sun. Chuck's area of specialty became the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
654 redisplay engine (he replaced the old Lucid Emacs redisplay engine with
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
655 a ported version from Epoch and then later rewrote it from scratch).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
656 Sun also hired Ben Wing (the author of Win-Emacs, a port of Lucid Emacs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
657 to Microsoft Windows 3.1) in 1993, for what was initially a one-month
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
658 contract to fix some event problems but later became a many-year
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
659 involvement, punctuated by a six-month contract with Amdahl Corporation.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
660
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
661 @cindex rename to XEmacs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
662 In 1994, Sun and Lucid agreed to rename Lucid Emacs to XEmacs (a name
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
663 not favorable to either company); the first release called XEmacs was
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
664 version 19.11. In June 1994, Lucid folded and Jamie quit to work for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
665 the newly formed Mosaic Communications Corp., later Netscape
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
666 Communications Corp. (co-founded by the same Marc Andreessen, who had
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
667 quit his Epoch job to work on a graphical browser for the World Wide
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
668 Web). Chuck then become the primary maintainer of XEmacs, and put out
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
669 versions 19.11 through 19.14 in conjunction with Ben. For 19.12 and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
670 19.13, Chuck added the new redisplay and many other display improvements
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
671 and Ben added MULE support (support for Asian and other languages) and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
672 redesigned most of the internal Lisp subsystems to better support the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
673 MULE work and the various other features being added to XEmacs. After
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
674 19.14 Chuck retired as primary maintainer and Steve Baur stepped in.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
675
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
676 @cindex MULE merged XEmacs appears
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
677 Soon after 19.13 was released, work began in earnest on the MULE
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
678 internationalization code and the source tree was divided into two
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
679 development paths. The MULE version was initially called 19.20, but was
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
680 soon renamed to 20.0. In 1996 Martin Buchholz of Sun Microsystems took
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
681 over the care and feeding of it and worked on it in parallel with the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
682 19.14 development that was occurring at the same time. After much work
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
683 by Martin, it was decided to release 20.0 ahead of 19.15 in February
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
684 1997. The source tree remained divided until 20.2 when the version 19
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
685 source was finally retired at version 19.16.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
686
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
687 @cindex Baur, Steve
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
688 @cindex Buchholz, Martin
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
689 @cindex Jones, Kyle
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
690 @cindex Niksic, Hrvoje
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
691 @cindex XEmacs goes it alone
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
692 In 1997, Sun finally dropped all pretense of support for XEmacs and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
693 Martin Buchholz left the company in November. Since then, and mostly
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
694 for the previous year, because Steve Baur was never paid to work on
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
695 XEmacs, XEmacs has existed solely on the contributions of volunteers
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
696 from the Free Software Community. Starting from 1997, Hrvoje Niksic and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
697 Kyle Jones have figured prominently in XEmacs development.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
698
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
699 @cindex merging attempts
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
700 Many attempts have been made to merge XEmacs and GNU Emacs, but they
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
701 have consistently failed.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
702
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
703 A more detailed history is contained in the XEmacs About page.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
704
464
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
705 A time line for XEmacs is
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
706
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
707 @itemize @bullet
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
708 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
709 version 19.11 (first XEmacs) released September 13, 1994.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
710 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
711 version 19.12 released June 23, 1995.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
712 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
713 version 19.13 released September 1, 1995.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
714 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
715 version 19.14 released June 23, 1996.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
716 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
717 version 20.0 released February 9, 1997.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
718 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
719 version 19.15 released March 28, 1997.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
720 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
721 version 20.1 (not released to the net) April 15, 1997.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
722 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
723 version 20.2 released May 16, 1997.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
724 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
725 version 19.16 released October 31, 1997.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
726 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
727 version 20.3 (the first stable version of XEmacs 20.x) released November 30,
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
728 1997.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
729 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
730 version 20.4 released February 28, 1998.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
731 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
732 version 21.0.60 released December 10, 1998. (The version naming scheme was
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
733 changed at this point: [a] the second version number is odd for stable
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
734 versions, even for beta versions; [b] a third version number is added,
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
735 replacing the "beta xxx" ending for beta versions and allowing for
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
736 periodic maintenance releases for stable versions. Therefore, 21.0 was
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
737 never "officially" released; similarly for 21.2, etc.)
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
738 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
739 version 21.0.61 released January 4, 1999.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
740 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
741 version 21.0.63 released February 3, 1999.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
742 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
743 version 21.0.64 released March 1, 1999.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
744 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
745 version 21.0.65 released March 5, 1999.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
746 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
747 version 21.0.66 released March 12, 1999.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
748 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
749 version 21.0.67 released March 25, 1999.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
750 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
751 version 21.1.2 released May 14, 1999. (This is the followup to 21.0.67.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
752 The second version number was bumped to indicate the beginning of the
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
753 "stable" series.)
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
754 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
755 version 21.1.3 released June 26, 1999.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
756 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
757 version 21.1.4 released July 8, 1999.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
758 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
759 version 21.1.6 released August 14, 1999. (There was no 21.1.5.)
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
760 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
761 version 21.1.7 released September 26, 1999.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
762 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
763 version 21.1.8 released November 2, 1999.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
764 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
765 version 21.1.9 released February 13, 2000.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
766 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
767 version 21.1.10 released May 7, 2000.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
768 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
769 version 21.1.10a released June 24, 2000.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
770 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
771 version 21.1.11 released July 18, 2000.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
772 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
773 version 21.1.12 released August 5, 2000.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
774 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
775 version 21.1.13 released January 7, 2001.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
776 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
777 version 21.1.14 released January 27, 2001.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
778 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
779 version 21.2.9 released February 3, 1999.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
780 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
781 version 21.2.10 released February 5, 1999.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
782 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
783 version 21.2.11 released March 1, 1999.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
784 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
785 version 21.2.12 released March 5, 1999.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
786 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
787 version 21.2.13 released March 12, 1999.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
788 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
789 version 21.2.14 released May 14, 1999.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
790 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
791 version 21.2.15 released June 4, 1999.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
792 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
793 version 21.2.16 released June 11, 1999.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
794 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
795 version 21.2.17 released June 22, 1999.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
796 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
797 version 21.2.18 released July 14, 1999.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
798 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
799 version 21.2.19 released July 30, 1999.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
800 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
801 version 21.2.20 released November 10, 1999.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
802 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
803 version 21.2.21 released November 28, 1999.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
804 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
805 version 21.2.22 released November 29, 1999.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
806 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
807 version 21.2.23 released December 7, 1999.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
808 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
809 version 21.2.24 released December 14, 1999.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
810 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
811 version 21.2.25 released December 24, 1999.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
812 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
813 version 21.2.26 released December 31, 1999.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
814 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
815 version 21.2.27 released January 18, 2000.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
816 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
817 version 21.2.28 released February 7, 2000.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
818 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
819 version 21.2.29 released February 16, 2000.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
820 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
821 version 21.2.30 released February 21, 2000.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
822 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
823 version 21.2.31 released February 23, 2000.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
824 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
825 version 21.2.32 released March 20, 2000.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
826 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
827 version 21.2.33 released May 1, 2000.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
828 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
829 version 21.2.34 released May 28, 2000.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
830 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
831 version 21.2.35 released July 19, 2000.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
832 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
833 version 21.2.36 released October 4, 2000.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
834 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
835 version 21.2.37 released November 14, 2000.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
836 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
837 version 21.2.38 released December 5, 2000.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
838 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
839 version 21.2.39 released December 31, 2000.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
840 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
841 version 21.2.40 released January 8, 2001.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
842 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
843 version 21.2.41 released January 17, 2001.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
844 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
845 version 21.2.42 released January 20, 2001.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
846 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
847 version 21.2.43 released January 26, 2001.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
848 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
849 version 21.2.44 released February 8, 2001.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
850 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
851 version 21.2.45 released February 23, 2001.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
852 @item
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
853 version 21.2.46 released March 21, 2001.
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
854 @end itemize
5aa1854ad537 Import from CVS: tag r21-2-47
cvs
parents: 462
diff changeset
855
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
856 @node XEmacs From the Outside, The Lisp Language, A History of Emacs, Top
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
857 @chapter XEmacs From the Outside
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
858 @cindex XEmacs from the outside
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
859 @cindex outside, XEmacs from the
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
860 @cindex read-eval-print
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
861
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
862 XEmacs appears to the outside world as an editor, but it is really a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
863 Lisp environment. At its heart is a Lisp interpreter; it also
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
864 ``happens'' to contain many specialized object types (e.g. buffers,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
865 windows, frames, events) that are useful for implementing an editor.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
866 Some of these objects (in particular windows and frames) have
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
867 displayable representations, and XEmacs provides a function
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
868 @code{redisplay()} that ensures that the display of all such objects
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
869 matches their internal state. Most of the time, a standard Lisp
440
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 438
diff changeset
870 environment is in a @dfn{read-eval-print} loop---i.e. ``read some Lisp
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
871 code, execute it, and print the results''. XEmacs has a similar loop:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
872
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
873 @itemize @bullet
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
874 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
875 read an event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
876 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
877 dispatch the event (i.e. ``do it'')
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
878 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
879 redisplay
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
880 @end itemize
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
881
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
882 Reading an event is done using the Lisp function @code{next-event},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
883 which waits for something to happen (typically, the user presses a key
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
884 or moves the mouse) and returns an event object describing this.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
885 Dispatching an event is done using the Lisp function
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
886 @code{dispatch-event}, which looks up the event in a keymap object (a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
887 particular kind of object that associates an event with a Lisp function)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
888 and calls that function. The function ``does'' what the user has
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
889 requested by changing the state of particular frame objects, buffer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
890 objects, etc. Finally, @code{redisplay()} is called, which updates the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
891 display to reflect those changes just made. Thus is an ``editor'' born.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
892
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
893 @cindex bridge, playing
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
894 @cindex taxes, doing
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
895 @cindex pi, calculating
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
896 Note that you do not have to use XEmacs as an editor; you could just
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
897 as well make it do your taxes, compute pi, play bridge, etc. You'd just
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
898 have to write functions to do those operations in Lisp.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
899
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
900 @node The Lisp Language, XEmacs From the Perspective of Building, XEmacs From the Outside, Top
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
901 @chapter The Lisp Language
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
902 @cindex Lisp language, the
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
903 @cindex Lisp vs. C
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
904 @cindex C vs. Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
905 @cindex Lisp vs. Java
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
906 @cindex Java vs. Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
907 @cindex dynamic scoping
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
908 @cindex scoping, dynamic
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
909 @cindex dynamic types
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
910 @cindex types, dynamic
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
911 @cindex Java
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
912 @cindex Common Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
913 @cindex Gosling, James
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
914
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
915 Lisp is a general-purpose language that is higher-level than C and in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
916 many ways more powerful than C. Powerful dialects of Lisp such as
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
917 Common Lisp are probably much better languages for writing very large
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
918 applications than is C. (Unfortunately, for many non-technical
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
919 reasons C and its successor C++ have become the dominant languages for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
920 application development. These languages are both inadequate for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
921 extremely large applications, which is evidenced by the fact that newer,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
922 larger programs are becoming ever harder to write and are requiring ever
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
923 more programmers despite great increases in C development environments;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
924 and by the fact that, although hardware speeds and reliability have been
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
925 growing at an exponential rate, most software is still generally
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
926 considered to be slow and buggy.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
927
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
928 The new Java language holds promise as a better general-purpose
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
929 development language than C. Java has many features in common with
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
930 Lisp that are not shared by C (this is not a coincidence, since
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
931 Java was designed by James Gosling, a former Lisp hacker). This
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
932 will be discussed more later.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
933
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
934 For those used to C, here is a summary of the basic differences between
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
935 C and Lisp:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
936
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
937 @enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
938 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
939 Lisp has an extremely regular syntax. Every function, expression,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
940 and control statement is written in the form
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
941
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
942 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
943 (@var{func} @var{arg1} @var{arg2} ...)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
944 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
945
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
946 This is as opposed to C, which writes functions as
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
947
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
948 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
949 func(@var{arg1}, @var{arg2}, ...)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
950 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
951
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
952 but writes expressions involving operators as (e.g.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
953
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
954 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
955 @var{arg1} + @var{arg2}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
956 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
957
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
958 and writes control statements as (e.g.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
959
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
960 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
961 while (@var{expr}) @{ @var{statement1}; @var{statement2}; ... @}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
962 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
963
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
964 Lisp equivalents of the latter two would be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
965
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
966 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
967 (+ @var{arg1} @var{arg2} ...)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
968 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
969
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
970 and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
971
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
972 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
973 (while @var{expr} @var{statement1} @var{statement2} ...)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
974 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
975
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
976 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
977 Lisp is a safe language. Assuming there are no bugs in the Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
978 interpreter/compiler, it is impossible to write a program that ``core
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
979 dumps'' or otherwise causes the machine to execute an illegal
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
980 instruction. This is very different from C, where perhaps the most
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
981 common outcome of a bug is exactly such a crash. A corollary of this is that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
982 the C operation of casting a pointer is impossible (and unnecessary) in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
983 Lisp, and that it is impossible to access memory outside the bounds of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
984 an array.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
985
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
986 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
987 Programs and data are written in the same form. The
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
988 parenthesis-enclosing form described above for statements is the same
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
989 form used for the most common data type in Lisp, the list. Thus, it is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
990 possible to represent any Lisp program using Lisp data types, and for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
991 one program to construct Lisp statements and then dynamically
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
992 @dfn{evaluate} them, or cause them to execute.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
993
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
994 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
995 All objects are @dfn{dynamically typed}. This means that part of every
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
996 object is an indication of what type it is. A Lisp program can
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
997 manipulate an object without knowing what type it is, and can query an
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
998 object to determine its type. This means that, correspondingly,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
999 variables and function parameters can hold objects of any type and are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1000 not normally declared as being of any particular type. This is opposed
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1001 to the @dfn{static typing} of C, where variables can hold exactly one
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1002 type of object and must be declared as such, and objects do not contain
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1003 an indication of their type because it's implicit in the variables they
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1004 are stored in. It is possible in C to have a variable hold different
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1005 types of objects (e.g. through the use of @code{void *} pointers or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1006 variable-argument functions), but the type information must then be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1007 passed explicitly in some other fashion, leading to additional program
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1008 complexity.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1009
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1010 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1011 Allocated memory is automatically reclaimed when it is no longer in use.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1012 This operation is called @dfn{garbage collection} and involves looking
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1013 through all variables to see what memory is being pointed to, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1014 reclaiming any memory that is not pointed to and is thus
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1015 ``inaccessible'' and out of use. This is as opposed to C, in which
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1016 allocated memory must be explicitly reclaimed using @code{free()}. If
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1017 you simply drop all pointers to memory without freeing it, it becomes
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1018 ``leaked'' memory that still takes up space. Over a long period of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1019 time, this can cause your program to grow and grow until it runs out of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1020 memory.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1021
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1022 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1023 Lisp has built-in facilities for handling errors and exceptions. In C,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1024 when an error occurs, usually either the program exits entirely or the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1025 routine in which the error occurs returns a value indicating this. If
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1026 an error occurs in a deeply-nested routine, then every routine currently
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1027 called must unwind itself normally and return an error value back up to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1028 the next routine. This means that every routine must explicitly check
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1029 for an error in all the routines it calls; if it does not do so,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1030 unexpected and often random behavior results. This is an extremely
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1031 common source of bugs in C programs. An alternative would be to do a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1032 non-local exit using @code{longjmp()}, but that is often very dangerous
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1033 because the routines that were exited past had no opportunity to clean
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1034 up after themselves and may leave things in an inconsistent state,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1035 causing a crash shortly afterwards.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1036
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1037 Lisp provides mechanisms to make such non-local exits safe. When an
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1038 error occurs, a routine simply signals that an error of a particular
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1039 class has occurred, and a non-local exit takes place. Any routine can
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1040 trap errors occurring in routines it calls by registering an error
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1041 handler for some or all classes of errors. (If no handler is registered,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1042 a default handler, generally installed by the top-level event loop, is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1043 executed; this prints out the error and continues.) Routines can also
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1044 specify cleanup code (called an @dfn{unwind-protect}) that will be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1045 called when control exits from a block of code, no matter how that exit
440
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 438
diff changeset
1046 occurs---i.e. even if a function deeply nested below it causes a
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1047 non-local exit back to the top level.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1048
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1049 Note that this facility has appeared in some recent vintages of C, in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1050 particular Visual C++ and other PC compilers written for the Microsoft
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1051 Win32 API.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1052
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1053 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1054 In Emacs Lisp, local variables are @dfn{dynamically scoped}. This means
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1055 that if you declare a local variable in a particular function, and then
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1056 call another function, that subfunction can ``see'' the local variable
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1057 you declared. This is actually considered a bug in Emacs Lisp and in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1058 all other early dialects of Lisp, and was corrected in Common Lisp. (In
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1059 Common Lisp, you can still declare dynamically scoped variables if you
440
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 438
diff changeset
1060 want to---they are sometimes useful---but variables by default are
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1061 @dfn{lexically scoped} as in C.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1062 @end enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1063
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1064 For those familiar with Lisp, Emacs Lisp is modelled after MacLisp, an
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1065 early dialect of Lisp developed at MIT (no relation to the Macintosh
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1066 computer). There is a Common Lisp compatibility package available for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1067 Emacs that provides many of the features of Common Lisp.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1068
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1069 The Java language is derived in many ways from C, and shares a similar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1070 syntax, but has the following features in common with Lisp (and different
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1071 from C):
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1072
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1073 @enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1074 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1075 Java is a safe language, like Lisp.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1076 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1077 Java provides garbage collection, like Lisp.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1078 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1079 Java has built-in facilities for handling errors and exceptions, like
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1080 Lisp.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1081 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1082 Java has a type system that combines the best advantages of both static
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1083 and dynamic typing. Objects (except very simple types) are explicitly
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1084 marked with their type, as in dynamic typing; but there is a hierarchy
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1085 of types and functions are declared to accept only certain types, thus
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1086 providing the increased compile-time error-checking of static typing.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1087 @end enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1088
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1089 The Java language also has some negative attributes:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1090
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1091 @enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1092 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1093 Java uses the edit/compile/run model of software development. This
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1094 makes it hard to use interactively. For example, to use Java like
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1095 @code{bc} it is necessary to write a special purpose, albeit tiny,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1096 application. In Emacs Lisp, a calculator comes built-in without any
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1097 effort - one can always just type an expression in the @code{*scratch*}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1098 buffer.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1099 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1100 Java tries too hard to enforce, not merely enable, portability, making
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1101 ordinary access to standard OS facilities painful. Java has an
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1102 @dfn{agenda}. I think this is why @code{chdir} is not part of standard
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1103 Java, which is inexcusable.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1104 @end enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1105
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1106 Unfortunately, there is no perfect language. Static typing allows a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1107 compiler to catch programmer errors and produce more efficient code, but
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1108 makes programming more tedious and less fun. For the foreseeable future,
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1109 an Ideal Editing and Programming Environment (and that is what XEmacs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1110 aspires to) will be programmable in multiple languages: high level ones
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1111 like Lisp for user customization and prototyping, and lower level ones
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1112 for infrastructure and industrial strength applications. If I had my
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1113 way, XEmacs would be friendly towards the Python, Scheme, C++, ML,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1114 etc... communities. But there are serious technical difficulties to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1115 achieving that goal.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1116
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1117 The word @dfn{application} in the previous paragraph was used
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1118 intentionally. XEmacs implements an API for programs written in Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1119 that makes it a full-fledged application platform, very much like an OS
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1120 inside the real OS.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1121
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1122 @node XEmacs From the Perspective of Building, XEmacs From the Inside, The Lisp Language, Top
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1123 @chapter XEmacs From the Perspective of Building
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
1124 @cindex XEmacs from the perspective of building
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
1125 @cindex building, XEmacs from the perspective of
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1126
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1127 The heart of XEmacs is the Lisp environment, which is written in C.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1128 This is contained in the @file{src/} subdirectory. Underneath
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1129 @file{src/} are two subdirectories of header files: @file{s/} (header
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1130 files for particular operating systems) and @file{m/} (header files for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1131 particular machine types). In practice the distinction between the two
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1132 types of header files is blurred. These header files define or undefine
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1133 certain preprocessor constants and macros to indicate particular
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1134 characteristics of the associated machine or operating system. As part
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1135 of the configure process, one @file{s/} file and one @file{m/} file is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1136 identified for the particular environment in which XEmacs is being
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1137 built.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1138
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1139 XEmacs also contains a great deal of Lisp code. This implements the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1140 operations that make XEmacs useful as an editor as well as just a Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1141 environment, and also contains many add-on packages that allow XEmacs to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1142 browse directories, act as a mail and Usenet news reader, compile Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1143 code, etc. There is actually more Lisp code than C code associated with
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1144 XEmacs, but much of the Lisp code is peripheral to the actual operation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1145 of the editor. The Lisp code all lies in subdirectories underneath the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1146 @file{lisp/} directory.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1147
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1148 The @file{lwlib/} directory contains C code that implements a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1149 generalized interface onto different X widget toolkits and also
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1150 implements some widgets of its own that behave like Motif widgets but
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1151 are faster, free, and in some cases more powerful. The code in this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1152 directory compiles into a library and is mostly independent from XEmacs.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1153
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1154 The @file{etc/} directory contains various data files associated with
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1155 XEmacs. Some of them are actually read by XEmacs at startup; others
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1156 merely contain useful information of various sorts.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1157
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1158 The @file{lib-src/} directory contains C code for various auxiliary
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1159 programs that are used in connection with XEmacs. Some of them are used
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1160 during the build process; others are used to perform certain functions
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1161 that cannot conveniently be placed in the XEmacs executable (e.g. the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1162 @file{movemail} program for fetching mail out of @file{/var/spool/mail},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1163 which must be setgid to @file{mail} on many systems; and the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1164 @file{gnuclient} program, which allows an external script to communicate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1165 with a running XEmacs process).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1166
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1167 The @file{man/} directory contains the sources for the XEmacs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1168 documentation. It is mostly in a form called Texinfo, which can be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1169 converted into either a printed document (by passing it through @TeX{})
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1170 or into on-line documentation called @dfn{info files}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1171
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1172 The @file{info/} directory contains the results of formatting the XEmacs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1173 documentation as @dfn{info files}, for on-line use. These files are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1174 used when you enter the Info system using @kbd{C-h i} or through the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1175 Help menu.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1176
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1177 The @file{dynodump/} directory contains auxiliary code used to build
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1178 XEmacs on Solaris platforms.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1179
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1180 The other directories contain various miscellaneous code and information
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1181 that is not normally used or needed.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1182
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1183 The first step of building involves running the @file{configure} program
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1184 and passing it various parameters to specify any optional features you
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1185 want and compiler arguments and such, as described in the @file{INSTALL}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1186 file. This determines what the build environment is, chooses the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1187 appropriate @file{s/} and @file{m/} file, and runs a series of tests to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1188 determine many details about your environment, such as which library
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1189 functions are available and exactly how they work. The reason for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1190 running these tests is that it allows XEmacs to be compiled on a much
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1191 wider variety of platforms than those that the XEmacs developers happen
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1192 to be familiar with, including various sorts of hybrid platforms. This
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1193 is especially important now that many operating systems give you a great
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1194 deal of control over exactly what features you want installed, and allow
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1195 for easy upgrading of parts of a system without upgrading the rest. It
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1196 would be impossible to pre-determine and pre-specify the information for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1197 all possible configurations.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1198
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1199 In fact, the @file{s/} and @file{m/} files are basically @emph{evil},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1200 since they contain unmaintainable platform-specific hard-coded
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1201 information. XEmacs has been moving in the direction of having all
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1202 system-specific information be determined dynamically by
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1203 @file{configure}. Perhaps someday we can @code{rm -rf src/s src/m}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1204
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1205 When configure is done running, it generates @file{Makefile}s and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1206 @file{GNUmakefile}s and the file @file{src/config.h} (which describes
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1207 the features of your system) from template files. You then run
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1208 @file{make}, which compiles the auxiliary code and programs in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1209 @file{lib-src/} and @file{lwlib/} and the main XEmacs executable in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1210 @file{src/}. The result of compiling and linking is an executable
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1211 called @file{temacs}, which is @emph{not} the final XEmacs executable.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1212 @file{temacs} by itself is not intended to function as an editor or even
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1213 display any windows on the screen, and if you simply run it, it will
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1214 exit immediately. The @file{Makefile} runs @file{temacs} with certain
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1215 options that cause it to initialize itself, read in a number of basic
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1216 Lisp files, and then dump itself out into a new executable called
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1217 @file{xemacs}. This new executable has been pre-initialized and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1218 contains pre-digested Lisp code that is necessary for the editor to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1219 function (this includes most basic editing functions,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1220 e.g. @code{kill-line}, that can be defined in terms of other Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1221 primitives; some initialization code that is called when certain
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1222 objects, such as frames, are created; and all of the standard
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1223 keybindings and code for the actions they result in). This executable,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1224 @file{xemacs}, is the executable that you run to use the XEmacs editor.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1225
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1226 Although @file{temacs} is not intended to be run as an editor, it can,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1227 by using the incantation @code{temacs -batch -l loadup.el run-temacs}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1228 This is useful when the dumping procedure described above is broken, or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1229 when using certain program debugging tools such as Purify. These tools
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1230 get mighty confused by the tricks played by the XEmacs build process,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1231 such as allocation memory in one process, and freeing it in the next.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1232
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1233 @node XEmacs From the Inside, The XEmacs Object System (Abstractly Speaking), XEmacs From the Perspective of Building, Top
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1234 @chapter XEmacs From the Inside
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
1235 @cindex XEmacs from the inside
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
1236 @cindex inside, XEmacs from the
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1237
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1238 Internally, XEmacs is quite complex, and can be very confusing. To
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1239 simplify things, it can be useful to think of XEmacs as containing an
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1240 event loop that ``drives'' everything, and a number of other subsystems,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1241 such as a Lisp engine and a redisplay mechanism. Each of these other
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1242 subsystems exists simultaneously in XEmacs, and each has a certain
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1243 state. The flow of control continually passes in and out of these
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1244 different subsystems in the course of normal operation of the editor.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1245
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1246 It is important to keep in mind that, most of the time, the editor is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1247 ``driven'' by the event loop. Except during initialization and batch
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1248 mode, all subsystems are entered directly or indirectly through the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1249 event loop, and ultimately, control exits out of all subsystems back up
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1250 to the event loop. This cycle of entering a subsystem, exiting back out
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1251 to the event loop, and starting another iteration of the event loop
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1252 occurs once each keystroke, mouse motion, etc.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1253
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1254 If you're trying to understand a particular subsystem (other than the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1255 event loop), think of it as a ``daemon'' process or ``servant'' that is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1256 responsible for one particular aspect of a larger system, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1257 periodically receives commands or environment changes that cause it to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1258 do something. Ultimately, these commands and environment changes are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1259 always triggered by the event loop. For example:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1260
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1261 @itemize @bullet
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1262 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1263 The window and frame mechanism is responsible for keeping track of what
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1264 windows and frames exist, what buffers are in them, etc. It is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1265 periodically given commands (usually from the user) to make a change to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1266 the current window/frame state: i.e. create a new frame, delete a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1267 window, etc.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1268
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1269 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1270 The buffer mechanism is responsible for keeping track of what buffers
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1271 exist and what text is in them. It is periodically given commands
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1272 (usually from the user) to insert or delete text, create a buffer, etc.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1273 When it receives a text-change command, it notifies the redisplay
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1274 mechanism.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1275
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1276 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1277 The redisplay mechanism is responsible for making sure that windows and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1278 frames are displayed correctly. It is periodically told (by the event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1279 loop) to actually ``do its job'', i.e. snoop around and see what the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1280 current state of the environment (mostly of the currently-existing
625
33f0f28b945c [xemacs-hg @ 2001-07-02 20:45:03 by adrian]
adrian
parents: 607
diff changeset
1281 windows, frames, and buffers) is, and make sure that state matches
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1282 what's actually displayed. It keeps lots and lots of information around
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1283 (such as what is actually being displayed currently, and what the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1284 environment was last time it checked) so that it can minimize the work
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1285 it has to do. It is also helped along in that whenever a relevant
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1286 change to the environment occurs, the redisplay mechanism is told about
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1287 this, so it has a pretty good idea of where it has to look to find
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1288 possible changes and doesn't have to look everywhere.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1289
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1290 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1291 The Lisp engine is responsible for executing the Lisp code in which most
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1292 user commands are written. It is entered through a call to @code{eval}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1293 or @code{funcall}, which occurs as a result of dispatching an event from
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1294 the event loop. The functions it calls issue commands to the buffer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1295 mechanism, the window/frame subsystem, etc.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1296
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1297 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1298 The Lisp allocation subsystem is responsible for keeping track of Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1299 objects. It is given commands from the Lisp engine to allocate objects,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1300 garbage collect, etc.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1301 @end itemize
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1302
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1303 etc.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1304
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1305 The important idea here is that there are a number of independent
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1306 subsystems each with its own responsibility and persistent state, just
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1307 like different employees in a company, and each subsystem is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1308 periodically given commands from other subsystems. Commands can flow
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1309 from any one subsystem to any other, but there is usually some sort of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1310 hierarchy, with all commands originating from the event subsystem.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1311
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1312 XEmacs is entered in @code{main()}, which is in @file{emacs.c}. When
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1313 this is called the first time (in a properly-invoked @file{temacs}), it
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1314 does the following:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1315
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1316 @enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1317 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1318 It does some very basic environment initializations, such as determining
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1319 where it and its directories (e.g. @file{lisp/} and @file{etc/}) reside
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1320 and setting up signal handlers.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1321 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1322 It initializes the entire Lisp interpreter.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1323 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1324 It sets the initial values of many built-in variables (including many
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1325 variables that are visible to Lisp programs), such as the global keymap
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1326 object and the built-in faces (a face is an object that describes the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1327 display characteristics of text). This involves creating Lisp objects
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1328 and thus is dependent on step (2).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1329 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1330 It performs various other initializations that are relevant to the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1331 particular environment it is running in, such as retrieving environment
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1332 variables, determining the current date and the user who is running the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1333 program, examining its standard input, creating any necessary file
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1334 descriptors, etc.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1335 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1336 At this point, the C initialization is complete. A Lisp program that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1337 was specified on the command line (usually @file{loadup.el}) is called
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1338 (temacs is normally invoked as @code{temacs -batch -l loadup.el dump}).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1339 @file{loadup.el} loads all of the other Lisp files that are needed for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1340 the operation of the editor, calls the @code{dump-emacs} function to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1341 write out @file{xemacs}, and then kills the temacs process.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1342 @end enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1343
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1344 When @file{xemacs} is then run, it only redoes steps (1) and (4)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1345 above; all variables already contain the values they were set to when
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1346 the executable was dumped, and all memory that was allocated with
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1347 @code{malloc()} is still around. (XEmacs knows whether it is being run
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1348 as @file{xemacs} or @file{temacs} because it sets the global variable
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1349 @code{initialized} to 1 after step (4) above.) At this point,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1350 @file{xemacs} calls a Lisp function to do any further initialization,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1351 which includes parsing the command-line (the C code can only do limited
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1352 command-line parsing, which includes looking for the @samp{-batch} and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1353 @samp{-l} flags and a few other flags that it needs to know about before
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1354 initialization is complete), creating the first frame (or @dfn{window}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1355 in standard window-system parlance), running the user's init file
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1356 (usually the file @file{.emacs} in the user's home directory), etc. The
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1357 function to do this is usually called @code{normal-top-level};
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1358 @file{loadup.el} tells the C code about this function by setting its
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1359 name as the value of the Lisp variable @code{top-level}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1360
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1361 When the Lisp initialization code is done, the C code enters the event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1362 loop, and stays there for the duration of the XEmacs process. The code
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1363 for the event loop is contained in @file{cmdloop.c}, and is called
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1364 @code{Fcommand_loop_1()}. Note that this event loop could very well be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1365 written in Lisp, and in fact a Lisp version exists; but apparently,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1366 doing this makes XEmacs run noticeably slower.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1367
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1368 Notice how much of the initialization is done in Lisp, not in C.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1369 In general, XEmacs tries to move as much code as is possible
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1370 into Lisp. Code that remains in C is code that implements the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1371 Lisp interpreter itself, or code that needs to be very fast, or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1372 code that needs to do system calls or other such stuff that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1373 needs to be done in C, or code that needs to have access to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1374 ``forbidden'' structures. (One conscious aspect of the design of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1375 Lisp under XEmacs is a clean separation between the external
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1376 interface to a Lisp object's functionality and its internal
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1377 implementation. Part of this design is that Lisp programs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1378 are forbidden from accessing the contents of the object other
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1379 than through using a standard API. In this respect, XEmacs Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1380 is similar to modern Lisp dialects but differs from GNU Emacs,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1381 which tends to expose the implementation and allow Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1382 programs to look at it directly. The major advantage of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1383 hiding the implementation is that it allows the implementation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1384 to be redesigned without affecting any Lisp programs, including
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1385 those that might want to be ``clever'' by looking directly at
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1386 the object's contents and possibly manipulating them.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1387
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1388 Moving code into Lisp makes the code easier to debug and maintain and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1389 makes it much easier for people who are not XEmacs developers to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1390 customize XEmacs, because they can make a change with much less chance
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1391 of obscure and unwanted interactions occurring than if they were to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1392 change the C code.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1393
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1394 @node The XEmacs Object System (Abstractly Speaking), How Lisp Objects Are Represented in C, XEmacs From the Inside, Top
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1395 @chapter The XEmacs Object System (Abstractly Speaking)
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
1396 @cindex XEmacs object system (abstractly speaking), the
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
1397 @cindex object system (abstractly speaking), the XEmacs
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1398
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1399 At the heart of the Lisp interpreter is its management of objects.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1400 XEmacs Lisp contains many built-in objects, some of which are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1401 simple and others of which can be very complex; and some of which
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1402 are very common, and others of which are rarely used or are only
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1403 used internally. (Since the Lisp allocation system, with its
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1404 automatic reclamation of unused storage, is so much more convenient
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1405 than @code{malloc()} and @code{free()}, the C code makes extensive use of it
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1406 in its internal operations.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1407
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1408 The basic Lisp objects are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1409
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1410 @table @code
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1411 @item integer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1412 28 or 31 bits of precision, or 60 or 63 bits on 64-bit machines; the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1413 reason for this is described below when the internal Lisp object
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1414 representation is described.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1415 @item float
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1416 Same precision as a double in C.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1417 @item cons
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1418 A simple container for two Lisp objects, used to implement lists and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1419 most other data structures in Lisp.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1420 @item char
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1421 An object representing a single character of text; chars behave like
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1422 integers in many ways but are logically considered text rather than
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1423 numbers and have a different read syntax. (the read syntax for a char
440
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 438
diff changeset
1424 contains the char itself or some textual encoding of it---for example,
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1425 a Japanese Kanji character might be encoded as @samp{^[$(B#&^[(B} using the
440
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 438
diff changeset
1426 ISO-2022 encoding standard---rather than the numerical representation
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1427 of the char; this way, if the mapping between chars and integers
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1428 changes, which is quite possible for Kanji characters and other extended
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1429 characters, the same character will still be created. Note that some
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1430 primitives confuse chars and integers. The worst culprit is @code{eq},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1431 which makes a special exception and considers a char to be @code{eq} to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1432 its integer equivalent, even though in no other case are objects of two
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1433 different types @code{eq}. The reason for this monstrosity is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1434 compatibility with existing code; the separation of char from integer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1435 came fairly recently.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1436 @item symbol
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1437 An object that contains Lisp objects and is referred to by name;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1438 symbols are used to implement variables and named functions
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1439 and to provide the equivalent of preprocessor constants in C.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1440 @item vector
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1441 A one-dimensional array of Lisp objects providing constant-time access
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1442 to any of the objects; access to an arbitrary object in a vector is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1443 faster than for lists, but the operations that can be done on a vector
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1444 are more limited.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1445 @item string
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1446 Self-explanatory; behaves much like a vector of chars
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1447 but has a different read syntax and is stored and manipulated
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1448 more compactly.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1449 @item bit-vector
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1450 A vector of bits; similar to a string in spirit.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1451 @item compiled-function
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1452 An object containing compiled Lisp code, known as @dfn{byte code}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1453 @item subr
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1454 A Lisp primitive, i.e. a Lisp-callable function implemented in C.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1455 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1456
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1457 @cindex closure
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1458 Note that there is no basic ``function'' type, as in more powerful
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1459 versions of Lisp (where it's called a @dfn{closure}). XEmacs Lisp does
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1460 not provide the closure semantics implemented by Common Lisp and Scheme.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1461 The guts of a function in XEmacs Lisp are represented in one of four
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1462 ways: a symbol specifying another function (when one function is an
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1463 alias for another), a list (whose first element must be the symbol
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1464 @code{lambda}) containing the function's source code, a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1465 compiled-function object, or a subr object. (In other words, given a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1466 symbol specifying the name of a function, calling @code{symbol-function}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1467 to retrieve the contents of the symbol's function cell will return one
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1468 of these types of objects.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1469
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1470 XEmacs Lisp also contains numerous specialized objects used to implement
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1471 the editor:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1472
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1473 @table @code
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1474 @item buffer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1475 Stores text like a string, but is optimized for insertion and deletion
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1476 and has certain other properties that can be set.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1477 @item frame
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1478 An object with various properties whose displayable representation is a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1479 @dfn{window} in window-system parlance.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1480 @item window
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1481 A section of a frame that displays the contents of a buffer;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1482 often called a @dfn{pane} in window-system parlance.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1483 @item window-configuration
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1484 An object that represents a saved configuration of windows in a frame.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1485 @item device
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1486 An object representing a screen on which frames can be displayed;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1487 equivalent to a @dfn{display} in the X Window System and a @dfn{TTY} in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1488 character mode.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1489 @item face
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1490 An object specifying the appearance of text or graphics; it has
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1491 properties such as font, foreground color, and background color.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1492 @item marker
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1493 An object that refers to a particular position in a buffer and moves
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1494 around as text is inserted and deleted to stay in the same relative
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1495 position to the text around it.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1496 @item extent
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1497 Similar to a marker but covers a range of text in a buffer; can also
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1498 specify properties of the text, such as a face in which the text is to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1499 be displayed, whether the text is invisible or unmodifiable, etc.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1500 @item event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1501 Generated by calling @code{next-event} and contains information
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1502 describing a particular event happening in the system, such as the user
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1503 pressing a key or a process terminating.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1504 @item keymap
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1505 An object that maps from events (described using lists, vectors, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1506 symbols rather than with an event object because the mapping is for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1507 classes of events, rather than individual events) to functions to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1508 execute or other events to recursively look up; the functions are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1509 described by name, using a symbol, or using lists to specify the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1510 function's code.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1511 @item glyph
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1512 An object that describes the appearance of an image (e.g. pixmap) on
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1513 the screen; glyphs can be attached to the beginning or end of extents
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1514 and in some future version of XEmacs will be able to be inserted
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1515 directly into a buffer.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1516 @item process
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1517 An object that describes a connection to an externally-running process.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1518 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1519
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1520 There are some other, less-commonly-encountered general objects:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1521
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1522 @table @code
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1523 @item hash-table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1524 An object that maps from an arbitrary Lisp object to another arbitrary
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1525 Lisp object, using hashing for fast lookup.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1526 @item obarray
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1527 A limited form of hash-table that maps from strings to symbols; obarrays
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1528 are used to look up a symbol given its name and are not actually their
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1529 own object type but are kludgily represented using vectors with hidden
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1530 fields (this representation derives from GNU Emacs).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1531 @item specifier
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1532 A complex object used to specify the value of a display property; a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1533 default value is given and different values can be specified for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1534 particular frames, buffers, windows, devices, or classes of device.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1535 @item char-table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1536 An object that maps from chars or classes of chars to arbitrary Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1537 objects; internally char tables use a complex nested-vector
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1538 representation that is optimized to the way characters are represented
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1539 as integers.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1540 @item range-table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1541 An object that maps from ranges of integers to arbitrary Lisp objects.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1542 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1543
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1544 And some strange special-purpose objects:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1545
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1546 @table @code
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1547 @item charset
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1548 @itemx coding-system
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1549 Objects used when MULE, or multi-lingual/Asian-language, support is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1550 enabled.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1551 @item color-instance
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1552 @itemx font-instance
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1553 @itemx image-instance
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1554 An object that encapsulates a window-system resource; instances are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1555 mostly used internally but are exposed on the Lisp level for cleanness
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1556 of the specifier model and because it's occasionally useful for Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1557 program to create or query the properties of instances.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1558 @item subwindow
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1559 An object that encapsulate a @dfn{subwindow} resource, i.e. a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1560 window-system child window that is drawn into by an external process;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1561 this object should be integrated into the glyph system but isn't yet,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1562 and may change form when this is done.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1563 @item tooltalk-message
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1564 @itemx tooltalk-pattern
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1565 Objects that represent resources used in the ToolTalk interprocess
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1566 communication protocol.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1567 @item toolbar-button
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1568 An object used in conjunction with the toolbar.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1569 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1570
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1571 And objects that are only used internally:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1572
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1573 @table @code
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1574 @item opaque
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1575 A generic object for encapsulating arbitrary memory; this allows you the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1576 generality of @code{malloc()} and the convenience of the Lisp object
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1577 system.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1578 @item lstream
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1579 A buffering I/O stream, used to provide a unified interface to anything
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1580 that can accept output or provide input, such as a file descriptor, a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1581 stdio stream, a chunk of memory, a Lisp buffer, a Lisp string, etc.;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1582 it's a Lisp object to make its memory management more convenient.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1583 @item char-table-entry
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1584 Subsidiary objects in the internal char-table representation.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1585 @item extent-auxiliary
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1586 @itemx menubar-data
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1587 @itemx toolbar-data
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1588 Various special-purpose objects that are basically just used to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1589 encapsulate memory for particular subsystems, similar to the more
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1590 general ``opaque'' object.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1591 @item symbol-value-forward
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1592 @itemx symbol-value-buffer-local
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1593 @itemx symbol-value-varalias
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1594 @itemx symbol-value-lisp-magic
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1595 Special internal-only objects that are placed in the value cell of a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1596 symbol to indicate that there is something special with this variable --
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1597 e.g. it has no value, it mirrors another variable, or it mirrors some C
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1598 variable; there is really only one kind of object, called a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1599 @dfn{symbol-value-magic}, but it is sort-of halfway kludged into
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1600 semi-different object types.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1601 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1602
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1603 @cindex permanent objects
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1604 @cindex temporary objects
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1605 Some types of objects are @dfn{permanent}, meaning that once created,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1606 they do not disappear until explicitly destroyed, using a function such
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1607 as @code{delete-buffer}, @code{delete-window}, @code{delete-frame}, etc.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1608 Others will disappear once they are not longer used, through the garbage
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1609 collection mechanism. Buffers, frames, windows, devices, and processes
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1610 are among the objects that are permanent. Note that some objects can go
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1611 both ways: Faces can be created either way; extents are normally
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1612 permanent, but detached extents (extents not referring to any text, as
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1613 happens to some extents when the text they are referring to is deleted)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1614 are temporary. Note that some permanent objects, such as faces and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1615 coding systems, cannot be deleted. Note also that windows are unique in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1616 that they can be @emph{undeleted} after having previously been
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1617 deleted. (This happens as a result of restoring a window configuration.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1618
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1619 @cindex read syntax
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1620 Note that many types of objects have a @dfn{read syntax}, i.e. a way of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1621 specifying an object of that type in Lisp code. When you load a Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1622 file, or type in code to be evaluated, what really happens is that the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1623 function @code{read} is called, which reads some text and creates an object
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1624 based on the syntax of that text; then @code{eval} is called, which
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1625 possibly does something special; then this loop repeats until there's
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1626 no more text to read. (@code{eval} only actually does something special
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1627 with symbols, which causes the symbol's value to be returned,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1628 similar to referencing a variable; and with conses [i.e. lists],
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1629 which cause a function invocation. All other values are returned
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1630 unchanged.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1631
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1632 The read syntax
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1633
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1634 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1635 17297
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1636 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1637
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1638 converts to an integer whose value is 17297.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1639
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1640 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1641 1.983e-4
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1642 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1643
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1644 converts to a float whose value is 1.983e-4, or .0001983.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1645
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1646 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1647 ?b
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1648 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1649
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1650 converts to a char that represents the lowercase letter b.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1651
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1652 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1653 ?^[$(B#&^[(B
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1654 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1655
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1656 (where @samp{^[} actually is an @samp{ESC} character) converts to a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1657 particular Kanji character when using an ISO2022-based coding system for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1658 input. (To decode this goo: @samp{ESC} begins an escape sequence;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1659 @samp{ESC $ (} is a class of escape sequences meaning ``switch to a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1660 94x94 character set''; @samp{ESC $ ( B} means ``switch to Japanese
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1661 Kanji''; @samp{#} and @samp{&} collectively index into a 94-by-94 array
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1662 of characters [subtract 33 from the ASCII value of each character to get
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1663 the corresponding index]; @samp{ESC (} is a class of escape sequences
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1664 meaning ``switch to a 94 character set''; @samp{ESC (B} means ``switch
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1665 to US ASCII''. It is a coincidence that the letter @samp{B} is used to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1666 denote both Japanese Kanji and US ASCII. If the first @samp{B} were
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1667 replaced with an @samp{A}, you'd be requesting a Chinese Hanzi character
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1668 from the GB2312 character set.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1669
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1670 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1671 "foobar"
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1672 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1673
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1674 converts to a string.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1675
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1676 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1677 foobar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1678 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1679
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1680 converts to a symbol whose name is @code{"foobar"}. This is done by
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1681 looking up the string equivalent in the global variable
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1682 @code{obarray}, whose contents should be an obarray. If no symbol
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1683 is found, a new symbol with the name @code{"foobar"} is automatically
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1684 created and added to @code{obarray}; this process is called
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1685 @dfn{interning} the symbol.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1686 @cindex interning
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1687
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1688 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1689 (foo . bar)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1690 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1691
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1692 converts to a cons cell containing the symbols @code{foo} and @code{bar}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1693
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1694 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1695 (1 a 2.5)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1696 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1697
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1698 converts to a three-element list containing the specified objects
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1699 (note that a list is actually a set of nested conses; see the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1700 XEmacs Lisp Reference).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1701
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1702 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1703 [1 a 2.5]
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1704 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1705
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1706 converts to a three-element vector containing the specified objects.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1707
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1708 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1709 #[... ... ... ...]
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1710 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1711
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1712 converts to a compiled-function object (the actual contents are not
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1713 shown since they are not relevant here; look at a file that ends with
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1714 @file{.elc} for examples).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1715
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1716 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1717 #*01110110
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1718 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1719
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1720 converts to a bit-vector.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1721
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1722 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1723 #s(hash-table ... ...)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1724 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1725
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1726 converts to a hash table (the actual contents are not shown).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1727
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1728 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1729 #s(range-table ... ...)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1730 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1731
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1732 converts to a range table (the actual contents are not shown).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1733
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1734 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1735 #s(char-table ... ...)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1736 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1737
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1738 converts to a char table (the actual contents are not shown).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1739
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1740 Note that the @code{#s()} syntax is the general syntax for structures,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1741 which are not really implemented in XEmacs Lisp but should be.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1742
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1743 When an object is printed out (using @code{print} or a related
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1744 function), the read syntax is used, so that the same object can be read
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1745 in again.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1746
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1747 The other objects do not have read syntaxes, usually because it does not
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1748 really make sense to create them in this fashion (i.e. processes, where
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1749 it doesn't make sense to have a subprocess created as a side effect of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1750 reading some Lisp code), or because they can't be created at all
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1751 (e.g. subrs). Permanent objects, as a rule, do not have a read syntax;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1752 nor do most complex objects, which contain too much state to be easily
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1753 initialized through a read syntax.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1754
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1755 @node How Lisp Objects Are Represented in C, Rules When Writing New C Code, The XEmacs Object System (Abstractly Speaking), Top
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1756 @chapter How Lisp Objects Are Represented in C
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
1757 @cindex Lisp objects are represented in C, how
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
1758 @cindex objects are represented in C, how Lisp
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
1759 @cindex represented in C, how Lisp objects are
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1760
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1761 Lisp objects are represented in C using a 32-bit or 64-bit machine word
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1762 (depending on the processor; i.e. DEC Alphas use 64-bit Lisp objects and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1763 most other processors use 32-bit Lisp objects). The representation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1764 stuffs a pointer together with a tag, as follows:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1765
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1766 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1767 [ 3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 ]
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1768 [ 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 ]
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1769
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1770 <---------------------------------------------------------> <->
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1771 a pointer to a structure, or an integer tag
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1772 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1773
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1774 A tag of 00 is used for all pointer object types, a tag of 10 is used
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1775 for characters, and the other two tags 01 and 11 are joined together to
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1776 form the integer object type. This representation gives us 31 bit
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1777 integers and 30 bit characters, while pointers are represented directly
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1778 without any bit masking or shifting. This representation, though,
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1779 assumes that pointers to structs are always aligned to multiples of 4,
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1780 so the lower 2 bits are always zero.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1781
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1782 Lisp objects use the typedef @code{Lisp_Object}, but the actual C type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1783 used for the Lisp object can vary. It can be either a simple type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1784 (@code{long} on the DEC Alpha, @code{int} on other machines) or a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1785 structure whose fields are bit fields that line up properly (actually, a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1786 union of structures is used). Generally the simple integral type is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1787 preferable because it ensures that the compiler will actually use a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1788 machine word to represent the object (some compilers will use more
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1789 general and less efficient code for unions and structs even if they can
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1790 fit in a machine word). The union type, however, has the advantage of
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1791 stricter type checking. If you accidentally pass an integer where a Lisp
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1792 object is desired, you get a compile error. The choice of which type
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1793 to use is determined by the preprocessor constant @code{USE_UNION_TYPE}
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1794 which is defined via the @code{--use-union-type} option to
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1795 @code{configure}.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1796
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1797 Various macros are used to convert between Lisp_Objects and the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1798 corresponding C type. Macros of the form @code{XINT()}, @code{XCHAR()},
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1799 @code{XSTRING()}, @code{XSYMBOL()}, do any required bit shifting and/or
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1800 masking and cast it to the appropriate type. @code{XINT()} needs to be
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1801 a bit tricky so that negative numbers are properly sign-extended. Since
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1802 integers are stored left-shifted, if the right-shift operator does an
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1803 arithmetic shift (i.e. it leaves the most-significant bit as-is rather
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1804 than shifting in a zero, so that it mimics a divide-by-two even for
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1805 negative numbers) the shift to remove the tag bit is enough. This is
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1806 the case on all the systems we support.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1807
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1808 Note that when @code{ERROR_CHECK_TYPECHECK} is defined, the converter
440
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 438
diff changeset
1809 macros become more complicated---they check the tag bits and/or the
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1810 type field in the first four bytes of a record type to ensure that the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1811 object is really of the correct type. This is great for catching places
440
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 438
diff changeset
1812 where an incorrect type is being dereferenced---this typically results
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1813 in a pointer being dereferenced as the wrong type of structure, with
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1814 unpredictable (and sometimes not easily traceable) results.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1815
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1816 There are similar @code{XSET@var{TYPE}()} macros that construct a Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1817 object. These macros are of the form @code{XSET@var{TYPE}
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1818 (@var{lvalue}, @var{result})}, i.e. they have to be a statement rather
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1819 than just used in an expression. The reason for this is that standard C
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1820 doesn't let you ``construct'' a structure (but GCC does). Granted, this
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1821 sometimes isn't too convenient; for the case of integers, at least, you
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1822 can use the function @code{make_int()}, which constructs and
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1823 @emph{returns} an integer Lisp object. Note that the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1824 @code{XSET@var{TYPE}()} macros are also affected by
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1825 @code{ERROR_CHECK_TYPECHECK} and make sure that the structure is of the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1826 right type in the case of record types, where the type is contained in
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1827 the structure.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1828
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1829 The C programmer is responsible for @strong{guaranteeing} that a
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1830 Lisp_Object is the correct type before using the @code{X@var{TYPE}}
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1831 macros. This is especially important in the case of lists. Use
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1832 @code{XCAR} and @code{XCDR} if a Lisp_Object is certainly a cons cell,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1833 else use @code{Fcar()} and @code{Fcdr()}. Trust other C code, but not
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1834 Lisp code. On the other hand, if XEmacs has an internal logic error,
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1835 it's better to crash immediately, so sprinkle @code{assert()}s and
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1836 ``unreachable'' @code{abort()}s liberally about the source code. Where
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1837 performance is an issue, use @code{type_checking_assert},
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1838 @code{bufpos_checking_assert}, and @code{gc_checking_assert}, which do
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1839 nothing unless the corresponding configure error checking flag was
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1840 specified.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1841
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1842 @node Rules When Writing New C Code, A Summary of the Various XEmacs Modules, How Lisp Objects Are Represented in C, Top
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1843 @chapter Rules When Writing New C Code
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
1844 @cindex writing new C code, rules when
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
1845 @cindex C code, rules when writing new
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
1846 @cindex code, rules when writing new C
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1847
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1848 The XEmacs C Code is extremely complex and intricate, and there are many
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1849 rules that are more or less consistently followed throughout the code.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1850 Many of these rules are not obvious, so they are explained here. It is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1851 of the utmost importance that you follow them. If you don't, you may
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1852 get something that appears to work, but which will crash in odd
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1853 situations, often in code far away from where the actual breakage is.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1854
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1855 @menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1856 * General Coding Rules::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1857 * Writing Lisp Primitives::
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
1858 * Writing Good Comments::
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1859 * Adding Global Lisp Variables::
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
1860 * Proper Use of Unsigned Types::
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1861 * Coding for Mule::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1862 * Techniques for XEmacs Developers::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1863 @end menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1864
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
1865 @node General Coding Rules
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1866 @section General Coding Rules
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
1867 @cindex coding rules, general
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1868
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1869 The C code is actually written in a dialect of C called @dfn{Clean C},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1870 meaning that it can be compiled, mostly warning-free, with either a C or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1871 C++ compiler. Coding in Clean C has several advantages over plain C.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1872 C++ compilers are more nit-picking, and a number of coding errors have
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1873 been found by compiling with C++. The ability to use both C and C++
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1874 tools means that a greater variety of development tools are available to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1875 the developer.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1876
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1877 Every module includes @file{<config.h>} (angle brackets so that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1878 @samp{--srcdir} works correctly; @file{config.h} may or may not be in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1879 the same directory as the C sources) and @file{lisp.h}. @file{config.h}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1880 must always be included before any other header files (including
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1881 system header files) to ensure that certain tricks played by various
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1882 @file{s/} and @file{m/} files work out correctly.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1883
440
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 438
diff changeset
1884 When including header files, always use angle brackets, not double
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1885 quotes, except when the file to be included is always in the same
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1886 directory as the including file. If either file is a generated file,
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1887 then that is not likely to be the case. In order to understand why we
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1888 have this rule, imagine what happens when you do a build in the source
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1889 directory using @samp{./configure} and another build in another
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1890 directory using @samp{../work/configure}. There will be two different
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1891 @file{config.h} files. Which one will be used if you @samp{#include
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1892 "config.h"}?
440
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 438
diff changeset
1893
448
3078fd1074e8 Import from CVS: tag r21-2-39
cvs
parents: 446
diff changeset
1894 Almost every module contains a @code{syms_of_*()} function and a
3078fd1074e8 Import from CVS: tag r21-2-39
cvs
parents: 446
diff changeset
1895 @code{vars_of_*()} function. The former declares any Lisp primitives
3078fd1074e8 Import from CVS: tag r21-2-39
cvs
parents: 446
diff changeset
1896 you have defined and defines any symbols you will be using. The latter
3078fd1074e8 Import from CVS: tag r21-2-39
cvs
parents: 446
diff changeset
1897 declares any global Lisp variables you have added and initializes global
3078fd1074e8 Import from CVS: tag r21-2-39
cvs
parents: 446
diff changeset
1898 C variables in the module. @strong{Important}: There are stringent
3078fd1074e8 Import from CVS: tag r21-2-39
cvs
parents: 446
diff changeset
1899 requirements on exactly what can go into these functions. See the
3078fd1074e8 Import from CVS: tag r21-2-39
cvs
parents: 446
diff changeset
1900 comment in @file{emacs.c}. The reason for this is to avoid obscure
3078fd1074e8 Import from CVS: tag r21-2-39
cvs
parents: 446
diff changeset
1901 unwanted interactions during initialization. If you don't follow these
3078fd1074e8 Import from CVS: tag r21-2-39
cvs
parents: 446
diff changeset
1902 rules, you'll be sorry! If you want to do anything that isn't allowed,
3078fd1074e8 Import from CVS: tag r21-2-39
cvs
parents: 446
diff changeset
1903 create a @code{complex_vars_of_*()} function for it. Doing this is
3078fd1074e8 Import from CVS: tag r21-2-39
cvs
parents: 446
diff changeset
1904 tricky, though: you have to make sure your function is called at the
3078fd1074e8 Import from CVS: tag r21-2-39
cvs
parents: 446
diff changeset
1905 right time so that all the initialization dependencies work out.
3078fd1074e8 Import from CVS: tag r21-2-39
cvs
parents: 446
diff changeset
1906
3078fd1074e8 Import from CVS: tag r21-2-39
cvs
parents: 446
diff changeset
1907 Declare each function of these kinds in @file{symsinit.h}. Make sure
3078fd1074e8 Import from CVS: tag r21-2-39
cvs
parents: 446
diff changeset
1908 it's called in the appropriate place in @file{emacs.c}. You never need
3078fd1074e8 Import from CVS: tag r21-2-39
cvs
parents: 446
diff changeset
1909 to include @file{symsinit.h} directly, because it is included by
3078fd1074e8 Import from CVS: tag r21-2-39
cvs
parents: 446
diff changeset
1910 @file{lisp.h}.
3078fd1074e8 Import from CVS: tag r21-2-39
cvs
parents: 446
diff changeset
1911
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1912 @strong{All global and static variables that are to be modifiable must
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1913 be declared uninitialized.} This means that you may not use the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1914 ``declare with initializer'' form for these variables, such as @code{int
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1915 some_variable = 0;}. The reason for this has to do with some kludges
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1916 done during the dumping process: If possible, the initialized data
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1917 segment is re-mapped so that it becomes part of the (unmodifiable) code
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1918 segment in the dumped executable. This allows this memory to be shared
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1919 among multiple running XEmacs processes. XEmacs is careful to place as
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1920 much constant data as possible into initialized variables during the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1921 @file{temacs} phase.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1922
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1923 @cindex copy-on-write
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1924 @strong{Please note:} This kludge only works on a few systems nowadays,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1925 and is rapidly becoming irrelevant because most modern operating systems
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1926 provide @dfn{copy-on-write} semantics. All data is initially shared
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1927 between processes, and a private copy is automatically made (on a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1928 page-by-page basis) when a process first attempts to write to a page of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1929 memory.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1930
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1931 Formerly, there was a requirement that static variables not be declared
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1932 inside of functions. This had to do with another hack along the same
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1933 vein as what was just described: old USG systems put statically-declared
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1934 variables in the initialized data space, so those header files had a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1935 @code{#define static} declaration. (That way, the data-segment remapping
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1936 described above could still work.) This fails badly on static variables
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1937 inside of functions, which suddenly become automatic variables;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1938 therefore, you weren't supposed to have any of them. This awful kludge
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1939 has been removed in XEmacs because
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1940
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1941 @enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1942 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1943 almost all of the systems that used this kludge ended up having
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1944 to disable the data-segment remapping anyway;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1945 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1946 the only systems that didn't were extremely outdated ones;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1947 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1948 this hack completely messed up inline functions.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1949 @end enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1950
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1951 The C source code makes heavy use of C preprocessor macros. One popular
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1952 macro style is:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1953
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1954 @example
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
1955 #define FOO(var, value) do @{ \
440
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 438
diff changeset
1956 Lisp_Object FOO_value = (value); \
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 438
diff changeset
1957 ... /* compute using FOO_value */ \
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 438
diff changeset
1958 (var) = bar; \
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1959 @} while (0)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1960 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1961
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1962 The @code{do @{...@} while (0)} is a standard trick to allow FOO to have
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1963 statement semantics, so that it can safely be used within an @code{if}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1964 statement in C, for example. Multiple evaluation is prevented by
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1965 copying a supplied argument into a local variable, so that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1966 @code{FOO(var,fun(1))} only calls @code{fun} once.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1967
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1968 Lisp lists are popular data structures in the C code as well as in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1969 Elisp. There are two sets of macros that iterate over lists.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1970 @code{EXTERNAL_LIST_LOOP_@var{n}} should be used when the list has been
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1971 supplied by the user, and cannot be trusted to be acyclic and
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 442
diff changeset
1972 @code{nil}-terminated. A @code{malformed-list} or @code{circular-list} error
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1973 will be generated if the list being iterated over is not entirely
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1974 kosher. @code{LIST_LOOP_@var{n}}, on the other hand, is faster and less
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1975 safe, and can be used only on trusted lists.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1976
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1977 Related macros are @code{GET_EXTERNAL_LIST_LENGTH} and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1978 @code{GET_LIST_LENGTH}, which calculate the length of a list, and in the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1979 case of @code{GET_EXTERNAL_LIST_LENGTH}, validating the properness of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1980 the list. The macros @code{EXTERNAL_LIST_LOOP_DELETE_IF} and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1981 @code{LIST_LOOP_DELETE_IF} delete elements from a lisp list satisfying some
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1982 predicate.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1983
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
1984 @node Writing Lisp Primitives
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1985 @section Writing Lisp Primitives
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
1986 @cindex writing Lisp primitives
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
1987 @cindex Lisp primitives, writing
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
1988 @cindex primitives, writing Lisp
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1989
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1990 Lisp primitives are Lisp functions implemented in C. The details of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1991 interfacing the C function so that Lisp can call it are handled by a few
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1992 C macros. The only way to really understand how to write new C code is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1993 to read the source, but we can explain some things here.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1994
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1995 An example of a special form is the definition of @code{prog1}, from
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1996 @file{eval.c}. (An ordinary function would have the same general
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1997 appearance.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1998
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1999 @cindex garbage collection protection
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2000 @smallexample
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2001 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2002 DEFUN ("prog1", Fprog1, 1, UNEVALLED, 0, /*
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2003 Similar to `progn', but the value of the first form is returned.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2004 \(prog1 FIRST BODY...): All the arguments are evaluated sequentially.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2005 The value of FIRST is saved during evaluation of the remaining args,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2006 whose values are discarded.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2007 */
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2008 (args))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2009 @{
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2010 /* This function can GC */
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2011 REGISTER Lisp_Object val, form, tail;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2012 struct gcpro gcpro1;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2013
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2014 val = Feval (XCAR (args));
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2015
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2016 GCPRO1 (val);
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2017
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2018 LIST_LOOP_3 (form, XCDR (args), tail)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2019 Feval (form);
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2020
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2021 UNGCPRO;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2022 return val;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2023 @}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2024 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2025 @end smallexample
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2026
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2027 Let's start with a precise explanation of the arguments to the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2028 @code{DEFUN} macro. Here is a template for them:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2029
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2030 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2031 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2032 DEFUN (@var{lname}, @var{fname}, @var{min_args}, @var{max_args}, @var{interactive}, /*
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2033 @var{docstring}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2034 */
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2035 (@var{arglist}))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2036 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2037 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2038
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2039 @table @var
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2040 @item lname
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2041 This string is the name of the Lisp symbol to define as the function
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2042 name; in the example above, it is @code{"prog1"}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2043
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2044 @item fname
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2045 This is the C function name for this function. This is the name that is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2046 used in C code for calling the function. The name is, by convention,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2047 @samp{F} prepended to the Lisp name, with all dashes (@samp{-}) in the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2048 Lisp name changed to underscores. Thus, to call this function from C
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2049 code, call @code{Fprog1}. Remember that the arguments are of type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2050 @code{Lisp_Object}; various macros and functions for creating values of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2051 type @code{Lisp_Object} are declared in the file @file{lisp.h}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2052
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2053 Primitives whose names are special characters (e.g. @code{+} or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2054 @code{<}) are named by spelling out, in some fashion, the special
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2055 character: e.g. @code{Fplus()} or @code{Flss()}. Primitives whose names
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2056 begin with normal alphanumeric characters but also contain special
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2057 characters are spelled out in some creative way, e.g. @code{let*}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2058 becomes @code{FletX()}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2059
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2060 Each function also has an associated structure that holds the data for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2061 the subr object that represents the function in Lisp. This structure
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2062 conveys the Lisp symbol name to the initialization routine that will
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2063 create the symbol and store the subr object as its definition. The C
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2064 variable name of this structure is always @samp{S} prepended to the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2065 @var{fname}. You hardly ever need to be aware of the existence of this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2066 structure, since @code{DEFUN} plus @code{DEFSUBR} takes care of all the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2067 details.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2068
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2069 @item min_args
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2070 This is the minimum number of arguments that the function requires. The
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2071 function @code{prog1} allows a minimum of one argument.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2072
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2073 @item max_args
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2074 This is the maximum number of arguments that the function accepts, if
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2075 there is a fixed maximum. Alternatively, it can be @code{UNEVALLED},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2076 indicating a special form that receives unevaluated arguments, or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2077 @code{MANY}, indicating an unlimited number of evaluated arguments (the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2078 C equivalent of @code{&rest}). Both @code{UNEVALLED} and @code{MANY}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2079 are macros. If @var{max_args} is a number, it may not be less than
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2080 @var{min_args} and it may not be greater than 8. (If you need to add a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2081 function with more than 8 arguments, use the @code{MANY} form. Resist
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2082 the urge to edit the definition of @code{DEFUN} in @file{lisp.h}. If
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2083 you do it anyways, make sure to also add another clause to the switch
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2084 statement in @code{primitive_funcall().})
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2085
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2086 @item interactive
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2087 This is an interactive specification, a string such as might be used as
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2088 the argument of @code{interactive} in a Lisp function. In the case of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2089 @code{prog1}, it is 0 (a null pointer), indicating that @code{prog1}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2090 cannot be called interactively. A value of @code{""} indicates a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2091 function that should receive no arguments when called interactively.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2092
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2093 @item docstring
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2094 This is the documentation string. It is written just like a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2095 documentation string for a function defined in Lisp; in particular, the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2096 first line should be a single sentence. Note how the documentation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2097 string is enclosed in a comment, none of the documentation is placed on
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2098 the same lines as the comment-start and comment-end characters, and the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2099 comment-start characters are on the same line as the interactive
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2100 specification. @file{make-docfile}, which scans the C files for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2101 documentation strings, is very particular about what it looks for, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2102 will not properly extract the doc string if it's not in this exact format.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2103
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2104 In order to make both @file{etags} and @file{make-docfile} happy, make
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2105 sure that the @code{DEFUN} line contains the @var{lname} and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2106 @var{fname}, and that the comment-start characters for the doc string
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2107 are on the same line as the interactive specification, and put a newline
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2108 directly after them (and before the comment-end characters).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2109
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2110 @item arglist
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2111 This is the comma-separated list of arguments to the C function. For a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2112 function with a fixed maximum number of arguments, provide a C argument
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2113 for each Lisp argument. In this case, unlike regular C functions, the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2114 types of the arguments are not declared; they are simply always of type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2115 @code{Lisp_Object}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2116
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2117 The names of the C arguments will be used as the names of the arguments
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2118 to the Lisp primitive as displayed in its documentation, modulo the same
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2119 concerns described above for @code{F...} names (in particular,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2120 underscores in the C arguments become dashes in the Lisp arguments).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2121
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2122 There is one additional kludge: A trailing `_' on the C argument is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2123 discarded when forming the Lisp argument. This allows C language
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2124 reserved words (like @code{default}) or global symbols (like
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2125 @code{dirname}) to be used as argument names without compiler warnings
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2126 or errors.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2127
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2128 A Lisp function with @w{@var{max_args} = @code{UNEVALLED}} is a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2129 @w{@dfn{special form}}; its arguments are not evaluated. Instead it
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2130 receives one argument of type @code{Lisp_Object}, a (Lisp) list of the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2131 unevaluated arguments, conventionally named @code{(args)}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2132
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2133 When a Lisp function has no upper limit on the number of arguments,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2134 specify @w{@var{max_args} = @code{MANY}}. In this case its implementation in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2135 C actually receives exactly two arguments: the number of Lisp arguments
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2136 (an @code{int}) and the address of a block containing their values (a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2137 @w{@code{Lisp_Object *}}). In this case only are the C types specified
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2138 in the @var{arglist}: @w{@code{(int nargs, Lisp_Object *args)}}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2139
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2140 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2141
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2142 Within the function @code{Fprog1} itself, note the use of the macros
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2143 @code{GCPRO1} and @code{UNGCPRO}. @code{GCPRO1} is used to ``protect''
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2144 a variable from garbage collection---to inform the garbage collector
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2145 that it must look in that variable and regard the object pointed at by
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2146 its contents as an accessible object. This is necessary whenever you
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2147 call @code{Feval} or anything that can directly or indirectly call
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2148 @code{Feval} (this includes the @code{QUIT} macro!). At such a time,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2149 any Lisp object that you intend to refer to again must be protected
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2150 somehow. @code{UNGCPRO} cancels the protection of the variables that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2151 are protected in the current function. It is necessary to do this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2152 explicitly.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2153
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2154 The macro @code{GCPRO1} protects just one local variable. If you want
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2155 to protect two, use @code{GCPRO2} instead; repeating @code{GCPRO1} will
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2156 not work. Macros @code{GCPRO3} and @code{GCPRO4} also exist.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2157
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2158 These macros implicitly use local variables such as @code{gcpro1}; you
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2159 must declare these explicitly, with type @code{struct gcpro}. Thus, if
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2160 you use @code{GCPRO2}, you must declare @code{gcpro1} and @code{gcpro2}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2161
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2162 @cindex caller-protects (@code{GCPRO} rule)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2163 Note also that the general rule is @dfn{caller-protects}; i.e. you are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2164 only responsible for protecting those Lisp objects that you create. Any
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2165 objects passed to you as arguments should have been protected by whoever
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2166 created them, so you don't in general have to protect them.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2167
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2168 In particular, the arguments to any Lisp primitive are always
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2169 automatically @code{GCPRO}ed, when called ``normally'' from Lisp code or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2170 bytecode. So only a few Lisp primitives that are called frequently from
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2171 C code, such as @code{Fprogn} protect their arguments as a service to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2172 their caller. You don't need to protect your arguments when writing a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2173 new @code{DEFUN}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2174
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2175 @code{GCPRO}ing is perhaps the trickiest and most error-prone part of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2176 XEmacs coding. It is @strong{extremely} important that you get this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2177 right and use a great deal of discipline when writing this code.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2178 @xref{GCPROing, ,@code{GCPRO}ing}, for full details on how to do this.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2179
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2180 What @code{DEFUN} actually does is declare a global structure of type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2181 @code{Lisp_Subr} whose name begins with capital @samp{SF} and which
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2182 contains information about the primitive (e.g. a pointer to the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2183 function, its minimum and maximum allowed arguments, a string describing
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2184 its Lisp name); @code{DEFUN} then begins a normal C function declaration
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2185 using the @code{F...} name. The Lisp subr object that is the function
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2186 definition of a primitive (i.e. the object in the function slot of the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2187 symbol that names the primitive) actually points to this @samp{SF}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2188 structure; when @code{Feval} encounters a subr, it looks in the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2189 structure to find out how to call the C function.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2190
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2191 Defining the C function is not enough to make a Lisp primitive
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2192 available; you must also create the Lisp symbol for the primitive (the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2193 symbol is @dfn{interned}; @pxref{Obarrays}) and store a suitable subr
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2194 object in its function cell. (If you don't do this, the primitive won't
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2195 be seen by Lisp code.) The code looks like this:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2196
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2197 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2198 DEFSUBR (@var{fname});
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2199 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2200
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2201 @noindent
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2202 Here @var{fname} is the same name you used as the second argument to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2203 @code{DEFUN}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2204
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2205 This call to @code{DEFSUBR} should go in the @code{syms_of_*()} function
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2206 at the end of the module. If no such function exists, create it and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2207 make sure to also declare it in @file{symsinit.h} and call it from the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2208 appropriate spot in @code{main()}. @xref{General Coding Rules}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2209
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2210 Note that C code cannot call functions by name unless they are defined
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2211 in C. The way to call a function written in Lisp from C is to use
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2212 @code{Ffuncall}, which embodies the Lisp function @code{funcall}. Since
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2213 the Lisp function @code{funcall} accepts an unlimited number of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2214 arguments, in C it takes two: the number of Lisp-level arguments, and a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2215 one-dimensional array containing their values. The first Lisp-level
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2216 argument is the Lisp function to call, and the rest are the arguments to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2217 pass to it. Since @code{Ffuncall} can call the evaluator, you must
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2218 protect pointers from garbage collection around the call to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2219 @code{Ffuncall}. (However, @code{Ffuncall} explicitly protects all of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2220 its parameters, so you don't have to protect any pointers passed as
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2221 parameters to it.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2222
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2223 The C functions @code{call0}, @code{call1}, @code{call2}, and so on,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2224 provide handy ways to call a Lisp function conveniently with a fixed
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2225 number of arguments. They work by calling @code{Ffuncall}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2226
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2227 @file{eval.c} is a very good file to look through for examples;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2228 @file{lisp.h} contains the definitions for important macros and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2229 functions.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2230
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2231 @node Writing Good Comments
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2232 @section Writing Good Comments
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2233 @cindex writing good comments
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2234 @cindex comments, writing good
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2235
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2236 Comments are a lifeline for programmers trying to understand tricky
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2237 code. In general, the less obvious it is what you are doing, the more
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2238 you need a comment, and the more detailed it needs to be. You should
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2239 always be on guard when you're writing code for stuff that's tricky, and
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2240 should constantly be putting yourself in someone else's shoes and asking
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2241 if that person could figure out without much difficulty what's going
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2242 on. (Assume they are a competent programmer who understands the
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2243 essentials of how the XEmacs code is structured but doesn't know much
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2244 about the module you're working on or any algorithms you're using.) If
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2245 you're not sure whether they would be able to, add a comment. Always
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2246 err on the side of more comments, rather than less.
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2247
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2248 Generally, when making comments, there is no need to attribute them with
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2249 your name or initials. This especially goes for small,
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2250 easy-to-understand, non-opinionated ones. Also, comments indicating
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2251 where, when, and by whom a file was changed are @emph{strongly}
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2252 discouraged, and in general will be removed as they are discovered.
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2253 This is exactly what @file{ChangeLogs} are there for. However, it can
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2254 occasionally be useful to mark exactly where (but not when or by whom)
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2255 changes are made, particularly when making small changes to a file
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2256 imported from elsewhere. These marks help when later on a newer version
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2257 of the file is imported and the changes need to be merged. (If
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2258 everything were always kept in CVS, there would be no need for this.
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2259 But in practice, this often doesn't happen, or the CVS repository is
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2260 later on lost or unavailable to the person doing the update.)
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2261
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2262 When putting in an explicit opinion in a comment, you should
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2263 @emph{always} attribute it with your name, and optionally the date.
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2264 This also goes for long, complex comments explaining in detail the
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2265 workings of something -- by putting your name there, you make it
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2266 possible for someone who has questions about how that thing works to
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2267 determine who wrote the comment so they can write to them. Preferably,
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2268 use your actual name and not your initials, unless your initials are
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2269 generally recognized (e.g. @samp{jwz}). You can use only your first
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2270 name if it's obvious who you are; otherwise, give first and last name.
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2271 If you're not a regular contributor, you might consider putting your
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2272 email address in -- it may be in the ChangeLog, but after awhile
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2273 ChangeLogs have a tendency of disappearing or getting
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2274 muddled. (E.g. your comment may get copied somewhere else or even into
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2275 another program, and tracking down the proper ChangeLog may be very
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2276 difficult.)
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2277
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2278 If you come across an opinion that is not or no longer valid, or you
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2279 come across any comment that no longer applies but you want to keep it
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2280 around, enclose it in @samp{[[ } and @samp{ ]]} marks and add a comment
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2281 afterwards explaining why the preceding comment is no longer valid. Put
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2282 your name on this comment, as explained above.
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2283
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2284 Just as comments are a lifeline to programmers, incorrect comments are
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2285 death. If you come across an incorrect comment, @strong{immediately}
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2286 correct it or flag it as incorrect, as described in the previous
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2287 paragraph. Whenever you work on a section of code, @emph{always} make
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2288 sure to update any comments to be correct -- or, at the very least, flag
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2289 them as incorrect.
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2290
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2291 To indicate a "todo" or other problem, use four pound signs --
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2292 i.e. @samp{####}.
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2293
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2294 @node Adding Global Lisp Variables
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2295 @section Adding Global Lisp Variables
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2296 @cindex global Lisp variables, adding
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2297 @cindex variables, adding global Lisp
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2298
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2299 Global variables whose names begin with @samp{Q} are constants whose
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2300 value is a symbol of a particular name. The name of the variable should
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2301 be derived from the name of the symbol using the same rules as for Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2302 primitives. These variables are initialized using a call to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2303 @code{defsymbol()} in the @code{syms_of_*()} function. (This call
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2304 interns a symbol, sets the C variable to the resulting Lisp object, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2305 calls @code{staticpro()} on the C variable to tell the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2306 garbage-collection mechanism about this variable. What
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2307 @code{staticpro()} does is add a pointer to the variable to a large
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2308 global array; when garbage-collection happens, all pointers listed in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2309 the array are used as starting points for marking Lisp objects. This is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2310 important because it's quite possible that the only current reference to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2311 the object is the C variable. In the case of symbols, the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2312 @code{staticpro()} doesn't matter all that much because the symbol is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2313 contained in @code{obarray}, which is itself @code{staticpro()}ed.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2314 However, it's possible that a naughty user could do something like
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2315 uninterning the symbol out of @code{obarray} or even setting
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2316 @code{obarray} to a different value [although this is likely to make
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2317 XEmacs crash!].)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2318
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2319 @strong{Please note:} It is potentially deadly if you declare a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2320 @samp{Q...} variable in two different modules. The two calls to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2321 @code{defsymbol()} are no problem, but some linkers will complain about
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2322 multiply-defined symbols. The most insidious aspect of this is that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2323 often the link will succeed anyway, but then the resulting executable
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2324 will sometimes crash in obscure ways during certain operations! To
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2325 avoid this problem, declare any symbols with common names (such as
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2326 @code{text}) that are not obviously associated with this particular
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2327 module in the module @file{general.c}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2328
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2329 Global variables whose names begin with @samp{V} are variables that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2330 contain Lisp objects. The convention here is that all global variables
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2331 of type @code{Lisp_Object} begin with @samp{V}, and all others don't
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2332 (including integer and boolean variables that have Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2333 equivalents). Most of the time, these variables have equivalents in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2334 Lisp, but some don't. Those that do are declared this way by a call to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2335 @code{DEFVAR_LISP()} in the @code{vars_of_*()} initializer for the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2336 module. What this does is create a special @dfn{symbol-value-forward}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2337 Lisp object that contains a pointer to the C variable, intern a symbol
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2338 whose name is as specified in the call to @code{DEFVAR_LISP()}, and set
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2339 its value to the symbol-value-forward Lisp object; it also calls
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2340 @code{staticpro()} on the C variable to tell the garbage-collection
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2341 mechanism about the variable. When @code{eval} (or actually
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2342 @code{symbol-value}) encounters this special object in the process of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2343 retrieving a variable's value, it follows the indirection to the C
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2344 variable and gets its value. @code{setq} does similar things so that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2345 the C variable gets changed.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2346
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2347 Whether or not you @code{DEFVAR_LISP()} a variable, you need to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2348 initialize it in the @code{vars_of_*()} function; otherwise it will end
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2349 up as all zeroes, which is the integer 0 (@emph{not} @code{nil}), and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2350 this is probably not what you want. Also, if the variable is not
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2351 @code{DEFVAR_LISP()}ed, @strong{you must call} @code{staticpro()} on the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2352 C variable in the @code{vars_of_*()} function. Otherwise, the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2353 garbage-collection mechanism won't know that the object in this variable
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2354 is in use, and will happily collect it and reuse its storage for another
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2355 Lisp object, and you will be the one who's unhappy when you can't figure
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2356 out how your variable got overwritten.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2357
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2358 @node Proper Use of Unsigned Types
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2359 @section Proper Use of Unsigned Types
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2360 @cindex unsigned types, proper use of
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2361 @cindex types, proper use of unsigned
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2362
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2363 Avoid using @code{unsigned int} and @code{unsigned long} whenever
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2364 possible. Unsigned types are viral -- any arithmetic or comparisons
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2365 involving mixed signed and unsigned types are automatically converted to
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2366 unsigned, which is almost certainly not what you want. Many subtle and
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2367 hard-to-find bugs are created by careless use of unsigned types. In
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2368 general, you should almost @emph{never} use an unsigned type to hold a
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2369 regular quantity of any sort. The only exceptions are
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2370
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2371 @enumerate
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2372 @item
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2373 When there's a reasonable possibility you will actually need all 32 or
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2374 64 bits to store the quantity.
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2375 @item
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2376 When calling existing API's that require unsigned types. In this case,
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2377 you should still do all manipulation using signed types, and do the
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2378 conversion at the very threshold of the API call.
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2379 @item
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2380 In existing code that you don't want to modify because you don't
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2381 maintain it.
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2382 @item
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2383 In bit-field structures.
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2384 @end enumerate
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2385
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2386 Other reasonable uses of @code{unsigned int} and @code{unsigned long}
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2387 are representing non-quantities -- e.g. bit-oriented flags and such.
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2388
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2389 @node Coding for Mule
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2390 @section Coding for Mule
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2391 @cindex coding for Mule
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2392 @cindex Mule, coding for
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2393
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2394 Although Mule support is not compiled by default in XEmacs, many people
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2395 are using it, and we consider it crucial that new code works correctly
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2396 with multibyte characters. This is not hard; it is only a matter of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2397 following several simple user-interface guidelines. Even if you never
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2398 compile with Mule, with a little practice you will find it quite easy
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2399 to code Mule-correctly.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2400
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2401 Note that these guidelines are not necessarily tied to the current Mule
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2402 implementation; they are also a good idea to follow on the grounds of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2403 code generalization for future I18N work.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2404
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2405 @menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2406 * Character-Related Data Types::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2407 * Working With Character and Byte Positions::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2408 * Conversion to and from External Data::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2409 * General Guidelines for Writing Mule-Aware Code::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2410 * An Example of Mule-Aware Code::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2411 @end menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2412
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2413 @node Character-Related Data Types
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2414 @subsection Character-Related Data Types
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2415 @cindex character-related data types
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2416 @cindex data types, character-related
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2417
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2418 First, let's review the basic character-related datatypes used by
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2419 XEmacs. Note that the separate @code{typedef}s are not mandatory in the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2420 current implementation (all of them boil down to @code{unsigned char} or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2421 @code{int}), but they improve clarity of code a great deal, because one
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2422 glance at the declaration can tell the intended use of the variable.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2423
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2424 @table @code
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2425 @item Emchar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2426 @cindex Emchar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2427 An @code{Emchar} holds a single Emacs character.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2429 Obviously, the equality between characters and bytes is lost in the Mule
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2430 world. Characters can be represented by one or more bytes in the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2431 buffer, and @code{Emchar} is the C type large enough to hold any
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2432 character.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2433
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2434 Without Mule support, an @code{Emchar} is equivalent to an
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2435 @code{unsigned char}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2436
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2437 @item Bufbyte
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2438 @cindex Bufbyte
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2439 The data representing the text in a buffer or string is logically a set
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2440 of @code{Bufbyte}s.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2441
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2442 XEmacs does not work with the same character formats all the time; when
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2443 reading characters from the outside, it decodes them to an internal
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2444 format, and likewise encodes them when writing. @code{Bufbyte} (in fact
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2445 @code{unsigned char}) is the basic unit of XEmacs internal buffers and
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2446 strings format. A @code{Bufbyte *} is the type that points at text
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2447 encoded in the variable-width internal encoding.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2448
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2449 One character can correspond to one or more @code{Bufbyte}s. In the
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2450 current Mule implementation, an ASCII character is represented by the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2451 same @code{Bufbyte}, and other characters are represented by a sequence
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2452 of two or more @code{Bufbyte}s.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2453
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2454 Without Mule support, there are exactly 256 characters, implicitly
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2455 Latin-1, and each character is represented using one @code{Bufbyte}, and
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2456 there is a one-to-one correspondence between @code{Bufbyte}s and
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2457 @code{Emchar}s.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2458
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2459 @item Bufpos
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2460 @itemx Charcount
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2461 @cindex Bufpos
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2462 @cindex Charcount
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2463 A @code{Bufpos} represents a character position in a buffer or string.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2464 A @code{Charcount} represents a number (count) of characters.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2465 Logically, subtracting two @code{Bufpos} values yields a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2466 @code{Charcount} value. Although all of these are @code{typedef}ed to
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2467 @code{EMACS_INT}, we use them in preference to @code{EMACS_INT} to make
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2468 it clear what sort of position is being used.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2469
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2470 @code{Bufpos} and @code{Charcount} values are the only ones that are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2471 ever visible to Lisp.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2472
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2473 @item Bytind
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2474 @itemx Bytecount
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2475 @cindex Bytind
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2476 @cindex Bytecount
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2477 A @code{Bytind} represents a byte position in a buffer or string. A
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2478 @code{Bytecount} represents the distance between two positions, in bytes.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2479 The relationship between @code{Bytind} and @code{Bytecount} is the same
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2480 as the relationship between @code{Bufpos} and @code{Charcount}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2481
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2482 @item Extbyte
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2483 @itemx Extcount
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2484 @cindex Extbyte
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2485 @cindex Extcount
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2486 When dealing with the outside world, XEmacs works with @code{Extbyte}s,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2487 which are equivalent to @code{unsigned char}. Obviously, an
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2488 @code{Extcount} is the distance between two @code{Extbyte}s. Extbytes
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2489 and Extcounts are not all that frequent in XEmacs code.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2490 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2491
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2492 @node Working With Character and Byte Positions
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2493 @subsection Working With Character and Byte Positions
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2494 @cindex character and byte positions, working with
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2495 @cindex byte positions, working with character and
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2496 @cindex positions, working with character and byte
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2497
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2498 Now that we have defined the basic character-related types, we can look
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2499 at the macros and functions designed for work with them and for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2500 conversion between them. Most of these macros are defined in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2501 @file{buffer.h}, and we don't discuss all of them here, but only the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2502 most important ones. Examining the existing code is the best way to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2503 learn about them.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2504
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2505 @table @code
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2506 @item MAX_EMCHAR_LEN
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2507 @cindex MAX_EMCHAR_LEN
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2508 This preprocessor constant is the maximum number of buffer bytes to
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2509 represent an Emacs character in the variable width internal encoding.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2510 It is useful when allocating temporary strings to keep a known number of
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2511 characters. For instance:
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2512
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2513 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2514 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2515 @{
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2516 Charcount cclen;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2517 ...
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2518 @{
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2519 /* Allocate place for @var{cclen} characters. */
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2520 Bufbyte *buf = (Bufbyte *)alloca (cclen * MAX_EMCHAR_LEN);
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2521 ...
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2522 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2523 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2524
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2525 If you followed the previous section, you can guess that, logically,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2526 multiplying a @code{Charcount} value with @code{MAX_EMCHAR_LEN} produces
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2527 a @code{Bytecount} value.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2528
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2529 In the current Mule implementation, @code{MAX_EMCHAR_LEN} equals 4.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2530 Without Mule, it is 1.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2531
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2532 @item charptr_emchar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2533 @itemx set_charptr_emchar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2534 @cindex charptr_emchar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2535 @cindex set_charptr_emchar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2536 The @code{charptr_emchar} macro takes a @code{Bufbyte} pointer and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2537 returns the @code{Emchar} stored at that position. If it were a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2538 function, its prototype would be:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2539
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2540 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2541 Emchar charptr_emchar (Bufbyte *p);
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2542 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2543
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2544 @code{set_charptr_emchar} stores an @code{Emchar} to the specified byte
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2545 position. It returns the number of bytes stored:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2546
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2547 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2548 Bytecount set_charptr_emchar (Bufbyte *p, Emchar c);
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2549 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2550
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2551 It is important to note that @code{set_charptr_emchar} is safe only for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2552 appending a character at the end of a buffer, not for overwriting a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2553 character in the middle. This is because the width of characters
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2554 varies, and @code{set_charptr_emchar} cannot resize the string if it
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2555 writes, say, a two-byte character where a single-byte character used to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2556 reside.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2557
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2558 A typical use of @code{set_charptr_emchar} can be demonstrated by this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2559 example, which copies characters from buffer @var{buf} to a temporary
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2560 string of Bufbytes.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2561
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2562 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2563 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2564 @{
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2565 Bufpos pos;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2566 for (pos = beg; pos < end; pos++)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2567 @{
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2568 Emchar c = BUF_FETCH_CHAR (buf, pos);
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2569 p += set_charptr_emchar (buf, c);
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2570 @}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2571 @}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2572 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2573 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2574
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2575 Note how @code{set_charptr_emchar} is used to store the @code{Emchar}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2576 and increment the counter, at the same time.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2577
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2578 @item INC_CHARPTR
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2579 @itemx DEC_CHARPTR
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2580 @cindex INC_CHARPTR
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2581 @cindex DEC_CHARPTR
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2582 These two macros increment and decrement a @code{Bufbyte} pointer,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2583 respectively. They will adjust the pointer by the appropriate number of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2584 bytes according to the byte length of the character stored there. Both
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2585 macros assume that the memory address is located at the beginning of a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2586 valid character.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2587
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2588 Without Mule support, @code{INC_CHARPTR (p)} and @code{DEC_CHARPTR (p)}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2589 simply expand to @code{p++} and @code{p--}, respectively.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2590
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2591 @item bytecount_to_charcount
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2592 @cindex bytecount_to_charcount
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2593 Given a pointer to a text string and a length in bytes, return the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2594 equivalent length in characters.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2595
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2596 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2597 Charcount bytecount_to_charcount (Bufbyte *p, Bytecount bc);
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2598 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2599
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2600 @item charcount_to_bytecount
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2601 @cindex charcount_to_bytecount
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2602 Given a pointer to a text string and a length in characters, return the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2603 equivalent length in bytes.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2604
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2605 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2606 Bytecount charcount_to_bytecount (Bufbyte *p, Charcount cc);
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2607 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2608
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2609 @item charptr_n_addr
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2610 @cindex charptr_n_addr
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2611 Return a pointer to the beginning of the character offset @var{cc} (in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2612 characters) from @var{p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2613
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2614 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2615 Bufbyte *charptr_n_addr (Bufbyte *p, Charcount cc);
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2616 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2617 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2618
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2619 @node Conversion to and from External Data
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2620 @subsection Conversion to and from External Data
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2621 @cindex conversion to and from external data
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2622 @cindex external data, conversion to and from
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2623
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2624 When an external function, such as a C library function, returns a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2625 @code{char} pointer, you should almost never treat it as @code{Bufbyte}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2626 This is because these returned strings may contain 8bit characters which
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2627 can be misinterpreted by XEmacs, and cause a crash. Likewise, when
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2628 exporting a piece of internal text to the outside world, you should
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2629 always convert it to an appropriate external encoding, lest the internal
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2630 stuff (such as the infamous \201 characters) leak out.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2631
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2632 The interface to conversion between the internal and external
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2633 representations of text are the numerous conversion macros defined in
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2634 @file{buffer.h}. There used to be a fixed set of external formats
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2635 supported by these macros, but now any coding system can be used with
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2636 these macros. The coding system alias mechanism is used to create the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2637 following logical coding systems, which replace the fixed external
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2638 formats. The (dontusethis-set-symbol-value-handler) mechanism was
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2639 enhanced to make this possible (more work on that is needed - like
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2640 remove the @code{dontusethis-} prefix).
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2641
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2642 @table @code
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2643 @item Qbinary
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2644 This is the simplest format and is what we use in the absence of a more
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2645 appropriate format. This converts according to the @code{binary} coding
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2646 system:
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2647
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2648 @enumerate a
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2649 @item
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2650 On input, bytes 0--255 are converted into (implicitly Latin-1)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2651 characters 0--255. A non-Mule xemacs doesn't really know about
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2652 different character sets and the fonts to display them, so the bytes can
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2653 be treated as text in different 1-byte encodings by simply setting the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2654 appropriate fonts. So in a sense, non-Mule xemacs is a multi-lingual
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2655 editor if, for example, different fonts are used to display text in
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2656 different buffers, faces, or windows. The specifier mechanism gives the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2657 user complete control over this kind of behavior.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2658 @item
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2659 On output, characters 0--255 are converted into bytes 0--255 and other
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2660 characters are converted into `~'.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2661 @end enumerate
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2662
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2663 @item Qfile_name
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2664 Format used for filenames. This is user-definable via either the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2665 @code{file-name-coding-system} or @code{pathname-coding-system} (now
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2666 obsolete) variables.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2667
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2668 @item Qnative
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2669 Format used for the external Unix environment---@code{argv[]}, stuff
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2670 from @code{getenv()}, stuff from the @file{/etc/passwd} file, etc.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2671 Currently this is the same as Qfile_name. The two should be
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2672 distinguished for clarity and possible future separation.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2673
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2674 @item Qctext
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2675 Compound--text format. This is the standard X11 format used for data
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2676 stored in properties, selections, and the like. This is an 8-bit
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2677 no-lock-shift ISO2022 coding system. This is a real coding system,
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2678 unlike Qfile_name, which is user-definable.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2679 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2680
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2681 There are two fundamental macros to convert between external and
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2682 internal format.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2683
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2684 @code{TO_INTERNAL_FORMAT} converts external data to internal format, and
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2685 @code{TO_EXTERNAL_FORMAT} converts the other way around. The arguments
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2686 each of these receives are a source type, a source, a sink type, a sink,
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2687 and a coding system (or a symbol naming a coding system).
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2688
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2689 A typical call looks like
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2690 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2691 TO_EXTERNAL_FORMAT (LISP_STRING, str, C_STRING_MALLOC, ptr, Qfile_name);
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2692 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2693
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2694 which means that the contents of the lisp string @code{str} are written
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2695 to a malloc'ed memory area which will be pointed to by @code{ptr}, after
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2696 the function returns. The conversion will be done using the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2697 @code{file-name} coding system, which will be controlled by the user
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2698 indirectly by setting or binding the variable
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2699 @code{file-name-coding-system}.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2700
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2701 Some sources and sinks require two C variables to specify. We use some
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2702 preprocessor magic to allow different source and sink types, and even
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2703 different numbers of arguments to specify different types of sources and
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2704 sinks.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2705
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2706 So we can have a call that looks like
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2707 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2708 TO_INTERNAL_FORMAT (DATA, (ptr, len),
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2709 MALLOC, (ptr, len),
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2710 coding_system);
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2711 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2712
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2713 The parenthesized argument pairs are required to make the preprocessor
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2714 magic work.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2715
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2716 Here are the different source and sink types:
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2717
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2718 @table @code
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2719 @item @code{DATA, (ptr, len),}
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2720 input data is a fixed buffer of size @var{len} at address @var{ptr}
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2721 @item @code{ALLOCA, (ptr, len),}
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2722 output data is placed in an alloca()ed buffer of size @var{len} pointed to by @var{ptr}
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2723 @item @code{MALLOC, (ptr, len),}
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2724 output data is in a malloc()ed buffer of size @var{len} pointed to by @var{ptr}
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2725 @item @code{C_STRING_ALLOCA, ptr,}
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2726 equivalent to @code{ALLOCA (ptr, len_ignored)} on output.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2727 @item @code{C_STRING_MALLOC, ptr,}
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2728 equivalent to @code{MALLOC (ptr, len_ignored)} on output
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2729 @item @code{C_STRING, ptr,}
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2730 equivalent to @code{DATA, (ptr, strlen (ptr) + 1)} on input
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2731 @item @code{LISP_STRING, string,}
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2732 input or output is a Lisp_Object of type string
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2733 @item @code{LISP_BUFFER, buffer,}
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2734 output is written to @code{(point)} in lisp buffer @var{buffer}
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2735 @item @code{LISP_LSTREAM, lstream,}
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2736 input or output is a Lisp_Object of type lstream
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2737 @item @code{LISP_OPAQUE, object,}
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2738 input or output is a Lisp_Object of type opaque
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2739 @end table
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2740
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2741 Often, the data is being converted to a '\0'-byte-terminated string,
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2742 which is the format required by many external system C APIs. For these
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2743 purposes, a source type of @code{C_STRING} or a sink type of
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2744 @code{C_STRING_ALLOCA} or @code{C_STRING_MALLOC} is appropriate.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2745 Otherwise, we should try to keep XEmacs '\0'-byte-clean, which means
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2746 using (ptr, len) pairs.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2747
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2748 The sinks to be specified must be lvalues, unless they are the lisp
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2749 object types @code{LISP_LSTREAM} or @code{LISP_BUFFER}.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2750
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2751 For the sink types @code{ALLOCA} and @code{C_STRING_ALLOCA}, the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2752 resulting text is stored in a stack-allocated buffer, which is
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2753 automatically freed on returning from the function. However, the sink
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2754 types @code{MALLOC} and @code{C_STRING_MALLOC} return @code{xmalloc()}ed
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2755 memory. The caller is responsible for freeing this memory using
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2756 @code{xfree()}.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2757
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2758 Note that it doesn't make sense for @code{LISP_STRING} to be a source
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2759 for @code{TO_INTERNAL_FORMAT} or a sink for @code{TO_EXTERNAL_FORMAT}.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2760 You'll get an assertion failure if you try.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2761
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2762
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2763 @node General Guidelines for Writing Mule-Aware Code
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2764 @subsection General Guidelines for Writing Mule-Aware Code
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2765 @cindex writing Mule-aware code, general guidelines for
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2766 @cindex Mule-aware code, general guidelines for writing
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2767 @cindex code, general guidelines for writing Mule-aware
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2768
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2769 This section contains some general guidance on how to write Mule-aware
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2770 code, as well as some pitfalls you should avoid.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2771
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2772 @table @emph
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2773 @item Never use @code{char} and @code{char *}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2774 In XEmacs, the use of @code{char} and @code{char *} is almost always a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2775 mistake. If you want to manipulate an Emacs character from ``C'', use
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2776 @code{Emchar}. If you want to examine a specific octet in the internal
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2777 format, use @code{Bufbyte}. If you want a Lisp-visible character, use a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2778 @code{Lisp_Object} and @code{make_char}. If you want a pointer to move
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2779 through the internal text, use @code{Bufbyte *}. Also note that you
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2780 almost certainly do not need @code{Emchar *}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2781
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2782 @item Be careful not to confuse @code{Charcount}, @code{Bytecount}, and @code{Bufpos}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2783 The whole point of using different types is to avoid confusion about the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2784 use of certain variables. Lest this effect be nullified, you need to be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2785 careful about using the right types.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2786
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2787 @item Always convert external data
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2788 It is extremely important to always convert external data, because
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2789 XEmacs can crash if unexpected 8bit sequences are copied to its internal
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2790 buffers literally.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2791
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2792 This means that when a system function, such as @code{readdir}, returns
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2793 a string, you may need to convert it using one of the conversion macros
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2794 described in the previous chapter, before passing it further to Lisp.
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2795
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2796 Actually, most of the basic system functions that accept '\0'-terminated
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2797 string arguments, like @code{stat()} and @code{open()}, have been
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2798 @strong{encapsulated} so that they are they @code{always} do internal to
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2799 external conversion themselves. This means you must pass internally
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2800 encoded data, typically the @code{XSTRING_DATA} of a Lisp_String to
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2801 these functions. This is actually a design bug, since it unexpectedly
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2802 changes the semantics of the system functions. A better design would be
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2803 to provide separate versions of these system functions that accepted
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2804 Lisp_Objects which were lisp strings in place of their current
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2805 @code{char *} arguments.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2806
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2807 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2808 int stat_lisp (Lisp_Object path, struct stat *buf); /* Implement me */
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2809 @end example
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2810
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2811 Also note that many internal functions, such as @code{make_string},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2812 accept Bufbytes, which removes the need for them to convert the data
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2813 they receive. This increases efficiency because that way external data
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2814 needs to be decoded only once, when it is read. After that, it is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2815 passed around in internal format.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2816 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2817
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2818 @node An Example of Mule-Aware Code
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2819 @subsection An Example of Mule-Aware Code
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2820 @cindex code, an example of Mule-aware
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2821 @cindex Mule-aware code, an example of
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2822
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2823 As an example of Mule-aware code, we will analyze the @code{string}
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2824 function, which conses up a Lisp string from the character arguments it
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2825 receives. Here is the definition, pasted from @code{alloc.c}:
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2826
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2827 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2828 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2829 DEFUN ("string", Fstring, 0, MANY, 0, /*
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2830 Concatenate all the argument characters and make the result a string.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2831 */
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2832 (int nargs, Lisp_Object *args))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2833 @{
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2834 Bufbyte *storage = alloca_array (Bufbyte, nargs * MAX_EMCHAR_LEN);
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2835 Bufbyte *p = storage;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2836
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2837 for (; nargs; nargs--, args++)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2838 @{
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2839 Lisp_Object lisp_char = *args;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2840 CHECK_CHAR_COERCE_INT (lisp_char);
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2841 p += set_charptr_emchar (p, XCHAR (lisp_char));
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2842 @}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2843 return make_string (storage, p - storage);
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2844 @}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2845 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2846 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2847
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2848 Now we can analyze the source line by line.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2849
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2850 Obviously, string will be as long as there are arguments to the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2851 function. This is why we allocate @code{MAX_EMCHAR_LEN} * @var{nargs}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2852 bytes on the stack, i.e. the worst-case number of bytes for @var{nargs}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2853 @code{Emchar}s to fit in the string.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2854
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2855 Then, the loop checks that each element is a character, converting
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2856 integers in the process. Like many other functions in XEmacs, this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2857 function silently accepts integers where characters are expected, for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2858 historical and compatibility reasons. Unless you know what you are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2859 doing, @code{CHECK_CHAR} will also suffice. @code{XCHAR (lisp_char)}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2860 extracts the @code{Emchar} from the @code{Lisp_Object}, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2861 @code{set_charptr_emchar} stores it to storage, increasing @code{p} in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2862 the process.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2863
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2864 Other instructive examples of correct coding under Mule can be found all
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2865 over the XEmacs code. For starters, I recommend
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2866 @code{Fnormalize_menu_item_name} in @file{menubar.c}. After you have
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2867 understood this section of the manual and studied the examples, you can
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2868 proceed writing new Mule-aware code.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2869
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2870 @node Techniques for XEmacs Developers
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2871 @section Techniques for XEmacs Developers
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2872 @cindex techniques for XEmacs developers
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2873 @cindex developers, techniques for XEmacs
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2874
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2875 @cindex Purify
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2876 @cindex Quantify
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2877 To make a purified XEmacs, do: @code{make puremacs}.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2878 To make a quantified XEmacs, do: @code{make quantmacs}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2879
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2880 You simply can't dump Quantified and Purified images (unless using the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2881 portable dumper). Purify gets confused when xemacs frees memory in one
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2882 process that was allocated in a @emph{different} process on a different
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2883 machine!. Run it like so:
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2884 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2885 temacs -batch -l loadup.el run-temacs @var{xemacs-args...}
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2886 @end example
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2887
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2888 @cindex error checking
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2889 Before you go through the trouble, are you compiling with all
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2890 debugging and error-checking off? If not, try that first. Be warned
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2891 that while Quantify is directly responsible for quite a few
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2892 optimizations which have been made to XEmacs, doing a run which
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2893 generates results which can be acted upon is not necessarily a trivial
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2894 task.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2895
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2896 Also, if you're still willing to do some runs make sure you configure
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2897 with the @samp{--quantify} flag. That will keep Quantify from starting
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2898 to record data until after the loadup is completed and will shut off
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2899 recording right before it shuts down (which generates enough bogus data
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2900 to throw most results off). It also enables three additional elisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2901 commands: @code{quantify-start-recording-data},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2902 @code{quantify-stop-recording-data} and @code{quantify-clear-data}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2903
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2904 If you want to make XEmacs faster, target your favorite slow benchmark,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2905 run a profiler like Quantify, @code{gprof}, or @code{tcov}, and figure
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2906 out where the cycles are going. Specific projects:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2907
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2908 @itemize @bullet
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2909 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2910 Make the garbage collector faster. Figure out how to write an
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2911 incremental garbage collector.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2912 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2913 Write a compiler that takes bytecode and spits out C code.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2914 Unfortunately, you will then need a C compiler and a more fully
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2915 developed module system.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2916 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2917 Speed up redisplay.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2918 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2919 Speed up syntax highlighting. Maybe moving some of the syntax
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2920 highlighting capabilities into C would make a difference.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2921 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2922 Implement tail recursion in Emacs Lisp (hard!).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2923 @end itemize
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2924
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2925 Unfortunately, Emacs Lisp is slow, and is going to stay slow. Function
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2926 calls in elisp are especially expensive. Iterating over a long list is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2927 going to be 30 times faster implemented in C than in Elisp.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2928
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2929 Heavily used small code fragments need to be fast. The traditional way
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2930 to implement such code fragments in C is with macros. But macros in C
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2931 are known to be broken.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2932
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2933 @cindex macro hygiene
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2934 Macro arguments that are repeatedly evaluated may suffer from repeated
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2935 side effects or suboptimal performance.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2936
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2937 Variable names used in macros may collide with caller's variables,
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2938 causing (at least) unwanted compiler warnings.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2939
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2940 In order to solve these problems, and maintain statement semantics, one
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2941 should use the @code{do @{ ... @} while (0)} trick while trying to
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2942 reference macro arguments exactly once using local variables.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2943
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2944 Let's take a look at this poor macro definition:
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2945
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2946 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2947 #define MARK_OBJECT(obj) \
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2948 if (!marked_p (obj)) mark_object (obj), did_mark = 1
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2949 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2950
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2951 This macro evaluates its argument twice, and also fails if used like this:
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2952 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2953 if (flag) MARK_OBJECT (obj); else do_something();
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2954 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2955
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2956 A much better definition is
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2957
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2958 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2959 #define MARK_OBJECT(obj) do @{ \
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2960 Lisp_Object mo_obj = (obj); \
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2961 if (!marked_p (mo_obj)) \
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2962 @{ \
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2963 mark_object (mo_obj); \
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2964 did_mark = 1; \
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2965 @} \
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2966 @} while (0)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2967 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2968
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2969 Notice the elimination of double evaluation by using the local variable
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2970 with the obscure name. Writing safe and efficient macros requires great
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2971 care. The one problem with macros that cannot be portably worked around
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2972 is, since a C block has no value, a macro used as an expression rather
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2973 than a statement cannot use the techniques just described to avoid
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2974 multiple evaluation.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2975
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
2976 @cindex inline functions
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2977 In most cases where a macro has function semantics, an inline function
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2978 is a better implementation technique. Modern compiler optimizers tend
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2979 to inline functions even if they have no @code{inline} keyword, and
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2980 configure magic ensures that the @code{inline} keyword can be safely
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2981 used as an additional compiler hint. Inline functions used in a single
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2982 .c files are easy. The function must already be defined to be
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2983 @code{static}. Just add another @code{inline} keyword to the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2984 definition.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2985
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2986 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2987 inline static int
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2988 heavily_used_small_function (int arg)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2989 @{
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2990 ...
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2991 @}
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2992 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2993
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2994 Inline functions in header files are trickier, because we would like to
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2995 make the following optimization if the function is @emph{not} inlined
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2996 (for example, because we're compiling for debugging). We would like the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2997 function to be defined externally exactly once, and each calling
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2998 translation unit would create an external reference to the function,
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
2999 instead of including a definition of the inline function in the object
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3000 code of every translation unit that uses it. This optimization is
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3001 currently only available for gcc. But you don't have to worry about the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3002 trickiness; just define your inline functions in header files using this
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3003 pattern:
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3004
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3005 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3006 INLINE_HEADER int
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3007 i_used_to_be_a_crufty_macro_but_look_at_me_now (int arg);
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3008 INLINE_HEADER int
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3009 i_used_to_be_a_crufty_macro_but_look_at_me_now (int arg)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3010 @{
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3011 ...
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3012 @}
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3013 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3014
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3015 The declaration right before the definition is to prevent warnings when
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3016 compiling with @code{gcc -Wmissing-declarations}. I consider issuing
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3017 this warning for inline functions a gcc bug, but the gcc maintainers disagree.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3018
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
3019 @cindex inline functions, headers
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
3020 @cindex header files, inline functions
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3021 Every header which contains inline functions, either directly by using
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3022 @code{INLINE_HEADER} or indirectly by using @code{DECLARE_LRECORD} must
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3023 be added to @file{inline.c}'s includes to make the optimization
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3024 described above work. (Optimization note: if all INLINE_HEADER
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3025 functions are in fact inlined in all translation units, then the linker
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3026 can just discard @code{inline.o}, since it contains only unreferenced code).
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3027
438
84b14dcb0985 Import from CVS: tag r21-2-27
cvs
parents: 436
diff changeset
3028 To get started debugging XEmacs, take a look at the @file{.gdbinit} and
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3029 @file{.dbxrc} files in the @file{src} directory. See the section in the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3030 XEmacs FAQ on How to Debug an XEmacs problem with a debugger.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3031
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3032 After making source code changes, run @code{make check} to ensure that
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3033 you haven't introduced any regressions. If you want to make xemacs more
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3034 reliable, please improve the test suite in @file{tests/automated}.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3035
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3036 Did you make sure you didn't introduce any new compiler warnings?
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3037
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3038 Before submitting a patch, please try compiling at least once with
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3039
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3040 @example
607
9979b8030c99 [xemacs-hg @ 2001-06-03 14:25:45 by martinb]
martinb
parents: 464
diff changeset
3041 configure --with-mule --use-union-type --error-checking=all
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3042 @end example
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3043
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3044 Here are things to know when you create a new source file:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3045
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3046 @itemize @bullet
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3047 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3048 All @file{.c} files should @code{#include <config.h>} first. Almost all
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3049 @file{.c} files should @code{#include "lisp.h"} second.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3050
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3051 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3052 Generated header files should be included using the @code{#include <...>} syntax,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3053 not the @code{#include "..."} syntax. The generated headers are:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3054
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3055 @file{config.h sheap-adjust.h paths.h Emacs.ad.h}
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3056
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3057 The basic rule is that you should assume builds using @code{--srcdir}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3058 and the @code{#include <...>} syntax needs to be used when the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3059 to-be-included generated file is in a potentially different directory
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3060 @emph{at compile time}. The non-obvious C rule is that @code{#include "..."}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3061 means to search for the included file in the same directory as the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3062 including file, @emph{not} in the current directory.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3063
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3064 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3065 Header files should @emph{not} include @code{<config.h>} and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3066 @code{"lisp.h"}. It is the responsibility of the @file{.c} files that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3067 use it to do so.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3068
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3069 @end itemize
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3070
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
3071 @cindex Lisp object types, creating
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
3072 @cindex creating Lisp object types
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
3073 @cindex object types, creating Lisp
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3074 Here is a checklist of things to do when creating a new lisp object type
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3075 named @var{foo}:
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3076
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3077 @enumerate
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3078 @item
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3079 create @var{foo}.h
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3080 @item
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3081 create @var{foo}.c
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3082 @item
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3083 add definitions of @code{syms_of_@var{foo}}, etc. to @file{@var{foo}.c}
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3084 @item
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3085 add declarations of @code{syms_of_@var{foo}}, etc. to @file{symsinit.h}
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3086 @item
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3087 add calls to @code{syms_of_@var{foo}}, etc. to @file{emacs.c}
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3088 @item
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3089 add definitions of macros like @code{CHECK_@var{FOO}} and
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3090 @code{@var{FOO}P} to @file{@var{foo}.h}
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3091 @item
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3092 add the new type index to @code{enum lrecord_type}
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3093 @item
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3094 add a DEFINE_LRECORD_IMPLEMENTATION call to @file{@var{foo}.c}
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3095 @item
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3096 add an INIT_LRECORD_IMPLEMENTATION call to @code{syms_of_@var{foo}.c}
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3097 @end enumerate
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3098
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3099 @node A Summary of the Various XEmacs Modules, Allocation of Objects in XEmacs Lisp, Rules When Writing New C Code, Top
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3100 @chapter A Summary of the Various XEmacs Modules
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
3101 @cindex modules, a summary of the various XEmacs
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3102
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3103 This is accurate as of XEmacs 20.0.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3104
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3105 @menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3106 * Low-Level Modules::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3107 * Basic Lisp Modules::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3108 * Modules for Standard Editing Operations::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3109 * Editor-Level Control Flow Modules::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3110 * Modules for the Basic Displayable Lisp Objects::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3111 * Modules for other Display-Related Lisp Objects::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3112 * Modules for the Redisplay Mechanism::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3113 * Modules for Interfacing with the File System::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3114 * Modules for Other Aspects of the Lisp Interpreter and Object System::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3115 * Modules for Interfacing with the Operating System::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3116 * Modules for Interfacing with X Windows::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3117 * Modules for Internationalization::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3118 @end menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3119
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
3120 @node Low-Level Modules
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3121 @section Low-Level Modules
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
3122 @cindex low-level modules
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
3123 @cindex modules, low-level
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3124
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3125 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3126 config.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3127 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3128
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3129 This is automatically generated from @file{config.h.in} based on the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3130 results of configure tests and user-selected optional features and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3131 contains preprocessor definitions specifying the nature of the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3132 environment in which XEmacs is being compiled.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3133
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3134
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3135
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3136 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3137 paths.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3138 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3139
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3140 This is automatically generated from @file{paths.h.in} based on supplied
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3141 configure values, and allows for non-standard installed configurations
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3142 of the XEmacs directories. It's currently broken, though.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3143
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3144
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3145
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3146 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3147 emacs.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3148 signal.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3149 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3150
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3151 @file{emacs.c} contains @code{main()} and other code that performs the most
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3152 basic environment initializations and handles shutting down the XEmacs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3153 process (this includes @code{kill-emacs}, the normal way that XEmacs is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3154 exited; @code{dump-emacs}, which is used during the build process to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3155 write out the XEmacs executable; @code{run-emacs-from-temacs}, which can
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3156 be used to start XEmacs directly when temacs has finished loading all
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3157 the Lisp code; and emergency code to handle crashes [XEmacs tries to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3158 auto-save all files before it crashes]).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3159
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3160 Low-level code that directly interacts with the Unix signal mechanism,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3161 however, is in @file{signal.c}. Note that this code does not handle system
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3162 dependencies in interfacing to signals; that is handled using the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3163 @file{syssignal.h} header file, described in section J below.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3164
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3165
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3166
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3167 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3168 unexaix.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3169 unexalpha.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3170 unexapollo.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3171 unexconvex.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3172 unexec.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3173 unexelf.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3174 unexelfsgi.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3175 unexencap.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3176 unexenix.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3177 unexfreebsd.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3178 unexfx2800.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3179 unexhp9k3.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3180 unexhp9k800.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3181 unexmips.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3182 unexnext.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3183 unexsol2.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3184 unexsunos4.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3185 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3186
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3187 These modules contain code dumping out the XEmacs executable on various
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3188 different systems. (This process is highly machine-specific and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3189 requires intimate knowledge of the executable format and the memory map
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3190 of the process.) Only one of these modules is actually used; this is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3191 chosen by @file{configure}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3192
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3193
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3194
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3195 @example
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3196 ecrt0.c
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3197 lastfile.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3198 pre-crt0.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3199 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3200
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3201 These modules are used in conjunction with the dump mechanism. On some
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3202 systems, an alternative version of the C startup code (the actual code
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3203 that receives control from the operating system when the process is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3204 started, and which calls @code{main()}) is required so that the dumping
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3205 process works properly; @file{crt0.c} provides this.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3206
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3207 @file{pre-crt0.c} and @file{lastfile.c} should be the very first and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3208 very last file linked, respectively. (Actually, this is not really true.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3209 @file{lastfile.c} should be after all Emacs modules whose initialized
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3210 data should be made constant, and before all other Emacs files and all
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3211 libraries. In particular, the allocation modules @file{gmalloc.c},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3212 @file{alloca.c}, etc. are normally placed past @file{lastfile.c}, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3213 all of the files that implement Xt widget classes @emph{must} be placed
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3214 after @file{lastfile.c} because they contain various structures that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3215 must be statically initialized and into which Xt writes at various
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3216 times.) @file{pre-crt0.c} and @file{lastfile.c} contain exported symbols
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3217 that are used to determine the start and end of XEmacs' initialized
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3218 data space when dumping.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3219
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3220
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3221
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3222 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3223 alloca.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3224 free-hook.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3225 getpagesize.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3226 gmalloc.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3227 malloc.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3228 mem-limits.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3229 ralloc.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3230 vm-limit.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3231 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3232
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3233 These handle basic C allocation of memory. @file{alloca.c} is an emulation of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3234 the stack allocation function @code{alloca()} on machines that lack
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3235 this. (XEmacs makes extensive use of @code{alloca()} in its code.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3236
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3237 @file{gmalloc.c} and @file{malloc.c} are two implementations of the standard C
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3238 functions @code{malloc()}, @code{realloc()} and @code{free()}. They are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3239 often used in place of the standard system-provided @code{malloc()}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3240 because they usually provide a much faster implementation, at the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3241 expense of additional memory use. @file{gmalloc.c} is a newer implementation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3242 that is much more memory-efficient for large allocations than @file{malloc.c},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3243 and should always be preferred if it works. (At one point, @file{gmalloc.c}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3244 didn't work on some systems where @file{malloc.c} worked; but this should be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3245 fixed now.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3246
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3247 @cindex relocating allocator
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3248 @file{ralloc.c} is the @dfn{relocating allocator}. It provides
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3249 functions similar to @code{malloc()}, @code{realloc()} and @code{free()}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3250 that allocate memory that can be dynamically relocated in memory. The
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3251 advantage of this is that allocated memory can be shuffled around to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3252 place all the free memory at the end of the heap, and the heap can then
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3253 be shrunk, releasing the memory back to the operating system. The use
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3254 of this can be controlled with the configure option @code{--rel-alloc};
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3255 if enabled, memory allocated for buffers will be relocatable, so that if
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3256 a very large file is visited and the buffer is later killed, the memory
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3257 can be released to the operating system. (The disadvantage of this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3258 mechanism is that it can be very slow. On systems with the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3259 @code{mmap()} system call, the XEmacs version of @file{ralloc.c} uses
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3260 this to move memory around without actually having to block-copy it,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3261 which can speed things up; but it can still cause noticeable performance
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3262 degradation.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3263
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3264 @file{free-hook.c} contains some debugging functions for checking for invalid
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3265 arguments to @code{free()}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3266
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3267 @file{vm-limit.c} contains some functions that warn the user when memory is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3268 getting low. These are callback functions that are called by @file{gmalloc.c}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3269 and @file{malloc.c} at appropriate times.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3270
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3271 @file{getpagesize.h} provides a uniform interface for retrieving the size of a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3272 page in virtual memory. @file{mem-limits.h} provides a uniform interface for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3273 retrieving the total amount of available virtual memory. Both are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3274 similar in spirit to the @file{sys*.h} files described in section J, below.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3275
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3276
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3277
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3278 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3279 blocktype.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3280 blocktype.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3281 dynarr.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3282 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3283
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3284 These implement a couple of basic C data types to facilitate memory
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3285 allocation. The @code{Blocktype} type efficiently manages the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3286 allocation of fixed-size blocks by minimizing the number of times that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3287 @code{malloc()} and @code{free()} are called. It allocates memory in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3288 large chunks, subdivides the chunks into blocks of the proper size, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3289 returns the blocks as requested. When blocks are freed, they are placed
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3290 onto a linked list, so they can be efficiently reused. This data type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3291 is not much used in XEmacs currently, because it's a fairly new
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3292 addition.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3293
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3294 @cindex dynamic array
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3295 The @code{Dynarr} type implements a @dfn{dynamic array}, which is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3296 similar to a standard C array but has no fixed limit on the number of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3297 elements it can contain. Dynamic arrays can hold elements of any type,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3298 and when you add a new element, the array automatically resizes itself
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3299 if it isn't big enough. Dynarrs are extensively used in the redisplay
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3300 mechanism.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3301
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3302
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3303
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3304 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3305 inline.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3306 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3307
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3308 This module is used in connection with inline functions (available in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3309 some compilers). Often, inline functions need to have a corresponding
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3310 non-inline function that does the same thing. This module is where they
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3311 reside. It contains no actual code, but defines some special flags that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3312 cause inline functions defined in header files to be rendered as actual
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3313 functions. It then includes all header files that contain any inline
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3314 function definitions, so that each one gets a real function equivalent.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3315
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3316
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3317
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3318 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3319 debug.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3320 debug.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3321 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3322
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3323 These functions provide a system for doing internal consistency checks
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3324 during code development. This system is not currently used; instead the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3325 simpler @code{assert()} macro is used along with the various checks
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3326 provided by the @samp{--error-check-*} configuration options.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3327
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3328
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3329
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3330 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3331 universe.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3332 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3333
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3334 This is not currently used.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3335
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3336
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3337
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
3338 @node Basic Lisp Modules
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3339 @section Basic Lisp Modules
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
3340 @cindex Lisp modules, basic
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
3341 @cindex modules, basic Lisp
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3342
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3343 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3344 lisp-disunion.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3345 lisp-union.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3346 lisp.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3347 lrecord.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3348 symsinit.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3349 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3350
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3351 These are the basic header files for all XEmacs modules. Each module
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3352 includes @file{lisp.h}, which brings the other header files in.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3353 @file{lisp.h} contains the definitions of the structures and extractor
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3354 and constructor macros for the basic Lisp objects and various other
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3355 basic definitions for the Lisp environment, as well as some
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3356 general-purpose definitions (e.g. @code{min()} and @code{max()}).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3357 @file{lisp.h} includes either @file{lisp-disunion.h} or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3358 @file{lisp-union.h}, depending on whether @code{USE_UNION_TYPE} is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3359 defined. These files define the typedef of the Lisp object itself (as
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3360 described above) and the low-level macros that hide the actual
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3361 implementation of the Lisp object. All extractor and constructor macros
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3362 for particular types of Lisp objects are defined in terms of these
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3363 low-level macros.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3364
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3365 As a general rule, all typedefs should go into the typedefs section of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3366 @file{lisp.h} rather than into a module-specific header file even if the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3367 structure is defined elsewhere. This allows function prototypes that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3368 use the typedef to be placed into other header files. Forward structure
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3369 declarations (i.e. a simple declaration like @code{struct foo;} where
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3370 the structure itself is defined elsewhere) should be placed into the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3371 typedefs section as necessary.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3372
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3373 @file{lrecord.h} contains the basic structures and macros that implement
440
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 438
diff changeset
3374 all record-type Lisp objects---i.e. all objects whose type is a field
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3375 in their C structure, which includes all objects except the few most
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3376 basic ones.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3377
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3378 @file{lisp.h} contains prototypes for most of the exported functions in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3379 the various modules. Lisp primitives defined using @code{DEFUN} that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3380 need to be called by C code should be declared using @code{EXFUN}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3381 Other function prototypes should be placed either into the appropriate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3382 section of @code{lisp.h}, or into a module-specific header file,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3383 depending on how general-purpose the function is and whether it has
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3384 special-purpose argument types requiring definitions not in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3385 @file{lisp.h}.) All initialization functions are prototyped in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3386 @file{symsinit.h}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3387
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3388
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3389
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3390 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3391 alloc.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3392 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3393
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3394 The large module @file{alloc.c} implements all of the basic allocation and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3395 garbage collection for Lisp objects. The most commonly used Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3396 objects are allocated in chunks, similar to the Blocktype data type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3397 described above; others are allocated in individually @code{malloc()}ed
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3398 blocks. This module provides the foundation on which all other aspects
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3399 of the Lisp environment sit, and is the first module initialized at
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3400 startup.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3401
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3402 Note that @file{alloc.c} provides a series of generic functions that are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3403 not dependent on any particular object type, and interfaces to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3404 particular types of objects using a standardized interface of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3405 type-specific methods. This scheme is a fundamental principle of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3406 object-oriented programming and is heavily used throughout XEmacs. The
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3407 great advantage of this is that it allows for a clean separation of
440
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 438
diff changeset
3408 functionality into different modules---new classes of Lisp objects, new
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3409 event interfaces, new device types, new stream interfaces, etc. can be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3410 added transparently without affecting code anywhere else in XEmacs.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3411 Because the different subsystems are divided into general and specific
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3412 code, adding a new subtype within a subsystem will in general not
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3413 require changes to the generic subsystem code or affect any of the other
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3414 subtypes in the subsystem; this provides a great deal of robustness to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3415 the XEmacs code.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3416
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3417
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3418 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3419 eval.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3420 backtrace.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3421 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3422
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3423 This module contains all of the functions to handle the flow of control.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3424 This includes the mechanisms of defining functions, calling functions,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3425 traversing stack frames, and binding variables; the control primitives
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3426 and other special forms such as @code{while}, @code{if}, @code{eval},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3427 @code{let}, @code{and}, @code{or}, @code{progn}, etc.; handling of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3428 non-local exits, unwind-protects, and exception handlers; entering the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3429 debugger; methods for the subr Lisp object type; etc. It does
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3430 @emph{not} include the @code{read} function, the @code{print} function,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3431 or the handling of symbols and obarrays.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3432
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3433 @file{backtrace.h} contains some structures related to stack frames and the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3434 flow of control.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3435
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3436
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3437
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3438 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3439 lread.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3440 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3441
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3442 This module implements the Lisp reader and the @code{read} function,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3443 which converts text into Lisp objects, according to the read syntax of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3444 the objects, as described above. This is similar to the parser that is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3445 a part of all compilers.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3446
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3447
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3448
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3449 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3450 print.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3451 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3452
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3453 This module implements the Lisp print mechanism and the @code{print}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3454 function and related functions. This is the inverse of the Lisp reader
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3455 -- it converts Lisp objects to a printed, textual representation.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3456 (Hopefully something that can be read back in using @code{read} to get
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3457 an equivalent object.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3458
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3459
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3460
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3461 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3462 general.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3463 symbols.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3464 symeval.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3465 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3466
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3467 @file{symbols.c} implements the handling of symbols, obarrays, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3468 retrieving the values of symbols. Much of the code is devoted to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3469 handling the special @dfn{symbol-value-magic} objects that define
440
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 438
diff changeset
3470 special types of variables---this includes buffer-local variables,
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3471 variable aliases, variables that forward into C variables, etc. This
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3472 module is initialized extremely early (right after @file{alloc.c}),
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3473 because it is here that the basic symbols @code{t} and @code{nil} are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3474 created, and those symbols are used everywhere throughout XEmacs.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3475
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3476 @file{symeval.h} contains the definitions of symbol structures and the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3477 @code{DEFVAR_LISP()} and related macros for declaring variables.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3478
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3479
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3480
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3481 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3482 data.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3483 floatfns.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3484 fns.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3485 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3486
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3487 These modules implement the methods and standard Lisp primitives for all
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3488 the basic Lisp object types other than symbols (which are described
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3489 above). @file{data.c} contains all the predicates (primitives that return
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3490 whether an object is of a particular type); the integer arithmetic
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3491 functions; and the basic accessor and mutator primitives for the various
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3492 object types. @file{fns.c} contains all the standard predicates for working
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3493 with sequences (where, abstractly speaking, a sequence is an ordered set
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3494 of objects, and can be represented by a list, string, vector, or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3495 bit-vector); it also contains @code{equal}, perhaps on the grounds that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3496 bulk of the operation of @code{equal} is comparing sequences.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3497 @file{floatfns.c} contains methods and primitives for floats and floating-point
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3498 arithmetic.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3499
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3500
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3501
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3502 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3503 bytecode.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3504 bytecode.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3505 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3506
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3507 @file{bytecode.c} implements the byte-code interpreter and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3508 compiled-function objects, and @file{bytecode.h} contains associated
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3509 structures. Note that the byte-code @emph{compiler} is written in Lisp.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3510
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3511
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3512
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3513
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
3514 @node Modules for Standard Editing Operations
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3515 @section Modules for Standard Editing Operations
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
3516 @cindex modules for standard editing operations
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
3517 @cindex editing operations, modules for standard
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3518
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3519 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3520 buffer.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3521 buffer.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3522 bufslots.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3523 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3524
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3525 @file{buffer.c} implements the @dfn{buffer} Lisp object type. This
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3526 includes functions that create and destroy buffers; retrieve buffers by
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3527 name or by other properties; manipulate lists of buffers (remember that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3528 buffers are permanent objects and stored in various ordered lists);
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3529 retrieve or change buffer properties; etc. It also contains the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3530 definitions of all the built-in buffer-local variables (which can be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3531 viewed as buffer properties). It does @emph{not} contain code to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3532 manipulate buffer-local variables (that's in @file{symbols.c}, described
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3533 above); or code to manipulate the text in a buffer.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3534
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3535 @file{buffer.h} defines the structures associated with a buffer and the various
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3536 macros for retrieving text from a buffer and special buffer positions
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3537 (e.g. @code{point}, the default location for text insertion). It also
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3538 contains macros for working with buffer positions and converting between
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3539 their representations as character offsets and as byte offsets (under
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3540 MULE, they are different, because characters can be multi-byte). It is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3541 one of the largest header files.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3542
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3543 @file{bufslots.h} defines the fields in the buffer structure that correspond to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3544 the built-in buffer-local variables. It is its own header file because
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3545 it is included many times in @file{buffer.c}, as a way of iterating over all
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3546 the built-in buffer-local variables.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3547
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3548
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3549
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3550 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3551 insdel.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3552 insdel.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3553 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3554
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3555 @file{insdel.c} contains low-level functions for inserting and deleting text in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3556 a buffer, keeping track of changed regions for use by redisplay, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3557 calling any before-change and after-change functions that may have been
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3558 registered for the buffer. It also contains the actual functions that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3559 convert between byte offsets and character offsets.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3560
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3561 @file{insdel.h} contains associated headers.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3562
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3563
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3564
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3565 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3566 marker.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3567 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3568
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3569 This module implements the @dfn{marker} Lisp object type, which
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3570 conceptually is a pointer to a text position in a buffer that moves
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3571 around as text is inserted and deleted, so as to remain in the same
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3572 relative position. This module doesn't actually move the markers around
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3573 -- that's handled in @file{insdel.c}. This module just creates them and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3574 implements the primitives for working with them. As markers are simple
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3575 objects, this does not entail much.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3576
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3577 Note that the standard arithmetic primitives (e.g. @code{+}) accept
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3578 markers in place of integers and automatically substitute the value of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3579 @code{marker-position} for the marker, i.e. an integer describing the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3580 current buffer position of the marker.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3581
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3582
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3583
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3584 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3585 extents.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3586 extents.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3587 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3588
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3589 This module implements the @dfn{extent} Lisp object type, which is like
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3590 a marker that works over a range of text rather than a single position.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3591 Extents are also much more complex and powerful than markers and have a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3592 more efficient (and more algorithmically complex) implementation. The
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3593 implementation is described in detail in comments in @file{extents.c}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3594
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3595 The code in @file{extents.c} works closely with @file{insdel.c} so that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3596 extents are properly moved around as text is inserted and deleted.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3597 There is also code in @file{extents.c} that provides information needed
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3598 by the redisplay mechanism for efficient operation. (Remember that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3599 extents can have display properties that affect [sometimes drastically,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3600 as in the @code{invisible} property] the display of the text they
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3601 cover.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3602
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3603
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3604
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3605 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3606 editfns.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3607 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3608
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3609 @file{editfns.c} contains the standard Lisp primitives for working with
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3610 a buffer's text, and calls the low-level functions in @file{insdel.c}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3611 It also contains primitives for working with @code{point} (the default
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3612 buffer insertion location).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3613
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3614 @file{editfns.c} also contains functions for retrieving various
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3615 characteristics from the external environment: the current time, the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3616 process ID of the running XEmacs process, the name of the user who ran
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3617 this XEmacs process, etc. It's not clear why this code is in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3618 @file{editfns.c}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3619
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3620
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3621
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3622 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3623 callint.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3624 cmds.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3625 commands.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3626 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3627
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3628 @cindex interactive
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3629 These modules implement the basic @dfn{interactive} commands,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3630 i.e. user-callable functions. Commands, as opposed to other functions,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3631 have special ways of getting their parameters interactively (by querying
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3632 the user), as opposed to having them passed in a normal function
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3633 invocation. Many commands are not really meant to be called from other
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3634 Lisp functions, because they modify global state in a way that's often
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3635 undesired as part of other Lisp functions.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3636
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3637 @file{callint.c} implements the mechanism for querying the user for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3638 parameters and calling interactive commands. The bulk of this module is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3639 code that parses the interactive spec that is supplied with an
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3640 interactive command.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3641
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3642 @file{cmds.c} implements the basic, most commonly used editing commands:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3643 commands to move around the current buffer and insert and delete
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3644 characters. These commands are implemented using the Lisp primitives
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3645 defined in @file{editfns.c}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3646
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3647 @file{commands.h} contains associated structure definitions and prototypes.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3648
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3649
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3650
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3651 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3652 regex.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3653 regex.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3654 search.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3655 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3656
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3657 @file{search.c} implements the Lisp primitives for searching for text in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3658 a buffer, and some of the low-level algorithms for doing this. In
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3659 particular, the fast fixed-string Boyer-Moore search algorithm is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3660 implemented in @file{search.c}. The low-level algorithms for doing
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3661 regular-expression searching, however, are implemented in @file{regex.c}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3662 and @file{regex.h}. These two modules are largely independent of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3663 XEmacs, and are similar to (and based upon) the regular-expression
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3664 routines used in @file{grep} and other GNU utilities.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3665
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3666
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3667
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3668 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3669 doprnt.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3670 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3671
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3672 @file{doprnt.c} implements formatted-string processing, similar to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3673 @code{printf()} command in C.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3674
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3675
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3676
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3677 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3678 undo.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3679 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3680
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3681 This module implements the undo mechanism for tracking buffer changes.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3682 Most of this could be implemented in Lisp.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3683
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3684
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3685
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
3686 @node Editor-Level Control Flow Modules
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3687 @section Editor-Level Control Flow Modules
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
3688 @cindex control flow modules, editor-level
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
3689 @cindex modules, editor-level control flow
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3690
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3691 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3692 event-Xt.c
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3693 event-msw.c
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3694 event-stream.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3695 event-tty.c
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3696 events-mod.h
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3697 gpmevent.c
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3698 gpmevent.h
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3699 events.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3700 events.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3701 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3702
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3703 These implement the handling of events (user input and other system
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3704 notifications).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3705
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3706 @file{events.c} and @file{events.h} define the @dfn{event} Lisp object
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3707 type and primitives for manipulating it.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3708
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3709 @file{event-stream.c} implements the basic functions for working with
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3710 event queues, dispatching an event by looking it up in relevant keymaps
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3711 and such, and handling timeouts; this includes the primitives
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3712 @code{next-event} and @code{dispatch-event}, as well as related
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3713 primitives such as @code{sit-for}, @code{sleep-for}, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3714 @code{accept-process-output}. (@file{event-stream.c} is one of the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3715 hairiest and trickiest modules in XEmacs. Beware! You can easily mess
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3716 things up here.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3717
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3718 @file{event-Xt.c} and @file{event-tty.c} implement the low-level
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3719 interfaces onto retrieving events from Xt (the X toolkit) and from TTY's
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3720 (using @code{read()} and @code{select()}), respectively. The event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3721 interface enforces a clean separation between the specific code for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3722 interfacing with the operating system and the generic code for working
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3723 with events, by defining an API of basic, low-level event methods;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3724 @file{event-Xt.c} and @file{event-tty.c} are two different
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3725 implementations of this API. To add support for a new operating system
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3726 (e.g. NeXTstep), one merely needs to provide another implementation of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3727 those API functions.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3728
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3729 Note that the choice of whether to use @file{event-Xt.c} or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3730 @file{event-tty.c} is made at compile time! Or at the very latest, it
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3731 is made at startup time. @file{event-Xt.c} handles events for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3732 @emph{both} X and TTY frames; @file{event-tty.c} is only used when X
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3733 support is not compiled into XEmacs. The reason for this is that there
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3734 is only one event loop in XEmacs: thus, it needs to be able to receive
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3735 events from all different kinds of frames.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3736
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3737
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3738
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3739 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3740 keymap.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3741 keymap.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3742 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3743
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3744 @file{keymap.c} and @file{keymap.h} define the @dfn{keymap} Lisp object
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3745 type and associated methods and primitives. (Remember that keymaps are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3746 objects that associate event descriptions with functions to be called to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3747 ``execute'' those events; @code{dispatch-event} looks up events in the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3748 relevant keymaps.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3749
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3750
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3751
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3752 @example
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3753 cmdloop.c
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3754 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3755
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3756 @file{cmdloop.c} contains functions that implement the actual editor
440
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 438
diff changeset
3757 command loop---i.e. the event loop that cyclically retrieves and
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3758 dispatches events. This code is also rather tricky, just like
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3759 @file{event-stream.c}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3760
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3761
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3762
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3763 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3764 macros.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3765 macros.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3766 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3767
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3768 These two modules contain the basic code for defining keyboard macros.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3769 These functions don't actually do much; most of the code that handles keyboard
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3770 macros is mixed in with the event-handling code in @file{event-stream.c}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3771
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3772
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3773
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3774 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3775 minibuf.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3776 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3777
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3778 This contains some miscellaneous code related to the minibuffer (most of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3779 the minibuffer code was moved into Lisp by Richard Mlynarik). This
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3780 includes the primitives for completion (although filename completion is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3781 in @file{dired.c}), the lowest-level interface to the minibuffer (if the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3782 command loop were cleaned up, this too could be in Lisp), and code for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3783 dealing with the echo area (this, too, was mostly moved into Lisp, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3784 the only code remaining is code to call out to Lisp or provide simple
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3785 bootstrapping implementations early in temacs, before the echo-area Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3786 code is loaded).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3787
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3788
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3789
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
3790 @node Modules for the Basic Displayable Lisp Objects
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3791 @section Modules for the Basic Displayable Lisp Objects
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
3792 @cindex modules for the basic displayable Lisp objects
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
3793 @cindex displayable Lisp objects, modules for the basic
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
3794 @cindex Lisp objects, modules for the basic displayable
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
3795 @cindex objects, modules for the basic displayable Lisp
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3796
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3797 @example
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3798 console-msw.c
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3799 console-msw.h
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3800 console-stream.c
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3801 console-stream.h
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3802 console-tty.c
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3803 console-tty.h
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3804 console-x.c
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3805 console-x.h
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3806 console.c
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3807 console.h
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3808 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3809
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3810 These modules implement the @dfn{console} Lisp object type. A console
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3811 contains multiple display devices, but only one keyboard and mouse.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3812 Most of the time, a console will contain exactly one device.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3813
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3814 Consoles are the top of a lisp object inclusion hierarchy. Consoles
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3815 contain devices, which contain frames, which contain windows.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3816
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3817
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3818
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3819 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3820 device-msw.c
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3821 device-tty.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3822 device-x.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3823 device.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3824 device.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3825 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3826
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3827 These modules implement the @dfn{device} Lisp object type. This
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3828 abstracts a particular screen or connection on which frames are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3829 displayed. As with Lisp objects, event interfaces, and other
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3830 subsystems, the device code is separated into a generic component that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3831 contains a standardized interface (in the form of a set of methods) onto
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3832 particular device types.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3833
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3834 The device subsystem defines all the methods and provides method
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3835 services for not only device operations but also for the frame, window,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3836 menubar, scrollbar, toolbar, and other displayable-object subsystems.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3837 The reason for this is that all of these subsystems have the same
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3838 subtypes (X, TTY, NeXTstep, Microsoft Windows, etc.) as devices do.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3839
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3840
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3841
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3842 @example
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3843 frame-msw.c
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3844 frame-tty.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3845 frame-x.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3846 frame.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3847 frame.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3848 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3849
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3850 Each device contains one or more frames in which objects (e.g. text) are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3851 displayed. A frame corresponds to a window in the window system;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3852 usually this is a top-level window but it could potentially be one of a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3853 number of overlapping child windows within a top-level window, using the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3854 MDI (Multiple Document Interface) protocol in Microsoft Windows or a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3855 similar scheme.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3856
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3857 The @file{frame-*} files implement the @dfn{frame} Lisp object type and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3858 provide the generic and device-type-specific operations on frames
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3859 (e.g. raising, lowering, resizing, moving, etc.).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3860
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3861
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3862
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3863 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3864 window.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3865 window.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3866 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3867
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3868 @cindex window (in Emacs)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3869 @cindex pane
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3870 Each frame consists of one or more non-overlapping @dfn{windows} (better
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3871 known as @dfn{panes} in standard window-system terminology) in which a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3872 buffer's text can be displayed. Windows can also have scrollbars
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3873 displayed around their edges.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3874
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3875 @file{window.c} and @file{window.h} implement the @dfn{window} Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3876 object type and provide code to manage windows. Since windows have no
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3877 associated resources in the window system (the window system knows only
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3878 about the frame; no child windows or anything are used for XEmacs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3879 windows), there is no device-type-specific code here; all of that code
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3880 is part of the redisplay mechanism or the code for particular object
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3881 types such as scrollbars.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3882
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3883
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3884
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
3885 @node Modules for other Display-Related Lisp Objects
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3886 @section Modules for other Display-Related Lisp Objects
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
3887 @cindex modules for other display-related Lisp objects
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
3888 @cindex display-related Lisp objects, modules for other
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
3889 @cindex Lisp objects, modules for other display-related
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3890
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3891 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3892 faces.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3893 faces.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3894 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3895
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3896
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3897
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3898 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3899 bitmaps.h
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3900 glyphs-eimage.c
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3901 glyphs-msw.c
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3902 glyphs-msw.h
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3903 glyphs-widget.c
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3904 glyphs-x.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3905 glyphs-x.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3906 glyphs.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3907 glyphs.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3908 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3909
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3910
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3911
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3912 @example
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3913 objects-msw.c
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3914 objects-msw.h
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3915 objects-tty.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3916 objects-tty.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3917 objects-x.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3918 objects-x.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3919 objects.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3920 objects.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3921 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3922
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3923
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3924
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3925 @example
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3926 menubar-msw.c
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3927 menubar-msw.h
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3928 menubar-x.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3929 menubar.c
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3930 menubar.h
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3931 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3932
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3933
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3934
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3935 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3936 scrollbar-msw.c
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3937 scrollbar-msw.h
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3938 scrollbar-x.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3939 scrollbar-x.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3940 scrollbar.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3941 scrollbar.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3942 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3943
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3944
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3945
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3946 @example
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3947 toolbar-msw.c
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3948 toolbar-x.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3949 toolbar.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3950 toolbar.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3951 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3952
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3953
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3954
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3955 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3956 font-lock.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3957 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3958
440
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 438
diff changeset
3959 This file provides C support for syntax highlighting---i.e.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3960 highlighting different syntactic constructs of a source file in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3961 different colors, for easy reading. The C support is provided so that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3962 this is fast.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3963
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3964
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3965
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3966 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3967 dgif_lib.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3968 gif_err.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3969 gif_lib.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3970 gifalloc.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3971 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3972
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3973 These modules decode GIF-format image files, for use with glyphs.
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3974 These files were removed due to Unisys patent infringement concerns.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3975
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3976
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3977
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
3978 @node Modules for the Redisplay Mechanism
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3979 @section Modules for the Redisplay Mechanism
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
3980 @cindex modules for the redisplay mechanism
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
3981 @cindex redisplay mechanism, modules for the
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3982
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3983 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3984 redisplay-output.c
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
3985 redisplay-msw.c
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3986 redisplay-tty.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3987 redisplay-x.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3988 redisplay.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3989 redisplay.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3990 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3991
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3992 These files provide the redisplay mechanism. As with many other
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3993 subsystems in XEmacs, there is a clean separation between the general
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3994 and device-specific support.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3995
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3996 @file{redisplay.c} contains the bulk of the redisplay engine. These
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3997 functions update the redisplay structures (which describe how the screen
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3998 is to appear) to reflect any changes made to the state of any
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3999 displayable objects (buffer, frame, window, etc.) since the last time
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4000 that redisplay was called. These functions are highly optimized to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4001 avoid doing more work than necessary (since redisplay is called
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4002 extremely often and is potentially a huge time sink), and depend heavily
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4003 on notifications from the objects themselves that changes have occurred,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4004 so that redisplay doesn't explicitly have to check each possible object.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4005 The redisplay mechanism also contains a great deal of caching to further
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4006 speed things up; some of this caching is contained within the various
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4007 displayable objects.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4008
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4009 @file{redisplay-output.c} goes through the redisplay structures and converts
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4010 them into calls to device-specific methods to actually output the screen
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4011 changes.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4012
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4013 @file{redisplay-x.c} and @file{redisplay-tty.c} are two implementations
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4014 of these redisplay output methods, for X frames and TTY frames,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4015 respectively.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4016
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4017
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4018
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4019 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4020 indent.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4021 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4022
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4023 This module contains various functions and Lisp primitives for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4024 converting between buffer positions and screen positions. These
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4025 functions call the redisplay mechanism to do most of the work, and then
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4026 examine the redisplay structures to get the necessary information. This
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4027 module needs work.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4028
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4029
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4030
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4031 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4032 termcap.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4033 terminfo.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4034 tparam.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4035 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4036
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4037 These files contain functions for working with the termcap (BSD-style)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4038 and terminfo (System V style) databases of terminal capabilities and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4039 escape sequences, used when XEmacs is displaying in a TTY.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4040
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4041
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4042
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4043 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4044 cm.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4045 cm.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4046 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4047
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4048 These files provide some miscellaneous TTY-output functions and should
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4049 probably be merged into @file{redisplay-tty.c}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4050
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4051
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4052
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
4053 @node Modules for Interfacing with the File System
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4054 @section Modules for Interfacing with the File System
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
4055 @cindex modules for interfacing with the file system
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
4056 @cindex interfacing with the file system, modules for
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
4057 @cindex file system, modules for interfacing with the
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4058
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4059 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4060 lstream.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4061 lstream.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4062 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4063
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4064 These modules implement the @dfn{stream} Lisp object type. This is an
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4065 internal-only Lisp object that implements a generic buffering stream.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4066 The idea is to provide a uniform interface onto all sources and sinks of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4067 data, including file descriptors, stdio streams, chunks of memory, Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4068 buffers, Lisp strings, etc. That way, I/O functions can be written to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4069 the stream interface and can transparently handle all possible sources
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4070 and sinks. (For example, the @code{read} function can read data from a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4071 file, a string, a buffer, or even a function that is called repeatedly
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4072 to return data, without worrying about where the data is coming from or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4073 what-size chunks it is returned in.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4074
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4075 @cindex lstream
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4076 Note that in the C code, streams are called @dfn{lstreams} (for ``Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4077 streams'') to distinguish them from other kinds of streams, e.g. stdio
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4078 streams and C++ I/O streams.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4079
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4080 Similar to other subsystems in XEmacs, lstreams are separated into
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4081 generic functions and a set of methods for the different types of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4082 lstreams. @file{lstream.c} provides implementations of many different
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4083 types of streams; others are provided, e.g., in @file{file-coding.c}.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4084
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4085
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4086
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4087 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4088 fileio.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4089 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4090
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4091 This implements the basic primitives for interfacing with the file
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4092 system. This includes primitives for reading files into buffers,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4093 writing buffers into files, checking for the presence or accessibility
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4094 of files, canonicalizing file names, etc. Note that these primitives
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4095 are usually not invoked directly by the user: There is a great deal of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4096 higher-level Lisp code that implements the user commands such as
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4097 @code{find-file} and @code{save-buffer}. This is similar to the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4098 distinction between the lower-level primitives in @file{editfns.c} and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4099 the higher-level user commands in @file{commands.c} and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4100 @file{simple.el}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4101
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4102
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4103
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4104 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4105 filelock.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4106 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4107
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4108 This file provides functions for detecting clashes between different
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4109 processes (e.g. XEmacs and some external process, or two different
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4110 XEmacs processes) modifying the same file. (XEmacs can optionally use
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4111 the @file{lock/} subdirectory to provide a form of ``locking'' between
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4112 different XEmacs processes.) This module is also used by the low-level
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4113 functions in @file{insdel.c} to ensure that, if the first modification
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4114 is being made to a buffer whose corresponding file has been externally
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4115 modified, the user is made aware of this so that the buffer can be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4116 synched up with the external changes if necessary.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4117
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4118
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4119 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4120 filemode.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4121 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4122
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4123 This file provides some miscellaneous functions that construct a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4124 @samp{rwxr-xr-x}-type permissions string (as might appear in an
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4125 @file{ls}-style directory listing) given the information returned by the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4126 @code{stat()} system call.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4127
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4128
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4129
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4130 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4131 dired.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4132 ndir.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4133 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4134
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4135 These files implement the XEmacs interface to directory searching. This
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4136 includes a number of primitives for determining the files in a directory
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4137 and for doing filename completion. (Remember that generic completion is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4138 handled by a different mechanism, in @file{minibuf.c}.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4139
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4140 @file{ndir.h} is a header file used for the directory-searching
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4141 emulation functions provided in @file{sysdep.c} (see section J below),
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4142 for systems that don't provide any directory-searching functions. (On
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4143 those systems, directories can be read directly as files, and parsed.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4144
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4145
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4146
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4147 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4148 realpath.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4149 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4150
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4151 This file provides an implementation of the @code{realpath()} function
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4152 for expanding symbolic links, on systems that don't implement it or have
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4153 a broken implementation.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4154
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4155
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4156
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
4157 @node Modules for Other Aspects of the Lisp Interpreter and Object System
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4158 @section Modules for Other Aspects of the Lisp Interpreter and Object System
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
4159 @cindex modules for other aspects of the Lisp interpreter and object system
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
4160 @cindex Lisp interpreter and object system, modules for other aspects of the
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
4161 @cindex interpreter and object system, modules for other aspects of the Lisp
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
4162 @cindex object system, modules for other aspects of the Lisp interpreter and
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4163
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4164 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4165 elhash.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4166 elhash.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4167 hash.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4168 hash.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4169 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4170
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4171 These files provide two implementations of hash tables. Files
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4172 @file{hash.c} and @file{hash.h} provide a generic C implementation of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4173 hash tables which can stand independently of XEmacs. Files
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4174 @file{elhash.c} and @file{elhash.h} provide a separate implementation of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4175 hash tables that can store only Lisp objects, and knows about Lispy
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4176 things like garbage collection, and implement the @dfn{hash-table} Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4177 object type.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4178
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4179
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4180 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4181 specifier.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4182 specifier.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4183 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4184
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4185 This module implements the @dfn{specifier} Lisp object type. This is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4186 primarily used for displayable properties, and allows for values that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4187 are specific to a particular buffer, window, frame, device, or device
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4188 class, as well as a default value existing. This is used, for example,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4189 to control the height of the horizontal scrollbar or the appearance of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4190 the @code{default}, @code{bold}, or other faces. The specifier object
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4191 consists of a number of specifications, each of which maps from a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4192 buffer, window, etc. to a value. The function @code{specifier-instance}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4193 looks up a value given a window (from which a buffer, frame, and device
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4194 can be derived).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4195
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4196
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4197 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4198 chartab.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4199 chartab.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4200 casetab.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4201 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4202
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4203 @file{chartab.c} and @file{chartab.h} implement the @dfn{char table}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4204 Lisp object type, which maps from characters or certain sorts of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4205 character ranges to Lisp objects. The implementation of this object
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4206 type is optimized for the internal representation of characters. Char
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4207 tables come in different types, which affect the allowed object types to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4208 which a character can be mapped and also dictate certain other
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4209 properties of the char table.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4210
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4211 @cindex case table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4212 @file{casetab.c} implements one sort of char table, the @dfn{case
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4213 table}, which maps characters to other characters of possibly different
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4214 case. These are used by XEmacs to implement case-changing primitives
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4215 and to do case-insensitive searching.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4216
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4217
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4218
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4219 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4220 syntax.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4221 syntax.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4222 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4223
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4224 @cindex scanner
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4225 This module implements @dfn{syntax tables}, another sort of char table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4226 that maps characters into syntax classes that define the syntax of these
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4227 characters (e.g. a parenthesis belongs to a class of @samp{open}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4228 characters that have corresponding @samp{close} characters and can be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4229 nested). This module also implements the Lisp @dfn{scanner}, a set of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4230 primitives for scanning over text based on syntax tables. This is used,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4231 for example, to find the matching parenthesis in a command such as
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4232 @code{forward-sexp}, and by @file{font-lock.c} to locate quoted strings,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4233 comments, etc.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4234
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4235
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4236
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4237 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4238 casefiddle.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4239 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4240
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4241 This module implements various Lisp primitives for upcasing, downcasing
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4242 and capitalizing strings or regions of buffers.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4243
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4244
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4245
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4246 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4247 rangetab.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4248 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4249
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4250 This module implements the @dfn{range table} Lisp object type, which
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4251 provides for a mapping from ranges of integers to arbitrary Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4252 objects.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4253
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4254
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4255
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4256 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4257 opaque.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4258 opaque.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4259 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4260
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4261 This module implements the @dfn{opaque} Lisp object type, an
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4262 internal-only Lisp object that encapsulates an arbitrary block of memory
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4263 so that it can be managed by the Lisp allocation system. To create an
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4264 opaque object, you call @code{make_opaque()}, passing a pointer to a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4265 block of memory. An object is created that is big enough to hold the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4266 memory, which is copied into the object's storage. The object will then
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4267 stick around as long as you keep pointers to it, after which it will be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4268 automatically reclaimed.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4269
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4270 @cindex mark method
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4271 Opaque objects can also have an arbitrary @dfn{mark method} associated
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4272 with them, in case the block of memory contains other Lisp objects that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4273 need to be marked for garbage-collection purposes. (If you need other
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4274 object methods, such as a finalize method, you should just go ahead and
440
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 438
diff changeset
4275 create a new Lisp object type---it's not hard.)
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4276
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4277
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4278
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4279 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4280 abbrev.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4281 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4282
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4283 This function provides a few primitives for doing dynamic abbreviation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4284 expansion. In XEmacs, most of the code for this has been moved into
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4285 Lisp. Some C code remains for speed and because the primitive
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4286 @code{self-insert-command} (which is executed for all self-inserting
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4287 characters) hooks into the abbrev mechanism. (@code{self-insert-command}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4288 is itself in C only for speed.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4289
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4290
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4291
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4292 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4293 doc.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4294 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4295
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4296 This function provides primitives for retrieving the documentation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4297 strings of functions and variables. These documentation strings contain
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4298 certain special markers that get dynamically expanded (e.g. a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4299 reverse-lookup is performed on some named functions to retrieve their
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4300 current key bindings). Some documentation strings (in particular, for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4301 the built-in primitives and pre-loaded Lisp functions) are stored
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4302 externally in a file @file{DOC} in the @file{lib-src/} directory and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4303 need to be fetched from that file. (Part of the build stage involves
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4304 building this file, and another part involves constructing an index for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4305 this file and embedding it into the executable, so that the functions in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4306 @file{doc.c} do not have to search the entire @file{DOC} file to find
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4307 the appropriate documentation string.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4308
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4309
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4310
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4311 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4312 md5.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4313 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4314
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4315 This function provides a Lisp primitive that implements the MD5 secure
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4316 hashing scheme, used to create a large hash value of a string of data such that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4317 the data cannot be derived from the hash value. This is used for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4318 various security applications on the Internet.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4319
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4320
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4321
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4322
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
4323 @node Modules for Interfacing with the Operating System
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4324 @section Modules for Interfacing with the Operating System
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
4325 @cindex modules for interfacing with the operating system
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
4326 @cindex interfacing with the operating system, modules for
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
4327 @cindex operating system, modules for interfacing with the
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4328
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4329 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4330 callproc.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4331 process.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4332 process.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4333 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4334
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4335 These modules allow XEmacs to spawn and communicate with subprocesses
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4336 and network connections.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4337
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4338 @cindex synchronous subprocesses
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4339 @cindex subprocesses, synchronous
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4340 @file{callproc.c} implements (through the @code{call-process}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4341 primitive) what are called @dfn{synchronous subprocesses}. This means
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4342 that XEmacs runs a program, waits till it's done, and retrieves its
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4343 output. A typical example might be calling the @file{ls} program to get
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4344 a directory listing.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4345
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4346 @cindex asynchronous subprocesses
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4347 @cindex subprocesses, asynchronous
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4348 @file{process.c} and @file{process.h} implement @dfn{asynchronous
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4349 subprocesses}. This means that XEmacs starts a program and then
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4350 continues normally, not waiting for the process to finish. Data can be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4351 sent to the process or retrieved from it as it's running. This is used
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4352 for the @code{shell} command (which provides a front end onto a shell
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4353 program such as @file{csh}), the mail and news readers implemented in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4354 XEmacs, etc. The result of calling @code{start-process} to start a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4355 subprocess is a process object, a particular kind of object used to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4356 communicate with the subprocess. You can send data to the process by
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4357 passing the process object and the data to @code{send-process}, and you
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4358 can specify what happens to data retrieved from the process by setting
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4359 properties of the process object. (When the process sends data, XEmacs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4360 receives a process event, which says that there is data ready. When
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4361 @code{dispatch-event} is called on this event, it reads the data from
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4362 the process and does something with it, as specified by the process
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4363 object's properties. Typically, this means inserting the data into a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4364 buffer or calling a function.) Another property of the process object is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4365 called the @dfn{sentinel}, which is a function that is called when the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4366 process terminates.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4367
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4368 @cindex network connections
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4369 Process objects are also used for network connections (connections to a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4370 process running on another machine). Network connections are started
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4371 with @code{open-network-stream} but otherwise work just like
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4372 subprocesses.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4373
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4374
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4375
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4376 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4377 sysdep.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4378 sysdep.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4379 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4380
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4381 These modules implement most of the low-level, messy operating-system
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4382 interface code. This includes various device control (ioctl) operations
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4383 for file descriptors, TTY's, pseudo-terminals, etc. (usually this stuff
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4384 is fairly system-dependent; thus the name of this module), and emulation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4385 of standard library functions and system calls on systems that don't
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4386 provide them or have broken versions.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4387
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4388
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4389
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4390 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4391 sysdir.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4392 sysfile.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4393 sysfloat.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4394 sysproc.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4395 syspwd.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4396 syssignal.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4397 systime.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4398 systty.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4399 syswait.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4400 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4401
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4402 These header files provide consistent interfaces onto system-dependent
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4403 header files and system calls. The idea is that, instead of including a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4404 standard header file like @file{<sys/param.h>} (which may or may not
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4405 exist on various systems) or having to worry about whether all system
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4406 provide a particular preprocessor constant, or having to deal with the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4407 four different paradigms for manipulating signals, you just include the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4408 appropriate @file{sys*.h} header file, which includes all the right
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4409 system header files, defines and missing preprocessor constants,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4410 provides a uniform interface onto system calls, etc.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4411
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4412 @file{sysdir.h} provides a uniform interface onto directory-querying
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4413 functions. (In some cases, this is in conjunction with emulation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4414 functions in @file{sysdep.c}.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4415
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4416 @file{sysfile.h} includes all the necessary header files for standard
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4417 system calls (e.g. @code{read()}), ensures that all necessary
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4418 @code{open()} and @code{stat()} preprocessor constants are defined, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4419 possibly (usually) substitutes sugared versions of @code{read()},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4420 @code{write()}, etc. that automatically restart interrupted I/O
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4421 operations.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4422
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4423 @file{sysfloat.h} includes the necessary header files for floating-point
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4424 operations.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4425
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4426 @file{sysproc.h} includes the necessary header files for calling
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4427 @code{select()}, @code{fork()}, @code{execve()}, socket operations, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4428 the like, and ensures that the @code{FD_*()} macros for descriptor-set
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4429 manipulations are available.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4430
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4431 @file{syspwd.h} includes the necessary header files for obtaining
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4432 information from @file{/etc/passwd} (the functions are emulated under
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4433 VMS).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4434
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4435 @file{syssignal.h} includes the necessary header files for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4436 signal-handling and provides a uniform interface onto the different
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4437 signal-handling and signal-blocking paradigms.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4438
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4439 @file{systime.h} includes the necessary header files and provides
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4440 uniform interfaces for retrieving the time of day, setting file
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4441 access/modification times, getting the amount of time used by the XEmacs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4442 process, etc.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4443
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4444 @file{systty.h} buffers against the infinitude of different ways of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4445 controlling TTY's.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4446
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4447 @file{syswait.h} provides a uniform way of retrieving the exit status
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4448 from a @code{wait()}ed-on process (some systems use a union, others use
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4449 an int).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4450
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4451
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4452
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4453 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4454 hpplay.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4455 libsst.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4456 libsst.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4457 libst.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4458 linuxplay.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4459 nas.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4460 sgiplay.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4461 sound.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4462 sunplay.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4463 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4464
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4465 These files implement the ability to play various sounds on some types
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4466 of computers. You have to configure your XEmacs with sound support in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4467 order to get this capability.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4468
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4469 @file{sound.c} provides the generic interface. It implements various
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4470 Lisp primitives and variables that let you specify which sounds should
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4471 be played in certain conditions. (The conditions are identified by
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4472 symbols, which are passed to @code{ding} to make a sound. Various
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4473 standard functions call this function at certain times; if sound support
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4474 does not exist, a simple beep results.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4475
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4476 @cindex native sound
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4477 @cindex sound, native
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4478 @file{sgiplay.c}, @file{sunplay.c}, @file{hpplay.c}, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4479 @file{linuxplay.c} interface to the machine's speaker for various
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4480 different kind of machines. This is called @dfn{native} sound.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4481
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4482 @cindex sound, network
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4483 @cindex network sound
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4484 @cindex NAS
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4485 @file{nas.c} interfaces to a computer somewhere else on the network
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4486 using the NAS (Network Audio Server) protocol, playing sounds on that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4487 machine. This allows you to run XEmacs on a remote machine, with its
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4488 display set to your local machine, and have the sounds be made on your
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4489 local machine, provided that you have a NAS server running on your local
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4490 machine.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4491
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4492 @file{libsst.c}, @file{libsst.h}, and @file{libst.h} provide some
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4493 additional functions for playing sound on a Sun SPARC but are not
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4494 currently in use.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4495
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4496
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4497
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4498 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4499 tooltalk.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4500 tooltalk.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4501 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4502
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4503 These two modules implement an interface to the ToolTalk protocol, which
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4504 is an interprocess communication protocol implemented on some versions
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4505 of Unix. ToolTalk is a high-level protocol that allows processes to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4506 register themselves as providers of particular services; other processes
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4507 can then request a service without knowing or caring exactly who is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4508 providing the service. It is similar in spirit to the DDE protocol
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4509 provided under Microsoft Windows. ToolTalk is a part of the new CDE
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4510 (Common Desktop Environment) specification and is used to connect the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4511 parts of the SPARCWorks development environment.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4512
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4513
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4514
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4515 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4516 getloadavg.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4517 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4518
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4519 This module provides the ability to retrieve the system's current load
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4520 average. (The way to do this is highly system-specific, unfortunately,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4521 and requires a lot of special-case code.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4522
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4523
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4524
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4525 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4526 sunpro.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4527 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4528
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4529 This module provides a small amount of code used internally at Sun to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4530 keep statistics on the usage of XEmacs.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4531
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4532
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4533
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4534 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4535 broken-sun.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4536 strcmp.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4537 strcpy.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4538 sunOS-fix.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4539 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4540
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4541 These files provide replacement functions and prototypes to fix numerous
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4542 bugs in early releases of SunOS 4.1.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4543
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4544
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4545
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4546 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4547 hftctl.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4548 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4549
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4550 This module provides some terminal-control code necessary on versions of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4551 AIX prior to 4.1.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4552
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4553
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4554
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
4555 @node Modules for Interfacing with X Windows
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4556 @section Modules for Interfacing with X Windows
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
4557 @cindex modules for interfacing with X Windows
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
4558 @cindex interfacing with X Windows, modules for
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
4559 @cindex X Windows, modules for interfacing with
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4560
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4561 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4562 Emacs.ad.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4563 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4564
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4565 A file generated from @file{Emacs.ad}, which contains XEmacs-supplied
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4566 fallback resources (so that XEmacs has pretty defaults).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4567
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4568
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4569
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4570 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4571 EmacsFrame.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4572 EmacsFrame.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4573 EmacsFrameP.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4574 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4575
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4576 These modules implement an Xt widget class that encapsulates a frame.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4577 This is for ease in integrating with Xt. The EmacsFrame widget covers
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4578 the entire X window except for the menubar; the scrollbars are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4579 positioned on top of the EmacsFrame widget.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4580
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4581 @strong{Warning:} Abandon hope, all ye who enter here. This code took
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4582 an ungodly amount of time to get right, and is likely to fall apart
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4583 mercilessly at the slightest change. Such is life under Xt.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4584
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4585
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4586
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4587 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4588 EmacsManager.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4589 EmacsManager.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4590 EmacsManagerP.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4591 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4592
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4593 These modules implement a simple Xt manager (i.e. composite) widget
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4594 class that simply lets its children set whatever geometry they want.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4595 It's amazing that Xt doesn't provide this standardly, but on second
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4596 thought, it makes sense, considering how amazingly broken Xt is.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4597
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4598
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4599 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4600 EmacsShell-sub.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4601 EmacsShell.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4602 EmacsShell.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4603 EmacsShellP.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4604 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4605
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4606 These modules implement two Xt widget classes that are subclasses of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4607 the TopLevelShell and TransientShell classes. This is necessary to deal
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4608 with more brokenness that Xt has sadistically thrust onto the backs of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4609 developers.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4610
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4611
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4612
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4613 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4614 xgccache.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4615 xgccache.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4616 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4617
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4618 These modules provide functions for maintenance and caching of GC's
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4619 (graphics contexts) under the X Window System. This code is junky and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4620 needs to be rewritten.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4621
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4622
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4623
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4624 @example
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4625 select-msw.c
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4626 select-x.c
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4627 select.c
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4628 select.h
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4629 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4630
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4631 @cindex selections
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4632 This module provides an interface to the X Window System's concept of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4633 @dfn{selections}, the standard way for X applications to communicate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4634 with each other.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4635
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4636
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4637
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4638 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4639 xintrinsic.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4640 xintrinsicp.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4641 xmmanagerp.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4642 xmprimitivep.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4643 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4644
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4645 These header files are similar in spirit to the @file{sys*.h} files and buffer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4646 against different implementations of Xt and Motif.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4647
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4648 @itemize @bullet
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4649 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4650 @file{xintrinsic.h} should be included in place of @file{<Intrinsic.h>}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4651 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4652 @file{xintrinsicp.h} should be included in place of @file{<IntrinsicP.h>}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4653 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4654 @file{xmmanagerp.h} should be included in place of @file{<XmManagerP.h>}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4655 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4656 @file{xmprimitivep.h} should be included in place of @file{<XmPrimitiveP.h>}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4657 @end itemize
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4658
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4659
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4660
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4661 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4662 xmu.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4663 xmu.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4664 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4665
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4666 These files provide an emulation of the Xmu library for those systems
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4667 (i.e. HPUX) that don't provide it as a standard part of X.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4668
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4669
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4670
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4671 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4672 ExternalClient-Xlib.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4673 ExternalClient.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4674 ExternalClient.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4675 ExternalClientP.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4676 ExternalShell.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4677 ExternalShell.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4678 ExternalShellP.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4679 extw-Xlib.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4680 extw-Xlib.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4681 extw-Xt.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4682 extw-Xt.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4683 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4684
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4685 @cindex external widget
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4686 These files provide the @dfn{external widget} interface, which allows an
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4687 XEmacs frame to appear as a widget in another application. To do this,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4688 you have to configure with @samp{--external-widget}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4689
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4690 @file{ExternalShell*} provides the server (XEmacs) side of the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4691 connection.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4692
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4693 @file{ExternalClient*} provides the client (other application) side of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4694 the connection. These files are not compiled into XEmacs but are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4695 compiled into libraries that are then linked into your application.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4696
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4697 @file{extw-*} is common code that is used for both the client and server.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4698
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4699 Don't touch this code; something is liable to break if you do.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4700
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4701
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4702
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
4703 @node Modules for Internationalization
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4704 @section Modules for Internationalization
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
4705 @cindex modules for internationalization
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
4706 @cindex internationalization, modules for
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4707
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4708 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4709 mule-canna.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4710 mule-ccl.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4711 mule-charset.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4712 mule-charset.h
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4713 file-coding.c
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4714 file-coding.h
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4715 mule-mcpath.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4716 mule-mcpath.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4717 mule-wnnfns.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4718 mule.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4719 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4720
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4721 These files implement the MULE (Asian-language) support. Note that MULE
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4722 actually provides a general interface for all sorts of languages, not
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4723 just Asian languages (although they are generally the most complicated
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4724 to support). This code is still in beta.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4725
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4726 @file{mule-charset.*} and @file{file-coding.*} provide the heart of the
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4727 XEmacs MULE support. @file{mule-charset.*} implements the @dfn{charset}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4728 Lisp object type, which encapsulates a character set (an ordered one- or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4729 two-dimensional set of characters, such as US ASCII or JISX0208 Japanese
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4730 Kanji).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4731
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4732 @file{file-coding.*} implements the @dfn{coding-system} Lisp object
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4733 type, which encapsulates a method of converting between different
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4734 encodings. An encoding is a representation of a stream of characters,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4735 possibly from multiple character sets, using a stream of bytes or words,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4736 and defines (e.g.) which escape sequences are used to specify particular
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4737 character sets, how the indices for a character are converted into bytes
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4738 (sometimes this involves setting the high bit; sometimes complicated
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4739 rearranging of the values takes place, as in the Shift-JIS encoding),
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4740 etc.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4741
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4742 @file{mule-ccl.c} provides the CCL (Code Conversion Language)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4743 interpreter. CCL is similar in spirit to Lisp byte code and is used to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4744 implement converters for custom encodings.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4745
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4746 @file{mule-canna.c} and @file{mule-wnnfns.c} implement interfaces to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4747 external programs used to implement the Canna and WNN input methods,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4748 respectively. This is currently in beta.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4749
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4750 @file{mule-mcpath.c} provides some functions to allow for pathnames
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4751 containing extended characters. This code is fragmentary, obsolete, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4752 completely non-working. Instead, @var{pathname-coding-system} is used
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4753 to specify conversions of names of files and directories. The standard
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4754 C I/O functions like @samp{open()} are wrapped so that conversion occurs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4755 automatically.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4756
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4757 @file{mule.c} provides a few miscellaneous things that should probably
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4758 be elsewhere.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4759
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4760
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4761
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4762 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4763 intl.c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4764 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4765
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4766 This provides some miscellaneous internationalization code for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4767 implementing message translation and interfacing to the Ximp input
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4768 method. None of this code is currently working.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4769
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4770
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4771
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4772 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4773 iso-wide.h
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4774 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4775
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4776 This contains leftover code from an earlier implementation of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4777 Asian-language support, and is not currently used.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4778
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4779
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4780
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4781
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4782 @node Allocation of Objects in XEmacs Lisp, Dumping, A Summary of the Various XEmacs Modules, Top
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4783 @chapter Allocation of Objects in XEmacs Lisp
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
4784 @cindex allocation of objects in XEmacs Lisp
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
4785 @cindex objects in XEmacs Lisp, allocation of
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
4786 @cindex Lisp objects, allocation of in XEmacs
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4787
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4788 @menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4789 * Introduction to Allocation::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4790 * Garbage Collection::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4791 * GCPROing::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4792 * Garbage Collection - Step by Step::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4793 * Integers and Characters::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4794 * Allocation from Frob Blocks::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4795 * lrecords::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4796 * Low-level allocation::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4797 * Cons::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4798 * Vector::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4799 * Bit Vector::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4800 * Symbol::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4801 * Marker::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4802 * String::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4803 * Compiled Function::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4804 @end menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4805
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
4806 @node Introduction to Allocation
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4807 @section Introduction to Allocation
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
4808 @cindex allocation, introduction to
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4809
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4810 Emacs Lisp, like all Lisps, has garbage collection. This means that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4811 the programmer never has to explicitly free (destroy) an object; it
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4812 happens automatically when the object becomes inaccessible. Most
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4813 experts agree that garbage collection is a necessity in a modern,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4814 high-level language. Its omission from C stems from the fact that C was
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4815 originally designed to be a nice abstract layer on top of assembly
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4816 language, for writing kernels and basic system utilities rather than
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4817 large applications.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4818
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4819 Lisp objects can be created by any of a number of Lisp primitives.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4820 Most object types have one or a small number of basic primitives
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4821 for creating objects. For conses, the basic primitive is @code{cons};
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4822 for vectors, the primitives are @code{make-vector} and @code{vector}; for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4823 symbols, the primitives are @code{make-symbol} and @code{intern}; etc.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4824 Some Lisp objects, especially those that are primarily used internally,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4825 have no corresponding Lisp primitives. Every Lisp object, though,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4826 has at least one C primitive for creating it.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4827
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4828 Recall from section (VII) that a Lisp object, as stored in a 32-bit or
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4829 64-bit word, has a few tag bits, and a ``value'' that occupies the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4830 remainder of the bits. We can separate the different Lisp object types
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4831 into three broad categories:
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4832
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4833 @itemize @bullet
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4834 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4835 (a) Those for whom the value directly represents the contents of the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4836 Lisp object. Only two types are in this category: integers and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4837 characters. No special allocation or garbage collection is necessary
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4838 for such objects. Lisp objects of these types do not need to be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4839 @code{GCPRO}ed.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4840 @end itemize
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4841
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4842 In the remaining two categories, the type is stored in the object
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4843 itself. The tag for all such objects is the generic @dfn{lrecord}
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4844 (Lisp_Type_Record) tag. The first bytes of the object's structure are an
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4845 integer (actually a char) characterising the object's type and some
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4846 flags, in particular the mark bit used for garbage collection. A
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4847 structure describing the type is accessible thru the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4848 lrecord_implementation_table indexed with said integer. This structure
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4849 includes the method pointers and a pointer to a string naming the type.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4850
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4851 @itemize @bullet
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4852 @item
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4853 (b) Those lrecords that are allocated in frob blocks (see above). This
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4854 includes the objects that are most common and relatively small, and
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4855 includes conses, strings, subrs, floats, compiled functions, symbols,
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4856 extents, events, and markers. With the cleanup of frob blocks done in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4857 19.12, it's not terribly hard to add more objects to this category, but
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4858 it's a bit trickier than adding an object type to type (c) (esp. if the
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4859 object needs a finalization method), and is not likely to save much
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4860 space unless the object is small and there are many of them. (In fact,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4861 if there are very few of them, it might actually waste space.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4862 @item
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4863 (c) Those lrecords that are individually @code{malloc()}ed. These are
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4864 called @dfn{lcrecords}. All other types are in this category. Adding a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4865 new type to this category is comparatively easy, and all types added
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4866 since 19.8 (when the current allocation scheme was devised, by Richard
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4867 Mlynarik), with the exception of the character type, have been in this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4868 category.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4869 @end itemize
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4870
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4871 Note that bit vectors are a bit of a special case. They are
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4872 simple lrecords as in category (b), but are individually @code{malloc()}ed
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4873 like vectors. You can basically view them as exactly like vectors
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4874 except that their type is stored in lrecord fashion rather than
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4875 in directly-tagged fashion.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4876
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4877
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
4878 @node Garbage Collection
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4879 @section Garbage Collection
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4880 @cindex garbage collection
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4881
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4882 @cindex mark and sweep
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4883 Garbage collection is simple in theory but tricky to implement.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4884 Emacs Lisp uses the oldest garbage collection method, called
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4885 @dfn{mark and sweep}. Garbage collection begins by starting with
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4886 all accessible locations (i.e. all variables and other slots where
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4887 Lisp objects might occur) and recursively traversing all objects
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4888 accessible from those slots, marking each one that is found.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4889 We then go through all of memory and free each object that is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4890 not marked, and unmarking each object that is marked. Note
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4891 that ``all of memory'' means all currently allocated objects.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4892 Traversing all these objects means traversing all frob blocks,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4893 all vectors (which are chained in one big list), and all
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4894 lcrecords (which are likewise chained).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4895
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4896 Garbage collection can be invoked explicitly by calling
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4897 @code{garbage-collect} but is also called automatically by @code{eval},
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4898 once a certain amount of memory has been allocated since the last
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4899 garbage collection (according to @code{gc-cons-threshold}).
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4900
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4901
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
4902 @node GCPROing
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4903 @section @code{GCPRO}ing
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
4904 @cindex @code{GCPRO}ing
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
4905 @cindex garbage collection protection
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
4906 @cindex protection, garbage collection
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4907
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4908 @code{GCPRO}ing is one of the ugliest and trickiest parts of Emacs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4909 internals. The basic idea is that whenever garbage collection
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4910 occurs, all in-use objects must be reachable somehow or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4911 other from one of the roots of accessibility. The roots
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4912 of accessibility are:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4913
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4914 @enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4915 @item
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4916 All objects that have been @code{staticpro()}d or
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4917 @code{staticpro_nodump()}ed. This is used for any global C variables
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4918 that hold Lisp objects. A call to @code{staticpro()} happens implicitly
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4919 as a result of any symbols declared with @code{defsymbol()} and any
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4920 variables declared with @code{DEFVAR_FOO()}. You need to explicitly
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4921 call @code{staticpro()} (in the @code{vars_of_foo()} method of a module)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4922 for other global C variables holding Lisp objects. (This typically
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4923 includes internal lists and such things.). Use
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4924 @code{staticpro_nodump()} only in the rare cases when you do not want
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4925 the pointed variable to be saved at dump time but rather recompute it at
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
4926 startup.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4927
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4928 Note that @code{obarray} is one of the @code{staticpro()}d things.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4929 Therefore, all functions and variables get marked through this.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4930 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4931 Any shadowed bindings that are sitting on the @code{specpdl} stack.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4932 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4933 Any objects sitting in currently active (Lisp) stack frames,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4934 catches, and condition cases.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4935 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4936 A couple of special-case places where active objects are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4937 located.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4938 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4939 Anything currently marked with @code{GCPRO}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4940 @end enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4941
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4942 Marking with @code{GCPRO} is necessary because some C functions (quite
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4943 a lot, in fact), allocate objects during their operation. Quite
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4944 frequently, there will be no other pointer to the object while the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4945 function is running, and if a garbage collection occurs and the object
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4946 needs to be referenced again, bad things will happen. The solution is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4947 to mark those objects with @code{GCPRO}. Unfortunately this is easy to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4948 forget, and there is basically no way around this problem. Here are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4949 some rules, though:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4950
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4951 @enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4952 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4953 For every @code{GCPRO@var{n}}, there have to be declarations of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4954 @code{struct gcpro gcpro1, gcpro2}, etc.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4955
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4956 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4957 You @emph{must} @code{UNGCPRO} anything that's @code{GCPRO}ed, and you
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4958 @emph{must not} @code{UNGCPRO} if you haven't @code{GCPRO}ed. Getting
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4959 either of these wrong will lead to crashes, often in completely random
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4960 places unrelated to where the problem lies.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4961
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4962 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4963 The way this actually works is that all currently active @code{GCPRO}s
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4964 are chained through the @code{struct gcpro} local variables, with the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4965 variable @samp{gcprolist} pointing to the head of the list and the nth
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4966 local @code{gcpro} variable pointing to the first @code{gcpro} variable
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4967 in the next enclosing stack frame. Each @code{GCPRO}ed thing is an
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4968 lvalue, and the @code{struct gcpro} local variable contains a pointer to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4969 this lvalue. This is why things will mess up badly if you don't pair up
440
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 438
diff changeset
4970 the @code{GCPRO}s and @code{UNGCPRO}s---you will end up with
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4971 @code{gcprolist}s containing pointers to @code{struct gcpro}s or local
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4972 @code{Lisp_Object} variables in no-longer-active stack frames.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4973
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4974 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4975 It is actually possible for a single @code{struct gcpro} to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4976 protect a contiguous array of any number of values, rather than
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4977 just a single lvalue. To effect this, call @code{GCPRO@var{n}} as usual on
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4978 the first object in the array and then set @code{gcpro@var{n}.nvars}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4979
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4980 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4981 @strong{Strings are relocated.} What this means in practice is that the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4982 pointer obtained using @code{XSTRING_DATA()} is liable to change at any
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4983 time, and you should never keep it around past any function call, or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4984 pass it as an argument to any function that might cause a garbage
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4985 collection. This is why a number of functions accept either a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4986 ``non-relocatable'' @code{char *} pointer or a relocatable Lisp string,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4987 and only access the Lisp string's data at the very last minute. In some
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4988 cases, you may end up having to @code{alloca()} some space and copy the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4989 string's data into it.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4990
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4991 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4992 By convention, if you have to nest @code{GCPRO}'s, use @code{NGCPRO@var{n}}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4993 (along with @code{struct gcpro ngcpro1, ngcpro2}, etc.), @code{NNGCPRO@var{n}},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4994 etc. This avoids compiler warnings about shadowed locals.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4995
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4996 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4997 It is @emph{always} better to err on the side of extra @code{GCPRO}s
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4998 rather than too few. The extra cycles spent on this are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4999 almost never going to make a whit of difference in the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5000 speed of anything.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5001
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5002 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5003 The general rule to follow is that caller, not callee, @code{GCPRO}s.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5004 That is, you should not have to explicitly @code{GCPRO} any Lisp objects
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5005 that are passed in as parameters.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5006
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5007 One exception from this rule is if you ever plan to change the parameter
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5008 value, and store a new object in it. In that case, you @emph{must}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5009 @code{GCPRO} the parameter, because otherwise the new object will not be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5010 protected.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5011
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5012 So, if you create any Lisp objects (remember, this happens in all sorts
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5013 of circumstances, e.g. with @code{Fcons()}, etc.), you are responsible
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5014 for @code{GCPRO}ing them, unless you are @emph{absolutely sure} that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5015 there's no possibility that a garbage-collection can occur while you
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5016 need to use the object. Even then, consider @code{GCPRO}ing.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5017
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5018 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5019 A garbage collection can occur whenever anything calls @code{Feval}, or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5020 whenever a QUIT can occur where execution can continue past
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5021 this. (Remember, this is almost anywhere.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5022
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5023 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5024 If you have the @emph{least smidgeon of doubt} about whether
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5025 you need to @code{GCPRO}, you should @code{GCPRO}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5026
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5027 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5028 Beware of @code{GCPRO}ing something that is uninitialized. If you have
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5029 any shade of doubt about this, initialize all your variables to @code{Qnil}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5030
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5031 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5032 Be careful of traps, like calling @code{Fcons()} in the argument to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5033 another function. By the ``caller protects'' law, you should be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5034 @code{GCPRO}ing the newly-created cons, but you aren't. A certain
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5035 number of functions that are commonly called on freshly created stuff
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5036 (e.g. @code{nconc2()}, @code{Fsignal()}), break the ``caller protects''
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5037 law and go ahead and @code{GCPRO} their arguments so as to simplify
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5038 things, but make sure and check if it's OK whenever doing something like
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5039 this.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5040
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5041 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5042 Once again, remember to @code{GCPRO}! Bugs resulting from insufficient
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5043 @code{GCPRO}ing are intermittent and extremely difficult to track down,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5044 often showing up in crashes inside of @code{garbage-collect} or in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5045 weirdly corrupted objects or even in incorrect values in a totally
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5046 different section of code.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5047 @end enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5048
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5049 @cindex garbage collection, conservative
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5050 @cindex conservative garbage collection
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5051 Given the extremely error-prone nature of the @code{GCPRO} scheme, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5052 the difficulties in tracking down, it should be considered a deficiency
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5053 in the XEmacs code. A solution to this problem would involve
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5054 implementing so-called @dfn{conservative} garbage collection for the C
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5055 stack. That involves looking through all of stack memory and treating
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5056 anything that looks like a reference to an object as a reference. This
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5057 will result in a few objects not getting collected when they should, but
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5058 it obviates the need for @code{GCPRO}ing, and allows garbage collection
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5059 to happen at any point at all, such as during object allocation.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5060
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
5061 @node Garbage Collection - Step by Step
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5062 @section Garbage Collection - Step by Step
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
5063 @cindex garbage collection - step by step
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5064
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5065 @menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5066 * Invocation::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5067 * garbage_collect_1::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5068 * mark_object::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5069 * gc_sweep::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5070 * sweep_lcrecords_1::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5071 * compact_string_chars::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5072 * sweep_strings::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5073 * sweep_bit_vectors_1::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5074 @end menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5075
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
5076 @node Invocation
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5077 @subsection Invocation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5078 @cindex garbage collection, invocation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5079
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5080 The first thing that anyone should know about garbage collection is:
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5081 when and how the garbage collector is invoked. One might think that this
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5082 could happen every time new memory is allocated, e.g. new objects are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5083 created, but this is @emph{not} the case. Instead, we have the following
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5084 situation:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5085
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5086 The entry point of any process of garbage collection is an invocation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5087 of the function @code{garbage_collect_1} in file @code{alloc.c}. The
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5088 invocation can occur @emph{explicitly} by calling the function
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5089 @code{Fgarbage_collect} (in addition this function provides information
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5090 about the freed memory), or can occur @emph{implicitly} in four different
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5091 situations:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5092 @enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5093 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5094 In function @code{main_1} in file @code{emacs.c}. This function is called
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5095 at each startup of xemacs. The garbage collection is invoked after all
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5096 initial creations are completed, but only if a special internal error
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5097 checking-constant @code{ERROR_CHECK_GC} is defined.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5098 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5099 In function @code{disksave_object_finalization} in file
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5100 @code{alloc.c}. The only purpose of this function is to clear the
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5101 objects from memory which need not be stored with xemacs when we dump out
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5102 an executable. This is only done by @code{Fdump_emacs} or by
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5103 @code{Fdump_emacs_data} respectively (both in @code{emacs.c}). The
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5104 actual clearing is accomplished by making these objects unreachable and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5105 starting a garbage collection. The function is only used while building
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5106 xemacs.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5107 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5108 In function @code{Feval / eval} in file @code{eval.c}. Each time the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5109 well known and often used function eval is called to evaluate a form,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5110 one of the first things that could happen, is a potential call of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5111 @code{garbage_collect_1}. There exist three global variables,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5112 @code{consing_since_gc} (counts the created cons-cells since the last
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5113 garbage collection), @code{gc_cons_threshold} (a specified threshold
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5114 after which a garbage collection occurs) and @code{always_gc}. If
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5115 @code{always_gc} is set or if the threshold is exceeded, the garbage
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5116 collection will start.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5117 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5118 In function @code{Ffuncall / funcall} in file @code{eval.c}. This
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5119 function evaluates calls of elisp functions and works according to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5120 @code{Feval}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5121 @end enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5122
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5123 The upshot is that garbage collection can basically occur everywhere
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5124 @code{Feval}, respectively @code{Ffuncall}, is used - either directly or
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5125 through another function. Since calls to these two functions are hidden
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5126 in various other functions, many calls to @code{garbage_collect_1} are
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5127 not obviously foreseeable, and therefore unexpected. Instances where
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5128 they are used that are worth remembering are various elisp commands, as
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5129 for example @code{or}, @code{and}, @code{if}, @code{cond}, @code{while},
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5130 @code{setq}, etc., miscellaneous @code{gui_item_...} functions,
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5131 everything related to @code{eval} (@code{Feval_buffer}, @code{call0},
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5132 ...) and inside @code{Fsignal}. The latter is used to handle signals, as
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 442
diff changeset
5133 for example the ones raised by every @code{QUIT}-macro triggered after
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5134 pressing Ctrl-g.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5135
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
5136 @node garbage_collect_1
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5137 @subsection @code{garbage_collect_1}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5138 @cindex @code{garbage_collect_1}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5139
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5140 We can now describe exactly what happens after the invocation takes
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5141 place.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5142 @enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5143 @item
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5144 There are several cases in which the garbage collector is left immediately:
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5145 when we are already garbage collecting (@code{gc_in_progress}), when
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5146 the garbage collection is somehow forbidden
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5147 (@code{gc_currently_forbidden}), when we are currently displaying something
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5148 (@code{in_display}) or when we are preparing for the armageddon of the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5149 whole system (@code{preparing_for_armageddon}).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5150 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5151 Next the correct frame in which to put
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5152 all the output occurring during garbage collecting is determined. In
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5153 order to be able to restore the old display's state after displaying the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5154 message, some data about the current cursor position has to be
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5155 saved. The variables @code{pre_gc_cursor} and @code{cursor_changed} take
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5156 care of that.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5157 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5158 The state of @code{gc_currently_forbidden} must be restored after
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5159 the garbage collection, no matter what happens during the process. We
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5160 accomplish this by @code{record_unwind_protect}ing the suitable function
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5161 @code{restore_gc_inhibit} together with the current value of
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5162 @code{gc_currently_forbidden}.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5163 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5164 If we are concurrently running an interactive xemacs session, the next step
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5165 is simply to show the garbage collector's cursor/message.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5166 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5167 The following steps are the intrinsic steps of the garbage collector,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5168 therefore @code{gc_in_progress} is set.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5169 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5170 For debugging purposes, it is possible to copy the current C stack
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5171 frame. However, this seems to be a currently unused feature.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5172 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5173 Before actually starting to go over all live objects, references to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5174 objects that are no longer used are pruned. We only have to do this for events
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5175 (@code{clear_event_resource}) and for specifiers
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5176 (@code{cleanup_specifiers}).
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5177 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5178 Now the mark phase begins and marks all accessible elements. In order to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5179 start from
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5180 all slots that serve as roots of accessibility, the function
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5181 @code{mark_object} is called for each root individually to go out from
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5182 there to mark all reachable objects. All roots that are traversed are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5183 shown in their processed order:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5184 @itemize @bullet
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5185 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5186 all constant symbols and static variables that are registered via
452
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
5187 @code{staticpro}@ in the dynarr @code{staticpros}.
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5188 @xref{Adding Global Lisp Variables}.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5189 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5190 all Lisp objects that are created in C functions and that must be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5191 protected from freeing them. They are registered in the global
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5192 list @code{gcprolist}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5193 @xref{GCPROing}.
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5194 @item
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5195 all local variables (i.e. their name fields @code{symbol} and old
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5196 values @code{old_values}) that are bound during the evaluation by the Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5197 engine. They are stored in @code{specbinding} structs pushed on a stack
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5198 called @code{specpdl}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5199 @xref{Dynamic Binding; The specbinding Stack; Unwind-Protects}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5200 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5201 all catch blocks that the Lisp engine encounters during the evaluation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5202 cause the creation of structs @code{catchtag} inserted in the list
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5203 @code{catchlist}. Their tag (@code{tag}) and value (@code{val} fields
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5204 are freshly created objects and therefore have to be marked.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5205 @xref{Catch and Throw}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5206 @item
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5207 every function application pushes new structs @code{backtrace}
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5208 on the call stack of the Lisp engine (@code{backtrace_list}). The unique
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5209 parts that have to be marked are the fields for each function
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5210 (@code{function}) and all their arguments (@code{args}).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5211 @xref{Evaluation}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5212 @item
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5213 all objects that are used by the redisplay engine that must not be freed
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5214 are marked by a special function called @code{mark_redisplay} (in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5215 @code{redisplay.c}).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5216 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5217 all objects created for profiling purposes are allocated by C functions
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5218 instead of using the lisp allocation mechanisms. In order to receive the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5219 right ones during the sweep phase, they also have to be marked
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5220 manually. That is done by the function @code{mark_profiling_info}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5221 @end itemize
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5222 @item
436
080151679be2 Import from CVS: tag r21-2-26
cvs
parents: 428
diff changeset
5223 Hash tables in XEmacs belong to a kind of special objects that
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5224 make use of a concept often called 'weak pointers'.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5225 To make a long story short, these kind of pointers are not followed
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5226 during the estimation of the live objects during garbage collection.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5227 Any object referenced only by weak pointers is collected
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5228 anyway, and the reference to it is cleared. In hash tables there are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5229 different usage patterns of them, manifesting in different types of hash
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5230 tables, namely 'non-weak', 'weak', 'key-weak' and 'value-weak'
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5231 (internally also 'key-car-weak' and 'value-car-weak') hash tables, each
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5232 clearing entries depending on different conditions. More information can
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5233 be found in the documentation to the function @code{make-hash-table}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5234
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5235 Because there are complicated dependency rules about when and what to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5236 mark while processing weak hash tables, the standard @code{marker}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5237 method is only active if it is marking non-weak hash tables. As soon as
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5238 a weak component is in the table, the hash table entries are ignored
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5239 while marking. Instead their marking is done each separately by the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5240 function @code{finish_marking_weak_hash_tables}. This function iterates
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5241 over each hash table entry @code{hentries} for each weak hash table in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5242 @code{Vall_weak_hash_tables}. Depending on the type of a table, the
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5243 appropriate action is performed.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5244 If a table is acting as @code{HASH_TABLE_KEY_WEAK}, and a key already marked,
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5245 everything reachable from the @code{value} component is marked. If it is
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5246 acting as a @code{HASH_TABLE_VALUE_WEAK} and the value component is
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5247 already marked, the marking starts beginning only from the
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5248 @code{key} component.
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5249 If it is a @code{HASH_TABLE_KEY_CAR_WEAK} and the car
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5250 of the key entry is already marked, we mark both the @code{key} and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5251 @code{value} components.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5252 Finally, if the table is of the type @code{HASH_TABLE_VALUE_CAR_WEAK}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5253 and the car of the value components is already marked, again both the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5254 @code{key} and the @code{value} components get marked.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5255
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5256 Again, there are lists with comparable properties called weak
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5257 lists. There exist different peculiarities of their types called
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5258 @code{simple}, @code{assoc}, @code{key-assoc} and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5259 @code{value-assoc}. You can find further details about them in the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5260 description to the function @code{make-weak-list}. The scheme of their
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5261 marking is similar: all weak lists are listed in @code{Qall_weak_lists},
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5262 therefore we iterate over them. The marking is advanced until we hit an
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5263 already marked pair. Then we know that during a former run all
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5264 the rest has been marked completely. Again, depending on the special
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5265 type of the weak list, our jobs differ. If it is a @code{WEAK_LIST_SIMPLE}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5266 and the elem is marked, we mark the @code{cons} part. If it is a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5267 @code{WEAK_LIST_ASSOC} and not a pair or a pair with both marked car and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5268 cdr, we mark the @code{cons} and the @code{elem}. If it is a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5269 @code{WEAK_LIST_KEY_ASSOC} and not a pair or a pair with a marked car of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5270 the elem, we mark the @code{cons} and the @code{elem}. Finally, if it is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5271 a @code{WEAK_LIST_VALUE_ASSOC} and not a pair or a pair with a marked
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5272 cdr of the elem, we mark both the @code{cons} and the @code{elem}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5273
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5274 Since, by marking objects in reach from weak hash tables and weak lists,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5275 other objects could get marked, this perhaps implies further marking of
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5276 other weak objects, both finishing functions are redone as long as
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5277 yet unmarked objects get freshly marked.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5278
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5279 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5280 After completing the special marking for the weak hash tables and for the weak
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5281 lists, all entries that point to objects that are going to be swept in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5282 the further process are useless, and therefore have to be removed from
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5283 the table or the list.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5284
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5285 The function @code{prune_weak_hash_tables} does the job for weak hash
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5286 tables. Totally unmarked hash tables are removed from the list
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5287 @code{Vall_weak_hash_tables}. The other ones are treated more carefully
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5288 by scanning over all entries and removing one as soon as one of
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5289 the components @code{key} and @code{value} is unmarked.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5290
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5291 The same idea applies to the weak lists. It is accomplished by
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5292 @code{prune_weak_lists}: An unmarked list is pruned from
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5293 @code{Vall_weak_lists} immediately. A marked list is treated more
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5294 carefully by going over it and removing just the unmarked pairs.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5295
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5296 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5297 The function @code{prune_specifiers} checks all listed specifiers held
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5298 in @code{Vall_specifiers} and removes the ones from the lists that are
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5299 unmarked.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5300
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5301 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5302 All syntax tables are stored in a list called
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5303 @code{Vall_syntax_tables}. The function @code{prune_syntax_tables} walks
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5304 through it and unlinks the tables that are unmarked.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5305
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5306 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5307 Next, we will attack the complete sweeping - the function
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5308 @code{gc_sweep} which holds the predominance.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5309 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5310 First, all the variables with respect to garbage collection are
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5311 reset. @code{consing_since_gc} - the counter of the created cells since
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5312 the last garbage collection - is set back to 0, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5313 @code{gc_in_progress} is not @code{true} anymore.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5314 @item
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5315 In case the session is interactive, the displayed cursor and message are
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5316 removed again.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5317 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5318 The state of @code{gc_inhibit} is restored to the former value by
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5319 unwinding the stack.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5320 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5321 A small memory reserve is always held back that can be reached by
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5322 @code{breathing_space}. If nothing more is left, we create a new reserve
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5323 and exit.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5324 @end enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5325
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
5326 @node mark_object
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5327 @subsection @code{mark_object}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5328 @cindex @code{mark_object}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5329
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5330 The first thing that is checked while marking an object is whether the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5331 object is a real Lisp object @code{Lisp_Type_Record} or just an integer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5332 or a character. Integers and characters are the only two types that are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5333 stored directly - without another level of indirection, and therefore they
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5334 don't have to be marked and collected.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5335 @xref{How Lisp Objects Are Represented in C}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5336
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5337 The second case is the one we have to handle. It is the one when we are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5338 dealing with a pointer to a Lisp object. But, there exist also three
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5339 possibilities, that prevent us from doing anything while marking: The
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5340 object is read only which prevents it from being garbage collected,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5341 i.e. marked (@code{C_READONLY_RECORD_HEADER}). The object in question is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5342 already marked, and need not be marked for the second time (checked by
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5343 @code{MARKED_RECORD_HEADER_P}). If it is a special, unmarkable object
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5344 (@code{UNMARKABLE_RECORD_HEADER_P}, apparently, these are objects that
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5345 sit in some const space, and can therefore not be marked, see
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5346 @code{this_one_is_unmarkable} in @code{alloc.c}).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5347
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5348 Now, the actual marking is feasible. We do so by once using the macro
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5349 @code{MARK_RECORD_HEADER} to mark the object itself (actually the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5350 special flag in the lrecord header), and calling its special marker
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5351 "method" @code{marker} if available. The marker method marks every
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5352 other object that is in reach from our current object. Note, that these
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5353 marker methods should not call @code{mark_object} recursively, but
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5354 instead should return the next object from where further marking has to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5355 be performed.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5356
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5357 In case another object was returned, as mentioned before, we reiterate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5358 the whole @code{mark_object} process beginning with this next object.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5359
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
5360 @node gc_sweep
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5361 @subsection @code{gc_sweep}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5362 @cindex @code{gc_sweep}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5363
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5364 The job of this function is to free all unmarked records from memory. As
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5365 we know, there are different types of objects implemented and managed, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5366 consequently different ways to free them from memory.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5367 @xref{Introduction to Allocation}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5368
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5369 We start with all objects stored through @code{lcrecords}. All
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5370 bulkier objects are allocated and handled using that scheme of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5371 @code{lcrecords}. Each object is @code{malloc}ed separately
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5372 instead of placing it in one of the contiguous frob blocks. All types
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5373 that are currently stored
438
84b14dcb0985 Import from CVS: tag r21-2-27
cvs
parents: 436
diff changeset
5374 using @code{lcrecords}'s @code{alloc_lcrecord} and
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5375 @code{make_lcrecord_list} are the types: vectors, buffers,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5376 char-table, char-table-entry, console, weak-list, database, device,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5377 ldap, hash-table, command-builder, extent-auxiliary, extent-info, face,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5378 coding-system, frame, image-instance, glyph, popup-data, gui-item,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5379 keymap, charset, color_instance, font_instance, opaque, opaque-list,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5380 process, range-table, specifier, symbol-value-buffer-local,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5381 symbol-value-lisp-magic, symbol-value-varalias, toolbar-button,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5382 tooltalk-message, tooltalk-pattern, window, and window-configuration. We
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5383 take care of them in the fist place
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5384 in order to be able to handle and to finalize items stored in them more
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5385 easily. The function @code{sweep_lcrecords_1} as described below is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5386 doing the whole job for us.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5387 For a description about the internals: @xref{lrecords}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5388
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5389 Our next candidates are the other objects that behave quite differently
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5390 than everything else: the strings. They consists of two parts, a
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5391 fixed-size portion (@code{struct Lisp_String}) holding the string's
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5392 length, its property list and a pointer to the second part, and the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5393 actual string data, which is stored in string-chars blocks comparable to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5394 frob blocks. In this block, the data is not only freed, but also a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5395 compression of holes is made, i.e. all strings are relocated together.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5396 @xref{String}. This compacting phase is performed by the function
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5397 @code{compact_string_chars}, the actual sweeping by the function
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5398 @code{sweep_strings} is described below.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5399
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5400 After that, the other types are swept step by step using functions
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5401 @code{sweep_conses}, @code{sweep_bit_vectors_1},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5402 @code{sweep_compiled_functions}, @code{sweep_floats},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5403 @code{sweep_symbols}, @code{sweep_extents}, @code{sweep_markers} and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5404 @code{sweep_extents}. They are the fixed-size types cons, floats,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5405 compiled-functions, symbol, marker, extent, and event stored in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5406 so-called "frob blocks", and therefore we can basically do the same on
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5407 every type objects, using the same macros, especially defined only to
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5408 handle everything with respect to fixed-size blocks. The only fixed-size
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5409 type that is not handled here are the fixed-size portion of strings,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5410 because we took special care of them earlier.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5411
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5412 The only big exceptions are bit vectors stored differently and
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5413 therefore treated differently by the function @code{sweep_bit_vectors_1}
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5414 described later.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5415
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5416 At first, we need some brief information about how
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5417 these fixed-size types are managed in general, in order to understand
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5418 how the sweeping is done. They have all a fixed size, and are therefore
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5419 stored in big blocks of memory - allocated at once - that can hold a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5420 certain amount of objects of one type. The macro
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5421 @code{DECLARE_FIXED_TYPE_ALLOC} creates the suitable structures for
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5422 every type. More precisely, we have the block struct
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5423 (holding a pointer to the previous block @code{prev} and the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5424 objects in @code{block[]}), a pointer to current block
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5425 (@code{current_..._block)}) and its last index
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5426 (@code{current_..._block_index}), and a pointer to the free list that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5427 will be created. Also a macro @code{FIXED_TYPE_FROM_BLOCK} plus some
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5428 related macros exists that are used to obtain a new object, either from
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5429 the free list @code{ALLOCATE_FIXED_TYPE_1} if there is an unused object
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5430 of that type stored or by allocating a completely new block using
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5431 @code{ALLOCATE_FIXED_TYPE_FROM_BLOCK}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5432
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5433 The rest works as follows: all of them define a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5434 macro @code{UNMARK_...} that is used to unmark the object. They define a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5435 macro @code{ADDITIONAL_FREE_...} that defines additional work that has
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5436 to be done when converting an object from in use to not in use (so far,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5437 only markers use it in order to unchain them). Then, they all call
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5438 the macro @code{SWEEP_FIXED_TYPE_BLOCK} instantiated with their type name
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5439 and their struct name.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5440
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5441 This call in particular does the following: we go over all blocks
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5442 starting with the current moving towards the oldest.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5443 For each block, we look at every object in it. If the object already
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5444 freed (checked with @code{FREE_STRUCT_P} using the first pointer of the
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5445 object), or if it is
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5446 set to read only (@code{C_READONLY_RECORD_HEADER_P}, nothing must be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5447 done. If it is unmarked (checked with @code{MARKED_RECORD_HEADER_P}), it
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5448 is put in the free list and set free (using the macro
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5449 @code{FREE_FIXED_TYPE}, otherwise it stays in the block, but is unmarked
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5450 (by @code{UNMARK_...}). While going through one block, we note if the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5451 whole block is empty. If so, the whole block is freed (using
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5452 @code{xfree}) and the free list state is set to the state it had before
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5453 handling this block.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5454
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
5455 @node sweep_lcrecords_1
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5456 @subsection @code{sweep_lcrecords_1}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5457 @cindex @code{sweep_lcrecords_1}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5458
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5459 After nullifying the complete lcrecord statistics, we go over all
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5460 lcrecords two separate times. They are all chained together in a list with
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5461 a head called @code{all_lcrecords}.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5462
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5463 The first loop calls for each object its @code{finalizer} method, but only
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5464 in the case that it is not read only
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5465 (@code{C_READONLY_RECORD_HEADER_P)}, it is not already marked
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5466 (@code{MARKED_RECORD_HEADER_P}), it is not already in a free list (list of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5467 freed objects, field @code{free}) and finally it owns a finalizer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5468 method.
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5469
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5470 The second loop actually frees the appropriate objects again by iterating
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5471 through the whole list. In case an object is read only or marked, it
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5472 has to persist, otherwise it is manually freed by calling
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5473 @code{xfree}. During this loop, the lcrecord statistics are kept up to
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5474 date by calling @code{tick_lcrecord_stats} with the right arguments,
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5475
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
5476 @node compact_string_chars
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5477 @subsection @code{compact_string_chars}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5478 @cindex @code{compact_string_chars}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5479
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5480 The purpose of this function is to compact all the data parts of the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5481 strings that are held in so-called @code{string_chars_block}, i.e. the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5482 strings that do not exceed a certain maximal length.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5483
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5484 The procedure with which this is done is as follows. We are keeping two
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5485 positions in the @code{string_chars_block}s using two pointer/integer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5486 pairs, namely @code{from_sb}/@code{from_pos} and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5487 @code{to_sb}/@code{to_pos}. They stand for the actual positions, from
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5488 where to where, to copy the actually handled string.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5489
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5490 While going over all chained @code{string_char_block}s and their held
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5491 strings, staring at @code{first_string_chars_block}, both pointers
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5492 are advanced and eventually a string is copied from @code{from_sb} to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5493 @code{to_sb}, depending on the status of the pointed at strings.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5494
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5495 More precisely, we can distinguish between the following actions.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5496 @itemize @bullet
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5497 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5498 The string at @code{from_sb}'s position could be marked as free, which
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5499 is indicated by an invalid pointer to the pointer that should point back
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5500 to the fixed size string object, and which is checked by
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5501 @code{FREE_STRUCT_P}. In this case, the @code{from_sb}/@code{from_pos}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5502 is advanced to the next string, and nothing has to be copied.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5503 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5504 Also, if a string object itself is unmarked, nothing has to be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5505 copied. We likewise advance the @code{from_sb}/@code{from_pos}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5506 pair as described above.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5507 @item
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5508 In all other cases, we have a marked string at hand. The string data
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5509 must be moved from the from-position to the to-position. In case
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5510 there is not enough space in the actual @code{to_sb}-block, we advance
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5511 this pointer to the beginning of the next block before copying. In case the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5512 from and to positions are different, we perform the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5513 actual copying using the library function @code{memmove}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5514 @end itemize
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5515
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5516 After compacting, the pointer to the current
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5517 @code{string_chars_block}, sitting in @code{current_string_chars_block},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5518 is reset on the last block to which we moved a string,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5519 i.e. @code{to_block}, and all remaining blocks (we know that they just
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5520 carry garbage) are explicitly @code{xfree}d.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5521
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
5522 @node sweep_strings
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5523 @subsection @code{sweep_strings}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5524 @cindex @code{sweep_strings}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5525
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5526 The sweeping for the fixed sized string objects is essentially exactly
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5527 the same as it is for all other fixed size types. As before, the freeing
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5528 into the suitable free list is done by using the macro
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5529 @code{SWEEP_FIXED_SIZE_BLOCK} after defining the right macros
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5530 @code{UNMARK_string} and @code{ADDITIONAL_FREE_string}. These two
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5531 definitions are a little bit special compared to the ones used
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5532 for the other fixed size types.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5533
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5534 @code{UNMARK_string} is defined the same way except some additional code
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5535 used for updating the bookkeeping information.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5536
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5537 For strings, @code{ADDITIONAL_FREE_string} has to do something in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5538 addition: in case, the string was not allocated in a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5539 @code{string_chars_block} because it exceeded the maximal length, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5540 therefore it was @code{malloc}ed separately, we know also @code{xfree}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5541 it explicitly.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5542
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
5543 @node sweep_bit_vectors_1
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5544 @subsection @code{sweep_bit_vectors_1}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5545 @cindex @code{sweep_bit_vectors_1}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5546
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5547 Bit vectors are also one of the rare types that are @code{malloc}ed
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5548 individually. Consequently, while sweeping, all further needless
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5549 bit vectors must be freed by hand. This is done, as one might imagine,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5550 the expected way: since they are all registered in a list called
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5551 @code{all_bit_vectors}, all elements of that list are traversed,
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5552 all unmarked bit vectors are unlinked by calling @code{xfree} and all of
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5553 them become unmarked.
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5554 In addition, the bookkeeping information used for garbage
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5555 collector's output purposes is updated.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5556
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
5557 @node Integers and Characters
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5558 @section Integers and Characters
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
5559 @cindex integers and characters
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
5560 @cindex characters, integers and
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5561
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5562 Integer and character Lisp objects are created from integers using the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5563 macros @code{XSETINT()} and @code{XSETCHAR()} or the equivalent
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5564 functions @code{make_int()} and @code{make_char()}. (These are actually
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5565 macros on most systems.) These functions basically just do some moving
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5566 of bits around, since the integral value of the object is stored
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5567 directly in the @code{Lisp_Object}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5568
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5569 @code{XSETINT()} and the like will truncate values given to them that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5570 are too big; i.e. you won't get the value you expected but the tag bits
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5571 will at least be correct.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5572
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
5573 @node Allocation from Frob Blocks
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5574 @section Allocation from Frob Blocks
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
5575 @cindex allocation from frob blocks
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
5576 @cindex frob blocks, allocation from
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5577
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5578 The uninitialized memory required by a @code{Lisp_Object} of a particular type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5579 is allocated using
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5580 @code{ALLOCATE_FIXED_TYPE()}. This only occurs inside of the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5581 lowest-level object-creating functions in @file{alloc.c}:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5582 @code{Fcons()}, @code{make_float()}, @code{Fmake_byte_code()},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5583 @code{Fmake_symbol()}, @code{allocate_extent()},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5584 @code{allocate_event()}, @code{Fmake_marker()}, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5585 @code{make_uninit_string()}. The idea is that, for each type, there are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5586 a number of frob blocks (each 2K in size); each frob block is divided up
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5587 into object-sized chunks. Each frob block will have some of these
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5588 chunks that are currently assigned to objects, and perhaps some that are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5589 free. (If a frob block has nothing but free chunks, it is freed at the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5590 end of the garbage collection cycle.) The free chunks are stored in a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5591 free list, which is chained by storing a pointer in the first four bytes
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5592 of the chunk. (Except for the free chunks at the end of the last frob
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5593 block, which are handled using an index which points past the end of the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5594 last-allocated chunk in the last frob block.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5595 @code{ALLOCATE_FIXED_TYPE()} first tries to retrieve a chunk from the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5596 free list; if that fails, it calls
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5597 @code{ALLOCATE_FIXED_TYPE_FROM_BLOCK()}, which looks at the end of the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5598 last frob block for space, and creates a new frob block if there is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5599 none. (There are actually two versions of these macros, one of which is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5600 more defensive but less efficient and is used for error-checking.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5601
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
5602 @node lrecords
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5603 @section lrecords
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
5604 @cindex lrecords
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5605
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5606 [see @file{lrecord.h}]
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5607
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5608 All lrecords have at the beginning of their structure a @code{struct
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5609 lrecord_header}. This just contains a type number and some flags,
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5610 including the mark bit. All builtin type numbers are defined as
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5611 constants in @code{enum lrecord_type}, to allow the compiler to generate
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5612 more efficient code for @code{@var{type}P}. The type number, thru the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5613 @code{lrecord_implementation_table}, gives access to a @code{struct
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5614 lrecord_implementation}, which is a structure containing method pointers
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5615 and such. There is one of these for each type, and it is a global,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5616 constant, statically-declared structure that is declared in the
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5617 @code{DEFINE_LRECORD_IMPLEMENTATION()} macro.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5618
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5619 Simple lrecords (of type (b) above) just have a @code{struct
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5620 lrecord_header} at their beginning. lcrecords, however, actually have a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5621 @code{struct lcrecord_header}. This, in turn, has a @code{struct
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5622 lrecord_header} at its beginning, so sanity is preserved; but it also
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5623 has a pointer used to chain all lcrecords together, and a special ID
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5624 field used to distinguish one lcrecord from another. (This field is used
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5625 only for debugging and could be removed, but the space gain is not
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5626 significant.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5627
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5628 Simple lrecords are created using @code{ALLOCATE_FIXED_TYPE()}, just
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5629 like for other frob blocks. The only change is that the implementation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5630 pointer must be initialized correctly. (The implementation structure for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5631 an lrecord, or rather the pointer to it, is named @code{lrecord_float},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5632 @code{lrecord_extent}, @code{lrecord_buffer}, etc.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5633
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5634 lcrecords are created using @code{alloc_lcrecord()}. This takes a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5635 size to allocate and an implementation pointer. (The size needs to be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5636 passed because some lcrecords, such as window configurations, are of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5637 variable size.) This basically just @code{malloc()}s the storage,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5638 initializes the @code{struct lcrecord_header}, and chains the lcrecord
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5639 onto the head of the list of all lcrecords, which is stored in the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5640 variable @code{all_lcrecords}. The calls to @code{alloc_lcrecord()}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5641 generally occur in the lowest-level allocation function for each lrecord
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5642 type.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5643
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5644 Whenever you create an lrecord, you need to call either
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5645 @code{DEFINE_LRECORD_IMPLEMENTATION()} or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5646 @code{DEFINE_LRECORD_SEQUENCE_IMPLEMENTATION()}. This needs to be
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5647 specified in a @file{.c} file, at the top level. What this actually
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5648 does is define and initialize the implementation structure for the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5649 lrecord. (And possibly declares a function @code{error_check_foo()} that
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5650 implements the @code{XFOO()} macro when error-checking is enabled.) The
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5651 arguments to the macros are the actual type name (this is used to
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5652 construct the C variable name of the lrecord implementation structure
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5653 and related structures using the @samp{##} macro concatenation
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5654 operator), a string that names the type on the Lisp level (this may not
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5655 be the same as the C type name; typically, the C type name has
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5656 underscores, while the Lisp string has dashes), various method pointers,
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5657 and the name of the C structure that contains the object. The methods
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5658 are used to encapsulate type-specific information about the object, such
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5659 as how to print it or mark it for garbage collection, so that it's easy
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5660 to add new object types without having to add a specific case for each
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5661 new type in a bunch of different places.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5662
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5663 The difference between @code{DEFINE_LRECORD_IMPLEMENTATION()} and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5664 @code{DEFINE_LRECORD_SEQUENCE_IMPLEMENTATION()} is that the former is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5665 used for fixed-size object types and the latter is for variable-size
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5666 object types. Most object types are fixed-size; some complex
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5667 types, however (e.g. window configurations), are variable-size.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5668 Variable-size object types have an extra method, which is called
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5669 to determine the actual size of a particular object of that type.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5670 (Currently this is only used for keeping allocation statistics.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5671
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5672 For the purpose of keeping allocation statistics, the allocation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5673 engine keeps a list of all the different types that exist. Note that,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5674 since @code{DEFINE_LRECORD_IMPLEMENTATION()} is a macro that is
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5675 specified at top-level, there is no way for it to initialize the global
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5676 data structures containing type information, like
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5677 @code{lrecord_implementations_table}. For this reason a call to
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5678 @code{INIT_LRECORD_IMPLEMENTATION} must be added to the same source file
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5679 containing @code{DEFINE_LRECORD_IMPLEMENTATION}, but instead of to the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5680 top level, to one of the init functions, typically
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5681 @code{syms_of_@var{foo}.c}. @code{INIT_LRECORD_IMPLEMENTATION} must be
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5682 called before an object of this type is used.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5683
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5684 The type number is also used to index into an array holding the number
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5685 of objects of each type and the total memory allocated for objects of
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5686 that type. The statistics in this array are computed during the sweep
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5687 stage. These statistics are returned by the call to
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5688 @code{garbage-collect}.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5689
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5690 Note that for every type defined with a @code{DEFINE_LRECORD_*()}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5691 macro, there needs to be a @code{DECLARE_LRECORD_IMPLEMENTATION()}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5692 somewhere in a @file{.h} file, and this @file{.h} file needs to be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5693 included by @file{inline.c}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5694
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5695 Furthermore, there should generally be a set of @code{XFOOBAR()},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5696 @code{FOOBARP()}, etc. macros in a @file{.h} (or occasionally @file{.c})
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5697 file. To create one of these, copy an existing model and modify as
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5698 necessary.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5699
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5700 @strong{Please note:} If you define an lrecord in an external
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5701 dynamically-loaded module, you must use @code{DECLARE_EXTERNAL_LRECORD},
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5702 @code{DEFINE_EXTERNAL_LRECORD_IMPLEMENTATION}, and
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5703 @code{DEFINE_EXTERNAL_LRECORD_SEQUENCE_IMPLEMENTATION} instead of the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5704 non-EXTERNAL forms. These macros will dynamically add new type numbers
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5705 to the global enum that records them, whereas the non-EXTERNAL forms
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5706 assume that the programmer has already inserted the correct type numbers
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5707 into the enum's code at compile-time.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5708
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5709 The various methods in the lrecord implementation structure are:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5710
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5711 @enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5712 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5713 @cindex mark method
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5714 A @dfn{mark} method. This is called during the marking stage and passed
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5715 a function pointer (usually the @code{mark_object()} function), which is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5716 used to mark an object. All Lisp objects that are contained within the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5717 object need to be marked by applying this function to them. The mark
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 442
diff changeset
5718 method should also return a Lisp object, which should be either @code{nil} or
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5719 an object to mark. (This can be used in lieu of calling
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5720 @code{mark_object()} on the object, to reduce the recursion depth, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5721 consequently should be the most heavily nested sub-object, such as a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5722 long list.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5723
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5724 @strong{Please note:} When the mark method is called, garbage collection
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5725 is in progress, and special precautions need to be taken when accessing
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5726 objects; see section (B) above.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5727
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5728 If your mark method does not need to do anything, it can be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5729 @code{NULL}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5730
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5731 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5732 A @dfn{print} method. This is called to create a printed representation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5733 of the object, whenever @code{princ}, @code{prin1}, or the like is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5734 called. It is passed the object, a stream to which the output is to be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5735 directed, and an @code{escapeflag} which indicates whether the object's
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5736 printed representation should be @dfn{escaped} so that it is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5737 readable. (This corresponds to the difference between @code{princ} and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5738 @code{prin1}.) Basically, @dfn{escaped} means that strings will have
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5739 quotes around them and confusing characters in the strings such as
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5740 quotes, backslashes, and newlines will be backslashed; and that special
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5741 care will be taken to make symbols print in a readable fashion
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5742 (e.g. symbols that look like numbers will be backslashed). Other
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5743 readable objects should perhaps pass @code{escapeflag} on when
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5744 sub-objects are printed, so that readability is preserved when necessary
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5745 (or if not, always pass in a 1 for @code{escapeflag}). Non-readable
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5746 objects should in general ignore @code{escapeflag}, except that some use
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5747 it as an indication that more verbose output should be given.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5748
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5749 Sub-objects are printed using @code{print_internal()}, which takes
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5750 exactly the same arguments as are passed to the print method.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5751
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5752 Literal C strings should be printed using @code{write_c_string()},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5753 or @code{write_string_1()} for non-null-terminated strings.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5754
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5755 Functions that do not have a readable representation should check the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5756 @code{print_readably} flag and signal an error if it is set.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5757
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5758 If you specify NULL for the print method, the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5759 @code{default_object_printer()} will be used.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5760
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5761 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5762 A @dfn{finalize} method. This is called at the beginning of the sweep
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5763 stage on lcrecords that are about to be freed, and should be used to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5764 perform any extra object cleanup. This typically involves freeing any
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5765 extra @code{malloc()}ed memory associated with the object, releasing any
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5766 operating-system and window-system resources associated with the object
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5767 (e.g. pixmaps, fonts), etc.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5768
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5769 The finalize method can be NULL if nothing needs to be done.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5770
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5771 WARNING #1: The finalize method is also called at the end of the dump
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5772 phase; this time with the for_disksave parameter set to non-zero. The
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5773 object is @emph{not} about to disappear, so you have to make sure to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5774 @emph{not} free any extra @code{malloc()}ed memory if you're going to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5775 need it later. (Also, signal an error if there are any operating-system
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5776 and window-system resources here, because they can't be dumped.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5777
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5778 Finalize methods should, as a rule, set to zero any pointers after
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5779 they've been freed, and check to make sure pointers are not zero before
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5780 freeing. Although I'm pretty sure that finalize methods are not called
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5781 twice on the same object (except for the @code{for_disksave} proviso),
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5782 we've gotten nastily burned in some cases by not doing this.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5783
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5784 WARNING #2: The finalize method is @emph{only} called for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5785 lcrecords, @emph{not} for simply lrecords. If you need a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5786 finalize method for simple lrecords, you have to stick
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5787 it in the @code{ADDITIONAL_FREE_foo()} macro in @file{alloc.c}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5788
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5789 WARNING #3: Things are in an @emph{extremely} bizarre state
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5790 when @code{ADDITIONAL_FREE_foo()} is called, so you have to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5791 be incredibly careful when writing one of these functions.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5792 See the comment in @code{gc_sweep()}. If you ever have to add
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5793 one of these, consider using an lcrecord or dealing with
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5794 the problem in a different fashion.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5795
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5796 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5797 An @dfn{equal} method. This compares the two objects for similarity,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5798 when @code{equal} is called. It should compare the contents of the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5799 objects in some reasonable fashion. It is passed the two objects and a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5800 @dfn{depth} value, which is used to catch circular objects. To compare
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5801 sub-Lisp-objects, call @code{internal_equal()} and bump the depth value
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5802 by one. If this value gets too high, a @code{circular-object} error
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5803 will be signaled.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5804
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5805 If this is NULL, objects are @code{equal} only when they are @code{eq},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5806 i.e. identical.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5807
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5808 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5809 A @dfn{hash} method. This is used to hash objects when they are to be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5810 compared with @code{equal}. The rule here is that if two objects are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5811 @code{equal}, they @emph{must} hash to the same value; i.e. your hash
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5812 function should use some subset of the sub-fields of the object that are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5813 compared in the ``equal'' method. If you specify this method as
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5814 @code{NULL}, the object's pointer will be used as the hash, which will
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5815 @emph{fail} if the object has an @code{equal} method, so don't do this.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5816
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5817 To hash a sub-Lisp-object, call @code{internal_hash()}. Bump the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5818 depth by one, just like in the ``equal'' method.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5819
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5820 To convert a Lisp object directly into a hash value (using
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5821 its pointer), use @code{LISP_HASH()}. This is what happens when
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5822 the hash method is NULL.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5823
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5824 To hash two or more values together into a single value, use
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5825 @code{HASH2()}, @code{HASH3()}, @code{HASH4()}, etc.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5826
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5827 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5828 @dfn{getprop}, @dfn{putprop}, @dfn{remprop}, and @dfn{plist} methods.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5829 These are used for object types that have properties. I don't feel like
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5830 documenting them here. If you create one of these objects, you have to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5831 use different macros to define them,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5832 i.e. @code{DEFINE_LRECORD_IMPLEMENTATION_WITH_PROPS()} or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5833 @code{DEFINE_LRECORD_SEQUENCE_IMPLEMENTATION_WITH_PROPS()}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5834
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5835 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5836 A @dfn{size_in_bytes} method, when the object is of variable-size.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5837 (i.e. declared with a @code{_SEQUENCE_IMPLEMENTATION} macro.) This should
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5838 simply return the object's size in bytes, exactly as you might expect.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5839 For an example, see the methods for window configurations and opaques.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5840 @end enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5841
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
5842 @node Low-level allocation
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5843 @section Low-level allocation
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
5844 @cindex low-level allocation
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
5845 @cindex allocation, low-level
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5846
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5847 Memory that you want to allocate directly should be allocated using
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5848 @code{xmalloc()} rather than @code{malloc()}. This implements
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5849 error-checking on the return value, and once upon a time did some more
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5850 vital stuff (i.e. @code{BLOCK_INPUT}, which is no longer necessary).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5851 Free using @code{xfree()}, and realloc using @code{xrealloc()}. Note
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5852 that @code{xmalloc()} will do a non-local exit if the memory can't be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5853 allocated. (Many functions, however, do not expect this, and thus XEmacs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5854 will likely crash if this happens. @strong{This is a bug.} If you can,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5855 you should strive to make your function handle this OK. However, it's
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5856 difficult in the general circumstance, perhaps requiring extra
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5857 unwind-protects and such.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5858
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5859 Note that XEmacs provides two separate replacements for the standard
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5860 @code{malloc()} library function. These are called @dfn{old GNU malloc}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5861 (@file{malloc.c}) and @dfn{new GNU malloc} (@file{gmalloc.c}),
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5862 respectively. New GNU malloc is better in pretty much every way than
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5863 old GNU malloc, and should be used if possible. (It used to be that on
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5864 some systems, the old one worked but the new one didn't. I think this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5865 was due specifically to a bug in SunOS, which the new one now works
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5866 around; so I don't think the old one ever has to be used any more.) The
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5867 primary difference between both of these mallocs and the standard system
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5868 malloc is that they are much faster, at the expense of increased space.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5869 The basic idea is that memory is allocated in fixed chunks of powers of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5870 two. This allows for basically constant malloc time, since the various
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5871 chunks can just be kept on a number of free lists. (The standard system
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5872 malloc typically allocates arbitrary-sized chunks and has to spend some
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5873 time, sometimes a significant amount of time, walking the heap looking
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5874 for a free block to use and cleaning things up.) The new GNU malloc
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5875 improves on things by allocating large objects in chunks of 4096 bytes
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5876 rather than in ever larger powers of two, which results in ever larger
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5877 wastage. There is a slight speed loss here, but it's of doubtful
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5878 significance.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5879
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5880 NOTE: Apparently there is a third-generation GNU malloc that is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5881 significantly better than the new GNU malloc, and should probably
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5882 be included in XEmacs.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5883
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5884 There is also the relocating allocator, @file{ralloc.c}. This actually
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5885 moves blocks of memory around so that the @code{sbrk()} pointer shrunk
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5886 and virtual memory released back to the system. On some systems,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5887 this is a big win. On all systems, it causes a noticeable (and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5888 sometimes huge) speed penalty, so I turn it off by default.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5889 @file{ralloc.c} only works with the new GNU malloc in @file{gmalloc.c}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5890 There are also two versions of @file{ralloc.c}, one that uses @code{mmap()}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5891 rather than block copies to move data around. This purports to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5892 be faster, although that depends on the amount of data that would
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5893 have had to be block copied and the system-call overhead for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5894 @code{mmap()}. I don't know exactly how this works, except that the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5895 relocating-allocation routines are pretty much used only for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5896 the memory allocated for a buffer, which is the biggest consumer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5897 of space, esp. of space that may get freed later.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5898
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5899 Note that the GNU mallocs have some ``memory warning'' facilities.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5900 XEmacs taps into them and issues a warning through the standard
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5901 warning system, when memory gets to 75%, 85%, and 95% full.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5902 (On some systems, the memory warnings are not functional.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5903
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5904 Allocated memory that is going to be used to make a Lisp object
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5905 is created using @code{allocate_lisp_storage()}. This just calls
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5906 @code{xmalloc()}. It used to verify that the pointer to the memory can
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5907 fit into a Lisp word, before the current Lisp object representation was
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5908 introduced. @code{allocate_lisp_storage()} is called by
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5909 @code{alloc_lcrecord()}, @code{ALLOCATE_FIXED_TYPE()}, and the vector
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5910 and bit-vector creation routines. These routines also call
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5911 @code{INCREMENT_CONS_COUNTER()} at the appropriate times; this keeps
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5912 statistics on how much memory is allocated, so that garbage-collection
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5913 can be invoked when the threshold is reached.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5914
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
5915 @node Cons
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5916 @section Cons
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
5917 @cindex cons
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5918
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5919 Conses are allocated in standard frob blocks. The only thing to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5920 note is that conses can be explicitly freed using @code{free_cons()}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5921 and associated functions @code{free_list()} and @code{free_alist()}. This
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5922 immediately puts the conses onto the cons free list, and decrements
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5923 the statistics on memory allocation appropriately. This is used
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5924 to good effect by some extremely commonly-used code, to avoid
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5925 generating extra objects and thereby triggering GC sooner.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5926 However, you have to be @emph{extremely} careful when doing this.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5927 If you mess this up, you will get BADLY BURNED, and it has happened
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5928 before.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5929
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
5930 @node Vector
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5931 @section Vector
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
5932 @cindex vector
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5933
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5934 As mentioned above, each vector is @code{malloc()}ed individually, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5935 all are threaded through the variable @code{all_vectors}. Vectors are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5936 marked strangely during garbage collection, by kludging the size field.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5937 Note that the @code{struct Lisp_Vector} is declared with its
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5938 @code{contents} field being a @emph{stretchy} array of one element. It
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5939 is actually @code{malloc()}ed with the right size, however, and access
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5940 to any element through the @code{contents} array works fine.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5941
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
5942 @node Bit Vector
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5943 @section Bit Vector
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
5944 @cindex bit vector
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
5945 @cindex vector, bit
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5946
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5947 Bit vectors work exactly like vectors, except for more complicated
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5948 code to access an individual bit, and except for the fact that bit
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5949 vectors are lrecords while vectors are not. (The only difference here is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5950 that there's an lrecord implementation pointer at the beginning and the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5951 tag field in bit vector Lisp words is ``lrecord'' rather than
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5952 ``vector''.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5953
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
5954 @node Symbol
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5955 @section Symbol
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
5956 @cindex symbol
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5957
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5958 Symbols are also allocated in frob blocks. Symbols in the awful
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
5959 horrible obarray structure are chained through their @code{next} field.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5960
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5961 Remember that @code{intern} looks up a symbol in an obarray, creating
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5962 one if necessary.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5963
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
5964 @node Marker
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5965 @section Marker
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
5966 @cindex marker
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5967
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5968 Markers are allocated in frob blocks, as usual. They are kept
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5969 in a buffer unordered, but in a doubly-linked list so that they
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5970 can easily be removed. (Formerly this was a singly-linked list,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5971 but in some cases garbage collection took an extraordinarily
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5972 long time due to the O(N^2) time required to remove lots of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5973 markers from a buffer.) Markers are removed from a buffer in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5974 the finalize stage, in @code{ADDITIONAL_FREE_marker()}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5975
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
5976 @node String
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5977 @section String
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
5978 @cindex string
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5979
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5980 As mentioned above, strings are a special case. A string is logically
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5981 two parts, a fixed-size object (containing the length, property list,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5982 and a pointer to the actual data), and the actual data in the string.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5983 The fixed-size object is a @code{struct Lisp_String} and is allocated in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5984 frob blocks, as usual. The actual data is stored in special
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5985 @dfn{string-chars blocks}, which are 8K blocks of memory.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5986 Currently-allocated strings are simply laid end to end in these
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5987 string-chars blocks, with a pointer back to the @code{struct Lisp_String}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5988 stored before each string in the string-chars block. When a new string
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5989 needs to be allocated, the remaining space at the end of the last
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5990 string-chars block is used if there's enough, and a new string-chars
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5991 block is created otherwise.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5992
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5993 There are never any holes in the string-chars blocks due to the string
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5994 compaction and relocation that happens at the end of garbage collection.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5995 During the sweep stage of garbage collection, when objects are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5996 reclaimed, the garbage collector goes through all string-chars blocks,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5997 looking for unused strings. Each chunk of string data is preceded by a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5998 pointer to the corresponding @code{struct Lisp_String}, which indicates
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5999 both whether the string is used and how big the string is, i.e. how to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6000 get to the next chunk of string data. Holes are compressed by
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6001 block-copying the next string into the empty space and relocating the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6002 pointer stored in the corresponding @code{struct Lisp_String}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6003 @strong{This means you have to be careful with strings in your code.}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6004 See the section above on @code{GCPRO}ing.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6005
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6006 Note that there is one situation not handled: a string that is too big
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6007 to fit into a string-chars block. Such strings, called @dfn{big
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6008 strings}, are all @code{malloc()}ed as their own block. (#### Although it
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6009 would make more sense for the threshold for big strings to be somewhat
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6010 lower, e.g. 1/2 or 1/4 the size of a string-chars block. It seems that
440
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 438
diff changeset
6011 this was indeed the case formerly---indeed, the threshold was set at
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 438
diff changeset
6012 1/8---but Mly forgot about this when rewriting things for 19.8.)
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6013
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6014 Note also that the string data in string-chars blocks is padded as
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6015 necessary so that proper alignment constraints on the @code{struct
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6016 Lisp_String} back pointers are maintained.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6017
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6018 Finally, strings can be resized. This happens in Mule when a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6019 character is substituted with a different-length character, or during
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6020 modeline frobbing. (You could also export this to Lisp, but it's not
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6021 done so currently.) Resizing a string is a potentially tricky process.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6022 If the change is small enough that the padding can absorb it, nothing
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6023 other than a simple memory move needs to be done. Keep in mind,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6024 however, that the string can't shrink too much because the offset to the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6025 next string in the string-chars block is computed by looking at the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6026 length and rounding to the nearest multiple of four or eight. If the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6027 string would shrink or expand beyond the correct padding, new string
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6028 data needs to be allocated at the end of the last string-chars block and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6029 the data moved appropriately. This leaves some dead string data, which
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6030 is marked by putting a special marker of 0xFFFFFFFF in the @code{struct
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6031 Lisp_String} pointer before the data (there's no real @code{struct
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6032 Lisp_String} to point to and relocate), and storing the size of the dead
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6033 string data (which would normally be obtained from the now-non-existent
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6034 @code{struct Lisp_String}) at the beginning of the dead string data gap.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6035 The string compactor recognizes this special 0xFFFFFFFF marker and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6036 handles it correctly.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6037
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6038 @node Compiled Function
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6039 @section Compiled Function
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6040 @cindex compiled function
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6041 @cindex function, compiled
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6042
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6043 Not yet documented.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6044
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6045
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6046 @node Dumping, Events and the Event Loop, Allocation of Objects in XEmacs Lisp, Top
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6047 @chapter Dumping
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6048 @cindex dumping
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6049
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6050 @section What is dumping and its justification
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6051 @cindex dumping and its justification, what is
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6052
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6053 The C code of XEmacs is just a Lisp engine with a lot of built-in
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6054 primitives useful for writing an editor. The editor itself is written
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6055 mostly in Lisp, and represents around 100K lines of code. Loading and
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6056 executing the initialization of all this code takes a bit a time (five
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6057 to ten times the usual startup time of current xemacs) and requires
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6058 having all the lisp source files around. Having to reload them each
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6059 time the editor is started would not be acceptable.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6060
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6061 The traditional solution to this problem is called dumping: the build
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6062 process first creates the lisp engine under the name @file{temacs}, then
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6063 runs it until it has finished loading and initializing all the lisp
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6064 code, and eventually creates a new executable called @file{xemacs}
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6065 including both the object code in @file{temacs} and all the contents of
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6066 the memory after the initialization.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6067
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6068 This solution, while working, has a huge problem: the creation of the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6069 new executable from the actual contents of memory is an extremely
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6070 system-specific process, quite error-prone, and which interferes with a
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6071 lot of system libraries (like malloc). It is even getting worse
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6072 nowadays with libraries using constructors which are automatically
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6073 called when the program is started (even before main()) which tend to
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6074 crash when they are called multiple times, once before dumping and once
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6075 after (IRIX 6.x libz.so pulls in some C++ image libraries thru
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6076 dependencies which have this problem). Writing the dumper is also one
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6077 of the most difficult parts of porting XEmacs to a new operating system.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6078 Basically, `dumping' is an operation that is just not officially
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6079 supported on many operating systems.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6080
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6081 The aim of the portable dumper is to solve the same problem as the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6082 system-specific dumper, that is to be able to reload quickly, using only
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6083 a small number of files, the fully initialized lisp part of the editor,
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6084 without any system-specific hacks.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6085
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6086 @menu
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6087 * Overview::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6088 * Data descriptions::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6089 * Dumping phase::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6090 * Reloading phase::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6091 * Remaining issues::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6092 @end menu
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6093
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6094 @node Overview
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6095 @section Overview
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6096 @cindex dumping overview
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6097
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6098 The portable dumping system has to:
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6099
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6100 @enumerate
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6101 @item
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6102 At dump time, write all initialized, non-quickly-rebuildable data to a
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6103 file [Note: currently named @file{xemacs.dmp}, but the name will
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6104 change], along with all informations needed for the reloading.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6105
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6106 @item
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6107 When starting xemacs, reload the dump file, relocate it to its new
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6108 starting address if needed, and reinitialize all pointers to this
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6109 data. Also, rebuild all the quickly rebuildable data.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6110 @end enumerate
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6111
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6112 @node Data descriptions
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6113 @section Data descriptions
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6114 @cindex dumping data descriptions
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6115
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6116 The more complex task of the dumper is to be able to write lisp objects
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6117 (lrecords) and C structs to disk and reload them at a different address,
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6118 updating all the pointers they include in the process. This is done by
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6119 using external data descriptions that give information about the layout
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6120 of the structures in memory.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6121
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6122 The specification of these descriptions is in lrecord.h. A description
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6123 of an lrecord is an array of struct lrecord_description. Each of these
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6124 structs include a type, an offset in the structure and some optional
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6125 parameters depending on the type. For instance, here is the string
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6126 description:
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6127
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6128 @example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6129 static const struct lrecord_description string_description[] = @{
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6130 @{ XD_BYTECOUNT, offsetof (Lisp_String, size) @},
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6131 @{ XD_OPAQUE_DATA_PTR, offsetof (Lisp_String, data), XD_INDIRECT(0, 1) @},
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6132 @{ XD_LISP_OBJECT, offsetof (Lisp_String, plist) @},
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6133 @{ XD_END @}
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6134 @};
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6135 @end example
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6136
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6137 The first line indicates a member of type Bytecount, which is used by
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6138 the next, indirect directive. The second means "there is a pointer to
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6139 some opaque data in the field @code{data}". The length of said data is
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6140 given by the expression @code{XD_INDIRECT(0, 1)}, which means "the value
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6141 in the 0th line of the description (welcome to C) plus one". The third
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6142 line means "there is a Lisp_Object member @code{plist} in the Lisp_String
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6143 structure". @code{XD_END} then ends the description.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6144
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6145 This gives us all the information we need to move around what is pointed
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6146 to by a structure (C or lrecord) and, by transitivity, everything that
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6147 it points to. The only missing information for dumping is the size of
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6148 the structure. For lrecords, this is part of the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6149 lrecord_implementation, so we don't need to duplicate it. For C
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6150 structures we use a struct struct_description, which includes a size
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6151 field and a pointer to an associated array of lrecord_description.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6152
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6153 @node Dumping phase
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6154 @section Dumping phase
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6155 @cindex dumping phase
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6156
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6157 Dumping is done by calling the function pdump() (in dumper.c) which is
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6158 invoked from Fdump_emacs (in emacs.c). This function performs a number
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6159 of tasks.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6160
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6161 @menu
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6162 * Object inventory::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6163 * Address allocation::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6164 * The header::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6165 * Data dumping::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6166 * Pointers dumping::
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6167 @end menu
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6168
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6169 @node Object inventory
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6170 @subsection Object inventory
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6171 @cindex dumping object inventory
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6172
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6173 The first task is to build the list of the objects to dump. This
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6174 includes:
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6175
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6176 @itemize @bullet
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6177 @item lisp objects
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6178 @item C structures
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6179 @end itemize
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6180
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6181 We end up with one @code{pdump_entry_list_elmt} per object group (arrays
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6182 of C structs are kept together) which includes a pointer to the first
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6183 object of the group, the per-object size and the count of objects in the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6184 group, along with some other information which is initialized later.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6185
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6186 These entries are linked together in @code{pdump_entry_list} structures
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6187 and can be enumerated thru either:
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6188
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6189 @enumerate
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6190 @item
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6191 the @code{pdump_object_table}, an array of @code{pdump_entry_list}, one
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6192 per lrecord type, indexed by type number.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6193
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6194 @item
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6195 the @code{pdump_opaque_data_list}, used for the opaque data which does
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6196 not include pointers, and hence does not need descriptions.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6197
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6198 @item
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6199 the @code{pdump_struct_table}, which is a vector of
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6200 @code{struct_description}/@code{pdump_entry_list} pairs, used for
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6201 non-opaque C structures.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6202 @end enumerate
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6203
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6204 This uses a marking strategy similar to the garbage collector. Some
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6205 differences though:
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6206
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6207 @enumerate
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6208 @item
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6209 We do not use the mark bit (which does not exist for C structures
448
3078fd1074e8 Import from CVS: tag r21-2-39
cvs
parents: 446
diff changeset
6210 anyway); we use a big hash table instead.
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6211
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6212 @item
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6213 We do not use the mark function of lrecords but instead rely on the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6214 external descriptions. This happens essentially because we need to
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6215 follow pointers to C structures and opaque data in addition to
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6216 Lisp_Object members.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6217 @end enumerate
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6218
452
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6219 This is done by @code{pdump_register_object()}, which handles Lisp_Object
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6220 variables, and @code{pdump_register_struct()} which handles C structures,
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6221 which both delegate the description management to @code{pdump_register_sub()}.
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6222
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6223 The hash table doubles as a map object to pdump_entry_list_elmt (i.e.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6224 allows us to look up a pdump_entry_list_elmt with the object it points
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6225 to). Entries are added with @code{pdump_add_entry()} and looked up with
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6226 @code{pdump_get_entry()}. There is no need for entry removal. The hash
448
3078fd1074e8 Import from CVS: tag r21-2-39
cvs
parents: 446
diff changeset
6227 value is computed quite simply from the object pointer by
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6228 @code{pdump_make_hash()}.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6229
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6230 The roots for the marking are:
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6231
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6232 @enumerate
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6233 @item
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6234 the @code{staticpro}'ed variables (there is a special @code{staticpro_nodump()}
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6235 call for protected variables we do not want to dump).
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6236
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6237 @item
452
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6238 the variables registered via @code{dump_add_root_object}
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6239 (@code{staticpro()} is equivalent to @code{staticpro_nodump()} +
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6240 @code{dump_add_root_object()}).
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6241
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6242 @item
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6243 the variables registered via @code{dump_add_root_struct_ptr}, each of
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6244 which points to a C structure.
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6245 @end enumerate
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6246
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6247 This does not include the GCPRO'ed variables, the specbinds, the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6248 catchtags, the backlist, the redisplay or the profiling info, since we
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6249 do not want to rebuild the actual chain of lisp calls which end up to
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6250 the dump-emacs call, only the global variables.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6251
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6252 Weak lists and weak hash tables are dumped as if they were their
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6253 non-weak equivalent (without changing their type, of course). This has
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6254 not yet been a problem.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6255
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6256 @node Address allocation
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6257 @subsection Address allocation
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6258 @cindex dumping address allocation
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6259
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6260
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6261 The next step is to allocate the offsets of each of the objects in the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6262 final dump file. This is done by @code{pdump_allocate_offset()} which
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6263 is called indirectly by @code{pdump_scan_by_alignment()}.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6264
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6265 The strategy to deal with alignment problems uses these facts:
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6266
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6267 @enumerate
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6268 @item
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6269 real world alignment requirements are powers of two.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6270
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6271 @item
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6272 the C compiler is required to adjust the size of a struct so that you
448
3078fd1074e8 Import from CVS: tag r21-2-39
cvs
parents: 446
diff changeset
6273 can have an array of them next to each other. This means you can have an
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6274 upper bound of the alignment requirements of a given structure by
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6275 looking at which power of two its size is a multiple.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6276
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6277 @item
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6278 the non-variant part of variable size lrecords has an alignment
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6279 requirement of 4.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6280 @end enumerate
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6281
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6282 Hence, for each lrecord type, C struct type or opaque data block the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6283 alignment requirement is computed as a power of two, with a minimum of
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6284 2^2 for lrecords. @code{pdump_scan_by_alignment()} then scans all the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6285 @code{pdump_entry_list_elmt}'s, the ones with the highest requirements
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6286 first. This ensures the best packing.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6287
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6288 The maximum alignment requirement we take into account is 2^8.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6289
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6290 @code{pdump_allocate_offset()} only has to do a linear allocation,
448
3078fd1074e8 Import from CVS: tag r21-2-39
cvs
parents: 446
diff changeset
6291 starting at offset 256 (this leaves room for the header and keeps the
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6292 alignments happy).
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6293
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6294 @node The header
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6295 @subsection The header
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6296 @cindex dumping, the header
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6297
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6298 The next step creates the file and writes a header with a signature and
452
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6299 some random information in it. The @code{reloc_address} field, which
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6300 indicates at which address the file should be loaded if we want to avoid
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6301 post-reload relocation, is set to 0. It then seeks to offset 256 (base
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6302 offset for the objects).
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6303
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6304 @node Data dumping
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6305 @subsection Data dumping
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6306 @cindex data dumping
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6307 @cindex dumping, data
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6308
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6309 The data is dumped in the same order as the addresses were allocated by
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6310 @code{pdump_dump_data()}, called from @code{pdump_scan_by_alignment()}.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6311 This function copies the data to a temporary buffer, relocates all
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6312 pointers in the object to the addresses allocated in step Address
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6313 Allocation, and writes it to the file. Using the same order means that,
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6314 if we are careful with lrecords whose size is not a multiple of 4, we
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6315 are ensured that the object is always written at the offset in the file
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6316 allocated in step Address Allocation.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6317
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6318 @node Pointers dumping
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6319 @subsection Pointers dumping
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6320 @cindex pointers dumping
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6321 @cindex dumping, pointers
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6322
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6323 A bunch of tables needed to reassign properly the global pointers are
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6324 then written. They are:
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6325
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6326 @enumerate
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6327 @item
452
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6328 the pdump_root_struct_ptrs dynarr
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6329 @item
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6330 the pdump_opaques dynarr
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6331 @item
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6332 a vector of all the offsets to the objects in the file that include a
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6333 description (for faster relocation at reload time)
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6334 @item
452
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6335 the pdump_root_objects and pdump_weak_object_chains dynarrs.
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6336 @end enumerate
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6337
452
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6338 For each of the dynarrs we write both the pointer to the variables and
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6339 the relocated offset of the object they point to. Since these variables
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6340 are global, the pointers are still valid when restarting the program and
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6341 are used to regenerate the global pointers.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6342
452
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6343 The @code{pdump_weak_object_chains} dynarr is a special case. The
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6344 variables it points to are the head of weak linked lists of lisp objects
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6345 of the same type. Not all objects of this list are dumped so the
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6346 relocated pointer we associate with them points to the first dumped
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6347 object of the list, or Qnil if none is available. This is also the
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6348 reason why they are not used as roots for the purpose of object
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6349 enumeration.
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6350
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6351 Some very important information like the @code{staticpros} and
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6352 @code{lrecord_implementations_table} are handled indirectly using
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6353 @code{dump_add_opaque} or @code{dump_add_root_struct_ptr}.
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6354
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6355 This is the end of the dumping part.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6356
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6357 @node Reloading phase
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6358 @section Reloading phase
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6359 @cindex reloading phase
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6360 @cindex dumping, reloading phase
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6361
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6362 @subsection File loading
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6363 @cindex dumping, file loading
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6364
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6365 The file is mmap'ed in memory (which ensures a PAGESIZE alignment, at
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6366 least 4096), or if mmap is unavailable or fails, a 256-bytes aligned
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6367 malloc is done and the file is loaded.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6368
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6369 Some variables are reinitialized from the values found in the header.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6370
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6371 The difference between the actual loading address and the reloc_address
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6372 is computed and will be used for all the relocations.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6373
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6374
452
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6375 @subsection Putting back the pdump_opaques
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6376 @cindex dumping, putting back the pdump_opaques
452
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6377
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6378 The memory contents are restored in the obvious and trivial way.
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6379
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6380
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6381 @subsection Putting back the pdump_root_struct_ptrs
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6382 @cindex dumping, putting back the pdump_root_struct_ptrs
452
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6383
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6384 The variables pointed to by pdump_root_struct_ptrs in the dump phase are
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6385 reset to the right relocated object addresses.
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6386
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6387
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6388 @subsection Object relocation
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6389 @cindex dumping, object relocation
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6390
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6391 All the objects are relocated using their description and their offset
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6392 by @code{pdump_reloc_one}. This step is unnecessary if the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6393 reloc_address is equal to the file loading address.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6394
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6395
452
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6396 @subsection Putting back the pdump_root_objects and pdump_weak_object_chains
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6397 @cindex dumping, putting back the pdump_root_objects and pdump_weak_object_chains
452
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6398
3d3049ae1304 Import from CVS: tag r21-2-41
cvs
parents: 448
diff changeset
6399 Same as Putting back the pdump_root_struct_ptrs.
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6400
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6401
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6402 @subsection Reorganize the hash tables
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6403 @cindex dumping, reorganize the hash tables
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6404
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6405 Since some of the hash values in the lisp hash tables are
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6406 address-dependent, their layout is now wrong. So we go through each of
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6407 them and have them resorted by calling @code{pdump_reorganize_hash_table}.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6408
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6409 @node Remaining issues
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6410 @section Remaining issues
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6411 @cindex dumping, remaining issues
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6412
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6413 The build process will have to start a post-dump xemacs, ask it the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6414 loading address (which will, hopefully, be always the same between
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6415 different xemacs invocations) and relocate the file to the new address.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6416 This way the object relocation phase will not have to be done, which
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6417 means no writes in the objects and that, because of the use of mmap, the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6418 dumped data will be shared between all the xemacs running on the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6419 computer.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6420
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6421 Some executable signature will be necessary to ensure that a given dump
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6422 file is really associated with a given executable, or random crashes
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6423 will occur. Maybe a random number set at compile or configure time thru
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6424 a define. This will also allow for having differently-compiled xemacsen
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6425 on the same system (mule and no-mule comes to mind).
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6426
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6427 The DOC file contents should probably end up in the dump file.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6428
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6429
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6430 @node Events and the Event Loop, Evaluation; Stack Frames; Bindings, Dumping, Top
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6431 @chapter Events and the Event Loop
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6432 @cindex events and the event loop
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6433 @cindex event loop, events and the
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6434
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6435 @menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6436 * Introduction to Events::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6437 * Main Loop::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6438 * Specifics of the Event Gathering Mechanism::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6439 * Specifics About the Emacs Event::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6440 * The Event Stream Callback Routines::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6441 * Other Event Loop Functions::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6442 * Converting Events::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6443 * Dispatching Events; The Command Builder::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6444 @end menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6445
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6446 @node Introduction to Events
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6447 @section Introduction to Events
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6448 @cindex events, introduction to
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6449
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6450 An event is an object that encapsulates information about an
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6451 interesting occurrence in the operating system. Events are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6452 generated either by user action, direct (e.g. typing on the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6453 keyboard or moving the mouse) or indirect (moving another
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6454 window, thereby generating an expose event on an Emacs frame),
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6455 or as a result of some other typically asynchronous action happening,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6456 such as output from a subprocess being ready or a timer expiring.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6457 Events come into the system in an asynchronous fashion (typically
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6458 through a callback being called) and are converted into a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6459 synchronous event queue (first-in, first-out) in a process that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6460 we will call @dfn{collection}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6461
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6462 Note that each application has its own event queue. (It is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6463 immaterial whether the collection process directly puts the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6464 events in the proper application's queue, or puts them into
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6465 a single system queue, which is later split up.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6466
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6467 The most basic level of event collection is done by the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6468 operating system or window system. Typically, XEmacs does
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6469 its own event collection as well. Often there are multiple
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6470 layers of collection in XEmacs, with events from various
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6471 sources being collected into a queue, which is then combined
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6472 with other sources to go into another queue (i.e. a second
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6473 level of collection), with perhaps another level on top of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6474 this, etc.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6475
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6476 XEmacs has its own types of events (called @dfn{Emacs events}),
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6477 which provides an abstract layer on top of the system-dependent
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6478 nature of the most basic events that are received. Part of the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6479 complex nature of the XEmacs event collection process involves
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6480 converting from the operating-system events into the proper
440
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 438
diff changeset
6481 Emacs events---there may not be a one-to-one correspondence.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6482
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6483 Emacs events are documented in @file{events.h}; I'll discuss them
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6484 later.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6485
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6486 @node Main Loop
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6487 @section Main Loop
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6488 @cindex main loop
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6489 @cindex events, main loop
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6490
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6491 The @dfn{command loop} is the top-level loop that the editor is always
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6492 running. It loops endlessly, calling @code{next-event} to retrieve an
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6493 event and @code{dispatch-event} to execute it. @code{dispatch-event} does
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6494 the appropriate thing with non-user events (process, timeout,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6495 magic, eval, mouse motion); this involves calling a Lisp handler
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6496 function, redrawing a newly-exposed part of a frame, reading
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6497 subprocess output, etc. For user events, @code{dispatch-event}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6498 looks up the event in relevant keymaps or menubars; when a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6499 full key sequence or menubar selection is reached, the appropriate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6500 function is executed. @code{dispatch-event} may have to keep state
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6501 across calls; this is done in the ``command-builder'' structure
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6502 associated with each console (remember, there's usually only
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6503 one console), and the engine that looks up keystrokes and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6504 constructs full key sequences is called the @dfn{command builder}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6505 This is documented elsewhere.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6506
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6507 The guts of the command loop are in @code{command_loop_1()}. This
440
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 438
diff changeset
6508 function doesn't catch errors, though---that's the job of
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6509 @code{command_loop_2()}, which is a condition-case (i.e. error-trapping)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6510 wrapper around @code{command_loop_1()}. @code{command_loop_1()} never
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6511 returns, but may get thrown out of.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6512
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6513 When an error occurs, @code{cmd_error()} is called, which usually
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6514 invokes the Lisp error handler in @code{command-error}; however, a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6515 default error handler is provided if @code{command-error} is @code{nil}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6516 (e.g. during startup). The purpose of the error handler is simply to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6517 display the error message and do associated cleanup; it does not need to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6518 throw anywhere. When the error handler finishes, the condition-case in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6519 @code{command_loop_2()} will finish and @code{command_loop_2()} will
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6520 reinvoke @code{command_loop_1()}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6521
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6522 @code{command_loop_2()} is invoked from three places: from
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6523 @code{initial_command_loop()} (called from @code{main()} at the end of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6524 internal initialization), from the Lisp function @code{recursive-edit},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6525 and from @code{call_command_loop()}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6526
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6527 @code{call_command_loop()} is called when a macro is started and when
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6528 the minibuffer is entered; normal termination of the macro or minibuffer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6529 causes a throw out of the recursive command loop. (To
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6530 @code{execute-kbd-macro} for macros and @code{exit} for minibuffers.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6531 Note also that the low-level minibuffer-entering function,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6532 @code{read-minibuffer-internal}, provides its own error handling and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6533 does not need @code{command_loop_2()}'s error encapsulation; so it tells
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6534 @code{call_command_loop()} to invoke @code{command_loop_1()} directly.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6535
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6536 Note that both read-minibuffer-internal and recursive-edit set up a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6537 catch for @code{exit}; this is why @code{abort-recursive-edit}, which
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6538 throws to this catch, exits out of either one.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6539
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6540 @code{initial_command_loop()}, called from @code{main()}, sets up a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6541 catch for @code{top-level} when invoking @code{command_loop_2()},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6542 allowing functions to throw all the way to the top level if they really
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6543 need to. Before invoking @code{command_loop_2()},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6544 @code{initial_command_loop()} calls @code{top_level_1()}, which handles
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6545 all of the startup stuff (creating the initial frame, handling the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6546 command-line options, loading the user's @file{.emacs} file, etc.). The
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6547 function that actually does this is in Lisp and is pointed to by the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6548 variable @code{top-level}; normally this function is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6549 @code{normal-top-level}. @code{top_level_1()} is just an error-handling
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6550 wrapper similar to @code{command_loop_2()}. Note also that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6551 @code{initial_command_loop()} sets up a catch for @code{top-level} when
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6552 invoking @code{top_level_1()}, just like when it invokes
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6553 @code{command_loop_2()}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6554
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6555 @node Specifics of the Event Gathering Mechanism
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6556 @section Specifics of the Event Gathering Mechanism
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6557 @cindex event gathering mechanism, specifics of the
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6558
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6559 Here is an approximate diagram of the collection processes
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6560 at work in XEmacs, under TTY's (TTY's are simpler than X
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6561 so we'll look at this first):
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6562
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6563 @noindent
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6564 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6565 asynch. asynch. asynch. asynch. [Collectors in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6566 kbd events kbd events process process the OS]
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6567 | | output output
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6568 | | | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6569 | | | | SIGINT, [signal handlers
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6570 | | | | SIGQUIT, in XEmacs]
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6571 V V V V SIGWINCH,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6572 file file file file SIGALRM
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6573 desc. desc. desc. desc. |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6574 (TTY) (TTY) (pipe) (pipe) |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6575 | | | | fake timeouts
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6576 | | | | file |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6577 | | | | desc. |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6578 | | | | (pipe) |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6579 | | | | | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6580 | | | | | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6581 | | | | | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6582 V V V V V V
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6583 ------>-----------<----------------<----------------
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6584 |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6585 |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6586 | [collected using select() in emacs_tty_next_event()
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6587 | and converted to the appropriate Emacs event]
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6588 |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6589 |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6590 V (above this line is TTY-specific)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6591 Emacs -----------------------------------------------
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6592 event (below this line is the generic event mechanism)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6593 |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6594 |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6595 was there if not, call
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6596 a SIGINT? emacs_tty_next_event()
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6597 | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6598 | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6599 | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6600 V V
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6601 --->------<----
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6602 |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6603 | [collected in event_stream_next_event();
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6604 | SIGINT is converted using maybe_read_quit_event()]
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6605 V
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6606 Emacs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6607 event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6608 |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6609 \---->------>----- maybe_kbd_translate() ---->---\
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6610 |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6611 |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6612 |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6613 command event queue |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6614 if not from command
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6615 (contains events that were event queue, call
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6616 read earlier but not processed, event_stream_next_event()
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6617 typically when waiting in a |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6618 sit-for, sleep-for, etc. for |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6619 a particular event to be received) |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6620 | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6621 | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6622 V V
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6623 ---->------------------------------------<----
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6624 |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6625 | [collected in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6626 | next_event_internal()]
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6627 |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6628 unread- unread- event from |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6629 command- command- keyboard else, call
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6630 events event macro next_event_internal()
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6631 | | | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6632 | | | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6633 | | | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6634 V V V V
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6635 --------->----------------------<------------
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6636 |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6637 | [collected in `next-event', which may loop
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6638 | more than once if the event it gets is on
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6639 | a dead frame, device, etc.]
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6640 |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6641 |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6642 V
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6643 feed into top-level event loop,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6644 which repeatedly calls `next-event'
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6645 and then dispatches the event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6646 using `dispatch-event'
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6647 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6648
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6649 Notice the separation between TTY-specific and generic event mechanism.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6650 When using the Xt-based event loop, the TTY-specific stuff is replaced
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6651 but the rest stays the same.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6652
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6653 It's also important to realize that only one different kind of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6654 system-specific event loop can be operating at a time, and must be able
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6655 to receive all kinds of events simultaneously. For the two existing
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6656 event loops (implemented in @file{event-tty.c} and @file{event-Xt.c},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6657 respectively), the TTY event loop @emph{only} handles TTY consoles,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6658 while the Xt event loop handles @emph{both} TTY and X consoles. This
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6659 situation is different from all of the output handlers, where you simply
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6660 have one per console type.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6661
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6662 Here's the Xt Event Loop Diagram (notice that below a certain point,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6663 it's the same as the above diagram):
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6664
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6665 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6666 asynch. asynch. asynch. asynch. [Collectors in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6667 kbd kbd process process the OS]
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6668 events events output output
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6669 | | | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6670 | | | | asynch. asynch. [Collectors in the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6671 | | | | X X OS and X Window System]
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6672 | | | | events events
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6673 | | | | | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6674 | | | | | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6675 | | | | | | SIGINT, [signal handlers
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6676 | | | | | | SIGQUIT, in XEmacs]
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6677 | | | | | | SIGWINCH,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6678 | | | | | | SIGALRM
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6679 | | | | | | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6680 | | | | | | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6681 | | | | | | | timeouts
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6682 | | | | | | | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6683 | | | | | | | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6684 | | | | | | V |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6685 V V V V V V fake |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6686 file file file file file file file |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6687 desc. desc. desc. desc. desc. desc. desc. |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6688 (TTY) (TTY) (pipe) (pipe) (socket) (socket) (pipe) |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6689 | | | | | | | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6690 | | | | | | | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6691 | | | | | | | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6692 V V V V V V V V
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6693 --->----------------------------------------<---------<------
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6694 | | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6695 | | |[collected using select() in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6696 | | | _XtWaitForSomething(), called
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6697 | | | from XtAppProcessEvent(), called
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6698 | | | in emacs_Xt_next_event();
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6699 | | | dispatched to various callbacks]
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6700 | | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6701 | | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6702 emacs_Xt_ p_s_callback(), | [popup_selection_callback]
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6703 event_handler() x_u_v_s_callback(),| [x_update_vertical_scrollbar_
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6704 | x_u_h_s_callback(),| callback]
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6705 | search_callback() | [x_update_horizontal_scrollbar_
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6706 | | | callback]
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6707 | | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6708 | | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6709 enqueue_Xt_ signal_special_ |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6710 dispatch_event() Xt_user_event() |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6711 [maybe multiple | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6712 times, maybe 0 | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6713 times] | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6714 | enqueue_Xt_ |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6715 | dispatch_event() |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6716 | | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6717 | | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6718 V V |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6719 -->----------<-- |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6720 | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6721 | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6722 dispatch Xt_what_callback()
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6723 event sets flags
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6724 queue |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6725 | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6726 | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6727 | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6728 | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6729 ---->-----------<--------
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6730 |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6731 |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6732 | [collected and converted as appropriate in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6733 | emacs_Xt_next_event()]
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6734 |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6735 |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6736 V (above this line is Xt-specific)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6737 Emacs ------------------------------------------------
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6738 event (below this line is the generic event mechanism)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6739 |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6740 |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6741 was there if not, call
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6742 a SIGINT? emacs_Xt_next_event()
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6743 | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6744 | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6745 | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6746 V V
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6747 --->-------<----
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6748 |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6749 | [collected in event_stream_next_event();
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6750 | SIGINT is converted using maybe_read_quit_event()]
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6751 V
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6752 Emacs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6753 event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6754 |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6755 \---->------>----- maybe_kbd_translate() -->-----\
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6756 |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6757 |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6758 |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6759 command event queue |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6760 if not from command
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6761 (contains events that were event queue, call
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6762 read earlier but not processed, event_stream_next_event()
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6763 typically when waiting in a |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6764 sit-for, sleep-for, etc. for |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6765 a particular event to be received) |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6766 | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6767 | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6768 V V
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6769 ---->----------------------------------<------
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6770 |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6771 | [collected in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6772 | next_event_internal()]
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6773 |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6774 unread- unread- event from |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6775 command- command- keyboard else, call
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6776 events event macro next_event_internal()
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6777 | | | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6778 | | | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6779 | | | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6780 V V V V
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6781 --------->----------------------<------------
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6782 |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6783 | [collected in `next-event', which may loop
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6784 | more than once if the event it gets is on
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6785 | a dead frame, device, etc.]
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6786 |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6787 |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6788 V
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6789 feed into top-level event loop,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6790 which repeatedly calls `next-event'
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6791 and then dispatches the event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6792 using `dispatch-event'
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6793 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6794
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6795 @node Specifics About the Emacs Event
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6796 @section Specifics About the Emacs Event
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6797 @cindex event, specifics about the Lisp object
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6798
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6799 @node The Event Stream Callback Routines
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6800 @section The Event Stream Callback Routines
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6801 @cindex event stream callback routines, the
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6802 @cindex callback routines, the event stream
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6803
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6804 @node Other Event Loop Functions
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6805 @section Other Event Loop Functions
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6806 @cindex event loop functions, other
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6807
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6808 @code{detect_input_pending()} and @code{input-pending-p} look for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6809 input by calling @code{event_stream->event_pending_p} and looking in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6810 @code{[V]unread-command-event} and the @code{command_event_queue} (they
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6811 do not check for an executing keyboard macro, though).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6812
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6813 @code{discard-input} cancels any command events pending (and any
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6814 keyboard macros currently executing), and puts the others onto the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6815 @code{command_event_queue}. There is a comment about a ``race
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6816 condition'', which is not a good sign.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6817
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6818 @code{next-command-event} and @code{read-char} are higher-level
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6819 interfaces to @code{next-event}. @code{next-command-event} gets the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6820 next @dfn{command} event (i.e. keypress, mouse event, menu selection,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6821 or scrollbar action), calling @code{dispatch-event} on any others.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6822 @code{read-char} calls @code{next-command-event} and uses
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6823 @code{event_to_character()} to return the character equivalent. With
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6824 the right kind of input method support, it is possible for (read-char)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6825 to return a Kanji character.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6826
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6827 @node Converting Events
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6828 @section Converting Events
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6829 @cindex converting events
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6830 @cindex events, converting
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6831
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6832 @code{character_to_event()}, @code{event_to_character()},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6833 @code{event-to-character}, and @code{character-to-event} convert between
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6834 characters and keypress events corresponding to the characters. If the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6835 event was not a keypress, @code{event_to_character()} returns -1 and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6836 @code{event-to-character} returns @code{nil}. These functions convert
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6837 between character representation and the split-up event representation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6838 (keysym plus mod keys).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6839
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6840 @node Dispatching Events; The Command Builder
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6841 @section Dispatching Events; The Command Builder
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6842 @cindex dispatching events; the command builder
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6843 @cindex events; the command builder, dispatching
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6844 @cindex command builder, dispatching events; the
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6845
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6846 Not yet documented.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6847
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6848 @node Evaluation; Stack Frames; Bindings, Symbols and Variables, Events and the Event Loop, Top
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6849 @chapter Evaluation; Stack Frames; Bindings
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6850 @cindex evaluation; stack frames; bindings
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6851 @cindex stack frames; bindings, evaluation;
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6852 @cindex bindings, evaluation; stack frames;
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6853
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6854 @menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6855 * Evaluation::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6856 * Dynamic Binding; The specbinding Stack; Unwind-Protects::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6857 * Simple Special Forms::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6858 * Catch and Throw::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6859 @end menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6860
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6861 @node Evaluation
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6862 @section Evaluation
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6863 @cindex evaluation
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6864
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6865 @code{Feval()} evaluates the form (a Lisp object) that is passed to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6866 it. Note that evaluation is only non-trivial for two types of objects:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6867 symbols and conses. A symbol is evaluated simply by calling
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6868 @code{symbol-value} on it and returning the value.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6869
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6870 Evaluating a cons means calling a function. First, @code{eval} checks
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6871 to see if garbage-collection is necessary, and calls
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6872 @code{garbage_collect_1()} if so. It then increases the evaluation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6873 depth by 1 (@code{lisp_eval_depth}, which is always less than
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6874 @code{max_lisp_eval_depth}) and adds an element to the linked list of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6875 @code{struct backtrace}'s (@code{backtrace_list}). Each such structure
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6876 contains a pointer to the function being called plus a list of the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6877 function's arguments. Originally these values are stored unevalled, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6878 as they are evaluated, the backtrace structure is updated. Garbage
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6879 collection pays attention to the objects pointed to in the backtrace
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6880 structures (garbage collection might happen while a function is being
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6881 called or while an argument is being evaluated, and there could easily
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6882 be no other references to the arguments in the argument list; once an
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6883 argument is evaluated, however, the unevalled version is not needed by
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6884 eval, and so the backtrace structure is changed).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6885
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6886 At this point, the function to be called is determined by looking at
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6887 the car of the cons (if this is a symbol, its function definition is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6888 retrieved and the process repeated). The function should then consist
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6889 of either a @code{Lisp_Subr} (built-in function written in C), a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6890 @code{Lisp_Compiled_Function} object, or a cons whose car is one of the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6891 symbols @code{autoload}, @code{macro} or @code{lambda}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6892
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6893 If the function is a @code{Lisp_Subr}, the lisp object points to a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6894 @code{struct Lisp_Subr} (created by @code{DEFUN()}), which contains a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6895 pointer to the C function, a minimum and maximum number of arguments
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6896 (or possibly the special constants @code{MANY} or @code{UNEVALLED}), a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6897 pointer to the symbol referring to that subr, and a couple of other
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6898 things. If the subr wants its arguments @code{UNEVALLED}, they are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6899 passed raw as a list. Otherwise, an array of evaluated arguments is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6900 created and put into the backtrace structure, and either passed whole
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6901 (@code{MANY}) or each argument is passed as a C argument.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6902
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6903 If the function is a @code{Lisp_Compiled_Function},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6904 @code{funcall_compiled_function()} is called. If the function is a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6905 lambda list, @code{funcall_lambda()} is called. If the function is a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6906 macro, [..... fill in] is done. If the function is an autoload,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6907 @code{do_autoload()} is called to load the definition and then eval
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6908 starts over [explain this more].
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6909
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6910 When @code{Feval()} exits, the evaluation depth is reduced by one, the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6911 debugger is called if appropriate, and the current backtrace structure
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6912 is removed from the list.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6913
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6914 Both @code{funcall_compiled_function()} and @code{funcall_lambda()} need
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6915 to go through the list of formal parameters to the function and bind
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6916 them to the actual arguments, checking for @code{&rest} and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6917 @code{&optional} symbols in the formal parameters and making sure the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6918 number of actual arguments is correct.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6919 @code{funcall_compiled_function()} can do this a little more
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6920 efficiently, since the formal parameter list can be checked for sanity
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6921 when the compiled function object is created.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6922
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6923 @code{funcall_lambda()} simply calls @code{Fprogn} to execute the code
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6924 in the lambda list.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6925
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6926 @code{funcall_compiled_function()} calls the real byte-code interpreter
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6927 @code{execute_optimized_program()} on the byte-code instructions, which
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6928 are converted into an internal form for faster execution.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6929
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6930 When a compiled function is executed for the first time by
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6931 @code{funcall_compiled_function()}, or during the dump phase of building
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6932 XEmacs, the byte-code instructions are converted from a
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6933 @code{Lisp_String} (which is inefficient to access, especially in the
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6934 presence of MULE) into a @code{Lisp_Opaque} object containing an array
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6935 of unsigned char, which can be directly executed by the byte-code
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6936 interpreter. At this time the byte code is also analyzed for validity
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6937 and transformed into a more optimized form, so that
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6938 @code{execute_optimized_program()} can really fly.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6939
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6940 Here are some of the optimizations performed by the internal byte-code
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6941 transformer:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6942 @enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6943 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6944 References to the @code{constants} array are checked for out-of-range
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6945 indices, so that the byte interpreter doesn't have to.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6946 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6947 References to the @code{constants} array that will be used as a Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6948 variable are checked for being correct non-constant (i.e. not @code{t},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6949 @code{nil}, or @code{keywordp}) symbols, so that the byte interpreter
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6950 doesn't have to.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6951 @item
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
6952 The maximum number of variable bindings in the byte-code is
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6953 pre-computed, so that space on the @code{specpdl} stack can be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6954 pre-reserved once for the whole function execution.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6955 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6956 All byte-code jumps are relative to the current program counter instead
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6957 of the start of the program, thereby saving a register.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6958 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6959 One-byte relative jumps are converted from the byte-code form of unsigned
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6960 chars offset by 127 to machine-friendly signed chars.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6961 @end enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6962
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6963 Of course, this transformation of the @code{instructions} should not be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6964 visible to the user, so @code{Fcompiled_function_instructions()} needs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6965 to know how to convert the optimized opaque object back into a Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6966 string that is identical to the original string from the @file{.elc}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6967 file. (Actually, the resulting string may (rarely) contain slightly
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6968 different, yet equivalent, byte code.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6969
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6970 @code{Ffuncall()} implements Lisp @code{funcall}. @code{(funcall fun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6971 x1 x2 x3 ...)} is equivalent to @code{(eval (list fun (quote x1) (quote
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6972 x2) (quote x3) ...))}. @code{Ffuncall()} contains its own code to do
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6973 the evaluation, however, and is very similar to @code{Feval()}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6974
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6975 From the performance point of view, it is worth knowing that most of the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6976 time in Lisp evaluation is spent executing @code{Lisp_Subr} and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6977 @code{Lisp_Compiled_Function} objects via @code{Ffuncall()} (not
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6978 @code{Feval()}).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6979
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6980 @code{Fapply()} implements Lisp @code{apply}, which is very similar to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6981 @code{funcall} except that if the last argument is a list, the result is the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6982 same as if each of the arguments in the list had been passed separately.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6983 @code{Fapply()} does some business to expand the last argument if it's a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6984 list, then calls @code{Ffuncall()} to do the work.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6985
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6986 @code{apply1()}, @code{call0()}, @code{call1()}, @code{call2()}, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6987 @code{call3()} call a function, passing it the argument(s) given (the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6988 arguments are given as separate C arguments rather than being passed as
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6989 an array). @code{apply1()} uses @code{Fapply()} while the others use
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6990 @code{Ffuncall()} to do the real work.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6991
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6992 @node Dynamic Binding; The specbinding Stack; Unwind-Protects
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6993 @section Dynamic Binding; The specbinding Stack; Unwind-Protects
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6994 @cindex dynamic binding; the specbinding stack; unwind-protects
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6995 @cindex binding; the specbinding stack; unwind-protects, dynamic
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6996 @cindex specbinding stack; unwind-protects, dynamic binding; the
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
6997 @cindex unwind-protects, dynamic binding; the specbinding stack;
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6998
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6999 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7000 struct specbinding
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7001 @{
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7002 Lisp_Object symbol;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7003 Lisp_Object old_value;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7004 Lisp_Object (*func) (Lisp_Object); /* for unwind-protect */
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7005 @};
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7006 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7007
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7008 @code{struct specbinding} is used for local-variable bindings and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7009 unwind-protects. @code{specpdl} holds an array of @code{struct specbinding}'s,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7010 @code{specpdl_ptr} points to the beginning of the free bindings in the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7011 array, @code{specpdl_size} specifies the total number of binding slots
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7012 in the array, and @code{max_specpdl_size} specifies the maximum number
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7013 of bindings the array can be expanded to hold. @code{grow_specpdl()}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7014 increases the size of the @code{specpdl} array, multiplying its size by
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7015 2 but never exceeding @code{max_specpdl_size} (except that if this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7016 number is less than 400, it is first set to 400).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7017
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7018 @code{specbind()} binds a symbol to a value and is used for local
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7019 variables and @code{let} forms. The symbol and its old value (which
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7020 might be @code{Qunbound}, indicating no prior value) are recorded in the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7021 specpdl array, and @code{specpdl_size} is increased by 1.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7022
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7023 @code{record_unwind_protect()} implements an @dfn{unwind-protect},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7024 which, when placed around a section of code, ensures that some specified
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7025 cleanup routine will be executed even if the code exits abnormally
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7026 (e.g. through a @code{throw} or quit). @code{record_unwind_protect()}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7027 simply adds a new specbinding to the @code{specpdl} array and stores the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7028 appropriate information in it. The cleanup routine can either be a C
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7029 function, which is stored in the @code{func} field, or a @code{progn}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7030 form, which is stored in the @code{old_value} field.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7031
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7032 @code{unbind_to()} removes specbindings from the @code{specpdl} array
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7033 until the specified position is reached. Each specbinding can be one of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7034 three types:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7035
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7036 @enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7037 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7038 an unwind-protect with a C cleanup function (@code{func} is not 0, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7039 @code{old_value} holds an argument to be passed to the function);
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7040 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7041 an unwind-protect with a Lisp form (@code{func} is 0, @code{symbol}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7042 is @code{nil}, and @code{old_value} holds the form to be executed with
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7043 @code{Fprogn()}); or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7044 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7045 a local-variable binding (@code{func} is 0, @code{symbol} is not
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7046 @code{nil}, and @code{old_value} holds the old value, which is stored as
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7047 the symbol's value).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7048 @end enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7049
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7050 @node Simple Special Forms
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7051 @section Simple Special Forms
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7052 @cindex special forms, simple
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7053
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7054 @code{or}, @code{and}, @code{if}, @code{cond}, @code{progn},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7055 @code{prog1}, @code{prog2}, @code{setq}, @code{quote}, @code{function},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7056 @code{let*}, @code{let}, @code{while}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7057
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7058 All of these are very simple and work as expected, calling
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7059 @code{Feval()} or @code{Fprogn()} as necessary and (in the case of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7060 @code{let} and @code{let*}) using @code{specbind()} to create bindings
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7061 and @code{unbind_to()} to undo the bindings when finished.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7062
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
7063 Note that, with the exception of @code{Fprogn}, these functions are
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7064 typically called in real life only in interpreted code, since the byte
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7065 compiler knows how to convert calls to these functions directly into
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7066 byte code.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7067
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7068 @node Catch and Throw
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7069 @section Catch and Throw
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7070 @cindex catch and throw
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7071 @cindex throw, catch and
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7072
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7073 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7074 struct catchtag
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7075 @{
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7076 Lisp_Object tag;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7077 Lisp_Object val;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7078 struct catchtag *next;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7079 struct gcpro *gcpro;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7080 jmp_buf jmp;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7081 struct backtrace *backlist;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7082 int lisp_eval_depth;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7083 int pdlcount;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7084 @};
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7085 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7086
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7087 @code{catch} is a Lisp function that places a catch around a body of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7088 code. A catch is a means of non-local exit from the code. When a catch
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7089 is created, a tag is specified, and executing a @code{throw} to this tag
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7090 will exit from the body of code caught with this tag, and its value will
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7091 be the value given in the call to @code{throw}. If there is no such
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7092 call, the code will be executed normally.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7093
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7094 Information pertaining to a catch is held in a @code{struct catchtag},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7095 which is placed at the head of a linked list pointed to by
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7096 @code{catchlist}. @code{internal_catch()} is passed a C function to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7097 call (@code{Fprogn()} when Lisp @code{catch} is called) and arguments to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7098 give it, and places a catch around the function. Each @code{struct
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7099 catchtag} is held in the stack frame of the @code{internal_catch()}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7100 instance that created the catch.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7101
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7102 @code{internal_catch()} is fairly straightforward. It stores into the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7103 @code{struct catchtag} the tag name and the current values of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7104 @code{backtrace_list}, @code{lisp_eval_depth}, @code{gcprolist}, and the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7105 offset into the @code{specpdl} array, sets a jump point with @code{_setjmp()}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7106 (storing the jump point into the @code{struct catchtag}), and calls the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7107 function. Control will return to @code{internal_catch()} either when
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7108 the function exits normally or through a @code{_longjmp()} to this jump
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7109 point. In the latter case, @code{throw} will store the value to be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7110 returned into the @code{struct catchtag} before jumping. When it's
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7111 done, @code{internal_catch()} removes the @code{struct catchtag} from
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7112 the catchlist and returns the proper value.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7113
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7114 @code{Fthrow()} goes up through the catchlist until it finds one with
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7115 a matching tag. It then calls @code{unbind_catch()} to restore
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7116 everything to what it was when the appropriate catch was set, stores the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7117 return value in the @code{struct catchtag}, and jumps (with
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7118 @code{_longjmp()}) to its jump point.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7119
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7120 @code{unbind_catch()} removes all catches from the catchlist until it
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7121 finds the correct one. Some of the catches might have been placed for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7122 error-trapping, and if so, the appropriate entries on the handlerlist
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7123 must be removed (see ``errors''). @code{unbind_catch()} also restores
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7124 the values of @code{gcprolist}, @code{backtrace_list}, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7125 @code{lisp_eval}, and calls @code{unbind_to()} to undo any specbindings
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7126 created since the catch.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7127
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7128
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7129 @node Symbols and Variables, Buffers and Textual Representation, Evaluation; Stack Frames; Bindings, Top
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7130 @chapter Symbols and Variables
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7131 @cindex symbols and variables
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7132 @cindex variables, symbols and
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7133
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7134 @menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7135 * Introduction to Symbols::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7136 * Obarrays::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7137 * Symbol Values::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7138 @end menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7139
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7140 @node Introduction to Symbols
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7141 @section Introduction to Symbols
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7142 @cindex symbols, introduction to
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7143
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7144 A symbol is basically just an object with four fields: a name (a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7145 string), a value (some Lisp object), a function (some Lisp object), and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7146 a property list (usually a list of alternating keyword/value pairs).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7147 What makes symbols special is that there is usually only one symbol with
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7148 a given name, and the symbol is referred to by name. This makes a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7149 symbol a convenient way of calling up data by name, i.e. of implementing
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7150 variables. (The variable's value is stored in the @dfn{value slot}.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7151 Similarly, functions are referenced by name, and the definition of the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7152 function is stored in a symbol's @dfn{function slot}. This means that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7153 there can be a distinct function and variable with the same name. The
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7154 property list is used as a more general mechanism of associating
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7155 additional values with particular names, and once again the namespace is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7156 independent of the function and variable namespaces.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7157
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7158 @node Obarrays
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7159 @section Obarrays
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7160 @cindex obarrays
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7161
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7162 The identity of symbols with their names is accomplished through a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7163 structure called an obarray, which is just a poorly-implemented hash
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7164 table mapping from strings to symbols whose name is that string. (I say
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7165 ``poorly implemented'' because an obarray appears in Lisp as a vector
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7166 with some hidden fields rather than as its own opaque type. This is an
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7167 Emacs Lisp artifact that should be fixed.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7168
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7169 Obarrays are implemented as a vector of some fixed size (which should
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7170 be a prime for best results), where each ``bucket'' of the vector
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7171 contains one or more symbols, threaded through a hidden @code{next}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7172 field in the symbol. Lookup of a symbol in an obarray, and adding a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7173 symbol to an obarray, is accomplished through standard hash-table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7174 techniques.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7175
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7176 The standard Lisp function for working with symbols and obarrays is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7177 @code{intern}. This looks up a symbol in an obarray given its name; if
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7178 it's not found, a new symbol is automatically created with the specified
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7179 name, added to the obarray, and returned. This is what happens when the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7180 Lisp reader encounters a symbol (or more precisely, encounters the name
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7181 of a symbol) in some text that it is reading. There is a standard
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7182 obarray called @code{obarray} that is used for this purpose, although
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7183 the Lisp programmer is free to create his own obarrays and @code{intern}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7184 symbols in them.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7185
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7186 Note that, once a symbol is in an obarray, it stays there until
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7187 something is done about it, and the standard obarray @code{obarray}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7188 always stays around, so once you use any particular variable name, a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7189 corresponding symbol will stay around in @code{obarray} until you exit
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7190 XEmacs.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7191
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7192 Note that @code{obarray} itself is a variable, and as such there is a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7193 symbol in @code{obarray} whose name is @code{"obarray"} and which
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7194 contains @code{obarray} as its value.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7195
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7196 Note also that this call to @code{intern} occurs only when in the Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7197 reader, not when the code is executed (at which point the symbol is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7198 already around, stored as such in the definition of the function).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7199
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7200 You can create your own obarray using @code{make-vector} (this is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7201 horrible but is an artifact) and intern symbols into that obarray.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7202 Doing that will result in two or more symbols with the same name.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7203 However, at most one of these symbols is in the standard @code{obarray}:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7204 You cannot have two symbols of the same name in any particular obarray.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7205 Note that you cannot add a symbol to an obarray in any fashion other
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7206 than using @code{intern}: i.e. you can't take an existing symbol and put
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7207 it in an existing obarray. Nor can you change the name of an existing
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7208 symbol. (Since obarrays are vectors, you can violate the consistency of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7209 things by storing directly into the vector, but let's ignore that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7210 possibility.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7211
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7212 Usually symbols are created by @code{intern}, but if you really want,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7213 you can explicitly create a symbol using @code{make-symbol}, giving it
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7214 some name. The resulting symbol is not in any obarray (i.e. it is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7215 @dfn{uninterned}), and you can't add it to any obarray. Therefore its
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7216 primary purpose is as a symbol to use in macros to avoid namespace
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7217 pollution. It can also be used as a carrier of information, but cons
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7218 cells could probably be used just as well.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7219
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7220 You can also use @code{intern-soft} to look up a symbol but not create
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7221 a new one, and @code{unintern} to remove a symbol from an obarray. This
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7222 returns the removed symbol. (Remember: You can't put the symbol back
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7223 into any obarray.) Finally, @code{mapatoms} maps over all of the symbols
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7224 in an obarray.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7225
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7226 @node Symbol Values
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7227 @section Symbol Values
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7228 @cindex symbol values
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7229 @cindex values, symbol
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7230
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7231 The value field of a symbol normally contains a Lisp object. However,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7232 a symbol can be @dfn{unbound}, meaning that it logically has no value.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7233 This is internally indicated by storing a special Lisp object, called
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7234 @dfn{the unbound marker} and stored in the global variable
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7235 @code{Qunbound}. The unbound marker is of a special Lisp object type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7236 called @dfn{symbol-value-magic}. It is impossible for the Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7237 programmer to directly create or access any object of this type.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7238
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7239 @strong{You must not let any ``symbol-value-magic'' object escape to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7240 the Lisp level.} Printing any of these objects will cause the message
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7241 @samp{INTERNAL EMACS BUG} to appear as part of the print representation.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7242 (You may see this normally when you call @code{debug_print()} from the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7243 debugger on a Lisp object.) If you let one of these objects escape to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7244 the Lisp level, you will violate a number of assumptions contained in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7245 the C code and make the unbound marker not function right.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7246
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7247 When a symbol is created, its value field (and function field) are set
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7248 to @code{Qunbound}. The Lisp programmer can restore these conditions
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7249 later using @code{makunbound} or @code{fmakunbound}, and can query to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7250 see whether the value of function fields are @dfn{bound} (i.e. have a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7251 value other than @code{Qunbound}) using @code{boundp} and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7252 @code{fboundp}. The fields are set to a normal Lisp object using
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7253 @code{set} (or @code{setq}) and @code{fset}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7254
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7255 Other symbol-value-magic objects are used as special markers to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7256 indicate variables that have non-normal properties. This includes any
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7257 variables that are tied into C variables (setting the variable magically
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7258 sets some global variable in the C code, and likewise for retrieving the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7259 variable's value), variables that magically tie into slots in the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7260 current buffer, variables that are buffer-local, etc. The
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7261 symbol-value-magic object is stored in the value cell in place of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7262 a normal object, and the code to retrieve a symbol's value
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7263 (i.e. @code{symbol-value}) knows how to do special things with them.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7264 This means that you should not just fetch the value cell directly if you
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7265 want a symbol's value.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7266
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7267 The exact workings of this are rather complex and involved and are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7268 well-documented in comments in @file{buffer.c}, @file{symbols.c}, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7269 @file{lisp.h}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7270
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7271 @node Buffers and Textual Representation, MULE Character Sets and Encodings, Symbols and Variables, Top
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7272 @chapter Buffers and Textual Representation
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7273 @cindex buffers and textual representation
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7274 @cindex textual representation, buffers and
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7275
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7276 @menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7277 * Introduction to Buffers:: A buffer holds a block of text such as a file.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7278 * The Text in a Buffer:: Representation of the text in a buffer.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7279 * Buffer Lists:: Keeping track of all buffers.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7280 * Markers and Extents:: Tagging locations within a buffer.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7281 * Bufbytes and Emchars:: Representation of individual characters.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7282 * The Buffer Object:: The Lisp object corresponding to a buffer.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7283 @end menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7284
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7285 @node Introduction to Buffers
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7286 @section Introduction to Buffers
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7287 @cindex buffers, introduction to
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7288
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7289 A buffer is logically just a Lisp object that holds some text.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7290 In this, it is like a string, but a buffer is optimized for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7291 frequent insertion and deletion, while a string is not. Furthermore:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7292
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7293 @enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7294 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7295 Buffers are @dfn{permanent} objects, i.e. once you create them, they
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7296 remain around, and need to be explicitly deleted before they go away.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7297 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7298 Each buffer has a unique name, which is a string. Buffers are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7299 normally referred to by name. In this respect, they are like
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7300 symbols.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7301 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7302 Buffers have a default insertion position, called @dfn{point}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7303 Inserting text (unless you explicitly give a position) goes at point,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7304 and moves point forward past the text. This is what is going on when
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7305 you type text into Emacs.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7306 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7307 Buffers have lots of extra properties associated with them.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7308 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7309 Buffers can be @dfn{displayed}. What this means is that there
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7310 exist a number of @dfn{windows}, which are objects that correspond
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7311 to some visible section of your display, and each window has
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7312 an associated buffer, and the current contents of the buffer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7313 are shown in that section of the display. The redisplay mechanism
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7314 (which takes care of doing this) knows how to look at the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7315 text of a buffer and come up with some reasonable way of displaying
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7316 this. Many of the properties of a buffer control how the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7317 buffer's text is displayed.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7318 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7319 One buffer is distinguished and called the @dfn{current buffer}. It is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7320 stored in the variable @code{current_buffer}. Buffer operations operate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7321 on this buffer by default. When you are typing text into a buffer, the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7322 buffer you are typing into is always @code{current_buffer}. Switching
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7323 to a different window changes the current buffer. Note that Lisp code
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7324 can temporarily change the current buffer using @code{set-buffer} (often
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7325 enclosed in a @code{save-excursion} so that the former current buffer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7326 gets restored when the code is finished). However, calling
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7327 @code{set-buffer} will NOT cause a permanent change in the current
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7328 buffer. The reason for this is that the top-level event loop sets
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7329 @code{current_buffer} to the buffer of the selected window, each time
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7330 it finishes executing a user command.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7331 @end enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7332
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7333 Make sure you understand the distinction between @dfn{current buffer}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7334 and @dfn{buffer of the selected window}, and the distinction between
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7335 @dfn{point} of the current buffer and @dfn{window-point} of the selected
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7336 window. (This latter distinction is explained in detail in the section
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7337 on windows.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7338
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7339 @node The Text in a Buffer
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7340 @section The Text in a Buffer
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7341 @cindex text in a buffer, the
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7342 @cindex buffer, the text in a
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7343
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7344 The text in a buffer consists of a sequence of zero or more
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7345 characters. A @dfn{character} is an integer that logically represents
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7346 a letter, number, space, or other unit of text. Most of the characters
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7347 that you will typically encounter belong to the ASCII set of characters,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7348 but there are also characters for various sorts of accented letters,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7349 special symbols, Chinese and Japanese ideograms (i.e. Kanji, Katakana,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7350 etc.), Cyrillic and Greek letters, etc. The actual number of possible
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7351 characters is quite large.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7352
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7353 For now, we can view a character as some non-negative integer that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7354 has some shape that defines how it typically appears (e.g. as an
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7355 uppercase A). (The exact way in which a character appears depends on the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7356 font used to display the character.) The internal type of characters in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7357 the C code is an @code{Emchar}; this is just an @code{int}, but using a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7358 symbolic type makes the code clearer.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7359
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7360 Between every character in a buffer is a @dfn{buffer position} or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7361 @dfn{character position}. We can speak of the character before or after
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7362 a particular buffer position, and when you insert a character at a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7363 particular position, all characters after that position end up at new
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7364 positions. When we speak of the character @dfn{at} a position, we
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7365 really mean the character after the position. (This schizophrenia
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7366 between a buffer position being ``between'' a character and ``on'' a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7367 character is rampant in Emacs.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7368
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7369 Buffer positions are numbered starting at 1. This means that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7370 position 1 is before the first character, and position 0 is not
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7371 valid. If there are N characters in a buffer, then buffer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7372 position N+1 is after the last one, and position N+2 is not valid.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7373
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7374 The internal makeup of the Emchar integer varies depending on whether
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7375 we have compiled with MULE support. If not, the Emchar integer is an
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7376 8-bit integer with possible values from 0 - 255. 0 - 127 are the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7377 standard ASCII characters, while 128 - 255 are the characters from the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7378 ISO-8859-1 character set. If we have compiled with MULE support, an
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7379 Emchar is a 19-bit integer, with the various bits having meanings
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7380 according to a complex scheme that will be detailed later. The
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7381 characters numbered 0 - 255 still have the same meanings as for the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7382 non-MULE case, though.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7383
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7384 Internally, the text in a buffer is represented in a fairly simple
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7385 fashion: as a contiguous array of bytes, with a @dfn{gap} of some size
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7386 in the middle. Although the gap is of some substantial size in bytes,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7387 there is no text contained within it: From the perspective of the text
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7388 in the buffer, it does not exist. The gap logically sits at some buffer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7389 position, between two characters (or possibly at the beginning or end of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7390 the buffer). Insertion of text in a buffer at a particular position is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7391 always accomplished by first moving the gap to that position
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7392 (i.e. through some block moving of text), then writing the text into the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7393 beginning of the gap, thereby shrinking the gap. If the gap shrinks
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7394 down to nothing, a new gap is created. (What actually happens is that a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7395 new gap is ``created'' at the end of the buffer's text, which requires
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7396 nothing more than changing a couple of indices; then the gap is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7397 ``moved'' to the position where the insertion needs to take place by
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7398 moving up in memory all the text after that position.) Similarly,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7399 deletion occurs by moving the gap to the place where the text is to be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7400 deleted, and then simply expanding the gap to include the deleted text.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7401 (@dfn{Expanding} and @dfn{shrinking} the gap as just described means
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7402 just that the internal indices that keep track of where the gap is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7403 located are changed.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7404
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7405 Note that the total amount of memory allocated for a buffer text never
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7406 decreases while the buffer is live. Therefore, if you load up a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7407 20-megabyte file and then delete all but one character, there will be a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7408 20-megabyte gap, which won't get any smaller (except by inserting
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7409 characters back again). Once the buffer is killed, the memory allocated
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7410 for the buffer text will be freed, but it will still be sitting on the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7411 heap, taking up virtual memory, and will not be released back to the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7412 operating system. (However, if you have compiled XEmacs with rel-alloc,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7413 the situation is different. In this case, the space @emph{will} be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7414 released back to the operating system. However, this tends to result in a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7415 noticeable speed penalty.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7416
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7417 Astute readers may notice that the text in a buffer is represented as
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7418 an array of @emph{bytes}, while (at least in the MULE case) an Emchar is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7419 a 19-bit integer, which clearly cannot fit in a byte. This means (of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7420 course) that the text in a buffer uses a different representation from
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7421 an Emchar: specifically, the 19-bit Emchar becomes a series of one to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7422 four bytes. The conversion between these two representations is complex
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7423 and will be described later.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7424
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7425 In the non-MULE case, everything is very simple: An Emchar
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7426 is an 8-bit value, which fits neatly into one byte.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7427
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7428 If we are given a buffer position and want to retrieve the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7429 character at that position, we need to follow these steps:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7430
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7431 @enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7432 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7433 Pretend there's no gap, and convert the buffer position into a @dfn{byte
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7434 index} that indexes to the appropriate byte in the buffer's stream of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7435 textual bytes. By convention, byte indices begin at 1, just like buffer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7436 positions. In the non-MULE case, byte indices and buffer positions are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7437 identical, since one character equals one byte.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7438 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7439 Convert the byte index into a @dfn{memory index}, which takes the gap
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7440 into account. The memory index is a direct index into the block of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7441 memory that stores the text of a buffer. This basically just involves
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7442 checking to see if the byte index is past the gap, and if so, adding the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7443 size of the gap to it. By convention, memory indices begin at 1, just
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7444 like buffer positions and byte indices, and when referring to the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7445 position that is @dfn{at} the gap, we always use the memory position at
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7446 the @emph{beginning}, not at the end, of the gap.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7447 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7448 Fetch the appropriate bytes at the determined memory position.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7449 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7450 Convert these bytes into an Emchar.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7451 @end enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7452
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7453 In the non-Mule case, (3) and (4) boil down to a simple one-byte
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7454 memory access.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7455
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7456 Note that we have defined three types of positions in a buffer:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7457
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7458 @enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7459 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7460 @dfn{buffer positions} or @dfn{character positions}, typedef @code{Bufpos}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7461 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7462 @dfn{byte indices}, typedef @code{Bytind}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7463 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7464 @dfn{memory indices}, typedef @code{Memind}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7465 @end enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7466
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7467 All three typedefs are just @code{int}s, but defining them this way makes
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7468 things a lot clearer.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7469
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7470 Most code works with buffer positions. In particular, all Lisp code
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7471 that refers to text in a buffer uses buffer positions. Lisp code does
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7472 not know that byte indices or memory indices exist.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7473
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7474 Finally, we have a typedef for the bytes in a buffer. This is a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7475 @code{Bufbyte}, which is an unsigned char. Referring to them as
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7476 Bufbytes underscores the fact that we are working with a string of bytes
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7477 in the internal Emacs buffer representation rather than in one of a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7478 number of possible alternative representations (e.g. EUC-encoded text,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7479 etc.).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7480
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7481 @node Buffer Lists
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7482 @section Buffer Lists
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7483 @cindex buffer lists
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7484
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7485 Recall earlier that buffers are @dfn{permanent} objects, i.e. that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7486 they remain around until explicitly deleted. This entails that there is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7487 a list of all the buffers in existence. This list is actually an
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7488 assoc-list (mapping from the buffer's name to the buffer) and is stored
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7489 in the global variable @code{Vbuffer_alist}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7490
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7491 The order of the buffers in the list is important: the buffers are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7492 ordered approximately from most-recently-used to least-recently-used.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7493 Switching to a buffer using @code{switch-to-buffer},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7494 @code{pop-to-buffer}, etc. and switching windows using
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7495 @code{other-window}, etc. usually brings the new current buffer to the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7496 front of the list. @code{switch-to-buffer}, @code{other-buffer},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7497 etc. look at the beginning of the list to find an alternative buffer to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7498 suggest. You can also explicitly move a buffer to the end of the list
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7499 using @code{bury-buffer}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7500
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7501 In addition to the global ordering in @code{Vbuffer_alist}, each frame
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7502 has its own ordering of the list. These lists always contain the same
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7503 elements as in @code{Vbuffer_alist} although possibly in a different
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7504 order. @code{buffer-list} normally returns the list for the selected
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7505 frame. This allows you to work in separate frames without things
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7506 interfering with each other.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7507
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7508 The standard way to look up a buffer given a name is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7509 @code{get-buffer}, and the standard way to create a new buffer is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7510 @code{get-buffer-create}, which looks up a buffer with a given name,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7511 creating a new one if necessary. These operations correspond exactly
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7512 with the symbol operations @code{intern-soft} and @code{intern},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7513 respectively. You can also force a new buffer to be created using
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7514 @code{generate-new-buffer}, which takes a name and (if necessary) makes
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7515 a unique name from this by appending a number, and then creates the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7516 buffer. This is basically like the symbol operation @code{gensym}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7517
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7518 @node Markers and Extents
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7519 @section Markers and Extents
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7520 @cindex markers and extents
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7521 @cindex extents, markers and
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7522
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7523 Among the things associated with a buffer are things that are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7524 logically attached to certain buffer positions. This can be used to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7525 keep track of a buffer position when text is inserted and deleted, so
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7526 that it remains at the same spot relative to the text around it; to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7527 assign properties to particular sections of text; etc. There are two
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7528 such objects that are useful in this regard: they are @dfn{markers} and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7529 @dfn{extents}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7530
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7531 A @dfn{marker} is simply a flag placed at a particular buffer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7532 position, which is moved around as text is inserted and deleted.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7533 Markers are used for all sorts of purposes, such as the @code{mark} that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7534 is the other end of textual regions to be cut, copied, etc.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7535
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7536 An @dfn{extent} is similar to two markers plus some associated
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7537 properties, and is used to keep track of regions in a buffer as text is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7538 inserted and deleted, and to add properties (e.g. fonts) to particular
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7539 regions of text. The external interface of extents is explained
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7540 elsewhere.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7541
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7542 The important thing here is that markers and extents simply contain
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7543 buffer positions in them as integers, and every time text is inserted or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7544 deleted, these positions must be updated. In order to minimize the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7545 amount of shuffling that needs to be done, the positions in markers and
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
7546 extents (there's one per marker, two per extent) are stored in Meminds.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7547 This means that they only need to be moved when the text is physically
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7548 moved in memory; since the gap structure tries to minimize this, it also
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7549 minimizes the number of marker and extent indices that need to be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7550 adjusted. Look in @file{insdel.c} for the details of how this works.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7551
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7552 One other important distinction is that markers are @dfn{temporary}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7553 while extents are @dfn{permanent}. This means that markers disappear as
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7554 soon as there are no more pointers to them, and correspondingly, there
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7555 is no way to determine what markers are in a buffer if you are just
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7556 given the buffer. Extents remain in a buffer until they are detached
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7557 (which could happen as a result of text being deleted) or the buffer is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7558 deleted, and primitives do exist to enumerate the extents in a buffer.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7559
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7560 @node Bufbytes and Emchars
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7561 @section Bufbytes and Emchars
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7562 @cindex Bufbytes and Emchars
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7563 @cindex Emchars, Bufbytes and
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7564
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7565 Not yet documented.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7566
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7567 @node The Buffer Object
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7568 @section The Buffer Object
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7569 @cindex buffer object, the
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7570 @cindex object, the buffer
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7571
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7572 Buffers contain fields not directly accessible by the Lisp programmer.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7573 We describe them here, naming them by the names used in the C code.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7574 Many are accessible indirectly in Lisp programs via Lisp primitives.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7575
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7576 @table @code
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7577 @item name
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7578 The buffer name is a string that names the buffer. It is guaranteed to
446
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
7579 be unique. @xref{Buffer Names,,, lispref, XEmacs Lisp Reference
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7580 Manual}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7581
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7582 @item save_modified
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7583 This field contains the time when the buffer was last saved, as an
446
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
7584 integer. @xref{Buffer Modification,,, lispref, XEmacs Lisp Reference
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7585 Manual}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7586
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7587 @item modtime
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7588 This field contains the modification time of the visited file. It is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7589 set when the file is written or read. Every time the buffer is written
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7590 to the file, this field is compared to the modification time of the
446
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
7591 file. @xref{Buffer Modification,,, lispref, XEmacs Lisp Reference
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7592 Manual}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7593
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7594 @item auto_save_modified
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7595 This field contains the time when the buffer was last auto-saved.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7596
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7597 @item last_window_start
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7598 This field contains the @code{window-start} position in the buffer as of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7599 the last time the buffer was displayed in a window.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7600
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7601 @item undo_list
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7602 This field points to the buffer's undo list. @xref{Undo,,, lispref,
446
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
7603 XEmacs Lisp Reference Manual}.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7604
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7605 @item syntax_table_v
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7606 This field contains the syntax table for the buffer. @xref{Syntax
446
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
7607 Tables,,, lispref, XEmacs Lisp Reference Manual}.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7608
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7609 @item downcase_table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7610 This field contains the conversion table for converting text to lower
446
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
7611 case. @xref{Case Tables,,, lispref, XEmacs Lisp Reference Manual}.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7612
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7613 @item upcase_table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7614 This field contains the conversion table for converting text to upper
446
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
7615 case. @xref{Case Tables,,, lispref, XEmacs Lisp Reference Manual}.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7616
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7617 @item case_canon_table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7618 This field contains the conversion table for canonicalizing text for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7619 case-folding search. @xref{Case Tables,,, lispref, XEmacs Lisp
446
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
7620 Reference Manual}.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7621
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7622 @item case_eqv_table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7623 This field contains the equivalence table for case-folding search.
446
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
7624 @xref{Case Tables,,, lispref, XEmacs Lisp Reference Manual}.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7625
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7626 @item display_table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7627 This field contains the buffer's display table, or @code{nil} if it
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7628 doesn't have one. @xref{Display Tables,,, lispref, XEmacs Lisp
446
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
7629 Reference Manual}.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7630
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7631 @item markers
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7632 This field contains the chain of all markers that currently point into
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7633 the buffer. Deletion of text in the buffer, and motion of the buffer's
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7634 gap, must check each of these markers and perhaps update it.
446
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
7635 @xref{Markers,,, lispref, XEmacs Lisp Reference Manual}.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7636
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7637 @item backed_up
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7638 This field is a flag that tells whether a backup file has been made for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7639 the visited file of this buffer.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7640
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7641 @item mark
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7642 This field contains the mark for the buffer. The mark is a marker,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7643 hence it is also included on the list @code{markers}. @xref{The Mark,,,
446
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
7644 lispref, XEmacs Lisp Reference Manual}.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7645
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7646 @item mark_active
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7647 This field is non-@code{nil} if the buffer's mark is active.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7648
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7649 @item local_var_alist
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7650 This field contains the association list describing the variables local
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7651 in this buffer, and their values, with the exception of local variables
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7652 that have special slots in the buffer object. (Those slots are omitted
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7653 from this table.) @xref{Buffer-Local Variables,,, lispref, XEmacs Lisp
446
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
7654 Reference Manual}.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7655
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7656 @item modeline_format
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7657 This field contains a Lisp object which controls how to display the mode
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7658 line for this buffer. @xref{Modeline Format,,, lispref, XEmacs Lisp
446
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
7659 Reference Manual}.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7660
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7661 @item base_buffer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7662 This field holds the buffer's base buffer (if it is an indirect buffer),
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7663 or @code{nil}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7664 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7665
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7666 @node MULE Character Sets and Encodings, The Lisp Reader and Compiler, Buffers and Textual Representation, Top
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7667 @chapter MULE Character Sets and Encodings
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7668 @cindex Mule character sets and encodings
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7669 @cindex character sets and encodings, Mule
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7670 @cindex encodings, Mule character sets and
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7671
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7672 Recall that there are two primary ways that text is represented in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7673 XEmacs. The @dfn{buffer} representation sees the text as a series of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7674 bytes (Bufbytes), with a variable number of bytes used per character.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7675 The @dfn{character} representation sees the text as a series of integers
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7676 (Emchars), one per character. The character representation is a cleaner
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7677 representation from a theoretical standpoint, and is thus used in many
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7678 cases when lots of manipulations on a string need to be done. However,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7679 the buffer representation is the standard representation used in both
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7680 Lisp strings and buffers, and because of this, it is the ``default''
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7681 representation that text comes in. The reason for using this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7682 representation is that it's compact and is compatible with ASCII.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7683
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7684 @menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7685 * Character Sets::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7686 * Encodings::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7687 * Internal Mule Encodings::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7688 * CCL::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7689 @end menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7690
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7691 @node Character Sets
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7692 @section Character Sets
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7693 @cindex character sets
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7694
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7695 A character set (or @dfn{charset}) is an ordered set of characters. A
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7696 particular character in a charset is indexed using one or more
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7697 @dfn{position codes}, which are non-negative integers. The number of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7698 position codes needed to identify a particular character in a charset is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7699 called the @dfn{dimension} of the charset. In XEmacs/Mule, all charsets
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7700 have dimension 1 or 2, and the size of all charsets (except for a few
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7701 special cases) is either 94, 96, 94 by 94, or 96 by 96. The range of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7702 position codes used to index characters from any of these types of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7703 character sets is as follows:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7704
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7705 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7706 Charset type Position code 1 Position code 2
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7707 ------------------------------------------------------------
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7708 94 33 - 126 N/A
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7709 96 32 - 127 N/A
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7710 94x94 33 - 126 33 - 126
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7711 96x96 32 - 127 32 - 127
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7712 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7713
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7714 Note that in the above cases position codes do not start at an
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7715 expected value such as 0 or 1. The reason for this will become clear
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7716 later.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7717
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7718 For example, Latin-1 is a 96-character charset, and JISX0208 (the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7719 Japanese national character set) is a 94x94-character charset.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7720
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7721 [Note that, although the ranges above define the @emph{valid} position
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7722 codes for a charset, some of the slots in a particular charset may in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7723 fact be empty. This is the case for JISX0208, for example, where (e.g.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7724 all the slots whose first position code is in the range 118 - 127 are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7725 empty.]
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7726
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7727 There are three charsets that do not follow the above rules. All of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7728 them have one dimension, and have ranges of position codes as follows:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7729
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7730 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7731 Charset name Position code 1
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7732 ------------------------------------
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7733 ASCII 0 - 127
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7734 Control-1 0 - 31
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7735 Composite 0 - some large number
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7736 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7737
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7738 (The upper bound of the position code for composite characters has not
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7739 yet been determined, but it will probably be at least 16,383).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7740
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7741 ASCII is the union of two subsidiary character sets: Printing-ASCII
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7742 (the printing ASCII character set, consisting of position codes 33 -
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7743 126, like for a standard 94-character charset) and Control-ASCII (the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7744 non-printing characters that would appear in a binary file with codes 0
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7745 - 32 and 127).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7746
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7747 Control-1 contains the non-printing characters that would appear in a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7748 binary file with codes 128 - 159.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7749
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7750 Composite contains characters that are generated by overstriking one
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7751 or more characters from other charsets.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7752
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7753 Note that some characters in ASCII, and all characters in Control-1,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7754 are @dfn{control} (non-printing) characters. These have no printed
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7755 representation but instead control some other function of the printing
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7756 (e.g. TAB or 8 moves the current character position to the next tab
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7757 stop). All other characters in all charsets are @dfn{graphic}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7758 (printing) characters.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7759
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7760 When a binary file is read in, the bytes in the file are assigned to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7761 character sets as follows:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7762
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7763 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7764 Bytes Character set Range
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7765 --------------------------------------------------
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7766 0 - 127 ASCII 0 - 127
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7767 128 - 159 Control-1 0 - 31
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7768 160 - 255 Latin-1 32 - 127
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7769 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7770
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7771 This is a bit ad-hoc but gets the job done.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7772
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7773 @node Encodings
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7774 @section Encodings
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7775 @cindex encodings, Mule
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7776 @cindex Mule encodings
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7777
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7778 An @dfn{encoding} is a way of numerically representing characters from
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7779 one or more character sets. If an encoding only encompasses one
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7780 character set, then the position codes for the characters in that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7781 character set could be used directly. This is not possible, however, if
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7782 more than one character set is to be used in the encoding.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7783
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7784 For example, the conversion detailed above between bytes in a binary
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7785 file and characters is effectively an encoding that encompasses the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7786 three character sets ASCII, Control-1, and Latin-1 in a stream of 8-bit
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7787 bytes.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7788
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7789 Thus, an encoding can be viewed as a way of encoding characters from a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7790 specified group of character sets using a stream of bytes, each of which
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7791 contains a fixed number of bits (but not necessarily 8, as in the common
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7792 usage of ``byte'').
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7793
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7794 Here are descriptions of a couple of common
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7795 encodings:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7796
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7797 @menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7798 * Japanese EUC (Extended Unix Code)::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7799 * JIS7::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7800 @end menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7801
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7802 @node Japanese EUC (Extended Unix Code)
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7803 @subsection Japanese EUC (Extended Unix Code)
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7804 @cindex Japanese EUC (Extended Unix Code)
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7805 @cindex EUC (Extended Unix Code), Japanese
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7806 @cindex Extended Unix Code, Japanese EUC
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7807
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7808 This encompasses the character sets Printing-ASCII, Japanese-JISX0201,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7809 and Japanese-JISX0208-Kana (half-width katakana, the right half of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7810 JISX0201). It uses 8-bit bytes.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7811
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7812 Note that Printing-ASCII and Japanese-JISX0201-Kana are 94-character
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7813 charsets, while Japanese-JISX0208 is a 94x94-character charset.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7814
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7815 The encoding is as follows:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7816
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7817 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7818 Character set Representation (PC=position-code)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7819 ------------- --------------
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7820 Printing-ASCII PC1
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7821 Japanese-JISX0201-Kana 0x8E | PC1 + 0x80
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7822 Japanese-JISX0208 PC1 + 0x80 | PC2 + 0x80
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7823 Japanese-JISX0212 PC1 + 0x80 | PC2 + 0x80
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7824 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7825
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7826
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7827 @node JIS7
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7828 @subsection JIS7
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7829 @cindex JIS7
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7830
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7831 This encompasses the character sets Printing-ASCII,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7832 Japanese-JISX0201-Roman (the left half of JISX0201; this character set
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7833 is very similar to Printing-ASCII and is a 94-character charset),
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7834 Japanese-JISX0208, and Japanese-JISX0201-Kana. It uses 7-bit bytes.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7835
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7836 Unlike Japanese EUC, this is a @dfn{modal} encoding, which
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7837 means that there are multiple states that the encoding can
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7838 be in, which affect how the bytes are to be interpreted.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7839 Special sequences of bytes (called @dfn{escape sequences})
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7840 are used to change states.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7841
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7842 The encoding is as follows:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7843
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7844 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7845 Character set Representation (PC=position-code)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7846 ------------- --------------
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7847 Printing-ASCII PC1
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7848 Japanese-JISX0201-Roman PC1
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7849 Japanese-JISX0201-Kana PC1
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7850 Japanese-JISX0208 PC1 PC2
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7851
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7852
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7853 Escape sequence ASCII equivalent Meaning
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7854 --------------- ---------------- -------
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7855 0x1B 0x28 0x4A ESC ( J invoke Japanese-JISX0201-Roman
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7856 0x1B 0x28 0x49 ESC ( I invoke Japanese-JISX0201-Kana
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7857 0x1B 0x24 0x42 ESC $ B invoke Japanese-JISX0208
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7858 0x1B 0x28 0x42 ESC ( B invoke Printing-ASCII
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7859 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7860
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7861 Initially, Printing-ASCII is invoked.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7862
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7863 @node Internal Mule Encodings
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7864 @section Internal Mule Encodings
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7865 @cindex internal Mule encodings
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7866 @cindex Mule encodings, internal
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7867 @cindex encodings, internal Mule
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7868
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7869 In XEmacs/Mule, each character set is assigned a unique number, called a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7870 @dfn{leading byte}. This is used in the encodings of a character.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7871 Leading bytes are in the range 0x80 - 0xFF (except for ASCII, which has
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7872 a leading byte of 0), although some leading bytes are reserved.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7873
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7874 Charsets whose leading byte is in the range 0x80 - 0x9F are called
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7875 @dfn{official} and are used for built-in charsets. Other charsets are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7876 called @dfn{private} and have leading bytes in the range 0xA0 - 0xFF;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7877 these are user-defined charsets.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7878
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7879 More specifically:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7880
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7881 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7882 Character set Leading byte
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7883 ------------- ------------
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7884 ASCII 0
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7885 Composite 0x80
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7886 Dimension-1 Official 0x81 - 0x8D
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7887 (0x8E is free)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7888 Control-1 0x8F
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7889 Dimension-2 Official 0x90 - 0x99
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7890 (0x9A - 0x9D are free;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7891 0x9E and 0x9F are reserved)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7892 Dimension-1 Private 0xA0 - 0xEF
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7893 Dimension-2 Private 0xF0 - 0xFF
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7894 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7895
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7896 There are two internal encodings for characters in XEmacs/Mule. One is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7897 called @dfn{string encoding} and is an 8-bit encoding that is used for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7898 representing characters in a buffer or string. It uses 1 to 4 bytes per
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7899 character. The other is called @dfn{character encoding} and is a 19-bit
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7900 encoding that is used for representing characters individually in a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7901 variable.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7902
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7903 (In the following descriptions, we'll ignore composite characters for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7904 the moment. We also give a general (structural) overview first,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7905 followed later by the exact details.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7906
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7907 @menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7908 * Internal String Encoding::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7909 * Internal Character Encoding::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7910 @end menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7911
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7912 @node Internal String Encoding
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7913 @subsection Internal String Encoding
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7914 @cindex internal string encoding
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7915 @cindex string encoding, internal
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7916 @cindex encoding, internal string
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7917
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7918 ASCII characters are encoded using their position code directly. Other
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7919 characters are encoded using their leading byte followed by their
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7920 position code(s) with the high bit set. Characters in private character
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7921 sets have their leading byte prefixed with a @dfn{leading byte prefix},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7922 which is either 0x9E or 0x9F. (No character sets are ever assigned these
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7923 leading bytes.) Specifically:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7924
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7925 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7926 Character set Encoding (PC=position-code, LB=leading-byte)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7927 ------------- --------
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7928 ASCII PC-1 |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7929 Control-1 LB | PC1 + 0xA0 |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7930 Dimension-1 official LB | PC1 + 0x80 |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7931 Dimension-1 private 0x9E | LB | PC1 + 0x80 |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7932 Dimension-2 official LB | PC1 + 0x80 | PC2 + 0x80 |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7933 Dimension-2 private 0x9F | LB | PC1 + 0x80 | PC2 + 0x80
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7934 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7935
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7936 The basic characteristic of this encoding is that the first byte
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7937 of all characters is in the range 0x00 - 0x9F, and the second and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7938 following bytes of all characters is in the range 0xA0 - 0xFF.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7939 This means that it is impossible to get out of sync, or more
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7940 specifically:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7941
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7942 @enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7943 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7944 Given any byte position, the beginning of the character it is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7945 within can be determined in constant time.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7946 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7947 Given any byte position at the beginning of a character, the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7948 beginning of the next character can be determined in constant
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7949 time.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7950 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7951 Given any byte position at the beginning of a character, the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7952 beginning of the previous character can be determined in constant
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7953 time.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7954 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7955 Textual searches can simply treat encoded strings as if they
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7956 were encoded in a one-byte-per-character fashion rather than
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7957 the actual multi-byte encoding.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7958 @end enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7959
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7960 None of the standard non-modal encodings meet all of these
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7961 conditions. For example, EUC satisfies only (2) and (3), while
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7962 Shift-JIS and Big5 (not yet described) satisfy only (2). (All
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7963 non-modal encodings must satisfy (2), in order to be unambiguous.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7964
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7965 @node Internal Character Encoding
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7966 @subsection Internal Character Encoding
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7967 @cindex internal character encoding
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7968 @cindex character encoding, internal
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
7969 @cindex encoding, internal character
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7970
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7971 One 19-bit word represents a single character. The word is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7972 separated into three fields:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7973
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7974 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7975 Bit number: 18 17 16 15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7976 <------------> <------------------> <------------------>
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7977 Field: 1 2 3
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7978 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7979
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7980 Note that fields 2 and 3 hold 7 bits each, while field 1 holds 5 bits.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7981
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7982 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7983 Character set Field 1 Field 2 Field 3
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7984 ------------- ------- ------- -------
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7985 ASCII 0 0 PC1
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7986 range: (00 - 7F)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7987 Control-1 0 1 PC1
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7988 range: (00 - 1F)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7989 Dimension-1 official 0 LB - 0x80 PC1
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7990 range: (01 - 0D) (20 - 7F)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7991 Dimension-1 private 0 LB - 0x80 PC1
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7992 range: (20 - 6F) (20 - 7F)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7993 Dimension-2 official LB - 0x8F PC1 PC2
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7994 range: (01 - 0A) (20 - 7F) (20 - 7F)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7995 Dimension-2 private LB - 0xE1 PC1 PC2
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7996 range: (0F - 1E) (20 - 7F) (20 - 7F)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7997 Composite 0x1F ? ?
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7998 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7999
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8000 Note that character codes 0 - 255 are the same as the ``binary encoding''
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8001 described above.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8002
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8003 @node CCL
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8004 @section CCL
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8005 @cindex CCL
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8006
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8007 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8008 CCL PROGRAM SYNTAX:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8009 CCL_PROGRAM := (CCL_MAIN_BLOCK
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8010 [ CCL_EOF_BLOCK ])
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8011
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8012 CCL_MAIN_BLOCK := CCL_BLOCK
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8013 CCL_EOF_BLOCK := CCL_BLOCK
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8014
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8015 CCL_BLOCK := STATEMENT | (STATEMENT [STATEMENT ...])
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8016 STATEMENT :=
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8017 SET | IF | BRANCH | LOOP | REPEAT | BREAK
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8018 | READ | WRITE
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8019
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8020 SET := (REG = EXPRESSION) | (REG SELF_OP EXPRESSION)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8021 | INT-OR-CHAR
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8022
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8023 EXPRESSION := ARG | (EXPRESSION OP ARG)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8024
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8025 IF := (if EXPRESSION CCL_BLOCK CCL_BLOCK)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8026 BRANCH := (branch EXPRESSION CCL_BLOCK [CCL_BLOCK ...])
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8027 LOOP := (loop STATEMENT [STATEMENT ...])
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8028 BREAK := (break)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8029 REPEAT := (repeat)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8030 | (write-repeat [REG | INT-OR-CHAR | string])
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8031 | (write-read-repeat REG [INT-OR-CHAR | string | ARRAY]?)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8032 READ := (read REG) | (read REG REG)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8033 | (read-if REG ARITH_OP ARG CCL_BLOCK CCL_BLOCK)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8034 | (read-branch REG CCL_BLOCK [CCL_BLOCK ...])
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8035 WRITE := (write REG) | (write REG REG)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8036 | (write INT-OR-CHAR) | (write STRING) | STRING
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8037 | (write REG ARRAY)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8038 END := (end)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8039
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8040 REG := r0 | r1 | r2 | r3 | r4 | r5 | r6 | r7
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8041 ARG := REG | INT-OR-CHAR
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8042 OP := + | - | * | / | % | & | '|' | ^ | << | >> | <8 | >8 | //
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8043 | < | > | == | <= | >= | !=
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8044 SELF_OP :=
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8045 += | -= | *= | /= | %= | &= | '|=' | ^= | <<= | >>=
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8046 ARRAY := '[' INT-OR-CHAR ... ']'
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8047 INT-OR-CHAR := INT | CHAR
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8048
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8049 MACHINE CODE:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8050
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8051 The machine code consists of a vector of 32-bit words.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8052 The first such word specifies the start of the EOF section of the code;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8053 this is the code executed to handle any stuff that needs to be done
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8054 (e.g. designating back to ASCII and left-to-right mode) after all
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8055 other encoded/decoded data has been written out. This is not used for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8056 charset CCL programs.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8057
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
8058 REGISTER: 0..7 -- referred by RRR or rrr
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8059
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8060 OPERATOR BIT FIELD (27-bit): XXXXXXXXXXXXXXX RRR TTTTT
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8061 TTTTT (5-bit): operator type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8062 RRR (3-bit): register number
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8063 XXXXXXXXXXXXXXXX (15-bit):
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8064 CCCCCCCCCCCCCCC: constant or address
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8065 000000000000rrr: register number
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8066
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8067 AAAA: 00000 +
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8068 00001 -
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8069 00010 *
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8070 00011 /
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8071 00100 %
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8072 00101 &
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8073 00110 |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8074 00111 ~
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8075
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8076 01000 <<
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8077 01001 >>
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8078 01010 <8
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8079 01011 >8
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8080 01100 //
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8081 01101 not used
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8082 01110 not used
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8083 01111 not used
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8084
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8085 10000 <
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8086 10001 >
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8087 10010 ==
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8088 10011 <=
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8089 10100 >=
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8090 10101 !=
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8091
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8092 OPERATORS: TTTTT RRR XX..
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8093
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8094 SetCS: 00000 RRR C...C RRR = C...C
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8095 SetCL: 00001 RRR ..... RRR = c...c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8096 c.............c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8097 SetR: 00010 RRR ..rrr RRR = rrr
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8098 SetA: 00011 RRR ..rrr RRR = array[rrr]
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8099 C.............C size of array = C...C
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8100 c.............c contents = c...c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8101
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8102 Jump: 00100 000 c...c jump to c...c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8103 JumpCond: 00101 RRR c...c if (!RRR) jump to c...c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8104 WriteJump: 00110 RRR c...c Write1 RRR, jump to c...c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8105 WriteReadJump: 00111 RRR c...c Write1, Read1 RRR, jump to c...c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8106 WriteCJump: 01000 000 c...c Write1 C...C, jump to c...c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8107 C...C
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8108 WriteCReadJump: 01001 RRR c...c Write1 C...C, Read1 RRR,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8109 C.............C and jump to c...c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8110 WriteSJump: 01010 000 c...c WriteS, jump to c...c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8111 C.............C
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8112 S.............S
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8113 ...
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8114 WriteSReadJump: 01011 RRR c...c WriteS, Read1 RRR, jump to c...c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8115 C.............C
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8116 S.............S
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8117 ...
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8118 WriteAReadJump: 01100 RRR c...c WriteA, Read1 RRR, jump to c...c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8119 C.............C size of array = C...C
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8120 c.............c contents = c...c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8121 ...
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8122 Branch: 01101 RRR C...C if (RRR >= 0 && RRR < C..)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8123 c.............c branch to (RRR+1)th address
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8124 Read1: 01110 RRR ... read 1-byte to RRR
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8125 Read2: 01111 RRR ..rrr read 2-byte to RRR and rrr
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8126 ReadBranch: 10000 RRR C...C Read1 and Branch
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8127 c.............c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8128 ...
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8129 Write1: 10001 RRR ..... write 1-byte RRR
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8130 Write2: 10010 RRR ..rrr write 2-byte RRR and rrr
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8131 WriteC: 10011 000 ..... write 1-char C...CC
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8132 C.............C
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8133 WriteS: 10100 000 ..... write C..-byte of string
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8134 C.............C
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8135 S.............S
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8136 ...
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8137 WriteA: 10101 RRR ..... write array[RRR]
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8138 C.............C size of array = C...C
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8139 c.............c contents = c...c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8140 ...
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8141 End: 10110 000 ..... terminate the execution
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8142
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8143 SetSelfCS: 10111 RRR C...C RRR AAAAA= C...C
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8144 ..........AAAAA
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8145 SetSelfCL: 11000 RRR ..... RRR AAAAA= c...c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8146 c.............c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8147 ..........AAAAA
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8148 SetSelfR: 11001 RRR ..Rrr RRR AAAAA= rrr
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8149 ..........AAAAA
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8150 SetExprCL: 11010 RRR ..Rrr RRR = rrr AAAAA c...c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8151 c.............c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8152 ..........AAAAA
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8153 SetExprR: 11011 RRR ..rrr RRR = rrr AAAAA Rrr
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8154 ............Rrr
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8155 ..........AAAAA
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8156 JumpCondC: 11100 RRR c...c if !(RRR AAAAA C..) jump to c...c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8157 C.............C
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8158 ..........AAAAA
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8159 JumpCondR: 11101 RRR c...c if !(RRR AAAAA rrr) jump to c...c
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8160 ............rrr
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8161 ..........AAAAA
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8162 ReadJumpCondC: 11110 RRR c...c Read1 and JumpCondC
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8163 C.............C
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8164 ..........AAAAA
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8165 ReadJumpCondR: 11111 RRR c...c Read1 and JumpCondR
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8166 ............rrr
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8167 ..........AAAAA
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8168 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8169
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8170 @node The Lisp Reader and Compiler, Lstreams, MULE Character Sets and Encodings, Top
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8171 @chapter The Lisp Reader and Compiler
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8172 @cindex Lisp reader and compiler, the
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8173 @cindex reader and compiler, the Lisp
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8174 @cindex compiler, the Lisp reader and
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8175
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8176 Not yet documented.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8177
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8178 @node Lstreams, Consoles; Devices; Frames; Windows, The Lisp Reader and Compiler, Top
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8179 @chapter Lstreams
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8180 @cindex lstreams
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8181
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8182 An @dfn{lstream} is an internal Lisp object that provides a generic
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8183 buffering stream implementation. Conceptually, you send data to the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8184 stream or read data from the stream, not caring what's on the other end
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8185 of the stream. The other end could be another stream, a file
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8186 descriptor, a stdio stream, a fixed block of memory, a reallocating
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8187 block of memory, etc. The main purpose of the stream is to provide a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8188 standard interface and to do buffering. Macros are defined to read or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8189 write characters, so the calling functions do not have to worry about
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8190 blocking data together in order to achieve efficiency.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8191
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8192 @menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8193 * Creating an Lstream:: Creating an lstream object.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8194 * Lstream Types:: Different sorts of things that are streamed.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8195 * Lstream Functions:: Functions for working with lstreams.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8196 * Lstream Methods:: Creating new lstream types.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8197 @end menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8198
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8199 @node Creating an Lstream
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8200 @section Creating an Lstream
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8201 @cindex lstream, creating an
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8202
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8203 Lstreams come in different types, depending on what is being interfaced
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8204 to. Although the primitive for creating new lstreams is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8205 @code{Lstream_new()}, generally you do not call this directly. Instead,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8206 you call some type-specific creation function, which creates the lstream
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8207 and initializes it as appropriate for the particular type.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8208
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8209 All lstream creation functions take a @var{mode} argument, specifying
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8210 what mode the lstream should be opened as. This controls whether the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8211 lstream is for input and output, and optionally whether data should be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8212 blocked up in units of MULE characters. Note that some types of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8213 lstreams can only be opened for input; others only for output; and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8214 others can be opened either way. #### Richard Mlynarik thinks that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8215 there should be a strict separation between input and output streams,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8216 and he's probably right.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8217
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8218 @var{mode} is a string, one of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8219
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8220 @table @code
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8221 @item "r"
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8222 Open for reading.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8223 @item "w"
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8224 Open for writing.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8225 @item "rc"
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8226 Open for reading, but ``read'' never returns partial MULE characters.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8227 @item "wc"
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8228 Open for writing, but never writes partial MULE characters.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8229 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8230
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8231 @node Lstream Types
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8232 @section Lstream Types
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8233 @cindex lstream types
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8234 @cindex types, lstream
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8235
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8236 @table @asis
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8237 @item stdio
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8238
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8239 @item filedesc
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8240
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8241 @item lisp-string
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8242
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8243 @item fixed-buffer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8244
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8245 @item resizing-buffer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8246
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8247 @item dynarr
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8248
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8249 @item lisp-buffer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8250
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8251 @item print
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8252
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8253 @item decoding
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8254
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8255 @item encoding
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8256 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8257
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8258 @node Lstream Functions
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8259 @section Lstream Functions
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8260 @cindex lstream functions
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8261
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
8262 @deftypefun {Lstream *} Lstream_new (Lstream_implementation *@var{imp}, const char *@var{mode})
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8263 Allocate and return a new Lstream. This function is not really meant to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8264 be called directly; rather, each stream type should provide its own
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8265 stream creation function, which creates the stream and does any other
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8266 necessary creation stuff (e.g. opening a file).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8267 @end deftypefun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8268
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8269 @deftypefun void Lstream_set_buffering (Lstream *@var{lstr}, Lstream_buffering @var{buffering}, int @var{buffering_size})
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8270 Change the buffering of a stream. See @file{lstream.h}. By default the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8271 buffering is @code{STREAM_BLOCK_BUFFERED}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8272 @end deftypefun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8273
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8274 @deftypefun int Lstream_flush (Lstream *@var{lstr})
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8275 Flush out any pending unwritten data in the stream. Clear any buffered
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8276 input data. Returns 0 on success, -1 on error.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8277 @end deftypefun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8278
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8279 @deftypefn Macro int Lstream_putc (Lstream *@var{stream}, int @var{c})
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8280 Write out one byte to the stream. This is a macro and so it is very
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8281 efficient. The @var{c} argument is only evaluated once but the @var{stream}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8282 argument is evaluated more than once. Returns 0 on success, -1 on
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8283 error.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8284 @end deftypefn
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8285
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8286 @deftypefn Macro int Lstream_getc (Lstream *@var{stream})
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8287 Read one byte from the stream. This is a macro and so it is very
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8288 efficient. The @var{stream} argument is evaluated more than once. Return
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8289 value is -1 for EOF or error.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8290 @end deftypefn
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8291
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8292 @deftypefn Macro void Lstream_ungetc (Lstream *@var{stream}, int @var{c})
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8293 Push one byte back onto the input queue. This will be the next byte
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8294 read from the stream. Any number of bytes can be pushed back and will
440
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 438
diff changeset
8295 be read in the reverse order they were pushed back---most recent
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 438
diff changeset
8296 first. (This is necessary for consistency---if there are a number of
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8297 bytes that have been unread and I read and unread a byte, it needs to be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8298 the first to be read again.) This is a macro and so it is very
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8299 efficient. The @var{c} argument is only evaluated once but the @var{stream}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8300 argument is evaluated more than once.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8301 @end deftypefn
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8302
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8303 @deftypefun int Lstream_fputc (Lstream *@var{stream}, int @var{c})
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8304 @deftypefunx int Lstream_fgetc (Lstream *@var{stream})
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8305 @deftypefunx void Lstream_fungetc (Lstream *@var{stream}, int @var{c})
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8306 Function equivalents of the above macros.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8307 @end deftypefun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8308
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8309 @deftypefun ssize_t Lstream_read (Lstream *@var{stream}, void *@var{data}, size_t @var{size})
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8310 Read @var{size} bytes of @var{data} from the stream. Return the number
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8311 of bytes read. 0 means EOF. -1 means an error occurred and no bytes
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8312 were read.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8313 @end deftypefun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8314
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8315 @deftypefun ssize_t Lstream_write (Lstream *@var{stream}, void *@var{data}, size_t @var{size})
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8316 Write @var{size} bytes of @var{data} to the stream. Return the number
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8317 of bytes written. -1 means an error occurred and no bytes were written.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8318 @end deftypefun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8319
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8320 @deftypefun void Lstream_unread (Lstream *@var{stream}, void *@var{data}, size_t @var{size})
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8321 Push back @var{size} bytes of @var{data} onto the input queue. The next
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8322 call to @code{Lstream_read()} with the same size will read the same
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8323 bytes back. Note that this will be the case even if there is other
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8324 pending unread data.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8325 @end deftypefun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8326
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8327 @deftypefun int Lstream_close (Lstream *@var{stream})
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8328 Close the stream. All data will be flushed out.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8329 @end deftypefun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8330
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8331 @deftypefun void Lstream_reopen (Lstream *@var{stream})
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8332 Reopen a closed stream. This enables I/O on it again. This is not
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8333 meant to be called except from a wrapper routine that reinitializes
440
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 438
diff changeset
8334 variables and such---the close routine may well have freed some
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8335 necessary storage structures, for example.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8336 @end deftypefun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8337
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8338 @deftypefun void Lstream_rewind (Lstream *@var{stream})
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8339 Rewind the stream to the beginning.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8340 @end deftypefun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8341
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8342 @node Lstream Methods
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8343 @section Lstream Methods
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8344 @cindex lstream methods
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8345
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8346 @deftypefn {Lstream Method} ssize_t reader (Lstream *@var{stream}, unsigned char *@var{data}, size_t @var{size})
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8347 Read some data from the stream's end and store it into @var{data}, which
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8348 can hold @var{size} bytes. Return the number of bytes read. A return
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8349 value of 0 means no bytes can be read at this time. This may be because
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8350 of an EOF, or because there is a granularity greater than one byte that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8351 the stream imposes on the returned data, and @var{size} is less than
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8352 this granularity. (This will happen frequently for streams that need to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8353 return whole characters, because @code{Lstream_read()} calls the reader
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8354 function repeatedly until it has the number of bytes it wants or until 0
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8355 is returned.) The lstream functions do not treat a 0 return as EOF or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8356 do anything special; however, the calling function will interpret any 0
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8357 it gets back as EOF. This will normally not happen unless the caller
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8358 calls @code{Lstream_read()} with a very small size.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8359
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8360 This function can be @code{NULL} if the stream is output-only.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8361 @end deftypefn
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8362
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
8363 @deftypefn {Lstream Method} ssize_t writer (Lstream *@var{stream}, const unsigned char *@var{data}, size_t @var{size})
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8364 Send some data to the stream's end. Data to be sent is in @var{data}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8365 and is @var{size} bytes. Return the number of bytes sent. This
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8366 function can send and return fewer bytes than is passed in; in that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8367 case, the function will just be called again until there is no data left
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8368 or 0 is returned. A return value of 0 means that no more data can be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8369 currently stored, but there is no error; the data will be squirreled
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8370 away until the writer can accept data. (This is useful, e.g., if you're
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8371 dealing with a non-blocking file descriptor and are getting
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8372 @code{EWOULDBLOCK} errors.) This function can be @code{NULL} if the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8373 stream is input-only.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8374 @end deftypefn
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8375
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8376 @deftypefn {Lstream Method} int rewinder (Lstream *@var{stream})
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8377 Rewind the stream. If this is @code{NULL}, the stream is not seekable.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8378 @end deftypefn
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8379
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8380 @deftypefn {Lstream Method} int seekable_p (Lstream *@var{stream})
440
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 438
diff changeset
8381 Indicate whether this stream is seekable---i.e. it can be rewound.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8382 This method is ignored if the stream does not have a rewind method. If
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8383 this method is not present, the result is determined by whether a rewind
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8384 method is present.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8385 @end deftypefn
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8386
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8387 @deftypefn {Lstream Method} int flusher (Lstream *@var{stream})
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8388 Perform any additional operations necessary to flush the data in this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8389 stream.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8390 @end deftypefn
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8391
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8392 @deftypefn {Lstream Method} int pseudo_closer (Lstream *@var{stream})
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8393 @end deftypefn
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8394
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8395 @deftypefn {Lstream Method} int closer (Lstream *@var{stream})
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8396 Perform any additional operations necessary to close this stream down.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8397 May be @code{NULL}. This function is called when @code{Lstream_close()}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8398 is called or when the stream is garbage-collected. When this function
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8399 is called, all pending data in the stream will already have been written
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8400 out.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8401 @end deftypefn
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8402
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8403 @deftypefn {Lstream Method} Lisp_Object marker (Lisp_Object @var{lstream}, void (*@var{markfun}) (Lisp_Object))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8404 Mark this object for garbage collection. Same semantics as a standard
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8405 @code{Lisp_Object} marker. This function can be @code{NULL}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8406 @end deftypefn
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8407
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8408 @node Consoles; Devices; Frames; Windows, The Redisplay Mechanism, Lstreams, Top
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8409 @chapter Consoles; Devices; Frames; Windows
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8410 @cindex consoles; devices; frames; windows
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8411 @cindex devices; frames; windows, consoles;
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8412 @cindex frames; windows, consoles; devices;
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8413 @cindex windows, consoles; devices; frames;
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8414
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8415 @menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8416 * Introduction to Consoles; Devices; Frames; Windows::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8417 * Point::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8418 * Window Hierarchy::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8419 * The Window Object::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8420 @end menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8421
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8422 @node Introduction to Consoles; Devices; Frames; Windows
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8423 @section Introduction to Consoles; Devices; Frames; Windows
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8424 @cindex consoles; devices; frames; windows, introduction to
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8425 @cindex devices; frames; windows, introduction to consoles;
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8426 @cindex frames; windows, introduction to consoles; devices;
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8427 @cindex windows, introduction to consoles; devices; frames;
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8429 A window-system window that you see on the screen is called a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8430 @dfn{frame} in Emacs terminology. Each frame is subdivided into one or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8431 more non-overlapping panes, called (confusingly) @dfn{windows}. Each
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8432 window displays the text of a buffer in it. (See above on Buffers.) Note
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8433 that buffers and windows are independent entities: Two or more windows
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8434 can be displaying the same buffer (potentially in different locations),
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8435 and a buffer can be displayed in no windows.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8436
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8437 A single display screen that contains one or more frames is called
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8438 a @dfn{display}. Under most circumstances, there is only one display.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8439 However, more than one display can exist, for example if you have
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8440 a @dfn{multi-headed} console, i.e. one with a single keyboard but
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8441 multiple displays. (Typically in such a situation, the various
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8442 displays act like one large display, in that the mouse is only
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8443 in one of them at a time, and moving the mouse off of one moves
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8444 it into another.) In some cases, the different displays will
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8445 have different characteristics, e.g. one color and one mono.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8446
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8447 XEmacs can display frames on multiple displays. It can even deal
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8448 simultaneously with frames on multiple keyboards (called @dfn{consoles} in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8449 XEmacs terminology). Here is one case where this might be useful: You
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8450 are using XEmacs on your workstation at work, and leave it running.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8451 Then you go home and dial in on a TTY line, and you can use the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8452 already-running XEmacs process to display another frame on your local
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8453 TTY.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8454
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8455 Thus, there is a hierarchy console -> display -> frame -> window.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8456 There is a separate Lisp object type for each of these four concepts.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8457 Furthermore, there is logically a @dfn{selected console},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8458 @dfn{selected display}, @dfn{selected frame}, and @dfn{selected window}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8459 Each of these objects is distinguished in various ways, such as being the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8460 default object for various functions that act on objects of that type.
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
8461 Note that every containing object remembers the ``selected'' object
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8462 among the objects that it contains: e.g. not only is there a selected
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8463 window, but every frame remembers the last window in it that was
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8464 selected, and changing the selected frame causes the remembered window
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8465 within it to become the selected window. Similar relationships apply
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8466 for consoles to devices and devices to frames.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8467
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8468 @node Point
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8469 @section Point
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8470 @cindex point
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8471
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8472 Recall that every buffer has a current insertion position, called
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8473 @dfn{point}. Now, two or more windows may be displaying the same buffer,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8474 and the text cursor in the two windows (i.e. @code{point}) can be in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8475 two different places. You may ask, how can that be, since each
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8476 buffer has only one value of @code{point}? The answer is that each window
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8477 also has a value of @code{point} that is squirreled away in it. There
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8478 is only one selected window, and the value of ``point'' in that buffer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8479 corresponds to that window. When the selected window is changed
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8480 from one window to another displaying the same buffer, the old
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8481 value of @code{point} is stored into the old window's ``point'' and the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8482 value of @code{point} from the new window is retrieved and made the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8483 value of @code{point} in the buffer. This means that @code{window-point}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8484 for the selected window is potentially inaccurate, and if you
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8485 want to retrieve the correct value of @code{point} for a window,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8486 you must special-case on the selected window and retrieve the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8487 buffer's point instead. This is related to why @code{save-window-excursion}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8488 does not save the selected window's value of @code{point}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8489
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8490 @node Window Hierarchy
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8491 @section Window Hierarchy
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8492 @cindex window hierarchy
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8493 @cindex hierarchy of windows
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8494
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8495 If a frame contains multiple windows (panes), they are always created
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8496 by splitting an existing window along the horizontal or vertical axis.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8497 Terminology is a bit confusing here: to @dfn{split a window
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8498 horizontally} means to create two side-by-side windows, i.e. to make a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8499 @emph{vertical} cut in a window. Likewise, to @dfn{split a window
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8500 vertically} means to create two windows, one above the other, by making
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8501 a @emph{horizontal} cut.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8502
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8503 If you split a window and then split again along the same axis, you
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8504 will end up with a number of panes all arranged along the same axis.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8505 The precise way in which the splits were made should not be important,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8506 and this is reflected internally. Internally, all windows are arranged
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8507 in a tree, consisting of two types of windows, @dfn{combination} windows
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8508 (which have children, and are covered completely by those children) and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8509 @dfn{leaf} windows, which have no children and are visible. Every
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8510 combination window has two or more children, all arranged along the same
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8511 axis. There are (logically) two subtypes of windows, depending on
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8512 whether their children are horizontally or vertically arrayed. There is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8513 always one root window, which is either a leaf window (if the frame
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8514 contains only one window) or a combination window (if the frame contains
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8515 more than one window). In the latter case, the root window will have
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8516 two or more children, either horizontally or vertically arrayed, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8517 each of those children will be either a leaf window or another
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8518 combination window.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8519
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8520 Here are some rules:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8521
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8522 @enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8523 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8524 Horizontal combination windows can never have children that are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8525 horizontal combination windows; same for vertical.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8526
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8527 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8528 Only leaf windows can be split (obviously) and this splitting does one
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8529 of two things: (a) turns the leaf window into a combination window and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8530 creates two new leaf children, or (b) turns the leaf window into one of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8531 the two new leaves and creates the other leaf. Rule (1) dictates which
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8532 of these two outcomes happens.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8533
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8534 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8535 Every combination window must have at least two children.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8536
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8537 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8538 Leaf windows can never become combination windows. They can be deleted,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8539 however. If this results in a violation of (3), the parent combination
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8540 window also gets deleted.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8541
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8542 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8543 All functions that accept windows must be prepared to accept combination
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8544 windows, and do something sane (e.g. signal an error if so).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8545 Combination windows @emph{do} escape to the Lisp level.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8546
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8547 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8548 All windows have three fields governing their contents:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8549 these are @dfn{hchild} (a list of horizontally-arrayed children),
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8550 @dfn{vchild} (a list of vertically-arrayed children), and @dfn{buffer}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8551 (the buffer contained in a leaf window). Exactly one of
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 442
diff changeset
8552 these will be non-@code{nil}. Remember that @dfn{horizontally-arrayed}
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8553 means ``side-by-side'' and @dfn{vertically-arrayed} means
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8554 @dfn{one above the other}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8555
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8556 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8557 Leaf windows also have markers in their @code{start} (the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8558 first buffer position displayed in the window) and @code{pointm}
440
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 438
diff changeset
8559 (the window's stashed value of @code{point}---see above) fields,
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 442
diff changeset
8560 while combination windows have @code{nil} in these fields.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8561
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8562 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8563 The list of children for a window is threaded through the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8564 @code{next} and @code{prev} fields of each child window.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8565
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8566 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8567 @strong{Deleted windows can be undeleted}. This happens as a result of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8568 restoring a window configuration, and is unlike frames, displays, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8569 consoles, which, once deleted, can never be restored. Deleting a window
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8570 does nothing except set a special @code{dead} bit to 1 and clear out the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8571 @code{next}, @code{prev}, @code{hchild}, and @code{vchild} fields, for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8572 GC purposes.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8573
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8574 @item
440
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 438
diff changeset
8575 Most frames actually have two top-level windows---one for the
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8576 minibuffer and one (the @dfn{root}) for everything else. The modeline
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8577 (if present) separates these two. The @code{next} field of the root
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8578 points to the minibuffer, and the @code{prev} field of the minibuffer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8579 points to the root. The other @code{next} and @code{prev} fields are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8580 @code{nil}, and the frame points to both of these windows.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8581 Minibuffer-less frames have no minibuffer window, and the @code{next}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8582 and @code{prev} of the root window are @code{nil}. Minibuffer-only
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8583 frames have no root window, and the @code{next} of the minibuffer window
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8584 is @code{nil} but the @code{prev} points to itself. (#### This is an
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8585 artifact that should be fixed.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8586 @end enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8587
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8588 @node The Window Object
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8589 @section The Window Object
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8590 @cindex window object, the
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8591 @cindex object, the window
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8592
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8593 Windows have the following accessible fields:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8594
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8595 @table @code
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8596 @item frame
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8597 The frame that this window is on.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8598
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8599 @item mini_p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8600 Non-@code{nil} if this window is a minibuffer window.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8601
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8602 @item buffer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8603 The buffer that the window is displaying. This may change often during
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8604 the life of the window.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8605
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8606 @item dedicated
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8607 Non-@code{nil} if this window is dedicated to its buffer.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8608
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8609 @item pointm
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8610 @cindex window point internals
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8611 This is the value of point in the current buffer when this window is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8612 selected; when it is not selected, it retains its previous value.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8613
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8614 @item start
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8615 The position in the buffer that is the first character to be displayed
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8616 in the window.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8617
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8618 @item force_start
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8619 If this flag is non-@code{nil}, it says that the window has been
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8620 scrolled explicitly by the Lisp program. This affects what the next
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8621 redisplay does if point is off the screen: instead of scrolling the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8622 window to show the text around point, it moves point to a location that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8623 is on the screen.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8624
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8625 @item last_modified
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8626 The @code{modified} field of the window's buffer, as of the last time
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8627 a redisplay completed in this window.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8628
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8629 @item last_point
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8630 The buffer's value of point, as of the last time
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8631 a redisplay completed in this window.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8632
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8633 @item left
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8634 This is the left-hand edge of the window, measured in columns. (The
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8635 leftmost column on the screen is @w{column 0}.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8636
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8637 @item top
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8638 This is the top edge of the window, measured in lines. (The top line on
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8639 the screen is @w{line 0}.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8640
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8641 @item height
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8642 The height of the window, measured in lines.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8643
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8644 @item width
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8645 The width of the window, measured in columns.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8646
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8647 @item next
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8648 This is the window that is the next in the chain of siblings. It is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8649 @code{nil} in a window that is the rightmost or bottommost of a group of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8650 siblings.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8651
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8652 @item prev
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8653 This is the window that is the previous in the chain of siblings. It is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8654 @code{nil} in a window that is the leftmost or topmost of a group of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8655 siblings.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8656
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8657 @item parent
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8658 Internally, XEmacs arranges windows in a tree; each group of siblings has
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8659 a parent window whose area includes all the siblings. This field points
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8660 to a window's parent.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8661
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8662 Parent windows do not display buffers, and play little role in display
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8663 except to shape their child windows. Emacs Lisp programs usually have
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8664 no access to the parent windows; they operate on the windows at the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8665 leaves of the tree, which actually display buffers.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8666
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8667 @item hscroll
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8668 This is the number of columns that the display in the window is scrolled
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8669 horizontally to the left. Normally, this is 0.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8670
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8671 @item use_time
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8672 This is the last time that the window was selected. The function
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8673 @code{get-lru-window} uses this field.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8674
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8675 @item display_table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8676 The window's display table, or @code{nil} if none is specified for it.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8677
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8678 @item update_mode_line
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8679 Non-@code{nil} means this window's mode line needs to be updated.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8680
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8681 @item base_line_number
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8682 The line number of a certain position in the buffer, or @code{nil}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8683 This is used for displaying the line number of point in the mode line.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8684
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8685 @item base_line_pos
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8686 The position in the buffer for which the line number is known, or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8687 @code{nil} meaning none is known.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8688
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8689 @item region_showing
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8690 If the region (or part of it) is highlighted in this window, this field
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8691 holds the mark position that made one end of that region. Otherwise,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8692 this field is @code{nil}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8693 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8694
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8695 @node The Redisplay Mechanism, Extents, Consoles; Devices; Frames; Windows, Top
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8696 @chapter The Redisplay Mechanism
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8697 @cindex redisplay mechanism, the
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8698
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8699 The redisplay mechanism is one of the most complicated sections of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8700 XEmacs, especially from a conceptual standpoint. This is doubly so
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8701 because, unlike for the basic aspects of the Lisp interpreter, the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8702 computer science theories of how to efficiently handle redisplay are not
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8703 well-developed.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8704
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8705 When working with the redisplay mechanism, remember the Golden Rules
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8706 of Redisplay:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8707
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8708 @enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8709 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8710 It Is Better To Be Correct Than Fast.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8711 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8712 Thou Shalt Not Run Elisp From Within Redisplay.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8713 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8714 It Is Better To Be Fast Than Not To Be.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8715 @end enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8716
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8717 @menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8718 * Critical Redisplay Sections::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8719 * Line Start Cache::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8720 * Redisplay Piece by Piece::
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8721 @end menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8722
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8723 @node Critical Redisplay Sections
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8724 @section Critical Redisplay Sections
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8725 @cindex redisplay sections, critical
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8726 @cindex critical redisplay sections
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8727
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8728 Within this section, we are defenseless and assume that the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8729 following cannot happen:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8730
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8731 @enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8732 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8733 garbage collection
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8734 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8735 Lisp code evaluation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8736 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8737 frame size changes
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8738 @end enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8739
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8740 We ensure (3) by calling @code{hold_frame_size_changes()}, which
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8741 will cause any pending frame size changes to get put on hold
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8742 till after the end of the critical section. (1) follows
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8743 automatically if (2) is met. #### Unfortunately, there are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8744 some places where Lisp code can be called within this section.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8745 We need to remove them.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8746
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8747 If @code{Fsignal()} is called during this critical section, we
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8748 will @code{abort()}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8749
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8750 If garbage collection is called during this critical section,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8751 we simply return. #### We should abort instead.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8752
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8753 #### If a frame-size change does occur we should probably
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8754 actually be preempting redisplay.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8755
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8756 @node Line Start Cache
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8757 @section Line Start Cache
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8758 @cindex line start cache
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8759
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8760 The traditional scrolling code in Emacs breaks in a variable height
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8761 world. It depends on the key assumption that the number of lines that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8762 can be displayed at any given time is fixed. This led to a complete
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8763 separation of the scrolling code from the redisplay code. In order to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8764 fully support variable height lines, the scrolling code must actually be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8765 tightly integrated with redisplay. Only redisplay can determine how
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8766 many lines will be displayed on a screen for any given starting point.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8767
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8768 What is ideally wanted is a complete list of the starting buffer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8769 position for every possible display line of a buffer along with the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8770 height of that display line. Maintaining such a full list would be very
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8771 expensive. We settle for having it include information for all areas
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8772 which we happen to generate anyhow (i.e. the region currently being
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8773 displayed) and for those areas we need to work with.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8774
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8775 In order to ensure that the cache accurately represents what redisplay
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8776 would actually show, it is necessary to invalidate it in many
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8777 situations. If the buffer changes, the starting positions may no longer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8778 be correct. If a face or an extent has changed then the line heights
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8779 may have altered. These events happen frequently enough that the cache
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8780 can end up being constantly disabled. With this potentially constant
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8781 invalidation when is the cache ever useful?
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8782
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8783 Even if the cache is invalidated before every single usage, it is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8784 necessary. Scrolling often requires knowledge about display lines which
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8785 are actually above or below the visible region. The cache provides a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8786 convenient light-weight method of storing this information for multiple
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8787 display regions. This knowledge is necessary for the scrolling code to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8788 always obey the First Golden Rule of Redisplay.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8789
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8790 If the cache already contains all of the information that the scrolling
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8791 routines happen to need so that it doesn't have to go generate it, then
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8792 we are able to obey the Third Golden Rule of Redisplay. The first thing
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8793 we do to help out the cache is to always add the displayed region. This
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8794 region had to be generated anyway, so the cache ends up getting the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8795 information basically for free. In those cases where a user is simply
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8796 scrolling around viewing a buffer there is a high probability that this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8797 is sufficient to always provide the needed information. The second
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8798 thing we can do is be smart about invalidating the cache.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8799
440
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 438
diff changeset
8800 TODO---Be smart about invalidating the cache. Potential places:
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8801
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8802 @itemize @bullet
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8803 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8804 Insertions at end-of-line which don't cause line-wraps do not alter the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8805 starting positions of any display lines. These types of buffer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8806 modifications should not invalidate the cache. This is actually a large
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8807 optimization for redisplay speed as well.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8808 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8809 Buffer modifications frequently only affect the display of lines at and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8810 below where they occur. In these situations we should only invalidate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8811 the part of the cache starting at where the modification occurs.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8812 @end itemize
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8813
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8814 In case you're wondering, the Second Golden Rule of Redisplay is not
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8815 applicable.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8816
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8817 @node Redisplay Piece by Piece
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8818 @section Redisplay Piece by Piece
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8819 @cindex redisplay piece by piece
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8820
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8821 As you can begin to see redisplay is complex and also not well
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8822 documented. Chuck no longer works on XEmacs so this section is my take
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8823 on the workings of redisplay.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8824
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8825 Redisplay happens in three phases:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8826
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8827 @enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8828 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8829 Determine desired display in area that needs redisplay.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8830 Implemented by @code{redisplay.c}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8831 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8832 Compare desired display with current display
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8833 Implemented by @code{redisplay-output.c}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8834 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8835 Output changes Implemented by @code{redisplay-output.c},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8836 @code{redisplay-x.c}, @code{redisplay-msw.c} and @code{redisplay-tty.c}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8837 @end enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8838
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
8839 Steps 1 and 2 are device-independent and relatively complex. Step 3 is
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8840 mostly device-dependent.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8841
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8842 Determining the desired display
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8843
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8844 Display attributes are stored in @code{display_line} structures. Each
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8845 @code{display_line} consists of a set of @code{display_block}'s and each
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8846 @code{display_block} contains a number of @code{rune}'s. Generally
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8847 dynarr's of @code{display_line}'s are held by each window representing
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8848 the current display and the desired display.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8849
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
8850 The @code{display_line} structures are tightly tied to buffers which
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8851 presents a problem for redisplay as this connection is bogus for the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8852 modeline. Hence the @code{display_line} generation routines are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8853 duplicated for generating the modeline. This means that the modeline
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8854 display code has many bugs that the standard redisplay code does not.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8855
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8856 The guts of @code{display_line} generation are in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8857 @code{create_text_block}, which creates a single display line for the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8858 desired locale. This incrementally parses the characters on the current
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
8859 line and generates redisplay structures for each.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8860
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8861 Gutter redisplay is different. Because the data to display is stored in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8862 a string we cannot use @code{create_text_block}. Instead we use
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8863 @code{create_text_string_block} which performs the same function as
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8864 @code{create_text_block} but for strings. Many of the complexities of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8865 @code{create_text_block} to do with cursor handling and selective
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8866 display have been removed.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8867
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8868 @node Extents, Faces, The Redisplay Mechanism, Top
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8869 @chapter Extents
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8870 @cindex extents
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8871
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8872 @menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8873 * Introduction to Extents:: Extents are ranges over text, with properties.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8874 * Extent Ordering:: How extents are ordered internally.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8875 * Format of the Extent Info:: The extent information in a buffer or string.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8876 * Zero-Length Extents:: A weird special case.
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
8877 * Mathematics of Extent Ordering:: A rigorous foundation.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8878 * Extent Fragments:: Cached information useful for redisplay.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8879 @end menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8880
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8881 @node Introduction to Extents
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8882 @section Introduction to Extents
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8883 @cindex extents, introduction to
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8884
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8885 Extents are regions over a buffer, with a start and an end position
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8886 denoting the region of the buffer included in the extent. In
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8887 addition, either end can be closed or open, meaning that the endpoint
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8888 is or is not logically included in the extent. Insertion of a character
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8889 at a closed endpoint causes the character to go inside the extent;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8890 insertion at an open endpoint causes the character to go outside.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8891
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8892 Extent endpoints are stored using memory indices (see @file{insdel.c}),
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8893 to minimize the amount of adjusting that needs to be done when
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8894 characters are inserted or deleted.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8895
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8896 (Formerly, extent endpoints at the gap could be either before or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8897 after the gap, depending on the open/closedness of the endpoint.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8898 The intent of this was to make it so that insertions would
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8899 automatically go inside or out of extents as necessary with no
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8900 further work needing to be done. It didn't work out that way,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8901 however, and just ended up complexifying and buggifying all the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8902 rest of the code.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8903
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8904 @node Extent Ordering
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8905 @section Extent Ordering
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8906 @cindex extent ordering
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8907
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8908 Extents are compared using memory indices. There are two orderings
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8909 for extents and both orders are kept current at all times. The normal
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8910 or @dfn{display} order is as follows:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8911
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8912 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8913 Extent A is ``less than'' extent B,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8914 that is, earlier in the display order,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8915 if: A-start < B-start,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8916 or if: A-start = B-start, and A-end > B-end
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8917 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8918
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8919 So if two extents begin at the same position, the larger of them is the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8920 earlier one in the display order (@code{EXTENT_LESS} is true).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8921
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8922 For the e-order, the same thing holds:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8923
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8924 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8925 Extent A is ``less than'' extent B in e-order,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8926 that is, later in the buffer,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8927 if: A-end < B-end,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8928 or if: A-end = B-end, and A-start > B-start
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8929 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8930
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8931 So if two extents end at the same position, the smaller of them is the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8932 earlier one in the e-order (@code{EXTENT_E_LESS} is true).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8933
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8934 The display order and the e-order are complementary orders: any
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8935 theorem about the display order also applies to the e-order if you swap
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8936 all occurrences of ``display order'' and ``e-order'', ``less than'' and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8937 ``greater than'', and ``extent start'' and ``extent end''.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8938
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8939 @node Format of the Extent Info
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8940 @section Format of the Extent Info
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8941 @cindex extent info, format of the
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8942
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8943 An extent-info structure consists of a list of the buffer or string's
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8944 extents and a @dfn{stack of extents} that lists all of the extents over
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8945 a particular position. The stack-of-extents info is used for
440
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 438
diff changeset
8946 optimization purposes---it basically caches some info that might
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8947 be expensive to compute. Certain otherwise hard computations are easy
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8948 given the stack of extents over a particular position, and if the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8949 stack of extents over a nearby position is known (because it was
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8950 calculated at some prior point in time), it's easy to move the stack
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8951 of extents to the proper position.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8952
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8953 Given that the stack of extents is an optimization, and given that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8954 it requires memory, a string's stack of extents is wiped out each
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8955 time a garbage collection occurs. Therefore, any time you retrieve
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8956 the stack of extents, it might not be there. If you need it to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8957 be there, use the @code{_force} version.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8958
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8959 Similarly, a string may or may not have an extent_info structure.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8960 (Generally it won't if there haven't been any extents added to the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8961 string.) So use the @code{_force} version if you need the extent_info
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8962 structure to be there.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8963
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8964 A list of extents is maintained as a double gap array: one gap array
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8965 is ordered by start index (the @dfn{display order}) and the other is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8966 ordered by end index (the @dfn{e-order}). Note that positions in an
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8967 extent list should logically be conceived of as referring @emph{to} a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8968 particular extent (as is the norm in programs) rather than sitting
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8969 between two extents. Note also that callers of these functions should
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8970 not be aware of the fact that the extent list is implemented as an
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8971 array, except for the fact that positions are integers (this should be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8972 generalized to handle integers and linked list equally well).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8973
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8974 @node Zero-Length Extents
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8975 @section Zero-Length Extents
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8976 @cindex zero-length extents
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
8977 @cindex extents, zero-length
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8978
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8979 Extents can be zero-length, and will end up that way if their endpoints
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 442
diff changeset
8980 are explicitly set that way or if their detachable property is @code{nil}
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8981 and all the text in the extent is deleted. (The exception is open-open
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8982 zero-length extents, which are barred from existing because there is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8983 no sensible way to define their properties. Deletion of the text in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8984 an open-open extent causes it to be converted into a closed-open
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8985 extent.) Zero-length extents are primarily used to represent
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8986 annotations, and behave as follows:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8987
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8988 @enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8989 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8990 Insertion at the position of a zero-length extent expands the extent
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8991 if both endpoints are closed; goes after the extent if it is closed-open;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8992 and goes before the extent if it is open-closed.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8993
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8994 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8995 Deletion of a character on a side of a zero-length extent whose
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8996 corresponding endpoint is closed causes the extent to be detached if
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8997 it is detachable; if the extent is not detachable or the corresponding
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8998 endpoint is open, the extent remains in the buffer, moving as necessary.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8999 @end enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9000
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9001 Note that closed-open, non-detachable zero-length extents behave
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9002 exactly like markers and that open-closed, non-detachable zero-length
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9003 extents behave like the ``point-type'' marker in Mule.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9004
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
9005 @node Mathematics of Extent Ordering
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9006 @section Mathematics of Extent Ordering
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
9007 @cindex mathematics of extent ordering
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9008 @cindex extent mathematics
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9009 @cindex extent ordering
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9010
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9011 @cindex display order of extents
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9012 @cindex extents, display order
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9013 The extents in a buffer are ordered by ``display order'' because that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9014 is that order that the redisplay mechanism needs to process them in.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9015 The e-order is an auxiliary ordering used to facilitate operations
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9016 over extents. The operations that can be performed on the ordered
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9017 list of extents in a buffer are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9018
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9019 @enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9020 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9021 Locate where an extent would go if inserted into the list.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9022 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9023 Insert an extent into the list.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9024 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9025 Remove an extent from the list.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9026 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9027 Map over all the extents that overlap a range.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9028 @end enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9029
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9030 (4) requires being able to determine the first and last extents
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9031 that overlap a range.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9032
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9033 NOTE: @dfn{overlap} is used as follows:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9034
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9035 @itemize @bullet
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9036 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9037 two ranges overlap if they have at least one point in common.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9038 Whether the endpoints are open or closed makes a difference here.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9039 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9040 a point overlaps a range if the point is contained within the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9041 range; this is equivalent to treating a point @math{P} as the range
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9042 @math{[P, P]}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9043 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9044 In the case of an @emph{extent} overlapping a point or range, the extent
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9045 is normally treated as having closed endpoints. This applies
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9046 consistently in the discussion of stacks of extents and such below.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9047 Note that this definition of overlap is not necessarily consistent with
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9048 the extents that @code{map-extents} maps over, since @code{map-extents}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9049 sometimes pays attention to whether the endpoints of an extents are open
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9050 or closed. But for our purposes, it greatly simplifies things to treat
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9051 all extents as having closed endpoints.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9052 @end itemize
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9053
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9054 First, define @math{>}, @math{<}, @math{<=}, etc. as applied to extents
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9055 to mean comparison according to the display order. Comparison between
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9056 an extent @math{E} and an index @math{I} means comparison between
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9057 @math{E} and the range @math{[I, I]}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9058
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9059 Also define @math{e>}, @math{e<}, @math{e<=}, etc. to mean comparison
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9060 according to the e-order.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9061
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9062 For any range @math{R}, define @math{R(0)} to be the starting index of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9063 the range and @math{R(1)} to be the ending index of the range.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9064
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9065 For any extent @math{E}, define @math{E(next)} to be the extent directly
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9066 following @math{E}, and @math{E(prev)} to be the extent directly
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9067 preceding @math{E}. Assume @math{E(next)} and @math{E(prev)} can be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9068 determined from @math{E} in constant time. (This is because we store
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9069 the extent list as a doubly linked list.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9070
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9071 Similarly, define @math{E(e-next)} and @math{E(e-prev)} to be the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9072 extents directly following and preceding @math{E} in the e-order.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9073
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9074 Now:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9075
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9076 Let @math{R} be a range.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9077 Let @math{F} be the first extent overlapping @math{R}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9078 Let @math{L} be the last extent overlapping @math{R}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9079
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9080 Theorem 1: @math{R(1)} lies between @math{L} and @math{L(next)},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9081 i.e. @math{L <= R(1) < L(next)}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9082
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9083 This follows easily from the definition of display order. The
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9084 basic reason that this theorem applies is that the display order
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9085 sorts by increasing starting index.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9086
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9087 Therefore, we can determine @math{L} just by looking at where we would
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9088 insert @math{R(1)} into the list, and if we know @math{F} and are moving
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9089 forward over extents, we can easily determine when we've hit @math{L} by
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9090 comparing the extent we're at to @math{R(1)}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9091
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9092 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9093 Theorem 2: @math{F(e-prev) e< [1, R(0)] e<= F}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9094 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9095
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9096 This is the analog of Theorem 1, and applies because the e-order
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9097 sorts by increasing ending index.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9098
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9099 Therefore, @math{F} can be found in the same amount of time as
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9100 operation (1), i.e. the time that it takes to locate where an extent
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9101 would go if inserted into the e-order list.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9102
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9103 If the lists were stored as balanced binary trees, then operation (1)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9104 would take logarithmic time, which is usually quite fast. However,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9105 currently they're stored as simple doubly-linked lists, and instead we
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9106 do some caching to try to speed things up.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9107
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9108 Define a @dfn{stack of extents} (or @dfn{SOE}) as the set of extents
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9109 (ordered in the display order) that overlap an index @math{I}, together
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9110 with the SOE's @dfn{previous} extent, which is an extent that precedes
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9111 @math{I} in the e-order. (Hopefully there will not be very many extents
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9112 between @math{I} and the previous extent.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9113
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9114 Now:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9115
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9116 Let @math{I} be an index, let @math{S} be the stack of extents on
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9117 @math{I}, let @math{F} be the first extent in @math{S}, and let @math{P}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9118 be @math{S}'s previous extent.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9119
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9120 Theorem 3: The first extent in @math{S} is the first extent that overlaps
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9121 any range @math{[I, J]}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9122
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9123 Proof: Any extent that overlaps @math{[I, J]} but does not include
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9124 @math{I} must have a start index @math{> I}, and thus be greater than
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9125 any extent in @math{S}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9126
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9127 Therefore, finding the first extent that overlaps a range @math{R} is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9128 the same as finding the first extent that overlaps @math{R(0)}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9129
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9130 Theorem 4: Let @math{I2} be an index such that @math{I2 > I}, and let
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9131 @math{F2} be the first extent that overlaps @math{I2}. Then, either
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9132 @math{F2} is in @math{S} or @math{F2} is greater than any extent in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9133 @math{S}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9134
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9135 Proof: If @math{F2} does not include @math{I} then its start index is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9136 greater than @math{I} and thus it is greater than any extent in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9137 @math{S}, including @math{F}. Otherwise, @math{F2} includes @math{I}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9138 and thus is in @math{S}, and thus @math{F2 >= F}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9139
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
9140 @node Extent Fragments
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9141 @section Extent Fragments
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
9142 @cindex extent fragments
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
9143 @cindex fragments, extent
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9144
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9145 Imagine that the buffer is divided up into contiguous, non-overlapping
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9146 @dfn{runs} of text such that no extent starts or ends within a run
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9147 (extents that abut the run don't count).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9148
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9149 An extent fragment is a structure that holds data about the run that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9150 contains a particular buffer position (if the buffer position is at the
440
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 438
diff changeset
9151 junction of two runs, the run after the position is used)---the
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9152 beginning and end of the run, a list of all of the extents in that run,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9153 the @dfn{merged face} that results from merging all of the faces
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9154 corresponding to those extents, the begin and end glyphs at the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9155 beginning of the run, etc. This is the information that redisplay needs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9156 in order to display this run.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9157
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9158 Extent fragments have to be very quick to update to a new buffer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9159 position when moving linearly through the buffer. They rely on the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9160 stack-of-extents code, which does the heavy-duty algorithmic work of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9161 determining which extents overly a particular position.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9162
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9163 @node Faces, Glyphs, Extents, Top
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9164 @chapter Faces
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
9165 @cindex faces
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9166
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9167 Not yet documented.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9168
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9169 @node Glyphs, Specifiers, Faces, Top
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9170 @chapter Glyphs
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
9171 @cindex glyphs
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9172
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9173 Glyphs are graphical elements that can be displayed in XEmacs buffers or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9174 gutters. We use the term graphical element here in the broadest possible
446
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9175 sense since glyphs can be as mundane as text or as arcane as a native
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9176 tab widget.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9177
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9178 In XEmacs, glyphs represent the uninstantiated state of graphical
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9179 elements, i.e. they hold all the information necessary to produce an
446
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9180 image on-screen but the image need not exist at this stage, and multiple
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9181 screen images can be instantiated from a single glyph.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9182
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9183 Glyphs are lazily instantiated by calling one of the glyph
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9184 functions. This usually occurs within redisplay when
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9185 @code{Fglyph_height} is called. Instantiation causes an image-instance
454
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9186 to be created and cached. This cache is on a per-device basis for all glyphs
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9187 except widget-glyphs, and on a per-window basis for widgets-glyphs. The
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9188 caching is done by @code{image_instantiate} and is necessary because it
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9189 is generally possible to display an image-instance in multiple
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9190 domains. For instance if we create a Pixmap, we can actually display
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9191 this on multiple windows - even though we only need a single Pixmap
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9192 instance to do this. If caching wasn't done then it would be necessary
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
9193 to create image-instances for every displayable occurrence of a glyph -
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9194 and every usage - and this would be extremely memory and cpu intensive.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9195
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9196 Widget-glyphs (a.k.a native widgets) are not cached in this way. This is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9197 because widget-glyph image-instances on screen are toolkit windows, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9198 thus cannot be reused in multiple XEmacs domains. Thus widget-glyphs are
446
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9199 cached on an XEmacs window basis.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9200
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9201 Any action on a glyph first consults the cache before actually
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9202 instantiating a widget.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9203
454
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9204 @section Glyph Instantiation
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
9205 @cindex glyph instantiation
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
9206 @cindex instantiation, glyph
454
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9207
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9208 Glyph instantiation is a hairy topic and requires some explanation. The
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9209 guts of glyph instantiation is contained within
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9210 @code{image_instantiate}. A glyph contains an image which is a
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9211 specifier. When a glyph function - for instance @code{Fglyph_height} -
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9212 asks for a property of the glyph that can only be determined from its
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9213 instantiated state, then the glyph image is instantiated and an image
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9214 instance created. The instantiation process is governed by the specifier
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9215 code and goes through a series of steps:
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9216
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9217 @itemize @bullet
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9218 @item
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9219 Validation. Instantiation of image instances happens dynamically - often
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9220 within the guts of redisplay. Thus it is often not feasible to catch
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9221 instantiator errors at instantiation time. Instead the instantiator is
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9222 validated at the time it is added to the image specifier. This function
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9223 is defined by @code{image_validate} and at a simple level validates
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9224 keyword value pairs.
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9225 @item
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9226 Duplication. The specifier code by default takes a copy of the
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9227 instantiator. This is reasonable for most specifiers but in the case of
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9228 widget-glyphs can be problematic, since some of the properties in the
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9229 instantiator - for instance callbacks - could cause infinite recursion
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9230 in the copying process. Thus the image code defines a function -
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9231 @code{image_copy_instantiator} - which will selectively copy values.
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9232 This is controlled by the way that a keyword is defined either using
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9233 @code{IIFORMAT_VALID_KEYWORD} or
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9234 @code{IIFORMAT_VALID_NONCOPY_KEYWORD}. Note that the image caching and
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9235 redisplay code relies on instantiator copying to ensure that current and
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9236 new instantiators are actually different rather than referring to the
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9237 same thing.
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9238 @item
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9239 Normalization. Once the instantiator has been copied it must be
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9240 converted into a form that is viable at instantiation time. This can
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9241 involve no changes at all, but typically involves things like converting
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9242 file names to the actual data. This function is defined by
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9243 @code{image_going_to_add} and @code{normalize_image_instantiator}.
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9244 @item
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9245 Instantiation. When an image instance is actually required for display
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9246 it is instantiated using @code{image_instantiate}. This involves calling
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9247 instantiate methods that are specific to the type of image being
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9248 instantiated.
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9249 @end itemize
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9250
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9251 The final instantiation phase also involves a number of steps. In order
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9252 to understand these we need to describe a number of concepts.
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9253
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9254 An image is instantiated in a @dfn{domain}, where a domain can be any
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9255 one of a device, frame, window or image-instance. The domain gives the
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9256 image-instance context and identity and properties that affect the
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9257 appearance of the image-instance may be different for the same glyph
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9258 instantiated in different domains. An example is the face used to
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9259 display the image-instance.
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9260
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9261 Although an image is instantiated in a particular domain the
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9262 instantiation domain is not necessarily the domain in which the
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9263 image-instance is cached. For example a pixmap can be instantiated in a
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9264 window be actually be cached on a per-device basis. The domain in which
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9265 the image-instance is actually cached is called the
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9266 @dfn{governing-domain}. A governing-domain is currently either a device
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9267 or a window. Widget-glyphs and text-glyphs have a window as a
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9268 governing-domain, all other image-instances have a device as the
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9269 governing-domain. The governing domain for an image-instance is
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9270 determined using the governing_domain image-instance method.
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9271
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9272 @section Widget-Glyphs
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
9273 @cindex widget-glyphs
454
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9274
440
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 438
diff changeset
9275 @section Widget-Glyphs in the MS-Windows Environment
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
9276 @cindex widget-glyphs in the MS-Windows environment
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
9277 @cindex MS-Windows environment, widget-glyphs in the
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9278
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9279 To Do
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9280
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9281 @section Widget-Glyphs in the X Environment
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
9282 @cindex widget-glyphs in the X environment
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
9283 @cindex X environment, widget-glyphs in the
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9284
446
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9285 Widget-glyphs under X make heavy use of lwlib (@pxref{Lucid Widget
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9286 Library}) for manipulating the native toolkit objects. This is primarily
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9287 so that different toolkits can be supported for widget-glyphs, just as
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9288 they are supported for features such as menubars etc.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9289
454
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9290 Lwlib is extremely poorly documented and quite hairy so here is my
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9291 understanding of what goes on.
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9292
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9293 Lwlib maintains a set of widget_instances which mirror the hierarchical
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9294 state of Xt widgets. I think this is so that widgets can be updated and
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9295 manipulated generically by the lwlib library. For instance
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9296 update_one_widget_instance can cope with multiple types of widget and
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9297 multiple types of toolkit. Each element in the widget hierarchy is updated
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9298 from its corresponding widget_instance by walking the widget_instance
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9299 tree recursively.
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9300
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9301 This has desirable properties such as lw_modify_all_widgets which is
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9302 called from @file{glyphs-x.c} and updates all the properties of a widget
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9303 without having to know what the widget is or what toolkit it is from.
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9304 Unfortunately this also has hairy properties such as making the lwlib
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9305 code quite complex. And of course lwlib has to know at some level what
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9306 the widget is and how to set its properties.
d7a9135ec789 Import from CVS: tag r21-2-42
cvs
parents: 452
diff changeset
9307
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9308 @node Specifiers, Menus, Glyphs, Top
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9309 @chapter Specifiers
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
9310 @cindex specifiers
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9311
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9312 Not yet documented.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9313
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9314 @node Menus, Subprocesses, Specifiers, Top
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9315 @chapter Menus
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
9316 @cindex menus
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9317
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9318 A menu is set by setting the value of the variable
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9319 @code{current-menubar} (which may be buffer-local) and then calling
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9320 @code{set-menubar-dirty-flag} to signal a change. This will cause the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9321 menu to be redrawn at the next redisplay. The format of the data in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9322 @code{current-menubar} is described in @file{menubar.c}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9323
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9324 Internally the data in current-menubar is parsed into a tree of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9325 @code{widget_value's} (defined in @file{lwlib.h}); this is accomplished
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9326 by the recursive function @code{menu_item_descriptor_to_widget_value()},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9327 called by @code{compute_menubar_data()}. Such a tree is deallocated
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9328 using @code{free_widget_value()}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9329
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9330 @code{update_screen_menubars()} is one of the external entry points.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9331 This checks to see, for each screen, if that screen's menubar needs to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9332 be updated. This is the case if
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9333
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9334 @enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9335 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9336 @code{set-menubar-dirty-flag} was called since the last redisplay. (This
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9337 function sets the C variable menubar_has_changed.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9338 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9339 The buffer displayed in the screen has changed.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9340 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9341 The screen has no menubar currently displayed.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9342 @end enumerate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9343
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9344 @code{set_screen_menubar()} is called for each such screen. This
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9345 function calls @code{compute_menubar_data()} to create the tree of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9346 widget_value's, then calls @code{lw_create_widget()},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9347 @code{lw_modify_all_widgets()}, and/or @code{lw_destroy_all_widgets()}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9348 to create the X-Toolkit widget associated with the menu.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9349
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9350 @code{update_psheets()}, the other external entry point, actually
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9351 changes the menus being displayed. It uses the widgets fixed by
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9352 @code{update_screen_menubars()} and calls various X functions to ensure
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9353 that the menus are displayed properly.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9354
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9355 The menubar widget is set up so that @code{pre_activate_callback()} is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9356 called when the menu is first selected (i.e. mouse button goes down),
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9357 and @code{menubar_selection_callback()} is called when an item is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9358 selected. @code{pre_activate_callback()} calls the function in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9359 activate-menubar-hook, which can change the menubar (this is described
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9360 in @file{menubar.c}). If the menubar is changed,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9361 @code{set_screen_menubars()} is called.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9362 @code{menubar_selection_callback()} enqueues a menu event, putting in it
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9363 a function to call (either @code{eval} or @code{call-interactively}) and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9364 its argument, which is the callback function or form given in the menu's
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9365 description.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9366
446
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9367 @node Subprocesses, Interface to the X Window System, Menus, Top
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9368 @chapter Subprocesses
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
9369 @cindex subprocesses
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9370
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9371 The fields of a process are:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9372
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9373 @table @code
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9374 @item name
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9375 A string, the name of the process.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9376
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9377 @item command
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9378 A list containing the command arguments that were used to start this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9379 process.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9380
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9381 @item filter
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9382 A function used to accept output from the process instead of a buffer,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9383 or @code{nil}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9384
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9385 @item sentinel
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9386 A function called whenever the process receives a signal, or @code{nil}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9387
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9388 @item buffer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9389 The associated buffer of the process.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9390
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9391 @item pid
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9392 An integer, the Unix process @sc{id}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9393
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9394 @item childp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9395 A flag, non-@code{nil} if this is really a child process.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9396 It is @code{nil} for a network connection.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9397
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9398 @item mark
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9399 A marker indicating the position of the end of the last output from this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9400 process inserted into the buffer. This is often but not always the end
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9401 of the buffer.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9402
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9403 @item kill_without_query
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9404 If this is non-@code{nil}, killing XEmacs while this process is still
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9405 running does not ask for confirmation about killing the process.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9406
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9407 @item raw_status_low
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9408 @itemx raw_status_high
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9409 These two fields record 16 bits each of the process status returned by
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9410 the @code{wait} system call.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9411
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9412 @item status
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9413 The process status, as @code{process-status} should return it.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9414
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9415 @item tick
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9416 @itemx update_tick
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9417 If these two fields are not equal, a change in the status of the process
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9418 needs to be reported, either by running the sentinel or by inserting a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9419 message in the process buffer.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9420
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9421 @item pty_flag
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9422 Non-@code{nil} if communication with the subprocess uses a @sc{pty};
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9423 @code{nil} if it uses a pipe.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9424
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9425 @item infd
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9426 The file descriptor for input from the process.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9427
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9428 @item outfd
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9429 The file descriptor for output to the process.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9430
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9431 @item subtty
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9432 The file descriptor for the terminal that the subprocess is using. (On
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9433 some systems, there is no need to record this, so the value is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9434 @code{-1}.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9435
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9436 @item tty_name
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9437 The name of the terminal that the subprocess is using,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9438 or @code{nil} if it is using pipes.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9439 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9440
446
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9441 @node Interface to the X Window System, Index, Subprocesses, Top
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9442 @chapter Interface to the X Window System
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
9443 @cindex X Window System, interface to the
446
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9444
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9445 Mostly undocumented.
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9446
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9447 @menu
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9448 * Lucid Widget Library:: An interface to various widget sets.
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9449 @end menu
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9450
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
9451 @node Lucid Widget Library
446
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9452 @section Lucid Widget Library
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
9453 @cindex Lucid Widget Library
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
9454 @cindex widget library, Lucid
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
9455 @cindex library, Lucid Widget
446
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9456
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9457 Lwlib is extremely poorly documented and quite hairy. The author(s)
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9458 blame that on X, Xt, and Motif, with some justice, but also sufficient
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9459 hypocrisy to avoid drawing the obvious conclusion about their own work.
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9460
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9461 The Lucid Widget Library is composed of two more or less independent
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9462 pieces. The first, as the name suggests, is a set of widgets. These
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9463 widgets are intended to resemble and improve on widgets provided in the
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9464 Motif toolkit but not in the Athena widgets, including menubars and
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9465 scrollbars. Recent additions by Andy Piper integrate some ``modern''
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9466 widgets by Edward Falk, including checkboxes, radio buttons, progress
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9467 gauges, and index tab controls (aka notebooks).
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9468
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9469 The second piece of the Lucid widget library is a generic interface to
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9470 several toolkits for X (including Xt, the Athena widget set, and Motif,
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9471 as well as the Lucid widgets themselves) so that core XEmacs code need
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9472 not know which widget set has been used to build the graphical user
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9473 interface.
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9474
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9475 @menu
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9476 * Generic Widget Interface:: The lwlib generic widget interface.
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9477 * Scrollbars::
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9478 * Menubars::
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9479 * Checkboxes and Radio Buttons::
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9480 * Progress Bars::
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9481 * Tab Controls::
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9482 @end menu
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9483
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
9484 @node Generic Widget Interface
446
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9485 @subsection Generic Widget Interface
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
9486 @cindex widget interface, generic
446
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9487
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9488 In general in any toolkit a widget may be a composite object. In Xt,
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9489 all widgets have an X window that they manage, but typically a complex
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9490 widget will have widget children, each of which manages a subwindow of
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9491 the parent widget's X window. These children may themselves be
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9492 composite widgets. Thus a widget is actually a tree or hierarchy of
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9493 widgets.
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9494
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9495 For each toolkit widget, lwlib maintains a tree of @code{widget_values}
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9496 which mirror the hierarchical state of Xt widgets (including Motif,
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9497 Athena, 3D Athena, and Falk's widget sets). Each @code{widget_value}
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9498 has @code{contents} member, which points to the head of a linked list of
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9499 its children. The linked list of siblings is chained through the
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9500 @code{next} member of @code{widget_value}.
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9501
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9502 @example
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9503 +-----------+
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9504 | composite |
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9505 +-----------+
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9506 |
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9507 | contents
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9508 V
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9509 +-------+ next +-------+ next +-------+
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9510 | child |----->| child |----->| child |
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9511 +-------+ +-------+ +-------+
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9512 |
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9513 | contents
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9514 V
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9515 +-------------+ next +-------------+
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9516 | grand child |----->| grand child |
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9517 +-------------+ +-------------+
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9518
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9519 The @code{widget_value} hierarchy of a composite widget with two simple
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9520 children and one composite child.
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9521 @end example
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9522
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9523 The @code{widget_instance} structure maintains the inverse view of the
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9524 tree. As for the @code{widget_value}, siblings are chained through the
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9525 @code{next} member. However, rather than naming children, the
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9526 @code{widget_instance} tree links to parents.
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9527
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9528 @example
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9529 +-----------+
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9530 | composite |
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9531 +-----------+
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9532 A
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9533 | parent
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9534 |
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9535 +-------+ next +-------+ next +-------+
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9536 | child |----->| child |----->| child |
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9537 +-------+ +-------+ +-------+
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9538 A
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9539 | parent
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9540 |
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9541 +-------------+ next +-------------+
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9542 | grand child |----->| grand child |
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9543 +-------------+ +-------------+
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9544
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9545 The @code{widget_value} hierarchy of a composite widget with two simple
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9546 children and one composite child.
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9547 @end example
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9548
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9549 This permits widgets derived from different toolkits to be updated and
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9550 manipulated generically by the lwlib library. For instance
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9551 @code{update_one_widget_instance} can cope with multiple types of widget
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9552 and multiple types of toolkit. Each element in the widget hierarchy is
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9553 updated from its corresponding @code{widget_value} by walking the
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9554 @code{widget_value} tree. This has desirable properties. For example,
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9555 @code{lw_modify_all_widgets} is called from @file{glyphs-x.c} and
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9556 updates all the properties of a widget without having to know what the
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9557 widget is or what toolkit it is from. Unfortunately this also has its
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9558 hairy properties; the lwlib code quite complex. And of course lwlib has
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9559 to know at some level what the widget is and how to set its properties.
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9560
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9561 The @code{widget_instance} structure also contains a pointer to the root
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9562 of its tree. Widget instances are further confi
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9563
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9564
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
9565 @node Scrollbars
446
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9566 @subsection Scrollbars
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
9567 @cindex scrollbars
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
9568
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
9569 @node Menubars
446
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9570 @subsection Menubars
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
9571 @cindex menubars
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
9572
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
9573 @node Checkboxes and Radio Buttons
446
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9574 @subsection Checkboxes and Radio Buttons
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
9575 @cindex checkboxes and radio buttons
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
9576 @cindex radio buttons, checkboxes and
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
9577 @cindex buttons, checkboxes and radio
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
9578
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
9579 @node Progress Bars
446
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9580 @subsection Progress Bars
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
9581 @cindex progress bars
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
9582 @cindex bars, progress
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
9583
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
9584 @node Tab Controls
446
1ccc32a20af4 Import from CVS: tag r21-2-38
cvs
parents: 444
diff changeset
9585 @subsection Tab Controls
462
0784d089fdc9 Import from CVS: tag r21-2-46
cvs
parents: 454
diff changeset
9586 @cindex tab controls
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9587
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9588 @include index.texi
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9589
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9590 @c Print the tables of contents
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9591 @summarycontents
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9592 @contents
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9593 @c That's all
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9594
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9595 @bye