contrib/lisp/org-depend.el

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