[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/orderless 09f4c74280 105/204: Update dispatchers docume
From: |
ELPA Syncer |
Subject: |
[elpa] externals/orderless 09f4c74280 105/204: Update dispatchers documentation, add transient vars |
Date: |
Tue, 11 Jan 2022 12:58:21 -0500 (EST) |
branch: externals/orderless
commit 09f4c7428041a25bc486a78334d6b917dd7da34d
Author: Omar Antolín <omar.antolin@gmail.com>
Commit: Omar Antolín <omar.antolin@gmail.com>
Update dispatchers documentation, add transient vars
---
README.org | 159 +++++++++++++++++++++++++++++++++++++++++++++----------------
1 file changed, 117 insertions(+), 42 deletions(-)
diff --git a/README.org b/README.org
index 22593e1385..a880ea01d7 100644
--- a/README.org
+++ b/README.org
@@ -56,9 +56,11 @@ Bug reports are highly welcome and appreciated!
- [[#screenshot][Screenshot]]
- [[#customization][Customization]]
- [[#component-matching-styles][Component matching styles]]
+ - [[#style-dispatchers][Style dispatchers]]
- [[#component-separator-regexp][Component separator regexp]]
- [[#faces-for-component-matches][Faces for component matches]]
- - [[#style-dispatchers][Style dispatchers]]
+ - [[#pattern-compiler][Pattern compiler]]
+ - [[#interactively-changing-the-configuration][Interactively changing the
configuration]]
- [[#related-packages][Related packages]]
- [[#ivy-and-helm][Ivy and Helm]]
- [[#prescient][Prescient]]
@@ -131,9 +133,76 @@ define new matching styles. The predefined ones are:
For example, =re-re= matches =query-replace-regexp=, =recode-region= and
=magit-remote-list-refs=; =f-d.t= matches =final-draft.txt=.
-The variable =orderless-component-matching-styles= should be set to a
-list of the desired styles to use. By default it enables the regexp
-and initialism styles.
+The variable =orderless-component-matching-styles= can be set to a list
+of the desired matching styles to use. By default it enables the
+regexp and initialism styles.
+
+That variable, in addition to matching styles, can contain dispatchers
+that can change which styles are used depending on the actual input
+string.
+
+*** Style dispatchers
+
+ For more fine-grained control on which matching styles to use for
+ each component of the input string, you can add use /style
+ dispatchers/. These are specificied in the
+ =orderless-component-matching-styles= whose full syntax is:
+
+ =(= /matching-styles/...
+ =:global-dispatchers= /global-dispatchers/...
+ =:component-dispatchers= /component-dispatchers/... =)=
+
+ There are two types of style dispatchers:
+
+ - /global style dispatchers/, which are functions that take the entire
+ input string and are used to determine which matching styles to use
+ by default for each component; and
+
+ - /component style dispatchers/, which take a component, its index in
+ the list of components (starting from 0), and the total number of
+ components, and are used to determine the matching styles used for
+ that specific component, overriding the default matching styles.
+
+ A style dispatcher can either decline to handle the input string or
+ component, or it can return which matching styles to use. It can
+ also, if desired, additionally return a new string to use in place of
+ the given one. Consult the documentation of =orderless-dispatch= for
+ full details.
+
+ As an example, say you wanted the following setup:
+
+ - you normally want components to match as regexps,
+ - but if you end the string with =!= you want the default to be that
+ components (of the string left removing the final =!=) match
+ literally,
+ - except for the first component, which should always match as an
+ initialism ---this is pretty useful for, say,
+ =execute-extended-command= (=M-x=) or =describe-function= (=C-h f=),
+ - and any later component ending in =~= should match (the characters
+ other than the final =~=) in the flex style.
+
+ You can achieve this with the following configuration:
+
+ #+begin_src emacs-lisp
+ (defun flex-if-twiddle (pattern _index _total)
+ (when (string-suffix-p "~" pattern)
+ `(orderless-flex . ,(substring pattern 0 -1))))
+
+ (defun literal-if-bang (pattern)
+ (when (string-suffix-p "!" pattern)
+ `(orderless-literal . ,(substring pattern 0 -1))))
+
+ (defun first-initialism (pattern index _total)
+ (if (= index 0) 'orderless-initialism))
+
+ (setq orderless-component-matching-styles
+ '(orderless-regexp orderless-initialism orderless-prefixes))
+
+ (setq orderless-component-matching-styles
+ '(orderless-regexp
+ :global-dispatchers literal-if-bang
+ :component-dispatchers first-initialism flex-if-twiddle))
+ #+end_src
** Component separator regexp
@@ -171,53 +240,59 @@ tries each completion style in turn and uses the first
one returning
matches. You will only see these particular faces when the =orderless=
completion is the one that ends up being used, of course.
-** Style dispatchers
-
-For more fine-grained control on which matching styles to use for each
-component of the input string, you can use the =orderless-style-dispatchers=
-variable, which should be set to list of /style dispatchers/.
-
-A style dispatcher is a function of three arguments, a string and two
-integers. It is called with each component of the input string, the
-component's index (starting from 0), and the total number of
-components. It can either decline to handle the component or return
-which matching styles to use for it. It can also, if desired,
-additionally return a new string to use in place of the
-component. Consult the documentation of =orderless-style-dispatchers=
-for full details.
+** Pattern compiler
-As an example, say you wanted the following setup:
+The default machanism for turning an input string into a list of
+regexps to match against, configured using
+=orderless-component-matching-styles=, is probably flexible enough for
+the vast majority of users. But if you want to completely change the
+mechanism, customize the =orderless-pattern-compiler=. It's value should
+be a function from string to lists of regexps.
+
+** Interactively changing the configuration
+
+You might want to change the separator or the matching style
+configuration on the fly while matching. There many possible UIs for
+this: you could toggle between two chosen configurations, cycle among
+several, have a keymap where each key sets a different configurations,
+have a set of named configurations and be prompted (with completion)
+for one of them, popup a [[https://github.com/abo-abo/hydra][hydra]] to choose
a configuration, etc.
+
+Rather than include commands for any of those on-the-fly configuration
+changes, =orderless= provides a general mechanism to make it easy to
+write such commands yourself. There are two "override" variables:
+
+- =orderless-transient-matching-styles= which, if non-nil, overrides
+ =orderless-component-matching-styles=, and
+- =orderless-transient-component-separator= which, if non-nil,
+ overrides =orderless-component-separator=.
+
+You can write your own commands to set these transient variable to the
+desired value without clobbering the value of the variables they
+override. To set them to =nil= again after each completion session, use
+the following configuration:
-- you want the first component to match as an initialism and
- subsequent components to match literally ---this is pretty useful for,
- say, =execute-extended-command= (=M-x=) or =describe-function= (=C-h f=).
-- except that any component ending in =~= should match (the characters
- other than the final =~=) in the flex style.
+#+begin_src emacs-lisp
+ (add-hook 'minibuffer-exit-hook
+ #'orderless-remove-transient-configuration)
+#+end_src
-You can achieve this with the following configuration:
+For example, say you want to use the keybinding =C-l= to make all
+components match literally. You could use the following configuration:
#+begin_src emacs-lisp
- (defun flex-if-twiddle (pattern _index _total)
- (when (string-suffix-p "~" pattern)
- `(orderless-flex . ,(substring pattern 0 (1- (length pattern))))))
+ (defun my/match-components-literally ()
+ "Components match literally for the rest of the session."
+ (interactive)
+ (setq orderless-transient-matching-styles '(orderless-literal)))
- (defun first-initialism-then-literal (pattern index _total)
- (if (= index 0) 'orderless-initialism 'orderless-literal))
+ (add-hook 'minibuffer-exit-hook
+ #'orderless-remove-transient-configuration)
- (setq orderless-style-dispatchers
- '(flex-if-twiddle first-initialism-then-literal))
+ (define-key minibuffer-local-completion-map (kbd "C-l")
+ #'my/match-components-literally)
#+end_src
-** Pattern compiler
-
-The default machanism for turning an input string into a list of
-regexps to match against, using =orderless-component-separator=,
-=orderless-component-matching-styles= and
-=orderless-style-dispatchers=, is probably fleixble enough for the
-vast majority of users. But if you want to completely change the
-mechanism, customize the =orderless-pattern-compiler=. It's value
-should be a function from string to lists of regexps.
-
* Related packages
** Ivy and Helm
- [elpa] externals/orderless ecddc3da2e 045/204: Un-nest definition of orderless--highlight-matches, (continued)
- [elpa] externals/orderless ecddc3da2e 045/204: Un-nest definition of orderless--highlight-matches, ELPA Syncer, 2022/01/11
- [elpa] externals/orderless 582b3a9fa8 031/204: Make all `defface' syntax more efficient+readable, ELPA Syncer, 2022/01/11
- [elpa] externals/orderless c51037b8ef 024/204: Add custom variable for component separator regexp, ELPA Syncer, 2022/01/11
- [elpa] externals/orderless 9856eeed32 047/204: Mention prefixes style in overview, ELPA Syncer, 2022/01/11
- [elpa] externals/orderless cacd856f9a 041/204: Leverage completion-regexp-list: simplify code, increase speed!, ELPA Syncer, 2022/01/11
- [elpa] externals/orderless 3005cf8ee9 077/204: Merge pull request #12 from noctuid/feature/strict-initialism, ELPA Syncer, 2022/01/11
- [elpa] externals/orderless f8efbdae4d 087/204: Document style dispatches in the README, ELPA Syncer, 2022/01/11
- [elpa] externals/orderless e16fc5ddb1 099/204: Ido has progressive completion too!, ELPA Syncer, 2022/01/11
- [elpa] externals/orderless dc1a31b5fc 098/204: Merge remote-tracking branch 'github/master', ELPA Syncer, 2022/01/11
- [elpa] externals/orderless 306fb267f5 100/204: Mark orderless-temporarily-change-separator obsolete (#15), ELPA Syncer, 2022/01/11
- [elpa] externals/orderless 09f4c74280 105/204: Update dispatchers documentation, add transient vars,
ELPA Syncer <=
- [elpa] externals/orderless bc9e48216e 120/204: Add option for "smart case" matching, ELPA Syncer, 2022/01/11
- [elpa] externals/orderless 1f1e0380e2 122/204: Test for match before highlighting it, ELPA Syncer, 2022/01/11
- [elpa] externals/orderless 6b94b9abf8 124/204: Merge pull request #21 from wyuenho/patch-1, ELPA Syncer, 2022/01/11
- [elpa] externals/orderless 0826fd4eb4 130/204: Merge pull request #27 from vifon/master, ELPA Syncer, 2022/01/11
- [elpa] externals/orderless fc420e3d07 134/204: Minor readme tweak, ELPA Syncer, 2022/01/11
- [elpa] externals/orderless b600f88db0 144/204: Add orderless-define-completion-style macro, a new fix for #31, ELPA Syncer, 2022/01/11
- [elpa] externals/orderless 94d52640d4 145/204: Change docstring interface for orderless-define-completion-style, ELPA Syncer, 2022/01/11
- [elpa] externals/orderless da876320b3 146/204: Remove all orderless-transient-* variables (fix #34), ELPA Syncer, 2022/01/11
- [elpa] externals/orderless c023ee1cbe 150/204: Add option to skip-highlighting as requested by @clemera, ELPA Syncer, 2022/01/11
- [elpa] externals/orderless 1ed0c4aabb 153/204: Fix typo, ELPA Syncer, 2022/01/11