Function: occur

occur is an interactive and byte-compiled function defined in replace.el.gz.

Signature

(occur REGEXP &optional NLINES REGION)

Documentation

Show all lines in the current buffer containing a match for REGEXP.

If a match spreads across multiple lines, all those lines are shown.

Each match is extended to include complete lines. Only non-overlapping matches are considered. (Note that extending matches to complete lines could cause some of the matches to overlap; if so, they will not be shown as separate matches.)

Each line is displayed with NLINES lines before and after, or -NLINES before if NLINES is negative. NLINES defaults to list-matching-lines-default-context-lines. Interactively it is the prefix arg.

Optional arg REGION, if non-nil, mean restrict search to the specified region. Otherwise search the entire buffer. REGION must be a list of (START . END) positions as returned by region-bounds.

The lines are shown in a buffer named *Occur*. That buffer can serve as a menu for finding any of the matches for REGEXP in the current buffer. C-h m (describe-mode) in that buffer will explain how.

Matches for REGEXP are shown in the face determined by the variable list-matching-lines-face. Names of buffers with matched lines are shown in the face determined by the variable list-matching-lines-buffer-name-face. The line numbers of the matching lines are shown in the face determined by the variable list-matching-lines-prefix-face.

If list-matching-lines-jump-to-current-line is non-nil, then the line in the current buffer which was current when the command was invoked will be shown in the *Occur* buffer highlighted with the list-matching-lines-current-line-face, with point at the end of that line. (If the current line doesn't match REGEXP, it will nonetheless be inserted into the *Occur* buffer between the 2 closest lines that do match REGEXP.)

If REGEXP contains upper case characters (excluding those preceded by \) and search-upper-case is non-nil, the matching is case-sensitive.

When NLINES is a string or when the function is called interactively with prefix argument without a number (C-u (universal-argument) alone as prefix) the matching strings are collected into the *Occur* buffer by using NLINES as a replacement regexp. NLINES may contain \& and \N which convention follows replace-match. For example, providing "defun\\s +\\(\\S +\\)" for REGEXP and
"\\1" for NLINES collects all the function names in a lisp
program. When there is no parenthesized subexpressions in REGEXP the entire match is collected. In any case the searched buffer is not modified.

View in manual

Probably introduced at or before Emacs version 18.

Key Bindings

Aliases

list-matching-lines

Source Code

;; Defined in /usr/src/emacs/lisp/replace.el.gz
(defun occur (regexp &optional nlines region)
  "Show all lines in the current buffer containing a match for REGEXP.
If a match spreads across multiple lines, all those lines are shown.

Each match is extended to include complete lines.  Only non-overlapping
matches are considered.  (Note that extending matches to complete
lines could cause some of the matches to overlap; if so, they will not
be shown as separate matches.)

Each line is displayed with NLINES lines before and after, or -NLINES
before if NLINES is negative.
NLINES defaults to `list-matching-lines-default-context-lines'.
Interactively it is the prefix arg.

Optional arg REGION, if non-nil, mean restrict search to the
specified region.  Otherwise search the entire buffer.
REGION must be a list of (START . END) positions as returned by
`region-bounds'.

The lines are shown in a buffer named `*Occur*'.
That buffer can serve as a menu for finding any of the matches for REGEXP
in the current buffer.
\\<occur-mode-map>\\[describe-mode] in that buffer will explain how.

Matches for REGEXP are shown in the face determined by the
variable `list-matching-lines-face'.
Names of buffers with matched lines are shown in the face determined
by the variable `list-matching-lines-buffer-name-face'.
The line numbers of the matching lines are shown in the face
determined by the variable `list-matching-lines-prefix-face'.

If `list-matching-lines-jump-to-current-line' is non-nil, then the
line in the current buffer which was current when the command was
invoked will be shown in the `*Occur*' buffer highlighted with
the `list-matching-lines-current-line-face', with point at the end
of that line.  (If the current line doesn't match REGEXP, it will
nonetheless be inserted into the `*Occur*' buffer between the 2
closest lines that do match REGEXP.)

If REGEXP contains upper case characters (excluding those preceded by `\\')
and `search-upper-case' is non-nil, the matching is case-sensitive.

When NLINES is a string or when the function is called
interactively with prefix argument without a number (\\[universal-argument] alone
as prefix) the matching strings are collected into the `*Occur*'
buffer by using NLINES as a replacement regexp.  NLINES may
contain \\& and \\N which convention follows `replace-match'.
For example, providing \"defun\\s +\\(\\S +\\)\" for REGEXP and
\"\\1\" for NLINES collects all the function names in a lisp
program.  When there is no parenthesized subexpressions in REGEXP
the entire match is collected.  In any case the searched buffer
is not modified."
  (interactive
   (nconc (occur-read-primary-args)
          (and (use-region-p) (list (region-bounds)))))
  (let* ((start (and (caar region) (max (caar region) (point-min))))
         (end (and (cdar region) (min (cdar region) (point-max))))
         (in-region (or start end))
         (bufs (if (not in-region) (list (current-buffer))
                 (let ((ol (make-overlay
                            (or start (point-min))
                            (or end (point-max)))))
                   (overlay-put ol 'occur--orig-point (point))
                   (list ol)))))
    (occur-1 regexp nlines bufs)))