Mercurial > emacs
annotate lispref/symbols.texi @ 38588:08a4c6c00af0
(init_from_display_pos): If POS is in an overlay string,
deal with the first overlay string having an image `display'
property.
(try_window_reusing_current_matrix, compute_line_metrics): Fix
computation of row's visible height for the case that part of the
row is invisible above and part of the row is at the same time
invisible below the window.
author | Gerd Moellmann <gerd@gnu.org> |
---|---|
date | Fri, 27 Jul 2001 15:29:16 +0000 |
parents | 4d3831f2899f |
children | 7a42abfb0c82 |
rev | line source |
---|---|
6411 | 1 @c -*-texinfo-*- |
2 @c This is part of the GNU Emacs Lisp Reference Manual. | |
27189 | 3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999 |
4 @c Free Software Foundation, Inc. | |
6411 | 5 @c See the file elisp.texi for copying conditions. |
6 @setfilename ../info/symbols | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23727
diff
changeset
|
7 @node Symbols, Evaluation, Hash Tables, Top |
6411 | 8 @chapter Symbols |
9 @cindex symbol | |
10 | |
11 A @dfn{symbol} is an object with a unique name. This chapter | |
12 describes symbols, their components, their property lists, and how they | |
13 are created and interned. Separate chapters describe the use of symbols | |
14 as variables and as function names; see @ref{Variables}, and | |
15 @ref{Functions}. For the precise read syntax for symbols, see | |
16 @ref{Symbol Type}. | |
17 | |
18 You can test whether an arbitrary Lisp object is a symbol | |
19 with @code{symbolp}: | |
20 | |
21 @defun symbolp object | |
22 This function returns @code{t} if @var{object} is a symbol, @code{nil} | |
23 otherwise. | |
24 @end defun | |
25 | |
26 @menu | |
27 * Symbol Components:: Symbols have names, values, function definitions | |
28 and property lists. | |
29 * Definitions:: A definition says how a symbol will be used. | |
30 * Creating Symbols:: How symbols are kept unique. | |
31 * Property Lists:: Each symbol has a property list | |
32 for recording miscellaneous information. | |
33 @end menu | |
34 | |
35 @node Symbol Components, Definitions, Symbols, Symbols | |
36 @section Symbol Components | |
37 @cindex symbol components | |
38 | |
39 Each symbol has four components (or ``cells''), each of which | |
40 references another object: | |
41 | |
42 @table @asis | |
43 @item Print name | |
44 @cindex print name cell | |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6411
diff
changeset
|
45 The @dfn{print name cell} holds a string that names the symbol for |
6411 | 46 reading and printing. See @code{symbol-name} in @ref{Creating Symbols}. |
47 | |
48 @item Value | |
49 @cindex value cell | |
50 The @dfn{value cell} holds the current value of the symbol as a | |
51 variable. When a symbol is used as a form, the value of the form is the | |
52 contents of the symbol's value cell. See @code{symbol-value} in | |
53 @ref{Accessing Variables}. | |
54 | |
55 @item Function | |
56 @cindex function cell | |
57 The @dfn{function cell} holds the function definition of the symbol. | |
58 When a symbol is used as a function, its function definition is used in | |
59 its place. This cell is also used to make a symbol stand for a keymap | |
60 or a keyboard macro, for editor command execution. Because each symbol | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23727
diff
changeset
|
61 has separate value and function cells, variables names and function names do |
6411 | 62 not conflict. See @code{symbol-function} in @ref{Function Cells}. |
63 | |
64 @item Property list | |
65 @cindex property list cell | |
66 The @dfn{property list cell} holds the property list of the symbol. See | |
67 @code{symbol-plist} in @ref{Property Lists}. | |
68 @end table | |
69 | |
70 The print name cell always holds a string, and cannot be changed. The | |
71 other three cells can be set individually to any specified Lisp object. | |
72 | |
73 The print name cell holds the string that is the name of the symbol. | |
74 Since symbols are represented textually by their names, it is important | |
75 not to have two symbols with the same name. The Lisp reader ensures | |
76 this: every time it reads a symbol, it looks for an existing symbol with | |
77 the specified name before it creates a new one. (In GNU Emacs Lisp, | |
78 this lookup uses a hashing algorithm and an obarray; see @ref{Creating | |
79 Symbols}.) | |
80 | |
27093
4b1a67a46d8c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25751
diff
changeset
|
81 The value cell holds the symbol's value as a variable |
4b1a67a46d8c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25751
diff
changeset
|
82 (@pxref{Variables}). That is what you get if you evaluate the symbol as |
4b1a67a46d8c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25751
diff
changeset
|
83 a Lisp expression (@pxref{Evaluation}). Any Lisp object is a legitimate |
4b1a67a46d8c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25751
diff
changeset
|
84 value. Certain symbols have values that cannot be changed; these |
4b1a67a46d8c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25751
diff
changeset
|
85 include @code{nil} and @code{t}, and any symbol whose name starts with |
4b1a67a46d8c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25751
diff
changeset
|
86 @samp{:} (those are called @dfn{keywords}). @xref{Constant Variables}. |
4b1a67a46d8c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25751
diff
changeset
|
87 |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
88 In normal usage, the function cell usually contains a function |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
89 (@pxref{Functions}) or a macro (@pxref{Macros}), as that is what the |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
90 Lisp interpreter expects to see there (@pxref{Evaluation}). Keyboard |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
91 macros (@pxref{Keyboard Macros}), keymaps (@pxref{Keymaps}) and autoload |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
92 objects (@pxref{Autoloading}) are also sometimes stored in the function |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
93 cells of symbols. We often refer to ``the function @code{foo}'' when we |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
94 really mean the function stored in the function cell of the symbol |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
95 @code{foo}. We make the distinction only when necessary. |
6411 | 96 |
97 The property list cell normally should hold a correctly formatted | |
98 property list (@pxref{Property Lists}), as a number of functions expect | |
99 to see a property list there. | |
100 | |
101 The function cell or the value cell may be @dfn{void}, which means | |
102 that the cell does not reference any object. (This is not the same | |
103 thing as holding the symbol @code{void}, nor the same as holding the | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
104 symbol @code{nil}.) Examining a function or value cell that is void |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
105 results in an error, such as @samp{Symbol's value as variable is void}. |
6411 | 106 |
107 The four functions @code{symbol-name}, @code{symbol-value}, | |
108 @code{symbol-plist}, and @code{symbol-function} return the contents of | |
109 the four cells of a symbol. Here as an example we show the contents of | |
110 the four cells of the symbol @code{buffer-file-name}: | |
111 | |
112 @example | |
113 (symbol-name 'buffer-file-name) | |
114 @result{} "buffer-file-name" | |
115 (symbol-value 'buffer-file-name) | |
116 @result{} "/gnu/elisp/symbols.texi" | |
117 (symbol-plist 'buffer-file-name) | |
118 @result{} (variable-documentation 29529) | |
119 (symbol-function 'buffer-file-name) | |
120 @result{} #<subr buffer-file-name> | |
121 @end example | |
122 | |
123 @noindent | |
124 Because this symbol is the variable which holds the name of the file | |
125 being visited in the current buffer, the value cell contents we see are | |
126 the name of the source file of this chapter of the Emacs Lisp Manual. | |
127 The property list cell contains the list @code{(variable-documentation | |
128 29529)} which tells the documentation functions where to find the | |
129 documentation string for the variable @code{buffer-file-name} in the | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
130 @file{DOC-@var{version}} file. (29529 is the offset from the beginning |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
131 of the @file{DOC-@var{version}} file to where that documentation string |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
132 begins---see @ref{Documentation Basics}.) The function cell contains |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
133 the function for returning the name of the file. |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
134 @code{buffer-file-name} names a primitive function, which has no read |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
135 syntax and prints in hash notation (@pxref{Primitive Function Type}). A |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
136 symbol naming a function written in Lisp would have a lambda expression |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
137 (or a byte-code object) in this cell. |
6411 | 138 |
139 @node Definitions, Creating Symbols, Symbol Components, Symbols | |
140 @section Defining Symbols | |
141 @cindex definition of a symbol | |
142 | |
143 A @dfn{definition} in Lisp is a special form that announces your | |
144 intention to use a certain symbol in a particular way. In Emacs Lisp, | |
145 you can define a symbol as a variable, or define it as a function (or | |
146 macro), or both independently. | |
147 | |
148 A definition construct typically specifies a value or meaning for the | |
149 symbol for one kind of use, plus documentation for its meaning when used | |
150 in this way. Thus, when you define a symbol as a variable, you can | |
151 supply an initial value for the variable, plus documentation for the | |
152 variable. | |
153 | |
154 @code{defvar} and @code{defconst} are special forms that define a | |
155 symbol as a global variable. They are documented in detail in | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
156 @ref{Defining Variables}. For defining user option variables that can |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
157 be customized, use @code{defcustom} (@pxref{Customization}). |
6411 | 158 |
159 @code{defun} defines a symbol as a function, creating a lambda | |
160 expression and storing it in the function cell of the symbol. This | |
161 lambda expression thus becomes the function definition of the symbol. | |
162 (The term ``function definition'', meaning the contents of the function | |
163 cell, is derived from the idea that @code{defun} gives the symbol its | |
12098 | 164 definition as a function.) @code{defsubst} and @code{defalias} are two |
165 other ways of defining a function. @xref{Functions}. | |
6411 | 166 |
167 @code{defmacro} defines a symbol as a macro. It creates a macro | |
168 object and stores it in the function cell of the symbol. Note that a | |
169 given symbol can be a macro or a function, but not both at once, because | |
170 both macro and function definitions are kept in the function cell, and | |
171 that cell can hold only one Lisp object at any given time. | |
172 @xref{Macros}. | |
173 | |
12098 | 174 In Emacs Lisp, a definition is not required in order to use a symbol |
175 as a variable or function. Thus, you can make a symbol a global | |
6411 | 176 variable with @code{setq}, whether you define it first or not. The real |
177 purpose of definitions is to guide programmers and programming tools. | |
178 They inform programmers who read the code that certain symbols are | |
179 @emph{intended} to be used as variables, or as functions. In addition, | |
180 utilities such as @file{etags} and @file{make-docfile} recognize | |
181 definitions, and add appropriate information to tag tables and the | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
182 @file{DOC-@var{version}} file. @xref{Accessing Documentation}. |
6411 | 183 |
184 @node Creating Symbols, Property Lists, Definitions, Symbols | |
185 @section Creating and Interning Symbols | |
186 @cindex reading symbols | |
187 | |
188 To understand how symbols are created in GNU Emacs Lisp, you must know | |
189 how Lisp reads them. Lisp must ensure that it finds the same symbol | |
190 every time it reads the same set of characters. Failure to do so would | |
191 cause complete confusion. | |
192 | |
193 @cindex symbol name hashing | |
194 @cindex hashing | |
195 @cindex obarray | |
196 @cindex bucket (in obarray) | |
197 When the Lisp reader encounters a symbol, it reads all the characters | |
198 of the name. Then it ``hashes'' those characters to find an index in a | |
199 table called an @dfn{obarray}. Hashing is an efficient method of | |
200 looking something up. For example, instead of searching a telephone | |
201 book cover to cover when looking up Jan Jones, you start with the J's | |
202 and go from there. That is a simple version of hashing. Each element | |
203 of the obarray is a @dfn{bucket} which holds all the symbols with a | |
204 given hash code; to look for a given name, it is sufficient to look | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23727
diff
changeset
|
205 through all the symbols in the bucket for that name's hash code. (The |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23727
diff
changeset
|
206 same idea is used for general Emacs hash tables, but they are a |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23727
diff
changeset
|
207 different data type; see @ref{Hash Tables}.) |
6411 | 208 |
209 @cindex interning | |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6411
diff
changeset
|
210 If a symbol with the desired name is found, the reader uses that |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6411
diff
changeset
|
211 symbol. If the obarray does not contain a symbol with that name, the |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6411
diff
changeset
|
212 reader makes a new symbol and adds it to the obarray. Finding or adding |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6411
diff
changeset
|
213 a symbol with a certain name is called @dfn{interning} it, and the |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6411
diff
changeset
|
214 symbol is then called an @dfn{interned symbol}. |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6411
diff
changeset
|
215 |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6411
diff
changeset
|
216 Interning ensures that each obarray has just one symbol with any |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6411
diff
changeset
|
217 particular name. Other like-named symbols may exist, but not in the |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6411
diff
changeset
|
218 same obarray. Thus, the reader gets the same symbols for the same |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6411
diff
changeset
|
219 names, as long as you keep reading with the same obarray. |
6411 | 220 |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23727
diff
changeset
|
221 Interning usually happens automatically in the reader, but sometimes |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23727
diff
changeset
|
222 other programs need to do it. For example, after the @kbd{M-x} command |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23727
diff
changeset
|
223 obtains the command name as a string using the minibuffer, it then |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23727
diff
changeset
|
224 interns the string, to get the interned symbol with that name. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23727
diff
changeset
|
225 |
6411 | 226 @cindex symbol equality |
227 @cindex uninterned symbol | |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6411
diff
changeset
|
228 No obarray contains all symbols; in fact, some symbols are not in any |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6411
diff
changeset
|
229 obarray. They are called @dfn{uninterned symbols}. An uninterned |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6411
diff
changeset
|
230 symbol has the same four cells as other symbols; however, the only way |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6411
diff
changeset
|
231 to gain access to it is by finding it in some other object or as the |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6411
diff
changeset
|
232 value of a variable. |
6411 | 233 |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23727
diff
changeset
|
234 Creating an uninterned symbol is useful in generating Lisp code, |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23727
diff
changeset
|
235 because an uninterned symbol used as a variable in the code you generate |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23727
diff
changeset
|
236 cannot clash with any variables used in other Lisp programs. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23727
diff
changeset
|
237 |
6411 | 238 In Emacs Lisp, an obarray is actually a vector. Each element of the |
239 vector is a bucket; its value is either an interned symbol whose name | |
240 hashes to that bucket, or 0 if the bucket is empty. Each interned | |
241 symbol has an internal link (invisible to the user) to the next symbol | |
242 in the bucket. Because these links are invisible, there is no way to | |
243 find all the symbols in an obarray except using @code{mapatoms} (below). | |
244 The order of symbols in a bucket is not significant. | |
245 | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23727
diff
changeset
|
246 In an empty obarray, every element is 0, so you can create an obarray |
6411 | 247 with @code{(make-vector @var{length} 0)}. @strong{This is the only |
248 valid way to create an obarray.} Prime numbers as lengths tend | |
249 to result in good hashing; lengths one less than a power of two are also | |
250 good. | |
251 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
252 @strong{Do not try to put symbols in an obarray yourself.} This does |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
253 not work---only @code{intern} can enter a symbol in an obarray properly. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
254 |
6411 | 255 @cindex CL note---symbol in obarrays |
256 @quotation | |
7734 | 257 @b{Common Lisp note:} In Common Lisp, a single symbol may be interned in |
6411 | 258 several obarrays. |
259 @end quotation | |
260 | |
261 Most of the functions below take a name and sometimes an obarray as | |
262 arguments. A @code{wrong-type-argument} error is signaled if the name | |
263 is not a string, or if the obarray is not a vector. | |
264 | |
265 @defun symbol-name symbol | |
266 This function returns the string that is @var{symbol}'s name. For example: | |
267 | |
268 @example | |
269 @group | |
270 (symbol-name 'foo) | |
271 @result{} "foo" | |
272 @end group | |
273 @end example | |
274 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
275 @strong{Warning:} Changing the string by substituting characters does |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
276 change the name of the symbol, but fails to update the obarray, so don't |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
277 do it! |
6411 | 278 @end defun |
279 | |
280 @defun make-symbol name | |
281 This function returns a newly-allocated, uninterned symbol whose name is | |
282 @var{name} (which must be a string). Its value and function definition | |
283 are void, and its property list is @code{nil}. In the example below, | |
284 the value of @code{sym} is not @code{eq} to @code{foo} because it is a | |
285 distinct uninterned symbol whose name is also @samp{foo}. | |
286 | |
287 @example | |
288 (setq sym (make-symbol "foo")) | |
289 @result{} foo | |
290 (eq sym 'foo) | |
291 @result{} nil | |
292 @end example | |
293 @end defun | |
294 | |
295 @defun intern name &optional obarray | |
296 This function returns the interned symbol whose name is @var{name}. If | |
297 there is no such symbol in the obarray @var{obarray}, @code{intern} | |
298 creates a new one, adds it to the obarray, and returns it. If | |
299 @var{obarray} is omitted, the value of the global variable | |
300 @code{obarray} is used. | |
301 | |
302 @example | |
303 (setq sym (intern "foo")) | |
304 @result{} foo | |
305 (eq sym 'foo) | |
306 @result{} t | |
307 | |
308 (setq sym1 (intern "foo" other-obarray)) | |
309 @result{} foo | |
23727 | 310 (eq sym1 'foo) |
6411 | 311 @result{} nil |
312 @end example | |
313 @end defun | |
314 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
315 @cindex CL note---interning existing symbol |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
316 @quotation |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
317 @b{Common Lisp note:} In Common Lisp, you can intern an existing symbol |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
318 in an obarray. In Emacs Lisp, you cannot do this, because the argument |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
319 to @code{intern} must be a string, not a symbol. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
320 @end quotation |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
321 |
6411 | 322 @defun intern-soft name &optional obarray |
323 This function returns the symbol in @var{obarray} whose name is | |
324 @var{name}, or @code{nil} if @var{obarray} has no symbol with that name. | |
325 Therefore, you can use @code{intern-soft} to test whether a symbol with | |
326 a given name is already interned. If @var{obarray} is omitted, the | |
327 value of the global variable @code{obarray} is used. | |
328 | |
27385
f7b7fdb0f3f4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27189
diff
changeset
|
329 The argument @var{name} may also be a symbol; in that case, |
f7b7fdb0f3f4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27189
diff
changeset
|
330 the function returns @var{name} if @var{name} is interned |
f7b7fdb0f3f4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27189
diff
changeset
|
331 in the specified obarray, and otherwise @code{nil}. |
f7b7fdb0f3f4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27189
diff
changeset
|
332 |
6411 | 333 @smallexample |
334 (intern-soft "frazzle") ; @r{No such symbol exists.} | |
335 @result{} nil | |
336 (make-symbol "frazzle") ; @r{Create an uninterned one.} | |
337 @result{} frazzle | |
12282
586e3ea81792
updates for version 19.29 made by melissa; also needed to check out files
Melissa Weisshaus <melissa@gnu.org>
parents:
12128
diff
changeset
|
338 @group |
6411 | 339 (intern-soft "frazzle") ; @r{That one cannot be found.} |
340 @result{} nil | |
12282
586e3ea81792
updates for version 19.29 made by melissa; also needed to check out files
Melissa Weisshaus <melissa@gnu.org>
parents:
12128
diff
changeset
|
341 @end group |
586e3ea81792
updates for version 19.29 made by melissa; also needed to check out files
Melissa Weisshaus <melissa@gnu.org>
parents:
12128
diff
changeset
|
342 @group |
6411 | 343 (setq sym (intern "frazzle")) ; @r{Create an interned one.} |
344 @result{} frazzle | |
12282
586e3ea81792
updates for version 19.29 made by melissa; also needed to check out files
Melissa Weisshaus <melissa@gnu.org>
parents:
12128
diff
changeset
|
345 @end group |
586e3ea81792
updates for version 19.29 made by melissa; also needed to check out files
Melissa Weisshaus <melissa@gnu.org>
parents:
12128
diff
changeset
|
346 @group |
6411 | 347 (intern-soft "frazzle") ; @r{That one can be found!} |
348 @result{} frazzle | |
12282
586e3ea81792
updates for version 19.29 made by melissa; also needed to check out files
Melissa Weisshaus <melissa@gnu.org>
parents:
12128
diff
changeset
|
349 @end group |
6411 | 350 @group |
351 (eq sym 'frazzle) ; @r{And it is the same one.} | |
352 @result{} t | |
353 @end group | |
354 @end smallexample | |
355 @end defun | |
356 | |
357 @defvar obarray | |
358 This variable is the standard obarray for use by @code{intern} and | |
359 @code{read}. | |
360 @end defvar | |
361 | |
362 @defun mapatoms function &optional obarray | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
363 This function calls @var{function} once with each symbol in the obarray |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
364 @var{obarray}. Then it returns @code{nil}. If @var{obarray} is |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
365 omitted, it defaults to the value of @code{obarray}, the standard |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
366 obarray for ordinary symbols. |
6411 | 367 |
368 @smallexample | |
369 (setq count 0) | |
370 @result{} 0 | |
371 (defun count-syms (s) | |
372 (setq count (1+ count))) | |
373 @result{} count-syms | |
374 (mapatoms 'count-syms) | |
375 @result{} nil | |
376 count | |
377 @result{} 1871 | |
378 @end smallexample | |
379 | |
380 See @code{documentation} in @ref{Accessing Documentation}, for another | |
381 example using @code{mapatoms}. | |
382 @end defun | |
383 | |
12067 | 384 @defun unintern symbol &optional obarray |
385 This function deletes @var{symbol} from the obarray @var{obarray}. If | |
386 @code{symbol} is not actually in the obarray, @code{unintern} does | |
387 nothing. If @var{obarray} is @code{nil}, the current obarray is used. | |
388 | |
389 If you provide a string instead of a symbol as @var{symbol}, it stands | |
390 for a symbol name. Then @code{unintern} deletes the symbol (if any) in | |
391 the obarray which has that name. If there is no such symbol, | |
392 @code{unintern} does nothing. | |
393 | |
394 If @code{unintern} does delete a symbol, it returns @code{t}. Otherwise | |
395 it returns @code{nil}. | |
396 @end defun | |
397 | |
6411 | 398 @node Property Lists,, Creating Symbols, Symbols |
399 @section Property Lists | |
400 @cindex property list | |
401 @cindex plist | |
402 | |
403 A @dfn{property list} (@dfn{plist} for short) is a list of paired | |
404 elements stored in the property list cell of a symbol. Each of the | |
405 pairs associates a property name (usually a symbol) with a property or | |
406 value. Property lists are generally used to record information about a | |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6411
diff
changeset
|
407 symbol, such as its documentation as a variable, the name of the file |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6411
diff
changeset
|
408 where it was defined, or perhaps even the grammatical class of the |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6411
diff
changeset
|
409 symbol (representing a word) in a language-understanding system. |
6411 | 410 |
411 Character positions in a string or buffer can also have property lists. | |
412 @xref{Text Properties}. | |
413 | |
414 The property names and values in a property list can be any Lisp | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
415 objects, but the names are usually symbols. Property list functions |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
416 compare the property names using @code{eq}. Here is an example of a |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
417 property list, found on the symbol @code{progn} when the compiler is |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
418 loaded: |
6411 | 419 |
420 @example | |
421 (lisp-indent-function 0 byte-compile byte-compile-progn) | |
422 @end example | |
423 | |
424 @noindent | |
425 Here @code{lisp-indent-function} and @code{byte-compile} are property | |
426 names, and the other two elements are the corresponding values. | |
427 | |
12067 | 428 @menu |
429 * Plists and Alists:: Comparison of the advantages of property | |
430 lists and association lists. | |
431 * Symbol Plists:: Functions to access symbols' property lists. | |
432 * Other Plists:: Accessing property lists stored elsewhere. | |
433 @end menu | |
434 | |
435 @node Plists and Alists | |
436 @subsection Property Lists and Association Lists | |
437 | |
6411 | 438 @cindex property lists vs association lists |
439 Association lists (@pxref{Association Lists}) are very similar to | |
440 property lists. In contrast to association lists, the order of the | |
441 pairs in the property list is not significant since the property names | |
442 must be distinct. | |
443 | |
444 Property lists are better than association lists for attaching | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
445 information to various Lisp function names or variables. If your |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
446 program keeps all of its associations in one association list, it will |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
447 typically need to search that entire list each time it checks for an |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
448 association. This could be slow. By contrast, if you keep the same |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
449 information in the property lists of the function names or variables |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
450 themselves, each search will scan only the length of one property list, |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
451 which is usually short. This is why the documentation for a variable is |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
452 recorded in a property named @code{variable-documentation}. The byte |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
453 compiler likewise uses properties to record those functions needing |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
454 special treatment. |
6411 | 455 |
456 However, association lists have their own advantages. Depending on | |
457 your application, it may be faster to add an association to the front of | |
458 an association list than to update a property. All properties for a | |
459 symbol are stored in the same property list, so there is a possibility | |
460 of a conflict between different uses of a property name. (For this | |
461 reason, it is a good idea to choose property names that are probably | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
462 unique, such as by beginning the property name with the program's usual |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
463 name-prefix for variables and functions.) An association list may be |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
464 used like a stack where associations are pushed on the front of the list |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
465 and later discarded; this is not possible with a property list. |
6411 | 466 |
12067 | 467 @node Symbol Plists |
468 @subsection Property List Functions for Symbols | |
469 | |
6411 | 470 @defun symbol-plist symbol |
471 This function returns the property list of @var{symbol}. | |
472 @end defun | |
473 | |
474 @defun setplist symbol plist | |
12067 | 475 This function sets @var{symbol}'s property list to @var{plist}. |
6411 | 476 Normally, @var{plist} should be a well-formed property list, but this is |
477 not enforced. | |
478 | |
479 @smallexample | |
480 (setplist 'foo '(a 1 b (2 3) c nil)) | |
481 @result{} (a 1 b (2 3) c nil) | |
482 (symbol-plist 'foo) | |
483 @result{} (a 1 b (2 3) c nil) | |
484 @end smallexample | |
485 | |
486 For symbols in special obarrays, which are not used for ordinary | |
487 purposes, it may make sense to use the property list cell in a | |
488 nonstandard fashion; in fact, the abbrev mechanism does so | |
489 (@pxref{Abbrevs}). | |
490 @end defun | |
491 | |
492 @defun get symbol property | |
493 This function finds the value of the property named @var{property} in | |
494 @var{symbol}'s property list. If there is no such property, @code{nil} | |
495 is returned. Thus, there is no distinction between a value of | |
496 @code{nil} and the absence of the property. | |
497 | |
498 The name @var{property} is compared with the existing property names | |
499 using @code{eq}, so any object is a legitimate property. | |
500 | |
501 See @code{put} for an example. | |
502 @end defun | |
503 | |
504 @defun put symbol property value | |
505 This function puts @var{value} onto @var{symbol}'s property list under | |
506 the property name @var{property}, replacing any previous property value. | |
507 The @code{put} function returns @var{value}. | |
508 | |
509 @smallexample | |
510 (put 'fly 'verb 'transitive) | |
511 @result{}'transitive | |
512 (put 'fly 'noun '(a buzzing little bug)) | |
513 @result{} (a buzzing little bug) | |
514 (get 'fly 'verb) | |
515 @result{} transitive | |
516 (symbol-plist 'fly) | |
517 @result{} (verb transitive noun (a buzzing little bug)) | |
518 @end smallexample | |
519 @end defun | |
12067 | 520 |
521 @node Other Plists | |
522 @subsection Property Lists Outside Symbols | |
523 | |
34014 | 524 These functions are useful for manipulating property lists |
12067 | 525 that are stored in places other than symbols: |
526 | |
527 @defun plist-get plist property | |
528 This returns the value of the @var{property} property | |
529 stored in the property list @var{plist}. For example, | |
530 | |
531 @example | |
532 (plist-get '(foo 4) 'foo) | |
533 @result{} 4 | |
534 @end example | |
535 @end defun | |
536 | |
537 @defun plist-put plist property value | |
12098 | 538 This stores @var{value} as the value of the @var{property} property in |
539 the property list @var{plist}. It may modify @var{plist} destructively, | |
12128
27144f55d1c6
fixed errors that appeared during update to 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents:
12098
diff
changeset
|
540 or it may construct a new list structure without altering the old. The |
12098 | 541 function returns the modified property list, so you can store that back |
542 in the place where you got @var{plist}. For example, | |
12067 | 543 |
544 @example | |
545 (setq my-plist '(bar t foo 4)) | |
546 @result{} (bar t foo 4) | |
547 (setq my-plist (plist-put my-plist 'foo 69)) | |
548 @result{} (bar t foo 69) | |
549 (setq my-plist (plist-put my-plist 'quux '(a))) | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
550 @result{} (bar t foo 69 quux (a)) |
12067 | 551 @end example |
552 @end defun | |
553 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
554 You could define @code{put} in terms of @code{plist-put} as follows: |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
555 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
556 @example |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
557 (defun put (symbol prop value) |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
558 (setplist symbol |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
559 (plist-put (symbol-plist symbol) prop value))) |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
560 @end example |
34014 | 561 |
562 @defun plist-member plist property | |
563 @tindex plist-member | |
564 This returns non-@code{nil} if @var{plist} contains the given | |
565 @var{property}. Unlike @code{plist-get}, this allows you to distinguish | |
566 between a missing property and a property with the value @code{nil}. | |
567 The value is actually the tail of @var{plist} whose @code{car} is | |
568 @var{property}. | |
569 @end defun |