(lispref.info)Property Lists


Prev: Creating Symbols Up: Symbols

Property Lists
==============

   A "property list" ("plist" for short) is a list of paired elements
stored in the property list cell of a symbol.  Each of the pairs
associates a property name (usually a symbol) with a property or value.
Property lists are generally used to record information about a
symbol, such as how to compile it, the name of the file where it was
defined, or perhaps even the grammatical class of the symbol
(representing a word) in a language understanding system.

   Character positions in a string or buffer can also have property
lists.  Note: Text Properties.

   The property names and values in a property list can be any Lisp
objects, but the names are usually symbols.  They are compared using
`eq'.  Here is an example of a property list, found on the symbol
`progn' when the compiler is loaded:

     (lisp-indent-function 0 byte-compile byte-compile-progn)

Here `lisp-indent-function' and `byte-compile' are property names, and
the other two elements are the corresponding values.

   Association lists (Note: 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 when it is necessary
to attach information to various Lisp function names or variables.  If
all the pairs are recorded in one association list, the program will
need to search that entire list each time a function or variable is to
be operated on.  By contrast, if the information is recorded 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.  For this reason, the documentation for a variable is recorded in
a property named `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 use property names that are probably
unique, such as by including the name of the library in the property
name.)  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.

 - Function: symbol-plist SYMBOL
     This function returns the property list of SYMBOL.

 - Function: setplist SYMBOL PLIST
     This function sets SYMBOL's property list to PLIST.  Normally,
     PLIST should be a well-formed property list, but this is not
     enforced.

          (setplist 'foo '(a 1 b (2 3) c nil))
               => (a 1 b (2 3) c nil)
          (symbol-plist 'foo)
               => (a 1 b (2 3) c nil)

     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 (*note
     Abbrevs::.).

 - Function: get SYMBOL PROPERTY
     This function finds the value of the property named PROPERTY in
     SYMBOL's property list.  If there is no such property, `nil' is
     returned.  Thus, there is no distinction between a value of `nil'
     and the absence of the property.

     The name PROPERTY is compared with the existing property names
     using `eq', so any object is a legitimate property.

     See `put' for an example.

 - Function: put SYMBOL PROPERTY VALUE
     This function puts VALUE onto SYMBOL's property list under the
     property name PROPERTY, replacing any previous value.

          (put 'fly 'verb 'transitive)
               =>'transitive
          (put 'fly 'noun '(a buzzing little bug))
               => (a buzzing little bug)
          (get 'fly 'verb)
               => transitive
          (symbol-plist 'fly)
               => (verb transitive noun (a buzzing little bug))


automatically generated by info2www