From f02f19bd4e705614ed5110fab5120f70b3e00c3a Mon Sep 17 00:00:00 2001 From: Chong Yidong Date: Sun, 2 Dec 2012 17:14:16 +0800 Subject: [PATCH] Lisp manual improvements for plists and symbol plists. * doc/lispref/commands.texi (Using Interactive): Fix index entry. * doc/lispref/customize.texi (Variable Definitions): * doc/lispref/display.texi (Defining Faces): * doc/lispref/sequences.texi (Char-Tables): Fix xref. * doc/lispref/lists.texi (Property Lists): Move here from symbols.texi. (Plist Access): Rename from Other Plists. * doc/lispref/symbols.texi (Symbol Properties): New node. (Symbol Plists): Make it a subsection under Symbol Properties. (Standard Properties): New node. --- doc/lispref/ChangeLog | 13 ++ doc/lispref/commands.texi | 4 +- doc/lispref/customize.texi | 4 +- doc/lispref/display.texi | 2 +- doc/lispref/elisp.texi | 17 ++- doc/lispref/lists.texi | 140 +++++++++++++++++ doc/lispref/sequences.texi | 8 +- doc/lispref/symbols.texi | 300 +++++++++++++++++-------------------- doc/lispref/variables.texi | 1 - 9 files changed, 314 insertions(+), 175 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index b55ded918b..22f20c7112 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,7 +1,20 @@ 2012-12-02 Chong Yidong + * symbols.texi (Symbol Properties): New node. + (Symbol Plists): Make it a subsection under Symbol Properties. + (Standard Properties): New node. + + * lists.texi (Property Lists): Move here from symbols.texi. + (Plist Access): Rename from Other Plists. + + * customize.texi (Variable Definitions): + * display.texi (Defining Faces): + * sequences.texi (Char-Tables): Fix xref. + * keymaps.texi (Key Sequences): kbd is now a function. + * commands.texi (Using Interactive): Fix index entry. + 2012-11-23 Martin Rudalics * windows.texi (Basic Windows): Fix typo. diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index c42e4b3b6d..8806c933bf 100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@ -141,10 +141,10 @@ A command may be called from Lisp programs like any other function, but then the caller supplies the arguments and @var{arg-descriptor} has no effect. -@cindex @code{interactive-form}, function property +@cindex @code{interactive-form}, symbol property The @code{interactive} form must be located at top-level in the function body, or in the function symbol's @code{interactive-form} -property (@pxref{Symbol Plists}). It has its effect because the +property (@pxref{Symbol Properties}). It has its effect because the command loop looks for it before calling the function (@pxref{Interactive Call}). Once the function is called, all its body forms are executed; at this time, if the @code{interactive} form diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi index c9d22851ed..d85361499b 100644 --- a/doc/lispref/customize.texi +++ b/doc/lispref/customize.texi @@ -472,8 +472,8 @@ Internally, @code{defcustom} uses the symbol property @code{saved-value} to record the value saved by the user with the customization buffer, and @code{customized-value} to record the value set by the user with the customization buffer, but not saved. -@xref{Property Lists}. These properties are lists, the car of which -is an expression that evaluates to the value. +@xref{Symbol Properties}. These properties are lists, the car of +which is an expression that evaluates to the value. @defun custom-reevaluate-setting symbol This function re-evaluates the standard value of @var{symbol}, which diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 475a9550f9..6799d3130b 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -2287,7 +2287,7 @@ terminal must match one of the @var{value}s specified for it in @end example Internally, Emacs stores the face's default specification in its -@code{face-defface-spec} symbol property (@pxref{Property Lists}). +@code{face-defface-spec} symbol property (@pxref{Symbol Properties}). The @code{saved-face} property stores the face specification saved by the user, using the customization buffer; the @code{customized-face} property stores the face specification customized for the current diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index cb00b5e988..b2b73b380b 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -378,6 +378,7 @@ Lists * Modifying Lists:: Storing new pieces into an existing list. * Sets And Lists:: A list can represent a finite mathematical set. * Association Lists:: A list can represent a finite relation or mapping. +* Property Lists:: A list of paired elements. Modifying Existing List Structure @@ -386,6 +387,12 @@ Modifying Existing List Structure This can be used to remove or add elements. * Rearrangement:: Reordering the elements in a list; combining lists. +Property Lists + +* Plists and Alists:: Comparison of the advantages of property + lists and association lists. +* Plist Access:: Accessing property lists stored elsewhere. + Sequences, Arrays, and Vectors * Sequence Functions:: Functions that accept any kind of sequence. @@ -410,15 +417,13 @@ Symbols 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. -Property Lists +Symbol Properties -* 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. Evaluation diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi index 40e8d08f72..1a3d85b9b3 100644 --- a/doc/lispref/lists.texi +++ b/doc/lispref/lists.texi @@ -22,6 +22,7 @@ the whole list. * Modifying Lists:: Storing new pieces into an existing list. * Sets And Lists:: A list can represent a finite mathematical set. * Association Lists:: A list can represent a finite relation or mapping. +* Property Lists:: A list of paired elements. @end menu @node Cons Cells @@ -1821,3 +1822,142 @@ often modifies the original list structure of @var{alist}. compares the @sc{cdr} of each @var{alist} association instead of the @sc{car}. @end defun + +@node Property Lists +@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. Here is an example of a property +list: + +@example +(pine cones numbers (1 2 3) color "blue") +@end example + +@noindent +This property list associates @code{pine} with @code{cones}, +@code{numbers} with @code{(1 2 3)}, and @code{color} with +@code{"blue"}. The property names and values can be any Lisp objects, +but the names are usually symbols (as they are in this example). + + Property lists are used in several contexts. For instance, the +function @code{put-text-property} takes an argument which is a +property list, specifying text properties and associated values which +are to be applied to text in a string or buffer. @xref{Text +Properties}. + + Another prominent use of property lists is for storing symbol +properties. Every symbol possesses a list of properties, used to +record miscellaneous information about the symbol; these properties +are stored in the form of a property list. @xref{Symbol Properties}. + +@menu +* Plists and Alists:: Comparison of the advantages of property + lists and association lists. +* Plist Access:: Accessing property lists stored elsewhere. +@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 such information in one association list, it will +typically need to search that entire list each time it checks for an +association for a particular Lisp function name or variable, which +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 Plist Access +@subsection Property Lists Outside Symbols + + The following functions can be used to manipulate property lists. +They all compare property names using @code{eq}. + +@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{} nil +(plist-get '(foo 4 bad) 'bar) + @result{} nil +@end example +@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, + +@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)) +@end example +@end defun + + You could define @code{put} in terms of @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}. +@end defun diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi index e66f61d22d..8bb1e9e5ab 100644 --- a/doc/lispref/sequences.texi +++ b/doc/lispref/sequences.texi @@ -542,10 +542,10 @@ the function @code{char-table-subtype}, described below. @item The subtype controls the number of @dfn{extra slots} in the char-table. This number is specified by the subtype's -@code{char-table-extra-slots} symbol property, which should be an -integer between 0 and 10. If the subtype has no such symbol property, -the char-table has no extra slots. @xref{Property Lists}, for -information about symbol properties. +@code{char-table-extra-slots} symbol property (@pxref{Symbol +Properties}), whose value should be an integer between 0 and 10. If +the subtype has no such symbol property, the char-table has no extra +slots. @end itemize @cindex parent of char-table diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi index 326c6cd4ab..d3e5c1f157 100644 --- a/doc/lispref/symbols.texi +++ b/doc/lispref/symbols.texi @@ -13,8 +13,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} @@ -26,7 +26,7 @@ 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 @@ -91,7 +91,7 @@ the contents of a symbol's function cell, use the function The property list cell normally should hold a correctly formatted property list. To get a symbol's property list, use the function -@code{symbol-plist}. @xref{Property Lists}. +@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 @@ -376,109 +376,34 @@ If @code{unintern} does delete a symbol, it returns @code{t}. Otherwise it returns @code{nil}. @end defun -@node Property Lists -@section Property Lists -@cindex property list -@cindex plist +@node Symbol Properties +@section Symbol Properties +@cindex symbol property - 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. + 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}). - 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}. - - 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: - -@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 such information in one association list, it will -typically need to search that entire list each time it checks for an -association for a particular Lisp function name or variable, which -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}. +@subsection Accessing Symbol Properties -@example -(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 - -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 @@ -487,12 +412,6 @@ using @code{eq}, so any object is a legitimate property. See @code{put} for an example. @end defun -@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 - @defun put symbol property value This function puts @var{value} onto @var{symbol}'s property list under the property name @var{property}, replacing any previous property value. @@ -510,69 +429,132 @@ The @code{put} function returns @var{value}. @end example @end defun -@node Other Plists -@subsection Property Lists Outside Symbols - - These functions are useful for manipulating property lists -not stored in 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{} nil -(plist-get '(foo 4 bad) 'bar) - @result{} nil -@end example -@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, - -@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)) -@end example +@defun symbol-plist symbol +This function returns the property list of @var{symbol}. @end defun - You could define @code{put} in terms of @code{plist-put} as follows: +@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 -(defun put (symbol prop value) - (setplist symbol - (plist-put (symbol-plist symbol) prop value))) +(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 -@defun lax-plist-get plist property -Like @code{plist-get} except that it compares properties -using @code{equal} instead of @code{eq}. +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 -@defun lax-plist-put plist property value -Like @code{plist-put} except that it compares properties -using @code{equal} instead of @code{eq}. +@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 -@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}. -@end defun +@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}. + +@itemx customized-face +@item 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}. + +@itemx customized-value +@itemx saved-value +@item 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 +normally 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 normally set automatically by @code{defvar} and +related functions. @xref{Defining Faces}. +@end table diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi index dfde3c45c0..2168bd5af0 100644 --- a/doc/lispref/variables.texi +++ b/doc/lispref/variables.texi @@ -1423,7 +1423,6 @@ disappear after doing its job and will not interfere with the subsequent major mode. @xref{Hooks}. @end defvar -@c Emacs 19 feature @cindex permanent local variable A buffer-local variable is @dfn{permanent} if the variable name (a symbol) has a @code{permanent-local} property that is non-@code{nil}. -- 2.20.1