Custom filter in plugin `gustavo-hms/peneira`

i’m using the plugin gustavo-hms/peneira to open files, buffer or search in the current open file.
I want to use the plugin to grep for file candidates to open. based on the docu GitHub - gustavo-hms/peneira: A fuzzy finder crafted for Kakoune I can write my own filter, but a filter which gets an argument. e.g.

define-command peneira-grep -params 1 %{
    peneira 'files: ' %{ printf '%s\n' rg --files-with-matches $1} %{
        edit %arg{1}

the problem I have i’m not getting the peneira command parametrized. I tried $1, %arg{1}, %arg(1)
nothing worked.
is it not working because params are not supported by paneira?
has anyone from you experience to write a custom peneira filter?


If you say:

define-command peneira-grep -params 1 %{

…then inside that block, %arg{1} will expand to the peneira-grep command’s argument.

However, Kakoune does not always expand such things. In the example you give, the peneira command has three arguments:

  • 'files: ' to show as a prompt
  • %{ printf '%s\n' rg --files-with-matches $1 } the shell-script to generate candidates
  • %{ edit %arg{1} } the Kakoune command to execute with the chosen candidate

According to Kakoune’s command parsing documentation, single-quoted strings and %{} strings are not expanded, but double-quoted strings are. So you should be able to change your shell-script argument to be:

"printf '%%s\n' rg --files-with-matches '%arg{1}'"

Note that the %s was changed to %%s because otherwise Kakoune would try to expand it. Also, $1 was changed to %arg{1} because that’s the Kakoune expansion for the first argument. Even though it’s being used in a shell-script, we need Kakoune to do the expansion to produce the shell-scipt. I also put it in single-quotes because a regex often includes shell-special characters like backslashes and asterisks that would break things. If your regex contains a single-quote, this will break too, but properly shell-quoting a regex is more complex than will fit in this comment.

1 Like

Hi, @mbauhardt !

@Screwtapello already gave an explanation about how Kakoune parses commands. But there’s yet an additional point preventing your code to work properly: I tried my best to make shell expansions (like the $1 above) work as expected and they usually work. For instance, the snippet bellow does work:

peneira 'buffer: ' "printf '%%s\n' $kak_bufflist" %{
    edit %arg{1}

But achieving that involved some hacks. As a consequence, the expansions involving arguments ($1, $2 and the like) don’t work. I mean, they do work, but expand arguments of an internal command of the plugin.

To achieve the same result, you can use %arg{1} instead (as Screwtapello suggested):

define-command peneira-grep -params 1 %{
    peneira 'files: ' "rg --files-with-matches %arg{1}" %{
        edit %arg{1}

Note there’s no need for printf.

If you also want it to open the file in the place where the match occurs, you can use this tip:

define-command peneira-grep -params 1 %{
    peneira 'line: ' "rg --column %arg{1}" %{
        lua %arg{1} %{
            local file, line, column = arg[1]:match("([^:]+):(%d+):(%d+):")
            kak.edit(file, line, column)

Hope it helps.


You are awesome! You saved my day.
especially the last code snipped does exact what I want.

  • fast
  • tiny preview
  • fzy algorithm helps to shrink the list of candidates as “I” expect to shrink

grepping with a parameter is fast, compared to without a param. without a param the searching is pretty slow and not usable, when having a huge list of candidates.

Awesome, this helps to be productive at work!

btw… @gustavo-hms why not having this as a builtin filter?

I was (perhaps quite naively) expecting people would publish their own custom filters for the good of the whole community. Maybe we could see the rise of new creative uses of peneira.

In the past, I was a user of the venerable unite plugin for Vim, and it was great (a source of inspiration for peneira actually). One of the most interesting things about it was that people started writing 3rd party integrations for it, increasing its original capabilities.

Since peneira’s API is way simpler than unite’s, my expectations were that we could see new filters being published by the community.

That’s why I took the responsibility to write some more complicated filters myself, like peneira-symbols (my favorite) and peneira-lines, and leave easier-to-write ones (like, say, hypothetical peneira-buffers and peneira-grep) as exercises to the community.

I don’t know… it’s not clear to me why people didn’t do it. Perhaps it’s because vim user base is way bigger than ours; or perhaps our culture doesn’t favor working as a united and strong community as much as I would like.

But there’s still time! If you want to publish it (and maybe other new filters) yourself, I would be happy to guide you in the implementation and to link the project in the README of peneira.

I’m coming from Plugins · martanne/vis Wiki · GitHub which has a small community.
Having a huge community around a project is pretty helpful. So I definitely see your point and idea about a peneira user base.

So here is peneira-filters with

  • the grep filter we talked about in this thread.
  • the buffer filter from your docu
  • And I added one more filter :wink: - Which helps me to open one of my git projects.
    This filter is pretty helpful in my daily worklife. And it was so easy and quick to write it.

Thx @gustavo-hms to drive this idea.
If you have suggestions/improvements for mbauhardt/peneira-filters: Additional custom filters for the kakoune plugin gustavo-hms/peneira - peneira-filters -, feel free to open issues/PR’s there.



Nice! Thanks for your contribution. I’ve already linked your project in the README.

If you have suggestions/improvements for mbauhardt/peneira-filters

My first suggestion is that you write proper documentation :slightly_smiling_face:, otherwise the project won’t be so useful for the community. There are two places where documentation can leave: in the README, for people understand what your filters do before installing them; and inline in the commands themselves.

The later is done using the -docstring flag of define-command, more or less like this:

define-command my-cool-command -params 1 -docstring %{
    my-cool-command <cool-argument>: do cool stuff based on the value of <cool-argument>
} %{
    # ...

The docstring will then appear in a Kakoune’s info box:

sorry for the delay.

I refactored the peneira-filters project into kakoune module structure. Because I’m new to kakoune the implementation could be a bit messy. anyway. I eat my own dog food - using it every day. I’m quit satisfied except some minor changes I plan todo.

I updated the documentation to understand why this project is there and what is the project doing. incl gif’s to show it.
There is also now a mirror on github GitHub - mbauhardt/peneira-filters: Mirror of, it can be find under the kakoune search.

Btw: @gustavo-hms I used your peneira-symbols, awesome! Very helpful as well to browse through code.