The documentation can be something like this. I just added the last
paragraph below.
-Tak
`M-x occur'
Prompt for a regexp, and display a list showing each line in the
buffer that contains a match for it. To limit the search to part
of the buffer, narrow to that part (*note Narrowing::). A numeric
argument N specifies that N lines of context are to be displayed
before and after each matching line. Currently, `occur' can not
correctly handle multiline matches.
The buffer `*Occur*' containing the output serves as a menu for
finding the occurrences in their original context. Click
`Mouse-2' on an occurrence listed in `*Occur*', or position point
there and type<RET>; this switches to the buffer that was
searched and moves point to the original of the chosen occurrence.
`o' and `C-o' display the match in another window; `C-o' does not
select it.
After using `M-x occur', you can use `next-error' to visit the
occurrences found, one by one. *note Compilation Mode::.
When the numeric argument N is 0 or negative the buffer `*Occur*'
collects all the matched strings. When N is 0 the entire text
matched is collected. When N is negative the text in the -Nth
parenthesized expression in the regexp is collected.
Thu, 04 Nov 2010 11:36:54 -0700: Tak Ota<address@hidden> wrote:
Thu, 4 Nov 2010 06:58:20 -0700: Stefan Monnier<address@hidden> wrote:
How about rename the command as collect-occur instead of
collect-string and document it as next?
Wrong namespace. IMO, the name should *start* with occur (but Stefan
and Yidong are final authorities on that).
Agreed, namespace cleanliness is one of my favorite forms of
anal retentiveness.
The way I see it, the suggested collect-string is a variant of occur
where the result buffer contains none of the regexp matches's context.
So it would make sense to integrate it very tightly with `occur',
i.e. make M-x occur do the job of collect-strings for some particular
value of its argument NLINES. Currently, NLINES is assumed to be
a number and all values of that number have a useful meaning, so we'd
have to add this new feature via a non-number value of NLINES.
E.g. C-u M-x occur could do the collect-string thingy (which is still an
incompatible change since some people may like to use C-u M-x occur to get
4 lines of context, but you can make omelets without breaking eggs).
Stefan
Now I am convinced. How about the change below? In conventional
occur zero or negative value for nlines is meaningless correct? We
can use that for collection purpose. i.e. C-u 0 M-x occur does the
collection of the matching pattern. C-u -1 M-x occur performs the
collection of the recorded pattern 1.
-Tak
(defun occur-1 (regexp nlines bufs&optional buf-name)
(unless (and regexp (not (equal regexp "")))
(error "Occur doesn't work with the empty regexp"))
(unless buf-name
(setq buf-name "*Occur*"))
(let (occur-buf
(active-bufs (delq nil (mapcar #'(lambda (buf)
(when (buffer-live-p buf) buf))
bufs))))
;; Handle the case where one of the buffers we're searching is the
;; output buffer. Just rename it.
(when (member buf-name (mapcar 'buffer-name active-bufs))
(with-current-buffer (get-buffer buf-name)
(rename-uniquely)))
;; Now find or create the output buffer.
;; If we just renamed that buffer, we will make a new one here.
(setq occur-buf (get-buffer-create buf-name))
(if (or (null (integerp nlines))
(> nlines 0))
;; nlines is not zero or negative so perform nomal occur
(with-current-buffer occur-buf
(occur-mode)
(let ((inhibit-read-only t)
;; Don't generate undo entries for creation of the initial
contents.
(buffer-undo-list t))
(erase-buffer)
(let ((count (occur-engine
regexp active-bufs occur-buf
(or nlines list-matching-lines-default-context-lines)
(if (and case-fold-search search-upper-case)
(isearch-no-upper-case-p regexp t)
case-fold-search)
list-matching-lines-buffer-name-face
nil list-matching-lines-face
(not (eq occur-excluded-properties t)))))
(let* ((bufcount (length active-bufs))
(diff (- (length bufs) bufcount)))
(message "Searched %d buffer%s%s; %s match%s for `%s'"
bufcount (if (= bufcount 1) "" "s")
(if (zerop diff) "" (format " (%d killed)" diff))
(if (zerop count) "no" (format "%d" count))
(if (= count 1) "" "es")
regexp))
(setq occur-revert-arguments (list regexp nlines bufs))
(if (= count 0)
(kill-buffer occur-buf)
(display-buffer occur-buf)
(setq next-error-last-buffer occur-buf)
(setq buffer-read-only t)
(set-buffer-modified-p nil)
(run-hooks 'occur-hook)))))
;; nlines is zero or negative integer perform collect-string
(with-current-buffer occur-buf
(setq nlines (- nlines))
(fundamental-mode)
(let ((inhibit-read-only t)
(buffer-undo-list t))
(erase-buffer)
(while active-bufs
(with-current-buffer (car active-bufs)
(save-excursion
(goto-char (point-min))
(while (re-search-forward regexp nil t)
(let ((str (match-string nlines)))
(if str
(with-current-buffer occur-buf
(insert str)
(or (zerop (current-column))
(insert "\n"))))))))
(setq active-bufs (cdr active-bufs))))
(display-buffer occur-buf)))))