CONTRIB/org-depend.el

   1 ;;; org-depend.el --- TODO dependencies for Org-mode
   2
   3 ;; This file is not part of GNU Emacs.
   4 ;;
   5 ;; This file is free software; you can redistribute it and/or modify
   6 ;; it under the terms of the GNU General Public License as published by
   7 ;; the Free Software Foundation; either version 3, or (at your option)
   8 ;; any later version.
   9
  10 ;; GNU Emacs is distributed in the hope that it will be useful,
  11 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 ;; GNU General Public License for more details.
  14
  15 ;; You should have received a copy of the GNU General Public License
  16 ;; along with GNU Emacs; see the file COPYING.  If not, write to the
  17 ;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18 ;; Boston, MA 02110-1301, USA.
  19 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  20 ;;
  21 ;;; Commentary:
  22 ;;
  23 ;; WARNING: This file is just a PROOF OF CONCEPT, not a supported part
  24 ;;          of Org-mode.
  25 ;;
  26 ;; This is an example implementation of TODO dependencies in Org-mode.
  27 ;; It uses the new hooks in version 5.13 of Org-mode,
  28 ;; `org-trigger-hook' and `org-blocker-hook'.
  29 ;;
  30 ;; It implements the following:
  31 ;;
  32 ;; Triggering
  33 ;; ----------
  34 ;;
  35 ;; 1) If an entry contains a TRIGGER property that contains the string
  36 ;;    "chain-siblings(KEYWORD)", then switching that entry to DONE does
  37 ;;    do the following:
  38 ;;    - The sibling following this entry switched to todo-state KEYWORD.
  39 ;;    - The sibling also gets a TRIGGER property "chain-sibling(KEYWORD)",
  40 ;;      property, to make sure that, when *it* is DONE, the chain will
  41 ;;      continue.
  42 ;;
  43 ;; 2) If the TRIGGER property contains any other words like
  44 ;;    XYZ(KEYWORD), these are treated as entry id's with keywords.  That
  45 ;;    means, Org-mode will search for an entry with the ID property XYZ
  46 ;;    and switch that entry to KEYWORD as well.
  47 ;;
  48 ;; Blocking
  49 ;; --------
  50 ;;
  51 ;; 1) If an entry contains a BLOCKER property that contains the word
  52 ;;    "previous-sibling", the sibling above the current entry is
  53 ;;    checked when you try to mark it DONE.  If it is still in a TODO
  54 ;;    state, the current state change is blocked.
  55 ;;
  56 ;; 2) If the BLOCKER property contains any other words, these are
  57 ;;    treated as entry id's.  That means, Org-mode will search for an
  58 ;;    entry with the ID property exactly equal to this word.  If any
  59 ;;    of these entries is not yet marked DONE, the current state change
  60 ;;    will be blocked.
  61 ;;
  62 ;; 3) Whenever a state change is blocked, an org-mark is pushed, so that
  63 ;;    you can find the offending entry with `C-c &'.
  64 ;;
  65 ;;; Example:
  66 ;;
  67 ;; When trying this example, make sure that the settings for TODO keywords
  68 ;; have been activated, i.e. include the following line and press C-c C-c
  69 ;; on the line before working with the example:
  70 ;;
  71 ;; #+TYP_TODO: TODO NEXT | DONE
  72 ;;
  73 ;; * TODO Win a million in Las Vegas
  74 ;;   The "third" TODO (see above) cannot become a TODO without this money.
  75 ;;
  76 ;;   :PROPERTIES:
  77 ;;     :ID: I-cannot-do-it-without-money
  78 ;;   :END:
  79 ;;
  80 ;; * Do this by doing a chain of TODO's
  81 ;; ** NEXT This is the first in this chain
  82 ;;    :PROPERTIES:
  83 ;;      :TRIGGER: chain-siblings(NEXT)
  84 ;;    :END:
  85 ;;
  86 ;; ** This is the second in this chain
  87 ;;
  88 ;; ** This is the third in this chain
  89 ;;    :PROPERTIES:
  90 ;;      :BLOCKER: I-cannot-do-it-without-money
  91 ;;    :END:
  92 ;;
  93 ;; ** This is the forth in this chain
  94 ;;    When this is DONE, we will also trigger entry XYZ-is-my-id
  95 ;;   :PROPERTIES:
  96 ;;     :TRIGGER: XYZ-is-my-id(TODO)
  97 ;;   :END:
  98 ;;
  99 ;; ** This is the fifth in this chain
 100 ;;
 101 ;; * Start writing report
 102 ;;   :PROPERTIES:
 103 ;;     :ID: XYZ-is-my-id
 104 ;;   :END:
 105 ;;
 106 ;;
 107
 108 (require 'org)
 109
 110 (defun org-depend-trigger-todo (change-plist)
 111   "Trigger new TODO entries after the current is switched to DONE.
 112 This does two different kinds of triggers:
 113
 114 - If the current entry contains a TRIGGER property that contains
 115   \"chain-siblings(KEYWORD)\", it goes to the next sibling, marks it
 116   KEYWORD and also installs the \"chain-sibling\" trigger to continue
 117   the chain.
 118 - Any other word (space-separated) like XYZ(KEYWORD) in the TRIGGER
 119   property is seen as an entry id.  Org-mode finds the entry with the
 120   corresponding ID property and switches it to the state TODO as well."
 121
 122   ;; Get information from the plist
 123   (let* ((type (plist-get change-plist :type))
 124                (pos (plist-get change-plist :position))
 125          (from (plist-get change-plist :from))
 126          (to (plist-get change-plist :to))
 127          (org-log-done nil) ; IMPROTANT!: no logging during automatic trigger!
 128          trigger triggers tr p1 kwd)
 129     (catch 'return
 130       (unless (eq type 'todo-state-change)
 131         ;; We are only handling todo-state-change....
 132         (throw 'return t))
 133       (unless (and (member from org-not-done-keywords)
 134                    (member to org-done-keywords))
 135         ;; This is not a change from TODO to DONE, ignore it
 136         (throw 'return t))
 137
 138       ;; OK, we just switched from a TODO state to a DONE state
 139       ;; Lets see if this entry has a TRIGGER property.
 140       ;; If yes, split it up on whitespace.
 141       (setq trigger (org-entry-get pos "TRIGGER")
 142             triggers (and trigger (org-split-string trigger "[ \t]+")))
 143
 144       ;; Go through all the triggers
 145       (while (setq tr (pop triggers))
 146         (cond
 147          ((string-match "\\`chain-siblings(\\(.*?\\))\\'" tr)
 148           ;; This is a TODO chain of siblings
 149           (setq kwd (match-string 1 tr))
 150           (catch 'exit
 151             (save-excursion
 152               (goto-char pos)
 153               ;; find the sibling, exit if no more siblings
 154               (condition-case nil
 155                   (outline-forward-same-level 1)
 156                 (error (throw 'exit t)))
 157               ;; mark the sibling TODO
 158               (org-todo kwd)
 159               ;; make sure the sibling will continue the chain
 160               (org-entry-add-to-multivalued-property
 161                nil "TRIGGER" (format "chain-siblings(%s)" kwd)))))
 162
 163          ((string-match "\\`\\(\\S-+\\)(\\(.*?\\))\\'" tr)
 164           ;; This seems to be ENTRY_ID(KEYWORD)
 165           (setq id (match-string 1 tr)
 166                 kwd (match-string 2 tr)
 167                 p1 (org-find-entry-with-id id))
 168           (when p1
 169             ;; there is an entry with this ID, mark it TODO
 170             (save-excursion
 171               (goto-char p1)
 172               (org-todo kwd)))))))))
 173
 174 (defun org-depend-block-todo (change-plist)
 175   "Block turning an entry into a TODO.
 176 This checks for a BLOCKER property in an entry and checks
 177 all the entries listed there.  If any of them is not done,
 178 block changing the current entry into a TODO entry.  If the property contains
 179 the word \"previous-sibling\", the sibling above the current entry is checked.
 180 Any other words are treated as entry id's. If an entry exists with the
 181 this ID property, that entry is also checked."
 182   ;; Get information from the plist
 183   (let* ((type (plist-get change-plist :type))
 184                (pos (plist-get change-plist :position))
 185          (from (plist-get change-plist :from))
 186          (to (plist-get change-plist :to))
 187          (org-log-done nil) ; IMPROTANT!: no logging during automatic trigger
 188          blocker blockers bl p1)
 189     (catch 'return
 190       (unless (eq type 'todo-state-change)
 191         ;; We are not handling this kind of change
 192         (throw 'return t))
 193       (unless (and (not from) (member to org-not-done-keywords))
 194         ;; This is not a change from nothing to TODO, ignore it
 195         (throw 'return t))
 196
 197       ;; OK, the plan is to switch from nothing to TODO
 198       ;; Lets see if we will allow it.  Find the BLOCKER property
 199       ;; and split it on whitespace.
 200       (setq blocker (org-entry-get pos "BLOCKER")
 201             blockers (and blocker (org-split-string blocker "[ \t]+")))
 202
 203       ;; go through all the blockers
 204       (while (setq bl (pop blockers))
 205         (cond
 206          ((equal bl "previous-sibling")
 207           ;; the sibling is required to be DONE.
 208           (catch 'ignore
 209             (save-excursion
 210               (goto-char pos)
 211               ;; find the older sibling, exit if no more siblings
 212               (condition-case nil
 213                   (outline-backward-same-level 1)
 214                 (error (throw 'ignore t)))
 215               ;; Check if this entry is not yet done and block
 216               (unless (org-entry-is-done-p)
 217                 ;; return nil, to indicate that we block the change!
 218                 (org-mark-ring-push)
 219                 (throw 'return nil)))))
 220
 221          ((setq p1 (org-find-entry-with-id bl))
 222           ;; there is an entry with this ID, check it out
 223           (save-excursion
 224             (goto-char p1)
 225             (unless (org-entry-is-done-p)
 226               ;; return nil, to indicate that we block the change!
 227               (org-mark-ring-push)
 228               (throw 'return nil))))))
 229       t ; return t to indicate that we are not blocking
 230       )))
 231
 232 (add-hook 'org-trigger-hook 'org-depend-trigger-todo)
 233 (add-hook 'org-blocker-hook 'org-depend-block-todo)
 234
 235 ;;; org-depend.el ends here