How I shortlist add-ons for my Emacs: Introducing `loccur`


In this article , you will learn about package loccur1.

loccur describes itself as a package that does

Perform an occur-like folding in current buffer

That description only hints at what the package does, but it doesn’t say much about what exactly you can accomplish with that.

I would describe the package as

Show lines (in your file) that match a text pattern

You can imagine infinite number of situations where you could make use of the above functionality.

In this article, you will learn about two use-cases for loccur, both in the context of Emacs Package Manager 1.

  • Shortlisting add-ons for your specific needs:  Specifically, shortlist a few custom themes of  your liking.
  • Viewing packages that are marked with some action, say installation or upgrade

(If you have any experience with the Emacs Package Manager,  those are the two areas where it falls short.)

Before jumping to the use-cases, here are a few preliminaries, you need to get out of your way.

Step 1:  Download and Install loccur

Download and install the package loccur. This package is available from GNU ELPA. If you are new to installing packages, see my earlier article 1.

Step 2: Create a menu for loccur

Copy the Emacs Lisp snippet1  below to your .emacs and restart your Emacs.

This snippet

  1. loads loccur
  2. sets up short-cut keys , that the author of this package recommends, to invoke commands that this package provides
  3. adds a sub-menu named Extra Tools to the menu.  To this sub-menu, it adds another sub-menu named Loccur.
(require 'loccur)

(with-eval-after-load 'loccur
  ;; defines shortcut for loccur of the current word
  (define-key global-map [(control o)] 'loccur-current)
  ;; defines shortcut for the interactive loccur command
  (define-key global-map [(control meta o)] 'loccur)
  ;; defines shortcut for the loccur of the previously found word
  (define-key global-map [(control shift o)] 'loccur-previous-match)

  (define-key-after global-map
    [menu-bar extra-tools]
    (cons "Extra Tools"
      (easy-menu-create-menu "Extra Tools" nil))
    'tools)

  (easy-menu-define my-loccur-menu nil "Menu for Loccur."
    '("Loccur" :visible (featurep 'loccur)
      ["Loccur Current Word" loccur-current :help "Call `loccur' for the current word."]
      "--"
      ["Loccur ..." loccur :help "Perform a simple grep in current buffer.\n\nThis command hides all lines from the current buffer except those\ncontaining the regular expression REGEX.  A second call of the function\nunhides lines again.\n\nWhen called interactively, either prompts the user for REGEXP or,\nwhen called with an active region, uses the content of the\nregion.\n\n(fn REGEX)"]
      ["Loccur, but Don't Highlight" loccur-no-highlight :help "Perform search like loccur, but temporary removing match highlight.\nREGEX is regexp to search\n\n(fn REGEX)"]
      "--"
      ["Loccur Previous Match" loccur-previous-match :help "Call `loccur' for the previously found word."]
      "--"
      ["Highlight Matches" loccur-toggle-highlight :style toggle :selected loccur-highlight-matching-regexp :help "Toggle the highlighting of the match."]
      ["Loccur Mode" loccur-mode :style toggle :selected loccur-mode :help "Minor mode for navigating through the file.\nHides all lines without matches like `occur' does, but without opening\na new window.\n\n(fn &optional ARG)"]
      ))

  (easy-menu-add-item (current-global-map) '("menu-bar" "extra-tools") my-loccur-menu))

Step 3: Ensure that you have  Extra Tools -> Loccur

Once you restart you Emacs,  your menu-bar should have an the sub-menu Extra Tools -> Loccur .  See the next step for a screenshot.  If you aren’t seeing this menu, repeat the earlier steps.

Step 4: Launch the package manager, and search for the occurrence of a word you are looking for

Launch the package manager, and view a list of all packages at your disposal.

As you can see you can see from the screenshot below, there are  thousands of packages and your challenge is to choose packages that provide custom themes.

Screenshot from 2018-10-01 13-35-49

When Emacs prompts you for a pattern to look for, enter the word theme.  Remember you are looking for some custom themes.

Screenshot from 2018-10-01 13-40-17

Once that is done, your list will narrow down from few thousands to few hundreds.  In my specific run, I see close to 230 custom themes.

Screenshot from 2018-10-01 13-40-54

You will notice that the word you are searching for is highlighted. If your are like me, you will find the result page hard to read.  In that case, you can remove the highlight as you see below.

Screenshot from 2018-10-01 13-52-56

From looking at 4000 odd packages, you are now only looking at only 200 odd packages.  This is a vast improvement.

Screenshot from 2018-10-01 13-48-43

Once you  have shortlisted a few themes, you can do whatever with that list.  For example, you can mark some of the themes for installation.

Step 5: Reset your view

Once that is done, you can get back to your original view, by turning off Loccur Mode as below.

Screenshot from 2018-10-01 13-49-27

Step 6: View Marked Packages

In the original screenshot,  Emacs reported that you can upgrade some of the packages.  But it doesn’t tell you exactly what packages are available for upgrade.  Not knowing what packages are available for upgrade could be frustrating.  In this case, you can loccur to see what packages will get upgraded.  To do this, press U to mark the upgraded pages. To narrow your view to all marked packages use  ^[^ ]+ as the text pattern.

Screenshot from 2018-10-01 13-57-07

Screenshot from 2018-10-01 13-57-49

As you can see above, the GNU version of loccur is marked for deletion (with a D) and the MELPA version of it marked for installation (with a I).

Concluding Words (on filtering Packages)

The Emacs’ official way of shortlisting of packages is via Package Keywords.  I find the use of keywords not only very pedantic, but very limiting.  The limitation of keywords becomes particularly glaring when one deals with repositories like MELPA.  Such repositories have a very lax review process, and the packages keywords may neither be complete or reliable.   In that case, I find loccur a very useful tool to have in my kit.

Advertisements
Categories gnu

2 thoughts on “How I shortlist add-ons for my Emacs: Introducing `loccur`

  1. Thanks for the great intro to loccur. However, you should at least mention the commands to be used as well, since not everybody uses emacs with menus enabled.

    best,
    Tom

    Like

  2.         <em><strong>&gt; Thanks for the great intro to loccur. However, you should at least mention the commands to be used as well, since not everybody uses emacs with menus enabled.</strong></em>
    

    Hello, thanks for the suggestion. In today’s article, you can see that the tooltip on the menu entry contains not only the command name (and full signature), but also it’s full-documentation. Screenshots in the earlier articles continue to NOT have the function name in the menu tooltip. This is because of my oversight. However, let this not make you or any other reader feel that the command name is left out. If you notice carefully, the name on the menu is nothing but human-readable form of the command. To get to the underlying command, take the name on the menu, replace the spaces with dashes and lower-case it. Alternatively, the Emacs Lisp snippet that creates the menu carries the command name.

    Thanks a lot taking time to comment on my post.

    Like

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this:
search previous next tag category expand menu location phone mail time cart zoom edit close