orderlessのREADME


- orderless.elのバージョン1.3のREADME.org日本語訳です

- 元の文書: https://github.com/oantolin/orderless/blob/master/README.org

- ライセンス: パッケージのライセンスと同じ、すなわちGPLv3.0ライセンスです

- - -

<a href="http://elpa.gnu.org/packages/orderless.html"><img alt="GNU ELPA" src="https://elpa.gnu.org/packages/orderless.svg"/></a>

<a href="http://elpa.gnu.org/devel/orderless.html"><img alt="GNU-devel ELPA" src="https://elpa.gnu.org/devel/orderless.svg"/></a>

<a href="https://melpa.org/#/orderless"><img alt="MELPA" src="https://melpa.org/packages/orderless-badge.svg"/></a>

<a href="https://stable.melpa.org/#/orderless"><img alt="MELPA Stable" src="https://stable.melpa.org/packages/orderless-badge.svg"/></a>

- - -


Table of Contents
=================

* [概要](#概要)
* [カスタマイズ](#カスタマイズ)
   * [コンポーネントをマッチするスタイル](#コンポーネントをマッチするスタイル)
      * [スタイル修飾子](#スタイル修飾子)
      * [スタイルディスパッチャ](#スタイルディスパッチャ)
   * [コンポーネントを区切るためのregexp](#コンポーネントを区切るためのregexp)
   * [カスタムorderlessスタイルの定義](#カスタムorderlessスタイルの定義)
   * [マッチしたコンポーネントのフェイス](#マッチしたコンポーネントのフェイス)
   * [パターンコンパイラー](#パターンコンパイラー)
   * [構成の対話的な変更](#構成の対話的な変更)
* [他の補完UIとの統合](#他の補完uiとの統合)
   * [Ivy](#ivy)
   * [Helm](#helm)
   * [Company](#company)
* [関連パッケージ](#関連パッケージ)
   * [IvyとHelm](#ivyとhelm)
   * [Prescient](#prescient)
   * [Icicles、Ido、Ivyで現在のマッチングを制限するには](#iciclesidoivyで現在のマッチングを制限するには)

<!-- Created by https://github.com/ekalinin/github-markdown-toc -->

- - -

# 概要

<!-- This package provides an `orderless` *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 literal matches are enabled. -->

このパッケージは`orderless`という *補完スタイル(completion style)* を提供する。これはパターンをスペース区切りのコンポーネントに分割、それらのコンポーネントすべてに順番は関係なく候補へのマッチングを行う。コンポーネントはそれぞれ複数ある方法のいずれかでマッチすることができる。literal(文字をそのまま一致)、regexp(正規表現)、initialism(頭文字)、flexスタイル、複数の単語プレフィックスのいずれかの方法でマッチさせることができるのだ。デフォルトではregexpとliteralが有効になっている。

<!-- 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), the icomplete-vertical variant from Emacs 28 (see the external [icomplete-vertical](https://github.com/oantolin/icomplete-vertical) package to get that functionality on earlier versions of Emacs), or with some third party minibuffer completion frameworks such as [Mct](https://gitlab.com/protesilaos/mct) or [Vertico](https://github.com/minad/vertico). -->

補完スタイルとは補完UI(ユーザーインターフェイス)を提供するフロントエンドから使用される、補完のバックエンドだ。Emacsのデフォルトの補完UI(ミニバッファーのタブ補完と呼ばれることもある)、ビルトインのIcompleteパッケージ(これに似ているIdoの方が知名度では勝る)、Emacs 28以降では変種としてicomplete-verticalパッケージ(これより古いバージョンのEmacsで同等の機能を得るには外部サイトの[icomplete-vertical](https://github.com/oantolin/icomplete-vertical)を参照のこと) 、あるいは[Mct](https://gitlab.com/protesilaos/mct)や[Vertico](https://github.com/minad/vertico)のようなサードパーティ製のミニバッファー補完フレームワークと任意の補完スタイルを組み合わせて使うことができる。

<!-- To use a completion style with any of the above mentioned completion UIs simply add it as an entry in the variables `completion-styles` and `completion-category-overrides` and `completion-category-defaults` (see their documentation). -->

ある補完スタイルを上記の補完UIのいずれかと使いたければ`completion-styles`、`completion-category-overrides``completion-category-defaults`といった変数のエントリーとして単に追加するだけでよい(ドキュメントを参照のこと)。

<!-- The `completion-category-defaults` variable serves as a default value for `completion-category-overrides`. If you want to use `orderless` exclusively, set both variables to `nil`, but be aware that `completion-category-defaults` is modified by packages at load time. -->

`completion-category-overrides`のデフォルト値としての役目をもつのが変数`completion-category-defaults`だ。`orderless`だけを使いたければ両方の変数に`nil`をセットすればよいが、パッケージのロード時に`completion-category-defaults`が変更されることに注意。


<!-- 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 [Ivy](https://github.com/abo-abo/swiper) (see below). Also, while Company does support completion styles directly, pressing `SPC` takes you out of completion, so comfortably using `orderless` with it takes a bit of configuration (see below). -->

たとえこれらのUIがEmacsの標準的な補完スタイルをサポートしていなくても、少し手を加えれば他の補完UIと`orderless`を使うことは依然として不可能ではない。今のところ[Ivy](https://github.com/abo-abo/swiper)向けのサポートが存在する(以下参照)。補完を直接サポートしているCompanyでも`SPC`を押下すれば補完から抜け出すことができる。したがって構成に少々手を加えれば`orderless`を快適に使うことができるだろう(以下参照)。

<!-- If you use ELPA or MELPA, the easiest way to install `orderless` is via `package-install`. If you use `use-package`, you can use: -->

ELPAかMELPAを使っていれば`package-install`を使うのが`orderless`をインストールする一番簡単な方法だ。`use-package`を使っている場合には以下のようにすればよいだろう:

```lisp
    (use-package orderless
      :ensure t
      :custom
      (completion-styles '(orderless basic))
      (completion-category-overrides '((file (styles basic partial-completion)))))
```

`load-path`のどこかに`orderless.el`を置いて、以下の構成を使ってもよい:

```lisp
    (require 'orderless)
    (setq completion-styles '(orderless basic)
          completion-category-overrides '((file (styles basic partial-completion))))
```

<!-- 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/s/l` for `/usr/share/local`. -->

動的補完テーブル(dynamic completion table)に依存する補完コマンド(`completion-table-dynamic`や`completion-table-in-turn`など)の正しい動作を保証するために、`orderless`の他にもフォールバックとして`basic`を補完スタイルに指定すること。更にTRAMPのホスト名の補完が機能するように、(フォールバックではなく)*最初*に試行される補完スタイルとして`basic`を指定する必要がある。これについては補完カテゴリー`file`の変数`completion-category-overrides`にエントリーを加えることによって実現している。更に`partial-completion`スタイルによりファイル補完やパス部分にワイルドカードが使用できるようにしている。

<!-- Bug reports are highly welcome and appreciated! -->

バグレポートはありがたいし、大歓迎だ!

# カスタマイズ

## コンポーネントをマッチするスタイル

<!-- Each component of a pattern can match in any of several matching styles. A matching style is a function from strings to regexps or predicates, so it is easy to define new matching styles. The value returned by a matching style can be either a regexp as a string, an s-expression in `rx` syntax or a predicate function. The predefined matching styles are: -->

パターンのコンポーネントはそれぞれ複数のマッチングスタイルのどれにたいしてマッチさせることができる。文字列からregexp、述語(predicate)といった関数までマッチングスタイルに指定できるので、新たなマッチングスタイルの定義は容易だ。マッチングスタイルはregexp(文字列)、`rx`構文のS式(s-expression、sexp)、あるいは述語関数を値としてリターンする。以下のマッチングスタイルが事前定義されている:



<!-- -   **orderless-regexp:** the component is treated as a regexp that must match somewhere in the candidate. -->
    
<!--     If the component is not a valid regexp, it is ignored. -->

<!-- -   **orderless-literal:** the component is treated as a literal string that must occur in the candidate. -->

<!-- -   **orderless-literal-prefix:** the component is treated as a literal string that must occur as a prefix of a candidate. -->

<!-- -   **orderless-prefixes:** the component is split at word endings and each piece must match at a word boundary in the candidate, occurring in that order. -->
    
<!--     This is similar to the built-in `partial-completion` completion-style. -->
<!--     For example, `re-re` matches `query-replace-regexp`, `recode-region` and `magit-remote-list-refs`; `f-d.t` matches `final-draft.txt`. -->

<!-- -   **orderless-initialism:** each character of the component should appear as the beginning of a word in the candidate, in order. -->
    
<!--     This maps `abc` to `\<a.*\<b.*\c`. -->

<!-- -   **orderless-flex:** the characters of the component should appear in that order in the candidate, but not necessarily consecutively. -->
    
<!--     This maps `abc` to `a.*b.*c`. -->

<!-- -   ****orderless-without-literal**:** the component is a treated as a literal string that must **not** occur in the candidate. -->
    
<!--     Nothing is highlighted by this style. This style should not be used directly in `orderless-matching-styles` but with a style dispatcher instead. See also the more general style modifier `orderless-not`. -->

-   **orderless-regexp:** コンポーネントは候補のいずれかがマッチしなければならないregexpとして扱われる
    有効なregexpでなければコンポーネントは無視される。

-   **orderless-literal:** コンポーネントは候補内に出現すべきリテラル文字列として扱われる

-   **orderless-literal-prefix:** コンポーネントは候補のプレフィックス(前置句)として出現すべきリテラル文字列として扱われる

-   **orderless-prefixes:** コンポーネントは単語終端で区切られて、区切られた要素はそれぞれ候補内の単語境界にで、出現順でマッチしなければならない
    これはビルトインの補完スタイル`partial-completion`と似ている
    たとえば`re-re`は`query-replace-regexp`、`recode-region`、`magit-remote-list-refs`にマッチ、`f-d.t`は`final-draft.txt`にマッチする

-   **orderless-initialism:** コンポーネントの各文字はその順番で候補の先頭に出現する
    `abc`は`\<a.*\<b.*\c`にマップされる

-   **orderless-flex:** コンポーネントの文字はその順番で候補内に出現する必要があるが、連続している必要はない
    `abc`は`a.*b.*c`にマップされる

-   **orderless-without-literal**: コンポーネントは候補内に **出現してはならない** リテラル文字列として扱われる
    このスタイルでは何もハイライトされない。これは`orderless-matching-styles`で直接使用するべきではなくスタイルディスパッチャ(style dispatcher)で使用すべきスタイルだ。より一般的なスタイル修飾子(style modifier)である`orderless-not`を参照して欲しい。

<!-- The variable `orderless-matching-styles` can be set to a list of the desired matching styles to use. By default it enables the literal and regexp styles. -->

変数`orderless-matching-styles`には使用したいマッチングスタイルのリストがセットできる。デフォルトで有効なスタイルはliteralとregexp。

### スタイル修飾子

<!-- Style modifiers are functions which take a predicate function and a regular expression as a string and return a new predicate function. Style modifiers should not be used directly in `orderless-matching-styles` but with a style dispatcher instead. -->

スタイル修飾子とは述語関数と正規表現(文字列)を受け取り、新たな述語関数をリターンする関数のことだ。スタイル修飾子は直接`orderless-matching-styles`で使用するのではなく、スタイルディスパッチャと使用する。

-   **orderless-annotation:** このスタイル修飾子は候補の文字列ではなく、候補の注釈文字列(annotation string)にたいしてマッチさせるパターンである

-   **orderless-not:** これはパターンにマッチしないパターンを渡すためのパターンを反転させるスタイル修飾子である

### スタイルディスパッチャ

<!-- For more fine-grained control on which matching styles to use for each component of the input string, you can customize the variable `orderless-style-dispatchers`. You can use this feature to define your own "query syntax". For example, the default value of `orderless-style-dispatchers` lists a single dispatcher called `orderless-affix-dispatch` which enables a simple syntax based on special characters used as either a prefix or suffix: -->

変数`orderless-style-dispatchers`をカスタマイズすれば、入力文字列のコンポーネントそれぞれにどのマッチングを用いるかを、より精密に制御できる。これは独自に"クエリー構文(query syntax)"を定義すればこの機能を使うことができるたとえば`orderless-style-dispatchers`のデフォルト値は`orderless-affix-dispatch`と呼ばれるディスパッチャのリストである。プレフィックス(前置文字)かサフィックス(後置文字)として用いられるスペシャル文字に基づくシンプルな構文を有効にするのがディスパッチャだ。

<!-- -   ! modifies the component with `orderless-not`. Both `!bad` and -->
<!--     `bad!` will match strings that do *not* contain the pattern `bad`. -->
<!-- -   & modifies the component with `orderless-annotation`. The pattern -->
<!--     will match against the candidate's annotation (cheesy mnemonic: -->
<!--     andnotation!). -->
<!-- -   , uses `orderless-initialism`. -->
<!-- -   = uses `orderless-literal`. -->
<!-- -   ^ uses `orderless-literal-prefix`. -->
<!-- -   ~ uses `orderless-flex`. -->
<!-- -   % makes the string match ignoring diacritics and similar -->
<!--     inflections on characters (it uses the function -->
<!--     `char-fold-to-regexp` to do this). -->


-   `!`はコンポーネントを`orderless-not`で修飾する。`!bad`と`bad!`はどちらもパターン`bad`を*含んでいない*文字列にマッチする。

-   `&`はコンポーネントを`orderless-annotation`で修飾する。パターンは候補の注釈にマッチする(暗記用に下手な語呂合わせを一発: andnotation!)。
    (訳注: 野暮とは思うが解説すると"n"と"n"の間に"d"を追加して"and notation"となり"and"が"&"。"下手"は訳者評ではなく原文の"cheesy"より)

-   `,`は`orderless-initialism`を使う

-   `=`は`orderless-literal`

-   `^`は`orderless-literal-prefix`

-   `~`は`orderless-flex`

-   `%`はダイアクリティクス(diacritics: 発音記号や装飾符号など)、その他同様の文字への語形変化を無視して文字列をマッチする(`char-fold-to-regexp`を使用)

<!-- You can add, remove or change this mapping between affix characters and matching styles by customizing the user option `orderless-affix-dispatch-alist`. Most users will probably find this type of customization sufficient for their query syntax needs, but for those desiring further control the rest of this section explains how to implement your own style dispatchers. -->

ユーザーオプション`orderless-affix-dispatch-alist`をカスタマイズすれば、接辞文字とマッチングスタイルの間のマッピングにたいする追加、削除、変更が可能だ。この種のカスタマイズがあればほとんどのユーザーは、自身のクエリー構文にたいするニーズは十分だと思うかもしれない。しかしより精緻な制御を望むユーザーのために、このセクションの残りの部分では独自のスタイルディスパッチャを実装する方法について説明しよう。

<!-- Style dispatchers are functions 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. -->

スタイルディスパッチャはコンポーネント、コンポーネントリストでのそのコンポーネントのインデックス(0基準)、コンポーネントの総数を受け取り、特定のコンポーネントにたいしてデフォルトのマッチングスタイルをオーバーライドして使用すべきマッチングスタイルの決定を行う。

<!-- 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. -->

スタイルディスパッチャは入力文字列やコンポーネントの処理を拒否するか、あるいは使用すべきマッチングスタイルをリターンできる。(もし望むなら)与えられた文字列のかわりに使用する新たな文字列wwwリターンすることもできる。完全な詳細については`orderless--dispatch`のドキュメントを参考にして欲しい。

<!-- As an example of writing your own dispatchers, say you wanted the following setup: -->

自分用にディスパッチャを記述する例として、以下のようなセットアップをしたい場合を考えてみよう:

<!-- -   you normally want components to match as regexps, -->
<!-- -   except for the first component, which should always match as an initialism &#x2014;this is pretty useful for, say, `execute-extended-command` (`M-x`) or `describe-function` (`C-h f`), -->
<!-- -   later components ending in `~` should match (the characters other than the final `~`) in the flex style, and -->
<!-- -   later components starting with `!` should indicate the rest of the component is a literal string not contained in the candidate (this is part of the functionality of the default configuration). -->


-   普段はregexpとしてマッチさせたいが、

-   最初のコンポーネントは常にinitialismとしてマッチさせたいので除外。これはたとえば`execute-extended-command`(`M-x`)や`describe-function`(`C-h f`),のときに特に重宝するだろう。

-   2つ目以降のコンポーネントの終端が`~`の場合には、(最後の`~`以外の文字は)flexスタイルでマッチさせて、

-   2つ目以降のコンポーネントの先頭が `!`の場合には、残りのコンポーネントは候補に含まれないリテラル文字列であることを示す(これはデフォルトの構成の一部でもある

<!-- You can achieve this with the following configuration: -->

これは以下のような構成で実現できる:

```lisp
    (defun flex-if-twiddle (pattern _index _total)
      (when (string-suffix-p "~" pattern)
        `(orderless-flex . ,(substring pattern 0 -1))))
    
    (defun first-initialism (pattern index _total)
      (if (= index 0) 'orderless-initialism))
    
    (defun not-if-bang (pattern _index _total)
      (cond
       ((equal "!" pattern)
        #'ignore)
       ((string-prefix-p "!" pattern)
        `(orderless-not . ,(substring pattern 1)))))
    
    (setq orderless-matching-styles '(orderless-regexp)
          orderless-style-dispatchers '(first-initialism
                                        flex-if-twiddle
                                        not-if-bang))
```

## コンポーネントを区切るためのregexp

<!-- The pattern components are space-separated by default: this is controlled by the variable `orderless-component-separator`, which should be set either to a regexp that matches the desired component separator, or to a function that takes a string and returns the list of components. The default value is a regexp matches a non-empty sequence of spaces. It may be useful to add hyphens or slashes (or both), to match symbols or file paths, respectively. -->

パターンコンポーネントはデフォルトではスペース区切りとなっている。これは変数`orderless-component-separator`によって制御されている。この変数にはコンポーネントの区切りにマッチさせたいregexp、または文字列を受け取りコンポーネントのリストをリターンする関数をセットする必要がある。空ではないスペースのシーケンスにマッチするregexpがデフォルトの値である。シンボルやファイルパスにマッチさせるためにハイフンやスラッシュ(あるいは両方)をセットすれば役に立つかもしれない。

 <!-- Even if you want to split on spaces you might want to be able to escape those spaces or to enclose space in double quotes (as in shell argument parsing). For backslash-escaped spaces set `orderless-component-separator` to the function `orderless-escapable-split-on-space`; for shell-like double-quotable space, set it to the standard Emacs function `split-string-and-unquote`. -->

スペースで分割したい場合であってもスペースをエスケープしたり、(シェルでの引数解析のように)ダブルクォーテーションで囲めるようにしたいと思うかもしれない。それならバックスラッシュによってエスケープされたスペースの場合には`orderless-component-separator`を関数`orderless-escapable-split-on-space`、シェルのようにダブルクォートされたスペースの場合にはEmacsの標準関数`split-string-and-unquote`にセットすればよいだろう。

<!-- If you are implementing a command for which you know you want a different separator for the components, bind `orderless-component-separator` in a `let` form. -->

コンポーネントの区切りを別の区切りにしたコマンドを実装する場合には、`let`内で`orderless-component-separator`をバインドすればよい。

## カスタムorderlessスタイルの定義

<!-- Orderless allows the definition of custom completion styles using the `orderless-define-completion-style` macro. Any Orderless configuration variable can be adjusted locally for the new style, e.g., `orderless-matching-styles`. -->

Orderlessでは`orderless-define-completion-style`マクロを使ってカスタム補完スタイルを定義できる。Orderlessのすべての構成変数は(たとえば`orderless-matching-styles`)はローカルに調節できる。

<!-- By default Orderless only enables the regexp and literal matching styles. In the following example an `orderless+initialism` style is defined, which additionally enables initialism matching. This completion style can then used when matching candidates of the symbol or command completion category. -->

Orderlessでデフォルトで有効なマッチングスタイルはregexpとliteralだけである。以下の例では有効なマッチングにinitialismを追加した`orderless+initialism`というスタイルを定義している。この補完スタイルはシンボルやコマンドといった補完カテゴリーの候補をマッチングする際に使用できるだろう。

```lisp
    (orderless-define-completion-style orderless+initialism
      (orderless-matching-styles '(orderless-initialism
                                   orderless-literal
                                   orderless-regexp)))
    (setq completion-category-overrides
          '((command (styles orderless+initialism))
            (symbol (styles orderless+initialism))
            (variable (styles orderless+initialism))))
```

<!-- Note that in order for the `orderless+initialism` style to kick-in with the above configuration, you'd need to use commands whose metadata indicates that the completion candidates are commands or symbols. In Emacs 28, `execute-extended-command` has metadata indicating you are selecting a command, but earlier versions of Emacs lack this metadata. Activating `marginalia-mode` from the [Marginalia](https://github.com/minad/marginalia) package provides this metadata automatically for many built-in commands and is recommended if you use the above example configuration, or other similarly fine-grained control of completion styles according to completion category. -->

上記の構成例で`orderless+initialism`が使用されるには、メタデータに補完の候補がコマンドやシンボルであることが示されているコマンドを使う必要があることに注意。Emacs 28では、あなたがコマンドの選択中であることが`execute-extended-command`のメタデータに示されているが、それ以前のバージョンのEmacsではこのメタデータは存在しない。[Marginalia](https://github.com/minad/marginalia)パッケージの`marginalia-mode`をアクティブにすることで、ビルトインコマンドの多くにこのパッケージが提供するメタデータが自動的に付加されるので上記の構成例や、他にも補完カテゴリーに応じて補完スタイルを精緻に制御したい場合にはこのパッケージのインストールをお勧めする。

## マッチしたコンポーネントのフェイス

<!-- The portions of a candidate matching each component get highlighted in one of four faces, `orderless-match-face-?` where `?` is a number from 0 to 3. If the pattern has more than four components, the faces get reused cyclically. -->

各コンポーネントの候補にマッチする部分は4つのフェイス`orderless-match-face-?`(`?`は0から3の数字)のいずれかのフェイスでハイライトされる。パターンに5つ以上のコンポーネントがあれば、フェイスを巡回して再利用する。

<!-- If your `completion-styles` (or `completion-category-overrides` for some particular category) has more than one entry, remember than Emacs 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. -->

`completion-styles`(あるいは何か特定のカテゴリー用の`completion-category-overrides`)2つ以上のエントリーがある場合には、Emacsが順番に各補完スタイルを試行して、最初にマッチをリターンした補完カテゴリーを使用することは覚えておいたほうがよいだろう。当然これら特定のフェイスを目にするのは、最初にマッチをリターンしたのが`orderless`補完の場合のみである。

## パターンコンパイラー

<!-- The default mechanism for turning an input string into a predicate and a list of regexps to match against, configured using `orderless-matching-styles`, is probably flexible enough for the vast majority of users. The patterns are compiled by `orderless-compile`. Under special circumstances it may be useful to implement a custom pattern compiler by advising `orderless-compile`.  -->

おそらく大多数のユーザーにとって、入力文字列を述語に変換するデフォルトのメカニズム、および`orderless-matching-styles`を使用して構成されたマッチさせるためのregexpのリストは十分に柔軟であろう。パターンをコンパイルするのは`orderless-compile`だ。特殊な状況下では、`orderless-compile`にadviceしてカスタム化したパターンコンパイラーを実装すると役に立つかもしれない。
<a id="orgb4af837"></a>

## 構成の対話的な変更

<!-- You might want to change the separator or the matching style configuration on the fly while matching. There many possible user interfaces 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 [hydra](https://github.com/abo-abo/hydra) to choose a configuration, etc. Since there are so many possible UIs and which to use is mostly a matter of taste, `orderless` does not provide any such commands. But it's easy to write your own! -->

区切り文字列やマッチングスタイルの構成を、マッチング中に臨機応変に変更したいと思うかもしれない。これを可能にするユーザーインターフェイスは多数存在する。たとえば選んでおいた2つの構成間を切り替える、複数の構成間を巡回する、それぞれのキーに異なる構成セットしたキーマップ(keyma)を作成する、名前付きの一連の構成を用意しておいて(補完付きで)それらの中から選ぶようなプロンプトを使用する、構成を選択するために[hydra](https://github.com/abo-abo/hydra)をポップアップする等が考えられるだろう。

<!-- Since there are so many possible UIs and which to use is mostly a matter of taste, `orderless` does not provide any such commands. But it's easy to write your own! -->

考えられるUIは非常に多く、どれを使用するかはほとんど好みの問題なので、`orderless`はその種のコマンドは何も提供しない。しかしそれを自分で記述するのは簡単なのだ!

<!-- For example, say you want to use the keybinding `C-l` to make all components match literally. You could use the following code: -->

たとえばすべてのコンポーネントをリテラルにマッチさせる場合にはキーバインディング`C-l`を使いたいとする。以下のコードを使うことができるだろう:

```lisp
    (defun my/match-components-literally ()
      "このセッションでは残りのコンポーネントはliteralにマッチさせる"
      (interactive)
      (setq-local orderless-matching-styles '(orderless-literal)
                  orderless-style-dispatchers nil))
    
    (define-key minibuffer-local-completion-map (kbd "C-l")
      #'my/match-components-literally)
```

<!-- Using `setq-local` to assign to the configuration variables ensures the values are only used for that minibuffer completion session. -->

構成変数への値の割り当てに`setq-local`を使用しているのは、その値が使用させるのはこのミニバッファー補完セッションの間だけであることを保証するためだ。

# 他の補完UIとの統合

<!-- Several excellent completion UIs exist for Emacs in third party packages. They do have a tendency to forsake standard Emacs APIs, so integration with them must be done on a case by case basis. -->

Emacs向けのサードパーティ製パッケージの中には、優れた補完UIをもつものがいくつか存在する。これらのパッケージはEmacsの標準APIを見限る傾向があるので、統合はケースバイケースで行わなければならない。。

<!-- If you manage to use `orderless` with a completion UI not listed here, please file an issue or make a pull request so others can benefit from your effort. The functions `orderless-filter`, `orderless-highlight-matches`, `orderless--highlight` and `orderless--component-regexps` are likely to help with the integration.  -->

ここに挙げた以外の補完UIで`orderless`の使用を管理する場合には、他の人たちがあなたの努力から恩恵を得られるように、是非issueに報告するか、あるいはpullリクエストを送って欲しい。統合の助けになりそうな関数には`orderless-filter`、`orderless-highlight-matches`、`orderless--highlight`、`orderless--component-regexps`がある。

## Ivy

<!-- To use `orderless` from Ivy add this to your Ivy configuration: -->

Ivyから`orderless`を使用するには、以下をIvyの構成に加えればよいだろう:

```lisp
    (setq ivy-re-builders-alist '((t . orderless-ivy-re-builder)))
    (add-to-list 'ivy-highlight-functions-alist '(orderless-ivy-re-builder . orderless-ivy-highlight))
```

## Helm

<!-- To use `orderless` from Helm, simply configure `orderless` as you would for completion UIs that use Emacs completion styles and add this to your Helm configuration:  -->

Helmから`orderless`を使用するには、単にEmacsの補完スタイルを使用する補完UIに行うときと同じように`orderless`を構成して、それをHelmの構成に加えればよいだろう:

```lisp
    (setq helm-completion-style 'emacs)
```

## Company

<!-- Company comes with a `company-capf` backend that uses the completion-at-point functions, which in turn use completion styles. This means that the `company-capf` backend will automatically use `orderless`, no configuration necessary! -->

Companyには`completion-at-point-functions`(順番に使用する補完スタイルを格納する変数)の関数を使用するバックエンド`company-capf`が同梱されている。これはつまり`company-capf`が`orderless`を自動的に使用するので、構成は不要ということだ!

<!-- But there are a couple of points of discomfort: -->

とはいえ気に入らない点もいくつかある:

<!-- 1.  Pressing SPC takes you out of completion, so with the default separator you are limited to one component, which is no fun. To fix this add a separator that is allowed to occur in identifiers, for example, for Emacs Lisp code you could use an ampersand: -->

<!-- ```lisp -->
<!--         (setq orderless-component-separator "[ &]") -->
<!-- ``` -->

<!-- 2.  The matching portions of candidates aren't highlighted. That's because `company-capf` is hard-coded to look for the `completions-common-part` face, and it only use one face, `company-echo-common` to highlight candidates. -->
    
<!--     So, while you can't get different faces for different components, you can at least get the matches highlighted in the sole available face with this configuration: -->

<!-- ```lisp -->
<!--         (defun just-one-face (fn &rest args) -->
<!--           (let ((orderless-match-faces [completions-common-part])) -->
<!--             (apply fn args))) -->
        
<!--         (advice-add 'company-capf--candidates :around #'just-one-face) -->
    
<!--     (Aren't dynamically scoped variables and the advice system nifty?) -->
<!-- ``` -->

1.  `SPC`の押下により補完が終了するのでデフォルトの区切りだとコンポーネントが1つに限定されて、これは面白くない。これを修正するためには識別子として出現できるように区切りを追加すればよい。たとえばEmacs Lispのコードならアンパサンドを使用できるだろう:

```lisp
        (setq orderless-component-separator "[ &]")
```

2.  候補のマッチした部分がハイライトされない。これは候補のハイライトに`company-echo-common`だけを使用する`completions-common-part`フェイスを探すように、`company-capf`がハードコーディングされているためだ

    したがってコンポーネントごとに違うフェイスを使用することはできないが、以下の構成により唯一利用可能フェイスでマッチをハイライトすることはできるだろう:

```lisp
        (defun just-one-face (fn &rest args)
          (let ((orderless-match-faces [completions-common-part]))
            (apply fn args)))
        
        (advice-add 'company-capf--candidates :around #'just-one-face)
    
    (動的スコープの変数とadviceシステムは粋な手ではないだろうか?)
```

<!-- If you would like to use different `completion-styles` with `company-capf` instead, you can add this to your configuration: -->

`company-capf`で違う`completion-styles`を使いたければ、以下を構成に加えればよいだろう:

```lisp
    ;; Companyのメンテナであるu/hvisのアドバイスにしたがった構成:
    ;; https://www.reddit.com/r/emacs/comments/nichkl/comment/gz1jr3s/
    (defun company-completion-styles (capf-fn &rest args)
      (let ((completion-styles '(basic partial-completion)))
        (apply capf-fn args))
    
    (advice-add 'company-capf :around #'company-completion-styles)
```

# 関連パッケージ

## IvyとHelm

<!-- The well-known and hugely powerful completion frameworks [Ivy](https://github.com/abo-abo/swiper) and [Helm](https://github.com/emacs-helm/helm) also provide for matching space-separated component regexps in any order. In Ivy, this is done with the `ivy--regex-ignore-order` matcher. In Helm, it is the default, called "multi pattern matching". -->

著名かつ非常に強力な補完フレームワークの[Ivy](https://github.com/abo-abo/swiper)と[Helm](https://github.com/emacs-helm/helm)も任意順のスペースで区切られたコンポーネントへのregexpマッチングをサポートしている。Ivyは`ivy--regex-ignore-order`というmatcherでこれを行っている。Helmではこれがデフォルトであり、"マルチパターンマッチング(multi pattern matching)"と呼ばれている。

<!-- This package is significantly smaller than either of those because it solely defines a completion style, meant to be used with any completion UI supporting completion styles while both of those provide their own completion UI (and many other cool features!). -->

このパッケージが行うのは補完スタイルの定義だけなので他のパッケージより断然サイズが小さくなる。他のパッケージは補完UI(やその他のイカした機能も!)を独自に提供するが、このパッケージは補完スタイルをサポートしている任意の補完UIで使用されることを意図しているのだ。

<!-- It is worth pointing out that Helm does provide its multi pattern matching as a completion style which could be used with default tab completion, Icomplete or other UIs supporting completion styles! (Ivy does not provide a completion style to my knowledge.) So, for example, Icomplete users could, instead of using this package, install Helm and configure Icomplete to use it as follows: -->

Helmが補完スタイルとして提供している自身のマルチパターンマッチングはデフォルトのタブ補完、Icomplete、その他補完スタイルをサポートするすべてのUIと併用できることについては言及しておいた方がよいだろう! (わたしの知る限りIvyは補完スタイルを提供していない。) したがってたとえばIcompleteのユーザーであればこのパッケージを使うかわりにHelmをインストールして、以下のようにそれを使うようにIcompleteを構成すればよいだろう:

```lisp
    (require 'helm)
    (setq completion-styles '(helm basic))
    (icomplete-mode)
```

<!-- (Of course, if you install Helm, you might as well use the Helm UI in `helm-mode` rather than Icomplete.) -->

(Helmをインストールしたら、当然Icompleteのかわりに`helm-mode`でHelmのUIを使うことになるだろう。)

## Prescient

<!-- The [prescient.el](https://github.com/radian-software/prescient.el) library also provides matching of space-separated components in any order. It offers a completion-style that can be used with Emacs' default completion UI, Mct, Vertico or with Icomplete. Furthermore Ivy is supported. The components can be matched literally, as regexps, as initialisms or in the flex style (called "fuzzy" in prescient). Prescient does not offer the same flexibility as Orderless with its style dispatchers. However in addition to matching, Prescient supports sorting of candidates, while Orderless leaves that up to the candidate source and the completion UI. -->

[prescient.el](https://github.com/radian-software/prescient.el)ライブラリーもスペースで区切られた任意順のコンポーネントへのマッチングを提供している。提供される補完スタイルはEmacsのデフォルトの補完UI、Mct、Vertico、Icompleteとともに使用できる上にIvyもサポートされているのだ。コンポーネントはliteral、regexp、initialism、またはflexスタイル(prescientでは"fuzzy"と呼ばれる)でマッチできる。PrescientではOrderlessがスタイルディスパッチャで実現した柔軟性と同等なものは提供されていない。とは言うもののマッチング以外にもPrescientは候補のソートをサポートしている(Orderlessは候補のソースと補完UIにソートを任せている)。

## Icicles、Ido、Ivyで現在のマッチングを制限するには

<!-- An effect equivalent to matching multiple components in any order can be achieved in completion frameworks that provide a way to restrict further matching to the current list of candidates. If you use the keybinding for restriction instead of `SPC` to separate your components, you get out of order matching! -->

任意の順番で複数コンポーネントをマッチングするのと同等な効果は、候補のカレントリストに更にマッチングすることを制限する方法を提供するような補完フレームワークによって実現し得る。この制限に`SPC`以外のキーバインディングをコンポーネントの区切りに使用すれば、順序付きのマッチングから抜け出すことができるのだ!

<!-- -   [Icicles](https://www.emacswiki.org/emacs/Icicles) calls this *progressive completion* and uses the -->
<!--     `icicle-apropos-complete-and-narrow` command, bound to `S-SPC`, to do it. -->

<!-- -   Ido has `ido-restrict-to-matches` and binds it to `C-SPC`. -->

<!-- -   Ivy has `ivy-restrict-to-matches`, bound to `S-SPC`, so you can get the effect of out of order matching without using `ivy--regex-ignore-order`. -->

-   [Icicles](https://www.emacswiki.org/emacs/Icicles)ではこれを*progressive completion*と呼んでおり、`S-SPC`にバインドされている`icicle-apropos-complete-and-narrow`コマンドで行っている

-   Idoには`ido-restrict-to-matches`があり、`C-SPC`にバインドされている

-   Ivyには`S-SPC`にバインドされている`ivy-restrict-to-matches`があるので、`ivy--regex-ignore-order`を使用せずに順序付きマッチングの支配から抜け出すことができるだろう。