2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @setfilename ../info/symbols
6 @node Symbols, Evaluation, Hash Tables, 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 names 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
81 (@pxref{Functions}) or a macro (@pxref{Macros}), as that is what the
82 Lisp interpreter expects to see there (@pxref{Evaluation}). Keyboard
83 macros (@pxref{Keyboard Macros}), keymaps (@pxref{Keymaps}) and autoload
84 objects (@pxref{Autoloading}) are also sometimes stored in the function
85 cells of symbols. We often refer to ``the function @code{foo}'' when we
86 really mean the function stored in the function cell of the symbol
87 @code{foo}. We make the distinction only when necessary.
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 function or value cell that is void
97 results in an error, 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-@var{version}} file. (29529 is the offset from the beginning
123 of the @file{DOC-@var{version}} file to where that documentation string
124 begins---see @ref{Documentation Basics}.) The function cell contains
125 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.
131 @node Definitions, Creating Symbols, Symbol Components, Symbols
132 @section Defining Symbols
133 @cindex definition of a symbol
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 Emacs Lisp,
137 you can define a symbol as a variable, or define it as a function (or
138 macro), or both independently.
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
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}. For defining user option variables that can
149 be customized, use @code{defcustom} (@pxref{Customization}).
151 @code{defun} defines a symbol as a function, creating a lambda
152 expression and storing it in the function cell of the symbol. This
153 lambda expression thus becomes the function definition of the symbol.
154 (The term ``function definition'', meaning the contents of the function
155 cell, is derived from the idea that @code{defun} gives the symbol its
156 definition as a function.) @code{defsubst} and @code{defalias} are two
157 other ways of defining a function. @xref{Functions}.
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.
166 In Emacs 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
174 @file{DOC-@var{version}} file. @xref{Accessing Documentation}.
176 @node Creating Symbols, Property Lists, Definitions, Symbols
177 @section Creating and Interning Symbols
178 @cindex reading symbols
180 To understand how symbols are created in GNU Emacs 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.
185 @cindex symbol name hashing
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. (The
198 same idea is used for general Emacs hash tables, but they are a
199 different data type; see @ref{Hash Tables}.)
202 If a symbol with the desired name is found, the reader uses that
203 symbol. If the obarray does not contain a symbol with that name, the
204 reader makes a new symbol and adds it to the obarray. Finding or adding
205 a symbol with a certain name is called @dfn{interning} it, and the
206 symbol is then called an @dfn{interned symbol}.
208 Interning ensures that each obarray has just one symbol with any
209 particular name. Other like-named symbols may exist, but not in the
210 same obarray. Thus, the reader gets the same symbols for the same
211 names, as long as you keep reading with the same obarray.
213 Interning usually happens automatically in the reader, but sometimes
214 other programs need to do it. For example, after the @kbd{M-x} command
215 obtains the command name as a string using the minibuffer, it then
216 interns the string, to get the interned symbol with that name.
218 @cindex symbol equality
219 @cindex uninterned symbol
220 No obarray contains all symbols; in fact, some symbols are not in any
221 obarray. They are called @dfn{uninterned symbols}. An uninterned
222 symbol has the same four cells as other symbols; however, the only way
223 to gain access to it is by finding it in some other object or as the
226 Creating an uninterned symbol is useful in generating Lisp code,
227 because an uninterned symbol used as a variable in the code you generate
228 cannot clash with any variables used in other Lisp programs.
230 In Emacs Lisp, an obarray is actually a vector. Each element of the
231 vector is a bucket; its value is either an interned symbol whose name
232 hashes to that bucket, or 0 if the bucket is empty. Each interned
233 symbol has an internal link (invisible to the user) to the next symbol
234 in the bucket. Because these links are invisible, there is no way to
235 find all the symbols in an obarray except using @code{mapatoms} (below).
236 The order of symbols in a bucket is not significant.
238 In an empty obarray, every element is 0, so you can create an obarray
239 with @code{(make-vector @var{length} 0)}. @strong{This is the only
240 valid way to create an obarray.} Prime numbers as lengths tend
241 to result in good hashing; lengths one less than a power of two are also
244 @strong{Do not try to put symbols in an obarray yourself.} This does
245 not work---only @code{intern} can enter a symbol in an obarray properly.
247 @cindex CL note---symbol in obarrays
249 @b{Common Lisp note:} In Common Lisp, a single symbol may be interned in
253 Most of the functions below take a name and sometimes an obarray as
254 arguments. A @code{wrong-type-argument} error is signaled if the name
255 is not a string, or if the obarray is not a vector.
257 @defun symbol-name symbol
258 This function returns the string that is @var{symbol}'s name. For example:
267 @strong{Warning:} Changing the string by substituting characters does
268 change the name of the symbol, but fails to update the obarray, so don't
272 @defun make-symbol name
273 This function returns a newly-allocated, uninterned symbol whose name is
274 @var{name} (which must be a string). Its value and function definition
275 are void, and its property list is @code{nil}. In the example below,
276 the value of @code{sym} is not @code{eq} to @code{foo} because it is a
277 distinct uninterned symbol whose name is also @samp{foo}.
280 (setq sym (make-symbol "foo"))
287 @defun intern name &optional obarray
288 This function returns the interned symbol whose name is @var{name}. If
289 there is no such symbol in the obarray @var{obarray}, @code{intern}
290 creates a new one, adds it to the obarray, and returns it. If
291 @var{obarray} is omitted, the value of the global variable
292 @code{obarray} is used.
295 (setq sym (intern "foo"))
300 (setq sym1 (intern "foo" other-obarray))
307 @cindex CL note---interning existing symbol
309 @b{Common Lisp note:} In Common Lisp, you can intern an existing symbol
310 in an obarray. In Emacs Lisp, you cannot do this, because the argument
311 to @code{intern} must be a string, not a symbol.
314 @defun intern-soft name &optional obarray
315 This function returns the symbol in @var{obarray} whose name is
316 @var{name}, or @code{nil} if @var{obarray} has no symbol with that name.
317 Therefore, you can use @code{intern-soft} to test whether a symbol with
318 a given name is already interned. If @var{obarray} is omitted, the
319 value of the global variable @code{obarray} is used.
322 (intern-soft "frazzle") ; @r{No such symbol exists.}
324 (make-symbol "frazzle") ; @r{Create an uninterned one.}
327 (intern-soft "frazzle") ; @r{That one cannot be found.}
331 (setq sym (intern "frazzle")) ; @r{Create an interned one.}
335 (intern-soft "frazzle") ; @r{That one can be found!}
339 (eq sym 'frazzle) ; @r{And it is the same one.}
346 This variable is the standard obarray for use by @code{intern} and
350 @defun mapatoms function &optional obarray
351 This function calls @var{function} once with each symbol in the obarray
352 @var{obarray}. Then it returns @code{nil}. If @var{obarray} is
353 omitted, it defaults to the value of @code{obarray}, the standard
354 obarray for ordinary symbols.
359 (defun count-syms (s)
360 (setq count (1+ count)))
362 (mapatoms 'count-syms)
368 See @code{documentation} in @ref{Accessing Documentation}, for another
369 example using @code{mapatoms}.
372 @defun unintern symbol &optional obarray
373 This function deletes @var{symbol} from the obarray @var{obarray}. If
374 @code{symbol} is not actually in the obarray, @code{unintern} does
375 nothing. If @var{obarray} is @code{nil}, the current obarray is used.
377 If you provide a string instead of a symbol as @var{symbol}, it stands
378 for a symbol name. Then @code{unintern} deletes the symbol (if any) in
379 the obarray which has that name. If there is no such symbol,
380 @code{unintern} does nothing.
382 If @code{unintern} does delete a symbol, it returns @code{t}. Otherwise
383 it returns @code{nil}.
386 @node Property Lists,, Creating Symbols, Symbols
387 @section Property Lists
388 @cindex property list
391 A @dfn{property list} (@dfn{plist} for short) is a list of paired
392 elements stored in the property list cell of a symbol. Each of the
393 pairs associates a property name (usually a symbol) with a property or
394 value. Property lists are generally used to record information about a
395 symbol, such as its documentation as a variable, the name of the file
396 where it was defined, or perhaps even the grammatical class of the
397 symbol (representing a word) in a language-understanding system.
399 Character positions in a string or buffer can also have property lists.
400 @xref{Text Properties}.
402 The property names and values in a property list can be any Lisp
403 objects, but the names are usually symbols. Property list functions
404 compare the property names using @code{eq}. Here is an example of a
405 property list, found on the symbol @code{progn} when the compiler is
409 (lisp-indent-function 0 byte-compile byte-compile-progn)
413 Here @code{lisp-indent-function} and @code{byte-compile} are property
414 names, and the other two elements are the corresponding values.
417 * Plists and Alists:: Comparison of the advantages of property
418 lists and association lists.
419 * Symbol Plists:: Functions to access symbols' property lists.
420 * Other Plists:: Accessing property lists stored elsewhere.
423 @node Plists and Alists
424 @subsection Property Lists and Association Lists
426 @cindex property lists vs association lists
427 Association lists (@pxref{Association Lists}) are very similar to
428 property lists. In contrast to association lists, the order of the
429 pairs in the property list is not significant since the property names
432 Property lists are better than association lists for attaching
433 information to various Lisp function names or variables. If your
434 program keeps all of its associations in one association list, it will
435 typically need to search that entire list each time it checks for an
436 association. This could be slow. By contrast, if you keep the same
437 information in the property lists of the function names or variables
438 themselves, each search will scan only the length of one property list,
439 which is usually short. This is why the documentation for a variable is
440 recorded in a property named @code{variable-documentation}. The byte
441 compiler likewise uses properties to record those functions needing
444 However, association lists have their own advantages. Depending on
445 your application, it may be faster to add an association to the front of
446 an association list than to update a property. All properties for a
447 symbol are stored in the same property list, so there is a possibility
448 of a conflict between different uses of a property name. (For this
449 reason, it is a good idea to choose property names that are probably
450 unique, such as by beginning the property name with the program's usual
451 name-prefix for variables and functions.) An association list may be
452 used like a stack where associations are pushed on the front of the list
453 and later discarded; this is not possible with a property list.
456 @subsection Property List Functions for Symbols
458 @defun symbol-plist symbol
459 This function returns the property list of @var{symbol}.
462 @defun setplist symbol plist
463 This function sets @var{symbol}'s property list to @var{plist}.
464 Normally, @var{plist} should be a well-formed property list, but this is
468 (setplist 'foo '(a 1 b (2 3) c nil))
469 @result{} (a 1 b (2 3) c nil)
471 @result{} (a 1 b (2 3) c nil)
474 For symbols in special obarrays, which are not used for ordinary
475 purposes, it may make sense to use the property list cell in a
476 nonstandard fashion; in fact, the abbrev mechanism does so
480 @defun get symbol property
481 This function finds the value of the property named @var{property} in
482 @var{symbol}'s property list. If there is no such property, @code{nil}
483 is returned. Thus, there is no distinction between a value of
484 @code{nil} and the absence of the property.
486 The name @var{property} is compared with the existing property names
487 using @code{eq}, so any object is a legitimate property.
489 See @code{put} for an example.
492 @defun put symbol property value
493 This function puts @var{value} onto @var{symbol}'s property list under
494 the property name @var{property}, replacing any previous property value.
495 The @code{put} function returns @var{value}.
498 (put 'fly 'verb 'transitive)
500 (put 'fly 'noun '(a buzzing little bug))
501 @result{} (a buzzing little bug)
505 @result{} (verb transitive noun (a buzzing little bug))
510 @subsection Property Lists Outside Symbols
512 These two functions are useful for manipulating property lists
513 that are stored in places other than symbols:
515 @defun plist-get plist property
516 This returns the value of the @var{property} property
517 stored in the property list @var{plist}. For example,
520 (plist-get '(foo 4) 'foo)
525 @defun plist-put plist property value
526 This stores @var{value} as the value of the @var{property} property in
527 the property list @var{plist}. It may modify @var{plist} destructively,
528 or it may construct a new list structure without altering the old. The
529 function returns the modified property list, so you can store that back
530 in the place where you got @var{plist}. For example,
533 (setq my-plist '(bar t foo 4))
534 @result{} (bar t foo 4)
535 (setq my-plist (plist-put my-plist 'foo 69))
536 @result{} (bar t foo 69)
537 (setq my-plist (plist-put my-plist 'quux '(a)))
538 @result{} (bar t foo 69 quux (a))
542 You could define @code{put} in terms of @code{plist-put} as follows:
545 (defun put (symbol prop value)
547 (plist-put (symbol-plist symbol) prop value)))