X-Git-Url: https://git.hcoop.net/bpt/emacs.git/blobdiff_plain/77ab81d0545e980c57c0a35510ade29a9e43b4cd..ab422c4d6899b1442cb6954c1829c1fb656b006c:/doc/lispref/symbols.texi diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi index 257a2a4c9a..3e6c8266ef 100644 --- a/doc/lispref/symbols.texi +++ b/doc/lispref/symbols.texi @@ -1,10 +1,9 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc. +@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software +@c Foundation, Inc. @c See the file elisp.texi for copying conditions. -@setfilename ../../info/symbols -@node Symbols, Evaluation, Hash Tables, Top +@node Symbols @chapter Symbols @cindex symbol @@ -15,8 +14,8 @@ as variables and as function names; see @ref{Variables}, and @ref{Functions}. For the precise read syntax for symbols, see @ref{Symbol Type}. - You can test whether an arbitrary Lisp object is a symbol -with @code{symbolp}: + You can test whether an arbitrary Lisp object is a symbol with +@code{symbolp}: @defun symbolp object This function returns @code{t} if @var{object} is a symbol, @code{nil} @@ -28,11 +27,11 @@ otherwise. and property lists. * Definitions:: A definition says how a symbol will be used. * Creating Symbols:: How symbols are kept unique. -* Property Lists:: Each symbol has a property list +* Symbol Properties:: Each symbol has a property list for recording miscellaneous information. @end menu -@node Symbol Components, Definitions, Symbols, Symbols +@node Symbol Components @section Symbol Components @cindex symbol components @@ -42,62 +41,58 @@ references another object: @table @asis @item Print name @cindex print name cell -The @dfn{print name cell} holds a string that names the symbol for -reading and printing. See @code{symbol-name} in @ref{Creating Symbols}. +The symbol's name. @item Value @cindex value cell -The @dfn{value cell} holds the current value of the symbol as a -variable. When a symbol is used as a form, the value of the form is the -contents of the symbol's value cell. See @code{symbol-value} in -@ref{Accessing Variables}. +The symbol's current value as a variable. @item Function @cindex function cell -The @dfn{function cell} holds the function definition of the symbol. -When a symbol is used as a function, its function definition is used in -its place. This cell is also used to make a symbol stand for a keymap -or a keyboard macro, for editor command execution. Because each symbol -has separate value and function cells, variables names and function names do -not conflict. See @code{symbol-function} in @ref{Function Cells}. +The symbol's function definition. It can also hold a symbol, a +keymap, or a keyboard macro. @item Property list @cindex property list cell -The @dfn{property list cell} holds the property list of the symbol. See -@code{symbol-plist} in @ref{Property Lists}. +The symbol's property list. @end table - The print name cell always holds a string, and cannot be changed. The -other three cells can be set individually to any specified Lisp object. - - The print name cell holds the string that is the name of the symbol. -Since symbols are represented textually by their names, it is important -not to have two symbols with the same name. The Lisp reader ensures -this: every time it reads a symbol, it looks for an existing symbol with -the specified name before it creates a new one. (In GNU Emacs Lisp, -this lookup uses a hashing algorithm and an obarray; see @ref{Creating -Symbols}.) - - The value cell holds the symbol's value as a variable -(@pxref{Variables}). That is what you get if you evaluate the symbol as -a Lisp expression (@pxref{Evaluation}). Any Lisp object is a legitimate -value. Certain symbols have values that cannot be changed; these -include @code{nil} and @code{t}, and any symbol whose name starts with -@samp{:} (those are called @dfn{keywords}). @xref{Constant Variables}. - - We often refer to ``the function @code{foo}'' when we really mean -the function stored in the function cell of the symbol @code{foo}. We -make the distinction explicit only when necessary. In normal -usage, the function cell usually contains a function -(@pxref{Functions}) or a macro (@pxref{Macros}), as that is what the -Lisp interpreter expects to see there (@pxref{Evaluation}). Keyboard -macros (@pxref{Keyboard Macros}), keymaps (@pxref{Keymaps}) and -autoload objects (@pxref{Autoloading}) are also sometimes stored in -the function cells of symbols. +@noindent +The print name cell always holds a string, and cannot be changed. +Each of the other three cells can be set to any Lisp object. + + The print name cell holds the string that is the name of a symbol. +Since symbols are represented textually by their names, it is +important not to have two symbols with the same name. The Lisp reader +ensures this: every time it reads a symbol, it looks for an existing +symbol with the specified name before it creates a new one. To get a +symbol's name, use the function @code{symbol-name} (@pxref{Creating +Symbols}). + + The value cell holds a symbol's value as a variable, which is what +you get if the symbol itself is evaluated as a Lisp expression. +@xref{Variables}, for details about how values are set and retrieved, +including complications such as @dfn{local bindings} and @dfn{scoping +rules}. Most symbols can have any Lisp object as a value, but certain +special symbols have values that cannot be changed; these include +@code{nil} and @code{t}, and any symbol whose name starts with +@samp{:} (those are called @dfn{keywords}). @xref{Constant +Variables}. + + The function cell holds a symbol's function definition. Often, we +refer to ``the function @code{foo}'' when we really mean the function +stored in the function cell of @code{foo}; we make the distinction +explicit only when necessary. Typically, the function cell is used to +hold a function (@pxref{Functions}) or a macro (@pxref{Macros}). +However, it can also be used to hold a symbol (@pxref{Function +Indirection}), keyboard macro (@pxref{Keyboard Macros}), keymap +(@pxref{Keymaps}), or autoload object (@pxref{Autoloading}). To get +the contents of a symbol's function cell, use the function +@code{symbol-function} (@pxref{Function Cells}). The property list cell normally should hold a correctly formatted -property list (@pxref{Property Lists}), as a number of functions expect -to see a property list there. +property list. To get a symbol's property list, use the function +@code{symbol-plist}. @xref{Symbol Properties}. The function cell or the value cell may be @dfn{void}, which means that the cell does not reference any object. (This is not the same @@ -105,62 +100,48 @@ thing as holding the symbol @code{void}, nor the same as holding the symbol @code{nil}.) Examining a function or value cell that is void results in an error, such as @samp{Symbol's value as variable is void}. - The four functions @code{symbol-name}, @code{symbol-value}, -@code{symbol-plist}, and @code{symbol-function} return the contents of -the four cells of a symbol. Here as an example we show the contents of -the four cells of the symbol @code{buffer-file-name}: + Because each symbol has separate value and function cells, variables +names and function names do not conflict. For example, the symbol +@code{buffer-file-name} has a value (the name of the file being +visited in the current buffer) as well as a function definition (a +primitive function that returns the name of the file): @example -(symbol-name 'buffer-file-name) - @result{} "buffer-file-name" -(symbol-value 'buffer-file-name) +buffer-file-name @result{} "/gnu/elisp/symbols.texi" (symbol-function 'buffer-file-name) @result{} # -(symbol-plist 'buffer-file-name) - @result{} (variable-documentation 29529) @end example -@noindent -Because this symbol is the variable which holds the name of the file -being visited in the current buffer, the value cell contents we see are -the name of the source file of this chapter of the Emacs Lisp Manual. -The property list cell contains the list @code{(variable-documentation -29529)} which tells the documentation functions where to find the -documentation string for the variable @code{buffer-file-name} in the -@file{DOC-@var{version}} file. (29529 is the offset from the beginning -of the @file{DOC-@var{version}} file to where that documentation string -begins---see @ref{Documentation Basics}.) The function cell contains -the function for returning the name of the file. -@code{buffer-file-name} names a primitive function, which has no read -syntax and prints in hash notation (@pxref{Primitive Function Type}). A -symbol naming a function written in Lisp would have a lambda expression -(or a byte-code object) in this cell. - -@node Definitions, Creating Symbols, Symbol Components, Symbols +@node Definitions @section Defining Symbols @cindex definitions of symbols - A @dfn{definition} in Lisp is a special form that announces your -intention to use a certain symbol in a particular way. In Emacs Lisp, -you can define a symbol as a variable, or define it as a function (or -macro), or both independently. - - A definition construct typically specifies a value or meaning for the -symbol for one kind of use, plus documentation for its meaning when used -in this way. Thus, when you define a symbol as a variable, you can -supply an initial value for the variable, plus documentation for the -variable. + A @dfn{definition} is a special kind of Lisp expression that +announces your intention to use a symbol in a particular way. It +typically specifies a value or meaning for the symbol for one kind of +use, plus documentation for its meaning when used in this way. Thus, +when you define a symbol as a variable, you can supply an initial +value for the variable, plus documentation for the variable. @code{defvar} and @code{defconst} are special forms that define a -symbol as a global variable. They are documented in detail in -@ref{Defining Variables}. For defining user option variables that can -be customized, use @code{defcustom} (@pxref{Customization}). +symbol as a @dfn{global variable}---a variable that can be accessed at +any point in a Lisp program. @xref{Variables}, for details about +variables. To define a customizable variable, use the +@code{defcustom} macro, which also calls @code{defvar} as a subroutine +(@pxref{Customization}). + + In principle, you can assign a variable value to any symbol with +@code{setq}, whether not it has first been defined as a variable. +However, you ought to write a variable definition for each global +variable that you want to use; otherwise, your Lisp program may not +act correctly if it is evaluated with lexical scoping enabled +(@pxref{Variable Scoping}). @code{defun} defines a symbol as a function, creating a lambda expression and storing it in the function cell of the symbol. This lambda expression thus becomes the function definition of the symbol. -(The term ``function definition,'' meaning the contents of the function +(The term ``function definition'', meaning the contents of the function cell, is derived from the idea that @code{defun} gives the symbol its definition as a function.) @code{defsubst} and @code{defalias} are two other ways of defining a function. @xref{Functions}. @@ -172,17 +153,16 @@ both macro and function definitions are kept in the function cell, and that cell can hold only one Lisp object at any given time. @xref{Macros}. - In Emacs Lisp, a definition is not required in order to use a symbol -as a variable or function. Thus, you can make a symbol a global -variable with @code{setq}, whether you define it first or not. The real -purpose of definitions is to guide programmers and programming tools. -They inform programmers who read the code that certain symbols are -@emph{intended} to be used as variables, or as functions. In addition, -utilities such as @file{etags} and @file{make-docfile} recognize -definitions, and add appropriate information to tag tables and the -@file{DOC-@var{version}} file. @xref{Accessing Documentation}. - -@node Creating Symbols, Property Lists, Definitions, Symbols + As previously noted, Emacs Lisp allows the same symbol to be defined +both as a variable (e.g., with @code{defvar}) and as a function or +macro (e.g., with @code{defun}). Such definitions do not conflict. + + These definition also act as guides for programming tools. For +example, the @kbd{C-h f} and @kbd{C-h v} commands create help buffers +containing links to the relevant variable, function, or macro +definitions. @xref{Name Help,,, emacs, The GNU Emacs Manual}. + +@node Creating Symbols @section Creating and Interning Symbols @cindex reading symbols @@ -255,8 +235,8 @@ not work---only @code{intern} can enter a symbol in an obarray properly. @cindex CL note---symbol in obarrays @quotation -@b{Common Lisp note:} In Common Lisp, a single symbol may be interned in -several obarrays. +@b{Common Lisp note:} Unlike Common Lisp, Emacs Lisp does not provide +for interning a single symbol in several obarrays. @end quotation Most of the functions below take a name and sometimes an obarray as @@ -331,7 +311,7 @@ The argument @var{name} may also be a symbol; in that case, the function returns @var{name} if @var{name} is interned in the specified obarray, and otherwise @code{nil}. -@smallexample +@example (intern-soft "frazzle") ; @r{No such symbol exists.} @result{} nil (make-symbol "frazzle") ; @r{Create an uninterned one.} @@ -352,7 +332,7 @@ in the specified obarray, and otherwise @code{nil}. (eq sym 'frazzle) ; @r{And it is the same one.} @result{} t @end group -@end smallexample +@end example @end defun @defvar obarray @@ -367,7 +347,7 @@ This function calls @var{function} once with each symbol in the obarray omitted, it defaults to the value of @code{obarray}, the standard obarray for ordinary symbols. -@smallexample +@example (setq count 0) @result{} 0 (defun count-syms (s) @@ -377,7 +357,7 @@ obarray for ordinary symbols. @result{} nil count @result{} 1871 -@end smallexample +@end example See @code{documentation} in @ref{Accessing Documentation}, for another example using @code{mapatoms}. @@ -397,108 +377,34 @@ If @code{unintern} does delete a symbol, it returns @code{t}. Otherwise it returns @code{nil}. @end defun -@node Property Lists,, Creating Symbols, Symbols -@section Property Lists -@cindex property list -@cindex plist - - A @dfn{property list} (@dfn{plist} for short) is a list of paired -elements. Each of the pairs associates a property name (usually a -symbol) with a property or value. - - Every symbol has a cell that stores a property list (@pxref{Symbol -Components}). This property list is used to record information about -the symbol, such as its variable documentation and the name of the -file where it was defined. - - Property lists can also be used in other contexts. For instance, -you can assign property lists to character positions in a string or -buffer. @xref{Text Properties}. +@node Symbol Properties +@section Symbol Properties +@cindex symbol property - The property names and values in a property list can be any Lisp -objects, but the names are usually symbols. Property list functions -compare the property names using @code{eq}. Here is an example of a -property list, found on the symbol @code{progn} when the compiler is -loaded: + A symbol may possess any number of @dfn{symbol properties}, which +can be used to record miscellaneous information about the symbol. For +example, when a symbol has a @code{risky-local-variable} property with +a non-@code{nil} value, that means the variable which the symbol names +is a risky file-local variable (@pxref{File Local Variables}). -@example -(lisp-indent-function 0 byte-compile byte-compile-progn) -@end example - -@noindent -Here @code{lisp-indent-function} and @code{byte-compile} are property -names, and the other two elements are the corresponding values. + Each symbol's properties and property values are stored in the +symbol's property list cell (@pxref{Symbol Components}), in the form +of a property list (@pxref{Property Lists}). @menu -* Plists and Alists:: Comparison of the advantages of property - lists and association lists. -* Symbol Plists:: Functions to access symbols' property lists. -* Other Plists:: Accessing property lists stored elsewhere. +* Symbol Plists:: Accessing symbol properties. +* Standard Properties:: Standard meanings of symbol properties. @end menu -@node Plists and Alists -@subsection Property Lists and Association Lists -@cindex plist vs. alist -@cindex alist vs. plist - -@cindex property lists vs association lists - Association lists (@pxref{Association Lists}) are very similar to -property lists. In contrast to association lists, the order of the -pairs in the property list is not significant since the property names -must be distinct. - - Property lists are better than association lists for attaching -information to various Lisp function names or variables. If your -program keeps all of its associations in one association list, it will -typically need to search that entire list each time it checks for an -association. This could be slow. By contrast, if you keep the same -information in the property lists of the function names or variables -themselves, each search will scan only the length of one property list, -which is usually short. This is why the documentation for a variable is -recorded in a property named @code{variable-documentation}. The byte -compiler likewise uses properties to record those functions needing -special treatment. - - However, association lists have their own advantages. Depending on -your application, it may be faster to add an association to the front of -an association list than to update a property. All properties for a -symbol are stored in the same property list, so there is a possibility -of a conflict between different uses of a property name. (For this -reason, it is a good idea to choose property names that are probably -unique, such as by beginning the property name with the program's usual -name-prefix for variables and functions.) An association list may be -used like a stack where associations are pushed on the front of the list -and later discarded; this is not possible with a property list. - @node Symbol Plists -@subsection Property List Functions for Symbols - -@defun symbol-plist symbol -This function returns the property list of @var{symbol}. -@end defun - -@defun setplist symbol plist -This function sets @var{symbol}'s property list to @var{plist}. -Normally, @var{plist} should be a well-formed property list, but this is -not enforced. The return value is @var{plist}. - -@smallexample -(setplist 'foo '(a 1 b (2 3) c nil)) - @result{} (a 1 b (2 3) c nil) -(symbol-plist 'foo) - @result{} (a 1 b (2 3) c nil) -@end smallexample +@subsection Accessing Symbol Properties -For symbols in special obarrays, which are not used for ordinary -purposes, it may make sense to use the property list cell in a -nonstandard fashion; in fact, the abbrev mechanism does so -(@pxref{Abbrevs}). -@end defun + The following functions can be used to access symbol properties. @defun get symbol property -This function finds the value of the property named @var{property} in -@var{symbol}'s property list. If there is no such property, @code{nil} -is returned. Thus, there is no distinction between a value of +This function returns the value of the property named @var{property} +in @var{symbol}'s property list. If there is no such property, it +returns @code{nil}. Thus, there is no distinction between a value of @code{nil} and the absence of the property. The name @var{property} is compared with the existing property names @@ -512,7 +418,7 @@ This function puts @var{value} onto @var{symbol}'s property list under the property name @var{property}, replacing any previous property value. The @code{put} function returns @var{value}. -@smallexample +@example (put 'fly 'verb 'transitive) @result{}'transitive (put 'fly 'noun '(a buzzing little bug)) @@ -521,76 +427,144 @@ The @code{put} function returns @var{value}. @result{} transitive (symbol-plist 'fly) @result{} (verb transitive noun (a buzzing little bug)) -@end smallexample +@end example @end defun -@node Other Plists -@subsection Property Lists Outside Symbols - - These functions are useful for manipulating property lists -that are stored in places other than symbols: - -@defun plist-get plist property -This returns the value of the @var{property} property stored in the -property list @var{plist}. It accepts a malformed @var{plist} -argument. If @var{property} is not found in the @var{plist}, it -returns @code{nil}. For example, - -@example -(plist-get '(foo 4) 'foo) - @result{} 4 -(plist-get '(foo 4 bad) 'foo) - @result{} 4 -(plist-get '(foo 4 bad) 'bad) - @result{} @code{nil} -(plist-get '(foo 4 bad) 'bar) - @result{} nil -@end example +@defun symbol-plist symbol +This function returns the property list of @var{symbol}. @end defun -@defun plist-put plist property value -This stores @var{value} as the value of the @var{property} property in -the property list @var{plist}. It may modify @var{plist} destructively, -or it may construct a new list structure without altering the old. The -function returns the modified property list, so you can store that back -in the place where you got @var{plist}. For example, +@defun setplist symbol plist +This function sets @var{symbol}'s property list to @var{plist}. +Normally, @var{plist} should be a well-formed property list, but this is +not enforced. The return value is @var{plist}. @example -(setq my-plist '(bar t foo 4)) - @result{} (bar t foo 4) -(setq my-plist (plist-put my-plist 'foo 69)) - @result{} (bar t foo 69) -(setq my-plist (plist-put my-plist 'quux '(a))) - @result{} (bar t foo 69 quux (a)) +(setplist 'foo '(a 1 b (2 3) c nil)) + @result{} (a 1 b (2 3) c nil) +(symbol-plist 'foo) + @result{} (a 1 b (2 3) c nil) @end example -@end defun - You could define @code{put} in terms of @code{plist-put} as follows: +For symbols in special obarrays, which are not used for ordinary +purposes, it may make sense to use the property list cell in a +nonstandard fashion; in fact, the abbrev mechanism does so +(@pxref{Abbrevs}). + +You could define @code{put} in terms of @code{setplist} and +@code{plist-put}, as follows: @example (defun put (symbol prop value) (setplist symbol (plist-put (symbol-plist symbol) prop value))) @end example - -@defun lax-plist-get plist property -Like @code{plist-get} except that it compares properties -using @code{equal} instead of @code{eq}. -@end defun - -@defun lax-plist-put plist property value -Like @code{plist-put} except that it compares properties -using @code{equal} instead of @code{eq}. @end defun -@defun plist-member plist property -This returns non-@code{nil} if @var{plist} contains the given -@var{property}. Unlike @code{plist-get}, this allows you to distinguish -between a missing property and a property with the value @code{nil}. -The value is actually the tail of @var{plist} whose @code{car} is -@var{property}. +@defun function-get symbol property +This function is identical to @code{get}, except that if @var{symbol} +is the name of a function alias, it looks in the property list of the +symbol naming the actual function. @xref{Defining Functions}. @end defun -@ignore - arch-tag: 8750b7d2-de4c-4923-809a-d35fc39fd8ce -@end ignore +@node Standard Properties +@subsection Standard Symbol Properties + + Here, we list the symbol properties which are used for special +purposes in Emacs. In the following table, whenever we say ``the +named function'', that means the function whose name is the relevant +symbol; similarly for ``the named variable'' etc. + +@table @code +@item :advertised-binding +This property value specifies the preferred key binding, when showing +documentation, for the named function. @xref{Keys in Documentation}. + +@item char-table-extra-slots +The value, if non-@code{nil}, specifies the number of extra slots in +the named char-table type. @xref{Char-Tables}. + +@item customized-face +@itemx face-defface-spec +@itemx saved-face +@itemx theme-face +These properties are used to record a face's standard, saved, +customized, and themed face specs. Do not set them directly; they are +managed by @code{defface} and related functions. @xref{Defining +Faces}. + +@item customized-value +@itemx saved-value +@itemx standard-value +@itemx theme-value +These properties are used to record a customizable variable's standard +value, saved value, customized-but-unsaved value, and themed values. +Do not set them directly; they are managed by @code{defcustom} and +related functions. @xref{Variable Definitions}. + +@item disabled +If the value is non-@code{nil}, the named function is disabled as a +command. @xref{Disabling Commands}. + +@item face-documentation +The value stores the documentation string of the named face. This is +set automatically by @code{defface}. @xref{Defining Faces}. + +@item history-length +The value, if non-@code{nil}, specifies the maximum minibuffer history +length for the named history list variable. @xref{Minibuffer +History}. + +@item interactive-form +The value is an interactive form for the named function. Normally, +you should not set this directly; use the @code{interactive} special +form instead. @xref{Interactive Call}. + +@item menu-enable +The value is an expression for determining whether the named menu item +should be enabled in menus. @xref{Simple Menu Items}. + +@item mode-class +If the value is @code{special}, the named major mode is ``special''. +@xref{Major Mode Conventions}. + +@item permanent-local +If the value is non-@code{nil}, the named variable is a buffer-local +variable whose value should not be reset when changing major modes. +@xref{Creating Buffer-Local}. + +@item permanent-local-hook +If the value is non-@code{nil}, the named function should not be +deleted from the local value of a hook variable when changing major +modes. @xref{Setting Hooks}. + +@item pure +This property is used internally to mark certain named functions for +byte compiler optimization. Do not set it. + +@item risky-local-variable +If the value is non-@code{nil}, the named variable is considered risky +as a file-local variable. @xref{File Local Variables}. + +@item safe-function +If the value is non-@code{nil}, the named function is considered +generally safe for evaluation. @xref{Function Safety}. + +@item safe-local-eval-function +If the value is non-@code{nil}, the named function is safe to call in +file-local evaluation forms. @xref{File Local Variables}. + +@item safe-local-variable +The value specifies a function for determining safe file-local values +for the named variable. @xref{File Local Variables}. + +@item side-effect-free +A non-@code{nil} value indicates that the named function is free of +side-effects, for determining function safety (@pxref{Function +Safety}) as well as for byte compiler optimizations. Do not set it. + +@item variable-documentation +If non-@code{nil}, this specifies the named vaariable's documentation +string. This is set automatically by @code{defvar} and related +functions. @xref{Defining Faces}. +@end table