Commit | Line | Data |
---|---|---|
1621af1e RS |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Emacs Lisp Reference Manual. | |
fd897522 GM |
3 | @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999 |
4 | @c Free Software Foundation, Inc. | |
1621af1e RS |
5 | @c See the file elisp.texi for copying conditions. |
6 | @setfilename ../info/symbols | |
8241495d | 7 | @node Symbols, Evaluation, Hash Tables, Top |
1621af1e RS |
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 | |
2b3fc6c3 | 45 | The @dfn{print name cell} holds a string that names the symbol for |
1621af1e RS |
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 | |
8241495d | 61 | has separate value and function cells, variables names and function names do |
1621af1e RS |
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 | ||
72821190 RS |
81 | The value cell holds the symbol's value as a variable |
82 | (@pxref{Variables}). That is what you get if you evaluate the symbol as | |
83 | a Lisp expression (@pxref{Evaluation}). Any Lisp object is a legitimate | |
84 | value. Certain symbols have values that cannot be changed; these | |
85 | include @code{nil} and @code{t}, and any symbol whose name starts with | |
86 | @samp{:} (those are called @dfn{keywords}). @xref{Constant Variables}. | |
87 | ||
f9f59935 RS |
88 | In normal usage, the function cell usually contains a function |
89 | (@pxref{Functions}) or a macro (@pxref{Macros}), as that is what the | |
90 | Lisp interpreter expects to see there (@pxref{Evaluation}). Keyboard | |
91 | macros (@pxref{Keyboard Macros}), keymaps (@pxref{Keymaps}) and autoload | |
92 | objects (@pxref{Autoloading}) are also sometimes stored in the function | |
93 | cells of symbols. We often refer to ``the function @code{foo}'' when we | |
94 | really mean the function stored in the function cell of the symbol | |
95 | @code{foo}. We make the distinction only when necessary. | |
1621af1e RS |
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 | |
f9f59935 RS |
104 | symbol @code{nil}.) Examining a function or value cell that is void |
105 | results in an error, such as @samp{Symbol's value as variable is void}. | |
1621af1e RS |
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 | |
f9f59935 RS |
130 | @file{DOC-@var{version}} file. (29529 is the offset from the beginning |
131 | of the @file{DOC-@var{version}} file to where that documentation string | |
a9f0a989 RS |
132 | begins---see @ref{Documentation Basics}.) The function cell contains |
133 | the function for returning the name of the file. | |
134 | @code{buffer-file-name} names a primitive function, which has no read | |
135 | syntax and prints in hash notation (@pxref{Primitive Function Type}). A | |
136 | symbol naming a function written in Lisp would have a lambda expression | |
137 | (or a byte-code object) in this cell. | |
1621af1e RS |
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 | |
969fe9b5 RS |
156 | @ref{Defining Variables}. For defining user option variables that can |
157 | be customized, use @code{defcustom} (@pxref{Customization}). | |
1621af1e RS |
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 | |
bfe721d1 KH |
164 | definition as a function.) @code{defsubst} and @code{defalias} are two |
165 | other ways of defining a function. @xref{Functions}. | |
1621af1e RS |
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 | ||
bfe721d1 KH |
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 | |
1621af1e RS |
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 | |
f9f59935 | 182 | @file{DOC-@var{version}} file. @xref{Accessing Documentation}. |
1621af1e RS |
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 | |
8241495d RS |
205 | through all the symbols in the bucket for that name's hash code. (The |
206 | same idea is used for general Emacs hash tables, but they are a | |
207 | different data type; see @ref{Hash Tables}.) | |
1621af1e RS |
208 | |
209 | @cindex interning | |
2b3fc6c3 RS |
210 | If a symbol with the desired name is found, the reader uses that |
211 | symbol. If the obarray does not contain a symbol with that name, the | |
212 | reader makes a new symbol and adds it to the obarray. Finding or adding | |
213 | a symbol with a certain name is called @dfn{interning} it, and the | |
214 | symbol is then called an @dfn{interned symbol}. | |
215 | ||
216 | Interning ensures that each obarray has just one symbol with any | |
217 | particular name. Other like-named symbols may exist, but not in the | |
218 | same obarray. Thus, the reader gets the same symbols for the same | |
219 | names, as long as you keep reading with the same obarray. | |
1621af1e | 220 | |
8241495d RS |
221 | Interning usually happens automatically in the reader, but sometimes |
222 | other programs need to do it. For example, after the @kbd{M-x} command | |
223 | obtains the command name as a string using the minibuffer, it then | |
224 | interns the string, to get the interned symbol with that name. | |
225 | ||
1621af1e RS |
226 | @cindex symbol equality |
227 | @cindex uninterned symbol | |
2b3fc6c3 RS |
228 | No obarray contains all symbols; in fact, some symbols are not in any |
229 | obarray. They are called @dfn{uninterned symbols}. An uninterned | |
230 | symbol has the same four cells as other symbols; however, the only way | |
231 | to gain access to it is by finding it in some other object or as the | |
232 | value of a variable. | |
1621af1e | 233 | |
8241495d RS |
234 | Creating an uninterned symbol is useful in generating Lisp code, |
235 | because an uninterned symbol used as a variable in the code you generate | |
236 | cannot clash with any variables used in other Lisp programs. | |
237 | ||
1621af1e RS |
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 | ||
8241495d | 246 | In an empty obarray, every element is 0, so you can create an obarray |
1621af1e RS |
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 | ||
f9f59935 RS |
252 | @strong{Do not try to put symbols in an obarray yourself.} This does |
253 | not work---only @code{intern} can enter a symbol in an obarray properly. | |
254 | ||
1621af1e RS |
255 | @cindex CL note---symbol in obarrays |
256 | @quotation | |
ec221d13 | 257 | @b{Common Lisp note:} In Common Lisp, a single symbol may be interned in |
1621af1e RS |
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 | ||
f9f59935 RS |
275 | @strong{Warning:} Changing the string by substituting characters does |
276 | change the name of the symbol, but fails to update the obarray, so don't | |
277 | do it! | |
1621af1e RS |
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 | |
433d0b26 | 310 | (eq sym1 'foo) |
1621af1e RS |
311 | @result{} nil |
312 | @end example | |
313 | @end defun | |
314 | ||
f9f59935 RS |
315 | @cindex CL note---interning existing symbol |
316 | @quotation | |
317 | @b{Common Lisp note:} In Common Lisp, you can intern an existing symbol | |
318 | in an obarray. In Emacs Lisp, you cannot do this, because the argument | |
319 | to @code{intern} must be a string, not a symbol. | |
320 | @end quotation | |
321 | ||
1621af1e RS |
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 | ||
02b14400 RS |
329 | The argument @var{name} may also be a symbol; in that case, |
330 | the function returns @var{name} if @var{name} is interned | |
331 | in the specified obarray, and otherwise @code{nil}. | |
332 | ||
1621af1e RS |
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 | |
bda144f4 | 338 | @group |
1621af1e RS |
339 | (intern-soft "frazzle") ; @r{That one cannot be found.} |
340 | @result{} nil | |
bda144f4 MW |
341 | @end group |
342 | @group | |
1621af1e RS |
343 | (setq sym (intern "frazzle")) ; @r{Create an interned one.} |
344 | @result{} frazzle | |
bda144f4 MW |
345 | @end group |
346 | @group | |
1621af1e RS |
347 | (intern-soft "frazzle") ; @r{That one can be found!} |
348 | @result{} frazzle | |
bda144f4 | 349 | @end group |
1621af1e RS |
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 | |
f9f59935 RS |
363 | This function calls @var{function} once with each symbol in the obarray |
364 | @var{obarray}. Then it returns @code{nil}. If @var{obarray} is | |
365 | omitted, it defaults to the value of @code{obarray}, the standard | |
366 | obarray for ordinary symbols. | |
1621af1e RS |
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 | ||
22697dac KH |
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 | ||
1621af1e RS |
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 | |
2b3fc6c3 RS |
407 | symbol, such as its documentation as a variable, the name of the file |
408 | where it was defined, or perhaps even the grammatical class of the | |
409 | symbol (representing a word) in a language-understanding system. | |
1621af1e RS |
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 | |
f9f59935 RS |
415 | objects, but the names are usually symbols. Property list functions |
416 | compare the property names using @code{eq}. Here is an example of a | |
417 | property list, found on the symbol @code{progn} when the compiler is | |
418 | loaded: | |
1621af1e RS |
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 | ||
22697dac KH |
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 | ||
1621af1e RS |
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 | |
f9f59935 RS |
445 | information to various Lisp function names or variables. If your |
446 | program keeps all of its associations in one association list, it will | |
447 | typically need to search that entire list each time it checks for an | |
448 | association. This could be slow. By contrast, if you keep the same | |
449 | information in the property lists of the function names or variables | |
450 | themselves, each search will scan only the length of one property list, | |
451 | which is usually short. This is why the documentation for a variable is | |
452 | recorded in a property named @code{variable-documentation}. The byte | |
453 | compiler likewise uses properties to record those functions needing | |
454 | special treatment. | |
1621af1e RS |
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 | |
969fe9b5 RS |
462 | unique, such as by beginning the property name with the program's usual |
463 | name-prefix for variables and functions.) An association list may be | |
464 | used like a stack where associations are pushed on the front of the list | |
465 | and later discarded; this is not possible with a property list. | |
1621af1e | 466 | |
22697dac KH |
467 | @node Symbol Plists |
468 | @subsection Property List Functions for Symbols | |
469 | ||
1621af1e RS |
470 | @defun symbol-plist symbol |
471 | This function returns the property list of @var{symbol}. | |
472 | @end defun | |
473 | ||
474 | @defun setplist symbol plist | |
22697dac | 475 | This function sets @var{symbol}'s property list to @var{plist}. |
1621af1e RS |
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 | |
22697dac KH |
520 | |
521 | @node Other Plists | |
522 | @subsection Property Lists Outside Symbols | |
523 | ||
524 | These two functions are useful for manipulating property lists | |
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 | |
bfe721d1 KH |
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, | |
cc8c51f1 | 540 | or it may construct a new list structure without altering the old. The |
bfe721d1 KH |
541 | function returns the modified property list, so you can store that back |
542 | in the place where you got @var{plist}. For example, | |
22697dac KH |
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))) | |
f9f59935 | 550 | @result{} (bar t foo 69 quux (a)) |
22697dac KH |
551 | @end example |
552 | @end defun | |
553 | ||
969fe9b5 RS |
554 | You could define @code{put} in terms of @code{plist-put} as follows: |
555 | ||
556 | @example | |
557 | (defun put (symbol prop value) | |
558 | (setplist symbol | |
559 | (plist-put (symbol-plist symbol) prop value))) | |
560 | @end example |