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