code.delx.au - gnu-emacs/blob - lisp/time-stamp.el

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