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, 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
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.
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}.
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.
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
219 In Emacs 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.
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
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.
236 @cindex CL note---symbol in obarrays
238 @b{Common Lisp note:} In Common Lisp, a single symbol may be interned in
242 Most of the functions below take a name and sometimes an obarray as
243 arguments. A @code{wrong-type-argument} error is signaled if the name
244 is not a string, or if the obarray is not a vector.
246 @defun symbol-name symbol
247 This function returns the string that is @var{symbol}'s name. For example:
256 @strong{Warning:} Changing the string by substituting characters does
257 change the name of the symbol, but fails to update the obarray, so don't
261 @defun make-symbol name
262 This function returns a newly-allocated, uninterned symbol whose name is
263 @var{name} (which must be a string). Its value and function definition
264 are void, and its property list is @code{nil}. In the example below,
265 the value of @code{sym} is not @code{eq} to @code{foo} because it is a
266 distinct uninterned symbol whose name is also @samp{foo}.
269 (setq sym (make-symbol "foo"))
276 @defun intern name &optional obarray
277 This function returns the interned symbol whose name is @var{name}. If
278 there is no such symbol in the obarray @var{obarray}, @code{intern}
279 creates a new one, adds it to the obarray, and returns it. If
280 @var{obarray} is omitted, the value of the global variable
281 @code{obarray} is used.
284 (setq sym (intern "foo"))
289 (setq sym1 (intern "foo" other-obarray))
296 @cindex CL note---interning existing symbol
298 @b{Common Lisp note:} In Common Lisp, you can intern an existing symbol
299 in an obarray. In Emacs Lisp, you cannot do this, because the argument
300 to @code{intern} must be a string, not a symbol.
303 @defun intern-soft name &optional obarray
304 This function returns the symbol in @var{obarray} whose name is
305 @var{name}, or @code{nil} if @var{obarray} has no symbol with that name.
306 Therefore, you can use @code{intern-soft} to test whether a symbol with
307 a given name is already interned. If @var{obarray} is omitted, the
308 value of the global variable @code{obarray} is used.
311 (intern-soft "frazzle") ; @r{No such symbol exists.}
313 (make-symbol "frazzle") ; @r{Create an uninterned one.}
316 (intern-soft "frazzle") ; @r{That one cannot be found.}
320 (setq sym (intern "frazzle")) ; @r{Create an interned one.}
324 (intern-soft "frazzle") ; @r{That one can be found!}
328 (eq sym 'frazzle) ; @r{And it is the same one.}
335 This variable is the standard obarray for use by @code{intern} and
339 @defun mapatoms function &optional obarray
340 This function calls @var{function} once with each symbol in the obarray
341 @var{obarray}. Then it returns @code{nil}. If @var{obarray} is
342 omitted, it defaults to the value of @code{obarray}, the standard
343 obarray for ordinary symbols.
348 (defun count-syms (s)
349 (setq count (1+ count)))
351 (mapatoms 'count-syms)
357 See @code{documentation} in @ref{Accessing Documentation}, for another
358 example using @code{mapatoms}.
361 @defun unintern symbol &optional obarray
362 This function deletes @var{symbol} from the obarray @var{obarray}. If
363 @code{symbol} is not actually in the obarray, @code{unintern} does
364 nothing. If @var{obarray} is @code{nil}, the current obarray is used.
366 If you provide a string instead of a symbol as @var{symbol}, it stands
367 for a symbol name. Then @code{unintern} deletes the symbol (if any) in
368 the obarray which has that name. If there is no such symbol,
369 @code{unintern} does nothing.
371 If @code{unintern} does delete a symbol, it returns @code{t}. Otherwise
372 it returns @code{nil}.
375 @node Property Lists,, Creating Symbols, Symbols
376 @section Property Lists
377 @cindex property list
380 A @dfn{property list} (@dfn{plist} for short) is a list of paired
381 elements stored in the property list cell of a symbol. Each of the
382 pairs associates a property name (usually a symbol) with a property or
383 value. Property lists are generally used to record information about a
384 symbol, such as its documentation as a variable, the name of the file
385 where it was defined, or perhaps even the grammatical class of the
386 symbol (representing a word) in a language-understanding system.
388 Character positions in a string or buffer can also have property lists.
389 @xref{Text Properties}.
391 The property names and values in a property list can be any Lisp
392 objects, but the names are usually symbols. Property list functions
393 compare the property names using @code{eq}. Here is an example of a
394 property list, found on the symbol @code{progn} when the compiler is
398 (lisp-indent-function 0 byte-compile byte-compile-progn)
402 Here @code{lisp-indent-function} and @code{byte-compile} are property
403 names, and the other two elements are the corresponding values.
406 * Plists and Alists:: Comparison of the advantages of property
407 lists and association lists.
408 * Symbol Plists:: Functions to access symbols' property lists.
409 * Other Plists:: Accessing property lists stored elsewhere.
412 @node Plists and Alists
413 @subsection Property Lists and Association Lists
415 @cindex property lists vs association lists
416 Association lists (@pxref{Association Lists}) are very similar to
417 property lists. In contrast to association lists, the order of the
418 pairs in the property list is not significant since the property names
421 Property lists are better than association lists for attaching
422 information to various Lisp function names or variables. If your
423 program keeps all of its associations in one association list, it will
424 typically need to search that entire list each time it checks for an
425 association. This could be slow. By contrast, if you keep the same
426 information in the property lists of the function names or variables
427 themselves, each search will scan only the length of one property list,
428 which is usually short. This is why the documentation for a variable is
429 recorded in a property named @code{variable-documentation}. The byte
430 compiler likewise uses properties to record those functions needing
433 However, association lists have their own advantages. Depending on
434 your application, it may be faster to add an association to the front of
435 an association list than to update a property. All properties for a
436 symbol are stored in the same property list, so there is a possibility
437 of a conflict between different uses of a property name. (For this
438 reason, it is a good idea to choose property names that are probably
439 unique, such as by beginning the property name with the program's usual
440 name-prefix for variables and functions.) An association list may be
441 used like a stack where associations are pushed on the front of the list
442 and later discarded; this is not possible with a property list.
445 @subsection Property List Functions for Symbols
447 @defun symbol-plist symbol
448 This function returns the property list of @var{symbol}.
451 @defun setplist symbol plist
452 This function sets @var{symbol}'s property list to @var{plist}.
453 Normally, @var{plist} should be a well-formed property list, but this is
457 (setplist 'foo '(a 1 b (2 3) c nil))
458 @result{} (a 1 b (2 3) c nil)
460 @result{} (a 1 b (2 3) c nil)
463 For symbols in special obarrays, which are not used for ordinary
464 purposes, it may make sense to use the property list cell in a
465 nonstandard fashion; in fact, the abbrev mechanism does so
469 @defun get symbol property
470 This function finds the value of the property named @var{property} in
471 @var{symbol}'s property list. If there is no such property, @code{nil}
472 is returned. Thus, there is no distinction between a value of
473 @code{nil} and the absence of the property.
475 The name @var{property} is compared with the existing property names
476 using @code{eq}, so any object is a legitimate property.
478 See @code{put} for an example.
481 @defun put symbol property value
482 This function puts @var{value} onto @var{symbol}'s property list under
483 the property name @var{property}, replacing any previous property value.
484 The @code{put} function returns @var{value}.
487 (put 'fly 'verb 'transitive)
489 (put 'fly 'noun '(a buzzing little bug))
490 @result{} (a buzzing little bug)
494 @result{} (verb transitive noun (a buzzing little bug))
499 @subsection Property Lists Outside Symbols
501 These two functions are useful for manipulating property lists
502 that are stored in places other than symbols:
504 @defun plist-get plist property
505 This returns the value of the @var{property} property
506 stored in the property list @var{plist}. For example,
509 (plist-get '(foo 4) 'foo)
514 @defun plist-put plist property value
515 This stores @var{value} as the value of the @var{property} property in
516 the property list @var{plist}. It may modify @var{plist} destructively,
517 or it may construct a new list structure without altering the old. The
518 function returns the modified property list, so you can store that back
519 in the place where you got @var{plist}. For example,
522 (setq my-plist '(bar t foo 4))
523 @result{} (bar t foo 4)
524 (setq my-plist (plist-put my-plist 'foo 69))
525 @result{} (bar t foo 69)
526 (setq my-plist (plist-put my-plist 'quux '(a)))
527 @result{} (bar t foo 69 quux (a))
531 You could define @code{put} in terms of @code{plist-put} as follows:
534 (defun put (symbol prop value)
536 (plist-put (symbol-plist symbol) prop value)))