lisp/time-stamp.el

   1 ;;; time-stamp.el --- Maintain last change time stamps in files edited by Emacs
   2
   3 ;; Copyright 1989, 1993, 1994, 1995 Free Software Foundation, Inc.
   4
   5 ;; Maintainer's Time-stamp: <95/12/28 19:48:49 gildea>
   6 ;; Maintainer: Stephen Gildea <gildea@lcs.mit.edu>
   7 ;; Keywords: tools
   8
   9 ;; This file is free software; you can redistribute it and/or modify
  10 ;; it under the terms of the GNU General Public License as published by
  11 ;; the Free Software Foundation; either version 2, or (at your option)
  12 ;; any later version.
  13
  14 ;; This file is distributed in the hope that it will be useful,
  15 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17 ;; GNU General Public License for more details.
  18
  19 ;; You should have received a copy of the GNU General Public License
  20 ;; along with GNU Emacs; see the file COPYING.  If not, write to the
  21 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  22 ;; Boston, MA 02111-1307, USA.
  23
  24 ;;; Commentary:
  25
  26 ;; If you put a time stamp template anywhere in the first 8 lines of a file,
  27 ;; it can be updated every time you save the file.  See the top of
  28 ;; time-stamp.el for a sample.  The template looks like one of the following:
  29 ;;     Time-stamp: <>
  30 ;;     Time-stamp: " "
  31 ;; The time stamp is written between the brackets or quotes, resulting in
  32 ;;     Time-stamp: <95/01/18 10:20:51 gildea>
  33 ;; Here is an example that puts the file name and time stamp in the binary:
  34 ;; static char *time_stamp = "sdmain.c Time-stamp: <>";
  35
  36 ;; To activate automatic time stamping in GNU Emacs 19, add this code
  37 ;; to your .emacs file:
  38 ;; (add-hook 'write-file-hooks 'time-stamp)
  39 ;;
  40 ;; In Emacs 18 you will need to do this instead:
  41 ;; (if (not (memq 'time-stamp write-file-hooks))
  42 ;;     (setq write-file-hooks
  43 ;;           (cons 'time-stamp write-file-hooks)))
  44 ;; (autoload 'time-stamp "time-stamp" "Update the time stamp in a buffer." t)
  45
  46 ;; See the documentation for the function `time-stamp' for more details.
  47
  48 ;; Change Log:
  49
  50 ;; Originally based on the 19 Dec 88 version of
  51 ;;   date.el by John Sturdy <mcvax!harlqn.co.uk!jcgs@uunet.uu.net>
  52 ;; version 2, January 1995: replaced functions with %-escapes
  53 ;; $Id: time-stamp.el,v 1.16 1996/01/06 01:03:24 kwzh Exp erik $
  54
  55 ;;; Code:
  56
  57 (defvar time-stamp-active t
  58   "*Non-nil to enable time-stamping of buffers by \\[time-stamp].
  59 Can be toggled by \\[time-stamp-toggle-active].
  60 See also the variable time-stamp-warn-inactive.")
  61
  62 (defvar time-stamp-warn-inactive t
  63   "*Non-nil to have \\[time-stamp] warn if a buffer did not get time-stamped.
  64 A warning is printed if time-stamp-active is nil and the buffer contains
  65 a time stamp template that would otherwise have been updated.")
  66
  67 (defvar time-stamp-format "%02y/%02m/%02d %02H:%02M:%02S %u"
  68   "*Template for the string inserted by \\[time-stamp].
  69 Value may be a string or a list.  (Lists are supported only for
  70 backward compatibility.)  A string is used verbatim except
  71 for character sequences beginning with %:
  72
  73 %a  weekday name: `Monday'.             %A gives uppercase: `MONDAY'
  74 %b  month name: `January'.              %B gives uppercase: `JANUARY'
  75 %d  day of month
  76 %H  24-hour clock hour
  77 %I  12-hour clock hour
  78 %m  month number
  79 %M  minute
  80 %p  `am' or `pm'.                       %P gives uppercase: `AM' or `PM'
  81 %S  seconds
  82 %w  day number of week, Sunday is 0
  83 %y  year: `1995'
  84 %z  time zone name: `est'.              %Z gives uppercase: `EST'
  85
  86 Non-date items:
  87 %%  a literal percent character: `%'
  88 %f  file name without directory         %F gives absolute pathname
  89 %s  system name
  90 %u  user's login name
  91 %h  mail host name
  92
  93 Decimal digits between the % and the type character specify the
  94 field width.  Strings are truncated on the right; numbers on the left.
  95 A leading zero causes numbers to be zero-filled.
  96
  97 For example, to get the format used by the `date' command,
  98 use \"%3a %3b %2d %02H:%02M:%02S %Z %y\"")
  99
 100
 101 ;;; Do not change time-stamp-line-limit, time-stamp-start, or
 102 ;;; time-stamp-end in your .emacs or you will be incompatible
 103 ;;; with other people's files!  If you must change them,
 104 ;;; do so only in the local variables section of the file itself.
 105
 106 (defvar time-stamp-line-limit 8     ;Do not change!
 107   "Lines of a file searched; positive counts from start, negative from end.
 108 The patterns `time-stamp-start' and `time-stamp-end' must be found on one
 109 of the first (last) `time-stamp-line-limit' lines of the file for the
 110 file to be time-stamped by \\[time-stamp].
 111
 112 Do not change `time-stamp-line-limit', `time-stamp-start', or
 113 `time-stamp-end' for yourself or you will be incompatible
 114 with other people's files!  If you must change them for some application,
 115 do so in the local variables section of the time-stamped file itself.")
 116
 117
 118 (defvar time-stamp-start "Time-stamp:[ \t]+\\\\?[\"<]+"    ;Do not change!
 119   "Regexp after which the time stamp is written by \\[time-stamp].
 120 See also the variables `time-stamp-end' and `time-stamp-line-limit'.
 121
 122 Do not change `time-stamp-line-limit', `time-stamp-start', or
 123 `time-stamp-end' for yourself or you will be incompatible
 124 with other people's files!  If you must change them for some application,
 125 do so in the local variables section of the time-stamped file itself.")
 126
 127
 128 (defvar time-stamp-end "\\\\?[\">]"    ;Do not change!
 129   "Regexp marking the text after the time stamp.
 130 \\[time-stamp] deletes the text between the first match of `time-stamp-start'
 131 and the following match of `time-stamp-end' on the same line,
 132 then writes the time stamp specified by `time-stamp-format' between them.
 133
 134 Do not change `time-stamp-line-limit', `time-stamp-start', or
 135 `time-stamp-end' for yourself or you will be incompatible
 136 with other people's files!  If you must change them for some application,
 137 do so in the local variables section of the time-stamped file itself.")
 138
 139
 140 ;;;###autoload
 141 (defun time-stamp ()
 142   "Update the time stamp string in the buffer.
 143 If you put a time stamp template anywhere in the first 8 lines of a file,
 144 it can be updated every time you save the file.  See the top of
 145 `time-stamp.el' for a sample.  The template looks like one of the following:
 146     Time-stamp: <>
 147     Time-stamp: \" \"
 148 The time stamp is written between the brackets or quotes, resulting in
 149     Time-stamp: <95/01/18 10:20:51 gildea>
 150 Only does its thing if the variable  time-stamp-active  is non-nil.
 151 Typically used on  write-file-hooks  for automatic time-stamping.
 152 The format of the time stamp is determined by the variable  time-stamp-format.
 153 The variables time-stamp-line-limit, time-stamp-start, and time-stamp-end
 154 control finding the template."
 155   (interactive)
 156   (let ((case-fold-search nil)
 157         (need-to-warn nil)
 158         start search-end)
 159     (if (and (stringp time-stamp-start)
 160              (stringp time-stamp-end))
 161         (save-excursion
 162           (save-restriction
 163             (widen)
 164             (if (> time-stamp-line-limit 0)
 165                 (progn
 166                   (goto-char (setq start (point-min)))
 167                   (forward-line time-stamp-line-limit)
 168                   (setq search-end (point)))
 169               (goto-char (setq search-end (point-max)))
 170               (forward-line time-stamp-line-limit)
 171               (setq start (point)))
 172             (goto-char start)
 173             (while
 174                 (and (< (point) search-end)
 175                      (re-search-forward time-stamp-start search-end 'move))
 176               (setq start (point))
 177               (end-of-line)
 178               (let ((line-end (point)))
 179                 (goto-char start)
 180                 (if (re-search-forward time-stamp-end line-end 'move)
 181                     (progn
 182                       (if time-stamp-active
 183                           (let ((end (match-beginning 0)))
 184                             (delete-region start end)
 185                             (goto-char start)
 186                             (insert (time-stamp-string))
 187                             (setq end (point))
 188                             ;; remove any tabs used to format time stamp
 189                             (goto-char start)
 190                             (if (search-forward "\t" end t)
 191                                 (untabify start end)))
 192                         (if time-stamp-warn-inactive
 193                             ;; do warning outside save-excursion
 194                             (setq need-to-warn t)))
 195                       (setq search-end (point))))))))
 196       ;; don't signal an error in a write-file-hook
 197       (message "time-stamp-start or time-stamp-end is not a string")
 198       (sit-for 1))
 199     (if need-to-warn
 200         (progn
 201           (message "Warning: time-stamp-active is off; did not time-stamp buffer.")
 202           (sit-for 1))))
 203   ;; be sure to return nil so can be used on write-file-hooks
 204   nil)
 205
 206 ;;;###autoload
 207 (defun time-stamp-toggle-active (&optional arg)
 208   "Toggle time-stamp-active, setting whether \\[time-stamp] updates a buffer.
 209 With arg, turn time stamping on if and only if arg is positive."
 210   (interactive "P")
 211   (setq time-stamp-active
 212         (if (null arg)
 213             (not time-stamp-active)
 214           (> (prefix-numeric-value arg) 0)))
 215     (message "time-stamp is now %s." (if time-stamp-active "active" "off")))
 216
 217
 218 (defun time-stamp-string ()
 219   "Generate the new string to be inserted by \\[time-stamp]."
 220   (if (stringp time-stamp-format)
 221       (time-stamp-strftime time-stamp-format)
 222     (time-stamp-fconcat time-stamp-format " "))) ;version 1 compatibility
 223
 224 (defconst time-stamp-month-numbers
 225   '(("Jan" . 1) ("Feb" . 2) ("Mar" . 3) ("Apr" . 4) ("May" . 5) ("Jun" . 6)
 226     ("Jul" . 7) ("Aug" . 8) ("Sep" . 9) ("Oct" . 10) ("Nov" . 11) ("Dec" . 12))
 227   "Alist of months and their number.")
 228
 229 (defconst time-stamp-month-full-names
 230   ["(zero)" "January" "February" "March" "April" "May" "June"
 231    "July" "August" "September" "October" "November" "December"])
 232
 233 (defconst time-stamp-weekday-numbers
 234   '(("Sun" . 0) ("Mon" . 1) ("Tue" . 2) ("Wed" . 3)
 235     ("Thu" . 4) ("Fri" . 5) ("Sat" . 6))
 236   "Alist of weekdays and their number.")
 237
 238 (defconst time-stamp-weekday-full-names
 239   ["Sunday" "Monday" "Tuesday" "Wednesday" "Thursday" "Friday" "Saturday"])
 240
 241 (defconst time-stamp-am-pm '("am" "pm")
 242   "List of strings used to denote morning and afternoon.")
 243
 244 (defconst time-stamp-no-file "(no file)"
 245   "String to use when the buffer is not associated with a file.")
 246
 247 (defun time-stamp-strftime (format &optional time)
 248   "Uses a FORMAT to format date, time, file, and user information.
 249 Optional second argument TIME will be used instead of the current time.
 250 See the description of the variable `time-stamp-format' for a description
 251 of the format string."
 252   (let ((time-string (cond ((stringp time)
 253                             time)
 254                            (time
 255                             (current-time-string time))
 256                            (t
 257                             (current-time-string))))
 258         (fmt-len (length format))
 259         (ind 0)
 260         cur-char
 261         (prev-char nil)
 262         (result "")
 263         field-index
 264         field-width
 265         field-result
 266         (paren-level 0))
 267     (while (< ind fmt-len)
 268       (setq cur-char (aref format ind))
 269       (setq
 270        result
 271        (concat result
 272       (cond
 273        ((eq cur-char ?%)
 274         (setq field-index (1+ ind))
 275         (while (progn
 276                  (setq ind (1+ ind))
 277                  (setq cur-char (if (< ind fmt-len)
 278                                     (aref format ind)
 279                                   ?\0))
 280                  (and (<= ?0 cur-char) (>= ?9 cur-char))))
 281         (setq field-width (substring format field-index ind))
 282         ;; eat any additional args to allow for future expansion
 283         (while (or (and (<= ?0 cur-char) (>= ?9 cur-char)) (eq ?. cur-char)
 284                    (eq ?, cur-char) (eq ?: cur-char) (eq ?@ cur-char)
 285                    (eq ?- cur-char) (eq ?+ cur-char)
 286                    (eq ?\  cur-char) (eq ?# cur-char)
 287                    (and (eq ?\( cur-char)
 288                         (not (eq prev-char ?\\))
 289                         (setq paren-level (1+ paren-level)))
 290                    (if (and (eq ?\) cur-char)
 291                             (not (eq prev-char ?\\))
 292                             (> paren-level 0))
 293                        (setq paren-level (1- paren-level))
 294                      (and (> paren-level 0)
 295                           (< ind fmt-len))))
 296           (setq ind (1+ ind))
 297           (setq prev-char cur-char)
 298           (setq cur-char (if (< ind fmt-len)
 299                              (aref format ind)
 300                            ?\0)))
 301         (setq field-result
 302         (cond
 303          ((eq cur-char ?%)
 304           "%")
 305          ((or (eq cur-char ?a)          ;weekday name
 306               (eq cur-char ?A))
 307           (let ((name
 308                  (aref time-stamp-weekday-full-names
 309                        (cdr (assoc (substring time-string 0 3)
 310                                    time-stamp-weekday-numbers)))))
 311             (if (eq cur-char ?a)
 312                 name
 313               (upcase name))))
 314          ((or (eq cur-char ?b)          ;month name
 315               (eq cur-char ?B))
 316           (let ((name
 317                  (aref time-stamp-month-full-names
 318                        (cdr (assoc (substring time-string 4 7)
 319                                    time-stamp-month-numbers)))))
 320             (if (eq cur-char ?b)
 321                 name
 322               (upcase name))))
 323          ((eq cur-char ?d)              ;day of month, 1-31
 324           (string-to-int (substring time-string 8 10)))
 325          ((eq cur-char ?H)              ;hour, 0-23
 326           (string-to-int (substring time-string 11 13)))
 327          ((eq cur-char ?I)              ;hour, 1-12
 328           (let ((hour (string-to-int (substring time-string 11 13))))
 329             (cond ((< hour 1)
 330                    (+ hour 12))
 331                   ((> hour 12)
 332                    (- hour 12))
 333                   (t
 334                    hour))))
 335          ((eq cur-char ?m)              ;month number, 1-12
 336           (cdr (assoc (substring time-string 4 7)
 337                       time-stamp-month-numbers)))
 338          ((eq cur-char ?M)              ;minute, 0-59
 339           (string-to-int (substring time-string 14 16)))
 340          ((or (eq cur-char ?p)          ;am or pm
 341               (eq cur-char ?P))
 342           (let ((name
 343                  (if (> 12 (string-to-int (substring time-string 11 13)))
 344                      (car time-stamp-am-pm)
 345                    (car (cdr time-stamp-am-pm)))))
 346             (if (eq cur-char ?p)
 347                 name
 348               (upcase name))))
 349          ((eq cur-char ?S)              ;seconds, 00-60
 350           (string-to-int (substring time-string 17 19)))
 351          ((eq cur-char ?w)              ;weekday number, Sunday is 0
 352           (cdr (assoc (substring time-string 0 3) time-stamp-weekday-numbers)))
 353          ((eq cur-char ?y)              ;year
 354           (string-to-int (substring time-string -4)))
 355          ((or (eq cur-char ?z)          ;time zone
 356               (eq cur-char ?Z))
 357           (let ((name
 358                  (if (fboundp 'current-time-zone)
 359                      (car (cdr (current-time-zone time))))))
 360             (or name (setq name ""))
 361             (if (eq cur-char ?z)
 362                 (downcase name)
 363               (upcase name))))
 364          ((eq cur-char ?f)              ;buffer-file-name, base name only
 365           (if buffer-file-name
 366               (file-name-nondirectory buffer-file-name)
 367             time-stamp-no-file))
 368          ((eq cur-char ?F)              ;buffer-file-name, full path
 369           (or buffer-file-name
 370               time-stamp-no-file))
 371          ((eq cur-char ?s)              ;system name
 372           (system-name))
 373          ((eq cur-char ?u)              ;user name
 374           (user-login-name))
 375          ((eq cur-char ?h)              ;mail host name
 376           (time-stamp-mail-host-name))
 377          ))
 378         (if (string-equal field-width "")
 379             field-result
 380           (let ((padded-result
 381                  (format (format "%%%s%c"
 382                                  field-width
 383                                  (if (numberp field-result) ?d ?s))
 384                          (or field-result ""))))
 385             (let ((initial-length (length padded-result))
 386                   (desired-length (string-to-int field-width)))
 387               (if (> initial-length desired-length)
 388                   ;; truncate strings on right, numbers on left
 389                   (if (stringp field-result)
 390                       (substring padded-result 0 desired-length)
 391                     (substring padded-result (- desired-length)))
 392                 padded-result)))))
 393        (t
 394         (char-to-string cur-char)))))
 395       (setq ind (1+ ind)))
 396     result))
 397
 398 (defun time-stamp-mail-host-name ()
 399   "Return the name of the host where the user receives mail.
 400 This is the value of `mail-host-address' if bound and a string,
 401 otherwise the value of `time-stamp-mail-host' (for versions of Emacs
 402 before 19.29) otherwise the value of the function system-name."
 403   (or (and (boundp 'mail-host-address)
 404            (stringp mail-host-address)
 405            mail-host-address)
 406       (and (boundp 'time-stamp-mail-host) ;for backward compatibility
 407            (stringp time-stamp-mail-host)
 408            time-stamp-mail-host)
 409       (system-name)))
 410
 411 ;;; the rest of this file is for version 1 compatibility
 412
 413 (defun time-stamp-fconcat (list sep)
 414   "Similar to (mapconcat 'funcall LIST SEP) but LIST allows literals.
 415 If an element of LIST is a symbol, it is funcalled to get the string to use;
 416 the separator SEP is used between two strings obtained by funcalling a
 417 symbol.  Otherwise the element itself is inserted; no separator is used
 418 around literals."
 419   (let ((return-string "")
 420         (insert-sep-p nil))
 421     (while list
 422       (cond ((symbolp (car list))
 423              (if insert-sep-p
 424                  (setq return-string (concat return-string sep)))
 425              (setq return-string (concat return-string (funcall (car list))))
 426              (setq insert-sep-p t))
 427             (t
 428              (setq return-string (concat return-string (car list)))
 429              (setq insert-sep-p nil)))
 430       (setq list (cdr list)))
 431     return-string))
 432
 433
 434 ;;; Some useful functions to use in time-stamp-format
 435
 436 ;;; Could generate most of a message-id with
 437 ;;; '(time-stamp-yymmdd "" time-stamp-hhmm "@" time-stamp-mail-host-name)
 438
 439 ;;; pretty form, suitable for a title page
 440
 441 (defun time-stamp-month-dd-yyyy ()
 442   "Return the current date as a string in \"Month DD, YYYY\" form."
 443   (let ((date (current-time-string)))
 444     (format "%s %d, %s"
 445             (aref time-stamp-month-full-names
 446                   (cdr (assoc (substring date 4 7) time-stamp-month-numbers)))
 447             (string-to-int (substring date 8 10))
 448             (substring date -4))))
 449
 450 ;;; same as __DATE__ in ANSI C
 451
 452 (defun time-stamp-mon-dd-yyyy ()
 453   "Return the current date as a string in \"Mon DD YYYY\" form.
 454 The first character of DD is space if the value is less than 10."
 455   (let ((date (current-time-string)))
 456     (format "%s %2d %s"
 457             (substring date 4 7)
 458             (string-to-int (substring date 8 10))
 459             (substring date -4))))
 460
 461 ;;; RFC 822 date
 462
 463 (defun time-stamp-dd-mon-yy ()
 464   "Return the current date as a string in \"DD Mon YY\" form."
 465   (let ((date (current-time-string)))
 466     (format "%02d %s %s"
 467             (string-to-int (substring date 8 10))
 468             (substring date 4 7)
 469             (substring date -2))))
 470
 471 ;;; RCS 3 date
 472
 473 (defun time-stamp-yy/mm/dd ()
 474   "Return the current date as a string in \"YY/MM/DD\" form."
 475   (let ((date (current-time-string)))
 476     (format "%s/%02d/%02d"
 477             (substring date -2)
 478             (cdr (assoc (substring date 4 7) time-stamp-month-numbers))
 479             (string-to-int (substring date 8 10)))))
 480
 481 ;;; RCS 5 date
 482
 483 (defun time-stamp-yyyy/mm/dd ()
 484   "Return the current date as a string in \"YYYY/MM/DD\" form."
 485   (let ((date (current-time-string)))
 486     (format "%s/%02d/%02d"
 487             (substring date -4)
 488             (cdr (assoc (substring date 4 7) time-stamp-month-numbers))
 489             (string-to-int (substring date 8 10)))))
 490
 491 ;;; ISO 8601 date
 492
 493 (defun time-stamp-yyyy-mm-dd ()
 494   "Return the current date as a string in \"YYYY-MM-DD\" form."
 495   (let ((date (current-time-string)))
 496     (format "%s-%02d-%02d"
 497             (substring date -4)
 498             (cdr (assoc (substring date 4 7) time-stamp-month-numbers))
 499             (string-to-int (substring date 8 10)))))
 500
 501 (defun time-stamp-yymmdd ()
 502   "Return the current date as a string in \"YYMMDD\" form."
 503   (let ((date (current-time-string)))
 504     (format "%s%02d%02d"
 505             (substring date -2)
 506             (cdr (assoc (substring date 4 7) time-stamp-month-numbers))
 507             (string-to-int (substring date 8 10)))))
 508
 509 (defun time-stamp-hh:mm:ss ()
 510   "Return the current time as a string in \"HH:MM:SS\" form."
 511   (substring (current-time-string) 11 19))
 512
 513 (defun time-stamp-hhmm ()
 514   "Return the current time as a string in \"HHMM\" form."
 515   (let ((date (current-time-string)))
 516     (concat (substring date 11 13)
 517             (substring date 14 16))))
 518
 519 (provide 'time-stamp)
 520
 521 ;;; time-stamp.el ends here