Hide .orgx files and use theindex.org directly.
[org-mode.git] / contrib / lisp / org-invoice.el
blob7e2dad269aa1e600127871352289958424b79fdd
1 ;;; org-invoice.el --- Help manage client invoices in OrgMode
2 ;;
3 ;; Copyright (C) 2008 pmade inc. (Peter Jones pjones@pmade.com)
4 ;;
5 ;; Permission is hereby granted, free of charge, to any person obtaining
6 ;; a copy of this software and associated documentation files (the
7 ;; "Software"), to deal in the Software without restriction, including
8 ;; without limitation the rights to use, copy, modify, merge, publish,
9 ;; distribute, sublicense, and/or sell copies of the Software, and to
10 ;; permit persons to whom the Software is furnished to do so, subject to
11 ;; the following conditions:
13 ;; The above copyright notice and this permission notice shall be
14 ;; included in all copies or substantial portions of the Software.
16 ;; THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
17 ;; EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
18 ;; MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
19 ;; NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
20 ;; LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
21 ;; OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
22 ;; WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
24 ;; Commentary:
26 ;; Building on top of the terrific OrgMode, org-invoice tries to
27 ;; provide functionality for managing invoices. Currently, it does
28 ;; this by implementing an OrgMode dynamic block where invoice
29 ;; information is aggregated so that it can be exported.
31 ;; It also provides a library of functions that can be used to collect
32 ;; this invoice information and use it in other ways, such as
33 ;; submitting it to on-line invoicing tools.
35 ;; I'm already working on an elisp package to submit this invoice data
36 ;; to the FreshBooks on-line accounting tool.
38 ;; Usage:
40 ;; In your ~/.emacs:
41 ;; (autoload 'org-invoice-report "org-invoice")
42 ;; (autoload 'org-dblock-write:invoice "org-invoice")
44 ;; See the documentation in the following functions:
46 ;; `org-invoice-report'
47 ;; `org-dblock-write:invoice'
49 ;; Latest version:
51 ;; git clone git://pmade.com/elisp
52 (eval-when-compile
53 (require 'cl)
54 (require 'org))
56 (defgroup org-invoice nil
57 "OrgMode Invoice Helper"
58 :tag "Org-Invoice" :group 'org)
60 (defcustom org-invoice-long-date-format "%A, %B %d, %Y"
61 "The format string for long dates."
62 :type 'string :group 'org-invoice)
64 (defcustom org-invoice-strip-ts t
65 "Remove org timestamps that appear in headings."
66 :type 'boolean :group 'org-invoice)
68 (defcustom org-invoice-default-level 2
69 "The heading level at which a new invoice starts. This value
70 is used if you don't specify a scope option to the invoice block,
71 and when other invoice helpers are trying to find the heading
72 that starts an invoice.
74 The default is 2, assuming that you structure your invoices so
75 that they fall under a single heading like below:
77 * Invoices
78 ** This is invoice number 1...
79 ** This is invoice number 2...
81 If you don't structure your invoices using those conventions,
82 change this setting to the number that corresponds to the heading
83 at which an invoice begins."
84 :type 'integer :group 'org-invoice)
86 (defcustom org-invoice-start-hook nil
87 "Hook called when org-invoice is about to collect data from an
88 invoice heading. When this hook is called, point will be on the
89 heading where the invoice begins.
91 When called, `org-invoice-current-invoice' will be set to the
92 alist that represents the info for this invoice."
93 :type 'hook :group 'org-invoice)
95 (defcustom org-invoice-heading-hook nil
96 "Hook called when org-invoice is collecting data from a
97 heading. You can use this hook to add additional information to
98 the alist that represents the heading.
100 When this hook is called, point will be on the current heading
101 being processed, and `org-invoice-current-item' will contain the
102 alist for the current heading.
104 This hook is called repeatedly for each invoice item processed."
105 :type 'hook :group 'org-invoice)
107 (defvar org-invoice-current-invoice nil
108 "Information about the current invoice.")
110 (defvar org-invoice-current-item nil
111 "Information about the current invoice item.")
113 (defvar org-invoice-table-params nil
114 "The table parameters currently being used.")
116 (defvar org-invoice-total-time nil
117 "The total invoice time for the summary line.")
119 (defvar org-invoice-total-price nil
120 "The total invoice price for the summary line.")
122 (defconst org-invoice-version "1.0.0"
123 "The org-invoice version number.")
125 (defun org-invoice-goto-tree (&optional tree)
126 "Move point to the heading that represents the head of the
127 current invoice. The heading level will be taken from
128 `org-invoice-default-level' unless tree is set to a string that
129 looks like tree2, where the level is 2."
130 (let ((level org-invoice-default-level))
131 (save-match-data
132 (when (and tree (string-match "^tree\\([0-9]+\\)$" tree))
133 (setq level (string-to-number (match-string 1 tree)))))
134 (org-back-to-heading)
135 (while (and (> (org-reduced-level (org-outline-level)) level)
136 (org-up-heading-safe)))))
138 (defun org-invoice-heading-info ()
139 "Return invoice information from the current heading."
140 (let ((title (org-no-properties (org-get-heading t)))
141 (date (org-entry-get nil "TIMESTAMP" 'selective))
142 (work (org-entry-get nil "WORK" nil))
143 (rate (or (org-entry-get nil "RATE" t) "0"))
144 (level (org-outline-level))
145 raw-date long-date)
146 (unless date (setq date (org-entry-get nil "TIMESTAMP_IA" 'selective)))
147 (unless date (setq date (org-entry-get nil "TIMESTAMP" t)))
148 (unless date (setq date (org-entry-get nil "TIMESTAMP_IA" t)))
149 (unless work (setq work (org-entry-get nil "CLOCKSUM" nil)))
150 (unless work (setq work "00:00"))
151 (when date
152 (setq raw-date (apply 'encode-time (org-parse-time-string date)))
153 (setq long-date (format-time-string org-invoice-long-date-format raw-date)))
154 (when (and org-invoice-strip-ts (string-match org-ts-regexp-both title))
155 (setq title (replace-match "" nil nil title)))
156 (when (string-match "^[ \t]+" title)
157 (setq title (replace-match "" nil nil title)))
158 (when (string-match "[ \t]+$" title)
159 (setq title (replace-match "" nil nil title)))
160 (setq work (org-hh:mm-string-to-minutes work))
161 (setq rate (string-to-number rate))
162 (setq org-invoice-current-item (list (cons 'title title)
163 (cons 'date date)
164 (cons 'raw-date raw-date)
165 (cons 'long-date long-date)
166 (cons 'work work)
167 (cons 'rate rate)
168 (cons 'level level)
169 (cons 'price (* rate (/ work 60.0)))))
170 (run-hook-with-args 'org-invoice-heading-hook)
171 org-invoice-current-item))
173 (defun org-invoice-level-min-max (ls)
174 "Return a list where the car is the min level, and the cdr the max."
175 (let ((max 0) min level)
176 (dolist (info ls)
177 (when (cdr (assoc 'date info))
178 (setq level (cdr (assoc 'level info)))
179 (when (or (not min) (< level min)) (setq min level))
180 (when (> level max) (setq max level))))
181 (cons (or min 0) max)))
183 (defun org-invoice-collapse-list (ls)
184 "Reorganize the given list by dates."
185 (let ((min-max (org-invoice-level-min-max ls)) new)
186 (dolist (info ls)
187 (let* ((date (cdr (assoc 'date info)))
188 (work (cdr (assoc 'work info)))
189 (price (cdr (assoc 'price info)))
190 (long-date (cdr (assoc 'long-date info)))
191 (level (cdr (assoc 'level info)))
192 (bucket (cdr (assoc date new))))
193 (if (and (/= (car min-max) (cdr min-max))
194 (= (car min-max) level)
195 (= work 0) (not bucket) date)
196 (progn
197 (setq info (assq-delete-all 'work info))
198 (push (cons 'total-work 0) info)
199 (push (cons date (list info)) new)
200 (setq bucket (cdr (assoc date new))))
201 (when (and date (not bucket))
202 (setq bucket (list (list (cons 'date date)
203 (cons 'title long-date)
204 (cons 'total-work 0)
205 (cons 'price 0))))
206 (push (cons date bucket) new)
207 (setq bucket (cdr (assoc date new))))
208 (when (and date bucket)
209 (setcdr (assoc 'total-work (car bucket))
210 (+ work (cdr (assoc 'total-work (car bucket)))))
211 (setcdr (assoc 'price (car bucket))
212 (+ price (cdr (assoc 'price (car bucket)))))
213 (nconc bucket (list info))))))
214 (nreverse new)))
216 (defun org-invoice-info-to-table (info)
217 "Create a single org table row from the given info alist."
218 (let ((title (cdr (assoc 'title info)))
219 (total (cdr (assoc 'total-work info)))
220 (work (cdr (assoc 'work info)))
221 (price (cdr (assoc 'price info)))
222 (with-price (plist-get org-invoice-table-params :price)))
223 (unless total
224 (setq
225 org-invoice-total-time (+ org-invoice-total-time work)
226 org-invoice-total-price (+ org-invoice-total-price price)))
227 (setq total (and total (org-minutes-to-hh:mm-string total)))
228 (setq work (and work (org-minutes-to-hh:mm-string work)))
229 (insert-before-markers
230 (concat "|" title
231 (cond
232 (total (concat "|" total))
233 (work (concat "|" work)))
234 (and with-price price (concat "|" (format "%.2f" price)))
235 "|" "\n"))))
237 (defun org-invoice-list-to-table (ls)
238 "Convert a list of heading info to an org table"
239 (let ((with-price (plist-get org-invoice-table-params :price))
240 (with-summary (plist-get org-invoice-table-params :summary))
241 (with-header (plist-get org-invoice-table-params :headers))
242 (org-invoice-total-time 0)
243 (org-invoice-total-price 0))
244 (insert-before-markers
245 (concat "| Task / Date | Time" (and with-price "| Price") "|\n"))
246 (dolist (info ls)
247 (insert-before-markers "|-\n")
248 (mapc 'org-invoice-info-to-table (if with-header (cdr info) (cdr (cdr info)))))
249 (when with-summary
250 (insert-before-markers
251 (concat "|-\n|Total:|"
252 (org-minutes-to-hh:mm-string org-invoice-total-time)
253 (and with-price (concat "|" (format "%.2f" org-invoice-total-price)))
254 "|\n")))))
256 (defun org-invoice-collect-invoice-data ()
257 "Collect all the invoice data from the current OrgMode tree and
258 return it. Before you call this function, move point to the
259 heading that begins the invoice data, usually using the
260 `org-invoice-goto-tree' function."
261 (let ((org-invoice-current-invoice
262 (list (cons 'point (point)) (cons 'buffer (current-buffer))))
263 (org-invoice-current-item nil))
264 (save-restriction
265 (org-narrow-to-subtree)
266 (org-clock-sum)
267 (run-hook-with-args 'org-invoice-start-hook)
268 (cons org-invoice-current-invoice
269 (org-invoice-collapse-list
270 (org-map-entries 'org-invoice-heading-info t 'tree 'archive))))))
272 (defun org-dblock-write:invoice (params)
273 "Function called by OrgMode to write the invoice dblock. To
274 create an invoice dblock you can use the `org-invoice-report'
275 function.
277 The following parameters can be given to the invoice block (for
278 information about dblock parameters, please see the Org manual):
280 :scope Allows you to override the `org-invoice-default-level'
281 variable. The only supported values right now are ones
282 that look like :tree1, :tree2, etc.
284 :prices Set to nil to turn off the price column.
286 :headers Set to nil to turn off the group headers.
288 :summary Set to nil to turn off the final summary line."
289 (let ((scope (plist-get params :scope))
290 (org-invoice-table-params params)
291 (zone (move-marker (make-marker) (point)))
292 table)
293 (unless scope (setq scope 'default))
294 (unless (plist-member params :price) (plist-put params :price t))
295 (unless (plist-member params :summary) (plist-put params :summary t))
296 (unless (plist-member params :headers) (plist-put params :headers t))
297 (save-excursion
298 (cond
299 ((eq scope 'tree) (org-invoice-goto-tree "tree1"))
300 ((eq scope 'default) (org-invoice-goto-tree))
301 ((symbolp scope) (org-invoice-goto-tree (symbol-name scope))))
302 (setq table (org-invoice-collect-invoice-data))
303 (goto-char zone)
304 (org-invoice-list-to-table (cdr table))
305 (goto-char zone)
306 (org-table-align)
307 (move-marker zone nil))))
309 (defun org-invoice-in-report-p ()
310 "Check to see if point is inside an invoice report."
311 (let ((pos (point)) start)
312 (save-excursion
313 (end-of-line 1)
314 (and (re-search-backward "^#\\+BEGIN:[ \t]+invoice" nil t)
315 (setq start (match-beginning 0))
316 (re-search-forward "^#\\+END:.*" nil t)
317 (>= (match-end 0) pos)
318 start))))
320 (defun org-invoice-report (&optional jump)
321 "Create or update an invoice dblock report. If point is inside
322 an existing invoice report, the report is updated. If point
323 isn't inside an invoice report, a new report is created.
325 When called with a prefix argument, move to the first invoice
326 report after point and update it.
328 For information about various settings for the invoice report,
329 see the `org-dblock-write:invoice' function documentation.
331 An invoice report is created by reading a heading tree and
332 collecting information from various properties. It is assumed
333 that all invoices start at a second level heading, but this can
334 be configured using the `org-invoice-default-level' variable.
336 Here is an example, where all invoices fall under the first-level
337 heading Invoices:
339 * Invoices
340 ** Client Foo (Jan 01 - Jan 15)
341 *** [2008-01-01 Tue] Built New Server for Production
342 *** [2008-01-02 Wed] Meeting with Team to Design New System
343 ** Client Bar (Jan 01 - Jan 15)
344 *** [2008-01-01 Tue] Searched for Widgets on Google
345 *** [2008-01-02 Wed] Billed You for Taking a Nap
347 In this layout, invoices begin at level two, and invoice
348 items (tasks) are at level three. You'll notice that each level
349 three heading starts with an inactive timestamp. The timestamp
350 can actually go anywhere you want, either in the heading, or in
351 the text under the heading. But you must have a timestamp
352 somewhere so that the invoice report can group your items by
353 date.
355 Properties are used to collect various bits of information for
356 the invoice. All properties can be set on the invoice item
357 headings, or anywhere in the tree. The invoice report will scan
358 up the tree looking for each of the properties.
360 Properties used:
362 CLOCKSUM: You can use the Org clock-in and clock-out commands to
363 create a CLOCKSUM property. Also see WORK.
365 WORK: An alternative to the CLOCKSUM property. This property
366 should contain the amount of work that went into this
367 invoice item formatted as HH:MM (e.g. 01:30).
369 RATE: Used to calculate the total price for an invoice item.
370 Should be the price per hour that you charge (e.g. 45.00).
371 It might make more sense to place this property higher in
372 the hierarchy than on the invoice item headings.
374 Using this information, a report is generated that details the
375 items grouped by days. For each day you will be able to see the
376 total number of hours worked, the total price, and the items
377 worked on.
379 You can place the invoice report anywhere in the tree you want.
380 I place mine under a third-level heading like so:
382 * Invoices
383 ** An Invoice Header
384 *** [2008-11-25 Tue] An Invoice Item
385 *** Invoice Report
386 #+BEGIN: invoice
387 #+END:"
388 (interactive "P")
389 (let ((report (org-invoice-in-report-p)))
390 (when (and (not report) jump)
391 (when (re-search-forward "^#\\+BEGIN:[ \t]+invoice" nil t)
392 (org-show-entry)
393 (beginning-of-line)
394 (setq report (point))))
395 (if report (goto-char report)
396 (org-create-dblock (list :name "invoice")))
397 (org-update-dblock)))
399 (provide 'org-invoice)