An opinionated Transient-based user interface for RE-Builder, a tool for building Emacs regular expressions (regexps).
While highly functional, RE-Builder has a steep learning curve to its many commands. Menus can lower this curve by offering users discoverability and recall. While menus are commonly associated with mouse-driven UI, the inclusion of Transient in Emacs core allows for a menu UI that is keyboard-driven. Casual RE-Builder endeavors to offer this as many Emacs users prefer keyboard-driven workflows.
- To provide a keyboard-driven menu UI for RE-Builder.
- To provide casual access to the RE-Builder command set.
- Strict adherence to RE-Builder command naming. While Casual RE-Builder is mostly in alignment with RE-Builder’s command naming, there are cases where it will make an opinionated change if the name is deemed too vague or idiomatic.
- UX Stability (for now). Given that Casual RE-Builder is early in its life-cycle, expect changes to its user experience in terms of menu hierarchy and keybinding choices in future releases.
Casual RE-Builder requires usage of
- Emacs ≥ 29.1
- Casual Lib ≥ 1.1.0
Casual RE-Builder has been verified with the following configuration.
- Emacs 29.4 (macOS 14.5, Ubuntu Linux 22.04.4 LTS)
As Casual RE-Builder is new, we are looking for early adopters! Your feedback is welcome as it will likely impact Casual RE-Builder’s evolution, particularly with regards to UI.
If installed via MELPA then add these lines to your Emacs initialization file with your binding of preference.
(require 'casual-re-builder) ;; optional
(keymap-set reb-mode-map "C-o" #'casual-re-builder-tmenu)
(keymap-set reb-lisp-mode-map "C-o" #'casual-re-builder-tmenu)If you use use-package, here is the recipe for installing and configuring it.
(use-package re-builder
:defer t)
(use-package casual-re-builder
:ensure t
:bind (:map
reb-mode-map ("C-o" . casual-re-builder-tmenu)
:map
reb-lisp-mode-map ("C-o" . casual-re-builder-tmenu))
:after (re-builder))Casual RE-Builder requires Casual Lib which in turn requires a recent installation of Transient 0.6.0+ from either ELPA or MELPA. As an older version of Transient is built-in to the Emacs release, the package manager package.el will not update this package unless the customizable variable package-install-upgrade-built-in is set to t. Set this variable and proceed with installing Casual RE-Builder. Alternately invoking package-install with a prefix (C-u) will temporarily coerce the update of the built-in package. (example: C-u M-x package-install casual-re-builder)
As Transient is closely tied to Magit, installing the latest version of Magit (via non-GNU ELPA or MELPA) before installing Casual RE-Builder can also pick up the latest version of Transient.
When the command re-builder is invoked, a buffer named “✳︎RE-Builder✳︎” is created. Activate Casual RE-Builder with the binding C-o (or one of your preference).
At the top of the menu shows the title “RE-Builder” with the target buffer enclosed in parenthesis. The regexp pattern will be applied to the target buffer. The target buffer can be changed with the (b) Target buffer menu item.
Emacs supports three different regexp syntax: 1) read, 2) string, 3) Rx. Use the (x) Syntax menu item to alter it. The current syntax is shown in parenthesis.
If multiple sub-expressions are in the regexp pattern, then they can be observed via the (s) Subexp mode menu item.
If the regexp pattern entered in the “✳︎RE-Builder✳︎” finds multiple matches, a match can be navigated to via the (p) Previous and (n) Next menu items.
Once a desired regexp pattern is defined, there are two menu items that can be used to export (copy) it to the kill-ring for further use.
- (w) Interactive will copy the regexp to the kill-ring so that it can be yanked in an interactive command that requires a regexp (e.g.
query-replace-regexp).- This can only be used when the regexp syntax is set to
string. - ❗️When yanking (typically
C-y) a regexp into an interactive prompt, you must have the point/focus in the minibuffer prompt (typically via mouse). Otherwise the desired content can be altered with extra escaping.
- This can only be used when the regexp syntax is set to
- (c) Code will copy the regexp to the kill-ring so that it can be yanked into a Elisp code that requires a regexp argument.
- (g) Interactive grep will copy the regexp so that it can be used with command that take a GNU grep regex argument.
- Example commands that do this are
dired-do-find-regexpanddired-do-find-regexp-and-replace. - This command presumes that you have GNU grep installed and configured for use by Emacs.
- ❗️At current this is an experimental feature. The regexp exported from RE-Builder may not work. If so please report an issue describing the desired regexp and the target text.
- This can only be used when the regexp syntax is set to
string.
- Example commands that do this are
The menu item (i) will invoke the Info page for regexp syntax with respect to the current syntax type.
Select (q) Quit to exit the RE-Builder tool.
By enabling “Use Unicode Symbols” from the Settings menu, Casual RE-Builder will use Unicode symbols as appropriate in its menus. The following mapping is shown in the table below:
| Name | Plain | Unicode |
|---|---|---|
| :previous | Previous | ↑ |
| :next | Next | ↓ |
Casual RE-Builder is built using Transient menus and as such adopts much of its default behavior.
Each menu item has a key and a label. The key is what is typed by the user to select the menu item. A key can be prefixed with a meta (M-) or control (C-) key.
Dismissing a menu regardless of how deep you are in sub-menus can be done by entering C-q. A menu can also be dismissed by entering C-g, but this will return you to the parent menu.
If a mouse is available, a menu item can be selected by moving the mouse cursor over its label and pressing down button 1.
Pressing the ? key will toggle help for all the menu items. Press the key of interest to get help for it.
When a Transient menu is raised, a prefix argument (C-u) can be entered before selecting a menu item.
For users who wish to help contribute to Casual RE-Builder or personally customize it for their own usage, please read the developer documentation.
If you enjoy using Casual RE-Builder, consider making a modest financial contribution to help support its development and maintenance.
Casual RE-Builder is part of a suite of user interfaces for different Emacs packages called Casual Suite.
Different interfaces include those for I-Search, Dired, Info, Calc, Bookmarks, IBuffer, and others. Learn more about them today!
A heartfelt thanks to all the contributors to RE-Builder and Transient. Casual RE-Builder would not be possible without your efforts.