Commit | Line | Data |
---|---|---|
b8d4c8d0 GM |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Emacs Lisp Reference Manual. | |
1e103a7c | 3 | @c Copyright (C) 1990-1995, 1998-1999, 2001-2012 Free Software Foundation, Inc. |
b8d4c8d0 | 4 | @c See the file elisp.texi for copying conditions. |
ecc6530d | 5 | @node Symbols |
b8d4c8d0 GM |
6 | @chapter Symbols |
7 | @cindex symbol | |
8 | ||
9 | A @dfn{symbol} is an object with a unique name. This chapter | |
10 | describes symbols, their components, their property lists, and how they | |
11 | are created and interned. Separate chapters describe the use of symbols | |
12 | as variables and as function names; see @ref{Variables}, and | |
13 | @ref{Functions}. For the precise read syntax for symbols, see | |
14 | @ref{Symbol Type}. | |
15 | ||
f02f19bd CY |
16 | You can test whether an arbitrary Lisp object is a symbol with |
17 | @code{symbolp}: | |
b8d4c8d0 GM |
18 | |
19 | @defun symbolp object | |
20 | This function returns @code{t} if @var{object} is a symbol, @code{nil} | |
21 | otherwise. | |
22 | @end defun | |
23 | ||
24 | @menu | |
25 | * Symbol Components:: Symbols have names, values, function definitions | |
26 | and property lists. | |
27 | * Definitions:: A definition says how a symbol will be used. | |
28 | * Creating Symbols:: How symbols are kept unique. | |
f02f19bd | 29 | * Symbol Properties:: Each symbol has a property list |
b8d4c8d0 GM |
30 | for recording miscellaneous information. |
31 | @end menu | |
32 | ||
ecc6530d | 33 | @node Symbol Components |
b8d4c8d0 GM |
34 | @section Symbol Components |
35 | @cindex symbol components | |
36 | ||
37 | Each symbol has four components (or ``cells''), each of which | |
38 | references another object: | |
39 | ||
40 | @table @asis | |
41 | @item Print name | |
42 | @cindex print name cell | |
31cbea1d | 43 | The symbol's name. |
b8d4c8d0 GM |
44 | |
45 | @item Value | |
46 | @cindex value cell | |
31cbea1d | 47 | The symbol's current value as a variable. |
b8d4c8d0 GM |
48 | |
49 | @item Function | |
50 | @cindex function cell | |
31cbea1d CY |
51 | The symbol's function definition. It can also hold a symbol, a |
52 | keymap, or a keyboard macro. | |
b8d4c8d0 GM |
53 | |
54 | @item Property list | |
55 | @cindex property list cell | |
31cbea1d | 56 | The symbol's property list. |
b8d4c8d0 GM |
57 | @end table |
58 | ||
31cbea1d CY |
59 | @noindent |
60 | The print name cell always holds a string, and cannot be changed. | |
61 | Each of the other three cells can be set to any Lisp object. | |
62 | ||
63 | The print name cell holds the string that is the name of a symbol. | |
64 | Since symbols are represented textually by their names, it is | |
65 | important not to have two symbols with the same name. The Lisp reader | |
66 | ensures this: every time it reads a symbol, it looks for an existing | |
67 | symbol with the specified name before it creates a new one. To get a | |
68 | symbol's name, use the function @code{symbol-name} (@pxref{Creating | |
69 | Symbols}). | |
70 | ||
71 | The value cell holds a symbol's value as a variable, which is what | |
72 | you get if the symbol itself is evaluated as a Lisp expression. | |
73 | @xref{Variables}, for details about how values are set and retrieved, | |
74 | including complications such as @dfn{local bindings} and @dfn{scoping | |
75 | rules}. Most symbols can have any Lisp object as a value, but certain | |
76 | special symbols have values that cannot be changed; these include | |
77 | @code{nil} and @code{t}, and any symbol whose name starts with | |
78 | @samp{:} (those are called @dfn{keywords}). @xref{Constant | |
79 | Variables}. | |
80 | ||
81 | The function cell holds a symbol's function definition. Often, we | |
82 | refer to ``the function @code{foo}'' when we really mean the function | |
83 | stored in the function cell of @code{foo}; we make the distinction | |
84 | explicit only when necessary. Typically, the function cell is used to | |
85 | hold a function (@pxref{Functions}) or a macro (@pxref{Macros}). | |
86 | However, it can also be used to hold a symbol (@pxref{Function | |
87 | Indirection}), keyboard macro (@pxref{Keyboard Macros}), keymap | |
88 | (@pxref{Keymaps}), or autoload object (@pxref{Autoloading}). To get | |
89 | the contents of a symbol's function cell, use the function | |
90 | @code{symbol-function} (@pxref{Function Cells}). | |
b8d4c8d0 GM |
91 | |
92 | The property list cell normally should hold a correctly formatted | |
ddff3351 | 93 | property list. To get a symbol's property list, use the function |
f02f19bd | 94 | @code{symbol-plist}. @xref{Symbol Properties}. |
b8d4c8d0 GM |
95 | |
96 | The function cell or the value cell may be @dfn{void}, which means | |
97 | that the cell does not reference any object. (This is not the same | |
98 | thing as holding the symbol @code{void}, nor the same as holding the | |
99 | symbol @code{nil}.) Examining a function or value cell that is void | |
100 | results in an error, such as @samp{Symbol's value as variable is void}. | |
101 | ||
31cbea1d CY |
102 | Because each symbol has separate value and function cells, variables |
103 | names and function names do not conflict. For example, the symbol | |
104 | @code{buffer-file-name} has a value (the name of the file being | |
105 | visited in the current buffer) as well as a function definition (a | |
106 | primitive function that returns the name of the file): | |
b8d4c8d0 GM |
107 | |
108 | @example | |
31cbea1d | 109 | buffer-file-name |
b8d4c8d0 GM |
110 | @result{} "/gnu/elisp/symbols.texi" |
111 | (symbol-function 'buffer-file-name) | |
112 | @result{} #<subr buffer-file-name> | |
b8d4c8d0 GM |
113 | @end example |
114 | ||
ecc6530d | 115 | @node Definitions |
b8d4c8d0 GM |
116 | @section Defining Symbols |
117 | @cindex definitions of symbols | |
118 | ||
31cbea1d CY |
119 | A @dfn{definition} is a special kind of Lisp expression that |
120 | announces your intention to use a symbol in a particular way. It | |
121 | typically specifies a value or meaning for the symbol for one kind of | |
122 | use, plus documentation for its meaning when used in this way. Thus, | |
123 | when you define a symbol as a variable, you can supply an initial | |
124 | value for the variable, plus documentation for the variable. | |
b8d4c8d0 GM |
125 | |
126 | @code{defvar} and @code{defconst} are special forms that define a | |
31cbea1d CY |
127 | symbol as a @dfn{global variable}---a variable that can be accessed at |
128 | any point in a Lisp program. @xref{Variables}, for details about | |
129 | variables. To define a customizable variable, use the | |
130 | @code{defcustom} macro, which also calls @code{defvar} as a subroutine | |
131 | (@pxref{Customization}). | |
132 | ||
133 | In principle, you can assign a variable value to any symbol with | |
134 | @code{setq}, whether not it has first been defined as a variable. | |
135 | However, you ought to write a variable definition for each global | |
136 | variable that you want to use; otherwise, your Lisp program may not | |
137 | act correctly if it is evaluated with lexical scoping enabled | |
138 | (@pxref{Variable Scoping}). | |
b8d4c8d0 GM |
139 | |
140 | @code{defun} defines a symbol as a function, creating a lambda | |
141 | expression and storing it in the function cell of the symbol. This | |
142 | lambda expression thus becomes the function definition of the symbol. | |
16152b76 | 143 | (The term ``function definition'', meaning the contents of the function |
b8d4c8d0 GM |
144 | cell, is derived from the idea that @code{defun} gives the symbol its |
145 | definition as a function.) @code{defsubst} and @code{defalias} are two | |
146 | other ways of defining a function. @xref{Functions}. | |
147 | ||
148 | @code{defmacro} defines a symbol as a macro. It creates a macro | |
149 | object and stores it in the function cell of the symbol. Note that a | |
150 | given symbol can be a macro or a function, but not both at once, because | |
151 | both macro and function definitions are kept in the function cell, and | |
152 | that cell can hold only one Lisp object at any given time. | |
153 | @xref{Macros}. | |
154 | ||
31cbea1d | 155 | As previously noted, Emacs Lisp allows the same symbol to be defined |
1df7defd PE |
156 | both as a variable (e.g., with @code{defvar}) and as a function or |
157 | macro (e.g., with @code{defun}). Such definitions do not conflict. | |
31cbea1d CY |
158 | |
159 | These definition also act as guides for programming tools. For | |
160 | example, the @kbd{C-h f} and @kbd{C-h v} commands create help buffers | |
161 | containing links to the relevant variable, function, or macro | |
162 | definitions. @xref{Name Help,,, emacs, The GNU Emacs Manual}. | |
b8d4c8d0 | 163 | |
ecc6530d | 164 | @node Creating Symbols |
b8d4c8d0 GM |
165 | @section Creating and Interning Symbols |
166 | @cindex reading symbols | |
167 | ||
168 | To understand how symbols are created in GNU Emacs Lisp, you must know | |
169 | how Lisp reads them. Lisp must ensure that it finds the same symbol | |
170 | every time it reads the same set of characters. Failure to do so would | |
171 | cause complete confusion. | |
172 | ||
173 | @cindex symbol name hashing | |
174 | @cindex hashing | |
175 | @cindex obarray | |
176 | @cindex bucket (in obarray) | |
177 | When the Lisp reader encounters a symbol, it reads all the characters | |
178 | of the name. Then it ``hashes'' those characters to find an index in a | |
179 | table called an @dfn{obarray}. Hashing is an efficient method of | |
180 | looking something up. For example, instead of searching a telephone | |
181 | book cover to cover when looking up Jan Jones, you start with the J's | |
182 | and go from there. That is a simple version of hashing. Each element | |
183 | of the obarray is a @dfn{bucket} which holds all the symbols with a | |
184 | given hash code; to look for a given name, it is sufficient to look | |
185 | through all the symbols in the bucket for that name's hash code. (The | |
186 | same idea is used for general Emacs hash tables, but they are a | |
187 | different data type; see @ref{Hash Tables}.) | |
188 | ||
189 | @cindex interning | |
190 | If a symbol with the desired name is found, the reader uses that | |
191 | symbol. If the obarray does not contain a symbol with that name, the | |
192 | reader makes a new symbol and adds it to the obarray. Finding or adding | |
193 | a symbol with a certain name is called @dfn{interning} it, and the | |
194 | symbol is then called an @dfn{interned symbol}. | |
195 | ||
196 | Interning ensures that each obarray has just one symbol with any | |
197 | particular name. Other like-named symbols may exist, but not in the | |
198 | same obarray. Thus, the reader gets the same symbols for the same | |
199 | names, as long as you keep reading with the same obarray. | |
200 | ||
201 | Interning usually happens automatically in the reader, but sometimes | |
202 | other programs need to do it. For example, after the @kbd{M-x} command | |
203 | obtains the command name as a string using the minibuffer, it then | |
204 | interns the string, to get the interned symbol with that name. | |
205 | ||
206 | @cindex symbol equality | |
207 | @cindex uninterned symbol | |
208 | No obarray contains all symbols; in fact, some symbols are not in any | |
209 | obarray. They are called @dfn{uninterned symbols}. An uninterned | |
210 | symbol has the same four cells as other symbols; however, the only way | |
211 | to gain access to it is by finding it in some other object or as the | |
212 | value of a variable. | |
213 | ||
214 | Creating an uninterned symbol is useful in generating Lisp code, | |
215 | because an uninterned symbol used as a variable in the code you generate | |
216 | cannot clash with any variables used in other Lisp programs. | |
217 | ||
218 | In Emacs Lisp, an obarray is actually a vector. Each element of the | |
219 | vector is a bucket; its value is either an interned symbol whose name | |
220 | hashes to that bucket, or 0 if the bucket is empty. Each interned | |
221 | symbol has an internal link (invisible to the user) to the next symbol | |
222 | in the bucket. Because these links are invisible, there is no way to | |
223 | find all the symbols in an obarray except using @code{mapatoms} (below). | |
224 | The order of symbols in a bucket is not significant. | |
225 | ||
226 | In an empty obarray, every element is 0, so you can create an obarray | |
227 | with @code{(make-vector @var{length} 0)}. @strong{This is the only | |
228 | valid way to create an obarray.} Prime numbers as lengths tend | |
229 | to result in good hashing; lengths one less than a power of two are also | |
230 | good. | |
231 | ||
232 | @strong{Do not try to put symbols in an obarray yourself.} This does | |
233 | not work---only @code{intern} can enter a symbol in an obarray properly. | |
234 | ||
235 | @cindex CL note---symbol in obarrays | |
236 | @quotation | |
31cbea1d CY |
237 | @b{Common Lisp note:} Unlike Common Lisp, Emacs Lisp does not provide |
238 | for interning a single symbol in several obarrays. | |
b8d4c8d0 GM |
239 | @end quotation |
240 | ||
241 | Most of the functions below take a name and sometimes an obarray as | |
242 | arguments. A @code{wrong-type-argument} error is signaled if the name | |
243 | is not a string, or if the obarray is not a vector. | |
244 | ||
245 | @defun symbol-name symbol | |
246 | This function returns the string that is @var{symbol}'s name. For example: | |
247 | ||
248 | @example | |
249 | @group | |
250 | (symbol-name 'foo) | |
251 | @result{} "foo" | |
252 | @end group | |
253 | @end example | |
254 | ||
255 | @strong{Warning:} Changing the string by substituting characters does | |
256 | change the name of the symbol, but fails to update the obarray, so don't | |
257 | do it! | |
258 | @end defun | |
259 | ||
260 | @defun make-symbol name | |
261 | This function returns a newly-allocated, uninterned symbol whose name is | |
262 | @var{name} (which must be a string). Its value and function definition | |
263 | are void, and its property list is @code{nil}. In the example below, | |
264 | the value of @code{sym} is not @code{eq} to @code{foo} because it is a | |
265 | distinct uninterned symbol whose name is also @samp{foo}. | |
266 | ||
267 | @example | |
268 | (setq sym (make-symbol "foo")) | |
269 | @result{} foo | |
270 | (eq sym 'foo) | |
271 | @result{} nil | |
272 | @end example | |
273 | @end defun | |
274 | ||
275 | @defun intern name &optional obarray | |
276 | This function returns the interned symbol whose name is @var{name}. If | |
277 | there is no such symbol in the obarray @var{obarray}, @code{intern} | |
278 | creates a new one, adds it to the obarray, and returns it. If | |
279 | @var{obarray} is omitted, the value of the global variable | |
280 | @code{obarray} is used. | |
281 | ||
282 | @example | |
283 | (setq sym (intern "foo")) | |
284 | @result{} foo | |
285 | (eq sym 'foo) | |
286 | @result{} t | |
287 | ||
288 | (setq sym1 (intern "foo" other-obarray)) | |
289 | @result{} foo | |
290 | (eq sym1 'foo) | |
291 | @result{} nil | |
292 | @end example | |
293 | @end defun | |
294 | ||
295 | @cindex CL note---interning existing symbol | |
296 | @quotation | |
297 | @b{Common Lisp note:} In Common Lisp, you can intern an existing symbol | |
298 | in an obarray. In Emacs Lisp, you cannot do this, because the argument | |
299 | to @code{intern} must be a string, not a symbol. | |
300 | @end quotation | |
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 | The argument @var{name} may also be a symbol; in that case, | |
310 | the function returns @var{name} if @var{name} is interned | |
311 | in the specified obarray, and otherwise @code{nil}. | |
312 | ||
ddff3351 | 313 | @example |
b8d4c8d0 GM |
314 | (intern-soft "frazzle") ; @r{No such symbol exists.} |
315 | @result{} nil | |
316 | (make-symbol "frazzle") ; @r{Create an uninterned one.} | |
317 | @result{} frazzle | |
318 | @group | |
319 | (intern-soft "frazzle") ; @r{That one cannot be found.} | |
320 | @result{} nil | |
321 | @end group | |
322 | @group | |
323 | (setq sym (intern "frazzle")) ; @r{Create an interned one.} | |
324 | @result{} frazzle | |
325 | @end group | |
326 | @group | |
327 | (intern-soft "frazzle") ; @r{That one can be found!} | |
328 | @result{} frazzle | |
329 | @end group | |
330 | @group | |
331 | (eq sym 'frazzle) ; @r{And it is the same one.} | |
332 | @result{} t | |
333 | @end group | |
ddff3351 | 334 | @end example |
b8d4c8d0 GM |
335 | @end defun |
336 | ||
337 | @defvar obarray | |
338 | This variable is the standard obarray for use by @code{intern} and | |
339 | @code{read}. | |
340 | @end defvar | |
341 | ||
342 | @defun mapatoms function &optional obarray | |
343 | @anchor{Definition of mapatoms} | |
344 | This function calls @var{function} once with each symbol in the obarray | |
345 | @var{obarray}. Then it returns @code{nil}. If @var{obarray} is | |
346 | omitted, it defaults to the value of @code{obarray}, the standard | |
347 | obarray for ordinary symbols. | |
348 | ||
ddff3351 | 349 | @example |
b8d4c8d0 GM |
350 | (setq count 0) |
351 | @result{} 0 | |
352 | (defun count-syms (s) | |
353 | (setq count (1+ count))) | |
354 | @result{} count-syms | |
355 | (mapatoms 'count-syms) | |
356 | @result{} nil | |
357 | count | |
358 | @result{} 1871 | |
ddff3351 | 359 | @end example |
b8d4c8d0 GM |
360 | |
361 | See @code{documentation} in @ref{Accessing Documentation}, for another | |
362 | example using @code{mapatoms}. | |
363 | @end defun | |
364 | ||
ec8a6295 | 365 | @defun unintern symbol obarray |
b8d4c8d0 GM |
366 | This function deletes @var{symbol} from the obarray @var{obarray}. If |
367 | @code{symbol} is not actually in the obarray, @code{unintern} does | |
368 | nothing. If @var{obarray} is @code{nil}, the current obarray is used. | |
369 | ||
370 | If you provide a string instead of a symbol as @var{symbol}, it stands | |
371 | for a symbol name. Then @code{unintern} deletes the symbol (if any) in | |
372 | the obarray which has that name. If there is no such symbol, | |
373 | @code{unintern} does nothing. | |
374 | ||
375 | If @code{unintern} does delete a symbol, it returns @code{t}. Otherwise | |
376 | it returns @code{nil}. | |
377 | @end defun | |
378 | ||
f02f19bd CY |
379 | @node Symbol Properties |
380 | @section Symbol Properties | |
381 | @cindex symbol property | |
b8d4c8d0 | 382 | |
f02f19bd CY |
383 | A symbol may possess any number of @dfn{symbol properties}, which |
384 | can be used to record miscellaneous information about the symbol. For | |
385 | example, when a symbol has a @code{risky-local-variable} property with | |
386 | a non-@code{nil} value, that means the variable which the symbol names | |
387 | is a risky file-local variable (@pxref{File Local Variables}). | |
b8d4c8d0 | 388 | |
f02f19bd CY |
389 | Each symbol's properties and property values are stored in the |
390 | symbol's property list cell (@pxref{Symbol Components}), in the form | |
391 | of a property list (@pxref{Property Lists}). | |
b8d4c8d0 GM |
392 | |
393 | @menu | |
f02f19bd CY |
394 | * Symbol Plists:: Accessing symbol properties. |
395 | * Standard Properties:: Standard meanings of symbol properties. | |
b8d4c8d0 GM |
396 | @end menu |
397 | ||
b8d4c8d0 | 398 | @node Symbol Plists |
f02f19bd | 399 | @subsection Accessing Symbol Properties |
b8d4c8d0 | 400 | |
f02f19bd | 401 | The following functions can be used to access symbol properties. |
b8d4c8d0 GM |
402 | |
403 | @defun get symbol property | |
f02f19bd CY |
404 | This function returns the value of the property named @var{property} |
405 | in @var{symbol}'s property list. If there is no such property, it | |
406 | returns @code{nil}. Thus, there is no distinction between a value of | |
b8d4c8d0 GM |
407 | @code{nil} and the absence of the property. |
408 | ||
409 | The name @var{property} is compared with the existing property names | |
410 | using @code{eq}, so any object is a legitimate property. | |
411 | ||
412 | See @code{put} for an example. | |
413 | @end defun | |
414 | ||
415 | @defun put symbol property value | |
416 | This function puts @var{value} onto @var{symbol}'s property list under | |
417 | the property name @var{property}, replacing any previous property value. | |
418 | The @code{put} function returns @var{value}. | |
419 | ||
ddff3351 | 420 | @example |
b8d4c8d0 GM |
421 | (put 'fly 'verb 'transitive) |
422 | @result{}'transitive | |
423 | (put 'fly 'noun '(a buzzing little bug)) | |
424 | @result{} (a buzzing little bug) | |
425 | (get 'fly 'verb) | |
426 | @result{} transitive | |
427 | (symbol-plist 'fly) | |
428 | @result{} (verb transitive noun (a buzzing little bug)) | |
ddff3351 | 429 | @end example |
b8d4c8d0 GM |
430 | @end defun |
431 | ||
f02f19bd CY |
432 | @defun symbol-plist symbol |
433 | This function returns the property list of @var{symbol}. | |
b8d4c8d0 GM |
434 | @end defun |
435 | ||
f02f19bd CY |
436 | @defun setplist symbol plist |
437 | This function sets @var{symbol}'s property list to @var{plist}. | |
438 | Normally, @var{plist} should be a well-formed property list, but this is | |
439 | not enforced. The return value is @var{plist}. | |
b8d4c8d0 GM |
440 | |
441 | @example | |
f02f19bd CY |
442 | (setplist 'foo '(a 1 b (2 3) c nil)) |
443 | @result{} (a 1 b (2 3) c nil) | |
444 | (symbol-plist 'foo) | |
445 | @result{} (a 1 b (2 3) c nil) | |
b8d4c8d0 GM |
446 | @end example |
447 | ||
f02f19bd CY |
448 | For symbols in special obarrays, which are not used for ordinary |
449 | purposes, it may make sense to use the property list cell in a | |
450 | nonstandard fashion; in fact, the abbrev mechanism does so | |
451 | (@pxref{Abbrevs}). | |
a20ae0b9 CY |
452 | |
453 | You could define @code{put} in terms of @code{setplist} and | |
454 | @code{plist-put}, as follows: | |
455 | ||
456 | @example | |
457 | (defun put (symbol prop value) | |
458 | (setplist symbol | |
459 | (plist-put (symbol-plist symbol) prop value))) | |
460 | @end example | |
b8d4c8d0 GM |
461 | @end defun |
462 | ||
f02f19bd CY |
463 | @defun function-get symbol property |
464 | This function is identical to @code{get}, except that if @var{symbol} | |
465 | is the name of a function alias, it looks in the property list of the | |
466 | symbol naming the actual function. @xref{Defining Functions}. | |
b8d4c8d0 GM |
467 | @end defun |
468 | ||
f02f19bd CY |
469 | @node Standard Properties |
470 | @subsection Standard Symbol Properties | |
471 | ||
472 | Here, we list the symbol properties which are used for special | |
473 | purposes in Emacs. In the following table, whenever we say ``the | |
474 | named function'', that means the function whose name is the relevant | |
475 | symbol; similarly for ``the named variable'' etc. | |
476 | ||
477 | @table @code | |
478 | @item :advertised-binding | |
479 | This property value specifies the preferred key binding, when showing | |
480 | documentation, for the named function. @xref{Keys in Documentation}. | |
481 | ||
482 | @item char-table-extra-slots | |
483 | The value, if non-@code{nil}, specifies the number of extra slots in | |
484 | the named char-table type. @xref{Char-Tables}. | |
485 | ||
a20ae0b9 CY |
486 | @item customized-face |
487 | @itemx face-defface-spec | |
f02f19bd CY |
488 | @itemx saved-face |
489 | @itemx theme-face | |
490 | These properties are used to record a face's standard, saved, | |
491 | customized, and themed face specs. Do not set them directly; they are | |
492 | managed by @code{defface} and related functions. @xref{Defining | |
493 | Faces}. | |
494 | ||
a20ae0b9 | 495 | @item customized-value |
f02f19bd | 496 | @itemx saved-value |
a20ae0b9 | 497 | @itemx standard-value |
f02f19bd CY |
498 | @itemx theme-value |
499 | These properties are used to record a customizable variable's standard | |
500 | value, saved value, customized-but-unsaved value, and themed values. | |
501 | Do not set them directly; they are managed by @code{defcustom} and | |
502 | related functions. @xref{Variable Definitions}. | |
503 | ||
504 | @item disabled | |
505 | If the value is non-@code{nil}, the named function is disabled as a | |
506 | command. @xref{Disabling Commands}. | |
507 | ||
508 | @item face-documentation | |
509 | The value stores the documentation string of the named face. This is | |
a20ae0b9 | 510 | set automatically by @code{defface}. @xref{Defining Faces}. |
f02f19bd CY |
511 | |
512 | @item history-length | |
513 | The value, if non-@code{nil}, specifies the maximum minibuffer history | |
514 | length for the named history list variable. @xref{Minibuffer | |
515 | History}. | |
516 | ||
517 | @item interactive-form | |
518 | The value is an interactive form for the named function. Normally, | |
519 | you should not set this directly; use the @code{interactive} special | |
520 | form instead. @xref{Interactive Call}. | |
521 | ||
522 | @item menu-enable | |
523 | The value is an expression for determining whether the named menu item | |
524 | should be enabled in menus. @xref{Simple Menu Items}. | |
525 | ||
526 | @item mode-class | |
527 | If the value is @code{special}, the named major mode is ``special''. | |
528 | @xref{Major Mode Conventions}. | |
529 | ||
530 | @item permanent-local | |
531 | If the value is non-@code{nil}, the named variable is a buffer-local | |
532 | variable whose value should not be reset when changing major modes. | |
533 | @xref{Creating Buffer-Local}. | |
534 | ||
535 | @item permanent-local-hook | |
536 | If the value is non-@code{nil}, the named function should not be | |
537 | deleted from the local value of a hook variable when changing major | |
538 | modes. @xref{Setting Hooks}. | |
539 | ||
540 | @item pure | |
541 | This property is used internally to mark certain named functions for | |
542 | byte compiler optimization. Do not set it. | |
543 | ||
544 | @item risky-local-variable | |
545 | If the value is non-@code{nil}, the named variable is considered risky | |
546 | as a file-local variable. @xref{File Local Variables}. | |
547 | ||
548 | @item safe-function | |
549 | If the value is non-@code{nil}, the named function is considered | |
550 | generally safe for evaluation. @xref{Function Safety}. | |
551 | ||
552 | @item safe-local-eval-function | |
553 | If the value is non-@code{nil}, the named function is safe to call in | |
554 | file-local evaluation forms. @xref{File Local Variables}. | |
555 | ||
556 | @item safe-local-variable | |
557 | The value specifies a function for determining safe file-local values | |
558 | for the named variable. @xref{File Local Variables}. | |
559 | ||
560 | @item side-effect-free | |
561 | A non-@code{nil} value indicates that the named function is free of | |
562 | side-effects, for determining function safety (@pxref{Function | |
563 | Safety}) as well as for byte compiler optimizations. Do not set it. | |
564 | ||
565 | @item variable-documentation | |
f24f2e22 | 566 | If non-@code{nil}, this specifies the named variable's documentation |
a20ae0b9 CY |
567 | string. This is set automatically by @code{defvar} and related |
568 | functions. @xref{Defining Faces}. | |
f02f19bd | 569 | @end table |