Function: org-datetree-find-create-hierarchy

org-datetree-find-create-hierarchy is a byte-compiled function defined in org-datetree.el.gz.

Signature

(org-datetree-find-create-hierarchy HIER-PAIRS &optional KEEP-RESTRICTION LEGACY-PROP)

Documentation

Find or create entry in datetree using the full date hierarchy.

Moves point to the beginning of the entry. Returns non-nil if an existing entry was found, or nil if a new entry was created.

HIER-PAIRS is a list whose first entry corresponds to the outermost element
(e.g. year) and last entry corresponds to the innermost (e.g. day).
Each entry of the list is a pair, the car is the headline for that level
(e.g. "2024" or "2024-12-28 Saturday"), and the cadr is a
string comparison function for sorting each headline among its siblings. The comparison function should take 2 arguments, corresponding to the titles of 2 headlines, and return a negative number if the first headline is earlier, a positive number if the second headline is earlier, 0 or t if the headlines are at the same time, or nil if a headline isn't a valid datetree subheading. For example, HIER-PAIRS could look like

   (("2024" compare-year-fun)
    ("2024-12 December" compare-month-fun)
    ("2024-12-28 Saturday" compare-day-fun))

where compare-month-fun would be some function where
(compare-month-fun "2024-11 November" "2024-12 December") is
negative, and (compare-month-fun "2024-12-December" "Potato") is nil. One way to construct such a comparison function is with org-datetree-comparefun-from-regex.

If KEEP-RESTRICTION is non-nil, do not widen the buffer. When it is nil, the buffer will be widened to make sure an existing date tree can be found. If it is the symbol subtree-at-point, then the tree will be built under the headline at point.

If LEGACY-PROP is non-nil, the tree is located by searching for a headline with property LEGACY-PROP, supporting the old way of tree placement via a property.

Source Code

;; Defined in /usr/src/emacs/lisp/org/org-datetree.el.gz
(defun org-datetree-find-create-hierarchy
    (hier-pairs &optional keep-restriction legacy-prop)
  "Find or create entry in datetree using the full date hierarchy.
Moves point to the beginning of the entry.  Returns non-nil if an
existing entry was found, or nil if a new entry was created.

HIER-PAIRS is a list whose first entry corresponds to the outermost element
(e.g. year) and last entry corresponds to the innermost (e.g. day).
Each entry of the list is a pair, the car is the headline for that level
(e.g. \"2024\" or \"2024-12-28 Saturday\"), and the cadr is a
string comparison function for sorting each headline among its
siblings.  The comparison function should take 2 arguments,
corresponding to the titles of 2 headlines, and return a negative
number if the first headline is earlier, a positive number if the
second headline is earlier, 0 or t if the headlines are at the
same time, or `nil' if a headline isn't a valid datetree
subheading.  For example, HIER-PAIRS could look like

   ((\"2024\" compare-year-fun)
    (\"2024-12 December\" compare-month-fun)
    (\"2024-12-28 Saturday\" compare-day-fun))

where compare-month-fun would be some function where
(compare-month-fun \"2024-11 November\" \"2024-12 December\") is
negative, and (compare-month-fun \"2024-12-December\" \"Potato\")
is nil.  One way to construct such a comparison function is with
`org-datetree-comparefun-from-regex'.

If KEEP-RESTRICTION is non-nil, do not widen the buffer.
When it is nil, the buffer will be widened to make sure an existing date
tree can be found.  If it is the symbol `subtree-at-point', then the tree
will be built under the headline at point.

If LEGACY-PROP is non-nil, the tree is located by searching for a
headline with property LEGACY-PROP, supporting the old way of
tree placement via a property."
  (let ((level 1)
        found-p)
    (save-restriction
      ;; get the datetree base and narrow to it
      (if (eq keep-restriction 'subtree-at-point)
          (progn
	    (unless (org-at-heading-p) (error "Not at heading"))
	    (widen)
	    (org-narrow-to-subtree)
            (setq level (org-get-valid-level (org-current-level) 1)))
        (unless keep-restriction (widen))
        ;; Support the old way of tree placement, using a property
        (let ((prop (and legacy-prop (org-find-property legacy-prop))))
          (when prop
            (progn
              (goto-char prop)
	      (org-narrow-to-subtree)
              (setq level (org-get-valid-level (org-current-level) 1))))))
      (cl-loop
       for pair in hier-pairs
       do
       (setq found-p (org-datetree--find-create-subheading
                      (cadr pair) (car pair) level))
       (setq level (1+ level))))
    found-p))