|
0
|
1 @c -*-texinfo-*-
|
|
|
2 @c This is part of the XEmacs Lisp Reference Manual.
|
|
|
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
|
|
|
4 @c See the file lispref.texi for copying conditions.
|
|
|
5 @setfilename ../../info/symbols.info
|
|
|
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 * Symbol Properties:: Each symbol has a property list
|
|
|
31 for recording miscellaneous information.
|
|
|
32 @end menu
|
|
|
33
|
|
|
34 @node Symbol Components
|
|
|
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
|
|
|
44 The @dfn{print name cell} holds a string that names the symbol for
|
|
|
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 (symbol)
|
|
|
65 The @dfn{property list cell} holds the property list of the symbol. See
|
|
|
66 @code{symbol-plist} in @ref{Symbol Properties}.
|
|
|
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 XEmacs 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
|
|
|
96 symbol @code{nil}.) Examining a cell that is void results in an error,
|
|
|
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
|
|
367
|
118 the name of the source file of this chapter of the XEmacs Lisp Reference
|
|
|
119 Manual.
|
|
0
|
120 The property list cell contains the list @code{(variable-documentation
|
|
|
121 29529)} which tells the documentation functions where to find the
|
|
|
122 documentation string for the variable @code{buffer-file-name} in the
|
|
|
123 @file{DOC} file. (29529 is the offset from the beginning of the
|
|
|
124 @file{DOC} file to where that documentation string begins.) The
|
|
|
125 function cell contains the function for returning the name of the file.
|
|
|
126 @code{buffer-file-name} names a primitive function, which has no read
|
|
|
127 syntax and prints in hash notation (@pxref{Primitive Function Type}). A
|
|
|
128 symbol naming a function written in Lisp would have a lambda expression
|
|
|
129 (or a byte-code object) in this cell.
|
|
|
130
|
|
|
131 @node Definitions
|
|
|
132 @section Defining Symbols
|
|
|
133 @cindex definition of a symbol
|
|
|
134
|
|
|
135 A @dfn{definition} in Lisp is a special form that announces your
|
|
|
136 intention to use a certain symbol in a particular way. In XEmacs Lisp,
|
|
|
137 you can define a symbol as a variable, or define it as a function (or
|
|
|
138 macro), or both independently.
|
|
|
139
|
|
|
140 A definition construct typically specifies a value or meaning for the
|
|
|
141 symbol for one kind of use, plus documentation for its meaning when used
|
|
|
142 in this way. Thus, when you define a symbol as a variable, you can
|
|
|
143 supply an initial value for the variable, plus documentation for the
|
|
|
144 variable.
|
|
|
145
|
|
|
146 @code{defvar} and @code{defconst} are special forms that define a
|
|
|
147 symbol as a global variable. They are documented in detail in
|
|
|
148 @ref{Defining Variables}.
|
|
|
149
|
|
|
150 @code{defun} defines a symbol as a function, creating a lambda
|
|
|
151 expression and storing it in the function cell of the symbol. This
|
|
|
152 lambda expression thus becomes the function definition of the symbol.
|
|
|
153 (The term ``function definition'', meaning the contents of the function
|
|
|
154 cell, is derived from the idea that @code{defun} gives the symbol its
|
|
|
155 definition as a function.) @code{defsubst}, @code{define-function} and
|
|
|
156 @code{defalias} are other ways of defining a function.
|
|
|
157 @xref{Functions}.
|
|
|
158
|
|
|
159 @code{defmacro} defines a symbol as a macro. It creates a macro
|
|
|
160 object and stores it in the function cell of the symbol. Note that a
|
|
|
161 given symbol can be a macro or a function, but not both at once, because
|
|
|
162 both macro and function definitions are kept in the function cell, and
|
|
|
163 that cell can hold only one Lisp object at any given time.
|
|
|
164 @xref{Macros}.
|
|
|
165
|
|
|
166 In XEmacs Lisp, a definition is not required in order to use a symbol
|
|
|
167 as a variable or function. Thus, you can make a symbol a global
|
|
|
168 variable with @code{setq}, whether you define it first or not. The real
|
|
|
169 purpose of definitions is to guide programmers and programming tools.
|
|
|
170 They inform programmers who read the code that certain symbols are
|
|
|
171 @emph{intended} to be used as variables, or as functions. In addition,
|
|
|
172 utilities such as @file{etags} and @file{make-docfile} recognize
|
|
|
173 definitions, and add appropriate information to tag tables and the
|
|
78
|
174 @file{DOC} file. @xref{Accessing Documentation}.
|
|
0
|
175
|
|
|
176 @node Creating Symbols
|
|
|
177 @section Creating and Interning Symbols
|
|
|
178 @cindex reading symbols
|
|
|
179
|
|
|
180 To understand how symbols are created in XEmacs Lisp, you must know
|
|
|
181 how Lisp reads them. Lisp must ensure that it finds the same symbol
|
|
|
182 every time it reads the same set of characters. Failure to do so would
|
|
|
183 cause complete confusion.
|
|
|
184
|
|
|
185 @cindex symbol name hashing
|
|
|
186 @cindex hashing
|
|
|
187 @cindex obarray
|
|
|
188 @cindex bucket (in obarray)
|
|
|
189 When the Lisp reader encounters a symbol, it reads all the characters
|
|
|
190 of the name. Then it ``hashes'' those characters to find an index in a
|
|
|
191 table called an @dfn{obarray}. Hashing is an efficient method of
|
|
|
192 looking something up. For example, instead of searching a telephone
|
|
|
193 book cover to cover when looking up Jan Jones, you start with the J's
|
|
|
194 and go from there. That is a simple version of hashing. Each element
|
|
|
195 of the obarray is a @dfn{bucket} which holds all the symbols with a
|
|
|
196 given hash code; to look for a given name, it is sufficient to look
|
|
|
197 through all the symbols in the bucket for that name's hash code.
|
|
|
198
|
|
|
199 @cindex interning
|
|
|
200 If a symbol with the desired name is found, the reader uses that
|
|
|
201 symbol. If the obarray does not contain a symbol with that name, the
|
|
|
202 reader makes a new symbol and adds it to the obarray. Finding or adding
|
|
|
203 a symbol with a certain name is called @dfn{interning} it, and the
|
|
|
204 symbol is then called an @dfn{interned symbol}.
|
|
|
205
|
|
|
206 Interning ensures that each obarray has just one symbol with any
|
|
|
207 particular name. Other like-named symbols may exist, but not in the
|
|
|
208 same obarray. Thus, the reader gets the same symbols for the same
|
|
|
209 names, as long as you keep reading with the same obarray.
|
|
|
210
|
|
|
211 @cindex symbol equality
|
|
|
212 @cindex uninterned symbol
|
|
|
213 No obarray contains all symbols; in fact, some symbols are not in any
|
|
|
214 obarray. They are called @dfn{uninterned symbols}. An uninterned
|
|
|
215 symbol has the same four cells as other symbols; however, the only way
|
|
|
216 to gain access to it is by finding it in some other object or as the
|
|
|
217 value of a variable.
|
|
|
218
|
|
|
219 In XEmacs Lisp, an obarray is actually a vector. Each element of the
|
|
|
220 vector is a bucket; its value is either an interned symbol whose name
|
|
|
221 hashes to that bucket, or 0 if the bucket is empty. Each interned
|
|
|
222 symbol has an internal link (invisible to the user) to the next symbol
|
|
|
223 in the bucket. Because these links are invisible, there is no way to
|
|
|
224 find all the symbols in an obarray except using @code{mapatoms} (below).
|
|
|
225 The order of symbols in a bucket is not significant.
|
|
|
226
|
|
|
227 In an empty obarray, every element is 0, and you can create an obarray
|
|
|
228 with @code{(make-vector @var{length} 0)}. @strong{This is the only
|
|
|
229 valid way to create an obarray.} Prime numbers as lengths tend
|
|
|
230 to result in good hashing; lengths one less than a power of two are also
|
|
|
231 good.
|
|
|
232
|
|
|
233 @strong{Do not try to put symbols in an obarray yourself.} This does
|
|
|
234 not work---only @code{intern} can enter a symbol in an obarray properly.
|
|
|
235 @strong{Do not try to intern one symbol in two obarrays.} This would
|
|
|
236 garble both obarrays, because a symbol has just one slot to hold the
|
|
|
237 following symbol in the obarray bucket. The results would be
|
|
|
238 unpredictable.
|
|
|
239
|
|
|
240 It is possible for two different symbols to have the same name in
|
|
|
241 different obarrays; these symbols are not @code{eq} or @code{equal}.
|
|
|
242 However, this normally happens only as part of the abbrev mechanism
|
|
|
243 (@pxref{Abbrevs}).
|
|
|
244
|
|
|
245 @cindex CL note---symbol in obarrays
|
|
|
246 @quotation
|
|
|
247 @b{Common Lisp note:} In Common Lisp, a single symbol may be interned in
|
|
|
248 several obarrays.
|
|
|
249 @end quotation
|
|
|
250
|
|
|
251 Most of the functions below take a name and sometimes an obarray as
|
|
|
252 arguments. A @code{wrong-type-argument} error is signaled if the name
|
|
|
253 is not a string, or if the obarray is not a vector.
|
|
|
254
|
|
|
255 @defun symbol-name symbol
|
|
|
256 This function returns the string that is @var{symbol}'s name. For example:
|
|
|
257
|
|
|
258 @example
|
|
|
259 @group
|
|
|
260 (symbol-name 'foo)
|
|
|
261 @result{} "foo"
|
|
|
262 @end group
|
|
|
263 @end example
|
|
|
264
|
|
|
265 Changing the string by substituting characters, etc, does change the
|
|
|
266 name of the symbol, but fails to update the obarray, so don't do it!
|
|
|
267 @end defun
|
|
|
268
|
|
|
269 @defun make-symbol name
|
|
|
270 This function returns a newly-allocated, uninterned symbol whose name is
|
|
|
271 @var{name} (which must be a string). Its value and function definition
|
|
|
272 are void, and its property list is @code{nil}. In the example below,
|
|
|
273 the value of @code{sym} is not @code{eq} to @code{foo} because it is a
|
|
|
274 distinct uninterned symbol whose name is also @samp{foo}.
|
|
|
275
|
|
|
276 @example
|
|
|
277 (setq sym (make-symbol "foo"))
|
|
|
278 @result{} foo
|
|
|
279 (eq sym 'foo)
|
|
|
280 @result{} nil
|
|
|
281 @end example
|
|
|
282 @end defun
|
|
|
283
|
|
|
284 @defun intern name &optional obarray
|
|
|
285 This function returns the interned symbol whose name is @var{name}. If
|
|
|
286 there is no such symbol in the obarray @var{obarray}, @code{intern}
|
|
|
287 creates a new one, adds it to the obarray, and returns it. If
|
|
|
288 @var{obarray} is omitted, the value of the global variable
|
|
|
289 @code{obarray} is used.
|
|
|
290
|
|
|
291 @example
|
|
|
292 (setq sym (intern "foo"))
|
|
|
293 @result{} foo
|
|
|
294 (eq sym 'foo)
|
|
|
295 @result{} t
|
|
|
296
|
|
|
297 (setq sym1 (intern "foo" other-obarray))
|
|
|
298 @result{} foo
|
|
|
299 (eq sym 'foo)
|
|
|
300 @result{} nil
|
|
|
301 @end example
|
|
|
302 @end defun
|
|
|
303
|
|
|
304 @defun intern-soft name &optional obarray
|
|
|
305 This function returns the symbol in @var{obarray} whose name is
|
|
|
306 @var{name}, or @code{nil} if @var{obarray} has no symbol with that name.
|
|
|
307 Therefore, you can use @code{intern-soft} to test whether a symbol with
|
|
|
308 a given name is already interned. If @var{obarray} is omitted, the
|
|
|
309 value of the global variable @code{obarray} is used.
|
|
|
310
|
|
|
311 @smallexample
|
|
|
312 (intern-soft "frazzle") ; @r{No such symbol exists.}
|
|
|
313 @result{} nil
|
|
|
314 (make-symbol "frazzle") ; @r{Create an uninterned one.}
|
|
|
315 @result{} frazzle
|
|
|
316 @group
|
|
|
317 (intern-soft "frazzle") ; @r{That one cannot be found.}
|
|
|
318 @result{} nil
|
|
|
319 @end group
|
|
|
320 @group
|
|
|
321 (setq sym (intern "frazzle")) ; @r{Create an interned one.}
|
|
|
322 @result{} frazzle
|
|
|
323 @end group
|
|
|
324 @group
|
|
|
325 (intern-soft "frazzle") ; @r{That one can be found!}
|
|
|
326 @result{} frazzle
|
|
|
327 @end group
|
|
|
328 @group
|
|
|
329 (eq sym 'frazzle) ; @r{And it is the same one.}
|
|
|
330 @result{} t
|
|
|
331 @end group
|
|
|
332 @end smallexample
|
|
|
333 @end defun
|
|
|
334
|
|
|
335 @defvar obarray
|
|
|
336 This variable is the standard obarray for use by @code{intern} and
|
|
|
337 @code{read}.
|
|
|
338 @end defvar
|
|
|
339
|
|
|
340 @defun mapatoms function &optional obarray
|
|
|
341 This function calls @var{function} for each symbol in the obarray
|
|
|
342 @var{obarray}. It returns @code{nil}. If @var{obarray} is omitted, it
|
|
|
343 defaults to the value of @code{obarray}, the standard obarray for
|
|
|
344 ordinary symbols.
|
|
|
345
|
|
|
346 @smallexample
|
|
|
347 (setq count 0)
|
|
|
348 @result{} 0
|
|
|
349 (defun count-syms (s)
|
|
|
350 (setq count (1+ count)))
|
|
|
351 @result{} count-syms
|
|
|
352 (mapatoms 'count-syms)
|
|
|
353 @result{} nil
|
|
|
354 count
|
|
|
355 @result{} 1871
|
|
|
356 @end smallexample
|
|
|
357
|
|
|
358 See @code{documentation} in @ref{Accessing Documentation}, for another
|
|
|
359 example using @code{mapatoms}.
|
|
|
360 @end defun
|
|
|
361
|
|
|
362 @defun unintern symbol &optional obarray
|
|
|
363 This function deletes @var{symbol} from the obarray @var{obarray}. If
|
|
|
364 @code{symbol} is not actually in the obarray, @code{unintern} does
|
|
|
365 nothing. If @var{obarray} is @code{nil}, the current obarray is used.
|
|
|
366
|
|
|
367 If you provide a string instead of a symbol as @var{symbol}, it stands
|
|
|
368 for a symbol name. Then @code{unintern} deletes the symbol (if any) in
|
|
|
369 the obarray which has that name. If there is no such symbol,
|
|
|
370 @code{unintern} does nothing.
|
|
|
371
|
|
|
372 If @code{unintern} does delete a symbol, it returns @code{t}. Otherwise
|
|
|
373 it returns @code{nil}.
|
|
|
374 @end defun
|
|
|
375
|
|
|
376 @node Symbol Properties
|
|
|
377 @section Symbol Properties
|
|
|
378 @cindex property list, symbol
|
|
|
379 @cindex plist, symbol
|
|
|
380
|
|
|
381 A @dfn{property list} (@dfn{plist} for short) is a list of paired
|
|
|
382 elements stored in the property list cell of a symbol. Each of the
|
|
|
383 pairs associates a property name (usually a symbol) with a property or
|
|
|
384 value. Property lists are generally used to record information about a
|
|
|
385 symbol, such as its documentation as a variable, the name of the file
|
|
|
386 where it was defined, or perhaps even the grammatical class of the
|
|
|
387 symbol (representing a word) in a language-understanding system.
|
|
|
388
|
|
|
389 Many objects other than symbols can have property lists associated
|
|
|
390 with them, and XEmacs provides a full complement of functions for
|
|
|
391 working with property lists. @xref{Property Lists}.
|
|
|
392
|
|
|
393 The property names and values in a property list can be any Lisp
|
|
|
394 objects, but the names are usually symbols. They are compared using
|
|
|
395 @code{eq}. Here is an example of a property list, found on the symbol
|
|
|
396 @code{progn} when the compiler is loaded:
|
|
|
397
|
|
|
398 @example
|
|
|
399 (lisp-indent-function 0 byte-compile byte-compile-progn)
|
|
|
400 @end example
|
|
|
401
|
|
|
402 @noindent
|
|
|
403 Here @code{lisp-indent-function} and @code{byte-compile} are property
|
|
|
404 names, and the other two elements are the corresponding values.
|
|
|
405
|
|
|
406 @menu
|
|
|
407 * Plists and Alists:: Comparison of the advantages of property
|
|
|
408 lists and association lists.
|
|
|
409 * Symbol Plists:: Functions to access symbols' property lists.
|
|
|
410 * Other Plists:: Accessing property lists stored elsewhere.
|
|
|
411 @end menu
|
|
|
412
|
|
|
413 @node Plists and Alists
|
|
|
414 @subsection Property Lists and Association Lists
|
|
|
415
|
|
|
416 @cindex property lists vs association lists
|
|
|
417 Association lists (@pxref{Association Lists}) are very similar to
|
|
|
418 property lists. In contrast to association lists, the order of the
|
|
|
419 pairs in the property list is not significant since the property names
|
|
|
420 must be distinct.
|
|
|
421
|
|
|
422 Property lists are better than association lists for attaching
|
|
|
423 information to various Lisp function names or variables. If all the
|
|
|
424 associations are recorded in one association list, the program will need
|
|
|
425 to search that entire list each time a function or variable is to be
|
|
|
426 operated on. By contrast, if the information is recorded in the
|
|
|
427 property lists of the function names or variables themselves, each
|
|
|
428 search will scan only the length of one property list, which is usually
|
|
|
429 short. This is why the documentation for a variable is recorded in a
|
|
|
430 property named @code{variable-documentation}. The byte compiler
|
|
|
431 likewise uses properties to record those functions needing special
|
|
|
432 treatment.
|
|
|
433
|
|
|
434 However, association lists have their own advantages. Depending on
|
|
|
435 your application, it may be faster to add an association to the front of
|
|
|
436 an association list than to update a property. All properties for a
|
|
|
437 symbol are stored in the same property list, so there is a possibility
|
|
|
438 of a conflict between different uses of a property name. (For this
|
|
|
439 reason, it is a good idea to choose property names that are probably
|
|
|
440 unique, such as by including the name of the library in the property
|
|
|
441 name.) An association list may be used like a stack where associations
|
|
|
442 are pushed on the front of the list and later discarded; this is not
|
|
|
443 possible with a property list.
|
|
|
444
|
|
|
445 @node Symbol Plists
|
|
|
446 @subsection Property List Functions for Symbols
|
|
|
447
|
|
|
448 @defun symbol-plist symbol
|
|
|
449 This function returns the property list of @var{symbol}.
|
|
|
450 @end defun
|
|
|
451
|
|
|
452 @defun setplist symbol plist
|
|
|
453 This function sets @var{symbol}'s property list to @var{plist}.
|
|
|
454 Normally, @var{plist} should be a well-formed property list, but this is
|
|
|
455 not enforced.
|
|
|
456
|
|
|
457 @smallexample
|
|
|
458 (setplist 'foo '(a 1 b (2 3) c nil))
|
|
|
459 @result{} (a 1 b (2 3) c nil)
|
|
|
460 (symbol-plist 'foo)
|
|
|
461 @result{} (a 1 b (2 3) c nil)
|
|
|
462 @end smallexample
|
|
|
463
|
|
|
464 For symbols in special obarrays, which are not used for ordinary
|
|
|
465 purposes, it may make sense to use the property list cell in a
|
|
|
466 nonstandard fashion; in fact, the abbrev mechanism does so
|
|
|
467 (@pxref{Abbrevs}).
|
|
|
468 @end defun
|
|
|
469
|
|
|
470 @defun get symbol property
|
|
|
471 This function finds the value of the property named @var{property} in
|
|
|
472 @var{symbol}'s property list. If there is no such property, @code{nil}
|
|
|
473 is returned. Thus, there is no distinction between a value of
|
|
|
474 @code{nil} and the absence of the property.
|
|
|
475
|
|
|
476 The name @var{property} is compared with the existing property names
|
|
|
477 using @code{eq}, so any object is a legitimate property.
|
|
|
478
|
|
|
479 See @code{put} for an example.
|
|
|
480 @end defun
|
|
|
481
|
|
|
482 @defun put symbol property value
|
|
|
483 This function puts @var{value} onto @var{symbol}'s property list under
|
|
|
484 the property name @var{property}, replacing any previous property value.
|
|
|
485 The @code{put} function returns @var{value}.
|
|
|
486
|
|
|
487 @smallexample
|
|
|
488 (put 'fly 'verb 'transitive)
|
|
|
489 @result{}'transitive
|
|
|
490 (put 'fly 'noun '(a buzzing little bug))
|
|
|
491 @result{} (a buzzing little bug)
|
|
|
492 (get 'fly 'verb)
|
|
|
493 @result{} transitive
|
|
|
494 (symbol-plist 'fly)
|
|
|
495 @result{} (verb transitive noun (a buzzing little bug))
|
|
|
496 @end smallexample
|
|
|
497 @end defun
|
|
|
498
|
|
|
499 @node Other Plists
|
|
|
500 @subsection Property Lists Outside Symbols
|
|
|
501
|
|
|
502 These functions are useful for manipulating property lists
|
|
|
503 that are stored in places other than symbols:
|
|
|
504
|
|
|
505 @defun getf plist property &optional default
|
|
|
506 This returns the value of the @var{property} property
|
|
|
507 stored in the property list @var{plist}. For example,
|
|
|
508
|
|
|
509 @example
|
|
|
510 (getf '(foo 4) 'foo)
|
|
|
511 @result{} 4
|
|
|
512 @end example
|
|
|
513 @end defun
|
|
|
514
|
|
|
515 @defun putf plist property value
|
|
|
516 This stores @var{value} as the value of the @var{property} property in
|
|
|
517 the property list @var{plist}. It may modify @var{plist} destructively,
|
|
|
518 or it may construct a new list structure without altering the old. The
|
|
|
519 function returns the modified property list, so you can store that back
|
|
|
520 in the place where you got @var{plist}. For example,
|
|
|
521
|
|
|
522 @example
|
|
|
523 (setq my-plist '(bar t foo 4))
|
|
|
524 @result{} (bar t foo 4)
|
|
|
525 (setq my-plist (putf my-plist 'foo 69))
|
|
|
526 @result{} (bar t foo 69)
|
|
|
527 (setq my-plist (putf my-plist 'quux '(a)))
|
|
|
528 @result{} (quux (a) bar t foo 5)
|
|
|
529 @end example
|
|
|
530 @end defun
|
|
|
531
|
|
|
532 @defun plists-eq a b
|
|
|
533 This function returns non-@code{nil} if property lists @var{a} and @var{b}
|
|
|
534 are @code{eq}. This means that the property lists have the same values
|
|
|
535 for all the same properties, where comparison between values is done using
|
|
|
536 @code{eq}.
|
|
|
537 @end defun
|
|
|
538
|
|
|
539 @defun plists-equal a b
|
|
|
540 This function returns non-@code{nil} if property lists @var{a} and @var{b}
|
|
|
541 are @code{equal}.
|
|
|
542 @end defun
|
|
|
543
|
|
|
544 Both of the above functions do order-insensitive comparisons.
|
|
|
545
|
|
|
546 @example
|
|
|
547 (plists-eq '(a 1 b 2 c nil) '(b 2 a 1))
|
|
|
548 @result{} t
|
|
|
549 (plists-eq '(foo "hello" bar "goodbye") '(bar "goodbye" foo "hello"))
|
|
|
550 @result{} nil
|
|
|
551 (plists-equal '(foo "hello" bar "goodbye") '(bar "goodbye" foo "hello"))
|
|
|
552 @result{} t
|
|
|
553 @end example
|
|
|
554
|
|
|
555
|
|
|
556
|
