Add imenu-list layer

[bmag]

imenu-list provides a side bar that shows all imenu entries of the current buffer. More info at https://github.com/bmag/imenu-list

I chose SPC b i as the binding to toggle imenu-list, as mnemonic for "buffer index", but of course that can be changed.

How imenu-list differs from NeoTree and sr-speedbar: NeoTree only shows files and directories, sr-speedbar shows files, directories and imenu indexes, and imenu-list shows only imenu indexes.

How imenu-list differs from spacemacs/jump-in-buffer (SPC s l): imenu-list is a side bar that stays visible and updates automatically when switching buffers and serves as a visual reminder of the buffer's structure, while spacemacs/jump-in-buffer serves as a jump command and doesn't remain visible.

[person808]

@bmag Perhaps this can be mentioned in VIMUSERS.org as a Spacemacs equivalent to tagbar?

[bmag]

I don't know tagbar, so I don't know if imenu-list really is equivalent to it. I also didn't find a proper place in VIMUSERS.org, but maybe you meant I should add a line under the "Evil plugins" section in DOCUMENTATION.org (as was done for NeoTree)?

[person808]

I also didn't find a proper place in VIMUSERS.org

Ah, you're right. I thought there was a section for that. Maybe I'll create it in the future.

I don't think it fits under "Evil plugins" because this is not part of the spacemacs layer.

[stshine]

Thank you, I do not know this extension before, it is usable for most languages, and extremly well for org mode; now I hope every document in the world is written as org file.
However, it is a pity that I do not know this extension until I randomly ran into this pull request while I was eagerly looking for a visual navigation extension, and it could also be difficult for new users of spacemacs to find this layer. Maybe it is better to change the name of this layer to contain the word 'navigation'?

[bmag]

I'm glad it helps you 😄

This layer is specifically for configuring the imenu-list package, so I think it's best to call the layer imenu-list. The name of the package comes from Imenu, which is a built-in Emacs feature, so it is very indicative to users who already know about Imenu.

Sounds to me that your concern regards searching and discovering layers in Spacemacs in genereal, and isn't particular to imenu-list layer. I could have given the layer a "navigation" tag, if there was some tagging system for layers, but right I know of only these 3 ways to search for layers:

• browse the directory tree under the 'layers' directory. Has the advantage of seeing layer categories (e.g. "+lang" subdirectory is for programming language related layers)
• SPC f e h and search by layer name (e.g. search for "auto completion")
• SPC f e h and search by package name (e.g. search for "company-mode"). Good for when you know about a package and want to find out if it has a layer

Going over the docs, I found a short section about package discovery in QUICK_START.org and a section about discovering available layers in DOCUMENTATION.org, but they don't offer a new method of searching for layers that isn't listed above (they do offer a way to search for emacs packages via SPC a P, though).

@syl20bnr I think that @stshine raises an important concern, but maybe you have thought about it already?

[StreakyCobra]

@bmag So I tried your package :-) I like it, but I have a few question/remarks:

• After having pressed enter (i.e. being on the file again), would it be possible to have SPC b i renter the imenu-list instead of hiding it?
• A keybinding that I'm missing is TAB to expend/collapse a node
• A feature that I'm missing (but I don't know if it is possible at all), is when the cursor is moved in the file buffer, the imenu-list being updated and highlighting the current position in the structure.
• Last, when pressing d (or RET), is it possible to move the highlighted line on the top of the screen? If the selected position is after the current one, the line will be at bottom, so you can't read the function/code content. I already noticed this behaviour on other places, so it may be a more general Emacs configuration.

[bmag]

After having pressed enter (i.e. being on the file again), would it be possible to have SPC b i renter the imenu-list instead of hiding it?

It's possible to write something for this, but the current behaviour matches Neotree. IMHO it's better to keep consistency with Neotree on this one.

---

A keybinding that I'm missing is TAB to expend/collapse a node

You can use f ("fold") for that. TAB and SHIFT-TAB are meant to go up/down in imenu-list, you can open an issue upstream if you think that's the wrong default.

---

when the cursor is moved in the file buffer, the imenu-list being updated and highlighting the current position in the structure

That's already implemented with an idle timer of one second. If you wait one second without typing, the update should happen.

---

when pressing d (or RET), is it possible to move the highlighted line on the top of the screen?

Good idea. Should be possible globally for Imenu jumps (including imenu-list) with:

(add-hook 'imenu-after-jump-hook #'recenter) ;; also an option: reposition-window

Or just for imenu-list jumps:

(defun imenu-list-recenter ()
  (when (memq this-command '(imenu-list-display-entry imenu-list-goto-entry))
    (recenter)))

(add-hook 'imenu-after-jump-hook #'imenu-list-recenter)

In fact, I think I'll add it upstream 😄 (on Wednesday)

[StreakyCobra]

It's possible to write something for this, but the current behaviour matches Neotree. IMHO it's better to keep consistency with Neotree on this one.

Indeed, it annoyed me with neotree too, so I started using ranger 😉 I'll need to find a way on my side then.

---

You can use f ("fold") for that. TAB and SHIFT-TAB are meant to go up/down in imenu-list, you can open an issue upstream if you think that's the wrong default.

I saw for f, but intuitively I would have expected TAB for folding/unfolding, not going up/down. I'll open an issue then.

---

That's already implemented with an idle timer of one second. If you wait one second without typing, the update should happen.

Doesn't work here. I notice an error in *Messages* but enabling debug-on-error doesn't show a backtrace.

imenu-list--current-entry: Wrong type argument: number-or-marker-p, #<overlay from 123 to 3195 in init.el>

---

In fact, I think I'll add it upstream

Cool, I'll wait a little bit before adding it to my config then :-)

[bmag]

Doesn't work here.

Can you report an issue upstream for this as well? I suspect there's a bug in imenu-list that's triggered when Semantic is enabled.

EDIT: yep, found a bag with the same error you quoted

[StreakyCobra]

@bmag I'll report it then :-)

[stshine]

How about call this layer imenu-visual?

[nixmaniack]

I like this package and have been using it since long specially with pdf tools which displays nice outline in imenu-list. I did have same issues as @StreakyCobra mentioned about TAB not being used for [un]folding and position in imenu-list not being updated as I move in corresponding buffer.

[bmag]

@nixmaniack can you tell me the major-mode and value of imenu-create-index-function in the corresponding buffer? (preferably comment here or open a new issue upstream)

[mandarvaze]

Should I see any outline (the way @nixmaniack is seeing) in the org-mode file ?
The structure isn't fancy at all. Bunch of top level headlines (line starting with single star) is all.
But I don't see anything at all in imenu-list

[bmag]

@mandarvaze there are screenshots on the homepage. imenu-list should show the same entries as M-x imenu or any other imenu interface (such as helm-semantic-or-imenu).

[mandarvaze]

The reason I asked was because :

1. both screenshots are for python files (which is working for me anyway)
2. Last night, when I opened an org-mode file, imenu-list pane remained empty, but this morning, I see the outline fine.

[syl20bnr]

Very nice, I see this package in default distribution at some point sharing the same window as neotree with window-purpose.
I like SPC b i and it seems that you foresee the changes on SPC j since the same functionality is under SPC j i which matches perfectly :-)
I added support for golden-ratio and updated the README.

Thank you ! 👍
Cherry-picked into develop branch, you can safely delete your branch.

[JohnLunzer]

If this is not the appropriate forum for my question please let me know where would be the best place.

I find it unintuitive that the imenu list does not center the found entry in the edit buffer . I have tried to change this myself but I am so new to emacs and elisp that I can't figure it out.

Can somebody possibly guide me on how to make the imenu-list perform an evil-scroll-to-center after pressing RET in the imenu-list window?

[bmag]

If this is not the appropriate forum for my question please let me know where would be the best place.

It would be better to open a new issue at either spacemacs repository or imenu-list repository

how to make the imenu-list perform an evil-scroll-to-center after pressing RET in the imenu-list window

imenu-list uses imenu to perform the jump, so you can add evil-scroll-to-center to imenu-after-jump-hook, like so:

(add-hook 'imenu-after-jump-hook #'evil-scroll-to-center)

I've created a new issue upstream to add a specific hook for imenu-list, and I'll implement it when I get to it.

[JohnLunzer]

@bmag, thanks! I'm constantly amazed by the forward thinking towards extensibility that emacs has. Very easy to change the behavior.

Along these lines, the imenu-list layer doesn't integrate with the color theme besides "light" or "dark". Is there a way to get the colors to match the theme colors?

[bmag]

@JohnLunzer you can set the relevant faces via the theming layer. Run SPC h d F and type "imenu-list" to find all the relevant faces. Another option is to submit a patch to the theme you're using.

[JohnLunzer]

@bmag, thank you again. When I add the hook you specified (add-hook 'imenu-after-jump-hook #'evil-scroll-line-to-center) (you left out the -line part I think) earlier I am receiving an error message in the minibuffer:

Wrong number of arguments: #[(count) "i^X                                                                                                             
^Z^Y^K\203^Q^@eb\210^KSy\210ÄÅ!\210Æ^H!+\207" [col goal-column temporary-goal-column count recenter nil move-to-column] 2 ("/home/lunz/.emacs.d/elpa/evil-20160619.2253/evil-commands.elc" . 52113) (list (if current-prefix-arg (progn (prefix-numeric-value current-prefix-arg))))], 0

[bmag]

The problem here is that evil-scroll-line-to-center requires an argument, but functions hooked into imenu-after-jump-hook are called without any arguments. Instead, you should use recenter or one of the other suggestions in the documentation of imenu-after-jump-hook (see SPC h d v imenu-after-jump-hook). I wrote evil-scroll-to-center earlier because that's what you specifically asked for in your comment.

[JohnLunzer]

Ahh, recenter works perfectly! I appreciate your help and your patience.

I also see the value in SPC h d . Again, emacs and spacemacs amaze me by how much they build in to help the user.