X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/6ccc848cd85e75d77d6b11a46f5f23f860db9ff5..3e1300f765befac6ed9e7f59c022f5f886babfd5:/doc/lispref/lists.texi

diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi
index 09948caaa1..9daf01cd0a 100644
--- a/doc/lispref/lists.texi
+++ b/doc/lispref/lists.texi
@@ -1,6 +1,7 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 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.
 @node Lists
 @chapter Lists
@@ -22,6 +23,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
@@ -234,17 +236,15 @@ This is in contrast to @code{cdr}, which signals an error if
 @end defun
 
 @defmac pop listname
-This macro is a way of examining the @sc{car} of a list,
-and taking it off the list, all at once.
-@c FIXME I don't think is a particularly good way to do it,
-@c but generalized variables have not been introduced yet.
-(In fact, this macro can act on generalized variables, not just lists.
-@xref{Generalized Variables}.)
-
-It operates on the list which is stored in the symbol @var{listname}.
-It removes this element from the list by setting @var{listname}
-to the @sc{cdr} of its old value---but it also returns the @sc{car}
-of that list, which is the element being removed.
+This macro provides a convenient way to examine the @sc{car} of a
+list, and take it off the list, all at once.  It operates on the list
+stored in @var{listname}.  It removes the first element from the list,
+saves the @sc{cdr} into @var{listname}, then returns the removed
+element.
+
+In the simplest case, @var{listname} is an unquoted symbol naming a
+list; in that case, this macro is equivalent to @w{@code{(prog1
+(car listname) (setq listname (cdr listname)))}}.
 
 @example
 x
@@ -255,7 +255,10 @@ x
      @result{} (b c)
 @end example
 
-@noindent
+More generally, @var{listname} can be a generalized variable.  In that
+case, this macro saves into @var{listname} using @code{setf}.
+@xref{Generalized Variables}.
+
 For the @code{push} macro, which adds an element to a list,
 @xref{List Variables}.
 @end defmac
@@ -267,8 +270,10 @@ are numbered starting with zero, so the @sc{car} of @var{list} is
 element number zero.  If the length of @var{list} is @var{n} or less,
 the value is @code{nil}.
 
-If @var{n} is negative, @code{nth} returns the first element of
-@var{list}.
+@c Behavior for -ve n undefined since 2013/08; see bug#15059.
+@ignore
+If @var{n} is negative, @code{nth} returns the first element of @var{list}.
+@end ignore
 
 @example
 @group
@@ -278,10 +283,6 @@ If @var{n} is negative, @code{nth} returns the first element of
 @group
 (nth 10 '(1 2 3 4))
      @result{} nil
-@end group
-@group
-(nth -3 '(1 2 3 4))
-     @result{} 1
 
 (nth n x) @equiv{} (car (nthcdr n x))
 @end group
@@ -297,7 +298,8 @@ This function returns the @var{n}th @sc{cdr} of @var{list}.  In other
 words, it skips past the first @var{n} links of @var{list} and returns
 what follows.
 
-If @var{n} is zero or negative, @code{nthcdr} returns all of
+@c "or negative" removed 2013/08; see bug#15059.
+If @var{n} is zero, @code{nthcdr} returns all of
 @var{list}.  If the length of @var{list} is @var{n} or less,
 @code{nthcdr} returns @code{nil}.
 
@@ -311,7 +313,7 @@ If @var{n} is zero or negative, @code{nthcdr} returns all of
      @result{} nil
 @end group
 @group
-(nthcdr -3 '(1 2 3 4))
+(nthcdr 0 '(1 2 3 4))
      @result{} (1 2 3 4)
 @end group
 @end example
@@ -683,13 +685,12 @@ Some examples:
   These functions, and one macro, provide convenient ways
 to modify a list which is stored in a variable.
 
-@defmac push newelt listname
-This macro provides an alternative way to write
-@code{(setq @var{listname} (cons @var{newelt} @var{listname}))}.
-@c FIXME I don't think is a particularly good way to do it,
-@c but generalized variables have not been introduced yet.
-(In fact, this macro can act on generalized variables, not just lists.
-@xref{Generalized Variables}.)
+@defmac push element listname
+This macro creates a new list whose @sc{car} is @var{element} and
+whose @sc{cdr} is the list specified by @var{listname}, and saves that
+list in @var{listname}.  In the simplest case, @var{listname} is an
+unquoted symbol naming a list, and this macro is equivalent
+to @w{@code{(setq @var{listname} (cons @var{element} @var{listname}))}}.
 
 @example
 (setq l '(a b))
@@ -700,7 +701,11 @@ l
      @result{} (c a b)
 @end example
 
-@noindent
+More generally, @code{listname} can be a generalized variable.  In
+that case, this macro does the equivalent of @w{@code{(setf
+@var{listname} (cons @var{element} @var{listname}))}}.
+@xref{Generalized Variables}.
+
 For the @code{pop} macro, which removes the first element from a list,
 @xref{List Elements}.
 @end defmac
@@ -1275,7 +1280,8 @@ functions for sets include @code{memq} and @code{delq}, and their
 @b{Common Lisp note:} Common Lisp has functions @code{union} (which
 avoids duplicate elements) and @code{intersection} for set operations.
 Although standard GNU Emacs Lisp does not have them, the @file{cl-lib}
-library provides versions.  @xref{Top,, Overview, cl, Common Lisp Extensions}.
+library provides versions.
+@xref{Lists as Sets,,, cl, Common Lisp Extensions}.
 @end quotation
 
 @defun memq object list
@@ -1816,3 +1822,134 @@ 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
+
+@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