Mercurial > hg > xemacs-beta
annotate man/lispref/symbols.texi @ 5888:a85efdabe237
Call #'read-passwd when requesting a password from the user, tls.c
src/ChangeLog addition:
2015-04-09 Aidan Kehoe <kehoea@parhasard.net>
* tls.c (nss_pk11_password):
* tls.c (gnutls_pk11_password):
* tls.c (openssl_password):
* tls.c (syms_of_tls):
Our read-a-password function is #'read-passwd, not
#'read-password, correct that in this file.
| author | Aidan Kehoe <kehoea@parhasard.net> |
|---|---|
| date | Thu, 09 Apr 2015 14:54:37 +0100 |
| parents | 9fae6227ede5 |
| children |
| rev | line source |
|---|---|
| 428 | 1 @c -*-texinfo-*- |
| 2 @c This is part of the XEmacs Lisp Reference Manual. | |
| 444 | 3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. |
| 428 | 4 @c See the file lispref.texi for copying conditions. |
| 5 @setfilename ../../info/symbols.info | |
| 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 | |
| 2492 | 14 @ref{Functions and Commands}. For the precise read syntax for symbols, |
| 15 see @ref{Symbol Type}. | |
| 428 | 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 * Symbol Properties:: Each symbol has a property list | |
| 31 for recording miscellaneous information. | |
| 32 @end menu | |
| 33 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5677
diff
changeset
|
34 @node Symbol Components, Definitions, Symbols, Symbols |
| 428 | 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 (symbol) | |
| 65 The @dfn{property list cell} holds the property list of the symbol. See | |
| 66 @code{symbol-plist} in @ref{Symbol Properties}. | |
| 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 | |
|
5677
febc025c4e0c
Adopt GNU's ## syntax for the interned symbol with name "".
Aidan Kehoe <kehoea@parhasard.net>
parents:
4905
diff
changeset
|
76 the specified name before it creates a new one. In XEmacs Lisp, |
|
febc025c4e0c
Adopt GNU's ## syntax for the interned symbol with name "".
Aidan Kehoe <kehoea@parhasard.net>
parents:
4905
diff
changeset
|
77 this lookup uses an hashing algorithm and an obarray; see @ref{Creating |
|
febc025c4e0c
Adopt GNU's ## syntax for the interned symbol with name "".
Aidan Kehoe <kehoea@parhasard.net>
parents:
4905
diff
changeset
|
78 Symbols}. In Emacs Lisp, the symbol with the zero-length name has the |
|
febc025c4e0c
Adopt GNU's ## syntax for the interned symbol with name "".
Aidan Kehoe <kehoea@parhasard.net>
parents:
4905
diff
changeset
|
79 special print syntax @code{##}: |
|
febc025c4e0c
Adopt GNU's ## syntax for the interned symbol with name "".
Aidan Kehoe <kehoea@parhasard.net>
parents:
4905
diff
changeset
|
80 |
|
febc025c4e0c
Adopt GNU's ## syntax for the interned symbol with name "".
Aidan Kehoe <kehoea@parhasard.net>
parents:
4905
diff
changeset
|
81 @example |
|
febc025c4e0c
Adopt GNU's ## syntax for the interned symbol with name "".
Aidan Kehoe <kehoea@parhasard.net>
parents:
4905
diff
changeset
|
82 (intern "") |
|
febc025c4e0c
Adopt GNU's ## syntax for the interned symbol with name "".
Aidan Kehoe <kehoea@parhasard.net>
parents:
4905
diff
changeset
|
83 @result{} ## |
|
febc025c4e0c
Adopt GNU's ## syntax for the interned symbol with name "".
Aidan Kehoe <kehoea@parhasard.net>
parents:
4905
diff
changeset
|
84 @end example |
| 428 | 85 |
| 86 In normal usage, the function cell usually contains a function or | |
| 87 macro, as that is what the Lisp interpreter expects to see there | |
| 88 (@pxref{Evaluation}). Keyboard macros (@pxref{Keyboard Macros}), | |
| 89 keymaps (@pxref{Keymaps}) and autoload objects (@pxref{Autoloading}) are | |
| 90 also sometimes stored in the function cell of symbols. We often refer | |
| 91 to ``the function @code{foo}'' when we really mean the function stored | |
| 92 in the function cell of the symbol @code{foo}. We make the distinction | |
| 93 only when necessary. | |
| 94 | |
| 95 The property list cell normally should hold a correctly formatted | |
| 96 property list (@pxref{Property Lists}), as a number of functions expect | |
| 97 to see a property list there. | |
| 98 | |
| 99 The function cell or the value cell may be @dfn{void}, which means | |
| 100 that the cell does not reference any object. (This is not the same | |
| 101 thing as holding the symbol @code{void}, nor the same as holding the | |
| 102 symbol @code{nil}.) Examining a cell that is void results in an error, | |
| 103 such as @samp{Symbol's value as variable is void}. | |
| 104 | |
| 105 The four functions @code{symbol-name}, @code{symbol-value}, | |
| 106 @code{symbol-plist}, and @code{symbol-function} return the contents of | |
| 107 the four cells of a symbol. Here as an example we show the contents of | |
| 108 the four cells of the symbol @code{buffer-file-name}: | |
| 109 | |
| 110 @example | |
| 111 (symbol-name 'buffer-file-name) | |
| 112 @result{} "buffer-file-name" | |
| 113 (symbol-value 'buffer-file-name) | |
| 114 @result{} "/gnu/elisp/symbols.texi" | |
| 115 (symbol-plist 'buffer-file-name) | |
| 116 @result{} (variable-documentation 29529) | |
| 117 (symbol-function 'buffer-file-name) | |
| 118 @result{} #<subr buffer-file-name> | |
| 119 @end example | |
| 120 | |
| 121 @noindent | |
| 122 Because this symbol is the variable which holds the name of the file | |
| 123 being visited in the current buffer, the value cell contents we see are | |
| 446 | 124 the name of the source file of this chapter of the XEmacs Lisp Reference |
| 125 Manual. | |
| 428 | 126 The property list cell contains the list @code{(variable-documentation |
| 127 29529)} which tells the documentation functions where to find the | |
| 128 documentation string for the variable @code{buffer-file-name} in the | |
| 129 @file{DOC} file. (29529 is the offset from the beginning of the | |
| 130 @file{DOC} file to where that documentation string begins.) The | |
| 131 function cell contains the function for returning the name of the file. | |
| 132 @code{buffer-file-name} names a primitive function, which has no read | |
| 133 syntax and prints in hash notation (@pxref{Primitive Function Type}). A | |
| 134 symbol naming a function written in Lisp would have a lambda expression | |
| 135 (or a byte-code object) in this cell. | |
| 136 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5677
diff
changeset
|
137 @node Definitions, Creating Symbols, Symbol Components, Symbols |
| 428 | 138 @section Defining Symbols |
| 139 @cindex definition of a symbol | |
| 140 | |
|
4905
755ae5b97edb
Change "special form" to "special operator" in our sources.
Aidan Kehoe <kehoea@parhasard.net>
parents:
2492
diff
changeset
|
141 A @dfn{definition} in Lisp is a special operator that announces your |
| 428 | 142 intention to use a certain symbol in a particular way. In XEmacs Lisp, |
| 143 you can define a symbol as a variable, or define it as a function (or | |
| 144 macro), or both independently. | |
| 145 | |
| 146 A definition construct typically specifies a value or meaning for the | |
| 147 symbol for one kind of use, plus documentation for its meaning when used | |
| 148 in this way. Thus, when you define a symbol as a variable, you can | |
| 149 supply an initial value for the variable, plus documentation for the | |
| 150 variable. | |
| 151 | |
|
4905
755ae5b97edb
Change "special form" to "special operator" in our sources.
Aidan Kehoe <kehoea@parhasard.net>
parents:
2492
diff
changeset
|
152 @code{defvar} and @code{defconst} are special operators that define a |
| 428 | 153 symbol as a global variable. They are documented in detail in |
| 154 @ref{Defining Variables}. | |
| 155 | |
| 156 @code{defun} defines a symbol as a function, creating a lambda | |
| 157 expression and storing it in the function cell of the symbol. This | |
| 158 lambda expression thus becomes the function definition of the symbol. | |
| 159 (The term ``function definition'', meaning the contents of the function | |
| 160 cell, is derived from the idea that @code{defun} gives the symbol its | |
| 161 definition as a function.) @code{defsubst}, @code{define-function} and | |
| 162 @code{defalias} are other ways of defining a function. | |
| 2492 | 163 @xref{Functions and Commands}. |
| 428 | 164 |
| 165 @code{defmacro} defines a symbol as a macro. It creates a macro | |
| 166 object and stores it in the function cell of the symbol. Note that a | |
| 167 given symbol can be a macro or a function, but not both at once, because | |
| 168 both macro and function definitions are kept in the function cell, and | |
| 169 that cell can hold only one Lisp object at any given time. | |
| 170 @xref{Macros}. | |
| 171 | |
| 172 In XEmacs Lisp, a definition is not required in order to use a symbol | |
| 173 as a variable or function. Thus, you can make a symbol a global | |
| 174 variable with @code{setq}, whether you define it first or not. The real | |
| 175 purpose of definitions is to guide programmers and programming tools. | |
| 176 They inform programmers who read the code that certain symbols are | |
| 177 @emph{intended} to be used as variables, or as functions. In addition, | |
| 178 utilities such as @file{etags} and @file{make-docfile} recognize | |
| 179 definitions, and add appropriate information to tag tables and the | |
| 180 @file{DOC} file. @xref{Accessing Documentation}. | |
| 181 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5677
diff
changeset
|
182 @node Creating Symbols, Symbol Properties, Definitions, Symbols |
| 428 | 183 @section Creating and Interning Symbols |
| 184 @cindex reading symbols | |
| 185 | |
| 186 To understand how symbols are created in XEmacs Lisp, you must know | |
| 187 how Lisp reads them. Lisp must ensure that it finds the same symbol | |
| 188 every time it reads the same set of characters. Failure to do so would | |
| 189 cause complete confusion. | |
| 190 | |
| 191 @cindex symbol name hashing | |
| 192 @cindex hashing | |
| 193 @cindex obarray | |
| 194 @cindex bucket (in obarray) | |
| 195 When the Lisp reader encounters a symbol, it reads all the characters | |
| 196 of the name. Then it ``hashes'' those characters to find an index in a | |
| 197 table called an @dfn{obarray}. Hashing is an efficient method of | |
| 198 looking something up. For example, instead of searching a telephone | |
| 199 book cover to cover when looking up Jan Jones, you start with the J's | |
| 200 and go from there. That is a simple version of hashing. Each element | |
| 201 of the obarray is a @dfn{bucket} which holds all the symbols with a | |
| 202 given hash code; to look for a given name, it is sufficient to look | |
| 203 through all the symbols in the bucket for that name's hash code. | |
| 204 | |
| 205 @cindex interning | |
| 206 If a symbol with the desired name is found, the reader uses that | |
| 207 symbol. If the obarray does not contain a symbol with that name, the | |
| 208 reader makes a new symbol and adds it to the obarray. Finding or adding | |
| 209 a symbol with a certain name is called @dfn{interning} it, and the | |
| 210 symbol is then called an @dfn{interned symbol}. | |
| 211 | |
| 212 Interning ensures that each obarray has just one symbol with any | |
| 213 particular name. Other like-named symbols may exist, but not in the | |
| 214 same obarray. Thus, the reader gets the same symbols for the same | |
| 215 names, as long as you keep reading with the same obarray. | |
| 216 | |
| 217 @cindex symbol equality | |
| 218 @cindex uninterned symbol | |
| 219 No obarray contains all symbols; in fact, some symbols are not in any | |
| 220 obarray. They are called @dfn{uninterned symbols}. An uninterned | |
| 221 symbol has the same four cells as other symbols; however, the only way | |
| 222 to gain access to it is by finding it in some other object or as the | |
| 223 value of a variable. | |
| 224 | |
| 225 In XEmacs Lisp, an obarray is actually a vector. Each element of the | |
| 226 vector is a bucket; its value is either an interned symbol whose name | |
| 227 hashes to that bucket, or 0 if the bucket is empty. Each interned | |
| 228 symbol has an internal link (invisible to the user) to the next symbol | |
| 229 in the bucket. Because these links are invisible, there is no way to | |
| 230 find all the symbols in an obarray except using @code{mapatoms} (below). | |
| 231 The order of symbols in a bucket is not significant. | |
| 232 | |
| 233 In an empty obarray, every element is 0, and you can create an obarray | |
| 234 with @code{(make-vector @var{length} 0)}. @strong{This is the only | |
| 235 valid way to create an obarray.} Prime numbers as lengths tend | |
| 236 to result in good hashing; lengths one less than a power of two are also | |
| 237 good. | |
| 238 | |
| 239 @strong{Do not try to put symbols in an obarray yourself.} This does | |
| 240 not work---only @code{intern} can enter a symbol in an obarray properly. | |
| 241 @strong{Do not try to intern one symbol in two obarrays.} This would | |
| 242 garble both obarrays, because a symbol has just one slot to hold the | |
| 243 following symbol in the obarray bucket. The results would be | |
| 244 unpredictable. | |
| 245 | |
| 246 It is possible for two different symbols to have the same name in | |
| 247 different obarrays; these symbols are not @code{eq} or @code{equal}. | |
| 248 However, this normally happens only as part of the abbrev mechanism | |
| 249 (@pxref{Abbrevs}). | |
| 250 | |
| 251 @cindex CL note---symbol in obarrays | |
| 252 @quotation | |
| 253 @b{Common Lisp note:} In Common Lisp, a single symbol may be interned in | |
| 254 several obarrays. | |
| 255 @end quotation | |
| 256 | |
| 257 Most of the functions below take a name and sometimes an obarray as | |
| 258 arguments. A @code{wrong-type-argument} error is signaled if the name | |
| 259 is not a string, or if the obarray is not a vector. | |
| 260 | |
| 261 @defun symbol-name symbol | |
| 262 This function returns the string that is @var{symbol}'s name. For example: | |
| 263 | |
| 264 @example | |
| 265 @group | |
| 266 (symbol-name 'foo) | |
| 267 @result{} "foo" | |
| 268 @end group | |
| 269 @end example | |
| 270 | |
| 271 Changing the string by substituting characters, etc, does change the | |
| 272 name of the symbol, but fails to update the obarray, so don't do it! | |
| 273 @end defun | |
| 274 | |
| 275 @defun make-symbol name | |
| 276 This function returns a newly-allocated, uninterned symbol whose name is | |
| 277 @var{name} (which must be a string). Its value and function definition | |
| 278 are void, and its property list is @code{nil}. In the example below, | |
| 279 the value of @code{sym} is not @code{eq} to @code{foo} because it is a | |
| 280 distinct uninterned symbol whose name is also @samp{foo}. | |
| 281 | |
| 282 @example | |
| 283 (setq sym (make-symbol "foo")) | |
| 284 @result{} foo | |
| 285 (eq sym 'foo) | |
| 286 @result{} nil | |
| 287 @end example | |
| 288 @end defun | |
| 289 | |
| 290 @defun intern name &optional obarray | |
| 291 This function returns the interned symbol whose name is @var{name}. If | |
| 292 there is no such symbol in the obarray @var{obarray}, @code{intern} | |
| 293 creates a new one, adds it to the obarray, and returns it. If | |
| 294 @var{obarray} is omitted, the value of the global variable | |
| 295 @code{obarray} is used. | |
| 296 | |
| 297 @example | |
| 298 (setq sym (intern "foo")) | |
| 299 @result{} foo | |
| 300 (eq sym 'foo) | |
| 301 @result{} t | |
| 302 | |
| 303 (setq sym1 (intern "foo" other-obarray)) | |
| 304 @result{} foo | |
| 305 (eq sym 'foo) | |
| 306 @result{} nil | |
| 307 @end example | |
| 308 @end defun | |
| 309 | |
| 310 @defun intern-soft name &optional obarray | |
| 311 This function returns the symbol in @var{obarray} whose name is | |
| 312 @var{name}, or @code{nil} if @var{obarray} has no symbol with that name. | |
| 313 Therefore, you can use @code{intern-soft} to test whether a symbol with | |
| 314 a given name is already interned. If @var{obarray} is omitted, the | |
| 315 value of the global variable @code{obarray} is used. | |
| 316 | |
| 317 @smallexample | |
| 318 (intern-soft "frazzle") ; @r{No such symbol exists.} | |
| 319 @result{} nil | |
| 320 (make-symbol "frazzle") ; @r{Create an uninterned one.} | |
| 321 @result{} frazzle | |
| 322 @group | |
| 323 (intern-soft "frazzle") ; @r{That one cannot be found.} | |
| 324 @result{} nil | |
| 325 @end group | |
| 326 @group | |
| 327 (setq sym (intern "frazzle")) ; @r{Create an interned one.} | |
| 328 @result{} frazzle | |
| 329 @end group | |
| 330 @group | |
| 331 (intern-soft "frazzle") ; @r{That one can be found!} | |
| 332 @result{} frazzle | |
| 333 @end group | |
| 334 @group | |
| 335 (eq sym 'frazzle) ; @r{And it is the same one.} | |
| 336 @result{} t | |
| 337 @end group | |
| 338 @end smallexample | |
| 339 @end defun | |
| 340 | |
| 341 @defvar obarray | |
| 342 This variable is the standard obarray for use by @code{intern} and | |
| 343 @code{read}. | |
| 344 @end defvar | |
| 345 | |
| 346 @defun mapatoms function &optional obarray | |
| 347 This function calls @var{function} for each symbol in the obarray | |
| 348 @var{obarray}. It returns @code{nil}. If @var{obarray} is omitted, it | |
| 349 defaults to the value of @code{obarray}, the standard obarray for | |
| 350 ordinary symbols. | |
| 351 | |
| 352 @smallexample | |
| 353 (setq count 0) | |
| 354 @result{} 0 | |
| 355 (defun count-syms (s) | |
| 356 (setq count (1+ count))) | |
| 357 @result{} count-syms | |
| 358 (mapatoms 'count-syms) | |
| 359 @result{} nil | |
| 360 count | |
| 361 @result{} 1871 | |
| 362 @end smallexample | |
| 363 | |
| 364 See @code{documentation} in @ref{Accessing Documentation}, for another | |
| 365 example using @code{mapatoms}. | |
| 366 @end defun | |
| 367 | |
| 368 @defun unintern symbol &optional obarray | |
| 369 This function deletes @var{symbol} from the obarray @var{obarray}. If | |
| 370 @code{symbol} is not actually in the obarray, @code{unintern} does | |
| 371 nothing. If @var{obarray} is @code{nil}, the current obarray is used. | |
| 372 | |
| 373 If you provide a string instead of a symbol as @var{symbol}, it stands | |
| 374 for a symbol name. Then @code{unintern} deletes the symbol (if any) in | |
| 375 the obarray which has that name. If there is no such symbol, | |
| 376 @code{unintern} does nothing. | |
| 377 | |
| 378 If @code{unintern} does delete a symbol, it returns @code{t}. Otherwise | |
| 379 it returns @code{nil}. | |
| 380 @end defun | |
| 381 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5677
diff
changeset
|
382 @node Symbol Properties, , Creating Symbols, Symbols |
| 428 | 383 @section Symbol Properties |
| 384 @cindex property list, symbol | |
| 385 @cindex plist, symbol | |
| 386 | |
| 387 A @dfn{property list} (@dfn{plist} for short) is a list of paired | |
| 442 | 388 elements, often stored in the property list cell of a symbol. Each of |
| 389 the pairs associates a property name (usually a symbol) with a property | |
| 390 or value. Property lists are generally used to record information about | |
| 391 a symbol, such as its documentation as a variable, the name of the file | |
| 428 | 392 where it was defined, or perhaps even the grammatical class of the |
| 393 symbol (representing a word) in a language-understanding system. | |
| 394 | |
| 442 | 395 Some objects which are not symbols also have property lists associated |
| 428 | 396 with them, and XEmacs provides a full complement of functions for |
| 397 working with property lists. @xref{Property Lists}. | |
| 398 | |
| 399 The property names and values in a property list can be any Lisp | |
| 400 objects, but the names are usually symbols. They are compared using | |
| 401 @code{eq}. Here is an example of a property list, found on the symbol | |
| 402 @code{progn} when the compiler is loaded: | |
| 403 | |
| 404 @example | |
| 405 (lisp-indent-function 0 byte-compile byte-compile-progn) | |
| 406 @end example | |
| 407 | |
| 408 @noindent | |
| 409 Here @code{lisp-indent-function} and @code{byte-compile} are property | |
| 410 names, and the other two elements are the corresponding values. | |
| 411 | |
| 412 @menu | |
| 413 * Plists and Alists:: Comparison of the advantages of property | |
| 414 lists and association lists. | |
| 442 | 415 * Object Plists:: Functions to access objects' property lists. |
| 428 | 416 * Other Plists:: Accessing property lists stored elsewhere. |
| 417 @end menu | |
| 418 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5677
diff
changeset
|
419 @node Plists and Alists, Object Plists, Symbol Properties, Symbol Properties |
| 428 | 420 @subsection Property Lists and Association Lists |
| 421 | |
| 422 @cindex property lists vs association lists | |
| 423 Association lists (@pxref{Association Lists}) are very similar to | |
| 424 property lists. In contrast to association lists, the order of the | |
| 425 pairs in the property list is not significant since the property names | |
| 426 must be distinct. | |
| 427 | |
| 428 Property lists are better than association lists for attaching | |
| 429 information to various Lisp function names or variables. If all the | |
| 430 associations are recorded in one association list, the program will need | |
| 431 to search that entire list each time a function or variable is to be | |
| 432 operated on. By contrast, if the information is recorded in the | |
| 433 property lists of the function names or variables themselves, each | |
| 434 search will scan only the length of one property list, which is usually | |
| 435 short. This is why the documentation for a variable is recorded in a | |
| 436 property named @code{variable-documentation}. The byte compiler | |
| 437 likewise uses properties to record those functions needing special | |
| 438 treatment. | |
| 439 | |
| 440 However, association lists have their own advantages. Depending on | |
| 441 your application, it may be faster to add an association to the front of | |
| 442 an association list than to update a property. All properties for a | |
| 443 symbol are stored in the same property list, so there is a possibility | |
| 444 of a conflict between different uses of a property name. (For this | |
| 445 reason, it is a good idea to choose property names that are probably | |
| 446 unique, such as by including the name of the library in the property | |
| 447 name.) An association list may be used like a stack where associations | |
| 448 are pushed on the front of the list and later discarded; this is not | |
| 449 possible with a property list. | |
| 450 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5677
diff
changeset
|
451 @node Object Plists, Other Plists, Plists and Alists, Symbol Properties |
| 442 | 452 @subsection Property List Functions for Objects |
| 453 | |
| 454 Once upon a time, only symbols had property lists. Now, several other | |
| 455 object types, including strings, extents, faces and glyphs also have | |
| 456 property lists. | |
| 428 | 457 |
| 458 @defun symbol-plist symbol | |
| 459 This function returns the property list of @var{symbol}. | |
| 460 @end defun | |
| 461 | |
| 442 | 462 @defun object-plist object |
| 463 This function returns the property list of @var{object}. If | |
| 464 @var{object} is a symbol, this is identical to @code{symbol-plist}. | |
| 465 @end defun | |
| 466 | |
| 428 | 467 @defun setplist symbol plist |
| 468 This function sets @var{symbol}'s property list to @var{plist}. | |
| 469 Normally, @var{plist} should be a well-formed property list, but this is | |
| 470 not enforced. | |
| 471 | |
| 472 @smallexample | |
| 473 (setplist 'foo '(a 1 b (2 3) c nil)) | |
| 474 @result{} (a 1 b (2 3) c nil) | |
| 475 (symbol-plist 'foo) | |
| 476 @result{} (a 1 b (2 3) c nil) | |
| 477 @end smallexample | |
| 478 | |
| 479 For symbols in special obarrays, which are not used for ordinary | |
| 480 purposes, it may make sense to use the property list cell in a | |
| 481 nonstandard fashion; in fact, the abbrev mechanism does so | |
| 442 | 482 (@pxref{Abbrevs}). But generally, its use is discouraged. Use |
| 483 @code{put} instead. @code{setplist} can only be used with symbols, not | |
| 484 other object types. | |
| 428 | 485 @end defun |
| 486 | |
| 442 | 487 @defun get object property &optional default |
| 428 | 488 This function finds the value of the property named @var{property} in |
| 442 | 489 @var{object}'s property list. If there is no such property, |
| 490 @code{default} (which itself defaults to @code{nil}) is returned. | |
| 428 | 491 |
| 442 | 492 @var{property} is compared with the existing properties using @code{eq}, |
| 493 so any object is a legitimate property. | |
| 428 | 494 |
| 495 See @code{put} for an example. | |
| 496 @end defun | |
| 497 | |
| 442 | 498 @defun put object property value |
| 499 This function puts @var{value} onto @var{object}'s property list under | |
| 428 | 500 the property name @var{property}, replacing any previous property value. |
| 501 The @code{put} function returns @var{value}. | |
| 502 | |
| 503 @smallexample | |
| 504 (put 'fly 'verb 'transitive) | |
| 505 @result{}'transitive | |
| 506 (put 'fly 'noun '(a buzzing little bug)) | |
| 507 @result{} (a buzzing little bug) | |
| 508 (get 'fly 'verb) | |
| 509 @result{} transitive | |
| 442 | 510 (object-plist 'fly) |
| 428 | 511 @result{} (verb transitive noun (a buzzing little bug)) |
| 512 @end smallexample | |
| 513 @end defun | |
| 514 | |
| 442 | 515 @defun remprop object property |
| 516 This function removes the entry for @var{property} from the property | |
| 517 list of @var{object}. It returns @code{t} if the property was | |
| 518 indeed found and removed, or @code{nil} if there was no such property. | |
| 519 (This function was probably omitted from Emacs originally because, | |
| 520 since @code{get} did not allow a @var{default}, it was very difficult | |
| 521 to distinguish between a missing property and a property whose value | |
| 522 was @code{nil}; thus, setting a property to @code{nil} was close | |
| 523 enough to @code{remprop} for most purposes.) | |
| 524 @end defun | |
| 525 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5677
diff
changeset
|
526 @node Other Plists, , Object Plists, Symbol Properties |
| 442 | 527 @subsection Property Lists Not Associated with Objects |
| 428 | 528 |
| 529 These functions are useful for manipulating property lists | |
| 530 that are stored in places other than symbols: | |
| 531 | |
| 532 @defun getf plist property &optional default | |
| 533 This returns the value of the @var{property} property | |
| 534 stored in the property list @var{plist}. For example, | |
| 535 | |
| 536 @example | |
| 537 (getf '(foo 4) 'foo) | |
| 538 @result{} 4 | |
| 539 @end example | |
| 540 @end defun | |
| 541 | |
| 444 | 542 @defmac putf plist property value |
| 428 | 543 This stores @var{value} as the value of the @var{property} property in |
| 544 the property list @var{plist}. It may modify @var{plist} destructively, | |
| 545 or it may construct a new list structure without altering the old. The | |
| 546 function returns the modified property list, so you can store that back | |
| 547 in the place where you got @var{plist}. For example, | |
| 548 | |
| 549 @example | |
| 550 (setq my-plist '(bar t foo 4)) | |
| 551 @result{} (bar t foo 4) | |
| 552 (setq my-plist (putf my-plist 'foo 69)) | |
| 553 @result{} (bar t foo 69) | |
| 554 (setq my-plist (putf my-plist 'quux '(a))) | |
| 555 @result{} (quux (a) bar t foo 5) | |
| 556 @end example | |
| 444 | 557 @end defmac |
| 428 | 558 |
| 559 @defun plists-eq a b | |
| 560 This function returns non-@code{nil} if property lists @var{a} and @var{b} | |
| 561 are @code{eq}. This means that the property lists have the same values | |
| 562 for all the same properties, where comparison between values is done using | |
| 563 @code{eq}. | |
| 564 @end defun | |
| 565 | |
| 566 @defun plists-equal a b | |
| 567 This function returns non-@code{nil} if property lists @var{a} and @var{b} | |
| 568 are @code{equal}. | |
| 569 @end defun | |
| 570 | |
| 571 Both of the above functions do order-insensitive comparisons. | |
| 572 | |
| 573 @example | |
| 574 (plists-eq '(a 1 b 2 c nil) '(b 2 a 1)) | |
| 575 @result{} t | |
| 576 (plists-eq '(foo "hello" bar "goodbye") '(bar "goodbye" foo "hello")) | |
| 577 @result{} nil | |
| 578 (plists-equal '(foo "hello" bar "goodbye") '(bar "goodbye" foo "hello")) | |
| 579 @result{} t | |
| 580 @end example | |
| 581 | |
| 582 | |
| 583 |