2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @setfilename ../info/symbols
6 @node Symbols, Evaluation, Sequences Arrays Vectors, Top
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
17 You can test whether an arbitrary Lisp object is a symbol
21 This function returns @code{t} if @var{object} is a symbol, @code{nil}
26 * Symbol Components:: Symbols have names, values, function definitions
28 * Definitions:: A definition says how a symbol will be used.
29 * Creating Symbols:: How symbols are kept unique.
30 * Property Lists:: Each symbol has a property list
31 for recording miscellaneous information.
34 @node Symbol Components, Definitions, Symbols, Symbols
35 @section Symbol Components
36 @cindex symbol components
38 Each symbol has four components (or ``cells''), each of which
39 references another object:
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}.
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}.
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}.
64 @cindex property list cell
65 The @dfn{property list cell} holds the property list of the symbol. See
66 @code{symbol-plist} in @ref{Property Lists}.
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.
72 The print name cell holds the string that is the name of the symbol.
73 Since symbols are represented textually by their names, it is important
74 not to have two symbols with the same name. The Lisp reader ensures
75 this: every time it reads a symbol, it looks for an existing symbol with
76 the specified name before it creates a new one. (In GNU Emacs Lisp,
77 this lookup uses a hashing algorithm and an obarray; see @ref{Creating
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
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.
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}.
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}:
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>
116 Because this symbol is the variable which holds the name of the file
117 being visited in the current buffer, the value cell contents we see are
118 the name of the source file of this chapter of the Emacs Lisp Manual.
119 The property list cell contains the list @code{(variable-documentation
120 29529)} which tells the documentation functions where to find the
121 documentation string for the variable @code{buffer-file-name} in the
122 @file{DOC} file. (29529 is the offset from the beginning of the
123 @file{DOC} file to where that documentation string begins.) The
124 function cell contains the function for returning the name of the file.
125 @code{buffer-file-name} names a primitive function, which has no read
126 syntax and prints in hash notation (@pxref{Primitive Function Type}). A
127 symbol naming a function written in Lisp would have a lambda expression
128 (or a byte-code object) in this cell.
130 @node Definitions, Creating Symbols, Symbol Components, Symbols
131 @section Defining Symbols
132 @cindex definition of a symbol
134 A @dfn{definition} in Lisp is a special form that announces your
135 intention to use a certain symbol in a particular way. In Emacs Lisp,
136 you can define a symbol as a variable, or define it as a function (or
137 macro), or both independently.
139 A definition construct typically specifies a value or meaning for the
140 symbol for one kind of use, plus documentation for its meaning when used
141 in this way. Thus, when you define a symbol as a variable, you can
142 supply an initial value for the variable, plus documentation for the
145 @code{defvar} and @code{defconst} are special forms that define a
146 symbol as a global variable. They are documented in detail in
147 @ref{Defining Variables}.
149 @code{defun} defines a symbol as a function, creating a lambda
150 expression and storing it in the function cell of the symbol. This
151 lambda expression thus becomes the function definition of the symbol.
152 (The term ``function definition'', meaning the contents of the function
153 cell, is derived from the idea that @code{defun} gives the symbol its
154 definition as a function.) @code{defsubst} and @code{defalias} are two
155 other ways of defining a function. @xref{Functions}.
157 @code{defmacro} defines a symbol as a macro. It creates a macro
158 object and stores it in the function cell of the symbol. Note that a
159 given symbol can be a macro or a function, but not both at once, because
160 both macro and function definitions are kept in the function cell, and
161 that cell can hold only one Lisp object at any given time.
164 In Emacs Lisp, a definition is not required in order to use a symbol
165 as a variable or function. Thus, you can make a symbol a global
166 variable with @code{setq}, whether you define it first or not. The real
167 purpose of definitions is to guide programmers and programming tools.
168 They inform programmers who read the code that certain symbols are
169 @emph{intended} to be used as variables, or as functions. In addition,
170 utilities such as @file{etags} and @file{make-docfile} recognize
171 definitions, and add appropriate information to tag tables and the
172 @file{emacs/etc/DOC-@var{version}} file. @xref{Accessing Documentation}.
174 @node Creating Symbols, Property Lists, Definitions, Symbols
175 @section Creating and Interning Symbols
176 @cindex reading symbols
178 To understand how symbols are created in GNU Emacs Lisp, you must know
179 how Lisp reads them. Lisp must ensure that it finds the same symbol
180 every time it reads the same set of characters. Failure to do so would
181 cause complete confusion.
183 @cindex symbol name hashing
186 @cindex bucket (in obarray)
187 When the Lisp reader encounters a symbol, it reads all the characters
188 of the name. Then it ``hashes'' those characters to find an index in a
189 table called an @dfn{obarray}. Hashing is an efficient method of
190 looking something up. For example, instead of searching a telephone
191 book cover to cover when looking up Jan Jones, you start with the J's
192 and go from there. That is a simple version of hashing. Each element
193 of the obarray is a @dfn{bucket} which holds all the symbols with a
194 given hash code; to look for a given name, it is sufficient to look
195 through all the symbols in the bucket for that name's hash code.
198 If a symbol with the desired name is found, the reader uses that
199 symbol. If the obarray does not contain a symbol with that name, the
200 reader makes a new symbol and adds it to the obarray. Finding or adding
201 a symbol with a certain name is called @dfn{interning} it, and the
202 symbol is then called an @dfn{interned symbol}.
204 Interning ensures that each obarray has just one symbol with any
205 particular name. Other like-named symbols may exist, but not in the
206 same obarray. Thus, the reader gets the same symbols for the same
207 names, as long as you keep reading with the same obarray.
209 @cindex symbol equality
210 @cindex uninterned symbol
211 No obarray contains all symbols; in fact, some symbols are not in any
212 obarray. They are called @dfn{uninterned symbols}. An uninterned
213 symbol has the same four cells as other symbols; however, the only way
214 to gain access to it is by finding it in some other object or as the
217 In Emacs Lisp, an obarray is actually a vector. Each element of the
218 vector is a bucket; its value is either an interned symbol whose name
219 hashes to that bucket, or 0 if the bucket is empty. Each interned
220 symbol has an internal link (invisible to the user) to the next symbol
221 in the bucket. Because these links are invisible, there is no way to
222 find all the symbols in an obarray except using @code{mapatoms} (below).
223 The order of symbols in a bucket is not significant.
225 In an empty obarray, every element is 0, and you can create an obarray
226 with @code{(make-vector @var{length} 0)}. @strong{This is the only
227 valid way to create an obarray.} Prime numbers as lengths tend
228 to result in good hashing; lengths one less than a power of two are also
231 @strong{Do not try to put symbols in an obarray yourself.} This does
232 not work---only @code{intern} can enter a symbol in an obarray properly.
233 @strong{Do not try to intern one symbol in two obarrays.} This would
234 garble both obarrays, because a symbol has just one slot to hold the
235 following symbol in the obarray bucket. The results would be
238 It is possible for two different symbols to have the same name in
239 different obarrays; these symbols are not @code{eq} or @code{equal}.
240 However, this normally happens only as part of the abbrev mechanism
243 @cindex CL note---symbol in obarrays
245 @b{Common Lisp note:} In Common Lisp, a single symbol may be interned in
249 Most of the functions below take a name and sometimes an obarray as
250 arguments. A @code{wrong-type-argument} error is signaled if the name
251 is not a string, or if the obarray is not a vector.
253 @defun symbol-name symbol
254 This function returns the string that is @var{symbol}'s name. For example:
263 Changing the string by substituting characters, etc, does change the
264 name of the symbol, but fails to update the obarray, so don't do it!
267 @defun make-symbol name
268 This function returns a newly-allocated, uninterned symbol whose name is
269 @var{name} (which must be a string). Its value and function definition
270 are void, and its property list is @code{nil}. In the example below,
271 the value of @code{sym} is not @code{eq} to @code{foo} because it is a
272 distinct uninterned symbol whose name is also @samp{foo}.
275 (setq sym (make-symbol "foo"))
282 @defun intern name &optional obarray
283 This function returns the interned symbol whose name is @var{name}. If
284 there is no such symbol in the obarray @var{obarray}, @code{intern}
285 creates a new one, adds it to the obarray, and returns it. If
286 @var{obarray} is omitted, the value of the global variable
287 @code{obarray} is used.
290 (setq sym (intern "foo"))
295 (setq sym1 (intern "foo" other-obarray))
302 @defun intern-soft name &optional obarray
303 This function returns the symbol in @var{obarray} whose name is
304 @var{name}, or @code{nil} if @var{obarray} has no symbol with that name.
305 Therefore, you can use @code{intern-soft} to test whether a symbol with
306 a given name is already interned. If @var{obarray} is omitted, the
307 value of the global variable @code{obarray} is used.
310 (intern-soft "frazzle") ; @r{No such symbol exists.}
312 (make-symbol "frazzle") ; @r{Create an uninterned one.}
314 (intern-soft "frazzle") ; @r{That one cannot be found.}
316 (setq sym (intern "frazzle")) ; @r{Create an interned one.}
318 (intern-soft "frazzle") ; @r{That one can be found!}
321 (eq sym 'frazzle) ; @r{And it is the same one.}
328 This variable is the standard obarray for use by @code{intern} and
332 @defun mapatoms function &optional obarray
333 This function calls @var{function} for each symbol in the obarray
334 @var{obarray}. It returns @code{nil}. If @var{obarray} is omitted, it
335 defaults to the value of @code{obarray}, the standard obarray for
341 (defun count-syms (s)
342 (setq count (1+ count)))
344 (mapatoms 'count-syms)
350 See @code{documentation} in @ref{Accessing Documentation}, for another
351 example using @code{mapatoms}.
354 @defun unintern symbol &optional obarray
355 This function deletes @var{symbol} from the obarray @var{obarray}. If
356 @code{symbol} is not actually in the obarray, @code{unintern} does
357 nothing. If @var{obarray} is @code{nil}, the current obarray is used.
359 If you provide a string instead of a symbol as @var{symbol}, it stands
360 for a symbol name. Then @code{unintern} deletes the symbol (if any) in
361 the obarray which has that name. If there is no such symbol,
362 @code{unintern} does nothing.
364 If @code{unintern} does delete a symbol, it returns @code{t}. Otherwise
365 it returns @code{nil}.
368 @node Property Lists,, Creating Symbols, Symbols
369 @section Property Lists
370 @cindex property list
373 A @dfn{property list} (@dfn{plist} for short) is a list of paired
374 elements stored in the property list cell of a symbol. Each of the
375 pairs associates a property name (usually a symbol) with a property or
376 value. Property lists are generally used to record information about a
377 symbol, such as its documentation as a variable, the name of the file
378 where it was defined, or perhaps even the grammatical class of the
379 symbol (representing a word) in a language-understanding system.
381 Character positions in a string or buffer can also have property lists.
382 @xref{Text Properties}.
384 The property names and values in a property list can be any Lisp
385 objects, but the names are usually symbols. They are compared using
386 @code{eq}. Here is an example of a property list, found on the symbol
387 @code{progn} when the compiler is loaded:
390 (lisp-indent-function 0 byte-compile byte-compile-progn)
394 Here @code{lisp-indent-function} and @code{byte-compile} are property
395 names, and the other two elements are the corresponding values.
398 * Plists and Alists:: Comparison of the advantages of property
399 lists and association lists.
400 * Symbol Plists:: Functions to access symbols' property lists.
401 * Other Plists:: Accessing property lists stored elsewhere.
404 @node Plists and Alists
405 @subsection Property Lists and Association Lists
407 @cindex property lists vs association lists
408 Association lists (@pxref{Association Lists}) are very similar to
409 property lists. In contrast to association lists, the order of the
410 pairs in the property list is not significant since the property names
413 Property lists are better than association lists for attaching
414 information to various Lisp function names or variables. If all the
415 associations are recorded in one association list, the program will need
416 to search that entire list each time a function or variable is to be
417 operated on. By contrast, if the information is recorded in the
418 property lists of the function names or variables themselves, each
419 search will scan only the length of one property list, which is usually
420 short. This is why the documentation for a variable is recorded in a
421 property named @code{variable-documentation}. The byte compiler
422 likewise uses properties to record those functions needing special
425 However, association lists have their own advantages. Depending on
426 your application, it may be faster to add an association to the front of
427 an association list than to update a property. All properties for a
428 symbol are stored in the same property list, so there is a possibility
429 of a conflict between different uses of a property name. (For this
430 reason, it is a good idea to choose property names that are probably
431 unique, such as by including the name of the library in the property
432 name.) An association list may be used like a stack where associations
433 are pushed on the front of the list and later discarded; this is not
434 possible with a property list.
437 @subsection Property List Functions for Symbols
439 @defun symbol-plist symbol
440 This function returns the property list of @var{symbol}.
443 @defun setplist symbol plist
444 This function sets @var{symbol}'s property list to @var{plist}.
445 Normally, @var{plist} should be a well-formed property list, but this is
449 (setplist 'foo '(a 1 b (2 3) c nil))
450 @result{} (a 1 b (2 3) c nil)
452 @result{} (a 1 b (2 3) c nil)
455 For symbols in special obarrays, which are not used for ordinary
456 purposes, it may make sense to use the property list cell in a
457 nonstandard fashion; in fact, the abbrev mechanism does so
461 @defun get symbol property
462 This function finds the value of the property named @var{property} in
463 @var{symbol}'s property list. If there is no such property, @code{nil}
464 is returned. Thus, there is no distinction between a value of
465 @code{nil} and the absence of the property.
467 The name @var{property} is compared with the existing property names
468 using @code{eq}, so any object is a legitimate property.
470 See @code{put} for an example.
473 @defun put symbol property value
474 This function puts @var{value} onto @var{symbol}'s property list under
475 the property name @var{property}, replacing any previous property value.
476 The @code{put} function returns @var{value}.
479 (put 'fly 'verb 'transitive)
481 (put 'fly 'noun '(a buzzing little bug))
482 @result{} (a buzzing little bug)
486 @result{} (verb transitive noun (a buzzing little bug))
491 @subsection Property Lists Outside Symbols
493 These two functions are useful for manipulating property lists
494 that are stored in places other than symbols:
496 @defun plist-get plist property
497 This returns the value of the @var{property} property
498 stored in the property list @var{plist}. For example,
501 (plist-get '(foo 4) 'foo)
506 @defun plist-put plist property value
507 This stores @var{value} as the value of the @var{property} property in
508 the property list @var{plist}. It may modify @var{plist} destructively,
509 or it may construct new list structure without altering the old. The
510 function returns the modified property list, so you can store that back
511 in the place where you got @var{plist}. For example,
514 (setq my-plist '(bar t foo 4))
515 @result{} (bar t foo 4)
516 (setq my-plist (plist-put my-plist 'foo 69))
517 @result{} (bar t foo 69)
518 (setq my-plist (plist-put my-plist 'quux '(a)))
519 @result{} (quux (a) bar t foo 5)