annotate lispref/symbols.texi @ 22471:39efe6bebb46

(info-other-window): New function.
author Richard M. Stallman <rms@gnu.org>
date Sat, 13 Jun 1998 06:00:00 +0000
parents d4ac295a98b3
children 682a37afcb98
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
6411
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1 @c -*-texinfo-*-
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2 @c This is part of the GNU Emacs Lisp Reference Manual.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
6411
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4 @c See the file elisp.texi for copying conditions.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
5 @setfilename ../info/symbols
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
6 @node Symbols, Evaluation, Sequences Arrays Vectors, Top
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
7 @chapter Symbols
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
8 @cindex symbol
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
9
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
10 A @dfn{symbol} is an object with a unique name. This chapter
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
11 describes symbols, their components, their property lists, and how they
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
12 are created and interned. Separate chapters describe the use of symbols
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
13 as variables and as function names; see @ref{Variables}, and
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
14 @ref{Functions}. For the precise read syntax for symbols, see
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
15 @ref{Symbol Type}.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
16
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
17 You can test whether an arbitrary Lisp object is a symbol
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
18 with @code{symbolp}:
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
19
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
20 @defun symbolp object
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
21 This function returns @code{t} if @var{object} is a symbol, @code{nil}
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
22 otherwise.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
23 @end defun
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
24
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
25 @menu
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
26 * Symbol Components:: Symbols have names, values, function definitions
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
27 and property lists.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
28 * Definitions:: A definition says how a symbol will be used.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
29 * Creating Symbols:: How symbols are kept unique.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
30 * Property Lists:: Each symbol has a property list
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
31 for recording miscellaneous information.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
32 @end menu
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
33
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
34 @node Symbol Components, Definitions, Symbols, Symbols
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
35 @section Symbol Components
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
36 @cindex symbol components
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
37
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
38 Each symbol has four components (or ``cells''), each of which
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
39 references another object:
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
40
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
41 @table @asis
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
42 @item Print name
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
43 @cindex print name cell
7118
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6411
diff changeset
44 The @dfn{print name cell} holds a string that names the symbol for
6411
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
45 reading and printing. See @code{symbol-name} in @ref{Creating Symbols}.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
46
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
47 @item Value
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
48 @cindex value cell
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
49 The @dfn{value cell} holds the current value of the symbol as a
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
50 variable. When a symbol is used as a form, the value of the form is the
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
51 contents of the symbol's value cell. See @code{symbol-value} in
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
52 @ref{Accessing Variables}.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
53
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
54 @item Function
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
55 @cindex function cell
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
56 The @dfn{function cell} holds the function definition of the symbol.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
57 When a symbol is used as a function, its function definition is used in
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
58 its place. This cell is also used to make a symbol stand for a keymap
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
59 or a keyboard macro, for editor command execution. Because each symbol
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
60 has separate value and function cells, variables and function names do
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
61 not conflict. See @code{symbol-function} in @ref{Function Cells}.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
62
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
63 @item Property list
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
64 @cindex property list cell
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
65 The @dfn{property list cell} holds the property list of the symbol. See
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
66 @code{symbol-plist} in @ref{Property Lists}.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
67 @end table
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
68
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
69 The print name cell always holds a string, and cannot be changed. The
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
70 other three cells can be set individually to any specified Lisp object.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
71
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
72 The print name cell holds the string that is the name of the symbol.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
73 Since symbols are represented textually by their names, it is important
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
74 not to have two symbols with the same name. The Lisp reader ensures
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
75 this: every time it reads a symbol, it looks for an existing symbol with
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
76 the specified name before it creates a new one. (In GNU Emacs Lisp,
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
77 this lookup uses a hashing algorithm and an obarray; see @ref{Creating
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
78 Symbols}.)
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
79
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
80 In normal usage, the function cell usually contains a function
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
81 (@pxref{Functions}) or a macro (@pxref{Macros}), as that is what the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
82 Lisp interpreter expects to see there (@pxref{Evaluation}). Keyboard
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
83 macros (@pxref{Keyboard Macros}), keymaps (@pxref{Keymaps}) and autoload
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
84 objects (@pxref{Autoloading}) are also sometimes stored in the function
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
85 cells of symbols. We often refer to ``the function @code{foo}'' when we
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
86 really mean the function stored in the function cell of the symbol
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
87 @code{foo}. We make the distinction only when necessary.
6411
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
88
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
89 The property list cell normally should hold a correctly formatted
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
90 property list (@pxref{Property Lists}), as a number of functions expect
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
91 to see a property list there.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
92
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
93 The function cell or the value cell may be @dfn{void}, which means
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
94 that the cell does not reference any object. (This is not the same
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
95 thing as holding the symbol @code{void}, nor the same as holding the
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
96 symbol @code{nil}.) Examining a function or value cell that is void
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
97 results in an error, such as @samp{Symbol's value as variable is void}.
6411
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
98
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
99 The four functions @code{symbol-name}, @code{symbol-value},
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
100 @code{symbol-plist}, and @code{symbol-function} return the contents of
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
101 the four cells of a symbol. Here as an example we show the contents of
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
102 the four cells of the symbol @code{buffer-file-name}:
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
103
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
104 @example
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
105 (symbol-name 'buffer-file-name)
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
106 @result{} "buffer-file-name"
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
107 (symbol-value 'buffer-file-name)
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
108 @result{} "/gnu/elisp/symbols.texi"
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
109 (symbol-plist 'buffer-file-name)
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
110 @result{} (variable-documentation 29529)
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
111 (symbol-function 'buffer-file-name)
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
112 @result{} #<subr buffer-file-name>
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
113 @end example
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
114
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
115 @noindent
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
116 Because this symbol is the variable which holds the name of the file
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
117 being visited in the current buffer, the value cell contents we see are
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
118 the name of the source file of this chapter of the Emacs Lisp Manual.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
119 The property list cell contains the list @code{(variable-documentation
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
120 29529)} which tells the documentation functions where to find the
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
121 documentation string for the variable @code{buffer-file-name} in the
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
122 @file{DOC-@var{version}} file. (29529 is the offset from the beginning
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
123 of the @file{DOC-@var{version}} file to where that documentation string
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
124 begins---see @ref{Documentation Basics}.) The function cell contains
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
125 the function for returning the name of the file.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
126 @code{buffer-file-name} names a primitive function, which has no read
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
127 syntax and prints in hash notation (@pxref{Primitive Function Type}). A
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
128 symbol naming a function written in Lisp would have a lambda expression
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
129 (or a byte-code object) in this cell.
6411
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
130
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
131 @node Definitions, Creating Symbols, Symbol Components, Symbols
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
132 @section Defining Symbols
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
133 @cindex definition of a symbol
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
134
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
135 A @dfn{definition} in Lisp is a special form that announces your
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
136 intention to use a certain symbol in a particular way. In Emacs Lisp,
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
137 you can define a symbol as a variable, or define it as a function (or
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
138 macro), or both independently.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
139
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
140 A definition construct typically specifies a value or meaning for the
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
141 symbol for one kind of use, plus documentation for its meaning when used
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
142 in this way. Thus, when you define a symbol as a variable, you can
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
143 supply an initial value for the variable, plus documentation for the
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
144 variable.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
145
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
146 @code{defvar} and @code{defconst} are special forms that define a
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
147 symbol as a global variable. They are documented in detail in
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
148 @ref{Defining Variables}. For defining user option variables that can
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
149 be customized, use @code{defcustom} (@pxref{Customization}).
6411
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
150
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
151 @code{defun} defines a symbol as a function, creating a lambda
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
152 expression and storing it in the function cell of the symbol. This
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
153 lambda expression thus becomes the function definition of the symbol.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
154 (The term ``function definition'', meaning the contents of the function
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
155 cell, is derived from the idea that @code{defun} gives the symbol its
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
156 definition as a function.) @code{defsubst} and @code{defalias} are two
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
157 other ways of defining a function. @xref{Functions}.
6411
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
158
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
159 @code{defmacro} defines a symbol as a macro. It creates a macro
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
160 object and stores it in the function cell of the symbol. Note that a
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
161 given symbol can be a macro or a function, but not both at once, because
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
162 both macro and function definitions are kept in the function cell, and
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
163 that cell can hold only one Lisp object at any given time.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
164 @xref{Macros}.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
165
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
166 In Emacs Lisp, a definition is not required in order to use a symbol
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
167 as a variable or function. Thus, you can make a symbol a global
6411
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
168 variable with @code{setq}, whether you define it first or not. The real
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
169 purpose of definitions is to guide programmers and programming tools.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
170 They inform programmers who read the code that certain symbols are
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
171 @emph{intended} to be used as variables, or as functions. In addition,
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
172 utilities such as @file{etags} and @file{make-docfile} recognize
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
173 definitions, and add appropriate information to tag tables and the
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
174 @file{DOC-@var{version}} file. @xref{Accessing Documentation}.
6411
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
175
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
176 @node Creating Symbols, Property Lists, Definitions, Symbols
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
177 @section Creating and Interning Symbols
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
178 @cindex reading symbols
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
179
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
180 To understand how symbols are created in GNU Emacs Lisp, you must know
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
181 how Lisp reads them. Lisp must ensure that it finds the same symbol
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
182 every time it reads the same set of characters. Failure to do so would
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
183 cause complete confusion.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
184
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
185 @cindex symbol name hashing
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
186 @cindex hashing
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
187 @cindex obarray
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
188 @cindex bucket (in obarray)
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
189 When the Lisp reader encounters a symbol, it reads all the characters
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
190 of the name. Then it ``hashes'' those characters to find an index in a
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
191 table called an @dfn{obarray}. Hashing is an efficient method of
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
192 looking something up. For example, instead of searching a telephone
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
193 book cover to cover when looking up Jan Jones, you start with the J's
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
194 and go from there. That is a simple version of hashing. Each element
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
195 of the obarray is a @dfn{bucket} which holds all the symbols with a
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
196 given hash code; to look for a given name, it is sufficient to look
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
197 through all the symbols in the bucket for that name's hash code.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
198
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
199 @cindex interning
7118
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6411
diff changeset
200 If a symbol with the desired name is found, the reader uses that
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6411
diff changeset
201 symbol. If the obarray does not contain a symbol with that name, the
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6411
diff changeset
202 reader makes a new symbol and adds it to the obarray. Finding or adding
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6411
diff changeset
203 a symbol with a certain name is called @dfn{interning} it, and the
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6411
diff changeset
204 symbol is then called an @dfn{interned symbol}.
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6411
diff changeset
205
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6411
diff changeset
206 Interning ensures that each obarray has just one symbol with any
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6411
diff changeset
207 particular name. Other like-named symbols may exist, but not in the
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6411
diff changeset
208 same obarray. Thus, the reader gets the same symbols for the same
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6411
diff changeset
209 names, as long as you keep reading with the same obarray.
6411
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
210
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
211 @cindex symbol equality
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
212 @cindex uninterned symbol
7118
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6411
diff changeset
213 No obarray contains all symbols; in fact, some symbols are not in any
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6411
diff changeset
214 obarray. They are called @dfn{uninterned symbols}. An uninterned
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6411
diff changeset
215 symbol has the same four cells as other symbols; however, the only way
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6411
diff changeset
216 to gain access to it is by finding it in some other object or as the
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6411
diff changeset
217 value of a variable.
6411
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
218
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
219 In Emacs Lisp, an obarray is actually a vector. Each element of the
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
220 vector is a bucket; its value is either an interned symbol whose name
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
221 hashes to that bucket, or 0 if the bucket is empty. Each interned
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
222 symbol has an internal link (invisible to the user) to the next symbol
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
223 in the bucket. Because these links are invisible, there is no way to
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
224 find all the symbols in an obarray except using @code{mapatoms} (below).
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
225 The order of symbols in a bucket is not significant.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
226
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
227 In an empty obarray, every element is 0, and you can create an obarray
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
228 with @code{(make-vector @var{length} 0)}. @strong{This is the only
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
229 valid way to create an obarray.} Prime numbers as lengths tend
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
230 to result in good hashing; lengths one less than a power of two are also
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
231 good.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
232
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
233 @strong{Do not try to put symbols in an obarray yourself.} This does
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
234 not work---only @code{intern} can enter a symbol in an obarray properly.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
235
6411
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
236 @cindex CL note---symbol in obarrays
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
237 @quotation
7734
2d4db32cccd5 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 7118
diff changeset
238 @b{Common Lisp note:} In Common Lisp, a single symbol may be interned in
6411
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
239 several obarrays.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
240 @end quotation
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
241
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
242 Most of the functions below take a name and sometimes an obarray as
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
243 arguments. A @code{wrong-type-argument} error is signaled if the name
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
244 is not a string, or if the obarray is not a vector.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
245
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
246 @defun symbol-name symbol
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
247 This function returns the string that is @var{symbol}'s name. For example:
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
248
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
249 @example
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
250 @group
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
251 (symbol-name 'foo)
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
252 @result{} "foo"
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
253 @end group
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
254 @end example
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
255
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
256 @strong{Warning:} Changing the string by substituting characters does
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
257 change the name of the symbol, but fails to update the obarray, so don't
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
258 do it!
6411
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
259 @end defun
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
260
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
261 @defun make-symbol name
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
262 This function returns a newly-allocated, uninterned symbol whose name is
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
263 @var{name} (which must be a string). Its value and function definition
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
264 are void, and its property list is @code{nil}. In the example below,
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
265 the value of @code{sym} is not @code{eq} to @code{foo} because it is a
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
266 distinct uninterned symbol whose name is also @samp{foo}.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
267
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
268 @example
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
269 (setq sym (make-symbol "foo"))
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
270 @result{} foo
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
271 (eq sym 'foo)
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
272 @result{} nil
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
273 @end example
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
274 @end defun
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
275
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
276 @defun intern name &optional obarray
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
277 This function returns the interned symbol whose name is @var{name}. If
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
278 there is no such symbol in the obarray @var{obarray}, @code{intern}
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
279 creates a new one, adds it to the obarray, and returns it. If
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
280 @var{obarray} is omitted, the value of the global variable
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
281 @code{obarray} is used.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
282
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
283 @example
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
284 (setq sym (intern "foo"))
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
285 @result{} foo
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
286 (eq sym 'foo)
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
287 @result{} t
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
288
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
289 (setq sym1 (intern "foo" other-obarray))
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
290 @result{} foo
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
291 (eq sym 'foo)
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
292 @result{} nil
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
293 @end example
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
294 @end defun
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
295
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
296 @cindex CL note---interning existing symbol
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
297 @quotation
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
298 @b{Common Lisp note:} In Common Lisp, you can intern an existing symbol
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
299 in an obarray. In Emacs Lisp, you cannot do this, because the argument
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
300 to @code{intern} must be a string, not a symbol.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
301 @end quotation
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
302
6411
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
303 @defun intern-soft name &optional obarray
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
304 This function returns the symbol in @var{obarray} whose name is
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
305 @var{name}, or @code{nil} if @var{obarray} has no symbol with that name.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
306 Therefore, you can use @code{intern-soft} to test whether a symbol with
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
307 a given name is already interned. If @var{obarray} is omitted, the
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
308 value of the global variable @code{obarray} is used.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
309
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
310 @smallexample
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
311 (intern-soft "frazzle") ; @r{No such symbol exists.}
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
312 @result{} nil
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
313 (make-symbol "frazzle") ; @r{Create an uninterned one.}
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
314 @result{} frazzle
12282
586e3ea81792 updates for version 19.29 made by melissa; also needed to check out files
Melissa Weisshaus <melissa@gnu.org>
parents: 12128
diff changeset
315 @group
6411
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
316 (intern-soft "frazzle") ; @r{That one cannot be found.}
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
317 @result{} nil
12282
586e3ea81792 updates for version 19.29 made by melissa; also needed to check out files
Melissa Weisshaus <melissa@gnu.org>
parents: 12128
diff changeset
318 @end group
586e3ea81792 updates for version 19.29 made by melissa; also needed to check out files
Melissa Weisshaus <melissa@gnu.org>
parents: 12128
diff changeset
319 @group
6411
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
320 (setq sym (intern "frazzle")) ; @r{Create an interned one.}
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
321 @result{} frazzle
12282
586e3ea81792 updates for version 19.29 made by melissa; also needed to check out files
Melissa Weisshaus <melissa@gnu.org>
parents: 12128
diff changeset
322 @end group
586e3ea81792 updates for version 19.29 made by melissa; also needed to check out files
Melissa Weisshaus <melissa@gnu.org>
parents: 12128
diff changeset
323 @group
6411
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
324 (intern-soft "frazzle") ; @r{That one can be found!}
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
325 @result{} frazzle
12282
586e3ea81792 updates for version 19.29 made by melissa; also needed to check out files
Melissa Weisshaus <melissa@gnu.org>
parents: 12128
diff changeset
326 @end group
6411
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
327 @group
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
328 (eq sym 'frazzle) ; @r{And it is the same one.}
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
329 @result{} t
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
330 @end group
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
331 @end smallexample
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
332 @end defun
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
333
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
334 @defvar obarray
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
335 This variable is the standard obarray for use by @code{intern} and
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
336 @code{read}.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
337 @end defvar
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
338
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
339 @defun mapatoms function &optional obarray
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
340 This function calls @var{function} once with each symbol in the obarray
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
341 @var{obarray}. Then it returns @code{nil}. If @var{obarray} is
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
342 omitted, it defaults to the value of @code{obarray}, the standard
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
343 obarray for ordinary symbols.
6411
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
344
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
345 @smallexample
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
346 (setq count 0)
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
347 @result{} 0
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
348 (defun count-syms (s)
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
349 (setq count (1+ count)))
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
350 @result{} count-syms
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
351 (mapatoms 'count-syms)
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
352 @result{} nil
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
353 count
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
354 @result{} 1871
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
355 @end smallexample
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
356
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
357 See @code{documentation} in @ref{Accessing Documentation}, for another
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
358 example using @code{mapatoms}.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
359 @end defun
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
360
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
361 @defun unintern symbol &optional obarray
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
362 This function deletes @var{symbol} from the obarray @var{obarray}. If
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
363 @code{symbol} is not actually in the obarray, @code{unintern} does
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
364 nothing. If @var{obarray} is @code{nil}, the current obarray is used.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
365
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
366 If you provide a string instead of a symbol as @var{symbol}, it stands
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
367 for a symbol name. Then @code{unintern} deletes the symbol (if any) in
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
368 the obarray which has that name. If there is no such symbol,
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
369 @code{unintern} does nothing.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
370
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
371 If @code{unintern} does delete a symbol, it returns @code{t}. Otherwise
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
372 it returns @code{nil}.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
373 @end defun
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
374
6411
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
375 @node Property Lists,, Creating Symbols, Symbols
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
376 @section Property Lists
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
377 @cindex property list
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
378 @cindex plist
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
379
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
380 A @dfn{property list} (@dfn{plist} for short) is a list of paired
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
381 elements stored in the property list cell of a symbol. Each of the
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
382 pairs associates a property name (usually a symbol) with a property or
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
383 value. Property lists are generally used to record information about a
7118
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6411
diff changeset
384 symbol, such as its documentation as a variable, the name of the file
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6411
diff changeset
385 where it was defined, or perhaps even the grammatical class of the
08d61ef58d13 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6411
diff changeset
386 symbol (representing a word) in a language-understanding system.
6411
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
387
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
388 Character positions in a string or buffer can also have property lists.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
389 @xref{Text Properties}.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
390
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
391 The property names and values in a property list can be any Lisp
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
392 objects, but the names are usually symbols. Property list functions
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
393 compare the property names using @code{eq}. Here is an example of a
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
394 property list, found on the symbol @code{progn} when the compiler is
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
395 loaded:
6411
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
396
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
397 @example
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
398 (lisp-indent-function 0 byte-compile byte-compile-progn)
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
399 @end example
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
400
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
401 @noindent
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
402 Here @code{lisp-indent-function} and @code{byte-compile} are property
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
403 names, and the other two elements are the corresponding values.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
404
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
405 @menu
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
406 * Plists and Alists:: Comparison of the advantages of property
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
407 lists and association lists.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
408 * Symbol Plists:: Functions to access symbols' property lists.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
409 * Other Plists:: Accessing property lists stored elsewhere.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
410 @end menu
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
411
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
412 @node Plists and Alists
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
413 @subsection Property Lists and Association Lists
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
414
6411
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
415 @cindex property lists vs association lists
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
416 Association lists (@pxref{Association Lists}) are very similar to
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
417 property lists. In contrast to association lists, the order of the
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
418 pairs in the property list is not significant since the property names
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
419 must be distinct.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
420
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
421 Property lists are better than association lists for attaching
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
422 information to various Lisp function names or variables. If your
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
423 program keeps all of its associations in one association list, it will
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
424 typically need to search that entire list each time it checks for an
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
425 association. This could be slow. By contrast, if you keep the same
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
426 information in the property lists of the function names or variables
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
427 themselves, each search will scan only the length of one property list,
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
428 which is usually short. This is why the documentation for a variable is
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
429 recorded in a property named @code{variable-documentation}. The byte
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
430 compiler likewise uses properties to record those functions needing
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
431 special treatment.
6411
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
432
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
433 However, association lists have their own advantages. Depending on
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
434 your application, it may be faster to add an association to the front of
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
435 an association list than to update a property. All properties for a
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
436 symbol are stored in the same property list, so there is a possibility
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
437 of a conflict between different uses of a property name. (For this
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
438 reason, it is a good idea to choose property names that are probably
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
439 unique, such as by beginning the property name with the program's usual
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
440 name-prefix for variables and functions.) An association list may be
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
441 used like a stack where associations are pushed on the front of the list
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
442 and later discarded; this is not possible with a property list.
6411
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
443
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
444 @node Symbol Plists
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
445 @subsection Property List Functions for Symbols
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
446
6411
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
447 @defun symbol-plist symbol
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
448 This function returns the property list of @var{symbol}.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
449 @end defun
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
450
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
451 @defun setplist symbol plist
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
452 This function sets @var{symbol}'s property list to @var{plist}.
6411
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
453 Normally, @var{plist} should be a well-formed property list, but this is
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
454 not enforced.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
455
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
456 @smallexample
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
457 (setplist 'foo '(a 1 b (2 3) c nil))
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
458 @result{} (a 1 b (2 3) c nil)
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
459 (symbol-plist 'foo)
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
460 @result{} (a 1 b (2 3) c nil)
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
461 @end smallexample
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
462
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
463 For symbols in special obarrays, which are not used for ordinary
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
464 purposes, it may make sense to use the property list cell in a
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
465 nonstandard fashion; in fact, the abbrev mechanism does so
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
466 (@pxref{Abbrevs}).
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
467 @end defun
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
468
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
469 @defun get symbol property
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
470 This function finds the value of the property named @var{property} in
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
471 @var{symbol}'s property list. If there is no such property, @code{nil}
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
472 is returned. Thus, there is no distinction between a value of
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
473 @code{nil} and the absence of the property.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
474
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
475 The name @var{property} is compared with the existing property names
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
476 using @code{eq}, so any object is a legitimate property.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
477
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
478 See @code{put} for an example.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
479 @end defun
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
480
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
481 @defun put symbol property value
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
482 This function puts @var{value} onto @var{symbol}'s property list under
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
483 the property name @var{property}, replacing any previous property value.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
484 The @code{put} function returns @var{value}.
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
485
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
486 @smallexample
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
487 (put 'fly 'verb 'transitive)
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
488 @result{}'transitive
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
489 (put 'fly 'noun '(a buzzing little bug))
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
490 @result{} (a buzzing little bug)
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
491 (get 'fly 'verb)
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
492 @result{} transitive
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
493 (symbol-plist 'fly)
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
494 @result{} (verb transitive noun (a buzzing little bug))
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
495 @end smallexample
aea7be7b925c Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
496 @end defun
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
497
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
498 @node Other Plists
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
499 @subsection Property Lists Outside Symbols
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
500
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
501 These two functions are useful for manipulating property lists
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
502 that are stored in places other than symbols:
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
503
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
504 @defun plist-get plist property
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
505 This returns the value of the @var{property} property
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
506 stored in the property list @var{plist}. For example,
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
507
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
508 @example
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
509 (plist-get '(foo 4) 'foo)
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
510 @result{} 4
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
511 @end example
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
512 @end defun
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
513
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
514 @defun plist-put plist property value
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
515 This stores @var{value} as the value of the @var{property} property in
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
516 the property list @var{plist}. It may modify @var{plist} destructively,
12128
27144f55d1c6 fixed errors that appeared during update to 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
517 or it may construct a new list structure without altering the old. The
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
518 function returns the modified property list, so you can store that back
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
519 in the place where you got @var{plist}. For example,
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
520
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
521 @example
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
522 (setq my-plist '(bar t foo 4))
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
523 @result{} (bar t foo 4)
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
524 (setq my-plist (plist-put my-plist 'foo 69))
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
525 @result{} (bar t foo 69)
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
526 (setq my-plist (plist-put my-plist 'quux '(a)))
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12282
diff changeset
527 @result{} (bar t foo 69 quux (a))
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
528 @end example
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
529 @end defun
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 7734
diff changeset
530
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
531 You could define @code{put} in terms of @code{plist-put} as follows:
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
532
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
533 @example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
534 (defun put (symbol prop value)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
535 (setplist symbol
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
536 (plist-put (symbol-plist symbol) prop value)))
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
537 @end example