contrib/lisp/org-checklist.el

   1 ;;; org-checklist.el --- org functions for checklist handling
   2
   3 ;; Copyright (C) 2008 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 (defgroup org-checklist nil
  48   "Extended checklist handling for org"
  49   :tag "Org-checklist"
  50   :group 'org)
  51
  52 (defcustom org-checklist-export-time-format "%Y%m%d%H%M"
  53   "The format of timestamp appended to LIST_EXPORT_BASENAME to
  54   make the name of the export file."
  55   :link '(function-link format-time-string)
  56   :group 'org-checklist
  57   :type 'string)
  58
  59 (defcustom org-checklist-export-function 'org-export-as-ascii
  60   "function used to prepare the export file for printing"
  61   :group 'org-checklist
  62   :type '(radio (function-item :tag "ascii text" org-export-as-ascii)
  63                 (function-item :tag "HTML"  org-export-as-html)
  64                 (function-item :tag "LaTeX" :value org-export-as-latex)
  65                 (function-item :tag "XOXO" :value org-export-as-xoxo)))
  66
  67 (defcustom org-checklist-export-params nil
  68   "options for the export function file for printing"
  69   :group 'org-checklist
  70   :type '(repeat string))
  71
  72 (defcustom org-checklist-a2ps-params nil
  73   "options for a2ps for printing"
  74   :group 'org-checklist
  75   :type '(repeat string))
  76
  77 (defun org-reset-checkbox-state-maybe ()
  78   "Reset all checkboxes in an entry if the `RESET_CHECK_BOXES' property is set"
  79   (interactive "*")
  80   (if (org-entry-get (point) "RESET_CHECK_BOXES")
  81       (org-reset-checkbox-state-subtree)))
  82
  83
  84 (defun org-make-checklist-export ()
  85   "Produce a checklist containing all unchecked items from a list
  86 of checkbox items"
  87   (interactive "*")
  88   (if (org-entry-get (point) "LIST_EXPORT_BASENAME")
  89       (let* ((export-file (concat (org-entry-get (point) "LIST_EXPORT_BASENAME" nil)
  90                                   "-" (format-time-string
  91                                        org-checklist-export-time-format)
  92                                   ".org"))
  93              (print (case (org-entry-get (point) "PRINT_EXPORT" nil)
  94                       (("" "nil" nil) nil)
  95                       (t t)
  96                       (nil (y-or-n-p "Print list? "))))
  97              exported-lines
  98              (title "Checklist export"))
  99         (save-restriction
 100           (save-excursion
 101             (org-narrow-to-subtree)
 102             (org-update-checkbox-count-maybe)
 103             (org-show-subtree)
 104             (goto-char (point-min))
 105             (when (looking-at org-complex-heading-regexp)
 106               (setq title (match-string 4)))
 107             (goto-char (point-min))
 108             (let ((end (point-max)))
 109               (while (< (point) end)
 110                 (when (and (org-at-item-checkbox-p)
 111                            (or (string= (match-string 0) "[ ]")
 112                                (string= (match-string 0) "[-]")))
 113                   (add-to-list 'exported-lines (thing-at-point 'line) t))
 114                 (beginning-of-line 2)))
 115             (set-buffer (get-buffer-create export-file))
 116             (org-insert-heading)
 117             (insert (or title export-file) "\n")
 118             (dolist (entry exported-lines) (insert entry))
 119             (org-update-checkbox-count-maybe)
 120             (write-file export-file)
 121             (if (print)
 122                 (progn (funcall org-checklist-export-function
 123                                 org-checklist-export-params)
 124                        (let* ((current-a2ps-switches a2ps-switches)
 125                               (a2ps-switches (append current-a2ps-switches
 126                                                      org-checklist-a2ps-params)))
 127                          (a2ps-buffer)))))))))
 128
 129 (defun org-checklist ()
 130   (when (member state org-done-keywords)
 131     (org-make-checklist-export)
 132     (org-reset-checkbox-state-maybe)))
 133
 134 (add-hook 'org-after-todo-state-change-hook 'org-checklist)
 135
 136 (provide 'org-checklist)
 137
 138 ;;; org-checklist.el ends here
 139
 140
 141