Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/kickingvegas/casual-avy

Casual Avy - An opinionated Transient menu for Avy.
https://github.com/kickingvegas/casual-avy

emacs

Last synced: about 1 month ago
JSON representation

Casual Avy - An opinionated Transient menu for Avy.

Awesome Lists containing this project

README 

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



* Casual Avy

An opinionated [[https://github.com/magit/transient][Transient]]-based user interface for [[https://github.com/abo-abo/avy][Avy]], a GNU Emacs package for jumping to visible text using a char-based decision tree.



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



* Motivation

While highly functional, Avy has a steep learning curve as it has a very diverse command set. Menus are a user interface (UI) affordance that offer users discoverability and recognition that can lower Avy's learning curve. 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 Avy endeavors to offer this as many Emacs users prefer keyboard-driven workflows.



** Goals

- To provide a keyboard-driven menu UI for Avy.

- To provide casual access to the Avy command set.



** Non-Goals

- Full coverage of all Avy commands. Casual Avy is not intended to be a power user tool.

- Strict adherence to Avy command naming. While Casual Avy is *mostly* in alignment with Avy’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 Avy 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 Avy requires usage of

- Emacs ≥ 29.1

- Avy ≥ 0.5.0

- Casual ≥ 2.0.0



Casual Avy has been verified with the following configuration. 

- Emacs 29.3 (macOS 14.4.1, Ubuntu Linux 22.04.4 LTS)

- Avy 0.5.0



* Asks

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



* Install

If installed via MELPA (pending) then add these lines to your Emacs initialization file with your binding of preference. 

#+begin_src elisp :lexical no

  (require 'casual-avy) ;; optional if using autoloaded menu

  (keymap-global-set "M-g" #'casual-avy-tmenu)

#+end_src



** Upgrading to Casual Avy 2.x

If you have been using an earlier version 1.x of Casual Avy, thank you. Please use the following guidance:



*** If you do not use ~use-package~ to configure Casual Avy



Updating the package ~casual-avy~ via the [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Package-Menu.html][package menu buffer]] will automatically update the ~casual~ package. However, this will not clean up older Casual 1.x packages. To migrate your existing Casual packages from 1.x to 2.x, run the following commands:



#+BEGIN_SRC elisp

M-x load-library casual

M-x casual-upgrade-base-to-version-2

#+END_SRC



Any Casual v1.x packages that have been superseded by this package will be uninstalled.



While not necessary, it is recommended to run ~M-x package-autoremove~ to purge any dangling dependent packages. Cautious readers can choose to audit any packages that are targeted to be removed.



*** If you have used ~use-package~ to configure Casual Avy

For version 2.x going forward, I (Charles Choi) have decided to not offer any documented guidance on using ~use-package~ to configure Casual Avy due my lack of expertise in using it. I leave it to more skilled readers to determine how to best use [[https://www.gnu.org/software/emacs/manual/html_node/use-package/][use-package]] for their configuration. Please also note that this is not a prohibition on using ~use-package~ with Casual Avy. I am simply admitting that I don't know how to use it. 



That said, if you have used ~:ensure t~ to install a superseded package, you /must/ remove that configuration. After doing so, please follow the above instructions for installing ~casual-avy~.



** A Note on Package Dependencies

Casual Avy 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]]. If your version of Emacs is ≤ 30 but also includes Transient as a built-in package, you will need to set the customizable variable ~package-install-upgrade-built-in~ to ~t~ to enable updating it via ~package.el~.  Set this variable and proceed with updating Casual Avy.  Alternately invoking ~package-install~ with a prefix (~C-u~) will temporarily coerce the update of dependent built-in packages (example: ~C-u M-x package-install~ ~casual~).



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 Avy can also pick up the latest version of Transient.



* Usage

A number of Avy commands have the option to limit the scope of candidates to the visible part of the current buffer above or below the point. Such commands are denoted with the ‘#’ or ‘⬍’ symbol. Press ~a~ to limit the scope above the point, ~b~ for below.



The commands listed under *Edit Other Line/Region* can perform an operation on a visible line or region while keeping the point stationary. This enables a workflow where a different visible part of the Emacs frame can be operated on without having to move the point.



The following glossary details the meaning of the menu labels.



| Menu Label                      | Operation                                                           |

|---------------------------------+---------------------------------------------------------------------|

| Copy                            | Copies the selected object (line, region) into the kill ring.       |

| Kill                            | Kills the selected object into the kill ring.                       |

| Move to above current line      | Moves the selected object to the line above the current point.      |

| Duplicate to above current line | Duplicates the selected object to the line above the current point. |



** Unicode Symbol Support

By enabling “Use Unicode Symbols” from the Settings menu, Casual Avy will use Unicode symbols as appropriate in its menus. The following mapping is shown in the table below:



| Name     | Plain    | Unicode |

|----------+----------+---------|

| Scope    | #        | ⬍       |

| Previous | Previous | ↑       |

| Next     | Next     | ↓       |



** Imenu (index) Support

The Emacs [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Imenu.html][Imenu]] (index menu) feature offers a way to navigate to a major definition in a file, provided that the current mode supports it. As Imenu behavior is closely related to Avy, support for it is provided here as the menu item labeled "(i) Index". The following configuration code turns on index menus for Markdown, Org, Makefile, and programming language modes.

#+begin_src elisp :lexical no

  (add-hook 'markdown-mode-hook #'imenu-add-menubar-index)

  (add-hook 'makefile-mode-hook #'imenu-add-menubar-index)

  (add-hook 'prog-mode-hook #'imenu-add-menubar-index)

  (add-hook 'org-mode-hook #'imenu-add-menubar-index)

#+end_src



** Org Support

If the current buffer is an Org file, then two menu items are supported:

- "(o) Org heading"

- "(g) Org Goto…"



Selecting "Org heading" will invoke the ~avy-org-goto-heading-timer~ command. Note as with all other Avy commands, this will only work with Org headings that are visible. If navigation to any Org header is desired, select "Org Goto…" to invoke the command ~org-goto~.



* Common Menu Actions

Casual Avy 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.



Options such as ~--above~ and ~--below~ can be saved for future use by typing ~C-x C-s~.



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 Avy or personally customize it for their own usage, please read the [[docs/developer.org][developer documentation]].



* Sponsorship

If you enjoy using Casual Avy, 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 Avy 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, RE-Builder, IBuffer, and others. Learn more about them today!



* Acknowledgments

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