| blob | dc99a1d2ea930637ff7cea1e4e96e9ce4de04d8c |
1 ;;; org-depend.el --- TODO dependencies for Org-mode
2 ;; Copyright (C) 2008-2013 Free Software Foundation, Inc.
3 ;;
4 ;; Author: Carsten Dominik <carsten at orgmode dot org>
5 ;; Keywords: outlines, hypermedia, calendar, wp
6 ;; Homepage: http://orgmode.org
7 ;; Version: 0.08
8 ;;
9 ;; This file is not part of GNU Emacs.
10 ;;
11 ;; This file is free software; you can redistribute it and/or modify
12 ;; it under the terms of the GNU General Public License as published by
13 ;; the Free Software Foundation; either version 3, or (at your option)
14 ;; any later version.
16 ;; This program is distributed in the hope that it will be useful,
17 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
18 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 ;; GNU General Public License for more details.
21 ;; You should have received a copy of the GNU General Public License
22 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
23 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
24 ;;
25 ;;; Commentary:
26 ;;
27 ;; WARNING: This file is just a PROOF OF CONCEPT, not a supported part
28 ;; of Org-mode.
29 ;;
30 ;; This is an example implementation of TODO dependencies in Org-mode.
31 ;; It uses the new hooks in version 5.13 of Org-mode,
32 ;; `org-trigger-hook' and `org-blocker-hook'.
33 ;;
34 ;; It implements the following:
35 ;;
36 ;; Triggering
37 ;; ----------
38 ;;
39 ;; 1) If an entry contains a TRIGGER property that contains the string
40 ;; "chain-siblings(KEYWORD)", then switching that entry to DONE does
41 ;; do the following:
42 ;; - The sibling following this entry switched to todo-state KEYWORD.
43 ;; - The sibling also gets a TRIGGER property "chain-sibling(KEYWORD)",
44 ;; property, to make sure that, when *it* is DONE, the chain will
45 ;; continue.
46 ;;
47 ;; 2) If an entry contains a TRIGGER property that contains the string
48 ;; "chain-siblings-scheduled", then switching that entry to DONE does
49 ;; the following actions, similarly to "chain-siblings(KEYWORD)":
50 ;; - The sibling receives the same scheduled time as the entry
51 ;; marked as DONE (or, in the case, in which there is no scheduled
52 ;; time, the sibling does not get any either).
53 ;; - The sibling also gets the same TRIGGER property
54 ;; "chain-siblings-scheduled", so the chain can continue.
55 ;;
56 ;; 3) If the TRIGGER property contains the string
57 ;; "chain-find-next(KEYWORD[,OPTIONS])", then switching that entry
58 ;; to DONE do the following:
59 ;; - All siblings are of the entry are collected into a temporary
60 ;; list and then filtered and sorted according to OPTIONS
61 ;; - The first sibling on the list is changed into KEYWORD state
62 ;; - The sibling also gets the same TRIGGER property
63 ;; "chain-find-next", so the chain can continue.
64 ;;
65 ;; OPTIONS should be a comma separated string without spaces, and
66 ;; can contain following options:
67 ;;
68 ;; - from-top the candidate list is all of the siblings in
69 ;; the current subtree
70 ;;
71 ;; - from-bottom candidate list are all siblings from bottom up
72 ;;
73 ;; - from-current candidate list are all siblings from current item
74 ;; until end of subtree, then wrapped around from
75 ;; first sibling
76 ;;
77 ;; - no-wrap candidate list are siblings from current one down
78 ;;
79 ;; - todo-only Only consider siblings that have a todo keyword
80 ;; -
81 ;; - todo-and-done-only
82 ;; Same as above but also include done items.
83 ;;
84 ;; - priority-up sort by highest priority
85 ;; - priority-down sort by lowest priority
86 ;; - effort-up sort by highest effort
87 ;; - effort-down sort by lowest effort
88 ;;
89 ;; Default OPTIONS are from-top
90 ;;
91 ;;
92 ;; 4) If the TRIGGER property contains any other words like
93 ;; XYZ(KEYWORD), these are treated as entry id's with keywords. That
94 ;; means Org-mode will search for an entry with the ID property XYZ
95 ;; and switch that entry to KEYWORD as well.
96 ;;
97 ;; Blocking
98 ;; --------
99 ;;
100 ;; 1) If an entry contains a BLOCKER property that contains the word
101 ;; "previous-sibling", the sibling above the current entry is
102 ;; checked when you try to mark it DONE. If it is still in a TODO
103 ;; state, the current state change is blocked.
104 ;;
105 ;; 2) If the BLOCKER property contains any other words, these are
106 ;; treated as entry id's. That means Org-mode will search for an
107 ;; entry with the ID property exactly equal to this word. If any
108 ;; of these entries is not yet marked DONE, the current state change
109 ;; will be blocked.
110 ;;
111 ;; 3) Whenever a state change is blocked, an org-mark is pushed, so that
112 ;; you can find the offending entry with `C-c &'.
113 ;;
114 ;;; Example:
115 ;;
116 ;; When trying this example, make sure that the settings for TODO keywords
117 ;; have been activated, i.e. include the following line and press C-c C-c
118 ;; on the line before working with the example:
119 ;;
120 ;; #+TYP_TODO: TODO NEXT | DONE
121 ;;
122 ;; * TODO Win a million in Las Vegas
123 ;; The "third" TODO (see above) cannot become a TODO without this money.
124 ;;
125 ;; :PROPERTIES:
126 ;; :ID: I-cannot-do-it-without-money
127 ;; :END:
128 ;;
129 ;; * Do this by doing a chain of TODO's
130 ;; ** NEXT This is the first in this chain
131 ;; :PROPERTIES:
132 ;; :TRIGGER: chain-siblings(NEXT)
133 ;; :END:
134 ;;
135 ;; ** This is the second in this chain
136 ;;
137 ;; ** This is the third in this chain
138 ;; :PROPERTIES:
139 ;; :BLOCKER: I-cannot-do-it-without-money
140 ;; :END:
141 ;;
142 ;; ** This is the forth in this chain
143 ;; When this is DONE, we will also trigger entry XYZ-is-my-id
144 ;; :PROPERTIES:
145 ;; :TRIGGER: XYZ-is-my-id(TODO)
146 ;; :END:
147 ;;
148 ;; ** This is the fifth in this chain
149 ;;
150 ;; * Start writing report
151 ;; :PROPERTIES:
152 ;; :ID: XYZ-is-my-id
153 ;; :END:
154 ;;
155 ;;
162 "Whether to indicate blocked TODO items by a special tag."
167 "from-current,todo-only,priority-up"
168 "Default options for chain-find-next trigger"
173 "Perform a set of actions on the next sibling, if it exists,
174 copying the sibling spec TRIGGER-VAL to the next sibling."
178 ;; find the sibling, exit if no more siblings
182 ;; mark the sibling TODO
183 ,@rest
184 ;; make sure the sibling will continue the chain
191 "Trigger new TODO entries after the current is switched to DONE.
192 This does two different kinds of triggers:
194 - If the current entry contains a TRIGGER property that contains
197 the chain.
198 - If the current entry contains a TRIGGER property that contains
200 the scheduled time from the current task, also installing the property
201 in the sibling.
202 - Any other word (space-separated) like XYZ(KEYWORD) in the TRIGGER
203 property is seen as an entry id. Org-mode finds the entry with the
204 corresponding ID property and switches it to the state TODO as well."
206 ;; Refresh the effort text properties
208 ;; Get information from the plist
214 trigger triggers tr p1 kwd id)
217 ;; We are only handling todo-state-change....
221 ;; This is not a change from TODO to DONE, ignore it
224 ;; OK, we just switched from a TODO state to a DONE state
225 ;; Lets see if this entry has a TRIGGER property.
226 ;; If yes, split it up on whitespace.
230 ;; Go through all the triggers
235 ;; smarter sibling selection
241 org-depend-find-next-options
242 options))
245 options))
257 ;; go up to the parent headline, then advance to next child
275 items))
278 ;; massage the list according to options
296 todo-and-done-only)
298 items))
301 items
330 ;; This is a TODO chain of siblings
335 ;; This seems to be ENTRY_ID(KEYWORD)
340 ;; there is an entry with this ID, mark it TODO
348 "chain-siblings-scheduled"
352 "Block turning an entry into a TODO.
353 This checks for a BLOCKER property in an entry and checks
354 all the entries listed there. If any of them is not done,
355 block changing the current entry into a TODO entry. If the property contains
357 Any other words are treated as entry id's. If an entry exists with the
358 this ID property, that entry is also checked."
359 ;; Get information from the plist
365 blocker blockers bl p1
368 ;; If this is not a todo state change, or if this entry is
369 ;; DONE, do not block
376 ;; OK, the plan is to switch from nothing to TODO
377 ;; Lets see if we will allow it. Find the BLOCKER property
378 ;; and split it on whitespace.
382 ;; go through all the blockers
386 ;; the sibling is required to be DONE.
390 ;; find the older sibling, exit if no more siblings
394 ;; Check if this entry is not yet done and block
396 ;; return nil, to indicate that we block the change!
401 ;; there is an entry with this ID, check it out
405 ;; return nil, to indicate that we block the change!
408 t ; return t to indicate that we are not blocking
409 )))
413 proceed-p))
420 ;;; org-depend.el ends here