Function: hierarchy-add-tree

hierarchy-add-tree is a byte-compiled function defined in hierarchy.el.gz.

Signature

(hierarchy-add-tree HIERARCHY ITEM PARENTFN &optional CHILDRENFN ACCEPTFN DELAY-CHILDREN-P)

Documentation

In HIERARCHY, add ITEM.

PARENTFN is either nil or a function defining the child-to-parent relationship: this function takes an item as parameter and should return the parent of this item in the hierarchy. If the item has no parent in the hierarchy (i.e., it should be a root), the function should return an object not accepted by acceptfn (i.e., nil for the default value of acceptfn).

CHILDRENFN is either nil or a function defining the parent-to-children relationship: this function takes an item as parameter and should return a list of children of this item in the hierarchy.

If both PARENTFN and CHILDRENFN are non-nil, the results of PARENTFN and CHILDRENFN are expected to be coherent with each other.

ACCEPTFN is a function returning non-nil if its parameter (any object) should be an item of the hierarchy. By default, ACCEPTFN returns non-nil if its parameter is non-nil.

DELAY-CHILDREN-P is a predicate determining whether the children that would normally be processed by CHILDRENFN should, instead, have their processing be delayed and stored to be processed by CHILDRENFN when the child is selected during use of the hierarchy.

Probably introduced at or before Emacs version 29.1.

Source Code

;; Defined in /usr/src/emacs/lisp/emacs-lisp/hierarchy.el.gz
(defun hierarchy-add-tree (hierarchy item parentfn
                                     &optional childrenfn acceptfn delay-children-p)
  "In HIERARCHY, add ITEM.

PARENTFN is either nil or a function defining the child-to-parent
relationship: this function takes an item as parameter and should return
the parent of this item in the hierarchy.  If the item has no parent in the
hierarchy (i.e., it should be a root), the function should return an object
not accepted by acceptfn (i.e., nil for the default value of acceptfn).

CHILDRENFN is either nil or a function defining the parent-to-children
relationship: this function takes an item as parameter and should return a
list of children of this item in the hierarchy.

If both PARENTFN and CHILDRENFN are non-nil, the results of PARENTFN and
CHILDRENFN are expected to be coherent with each other.

ACCEPTFN is a function returning non-nil if its parameter (any object)
should be an item of the hierarchy.  By default, ACCEPTFN returns non-nil
if its parameter is non-nil.

DELAY-CHILDREN-P is a predicate determining whether the children that would
normally be processed by CHILDRENFN should, instead, have their processing be
delayed and stored to be processed by CHILDRENFN when the child is selected
during use of the hierarchy."
  (unless (hierarchy-has-item hierarchy item)
    (let ((acceptfn (or acceptfn #'identity)))
      (hierarchy--seen-items-add hierarchy item)
      (let ((parent (and parentfn (funcall parentfn item))))
        (when (funcall acceptfn parent)
          (hierarchy--add-relation hierarchy item parent acceptfn)
          (hierarchy-add-tree hierarchy parent
                              parentfn (if delay-children-p nil childrenfn))))
      (if (and childrenfn delay-children-p)
          (map-put! (hierarchy--delaying-parents hierarchy) item childrenfn)
        (let ((children (and childrenfn (funcall childrenfn item))))
          (map-put! (hierarchy--delaying-parents hierarchy) item nil)
          (mapc (lambda (child)
                  (when (funcall acceptfn child)
                    (hierarchy--add-relation hierarchy child item acceptfn)
                    (hierarchy-add-tree hierarchy child parentfn childrenfn)))
                children))))))