lisp/org-inlinetask.el

   1 ;;; org-inlinetask.el --- Tasks independent of outline hierarchy
   2
   3 ;; Copyright (C) 2009-2012 Free Software Foundation, Inc.
   4 ;;
   5 ;; Author: Carsten Dominik <carsten at orgmode dot org>
   6 ;; Keywords: outlines, hypermedia, calendar, wp
   7 ;; Homepage: http://orgmode.org
   8
   9 ;; This file is part of GNU Emacs.
  10
  11 ;; GNU Emacs is free software: you can redistribute it and/or modify
  12
  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.
  16
  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.
  21
  22 ;; You should have received a copy of the GNU General Public License
  23 ;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
  24
  25 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  26 ;;
  27 ;;; Commentary:
  28 ;;
  29 ;; This module implements inline tasks in Org-mode.  Inline tasks are
  30 ;; tasks that have all the properties of normal outline nodes, including
  31 ;; the ability to store meta data like scheduling dates, TODO state, tags
  32 ;; and properties.  However, these nodes are treated specially by the
  33 ;; visibility cycling and export commands.
  34 ;;
  35 ;; Visibility cycling exempts these nodes from cycling.  So whenever their
  36 ;; parent is opened, so are these tasks.  This will only work with
  37 ;; `org-cycle', so if you are also using other commands to show/hide
  38 ;; entries, you will occasionally find these tasks to behave like
  39 ;; all other outline nodes, seemingly splitting the text of the parent
  40 ;; into children.
  41 ;;
  42 ;; Export commands do not treat these nodes as part of the sectioning
  43 ;; structure, but as a special inline text that is either removed, or
  44 ;; formatted in some special way.  This in handled by
  45 ;; `org-inlinetask-export' and `org-inlinetask-export-templates'
  46 ;; variables.
  47 ;;
  48 ;; Special fontification of inline tasks, so that they can be immediately
  49 ;; recognized.  From the stars of the headline, only the first and the
  50 ;; last two will be visible, the others will be hidden using the
  51 ;; `org-hide' face.
  52 ;;
  53 ;; An inline task is identified solely by a minimum outline level, given
  54 ;; by the variable `org-inlinetask-min-level', default 15.
  55 ;;
  56 ;; If you need to have a time planning line (DEADLINE etc), drawers,
  57 ;; for example LOGBOOK of PROPERTIES, or even normal text as part of
  58 ;; the inline task, you must add an "END" headline with the same
  59 ;; number of stars.
  60 ;;
  61 ;; As an example, here are two valid inline tasks:
  62 ;;
  63 ;;    **************** TODO a small task
  64 ;;
  65 ;; and
  66 ;;
  67 ;;    **************** TODO another small task
  68 ;;                     DEADLINE: <2009-03-30 Mon>
  69 ;;                     :PROPERTIES:
  70 ;;                       :SOMETHING: or other
  71 ;;                     :END:
  72 ;;                     And here is some extra text
  73 ;;    **************** END
  74 ;;
  75 ;; Also, if you want to use refiling and archiving for inline tasks,
  76 ;; The END line must be present to make things work properly.
  77 ;;
  78 ;; This package installs one new command:
  79 ;;
  80 ;; C-c C-x t      Insert a new inline task with END line
  81
  82 ;;; Code:
  83
  84 (require 'org)
  85
  86 (defgroup org-inlinetask nil
  87   "Options concerning inline tasks in Org mode."
  88   :tag "Org Inline Tasks"
  89   :group 'org-structure)
  90
  91 (defcustom org-inlinetask-min-level 15
  92   "Minimum level a headline must have before it is treated as an inline task.
  93 Don't set it to something higher than `29' or clocking will break since this
  94 is the hardcoded maximum number of stars `org-clock-sum' will work with.
  95
  96 It is strongly recommended that you set `org-cycle-max-level' not at all,
  97 or to a number smaller than this one.  In fact, when `org-cycle-max-level' is
  98 not set, it will be assumed to be one less than the value of smaller than
  99 the value of this variable."
 100   :group 'org-inlinetask
 101   :type '(choice
 102           (const :tag "Off" nil)
 103           (integer)))
 104
 105 (defcustom org-inlinetask-export t
 106   "Non-nil means export inline tasks.
 107 When nil, they will not be exported."
 108   :group 'org-inlinetask
 109   :type 'boolean)
 110
 111 (defvar org-inlinetask-export-templates
 112   '((html "<div class=\"inlinetask\"><b>%s%s</b><br />%s</div>"
 113           '((unless (eq todo "")
 114               (format "<span class=\"%s %s\">%s%s</span> "
 115                       class todo todo priority))
 116             heading content))
 117     (odt "%s" '((org-odt-format-inlinetask heading content
 118                                            todo priority tags)))
 119
 120     (latex "\\begin\{description\}\n\\item[%s%s]~%s\\end\{description\}"
 121            '((unless (eq todo "") (format "\\textsc\{%s%s\} " todo priority))
 122              heading content))
 123     (ascii "     -- %s%s%s"
 124            '((unless (eq todo "") (format "%s%s " todo priority))
 125              heading
 126              (unless (eq content "")
 127                (format "\n         ¦ %s"
 128                        (mapconcat 'identity (org-split-string content "\n")
 129                                   "\n         ¦ ")))))
 130     (docbook "<variablelist>
 131 <varlistentry>
 132 <term>%s%s</term>
 133 <listitem><para>%s</para></listitem>
 134 </varlistentry>
 135 </variablelist>"
 136              '((unless (eq todo "") (format "%s%s " todo priority))
 137                heading content)))
 138   "Templates for inline tasks in various exporters.
 139
 140 This variable is an alist in the shape of \(BACKEND STRING OBJECTS\).
 141
 142 BACKEND is the name of the backend for the template \(ascii, html...\).
 143
 144 STRING is a format control string.
 145
 146 OBJECTS is a list of elements to be substituted into the format
 147 string.  They can be of any type, from a string to a form
 148 returning a value (thus allowing conditional insertion).  A nil
 149 object will be substituted as the empty string.  Obviously, there
 150 must be at least as many objects as %-sequences in the format
 151 string.
 152
 153 Moreover, the following special keywords are provided: `todo',
 154 `priority', `heading', `content', `tags'.  If some of them are not
 155 defined in an inline task, their value is the empty string.
 156
 157 As an example, valid associations are:
 158
 159 \(html \"<ul><li>%s <p>%s</p></li></ul>\" \(heading content\)\)
 160
 161 or, with the additional package \"todonotes\" for LaTeX,
 162
 163 \(latex \"\\todo[inline]{\\textbf{\\textsf{%s %s}}\\linebreak{} %s}\"
 164        '\(\(unless \(eq todo \"\"\)
 165            \(format \"\\textsc{%s%s}\" todo priority\)\)
 166          heading content\)\)\)")
 167
 168 (defvar org-odd-levels-only)
 169 (defvar org-keyword-time-regexp)
 170 (defvar org-drawer-regexp)
 171 (defvar org-complex-heading-regexp)
 172 (defvar org-property-end-re)
 173
 174 (defcustom org-inlinetask-default-state nil
 175   "Non-nil means make inline tasks have a TODO keyword initially.
 176 This should be the state `org-inlinetask-insert-task' should use by
 177 default, or nil of no state should be assigned."
 178   :group 'org-inlinetask
 179   :type '(choice
 180           (const :tag "No state" nil)
 181           (string :tag "Specific state")))
 182
 183 (defun org-inlinetask-insert-task (&optional no-state)
 184   "Insert an inline task.
 185 If prefix arg NO-STATE is set, ignore `org-inlinetask-default-state'."
 186   (interactive "P")
 187   ;; Error when inside an inline task, except if point was at its very
 188   ;; beginning, in which case the new inline task will be inserted
 189   ;; before this one.
 190   (when (and (org-inlinetask-in-task-p)
 191              (not (and (org-inlinetask-at-task-p) (bolp))))
 192     (error "Cannot nest inline tasks"))
 193   (or (bolp) (newline))
 194   (let* ((indent (if org-odd-levels-only
 195                      (1- (* 2 org-inlinetask-min-level))
 196                    org-inlinetask-min-level))
 197          (indent-string (concat (make-string indent ?*) " ")))
 198     (insert indent-string
 199             (if (or no-state (not org-inlinetask-default-state))
 200                 "\n"
 201               (concat org-inlinetask-default-state " \n"))
 202             indent-string "END\n"))
 203   (end-of-line -1))
 204 (define-key org-mode-map "\C-c\C-xt" 'org-inlinetask-insert-task)
 205
 206 (defun org-inlinetask-outline-regexp ()
 207   "Return string matching an inline task heading.
 208 The number of levels is controlled by `org-inlinetask-min-level'."
 209   (let ((nstars (if org-odd-levels-only
 210                     (1- (* org-inlinetask-min-level 2))
 211                   org-inlinetask-min-level)))
 212     (format "^\\(\\*\\{%d,\\}\\)[ \t]+" nstars)))
 213
 214 (defun org-inlinetask-at-task-p ()
 215   "Return true if point is at beginning of an inline task."
 216   (save-excursion
 217     (beginning-of-line)
 218     (and (looking-at (concat (org-inlinetask-outline-regexp)  "\\(.*\\)"))
 219          (not (string-match "^end[ \t]*$" (downcase (match-string 2)))))))
 220
 221 (defun org-inlinetask-in-task-p ()
 222   "Return true if point is inside an inline task."
 223   (save-excursion
 224     (beginning-of-line)
 225     (let* ((case-fold-search t)
 226            (stars-re (org-inlinetask-outline-regexp))
 227            (task-beg-re (concat stars-re "\\(?:.*\\)"))
 228            (task-end-re (concat stars-re "END[ \t]*$")))
 229       (or (org-looking-at-p task-beg-re)
 230           (and (re-search-forward "^\\*+[ \t]+" nil t)
 231                (progn (beginning-of-line) (org-looking-at-p task-end-re)))))))
 232
 233 (defun org-inlinetask-goto-beginning ()
 234   "Go to the beginning of the inline task at point."
 235   (end-of-line)
 236   (let ((case-fold-search t)
 237         (inlinetask-re (org-inlinetask-outline-regexp)))
 238     (re-search-backward inlinetask-re nil t)
 239     (when (org-looking-at-p (concat inlinetask-re "END[ \t]*$"))
 240       (re-search-backward inlinetask-re nil t))))
 241
 242 (defun org-inlinetask-goto-end ()
 243   "Go to the end of the inline task at point.
 244 Return point."
 245   (save-match-data
 246     (beginning-of-line)
 247     (let* ((case-fold-search t)
 248            (inlinetask-re (org-inlinetask-outline-regexp))
 249            (task-end-re (concat inlinetask-re "END[ \t]*$")))
 250       (cond
 251        ((looking-at task-end-re) (forward-line))
 252        ((looking-at inlinetask-re)
 253         (forward-line)
 254         (cond
 255          ((looking-at task-end-re) (forward-line))
 256          ((looking-at inlinetask-re))
 257          ((org-inlinetask-in-task-p)
 258           (re-search-forward inlinetask-re nil t)
 259           (forward-line))))
 260        (t (re-search-forward inlinetask-re nil t)
 261           (forward-line)))
 262       (point))))
 263
 264 (defun org-inlinetask-get-task-level ()
 265   "Get the level of the inline task around.
 266 This assumes the point is inside an inline task."
 267   (save-excursion
 268     (end-of-line)
 269     (re-search-backward (org-inlinetask-outline-regexp) nil t)
 270     (- (match-end 1) (match-beginning 1))))
 271
 272 (defun org-inlinetask-promote ()
 273   "Promote the inline task at point.
 274 If the task has an end part, promote it.  Also, prevents level from
 275 going below `org-inlinetask-min-level'."
 276   (interactive)
 277   (if (not (org-inlinetask-in-task-p))
 278       (error "Not in an inline task")
 279     (save-excursion
 280       (let* ((lvl (org-inlinetask-get-task-level))
 281              (next-lvl (org-get-valid-level lvl -1))
 282              (diff (- next-lvl lvl))
 283              (down-task (concat (make-string next-lvl ?*)))
 284              beg)
 285         (if (< next-lvl org-inlinetask-min-level)
 286             (error "Cannot promote an inline task at minimum level")
 287           (org-inlinetask-goto-beginning)
 288           (setq beg (point))
 289           (replace-match down-task nil t nil 1)
 290           (org-inlinetask-goto-end)
 291           (if (eobp) (beginning-of-line) (forward-line -1))
 292           (unless (= (point) beg)
 293             (replace-match down-task nil t nil 1)
 294             (when org-adapt-indentation
 295               (goto-char beg)
 296               (org-fixup-indentation diff))))))))
 297
 298 (defun org-inlinetask-demote ()
 299   "Demote the inline task at point.
 300 If the task has an end part, also demote it."
 301   (interactive)
 302   (if (not (org-inlinetask-in-task-p))
 303       (error "Not in an inline task")
 304     (save-excursion
 305       (let* ((lvl (org-inlinetask-get-task-level))
 306              (next-lvl (org-get-valid-level lvl 1))
 307              (diff (- next-lvl lvl))
 308              (down-task (concat (make-string next-lvl ?*)))
 309              beg)
 310         (org-inlinetask-goto-beginning)
 311         (setq beg (point))
 312         (replace-match down-task nil t nil 1)
 313         (org-inlinetask-goto-end)
 314         (if (eobp) (beginning-of-line) (forward-line -1))
 315         (unless (= (point) beg)
 316           (replace-match down-task nil t nil 1)
 317           (when org-adapt-indentation
 318             (goto-char beg)
 319             (org-fixup-indentation diff)))))))
 320
 321 (defvar org-export-current-backend) ; dynamically bound in org-exp.el
 322 (defun org-inlinetask-export-handler ()
 323   "Handle headlines with level larger or equal to `org-inlinetask-min-level'.
 324 Either remove headline and meta data, or do special formatting."
 325   (goto-char (point-min))
 326   (let* ((keywords-re (concat "^[ \t]*" org-keyword-time-regexp))
 327          (inline-re (concat (org-inlinetask-outline-regexp) ".*")))
 328     (while (re-search-forward inline-re nil t)
 329       (let ((headline (match-string 0))
 330             (beg (point-at-bol))
 331             (end (copy-marker (save-excursion
 332                                 (org-inlinetask-goto-end) (point))))
 333             content)
 334       ;; Delete SCHEDULED, DEADLINE...
 335       (while (re-search-forward keywords-re end t)
 336         (delete-region (point-at-bol) (1+ (point-at-eol))))
 337       (goto-char beg)
 338       ;; Delete drawers
 339       (while (re-search-forward org-drawer-regexp end t)
 340         (when (save-excursion (re-search-forward org-property-end-re nil t))
 341           (delete-region beg (1+ (match-end 0)))))
 342       ;; Get CONTENT, if any.
 343       (goto-char beg)
 344       (forward-line 1)
 345       (unless (= (point) end)
 346         (setq content (buffer-substring (point)
 347                                         (save-excursion (goto-char end)
 348                                                         (forward-line -1)
 349                                                         (point)))))
 350       ;; Remove the task.
 351       (goto-char beg)
 352       (delete-region beg end)
 353       (when (and org-inlinetask-export
 354                  (assq org-export-current-backend
 355                        org-inlinetask-export-templates))
 356         ;; Format CONTENT, if appropriate.
 357         (setq content
 358               (if (not (and content (string-match "\\S-" content)))
 359                   ""
 360                 ;; Ensure CONTENT has minimal indentation, a single
 361                 ;; newline character at its boundaries, and isn't
 362                 ;; protected.
 363                 (when (string-match "\\`\\([ \t]*\n\\)+" content)
 364                   (setq content (substring content (match-end 0))))
 365                 (when (string-match "[ \t\n]+\\'" content)
 366                   (setq content (substring content 0 (match-beginning 0))))
 367                 (org-add-props
 368                     (concat "\n\n" (org-remove-indentation content) "\n\n")
 369                     '(org-protected nil org-native-text nil))))
 370
 371         (when (string-match org-complex-heading-regexp headline)
 372           (let* ((nil-to-str
 373                   (function
 374                    ;; Change nil arguments into empty strings.
 375                    (lambda (el) (or (eval el) ""))))
 376                  ;;  Set up keywords provided to templates.
 377                  (todo (or (match-string 2 headline) ""))
 378                  (class (or (and (eq "" todo) "")
 379                             (if (member todo org-done-keywords) "done" "todo")))
 380                  (priority (or (match-string 3 headline) ""))
 381                  (heading (or (match-string 4 headline) ""))
 382                  (tags (or (match-string 5 headline) ""))
 383                  ;; Read `org-inlinetask-export-templates'.
 384                  (backend-spec (assq org-export-current-backend
 385                                      org-inlinetask-export-templates))
 386                  (format-str (org-add-props (nth 1 backend-spec)
 387                                  '(org-protected t org-native-text t)))
 388                  (tokens (cadr (nth 2 backend-spec)))
 389                  ;; Build export string. Ensure it won't break
 390                  ;; surrounding lists by giving it arbitrary high
 391                  ;; indentation.
 392                  (export-str (org-add-props
 393                                  (eval (append '(format format-str)
 394                                                (mapcar nil-to-str tokens)))
 395                                  '(original-indentation 1000))))
 396             ;; Ensure task starts a new paragraph.
 397             (unless (or (bobp)
 398                         (save-excursion (forward-line -1)
 399                                         (looking-at "[ \t]*$")))
 400               (insert "\n"))
 401             (insert export-str)
 402             (unless (bolp) (insert "\n")))))))))
 403
 404 (defun org-inlinetask-get-current-indentation ()
 405   "Get the indentation of the last non-while line above this one."
 406   (save-excursion
 407     (beginning-of-line 1)
 408     (skip-chars-backward " \t\n")
 409     (beginning-of-line 1)
 410     (or (org-at-item-p)
 411         (looking-at "[ \t]*"))
 412     (goto-char (match-end 0))
 413     (current-column)))
 414
 415 (defvar org-indent-indentation-per-level) ; defined in org-indent.el
 416
 417 (defface org-inlinetask
 418   (org-compatible-face 'shadow '((t (:bold t))))
 419   "Face for inlinetask headlines."
 420   :group 'org-faces)
 421
 422 (defun org-inlinetask-fontify (limit)
 423   "Fontify the inline tasks down to LIMIT."
 424   (let* ((nstars (if org-odd-levels-only
 425                      (1- (* 2 (or org-inlinetask-min-level 200)))
 426                    (or org-inlinetask-min-level 200)))
 427          (re (concat "^\\(\\*\\)\\(\\*\\{"
 428                     (format "%d" (- nstars 3))
 429                     ",\\}\\)\\(\\*\\* .*\\)"))
 430          ;; Virtual indentation will add the warning face on the first
 431          ;; star. Thus, in that case, only hide it.
 432          (start-face (if (and (org-bound-and-true-p org-indent-mode)
 433                               (> org-indent-indentation-per-level 1))
 434                          'org-hide
 435                        'org-warning)))
 436     (while (re-search-forward re limit t)
 437       (add-text-properties (match-beginning 1) (match-end 1)
 438                            `(face ,start-face font-lock-fontified t))
 439       (add-text-properties (match-beginning 2) (match-end 2)
 440                            '(face org-hide font-lock-fontified t))
 441       (add-text-properties (match-beginning 3) (match-end 3)
 442                            '(face org-inlinetask font-lock-fontified t)))))
 443
 444 (defun org-inlinetask-toggle-visibility ()
 445   "Toggle visibility of inline task at point."
 446   (let ((end (save-excursion
 447                (org-inlinetask-goto-end)
 448                (if (bolp) (1- (point)) (point))))
 449         (start (save-excursion
 450                  (org-inlinetask-goto-beginning)
 451                  (point-at-eol))))
 452     (cond
 453      ;; Nothing to show/hide.
 454      ((= end start))
 455      ;; Inlinetask was folded: expand it.
 456      ((get-char-property (1+ start) 'invisible)
 457       (outline-flag-region start end nil))
 458      (t (outline-flag-region start end t)))))
 459
 460 (defun org-inlinetask-remove-END-maybe ()
 461   "Remove an END line when present."
 462   (when (looking-at (format "\\([ \t]*\n\\)*\\*\\{%d,\\}[ \t]+END[ \t]*$"
 463                             org-inlinetask-min-level))
 464     (replace-match "")))
 465
 466 (eval-after-load "org-exp"
 467   '(add-hook 'org-export-preprocess-before-backend-specifics-hook
 468              'org-inlinetask-export-handler))
 469 (eval-after-load "org"
 470   '(add-hook 'org-font-lock-hook 'org-inlinetask-fontify))
 471
 472 (provide 'org-inlinetask)
 473
 474 ;;; org-inlinetask.el ends here