summaryrefslogtreecommitdiff
path: root/lisp/org/org-capture.el
diff options
context:
space:
mode:
Diffstat (limited to 'lisp/org/org-capture.el')
-rw-r--r--lisp/org/org-capture.el338
1 files changed, 178 insertions, 160 deletions
diff --git a/lisp/org/org-capture.el b/lisp/org/org-capture.el
index 7ae8fae3aab..1756b34fc5b 100644
--- a/lisp/org/org-capture.el
+++ b/lisp/org/org-capture.el
@@ -2,7 +2,7 @@
;; Copyright (C) 2010-2021 Free Software Foundation, Inc.
-;; Author: Carsten Dominik <carsten at orgmode dot org>
+;; Author: Carsten Dominik <carsten.dominik@gmail.com>
;; Keywords: outlines, hypermedia, calendar, wp
;; Homepage: https://orgmode.org
;;
@@ -69,6 +69,7 @@
(declare-function org-table-goto-line "org-table" (N))
(defvar dired-buffers)
+(defvar crm-separator)
(defvar org-end-time-was-given)
(defvar org-keyword-properties)
(defvar org-remember-default-headline)
@@ -107,7 +108,7 @@
(defun org-capture-upgrade-templates (templates)
"Update the template list to the new format.
-TEMPLATES is a template list, as in `org-capture-templates'. The
+TEMPLATES is a template list, as in `org-capture-templates'. The
new format unifies all the date/week tree targets into one that
also allows for an optional outline path to specify a target."
(let ((modified-templates
@@ -246,6 +247,10 @@ properties are:
:jump-to-captured When set, jump to the captured entry when finished.
+ :refile-targets When exiting capture mode via `org-capture-refile', the
+ variable `org-refile-targets' will be temporarily bound
+ to the value of this property.
+
:empty-lines Set this to the number of lines that should be inserted
before and after the new item. Default 0, only common
other value is 1.
@@ -301,13 +306,15 @@ be replaced with content and expanded:
current template.
%(sexp) Evaluate elisp `(sexp)' and replace it with the results.
Only placeholders pre-existing within the template, or
- introduced with %[pathname] are expanded this way. Since this
- happens after expanding non-interactive %-escapes, those can
- be used to fill the expression.
- %<...> The result of format-time-string on the ... format specification.
- %t Time stamp, date only. The time stamp is the current time,
- except when called from agendas with `\\[org-agenda-capture]' or
- with `org-capture-use-agenda-date' set.
+ introduced with %[pathname] are expanded this way.
+ Since this happens after expanding non-interactive
+ %-escapes, those can be used to fill the expression.
+ %<...> The result of `format-time-string' on the ... format
+ specification.
+ %t Time stamp, date only. The time stamp is the current
+ time, except when called from agendas with
+ `\\[org-agenda-capture]' or with
+ `org-capture-use-agenda-date' set.
%T Time stamp as above, with date and time.
%u, %U Like the above, but inactive time stamps.
%i Initial content, copied from the active region. If
@@ -317,12 +324,13 @@ be replaced with content and expanded:
%a Annotation, normally the link created with `org-store-link'.
%A Like %a, but prompt for the description part.
%l Like %a, but only insert the literal link.
+ %L Like %l, but without brackets (the link content itself).
%c Current kill ring head.
%x Content of the X clipboard.
%k Title of currently clocked task.
%K Link to currently clocked task.
%n User name (taken from the variable `user-full-name').
- %f File visited by current buffer when org-capture was called.
+ %f File visited by current buffer when `org-capture' was called.
%F Full path of the file or directory visited by current buffer.
%:keyword Specific information for certain link types, see below.
%^g Prompt for tags, with completion on tags in target file.
@@ -333,6 +341,8 @@ be replaced with content and expanded:
%^C Interactive selection of which kill or clip to use.
%^L Like %^C, but insert as link.
%^{prop}p Prompt the user for a value for property `prop'.
+ A default value can be specified like this:
+ %^{prop|default}p.
%^{prompt} Prompt the user for a string and replace this sequence with it.
A default value and a completion table can be specified like this:
%^{prompt|default|completion2|completion3|...}.
@@ -363,7 +373,7 @@ calendar | %:type %:date
When you need to insert a literal percent sign in the template,
you can escape ambiguous cases with a backward slash, e.g., \\%i."
:group 'org-capture
- :version "24.1"
+ :package-version '(Org . "9.5")
:set (lambda (s v) (set s (org-capture-upgrade-templates v)))
:type
(let ((file-variants '(choice :tag "Filename "
@@ -371,78 +381,78 @@ you can escape ambiguous cases with a backward slash, e.g., \\%i."
(function :tag "Function")
(variable :tag "Variable")
(sexp :tag "Form"))))
- `(repeat
- (choice :value ("" "" entry (file "~/org/notes.org") "")
- (list :tag "Multikey description"
- (string :tag "Keys ")
- (string :tag "Description"))
- (list :tag "Template entry"
- (string :tag "Keys ")
- (string :tag "Description ")
- (choice :tag "Capture Type " :value entry
- (const :tag "Org entry" entry)
- (const :tag "Plain list item" item)
- (const :tag "Checkbox item" checkitem)
- (const :tag "Plain text" plain)
- (const :tag "Table line" table-line))
- (choice :tag "Target location"
- (list :tag "File"
- (const :format "" file)
- ,file-variants)
- (list :tag "ID"
- (const :format "" id)
- (string :tag " ID"))
- (list :tag "File & Headline"
- (const :format "" file+headline)
- ,file-variants
- (string :tag " Headline"))
- (list :tag "File & Outline path"
- (const :format "" file+olp)
- ,file-variants
- (repeat :tag "Outline path" :inline t
- (string :tag "Headline")))
- (list :tag "File & Regexp"
- (const :format "" file+regexp)
- ,file-variants
- (regexp :tag " Regexp"))
- (list :tag "File [ & Outline path ] & Date tree"
- (const :format "" file+olp+datetree)
- ,file-variants
- (option (repeat :tag "Outline path" :inline t
- (string :tag "Headline"))))
- (list :tag "File & function"
- (const :format "" file+function)
- ,file-variants
- (sexp :tag " Function"))
- (list :tag "Current clocking task"
- (const :format "" clock))
- (list :tag "Function"
- (const :format "" function)
- (sexp :tag " Function")))
- (choice :tag "Template "
- (string)
- (list :tag "File"
- (const :format "" file)
- (file :tag "Template file"))
- (list :tag "Function"
- (const :format "" function)
- (function :tag "Template function")))
- (plist :inline t
- ;; Give the most common options as checkboxes
- :options (((const :format "%v " :prepend) (const t))
- ((const :format "%v " :immediate-finish) (const t))
- ((const :format "%v " :jump-to-captured) (const t))
- ((const :format "%v " :empty-lines) (const 1))
- ((const :format "%v " :empty-lines-before) (const 1))
- ((const :format "%v " :empty-lines-after) (const 1))
- ((const :format "%v " :clock-in) (const t))
- ((const :format "%v " :clock-keep) (const t))
- ((const :format "%v " :clock-resume) (const t))
- ((const :format "%v " :time-prompt) (const t))
- ((const :format "%v " :tree-type) (const week))
- ((const :format "%v " :unnarrowed) (const t))
- ((const :format "%v " :table-line-pos) (string))
- ((const :format "%v " :kill-buffer) (const t)))))))))
+ `(repeat
+ (choice :value ("" "" entry (file "~/org/notes.org") "")
+ (list :tag "Multikey description"
+ (string :tag "Keys ")
+ (string :tag "Description"))
+ (list :tag "Template entry"
+ (string :tag "Keys ")
+ (string :tag "Description ")
+ (choice :tag "Capture Type " :value entry
+ (const :tag "Org entry" entry)
+ (const :tag "Plain list item" item)
+ (const :tag "Checkbox item" checkitem)
+ (const :tag "Plain text" plain)
+ (const :tag "Table line" table-line))
+ (choice :tag "Target location"
+ (list :tag "File"
+ (const :format "" file)
+ ,file-variants)
+ (list :tag "ID"
+ (const :format "" id)
+ (string :tag " ID"))
+ (list :tag "File & Headline"
+ (const :format "" file+headline)
+ ,file-variants
+ (string :tag " Headline"))
+ (list :tag "File & Outline path"
+ (const :format "" file+olp)
+ ,file-variants
+ (repeat :tag "Outline path" :inline t
+ (string :tag "Headline")))
+ (list :tag "File & Regexp"
+ (const :format "" file+regexp)
+ ,file-variants
+ (regexp :tag " Regexp"))
+ (list :tag "File [ & Outline path ] & Date tree"
+ (const :format "" file+olp+datetree)
+ ,file-variants
+ (option (repeat :tag "Outline path" :inline t
+ (string :tag "Headline"))))
+ (list :tag "File & function"
+ (const :format "" file+function)
+ ,file-variants
+ (sexp :tag " Function"))
+ (list :tag "Current clocking task"
+ (const :format "" clock))
+ (list :tag "Function"
+ (const :format "" function)
+ (sexp :tag " Function")))
+ (choice :tag "Template "
+ (string)
+ (list :tag "File"
+ (const :format "" file)
+ (file :tag "Template file"))
+ (list :tag "Function"
+ (const :format "" function)
+ (function :tag "Template function")))
+ (plist :inline t
+ ;; Give the most common options as checkboxes
+ :options (((const :format "%v " :prepend) (const t))
+ ((const :format "%v " :immediate-finish) (const t))
+ ((const :format "%v " :jump-to-captured) (const t))
+ ((const :format "%v " :empty-lines) (const 1))
+ ((const :format "%v " :empty-lines-before) (const 1))
+ ((const :format "%v " :empty-lines-after) (const 1))
+ ((const :format "%v " :clock-in) (const t))
+ ((const :format "%v " :clock-keep) (const t))
+ ((const :format "%v " :clock-resume) (const t))
+ ((const :format "%v " :time-prompt) (const t))
+ ((const :format "%v " :tree-type) (const week))
+ ((const :format "%v " :unnarrowed) (const t))
+ ((const :format "%v " :table-line-pos) (string))
+ ((const :format "%v " :kill-buffer) (const t)))))))))
(defcustom org-capture-before-finalize-hook nil
"Hook that is run right before a capture process is finalized.
@@ -467,8 +477,7 @@ The capture buffer is current and still narrowed."
:type 'hook)
(defcustom org-capture-bookmark t
- "When non-nil, add a bookmark pointing at the last stored
-position when capturing."
+ "When non-nil, add bookmark pointing at the last stored position when capturing."
:group 'org-capture
:version "24.3"
:type 'boolean)
@@ -488,19 +497,19 @@ is copied to this variable, which is local in the indirect buffer.")
(defvar org-capture-clock-keep nil
"Local variable to store the value of the :clock-keep parameter.
-This is needed in case org-capture-finalize is called interactively.")
+This is needed in case `org-capture-finalize' is called interactively.")
-(defun org-capture-put (&rest stuff)
- "Add properties to the capture property list `org-capture-plist'."
- (while stuff
+(defun org-capture-put (&rest elements)
+ "Add ELEMENTS to the capture property list `org-capture-plist'."
+ (while elements
(setq org-capture-plist (plist-put org-capture-plist
- (pop stuff) (pop stuff)))))
-(defun org-capture-get (prop &optional local)
- "Get properties from the capture property list `org-capture-plist'.
+ (pop elements) (pop elements)))))
+(defun org-capture-get (property &optional local)
+ "Get PROPERTY from the capture property list `org-capture-plist'.
When LOCAL is set, use the local variable `org-capture-current-plist',
this is necessary after initialization of the capture process,
to avoid conflicts with other active capture processes."
- (plist-get (if local org-capture-current-plist org-capture-plist) prop))
+ (plist-get (if local org-capture-current-plist org-capture-plist) property))
;;; The minor mode
@@ -579,17 +588,17 @@ to avoid duplicates.)"
(string :tag " Capture key")
(string :tag "Replace by template")
(repeat :tag "Available when"
- (choice
- (cons :tag "Condition"
- (choice
- (const :tag "In file" in-file)
- (const :tag "Not in file" not-in-file)
- (const :tag "In buffer" in-buffer)
- (const :tag "Not in buffer" not-in-buffer)
- (const :tag "In mode" in-mode)
- (const :tag "Not in mode" not-in-mode))
- (regexp))
- (function :tag "Custom function"))))))
+ (choice
+ (cons :tag "Condition"
+ (choice
+ (const :tag "In file" in-file)
+ (const :tag "Not in file" not-in-file)
+ (const :tag "In buffer" in-buffer)
+ (const :tag "Not in buffer" not-in-buffer)
+ (const :tag "In mode" in-mode)
+ (const :tag "Not in mode" not-in-mode))
+ (regexp))
+ (function :tag "Custom function"))))))
(defcustom org-capture-use-agenda-date nil
"Non-nil means use the date at point when capturing from agendas.
@@ -882,7 +891,8 @@ for `entry'-type templates"))
(pos (make-marker))
(org-capture-is-refiling t)
(kill-buffer (org-capture-get :kill-buffer 'local))
- (jump-to-captured (org-capture-get :jump-to-captured 'local)))
+ (jump-to-captured (org-capture-get :jump-to-captured 'local))
+ (refile-targets (org-capture-get :refile-targets 'local)))
;; Since `org-capture-finalize' may alter buffer contents (e.g.,
;; empty lines) around entry, use a marker to refer to the
;; headline to be refiled. Place the marker in the base buffer,
@@ -892,11 +902,12 @@ for `entry'-type templates"))
;; early. We want to wait for the refiling to be over, so we
;; control when the latter function is called.
(org-capture-put :kill-buffer nil :jump-to-captured nil)
- (org-capture-finalize)
- (save-window-excursion
- (with-current-buffer base
- (org-with-point-at pos
- (call-interactively 'org-refile))))
+ (let ((org-refile-targets (or refile-targets org-refile-targets)))
+ (org-capture-finalize)
+ (save-window-excursion
+ (with-current-buffer base
+ (org-with-point-at pos
+ (call-interactively 'org-refile)))))
(when kill-buffer
(with-current-buffer base (save-buffer))
(kill-buffer base))
@@ -916,7 +927,7 @@ for `entry'-type templates"))
(interactive)
(org-goto-marker-or-bmk org-capture-last-stored-marker
(plist-get org-bookmark-names-plist
- :last-capture))
+ :last-capture))
(message "This is the last note stored by a capture process"))
;;; Supporting functions for handling the process
@@ -1025,28 +1036,23 @@ Store them in the capture property list."
(time-to-days org-overriding-default-time))
((or (org-capture-get :time-prompt)
(equal current-prefix-arg 1))
- ;; Prompt for date.
- (let ((prompt-time (org-read-date
- nil t nil "Date for tree entry:")))
+ ;; Prompt for date. Bind `org-end-time-was-given' so
+ ;; that `org-read-date-analyze' handles the time range
+ ;; case and returns `prompt-time' with the start value.
+ (let* ((org-time-was-given nil)
+ (org-end-time-was-given nil)
+ (prompt-time (org-read-date
+ nil t nil "Date for tree entry:")))
(org-capture-put
:default-time
- (cond ((and (or (not (boundp 'org-time-was-given))
- (not org-time-was-given))
- (not (= (time-to-days prompt-time) (org-today))))
- ;; Use 00:00 when no time is given for another
- ;; date than today?
- (apply #'encode-time 0 0
- org-extend-today-until
- (cl-cdddr (decode-time prompt-time))))
- ((string-match "\\([^ ]+\\)-[^ ]+[ ]+\\(.*\\)"
- org-read-date-final-answer)
- ;; Replace any time range by its start.
- (apply #'encode-time
- (org-read-date-analyze
- (replace-match "\\1 \\2" nil nil
- org-read-date-final-answer)
- prompt-time (decode-time prompt-time))))
- (t prompt-time)))
+ (if (or org-time-was-given
+ (= (time-to-days prompt-time) (org-today)))
+ prompt-time
+ ;; Use 00:00 when no time is given for another
+ ;; date than today?
+ (apply #'encode-time 0 0
+ org-extend-today-until
+ (cl-cdddr (decode-time prompt-time)))))
(time-to-days prompt-time)))
(t
;; Current date, possibly corrected for late night
@@ -1115,7 +1121,7 @@ FILE is a generalized file location, as handled by
(defun org-capture-place-template (&optional inhibit-wconf-store)
"Insert the template at the target location, and display the buffer.
-When `inhibit-wconf-store', don't store the window configuration, as it
+When INHIBIT-WCONF-STORE is non-nil, don't store the window configuration, as it
may have been stored before."
(unless inhibit-wconf-store
(org-capture-put :return-to-wconf (current-window-configuration)))
@@ -1410,21 +1416,21 @@ Of course, if exact position has been required, just put it there."
(org-capture--position-cursor beg end)))))
(defun org-capture-mark-kill-region (beg end)
- "Mark the region that will have to be killed when aborting capture."
+ "Mark region between BEG and END to be killed on aborted capture."
(let ((m1 (copy-marker beg))
(m2 (copy-marker end t)))
(org-capture-put :begin-marker m1)
(org-capture-put :end-marker m2)))
-(defun org-capture-position-for-last-stored (where)
- "Memorize the position that should later become the position of last capture."
+(defun org-capture-position-for-last-stored (position)
+ "Put POSITION on `org-capture-plist' for future use as `last capture`."
(cond
- ((integerp where)
+ ((integerp position)
(org-capture-put :position-for-last-stored
- (move-marker (make-marker) where
+ (move-marker (make-marker) position
(or (buffer-base-buffer (current-buffer))
(current-buffer)))))
- ((eq where 'table-line)
+ ((eq position 'table-line)
(org-capture-put :position-for-last-stored
(list 'table-line
(org-table-current-dline))))
@@ -1451,7 +1457,8 @@ Of course, if exact position has been required, just put it there."
(move-marker org-capture-last-stored-marker (point))))))
(defun org-capture-narrow (beg end)
- "Narrow, unless configuration says not to narrow."
+ "Possibly narrow to region between BEG and END.
+If configuration contains non-nil :unnarrowed property, do not narrow."
(unless (org-capture-get :unnarrowed)
(narrow-to-region beg end)))
@@ -1464,8 +1471,9 @@ of the template."
(replace-match "")))
(defun org-capture-empty-lines-before (&optional n)
- "Set the correct number of empty lines before the insertion point.
-Point will be after the empty lines, so insertion can directly be done."
+ "Insert N empty lines before the insertion point.
+Point will be after the empty lines, so insertion can directly be done.
+If N is nil, :empty-lines-before or :empty-lines are considered."
(setq n (or n (org-capture-get :empty-lines-before)
(org-capture-get :empty-lines) 0))
(let ((pos (point)))
@@ -1475,7 +1483,8 @@ Point will be after the empty lines, so insertion can directly be done."
(defun org-capture-empty-lines-after (&optional n)
"Set the correct number of empty lines after the inserted string.
-Point will remain at the first line after the inserted text."
+Point will remain at the first line after the inserted text.
+If N is nil, :empty-lines-after or :empty-lines are considered."
(setq n (or n (org-capture-get :empty-lines-after)
(org-capture-get :empty-lines) 0))
(org-back-over-empty-lines)
@@ -1487,7 +1496,7 @@ Point will remain at the first line after the inserted text."
(defvar org-clock-marker) ; Defined in org.el
(defun org-capture-set-plist (entry)
- "Initialize the property list from the template definition."
+ "Initialize the property list for ENTRY from the template definition."
(setq org-capture-plist (copy-sequence (nthcdr 5 entry)))
(org-capture-put :key (car entry) :description (nth 1 entry)
:target (nth 3 entry))
@@ -1504,7 +1513,7 @@ Point will remain at the first line after the inserted text."
(defun org-capture-goto-target (&optional template-key)
"Go to the target location of a capture template.
-The user is queried for the template."
+If TEMPLATE-KEY is nil, the user is queried for the template."
(interactive)
(let ((entry (org-capture-select-template template-key)))
(unless entry (error "No capture template selected"))
@@ -1514,7 +1523,7 @@ The user is queried for the template."
(goto-char (org-capture-get :pos))))
(defun org-capture-get-indirect-buffer (&optional buffer prefix)
- "Make an indirect buffer for a capture process.
+ "Make an indirect BUFFER for a capture process.
Use PREFIX as a prefix for the name of the indirect buffer."
(setq buffer (or buffer (current-buffer)))
(let ((n 1) (base (buffer-name buffer)) bname)
@@ -1556,8 +1565,10 @@ Lisp programs can force the template by setting KEYS to a string."
"List various clipboards values.")
(defun org-capture-fill-template (&optional template initial annotation)
- "Fill a template and return the filled template as a string.
-The template may still contain \"%?\" for cursor positioning."
+ "Fill a TEMPLATE and return the filled template as a string.
+The template may still contain \"%?\" for cursor positioning.
+INITIAL content and/or ANNOTATION may be specified, but will be overridden
+by their respective `org-store-link-plist' properties if present."
(let* ((template (or template (org-capture-get :template)))
(buffer (org-capture-get :buffer))
(file (buffer-file-name (or (buffer-base-buffer buffer) buffer)))
@@ -1595,6 +1606,9 @@ The template may still contain \"%?\" for cursor positioning."
(v-l (if (and v-a (string-match l-re v-a))
(replace-match "[[\\1]]" nil nil v-a)
v-a))
+ (v-L (if (and v-a (string-match l-re v-a))
+ (replace-match "\\1" nil nil v-a)
+ v-a))
(v-n user-full-name)
(v-k (if (marker-buffer org-clock-marker)
(org-no-properties org-clock-heading)
@@ -1647,7 +1661,7 @@ The template may still contain \"%?\" for cursor positioning."
;; Mark %() embedded elisp for later evaluation.
(org-capture-expand-embedded-elisp 'mark)
;; Expand non-interactive templates.
- (let ((regexp "%\\(:[-A-Za-z]+\\|<\\([^>\n]+\\)>\\|[aAcfFikKlntTuUx]\\)"))
+ (let ((regexp "%\\(:[-A-Za-z]+\\|<\\([^>\n]+\\)>\\|[aAcfFikKlLntTuUx]\\)"))
(save-excursion
(while (re-search-forward regexp nil t)
;; `org-capture-escaped-%' may modify buffer and cripple
@@ -1684,6 +1698,7 @@ The template may still contain \"%?\" for cursor positioning."
(?k v-k)
(?K v-K)
(?l v-l)
+ (?L v-L)
(?n v-n)
(?t v-t)
(?T v-T)
@@ -1731,12 +1746,11 @@ The template may still contain \"%?\" for cursor positioning."
(org-add-colon-after-tag-completion t)
(ins (mapconcat
#'identity
- (org-split-string
- (completing-read
- (if prompt (concat prompt ": ") "Tags: ")
- 'org-tags-completion-function nil nil nil
- 'org-tags-history)
- "[^[:alnum:]_@#%]+")
+ (let ((crm-separator "[ \t]*:[ \t]*"))
+ (completing-read-multiple
+ (if prompt (concat prompt ": ") "Tags: ")
+ org-last-tags-completion-table nil nil nil
+ 'org-tags-history))
":")))
(when (org-string-nw-p ins)
(unless (eq (char-before) ?:) (insert ":"))
@@ -1785,7 +1799,8 @@ The template may still contain \"%?\" for cursor positioning."
(setq l (org-up-heading-safe)))
(if l (point-marker)
(point-min-marker)))))))
- (value (org-read-property-value prompt pom)))
+ (value
+ (org-read-property-value prompt pom default)))
(org-set-property prompt value)))
((or "t" "T" "u" "U")
;; These are the date/time related ones.
@@ -1800,10 +1815,13 @@ The template may still contain \"%?\" for cursor positioning."
;; Load history list for current prompt.
(setq org-capture--prompt-history
(gethash prompt org-capture--prompt-history-table))
- (push (org-completing-read
- (concat (or prompt "Enter string")
- (and default (format " [%s]" default))
- ": ")
+ (push (org-completing-read
+ ;; `format-prompt' is new in Emacs 28.1.
+ (if (fboundp 'format-prompt)
+ (format-prompt (or prompt "Enter string") default)
+ (concat (or prompt "Enter string")
+ (and default (format " [%s]" default))
+ ": "))
completions
nil nil nil 'org-capture--prompt-history default)
strings)
@@ -1840,7 +1858,7 @@ The template may still contain \"%?\" for cursor positioning."
(defun org-capture-escaped-% ()
"Non-nil if % was escaped.
-If yes, unescape it now. Assume match-data contains the
+If yes, unescape it now. Assume `match-data' contains the
placeholder to check."
(save-excursion
(goto-char (match-beginning 0))
generated by cgit v1.2.3 (git 2.39.1) at 2025-04-06 05:13:26 +0000