Function: org-agenda-to-appt

org-agenda-to-appt is an autoloaded, interactive and byte-compiled function defined in org-agenda.el.gz.

Signature

(org-agenda-to-appt &optional REFRESH FILTER &rest ARGS)

Documentation

Activate appointments found in org-agenda-files(var)/org-agenda-files(fun).

With a C-u (universal-argument) prefix, refresh the list of appointments.

If FILTER is t, interactively prompt the user for a regular expression, and filter out entries that don't match it.

If FILTER is a string, use this string as a regular expression for filtering entries out.

If FILTER is a function, filter out entries against which calling the function returns nil. This function takes one argument: an entry from org-agenda-get-day-entries.

FILTER can also be an alist with the car of each cell being either headline or category. For example:

   ((headline "IMPORTANT")
    (category "Work"))

will only add headlines containing IMPORTANT or headlines belonging to the "Work" category.

ARGS are symbols indicating what kind of entries to consider. By default org-agenda-to-appt will use :deadline*, :scheduled*
(i.e., deadlines and scheduled items with a hh:mm specification)
and :timestamp entries. See the docstring of org-diary for details and examples.

If an entry has a APPT_WARNTIME property, its value will be used to override appt-message-warning-time.

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/org/org-agenda.el.gz
(defvar appt-time-msg-list) ; defined in appt.el

;;;###autoload
(defun org-agenda-to-appt (&optional refresh filter &rest args)
  "Activate appointments found in `org-agenda-files'.

With a `\\[universal-argument]' prefix, refresh the list of \
appointments.

If FILTER is t, interactively prompt the user for a regular
expression, and filter out entries that don't match it.

If FILTER is a string, use this string as a regular expression
for filtering entries out.

If FILTER is a function, filter out entries against which
calling the function returns nil.  This function takes one
argument: an entry from `org-agenda-get-day-entries'.

FILTER can also be an alist with the car of each cell being
either `headline' or `category'.  For example:

   ((headline \"IMPORTANT\")
    (category \"Work\"))

will only add headlines containing IMPORTANT or headlines
belonging to the \"Work\" category.

ARGS are symbols indicating what kind of entries to consider.
By default `org-agenda-to-appt' will use :deadline*, :scheduled*
\(i.e., deadlines and scheduled items with a hh:mm specification)
and :timestamp entries.  See the docstring of `org-diary' for
details and examples.

If an entry has a APPT_WARNTIME property, its value will be used
to override `appt-message-warning-time'."
  (interactive "P")
  (when refresh (setq appt-time-msg-list nil))
  (when (eq filter t)
    (setq filter (read-from-minibuffer "Regexp filter: ")))
  (let* ((cnt 0)                        ; count added events
         (scope (or args '(:deadline* :scheduled* :timestamp)))
         (org-agenda-new-buffers nil)
         (org-deadline-warning-days 0)
         ;; Do not use `org-today' here because appt only takes
         ;; time and without date as argument, so it may pass wrong
         ;; information otherwise
         (today (org-date-to-gregorian
                 (time-to-days nil)))
         (org-agenda-restrict nil)
         (files (org-agenda-files 'unrestricted)) entries file
         (org-agenda-buffer nil))
    ;; Get all entries which may contain an appt
    (org-agenda-prepare-buffers files)
    (while (setq file (pop files))
      (setq entries
            (delq nil
                  (append entries
                          (apply #'org-agenda-get-day-entries
                                 file today scope)))))
    ;; Map through entries and find if we should filter them out
    (mapc
     (lambda (x)
       (let* ((evt (org-trim
                    (replace-regexp-in-string
                     org-link-bracket-re "\\2"
                     (or (get-text-property 1 'txt x) ""))))
              (cat (get-text-property (1- (length x)) 'org-category x))
              (tod (get-text-property 1 'time-of-day x))
              (ok (or (null filter)
                      (and (stringp filter) (string-match filter evt))
                      (and (functionp filter) (funcall filter x))
                      (and (listp filter)
                           (let ((cat-filter (cadr (assq 'category filter)))
                                 (evt-filter (cadr (assq 'headline filter))))
                             (or (and (stringp cat-filter)
                                      (string-match cat-filter cat))
                                 (and (stringp evt-filter)
                                      (string-match evt-filter evt)))))))
              (wrn (get-text-property 1 'warntime x))
              (todo-regexp (get-text-property 1 'org-todo-regexp x))
              (not-done-regexp (get-text-property 1 'org-not-done-regexp x)))
         ;; FIXME: Shall we remove text-properties for the appt text?
         ;; (setq evt (set-text-properties 0 (length evt) nil evt))
         (when (and ok tod
                    ;; Exclude done items unconditionally.
                    (or (not (and todo-regexp (string-match-p todo-regexp evt))) ; no todo keyword
                        (and not-done-regexp (string-match-p not-done-regexp evt)) ; or not done
                        ))
           (setq tod (concat "00" (number-to-string tod)))
           (setq tod (when (string-match
                            "\\([0-9]\\{1,2\\}\\)\\([0-9]\\{2\\}\\)\\'" tod)
                       (concat (match-string 1 tod) ":"
                               (match-string 2 tod))))
           (when (appt-add tod evt wrn)
             (setq cnt (1+ cnt))))))
     entries)
    (org-release-buffers org-agenda-new-buffers)
    (if (eq cnt 0)
        (message "No event to add")
      (message "Added %d event%s for today" cnt (if (> cnt 1) "s" "")))))