Use Emacs Occur Mode For Magik Pattern Matches

When a Magik image or source tree becomes large, searching for a name is only the beginning. You may need to find every method declaration, inspect uses of _proc, locate database query patterns, or compare collection-handling code across several packages. Emacs Occur mode turns those matches into a navigable results buffer rather than leaving you to move through one long stream of search results.

Occur works particularly well for Magik because Magik source has recognisable structural markers. Keywords such as _method, _proc, _if, _loop, and _endmethod make useful regular-expression targets. With a carefully chosen expression, you can create a compact index of relevant lines and jump directly into the original source.

The workflow is useful for developers maintaining GE Smallworld customisations, integrations, and application frameworks. A team in Melbourne can use the same search approach as a consultant working with a Perth utility or a Sydney-based mapping group, even when their local source conventions differ.

This guide focuses on source-level pattern matching. It does not run a Magik expression or evaluate objects in the Smallworld environment. Instead, it helps you inspect text quickly, refine a code search, and turn recurring investigations into repeatable Emacs commands.

Why Occur Fits Magik Work

The standard command is M-x occur. Emacs prompts for a regular expression, searches the current buffer, and opens an *Occur* buffer containing matching lines. Each result normally includes a source line number, so the list becomes a lightweight map of the file. Press n and p to move between matches, or place the cursor on an entry and press RET to visit the source location.

This is more informative than an ordinary incremental search when you need to see a pattern’s distribution. For example, searching for _return can reveal whether a method has several exit paths, while searching for _proc can show where procedural callbacks are concentrated. A single Occur buffer can also expose whether a naming convention is consistent across an older Magik package.

Occur is especially convenient when reviewing code during a maintenance window. Rather than opening each method in turn, you can collect declarations, inspect them in context, and return to the result list. The approach suits Australian teams working across AEST, AEDT, and AWST because a reproducible local search is easier to hand over than a description such as “look near the middle of the file”.

Prepare Magik Buffers

Start with the correct source buffer and confirm that Emacs has recognised the file as Magik, if a Magik major mode is installed. Syntax highlighting is helpful, but Occur itself searches the buffer’s text. If a file uses unusual indentation, generated headers, or mixed line endings, check the actual characters before designing a complex expression.

A simple declaration search might be:

^[ \t]*_method[ \t]+

This finds lines beginning with optional whitespace followed by _method. If your code places method names immediately after the keyword, add a capture-like descriptive pattern for the name:

^[ \t]*_method[ \t]+[^ (]+

Emacs regular expressions use backslashes differently from many modern search tools. In an interactive occur prompt, type the expression as Emacs expects it; in an Elisp string, backslashes generally need to be doubled. Keep the first search uncomplicated, inspect the results, and only then tighten the pattern.

Before sharing Occur output outside your organisation, consider what source or comments it exposes. Australian organisations handling customer, health, utility, or location data may have obligations under the Privacy Act 1988 and internal data-handling policies. A search result containing a method name is usually harmless, but embedded addresses, identifiers, or operational details deserve the same care as the original file.

Build Useful Regular Expressions

To find procedure declarations, try:

^[ \t]*_proc[ \t]*

For control-flow review, search for several related keywords with alternation:

^[ \t]*_\(?:if\|elif\|else\|endif\)

The \| operator means “or” in Emacs regular expressions, while \(?: ... \) groups alternatives without creating a numbered capture. This gives you one Occur list for conditional branches. A similar expression can locate loop boundaries:

^[ \t]*_\(?:for\|loop\|endloop\)

You can search for method calls or domain-specific naming patterns by combining a literal fragment with a flexible suffix. For example, a project that uses methods beginning with gis_ might use:

\_<gis_[[:alnum:]_]+\_>

Word boundaries can be surprising when underscores are part of Magik identifiers. If the result list misses valid names, remove the boundaries and search for gis_[[:alnum:]_]+ instead. Bracket expressions such as [[:space:]] and [[:alnum:]] are portable Emacs forms and make the intention clearer than a collection of individual characters.

Occur can also search for comments, logging calls, or suspicious constructs. A pattern such as TODO\|FIXME\|XXX finds review markers, while _raise or a project-specific error class can identify exception paths. Use case sensitivity deliberately: M-x toggle-case-fold-search changes whether the search treats upper- and lower-case text as equivalent.

Run And Navigate Occur

After running M-x occur, enter the expression and press RET. Emacs creates or refreshes the *Occur* buffer. You can control the amount of surrounding context by supplying a numeric prefix, such as C-u 2 M-x occur, which displays two lines before and after each match. Context is valuable for Magik declarations because the method signature may wrap across lines or include a documentation comment immediately above it.

In the results buffer, RET visits the selected match, while o opens the source in another window. C-o can display the source without moving away from the Occur buffer. Press q to hide the results window. If the file changes, press g in the Occur buffer to regenerate the matches. These small commands make repeated source inspection considerably faster.

The results are more useful when the buffer is narrowed to the relevant package or class file. Use C-x n n to narrow to a region when appropriate, then run Occur on that restricted view. This prevents unrelated framework code from overwhelming a search for application-specific methods. Widen again with C-x n w when the investigation is complete.

For a project-wide search, M-x multi-occur can search several already-open buffers. M-x occur remains the better first step when testing a pattern, because a false positive is easy to diagnose in one file. Once the expression is reliable, project tools such as grep, rgrep, or consult-ripgrep can provide broader coverage while preserving a similar review workflow.

Turn Matches Into A Review Workflow

Occur is most powerful when used as an inspection index rather than a one-off search. Begin with a broad expression, such as all method declarations, then narrow the results by searching within the Occur buffer or returning to the source. For example, find every _method, inspect which ones call a particular collection operation, and then create a second Occur list for that operation.

You can edit matches with e, which activates Occur Edit mode in supported Emacs versions. This presents matching lines in an editable form, allowing controlled changes to the source-backed results. Finish with C-c C-c to apply edits or C-c C-k to discard them. Treat this as a deliberate refactoring tool: make a backup or use version control, especially when a regular expression could match comments or generated code.

An Elisp helper is useful for searches performed frequently:

(defun magik-occur-methods ()
  (interactive)
  (occur "^[ \t]*_method[ \t]+[^ (]+"))

Place the function in your Emacs configuration, evaluate it, and run M-x magik-occur-methods. You can create similar commands for _proc, error handling, or project naming conventions. Teams that maintain shared editor configurations can document these commands alongside their Magik coding standards.

For broader delivery work, a consistent search routine can sit beside planning and task tracking. A consultant coordinating changes across multiple clients may keep the search expressions and review notes with the project workflow used in project workspaces, rather than relying on ad hoc shell history.

Handle Large Codebases Safely

Large Smallworld installations often contain generated files, vendor extensions, historical backups, and several application directories. Searching everything produces noisy results and can make it difficult to distinguish active Magik from archived code. Exclude generated and backup paths at the project-search level, or visit only the relevant buffers before using multi-occur.

Long lines and huge generated buffers can also slow down display. Start with a distinctive anchor, such as ^[ \t]*_method, and avoid expressions that can match an empty string. If an Occur search behaves unexpectedly, test the expression with M-x re-builder, which shows how Emacs interprets the regular expression against the current buffer.

Remote development deserves attention as well. A team in Brisbane may edit code on a server in Sydney, while another engineer in Perth accesses the same repository over a slower connection. Occur operates on the buffer already available in Emacs, so it avoids repeatedly sending individual search requests across the network. For very large repositories, server-side ripgrep followed by an Occur-style compilation buffer may be more efficient.

Do not treat a result list as proof that a pattern is safe to change. Magik methods can be invoked dynamically, names can be assembled from symbols, and framework conventions may hide relationships from a text search. Use Occur to locate candidates, then inspect callers, inheritance, object types, and runtime behaviour before making a structural change.

Choose The Right Search Method

The best command depends on the question being asked. Occur is ideal for collecting every matching line in the current buffer and reviewing the surrounding code. Incremental search is faster when you already know the exact next occurrence. multi-occur suits a set of open files, while rgrep and consult-ripgrep are better for repository-wide discovery.

A useful Magik investigation often combines them. Search the repository for a class or method name, open the most relevant files, use Occur to list declarations or control-flow markers, and then use cross-reference or object-inspection features in the Magik environment to verify runtime relationships. This division keeps text search quick without pretending that source patterns reveal every dynamic behaviour.

Task	Recommended Emacs approach	Useful Magik example
Find matches in one file	M-x occur	_method, _proc, _raise
Inspect nearby source	Occur with a numeric prefix	Method signatures and comments
Search several open files	M-x multi-occur	Repeated collection operations
Search a repository	rgrep or consult-ripgrep	Project-specific method names
Make controlled replacements	Occur Edit mode	Consistent spelling or naming fixes
Check runtime relationships	Magik debugger or inspector	Dynamic calls and object state

Teams supporting Australian councils, utilities, and infrastructure projects can save these expressions in a shared Emacs configuration and document when each one should be used. That creates a common vocabulary for code review across offices in Adelaide, Canberra, or regional locations, while leaving runtime validation to the Smallworld development environment.

When a search pattern needs to reflect your organisation’s Magik conventions, examples and configuration advice can be discussed through Magik Emacs contact. A small, tested Occur command is often enough to turn a recurring investigation into a dependable part of daily development.

Use M-x occur as a fast source index: begin with a clear Magik keyword, inspect the matches, add context, and refine the regular expression only when the results show what is missing. Save the searches that prove useful, review edits through version control, and pair text-based findings with Magik’s runtime tools before committing significant changes.