fzf-native

fzf-native copied to clipboard

#+TITLE: fzf-native #+STARTUP: noindent

[[https://github.com/dangduc/fzf-native/actions/workflows/test.yaml][https://github.com/dangduc/fzf-native/actions/workflows/test.yaml/badge.svg]] [[https://github.com/dangduc/fzf-native/actions/workflows/cmake.yaml][https://github.com/dangduc/fzf-native/actions/workflows/cmake.yaml/badge.svg]] [[https://github.com/dangduc/fzf-native/actions/workflows/format.yaml][https://github.com/dangduc/fzf-native/actions/workflows/format.yaml/badge.svg]]

This is a package that provides fuzzy match scoring based on the fzf algorithm by [[https://github.com/junegunn][junegunn]]. The main contribution is a wrapper over the C implementation of fzf from the project [[https://github.com/nvim-telescope/telescope-fzf-native.nvim][telescope-fzf-native.nvim]]. Elisp functions for scoring are exported through an Emacs dynamic module.

This package /does one thing/ -- For a given STR and QUERY compute and return a score and matching indices. If you're looking for a fuzzy auto-completion engine, see the Use Cases section for how this package can be used in a ~completion-style~.

#+begin_src emacs-lisp ;; Example of basic usage (fzf-native-score "Hot-Topic" "hp") ;; (41 0 6) #+end_src

#+begin_src emacs-lisp ;; Example of no match (fzf-native-score "Hot-Topic" "2") ;; (0) #+end_src

#+begin_src emacs-lisp ;; Example of slab re-use (let ((slab (fzf-native-make-default-slab))) (fzf-native-score "Hello World" "er" slab) (fzf-native-score "Example of slab re-use" "xu" slab)) ;; (24 1 19) #+end_src

See [[fzf-native-test.el][test cases]] for more examples.

** Supported Platforms

Linux, macOS (incl. Apple silicon), and Windows are supported. Pre-built shared libraries are in the [[bin][bin/]] directory.

** Installation

*** MELPA

Not yet on MELPA.

*** Manually

Clone / download this repository and modify your ~load-path~:

#+begin_src emacs-lisp (add-to-list 'load-path (expand-file-name "/path/to/fzf-native/" user-emacs-directory)) #+end_src

*** Straight Examples

#+begin_src emacs-lisp ; Configuration that builds dynamic module locally. (use-package fzf-native :straight (:repo "dangduc/fzf-native" :host github :files (:defaults ".c" ".h" "*.txt")) :init (setq fzf-native-always-compile-module t) :config (fzf-native-load-own-build-dyn)) #+end_src

#+begin_src emacs-lisp ; Configuration that uses pre-built dynamic module. (use-package fzf-native :straight (:repo "dangduc/fzf-native" :host github :files (:defaults "bin")) :config (fzf-native-load-dyn)) #+end_src

*** Multibyte character support

Work around the lib's lack of support for multibyte chars. Add this advice if you want accurate indices for multibyte chars. Don't add this advice if you want better run time performance or you don't need accurate indices for multibyte chars.

#+begin_src emacs-lisp (advice-add 'fzf-native-score :around #'fzf-native--fix-score-indices) #+end_src

** Use Cases

[[https://github.com/jojojames/fussy][Fussy]]: ~fzf-native~ is used as one of several choose-your-own scoring backends in ~fussy~, a package that provides a ~completing-style~ for intelligent matching and sorting.

** Building the Native Libraries

#+begin_src bash mkdir build && cmake -B build -DCMAKE_C_FLAGS='-O3 -march=native' && cmake --build build #+end_src

** Credit All credit for fzf.c goes to the [[https://github.com/nvim-telescope/telescope-fzf-native.nvim][telescope-fzf-native.nvim]] project. Much credit for Emacs module binding code goes to the [[https://github.com/axelf4/hotfuzz][hotfuzz]] project.