{"id":13896125,"url":"https://github.com/gustavo-hms/peneira","last_synced_at":"2025-12-26T15:03:45.042Z","repository":{"id":43879816,"uuid":"388949585","full_name":"gustavo-hms/peneira","owner":"gustavo-hms","description":"A fuzzy finder crafted for Kakoune","archived":false,"fork":false,"pushed_at":"2024-11-07T08:25:31.000Z","size":4344,"stargazers_count":35,"open_issues_count":3,"forks_count":6,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-11-25T01:33:31.215Z","etag":null,"topics":["kakoune","lua","plugin"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-2.1","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gustavo-hms.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-07-23T23:18:42.000Z","updated_at":"2024-11-10T17:18:23.000Z","dependencies_parsed_at":"2024-11-07T09:23:54.372Z","dependency_job_id":"485fff57-7369-40d8-aa5a-103cc4175e43","html_url":"https://github.com/gustavo-hms/peneira","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/gustavo-hms/peneira","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gustavo-hms%2Fpeneira","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gustavo-hms%2Fpeneira/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gustavo-hms%2Fpeneira/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gustavo-hms%2Fpeneira/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gustavo-hms","download_url":"https://codeload.github.com/gustavo-hms/peneira/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gustavo-hms%2Fpeneira/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265606592,"owners_count":23796968,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["kakoune","lua","plugin"],"created_at":"2024-08-06T18:02:40.613Z","updated_at":"2025-12-26T15:03:45.032Z","avatar_url":"https://github.com/gustavo-hms.png","language":"Lua","funding_links":[],"categories":["Lua"],"sub_categories":[],"readme":"# Peneira\n\nPeneira is a fuzzy finder for the [Kakoune](https://kakoune.org) editor. You can\nuse it to write custom filters for candidates lists. You can also use its built-in\nfilters, that allow you to select files in a directory, symbols in the\ncurrent document, an so on.\n\n![](assets/peneira-files.gif)\n\nIt depends on the [luar](https://github.com/gustavo-hms/luar) plugin. So make\nsure you have it installed first.\n\n## Highlights\n\n### Multi-client support\n\nPeneira opens its panel in the focused client, and can have many panels working\nindependently, one for each client.\n\n![](assets/multiclient.png)\n\n### Multi-word search\n\nYou can search using multiple words separated by spaces. Each word matches from\nthe beginning of the line.\n\n![](assets/multiword.png)\n\n### It follows your colorscheme\n\n**Palenight**:\n\n![](assets/palenight.png)\n\n**[Garbo](https://github.com/gustavo-hms/garbo)**:\n\n![](assets/garbo.png)\n\n**Solarized-light**:\n\n![](assets/solarized-light.png)\n\n## Writting your own filter\n\nYou can use the `peneira` command to write a filter for yourself. For instance,\nhere is a simple `buffers` filter to go to a buffer in the buffer list:\n\n```kak\ndefine-command buffers %{\n    peneira 'buffers: ' %{ eval \"printf '%s\\n' $kak_quoted_buflist\" } %{\n        buffer %arg{1}\n    }\n}\n```\n\nThe `peneira` command expects 3 arguments:\n\n* a text to show in the prompt;\n* a shell command that, when executed, will generate a list of candidates (one\n  per line);\n* a block of Kakoune commands to execute after the user has selected a line.\n\nInside the commands block, the `%arg{1}` expansion refers to the selected line.\n\nBy default, `peneira` ranks the candidates according to an internal score,\nshowing first the results it thinks the user intended. If you want that it respects\nthe candidates order instead, you can pass the `-no-rank` switch:\n\n```kak\npeneira -no-rank 'buffers: ' %{ printf '%s\\n' $kak_quoted_buflist } %{\n    buffer %arg{1}\n}\n```\n\n## Built-in filters\n\nPeneira also comes with predefined filters you can use at will.\n\n### peneira-symbols\n\nThe `peneira-symbols` filter lists the symbols defined in the current file. You\ncan use it to quickly navigate in your code structure. It requires [Universal\nCtags](https://ctags.io) compiled with JSON support.\n\n![](assets/peneira-symbols.gif)\n\n### peneira-lines\n\nThe `peneira-lines` filter lists lines in the current file. Use it to quickly go\nto a specific line in your document.\n\n![](assets/peneira-lines.gif)\n\n### peneira-files\n\nThe `peneira-files` filter lists files in the current directory, recursively.\n\nIf the switch `-hide-opened` is passed, it ignores already opened files,\nremoving them from the candidates list.\n\nBy default, `peneira-files` uses [fd](https://github.com/sharkdp/fd) to get the list of files. You can change\nthat by editing `peneira_files_command` option, e.g.:\n\n```kak\nset-option global peneira_files_command \"find .\"\n```\n\nOr even\n\n```kak\nset-option global peneira_files_command \"rg --files\"\n```\n\n### peneira-local-files\n\nThe `peneira-local-files` filter works like `peneira-files`, except that it uses\nthe directory of the currently edited file as the root directory.\n\n### peneira-mru\n\nIf you have [mru-files](https://gitlab.com/kstr0k/mru-files.kak) installed,\nPeneira will detect it and automatically enable the `peneira-mru` filter, which\nlists recently opened files in the subtree of the current working directory.\nThis way, you can easily jump to the most recently used files of the project you\nare currently working on.\n\nThe `-global` switch disables the restriction for files inside the current working directory.\nThis will cause the full file paths to be shown.\nIf you want to strip the current working directory from file paths inside it, you can pass the `-strip-cwd` switch.\nFiles outside the current working directory will still be shown with their full paths.\n\nHint: for this command to work best, try increasing the history size of the MRU plugin:\n\n```kak\nset-option global mru_files_max 100\n```\n\n## Installation\n\nRemember peneira requires [luar](https://github.com/gustavo-hms/luar). If you use [Almoxarife](https://github.com/gustavo-hms/almoxarife), you can make this dependency explicit:\n\n```yaml\nluar:\n  location: https://github.com/gustavo-hms/luar\n\n  peneira:\n    location: https://github.com/gustavo-hms/peneira\n```\n\nIf, on the other hand, you use [kak-bundle](https://codeberg.org/jdugan6240/kak-bundle), add this to your `kakrc`:\n\n```kak\nbundle luar \"gustavo-hms/luar\" %{\n  require-module luar\n}\n\nbundle peneira \"gustavo-hms/peneira\" %{\n  require-module peneira\n}\n```\n\n\n## Performance tips\n\nPeneira is fast. It should perform well in most cases. However, since everything\nhappens synchronously, you may experience performance issues on large candidates\nlist. If that's the case, try configuring Luar to use `luajit` instead:\n\n```kak\nset-option global luar_interpreter luajit\n```\n\n## Customization\n\nPeneira follows your colorscheme, so it should fit well in your configuration.\nBut, if you want, you can customize some aspects of its appearance, but\noverwriting the following faces:\n\n* `PeneiraSelected`: used to highlight the selected line;\n* `PeneiraFlag`: the appearance of the flag in the left side of the selected line;\n* `PeneiraMatches`: used to highlight matched characters.\n* `PeneiraFileName`: used to highlight the file name on `peneira-files` and `peneira-local-files`.\n\nFor example:\n\n```kak\nset-face global PeneiraMatches +ui\n```\n\n## Caveats\n\nPeneira tries to remove line numbers when showing candidates, for a cleaner and\nmore immersive experience. But, due to how highlighters work on Kakoune, you must\nname the `number-lines` highlighter (if you use it) _exactly_\n`window/number-lines`, like so:\n\n```kak\nadd-highlighter window/number-lines number-lines\n```\n\nOr, say:\n\n```kak\nadd-highlighter window/number-lines number-lines -separator ' ' -hlcursor\n```\n\nOr even:\n\n```kak\nadd-highlighter window/number-lines number-lines -separator ' ' -hlcursor -min-digits 3\n```\n\nThe important thing is that it's named `window/number-lines`, otherwise peneira\nwon't be able to remove it.\n\n## Third-party filters\n\nYou can find a selection of some custom filters implemented by Marko Bauhardt [here](https://codeberg.org/mbauhardt/peneira-filters).\n\n## Acknowledgement\n\nMany thanks to swarn for [porting the fzy algorithm to lua](https://github.com/swarn/fzy-lua).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgustavo-hms%2Fpeneira","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgustavo-hms%2Fpeneira","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgustavo-hms%2Fpeneira/lists"}