[[https://melpa.org/#/casual-re-builder][file:https://melpa.org/packages/casual-re-builder-badge.svg]]

• Casual RE-Builder An opinionated [[https://github.com/magit/transient][Transient]]-based user interface for [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Regular-Expressions.html][RE-Builder]], a tool for building Emacs regular expressions (regexps).

[[file:docs/images/casual-re-builder-screenshot.png]]

• Motivation 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.

** Goals

• To provide a keyboard-driven menu UI for RE-Builder.
• To provide casual access to the RE-Builder command set.

** Non-Goals

• 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.

• Requirements 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)

• Asks As Casual RE-Builder is new, we are looking for early adopters! Your [[https://github.com/kickingvegas/casual-re-builder/discussions][feedback]] is welcome as it will likely impact Casual RE-Builder's evolution, particularly with regards to UI.

• Install If installed via [[https://melpa.org/#/casual-re-builder][MELPA]] then add these lines to your Emacs initialization file with your binding of preference.

  +begin_src elisp :lexical no

  (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)

  +end_src

If you use ~use-package~, here is the recipe for installing and configuring it.

+begin_src elisp :lexical no

(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))

+end_src

** A Note on Package Dependencies Casual RE-Builder requires Casual Lib which in turn requires a recent installation of Transient 0.6.0+ from either [[https://elpa.gnu.org/packages/transient.html][ELPA]] or [[https://melpa.org/#/transient][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 [[https://elpa.nongnu.org/nongnu/magit.html][non-GNU ELPA]] or [[https://melpa.org/#/magit][MELPA]]) before installing Casual RE-Builder can also pick up the latest version of Transient.

• Usage

** Basic Usage 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.

** Exporting the Regexp Pattern 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.
• /(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-regexp~ and ~dired-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 [[https://github.com/kickingvegas/casual-re-builder/issues][issue]] describing the desired regexp and the target text.
  • This can only be used when the regexp syntax is set to ~string~.

** Regexp Syntax Help The menu item /(i)/ will invoke the Info page for regexp syntax with respect to the current syntax type.

** Quitting RE-Builder Select /(q) Quit/ to exit the RE-Builder tool.

** Unicode Symbol Support 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 | ↓ |

• Common Menu Actions 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.

• Development For users who wish to help contribute to Casual RE-Builder or personally customize it for their own usage, please read the [[docs/developer.org][developer documentation]].

• Sponsorship If you enjoy using Casual RE-Builder, consider making a modest financial contribution to help support its development and maintenance.

[[https://www.buymeacoffee.com/kickingvegas][file:docs/images/default-yellow.png]]

• See Also Casual RE-Builder is part of a suite of user interfaces for different Emacs packages called [[https://github.com/kickingvegas/casual-suite][Casual Suite]].

Different interfaces include those for I-Search, Dired, Info, Calc, Bookmarks, IBuffer, and others. Learn more about them today!

• Acknowledgments A heartfelt thanks to all the contributors to RE-Builder and [[https://github.com/magit/transient][Transient]]. Casual RE-Builder would not be possible without your efforts.