;;; timeclock.el --- mode for keeping track of how much you work
-;; Copyright (C) 1999, 2000, 2001, 2003 Free Software Foundation, Inc.
+;; Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006
+;; Free Software Foundation, Inc.
;; Author: John Wiegley <johnw@gnu.org>
;; Created: 25 Mar 1999
;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs; see the file COPYING. If not, write to the
-;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-;; Boston, MA 02111-1307, USA.
+;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+;; Boston, MA 02110-1301, USA.
;;; Commentary:
;; `timeclock-modeline-display' again.
;; You may also want Emacs to ask you before exiting, if you are
-;; current working on a project. This can be done either by setting
+;; currently working on a project. This can be done either by setting
;; `timeclock-ask-before-exiting' to t using M-x customize (this is
;; the default), or by adding the following to your .emacs file:
;;
;;; Code:
(defgroup timeclock nil
- "Keeping track time of the time that gets spent."
+ "Keeping track of the time that gets spent."
:group 'data)
;;; User Variables:
:group 'timeclock)
(defcustom timeclock-relative t
- "*When reporting time, make it relative to `timeclock-workday'?
+ "*Whether to make reported time relative to `timeclock-workday'.
For example, if the length of a normal workday is eight hours, and you
work four hours on Monday, then the amount of time \"remaining\" on
Tuesday is twelve hours -- relative to an averaged work period of
(defcustom timeclock-get-project-function 'timeclock-ask-for-project
"*The function used to determine the name of the current project.
When clocking in, and no project is specified, this function will be
-called to determine what the current project to be worked on is.
+called to determine what is the current project to be worked on.
If this variable is nil, no questions will be asked."
:type 'function
:group 'timeclock)
(defcustom timeclock-get-reason-function 'timeclock-ask-for-reason
"*A function used to determine the reason for clocking out.
When clocking out, and no reason is specified, this function will be
-called to determine what the reason is.
+called to determine what is the reason.
If this variable is nil, no questions will be asked."
:type 'function
:group 'timeclock)
(defcustom timeclock-get-workday-function nil
"*A function used to determine the length of today's workday.
The first time that a user clocks in each day, this function will be
-called to determine what the length of the current workday is. If
+called to determine what is the length of the current workday. If
the return value is nil, or equal to `timeclock-workday', nothing special
will be done. If it is a quantity different from `timeclock-workday',
however, a record will be output to the timelog file to note the fact that
-that day has a different length from the norm."
+that day has a length that is different from the norm."
:type '(choice (const nil) function)
:group 'timeclock)
(defcustom timeclock-ask-before-exiting t
"*If non-nil, ask if the user wants to clock out before exiting Emacs.
-This variable only has an effect if set with \\[customize]."
+This variable only has effect if set with \\[customize]."
:set (lambda (symbol value)
(if value
(add-hook 'kill-emacs-query-functions 'timeclock-query-out)
(defcustom timeclock-use-display-time t
"*If non-nil, use `display-time-hook' for doing modeline updates.
-The advantage to this is that it means one less timer has to be set
-running amok in Emacs' process space. The disadvantage is that it
-requires you to have `display-time' running. If you don't want to use
+The advantage of this is that one less timer has to be set running
+amok in Emacs' process space. The disadvantage is that it requires
+you to have `display-time' running. If you don't want to use
`display-time', but still want the modeline to show how much time is
left, set this variable to nil. Changing the value of this variable
while timeclock information is being displayed in the modeline has no
Normally, timeclock assumes that you intend to work for
`timeclock-workday' seconds every day. Any days in which you work
more or less than this amount is considered either a positive or
-negative discrepancy. If you work in such a manner that the
+a negative discrepancy. If you work in such a manner that the
discrepancy is always brought back to zero, then you will by
definition have worked an average amount equal to `timeclock-workday'
each day.")
This value is not accurate enough to be useful by itself. Rather,
call `timeclock-workday-elapsed', to determine how much time has been
worked so far today. Also, if `timeclock-relative' is nil, this value
-will be the same as `timeclock-discrepancy'.") ; ? gm
+will be the same as `timeclock-discrepancy'.")
+
+(defvar timeclock-use-elapsed nil
+ "Non-nil if the modeline should display time elapsed, not remaining.")
(defvar timeclock-last-period nil
"Integer representing the number of seconds in the last period.
-Note that you shouldn't access this value, but should use the function
-`timeclock-last-period' instead.")
+Note that you shouldn't access this value, but instead should use the
+function `timeclock-last-period'.")
(defvar timeclock-mode-string nil
"The timeclock string (optionally) displayed in the modeline.
_seconds_ worked today*. This feature only has effect the first time
this function is called within a day.
-PROJECT as the project being clocked into. If PROJECT is nil, and
+PROJECT is the project being clocked into. If PROJECT is nil, and
FIND-PROJECT is non-nil -- or the user calls `timeclock-in'
interactively -- call the function `timeclock-get-project-function' to
discover the name of the project."
If TODAY-ONLY is non-nil, the display will be relative only to time
worked today, ignoring the time worked on previous days."
(interactive "P")
- (let ((remainder (timeclock-workday-remaining)) ; today-only?
+ (let ((remainder (timeclock-workday-remaining
+ (or today-only
+ (not timeclock-relative))))
(last-in (equal (car timeclock-last-event) "i"))
status)
(setq status
"remaining" "over")
(timeclock-when-to-leave-string show-seconds today-only)))
(if (interactive-p)
- (message status)
+ (message "%s" status)
status)))
;;;###autoload
(defun timeclock-change (&optional arg project)
- "Change to working on a different project, by clocking in then out.
-With a prefix ARG, consider the previous project as having been
-finished at the time of changeover. PROJECT is the name of the last
-project you were working on."
+ "Change to working on a different project.
+This clocks out of the current project, then clocks in on a new one.
+With a prefix ARG, consider the previous project as finished at the
+time of changeover. PROJECT is the name of the last project you were
+working on."
(interactive "P")
(timeclock-out arg)
(timeclock-in nil project (interactive-p)))
;;;###autoload
(defun timeclock-query-out ()
- "Ask the user before clocking out.
+ "Ask the user whether to clock out.
This is a useful function for adding to `kill-emacs-query-functions'."
(and (equal (car timeclock-last-event) "i")
(y-or-n-p "You're currently clocking time, clock out? ")
(timeclock-workday-remaining today-only)
show-seconds t)))
(if (interactive-p)
- (message string)
+ (message "%s" string)
string)))
(defsubst timeclock-workday-elapsed ()
(let ((string (timeclock-seconds-to-string (timeclock-workday-elapsed)
show-seconds)))
(if (interactive-p)
- (message string)
+ (message "%s" string)
string)))
(defsubst timeclock-time-to-seconds (time)
;; Should today-only be removed in favour of timeclock-relative? - gm
(defsubst timeclock-when-to-leave (&optional today-only)
- "Return a time value representing at when the workday ends today.
+ "Return a time value representing the end of today's workday.
If TODAY-ONLY is non-nil, the value returned will be relative only to
the time worked today, and not to past time."
(timeclock-seconds-to-time
;;;###autoload
(defun timeclock-when-to-leave-string (&optional show-seconds
today-only)
- "Return a string representing at what time the workday ends today.
+ "Return a string representing the end of today's workday.
This string is relative to the value of `timeclock-workday'. If
SHOW-SECONDS is non-nil, the value printed/returned will include
seconds. If TODAY-ONLY is non-nil, the value returned will be
(format-time-string "%-I:%M:%S %p" then)
(format-time-string "%-I:%M %p" then))))
(if (interactive-p)
- (message string)
+ (message "%s" string)
string)))
;;; Internal Functions:
(defun timeclock-ask-for-project ()
"Ask the user for the project they are clocking into."
(timeclock-completing-read
- (format "Clock into which project (default \"%s\"): "
+ (format "Clock into which project (default %s): "
(or timeclock-last-project
(car timeclock-project-list)))
(mapcar 'list timeclock-project-list)
The value of `timeclock-relative' affects the display as described in
that variable's documentation."
(interactive)
- (let ((remainder (timeclock-workday-remaining (not timeclock-relative)))
+ (let ((remainder
+ (if timeclock-use-elapsed
+ (timeclock-workday-elapsed)
+ (timeclock-workday-remaining (not timeclock-relative))))
(last-in (equal (car timeclock-last-event) "i")))
(when (and (< remainder 0)
(not (and timeclock-day-over
h Set the required working time for the given day. This must
be the first entry for that day. The COMMENT in this case is
- the number of hours that must be worked. Floating point
- amounts are allowed.
+ the number of hours in this workday. Floating point amounts
+ are allowed.
i Clock in. The COMMENT in this case should be the name of the
project worked on.
;;; A reporting function that uses timeclock-log-data
-(defun timeclock-time-less-p (t1 t2)
- "Say whether time T1 is less than time T2."
- (or (< (car t1) (car t2))
- (and (= (car t1) (car t2))
- (< (nth 1 t1) (nth 1 t2)))))
-
(defun timeclock-day-base (&optional time)
"Given a time within a day, return 0:0:0 within that day.
If optional argument TIME is non-nil, use that instead of the current time."
(apply 'encode-time decoded)))
(defun timeclock-geometric-mean (l)
- "Compute the geometric mean of the list L."
+ "Compute the geometric mean of the values in the list L."
(let ((total 0)
(count 0))
(while l
(defun timeclock-generate-report (&optional html-p)
"Generate a summary report based on the current timelog file.
By default, the report is in plain text, but if the optional argument
-HTML-P is non-nil html markup is added."
+HTML-P is non-nil, HTML markup is added."
(interactive)
(let ((log (timeclock-log-data))
(today (timeclock-day-base)))
(* 2 7 24 60 60))))
two-week-len today-len)
(while proj-data
- (if (not (timeclock-time-less-p
+ (if (not (time-less-p
(timeclock-entry-begin (car proj-data)) today))
(setq today-len (timeclock-entry-list-length proj-data)
proj-data nil)
(if (and (null two-week-len)
- (not (timeclock-time-less-p
+ (not (time-less-p
(timeclock-entry-begin (car proj-data))
two-weeks-ago)))
(setq two-week-len (timeclock-entry-list-length proj-data)))
(while day-list
(let ((i 0) (l 5))
(while (< i l)
- (unless (timeclock-time-less-p
+ (unless (time-less-p
(timeclock-day-begin (car day-list))
(aref lengths i))
(let ((base (timeclock-time-to-seconds
(if (file-readable-p timeclock-file)
(timeclock-reread-log))
+;;; arch-tag: a0be3377-deb6-44ec-b9a2-a7be28436a40
;;; timeclock.el ends here