lisp/textmodes/paragraphs.el

   1 ;;; paragraphs.el --- paragraph and sentence parsing
   2
   3 ;; Copyright (C) 1985, 86, 87, 91, 94, 95, 96, 1997, 1999, 2000, 2001
   4 ;;    Free Software Foundation, Inc.
   5
   6 ;; Maintainer: FSF
   7 ;; Keywords: wp
   8
   9 ;; This file is part of GNU Emacs.
  10
  11 ;; GNU Emacs is free software; you can redistribute it and/or modify
  12 ;; it under the terms of the GNU General Public License as published by
  13 ;; the Free Software Foundation; either version 2, or (at your option)
  14 ;; any later version.
  15
  16 ;; GNU Emacs is distributed in the hope that it will be useful,
  17 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  18 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19 ;; GNU General Public License for more details.
  20
  21 ;; You should have received a copy of the GNU General Public License
  22 ;; along with GNU Emacs; see the file COPYING.  If not, write to the
  23 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  24 ;; Boston, MA 02111-1307, USA.
  25
  26 ;;; Commentary:
  27
  28 ;; This package provides the paragraph-oriented commands documented in the
  29 ;; Emacs manual.
  30
  31 ;;; Code:
  32
  33 (defgroup paragraphs nil
  34   "Paragraph and sentence parsing."
  35   :group 'editing)
  36
  37 (define-minor-mode use-hard-newlines
  38   "Minor mode to distinguish hard and soft newlines.
  39 When active, the functions `newline' and `open-line' add the
  40 text-property `hard' to newlines that they insert, and a line is
  41 only considered as a candidate to match `paragraph-start' or
  42 `paragraph-separate' if it follows a hard newline.
  43
  44 Prefix argument says to turn mode on if positive, off if negative.
  45 When the mode is turned on, if there are newlines in the buffer but no hard
  46 newlines, ask the user whether to mark as hard any newlines preceeding a
  47 `paragraph-start' line.  From a program, second arg INSERT specifies whether
  48 to do this; it can be `never' to change nothing, t or `always' to force
  49 marking, `guess' to try to do the right thing with no questions, nil
  50 or anything else to ask the user.
  51
  52 Newlines not marked hard are called \"soft\", and are always internal
  53 to paragraphs.  The fill functions insert and delete only soft newlines."
  54   :extra-args (insert)
  55   (when use-hard-newlines
  56     ;; Turn mode on
  57     ;; Intuit hard newlines --
  58     ;;   mark as hard any newlines preceding a paragraph-start line.
  59     (if (or (eq insert t) (eq insert 'always)
  60             (and (not (eq 'never insert))
  61                  (not (text-property-any (point-min) (point-max) 'hard t))
  62                  (save-excursion
  63                    (goto-char (point-min))
  64                    (search-forward "\n" nil t))
  65                  (or (eq insert 'guess)
  66                      (y-or-n-p "Make newlines between paragraphs hard? "))))
  67         (save-excursion
  68           (goto-char (point-min))
  69           (while (search-forward "\n" nil t)
  70             (let ((pos (point)))
  71               (move-to-left-margin)
  72               (when (looking-at paragraph-start)
  73                 (set-hard-newline-properties (1- pos) pos))
  74               ;; If paragraph-separate, newline after it is hard too.
  75               (when (looking-at paragraph-separate)
  76                 (set-hard-newline-properties (1- pos) pos)
  77                 (end-of-line)
  78                 (unless (eobp)
  79                   (set-hard-newline-properties (point) (1+ (point)))))))))))
  80
  81 (defcustom paragraph-start "\f\\|[ \t]*$" "\
  82 *Regexp for beginning of a line that starts OR separates paragraphs.
  83 This regexp should match lines that separate paragraphs
  84 and should also match lines that start a paragraph
  85 \(and are part of that paragraph).
  86
  87 This is matched against the text at the left margin, which is not necessarily
  88 the beginning of the line, so it should never use \"^\" as an anchor.  This
  89 ensures that the paragraph functions will work equally well within a region
  90 of text indented by a margin setting.
  91
  92 The variable `paragraph-separate' specifies how to distinguish
  93 lines that start paragraphs from lines that separate them.
  94
  95 If the variable `use-hard-newlines' is non-nil, then only lines following a
  96 hard newline are considered to match."
  97   :group 'paragraphs
  98   :type 'regexp)
  99
 100 ;; paragraph-start requires a hard newline, but paragraph-separate does not:
 101 ;; It is assumed that paragraph-separate is distinctive enough to be believed
 102 ;; whenever it occurs, while it is reasonable to set paragraph-start to
 103 ;; something very minimal, even including "." (which makes every hard newline
 104 ;; start a new paragraph).
 105
 106 (defcustom paragraph-separate "[ \t\f]*$"
 107   "*Regexp for beginning of a line that separates paragraphs.
 108 If you change this, you may have to change `paragraph-start' also.
 109
 110 This is matched against the text at the left margin, which is not necessarily
 111 the beginning of the line, so it should not use \"^\" as an anchor.  This
 112 ensures that the paragraph functions will work equally within a region of
 113 text indented by a margin setting."
 114   :group 'paragraphs
 115   :type 'regexp)
 116
 117 (defcustom sentence-end-double-space t
 118   "*Non-nil means a single space does not end a sentence.
 119 This is relevant for filling.  See also `sentence-end-without-period'
 120 and `colon-double-space'.
 121
 122 If you change this, you should also change `sentence-end'.  See Info
 123 node `Sentences'."
 124   :type 'boolean
 125   :group 'fill)
 126
 127 (defcustom sentence-end-without-period nil
 128   "*Non-nil means a sentence will end without a period.
 129 For example, a sentence in Thai text ends with double space but
 130 without a period."
 131   :type 'boolean
 132   :group 'fill)
 133
 134 (defcustom sentence-end
 135   (purecopy
 136    ;; This is a bit stupid since it's not auto-updated when the
 137    ;; other variables are changes, but it's still useful info.
 138    (concat (if sentence-end-without-period "\\w  \\|")
 139            "[.?!][]\"')}]*"
 140            (if sentence-end-double-space
 141                "\\($\\| $\\|\t\\|  \\)" "\\($\\|[\t ]\\)")
 142            "[ \t\n]*"))
 143   "*Regexp describing the end of a sentence.
 144 The value includes the whitespace following the sentence.
 145 All paragraph boundaries also end sentences, regardless.
 146
 147 The default value specifies that in order to be recognized as the end
 148 of a sentence, the ending period, question mark, or exclamation point
 149 must be followed by two spaces, unless it's inside some sort of quotes
 150 or parenthesis.
 151
 152 See also the variable `sentence-end-double-space', the variable
 153 `sentence-end-without-period' and Info node `Sentences'."
 154   :group 'paragraphs
 155   :type 'regexp)
 156
 157 (defcustom page-delimiter "^\014"
 158   "*Regexp describing line-beginnings that separate pages."
 159   :group 'paragraphs
 160   :type 'regexp)
 161
 162 (defcustom paragraph-ignore-fill-prefix nil
 163   "*Non-nil means the paragraph commands are not affected by `fill-prefix'.
 164 This is desirable in modes where blank lines are the paragraph delimiters."
 165   :group 'paragraphs
 166   :type 'boolean)
 167
 168 (defun forward-paragraph (&optional arg)
 169   "Move forward to end of paragraph.
 170 With argument ARG, do it ARG times;
 171 a negative argument ARG = -N means move backward N paragraphs.
 172
 173 A line which `paragraph-start' matches either separates paragraphs
 174 \(if `paragraph-separate' matches it also) or is the first line of a paragraph.
 175 A paragraph end is the beginning of a line which is not part of the paragraph
 176 to which the end of the previous line belongs, or the end of the buffer."
 177   (interactive "p")
 178   (or arg (setq arg 1))
 179   (let* ((opoint (point))
 180          (fill-prefix-regexp
 181           (and fill-prefix (not (equal fill-prefix ""))
 182                (not paragraph-ignore-fill-prefix)
 183                (regexp-quote fill-prefix)))
 184          ;; Remove ^ from paragraph-start and paragraph-sep if they are there.
 185          ;; These regexps shouldn't be anchored, because we look for them
 186          ;; starting at the left-margin.  This allows paragraph commands to
 187          ;; work normally with indented text.
 188          ;; This hack will not find problem cases like "whatever\\|^something".
 189          (parstart (if (and (not (equal "" paragraph-start))
 190                             (equal ?^ (aref paragraph-start 0)))
 191                        (substring paragraph-start 1)
 192                      paragraph-start))
 193          (parsep (if (and (not (equal "" paragraph-separate))
 194                           (equal ?^ (aref paragraph-separate 0)))
 195                      (substring paragraph-separate 1)
 196                    paragraph-separate))
 197          (parsep
 198           (if fill-prefix-regexp
 199               (concat parsep "\\|"
 200                       fill-prefix-regexp "[ \t]*$")
 201             parsep))
 202          ;; This is used for searching.
 203          (sp-parstart (concat "^[ \t]*\\(?:" parstart "\\|" parsep "\\)"))
 204          start found-start)
 205     (while (and (< arg 0) (not (bobp)))
 206       (if (and (not (looking-at parsep))
 207                (re-search-backward "^\n" (max (1- (point)) (point-min)) t)
 208                (looking-at parsep))
 209           nil
 210         (setq start (point))
 211         ;; Move back over paragraph-separating lines.
 212         (forward-char -1) (beginning-of-line)
 213         (while (and (not (bobp))
 214                     (progn (move-to-left-margin)
 215                            (looking-at parsep)))
 216           (forward-line -1))
 217         (if (bobp)
 218             nil
 219           ;; Go to end of the previous (non-separating) line.
 220           (end-of-line)
 221           ;; Search back for line that starts or separates paragraphs.
 222           (if (if fill-prefix-regexp
 223                   ;; There is a fill prefix; it overrides parstart.
 224                   (let (multiple-lines)
 225                     (while (and (progn (beginning-of-line) (not (bobp)))
 226                                 (progn (move-to-left-margin)
 227                                        (not (looking-at parsep)))
 228                                 (looking-at fill-prefix-regexp))
 229                       (unless (= (point) start)
 230                         (setq multiple-lines t))
 231                       (forward-line -1))
 232                     (move-to-left-margin)
 233                     ;; This deleted code caused a long hanging-indent line
 234                     ;; not to be filled together with the following lines.
 235                     ;; ;; Don't move back over a line before the paragraph
 236                     ;; ;; which doesn't start with fill-prefix
 237                     ;; ;; unless that is the only line we've moved over.
 238                     ;; (and (not (looking-at fill-prefix-regexp))
 239                     ;;      multiple-lines
 240                     ;;      (forward-line 1))
 241                     (not (bobp)))
 242                 (while (and (re-search-backward sp-parstart nil 1)
 243                             (setq found-start t)
 244                             ;; Found a candidate, but need to check if it is a
 245                             ;; REAL parstart.
 246                             (progn (setq start (point))
 247                                    (move-to-left-margin)
 248                                    (not (looking-at parsep)))
 249                             (not (and (looking-at parstart)
 250                                       (or (not use-hard-newlines)
 251                                           (get-text-property (1- start) 'hard)
 252                                           (bobp)))))
 253                   (setq found-start nil)
 254                   (goto-char start))
 255                 found-start)
 256             ;; Found one.
 257             (progn
 258                 ;; Move forward over paragraph separators.
 259                 ;; We know this cannot reach the place we started
 260                 ;; because we know we moved back over a non-separator.
 261                 (while (and (not (eobp))
 262                             (progn (move-to-left-margin)
 263                                    (looking-at parsep)))
 264                   (forward-line 1))
 265                 ;; If line before paragraph is just margin, back up to there.
 266                 (end-of-line 0)
 267                 (if (> (current-column) (current-left-margin))
 268                     (forward-char 1)
 269                   (skip-chars-backward " \t")
 270                   (if (not (bolp))
 271                       (forward-line 1))))
 272             ;; No starter or separator line => use buffer beg.
 273             (goto-char (point-min)))))
 274       (setq arg (1+ arg)))
 275
 276     (while (and (> arg 0) (not (eobp)))
 277       ;; Move forward over separator lines, and one more line.
 278       (while (prog1 (and (not (eobp))
 279                          (progn (move-to-left-margin) (not (eobp)))
 280                          (looking-at parsep))
 281                (forward-line 1)))
 282       (if fill-prefix-regexp
 283           ;; There is a fill prefix; it overrides parstart.
 284           (while (and (not (eobp))
 285                       (progn (move-to-left-margin) (not (eobp)))
 286                       (not (looking-at parsep))
 287                       (looking-at fill-prefix-regexp))
 288             (forward-line 1))
 289         (while (and (re-search-forward sp-parstart nil 1)
 290                     (progn (setq start (match-beginning 0))
 291                            (goto-char start)
 292                            (not (eobp)))
 293                     (progn (move-to-left-margin)
 294                            (not (looking-at parsep)))
 295                     (or (not (looking-at parstart))
 296                         (and use-hard-newlines
 297                              (not (get-text-property (1- start) 'hard)))))
 298           (forward-char 1))
 299         (if (< (point) (point-max))
 300             (goto-char start)))
 301       (setq arg (1- arg)))
 302     (constrain-to-field nil opoint t)))
 303
 304 (defun backward-paragraph (&optional arg)
 305   "Move backward to start of paragraph.
 306 With argument ARG, do it ARG times;
 307 a negative argument ARG = -N means move forward N paragraphs.
 308
 309 A paragraph start is the beginning of a line which is a
 310 `first-line-of-paragraph' or which is ordinary text and follows a
 311 paragraph-separating line; except: if the first real line of a
 312 paragraph is preceded by a blank line, the paragraph starts at that
 313 blank line.
 314
 315 See `forward-paragraph' for more information."
 316   (interactive "p")
 317   (or arg (setq arg 1))
 318   (forward-paragraph (- arg)))
 319
 320 (defun mark-paragraph (&optional arg)
 321   "Put point at beginning of this paragraph, mark at end.
 322 The paragraph marked is the one that contains point or follows point.
 323
 324 With argument ARG, puts mark at end of a following paragraph, so that
 325 the number of paragraphs marked equals ARG.
 326
 327 If ARG is negative, point is put at end of this paragraph, mark is put
 328 at beginning of this or a previous paragraph."
 329   (interactive "p")
 330   (unless arg (setq arg 1))
 331   (when (zerop arg)
 332     (error "Cannot mark zero paragraphs"))
 333   (forward-paragraph arg)
 334   (push-mark nil t t)
 335   (backward-paragraph arg))
 336
 337 (defun kill-paragraph (arg)
 338   "Kill forward to end of paragraph.
 339 With arg N, kill forward to Nth end of paragraph;
 340 negative arg -N means kill backward to Nth start of paragraph."
 341   (interactive "p")
 342   (kill-region (point) (progn (forward-paragraph arg) (point))))
 343
 344 (defun backward-kill-paragraph (arg)
 345   "Kill back to start of paragraph.
 346 With arg N, kill back to Nth start of paragraph;
 347 negative arg -N means kill forward to Nth end of paragraph."
 348   (interactive "p")
 349   (kill-region (point) (progn (backward-paragraph arg) (point))))
 350
 351 (defun transpose-paragraphs (arg)
 352   "Interchange this (or next) paragraph with previous one."
 353   (interactive "*p")
 354   (transpose-subr 'forward-paragraph arg))
 355
 356 (defun start-of-paragraph-text ()
 357   (let ((opoint (point)) npoint)
 358     (forward-paragraph -1)
 359     (setq npoint (point))
 360     (skip-chars-forward " \t\n")
 361     ;; If the range of blank lines found spans the original start point,
 362     ;; try again from the beginning of it.
 363     ;; Must be careful to avoid infinite loop
 364     ;; when following a single return at start of buffer.
 365     (if (and (>= (point) opoint) (< npoint opoint))
 366         (progn
 367           (goto-char npoint)
 368           (if (> npoint (point-min))
 369               (start-of-paragraph-text))))))
 370
 371 (defun end-of-paragraph-text ()
 372   (let ((opoint (point)))
 373     (forward-paragraph 1)
 374     (if (eq (preceding-char) ?\n) (forward-char -1))
 375     (if (<= (point) opoint)
 376         (progn
 377           (forward-char 1)
 378           (if (< (point) (point-max))
 379               (end-of-paragraph-text))))))
 380
 381 (defun forward-sentence (&optional arg)
 382   "Move forward to next `sentence-end'.  With argument, repeat.
 383 With negative argument, move backward repeatedly to `sentence-beginning'.
 384
 385 The variable `sentence-end' is a regular expression that matches ends of
 386 sentences.  Also, every paragraph boundary terminates sentences as well."
 387   (interactive "p")
 388   (or arg (setq arg 1))
 389   (let ((opoint (point)))
 390     (while (< arg 0)
 391       (let ((pos (point))
 392             (par-beg (save-excursion (start-of-paragraph-text) (point))))
 393        (if (and (re-search-backward sentence-end par-beg t)
 394                 (or (< (match-end 0) pos)
 395                     (re-search-backward sentence-end par-beg t)))
 396            (goto-char (match-end 0))
 397          (goto-char par-beg)))
 398       (setq arg (1+ arg)))
 399     (while (> arg 0)
 400       (let ((par-end (save-excursion (end-of-paragraph-text) (point))))
 401        (if (re-search-forward sentence-end par-end t)
 402            (skip-chars-backward " \t\n")
 403          (goto-char par-end)))
 404       (setq arg (1- arg)))
 405     (constrain-to-field nil opoint t)))
 406
 407 (defun backward-sentence (&optional arg)
 408   "Move backward to start of sentence.  With arg, do it arg times.
 409 See `forward-sentence' for more information."
 410   (interactive "p")
 411   (or arg (setq arg 1))
 412   (forward-sentence (- arg)))
 413
 414 (defun kill-sentence (&optional arg)
 415   "Kill from point to end of sentence.
 416 With arg, repeat; negative arg -N means kill back to Nth start of sentence."
 417   (interactive "p")
 418   (kill-region (point) (progn (forward-sentence arg) (point))))
 419
 420 (defun backward-kill-sentence (&optional arg)
 421   "Kill back from point to start of sentence.
 422 With arg, repeat, or kill forward to Nth end of sentence if negative arg -N."
 423   (interactive "p")
 424   (kill-region (point) (progn (backward-sentence arg) (point))))
 425
 426 (defun mark-end-of-sentence (arg)
 427   "Put mark at end of sentence.  Arg works as in `forward-sentence'."
 428   (interactive "p")
 429   (push-mark
 430     (save-excursion
 431       (forward-sentence arg)
 432       (point))
 433     nil t))
 434
 435 (defun transpose-sentences (arg)
 436   "Interchange this (next) and previous sentence."
 437   (interactive "*p")
 438   (transpose-subr 'forward-sentence arg))
 439
 440 ;;; paragraphs.el ends here