lisp/mh-e/mh-scan.el

   1 ;;; mh-scan.el --- MH-E scan line constants and utilities
   2
   3 ;; Copyright (C) 1993, 1995, 1997, 2000-2011  Free Software Foundation, Inc.
   4
   5 ;; Author: Bill Wohler <wohler@newt.com>
   6 ;; Maintainer: Bill Wohler <wohler@newt.com>
   7 ;; Keywords: mail
   8 ;; See: mh-e.el
   9
  10 ;; This file is part of GNU Emacs.
  11
  12 ;; GNU Emacs is free software: you can redistribute it and/or modify
  13 ;; it under the terms of the GNU General Public License as published by
  14 ;; the Free Software Foundation, either version 3 of the License, or
  15 ;; (at your option) any later version.
  16
  17 ;; GNU Emacs is distributed in the hope that it will be useful,
  18 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  19 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20 ;; GNU General Public License for more details.
  21
  22 ;; You should have received a copy of the GNU General Public License
  23 ;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
  24
  25 ;;; Commentary:
  26
  27 ;; This file contains constants and a few functions for interpreting
  28 ;; scan lines.
  29
  30 ;;; Change Log:
  31
  32 ;;; Code:
  33
  34 (require 'mh-e)
  35
  36 \f
  37
  38 ;;; Scan Formats
  39
  40 ;; The following scan formats are passed to the scan program if the setting of
  41 ;; `mh-scan-format-file' is t. They are identical except the later one makes
  42 ;; use of the nmh `decode' function to decode RFC 2047 encodings. If you just
  43 ;; want to change the column of the notations, use the `mh-set-cmd-note'
  44 ;; function.
  45
  46 (defvar mh-scan-format-mh
  47   (concat
  48    "%4(msg)"
  49    "%<(cur)+%| %>"
  50    "%<{replied}-"
  51    "%?(nonnull(comp{to}))%<(mymbox{to})t%>"
  52    "%?(nonnull(comp{cc}))%<(mymbox{cc})c%>"
  53    "%?(nonnull(comp{bcc}))%<(mymbox{bcc})b%>"
  54    "%?(nonnull(comp{newsgroups}))n%>"
  55    "%<(zero) %>"
  56    "%02(mon{date})/%02(mday{date})%<{date} %|*%>"
  57    "%<(mymbox{from})%<{to}To:%14(friendly{to})%>%>"
  58    "%<(zero)%17(friendly{from})%>  "
  59    "%{subject}%<{body}<<%{body}%>")
  60   "*Scan format string for MH.
  61 This string is passed to the scan program via the -format
  62 argument.  This format is identical to the default except that
  63 additional hints for fontification have been added to the fifth
  64 column (remember that in Emacs, the first column is 0).
  65
  66 The values of the fifth column, in priority order, are: \"-\" if
  67 the message has been replied to, t if an address on the To: line
  68 matches one of the mailboxes of the current user, \"c\" if the Cc:
  69 line matches, \"b\" if the Bcc: line matches, and \"n\" if a
  70 non-empty Newsgroups: header is present.")
  71
  72 (defvar mh-scan-format-nmh
  73   (concat
  74    "%4(msg)"
  75    "%<(cur)+%| %>"
  76    "%<{replied}-"
  77    "%?(nonnull(comp{to}))%<(mymbox{to})t%>"
  78    "%?(nonnull(comp{cc}))%<(mymbox{cc})c%>"
  79    "%?(nonnull(comp{bcc}))%<(mymbox{bcc})b%>"
  80    "%?(nonnull(comp{newsgroups}))n%>"
  81    "%<(zero) %>"
  82    "%02(mon{date})/%02(mday{date})%<{date} %|*%>"
  83    "%<(mymbox{from})%<{to}To:%14(decode(friendly{to}))%>%>"
  84    "%<(zero)%17(decode(friendly{from}))%>  "
  85    "%(decode{subject})%<{body}<<%{body}%>")
  86   "*Scan format string for nmh.
  87 This string is passed to the scan program via the -format arg.
  88 This format is identical to the default except that additional
  89 hints for fontification have been added to the fifth
  90 column (remember that in Emacs, the first column is 0).
  91
  92 The values of the fifth column, in priority order, are: \"-\" if
  93 the message has been replied to, t if an address on the To: field
  94 matches one of the mailboxes of the current user, \"c\" if the Cc:
  95 field matches, \"b\" if the Bcc: field matches, and \"n\" if a
  96 non-empty Newsgroups: field is present.")
  97
  98 \f
  99
 100 ;;; Regular Expressions
 101
 102 ;; Alphabetical.
 103
 104 (defvar mh-scan-body-regexp "\\(<<\\([^\n]+\\)?\\)"
 105   "This regular expression matches the message body fragment.
 106
 107 Note that the default setting of `mh-folder-font-lock-keywords'
 108 expects this expression to contain at least one parenthesized
 109 expression which matches the body text as in the default of
 110 \"\\\\(<<\\\\([^\\n]+\\\\)?\\\\)\".  If this regular expression is
 111 not correct, the body fragment will not be highlighted with the
 112 face `mh-folder-body'.")
 113
 114 (defvar mh-scan-cur-msg-number-regexp "^\\( *[0-9]+\\+\\).*"
 115   "This regular expression matches the current message.
 116
 117 It must match from the beginning of the line.  Note that the
 118 default setting of `mh-folder-font-lock-keywords' expects this
 119 expression to contain at least one parenthesized expression which
 120 matches the message number as in the default of
 121
 122   \"^\\\\( *[0-9]+\\\\+\\\\).*\".
 123
 124 This expression includes the leading space and current message
 125 marker \"+\" within the parenthesis since it looks better to
 126 highlight these items as well.  The highlighting is done with the
 127 face `mh-folder-cur-msg-number'.  This regular expression should
 128 be correct as it is needed by non-fontification functions.  See
 129 also `mh-note-cur'.")
 130
 131 (defvar mh-scan-date-regexp "\\([0-9][0-9]/[0-9][0-9]\\)"
 132   "This regular expression matches a valid date.
 133
 134 It must not be anchored to the beginning or the end of the line.
 135 Note that the default setting of `mh-folder-font-lock-keywords'
 136 expects this expression to contain only one parenthesized
 137 expression which matches the date field as in the default of
 138 \"\\\\([0-9][0-9]/[0-9][0-9]\\\\)\"}.  If this regular expression
 139 is not correct, the date will not be highlighted with the face
 140 `mh-folder-date'.")
 141
 142 (defvar mh-scan-deleted-msg-regexp "^\\( *[0-9]+\\)D"
 143   "This regular expression matches deleted messages.
 144
 145 It must match from the beginning of the line.  Note that the
 146 default setting of `mh-folder-font-lock-keywords' expects this
 147 expression to contain at least one parenthesized expression which
 148 matches the message number as in the default of
 149
 150   \"^\\\\( *[0-9]+\\\\)D\".
 151
 152 This expression includes the leading space within the parenthesis
 153 since it looks better to highlight it as well.  The highlighting
 154 is done with the face `mh-folder-deleted'.  This regular
 155 expression should be correct as it is needed by non-fontification
 156 functions.  See also `mh-note-deleted'.")
 157
 158 (defvar mh-scan-good-msg-regexp  "^\\( *[0-9]+\\)[^D^0-9]"
 159   "This regular expression matches \"good\" messages.
 160
 161 It must match from the beginning of the line.  Note that the
 162 default setting of `mh-folder-font-lock-keywords' expects this
 163 expression to contain at least one parenthesized expression which
 164 matches the message number as in the default of
 165
 166   \"^\\\\( *[0-9]+\\\\)[^D^0-9]\".
 167
 168 This expression includes the leading space within the parenthesis
 169 since it looks better to highlight it as well.  The highlighting
 170 is done with the face `mh-folder-msg-number'.  This regular
 171 expression should be correct as it is needed by non-fontification
 172 functions.")
 173
 174 (defvar mh-scan-msg-format-regexp "%\\([0-9]*\\)(msg)"
 175   "This regular expression finds the message number width in a scan format.
 176
 177 Note that the message number must be placed in a parenthesized
 178 expression as in the default of \"%\\\\([0-9]*\\\\)(msg)\".  This
 179 variable is only consulted if `mh-scan-format-file' is set to
 180 \"Use MH-E scan Format\".")
 181
 182 (defvar mh-scan-msg-format-string "%d"
 183   "This is a format string for width of the message number in a scan format.
 184
 185 Use \"0%d\" for zero-filled message numbers.  This variable is only
 186 consulted if `mh-scan-format-file' is set to \"Use MH-E scan
 187 Format\".")
 188
 189 (defvar mh-scan-msg-number-regexp "^ *\\([0-9]+\\)"
 190   "This regular expression extracts the message number.
 191
 192 It must match from the beginning of the line.  Note that the
 193 message number must be placed in a parenthesized expression as in
 194 the default of \"^ *\\\\([0-9]+\\\\)\".")
 195
 196 (defvar mh-scan-msg-overflow-regexp "^[?0-9][0-9]"
 197   "This regular expression matches overflowed message numbers.")
 198
 199 (defvar mh-scan-msg-search-regexp "^[^0-9]*%d[^0-9]"
 200   "This regular expression matches a particular message.
 201
 202 It is a format string; use \"%d\" to represent the location of the
 203 message number within the expression as in the default of
 204 \"^[^0-9]*%d[^0-9]\".")
 205
 206 (defvar mh-scan-rcpt-regexp  "\\(To:\\)\\(..............\\)"
 207   "This regular expression specifies the recipient in messages you sent.
 208
 209 Note that the default setting of `mh-folder-font-lock-keywords'
 210 expects this expression to contain two parenthesized expressions.
 211 The first is expected to match the \"To:\" that the default scan
 212 format file generates.  The second is expected to match the
 213 recipient's name as in the default of
 214 \"\\\\(To:\\\\)\\\\(..............\\\\)\".  If this regular
 215 expression is not correct, the \"To:\" string will not be
 216 highlighted with the face `mh-folder-to' and the recipient will
 217 not be highlighted with the face `mh-folder-address'")
 218
 219 (defvar mh-scan-refiled-msg-regexp  "^\\( *[0-9]+\\)\\^"
 220   "This regular expression matches refiled messages.
 221
 222 It must match from the beginning of the line.  Note that the
 223 default setting of `mh-folder-font-lock-keywords' expects this
 224 expression to contain at least one parenthesized expression which
 225 matches the message number as in the default of
 226
 227   \"^\\\\( *[0-9]+\\\\)\\\\^\".
 228
 229 This expression includes the leading space within the parenthesis
 230 since it looks better to highlight it as well.  The highlighting
 231 is done with the face `mh-folder-refiled'.  This regular
 232 expression should be correct as it is needed by non-fontification
 233 functions.  See also `mh-note-refiled'.")
 234
 235 (defvar mh-scan-sent-to-me-sender-regexp
 236   "^ *[0-9]+.\\([bct]\\).....[ ]*\\(..................\\)"
 237   "This regular expression matches messages sent to us.
 238
 239 Note that the default setting of `mh-folder-font-lock-keywords'
 240 expects this expression to contain at least two parenthesized
 241 expressions.  The first should match the fontification hint (see
 242 `mh-scan-format-nmh') and the second should match the user name
 243 as in the default of
 244
 245   ^ *[0-9]+.\\\\([bct]\\\\).....[ ]*\\\\(..................\\\\)
 246
 247 If this regular expression is not correct, the notation hints
 248 will not be highlighted with the face
 249 `mh-mh-folder-sent-to-me-hint' and the sender will not be
 250 highlighted with the face `mh-folder-sent-to-me-sender'.")
 251
 252 (defvar mh-scan-subject-regexp
 253   "^ *[0-9]+........[ ]*...................\\([Rr][Ee]\\(\\[[0-9]+\\]\\)?:\\s-*\\)*\\([^<\n]*\\)"
 254   "This regular expression matches the subject.
 255
 256 It must match from the beginning of the line.  Note that the
 257 default setting of `mh-folder-font-lock-keywords' expects this
 258 expression to contain at least three parenthesized expressions.
 259 The first is expected to match the \"Re:\" string, if any, and is
 260 highlighted with the face `mh-folder-followup'.  The second
 261 matches an optional bracketed number after \"Re:\", such as in
 262 \"Re[2]:\" (and is thus a sub-expression of the first expression)
 263 and the third is expected to match the subject line itself which
 264 is highlighted with the face `mh-folder-subject'.  For example,
 265 the default (broken on multiple lines for readability) is
 266
 267   ^ *[0-9]+........[ ]*...................
 268   \\\\([Rr][Ee]\\\\(\\\\\\=[[0-9]+\\\\]\\\\)?:\\\\s-*\\\\)*
 269   \\\\([^<\\n]*\\\\)
 270
 271 This regular expression should be correct as it is needed by
 272 non-fontification functions.")
 273
 274 (defvar mh-scan-valid-regexp "^ *[0-9]"
 275   "This regular expression describes a valid scan line.
 276
 277 This is used to eliminate error messages that are occasionally
 278 produced by \"inc\".")
 279
 280 \f
 281
 282 ;;; Widths, Offsets and Columns
 283
 284 (defvar mh-cmd-note 4
 285   "Column for notations.
 286
 287 This variable should be set with the function `mh-set-cmd-note'.
 288 This variable may be updated dynamically if
 289 `mh-adaptive-cmd-note-flag' is on.
 290
 291 Note that columns in Emacs start with 0.")
 292 (make-variable-buffer-local 'mh-cmd-note)
 293
 294 (defvar mh-scan-cmd-note-width 1
 295   "Number of columns consumed by the cmd-note field in `mh-scan-format'.
 296
 297 This column will have one of the values: \" \", \"D\", \"^\", \"+\", where
 298
 299   \" \" is the default value,
 300   \"D\" is the `mh-note-deleted' character,
 301   \"^\" is the `mh-note-refiled' character, and
 302   \"+\" is the `mh-note-cur' character.")
 303
 304 (defvar mh-scan-destination-width 1
 305   "Number of columns consumed by the destination field in `mh-scan-format'.
 306
 307 This column will have one of \" \", \"%\", \"-\", \"t\", \"c\", \"b\", or \"n\"
 308 in it.
 309
 310   \" \" blank space is the default character.
 311   \"%\" indicates that the message in in a named MH sequence.
 312   \"-\" indicates that the message has been annotated with a replied field.
 313   \"t\" indicates that the message contains mymbox in the To: field.
 314   \"c\" indicates that the message contains mymbox in the Cc: field.
 315   \"b\" indicates that the message contains mymbox in the Bcc: field.
 316   \"n\" indicates that the message contains a Newsgroups: field.")
 317
 318 (defvar mh-scan-date-width 5
 319   "Number of columns consumed by the date field in `mh-scan-format'.
 320 This column will typically be of the form mm/dd.")
 321
 322 (defvar mh-scan-date-flag-width 1
 323   "Number of columns consumed to flag (in)valid dates in `mh-scan-format'.
 324 This column will have \" \" for valid and \"*\" for invalid or
 325 missing dates.")
 326
 327 (defvar mh-scan-from-mbox-width 17
 328   "Number of columns consumed with the \"From:\" line in `mh-scan-format'.
 329 This column will have a friendly name or e-mail address of the
 330 originator, or a \"To: address\" for outgoing e-mail messages.")
 331
 332 (defvar mh-scan-from-mbox-sep-width 2
 333   "Number of columns consumed by whitespace after from-mbox in `mh-scan-format'.
 334 This column will only ever have spaces in it.")
 335
 336 (defvar mh-scan-field-destination-offset
 337   (+ mh-scan-cmd-note-width)
 338   "The offset from the `mh-cmd-note' for the destination column.")
 339
 340 (defvar mh-scan-field-from-start-offset
 341   (+ mh-scan-cmd-note-width
 342      mh-scan-destination-width
 343      mh-scan-date-width
 344      mh-scan-date-flag-width)
 345   "The offset from the `mh-cmd-note' to find the start of \"From:\" address.")
 346
 347 (defvar mh-scan-field-from-end-offset
 348   (+ mh-scan-field-from-start-offset mh-scan-from-mbox-width)
 349   "The offset from the `mh-cmd-note' to find the end of \"From:\" address.")
 350
 351 (defvar mh-scan-field-subject-start-offset
 352   (+ mh-scan-cmd-note-width
 353      mh-scan-destination-width
 354      mh-scan-date-width
 355      mh-scan-date-flag-width
 356      mh-scan-from-mbox-width
 357      mh-scan-from-mbox-sep-width)
 358   "The offset from the `mh-cmd-note' to find the start of the subject.")
 359
 360 \f
 361
 362 ;;; Notation
 363
 364 ;; Alphabetical.
 365
 366 (defvar mh-note-cur ?+
 367   "The current message (in MH, not in MH-E) is marked by this character.
 368 See also `mh-scan-cur-msg-number-regexp'.")
 369
 370 (defvar mh-note-copied ?C
 371   "Messages that have been copied are marked by this character.")
 372
 373 (defvar mh-note-deleted ?D
 374   "Messages that have been deleted are marked by this character.
 375 See also `mh-scan-deleted-msg-regexp'.")
 376
 377 (defvar mh-note-dist ?R
 378   "Messages that have been redistributed are marked by this character.")
 379
 380 (defvar mh-note-forw ?F
 381   "Messages that have been forwarded are marked by this character.")
 382
 383 (defvar mh-note-printed ?P
 384   "Messages that have been printed are marked by this character.")
 385
 386 (defvar mh-note-refiled ?^
 387   "Messages that have been refiled are marked by this character.
 388 See also `mh-scan-refiled-msg-regexp'.")
 389
 390 (defvar mh-note-repl ?-
 391   "Messages that have been replied to are marked by this character.")
 392
 393 (defvar mh-note-seq ?%
 394   "Messages in a user-defined sequence are marked by this character.
 395
 396 Messages in the \"search\" sequence are marked by this character as
 397 well.")
 398
 399 \f
 400
 401 ;;; Utilities
 402
 403 ;;;###mh-autoload
 404 (defun mh-scan-msg-number-regexp ()
 405   "Return value of variable `mh-scan-msg-number-regexp'."
 406   mh-scan-msg-number-regexp)
 407
 408 ;;;###mh-autoload
 409 (defun mh-scan-msg-search-regexp ()
 410   "Return value of variable `mh-scan-msg-search-regexp'."
 411   mh-scan-msg-search-regexp)
 412
 413 ;;;###mh-autoload
 414 (defun mh-set-cmd-note (column)
 415   "Set `mh-cmd-note' to COLUMN.
 416 Note that columns in Emacs start with 0."
 417   (setq mh-cmd-note column))
 418
 419 ;;;###mh-autoload
 420 (defun mh-scan-format ()
 421   "Return the output format argument for the scan program."
 422   (if (equal mh-scan-format-file t)
 423       (list "-format" (if (mh-variant-p 'nmh 'gnu-mh)
 424                           (list (mh-update-scan-format
 425                                  mh-scan-format-nmh mh-cmd-note))
 426                         (list (mh-update-scan-format
 427                                mh-scan-format-mh mh-cmd-note))))
 428     (if (not (equal mh-scan-format-file nil))
 429         (list "-form" mh-scan-format-file))))
 430
 431 (defun mh-update-scan-format (fmt width)
 432   "Return a scan format with the (msg) width in the FMT replaced with WIDTH.
 433
 434 The message number width portion of the format is discovered
 435 using `mh-scan-msg-format-regexp'.  Its replacement is controlled
 436 with `mh-scan-msg-format-string'."
 437   (or (and
 438        (string-match mh-scan-msg-format-regexp fmt)
 439        (let ((begin (match-beginning 1))
 440              (end (match-end 1)))
 441          (concat (substring fmt 0 begin)
 442                  (format mh-scan-msg-format-string width)
 443                  (substring fmt end))))
 444       fmt))
 445
 446 ;;;###mh-autoload
 447 (defun mh-msg-num-width (folder)
 448   "Return the width of the largest message number in this FOLDER."
 449   (or mh-progs (mh-find-path))
 450   (let ((tmp-buffer (get-buffer-create mh-temp-buffer))
 451         (width 0))
 452     (with-current-buffer tmp-buffer
 453       (erase-buffer)
 454       (apply 'call-process
 455              (expand-file-name mh-scan-prog mh-progs) nil '(t nil) nil
 456              (list folder "last" "-format" "%(msg)"))
 457       (goto-char (point-min))
 458       (if (re-search-forward mh-scan-msg-number-regexp nil 0 1)
 459           (setq width (length (buffer-substring
 460                                (match-beginning 1) (match-end 1))))))
 461     width))
 462
 463 ;;;###mh-autoload
 464 (defun mh-msg-num-width-to-column (width)
 465   "Return the column for notations given message number WIDTH.
 466 Note that columns in Emacs start with 0.
 467
 468 If `mh-scan-format-file' is set to \"Use MH-E scan Format\" this
 469 means that either `mh-scan-format-mh' or `mh-scan-format-nmh' are
 470 in use.  This function therefore assumes that the first column is
 471 empty (to provide room for the cursor), the following WIDTH
 472 columns contain the message number, and the column for notations
 473 comes after that."
 474   (if (eq mh-scan-format-file t)
 475       (max (1+ width) 2)
 476     (error "%s %s" "Can't call `mh-msg-num-width-to-column' when"
 477            "`mh-scan-format-file' is not set to \"Use MH-E scan Format\"")))
 478
 479 (provide 'mh-scan)
 480
 481 ;; Local Variables:
 482 ;; indent-tabs-mode: nil
 483 ;; sentence-end-double-space: nil
 484 ;; End:
 485
 486 ;;; mh-scan.el ends here