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