@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
* 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
@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.
+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.
-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.
+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
@result{} (b c)
@end example
-@noindent
-For the @code{pop} macro, which removes an element from a list,
+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
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}))}.
+@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))
@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
@quotation
@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}
-library provides versions. @xref{Top,, Overview, cl, Common Lisp Extensions}.
+Although standard GNU Emacs Lisp does not have them, the @file{cl-lib}
+library provides versions.
+@xref{Lists as Sets,,, cl, Common Lisp Extensions}.
@end quotation
@defun memq object list
@defun delq object list
@cindex deleting list elements
This function destructively removes all elements @code{eq} to
-@var{object} from @var{list}. The letter @samp{q} in @code{delq} says
-that it uses @code{eq} to compare @var{object} against the elements of
-the list, like @code{memq} and @code{remq}.
+@var{object} from @var{list}, and returns the resulting list. The
+letter @samp{q} in @code{delq} says that it uses @code{eq} to compare
+@var{object} against the elements of the list, like @code{memq} and
+@code{remq}.
+
+Typically, when you invoke @code{delq}, you should use the return
+value by assigning it to the variable which held the original list.
+The reason for this is explained below.
@end defun
-When @code{delq} deletes elements from the front of the list, it does so
-simply by advancing down the list and returning a sublist that starts
-after those elements:
+The @code{delq} function deletes elements from the front of the list
+by simply advancing down the list, and returning a sublist that starts
+after those elements. For example:
@example
@group
@end group
@end example
+@noindent
When an element to be deleted appears in the middle of the list,
removing it involves changing the @sc{cdr}s (@pxref{Setcdr}).
@end defun
@defun delete object sequence
-If @code{sequence} is a list, this function destructively removes all
-elements @code{equal} to @var{object} from @var{sequence}. For lists,
-@code{delete} is to @code{delq} as @code{member} is to @code{memq}: it
-uses @code{equal} to compare elements with @var{object}, like
-@code{member}; when it finds an element that matches, it cuts the
-element out just as @code{delq} would.
+This function removes all elements @code{equal} to @var{object} from
+@var{sequence}, and returns the resulting sequence.
+
+If @var{sequence} is a list, @code{delete} is to @code{delq} as
+@code{member} is to @code{memq}: it uses @code{equal} to compare
+elements with @var{object}, like @code{member}; when it finds an
+element that matches, it cuts the element out just as @code{delq}
+would. As with @code{delq}, you should typically use the return value
+by assigning it to the variable which held the original list.
If @code{sequence} is a vector or string, @code{delete} returns a copy
of @code{sequence} with all elements @code{equal} to @code{object}
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