Mercurial > emacs
annotate lispref/symbols.texi @ 88776:805a3bb7daf4
(file-coding-system-alist): Change
.elc to utf-8-Emacs.
author | Dave Love <fx@gnu.org> |
---|---|
date | Mon, 24 Jun 2002 18:24:44 +0000 |
parents | 7a42abfb0c82 |
children | 23a1cea22d13 |
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 |
38944 | 88 We often refer to ``the function @code{foo}'' when we really mean |
89 the function stored in the function cell of the symbol @code{foo}. We | |
90 make the distinction explicit only when necessary. In normal | |
91 usage, the function cell usually contains a function | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
92 (@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
|
93 Lisp interpreter expects to see there (@pxref{Evaluation}). Keyboard |
38944 | 94 macros (@pxref{Keyboard Macros}), keymaps (@pxref{Keymaps}) and |
95 autoload objects (@pxref{Autoloading}) are also sometimes stored in | |
96 the function cells of symbols. | |
6411 | 97 |
98 The property list cell normally should hold a correctly formatted | |
99 property list (@pxref{Property Lists}), as a number of functions expect | |
100 to see a property list there. | |
101 | |
102 The function cell or the value cell may be @dfn{void}, which means | |
103 that the cell does not reference any object. (This is not the same | |
104 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
|
105 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
|
106 results in an error, such as @samp{Symbol's value as variable is void}. |
6411 | 107 |
108 The four functions @code{symbol-name}, @code{symbol-value}, | |
109 @code{symbol-plist}, and @code{symbol-function} return the contents of | |
110 the four cells of a symbol. Here as an example we show the contents of | |
111 the four cells of the symbol @code{buffer-file-name}: | |
112 | |
113 @example | |
114 (symbol-name 'buffer-file-name) | |
115 @result{} "buffer-file-name" | |
116 (symbol-value 'buffer-file-name) | |
117 @result{} "/gnu/elisp/symbols.texi" | |
118 (symbol-plist 'buffer-file-name) | |
119 @result{} (variable-documentation 29529) | |
120 (symbol-function 'buffer-file-name) | |
121 @result{} #<subr buffer-file-name> | |
122 @end example | |
123 | |
124 @noindent | |
125 Because this symbol is the variable which holds the name of the file | |
126 being visited in the current buffer, the value cell contents we see are | |
127 the name of the source file of this chapter of the Emacs Lisp Manual. | |
128 The property list cell contains the list @code{(variable-documentation | |
129 29529)} which tells the documentation functions where to find the | |
130 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
|
131 @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
|
132 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
|
133 begins---see @ref{Documentation Basics}.) The function cell contains |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
134 the function for returning the name of the file. |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
135 @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
|
136 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
|
137 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
|
138 (or a byte-code object) in this cell. |
6411 | 139 |
140 @node Definitions, Creating Symbols, Symbol Components, Symbols | |
141 @section Defining Symbols | |
142 @cindex definition of a symbol | |
143 | |
144 A @dfn{definition} in Lisp is a special form that announces your | |
145 intention to use a certain symbol in a particular way. In Emacs Lisp, | |
146 you can define a symbol as a variable, or define it as a function (or | |
147 macro), or both independently. | |
148 | |
149 A definition construct typically specifies a value or meaning for the | |
150 symbol for one kind of use, plus documentation for its meaning when used | |
151 in this way. Thus, when you define a symbol as a variable, you can | |
152 supply an initial value for the variable, plus documentation for the | |
153 variable. | |
154 | |
155 @code{defvar} and @code{defconst} are special forms that define a | |
156 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
|
157 @ref{Defining Variables}. For defining user option variables that can |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
158 be customized, use @code{defcustom} (@pxref{Customization}). |
6411 | 159 |
160 @code{defun} defines a symbol as a function, creating a lambda | |
161 expression and storing it in the function cell of the symbol. This | |
162 lambda expression thus becomes the function definition of the symbol. | |
163 (The term ``function definition'', meaning the contents of the function | |
164 cell, is derived from the idea that @code{defun} gives the symbol its | |
12098 | 165 definition as a function.) @code{defsubst} and @code{defalias} are two |
166 other ways of defining a function. @xref{Functions}. | |
6411 | 167 |
168 @code{defmacro} defines a symbol as a macro. It creates a macro | |
169 object and stores it in the function cell of the symbol. Note that a | |
170 given symbol can be a macro or a function, but not both at once, because | |
171 both macro and function definitions are kept in the function cell, and | |
172 that cell can hold only one Lisp object at any given time. | |
173 @xref{Macros}. | |
174 | |
12098 | 175 In Emacs Lisp, a definition is not required in order to use a symbol |
176 as a variable or function. Thus, you can make a symbol a global | |
6411 | 177 variable with @code{setq}, whether you define it first or not. The real |
178 purpose of definitions is to guide programmers and programming tools. | |
179 They inform programmers who read the code that certain symbols are | |
180 @emph{intended} to be used as variables, or as functions. In addition, | |
181 utilities such as @file{etags} and @file{make-docfile} recognize | |
182 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
|
183 @file{DOC-@var{version}} file. @xref{Accessing Documentation}. |
6411 | 184 |
185 @node Creating Symbols, Property Lists, Definitions, Symbols | |
186 @section Creating and Interning Symbols | |
187 @cindex reading symbols | |
188 | |
189 To understand how symbols are created in GNU Emacs Lisp, you must know | |
190 how Lisp reads them. Lisp must ensure that it finds the same symbol | |
191 every time it reads the same set of characters. Failure to do so would | |
192 cause complete confusion. | |
193 | |
194 @cindex symbol name hashing | |
195 @cindex hashing | |
196 @cindex obarray | |
197 @cindex bucket (in obarray) | |
198 When the Lisp reader encounters a symbol, it reads all the characters | |
199 of the name. Then it ``hashes'' those characters to find an index in a | |
200 table called an @dfn{obarray}. Hashing is an efficient method of | |
201 looking something up. For example, instead of searching a telephone | |
202 book cover to cover when looking up Jan Jones, you start with the J's | |
203 and go from there. That is a simple version of hashing. Each element | |
204 of the obarray is a @dfn{bucket} which holds all the symbols with a | |
205 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
|
206 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
|
207 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
|
208 different data type; see @ref{Hash Tables}.) |
6411 | 209 |
210 @cindex interning | |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6411
diff
changeset
|
211 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
|
212 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
|
213 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
|
214 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
|
215 symbol is then called an @dfn{interned symbol}. |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6411
diff
changeset
|
216 |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6411
diff
changeset
|
217 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
|
218 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
|
219 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
|
220 names, as long as you keep reading with the same obarray. |
6411 | 221 |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23727
diff
changeset
|
222 Interning usually happens automatically in the reader, but sometimes |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23727
diff
changeset
|
223 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
|
224 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
|
225 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
|
226 |
6411 | 227 @cindex symbol equality |
228 @cindex uninterned symbol | |
7118
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6411
diff
changeset
|
229 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
|
230 obarray. They are called @dfn{uninterned symbols}. An uninterned |
08d61ef58d13
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6411
diff
changeset
|
231 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
|
232 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
|
233 value of a variable. |
6411 | 234 |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23727
diff
changeset
|
235 Creating an uninterned symbol is useful in generating Lisp code, |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23727
diff
changeset
|
236 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
|
237 cannot clash with any variables used in other Lisp programs. |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23727
diff
changeset
|
238 |
6411 | 239 In Emacs Lisp, an obarray is actually a vector. Each element of the |
240 vector is a bucket; its value is either an interned symbol whose name | |
241 hashes to that bucket, or 0 if the bucket is empty. Each interned | |
242 symbol has an internal link (invisible to the user) to the next symbol | |
243 in the bucket. Because these links are invisible, there is no way to | |
244 find all the symbols in an obarray except using @code{mapatoms} (below). | |
245 The order of symbols in a bucket is not significant. | |
246 | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
23727
diff
changeset
|
247 In an empty obarray, every element is 0, so you can create an obarray |
6411 | 248 with @code{(make-vector @var{length} 0)}. @strong{This is the only |
249 valid way to create an obarray.} Prime numbers as lengths tend | |
250 to result in good hashing; lengths one less than a power of two are also | |
251 good. | |
252 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
253 @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
|
254 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
|
255 |
6411 | 256 @cindex CL note---symbol in obarrays |
257 @quotation | |
7734 | 258 @b{Common Lisp note:} In Common Lisp, a single symbol may be interned in |
6411 | 259 several obarrays. |
260 @end quotation | |
261 | |
262 Most of the functions below take a name and sometimes an obarray as | |
263 arguments. A @code{wrong-type-argument} error is signaled if the name | |
264 is not a string, or if the obarray is not a vector. | |
265 | |
266 @defun symbol-name symbol | |
267 This function returns the string that is @var{symbol}'s name. For example: | |
268 | |
269 @example | |
270 @group | |
271 (symbol-name 'foo) | |
272 @result{} "foo" | |
273 @end group | |
274 @end example | |
275 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
276 @strong{Warning:} Changing the string by substituting characters does |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
277 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
|
278 do it! |
6411 | 279 @end defun |
280 | |
281 @defun make-symbol name | |
282 This function returns a newly-allocated, uninterned symbol whose name is | |
283 @var{name} (which must be a string). Its value and function definition | |
284 are void, and its property list is @code{nil}. In the example below, | |
285 the value of @code{sym} is not @code{eq} to @code{foo} because it is a | |
286 distinct uninterned symbol whose name is also @samp{foo}. | |
287 | |
288 @example | |
289 (setq sym (make-symbol "foo")) | |
290 @result{} foo | |
291 (eq sym 'foo) | |
292 @result{} nil | |
293 @end example | |
294 @end defun | |
295 | |
296 @defun intern name &optional obarray | |
297 This function returns the interned symbol whose name is @var{name}. If | |
298 there is no such symbol in the obarray @var{obarray}, @code{intern} | |
299 creates a new one, adds it to the obarray, and returns it. If | |
300 @var{obarray} is omitted, the value of the global variable | |
301 @code{obarray} is used. | |
302 | |
303 @example | |
304 (setq sym (intern "foo")) | |
305 @result{} foo | |
306 (eq sym 'foo) | |
307 @result{} t | |
308 | |
309 (setq sym1 (intern "foo" other-obarray)) | |
310 @result{} foo | |
23727 | 311 (eq sym1 'foo) |
6411 | 312 @result{} nil |
313 @end example | |
314 @end defun | |
315 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
316 @cindex CL note---interning existing symbol |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
317 @quotation |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
318 @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
|
319 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
|
320 to @code{intern} must be a string, not a symbol. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
321 @end quotation |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
322 |
6411 | 323 @defun intern-soft name &optional obarray |
324 This function returns the symbol in @var{obarray} whose name is | |
325 @var{name}, or @code{nil} if @var{obarray} has no symbol with that name. | |
326 Therefore, you can use @code{intern-soft} to test whether a symbol with | |
327 a given name is already interned. If @var{obarray} is omitted, the | |
328 value of the global variable @code{obarray} is used. | |
329 | |
27385
f7b7fdb0f3f4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27189
diff
changeset
|
330 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
|
331 the function returns @var{name} if @var{name} is interned |
f7b7fdb0f3f4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27189
diff
changeset
|
332 in the specified obarray, and otherwise @code{nil}. |
f7b7fdb0f3f4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27189
diff
changeset
|
333 |
6411 | 334 @smallexample |
335 (intern-soft "frazzle") ; @r{No such symbol exists.} | |
336 @result{} nil | |
337 (make-symbol "frazzle") ; @r{Create an uninterned one.} | |
338 @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
|
339 @group |
6411 | 340 (intern-soft "frazzle") ; @r{That one cannot be found.} |
341 @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
|
342 @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
|
343 @group |
6411 | 344 (setq sym (intern "frazzle")) ; @r{Create an interned one.} |
345 @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
|
346 @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
|
347 @group |
6411 | 348 (intern-soft "frazzle") ; @r{That one can be found!} |
349 @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
|
350 @end group |
6411 | 351 @group |
352 (eq sym 'frazzle) ; @r{And it is the same one.} | |
353 @result{} t | |
354 @end group | |
355 @end smallexample | |
356 @end defun | |
357 | |
358 @defvar obarray | |
359 This variable is the standard obarray for use by @code{intern} and | |
360 @code{read}. | |
361 @end defvar | |
362 | |
363 @defun mapatoms function &optional obarray | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
364 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
|
365 @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
|
366 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
|
367 obarray for ordinary symbols. |
6411 | 368 |
369 @smallexample | |
370 (setq count 0) | |
371 @result{} 0 | |
372 (defun count-syms (s) | |
373 (setq count (1+ count))) | |
374 @result{} count-syms | |
375 (mapatoms 'count-syms) | |
376 @result{} nil | |
377 count | |
378 @result{} 1871 | |
379 @end smallexample | |
380 | |
381 See @code{documentation} in @ref{Accessing Documentation}, for another | |
382 example using @code{mapatoms}. | |
383 @end defun | |
384 | |
12067 | 385 @defun unintern symbol &optional obarray |
386 This function deletes @var{symbol} from the obarray @var{obarray}. If | |
387 @code{symbol} is not actually in the obarray, @code{unintern} does | |
388 nothing. If @var{obarray} is @code{nil}, the current obarray is used. | |
389 | |
390 If you provide a string instead of a symbol as @var{symbol}, it stands | |
391 for a symbol name. Then @code{unintern} deletes the symbol (if any) in | |
392 the obarray which has that name. If there is no such symbol, | |
393 @code{unintern} does nothing. | |
394 | |
395 If @code{unintern} does delete a symbol, it returns @code{t}. Otherwise | |
396 it returns @code{nil}. | |
397 @end defun | |
398 | |
6411 | 399 @node Property Lists,, Creating Symbols, Symbols |
400 @section Property Lists | |
401 @cindex property list | |
402 @cindex plist | |
403 | |
404 A @dfn{property list} (@dfn{plist} for short) is a list of paired | |
405 elements stored in the property list cell of a symbol. Each of the | |
406 pairs associates a property name (usually a symbol) with a property or | |
407 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
|
408 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
|
409 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
|
410 symbol (representing a word) in a language-understanding system. |
6411 | 411 |
412 Character positions in a string or buffer can also have property lists. | |
413 @xref{Text Properties}. | |
414 | |
415 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
|
416 objects, but the names are usually symbols. Property list functions |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
417 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
|
418 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
|
419 loaded: |
6411 | 420 |
421 @example | |
422 (lisp-indent-function 0 byte-compile byte-compile-progn) | |
423 @end example | |
424 | |
425 @noindent | |
426 Here @code{lisp-indent-function} and @code{byte-compile} are property | |
427 names, and the other two elements are the corresponding values. | |
428 | |
12067 | 429 @menu |
430 * Plists and Alists:: Comparison of the advantages of property | |
431 lists and association lists. | |
432 * Symbol Plists:: Functions to access symbols' property lists. | |
433 * Other Plists:: Accessing property lists stored elsewhere. | |
434 @end menu | |
435 | |
436 @node Plists and Alists | |
437 @subsection Property Lists and Association Lists | |
438 | |
6411 | 439 @cindex property lists vs association lists |
440 Association lists (@pxref{Association Lists}) are very similar to | |
441 property lists. In contrast to association lists, the order of the | |
442 pairs in the property list is not significant since the property names | |
443 must be distinct. | |
444 | |
445 Property lists are better than association lists for attaching | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
446 information to various Lisp function names or variables. If your |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
447 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
|
448 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
|
449 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
|
450 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
|
451 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
|
452 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
|
453 recorded in a property named @code{variable-documentation}. The byte |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
454 compiler likewise uses properties to record those functions needing |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
455 special treatment. |
6411 | 456 |
457 However, association lists have their own advantages. Depending on | |
458 your application, it may be faster to add an association to the front of | |
459 an association list than to update a property. All properties for a | |
460 symbol are stored in the same property list, so there is a possibility | |
461 of a conflict between different uses of a property name. (For this | |
462 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
|
463 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
|
464 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
|
465 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
|
466 and later discarded; this is not possible with a property list. |
6411 | 467 |
12067 | 468 @node Symbol Plists |
469 @subsection Property List Functions for Symbols | |
470 | |
6411 | 471 @defun symbol-plist symbol |
472 This function returns the property list of @var{symbol}. | |
473 @end defun | |
474 | |
475 @defun setplist symbol plist | |
12067 | 476 This function sets @var{symbol}'s property list to @var{plist}. |
6411 | 477 Normally, @var{plist} should be a well-formed property list, but this is |
478 not enforced. | |
479 | |
480 @smallexample | |
481 (setplist 'foo '(a 1 b (2 3) c nil)) | |
482 @result{} (a 1 b (2 3) c nil) | |
483 (symbol-plist 'foo) | |
484 @result{} (a 1 b (2 3) c nil) | |
485 @end smallexample | |
486 | |
487 For symbols in special obarrays, which are not used for ordinary | |
488 purposes, it may make sense to use the property list cell in a | |
489 nonstandard fashion; in fact, the abbrev mechanism does so | |
490 (@pxref{Abbrevs}). | |
491 @end defun | |
492 | |
493 @defun get symbol property | |
494 This function finds the value of the property named @var{property} in | |
495 @var{symbol}'s property list. If there is no such property, @code{nil} | |
496 is returned. Thus, there is no distinction between a value of | |
497 @code{nil} and the absence of the property. | |
498 | |
499 The name @var{property} is compared with the existing property names | |
500 using @code{eq}, so any object is a legitimate property. | |
501 | |
502 See @code{put} for an example. | |
503 @end defun | |
504 | |
505 @defun put symbol property value | |
506 This function puts @var{value} onto @var{symbol}'s property list under | |
507 the property name @var{property}, replacing any previous property value. | |
508 The @code{put} function returns @var{value}. | |
509 | |
510 @smallexample | |
511 (put 'fly 'verb 'transitive) | |
512 @result{}'transitive | |
513 (put 'fly 'noun '(a buzzing little bug)) | |
514 @result{} (a buzzing little bug) | |
515 (get 'fly 'verb) | |
516 @result{} transitive | |
517 (symbol-plist 'fly) | |
518 @result{} (verb transitive noun (a buzzing little bug)) | |
519 @end smallexample | |
520 @end defun | |
12067 | 521 |
522 @node Other Plists | |
523 @subsection Property Lists Outside Symbols | |
524 | |
34014 | 525 These functions are useful for manipulating property lists |
12067 | 526 that are stored in places other than symbols: |
527 | |
528 @defun plist-get plist property | |
529 This returns the value of the @var{property} property | |
530 stored in the property list @var{plist}. For example, | |
531 | |
532 @example | |
533 (plist-get '(foo 4) 'foo) | |
534 @result{} 4 | |
535 @end example | |
536 @end defun | |
537 | |
538 @defun plist-put plist property value | |
12098 | 539 This stores @var{value} as the value of the @var{property} property in |
540 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
|
541 or it may construct a new list structure without altering the old. The |
12098 | 542 function returns the modified property list, so you can store that back |
543 in the place where you got @var{plist}. For example, | |
12067 | 544 |
545 @example | |
546 (setq my-plist '(bar t foo 4)) | |
547 @result{} (bar t foo 4) | |
548 (setq my-plist (plist-put my-plist 'foo 69)) | |
549 @result{} (bar t foo 69) | |
550 (setq my-plist (plist-put my-plist 'quux '(a))) | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
12282
diff
changeset
|
551 @result{} (bar t foo 69 quux (a)) |
12067 | 552 @end example |
553 @end defun | |
554 | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
555 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
|
556 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
557 @example |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
558 (defun put (symbol prop value) |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
559 (setplist symbol |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
560 (plist-put (symbol-plist symbol) prop value))) |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
561 @end example |
34014 | 562 |
563 @defun plist-member plist property | |
564 @tindex plist-member | |
565 This returns non-@code{nil} if @var{plist} contains the given | |
566 @var{property}. Unlike @code{plist-get}, this allows you to distinguish | |
567 between a missing property and a property with the value @code{nil}. | |
568 The value is actually the tail of @var{plist} whose @code{car} is | |
569 @var{property}. | |
570 @end defun |