diff options
| -rw-r--r-- | README.org | 40 | ||||
| -rw-r--r-- | orderless.texi | 57 |
2 files changed, 70 insertions, 27 deletions
@@ -10,7 +10,7 @@ [[https://stable.melpa.org/#/orderless][file:https://stable.melpa.org/packages/orderless-badge.svg]] :END: -* COMMENT Overview +* Overview :PROPERTIES: :TOC: :include all :ignore this :END: @@ -28,45 +28,38 @@ used with the default Emacs completion UI (sometimes called minibuffer tab completion) or with the built-in Icomplete package (which is similar to the more well-known Ido Mode). To use a completion style in this fashion simply add it as an entry in the variables -=completion-styles= or =completion-category-overrides= (see their -documentation). Note that there is also the variable -=completion-category-defaults= which configures some completion styles -for special kinds of completion by default. If you want to use /only/ -orderless, set that variable to nil. +=completion-styles= and =completion-category-overrides= (see their +documentation). With a bit of effort, it might still be possible to use =orderless= with other completion UIs, even if those UIs don't support the standard -Emacs completion styles. Currently there is support for [[https://github.com/raxod502/selectrum][Selectrum]] and -[[https://github.com/abo-abo/swiper][Ivy]] (see below). +Emacs completion styles. Currently there is support for [[https://github.com/abo-abo/swiper][Ivy]] and +[[https://github.com/raxod502/selectrum][Selectrum]] (see below). + +If you use MELPA, the easiest way to install =orderless= is via +=package-install=. If you use both MELPA and =use-package=, you can use: #+begin_src emacs-lisp (use-package orderless :ensure t - :init (icomplete-mode) ; optional but recommended - :custom - (completion-styles '(orderless)) - (completion-category-defaults nil)) ; optional + :init (icomplete-mode) ; optional but recommended! + :custom (completion-styles '(orderless))) #+end_src Alternatively, put =orderless.el= somewhere on your =load-path=, and use the following configuration: -If you use MELPA, the easiest way to install =orderless= is via -=package-install=. If you use both MELPA and =use-package=, you can use: - #+begin_src emacs-lisp - (require 'orderless) - (setq completion-styles '(orderless) - completion-category-defaults nil) ; optional - (icomplete-mode) ; optional but recommended +(require 'orderless) +(setq completion-styles '(orderless)) +(icomplete-mode) ; optional but recommended! #+end_src (And of course, if you use another completion framework such as Ivy or Helm, disable it.) If you like the experience of using =orderless= with Icomplete, but wish -the candidates displayed vertically, you can use [[https://github.com/oantolin/icomplete-vertical][icomplete-vertical]], -[[https://github.com/raxod502/selectrum][Selectrum]] or [[https://github.com/abo-abo/swiper][Ivy]]. +the candidates displayed vertically, you can use [[https://github.com/oantolin/icomplete-vertical][icomplete-vertical]]. Bug reports are highly welcome and appreciated! @@ -360,9 +353,8 @@ To use =orderless= from Ivy add this to your Ivy configuration: ** Selectrum -Recent versions of Selectrum use your configured completion styles by -default! To use =orderless= from Selectrum, you can either stick to that -default or add this to your Selectrum configuration: +To use =orderless= from Selectrum add this to your Selectrum +configuration: #+begin_src emacs-lisp (setq selectrum-refine-candidates-function #'orderless-filter) diff --git a/orderless.texi b/orderless.texi index c1dc217..0aa29c6 100644 --- a/orderless.texi +++ b/orderless.texi @@ -25,6 +25,7 @@ @end ifnottex @menu +* Overview:: * Customization:: * Integration with other completion UIs:: * Related packages:: @@ -59,6 +60,57 @@ Related packages @end detailmenu @end menu +@node Overview +@chapter Overview + +This package provides an @samp{orderless} @emph{completion style} that divides the +pattern into space-separated components, and matches candidates that +match all of the components in any order. Each component can match in +any one of several ways: literally, as a regexp, as an initialism, in +the flex style, or as multiple word prefixes. By default, regexp and +initialism matches are enabled. + +A completion style is a back-end for completion and is used from a +front-end that provides a completion UI@. Any completion style can be +used with the default Emacs completion UI (sometimes called minibuffer +tab completion) or with the built-in Icomplete package (which is +similar to the more well-known Ido Mode). To use a completion style in +this fashion simply add it as an entry in the variables +@samp{completion-styles} and @samp{completion-category-overrides} (see their +documentation). + +With a bit of effort, it might still be possible to use @samp{orderless} with +other completion UIs, even if those UIs don't support the standard +Emacs completion styles. Currently there is support for @uref{https://github.com/abo-abo/swiper, Ivy} and +@uref{https://github.com/raxod502/selectrum, Selectrum} (see below). + +If you use MELPA, the easiest way to install @samp{orderless} is via +@samp{package-install}. If you use both MELPA and @samp{use-package}, you can use: + +@lisp +(use-package orderless + :ensure t + :init (icomplete-mode) ; optional but recommended! + :custom (completion-styles '(orderless))) +@end lisp + +Alternatively, put @samp{orderless.el} somewhere on your @samp{load-path}, and use +the following configuration: + +@lisp +(require 'orderless) +(setq completion-styles '(orderless)) +(icomplete-mode) ; optional but recommended! +@end lisp + +(And of course, if you use another completion framework such as Ivy or +Helm, disable it.) + +If you like the experience of using @samp{orderless} with Icomplete, but wish +the candidates displayed vertically, you can use @uref{https://github.com/oantolin/icomplete-vertical, icomplete-vertical}. + +Bug reports are highly welcome and appreciated! + @node Customization @chapter Customization @@ -369,9 +421,8 @@ To use @samp{orderless} from Ivy add this to your Ivy configuration: @node Selectrum @section Selectrum -Recent versions of Selectrum use your configured completion styles by -default! To use @samp{orderless} from Selectrum, you can either stick to that -default or add this to your Selectrum configuration: +To use @samp{orderless} from Selectrum add this to your Selectrum +configuration: @lisp (setq selectrum-refine-candidates-function #'orderless-filter) |