Function: diary-list-entries
diary-list-entries is an autoloaded and byte-compiled function defined
in diary-lib.el.gz.
Signature
(diary-list-entries DATE NUMBER &optional LIST-ONLY)
Documentation
Create and display a buffer containing the relevant lines in diary-file.
Selects entries for NUMBER days starting with date DATE. Hides any other entries using overlays. If NUMBER is less than 1, this function does nothing.
Returns a list of all relevant diary entries found.
The list entries have the form ((MONTH DAY YEAR) STRING SPECIFIER) where
(MONTH DAY YEAR) is the date of the entry, STRING is the entry text, and
SPECIFIER is the applicability. If the variable diary-list-include-blanks
is non-nil, this list includes a dummy diary entry consisting of the empty
string for a date with no diary entries.
If producing entries for multiple dates (i.e., NUMBER > 1), then
this function normally returns the entries from any given diary
file in date order. The entries for any given day are in the
order in which they were found in the file, not necessarily in
time-of-day order. Note that any functions present on the
hooks (see below) may add entries, or change the order. For
example, diary-include-other-diary-files adds entries from any
include files that it finds to the end of the original list. The
entries from each file will be in date order, but the overall
list will not be. If you want the entire list to be in time
order, add diary-sort-entries to the end of diary-list-entries-hook.
After preparing the initial list, hooks run in this order:
diary-nongregorian-listing-hook runs for the main diary file,
and each included file. For example, this is the appropriate hook
to process Islamic entries in all diary files.
diary-list-entries-hook runs once only, for the main diary file.
For example, this is appropriate for sorting all the entries.
If not using include files, there is no difference from the previous
hook.
diary-hook runs last, after the diary is displayed.
This is used e.g. by appt-check.
Functions called by these hooks may use the variables original-date
and number, which are the arguments with which this function was called.
Note that hook functions should _not_ use date, but original-date.
(Sexp diary entries may use date - see diary-list-sexp-entries.)
This function displays the list using diary-display-function, unless
LIST-ONLY is non-nil, in which case it just returns the list.
Source Code
;; Defined in /usr/src/emacs/lisp/calendar/diary-lib.el.gz
(defvar diary--date-string) ; bound in diary-list-entries
(defun diary-list-entries (date number &optional list-only)
"Create and display a buffer containing the relevant lines in `diary-file'.
Selects entries for NUMBER days starting with date DATE. Hides any
other entries using overlays. If NUMBER is less than 1, this function
does nothing.
Returns a list of all relevant diary entries found.
The list entries have the form ((MONTH DAY YEAR) STRING SPECIFIER) where
\(MONTH DAY YEAR) is the date of the entry, STRING is the entry text, and
SPECIFIER is the applicability. If the variable `diary-list-include-blanks'
is non-nil, this list includes a dummy diary entry consisting of the empty
string for a date with no diary entries.
If producing entries for multiple dates (i.e., NUMBER > 1), then
this function normally returns the entries from any given diary
file in date order. The entries for any given day are in the
order in which they were found in the file, not necessarily in
time-of-day order. Note that any functions present on the
hooks (see below) may add entries, or change the order. For
example, `diary-include-other-diary-files' adds entries from any
include files that it finds to the end of the original list. The
entries from each file will be in date order, but the overall
list will not be. If you want the entire list to be in time
order, add `diary-sort-entries' to the end of `diary-list-entries-hook'.
After preparing the initial list, hooks run in this order:
`diary-nongregorian-listing-hook' runs for the main diary file,
and each included file. For example, this is the appropriate hook
to process Islamic entries in all diary files.
`diary-list-entries-hook' runs once only, for the main diary file.
For example, this is appropriate for sorting all the entries.
If not using include files, there is no difference from the previous
hook.
`diary-hook' runs last, after the diary is displayed.
This is used e.g. by `appt-check'.
Functions called by these hooks may use the variables `original-date'
and `number', which are the arguments with which this function was called.
Note that hook functions should _not_ use `date', but `original-date'.
\(Sexp diary entries may use `date' - see `diary-list-sexp-entries'.)
This function displays the list using `diary-display-function', unless
LIST-ONLY is non-nil, in which case it just returns the list."
(unless number
(setq number (if (vectorp diary-number-of-entries)
(aref diary-number-of-entries (calendar-day-of-week date))
diary-number-of-entries)))
(when (> number 0)
(let* ((original-date date) ; save for possible use in the hooks
(diary--date-string (calendar-date-string date))
(diary-buffer (find-buffer-visiting diary-file))
;; Dynamically bound in diary-include-files.
(d-incp (and (boundp 'diary-including) diary-including))
diary-entries-list file-glob-attrs temp-buff)
(unless d-incp
(setq diary-included-files nil)
(message "Preparing diary..."))
(unwind-protect
(with-current-buffer (or diary-buffer
(if list-only
(setq temp-buff (generate-new-buffer
" *diary-temp*"))
(find-file-noselect diary-file t)))
(if diary-buffer
(or (verify-visited-file-modtime diary-buffer)
(revert-buffer t t)))
(if temp-buff
;; If including, caller has already verified it is readable.
(insert-file-contents diary-file)
;; Setup things like the header-line-format and invisibility-spec.
(if (eq major-mode (default-value 'major-mode))
(diary-mode)
;; This kludge is to make customizations to
;; diary-header-line-flag after diary has been displayed
;; take effect. Unconditionally calling (diary-mode)
;; clobbers file local variables.
;; https://lists.gnu.org/r/emacs-pretest-bug/2007-03/msg00363.html
;; https://lists.gnu.org/r/emacs-pretest-bug/2007-04/msg00404.html
(if (eq major-mode 'diary-mode)
(setq header-line-format (and diary-header-line-flag
diary-header-line-format)))))
;; d-s-p is passed to the diary display function.
(let ((diary-saved-point (point)))
(save-excursion
(save-restriction
(widen) ; bug#5093
(setq file-glob-attrs (cadr (diary-pull-attrs nil "")))
(with-syntax-table diary-syntax-table
(goto-char (point-min))
(unless list-only
(let ((ol (make-overlay (point-min) (point-max) nil t nil)))
(setq-local diary-selective-display t)
(overlay-put ol 'invisible 'diary)
(overlay-put ol 'evaporate t)))
(dotimes (_ number)
(let ((sexp-found (diary-list-sexp-entries date))
(entry-found (diary-list-entries-2
date diary-nonmarking-symbol
file-glob-attrs list-only)))
(if diary-list-include-blanks
(or sexp-found entry-found
(diary-add-to-list date "" "" "" "")))
(setq date
(calendar-gregorian-from-absolute
(1+ (calendar-absolute-from-gregorian date)))))))
(goto-char (point-min))
;; Although it looks like list-entries-hook runs
;; every time, diary-include-other-diary-files
;; binds it to nil (essentially) when it runs
;; in included files.
(calendar-dlet ((number number)
(list-only list-only))
(run-hooks 'diary-nongregorian-listing-hook
'diary-list-entries-hook))
;; We could make this explicit:
;;; (run-hooks 'diary-nongregorian-listing-hook)
;;; (if d-incp
;;; (diary-include-other-diary-files) ; recurse
;;; (run-hooks 'diary-list-entries-hook))
(unless list-only
;; Avoid M-x diary; M-x calendar; M-x diary
;; clobbering the calendar window.
;; FIXME this is not the right solution.
(let ((display-buffer-fallback-action
(list (delq
'display-buffer-in-previous-window
(copy-sequence
(car display-buffer-fallback-action))))))
(funcall diary-display-function)))
(calendar-dlet ((number number)
(original-date original-date))
(run-hooks 'diary-hook))))))
(and temp-buff (buffer-name temp-buff) (kill-buffer temp-buff)))
(or d-incp
;; Don't clobber messages displayed while preparing the diary.
(not (equal (current-message) "Preparing diary..."))
(message "Preparing diary...done"))
diary-entries-list)))