Fix bug #11035 with cursor positioning on overlay strings with newlines.
[emacs.git] / doc / lispref / symbols.texi
blob0ee22b905b61046060af9fa253915fe80a83f5e0
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2012  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
7 @chapter Symbols
8 @cindex symbol
10   A @dfn{symbol} is an object with a unique name.  This chapter
11 describes symbols, their components, their property lists, and how they
12 are created and interned.  Separate chapters describe the use of symbols
13 as variables and as function names; see @ref{Variables}, and
14 @ref{Functions}.  For the precise read syntax for symbols, see
15 @ref{Symbol Type}.
17   You can test whether an arbitrary Lisp object is a symbol
18 with @code{symbolp}:
20 @defun symbolp object
21 This function returns @code{t} if @var{object} is a symbol, @code{nil}
22 otherwise.
23 @end defun
25 @menu
26 * Symbol Components::        Symbols have names, values, function definitions
27                                and property lists.
28 * Definitions::              A definition says how a symbol will be used.
29 * Creating Symbols::         How symbols are kept unique.
30 * Property Lists::           Each symbol has a property list
31                                for recording miscellaneous information.
32 @end menu
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:
41 @table @asis
42 @item Print name
43 @cindex print name cell
44 The symbol's name.
46 @item Value
47 @cindex value cell
48 The symbol's current value as a variable.
50 @item Function
51 @cindex function cell
52 The symbol's function definition.  It can also hold a symbol, a
53 keymap, or a keyboard macro.
55 @item Property list
56 @cindex property list cell
57 The symbol's property list.
58 @end table
60 @noindent
61 The print name cell always holds a string, and cannot be changed.
62 Each of the other three cells can be set to any Lisp object.
64   The print name cell holds the string that is the name of a symbol.
65 Since symbols are represented textually by their names, it is
66 important not to have two symbols with the same name.  The Lisp reader
67 ensures this: every time it reads a symbol, it looks for an existing
68 symbol with the specified name before it creates a new one.  To get a
69 symbol's name, use the function @code{symbol-name} (@pxref{Creating
70 Symbols}).
72   The value cell holds a symbol's value as a variable, which is what
73 you get if the symbol itself is evaluated as a Lisp expression.
74 @xref{Variables}, for details about how values are set and retrieved,
75 including complications such as @dfn{local bindings} and @dfn{scoping
76 rules}.  Most symbols can have any Lisp object as a value, but certain
77 special symbols have values that cannot be changed; these include
78 @code{nil} and @code{t}, and any symbol whose name starts with
79 @samp{:} (those are called @dfn{keywords}).  @xref{Constant
80 Variables}.
82   The function cell holds a symbol's function definition.  Often, we
83 refer to ``the function @code{foo}'' when we really mean the function
84 stored in the function cell of @code{foo}; we make the distinction
85 explicit only when necessary.  Typically, the function cell is used to
86 hold a function (@pxref{Functions}) or a macro (@pxref{Macros}).
87 However, it can also be used to hold a symbol (@pxref{Function
88 Indirection}), keyboard macro (@pxref{Keyboard Macros}), keymap
89 (@pxref{Keymaps}), or autoload object (@pxref{Autoloading}).  To get
90 the contents of a symbol's function cell, use the function
91 @code{symbol-function} (@pxref{Function Cells}).
93   The property list cell normally should hold a correctly formatted
94 property list.  To get a symbol's function cell, use the function
95 @code{symbol-plist}.  @xref{Property Lists}.
97   The function cell or the value cell may be @dfn{void}, which means
98 that the cell does not reference any object.  (This is not the same
99 thing as holding the symbol @code{void}, nor the same as holding the
100 symbol @code{nil}.)  Examining a function or value cell that is void
101 results in an error, such as @samp{Symbol's value as variable is void}.
103   Because each symbol has separate value and function cells, variables
104 names and function names do not conflict.  For example, the symbol
105 @code{buffer-file-name} has a value (the name of the file being
106 visited in the current buffer) as well as a function definition (a
107 primitive function that returns the name of the file):
109 @example
110 buffer-file-name
111      @result{} "/gnu/elisp/symbols.texi"
112 (symbol-function 'buffer-file-name)
113      @result{} #<subr buffer-file-name>
114 @end example
116 @node Definitions, Creating Symbols, Symbol Components, Symbols
117 @section Defining Symbols
118 @cindex definitions of symbols
120   A @dfn{definition} is a special kind of Lisp expression that
121 announces your intention to use a symbol in a particular way.  It
122 typically specifies a value or meaning for the symbol for one kind of
123 use, plus documentation for its meaning when used in this way.  Thus,
124 when you define a symbol as a variable, you can supply an initial
125 value for the variable, plus documentation for the variable.
127   @code{defvar} and @code{defconst} are special forms that define a
128 symbol as a @dfn{global variable}---a variable that can be accessed at
129 any point in a Lisp program.  @xref{Variables}, for details about
130 variables.  To define a customizable variable, use the
131 @code{defcustom} macro, which also calls @code{defvar} as a subroutine
132 (@pxref{Customization}).
134   In principle, you can assign a variable value to any symbol with
135 @code{setq}, whether not it has first been defined as a variable.
136 However, you ought to write a variable definition for each global
137 variable that you want to use; otherwise, your Lisp program may not
138 act correctly if it is evaluated with lexical scoping enabled
139 (@pxref{Variable Scoping}).
141   @code{defun} defines a symbol as a function, creating a lambda
142 expression and storing it in the function cell of the symbol.  This
143 lambda expression thus becomes the function definition of the symbol.
144 (The term ``function definition,'' meaning the contents of the function
145 cell, is derived from the idea that @code{defun} gives the symbol its
146 definition as a function.)  @code{defsubst} and @code{defalias} are two
147 other ways of defining a function.  @xref{Functions}.
149   @code{defmacro} defines a symbol as a macro.  It creates a macro
150 object and stores it in the function cell of the symbol.  Note that a
151 given symbol can be a macro or a function, but not both at once, because
152 both macro and function definitions are kept in the function cell, and
153 that cell can hold only one Lisp object at any given time.
154 @xref{Macros}.
156   As previously noted, Emacs Lisp allows the same symbol to be defined
157 both as a variable (e.g.@: with @code{defvar}) and as a function or
158 macro (e.g.@: with @code{defun}).  Such definitions do not conflict.
160   These definition also act as guides for programming tools.  For
161 example, the @kbd{C-h f} and @kbd{C-h v} commands create help buffers
162 containing links to the relevant variable, function, or macro
163 definitions.  @xref{Name Help,,, emacs, The GNU Emacs Manual}.
165 @node Creating Symbols, Property Lists, Definitions, Symbols
166 @section Creating and Interning Symbols
167 @cindex reading symbols
169   To understand how symbols are created in GNU Emacs Lisp, you must know
170 how Lisp reads them.  Lisp must ensure that it finds the same symbol
171 every time it reads the same set of characters.  Failure to do so would
172 cause complete confusion.
174 @cindex symbol name hashing
175 @cindex hashing
176 @cindex obarray
177 @cindex bucket (in obarray)
178   When the Lisp reader encounters a symbol, it reads all the characters
179 of the name.  Then it ``hashes'' those characters to find an index in a
180 table called an @dfn{obarray}.  Hashing is an efficient method of
181 looking something up.  For example, instead of searching a telephone
182 book cover to cover when looking up Jan Jones, you start with the J's
183 and go from there.  That is a simple version of hashing.  Each element
184 of the obarray is a @dfn{bucket} which holds all the symbols with a
185 given hash code; to look for a given name, it is sufficient to look
186 through all the symbols in the bucket for that name's hash code.  (The
187 same idea is used for general Emacs hash tables, but they are a
188 different data type; see @ref{Hash Tables}.)
190 @cindex interning
191   If a symbol with the desired name is found, the reader uses that
192 symbol.  If the obarray does not contain a symbol with that name, the
193 reader makes a new symbol and adds it to the obarray.  Finding or adding
194 a symbol with a certain name is called @dfn{interning} it, and the
195 symbol is then called an @dfn{interned symbol}.
197   Interning ensures that each obarray has just one symbol with any
198 particular name.  Other like-named symbols may exist, but not in the
199 same obarray.  Thus, the reader gets the same symbols for the same
200 names, as long as you keep reading with the same obarray.
202   Interning usually happens automatically in the reader, but sometimes
203 other programs need to do it.  For example, after the @kbd{M-x} command
204 obtains the command name as a string using the minibuffer, it then
205 interns the string, to get the interned symbol with that name.
207 @cindex symbol equality
208 @cindex uninterned symbol
209   No obarray contains all symbols; in fact, some symbols are not in any
210 obarray.  They are called @dfn{uninterned symbols}.  An uninterned
211 symbol has the same four cells as other symbols; however, the only way
212 to gain access to it is by finding it in some other object or as the
213 value of a variable.
215   Creating an uninterned symbol is useful in generating Lisp code,
216 because an uninterned symbol used as a variable in the code you generate
217 cannot clash with any variables used in other Lisp programs.
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, so you can create an obarray
228 with @code{(make-vector @var{length} 0)}.  @strong{This is the only
229 valid way to create an obarray.}  Prime numbers as lengths tend
230 to result in good hashing; lengths one less than a power of two are also
231 good.
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
237 @quotation
238 @b{Common Lisp note:} Unlike Common Lisp, Emacs Lisp does not provide
239 for interning a single symbol in several obarrays.
240 @end quotation
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:
249 @example
250 @group
251 (symbol-name 'foo)
252      @result{} "foo"
253 @end group
254 @end 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
258 do it!
259 @end defun
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}.
268 @example
269 (setq sym (make-symbol "foo"))
270      @result{} foo
271 (eq sym 'foo)
272      @result{} nil
273 @end example
274 @end defun
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.
283 @example
284 (setq sym (intern "foo"))
285      @result{} foo
286 (eq sym 'foo)
287      @result{} t
289 (setq sym1 (intern "foo" other-obarray))
290      @result{} foo
291 (eq sym1 'foo)
292      @result{} nil
293 @end example
294 @end defun
296 @cindex CL note---interning existing symbol
297 @quotation
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.
301 @end quotation
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.
310 The argument @var{name} may also be a symbol; in that case,
311 the function returns @var{name} if @var{name} is interned
312 in the specified obarray, and otherwise @code{nil}.
314 @smallexample
315 (intern-soft "frazzle")        ; @r{No such symbol exists.}
316      @result{} nil
317 (make-symbol "frazzle")        ; @r{Create an uninterned one.}
318      @result{} frazzle
319 @group
320 (intern-soft "frazzle")        ; @r{That one cannot be found.}
321      @result{} nil
322 @end group
323 @group
324 (setq sym (intern "frazzle"))  ; @r{Create an interned one.}
325      @result{} frazzle
326 @end group
327 @group
328 (intern-soft "frazzle")        ; @r{That one can be found!}
329      @result{} frazzle
330 @end group
331 @group
332 (eq sym 'frazzle)              ; @r{And it is the same one.}
333      @result{} t
334 @end group
335 @end smallexample
336 @end defun
338 @defvar obarray
339 This variable is the standard obarray for use by @code{intern} and
340 @code{read}.
341 @end defvar
343 @defun mapatoms function &optional obarray
344 @anchor{Definition of mapatoms}
345 This function calls @var{function} once with each symbol in the obarray
346 @var{obarray}.  Then it returns @code{nil}.  If @var{obarray} is
347 omitted, it defaults to the value of @code{obarray}, the standard
348 obarray for ordinary symbols.
350 @smallexample
351 (setq count 0)
352      @result{} 0
353 (defun count-syms (s)
354   (setq count (1+ count)))
355      @result{} count-syms
356 (mapatoms 'count-syms)
357      @result{} nil
358 count
359      @result{} 1871
360 @end smallexample
362 See @code{documentation} in @ref{Accessing Documentation}, for another
363 example using @code{mapatoms}.
364 @end defun
366 @defun unintern symbol obarray
367 This function deletes @var{symbol} from the obarray @var{obarray}.  If
368 @code{symbol} is not actually in the obarray, @code{unintern} does
369 nothing.  If @var{obarray} is @code{nil}, the current obarray is used.
371 If you provide a string instead of a symbol as @var{symbol}, it stands
372 for a symbol name.  Then @code{unintern} deletes the symbol (if any) in
373 the obarray which has that name.  If there is no such symbol,
374 @code{unintern} does nothing.
376 If @code{unintern} does delete a symbol, it returns @code{t}.  Otherwise
377 it returns @code{nil}.
378 @end defun
380 @node Property Lists,, Creating Symbols, Symbols
381 @section Property Lists
382 @cindex property list
383 @cindex plist
385   A @dfn{property list} (@dfn{plist} for short) is a list of paired
386 elements.  Each of the pairs associates a property name (usually a
387 symbol) with a property or value.
389   Every symbol has a cell that stores a property list (@pxref{Symbol
390 Components}).  This property list is used to record information about
391 the symbol, such as its variable documentation and the name of the
392 file where it was defined.
394   Property lists can also be used in other contexts.  For instance,
395 you can assign property lists to character positions in a string or
396 buffer.  @xref{Text Properties}.
398   The property names and values in a property list can be any Lisp
399 objects, but the names are usually symbols.  Property list functions
400 compare the property names using @code{eq}.  Here is an example of a
401 property list, found on the symbol @code{progn} when the compiler is
402 loaded:
404 @example
405 (lisp-indent-function 0 byte-compile byte-compile-progn)
406 @end example
408 @noindent
409 Here @code{lisp-indent-function} and @code{byte-compile} are property
410 names, and the other two elements are the corresponding values.
412 @menu
413 * Plists and Alists::           Comparison of the advantages of property
414                                   lists and association lists.
415 * Symbol Plists::               Functions to access symbols' property lists.
416 * Other Plists::                Accessing property lists stored elsewhere.
417 @end menu
419 @node Plists and Alists
420 @subsection Property Lists and Association Lists
421 @cindex plist vs. alist
422 @cindex alist vs. plist
424 @cindex property lists vs association lists
425   Association lists (@pxref{Association Lists}) are very similar to
426 property lists.  In contrast to association lists, the order of the
427 pairs in the property list is not significant since the property names
428 must be distinct.
430   Property lists are better than association lists for attaching
431 information to various Lisp function names or variables.  If your
432 program keeps all such information in one association list, it will
433 typically need to search that entire list each time it checks for an
434 association for a particular Lisp function name or variable, which
435 could be slow.  By contrast, if you keep the same information in the
436 property lists of the function names or variables themselves, each
437 search will scan only the length of one property list, which is
438 usually short.  This is why the documentation for a variable is
439 recorded in a property named @code{variable-documentation}.  The byte
440 compiler likewise uses properties to record those functions needing
441 special treatment.
443   However, association lists have their own advantages.  Depending on
444 your application, it may be faster to add an association to the front of
445 an association list than to update a property.  All properties for a
446 symbol are stored in the same property list, so there is a possibility
447 of a conflict between different uses of a property name.  (For this
448 reason, it is a good idea to choose property names that are probably
449 unique, such as by beginning the property name with the program's usual
450 name-prefix for variables and functions.)  An association list may be
451 used like a stack where associations are pushed on the front of the list
452 and later discarded; this is not possible with a property list.
454 @node Symbol Plists
455 @subsection Property List Functions for Symbols
457 @defun symbol-plist symbol
458 This function returns the property list of @var{symbol}.
459 @end defun
461 @defun setplist symbol plist
462 This function sets @var{symbol}'s property list to @var{plist}.
463 Normally, @var{plist} should be a well-formed property list, but this is
464 not enforced.  The return value is @var{plist}.
466 @smallexample
467 (setplist 'foo '(a 1 b (2 3) c nil))
468      @result{} (a 1 b (2 3) c nil)
469 (symbol-plist 'foo)
470      @result{} (a 1 b (2 3) c nil)
471 @end smallexample
473 For symbols in special obarrays, which are not used for ordinary
474 purposes, it may make sense to use the property list cell in a
475 nonstandard fashion; in fact, the abbrev mechanism does so
476 (@pxref{Abbrevs}).
477 @end defun
479 @defun get symbol property
480 This function finds the value of the property named @var{property} in
481 @var{symbol}'s property list.  If there is no such property, @code{nil}
482 is returned.  Thus, there is no distinction between a value of
483 @code{nil} and the absence of the property.
485 The name @var{property} is compared with the existing property names
486 using @code{eq}, so any object is a legitimate property.
488 See @code{put} for an example.
489 @end defun
491 @defun put symbol property value
492 This function puts @var{value} onto @var{symbol}'s property list under
493 the property name @var{property}, replacing any previous property value.
494 The @code{put} function returns @var{value}.
496 @smallexample
497 (put 'fly 'verb 'transitive)
498      @result{}'transitive
499 (put 'fly 'noun '(a buzzing little bug))
500      @result{} (a buzzing little bug)
501 (get 'fly 'verb)
502      @result{} transitive
503 (symbol-plist 'fly)
504      @result{} (verb transitive noun (a buzzing little bug))
505 @end smallexample
506 @end defun
508 @node Other Plists
509 @subsection Property Lists Outside Symbols
511   These functions are useful for manipulating property lists
512 that are stored in places other than symbols:
514 @defun plist-get plist property
515 This returns the value of the @var{property} property stored in the
516 property list @var{plist}.  It accepts a malformed @var{plist}
517 argument.  If @var{property} is not found in the @var{plist}, it
518 returns @code{nil}.  For example,
520 @example
521 (plist-get '(foo 4) 'foo)
522      @result{} 4
523 (plist-get '(foo 4 bad) 'foo)
524      @result{} 4
525 (plist-get '(foo 4 bad) 'bad)
526      @result{} nil
527 (plist-get '(foo 4 bad) 'bar)
528      @result{} nil
529 @end example
530 @end defun
532 @defun plist-put plist property value
533 This stores @var{value} as the value of the @var{property} property in
534 the property list @var{plist}.  It may modify @var{plist} destructively,
535 or it may construct a new list structure without altering the old.  The
536 function returns the modified property list, so you can store that back
537 in the place where you got @var{plist}.  For example,
539 @example
540 (setq my-plist '(bar t foo 4))
541      @result{} (bar t foo 4)
542 (setq my-plist (plist-put my-plist 'foo 69))
543      @result{} (bar t foo 69)
544 (setq my-plist (plist-put my-plist 'quux '(a)))
545      @result{} (bar t foo 69 quux (a))
546 @end example
547 @end defun
549   You could define @code{put} in terms of @code{plist-put} as follows:
551 @example
552 (defun put (symbol prop value)
553   (setplist symbol
554             (plist-put (symbol-plist symbol) prop value)))
555 @end example
557 @defun lax-plist-get plist property
558 Like @code{plist-get} except that it compares properties
559 using @code{equal} instead of @code{eq}.
560 @end defun
562 @defun lax-plist-put plist property value
563 Like @code{plist-put} except that it compares properties
564 using @code{equal} instead of @code{eq}.
565 @end defun
567 @defun plist-member plist property
568 This returns non-@code{nil} if @var{plist} contains the given
569 @var{property}.  Unlike @code{plist-get}, this allows you to distinguish
570 between a missing property and a property with the value @code{nil}.
571 The value is actually the tail of @var{plist} whose @code{car} is
572 @var{property}.
573 @end defun