1 ;;; timeclock.el --- mode for keeping track of how much you work
3 ;; Copyright (C) 1999, 2000 Free Software Foundation, Inc.
5 ;; Author: John Wiegley <johnw@gnu.org>
6 ;; Created: 25 Mar 1999
8 ;; Keywords: calendar data
10 ;; This file is part of GNU Emacs.
12 ;; GNU Emacs is free software; you can redistribute it and/or modify
13 ;; it under the terms of the GNU General Public License as published by
14 ;; the Free Software Foundation; either version 2, or (at your option)
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.
22 ;; You should have received a copy of the GNU General Public License
23 ;; along with GNU Emacs; see the file COPYING. If not, write to the
24 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
25 ;; Boston, MA 02111-1307, USA.
29 ;; This mode is for keeping track of time intervals. You can use it
30 ;; for whatever purpose you like, but the typical scenario is to keep
31 ;; track of how much time you spend working on certain projects.
33 ;; Use `timeclock-in' when you start on a project, and `timeclock-out'
34 ;; when you're done. Once you've collected some data, you can use
35 ;; `timeclock-workday-remaining' to see how much time is left to be
36 ;; worked today (assuming a typical average of 8 hours a day), and
37 ;; `timeclock-when-to-leave' which will calculate when you're free.
39 ;; You'll probably want to bind the timeclock commands to some handy
40 ;; keystrokes. At the moment, C-x t is unused in Emacs 20:
42 ;; (require 'timeclock)
44 ;; (define-key ctl-x-map "ti" 'timeclock-in)
45 ;; (define-key ctl-x-map "to" 'timeclock-out)
46 ;; (define-key ctl-x-map "tc" 'timeclock-change)
47 ;; (define-key ctl-x-map "tr" 'timeclock-reread-log)
48 ;; (define-key ctl-x-map "tu" 'timeclock-update-modeline)
49 ;; (define-key ctl-x-map "tw" 'timeclock-when-to-leave-string)
51 ;; If you want Emacs to display the amount of time "left" to your
52 ;; workday in the modeline, you can either set the value of
53 ;; `timeclock-modeline-display' to t using M-x customize, or you
54 ;; can add this code to your .emacs file:
56 ;; (require 'timeclock)
57 ;; (timeclock-modeline-display)
59 ;; To cancel this modeline display at any time, just call
60 ;; `timeclock-modeline-display' again.
62 ;; You may also want Emacs to ask you before exiting, if you are
63 ;; current working on a project. This can be done either by setting
64 ;; `timeclock-ask-before-exiting' to t using M-x customize (this is
65 ;; the default), or by adding the following to your .emacs file:
67 ;; (add-hook 'kill-emacs-hook 'timeclock-query-out)
69 ;; NOTE: If you change your .timelog file without using timeclock's
70 ;; functions, or if you change the value of any of timeclock's
71 ;; customizable variables, you should run the command
72 ;; `timeclock-reread-log'. This will recompute any discrepancies in
73 ;; your average working time, and will make sure that the various
74 ;; display functions return the correct value.
80 (defgroup timeclock nil
81 "Keeping track time of the time that gets spent."
86 (defcustom timeclock-file
(convert-standard-filename "~/.timelog")
87 "*The file used to store timeclock data in."
91 (defcustom timeclock-workday
(* 8 60 60)
92 "*The length of a work period."
96 (defcustom timeclock-relative t
97 "*When reporting time, make it relative to `timeclock-workday'?
98 For example, if the length of a normal workday is eight hours, and you
99 work four hours on Monday, then the amount of time \"remaining\" on
100 Tuesday is twelve hours -- relative to an averaged work period of
101 eight hours -- or eight hours, non-relative. So relative time takes
102 into account any discrepancy of time under-worked or overworked on
107 (defcustom timeclock-get-project-function
'timeclock-ask-for-project
108 "*The function used to determine the name of the current project.
109 When clocking in, and no project is specified, this function will be
110 called to determine what the current project to be worked on is.
111 If this variable is nil, no questions will be asked."
115 (defcustom timeclock-get-reason-function
'timeclock-ask-for-reason
116 "*A function used to determine the reason for clocking out.
117 When clocking out, and no reason is specified, this function will be
118 called to determine what the reason is.
119 If this variable is nil, no questions will be asked."
123 (defcustom timeclock-get-workday-function nil
124 "*A function used to determine the length of today's workday.
125 The first time that a user clocks in each day, this function will be
126 called to determine what the length of the current workday is. If
127 nil, or equal to `timeclock-workday', nothing special will be done.
128 If it is a quantity different from `timeclock-workday', however, a
129 record will be output to the timelog file to note the fact that that
130 day has a different length from the norm."
131 :type
'(choice (const nil
) (function-item timeclock-workday
) function
)
134 (defcustom timeclock-ask-before-exiting t
135 "*If non-nil, ask if the user wants to clock out before exiting Emacs."
136 :set
(lambda (symbol value
)
138 (add-hook 'kill-emacs-hook
'timeclock-query-out
)
139 (remove-hook 'kill-emacs-hook
'timeclock-query-out
))
140 (setq timeclock-ask-before-exiting value
))
144 (defvar timeclock-update-timer nil
145 "The timer used to update `timeclock-mode-string'.")
147 (defcustom timeclock-use-display-time t
148 "*If non-nil, use `display-time-hook' for doing modeline updates.
149 The advantage to this is that it means one less timer has to be set
150 running amok in Emacs' process space. The disadvantage is that it
151 requires you to have `display-time' running. If you don't want to use
152 `display-time', but still want the modeline to show how much time is
153 left, set this variable to nil. You will need to restart Emacs (or
154 toggle the value of `timeclock-modeline-display') for the change to
156 :set
(lambda (symbol value
)
157 (let ((currently-displaying
158 (and (boundp 'timeclock-modeline-display
)
159 timeclock-modeline-display
)))
160 ;; if we're changing to the state that
161 ;; `timeclock-modeline-display' is already using, don't
162 ;; bother toggling it. This happens on the initial loading
164 (if (and currently-displaying
166 (boundp 'display-time-hook
)
167 (memq 'timeclock-update-modeline
170 timeclock-update-timer
)))
171 (setq currently-displaying nil
))
172 (and currently-displaying
173 (set-variable timeclock-modeline-display nil
))
174 (setq timeclock-use-display-time value
)
175 (and currently-displaying
176 (set-variable timeclock-modeline-display t
))
177 timeclock-use-display-time
))
182 (defcustom timeclock-first-in-hook nil
183 "*A hook run for the first \"in\" event each day.
184 Note that this hook is run before recording any events. Thus the
185 value of `timeclock-hours-today', `timeclock-last-event' and the
186 return value of function `timeclock-last-period' are relative previous
191 (defcustom timeclock-load-hook nil
192 "*Hook that gets run after timeclock has been loaded."
196 (defcustom timeclock-in-hook nil
197 "*A hook run every time an \"in\" event is recorded."
201 (defcustom timeclock-day-over-hook nil
202 "*A hook that is run when the workday has been completed.
203 This hook is only run if the current time remaining is being display
204 in the modeline. See the variable `timeclock-modeline-display'."
208 (defcustom timeclock-out-hook nil
209 "*A hook run every time an \"out\" event is recorded."
213 (defcustom timeclock-done-hook nil
214 "*A hook run every time a project is marked as completed."
218 (defcustom timeclock-event-hook nil
219 "*A hook run every time any event is recorded."
223 (defvar timeclock-last-event nil
224 "A list containing the last event that was recorded.
225 The format of this list is (CODE TIME PROJECT).")
227 (defvar timeclock-last-event-workday nil
228 "The number of seconds in the workday of `timeclock-last-event'.")
230 ;;; Internal Variables:
232 (defvar timeclock-discrepancy nil
233 "A variable containing the time discrepancy before the last event.
234 Normally, timeclock assumes that you intend to work for
235 `timeclock-workday' seconds every day. Any days in which you work
236 more or less than this amount is considered either a positive or
237 negative discrepancy. If you work in such a manner that the
238 discrepancy is always brought back to zero, then you will by
239 definition have worked an average amount equal to `timeclock-workday'
242 (defvar timeclock-elapsed nil
243 "A variable containing the time elapsed for complete periods today.
244 This value is not accurate enough to be useful by itself. Rather,
245 call `timeclock-workday-elapsed', to determine how much time has been
246 worked so far today. Also, if `timeclock-relative' is nil, this value
247 will be the same as `timeclock-discrepancy'.")
249 (defvar timeclock-last-period nil
250 "Integer representing the number of seconds in the last period.
251 Note that you shouldn't access this value, but should use the function
252 `timeclock-last-period' instead.")
254 (defvar timeclock-mode-string nil
255 "The timeclock string (optionally) displayed in the modeline.")
257 (defvar timeclock-day-over nil
258 "The date of the last day when notified \"day over\" for.")
263 (defun timeclock-modeline-display (&optional arg
)
264 "Toggle display of the amount of time left today in the modeline.
265 If `timeclock-use-display-time' is non-nil, the modeline will be
266 updated whenever the time display is updated. Otherwise, the
267 timeclock will use its own sixty second timer to do its updating.
268 With prefix ARG, turn modeline display on if and only if ARG is
269 positive. Returns the new status of timeclock modeline display
270 \(non-nil means on)."
273 (> (prefix-numeric-value arg
) 0)
274 (not timeclock-modeline-display
))))
276 (let ((list-entry (memq 'global-mode-string
278 (unless (memq 'timeclock-mode-string mode-line-format
)
280 (cons 'timeclock-mode-string
282 (unless (memq 'timeclock-update-modeline timeclock-event-hook
)
283 (add-hook 'timeclock-event-hook
'timeclock-update-modeline
))
284 (when timeclock-update-timer
285 (cancel-timer timeclock-update-timer
)
286 (setq timeclock-update-timer nil
))
287 (if (boundp 'display-time-hook
)
288 (remove-hook 'display-time-hook
'timeclock-update-modeline
))
289 (if timeclock-use-display-time
290 (add-hook 'display-time-hook
'timeclock-update-modeline
)
291 (setq timeclock-update-timer
292 (run-at-time nil
60 'timeclock-update-modeline
))))
293 (setq mode-line-format
294 (delq 'timeclock-mode-string mode-line-format
))
295 (remove-hook 'timeclock-event-hook
'timeclock-update-modeline
)
296 (if (boundp 'display-time-hook
)
297 (remove-hook 'display-time-hook
298 'timeclock-update-modeline
))
299 (when timeclock-update-timer
300 (cancel-timer timeclock-update-timer
)
301 (setq timeclock-update-timer nil
)))
302 (force-mode-line-update)
305 ;; This has to be here so that the function definition of
306 ;; `timeclock-modeline-display' is known to the "set" function.
307 (defcustom timeclock-modeline-display nil
308 "Toggle modeline display of time remaining.
309 You must modify via \\[customize] for this variable to have an effect."
310 :set
(lambda (symbol value
)
311 (setq timeclock-modeline-display
312 (timeclock-modeline-display (or value
0))))
318 (defun timeclock-in (&optional arg project find-project
)
319 "Clock in, recording the current time moment in the timelog.
320 With a numeric prefix ARG, record the fact that today has only that
321 many hours in it to be worked. If arg is a non-numeric prefix arg
322 \(non-nil, but not a number), 0 is assumed (working on a holiday or
323 weekend). *If not called interactively, ARG should be the number of
324 _seconds_ worked today*. This feature only has effect the first time
325 this function is called within a day.
327 PROJECT as the project being clocked into. If PROJECT is nil, and
328 FIND-PROJECT is non-nil -- or the user calls `timeclock-in'
329 interactively -- call the function `timeclock-get-project-function' to
330 discover the name of the project."
332 (list (and current-prefix-arg
333 (if (numberp current-prefix-arg
)
334 (* current-prefix-arg
60 60)
336 (if (equal (car timeclock-last-event
) "i")
337 (error "You've already clocked in!")
338 (unless timeclock-last-event
339 (timeclock-reread-log))
340 (unless (equal (timeclock-time-to-date
341 (cadr timeclock-last-event
))
342 (timeclock-time-to-date (current-time)))
343 (let ((workday (or (and (numberp arg
) arg
)
345 (and timeclock-get-workday-function
346 (funcall timeclock-get-workday-function
))
348 (run-hooks 'timeclock-first-in-hook
)
349 ;; settle the discrepancy for the new day
350 (setq timeclock-discrepancy
351 (- timeclock-discrepancy workday
))
352 (if (not (= workday timeclock-workday
))
353 (timeclock-log "h" (and (numberp arg
)
354 (number-to-string arg
))))))
355 (timeclock-log "i" (or project
356 (and timeclock-get-project-function
357 (or find-project
(interactive-p))
358 (funcall timeclock-get-project-function
))))
359 (run-hooks 'timeclock-in-hook
)))
362 (defun timeclock-out (&optional arg reason find-reason
)
363 "Clock out, recording the current time moment in the timelog.
364 If a prefix ARG is given, the user has completed the project that was
365 begun during the last time segment.
367 REASON is the user's reason for clocking out. If REASON is nil, and
368 FIND-REASON is non-nil -- or the user calls `timeclock-out'
369 interactively -- call the function `timeclock-get-reason-function' to
370 discover the reason."
372 (if (equal (downcase (car timeclock-last-event
)) "o")
373 (error "You've already clocked out!")
377 (and timeclock-get-reason-function
378 (or find-reason
(interactive-p))
379 (funcall timeclock-get-reason-function
))))
380 (run-hooks 'timeclock-out-hook
)
382 (run-hooks 'timeclock-done-hook
))))
385 (defun timeclock-status-string (&optional show-seconds today-only
)
386 "Report the overall timeclock status at the present moment."
388 (let* ((remainder (timeclock-workday-remaining))
389 (last-in (equal (car timeclock-last-event
) "i"))
392 (format "Currently %s since %s (%s), %s %s, leave at %s"
393 (if last-in
"IN" "OUT")
395 (format-time-string "%-I:%M:%S %p"
396 (nth 1 timeclock-last-event
))
397 (format-time-string "%-I:%M %p"
398 (nth 1 timeclock-last-event
)))
399 (or (nth 2 timeclock-last-event
)
400 (if last-in
"**UNKNOWN**" "workday over"))
401 (timeclock-seconds-to-string remainder show-seconds t
)
404 (timeclock-when-to-leave-string show-seconds today-only
)))
410 (defun timeclock-change (&optional arg project
)
411 "Change to working on a different project, by clocking in then out.
412 With a prefix ARG, consider the previous project as having been
413 finished at the time of changeover. PROJECT is the name of the last
414 project you were working on."
417 (timeclock-in nil project
(interactive-p)))
420 (defun timeclock-query-out ()
421 "Ask the user before clocking out.
422 This is a useful function for adding to `kill-emacs-hook'."
423 (if (and (equal (car timeclock-last-event
) "i")
424 (y-or-n-p "You're currently clocking time, clock out? "))
428 (defun timeclock-reread-log ()
429 "Re-read the timeclock, to account for external changes.
430 Returns the new value of `timeclock-discrepancy'."
432 (setq timeclock-discrepancy nil
)
433 (timeclock-find-discrep)
434 (if (and timeclock-discrepancy timeclock-modeline-display
)
435 (timeclock-update-modeline))
436 timeclock-discrepancy
)
438 (defun timeclock-seconds-to-string (seconds &optional show-seconds
440 "Convert SECONDS into a compact time string.
441 If SHOW-SECONDS is non-nil, make the resolution of the return string
442 include the second count. If REVERSE-LEADER is non-nil, it means to
443 output a \"+\" if the time value is negative, rather than a \"-\".
444 This is used when negative time values have an inverted meaning (such
445 as with time remaining, where negative time really means overtime)."
447 (format "%s%d:%02d:%02d"
448 (if (< seconds
0) (if reverse-leader
"+" "-") "")
449 (truncate (/ (abs seconds
) 60 60))
450 (%
(truncate (/ (abs seconds
) 60)) 60)
451 (%
(truncate (abs seconds
)) 60))
453 (if (< seconds
0) (if reverse-leader
"+" "-") "")
454 (truncate (/ (abs seconds
) 60 60))
455 (%
(truncate (/ (abs seconds
) 60)) 60))))
457 (defsubst timeclock-workday-remaining
(&optional today-only
)
458 "Return a the number of seconds until the workday is complete.
459 The amount returned is relative to the value of `timeclock-workday'.
460 If TODAY-ONLY is non-nil, the value returned will be relative only to
461 the time worked today, and not to past time. This argument only makes
462 a difference if `timeclock-relative' is non-nil."
463 (let ((discrep (timeclock-find-discrep today-only
)))
464 (or (and discrep
(- discrep
)) 0.0)))
466 (defsubst timeclock-currently-in-p
()
467 "Return non-nil if the user is currently clocked in."
468 (equal (car timeclock-last-event
) "i"))
471 (defun timeclock-workday-remaining-string (&optional show-seconds
473 "Return a string representing the amount of time left today.
474 Display second resolution if SHOW-SECONDS is non-nil. If TODAY-ONLY
475 is non-nil, the display will be relative only to time worked today.
476 See `timeclock-relative' for more information about the meaning of
477 \"relative to today\"."
479 (let ((string (timeclock-seconds-to-string
480 (timeclock-workday-remaining today-only
)
486 (defsubst timeclock-workday-elapsed
(&optional relative
)
487 "Return a the number of seconds worked so far today.
488 If RELATIVE is non-nil, the amount returned will be relative to past
489 time worked. The default is to return only the time that has elapsed
492 (timeclock-find-discrep (not relative
))))
495 (defun timeclock-workday-elapsed-string (&optional show-seconds
497 "Return a string representing the amount of time worked today.
498 Display seconds resolution if SHOW-SECONDS is non-nil. If RELATIVE is
499 non-nil, the amount returned will be relative to past time worked."
501 (let ((string (timeclock-seconds-to-string
502 (timeclock-workday-elapsed relative
)
508 (defsubst timeclock-when-to-leave
(&optional today-only
)
509 "Return a time value representing at when the workday ends today.
510 If TODAY-ONLY is non-nil, the value returned will be relative only to
511 the time worked today, and not to past time. This argument only makes
512 a difference if `timeclock-relative' is non-nil."
513 (timeclock-seconds-to-time
514 (- (timeclock-time-to-seconds (current-time))
515 (timeclock-find-discrep today-only
))))
518 (defun timeclock-when-to-leave-string (&optional show-seconds
520 "Return a string representing at what time the workday ends today.
521 This string is relative to the value of `timeclock-workday'. If
522 NO-MESSAGE is non-nil, no messages will be displayed in the
523 minibuffer. If SHOW-SECONDS is non-nil, the value printed/returned
524 will include seconds. If TODAY-ONLY is non-nil, the value returned
525 will be relative only to the time worked today, and not to past time.
526 This argument only makes a difference if `timeclock-relative' is
529 (let* ((then (timeclock-when-to-leave today-only
))
532 (format-time-string "%-I:%M:%S %p" then
)
533 (format-time-string "%-I:%M %p" then
))))
538 ;;; Internal Functions:
540 (defvar timeclock-project-list nil
)
541 (defvar timeclock-last-project nil
)
543 (defun timeclock-ask-for-project ()
544 "Ask the user for the project they are clocking into."
545 (completing-read (format "Clock into which project (default \"%s\"): "
546 (or timeclock-last-project
547 (car timeclock-project-list
)))
548 (mapcar 'list timeclock-project-list
)
549 nil nil nil nil
(or timeclock-last-project
550 (car timeclock-project-list
))))
552 (defvar timeclock-reason-list nil
)
554 (defun timeclock-ask-for-reason ()
555 "Ask the user for the reason they are clocking out."
556 (completing-read "Reason for clocking out: "
557 (mapcar 'list timeclock-reason-list
)))
559 (defun timeclock-update-modeline ()
560 "Update the `timeclock-mode-string' displayed in the modeline."
562 (let* ((remainder (timeclock-workday-remaining))
563 (last-in (equal (car timeclock-last-event
) "i")))
564 (when (and (< remainder
0)
565 (not (and timeclock-day-over
566 (equal timeclock-day-over
567 (timeclock-time-to-date
569 (setq timeclock-day-over
570 (timeclock-time-to-date (current-time)))
571 (run-hooks 'timeclock-day-over-hook
))
572 (setq timeclock-mode-string
575 (timeclock-seconds-to-string remainder nil t
)
576 (if last-in ?
> ?
])))))
578 (defun timeclock-log (code &optional project
)
579 "Log the event CODE to the timeclock log, at the time of call.
580 If PROJECT is a string, it represents the project which the event is
581 being logged for. Normally only \"in\" events specify a project."
582 (with-current-buffer (find-file-noselect timeclock-file
)
583 (goto-char (point-max))
586 (let ((now (current-time)))
588 (format-time-string "%Y/%m/%d %H:%M:%S" now
)
591 (> (length project
) 0)
592 (concat " " project
))
595 (if (equal (downcase code
) "o")
596 (setq timeclock-last-period
597 (- (timeclock-time-to-seconds now
)
598 (timeclock-time-to-seconds
599 (cadr timeclock-last-event
)))
600 timeclock-discrepancy
601 (+ timeclock-discrepancy
602 timeclock-last-period
)))
603 (setq timeclock-last-event
(list code now project
)))
605 (run-hooks 'timeclock-event-hook
)
606 (kill-buffer (current-buffer))))
608 (defvar timeclock-moment-regexp
609 (concat "\\([bhioO]\\)\\s-+"
610 "\\([0-9]+\\)/\\([0-9]+\\)/\\([0-9]+\\)\\s-+"
611 "\\([0-9]+\\):\\([0-9]+\\):\\([0-9]+\\)[ \t]*" "\\([^\n]*\\)"))
613 (defsubst timeclock-read-moment
()
614 "Read the moment under point from the timelog."
615 (if (looking-at timeclock-moment-regexp
)
616 (let ((code (match-string 1))
617 (year (string-to-number (match-string 2)))
618 (mon (string-to-number (match-string 3)))
619 (mday (string-to-number (match-string 4)))
620 (hour (string-to-number (match-string 5)))
621 (min (string-to-number (match-string 6)))
622 (sec (string-to-number (match-string 7)))
623 (project (match-string 8)))
624 (list code
(encode-time sec min hour mday mon year
) project
))))
626 (defsubst timeclock-time-to-seconds
(time)
627 "Convert TIME to a floating point number."
628 (+ (* (car time
) 65536.0)
630 (/ (or (car (cdr (cdr time
))) 0) 1000000.0)))
632 (defsubst timeclock-seconds-to-time
(seconds)
633 "Convert SECONDS (a floating point number) to an Emacs time structure."
634 (list (floor seconds
65536)
635 (floor (mod seconds
65536))
636 (floor (* (- seconds
(ffloor seconds
)) 1000000))))
638 (defsubst timeclock-time-to-date
(time)
639 "Convert the TIME value to a textual date string."
640 (format-time-string "%Y/%m/%d" time
))
642 (defun timeclock-last-period (&optional moment
)
643 "Return the value of the last event period.
644 If the last event was a clock-in, the period will be open ended, and
645 growing every second. Otherwise, it is a fixed amount which has been
646 recorded to disk. If MOMENT is non-nil, use that as the current time.
647 This is only provided for coherency when used by
648 `timeclock-discrepancy'."
649 (if (equal (car timeclock-last-event
) "i")
650 (- (timeclock-time-to-seconds (or moment
(current-time)))
651 (timeclock-time-to-seconds
652 (cadr timeclock-last-event
)))
653 timeclock-last-period
))
655 (defsubst timeclock-entry-length
(entry)
656 (- (timeclock-time-to-seconds (cadr entry
))
657 (timeclock-time-to-seconds (car entry
))))
659 (defsubst timeclock-entry-begin
(entry)
662 (defsubst timeclock-entry-end
(entry)
665 (defsubst timeclock-entry-project
(entry)
668 (defsubst timeclock-entry-comment
(entry)
672 (defsubst timeclock-entry-list-length
(entry-list)
675 (setq length
(+ length
(timeclock-entry-length (car entry-list
))))
676 (setq entry-list
(cdr entry-list
)))
679 (defsubst timeclock-entry-list-begin
(entry-list)
680 (timeclock-entry-begin (car entry-list
)))
682 (defsubst timeclock-entry-list-end
(entry-list)
683 (timeclock-entry-end (car (last entry-list
))))
685 (defsubst timeclock-entry-list-span
(entry-list)
686 (- (timeclock-time-to-seconds (timeclock-entry-list-end entry-list
))
687 (timeclock-time-to-seconds (timeclock-entry-list-begin entry-list
))))
689 (defsubst timeclock-entry-list-break
(entry-list)
690 (- (timeclock-entry-list-span entry-list
)
691 (timeclock-entry-list-length entry-list
)))
693 (defsubst timeclock-entry-list-projects
(entry-list)
696 (let ((project (timeclock-entry-project (car entry-list
))))
698 (add-to-list 'projects project
)
699 (setq projects
(list project
))))
700 (setq entry-list
(cdr entry-list
)))
704 (defsubst timeclock-day-required
(day)
707 (defsubst timeclock-day-length
(day)
708 (timeclock-entry-list-length (cdr day
)))
710 (defsubst timeclock-day-debt
(day)
711 (- (timeclock-day-required day
)
712 (timeclock-day-length day
)))
714 (defsubst timeclock-day-begin
(day)
715 (timeclock-entry-list-begin (cdr day
)))
717 (defsubst timeclock-day-end
(day)
718 (timeclock-entry-list-end (cdr day
)))
720 (defsubst timeclock-day-span
(day)
721 (timeclock-entry-list-span (cdr day
)))
723 (defsubst timeclock-day-break
(day)
724 (timeclock-entry-list-break (cdr day
)))
726 (defsubst timeclock-day-projects
(day)
727 (timeclock-entry-list-projects (cdr day
)))
729 (defmacro timeclock-day-list-template
(func)
732 (setq length
(+ length
(,(eval func
) (car day-list
))))
733 (setq day-list
(cdr day-list
)))
736 (defun timeclock-day-list-required (day-list)
737 (timeclock-day-list-template 'timeclock-day-required
))
739 (defun timeclock-day-list-length (day-list)
740 (timeclock-day-list-template 'timeclock-day-length
))
742 (defun timeclock-day-list-debt (day-list)
743 (timeclock-day-list-template 'timeclock-day-debt
))
745 (defsubst timeclock-day-list-begin
(day-list)
746 (timeclock-day-begin (car day-list
)))
748 (defsubst timeclock-day-list-end
(day-list)
749 (timeclock-day-end (car (last day-list
))))
751 (defun timeclock-day-list-span (day-list)
752 (timeclock-day-list-template 'timeclock-day-span
))
754 (defun timeclock-day-list-break (day-list)
755 (timeclock-day-list-template 'timeclock-day-break
))
757 (defun timeclock-day-list-projects (day-list)
760 (let ((projs (timeclock-day-projects (car day-list
))))
763 (add-to-list 'projects
(car projs
))
764 (setq projects
(list (car projs
))))
765 (setq projs
(cdr projs
))))
766 (setq day-list
(cdr day-list
)))
770 (defsubst timeclock-current-debt
(&optional log-data
)
771 (nth 0 (or log-data
(timeclock-log-data))))
773 (defsubst timeclock-day-alist
(&optional log-data
)
774 (nth 1 (or log-data
(timeclock-log-data))))
776 (defun timeclock-day-list (&optional log-data
)
777 (let ((alist (timeclock-day-alist log-data
))
780 (setq day-list
(cons (cdar alist
) day-list
)
784 (defsubst timeclock-project-alist
(&optional log-data
)
785 (nth 2 (or log-data
(timeclock-log-data))))
788 (defun timeclock-log-data (&optional recent-only filename
)
789 "Return the contents of the timelog file, in a useful format.
790 A timelog contains data in the form of a single entry per line.
791 Each entry has the form:
793 CODE YYYY/MM/DD HH:MM:SS [COMMENT]
795 CODE is one of: b, h, i, o or O. COMMENT is optional when the code is
796 i, o or O. The meanings of the codes are:
798 b Set the current time balance, or \"time debt\". Useful when
799 archiving old log data, when a debt must be carried forward.
800 The COMMENT here is the number of seconds of debt.
802 h Set the required working time for the given day. This must
803 be the first entry for that day. The COMMENT in this case is
804 the number of hours that must be worked. Floating point
807 i Clock in. The COMMENT in this case should be the name of the
810 o Clock out. COMMENT is unnecessary, but can be used to provide
811 a description of how the period went, for example.
813 O Final clock out. Whatever project was being worked on, it is
814 now finished. Useful for creating summary reports.
816 When this function is called, it will return a data structure with the
819 (DEBT ENTRIES-BY-DAY ENTRIES-BY-PROJECT)
821 DEBT is a floating point number representing the number of seconds
822 \"owed\" before any work was done. For a new file (one without a 'b'
823 entry), this is always zero.
825 The two entries lists have similar formats. They are both alists,
826 where the CAR is the index, and the CDR is a list of time entries.
827 For ENTRIES-BY-DAY, the CAR is a textual date string, of the form
828 YYYY/MM/DD. For ENTRIES-BY-PROJECT, it is the name of the project
829 worked on, or t for the default project.
831 The CDR for ENTRIES-BY-DAY is slightly different than for
832 ENTRIES-BY-PROJECT. It has the following form:
834 (DAY-LENGTH TIME-ENTRIES...)
836 For ENTRIES-BY-PROJECT, there is no DAY-LENGTH member. It is simply a
837 list of TIME-ENTRIES. Note that if DAY-LENGTH is nil, it means
838 whatever is the default should be used.
840 A TIME-ENTRY is a recorded time interval. It has the following format
841 \(although generally one does not have to manipulate these entries
842 directly; see below):
844 (BEGIN-TIME END-TIME PROJECT [COMMENT] [FINAL-P])
846 Anyway, suffice it to say there are a lot of structures. Typically
847 the user is expected to manipulate to the day(s) or project(s) that he
848 or she wants, at which point the following helper functions may be
851 timeclock-day-required
858 timeclock-day-projects
860 timeclock-day-list-required
861 timeclock-day-list-length
862 timeclock-day-list-debt
863 timeclock-day-list-begin
864 timeclock-day-list-end
865 timeclock-day-list-span
866 timeclock-day-list-break
867 timeclock-day-list-projects
869 timeclock-entry-length
870 timeclock-entry-begin
872 timeclock-entry-project
873 timeclock-entry-comment
875 timeclock-entry-list-length
876 timeclock-entry-list-begin
877 timeclock-entry-list-end
878 timeclock-entry-list-span
879 timeclock-entry-list-break
880 timeclock-entry-list-projects
882 A few comments should make the use of the above functions obvious:
884 `required' is the amount of time that must be spent during a day, or
885 sequence of days, in order to have no debt.
887 `length' is the actual amount of time that was spent.
889 `debt' is the difference between required time and length. A
890 negative debt signifies overtime.
892 `begin' is the earliest moment at which work began.
894 `end' is the final moment work was done.
896 `span' is the difference between begin and end.
898 `break' is the difference between span and length.
900 `project' is the project that was worked on, and `projects' is a
901 list of all the projects that were worked on during a given period.
903 `comment', where it applies, could mean anything.
905 There are a few more functions available, for locating day and entry
908 timeclock-day-alist LOG-DATA
909 timeclock-project-alist LOG-DATA
910 timeclock-current-debt LOG-DATA
912 See the documentation for the given function if more info is needed."
913 (let* ((log-data (list 0.0 nil nil
))
915 (todays-date (timeclock-time-to-date now
))
916 last-date-limited last-date-seconds last-date
917 (line 0) last beg day entry event
)
919 (insert-file-contents (or filename timeclock-file
))
921 (goto-char (point-max))
922 (unless (re-search-backward "^b\\s-+" nil t
)
923 (goto-char (point-min))))
924 (while (or (setq event
(timeclock-read-moment))
926 (setq last t event
(list "o" now
))))
927 (setq line
(1+ line
))
928 (cond ((equal (car event
) "b")
929 (setcar log-data
(string-to-number (nth 2 event
))))
930 ((equal (car event
) "h")
931 (setq last-date-limited
(timeclock-time-to-date (cadr event
))
932 last-date-seconds
(* (string-to-number (nth 2 event
))
934 ((equal (car event
) "i")
936 (error "Error in format of timelog file, line %d" line
)
938 (setq entry
(list (cadr event
) nil
939 (and (> (length (nth 2 event
)) 0)
941 (let ((date (timeclock-time-to-date (cadr event
))))
943 (not (equal date last-date
)))
945 (setcar (cdr log-data
)
946 (cons (cons last-date day
)
948 (setq day
(list (and last-date-limited
949 last-date-seconds
))))
951 (setq day
(list (and last-date-limited
952 last-date-seconds
)))))
954 last-date-limited nil
)))
955 ((equal (downcase (car event
)) "o")
957 (error "Error in format of timelog file, line %d" line
)
959 (setcar (cdr entry
) (cadr event
))
960 (let ((desc (and (> (length (nth 2 event
)) 0)
963 (nconc entry
(list (nth 2 event
))))
964 (if (equal (car event
) "O")
965 (nconc entry
(if desc
968 (nconc day
(list entry
))
969 (setq desc
(nth 2 entry
))
970 (let ((proj (assoc desc
(nth 2 log-data
))))
972 (setcar (cddr log-data
)
973 (cons (cons desc
(list entry
))
974 (car (cddr log-data
))))
975 (nconc (cdr proj
) (list entry
)))))))
978 (setcar (cdr log-data
)
979 (cons (cons last-date day
)
983 (defun timeclock-find-discrep (&optional today-only
)
984 "Find overall discrepancy from `timeclock-workday' (in seconds).
985 If TODAY-ONLY is non-nil, the discrepancy will be not be relative, and
986 will correspond only to the amount of time elapsed today. This is
987 identical to what would be return if `timeclock-relative' were nil."
988 ;; This is not implemented in terms of the functions above, because
989 ;; it's a bit wasteful to read all of that data in, just to throw
990 ;; away more than 90% of the information afterwards.
991 (when (file-readable-p timeclock-file
)
992 (let* ((now (current-time))
993 (todays-date (timeclock-time-to-date now
))
995 event beg last-date avg
996 last-date-limited last-date-seconds
)
997 (unless timeclock-discrepancy
998 (setq timeclock-project-list nil
999 timeclock-last-project nil
1000 timeclock-reason-list nil
1001 timeclock-elapsed
0)
1003 (insert-file-contents timeclock-file
)
1004 (goto-char (point-max))
1005 (unless (re-search-backward "^b\\s-+" nil t
)
1006 (goto-char (point-min)))
1007 (while (setq event
(timeclock-read-moment))
1008 (cond ((equal (car event
) "b")
1009 (setq accum
(string-to-number (nth 2 event
))))
1010 ((equal (car event
) "h")
1011 (setq last-date-limited
1012 (timeclock-time-to-date (cadr event
))
1014 (* (string-to-number (nth 2 event
)) 3600.0)))
1015 ((equal (car event
) "i")
1016 (when (and (nth 2 event
)
1017 (> (length (nth 2 event
)) 0))
1018 (add-to-list 'timeclock-project-list
(nth 2 event
))
1019 (setq timeclock-last-project
(nth 2 event
)))
1020 (let ((date (timeclock-time-to-date (cadr event
))))
1021 (if (and timeclock-relative
1023 (not (equal date last-date
))
1027 (if last-date-limited
1029 timeclock-workday
))))
1030 (setq last-date date
1031 last-date-limited nil
)
1033 (error "Error in format of timelog file!")
1034 (setq beg
(timeclock-time-to-seconds (cadr event
))))))
1035 ((equal (downcase (car event
)) "o")
1036 (if (and (nth 2 event
)
1037 (> (length (nth 2 event
)) 0))
1038 (add-to-list 'timeclock-reason-list
(nth 2 event
)))
1039 (if (or timeclock-relative
1040 (equal last-date todays-date
))
1042 (error "Error in format of timelog file!")
1043 (setq timeclock-last-period
1044 (- (timeclock-time-to-seconds (cadr event
))
1046 accum
(+ timeclock-last-period accum
)
1048 (if (equal last-date todays-date
)
1049 (setq timeclock-elapsed
1050 (+ timeclock-last-period timeclock-elapsed
)))))
1051 (setq timeclock-last-event event
1052 timeclock-last-event-workday
1053 (if (equal (timeclock-time-to-date now
)
1058 (setq timeclock-discrepancy accum
)))
1059 (setq accum
(if today-only
1061 timeclock-discrepancy
))
1062 (if timeclock-last-event
1063 (if (equal (car timeclock-last-event
) "i")
1064 (setq accum
(+ accum
(timeclock-last-period now
)))
1065 (if (not (equal (timeclock-time-to-date
1066 (cadr timeclock-last-event
))
1067 (timeclock-time-to-date now
)))
1068 (setq accum
(- accum timeclock-last-event-workday
)))))
1071 (if (and timeclock-last-event
1072 (equal (timeclock-time-to-date
1073 (cadr timeclock-last-event
))
1074 (timeclock-time-to-date now
)))
1075 timeclock-last-event-workday
1076 timeclock-workday
))))))
1078 ;;; A reporting function that uses timeclock-log-data
1080 (defun timeclock-time-less-p (t1 t2
)
1081 "Say whether time T1 is less than time T2."
1082 (or (< (car t1
) (car t2
))
1083 (and (= (car t1
) (car t2
))
1084 (< (nth 1 t1
) (nth 1 t2
)))))
1086 (defun timeclock-day-base (&optional time
)
1087 "Given a time within a day, return 0:0:0 within that day."
1088 (let ((decoded (decode-time (or time
(current-time)))))
1089 (setcar (nthcdr 0 decoded
) 0)
1090 (setcar (nthcdr 1 decoded
) 0)
1091 (setcar (nthcdr 2 decoded
) 0)
1092 (apply 'encode-time decoded
)))
1094 (defun timeclock-geometric-mean (l)
1095 "Compute the geometric mean of the list L."
1099 (setq total
(+ total
(car l
))
1106 (defun timeclock-generate-report (&optional html-p
)
1107 "Generate a summary report based on the current timelog file."
1109 (let ((log (timeclock-log-data))
1110 (today (timeclock-day-base)))
1111 (if html-p
(insert "<p>"))
1112 (insert "Currently ")
1113 (let ((project (nth 2 timeclock-last-event
))
1114 (begin (nth 1 timeclock-last-event
))
1116 (if (timeclock-currently-in-p)
1118 (if (or (null project
) (= (length project
) 0))
1119 (progn (insert "Done Working Today")
1123 (insert " since " (format-time-string "%Y/%m/%d %-I:%M %p" begin
))
1125 (insert "<br>\n<b>")
1127 (if (timeclock-currently-in-p)
1128 (insert "Working on "))
1130 (insert "</b><br>\n")
1131 (insert project
"*\n"))
1132 (let ((proj-data (cdr (assoc project
(timeclock-project-alist log
))))
1133 (two-weeks-ago (timeclock-seconds-to-time
1134 (- (timeclock-time-to-seconds today
)
1136 two-week-len today-len
)
1138 (if (not (timeclock-time-less-p
1139 (timeclock-entry-begin (car proj-data
)) today
))
1140 (setq today-len
(timeclock-entry-list-length proj-data
)
1142 (if (and (null two-week-len
)
1143 (not (timeclock-time-less-p
1144 (timeclock-entry-begin (car proj-data
))
1146 (setq two-week-len
(timeclock-entry-list-length proj-data
)))
1147 (setq proj-data
(cdr proj-data
))))
1148 (if (null two-week-len
)
1149 (setq two-week-len today-len
))
1150 (if html-p
(insert "<p>"))
1151 (insert "\nTime spent on this task today: "
1152 (timeclock-seconds-to-string today-len
)
1153 ". In the last two weeks: "
1154 (timeclock-seconds-to-string two-week-len
))
1155 (if html-p
(insert "<br>"))
1157 (timeclock-seconds-to-string (timeclock-workday-elapsed))
1159 (timeclock-seconds-to-string (timeclock-workday-remaining))
1160 " remaining, done at "
1161 (timeclock-when-to-leave-string) "\n")))
1162 (if html-p
(insert "<p>"))
1163 (insert "\nThere have been "
1165 (length (timeclock-day-alist log
)))
1166 " days of activity, starting "
1167 (caar (last (timeclock-day-alist log
))))
1168 (if html-p
(insert "</p>"))
1172 <td width=\"25\"><br></td><td>
1173 <table border=1 cellpadding=3>
1174 <tr><th><i>Statistics</i></th>
1181 (let* ((day-list (timeclock-day-list))
1182 (thirty-days-ago (timeclock-seconds-to-time
1183 (- (timeclock-time-to-seconds today
)
1185 (three-months-ago (timeclock-seconds-to-time
1186 (- (timeclock-time-to-seconds today
)
1188 (six-months-ago (timeclock-seconds-to-time
1189 (- (timeclock-time-to-seconds today
)
1191 (one-year-ago (timeclock-seconds-to-time
1192 (- (timeclock-time-to-seconds today
)
1194 (time-in (vector (list t
) (list t
) (list t
) (list t
) (list t
)))
1195 (time-out (vector (list t
) (list t
) (list t
) (list t
) (list t
)))
1196 (breaks (vector (list t
) (list t
) (list t
) (list t
) (list t
)))
1197 (workday (vector (list t
) (list t
) (list t
) (list t
) (list t
)))
1198 (lengths (vector '(0 0) thirty-days-ago three-months-ago
1199 six-months-ago one-year-ago
)))
1200 ;; collect statistics from complete timelog
1204 (unless (timeclock-time-less-p
1205 (timeclock-day-begin (car day-list
))
1207 (let ((base (timeclock-time-to-seconds
1209 (timeclock-day-begin (car day-list
))))))
1210 (nconc (aref time-in i
)
1211 (list (- (timeclock-time-to-seconds
1212 (timeclock-day-begin (car day-list
)))
1214 (let ((span (timeclock-day-span (car day-list
)))
1215 (len (timeclock-day-length (car day-list
)))
1216 (req (timeclock-day-required (car day-list
))))
1217 ;; If the day's actual work length is less than
1218 ;; 70% of its span, then likely the exit time
1219 ;; and break amount are not worthwhile adding to
1221 (when (and (> span
0)
1222 (> (/ (float len
) (float span
)) 0.70))
1223 (nconc (aref time-out i
)
1224 (list (- (timeclock-time-to-seconds
1225 (timeclock-day-end (car day-list
)))
1227 (nconc (aref breaks i
) (list (- span len
))))
1229 (setq len
(+ len
(- timeclock-workday req
))))
1230 (nconc (aref workday i
) (list len
)))))
1232 (setq day-list
(cdr day-list
)))
1233 ;; average statistics
1236 (aset time-in i
(timeclock-geometric-mean
1237 (cdr (aref time-in i
))))
1238 (aset time-out i
(timeclock-geometric-mean
1239 (cdr (aref time-out i
))))
1240 (aset breaks i
(timeclock-geometric-mean
1241 (cdr (aref breaks i
))))
1242 (aset workday i
(timeclock-geometric-mean
1243 (cdr (aref workday i
))))
1245 ;; Output the HTML table
1247 (insert "<td align=\"center\">Time in</td>\n")
1250 (insert "<td align=\"right\">"
1251 (timeclock-seconds-to-string (aref time-in i
))
1257 (insert "<td align=\"center\">Time out</td>\n")
1260 (insert "<td align=\"right\">"
1261 (timeclock-seconds-to-string (aref time-out i
))
1267 (insert "<td align=\"center\">Break</td>\n")
1270 (insert "<td align=\"right\">"
1271 (timeclock-seconds-to-string (aref breaks i
))
1277 (insert "<td align=\"center\">Workday</td>\n")
1280 (insert "<td align=\"right\">"
1281 (timeclock-seconds-to-string (aref workday i
))
1286 <td colspan=\"6\" align=\"center\">
1287 <i>These are approximate figures</i></td>
1292 ;;; A helpful little function
1294 (defun timeclock-visit-timelog ()
1295 "Open up the .timelog file in another window."
1297 (find-file-other-window timeclock-file
))
1299 (provide 'timeclock
)
1301 (run-hooks 'timeclock-load-hook
)
1303 ;; make sure we know the list of reasons, projects, and have computed
1304 ;; the last event and current discrepancy.
1305 (if (file-readable-p timeclock-file
)
1306 (timeclock-reread-log))
1308 ;;; timeclock.el ends here