Function: org-datetree-find-create-entry

org-datetree-find-create-entry is an autoloaded and byte-compiled function defined in org-datetree.el.gz.

Signature

(org-datetree-find-create-entry TIME-GROUPING D &optional KEEP-RESTRICTION)

Documentation

Find or create an entry for date D.

Moves point to the beginning of the entry.

TIME-GROUPING specifies the grouping levels of the datetree, and should be a subset of (year quarter month week day). Weeks are assigned to years according to ISO-8601. If TIME-GROUPING contains both month and week, then weeks are assigned to the month containing Thursday, for consistency with the ISO-8601 year-week rule. If TIME-GROUPING contains quarter and week but not month, quarters are defined as 13-week periods; otherwise they are defined as 3-month periods.

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 org-datetree-add-timestamp is non-nil and TIME-GROUPING includes day and a new entry is created, adds a time stamp after the new headline.

Source Code

;; Defined in /usr/src/emacs/lisp/org/org-datetree.el.gz
;;;###autoload
(defun org-datetree-find-create-entry
    (time-grouping d &optional keep-restriction)
  "Find or create an entry for date D.
Moves point to the beginning of the entry.

TIME-GROUPING specifies the grouping levels of the datetree, and
should be a subset of `(year quarter month week day)'.  Weeks are
assigned to years according to ISO-8601.  If TIME-GROUPING
contains both `month' and `week', then weeks are assigned to the
month containing Thursday, for consistency with the ISO-8601
year-week rule.  If TIME-GROUPING contains `quarter' and `week'
but not `month', quarters are defined as 13-week periods;
otherwise they are defined as 3-month periods.

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 `org-datetree-add-timestamp' is non-nil and TIME-GROUPING
includes `day' and a new entry is created, adds a time stamp
after the new headline."
  (when-let* ((setdiff (seq-difference time-grouping
                                      '(year quarter month week day))))
    (error (format "Unrecognized datetree grouping elements %s" setdiff)))
  (let* ((year (calendar-extract-year d))
	 (month (calendar-extract-month d))
	 (day (calendar-extract-day d))
         (time (org-encode-time 0 0 0 day month year))
         (iso-date (calendar-iso-from-absolute
		    (calendar-absolute-from-gregorian d)))
         (week (nth 0 iso-date))
         (nominal-year
          (if (memq 'week time-grouping)
              (nth 2 iso-date)
            year))
         (nominal-month
          (if (memq 'week time-grouping)
              (calendar-extract-month
               ;; anchor on Thurs, to be consistent with weekyear
               (calendar-gregorian-from-absolute
                (calendar-iso-to-absolute
                 `(,week 4 ,nominal-year))))
            month))
         (quarter (if (and (memq 'week time-grouping)
                           (not (memq 'month time-grouping)))
                      (min 4 (1+ (/ (1- week) 13)))
                    (1+ (/ (1- nominal-month) 3))))
         (found-p
          (org-datetree-find-create-hierarchy
           (append
            (when (memq 'year time-grouping)
              (list (list (number-to-string nominal-year)
                          (org-datetree-comparefun-from-regex
                           "\\([12][0-9]\\{3\\}\\)"))))
            (when (memq 'quarter time-grouping)
              (list (list (format "%d-Q%d" nominal-year quarter)
                          (org-datetree-comparefun-from-regex
                           "\\([12][0-9]\\{3\\}-Q[1-4]\\)"))))
            (when (memq 'month time-grouping)
              (list (list (format-time-string
                           "%Y-%m %B" (org-encode-time 0 0 0 1 nominal-month
                                                       nominal-year))
                          (org-datetree-comparefun-from-regex
                           "\\([12][0-9]\\{3\\}-[01][0-9]\\) \\w+"))))
            (when (memq 'week time-grouping)
              (list (list (format-time-string "%G-W%V" time)
                          (org-datetree-comparefun-from-regex
                           "\\([12][0-9]\\{3\\}-W[0-5][0-9]\\)"))))
            (when (memq 'day time-grouping)
              ;; Use regular date instead of ISO-week year/month
              (list (list (format-time-string
                           "%Y-%m-%d %A" (org-encode-time 0 0 0 day month year))
                          (org-datetree-comparefun-from-regex
                           "\\([12][0-9]\\{3\\}-[01][0-9]-[0123][0-9]\\) \\w+")))))
           keep-restriction
           ;; Support the old way of tree placement, using a property
           (cond
            ((seq-set-equal-p time-grouping '(year month day))
             "DATE_TREE")
            ((seq-set-equal-p time-grouping '(year month))
             "DATE_TREE")
            ((seq-set-equal-p time-grouping '(year week day))
             "WEEK_TREE")))))
    (when (memq 'day time-grouping)
      (when (and (not found-p) org-datetree-add-timestamp)
        (save-excursion
          (end-of-line)
          (insert "\n")
          (org-indent-line)
          (org-insert-timestamp
           (org-encode-time 0 0 0 day month year)
           nil
           (eq org-datetree-add-timestamp 'inactive)))))))