@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc. 
@c See the file elisp.texi for copying conditions.
@setfilename ../info/symbols
@node Symbols, Evaluation, Sequences Arrays Vectors, Top
@c @chapter Symbols
@chapter $B%7%s%\%k(B
@c @cindex symbol
@cindex $B%7%s%\%k(B

@c   A @dfn{symbol} is an object with a unique name.  This chapter
@c describes symbols, their components, their property lists, and how they
@c are created and interned.  Separate chapters describe the use of symbols
@c as variables and as function names; see @ref{Variables}, and
@c @ref{Functions}.  For the precise read syntax for symbols, see
@c @ref{Symbol Type}.
@dfn{$B%7%s%\%k(B}$B!J(Bsymbol$B!K$H$O!"0l0U$JL>A0$,IU$$$?%*%V%8%'%/%H$G$9!#(B
$BK\>O$G$O!"%7%s%\%k!"$=$N9=@.MWAG!"B0@-%j%9%H!":n@.J}K!$H%$%s%?!<%sJ}K!$K(B
$B$D$$$F@bL@$7$^$9!#(B
$B%7%s%\%k$NJQ?t$H$7$F$N;HMQJ}K!!"4X?tL>$H$7$F$N;HMQJ}K!$K$D$$$F@bL@$7$?(B
$BJL$N>O$b$"$j$^$9!#(B
@ref{Variables}$B$H(B@xref{Functions}$B!#(B
$B%7%s%\%k$N@53N$JF~NO9=J8$K$D$$$F$O!"(B@xref{Symbol Type}$B!#(B

@c   You can test whether an arbitrary Lisp object is a symbol
@c with @code{symbolp}:
@code{symbolp}$B$G!"G$0U$N(BLisp$B%*%V%8%'%/%H$,%7%s%\%k$+$I$&$+D4$Y$i$l$^$9!#(B

@defun symbolp object
@c This function returns @code{t} if @var{object} is a symbol, @code{nil}
@c otherwise.
$B$3$N4X?t$O!"(B@var{object}$B$,%7%s%\%k$J$i$P(B@code{t}$B$rJV$7!"(B
$B$5$b$J$1$l$P(B@code{nil}$B$rJV$9!#(B
@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
@c @section Symbol Components
@section $B%7%s%\%k$N9=@.MWAG(B
@c @cindex symbol components
@cindex $B%7%s%\%k$N9=@.MWAG(B

@c   Each symbol has four components (or ``cells''), each of which
@c references another object:
$B3F%7%s%\%k$K$O(B4$B$D$N9=@.MWAG!J$D$^$j!"!X%;%k!Y!K$,$"$j!"(B
$B$=$l$>$l$GJL$N%*%V%8%'%/%H$r;2>H$7$^$9!#(B

@table @asis
@c @item Print name
@item $BI=<(L>!J(Bprint name$B!K(B
@c @cindex print name cell
@cindex $BI=<(L>(B
@c The @dfn{print name cell} holds a string that names the symbol for
@c reading and printing.  See @code{symbol-name} in @ref{Creating Symbols}.
@dfn{$BI=<(L>%;%k(B}$B!J(Bprint name cell$B!K$K$O!"(B
$B%7%s%\%k$NF~NO$dI=<($K;H$&L>A0$G$"$kJ8;zNs$,F~$C$F$$$k!#(B
@ref{Creating Symbols}$B$N(B@code{symbol-name}$B$r;2>H!#(B

@c @item Value
@item $BCM!J(Bvalue$B!K(B
@c @cindex value cell
@cindex $BCM%;%k(B
@c The @dfn{value cell} holds the current value of the symbol as a
@c variable.  When a symbol is used as a form, the value of the form is the
@c contents of the symbol's value cell.  See @code{symbol-value} in
@c @ref{Accessing Variables}.
@dfn{$BCM%;%k(B}$B!J(Bvalue cell$B!K$K$O!"(B
$B%7%s%\%k$NJQ?t$H$7$F$N8=:_CM$,F~$C$F$$$k!#(B
$B%7%s%\%k$r%U%)!<%`$H$7$F;HMQ$7$?$H$-!"(B
$B%U%)!<%`$NCM$O%7%s%\%k$NCM%;%k$NFbMF$G$"$k!#(B
@ref{Accessing Variables}$B$N(B@code{symbol-value}$B$r;2>H!#(B

@c @item Function
@item $B4X?t!J(Bfunction$B!K(B
@c @cindex function cell
@cindex $B4X?t%;%k(B
@c The @dfn{function cell} holds the function definition of the symbol.
@c When a symbol is used as a function, its function definition is used in
@c its place.  This cell is also used to make a symbol stand for a keymap
@c or a keyboard macro, for editor command execution.  Because each symbol
@c has separate value and function cells, variables and function names do
@c not conflict.  See @code{symbol-function} in @ref{Function Cells}.
@dfn{$B4X?t%;%k(B}$B!J(Bfunction cell$B!K$K$O!"%7%s%\%k$N4X?tDj5A$,F~$C$F$$$k!#(B
$B%7%s%\%k$r4X?t$H$7$F;HMQ$7$?$H$-!"$=$N4X?tDj5A$r;H$&!#(B
$B%7%s%\%k$,!"JT=8%3%^%s%I$r<B9T$9$k$?$a$N%-!<%^%C%W$d%-!<%\!<%I%^%/%m$r(B
$BI=$9$H$-$b$3$N%;%k$r;H$&!#(B
$B3F%7%s%\%k$K$OCM%;%k$H4X?t%;%k$,JL!9$K$"$k$N$G!"(B
$BJQ?tL>$H4X?tL>$O>WFM$7$J$$!#(B
@ref{Function Cells}$B$N(B@code{symbol-function}$B$r;2>H!#(B

@c @item Property list
@item $BB0@-%j%9%H!J(Bproperty list$B!K(B
@c @cindex property list cell
@cindex $BB0@-%j%9%H%;%k(B
@c The @dfn{property list cell} holds the property list of the symbol.  See
@c @code{symbol-plist} in @ref{Property Lists}.
@dfn{$BB0@-%j%9%H%;%k(B}$B!J(Bproperty list cell$B!K$K$O!"(B
$B%7%s%\%k$NB0@-%j%9%H$,F~$C$F$$$k!#(B
@ref{Property Lists}$B$N(B@code{symbol-plist}$B$r;2>H!#(B
@end table

@c   The print name cell always holds a string, and cannot be changed.  The
@c other three cells can be set individually to any specified Lisp object.
$BI=<(L>%;%k$O$D$M$KJ8;zNs$rJ];}$7$F$$$F!"JQ99$G$-$^$;$s!#(B
$BB>$N(B3$B$D$N%;%k$K$O!"G$0U$N;XDj$7$?(BLisp$B%*%V%8%'%/%H$r8DJL$K@_Dj$G$-$^$9!#(B

@c   The print name cell holds the string that is the name of the symbol.
@c Since symbols are represented textually by their names, it is important
@c not to have two symbols with the same name.  The Lisp reader ensures
@c this: every time it reads a symbol, it looks for an existing symbol with
@c the specified name before it creates a new one.  (In GNU Emacs Lisp,
@c this lookup uses a hashing algorithm and an obarray; see @ref{Creating
@c Symbols}.)
$BI=<(L>%;%k$O!"%7%s%\%k$NL>A0$G$"$kJ8;zNs$rJ];}$7$F$$$^$9!#(B
$B%7%s%\%k$O%F%-%9%H>e$O$=$NL>A0$GI=8=$5$l$k$N$G!"(B
2$B$D$N%7%s%\%k$,F1$8L>A0$r;}$?$J$$$3$H$,=EMW$G$9!#(B
Lisp$B%j!<%@$,$3$N$3$H$rJ]>Z$7$^$9!#(B
$B%7%s%\%k$rFI$_<h$k$?$S$K!"?7$?$K%7%s%\%k$r:n@.$9$k$^$($K!"(B
$B;XDj$7$?L>A0$N%7%s%\%k$,B8:_$9$k$+$I$&$+D4$Y$^$9!#(B
$B!J(BGNU Emacs Lisp$B$G$O!"$3$l$K$O%O%C%7%e%"%k%4%j%:%`$H(B
$B%*%V%8%'%/%HG[Ns(Bobarray$B$r;H$&!#(B
@pxref{Creating Symbols}$B!#!K(B

@c   In normal usage, the function cell usually contains a function
@c (@pxref{Functions}) or a macro (@pxref{Macros}), as that is what the
@c Lisp interpreter expects to see there (@pxref{Evaluation}).  Keyboard
@c macros (@pxref{Keyboard Macros}), keymaps (@pxref{Keymaps}) and autoload
@c objects (@pxref{Autoloading}) are also sometimes stored in the function
@c cells of symbols.  We often refer to ``the function @code{foo}'' when we
@c really mean the function stored in the function cell of the symbol
@c @code{foo}.  We make the distinction only when necessary.
$BIaDL$N;H$$J}$G$O!"4X?t%;%k$K$O4X?t!J(B@pxref{Functions}$B!K$d(B
$B%^%/%m!J(B@pxref{Macros}$B!K$,F~$C$F$$$F!"(B
Lisp$B%$%s%?!<%W%j%?$O$=$N$h$&$K2>Dj$7$^$9!J(B@pxref{Evaluation}$B!K!#(B
$B%7%s%\%k$N4X?t%;%k$K$O!"(B
$B%-!<%\!<%I%^%/%m!J(B@pxref{Keyboard Macros}$B!K!"%-!<%^%C%W!J(B@pxref{Keymaps}$B!K!"(B
$B<+F0%m!<%I%*%V%8%'%/%H!J(B@pxref{Autoloading}$B!K$,F~$C$F$$$k$3$H$b$"$j$^$9!#(B
$B!X4X?t(B@code{foo}$B!Y$H$$$C$?>l9g!"<B:]$K$O!"%7%s%\%k(B@code{foo}$B$N4X?t%;%k$K(B
$BF~$C$F$$$k4X?t$r0UL#$7$^$9!#(B
$BI,MW$J>l9g$K8B$C$F6hJL$7$^$9!#(B

@c   The property list cell normally should hold a correctly formatted
@c property list (@pxref{Property Lists}), as a number of functions expect
@c to see a property list there.
$BB0@-%j%9%H%;%k$O!"DL>o!"@5$7$$7A<0$NB0@-%j%9%H!J(B@pxref{Property Lists}$B!K$,(B
$BF~$C$F$$$kI,MW$,$"$j!"$5$^$6$^$J4X?t$,$=$N$h$&$K2>Dj$7$F$$$^$9!#(B

@c   The function cell or the value cell may be @dfn{void}, which means
@c that the cell does not reference any object.  (This is not the same
@c thing as holding the symbol @code{void}, nor the same as holding the
@c symbol @code{nil}.)  Examining a function or value cell that is void
@c results in an error, such as @samp{Symbol's value as variable is void}.
$B4X?t%;%k$dCM%;%k$O(B@dfn{$B6u(B}$B!J(Bvoid$B!K$G$b$+$^$$$^$;$s!#(B
$B$D$^$j!"%;%k$O$I$s$J%*%V%8%'%/%H$b;X$7$F$$$^$;$s!#(B
$B!J$3$N$3$H$O!"%7%s%\%k(B@code{void}$B$rJ];}$7$F$$$k$H$+!"(B
$B%7%s%\%k(B@code{nil}$B$rJ];}$7$F$$$k$N$H$O0c$&!#!K(B
$B6u$G$"$k4X?t%;%k$dCM%;%k$r;2>H$9$k$H!"(B
$B$=$N7k2L$O(B@samp{Symbol's value as variable is void}
$B!J!VJQ?t$H$7$F$N%7%s%\%k$NCM$O6u!W!K$N$h$&$J%(%i!<$K$J$j$^$9!#(B

@c   The four functions @code{symbol-name}, @code{symbol-value},
@c @code{symbol-plist}, and @code{symbol-function} return the contents of
@c the four cells of a symbol.  Here as an example we show the contents of
@c the four cells of the symbol @code{buffer-file-name}:
4$B$D$N4X?t!"(B@code{symbol-name}$B!"(B@code{symbol-value}$B!"(B
@code{symbol-plist}$B!"(B@code{symbol-function}$B$O!"(B
$B%7%s%\%k$N(B4$B$D$N%;%k$NFbMF$rJV$7$^$9!#(B
$B0J2<$K!"%7%s%\%k(B@code{buffer-file-name}$B$N(B
4$B$D$N%;%k$NFbMF$rI=<($9$kNc$r<($7$^$9!#(B

@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{} #<subr buffer-file-name>
@end example

@noindent
@c Because this symbol is the variable which holds the name of the file
@c being visited in the current buffer, the value cell contents we see are
@c the name of the source file of this chapter of the Emacs Lisp Manual.
@c The property list cell contains the list @code{(variable-documentation
@c 29529)} which tells the documentation functions where to find the
@c documentation string for the variable @code{buffer-file-name} in the
@c @file{DOC-@var{version}} file.  (29529 is the offset from the beginning
@c of the @file{DOC-@var{version}} file to where that documentation string
@c begins---see @ref{Documentation Basics}.)  The function cell contains
@c the function for returning the name of the file.
@c @code{buffer-file-name} names a primitive function, which has no read
@c syntax and prints in hash notation (@pxref{Primitive Function Type}).  A
@c symbol naming a function written in Lisp would have a lambda expression
@c (or a byte-code object) in this cell.
$B$3$N%7%s%\%k$O!"%+%l%s%H%P%C%U%!$GK,Ld$7$F$$$k%U%!%$%k$NL>A0$rJ];}$9$k$N$G!"(B
$BCM%;%k$NFbMF$OK\=q(BEmacs Lisp$B%^%K%e%"%k$NK\>O$N%=!<%9%U%!%$%k$NL>A0$G$9!#(B
$BB0@-%j%9%H%;%k$K$O!"%j%9%H(B@code{(variable-documentation 29529)}$B$,F~$C$F$$$F!"(B
$B%I%-%e%a%s%H4X?t$KBP$7$F%U%!%$%k(B@file{DOC-@var{version}}$B$N$I$3$K(B
$BJQ?t(B@code{buffer-file-name}$B$N@bL@J8;zNs$,F~$C$F$$$k$+EA$($^$9!#(B
$B!J(B29529$B$O!"Ev3:@bL@J8;zNs$N3+;O0LCV$rI=$9(B
@file{DOC-@var{version}}$B$N@hF,$+$i$N%*%U%;%C%H!#(B
@ref{Documentation Basics}$B$r;2>H!#!K(B
$B4X?t%;%k$K$O!"%U%!%$%k$NL>A0$rJV$94X?t$,F~$C$F$$$^$9!#(B
@code{buffer-file-name}$B$O4pK\4X?t$NL>A0$G$9!#(B
$B$3$l$K$OF~NO9=J8$O$J$/!"(B
$B%O%C%7%e5-K!!J(B@pxref{Primitive Function Type}$B!K$GI=<($5$l$F$$$^$9!#(B
Lisp$B$G=q$$$?4X?t$rI=$9%7%s%\%k$G$O!"(B
$B$3$N%;%k$K%i%`%@<0!J$"$k$$$O%P%$%H%3!<%I%*%V%8%'%/%H!K$,F~$C$F$$$^$9!#(B

@node Definitions, Creating Symbols, Symbol Components, Symbols
@c @section Defining Symbols
@section $B%7%s%\%k$rDj5A$9$k(B
@c @cindex definition of a symbol
@cindex $B%7%s%\%k$rDj5A$9$k(B

@c   A @dfn{definition} in Lisp is a special form that announces your
@c intention to use a certain symbol in a particular way.  In Emacs Lisp,
@c you can define a symbol as a variable, or define it as a function (or
@c macro), or both independently.
Lisp$B$K$*$1$k(B@dfn{$BDj5A(B}$B!J(Bdefinition$B!K$H$O!"(B
$BFCDj$N%7%s%\%k$r$I$N$h$&$K;H$&$+$r0U;WI=<($9$k%9%Z%7%c%k%U%)!<%`$G$9!#(B
Emacs Lisp$B$G$O!"%7%s%\%k$rJQ?t$HDj5A$7$?$j!"(B
$B4X?t!J$"$k$$$O%^%/%m!K$HDj5A$7$?$j!"$"$k$$$O!"$=$l$i$rFHN)$KDj5A$G$-$^$9!#(B

@c   A definition construct typically specifies a value or meaning for the
@c symbol for one kind of use, plus documentation for its meaning when used
@c in this way.  Thus, when you define a symbol as a variable, you can
@c supply an initial value for the variable, plus documentation for the
@c variable.
$BDj5A$r9T$&9=J8$G$O!"E57?E*$K$O!"CM$r;XDj$7$?$j!"(B
$B%7%s%\%k$rFCDj$N;H$$J}$r$9$k$H;XDj$7$?$j$7!"(B
$B$5$i$K!"$=$N$h$&$J;H$$J}$r$7$?$H$-$N0UL#$rI=$9$?$a$N@bL@J8;zNs$r;XDj$7$^$9!#(B
$B$7$?$,$C$F!"%7%s%\%k$rJQ?t$H$7$FDj5A$9$k$H$-$K$O!"(B
$BJQ?t$K=i4|CM$rM?$(!"$=$NJQ?t$N@bL@J8;zNs$r;XDj$G$-$^$9!#(B

@c   @code{defvar} and @code{defconst} are special forms that define a
@c symbol as a global variable.  They are documented in detail in
@c @ref{Defining Variables}.  For defining user option variables that can
@c be customized, use @code{defcustom} (@pxref{Customization}).
@code{defvar}$B$H(B@code{defconst}$B$O!"%7%s%\%k$r%0%m!<%P%kJQ?t$H$7$FDj5A$9$k(B
$B%9%Z%7%c%k%U%)!<%`$G$9!#(B
$B$3$l$i$O(B@ref{Defining Variables}$B$G>\$7$/@bL@$7$F$"$j$^$9!#(B
$B%+%9%?%^%$%:2DG=$J$h$&$K%f!<%6!<%*%W%7%g%sMQ$NJQ?t$rDj5A$9$k$K$O!"(B
@code{defcustom}$B!J(B@pxref{Customization}$B!K$r;H$$$^$9!#(B

@c   @code{defun} defines a symbol as a function, creating a lambda
@c expression and storing it in the function cell of the symbol.  This
@c lambda expression thus becomes the function definition of the symbol.
@c (The term ``function definition'', meaning the contents of the function
@c cell, is derived from the idea that @code{defun} gives the symbol its
@c definition as a function.)  @code{defsubst} and @code{defalias} are two
@c other ways of defining a function.  @xref{Functions}.
@code{defun}$B$O!"%7%s%\%k$r4X?t$H$7$FDj5A$7!"(B
$B%i%`%@<0$r:n$C$F%7%s%\%k$N4X?t%;%k$K3JG<$7$^$9!#(B
$B$7$?$,$C$F!"$3$N%i%`%@<0$,%7%s%\%k$N4X?tDj5A$K$J$j$^$9!#(B
$B!JMQ8l!X4X?tDj5A!Y$O!"4X?t%;%k$NFbMF$r0UL#$7!"(B
@code{defun}$B$,%7%s%\%k$K4X?t$H$7$F$NDj5A$rM?$($k$3$H$+$i$-$F$$$k!#!K(B
@code{defsubst}$B$H(B@code{defalias}$B$O!"4X?t$rDj5A$9$kJL$N(B2$B$D$NJ}K!$G$9!#(B
@xref{Functions}$B!#(B

@c   @code{defmacro} defines a symbol as a macro.  It creates a macro
@c object and stores it in the function cell of the symbol.  Note that a
@c given symbol can be a macro or a function, but not both at once, because
@c both macro and function definitions are kept in the function cell, and
@c that cell can hold only one Lisp object at any given time.
@c @xref{Macros}.
@code{defmacro}$B$O!"%7%s%\%k$r%^%/%m$H$7$FDj5A$7$^$9!#(B
$B%^%/%m%*%V%8%'%/%H$r:n$C$F%7%s%\%k$N4X?t%;%k$K3JG<$7$^$9!#(B
$B%7%s%\%k$O!"%^%/%m$+4X?t$N$$$:$l$+$G$"$C$F!"(B
$BF1;~$KN>J}$K$O$J$i$J$$$3$H$KCm0U$7$F$/$@$5$$!#(B
$B$H$$$&$N$O!"%^%/%mDj5A$b4X?tDj5A$b4X?t%;%k$K<}$a$i$l!"(B
$B$=$N%;%k$K$O$I$s$J$H$-$G$b$?$C$?(B1$B$D$N(BLisp$B%*%V%8%'%/%H$7$+(B
$BJ];}$G$-$J$$$+$i$G$9!#(B
@xref{Macros}$B!#(B

@c   In Emacs Lisp, a definition is not required in order to use a symbol
@c as a variable or function.  Thus, you can make a symbol a global
@c variable with @code{setq}, whether you define it first or not.  The real
@c purpose of definitions is to guide programmers and programming tools.
@c They inform programmers who read the code that certain symbols are
@c @emph{intended} to be used as variables, or as functions.  In addition,
@c utilities such as @file{etags} and @file{make-docfile} recognize
@c definitions, and add appropriate information to tag tables and the
@c @file{DOC-@var{version}} file.  @xref{Accessing Documentation}.
Emacs Lisp$B$G$O!"%7%s%\%k$rJQ?t$d4X?t$H$7$F;H$&$?$a$N(B
$BDj5A$OI,?\$G$O$"$j$^$;$s!#(B
$B$7$?$,$C$F!"%7%s%\%k$r$"$i$+$8$aDj5A$7$h$&$,$7$^$$$,!"(B
@code{setq}$B$r;H$C$F%7%s%\%k$r%0%m!<%P%kJQ?t$K$G$-$^$9!#(B
$BDj5A$N??$NL\E*$O!"%W%m%0%i%^$KBP$9$k;X?K$G$"$j!"%W%m%0%i%_%s%0%D!<%k$J$N$G$9!#(B
$B$3$l$i$O!"%3!<%I$rFI$`%W%m%0%i%^$KBP$7$F!"(B
$BFCDj$N%7%s%\%k$rJQ?t$H$7$F;H$&$N$+4X?t$H$7$F;H$&$N$+!"(B
$B$=$N(B@emph{$B0U?^(B}$B$rEA$($^$9!#(B
$B$5$i$K!"(B@file{etags}$B$d(B@file{make-docfile}$B$J$I$N%f!<%F%#%j%F%#$O!"(B
$BDj5A$rG'<1$7$F%?%0%F!<%V%k$d%U%!%$%k(B@file{DOC-@var{version}}$B$K(B
$BE,@Z$J>pJs$rDI2C$7$^$9!#(B
@xref{Accessing Documentation}$B!#(B

@node Creating Symbols, Property Lists, Definitions, Symbols
@c @section Creating and Interning Symbols
@section $B%7%s%\%k$N:n@.$H%$%s%?!<%s(B
@c @cindex reading symbols
@cindex $B%7%s%\%k$rFI$`(B

@c   To understand how symbols are created in GNU Emacs Lisp, you must know
@c how Lisp reads them.  Lisp must ensure that it finds the same symbol
@c every time it reads the same set of characters.  Failure to do so would
@c cause complete confusion.
GNU Emacs Lisp$B$K$*$$$F!"$I$N$h$&$K%7%s%\%k$r:n@.$9$k$+$rM}2r$9$k$K$O!"(B
Lisp$B$,$=$l$i$r$I$N$h$&$KFI$`$+$rCN$kI,MW$,$"$j$^$9!#(B
Lisp$B$O!"F1$8J8;z72$rFI$_<h$k$?$S$K!"F1$8%7%s%\%k$r$_$D$1$k$3$H$rJ]>Z$9$k(B
$BI,MW$,$"$j$^$9!#(B
$B$3$l$K<:GT$9$k$H40A4$K:.Mp$7$^$9!#(B

@c @cindex symbol name hashing
@c @cindex hashing
@c @cindex obarray
@cindex $B%7%s%\%kL>$N%O%C%7%e2=(B
@cindex $B%O%C%7%e2=(B
@cindex $B%*%V%8%'%/%HG[Ns!J(Bobarray$B!K(B
@cindex obarray$B!J%*%V%8%'%/%HG[Ns!K(B
@c @cindex bucket (in obarray)
@cindex $B%P%1%C%H!J%*%V%8%'%/%HG[Ns!K(B
@c   When the Lisp reader encounters a symbol, it reads all the characters
@c of the name.  Then it ``hashes'' those characters to find an index in a
@c table called an @dfn{obarray}.  Hashing is an efficient method of
@c looking something up.  For example, instead of searching a telephone
@c book cover to cover when looking up Jan Jones, you start with the J's
@c and go from there.  That is a simple version of hashing.  Each element
@c of the obarray is a @dfn{bucket} which holds all the symbols with a
@c given hash code; to look for a given name, it is sufficient to look
@c through all the symbols in the bucket for that name's hash code.
Lisp$B%j!<%@$,%7%s%\%k$K=P2q$&$H!"L>A0$NJ8;z72$r$9$Y$FFI$_<h$j$^$9!#(B
$B$=$7$F!"$3$l$i$NJ8;z72$r!X%O%C%7%e2=!Y$7$F!"(B
@dfn{$B%*%V%8%'%/%HG[Ns(B}$B!J(Bobarray$B!K$H8F$P$l$kI=$NE:;z$rC5$7$^$9!#(B
$B%O%C%7%e2=$O8zN(E*$KC5:w$9$k<jK!$G$9!#(B
$B$?$H$($P!"(BJan Jones$B$rEEOCHV9fJm$NI=;f$+$i(B1$B%Z!<%8$:$D=g$KC5$9$+$o$j$K!"(B
J$B$N%Z!<%8$+$iC5$7;O$a$^$9!#(B
$B$3$l$OC1=c$J%O%C%7%e2=$G$9!#(B
$B%*%V%8%'%/%HG[Ns$N3FMWAG$O!"(B
$B$"$k%O%C%7%e%3!<%I$rM-$9$k$9$Y$F$N%7%s%\%k$r3JG<$7$?(B
@dfn{$B%P%1%C%H(B}$B!J(Bbucket$B!K$G$9!#(B
$B$"$kL>A0$rC5$9$K$O!"$=$NL>A0$N%O%C%7%e%3!<%I$KBP1~$9$k%P%1%C%HFb$N(B
$B$9$Y$F$N%7%s%\%k$rD4$Y$k$@$1$G==J,$G$9!#(B

@c @cindex interning
@cindex $B%$%s%?!<%s(B
@c   If a symbol with the desired name is found, the reader uses that
@c symbol.  If the obarray does not contain a symbol with that name, the
@c reader makes a new symbol and adds it to the obarray.  Finding or adding
@c a symbol with a certain name is called @dfn{interning} it, and the
@c symbol is then called an @dfn{interned symbol}.
$BL\E*$NL>A0$N%7%s%\%k$,$_$D$+$l$P!"%j!<%@$O$=$N%7%s%\%k$r;H$$$^$9!#(B
$B%*%V%8%'%/%HG[Ns$KL\E*$NL>A0$N%7%s%\%k$,$J$1$l$P!"(B
$B%j!<%@$O?7$?$J%7%s%\%k$r:n@.$7!"$=$l$r%*%V%8%'%/%HG[Ns$KDI2C$7$^$9!#(B
$B$"$kL>A0$N%7%s%\%k$rC5$7$?$jDI2C$9$k$3$H$r%7%s%\%k$r(B
@dfn{$B%$%s%?!<%s(B}$B!J(Binterning$B!K$9$k$H$$$$!"(B
$B$=$N%7%s%\%k$r(B@dfn{$B%$%s%?!<%s$7$?%7%s%\%k(B}$B!J(Binterned symbol$B!K$H8F$S$^$9!#(B

@c   Interning ensures that each obarray has just one symbol with any
@c particular name.  Other like-named symbols may exist, but not in the
@c same obarray.  Thus, the reader gets the same symbols for the same
@c names, as long as you keep reading with the same obarray.
$B%$%s%?!<%s$9$k$3$H$G!"3F%*%V%8%'%/%HG[Ns$K$O(B
$BFCDj$NL>A0$N%7%s%\%k$,(B1$B8D$@$1$"$k$3$H$rJ]>Z$7$^$9!#(B
$BB>$N;w$?$h$&$JL>A0$N%7%s%\%k$,B8:_$7$F$b!"(B
$BF1$8%*%V%8%'%/%HG[Ns$K$OF~$C$F$$$^$;$s!#(B
$B$7$?$,$C$F!"F1$8%*%V%8%'%/%HG[Ns$r;H$C$FFI$`8B$j!"(B
$B%j!<%@$OF1$8L>A0$KBP$7$FF1$8%7%s%\%k$rF@$k$3$H$,$G$-$^$9!#(B

@c @cindex symbol equality
@c @cindex uninterned symbol
@cindex $B%7%s%\%k$NF1CM@-(B
@cindex $BF1CM@-!"%7%s%\%k(B
@cindex $B%$%s%?!<%s$7$F$J$$%7%s%\%k(B
@c   No obarray contains all symbols; in fact, some symbols are not in any
@c obarray.  They are called @dfn{uninterned symbols}.  An uninterned
@c symbol has the same four cells as other symbols; however, the only way
@c to gain access to it is by finding it in some other object or as the
@c value of a variable.
$B$9$Y$F$N%7%s%\%k$,%*%V%8%'%/%HG[Ns$KF~$C$F$$$k$H$O8B$j$^$;$s!#(B
$B<B:]!"$I$N%*%V%8%'%/%HG[Ns$K$bB0$5$J$$%7%s%\%k$,$$$/$D$+$"$j$^$9!#(B
$B$3$l$i$r(B@dfn{$B%$%s%?!<%s$7$F$J$$%7%s%\%k(B}$B!J(Buninterned symbols$B!K$H8F$S$^$9!#(B
$B%$%s%?!<%s$7$F$J$$%7%s%\%k$K$b!"B>$N%7%s%\%k$HF1MM$K(B4$B$D$N%;%k$,$"$j$^$9!#(B
$B$7$+$7!"$=$l$r;2>H$9$k<jCJ$O!"B>$N%*%V%8%'%/%H$r2p$7$FC5$9$+!"(B
$BJQ?t$NCM$H$7$FC5$9$7$+$"$j$^$;$s!#(B

@c   In Emacs Lisp, an obarray is actually a vector.  Each element of the
@c vector is a bucket; its value is either an interned symbol whose name
@c hashes to that bucket, or 0 if the bucket is empty.  Each interned
@c symbol has an internal link (invisible to the user) to the next symbol
@c in the bucket.  Because these links are invisible, there is no way to
@c find all the symbols in an obarray except using @code{mapatoms} (below).
@c The order of symbols in a bucket is not significant.
Emacs Lisp$B$G$O!"%*%V%8%'%/%HG[Ns$O<B:]$K$O%Y%/%H%k$G$9!#(B
$B%Y%/%H%k$N3FMWAG$O%P%1%C%H$G$9!#(B
$B$=$NCM$O!"$=$N%P%1%C%H$K%O%C%7%e2=$5$l$kL>A0$N%$%s%?!<%s$7$?%7%s%\%k$G$"$k$+!"(B
$B$=$N%P%1%C%H$,6u$J$i$P(B0$B$G$9!#(B
$B%$%s%?!<%s$7$?3F%7%s%\%k$K$O!"%P%1%C%H$N$D$.$N%7%s%\%k$r;X$9(B
$B!J%f!<%6!<$K$O8+$($J$$!KFbItE*$J%j%s%/$,$"$j$^$9!#(B
$B$3$N%j%s%/$O8+$($J$$$N$G!"(B@code{mapatoms}$B!J2<5-!K$r;H$&0J30$K$O!"(B
$B%*%V%8%'%/%HG[NsFb$N$9$Y$F$N%7%s%\%k$rC5$9J}K!$O$"$j$^$;$s!#(B
$B%P%1%C%HFb$G$N%7%s%\%k$N=g=x$O4X78$"$j$^$;$s!#(B

@c   In an empty obarray, every element is 0, and you can create an obarray
@c with @code{(make-vector @var{length} 0)}.  @strong{This is the only
@c valid way to create an obarray.}  Prime numbers as lengths tend
@c to result in good hashing; lengths one less than a power of two are also
@c good.
$B6u$N%*%V%8%'%/%HG[Ns$G$O!"3FMWAG$O(B0$B$G$9!#(B
@code{(make-vector @var{length} 0)}$B$G%*%V%8%'%/%HG[Ns$r:n@.$G$-$^$9!#(B
@strong{$B$3$l$O!"%*%V%8%'%/%HG[Ns$r:n@.$9$kM#0l$N@5Ev$JJ}K!$G$9!#(B}
$BD9$5$H$7$FAG?t$rMQ$$$k$H!"%O%C%7%e2=$N7k2L$,$h$$798~$,$"$j$^$9!#(B
2$B$N6R$h$j(B1$B>.$5$$D9$5$b$h$$7k2L$K$J$j$^$9!#(B

@c   @strong{Do not try to put symbols in an obarray yourself.}  This does
@c not work---only @code{intern} can enter a symbol in an obarray properly.
@strong{$BFI<T<+?H$G%*%V%8%'%/%HG[Ns$K%7%s%\%k$rF~$l$J$$$G$/$@$5$$!#(B}
$B$&$^$/$$$-$^$;$s!#(B
$B%*%V%8%'%/%HG[Ns$K%7%s%\%k$r@5$7$/F~$l$i$l$k$N$O(B@code{intern}$B$@$1$G$9!#(B

@c @cindex CL note---symbol in obarrays
@cindex CL$B$K4X$7$?Cm0U!]!]%*%V%8%'%/%HG[NsFb$N%7%s%\%k(B
@quotation
@c @b{Common Lisp note:} In Common Lisp, a single symbol may be interned in
@c several obarrays.
@b{Common Lisp$B$K4X$7$?Cm0U!'(B}@code{ }
Common Lisp$B$G$O!"(B1$B$D$N%7%s%\%k$rJ#?t$N%*%V%8%'%/%HG[Ns$KF~$l$k$3$H$,$G$-$k!#(B
@end quotation

@c   Most of the functions below take a name and sometimes an obarray as
@c arguments.  A @code{wrong-type-argument} error is signaled if the name
@c is not a string, or if the obarray is not a vector.
$B2<5-$N4X?t$N$[$H$s$I$O!"0z?t$KL>A0$r<h$j!"(B
$B>l9g$K$h$C$F$O%*%V%8%'%/%HG[Ns$r0z?t$K<h$j$^$9!#(B
$BL>A0$,J8;zNs$G$J$+$C$?$j!"%*%V%8%'%/%HG[Ns$,%Y%/%H%k$G$J$$$H!"(B
$B%(%i!<(B@code{wrong-type-argument}$B$rDLCN$7$^$9!#(B

@defun symbol-name symbol
@c This function returns the string that is @var{symbol}'s name.  For example:
$B$3$N4X?t$O!"(B@var{symbol}$B$NL>A0$rI=$9J8;zNs$rJV$9!#(B
$B$?$H$($P!"$D$.$N$H$*$j!#(B

@example
@group
(symbol-name 'foo)
     @result{} "foo"
@end group
@end example

@c @strong{Warning:} Changing the string by substituting characters does
@c change the name of the symbol, but fails to update the obarray, so don't
@c do it!
@strong{$B7Y9p!'(B}@code{ }
$BJ8;zNs$NJ8;z$rCV$-49$($k$H%7%s%\%k$NL>A0$rJQ99$9$k$,!"(B
$B%*%V%8%'%/%HG[Ns$O99?7$G$-$J$$$N$GJQ99$7$J$$$3$H!*(B
@end defun

@defun make-symbol name
@c This function returns a newly-allocated, uninterned symbol whose name is
@c @var{name} (which must be a string).  Its value and function definition
@c are void, and its property list is @code{nil}.  In the example below,
@c the value of @code{sym} is not @code{eq} to @code{foo} because it is a
@c distinct uninterned symbol whose name is also @samp{foo}.
$B$3$N4X?t$O!"(B@var{name}$B!JJ8;zNs$G$"$k$3$H!K$rL>A0$H$9$k(B
$B?7$?$K3d$jIU$1$?%$%s%?!<%s$7$F$$$J$$%7%s%\%k$rJV$9!#(B
$B$=$NCM$H4X?tDj5A$O6u$G$"$j!"B0@-%j%9%H$O(B@code{nil}$B$G$"$k!#(B
$B0J2<$NNc$G$O!"(B@code{sym}$B$NCM$O(B@code{foo}$B$H(B@code{eq}$B$G$O$J$$!#(B
$B$J$<$J$i!"L>A0$O(B@samp{foo}$B$G$O$"$k$,!"(B
$B%$%s%?!<%s$7$F$$$J$$JL$N%7%s%\%k$G$"$k$?$a!#(B

@example
(setq sym (make-symbol "foo"))
     @result{} foo
(eq sym 'foo)
     @result{} nil
@end example
@end defun

@defun intern name &optional obarray
@c This function returns the interned symbol whose name is @var{name}.  If
@c there is no such symbol in the obarray @var{obarray}, @code{intern}
@c creates a new one, adds it to the obarray, and returns it.  If
@c @var{obarray} is omitted, the value of the global variable
@c @code{obarray} is used.
$B$3$N4X?t$O!"(B@var{name}$B$rL>A0$H$9$k%$%s%?!<%s$7$?%7%s%\%k$rJV$9!#(B
$B$=$N$h$&$J%7%s%\%k$,%*%V%8%'%/%HG[Ns(B@var{obarray}$B$KB8:_$7$J$1$l$P!"(B
@code{intern}$B$O?7$?$J$b$N$r:n@.$7!"$=$l$r%*%V%8%'%/%HG[Ns$KDI2C$7$F$+$i!"(B
$B$=$l$rJV$9!#(B
@var{obarray}$B$r>JN,$9$k$H!"%0%m!<%P%kJQ?t(B@code{obarray}$B$NCM$r;H$&!#(B

@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

@c @cindex CL note---interning existing symbol
@cindex CL$B$K4X$7$?Cm0U!]!]4{B8%7%s%\%k$N%$%s%?!<%s(B
@quotation
@c @b{Common Lisp note:} In Common Lisp, you can intern an existing symbol
@c in an obarray.  In Emacs Lisp, you cannot do this, because the argument
@c to @code{intern} must be a string, not a symbol.
@b{Common Lisp$B$K4X$7$?Cm0U!'(B}@code{ }
Common Lisp$B$G$O!"4{B8$N%7%s%\%k$r%*%V%8%'%/%HG[Ns$K%$%s%?!<%s$G$-$k!#(B
Emacs Lisp$B$G$O!"$3$l$O$G$-$J$$!#(B
$B$J$<$J$i!"(B@code{intern}$B$N0z?t$OJ8;zNs$G$"$kI,MW$,$"$j!"(B
$B%7%s%\%k$G$O$J$$!#(B
@end quotation

@defun intern-soft name &optional obarray
@c This function returns the symbol in @var{obarray} whose name is
@c @var{name}, or @code{nil} if @var{obarray} has no symbol with that name.
@c Therefore, you can use @code{intern-soft} to test whether a symbol with
@c a given name is already interned.  If @var{obarray} is omitted, the
@c value of the global variable @code{obarray} is used.
$B$3$N4X?t$O!"(B@var{obarray}$BFb$N(B@var{name}$B$rL>A0$H$9$k%7%s%\%k$rJV$9!#(B
$B$?$@$7!"$=$NL>A0$N%7%s%\%k$,(B@var{obarray}$B$K$J$1$l$P(B@code{nil}$B$rJV$9!#(B
$B$7$?$,$C$F!"(B@code{intern-soft}$B$rMQ$$$F!";XDj$7$?L>A0$N%7%s%\%k$,(B
$B%$%s%?!<%s$5$l$F$$$k$+$I$&$+D4$Y$i$l$k!#(B
@var{obarray}$B$r>JN,$9$k$H!"%0%m!<%P%kJQ?t(B@code{obarray}$B$NCM$r;H$&!#(B

@smallexample
@c (intern-soft "frazzle")        ; @r{No such symbol exists.}
(intern-soft "frazzle")        ; @r{$B$=$N$h$&$J%7%s%\%k$OB8:_$7$J$$(B}
     @result{} nil
@c (make-symbol "frazzle")        ; @r{Create an uninterned one.}
(make-symbol "frazzle")        ; @r{$B%$%s%?!<%s$7$J$$$b$N$r:n$k(B}
     @result{} frazzle
@group
@c (intern-soft "frazzle")        ; @r{That one cannot be found.}
(intern-soft "frazzle")        ; @r{$B$=$N$h$&$J$b$N$O$_$D$+$i$J$$(B}
     @result{} nil
@end group
@group
@c (setq sym (intern "frazzle"))  ; @r{Create an interned one.}
(setq sym (intern "frazzle"))  ; @r{$B%$%s%?!<%s$7$?$b$N$r:n$k(B}
     @result{} frazzle
@end group
@group
@c (intern-soft "frazzle")        ; @r{That one can be found!}
(intern-soft "frazzle")        ; @r{$B$=$N$h$&$J$b$N$,$_$D$+$C$?!*(B}
     @result{} frazzle
@end group
@group
@c (eq sym 'frazzle)              ; @r{And it is the same one.}
(eq sym 'frazzle)              ; @r{$B$7$+$b!"$=$l$i$OF10l(B}
     @result{} t
@end group
@end smallexample
@end defun

@defvar obarray
@c This variable is the standard obarray for use by @code{intern} and
@c @code{read}.
$B$3$NJQ?t$O!"(B@code{intern}$B$d(B@code{read}$B$,;H$&I8=`$N%*%V%8%'%/%HG[Ns!#(B
@end defvar

@defun mapatoms function &optional obarray
@c This function calls @var{function} once with each symbol in the obarray
@c @var{obarray}.  Then it returns @code{nil}.  If @var{obarray} is
@c omitted, it defaults to the value of @code{obarray}, the standard
@c obarray for ordinary symbols.
$B$3$N4X?t$O!"%*%V%8%'%/%HG[Ns(B@var{obarray}$B$N3F%7%s%\%k$K$D$$$F!"(B
1$B2s$:$D(B@var{function}$B$r8F$S=P$9!#(B
$B$=$7$F!"(B@code{nil}$B$rJV$9!#(B
@var{obarray}$B$r>JN,$9$k$H!"DL>o$N%7%s%\%k8~$1$NI8=`$N%*%V%8%'%/%HG[Ns$G$"$k(B
@code{obarray}$B$NCM$r%G%U%)%k%H$K$9$k!#(B

@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

@c See @code{documentation} in @ref{Accessing Documentation}, for another
@c example using @code{mapatoms}.
@code{mapatoms}$B$r;H$C$?JL$NNc$K$D$$$F$O!"(B
@ref{Accessing Documentation}$B$N(B@code{documentation}$B$r;2>H!#(B
@end defun

@defun unintern symbol &optional obarray
@c This function deletes @var{symbol} from the obarray @var{obarray}.  If
@c @code{symbol} is not actually in the obarray, @code{unintern} does
@c nothing.  If @var{obarray} is @code{nil}, the current obarray is used.
$B$3$N4X?t$O!"%*%V%8%'%/%HG[Ns(B@var{obarray}$B$+$i(B@var{symbol}$B$r:o=|$9$k!#(B
@code{symbol}$B$,<B:]$K$O%*%V%8%'%/%HG[NsFb$K$J$1$l$P!"(B
@code{unintern}$B$O$J$K$b$7$J$$!#(B
@var{obarray}$B$,(B@code{nil}$B$G$"$k$H!"8=:_$N%*%V%8%'%/%HG[Ns$r;H$&!#(B

@c If you provide a string instead of a symbol as @var{symbol}, it stands
@c for a symbol name.  Then @code{unintern} deletes the symbol (if any) in
@c the obarray which has that name.  If there is no such symbol,
@c @code{unintern} does nothing.
@var{symbol}$B$N%7%s%\%k$N$+$o$j$KJ8;zNs$r;XDj$9$k$H!"(B
$B$=$l$O%7%s%\%k$NL>A0$rI=$9!#(B
$B$=$7$F!"(B@code{unintern}$B$O$=$NL>A0$N%7%s%\%k$r!J$"$l$P!K%*%V%8%'%/%HG[Ns$+$i(B
$B:o=|$9$k!#(B
$B$=$N$h$&$J%7%s%\%k$,$J$1$l$P!"(B@code{unintern}$B$O$J$K$b$7$J$$!#(B

@c If @code{unintern} does delete a symbol, it returns @code{t}.  Otherwise
@c it returns @code{nil}.
@code{unintern}$B$O!"%7%s%\%k$r:o=|$7$?$H$-$K$O(B@code{t}$B$rJV$9!#(B
$B$5$b$J$1$l$P(B@code{nil}$B$rJV$9!#(B
@end defun

@node Property Lists,, Creating Symbols, Symbols
@c @section Property Lists
@section $BB0@-%j%9%H(B
@c @cindex property list
@c @cindex plist
@cindex $BB0@-%j%9%H!J(Bplist$B!K(B
@cindex plist$B!JB0@-%j%9%H!K(B

@c   A @dfn{property list} (@dfn{plist} for short) is a list of paired
@c elements stored in the property list cell of a symbol.  Each of the
@c pairs associates a property name (usually a symbol) with a property or
@c value.  Property lists are generally used to record information about a
@c symbol, such as its documentation as a variable, the name of the file
@c where it was defined, or perhaps even the grammatical class of the
@c symbol (representing a word) in a language-understanding system.
@dfn{$BB0@-%j%9%H(B}$B!J(Bproperty list$B!"N,$7$F(B@dfn{plist}$B!K$H$O!"(B
$B%7%s%\%k$NB0@-%j%9%H%;%k$K3JG<$5$l$?BP$K$J$C$?MWAG$+$i@.$k%j%9%H$G$9!#(B
$B3FBP$O!"B0@-L>!JDL>o!"%7%s%\%k!K$rB0@-!"$9$J$o$A!"B0@-CM$KBP1~IU$1$^$9!#(B
$BB0@-%j%9%H$O!"0lHL$K!"%7%s%\%k$K4X$9$k>pJs$r5-O?$7$^$9!#(B
$BJQ?t$H$7$F$N@bL@J8;zNs!"Dj5A$5$l$F$$$k%U%!%$%k$NL>A0!"(B
$B8@8lM}2r%7%9%F%`$K$*$$$F$O!J8l$rI=$9!K%7%s%\%k$NJ8K!%/%i%9$J$I$G$9!#(B

@c   Character positions in a string or buffer can also have property lists.
@c @xref{Text Properties}.
$BJ8;zNsFb$d%P%C%U%!Fb$NJ8;z0LCV$bB0@-%j%9%H$r;}$F$^$9!#(B
@xref{Text Properties}$B!#(B

@c   The property names and values in a property list can be any Lisp
@c objects, but the names are usually symbols.  Property list functions
@c compare the property names using @code{eq}.  Here is an example of a
@c property list, found on the symbol @code{progn} when the compiler is
@c loaded:
$BB0@-%j%9%HFb$NB0@-L>$HB0@-CM$O!"G$0U$N(BLisp$B%*%V%8%'%/%H$G$+$^$$$^$;$s$,!"(B
$BIaDL!"B0@-L>$O%7%s%\%k$G$9!#(B
$BB0@-%j%9%H4X?t$O!"(B@code{eq}$B$r;H$C$FB0@-L>$rHf3S$7$^$9!#(B
$B%3%s%Q%$%i$r%m!<%I$7$?:]$N%7%s%\%k(B@code{progn}$B$NB0@-%j%9%H$r$D$.$K<($7$^$9!#(B

@example
(lisp-indent-function 0 byte-compile byte-compile-progn)
@end example

@noindent
@c Here @code{lisp-indent-function} and @code{byte-compile} are property
@c names, and the other two elements are the corresponding values.
$B$3$3$G!"(B@code{lisp-indent-function}$B$d(B@code{byte-compile}$B$OB0@-L>$G$"$j!"(B
$BB>$N(B2$B$D$NMWAG$OBP1~$9$kB0@-CM$G$9!#(B

@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
@c @subsection Property Lists and Association Lists
@subsection $BB0@-%j%9%H$HO"A[%j%9%H(B

@c @cindex property lists vs association lists
@cindex $BB0@-%j%9%H$HO"A[%j%9%H(B
@cindex $BO"A[%j%9%H$HB0@-%j%9%H(B
@c   Association lists (@pxref{Association Lists}) are very similar to
@c property lists.  In contrast to association lists, the order of the
@c pairs in the property list is not significant since the property names
@c must be distinct.
$BO"A[%j%9%H!J(B@pxref{Association Lists}$B!K$O!"(B
$BB0@-%j%9%H$KHs>o$K$h$/;w$F$$$^$9!#(B
$BO"A[%j%9%H$H0[$J$j!"B0@-L>$O0l0U$G$"$kI,MW$,$"$k$N$G!"(B
$BB0@-%j%9%HFb$G$NBP$N=P8==g=x$O4X78$"$j$^$;$s!#(B

@c   Property lists are better than association lists for attaching
@c information to various Lisp function names or variables.  If your
@c program keeps all of its associations in one association list, it will
@c typically need to search that entire list each time it checks for an
@c association.  This could be slow.  By contrast, if you keep the same
@c information in the property lists of the function names or variables
@c themselves, each search will scan only the length of one property list,
@c which is usually short.  This is why the documentation for a variable is
@c recorded in a property named @code{variable-documentation}.  The byte
@c compiler likewise uses properties to record those functions needing
@c special treatment.
$B$5$^$6$^$J(BLisp$B4X?t$d(BLisp$BJQ?t$K>pJs$rIU2C$9$k$K$O!"(B
$BB0@-%j%9%H$OO"A[%j%9%H$h$jM%$l$F$$$^$9!#(B
$BFI<T$N%W%m%0%i%`$G(B1$B$D$NO"A[%j%9%H$K$9$Y$F$NO"A[$rF~$l$F$*$$$?$H$9$k$H!"(B
1$B$D$NO"A[$rC5$9$?$S$K!"%j%9%HA4BN$rC5:w$9$kI,MW$,$"$j$^$9!#(B
$B$3$l$K$O;~4V$,$+$+$j$^$9!#(B
$B0lJ}!"F1$8>pJs$r4X?tL>$dJQ?t<+?H$NB0@-%j%9%H$KJ];}$7$F$*$1$P!"(B
$B3FC5:w$G$O(B1$B$D$NB0@-%j%9%H$rAv::$9$k$@$1$G$h$/!"(B
$BB0@-%j%9%H$O!"IaDL!"C;$$$b$N$G$9!#(B
$B$3$N$?$a!"JQ?t$N@bL@J8;zNs$r(B@code{variable-documentation}$B$H$$$&L>A0$N(B
$BB0@-$K5-O?$7$F$$$k$N$G$9!#(B
$BF1MM$K!"%P%$%H%3%s%Q%$%i$b!"(B
$BFCJL$J=hM}$,I,MW$J4X?t$rB0@-$r;H$C$F5-O?$7$F$$$^$9!#(B

@c   However, association lists have their own advantages.  Depending on
@c your application, it may be faster to add an association to the front of
@c an association list than to update a property.  All properties for a
@c symbol are stored in the same property list, so there is a possibility
@c of a conflict between different uses of a property name.  (For this
@c reason, it is a good idea to choose property names that are probably
@c unique, such as by beginning the property name with the program's usual
@c name-prefix for variables and functions.)  An association list may be
@c used like a stack where associations are pushed on the front of the list
@c and later discarded; this is not possible with a property list.
$B$7$+$7$J$,$i!"O"A[%j%9%H$K$b$=$lFH<+$NMxE@$,$"$j$^$9!#(B
$BFI<T$N%"%W%j%1!<%7%g%s$K0MB8$7$^$9$,!"(B
$BB0@-$r99?7$9$k$h$j!"O"A[%j%9%H$N@hF,$KO"A[$rDI2C$9$k$[$&$,B.$$$G$9!#(B
$B$"$k%7%s%\%k$N$9$Y$F$NB0@-$OF10l$NB0@-%j%9%H$K3JG<$7$F$"$k$N$G!"(B
1$B$D$NB0@-L>$r0[$J$kL\E*$K;H$&$H>WFM$7$^$9!#(B
$B!J$3$NM}M3$+$i!"%W%m%0%i%`$GIaDL$K;H$&(B
$BJQ?tL>$d4X?tL>$N@\F,<-$G;O$^$kB0@-L>$rA*$V$J$I$7$F!"(B
$B0l0U$JB0@-L>$rA*$V$N$,$h$$!#!K(B
$BO"A[%j%9%H$O!"%j%9%H$N@hF,$KMWAG$rDI2C$7!"@hF,$+$iMWAG$r:o=|$9$k$N$G!"(B
$B%9%?%C%/$N$h$&$K;H$($^$9!#(B
$BB0@-%j%9%H$G$O!"$3$l$OIT2DG=$G$9!#(B

@node Symbol Plists
@c @subsection Property List Functions for Symbols
@subsection $B%7%s%\%k8~$1B0@-%j%9%H4X?t(B

@defun symbol-plist symbol
@c This function returns the property list of @var{symbol}.
$B$3$N4X?t$O(B@var{symbol}$B$NB0@-%j%9%H$rJV$9!#(B
@end defun

@defun setplist symbol plist
@c This function sets @var{symbol}'s property list to @var{plist}.
@c Normally, @var{plist} should be a well-formed property list, but this is
@c not enforced.
$B$3$N4X?t$O!"(B@var{symbol}$B$NB0@-%j%9%H$r(B@var{plist}$B$H$9$k!#(B
$BDL>o!"(B@var{plist}$B$O@5$7$$7A$NB0@-%j%9%H$G$"$k$Y$-$@$,6/MW$5$l$J$$!#(B

@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

@c For symbols in special obarrays, which are not used for ordinary
@c purposes, it may make sense to use the property list cell in a
@c nonstandard fashion; in fact, the abbrev mechanism does so
@c (@pxref{Abbrevs}).
$BIaDL$N;H$$J}$r0U?^$7$F$$$J$$FCJL$J%*%V%8%'%/%HG[NsFb$N%7%s%\%k$KBP$7$F$O!"(B
$BB0@-%j%9%H%;%k$NHsI8=`$J;H$$J}$K$b0UL#$,$"$m$&!#(B
$B<B:]!"N,8l5!9=!J(B@pxref{Abbrevs}$B!K$G$O$=$N$h$&$K$7$F$$$k!#(B
@end defun

@defun get symbol property
@c This function finds the value of the property named @var{property} in
@c @var{symbol}'s property list.  If there is no such property, @code{nil}
@c is returned.  Thus, there is no distinction between a value of
@c @code{nil} and the absence of the property.
$B$3$N4X?t$O!"(B@var{symbol}$B$NB0@-%j%9%H$+$i(B
@var{property}$B$H$$$&L>A0$NB0@-$NCM$rC5$9!#(B
$B$=$N$h$&$JB0@-$,$J$1$l$P!"(B@code{nil}$B$rJV$9!#(B
$B$D$^$j!"(B@code{nil}$B$H$$$&CM$HB0@-$N7gG!$r6hJL$G$-$J$$!#(B

@c The name @var{property} is compared with the existing property names
@c using @code{eq}, so any object is a legitimate property.
$BL>A0(B@var{property}$B$O4{B8$NB0@-L>$H(B@code{eq}$B$GHf3S$9$k$?$a!"(B
$B$I$s$J%*%V%8%'%/%H$G$b@5Ev$JB0@-$G$"$k!#(B

@c See @code{put} for an example.
$BNc$K$D$$$F$O!"(B@code{put}$B$r;2>H!#(B
@end defun

@defun put symbol property value
@c This function puts @var{value} onto @var{symbol}'s property list under
@c the property name @var{property}, replacing any previous property value.
@c The @code{put} function returns @var{value}.
$B$3$N4X?t$O!"(B@var{symbol}$B$NB0@-%j%9%H$K$*$$$F!"(B
$BB0@-L>(B@var{property}$B$N8E$$B0@-CM$r(B@var{value}$B$GCV$-49$($k!#(B
$B4X?t(B@code{put}$B$O(B@var{value}$B$rJV$9!#(B

@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
@c @subsection Property Lists Outside Symbols
@subsection $B%7%s%\%k$N30It$NB0@-%j%9%H(B

@c   These two functions are useful for manipulating property lists
@c that are stored in places other than symbols:
$B%7%s%\%k0J30$N>l=j$KJ]B8$7$?B0@-%j%9%H$NA`:n$KJXMx$J(B2$B$D$N4X?t$,$"$j$^$9!#(B

@defun plist-get plist property
@c This returns the value of the @var{property} property
@c stored in the property list @var{plist}.  For example,
$B$3$l$O!"B0@-%j%9%H(B@var{plist}$B$KJ]B8$5$l$F$$$kB0@-(B@var{property}$B$NCM$rJV$9!#(B
$B$?$H$($P!"$D$.$N$H$*$j!#(B

@example
(plist-get '(foo 4) 'foo)
     @result{} 4
@end example
@end defun

@defun plist-put plist property value
@c This stores @var{value} as the value of the @var{property} property in
@c the property list @var{plist}.  It may modify @var{plist} destructively,
@c or it may construct a new list structure without altering the old.  The
@c function returns the modified property list, so you can store that back
@c in the place where you got @var{plist}.  For example,
$B$3$l$O!"B0@-%j%9%H(B@var{plist}$B$K!"(B
@var{property}$B$NCM$H$7$F(B@var{value}$B$r3JG<$9$k!#(B
$B$3$l$O(B@var{plist}$B$rGK2uE*$KJQ99$9$k$+!"$"$k$$$O!"(B
$B8E$$$b$N$rJQ99$;$:$K?7$?$J%j%9%H9=B$$r9=C[$9$k!#(B
$B4X?t$OJQ99$7$?B0@-%j%9%H$rJV$9$N$G!"(B
@var{plist}$B$rJ];}$7$F$$$?$H$3$m$XJ]B8$7D>$;$k!#(B
$B$?$H$($P!"$D$.$N$H$*$j!#(B

@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

@c   You could define @code{put} in terms of @code{plist-put} as follows:
$B$D$.$N$h$&$K$7$F!"(B@code{plist-put}$B$rMQ$$$F(B@code{put}$B$rDj5A$G$-$^$9!#(B

@example
(defun put (symbol prop value)
  (setplist symbol
            (plist-put (symbol-plist symbol) prop value)))
@end example