Info Catalog cl: Symbols cl: Creating Symbols

cl: Property Lists

 
 7.1 Property Lists
 ==================
 
 These functions augment the standard Emacs Lisp functions ‘get’ and
 ‘put’ for operating on properties attached to symbols.  There are also
 functions for working with property lists as first-class data structures
 not attached to particular symbols.
 
  -- Function: cl-get symbol property &optional default
      This function is like ‘get’, except that if the property is not
      found, the DEFAULT argument provides the return value.  (The Emacs
      Lisp ‘get’ function always uses ‘nil’ as the default; this
      package’s ‘cl-get’ is equivalent to Common Lisp’s ‘get’.)
 
      The ‘cl-get’ function is ‘setf’-able; when used in this fashion,
      the DEFAULT argument is allowed but ignored.
 
  -- Function: cl-remprop symbol property
      This function removes the entry for PROPERTY from the property list
      of SYMBOL.  It returns a true value if the property was indeed
      found and removed, or ‘nil’ if there was no such property.  (This
      function was probably omitted from Emacs originally because, since
      ‘get’ did not allow a DEFAULT, it was very difficult to distinguish
      between a missing property and a property whose value was ‘nil’;
      thus, setting a property to ‘nil’ was close enough to ‘cl-remprop’
      for most purposes.)
 
  -- Function: cl-getf place property &optional default
      This function scans the list PLACE as if it were a property list,
      i.e., a list of alternating property names and values.  If an
      even-numbered element of PLACE is found which is ‘eq’ to PROPERTY,
      the following odd-numbered element is returned.  Otherwise, DEFAULT
      is returned (or ‘nil’ if no default is given).
 
      In particular,
 
           (get sym prop)  ≡  (cl-getf (symbol-plist sym) prop)
 
      It is valid to use ‘cl-getf’ as a ‘setf’ place, in which case its
      PLACE argument must itself be a valid ‘setf’ place.  The DEFAULT
      argument, if any, is ignored in this context.  The effect is to
      change (via ‘setcar’) the value cell in the list that corresponds
      to PROPERTY, or to cons a new property-value pair onto the list if
      the property is not yet present.
 
           (put sym prop val) ≡ (setf (cl-getf (symbol-plist sym) prop) val)
 
      The ‘get’ and ‘cl-get’ functions are also ‘setf’-able.  The fact
      that ‘default’ is ignored can sometimes be useful:
 
           (cl-incf (cl-get 'foo 'usage-count 0))
 
      Here, symbol ‘foo’’s ‘usage-count’ property is incremented if it
      exists, or set to 1 (an incremented 0) otherwise.
 
      When not used as a ‘setf’ form, ‘cl-getf’ is just a regular
      function and its PLACE argument can actually be any Lisp
      expression.
 
  -- Macro: cl-remf place property
      This macro removes the property-value pair for PROPERTY from the
      property list stored at PLACE, which is any ‘setf’-able place
      expression.  It returns true if the property was found.  Note that
      if PROPERTY happens to be first on the list, this will effectively
      do a ‘(setf PLACE (cddr PLACE))’, whereas if it occurs later, this
      simply uses ‘setcdr’ to splice out the property and value cells.
 

Info Catalog cl: Symbols cl: Creating Symbols