Function: org-occur

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

Signature

(org-occur REGEXP &optional KEEP-PREVIOUS CALLBACK)

Documentation

Make a compact tree showing all matches of REGEXP.

The tree will show the lines where the regexp matches, and any other context defined in org-fold-show-context-detail, which see.

When optional argument KEEP-PREVIOUS is non-nil, highlighting and exposing done by a previous call to org-occur will be kept, to allow stacking of calls to this command.

Optional argument CALLBACK can be a function of no argument. In this case, it is called with point at the end of the match, match data being set accordingly. Current match is shown only if the return value is non-nil. The function must neither move point nor alter narrowing.

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/org/org.el.gz
(defun org-occur (regexp &optional keep-previous callback)
  "Make a compact tree showing all matches of REGEXP.

The tree will show the lines where the regexp matches, and any other context
defined in `org-fold-show-context-detail', which see.

When optional argument KEEP-PREVIOUS is non-nil, highlighting and exposing
done by a previous call to `org-occur' will be kept, to allow stacking of
calls to this command.

Optional argument CALLBACK can be a function of no argument.  In this case,
it is called with point at the end of the match, match data being set
accordingly.  Current match is shown only if the return value is non-nil.
The function must neither move point nor alter narrowing."
  (interactive "sRegexp: \nP")
  (when (equal regexp "")
    (user-error "Regexp cannot be empty"))
  (unless keep-previous
    (org-remove-occur-highlights nil nil t))
  (push (cons regexp callback) org-occur-parameters)
  (let ((cnt 0))
    (save-excursion
      (goto-char (point-min))
      (when (or (not keep-previous)	    ; do not want to keep
		(not org-occur-highlights)) ; no previous matches
	;; hide everything
	(org-cycle-overview))
      (let ((case-fold-search (if (eq org-occur-case-fold-search 'smart)
				  (isearch-no-upper-case-p regexp t)
				org-occur-case-fold-search)))
	(while (re-search-forward regexp nil t)
	  (when (or (not callback)
		    (save-match-data (funcall callback)))
	    (setq cnt (1+ cnt))
	    (when org-highlight-sparse-tree-matches
	      (org-highlight-new-match (match-beginning 0) (match-end 0)))
	    (org-fold-show-context 'occur-tree)))))
    (when org-remove-highlights-with-change
      (add-hook 'before-change-functions 'org-remove-occur-highlights
		nil 'local))
    (unless org-sparse-tree-open-archived-trees
      (org-fold-hide-archived-subtrees (point-min) (point-max)))
    (run-hooks 'org-occur-hook)
    (when (called-interactively-p 'interactive)
      (message "%d match(es) for regexp %s" cnt regexp))
    cnt))