comparison lisp/calendar/timeclock.el @ 51861:91e4e5fd11de

(timeclock-use-display-time, timeclock-day-over-hook) (timeclock-workday-remaining, timeclock-status-string) (timeclock-when-to-leave, timeclock-when-to-leave-string) (timeclock-log-data, timeclock-find-discrep, timeclock-day-base) (timeclock-generate-report, timeclock-visit-timelog): Doc fix. (timeclock-modeline-display): Set the variable `timeclock-modeline-display'. (timeclock-update-modeline): Doc fix. Respect value of `timeclock-relative'.

51860:f9ae39b1c1e6

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.  You will need to restart Emacs (or
toggle the value of `timeclock-modeline-display') for the change to
take effect."
  :set (lambda (symbol value)
	 (let ((currently-displaying
		(and (boundp 'timeclock-modeline-display)
		     timeclock-modeline-display)))

  :type 'hook
  :group 'timeclock)

(defcustom timeclock-day-over-hook nil
  "*A hook that is run when the workday has been completed.
This hook is only run if the current time remaining is being display
in the modeline.  See the variable `timeclock-modeline-display'."
  :type 'hook
  :group 'timeclock)

(defcustom timeclock-out-hook nil

                ;; on calling this function.
                (if display-time-mode (timeclock-update-modeline))
                (add-hook 'display-time-hook 'timeclock-update-modeline))
	    (setq timeclock-update-timer
		  (run-at-time nil 60 'timeclock-update-modeline))))
      (setq global-mode-string 
	    (delq 'timeclock-mode-string global-mode-string))
      (remove-hook 'timeclock-event-hook 'timeclock-update-modeline)
      (if (boundp 'display-time-hook)
	  (remove-hook 'display-time-hook
		       'timeclock-update-modeline))
      (when timeclock-update-timer
	(cancel-timer timeclock-update-timer)
	(setq timeclock-update-timer nil)))
    (force-mode-line-update)
    on-p))

;; This has to be here so that the function definition of
;; `timeclock-modeline-display' is known to the "set" function.
(defcustom timeclock-modeline-display nil
  "Toggle modeline display of time remaining.

	      (funcall timeclock-get-reason-function))))
    (run-hooks 'timeclock-out-hook)
    (if arg
	(run-hooks 'timeclock-done-hook))))

(defsubst timeclock-workday-remaining (&optional today-only)
  "Return the number of seconds until the workday is complete.
The amount returned is relative to the value of `timeclock-workday'.
If TODAY-ONLY is non-nil, the value returned will be relative only to
the time worked today, and not to past time.  This argument only makes
a difference if `timeclock-relative' is non-nil."
  (let ((discrep (timeclock-find-discrep)))
    (if discrep
	(if today-only
	    (- (cadr discrep))
	  (- (car discrep)))
      0.0)))

;;;###autoload
(defun timeclock-status-string (&optional show-seconds today-only)
  "Report the overall timeclock status at the present moment."
  (interactive "P")
  (let ((remainder (timeclock-workday-remaining))
        (last-in (equal (car timeclock-last-event) "i"))
        status)
    (setq status
	  (format "Currently %s since %s (%s), %s %s, leave at %s"
		  (if last-in "IN" "OUT")

  "Convert SECONDS (a floating point number) to an Emacs time structure."
  (list (floor seconds 65536)
	(floor (mod seconds 65536))
	(floor (* (- seconds (ffloor seconds)) 1000000))))

(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.  This argument only makes
a difference if `timeclock-relative' is non-nil."
  (timeclock-seconds-to-time
   (- (timeclock-time-to-seconds (current-time))
      (let ((discrep (timeclock-find-discrep)))
	(if discrep
	    (if today-only

;;;###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
NO-MESSAGE is non-nil, no messages will be displayed in the
minibuffer.  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.
This argument only makes a difference if `timeclock-relative' is
non-nil."
  (interactive)
  (let* ((then (timeclock-when-to-leave today-only))
	 (string
	  (if show-seconds
	      (format-time-string "%-I:%M:%S %p" then)

  "Ask the user for the reason they are clocking out."
  (timeclock-completing-read "Reason for clocking out: "
			     (mapcar 'list timeclock-reason-list)))

(defun timeclock-update-modeline ()
  "Update the `timeclock-mode-string' displayed in the modeline."
  (interactive)
  (let ((remainder (timeclock-workday-remaining))
        (last-in (equal (car timeclock-last-event) "i")))
    (when (and (< remainder 0)
	       (not (and timeclock-day-over
			 (equal timeclock-day-over
				(timeclock-time-to-date

  (nth 2 (or log-data (timeclock-log-data))))


(defun timeclock-log-data (&optional recent-only filename)
  "Return the contents of the timelog file, in a useful format.
A timelog contains data in the form of a single entry per line.
Each entry has the form:

  CODE YYYY/MM/DD HH:MM:SS [COMMENT]

		  (cons (cons last-date day)
			(cadr log-data))))
      log-data)))

(defun timeclock-find-discrep ()
  "Find overall discrepancy from `timeclock-workday' (in seconds)."
  ;; This is not implemented in terms of the functions above, because
  ;; it's a bit wasteful to read all of that data in, just to throw
  ;; away more than 90% of the information afterwards.
  ;;
  ;; If it were implemented using those functions, it would look

  (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."
  (let ((decoded (decode-time (or time (current-time)))))
    (setcar (nthcdr 0 decoded) 0)
    (setcar (nthcdr 1 decoded) 0)
    (setcar (nthcdr 2 decoded) 0)
    (apply 'encode-time decoded)))

    (if (> count 0)
	(/ total count)
      0)))

(defun timeclock-generate-report (&optional html-p)
  "Generate a summary report based on the current timelog file."
  (interactive)
  (let ((log (timeclock-log-data))
	(today (timeclock-day-base)))
    (if html-p (insert "<p>"))
    (insert "Currently ")

</td></table>")))))

;;; A helpful little function

(defun timeclock-visit-timelog ()
  "Open up the .timelog file in another window."
  (interactive)
  (find-file-other-window timeclock-file))

(provide 'timeclock)

51861:91e4e5fd11de

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.  You will need to restart Emacs (or
toggle the function `timeclock-modeline-display') for the change to
take effect."
  :set (lambda (symbol value)
	 (let ((currently-displaying
		(and (boundp 'timeclock-modeline-display)
		     timeclock-modeline-display)))

  :type 'hook
  :group 'timeclock)

(defcustom timeclock-day-over-hook nil
  "*A hook that is run when the workday has been completed.
This hook is only run if the current time remaining is being displayed
in the modeline.  See the variable `timeclock-modeline-display'."
  :type 'hook
  :group 'timeclock)

(defcustom timeclock-out-hook nil

                ;; on calling this function.
                (if display-time-mode (timeclock-update-modeline))
                (add-hook 'display-time-hook 'timeclock-update-modeline))
	    (setq timeclock-update-timer
		  (run-at-time nil 60 'timeclock-update-modeline))))
      (setq global-mode-string
	    (delq 'timeclock-mode-string global-mode-string))
      (remove-hook 'timeclock-event-hook 'timeclock-update-modeline)
      (if (boundp 'display-time-hook)
	  (remove-hook 'display-time-hook
		       'timeclock-update-modeline))
      (when timeclock-update-timer
	(cancel-timer timeclock-update-timer)
	(setq timeclock-update-timer nil)))
    (force-mode-line-update)
    (setq timeclock-modeline-display on-p)))

;; This has to be here so that the function definition of
;; `timeclock-modeline-display' is known to the "set" function.
(defcustom timeclock-modeline-display nil
  "Toggle modeline display of time remaining.

	      (funcall timeclock-get-reason-function))))
    (run-hooks 'timeclock-out-hook)
    (if arg
	(run-hooks 'timeclock-done-hook))))

;; Should today-only be removed in favour of timeclock-relative? - gm
(defsubst timeclock-workday-remaining (&optional today-only)
  "Return the number of seconds until the workday is complete.
The amount returned is relative to the value of `timeclock-workday'.
If TODAY-ONLY is non-nil, the value returned will be relative only to
the time worked today, and not to past time."
  (let ((discrep (timeclock-find-discrep)))
    (if discrep
        (- (if today-only (cadr discrep)
             (car discrep)))
      0.0)))

;;;###autoload
(defun timeclock-status-string (&optional show-seconds today-only)
  "Report the overall timeclock status at the present moment.
If SHOW-SECONDS is non-nil, display second resolution.
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?
        (last-in (equal (car timeclock-last-event) "i"))
        status)
    (setq status
	  (format "Currently %s since %s (%s), %s %s, leave at %s"
		  (if last-in "IN" "OUT")

  "Convert SECONDS (a floating point number) to an Emacs time structure."
  (list (floor seconds 65536)
	(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)))
	(if discrep
	    (if today-only

;;;###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
  (interactive)
  (let* ((then (timeclock-when-to-leave today-only))
	 (string
	  (if show-seconds
	      (format-time-string "%-I:%M:%S %p" then)

  "Ask the user for the reason they are clocking out."
  (timeclock-completing-read "Reason for clocking out: "
			     (mapcar 'list timeclock-reason-list)))

(defun timeclock-update-modeline ()
  "Update the `timeclock-mode-string' displayed in the modeline.
The value of `timeclock-relative' affects the display as described in
that variable's documentation."
  (interactive)
  (let ((remainder (timeclock-workday-remaining (not timeclock-relative)))
        (last-in (equal (car timeclock-last-event) "i")))
    (when (and (< remainder 0)
	       (not (and timeclock-day-over
			 (equal timeclock-day-over
				(timeclock-time-to-date

  (nth 2 (or log-data (timeclock-log-data))))


(defun timeclock-log-data (&optional recent-only filename)
  "Return the contents of the timelog file, in a useful format.
If the optional argument RECENT-ONLY is non-nil, only show the contents
from the last point where the time debt (see below) was set.
If the optional argument FILENAME is non-nil, it is used instead of
the file specified by `timeclock-file.'

A timelog contains data in the form of a single entry per line.
Each entry has the form:

  CODE YYYY/MM/DD HH:MM:SS [COMMENT]

		  (cons (cons last-date day)
			(cadr log-data))))
      log-data)))

(defun timeclock-find-discrep ()
  "Calculate time discrepancies, in seconds.
The result is a three element list, containing the total time
discrepancy, today's discrepancy, and the time worked today."
  ;; This is not implemented in terms of the functions above, because
  ;; it's a bit wasteful to read all of that data in, just to throw
  ;; away more than 90% of the information afterwards.
  ;;
  ;; If it were implemented using those functions, it would look

  (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."
  (let ((decoded (decode-time (or time (current-time)))))
    (setcar (nthcdr 0 decoded) 0)
    (setcar (nthcdr 1 decoded) 0)
    (setcar (nthcdr 2 decoded) 0)
    (apply 'encode-time decoded)))

    (if (> count 0)
	(/ total 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 ")

</td></table>")))))

;;; A helpful little function

(defun timeclock-visit-timelog ()
  "Open the file named by `timeclock-file' in another window."
  (interactive)
  (find-file-other-window timeclock-file))

(provide 'timeclock)