contrib/lisp/org-checklist.el

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