Browsing functions in a single file with occur-mode

Dec 29, 2016

Browsing through functions in source code in one buffer

Overview

When you want to glance at the overall structure of a source code file, and are overwhelmed by the file size or the detailed code present I find useful two things:

see a list of the function names to get an idea of the naming conventions and an overview of the file content
an easy way to browse functions or procedures having a quick look at their content.

If you can identify any special keyword of how functions are defined in the programming language you are using, you can filter them using the occur command.

occur is a standard command that find matches for a regular expression and list them in a new buffer.

Using occur

We start by looking for the keyword that defines functions with the occur command M-s o so It prompt for a regexp and display a list in a new buffer in Occur-mode.

Then we can work directly from the source code or move to the Occur buffer.

In Occur buffer

This is a special buffer where we can move around with M-n and M-p:

occur-next M-n: Move to the Nth (default 1) next match in an Occur mode buffer.

occur-prev M-p: Move to the Nth (default 1) previous match in an Occur mode buffer.

To visit the corresponding position in the buffer RET:

occur-mode-goto-occurrence RET,C-c C-c: Go to the occurrence on the current line.

Or visit the position in the buffer but in a new window C-o:

occur-mode-display-occurrence C-o: Display in another window the occurrence the current line describes.

We can also toggle Next Error Follow minor mode with C-c C-f which is a feature of the Compilation mode “which makes cursor motion in the compilation buffer produce automatic source display”, so in this case it will automatically update the cursor in the buffer where we looked at the functions.

next-error-follow-minor-mode C-c C-f: Minor mode for compilation, occur and diff modes.

From the source code buffer

From the source code window we can:

View the occurences scrolling the other window C-M-v

scroll-other-window C-M-v: Scroll next window upward ARG lines; or near full screen if no ARG.

scroll-other-window-down C-M-S-v: Scroll the “other window” down.

Browse through occurences from the source code window with M-g n and M-g M-p. This approach uses the Compilation Mode, a mode that turns each error message in the buffer into a hyperlink, this is why they are named with the “error” prefix, in this case they are just occurences.

next-error C-x `,M-g n,M-g M-n.: Visit next `next-error’ message and corresponding source code.

previous-error M-g p,M-g M-p: Visit previous `next-error’ message and corresponding source code.

Notes

occur is part of a set of basic editing commands for Emacs included in replace.el, which already comes with Emacs, that makes it always available and a quick solution to browse a buffer.

Replace.el derives from Special Mode.

Special mode is a basic major mode for buffers containing text that is produced specially by Emacs, rather than directly from a file. Major modes derived from Special mode are given a ‘mode-class’ property of ‘special’.

Special mode sets the buffer to read-only. Its keymap defines several common bindings, including q for ‘quit-window’ and g for ‘revert-buffer’

Summary

Using standard command from Emacs we can adapt them to browse functions or other special keywords.