Function: org-read-date
org-read-date is a byte-compiled function defined in org.el.gz.
Signature
(org-read-date &optional WITH-TIME TO-TIME FROM-STRING PROMPT DEFAULT-TIME DEFAULT-INPUT INACTIVE)
Documentation
Read a date, possibly a time, and make things smooth for the user.
The prompt will suggest to enter an ISO date, but you can also enter anything
which will at least partially be understood by parse-time-string.
Unrecognized parts of the date will default to the current day, month, year,
hour and minute. If this command is called to replace a timestamp at point,
or to enter the second timestamp of a range, the default time is taken
from the existing stamp. Furthermore, the command prefers the future,
so if you are giving a date where the year is not given, and the day-month
combination is already past in the current year, it will assume you
mean next year. For details, see the manual. A few examples:
3-2-5 --> 2003-02-05
feb 15 --> currentyear-02-15
2/15 --> currentyear-02-15
sep 12 9 --> 2009-09-12
12:45 --> today 12:45
22 sept 0:34 --> currentyear-09-22 0:34
12 --> currentyear-currentmonth-12
Fri --> nearest Friday after today
-Tue --> last Tuesday
etc.
Furthermore you can specify a relative date by giving, as the *first* thing
in the input: a plus/minus sign, a number and a letter [hdwmy] to indicate
change in days weeks, months, years.
With a single plus or minus, the date is relative to today. With a double
plus or minus, it is relative to the date in DEFAULT-TIME. E.g.
+4d --> four days from today
+4 --> same as above
+2w --> two weeks from today
++5 --> five days from default date
The function understands only English month and weekday abbreviations.
While prompting, a calendar is popped up - you can also select the
date with the mouse (button 1). The calendar shows a period of three
months. To scroll it to other months, use the keys > and <.
There are many other calendar navigation commands available, see
Info node (org) The date/time prompt for a full list.
If you don't like the calendar, turn it off with
(setq org-read-date-popup-calendar nil)
With optional argument TO-TIME, the date will immediately be converted to an internal time. With an optional argument WITH-TIME, the prompt will suggest to also insert a time. Note that when WITH-TIME is not set, you can still enter a time, and this function will inform the calling routine about this change. The calling routine may then choose to change the format used to insert the time stamp into the buffer to include the time. With optional argument FROM-STRING, read from this string instead from the user. PROMPT can overwrite the default prompt. DEFAULT-TIME is the time/date that is used for everything that is not specified by the user.
Source Code
;; Defined in /usr/src/emacs/lisp/org/org.el.gz
(defvar calendar-setup) ; Dynamically scoped.
(defun org-read-date (&optional with-time to-time from-string prompt
default-time default-input inactive)
"Read a date, possibly a time, and make things smooth for the user.
The prompt will suggest to enter an ISO date, but you can also enter anything
which will at least partially be understood by `parse-time-string'.
Unrecognized parts of the date will default to the current day, month, year,
hour and minute. If this command is called to replace a timestamp at point,
or to enter the second timestamp of a range, the default time is taken
from the existing stamp. Furthermore, the command prefers the future,
so if you are giving a date where the year is not given, and the day-month
combination is already past in the current year, it will assume you
mean next year. For details, see the manual. A few examples:
3-2-5 --> 2003-02-05
feb 15 --> currentyear-02-15
2/15 --> currentyear-02-15
sep 12 9 --> 2009-09-12
12:45 --> today 12:45
22 sept 0:34 --> currentyear-09-22 0:34
12 --> currentyear-currentmonth-12
Fri --> nearest Friday after today
-Tue --> last Tuesday
etc.
Furthermore you can specify a relative date by giving, as the *first* thing
in the input: a plus/minus sign, a number and a letter [hdwmy] to indicate
change in days weeks, months, years.
With a single plus or minus, the date is relative to today. With a double
plus or minus, it is relative to the date in DEFAULT-TIME. E.g.
+4d --> four days from today
+4 --> same as above
+2w --> two weeks from today
++5 --> five days from default date
The function understands only English month and weekday abbreviations.
While prompting, a calendar is popped up - you can also select the
date with the mouse (button 1). The calendar shows a period of three
months. To scroll it to other months, use the keys `>' and `<'.
There are many other calendar navigation commands available, see
Info node `(org) The date/time prompt' for a full list.
If you don't like the calendar, turn it off with
(setq org-read-date-popup-calendar nil)
With optional argument TO-TIME, the date will immediately be converted
to an internal time.
With an optional argument WITH-TIME, the prompt will suggest to
also insert a time. Note that when WITH-TIME is not set, you can
still enter a time, and this function will inform the calling routine
about this change. The calling routine may then choose to change the
format used to insert the time stamp into the buffer to include the time.
With optional argument FROM-STRING, read from this string instead from
the user. PROMPT can overwrite the default prompt. DEFAULT-TIME is
the time/date that is used for everything that is not specified by the
user."
(require 'parse-time)
(let* ((org-with-time with-time)
(org-timestamp-rounding-minutes
(if (equal org-with-time '(16))
'(0 0)
org-timestamp-rounding-minutes))
(ct (org-current-time))
(org-def (or org-overriding-default-time default-time ct))
(org-defdecode (decode-time org-def))
(cur-frame (selected-frame))
(mouse-autoselect-window nil) ; Don't let the mouse jump
(calendar-setup
(and (eq calendar-setup 'calendar-only) 'calendar-only))
(calendar-move-hook nil)
(calendar-view-diary-initially-flag nil)
(calendar-view-holidays-initially-flag nil)
ans (org-ans0 "") org-ans1 org-ans2 final cal-frame)
;; Rationalize `org-def' and `org-defdecode', if required.
;; Only consider `org-extend-today-until' when explicit reference
;; time is not given.
(when (and (not default-time)
(not org-overriding-default-time)
(< (nth 2 org-defdecode) org-extend-today-until))
(setf (nth 2 org-defdecode) -1)
(setf (nth 1 org-defdecode) 59)
(setq org-def (org-encode-time org-defdecode))
(setq org-defdecode (decode-time org-def)))
(let* ((timestr (format-time-string
(if org-with-time "%Y-%m-%d %H:%M" "%Y-%m-%d")
org-def))
(prompt (concat (if prompt (concat prompt " ") "")
(format "Date+time [%s]: " timestr))))
(cond
(from-string (setq ans from-string))
(org-read-date-popup-calendar
(save-excursion
(save-window-excursion
(calendar)
(when (eq calendar-setup 'calendar-only)
(setq cal-frame
(window-frame (get-buffer-window calendar-buffer 'visible)))
(select-frame cal-frame))
(org-eval-in-calendar '(setq cursor-type nil) t)
(unwind-protect
(progn
(calendar-forward-day (- (time-to-days org-def)
(calendar-absolute-from-gregorian
(calendar-current-date))))
(org-eval-in-calendar nil t)
(let* ((old-map (current-local-map))
(map (copy-keymap calendar-mode-map))
(minibuffer-local-map
(copy-keymap org-read-date-minibuffer-local-map)))
(org-defkey map (kbd "RET") 'org-calendar-select)
(org-defkey map [mouse-1] 'org-calendar-select-mouse)
(org-defkey map [mouse-2] 'org-calendar-select-mouse)
(unwind-protect
(progn
(use-local-map map)
(setq org-read-date-inactive inactive)
(add-hook 'post-command-hook 'org-read-date-display)
(setq org-ans0
(read-string prompt
default-input
'org-read-date-history
nil))
;; org-ans0: from prompt
;; org-ans1: from mouse click
;; org-ans2: from calendar motion
(setq ans
(concat org-ans0 " " (or org-ans1 org-ans2))))
(remove-hook 'post-command-hook 'org-read-date-display)
(use-local-map old-map)
(when org-read-date-overlay
(delete-overlay org-read-date-overlay)
(setq org-read-date-overlay nil)))))
(bury-buffer calendar-buffer)
(when cal-frame
(delete-frame cal-frame)
(select-frame-set-input-focus cur-frame))))))
(t ; Naked prompt only
(unwind-protect
(setq ans (read-string prompt default-input
'org-read-date-history timestr))
(when org-read-date-overlay
(delete-overlay org-read-date-overlay)
(setq org-read-date-overlay nil))))))
(setq final (org-read-date-analyze ans org-def org-defdecode))
(when org-read-date-analyze-forced-year
(message "Year was forced into %s"
(if org-read-date-force-compatible-dates
"compatible range (1970-2037)"
"range representable on this machine"))
(ding))
(setq final (org-encode-time final))
(setq org-read-date-final-answer ans)
(if to-time
final
;; This round-trip gets rid of 34th of August and stuff like that....
(setq final (decode-time final))
(if (and (boundp 'org-time-was-given) org-time-was-given)
(format "%04d-%02d-%02d %02d:%02d"
(nth 5 final) (nth 4 final) (nth 3 final)
(nth 2 final) (nth 1 final))
(format "%04d-%02d-%02d" (nth 5 final) (nth 4 final) (nth 3 final))))))