comparison lisp/calendar/timeclock.el @ 89909:68c22ea6027c

Sync to HEAD

89908:ee1402f7b568

;;; timeclock.el --- mode for keeping track of how much you work

;; Copyright (C) 1999, 2000, 2001, 2003 Free Software Foundation, Inc.

;; Author: John Wiegley <[e-mail]>
;; Created: 25 Mar 1999
;; Version: 2.6
;; Keywords: calendar data

;;
;; To cancel this modeline display at any time, just call
;; `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
;; `timeclock-ask-before-exiting' to t using M-x customize (this is
;; the default), or by adding the following to your .emacs file:
;;
;;   (add-hook 'kill-emacs-query-functions 'timeclock-query-out)

  "*The length of a work period."
  :type 'integer
  :group 'timeclock)

(defcustom timeclock-relative t
  "*When reporting time, make it 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
eight hours -- or eight hours, non-relative.  So relative time takes
into account any discrepancy of time under-worked or over-worked on

  :group 'timeclock)

(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.
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.
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
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."
  :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]."
  :set (lambda (symbol value)
	 (if value
	     (add-hook 'kill-emacs-query-functions 'timeclock-query-out)
	   (remove-hook 'kill-emacs-query-functions 'timeclock-query-out))
	 (setq timeclock-ask-before-exiting value))

(defvar display-time-hook)
(defvar timeclock-modeline-display)

(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
`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
effect.  You should call the function `timeclock-modeline-display' with
a positive argument to force an update."

(defvar timeclock-discrepancy nil
  "A variable containing the time discrepancy before the last event.
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
discrepancy is always brought back to zero, then you will by
definition have worked an average amount equal to `timeclock-workday'
each day.")

(defvar timeclock-elapsed nil

worked so far today.  Also, if `timeclock-relative' is nil, this value
will be the same as `timeclock-discrepancy'.") ; ? gm

(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.")

(defvar timeclock-mode-string nil
  "The timeclock string (optionally) displayed in the modeline.
The time is bracketed by <> if you are clocked in, otherwise by [].")

\(non-nil, but not a number), 0 is assumed (working on a holiday or
weekend).  *If not called interactively, ARG should be the number of
_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
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."
  (interactive
   (list (and current-prefix-arg

	(message 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."
  (interactive "P")
  (timeclock-out arg)
  (timeclock-in nil project (interactive-p)))

;;;###autoload
(defun timeclock-query-out ()
  "Ask the user before clocking 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-out))
  ;; Unconditionally return t for `kill-emacs-query-functions'.

	(floor (mod seconds 65536))
	(floor (* (- seconds (ffloor seconds)) 1000000))))

;; 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.
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
   (- (timeclock-time-to-seconds (current-time))
      (let ((discrep (timeclock-find-discrep)))

	  0.0)))))

;;;###autoload
(defun timeclock-when-to-leave-string (&optional show-seconds
						 today-only)
  "Return a string representing at what time the workday ends today.
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
relative only to the time worked today, and not to past time."
  ;; Should today-only be removed in favour of timeclock-relative? - gm

     archiving old log data, when a debt must be carried forward.
     The COMMENT here is the number of seconds of debt.

  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.

  i  Clock in.  The COMMENT in this case should be the name of the
     project worked on.

  o  Clock out.  COMMENT is unnecessary, but can be used to provide

    (setcar (nthcdr 1 decoded) 0)
    (setcar (nthcdr 2 decoded) 0)
    (apply 'encode-time decoded)))

(defun timeclock-geometric-mean (l)
  "Compute the geometric mean of the list L."
  (let ((total 0)
	(count 0))
    (while l
      (setq total (+ total (car l))
	    count (1+ count)

      0)))

(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."
  (interactive)
  (let ((log (timeclock-log-data))
	(today (timeclock-day-base)))
    (if html-p (insert "<p>"))
    (insert "Currently ")

;; make sure we know the list of reasons, projects, and have computed
;; the last event and current discrepancy.
(if (file-readable-p timeclock-file)
    (timeclock-reread-log))

;;; timeclock.el ends here

89909:68c22ea6027c

;;; timeclock.el --- mode for keeping track of how much you work

;; Copyright (C) 1999, 2000, 2001, 2003, 2004 Free Software Foundation, Inc.

;; Author: John Wiegley <[e-mail]>
;; Created: 25 Mar 1999
;; Version: 2.6
;; Keywords: calendar data

;;
;; To cancel this modeline display at any time, just call
;; `timeclock-modeline-display' again.

;; You may also want Emacs to ask you before exiting, if you are
;; 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:
;;
;;   (add-hook 'kill-emacs-query-functions 'timeclock-query-out)

  "*The length of a work period."
  :type 'integer
  :group 'timeclock)

(defcustom timeclock-relative t
  "*Whether to maken 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
eight hours -- or eight hours, non-relative.  So relative time takes
into account any discrepancy of time under-worked or over-worked on

  :group 'timeclock)

(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 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 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 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 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 effect if set with \\[customize]."
  :set (lambda (symbol value)
	 (if value
	     (add-hook 'kill-emacs-query-functions 'timeclock-query-out)
	   (remove-hook 'kill-emacs-query-functions 'timeclock-query-out))
	 (setq timeclock-ask-before-exiting value))

(defvar display-time-hook)
(defvar timeclock-modeline-display)

(defcustom timeclock-use-display-time t
  "*If non-nil, use `display-time-hook' for doing modeline updates.
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
effect.  You should call the function `timeclock-modeline-display' with
a positive argument to force an update."

(defvar timeclock-discrepancy nil
  "A variable containing the time discrepancy before the last event.
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
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.")

(defvar timeclock-elapsed nil

worked so far today.  Also, if `timeclock-relative' is nil, this value
will be the same as `timeclock-discrepancy'.") ; ? gm

(defvar timeclock-last-period nil
  "Integer representing the number of seconds in the last period.
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.
The time is bracketed by <> if you are clocked in, otherwise by [].")

\(non-nil, but not a number), 0 is assumed (working on a holiday or
weekend).  *If not called interactively, ARG should be the number of
_seconds_ worked today*.  This feature only has effect the first time
this function is called within a day.

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."
  (interactive
   (list (and current-prefix-arg

	(message status)
      status)))

;;;###autoload
(defun timeclock-change (&optional arg project)
  "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 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-out))
  ;; Unconditionally return t for `kill-emacs-query-functions'.

	(floor (mod seconds 65536))
	(floor (* (- seconds (ffloor seconds)) 1000000))))

;; Should today-only be removed in favour of timeclock-relative? - gm
(defsubst timeclock-when-to-leave (&optional today-only)
  "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
   (- (timeclock-time-to-seconds (current-time))
      (let ((discrep (timeclock-find-discrep)))

	  0.0)))))

;;;###autoload
(defun timeclock-when-to-leave-string (&optional show-seconds
						 today-only)
  "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
relative only to the time worked today, and not to past time."
  ;; Should today-only be removed in favour of timeclock-relative? - gm

     archiving old log data, when a debt must be carried forward.
     The COMMENT here is the number of seconds of debt.

  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 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.

  o  Clock out.  COMMENT is unnecessary, but can be used to provide

    (setcar (nthcdr 1 decoded) 0)
    (setcar (nthcdr 2 decoded) 0)
    (apply 'encode-time decoded)))

(defun timeclock-geometric-mean (l)
  "Compute the geometric mean of the values in the list L."
  (let ((total 0)
	(count 0))
    (while l
      (setq total (+ total (car l))
	    count (1+ count)

      0)))

(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."
  (interactive)
  (let ((log (timeclock-log-data))
	(today (timeclock-day-base)))
    (if html-p (insert "<p>"))
    (insert "Currently ")

;; make sure we know the list of reasons, projects, and have computed
;; the last event and current discrepancy.
(if (file-readable-p timeclock-file)
    (timeclock-reread-log))

;;; arch-tag: a0be3377-deb6-44ec-b9a2-a7be28436a40
;;; timeclock.el ends here