[elpa] externals/timerfunctions 85266b3 1/5: * timerfunctions.el: Fix up copyright and conventions

[Stefan Monnier]

branch: externals/timerfunctions
commit 85266b322f01e2987041ed3526b746a146c9960e
Author: Stefan Monnier <monnier@iro.umontreal.ca>
Commit: Stefan Monnier <monnier@iro.umontreal.ca>

    * timerfunctions.el: Fix up copyright and conventions
---
 timerfunctions.el | 204 +++++++++++++++++++++++-------------------------------
 1 file changed, 88 insertions(+), 116 deletions(-)

diff --git a/timerfunctions.el b/timerfunctions.el
index 42e7bfd..b0e29dc 100644
--- a/timerfunctions.el
+++ b/timerfunctions.el
@@ -1,52 +1,42 @@
-;;; timerfunctions.el---enhanced versions of some timer.el functions.
+;;; timerfunctions.el --- Enhanced versions of some timer.el functions
+
+;; Copyright (C) 2000-2002, 2015  Free Software Foundation, Inc.
+
 ;; Time-stamp: <2011-10-04 21:58:10 deego>
-;; Copyright (C) Deepak Goel 2000, 2001, 2002
 ;; Emacs Lisp Archive entry
 ;; Filename: timerfunctions.el
 ;; Author: Deepak Goel <deego@gnufans.org>
 ;; Version: 1.4.2
 ;; Created: 2000/11/20
-
 ;; Author's homepage: http://gnufans.net/~deego
-;; For latest version: 
-
-(defconst timerfunctions-home-page
-  "http://gnufans.net/~deego/emacspub/timerfunctions";)
-
-
-
-(defvar timerfunctions-version "1.4.2")
 
-
-;;;========================================================
-;;;========================================================
-;;; Commentary:   The latest version can always be downloaded from
-;;; http://www.glue.umd.edu/~deego/emacs.html
-
-
- 
 ;; This file is NOT (yet) part of GNU Emacs.
- 
+
 ;; This is free software; you can redistribute it and/or modify
 ;; it under the terms of the GNU General Public License as published by
-;; the Free Software Foundation; either version 2, or (at your option)
+;; the Free Software Foundation; either version 3, or (at your option)
 ;; any later version.
- 
+
 ;; This is distributed in the hope that it will be useful,
 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 ;; GNU General Public License for more details.
 
 ;; 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.
+;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
 
+;; For latest version:
+;; Gives me a "Not found"!
+;;(defconst timerfunctions-home-page
+;;  "http://gnufans.net/~deego/emacspub/timerfunctions";)
 
+;;; Commentary:
 
-;;; See also: midnight.el (part of emacs), timer.el
+;; See also: midnight.el (part of Emacs), timer.el
 
+;;; Code:
 
+(defvar timerfunctions-version "1.4.2")
 
 
 ;;; New features:
@@ -58,22 +48,22 @@ provided a `tf-with-timeout-check'.")
   "Provides electric help from variable `timerfunctions-new-features'."
   (interactive)
   (with-electric-help
-   '(lambda () (insert timerfunctions-new-features) nil) "*doc*"))
+   (lambda () (insert timerfunctions-new-features) nil) "*doc*"))
 
 
 (defconst timerfunctions-introduction
   "timerfunctions.el contains some 'enhanced' versions of a few timer.el
 functions.  It is also used by vel.el, idledo.el etc.
 
- Suppose you want emacs to run an action every REDOSECS for
- _as_long_as emacs remains idle.  `tf-run-with-idle-timer' allows that.
-  
+ Suppose you want Emacs to run an action every REDOSECS for
+ _as_long_as Emacs remains idle.  `tf-run-with-idle-timer' allows that.
+
  `tf-with-timeout' is a generalized with-timeout where you can inhibit
  breaks within parts of the body that you want.
 
- QUICKSTART: 
- Place this file somewhere in yr emacs-load-path, and add the
- foll. to your .emacs: (load \"timerfunctions.el\")
+ QUICKSTART:
+ Place this file somewhere in your load-path, and add the
+ following to your ~/.emacs: (load \"timerfunctions.el\")
 "
 )
 
@@ -84,7 +74,7 @@ functions.  It is also used by vel.el, idledo.el etc.
   (with-electric-help
    '(lambda () (insert timerfunctions-introduction) nil) "*doc*"))
 
-;;; Real Code: 
+;;; Real Code:
 
 
 ;;;###autoload
@@ -97,27 +87,25 @@ Almost like \(- TIMEPLUS TIMESUB \)."
 
 
 ;;;###autoload
-(defun tf-run-with-idle-timer  (secs repeat redosecs redorepeat includeruntime 
function &rest args) 
-  "Args are SECS, REPEAT, REDOSECS, REDOREPEAT, INCLUDERUNTIME,
-FUNCTION and &rest ARGS.
-Similar to run-with-idle-timer, except that provides more options.
-Suppose you want emacs to run an action every REDOSECS for as long as
-emacs remains idle.  Think you can do it with the emacs' 
-run-with-idle-timer? Think again.. :)   That function will perform the
-action exactly once every time emacs goes idle.  This funciton, 
-tf-run-with-idle-timer *will* allow you to keep performing an action
-as long as emacs remains idle.
-
-SECS is the number of seconds to wait once emacs has first gone
+(defun tf-run-with-idle-timer  (secs repeat redosecs redorepeat includeruntime 
function &rest args)
+  "Similar to `run-with-idle-timer', except that provides more options.
+
+Suppose you want Emacs to run an action every REDOSECS for as
+long as Emacs remains idle.  Think you can do it with Emacs's
+`run-with-idle-timer'? Think again.. :)   That function will
+perform the action exactly once every time Emacs goes idle.
+This function *will* allow you to keep performing an action as
+long as Emacs remains idle.
+
+SECS is the number of seconds to wait once Emacs has first gone
 idle. It can really be any expression whose at runtime yields a
-number..  Note that the way run-with-idle-timer is defined, SECS will
+number..  Note that the way `run-with-idle-timer' is defined, SECS will
 unfortunately be evalled immediately after you call this function, but
-redosecs will be *every* time emacs *remains* idle..yay..
-
+redosecs will be *every* time Emacs *remains* idle..yay..
 
-If REDOREPEAT is non-nil, the action is repeated as long emacs remains
+If REDOREPEAT is non-nil, the action is repeated as long Emacs remains
 idle.  REDOSECS is the number of additional seconds (after the action
-has been done) to wait if emacs remains idle before performing the
+has been done) to wait if Emacs remains idle before performing the
 action again.  Again, redosecs does not have to be a number, it can be
 any expression whose eval yields to a number...
 
@@ -125,10 +113,10 @@ If INCLUDERUNTIME is non-nil, REDOSECS is the number of
 additional seconds to wait after the action has been invoked (not
 finished).
 
-If REPEAT is nonnil, the entire cycle is repeated every time emacs
-next goes idle.. (as in the default run-with-idle-timer."
-  (apply 'run-with-idle-timer 
-        (eval secs) repeat 'tf-run-while-idle 
+If REPEAT is nonnil, the entire cycle is repeated every time Emacs
+next goes idle.. (as in the default `run-with-idle-timer')."
+  (apply 'run-with-idle-timer
+        (eval secs) repeat 'tf-run-while-idle
         redosecs redorepeat includeruntime
         function args)
   )
@@ -136,17 +124,15 @@ next goes idle.. (as in the default run-with-idle-timer."
 
 (defun tf-run-while-idle (redosecs redorepeat includeruntime
 function &rest args)
-  "Runs FUNCTION with ARGS and optionally repeats if emacs idle.
+  "Run FUNCTION with ARGS and optionally repeats if Emacs idle.
 Probably is of no use unless used in programs.
  If REDOREPEAT is non-nil, the function is repeated periodically every
-REDOSECS as long as emacs remains idle. By default, emacs waits
-REDOSECS *after* the function is done executing to repeat. If you want
+REDOSECS as long as Emacs remains idle.  By default, Emacs waits
+REDOSECS *after* the function is done executing to repeat.  If you want
 the execution-time to count towards REDOSECS, make INCLUDERUNTIME
 non-nil.
 SECS and REDOSECS can be any expressions that eval at runtime to
-numbers.. In particular, they can simply be numbers..
-
-"
+numbers..  In particular, they can simply be numbers.."
   (if (not includeruntime)
       (progn
        (apply function args)
@@ -157,7 +143,7 @@ numbers.. In particular, they can simply be numbers..
       (let ((before-time (current-time)))
        (apply function args)
        (if redorepeat
-           (while (sit-for (- 
+           (while (sit-for (-
                             (eval redosecs)
                             (tf-time-difference (current-time)
                                                 before-time)))
@@ -168,8 +154,7 @@ numbers.. In particular, they can simply be numbers..
 
 ;;;====================================================
 ;;;TESTS FOLLOW
-(defun tf-test-display-time-internal
-  ()
+(defun tf-test-display-time-internal ()
   (interactive)
   (let ((thisbuffer (buffer-name)))
     (switch-to-buffer-other-window "*scratch*")
@@ -182,7 +167,7 @@ numbers.. In particular, they can simply be numbers..
 
 (defun tf-test-idle-timer ()
   "Run this and watch..Play around with the options.. If you run it,
-you may have to exit your emacs session to restore normal emacs!
+you may have to exit your Emacs session to restore normal Emacs!
 unless you are an expert, that is.."
 
   (interactive)
@@ -191,17 +176,17 @@ unless you are an expert, that is.."
 )
 
 
-  
+
 
 
 (defun tf-test-timeout ()
-  "Bad count should be zero. "
+  "Bad count should be zero."
   (interactive)
   (let ((inhi nil) (goodcount 0) (badcount 0) (ctr 0) (a 1) (b 2)
        (mytag nil)
        (myvar nil)
        )
-    (loop 
+    (loop
      for ctr from 0 to 10 do
      (message "ctr=%S" ctr)
      (tf-with-timeout 'inhi 'mytah 'myvar
@@ -221,8 +206,7 @@ unless you are an expert, that is.."
 
 
 (defun tf-test-timeout-complex ()
-  "Should return a value of 20000 for a. "
-
+  "Should return a value of 20000 for a."
   (interactive)
   (let ((inhi t) (goodcount 0) (badcount 0) (ctr 0) (a 1) (b 2)
        (mytag nil)
@@ -230,14 +214,14 @@ unless you are an expert, that is.."
        )
     (setq a 0)
     (message "ctr=%S" ctr)
-    (tf-with-timeout 
+    (tf-with-timeout
      'inhi 'mytag 'myvar
      (0.1 nil)
      (loop for i from 0 to 10000 do
           (message "first loop. i=%S" ctr i)
           (incf a))
      (message "initial loop ends here.")
-     ;; no throw here because loop prohibited. 
+     ;; no throw here because loop prohibited.
      (tf-with-timeout-check 'inhi 'mytag 'myvar)
      ;; this shouldn't help either
      (sit-for 0.3)
@@ -247,9 +231,9 @@ unless you are an expert, that is.."
           (incf a))
      (message "second loop ends here.")
      (setq inhi nil)
-     ;; this should throw. 
+     ;; this should throw.
      (tf-with-timeout-check 'inhi 'mytag 'myvar)
-     ;; this should NOT be needed. 
+     ;; this should NOT be needed.
      ;;(sit-for 0.2)
      ;; this loop should never take place.
      (loop for i from 0 to 1000 do
@@ -268,60 +252,52 @@ unless you are an expert, that is.."
   (setq tf-internal-var-recenter (- 0 tf-internal-var-recenter)))
 
 (defun tf-example-timer-recenter ()
-  "Changes the screen display every 3 seconds, thus ensuring that you
-  don't time out of ssh sessions."
+  "Change the screen display every 3 seconds, thus ensuring that you
+don't time out of ssh sessions."
   tf-run-with-idle-timer 3 t 3 t nil 'tf-internal-recenter-toggle-my)
 
 
 
 
 (defun tf-wait-until-idle (&optional secs)
-  "DOES NOT WORK YET. Waits until idle. 
+  "DOES NOT WORK YET. Wait until idle.
 Will help run processes in background.  This function will NOT create
-a timer.  Will simply use sit-for.  "
+a timer.  Will simply use `sit-for'."
   (if (null secs)
       (setq secs 1))
   (while (not (sit-for secs))
     (sit-for 1))
-  (message "tf-wait-until-idle DONE WAITING!")
-)
+  (message "tf-wait-until-idle DONE WAITING!"))
 
 
 ;;;Tue Jan 23 17:38:44 2001
+;; FIXME: Use `with-demoted-errors' instead.
 (defmacro tf-ignore-errors (&rest body)
- "Like ignore-errors, but tells the error.."
- (let ((err (gensym)))
-   (list 'condition-case err (cons 'progn body)
-        (list 'error
-              (list 'message
-                    (list 'concat
-                          "IGNORED ERROR: "
-                          (list 'error-message-string err)))))
-   ))
-
-
+  "Like `ignore-errors', but tells the error.."
+  `(condition-case err (progn ,@body)
+     (error (message "IGNORED ERROR: %S"
+                     (error-message-string err)))))
 
 
 (defvar tf-with-timeout-repeat-sec 0.01
   "If the initial timeout fails because of inhibitedness, we shall
 check every this many seconds to see if we are uninhibited.  This
-variable is customizable. ")
+variable is customizable.")
 
 
 (defun tf-with-timeout-handler-internal (tag timedoutvar inhibitp)
   (set timedoutvar t)
   ;;(tf-with-timeout-check tag timedoutvar inhibitp)
   ;; which is equivalent to:
-  (unless (eval inhibitp) 
-    (tf-ignore-errors (throw tag 'timeout)))
-  )
+  (unless (eval inhibitp)
+    (tf-ignore-errors (throw tag 'timeout))))
 
 (defun tf-with-timeout-check (inhibitp tag timedoutvar)
-  ;; check whether timeout has actually reached. 
+  ;; check whether timeout has actually reached.
   ;; we need this step because this function might be called by the
-  ;; user as well. 
+  ;; user as well.
   (when (eval timedoutvar)
-    (unless (eval inhibitp) 
+    (unless (eval inhibitp)
       (tf-ignore-errors (throw tag 'timeout)))))
 
 
@@ -329,7 +305,7 @@ variable is customizable. ")
 (defvar tf-tag-tmpvar nil)
 
 (defmacro tf-catch (tag &rest body)
-  `(let 
+  `(let
        ;; unquote the tag here..
        ((,(cadr tag) 'tf-catch))
      (catch ,tag
@@ -339,21 +315,21 @@ variable is customizable. ")
   `(when (eql (eval ,tag) 'tf-catch)
      (throw ,tag value)))
 
-  
+
 ;;;###autoload
 (defmacro tf-with-timeout (inhibitp timertag timedoutvar tlist &rest body)
   "Like `with-timeout' but provide ability to inhibit timeout during
 parts of the body.  Note that most of the time, you may not need this
 functionality at all unless you want to be very 'clean' about
-things---you could get by with the regular with-timeout and not using
-sit-for's in the body.  Or with the regular with-timeout and using
-unwind-protect.
+things---you could get by with the regular `with-timeout' and not using
+sit-for's in the body.  Or with the regular `with-timeout' and using
+`unwind-protect'.
 
 
 TO DECIDE: IN VIEW OF THE UNWIND-PROTECT, DO WE NEED THIS FUNCTION AT ALL??
 
 Run BODY, but if it doesn't finish in SECONDS seconds, give up.
-If we give up, we run the TIMEOUT-FORMS which are contained in TLIST 
+If we give up, we run the TIMEOUT-FORMS which are contained in TLIST
 and return the value of the last one.
 The call should look like:
  (tf-with-timeout quoted-expr (SECONDS TIMEOUT-FORMS...) BODY...)
@@ -377,9 +353,9 @@ don't have to worry about this in the first place..)
 again, Do not forget my-var to some value before attempting to use this
 tf-with-timeout :)
 
-Here's an example: 
+Here's an example:
+
 
- 
  (let ((myinhibit t))
   (tf-with-timeout 'myinhibit 'mytag 'mytimedoutvar
                   (2 2)
@@ -398,13 +374,13 @@ timeout can takes place only when myinhibit is set to nil,
 which becomes true after about 4 seconds.  Thus, after the execution of the
 body, a has the value 4, but b has the value nil.
 
-See `tf-test-timeout' for another example. 
+See `tf-test-timeout' for another example.
 
 Important Note: If the body of a loop tends to stay in a timeout
 inhibited region for most of the time, then make sure that the timeout
 enabled region atleast spans about 0.02 seconds.. thus, use (sleep-for
 0.02) if needed.. this is because we check every 0.01 seconds if an
-uninhibited timeout condition has been satisfied.  
+uninhibited timeout condition has been satisfied.
 
 But perhaps you do not want to include (sleep-for 0.02) because that
 wastes precious cpu time.  Simple, don't include it, just after a long
@@ -415,12 +391,10 @@ instead of (sleep-for 0.02):
 Moreover, if that is the main check you rely on, you it perhaps makes
 sense to increase the value of tf-with-timeout-repeat-sec, so that
 your cpu cycles are not wasted every 0.01 sec.  See the doc of that
-variable for more. 
+variable for more.
 
 Timertag should be a quoted symbol, also we WILL set that symbol to t
-during the execution of these forms.
-
-"
+during the execution of these forms."
   (let ((seconds (car tlist))
        (timeout-forms (cdr tlist)))
     `(let (
@@ -432,7 +406,7 @@ during the execution of these forms.
               (setq with-timeout-timer
                     (run-with-timer ,seconds tf-with-timeout-repeat-sec
                                     'tf-with-timeout-handler-internal
-                                    ,timertag ,timedoutvar 
+                                    ,timertag ,timedoutvar
                                     ,inhibitp))
               (setq with-timeout-value (progn ,@body))
               nil))
@@ -442,6 +416,4 @@ during the execution of these forms.
 
 
 (provide 'timerfunctions)
-
-;;;timerfunctions.el ends here.
-
+;;; timerfunctions.el ends here