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