contrib/lisp/org-checklist.el

   1 ;;; org-checklist.el --- org functions for checklist handling
   2
   3 ;; Copyright (C) 2008-2014 James TD Smith
   4
   5 ;; Author: James TD Smith (@ ahktenzero (. mohorovi cc))
   6 ;; Version: 1.0
   7 ;; Keywords: org, checklists
   8 ;;
   9 ;; This file is not part of GNU Emacs.
  10 ;;
  11 ;; This program 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 ;; 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.
  20 ;;
  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 ;;; Commentary:
  25
  26 ;; This file provides some functions for handing repeated tasks which involve
  27 ;; checking off a list of items. By setting the RESET_CHECK_BOXES property in an
  28 ;; item, when the TODO state is set to done all checkboxes under that item are
  29 ;; cleared. If the LIST_EXPORT_BASENAME property is set, a file will be created
  30 ;; using the value of that property plus a timestamp, containing all the items
  31 ;; in the list which are not checked. Additionally the user will be prompted to
  32 ;; print the list.
  33 ;;
  34 ;; I use this for to keep track of stores of various things (food stores,
  35 ;; components etc) which I check periodically and use the exported list of items
  36 ;; which are not present as a shopping list.
  37 ;;
  38 ;;; Usage:
  39 ;; (require 'org-checklist)
  40 ;;
  41 ;; Set the RESET_CHECK_BOXES and LIST_EXPORT_BASENAME properties in items as
  42 ;; needed.
  43 ;;
  44 ;;; Code:
  45 (require 'org)
  46 (load "a2ps-print" 'no-error)
  47
  48 (setq org-default-properties (cons "RESET_CHECK_BOXES" (cons "LIST_EXPORT_BASENAME" org-default-properties)))
  49
  50 (defgroup org-checklist nil
  51   "Extended checklist handling for org"
  52   :tag "Org-checklist"
  53   :group 'org)
  54
  55 (defcustom org-checklist-export-time-format "%Y%m%d%H%M"
  56   "The format of timestamp appended to LIST_EXPORT_BASENAME to
  57   make the name of the export file."
  58   :link '(function-link format-time-string)
  59   :group 'org-checklist
  60   :type 'string)
  61
  62 (defcustom org-checklist-export-function 'org-export-as-ascii
  63   "function used to prepare the export file for printing"
  64   :group 'org-checklist
  65   :type '(radio (function-item :tag "ascii text" org-export-as-ascii)
  66                 (function-item :tag "HTML"  org-export-as-html)
  67                 (function-item :tag "LaTeX" :value org-export-as-latex)
  68                 (function-item :tag "XOXO" :value org-export-as-xoxo)))
  69
  70 (defcustom org-checklist-export-params nil
  71   "options for the export function file for printing"
  72   :group 'org-checklist
  73   :type '(repeat string))
  74
  75 (defcustom org-checklist-a2ps-params nil
  76   "options for a2ps for printing"
  77   :group 'org-checklist
  78   :type '(repeat string))
  79
  80 (defun org-reset-checkbox-state-maybe ()
  81   "Reset all checkboxes in an entry if the `RESET_CHECK_BOXES' property is set"
  82   (interactive "*")
  83   (if (org-entry-get (point) "RESET_CHECK_BOXES")
  84       (org-reset-checkbox-state-subtree)))
  85
  86
  87 (defun org-make-checklist-export ()
  88   "Produce a checklist containing all unchecked items from a list
  89 of checkbox items"
  90   (interactive "*")
  91   (if (org-entry-get (point) "LIST_EXPORT_BASENAME")
  92       (let* ((export-file (concat (org-entry-get (point) "LIST_EXPORT_BASENAME" nil)
  93                                   "-" (format-time-string
  94                                        org-checklist-export-time-format)
  95                                   ".org"))
  96              (print (case (org-entry-get (point) "PRINT_EXPORT" nil)
  97                       (("" "nil" nil) nil)
  98                       (t t)
  99                       (nil (y-or-n-p "Print list? "))))
 100              exported-lines
 101              (title "Checklist export"))
 102         (save-restriction
 103           (save-excursion
 104             (org-narrow-to-subtree)
 105             (org-update-checkbox-count-maybe)
 106             (org-show-subtree)
 107             (goto-char (point-min))
 108             (when (looking-at org-complex-heading-regexp)
 109               (setq title (match-string 4)))
 110             (goto-char (point-min))
 111             (let ((end (point-max)))
 112               (while (< (point) end)
 113                 (when (and (org-at-item-checkbox-p)
 114                            (or (string= (match-string 0) "[ ]")
 115                                (string= (match-string 0) "[-]")))
 116                   (add-to-list 'exported-lines (thing-at-point 'line) t))
 117                 (beginning-of-line 2)))
 118             (set-buffer (get-buffer-create export-file))
 119             (org-insert-heading)
 120             (insert (or title export-file) "\n")
 121             (dolist (entry exported-lines) (insert entry))
 122             (org-update-checkbox-count-maybe)
 123             (write-file export-file)
 124             (if (print)
 125                 (progn (funcall org-checklist-export-function
 126                                 org-checklist-export-params)
 127                        (let* ((current-a2ps-switches a2ps-switches)
 128                               (a2ps-switches (append current-a2ps-switches
 129                                                      org-checklist-a2ps-params)))
 130                          (a2ps-buffer)))))))))
 131
 132 (defun org-checklist ()
 133   (when (member org-state org-done-keywords) ;; org-state dynamically bound in org.el/org-todo
 134     (org-make-checklist-export)
 135     (org-reset-checkbox-state-maybe)))
 136
 137 (add-hook 'org-after-todo-state-change-hook 'org-checklist)
 138
 139 (provide 'org-checklist)
 140
 141 ;;; org-checklist.el ends here