# HG changeset patch # User Richard M. Stallman # Date 764038001 0 # Node ID aea7be7b925ca145274183f42a6e334ff62a1287 # Parent 3989978f6631c094237749477a625a34c719aca8 Initial revision diff -r 3989978f6631 -r aea7be7b925c lispref/symbols.texi --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/lispref/symbols.texi Sat Mar 19 00:46:41 1994 +0000 @@ -0,0 +1,454 @@ +@c -*-texinfo-*- +@c This is part of the GNU Emacs Lisp Reference Manual. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. +@c See the file elisp.texi for copying conditions. +@setfilename ../info/symbols +@node Symbols, Evaluation, Sequences Arrays Vectors, Top +@chapter Symbols +@cindex symbol + + A @dfn{symbol} is an object with a unique name. This chapter +describes symbols, their components, their property lists, and how they +are created and interned. Separate chapters describe the use of symbols +as 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 symbol +with @code{symbolp}: + +@defun symbolp object +This 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 which +references another object: + +@table @asis +@item Print name +@cindex print name cell +The @dfn{print name cell} holds a string which names the symbol for +reading and printing. See @code{symbol-name} in @ref{Creating Symbols}. + +@item Value +@cindex value cell +The @dfn{value cell} holds the current value of the symbol as a +variable. When a symbol is used as a form, the value of the form is the +contents of the symbol's value cell. See @code{symbol-value} in +@ref{Accessing Variables}. + +@item Function +@cindex function cell +The @dfn{function cell} holds the function definition of the symbol. +When a symbol is used as a function, its function definition is used in +its place. This cell is also used to make a symbol stand for a keymap +or a keyboard macro, for editor command execution. Because each symbol +has separate value and function cells, variables and function names do +not conflict. See @code{symbol-function} in @ref{Function Cells}. + +@item Property list +@cindex property list cell +The @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. The +other 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 important +not to have two symbols with the same name. The Lisp reader ensures +this: every time it reads a symbol, it looks for an existing symbol with +the specified name before it creates a new one. (In GNU Emacs Lisp, +this lookup uses a hashing algorithm and an obarray; see @ref{Creating +Symbols}.) + + In normal usage, the function cell usually contains a function or +macro, as that is what the Lisp interpreter expects to see there +(@pxref{Evaluation}). Keyboard macros (@pxref{Keyboard Macros}), +keymaps (@pxref{Keymaps}) and autoload objects (@pxref{Autoloading}) are +also sometimes stored in the function cell of symbols. We often refer +to ``the function @code{foo}'' when we really mean the function stored +in the function cell of the symbol @code{foo}. We make the distinction +only when necessary. + + The property list cell normally should hold a correctly formatted +property list (@pxref{Property Lists}), as a number of functions expect +to see a property list there. + + The function cell or the value cell may be @dfn{void}, which means +that the cell does not reference any object. (This is not the same +thing as holding the symbol @code{void}, nor the same as holding the +symbol @code{nil}.) Examining a cell which is void results 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 of +the four cells of a symbol. Here as an example we show the contents of +the 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-plist 'buffer-file-name) + @result{} (variable-documentation 29529) +(symbol-function 'buffer-file-name) + @result{} # +@end example + +@noindent +Because this symbol is the variable which holds the name of the file +being visited in the current buffer, the value cell contents we see are +the name of the source file of this chapter of the Emacs Lisp Manual. +The property list cell contains the list @code{(variable-documentation +29529)} which tells the documentation functions where to find the +documentation string for the variable @code{buffer-file-name} in the +@file{DOC} file. (29529 is the offset from the beginning of the +@file{DOC} file to where that documentation string begins.) The +function cell contains the function for returning the name of the file. +@code{buffer-file-name} names a primitive function, which has no read +syntax and prints in hash notation (@pxref{Primitive Function Type}). A +symbol 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 definition of a symbol + + A @dfn{definition} in Lisp is a special form that announces your +intention 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 (or +macro), or both independently. + + A definition construct typically specifies a value or meaning for the +symbol for one kind of use, plus documentation for its meaning when used +in this way. Thus, when you define a symbol as a variable, you can +supply an initial value for the variable, plus documentation for the +variable. + + @code{defvar} and @code{defconst} are special forms that define a +symbol as a global variable. They are documented in detail in +@ref{Defining Variables}. + + @code{defun} defines a symbol as a function, creating a lambda +expression and storing it in the function cell of the symbol. This +lambda expression thus becomes the function definition of the symbol. +(The term ``function definition'', meaning the contents of the function +cell, is derived from the idea that @code{defun} gives the symbol its +definition as a function.) @xref{Functions}. + + @code{defmacro} defines a symbol as a macro. It creates a macro +object and stores it in the function cell of the symbol. Note that a +given symbol can be a macro or a function, but not both at once, because +both macro and function definitions are kept in the function cell, and +that cell can hold only one Lisp object at any given time. +@xref{Macros}. + + In GNU Emacs Lisp, a definition is not required in order to use a +symbol as a variable or function. Thus, you can make a symbol a global +variable with @code{setq}, whether you define it first or not. The real +purpose 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} recognize +definitions, and add appropriate information to tag tables and the +@file{emacs/etc/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 know +how Lisp reads them. Lisp must ensure that it finds the same symbol +every time it reads the same set of characters. Failure to do so would +cause 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 characters +of the name. Then it ``hashes'' those characters to find an index in a +table called an @dfn{obarray}. Hashing is an efficient method of +looking something up. For example, instead of searching a telephone +book cover to cover when looking up Jan Jones, you start with the J's +and go from there. That is a simple version of hashing. Each element +of the obarray is a @dfn{bucket} which holds all the symbols with a +given hash code; to look for a given name, it is sufficient to look +through all the symbols in the bucket for that name's hash code. + +@cindex interning + If a symbol with the desired name is found, then it is used. If no +such symbol is found, then a new symbol is created and added to the +obarray bucket. Adding a symbol to an obarray is called @dfn{interning} +it, and the symbol is then called an @dfn{interned symbol}. + +@cindex symbol equality +@cindex uninterned symbol + If a symbol is not in the obarray, then there is no way for Lisp to +find it when its name is read. Such a symbol is called an +@dfn{uninterned symbol} relative to the obarray. An uninterned symbol +has all the other characteristics of interned symbols; it has the same +four cells and they work in the usual way. + + In Emacs Lisp, an obarray is actually a vector. Each element of the +vector is a bucket; its value is either an interned symbol whose name +hashes to that bucket, or 0 if the bucket is empty. Each interned +symbol has an internal link (invisible to the user) to the next symbol +in the bucket. Because these links are invisible, there is no way to +find 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, and you can create an obarray +with @code{(make-vector @var{length} 0)}. @strong{This is the only +valid way to create an obarray.} Prime numbers as lengths tend +to result in good hashing; lengths one less than a power of two are also +good. + + @strong{Do not try to put symbols in an obarray yourself.} This does +not work---only @code{intern} can enter a symbol in an obarray properly. +@strong{Do not try to intern one symbol in two obarrays.} This would +garble both obarrays, because a symbol has just one slot to hold the +following symbol in the obarray bucket. The results would be +unpredictable. + + It is possible for two different symbols to have the same name in +different obarrays; these symbols are not @code{eq} or @code{equal}. +However, this normally happens only as part of the abbrev mechanism +(@pxref{Abbrevs}). + +@cindex CL note---symbol in obarrays +@quotation +@b{Common Lisp note:} in Common Lisp, a single symbol may be interned in +several obarrays. +@end quotation + + Most of the functions below take a name and sometimes an obarray as +arguments. A @code{wrong-type-argument} error is signaled if the name +is not a string, or if the obarray is not a vector. + +@defun symbol-name symbol +This function returns the string that is @var{symbol}'s name. For example: + +@example +@group +(symbol-name 'foo) + @result{} "foo" +@end group +@end example + +Changing the string by substituting characters, etc, does change the +name of the symbol, but fails to update the obarray, so don't do it! +@end defun + +@defun make-symbol name +This function returns a newly-allocated, uninterned symbol whose name is +@var{name} (which must be a string). Its value and function definition +are 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 a +distinct 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 obarray +This function returns the interned symbol whose name is @var{name}. If +there 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 sym 'foo) + @result{} nil +@end example +@end defun + +@defun intern-soft name &optional obarray +This 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 with +a given name is already interned. If @var{obarray} is omitted, the +value of the global variable @code{obarray} is used. + +@smallexample +(intern-soft "frazzle") ; @r{No such symbol exists.} + @result{} nil +(make-symbol "frazzle") ; @r{Create an uninterned one.} + @result{} frazzle +(intern-soft "frazzle") ; @r{That one cannot be found.} + @result{} nil +(setq sym (intern "frazzle")) ; @r{Create an interned one.} + @result{} frazzle +(intern-soft "frazzle") ; @r{That one can be found!} + @result{} frazzle +@group +(eq sym 'frazzle) ; @r{And it is the same one.} + @result{} t +@end group +@end smallexample +@end defun + +@defvar obarray +This variable is the standard obarray for use by @code{intern} and +@code{read}. +@end defvar + +@defun mapatoms function &optional obarray +This function call @var{function} for each symbol in the obarray +@var{obarray}. It returns @code{nil}. If @var{obarray} is omitted, it +defaults to the value of @code{obarray}, the standard obarray for +ordinary symbols. + +@smallexample +(setq count 0) + @result{} 0 +(defun count-syms (s) + (setq count (1+ count))) + @result{} count-syms +(mapatoms 'count-syms) + @result{} nil +count + @result{} 1871 +@end smallexample + +See @code{documentation} in @ref{Accessing Documentation}, for another +example using @code{mapatoms}. +@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 paired +elements stored in the property list cell of a symbol. Each of the +pairs associates a property name (usually a symbol) with a property or +value. Property lists are generally used to record information about a +symbol, such as how to compile it, the name of the file where it was +defined, or perhaps even the grammatical class of the symbol +(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 Lisp +objects, but the names are usually symbols. They are compared using +@code{eq}. Here is an example of a property list, found on the symbol +@code{progn} when the compiler is loaded: + +@example +(lisp-indent-function 0 byte-compile byte-compile-progn) +@end example + +@noindent +Here @code{lisp-indent-function} and @code{byte-compile} are property +names, and the other two elements are the corresponding values. + +@cindex property lists vs association lists + Association lists (@pxref{Association Lists}) are very similar to +property lists. In contrast to association lists, the order of the +pairs in the property list is not significant since the property names +must be distinct. + + Property lists are better than association lists for attaching +information to various Lisp function names or variables. If all the +associations are recorded in one association list, the program will need +to search that entire list each time a function or variable is to be +operated on. By contrast, if the information is recorded in the +property lists of the function names or variables themselves, each +search will scan only the length of one property list, which is usually +short. This is why the documentation for a variable is recorded in a +property named @code{variable-documentation}. The byte compiler +likewise uses properties to record those functions needing special +treatment. + + However, association lists have their own advantages. Depending on +your application, it may be faster to add an association to the front of +an association list than to update a property. All properties for a +symbol are stored in the same property list, so there is a possibility +of a conflict between different uses of a property name. (For this +reason, it is a good idea to choose property names that are probably +unique, such as by including the name of the library in the property +name.) An association list may be used like a stack where associations +are pushed on the front of the list and later discarded; this is not +possible with a property list. + +@defun symbol-plist symbol +This function returns the property list of @var{symbol}. +@end defun + +@defun setplist symbol plist + This function sets @var{symbol}'s property list to @var{plist}. +Normally, @var{plist} should be a well-formed property list, but this is +not enforced. + +@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 smallexample + +For symbols in special obarrays, which are not used for ordinary +purposes, it may make sense to use the property list cell in a +nonstandard fashion; in fact, the abbrev mechanism does so +(@pxref{Abbrevs}). +@end defun + +@defun get symbol property +This 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 names +using @code{eq}, so any object is a legitimate property. + +See @code{put} for an example. +@end defun + +@defun put symbol property value +This function puts @var{value} onto @var{symbol}'s property list under +the 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