@c -*-texinfo-*-@c This is part of the GNU Emacs Lisp Reference Manual.@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.@c See the file elisp.texi for copying conditions.@setfilename ../info/symbols@node Symbols, Evaluation, Hash Tables, Top@chapter Symbols@cindex symbol A @dfn{symbol} is an object with a unique name. This chapterdescribes symbols, their components, their property lists, and how theyare created and interned. Separate chapters describe the use of symbolsas variables and as function names; see @ref{Variables}, and@ref{Functions}. For the precise read syntax for symbols, see@ref{Symbol Type}. You can test whether an arbitrary Lisp object is a symbolwith @code{symbolp}:@defun symbolp objectThis function returns @code{t} if @var{object} is a symbol, @code{nil}otherwise.@end defun@menu* Symbol Components:: Symbols have names, values, function definitions and property lists.* Definitions:: A definition says how a symbol will be used.* Creating Symbols:: How symbols are kept unique.* Property Lists:: Each symbol has a property list for recording miscellaneous information.@end menu@node Symbol Components, Definitions, Symbols, Symbols@section Symbol Components@cindex symbol components Each symbol has four components (or ``cells''), each of whichreferences another object:@table @asis@item Print name@cindex print name cellThe @dfn{print name cell} holds a string that names the symbol forreading and printing. See @code{symbol-name} in @ref{Creating Symbols}.@item Value@cindex value cellThe @dfn{value cell} holds the current value of the symbol as avariable. When a symbol is used as a form, the value of the form is thecontents of the symbol's value cell. See @code{symbol-value} in@ref{Accessing Variables}.@item Function@cindex function cellThe @dfn{function cell} holds the function definition of the symbol.When a symbol is used as a function, its function definition is used inits place. This cell is also used to make a symbol stand for a keymapor a keyboard macro, for editor command execution. Because each symbolhas separate value and function cells, variables names and function names donot conflict. See @code{symbol-function} in @ref{Function Cells}.@item Property list@cindex property list cellThe @dfn{property list cell} holds the property list of the symbol. See@code{symbol-plist} in @ref{Property Lists}.@end table The print name cell always holds a string, and cannot be changed. Theother three cells can be set individually to any specified Lisp object. The print name cell holds the string that is the name of the symbol.Since symbols are represented textually by their names, it is importantnot to have two symbols with the same name. The Lisp reader ensuresthis: every time it reads a symbol, it looks for an existing symbol withthe specified name before it creates a new one. (In GNU Emacs Lisp,this lookup uses a hashing algorithm and an obarray; see @ref{CreatingSymbols}.) The value cell holds the symbol's value as a variable(@pxref{Variables}). That is what you get if you evaluate the symbol asa Lisp expression (@pxref{Evaluation}). Any Lisp object is a legitimatevalue. Certain symbols have values that cannot be changed; theseinclude @code{nil} and @code{t}, and any symbol whose name starts with@samp{:} (those are called @dfn{keywords}). @xref{Constant Variables}. We often refer to ``the function @code{foo}'' when we really meanthe function stored in the function cell of the symbol @code{foo}. Wemake the distinction explicit only when necessary. In normalusage, the function cell usually contains a function(@pxref{Functions}) or a macro (@pxref{Macros}), as that is what theLisp interpreter expects to see there (@pxref{Evaluation}). Keyboardmacros (@pxref{Keyboard Macros}), keymaps (@pxref{Keymaps}) andautoload objects (@pxref{Autoloading}) are also sometimes stored inthe function cells of symbols. The property list cell normally should hold a correctly formattedproperty list (@pxref{Property Lists}), as a number of functions expectto see a property list there. The function cell or the value cell may be @dfn{void}, which meansthat the cell does not reference any object. (This is not the samething as holding the symbol @code{void}, nor the same as holding thesymbol @code{nil}.) Examining a function or value cell that is voidresults in an error, such as @samp{Symbol's value as variable is void}. The four functions @code{symbol-name}, @code{symbol-value},@code{symbol-plist}, and @code{symbol-function} return the contents ofthe four cells of a symbol. Here as an example we show the contents ofthe four cells of the symbol @code{buffer-file-name}:@example(symbol-name 'buffer-file-name) @result{} "buffer-file-name"(symbol-value 'buffer-file-name) @result{} "/gnu/elisp/symbols.texi"(symbol-function 'buffer-file-name) @result{} #<subr buffer-file-name>(symbol-plist 'buffer-file-name) @result{} (variable-documentation 29529)@end example@noindentBecause this symbol is the variable which holds the name of the filebeing visited in the current buffer, the value cell contents we see arethe name of the source file of this chapter of the Emacs Lisp Manual.The property list cell contains the list @code{(variable-documentation29529)} which tells the documentation functions where to find thedocumentation string for the variable @code{buffer-file-name} in the@file{DOC-@var{version}} file. (29529 is the offset from the beginningof the @file{DOC-@var{version}} file to where that documentation stringbegins---see @ref{Documentation Basics}.) The function cell containsthe function for returning the name of the file.@code{buffer-file-name} names a primitive function, which has no readsyntax and prints in hash notation (@pxref{Primitive Function Type}). Asymbol naming a function written in Lisp would have a lambda expression(or a byte-code object) in this cell.@node Definitions, Creating Symbols, Symbol Components, Symbols@section Defining Symbols@cindex definitions of symbols A @dfn{definition} in Lisp is a special form that announces yourintention to use a certain symbol in a particular way. In Emacs Lisp,you can define a symbol as a variable, or define it as a function (ormacro), or both independently. A definition construct typically specifies a value or meaning for thesymbol for one kind of use, plus documentation for its meaning when usedin this way. Thus, when you define a symbol as a variable, you cansupply an initial value for the variable, plus documentation for thevariable. @code{defvar} and @code{defconst} are special forms that define asymbol as a global variable. They are documented in detail in@ref{Defining Variables}. For defining user option variables that canbe customized, use @code{defcustom} (@pxref{Customization}). @code{defun} defines a symbol as a function, creating a lambdaexpression and storing it in the function cell of the symbol. Thislambda expression thus becomes the function definition of the symbol.(The term ``function definition,'' meaning the contents of the functioncell, is derived from the idea that @code{defun} gives the symbol itsdefinition as a function.) @code{defsubst} and @code{defalias} are twoother ways of defining a function. @xref{Functions}. @code{defmacro} defines a symbol as a macro. It creates a macroobject and stores it in the function cell of the symbol. Note that agiven symbol can be a macro or a function, but not both at once, becauseboth macro and function definitions are kept in the function cell, andthat cell can hold only one Lisp object at any given time.@xref{Macros}. In Emacs Lisp, a definition is not required in order to use a symbolas a variable or function. Thus, you can make a symbol a globalvariable with @code{setq}, whether you define it first or not. The realpurpose of definitions is to guide programmers and programming tools.They inform programmers who read the code that certain symbols are@emph{intended} to be used as variables, or as functions. In addition,utilities such as @file{etags} and @file{make-docfile} recognizedefinitions, and add appropriate information to tag tables and the@file{DOC-@var{version}} file. @xref{Accessing Documentation}.@node Creating Symbols, Property Lists, Definitions, Symbols@section Creating and Interning Symbols@cindex reading symbols To understand how symbols are created in GNU Emacs Lisp, you must knowhow Lisp reads them. Lisp must ensure that it finds the same symbolevery time it reads the same set of characters. Failure to do so wouldcause complete confusion.@cindex symbol name hashing@cindex hashing@cindex obarray@cindex bucket (in obarray) When the Lisp reader encounters a symbol, it reads all the charactersof the name. Then it ``hashes'' those characters to find an index in atable called an @dfn{obarray}. Hashing is an efficient method oflooking something up. For example, instead of searching a telephonebook cover to cover when looking up Jan Jones, you start with the J'sand go from there. That is a simple version of hashing. Each elementof the obarray is a @dfn{bucket} which holds all the symbols with agiven hash code; to look for a given name, it is sufficient to lookthrough all the symbols in the bucket for that name's hash code. (Thesame idea is used for general Emacs hash tables, but they are adifferent data type; see @ref{Hash Tables}.)@cindex interning If a symbol with the desired name is found, the reader uses thatsymbol. If the obarray does not contain a symbol with that name, thereader makes a new symbol and adds it to the obarray. Finding or addinga symbol with a certain name is called @dfn{interning} it, and thesymbol is then called an @dfn{interned symbol}. Interning ensures that each obarray has just one symbol with anyparticular name. Other like-named symbols may exist, but not in thesame obarray. Thus, the reader gets the same symbols for the samenames, as long as you keep reading with the same obarray. Interning usually happens automatically in the reader, but sometimesother programs need to do it. For example, after the @kbd{M-x} commandobtains the command name as a string using the minibuffer, it theninterns the string, to get the interned symbol with that name.@cindex symbol equality@cindex uninterned symbol No obarray contains all symbols; in fact, some symbols are not in anyobarray. They are called @dfn{uninterned symbols}. An uninternedsymbol has the same four cells as other symbols; however, the only wayto gain access to it is by finding it in some other object or as thevalue of a variable. Creating an uninterned symbol is useful in generating Lisp code,because an uninterned symbol used as a variable in the code you generatecannot clash with any variables used in other Lisp programs. In Emacs Lisp, an obarray is actually a vector. Each element of thevector is a bucket; its value is either an interned symbol whose namehashes to that bucket, or 0 if the bucket is empty. Each internedsymbol has an internal link (invisible to the user) to the next symbolin the bucket. Because these links are invisible, there is no way tofind all the symbols in an obarray except using @code{mapatoms} (below).The order of symbols in a bucket is not significant. In an empty obarray, every element is 0, so you can create an obarraywith @code{(make-vector @var{length} 0)}. @strong{This is the onlyvalid way to create an obarray.} Prime numbers as lengths tendto result in good hashing; lengths one less than a power of two are alsogood. @strong{Do not try to put symbols in an obarray yourself.} This doesnot work---only @code{intern} can enter a symbol in an obarray properly.@cindex CL note---symbol in obarrays@quotation@b{Common Lisp note:} In Common Lisp, a single symbol may be interned inseveral obarrays.@end quotation Most of the functions below take a name and sometimes an obarray asarguments. A @code{wrong-type-argument} error is signaled if the nameis not a string, or if the obarray is not a vector.@defun symbol-name symbolThis function returns the string that is @var{symbol}'s name. For example:@example@group(symbol-name 'foo) @result{} "foo"@end group@end example@strong{Warning:} Changing the string by substituting characters doeschange the name of the symbol, but fails to update the obarray, so don'tdo it!@end defun@defun make-symbol nameThis function returns a newly-allocated, uninterned symbol whose name is@var{name} (which must be a string). Its value and function definitionare void, and its property list is @code{nil}. In the example below,the value of @code{sym} is not @code{eq} to @code{foo} because it is adistinct uninterned symbol whose name is also @samp{foo}.@example(setq sym (make-symbol "foo")) @result{} foo(eq sym 'foo) @result{} nil@end example@end defun@defun intern name &optional obarrayThis function returns the interned symbol whose name is @var{name}. Ifthere is no such symbol in the obarray @var{obarray}, @code{intern}creates a new one, adds it to the obarray, and returns it. If@var{obarray} is omitted, the value of the global variable@code{obarray} is used.@example(setq sym (intern "foo")) @result{} foo(eq sym 'foo) @result{} t(setq sym1 (intern "foo" other-obarray)) @result{} foo(eq sym1 'foo) @result{} nil@end example@end defun@cindex CL note---interning existing symbol@quotation@b{Common Lisp note:} In Common Lisp, you can intern an existing symbolin an obarray. In Emacs Lisp, you cannot do this, because the argumentto @code{intern} must be a string, not a symbol.@end quotation@defun intern-soft name &optional obarrayThis function returns the symbol in @var{obarray} whose name is@var{name}, or @code{nil} if @var{obarray} has no symbol with that name.Therefore, you can use @code{intern-soft} to test whether a symbol witha given name is already interned. If @var{obarray} is omitted, thevalue of the global variable @code{obarray} is used.The argument @var{name} may also be a symbol; in that case,the function returns @var{name} if @var{name} is internedin the specified obarray, and otherwise @code{nil}.@smallexample(intern-soft "frazzle") ; @r{No such symbol exists.} @result{} nil(make-symbol "frazzle") ; @r{Create an uninterned one.} @result{} frazzle@group(intern-soft "frazzle") ; @r{That one cannot be found.} @result{} nil@end group@group(setq sym (intern "frazzle")) ; @r{Create an interned one.} @result{} frazzle@end group@group(intern-soft "frazzle") ; @r{That one can be found!} @result{} frazzle@end group@group(eq sym 'frazzle) ; @r{And it is the same one.} @result{} t@end group@end smallexample@end defun@defvar obarrayThis variable is the standard obarray for use by @code{intern} and@code{read}.@end defvar@defun mapatoms function &optional obarray@anchor{Definition of mapatoms}This function calls @var{function} once with each symbol in the obarray@var{obarray}. Then it returns @code{nil}. If @var{obarray} isomitted, it defaults to the value of @code{obarray}, the standardobarray for ordinary symbols.@smallexample(setq count 0) @result{} 0(defun count-syms (s) (setq count (1+ count))) @result{} count-syms(mapatoms 'count-syms) @result{} nilcount @result{} 1871@end smallexampleSee @code{documentation} in @ref{Accessing Documentation}, for anotherexample using @code{mapatoms}.@end defun@defun unintern symbol &optional obarrayThis function deletes @var{symbol} from the obarray @var{obarray}. If@code{symbol} is not actually in the obarray, @code{unintern} doesnothing. If @var{obarray} is @code{nil}, the current obarray is used.If you provide a string instead of a symbol as @var{symbol}, it standsfor a symbol name. Then @code{unintern} deletes the symbol (if any) inthe obarray which has that name. If there is no such symbol,@code{unintern} does nothing.If @code{unintern} does delete a symbol, it returns @code{t}. Otherwiseit returns @code{nil}.@end defun@node Property Lists,, Creating Symbols, Symbols@section Property Lists@cindex property list@cindex plist A @dfn{property list} (@dfn{plist} for short) is a list of pairedelements stored in the property list cell of a symbol. Each of thepairs associates a property name (usually a symbol) with a property orvalue. Property lists are generally used to record information about asymbol, such as its documentation as a variable, the name of the filewhere it was defined, or perhaps even the grammatical class of thesymbol (representing a word) in a language-understanding system. Character positions in a string or buffer can also have property lists.@xref{Text Properties}. The property names and values in a property list can be any Lispobjects, but the names are usually symbols. Property list functionscompare the property names using @code{eq}. Here is an example of aproperty list, found on the symbol @code{progn} when the compiler isloaded:@example(lisp-indent-function 0 byte-compile byte-compile-progn)@end example@noindentHere @code{lisp-indent-function} and @code{byte-compile} are propertynames, and the other two elements are the corresponding values.@menu* Plists and Alists:: Comparison of the advantages of property lists and association lists.* Symbol Plists:: Functions to access symbols' property lists.* Other Plists:: Accessing property lists stored elsewhere.@end menu@node Plists and Alists@subsection Property Lists and Association Lists@cindex plist vs. alist@cindex alist vs. plist@cindex property lists vs association lists Association lists (@pxref{Association Lists}) are very similar toproperty lists. In contrast to association lists, the order of thepairs in the property list is not significant since the property namesmust be distinct. Property lists are better than association lists for attachinginformation to various Lisp function names or variables. If yourprogram keeps all of its associations in one association list, it willtypically need to search that entire list each time it checks for anassociation. This could be slow. By contrast, if you keep the sameinformation in the property lists of the function names or variablesthemselves, each search will scan only the length of one property list,which is usually short. This is why the documentation for a variable isrecorded in a property named @code{variable-documentation}. The bytecompiler likewise uses properties to record those functions needingspecial treatment. However, association lists have their own advantages. Depending onyour application, it may be faster to add an association to the front ofan association list than to update a property. All properties for asymbol are stored in the same property list, so there is a possibilityof a conflict between different uses of a property name. (For thisreason, it is a good idea to choose property names that are probablyunique, such as by beginning the property name with the program's usualname-prefix for variables and functions.) An association list may beused like a stack where associations are pushed on the front of the listand later discarded; this is not possible with a property list.@node Symbol Plists@subsection Property List Functions for Symbols@defun symbol-plist symbolThis function returns the property list of @var{symbol}.@end defun@defun setplist symbol plistThis function sets @var{symbol}'s property list to @var{plist}.Normally, @var{plist} should be a well-formed property list, but this isnot enforced. The return value is @var{plist}.@smallexample(setplist 'foo '(a 1 b (2 3) c nil)) @result{} (a 1 b (2 3) c nil)(symbol-plist 'foo) @result{} (a 1 b (2 3) c nil)@end smallexampleFor symbols in special obarrays, which are not used for ordinarypurposes, it may make sense to use the property list cell in anonstandard fashion; in fact, the abbrev mechanism does so(@pxref{Abbrevs}).@end defun@defun get symbol propertyThis function finds the value of the property named @var{property} in@var{symbol}'s property list. If there is no such property, @code{nil}is returned. Thus, there is no distinction between a value of@code{nil} and the absence of the property.The name @var{property} is compared with the existing property namesusing @code{eq}, so any object is a legitimate property.See @code{put} for an example.@end defun@defun put symbol property valueThis function puts @var{value} onto @var{symbol}'s property list underthe property name @var{property}, replacing any previous property value.The @code{put} function returns @var{value}.@smallexample(put 'fly 'verb 'transitive) @result{}'transitive(put 'fly 'noun '(a buzzing little bug)) @result{} (a buzzing little bug)(get 'fly 'verb) @result{} transitive(symbol-plist 'fly) @result{} (verb transitive noun (a buzzing little bug))@end smallexample@end defun@node Other Plists@subsection Property Lists Outside Symbols These functions are useful for manipulating property liststhat are stored in places other than symbols:@defun plist-get plist propertyThis returns the value of the @var{property} propertystored in the property list @var{plist}. For example,@example(plist-get '(foo 4) 'foo) @result{} 4(plist-get '(foo 4 bad) 'foo) @result{} 4(plist-get '(foo 4 bad) 'bar) @result{} @code{wrong-type-argument} error@end exampleIt accepts a malformed @var{plist} argument and always returns @code{nil}if @var{property} is not found in the @var{plist}. For example,@example(plist-get '(foo 4 bad) 'bar) @result{} nil@end example@end defun@defun plist-put plist property valueThis stores @var{value} as the value of the @var{property} property inthe property list @var{plist}. It may modify @var{plist} destructively,or it may construct a new list structure without altering the old. Thefunction returns the modified property list, so you can store that backin the place where you got @var{plist}. For example,@example(setq my-plist '(bar t foo 4)) @result{} (bar t foo 4)(setq my-plist (plist-put my-plist 'foo 69)) @result{} (bar t foo 69)(setq my-plist (plist-put my-plist 'quux '(a))) @result{} (bar t foo 69 quux (a))@end example@end defun You could define @code{put} in terms of @code{plist-put} as follows:@example(defun put (symbol prop value) (setplist symbol (plist-put (symbol-plist symbol) prop value)))@end example@defun lax-plist-get plist propertyLike @code{plist-get} except that it compares propertiesusing @code{equal} instead of @code{eq}.@end defun@defun lax-plist-put plist property valueLike @code{plist-put} except that it compares propertiesusing @code{equal} instead of @code{eq}.@end defun@defun plist-member plist propertyThis returns non-@code{nil} if @var{plist} contains the given@var{property}. Unlike @code{plist-get}, this allows you to distinguishbetween a missing property and a property with the value @code{nil}.The value is actually the tail of @var{plist} whose @code{car} is@var{property}.@end defun@ignore arch-tag: 8750b7d2-de4c-4923-809a-d35fc39fd8ce@end ignore