branch: externals/orderless
commit 8867200d5d2942c4d6960e03f6c5248f5d138681
Merge: f2c78c4a60 c73716ecc9
Author: Omar Antolín Camarena <[email protected]>
Commit: GitHub <[email protected]>
Merge pull request #112 from minad/doc-update
Use (orderless basic) as completion-styles (Fix #111)
---
README.org | 40 ++++++++++++++++++++++++++--------------
orderless.texi | 28 ++++++++++++++++++++--------
2 files changed, 46 insertions(+), 22 deletions(-)
diff --git a/README.org b/README.org
index a508befa1c..b360c3973d 100644
--- a/README.org
+++ b/README.org
@@ -26,13 +26,11 @@ 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), with the built-in Icomplete package (which is similar
-to the more well-known Ido Mode), or with some third party minibuffer
-completion frameworks such as [[https://github.com/minad/vertico][Vertico]],
[[https://github.com/raxod502/selectrum][Selectrum]] (in its default
-configuration), or
[[https://github.com/oantolin/icomplete-vertical][icomplete-vertical]] (note
there is also a /built-in/
-package named icomplete-vertical in the unreleased version 28 of
-Emacs, which will eventually make the third party icomplete-vertical
-obsolete ---orderless works equally well with both icomplete-vertical
-packages).
+to the more well-known Ido Mode), the icomplete-vertical variant from
+Emacs 28 (see the external
[[https://github.com/oantolin/icomplete-vertical][icomplete-vertical]] package
to get that
+functionality on earlier versions of Emacs), or with some third party
+minibuffer completion frameworks such as
[[https://gitlab.com/protesilaos/mct][Mct]],
[[https://github.com/minad/vertico][Vertico]], or
[[https://github.com/raxod502/selectrum][Selectrum]]
+(in its default configuration).
All the completion UIs just mentioned are for minibuffer completion,
used when Emacs commands prompt the user in the minibuffer for some
@@ -62,17 +60,31 @@ If you use ELPA or MELPA, the easiest way to install
=orderless= is via
#+begin_src emacs-lisp
(use-package orderless
:ensure t
- :custom (completion-styles '(orderless)))
+ :custom
+ (completion-styles '(orderless basic))
+ (completion-category-overrides '((file (styles basic
partial-completion)))))
#+end_src
Alternatively, put =orderless.el= somewhere on your =load-path=, and use
the following configuration:
#+begin_src emacs-lisp
-(require 'orderless)
-(setq completion-styles '(orderless))
+ (require 'orderless)
+ (setq completion-styles '(orderless basic)
+ completion-category-overrides '((file (styles basic
partial-completion))))
#+end_src
+The =basic= completion style is specified as fallback in addition to
+=orderless= in order to ensure that completion commands which rely on
+dynamic completion tables, e.g., ~completion-table-dynamic~ or
+~completion-table-in-turn~, work correctly. Furthermore the =basic=
+completion style needs to be tried /first/ (not as a fallback) for TRAMP
+hostname completion to work. In order to achieve that, we add an entry
+for the =file= completion category in the =completion-category-overrides=
+variable. In addition, the =partial-completion= style allows you to use
+wildcards for file completion and partial paths, e.g., ~/u/l/s~ for
+~/usr/share/local~.
+
Bug reports are highly welcome and appreciated!
:CONTENTS:
@@ -407,7 +419,7 @@ install Helm and configure Icomplete to use it as follows:
#+begin_src emacs-lisp
(require 'helm)
- (setq completion-styles '(helm))
+ (setq completion-styles '(helm basic))
(icomplete-mode)
#+end_src
@@ -417,9 +429,9 @@ install Helm and configure Icomplete to use it as follows:
** Prescient
The [[https://github.com/raxod502/prescient.el][prescient.el]] library also
provides matching of space-separated
-components in any order and it can be used with either the
[[https://github.com/raxod502/selectrum][Selectrum]]
-or [[https://github.com/abo-abo/swiper][Ivy]] completion UIs (it does not
offer a completion-style that
-could be used with Emacs' default completion UI or with Icomplete).
+components in any order and it can be used with either the
[[https://github.com/raxod502/selectrum][Selectrum]] or
+[[https://github.com/abo-abo/swiper][Ivy]] completion UIs (it does not offer a
completion-style that could be
+used with Emacs' default completion UI, Mct, Vertico or with Icomplete).
The components can be matched literally, as regexps, as initialisms or
in the flex style (called "fuzzy" in prescient). In addition to
matching, =prescient.el= also supports sorting of candidates (=orderless=
diff --git a/orderless.texi b/orderless.texi
index 92d6d5771d..732562e83b 100644
--- a/orderless.texi
+++ b/orderless.texi
@@ -76,7 +76,7 @@ front-end that provides a completion UI@. Any completion
style can be
used with the default Emacs completion UI (sometimes called minibuffer
tab completion), with the built-in Icomplete package (which is similar
to the more well-known Ido Mode), or with some third party minibuffer
-completion frameworks such as @uref{https://github.com/minad/vertico,
Vertico}, @uref{https://github.com/raxod502/selectrum, Selectrum} (in its
default
+completion frameworks such as @uref{https://gitlab.com/protesilaos/mct, Mct},
@uref{https://github.com/minad/vertico, Vertico},
@uref{https://github.com/raxod502/selectrum, Selectrum} (in its default
configuration), or @uref{https://github.com/oantolin/icomplete-vertical,
icomplete-vertical} (note there is also a @emph{built-in}
package named icomplete-vertical in the unreleased version 28 of
Emacs, which will eventually make the third party icomplete-vertical
@@ -111,7 +111,9 @@ If you use ELPA or MELPA, the easiest way to install
@samp{orderless} is via
@lisp
(use-package orderless
:ensure t
- :custom (completion-styles '(orderless)))
+ :custom
+ (completion-styles '(orderless basic))
+ (completion-category-overrides '((file (styles basic partial-completion)))))
@end lisp
Alternatively, put @samp{orderless.el} somewhere on your @samp{load-path}, and
use
@@ -119,9 +121,19 @@ the following configuration:
@lisp
(require 'orderless)
-(setq completion-styles '(orderless))
+(setq completion-styles '(orderless basic)
+ completion-category-overrides '((file (styles basic
partial-completion))))
@end lisp
+The @samp{basic} completion style is specified as fallback in addition to
@samp{orderless} in
+order to ensure that completion commands which rely on dynamic completion
+tables, e.g., @code{completion-table-dynamic} or
@code{completion-table-in-turn}, work
+correctly. Furthermore the @samp{basic} completion style is needed by Tramp
hostname
+completion for the @samp{file} completion category in the
+@samp{completion-category-overrides}. In addition, the
@samp{partial-completion} style allows
+you to use wildcards for file completion and partial paths, e.g.,
@code{/u/l/s} for
+@code{/usr/share/local}.
+
Bug reports are highly welcome and appreciated!
@node Customization
@@ -484,7 +496,7 @@ install Helm and configure Icomplete to use it as follows:
@lisp
(require 'helm)
-(setq completion-styles '(helm))
+(setq completion-styles '(helm basic))
(icomplete-mode)
@end lisp
@@ -495,11 +507,11 @@ install Helm and configure Icomplete to use it as follows:
@section Prescient
The @uref{https://github.com/raxod502/prescient.el, prescient.el} library also
provides matching of space-separated
-components in any order and it can be used with either the
@uref{https://github.com/raxod502/selectrum, Selectrum}
-or @uref{https://github.com/abo-abo/swiper, Ivy} completion UIs (it does not
offer a completion-style that
-could be used with Emacs' default completion UI or with Icomplete).
+components in any order and it can be used with either the
@uref{https://github.com/raxod502/selectrum, Selectrum} or
+@uref{https://github.com/abo-abo/swiper, Ivy} completion UIs (it does not
offer a completion-style that could be
+used with Emacs' default completion UI, Mct, Vertico or with Icomplete).
The components can be matched literally, as regexps, as initialisms or
-in the flex style (called ``fuzzy'' in prescient). In addition to
+in the flex style (called "fuzzy" in prescient). In addition to
matching, @samp{prescient.el} also supports sorting of candidates
(@samp{orderless}
leaves that up to the candidate source and the completion UI).
