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