1 ;;; org-inlinetask.el --- Tasks Independent of Outline Hierarchy -*- lexical-binding: t; -*-
3 ;; Copyright (C) 2009-2017 Free Software Foundation, Inc.
5 ;; Author: Carsten Dominik <carsten at orgmode dot org>
6 ;; Keywords: outlines, hypermedia, calendar, wp
7 ;; Homepage: http://orgmode.org
9 ;; This file is part of GNU Emacs.
11 ;; GNU Emacs is free software: you can redistribute it and/or modify
13 ;; it under the terms of the GNU General Public License as published by
14 ;; the Free Software Foundation, either version 3 of the License, or
15 ;; (at your option) any later version.
17 ;; GNU Emacs is distributed in the hope that it will be useful,
18 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
19 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 ;; GNU General Public License for more details.
22 ;; You should have received a copy of the GNU General Public License
23 ;; along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>.
25 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
29 ;; This module implements inline tasks in Org mode. Inline tasks are
30 ;; tasks that have all the properties of normal outline nodes,
31 ;; including the ability to store meta data like scheduling dates,
32 ;; TODO state, tags and properties. However, these nodes are treated
33 ;; specially by the visibility cycling.
35 ;; Visibility cycling exempts these nodes from cycling. So whenever
36 ;; their parent is opened, so are these tasks. This will only work
37 ;; with `org-cycle', so if you are also using other commands to
38 ;; show/hide entries, you will occasionally find these tasks to behave
39 ;; like all other outline nodes, seemingly splitting the text of the
40 ;; parent into children.
42 ;; Special fontification of inline tasks, so that they can be
43 ;; immediately recognized. From the stars of the headline, only the
44 ;; first and the last two will be visible, the others will be hidden
45 ;; using the `org-hide' face.
47 ;; An inline task is identified solely by a minimum outline level,
48 ;; given by the variable `org-inlinetask-min-level', default 15.
50 ;; If you need to have a time planning line (DEADLINE etc), drawers,
51 ;; for example LOGBOOK of PROPERTIES, or even normal text as part of
52 ;; the inline task, you must add an "END" headline with the same
55 ;; As an example, here are two valid inline tasks:
57 ;; **************** TODO a small task
61 ;; **************** TODO another small task
62 ;; DEADLINE: <2009-03-30 Mon>
64 ;; :SOMETHING: or other
66 ;; And here is some extra text
67 ;; **************** END
69 ;; Also, if you want to use refiling and archiving for inline tasks,
70 ;; The END line must be present to make things work properly.
72 ;; Note that you should not try to use inline tasks within plain list,
73 ;; visibility cycling is known to be problematic when doing so.
75 ;; This package installs one new command:
77 ;; C-c C-x t Insert a new inline task with END line
83 (defgroup org-inlinetask nil
84 "Options concerning inline tasks in Org mode."
85 :tag
"Org Inline Tasks"
86 :group
'org-structure
)
88 (defcustom org-inlinetask-min-level
15
89 "Minimum level a headline must have before it is treated as an inline task.
90 Don't set it to something higher than `29' or clocking will break since this
91 is the hardcoded maximum number of stars `org-clock-sum' will work with.
93 It is strongly recommended that you set `org-cycle-max-level' not at all,
94 or to a number smaller than this one. In fact, when `org-cycle-max-level' is
95 not set, it will be assumed to be one less than the value of smaller than
96 the value of this variable."
97 :group
'org-inlinetask
99 (const :tag
"Off" nil
)
102 (defcustom org-inlinetask-show-first-star nil
103 "Non-nil means display the first star of an inline task as additional marker.
104 When nil, the first star is not shown."
105 :tag
"Org Inline Tasks"
106 :group
'org-structure
109 (defvar org-odd-levels-only
)
110 (defvar org-keyword-time-regexp
)
111 (defvar org-complex-heading-regexp
)
112 (defvar org-property-end-re
)
114 (defcustom org-inlinetask-default-state nil
115 "Non-nil means make inline tasks have a TODO keyword initially.
116 This should be the state `org-inlinetask-insert-task' should use by
117 default, or nil if no state should be assigned."
118 :group
'org-inlinetask
121 (const :tag
"No state" nil
)
122 (string :tag
"Specific state")))
124 (defun org-inlinetask-insert-task (&optional no-state
)
125 "Insert an inline task.
126 If prefix arg NO-STATE is set, ignore `org-inlinetask-default-state'."
128 ;; Error when inside an inline task, except if point was at its very
129 ;; beginning, in which case the new inline task will be inserted
131 (when (and (org-inlinetask-in-task-p)
132 (not (and (org-inlinetask-at-task-p) (bolp))))
133 (error "Cannot nest inline tasks"))
134 (or (bolp) (newline))
135 (let* ((indent (if org-odd-levels-only
136 (1- (* 2 org-inlinetask-min-level
))
137 org-inlinetask-min-level
))
138 (indent-string (concat (make-string indent ?
*) " ")))
139 (insert indent-string
140 (if (or no-state
(not org-inlinetask-default-state
))
142 (concat org-inlinetask-default-state
" \n"))
143 indent-string
"END\n"))
145 (define-key org-mode-map
"\C-c\C-xt" 'org-inlinetask-insert-task
)
147 (defun org-inlinetask-outline-regexp ()
148 "Return string matching an inline task heading.
149 The number of levels is controlled by `org-inlinetask-min-level'."
150 (let ((nstars (if org-odd-levels-only
151 (1- (* org-inlinetask-min-level
2))
152 org-inlinetask-min-level
)))
153 (format "^\\(\\*\\{%d,\\}\\)[ \t]+" nstars
)))
155 (defun org-inlinetask-at-task-p ()
156 "Return true if point is at beginning of an inline task."
159 (and (looking-at (concat (org-inlinetask-outline-regexp) "\\(.*\\)"))
160 (not (string-match "^end[ \t]*$" (downcase (match-string 2)))))))
162 (defun org-inlinetask-in-task-p ()
163 "Return true if point is inside an inline task."
166 (let* ((case-fold-search t
)
167 (stars-re (org-inlinetask-outline-regexp))
168 (task-beg-re (concat stars-re
"\\(?:.*\\)"))
169 (task-end-re (concat stars-re
"END[ \t]*$")))
170 (or (looking-at-p task-beg-re
)
171 (and (re-search-forward "^\\*+[ \t]+" nil t
)
172 (progn (beginning-of-line) (looking-at-p task-end-re
)))))))
174 (defun org-inlinetask-goto-beginning ()
175 "Go to the beginning of the inline task at point."
177 (let ((case-fold-search t
)
178 (inlinetask-re (org-inlinetask-outline-regexp)))
179 (re-search-backward inlinetask-re nil t
)
180 (when (looking-at-p (concat inlinetask-re
"END[ \t]*$"))
181 (re-search-backward inlinetask-re nil t
))))
183 (defun org-inlinetask-goto-end ()
184 "Go to the end of the inline task at point.
188 (let* ((case-fold-search t
)
189 (inlinetask-re (org-inlinetask-outline-regexp))
190 (task-end-re (concat inlinetask-re
"END[ \t]*$")))
192 ((looking-at-p task-end-re
)
194 ((looking-at-p inlinetask-re
)
197 ((looking-at-p task-end-re
) (forward-line))
198 ((looking-at-p inlinetask-re
))
199 ((org-inlinetask-in-task-p)
200 (re-search-forward inlinetask-re nil t
)
204 (re-search-forward inlinetask-re nil t
)
208 (defun org-inlinetask-get-task-level ()
209 "Get the level of the inline task around.
210 This assumes the point is inside an inline task."
213 (re-search-backward (org-inlinetask-outline-regexp) nil t
)
214 (- (match-end 1) (match-beginning 1))))
216 (defun org-inlinetask-promote ()
217 "Promote the inline task at point.
218 If the task has an end part, promote it. Also, prevents level from
219 going below `org-inlinetask-min-level'."
221 (if (not (org-inlinetask-in-task-p))
222 (error "Not in an inline task")
224 (let* ((lvl (org-inlinetask-get-task-level))
225 (next-lvl (org-get-valid-level lvl -
1))
226 (diff (- next-lvl lvl
))
227 (down-task (concat (make-string next-lvl ?
*)))
229 (if (< next-lvl org-inlinetask-min-level
)
230 (error "Cannot promote an inline task at minimum level")
231 (org-inlinetask-goto-beginning)
233 (replace-match down-task nil t nil
1)
234 (org-inlinetask-goto-end)
235 (if (eobp) (beginning-of-line) (forward-line -
1))
236 (unless (= (point) beg
)
237 (replace-match down-task nil t nil
1)
238 (when org-adapt-indentation
240 (org-fixup-indentation diff
))))))))
242 (defun org-inlinetask-demote ()
243 "Demote the inline task at point.
244 If the task has an end part, also demote it."
246 (if (not (org-inlinetask-in-task-p))
247 (error "Not in an inline task")
249 (let* ((lvl (org-inlinetask-get-task-level))
250 (next-lvl (org-get-valid-level lvl
1))
251 (diff (- next-lvl lvl
))
252 (down-task (concat (make-string next-lvl ?
*)))
254 (org-inlinetask-goto-beginning)
256 (replace-match down-task nil t nil
1)
257 (org-inlinetask-goto-end)
258 (if (eobp) (beginning-of-line) (forward-line -
1))
259 (unless (= (point) beg
)
260 (replace-match down-task nil t nil
1)
261 (when org-adapt-indentation
263 (org-fixup-indentation diff
)))))))
265 (defun org-inlinetask-get-current-indentation ()
266 "Get the indentation of the last non-while line above this one."
268 (beginning-of-line 1)
269 (skip-chars-backward " \t\n")
270 (beginning-of-line 1)
272 (looking-at "[ \t]*"))
273 (goto-char (match-end 0))
276 (defvar org-indent-indentation-per-level
) ; defined in org-indent.el
278 (defface org-inlinetask
'((t :inherit shadow
))
279 "Face for inlinetask headlines."
282 (defun org-inlinetask-fontify (limit)
283 "Fontify the inline tasks down to LIMIT."
284 (let* ((nstars (if org-odd-levels-only
285 (1- (* 2 (or org-inlinetask-min-level
200)))
286 (or org-inlinetask-min-level
200)))
287 (re (concat "^\\(\\*\\)\\(\\*\\{"
288 (format "%d" (- nstars
3))
289 ",\\}\\)\\(\\*\\* .*\\)"))
290 ;; Virtual indentation will add the warning face on the first
291 ;; star. Thus, in that case, only hide it.
292 (start-face (if (and (bound-and-true-p org-indent-mode
)
293 (> org-indent-indentation-per-level
1))
296 (while (re-search-forward re limit t
)
297 (if org-inlinetask-show-first-star
298 (add-text-properties (match-beginning 1) (match-end 1)
299 `(face ,start-face font-lock-fontified t
)))
300 (add-text-properties (match-beginning
301 (if org-inlinetask-show-first-star
2 1))
303 '(face org-hide font-lock-fontified t
))
304 (add-text-properties (match-beginning 3) (match-end 3)
305 '(face org-inlinetask font-lock-fontified t
)))))
307 (defun org-inlinetask-toggle-visibility ()
308 "Toggle visibility of inline task at point."
309 (let ((end (save-excursion
310 (org-inlinetask-goto-end)
311 (if (bolp) (1- (point)) (point))))
312 (start (save-excursion
313 (org-inlinetask-goto-beginning)
316 ;; Nothing to show/hide.
318 ;; Inlinetask was folded: expand it.
319 ((eq (get-char-property (1+ start
) 'invisible
) 'outline
)
320 (outline-flag-region start end nil
)
321 (org-cycle-hide-drawers 'children
))
322 (t (outline-flag-region start end t
)))))
324 (defun org-inlinetask-hide-tasks (state)
325 "Hide inline tasks in buffer when STATE is `contents' or `children'.
326 This function is meant to be used in `org-cycle-hook'."
329 (let ((regexp (org-inlinetask-outline-regexp)))
331 (goto-char (point-min))
332 (while (re-search-forward regexp nil t
)
333 (org-inlinetask-toggle-visibility)
334 (org-inlinetask-goto-end)))))
338 (or (org-inlinetask-at-task-p)
339 (and (outline-next-heading) (org-inlinetask-at-task-p)))
340 (org-inlinetask-toggle-visibility)
341 (org-inlinetask-goto-end))))))
343 (defun org-inlinetask-remove-END-maybe ()
344 "Remove an END line when present."
345 (when (looking-at (format "\\([ \t]*\n\\)*\\*\\{%d,\\}[ \t]+END[ \t]*$"
346 org-inlinetask-min-level
))
349 (add-hook 'org-font-lock-hook
'org-inlinetask-fontify
)
350 (add-hook 'org-cycle-hook
'org-inlinetask-hide-tasks
)
352 (provide 'org-inlinetask
)
354 ;;; org-inlinetask.el ends here