VerticoのREADME


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

- 元の文書: https://github.com/minad/vertico/blob/main/README.org

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

- - -

<a href="https://www.gnu.org/software/emacs/"><img alt="GNU Emacs" src="https://github.com/minad/corfu/blob/screenshots/emacs.svg?raw=true"/></a>

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

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

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

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

<img src="https://upload.wikimedia.org/wikipedia/commons/thumb/7/75/Vertigomovie_restoration.jpg/800px-Vertigomovie_restoration.jpg" align="right" width="30%">

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

* [機能](#機能)
* [インストール](#インストール)
* [キーバインディング](#キーバインディング)
* [構成](#構成)
   * [補完スタイルとタブ補完](#補完スタイルとタブ補完)
   * [Completion-at-pointとcompletion-in-region](#completion-at-pointとcompletion-in-region)
* [拡張](#拡張)
   * [コマンドごとあるいはカテゴリごとにVerticoを構成する](#コマンドごとあるいはカテゴリごとにverticoを構成する)
* [補足的なパッケージ](#補足的なパッケージ)
* [子フレームとポップアップ](#子フレームとポップアップ)
* [他の選択肢](#他の選択肢)
* [リソース](#リソース)
* [貢献するには](#貢献するには)
* [Verticoのデバッグ](#verticoのデバッグ)
* [問題の発生しがちな補完コマンド](#問題の発生しがちな補完コマンド)
   * [org-refile](#org-refile)
   * [org-agenda-filterとorg-tags-view](#org-agenda-filterとorg-tags-view)
   * [tmm-menubar](#tmm-menubar)
   * [ffap-menu](#ffap-menu)
   * [completion-table-dynamic](#completion-table-dynamic)
   * [空文字列の入力](#空文字列の入力)
   * [Trampでのhostname/usernameの補完](#trampでのhostnameusernameの補完)

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

- - -

<!-- Vertico provides a performant and minimalistic vertical completion UI based on the default completion system. The focus of Vertico is to provide a UI which behaves *correctly* under all circumstances. By reusing the built-in facilities system, Vertico achieves *full compatibility* with built-in Emacs completion commands and completion tables. Vertico only provides the completion UI but aims to be highly flexible, extendable and modular. Additional enhancements are available as [extensions](#extensions) or [complementary packages](#complementary-packages). The code base is small and maintainable. The main `vertico.el` package is only about 600 lines of code without white space and comments. -->

Verticoはデフォルトの補完システムに基づき効率的かつミニマリズム的な垂直補完ユーザーインターフェイスを提供する。Vertico焦点を当てているのは、すべての状況下において*正しく*振る舞うユーザーインターフェイスを提供することだ。ビルトイン機能システムの再利用することで、VerticoはEmacsのビルトイン補完コマンドや補完テーブルとの*完全な互換性*を実現した。Verticoが提供するのは補完ユーザーインターフェイスだけではあるが柔軟性、拡張性、モジュール性を高めるということも目標としている。拡張性については[extensions](#extensions)や[complementary packages](#complementary-packages)を利用して追加できる。コードベースは小さく保守性にも優れる。メインとなる`vertico.el`パッケージは空白やコメントを除けばおよそ600行程度に過ぎない。

# 機能

<!-- -   Vertical display with arrow key navigation. Many additional display modes are -->
<!--     provided as [extensions](#extensions). -->
<!-- -   Prompt shows the current candidate index and the total number of candidates. -->
<!-- -   The current candidate is inserted with `TAB` and selected with `RET`. -->
<!-- -   Non-existing candidates can be submitted with `M-RET` or by moving the point to the prompt. -->
<!-- -   Efficient sorting by history position, length and alphabetically. -->
<!-- -   Long candidates with newlines are formatted to take up less space. -->
<!-- -   Lazy completion candidate highlighting for performance. -->
<!-- -   Annotations are displayed next to the candidates (`annotation-` and `affixation-function`). -->
<!-- -   Support for candidate grouping and group cycling commands (`group-function`). -->

-   矢印キーを使ったナビゲーションによる垂直表示、他の表示モードも[extensions](#extensions)として追加で多数用意されている
-   カレント候補のインデックスと候補の総数をプロンプトに表示
-   `TAB`でカレント候補の挿入、選択は`RET`
-   入力プロンプトにポイントを移動、または`M-RET`で既存にはない候補の入力が可能
-   ヒストリー(history: 履歴)内での位置、長さ、アルファベット順での効率的なソート
-   改行を含む長い候補の表示幅を減少させるフォーマット処理
-   lazy補完で候補をハイライトすることによる性能向上
-   候補の隣に表示される注釈(`annotation-`および`affixation-function`)
-   候補のグルーピングとグループ巡回コマンド(`group-function`)のサポート

![img](https://github.com/minad/vertico/blob/screenshots/vertico-mx.png?raw=true)

# インストール

<!-- Vertico is available from [GNU ELPA](https://elpa.gnu.org/packages/vertico.html). You can install it directly via `M-x package-install RET vertico RET`. After installation, activate the global minor mode with `M-x vertico-mode RET`.  -->

Verticoは[GNU ELPA](https://elpa.gnu.org/packages/vertico.html)から入手できる。`M-x package-install RET vertico RET`で直接インストール可能だ。インストール後に、`M-x vertico-mode RET`でグローバルマイナーモードをアクティブにすればよい。

# キーバインディング

<!-- Vertico defines its own local keymap in the minibuffer which is derived from `minibuffer-local-map`. The keymap keeps most of the `fundamental-mode` keybindings intact and remaps and binds only a handful of commands. -->

Verticoはミニバッファー用に`minibuffer-local-map`から継承したローカルキーマップを独自に定義している。このキーマップでは`fundamental-mode`のキーバインディングがほとんど手付かずで残されており、いくつかのコマンドをリマップ(remap: 再マップ)やバインドしているだけだ。

<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">


<colgroup>
<col  class="org-left" />

<col  class="org-left" />
</colgroup>
<thead>
<tr>
<th scope="col" class="org-left">バインディング/リマップ</th>
<th scope="col" class="org-left">Verticoコマンド</th>
</tr>
</thead>

<tbody>
<tr>
<td class="org-left"><code>beginning-of-buffer</code>, <code>minibuffer-beginning-of-buffer</code></td>
<td class="org-left"><code>vertico-first</code></td>
</tr>


<tr>
<td class="org-left"><code>end-of-buffer</code></td>
<td class="org-left"><code>vertico-last</code></td>
</tr>


<tr>
<td class="org-left"><code>scroll-down-command</code></td>
<td class="org-left"><code>vertico-scroll-down</code></td>
</tr>


<tr>
<td class="org-left"><code>scroll-up-command</code></td>
<td class="org-left"><code>vertico-scroll-up</code></td>
</tr>


<tr>
<td class="org-left"><code>next-line</code>, <code>next-line-or-history-element</code></td>
<td class="org-left"><code>vertico-next</code></td>
</tr>


<tr>
<td class="org-left"><code>previous-line</code>, <code>previous-line-or-history-element</code></td>
<td class="org-left"><code>vertico-previous</code></td>
</tr>


<tr>
<td class="org-left"><code>forward-paragraph</code></td>
<td class="org-left"><code>vertico-next-group</code></td>
</tr>


<tr>
<td class="org-left"><code>backward-paragraph</code></td>
<td class="org-left"><code>vertico-previous-group</code></td>
</tr>


<tr>
<td class="org-left"><code>exit-minibuffer</code></td>
<td class="org-left"><code>vertico-exit</code></td>
</tr>


<tr>
<td class="org-left"><code>kill-ring-save</code></td>
<td class="org-left"><code>vertico-save</code></td>
</tr>


<tr>
<td class="org-left"><code>M-RET</code></td>
<td class="org-left"><code>vertico-exit-input</code></td>
</tr>


<tr>
<td class="org-left"><code>TAB</code></td>
<td class="org-left"><code>vertico-insert</code></td>
</tr>
</tbody>
</table>

<!-- Note in particular the binding of `TAB` to `vertico-insert`, which inserts the currently selected candidate, and the binding of `RET` and `M-RET` to `vertico-exit` and `vertico-exit-input` respectively. -->

カレントで選択されている候補を挿入する`vertico-insert`にバインドされている`TAB`、そして`vertico-exit`、`vertico-exit-input`にバインドされている`RET`と`M-RET`には特に注意して欲しい。

<!-- `vertico-exit` exits with the currently selected candidate, while `vertico-exit-input` exits with the minibuffer input instead. Exiting with the current input is needed when you want to create a new buffer or a new file with `find-file` or `switch-to-buffer`. As an alternative to pressing `M-RET`, move the selection up to the input prompt by pressing the `up` arrow key and then press `RET`. -->

`vertico-exit`はカレントで選択された候補で補完を終了するが、`vertico-exit-input`は候補をミニバッファーに入力して補完を終了する。`switch-to-buffer`で新しいバッファーを作成したり、`find-file`で新たにファイルを作成したいときには、カレントの入力で補完を終える手段が必要になるのだ。`M-RET`を押下するかわりに矢印キー`up`で選択を入力プロンプトまで移動してから`RET`の押下でもよい。

# 構成

<!-- In order to configure Vertico and other packages in your init.el, you may want to take advantage of `use-package`. Here is an example configuration: -->

"init.el"でVerticoやその他パッケージを構成する場合には、`use-package`のメリットを享受したいと思うかもしれない。以下に構成の例を示そう:

```lisp
    ;; Verticoを有効化
    (use-package vertico
      :custom
      ;; (vertico-scroll-margin 0) ;; スクロールマージンの変更
      ;; (vertico-count 20) ;; 表示する補完の数を増やす
      ;; (vertico-resize t) ;; Verticoミニバッファーの拡大、縮小
      ;; (vertico-cycle t) ;; `vertico-next/previous'の巡回を有効化
      :init
      (vertico-mode))
    
    ;; Emacsの再起動を跨いでヒストリーを永続化
    ;; Verticoはヒストリー位置によってソートを行う
    (use-package savehist
      :init
      (savehist-mode))
    
    ;; 更に便利な構成をいくつか...
    (use-package emacs
      :custom
      ;; 既存ミニバッファー内部からの新たなミニバッファーのオープンをサポート
      (enable-recursive-minibuffers t)
      ;; カレントモードでは動作しないコマンドをM-xのコマンドから除外
      ;; 通常のバッファーではVerticoのコマンドは表示されなくなる
      ;; Verticoに限らず役に立つセッティングではないだろうか
      (read-extended-command-predicate #'command-completion-default-include-p)
      :init
      ;; `completing-read-multiple'にプロンプトのインジケーターを追加する
      ;; [CRM<separator>]のような表示になる
      ;; たとえばseparatorがカンマなら[CRM,]
      (defun crm-indicator (args)
        (cons (format "[CRM%s] %s"
                      (replace-regexp-in-string
                       "\\`\\[.*?]\\*\\|\\[.*?]\\*\\'" ""
                       crm-separator)
                      (car args))
              (cdr args)))
      (advice-add #'completing-read-multiple :filter-args #'crm-indicator)
    
      ;; ミニバッファープロンプトへのカーソル移動の禁止
      (setq minibuffer-prompt-properties
            '(read-only t cursor-intangible t face minibuffer-prompt))
      (add-hook 'minibuffer-setup-hook #'cursor-intangible-mode))
```

<!-- I recommend to give Orderless completion a try, which is more flexible and powerful than the default completion styles. -->

試しにOrderless補完を与えてみることをお勧めする。これはデフォルトの補完スタイルに比べて柔軟かつ強力な補完スタイルだ。

```lisp
    ;; オプションで`orderless'補完スタイルを使用
    (use-package orderless
      :custom
      ;; カスタムスタイルのdispatcherを構成(Consultのwikiを参照)
      ;; (orderless-style-dispatchers '(+orderless-consult-dispatch orderless-affix-dispatch))
      ;; (orderless-component-separator #'orderless-escapable-split-on-space)
      (completion-styles '(orderless basic))
      (completion-category-defaults nil)
      (completion-category-overrides '((file (styles 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. See the [Consult wiki](https://github.com/minad/consult/wiki#minads-orderless-configuration) for my advanced Orderless configuration with style dispatchers. Additionally enable `partial-completion` for file path expansion. `partial-completion` is important for file wildcard support in `find-file`. In order to open multiple files with a wildcard at once, you have to submit the prompt with `M-RET`. Alternative first move to the prompt and then press `RET`. -->

`orderless`に加えてフォールバックとして補完スタイル`basic`を指定する理由は、たとえば`completion-table-dynamic`や`completion-table-in-turn`のような動的な補完テーブルに依存する補完コマンドが正しく機能することを保証するためだ。スタイルディスパッチャによる、より高度なOrderless構成については[Consult wiki](https://github.com/minad/consult/wiki#minads-orderless-configuration)を参考にして欲しい。更にファイル名の展開用に`partial-completion`を有効にしている。`partial-completion`は`find-file`におけるファイル名のワイルドカードサポートにとっては重要だ。複数のファイルをワイルドカードで一度にオープンするためには、プロンプトで`M-RET`を入力する必要がある。かわりにまずプロンプトに移動してから`RET`の押下でもよい。

<!-- See also the [Vertico Wiki](https://github.com/minad/vertico/wiki) for additional configuration tips. For more general documentation read the chapter about completion in the [Emacs manual](https://www.gnu.org/software/emacs/manual/html_node/emacs/Completion.html). If you want to create your own completion commands, you can find documentation about completion in the [Elisp manual](https://www.gnu.org/software/emacs/manual/html_node/elisp/Completion.html). -->

追加の構成についてのヒントについては[Vertico Wiki](https://github.com/minad/vertico/wiki)も参考にして欲しい。より一般的なドキュメントについては、[Emacsマニュアル](https://www.gnu.org/software/emacs/manual/html_node/emacs/Completion.html)の補完のチャプターに目を通すのもお勧めだ。自分で補完コマンドを作成したい場合には、[Elispマニュアル](https://www.gnu.org/software/emacs/manual/html_node/elisp/Completion.html)でも補完に関する文書を見つけることができるだろう。

## 補完スタイルとタブ補完

<!-- The bindings of the `minibuffer-local-completion-map` are not available in Vertico by default. This means that `TAB` works differently from what you may expect from shells like Bash or the default Emacs completion system. In Vertico `TAB` inserts the currently selected candidate. -->

`minibuffer-local-completion-map`のバインディングは、Verticoではデフォルトでは利用できない。これは`TAB`がBashのようなシェルやEmacsのデフォルトの補完システムなどから期待されるるような動きをしないことを意味している。Verticoにおける`TAB`はカレントで選択されている候補の挿入を行うのだ。

<!-- If you prefer to have the default completion commands available you can add new bindings or even replace the Vertico bindings. For example you can use `M-TAB` to expand the prefix of candidates (TAB complete) or cycle between candidates if `completion-cycle-threshold` is non-nil, with the following configuration. -->

他の補完コマンドが利用できるようにしたければ新たにバインディングを追加したり、あるいはVerticoのバインディングの置き換えさえできる。たとえば`M-TAB`で補完のプレフィックスを展開したい(いわゆるTAB補完だ)、あるいは`completion-cycle-threshold`が非nilの場合には補完を巡回したければ以下の構成がよいだろう。

```lisp
    ;; オプション1: 追加のバインディング
    (keymap-set vertico-map "?" #'minibuffer-completion-help)
    (keymap-set vertico-map "M-RET" #'minibuffer-force-complete-and-exit)
    (keymap-set vertico-map "M-TAB" #'minibuffer-complete)
    
    ;; オプション2: `vertico-insert'ではなくTABでプレフィックス展開に置き換え
    ;; (keymap-set vertico-map "TAB" #'minibuffer-complete)
```

<!-- The command `minibuffer-complete` performs prefix expansion for the `basic` completion style, while the `orderless` and `substring` completion styles expand to the longest candidate substring. Alternatively you can use completion-styles like `partial-completion`, `flex` or `initials`, which perform different expansion and filtering. The `partial-completion` style is important if you want to open multiple files at once with `find-file` using wildcards. In order to open multiple files with a wildcard at once, you have to submit the prompt with `M-RET`. Alternative first move to the prompt and then press `RET`. -->

コマンド`minibuffer-complete`は補完スタイル`basic`にたいしてプレフィックス展開を行い、補完スタイルの`orderless`と`substring`は補完の一番長い部分文字列の展開を行う。展開やフィルタリングを行う`partial-completion`、`flex`、`initials`といった他の補完スタイルを使うこともできるだろう。ワイルドカードを使用して`find-file`で一度に複数のファイルをオープンしたければ、`partial-completion`も重要な選択肢だ。ワイルドカードで一度に複数ファイルをオープンするためには、プロンプトで`M-RET`を入力する必要がある。最初にプロンプトに移動してから`RET`の押下でもよいだろう。

```lisp
    (setq completion-styles '(basic substring partial-completion flex))
```

<!-- Because Vertico is fully compatible with Emacs default completion system, further customization of completion behavior can be achieved by setting the designated Emacs variables. For example, one may wish to disable case-sensitivity for file and buffer matching when built-in completion styles are used: -->

VerticoはEmacsのデフォルトの補完システムと完全な互換性があるので、Emacsの準公式変数をセットすることで、補完の振る舞いの更なるカスタマイズを実現できる筈だ。たとえばビルトインの補完システムを使用しているときには、大文字小文字の区別を無効にしたいと思ったら以下のようにすればよい:

```lisp
    (setq read-file-name-completion-ignore-case t
          read-buffer-completion-ignore-case t
          completion-ignore-case t)
```

## Completion-at-pointとcompletion-in-region

<!-- The tab completion command `completion-at-point` command is usually bound to `M-TAB` or `TAB`. Tab completion is also used in the minibuffer by `M-:` (`eval-expression`). In case you want to use Vertico to show the completion candidates of `completion-at-point` and `completion-in-region`, you can use the function `consult-completion-in-region` provided by the Consult package. -->

タブ補完コマンド`completion-at-point`は通常だと`M-TAB`や`TAB`にバインドされている。タブ補完はミニバッファーにおいても`M-:` (`eval-expression`)によって使用されている。このような場合に`completion-at-point`や`completion-in-region`の補完候補表示にVerticoを使いたければ、Consultパッケージ提供の関数`consult-completion-in-region`を使用できる。

```lisp
    ;; Verticoが有効なら`consult-completion-in-region'を使用、
    ;; それ以外はデフォルトの`completion--in-region'関数を使用
    (setq completion-in-region-function
          (lambda (&rest args)
            (apply (if vertico-mode
                       #'consult-completion-in-region
                     #'completion--in-region)
                   args)))
```

<!-- You may also want to look into my [Corfu](https://github.com/minad/corfu) package, which provides a minimal completion system for `completion-in-region` in a child frame popup. Corfu is a narrowly focused package and developed in the same spirit as Vertico. You can even use Corfu in the minibuffer. -->

わたしの[Corfu](https://github.com/minad/corfu)パッケージも調べてみたいと思うかもしれない。これは子フレームをポップアップして`completion-in-region`用のミニマリズム的な補完システムを提供するパッケージだ。Corfuのほうはパッケージに焦点を絞っているが、Verticoと同じ精神で開発している。ミニバッファーでCorfuを使うことすら可能だ。

# 拡張

<!-- We maintain small extension packages to Vertico in this repository in the subdirectory [extensions/](https://github.com/minad/vertico/tree/main/extensions). The extensions are installed together with Vertico if you pull the package from ELPA. The extensions are inactive by default and can be enabled manually if desired. Furthermore it is possible to install all of the files separately, both `vertico.el` and the `vertico-*.el` extensions. Currently the following extensions come with the Vertico ELPA package: -->

このレポジトリでは[extensions/](https://github.com/minad/vertico/tree/main/extensions)というサブディレクトリーで、Vertico用に小さな拡張パッケージを保守している。ELPAからパッケージを取得した場合には、Verticoと一緒に拡張のインストールができる。拡張はデフォルトではアクティブになっていないが、もしアクティブにしたければ手作業で有効にできる。更に`vertico.el`と`vertico-*.el`といった拡張のファイルはすべて個別にインストールすることができるのだ。現在のところELPAのVerticoパッケージには以下の拡張が同梱されている:

<!-- -   [vertico-buffer](https://github.com/minad/vertico/blob/main/extensions/vertico-buffer.el): `vertico-buffer-mode` to display Vertico like a regular buffer. -->
<!-- -   [vertico-directory](https://github.com/minad/vertico/blob/main/extensions/vertico-directory.el): Commands for Ido-like directory navigation. -->
<!-- -   [vertico-flat](https://github.com/minad/vertico/blob/main/extensions/vertico-flat.el): `vertico-flat-mode` to enable a flat, horizontal display. -->
<!-- -   [vertico-grid](https://github.com/minad/vertico/blob/main/extensions/vertico-grid.el): `vertico-grid-mode` to enable a grid display. -->
<!-- -   [vertico-indexed](https://github.com/minad/vertico/blob/main/extensions/vertico-indexed.el): `vertico-indexed-mode` to select indexed candidates with prefix arguments. -->
<!-- -   [vertico-mouse](https://github.com/minad/vertico/blob/main/extensions/vertico-mouse.el): `vertico-mouse-mode` to support for scrolling and candidate selection. -->
<!-- -   [vertico-multiform](https://github.com/minad/vertico/blob/main/extensions/vertico-multiform.el): Configure Vertico modes per command or completion category. -->
<!-- -   [vertico-quick](https://github.com/minad/vertico/blob/main/extensions/vertico-quick.el): Commands to select using Avy-style quick keys. -->
<!-- -   [vertico-repeat](https://github.com/minad/vertico/blob/main/extensions/vertico-repeat.el): The command `vertico-repeat` repeats the last completion session. -->
<!-- -   [vertico-reverse](https://github.com/minad/vertico/blob/main/extensions/vertico-reverse.el): `vertico-reverse-mode` to reverse the display. -->
<!-- -   [vertico-suspend](https://github.com/minad/vertico/blob/main/extensions/vertico-suspend.el): The command `vertico-suspend` suspends and restores the current session. -->
<!-- -   [vertico-unobtrusive](https://github.com/minad/vertico/blob/main/extensions/vertico-unobtrusive.el): `vertico-unobtrusive-mode` displays only the topmost candidate. -->

-   [vertico-buffer](https://github.com/minad/vertico/blob/main/extensions/vertico-buffer.el): `vertico-buffer-mode`は通常のバッファーのようにVerticoを表示する

-   [vertico-directory](https://github.com/minad/vertico/blob/main/extensions/vertico-directory.el): Ido風にディレクトリーをナビゲーションするコマンド

-   [vertico-flat](https://github.com/minad/vertico/blob/main/extensions/vertico-flat.el): `vertico-flat-mode`はフラットで水平方向の表示を有効にする

-   [vertico-grid](https://github.com/minad/vertico/blob/main/extensions/vertico-grid.el): `vertico-grid-mode`はグリッド表示を有効にする

-   [vertico-indexed](https://github.com/minad/vertico/blob/main/extensions/vertico-indexed.el): `vertico-indexed-mode`はプレフィックス引数でインデックス付けされた候補を選択できる

-   [vertico-mouse](https://github.com/minad/vertico/blob/main/extensions/vertico-mouse.el): `vertico-mouse-mode`はスクロールと候補選択のサポート

-   [vertico-multiform](https://github.com/minad/vertico/blob/main/extensions/vertico-multiform.el): コマンドごと、あるいは補完カテゴリーごとにVerticoモードを構成する

-   [vertico-quick](https://github.com/minad/vertico/blob/main/extensions/vertico-quick.el): Avyスタイルのクイックキーを用いて選択を行うコマンド

-   [vertico-repeat](https://github.com/minad/vertico/blob/main/extensions/vertico-repeat.el): `vertico-repeat`は最後の補完セッションを繰り返すコマンド

-   [vertico-reverse](https://github.com/minad/vertico/blob/main/extensions/vertico-reverse.el): `vertico-reverse-mode`は表示の反転

-   [vertico-suspend](https://github.com/minad/vertico/blob/main/extensions/vertico-suspend.el): `vertico-suspend`はカレントセッションのサスペンドとリストアを行うコマンド

-   [vertico-unobtrusive](https://github.com/minad/vertico/blob/main/extensions/vertico-unobtrusive.el): `vertico-unobtrusive-mode`は一番上の候補だけを表示する

<!-- See the commentary of those files for configuration details. With these extensions it is possible to adapt Vertico such that it matches your preference or behaves similar to other familiar UIs. For example, the combination `vertico-flat` plus `vertico-directory` resembles Ido in look and feel. For an interface similar to Helm, the extension `vertico-buffer` allows you to configure freely where the completion buffer opens, instead of growing the minibuffer. Furthermore `vertico-buffer` will adjust the number of displayed candidates according to the buffer height. -->

構成の詳細についてはこれらのファイルのコメントを確認して欲しい。これらの拡張を用いればあなたの好みに合うように、あるいは他の類似UIと同様の挙動になるようにVerticoを改造できるだろう。たとえば`vertico-flat`に`vertico-directory`を追加して組み合わせれば、Idoのルック&フィールに似せられる。Helmに似せたインターフェイスであれば、`vertico-buffer`の拡張を使ってミニバッファーを広げるかわりに補完バッファーをどこにオープンするか自由に構成できるだろう。更に`vertico-buffer`ならバッファーの高さに応じて候補の表示数を調節できるのだ。

<!-- Configuration example for `vertico-directory`: -->

以下に`vertico-directory`用の構成を示す:

```lisp
    ;; ディレクトリー拡張の構成
    (use-package vertico-directory
      :after vertico
      :ensure nil
      ;; より便利にディレクトリーをナビゲーションするコマンド
      :bind (:map vertico-map
                  ("RET" . vertico-directory-enter)
                  ("DEL" . vertico-directory-delete-char)
                  ("M-DEL" . vertico-directory-delete-word))
      ;; ミニバッファーのシャドー部分でファイル名を整える
      :hook (rfn-eshadow-update-overlay . vertico-directory-tidy))
```

## コマンドごとあるいはカテゴリごとにVerticoを構成する

![img](https://github.com/minad/vertico/blob/screenshots/vertico-ripgrep.png?raw=true)

<!-- Vertico offers the `vertico-multiform-mode` which allows you to configure Vertico per command or per completion category. The `vertico-buffer-mode` enables a Helm-like buffer display, which takes more space but also displays more candidates. This verbose display mode is useful for commands like `consult-imenu` or `consult-outline` since the buffer display allows you to get a better overview over the entire current buffer. But for other commands you want to keep using the default Vertico display. `vertico-multiform-mode` solves this configuration problem. -->

Verticoが提供する`vertico-multiform-mode`ではコマンドごと、あるいは補完カテゴリーごとにVerticoを構成できる。`vertico-buffer-mode`ではHelm風のバッファー表示が利用できるので、スペースの消費は増えるがより多くの補完を表示できる。この冗長な表示モードはカレントバッファー全体に渡ってより良い概観を得られるバッファー表示なので、`consult-imenu`や`consult-outline`のようなコマンドで役に立つだろう。しかしそれ以外のコマンドではVerticoのデフォルト表示を使い続けたいと思うかもしれない。この構成問題を解決するのが`vertico-multiform-mode`だ。

```lisp
    ;; vertico-multiformを有効にする
    (vertico-multiform-mode)
    
    ;; コマンドごとに表示を構成する
    ;; imenuの表示にはバッファーを使い
    ;; M-xには(Ido風の)フラットなメニューを使用する
    (setq vertico-multiform-commands
          '((consult-imenu buffer indexed)
            (execute-extended-command unobtrusive)))
    
    ;; コマンドカテゴリーごとに票を構成する
    ;; ファイルにはグリッド表示を使い
    ;; consult-grepにはバッファー表示を使用する
    (setq vertico-multiform-categories
          '((file grid)
            (consult-grep buffer)))
```

<!-- Temporary toggling between the different display modes is possible. The following commands are bound by default in the `vertico-multiform-map`. You can of course change these bindings if you like. -->

異なる表示モード間を一時的に切り替えることができる。以下のコマンドは`vertico-multiform-map`にデフォルトでバインドされている。もちろんお望みならバインディングの変更も可能だ。

-   `M-B` -> `vertico-multiform-buffer`

-   `M-F` -> `vertico-multiform-flat`

-   `M-G` -> `vertico-multiform-grid`

-   `M-R` -> `vertico-multiform-reverse`

-   `M-U` -> `vertico-multiform-unobtrusive`

-   `M-V` -> `vertico-multiform-vertical`

<!-- For special configuration you can use your own functions or even lambdas to configure the completion behavior per command or per completion category. Functions must have the calling convention of a mode, i.e., take a single argument, which is either 1 to turn on the mode and -1 to turn off the mode. -->

コマンドごと、あるいは補完カテゴリーごとに補完の振る舞いを構成するために、特別構成として独自の関数、あるいはラムダ式さえ使うことができる。関数はモードの呼び出し規約にしたがわなければならない。つまり1つの引数を受け取り、その値が1ならモードをオンに、-1ならモードをオフに切り替える関数だ。

```lisp
    ;; 別バッファーにスケールダウンされたTOCとして`consult-outline'を構成
    (setq vertico-multiform-commands
          `((consult-outline buffer ,(lambda (_) (text-scale-set -1)))))
```

<!-- Furthermore you can tune buffer-local settings per command or category. -->

さらにバッファーローカルにコマンドごと、あるいは補完カテゴリーごとにチューニングすることもできるのだ。

```lisp
    ;; デフォルトのソート関数を変更
    ;; `vertico-sort-function'および`vertico-sort-override-function'を参照
    (setq vertico-multiform-commands
          '((describe-symbol (vertico-sort-function . vertico-sort-alpha))))
    
    (setq vertico-multiform-categories
          '((symbol (vertico-sort-function . vertico-sort-alpha))
            (file (vertico-sort-function . sort-directories-first))))
    
    ;; ファイルの前にソートしたディレクトリー
    (defun sort-directories-first (files)
      (setq files (vertico-sort-history-length-alpha files))
      (nconc (seq-filter (lambda (x) (string-suffix-p "/" x)) files)
             (seq-remove (lambda (x) (string-suffix-p "/" x)) files)))
```

<!-- Combining these features allows us to fine-tune the completion display even more by adjusting the `vertico-buffer-display-action`. We can for example reuse the current window for commands of the `consult-grep` category (`consult-grep`, `consult-git-grep` and `consult-ripgrep`). Note that this configuration is incompatible with Consult preview, since the previewed buffer is usually shown in exactly this window. Nevertheless this snippet demonstrates the flexibility of the configuration system. -->

3つの機能を組み合わせることで、`vertico-buffer-display-action`より以上に補完表示を精密に調節できる。たとえば`consult-grep`カテゴリーのコマンド(`consult-grep`、`consult-git-grep`、`consult-ripgrep`)にたいしてカレントウィンドウを再利用するといったことが可能になる。この構成はConsultのプレビューとは互換性がないことに注意。これはプレビューバッファーが正確にそのウィンドウに表示されるからだ。とはいえこのスニペットで構成の柔軟度については判ってもらえたと思う。

```lisp
    ;; バッファー表示とバッファーディスプレイアクションを構成
    (setq vertico-multiform-categories
          '((consult-grep
             buffer
             (vertico-buffer-display-action . (display-buffer-same-window)))))
    
    ;; consult-grepコマンドのプレビューは無効化
    (consult-customize consult-ripgrep consult-git-grep consult-grep :preview-key nil)
```

<!-- As another example, the following code uses `vertico-flat` and `vertico-cycle` to emulate `(ido-mode 'buffer)`, i.e., Ido when it is enabled only for completion of buffer names. `vertico-cycle` set to `t` is necessary here to prevent completion candidates from disappearing when they scroll off-screen to the left. -->

別の例として、以下は`vertico-flat`と`vertico-cycle`を用いて`(ido-mode 'buffer)` (バッファー名の補完にたいしてのみIdoを有効化)をエミュレートするコードを示そう。スクリーンを左にスクロールオフした際に補完候補が見えなくなることを防ぐために、ここでは`vertico-cycle`に`t`をセットする必要がある。

```lisp
    (setq vertico-multiform-categories
          '((buffer flat (vertico-cycle . t))))
```

# 補足的なパッケージ

<!-- Vertico integrates well with complementary packages, which enrich the completion UI. These packages are fully supported: -->

Verticoには豪華な補完UIをもつ補足パッケージが統合されている。以下は完全にサポートされているパッケージだ:

<!-- -   [Marginalia](https://github.com/minad/marginalia): Rich annotations in the minibuffer -->
<!-- -   [Consult](https://github.com/minad/consult): Useful search and navigation commands -->
<!-- -   [Embark](https://github.com/oantolin/embark): Minibuffer actions and context menu -->
<!-- -   [Orderless](https://github.com/oantolin/orderless): Advanced completion style -->


-   [Marginalia](https://github.com/minad/marginalia): ミニバッファーでの贅沢な注釈

-   [Consult](https://github.com/minad/consult): 使いやすい検索やナビゲーション用のコマンド

-   [Embark](https://github.com/oantolin/embark): ミニバッファーアクションとコンテキストメニュー

-   [Orderless](https://github.com/oantolin/orderless): 先進的な補完スタイル

<!-- In order to get accustomed with the package ecosystem, I recommend the following quick start approach: -->

このパッケージエコシステムに馴染むためのアプローチとして以下のクイックスタートをお勧めする:



<!-- 1.  Start with plain Emacs (`emacs -Q`). -->
<!-- 2.  Install and enable Vertico to get incremental minibuffer completion. -->
<!-- 3.  Install Orderless and/or configure the built-in completion styles -->
<!--     for more flexible minibuffer filtering. -->
<!-- 4.  Install Marginalia if you like rich minibuffer annotations. -->
<!-- 5.  Install Embark and add two keybindings for `embark-dwim` and `embark-act`. -->
<!--     I am using the mnemonic keybindings `M-.` and `C-.` since these commands allow -->
<!--     you to act on the object at point or in the minibuffer. -->
<!-- 6.  Install Consult if you want additional featureful completion commands, -->
<!--     e.g., the buffer switcher `consult-buffer` with preview or the line-based -->
<!--     search `consult-line`. -->
<!-- 7.  Install Embark-Consult and Wgrep for export from `consult-line` to `occur-mode` -->
<!--     buffers and from `consult-grep` to editable `grep-mode` buffers. -->
<!-- 8.  Fine tune Vertico with [extensions](#extensions). -->


1.  Emacsを素で起動(`emacs -Q`)

2.  Verticoをインストールしてインクリメンタルなミニバッファー補完を有効にする

3.  Orderlessのインストールおよび/またはビルトインの補完システムを構成して、ミニバッファーでのフィルタリングをより柔軟にする

4.  豪華なミニバッファーの注釈がお好みならMarginaliaをインストール

5.  Embarkをインストールして`embark-dwim``embark-act`のためにキーバインディングを2つ追加(これらのコマンドによってポイント位置やミニバッファーにあるオブジェクトにアクションできるので、わたしは覚えやすいようにキーバインディングとして`M-.`と`C-.`を割り当てている)

6.  機能豊富な補完コマンド(たとえばプレビュー付きのバッファー切り替えには`consult-buffer`、行志向の検索なら`consult-line`など)を追加したければConsultをインストール

7.  `consult-line`から`occur-mode`バッファーへのエクスポートや、`consult-grep`から編集可能な`grep-mode`へエクスポートするなら、WgrepとEmbark-Consultをインストールしよう

8.  そして[extensions](#extensions)を使ってVerticoを更に細かくチューニングしていく


<!-- The ecosystem is modular. You don't have to use all of these components. Use only the ones you like and the ones which fit well into your setup. The steps 1. to 4. introduce no new commands over plain Emacs. Step 5. introduces the new commands `embark-act` and `embark-dwim`. In step 6. you get the Consult commands, some offer new functionality not present in Emacs already (e.g., `consult-line`) and some are substitutes (e.g., `consult-buffer` for `switch-to-buffer`). -->

このエコシステムはモジュール化されている。これらのコンポーネントすべてを使う必要はない。あなたが気に入ったパッケージ、あなたのセッティングによく馴染むパッケージだけを使おう。1.から4.は素のEmacsに新たなコマンドを導入するステップ、ステップ5.で新たなコマンド`embark-act`と`embark-dwim`も導入、ステップ6.でConsultのコマンドが手に入る。Emacsにまだない機能を提供するコマンド(`consult-line`とか)があるし、置き換えるコマンド(`switch-to-buffer`の`consult-buffer`による置き換え)もある。

# 子フレームとポップアップ

<!-- An often requested feature is the ability to display the completions in a child frame popup. Personally I am critical of using child frames for minibuffer completion. From my experience it introduces more problems than it solves. Most importantly child frames hide the content of the underlying buffer. Furthermore child frames do not play well together with changing windows and entering recursive minibuffer sessions. On top, child frames can feel slow and sometimes flicker. A better alternative is the `vertico-buffer` display which can even be configured individually per command using `vertico-multiform`. On the plus side of child frames, the completion display appears at the center of the screen, where your eyes are focused. Please give the following packages a try and judge for yourself.  -->

よくあるリクエストが子フレームをポップアップして補完できる機能だろう。個人的にはミニバッファー補完に子フレームを使うことには批判的である。経験的には解決されるより多くの問題が引き起こされたからだ。もっとも重要なのは子フレームが背後のバッファーコンテンツを隠してしまう点にある。更に子フレームはウィンドウの変更や再帰的なミニバッファーセッションとの相性が良くない。その上に子フレームだと遅く感じたり、ちらつくこともあり得る。`vertico-buffer`での表示がよい代替えだと思う。こちらは`vertico-multiform`を使えばコマンドごとに個別に構成することさえ可能だ。子フレームの利点は視線が焦点を結ぶスクリーン中央に補完が表示される点だろうか。以下のパッケージを試してあなた自身で判断して欲しい。

<!-- -   [mini-frame](https://github.com/muffinmad/emacs-mini-frame): Display the entire minibuffer in a child frame. -->

<!-- -   [mini-popup](https://github.com/minad/mini-popup): Slightly simpler alternative to mini-frame. -->

<!-- -   [vertico-posframe](https://github.com/tumashu/vertico-posframe): Display only the Vertico minibuffer in a child frame using -->
<!--     the posframe library. -->

-   [mini-frame](https://github.com/muffinmad/emacs-mini-frame): 子フレームにミニバッファー全体を表示

-   [mini-popup](https://github.com/minad/mini-popup): 若干シンプルなミニフレームの代替品

-   [vertico-posframe](https://github.com/tumashu/vertico-posframe): posframeライブラリーを使って子フレームにverticoミニバッファーだけを表示

# 他の選択肢

<!-- There are many alternative completion UIs, each UI with its own advantages and disadvantages. -->

補完UIには多くの選択肢があり、UIごとに利点と欠点が存在する。


<!-- Vertico aims to be 100% compliant with all Emacs commands and achieves that with a minimal code base, relying purely on `completing-read` while avoiding to invent its own APIs. Inventing a custom API as Helm or Ivy is explicitly avoided in order to increase flexibility and package reuse. Due to its small code base and reuse of the Emacs built-in facilities, bugs and compatibility issues are less likely to occur in comparison to completion UIs or monolithic completion systems. -->

Verticoが目指すのは`completing-read`に信を置くことで独自APIの作成を避けて、最小限のコードベースでEmacsのコマンドすべてに100%準拠するというゴールだ。パッケージの柔軟性と再利用度を向上させるために、HelmやIvyのようなカスタムAPIの発明は意識的に避けている。このパッケージ自身の小さなコードベースとEmacs機能の再利用のお陰で、補完UIやモノリシックな補完システムと比較するとバグや互換性問題が発生しにくくなっている。

<!-- Since Vertico only provides the UI, you may want to combine it with some of the complementary packages, to give a full-featured completion experience similar to Helm or Ivy. The idea is to have smaller independent components, which one can add and understand step by step. Each component focuses on its niche and tries to be as non-intrusive as possible. Vertico targets users interested in crafting their Emacs precisely to their liking - completion plays an integral part in how the users interacts with Emacs. -->

Verticoが提供するのはユーザーインターフェイスだけなので、他の何らかの補完パッケージと組み合わせることによりHelmやIvyに似たフル機能の補完体験を提供できるようにしたいと思うかもしれない。これはより小さな独立したコンポーネントをもつことによって、ステップ&ステップでコンポーネントの追加と理解ができるというアイデアである。コンポーネントはそれぞれ可能な限り出しゃばらないように努めて自分の得意分野に注力するのだ。これらのコンポーネントと、ユーザーがEmacsと対話する手法において欠かせない役を演じる補完をリンクさせて、自分のEmacsを細部に渡り正確に作り出すことに興味があるユーザーこそ、Verticoがターゲットとするユーザーだ。

<!-- There are other interactive completion UIs, which follow a similar philosophy: -->

似たような哲学にしたがう対話的な補完UIが他にも存在する:

<!-- -   [Mct](https://git.sr.ht/~protesilaos/mct): Minibuffer and Completions in Tandem. Mct reuses the default `*Completions*` buffer and enhances it with automatic updates and additional keybindings, to select a candidate and move between minibuffer and completions buffer. Since Mct uses a fully functional buffer you can use familiar buffer commands inside the completions buffer. The main distinction to Vertico's approach is that `*Completions*` buffer displays all matching candidates. This has the advantage that you can interact freely with the candidates and jump around with Isearch or Avy. On the other hand it necessarily causes a slowdown. -->

<!-- -   [Selectrum](https://github.com/radian-software/selectrum): Selectrum is the predecessor of Vertico has been deprecated in favor of Vertico. Read the [migration guide](https://github.com/minad/vertico/wiki/Migrating-from-Selectrum-to-Vertico) when migrating from Selectrum. -->
<!--     Vertico was designed specifically to address the technical shortcomings of Selectrum. Selectrum is not fully compatible with every Emacs completion command and dynamic completion tables, since it uses its own filtering infrastructure, which deviates from the standard Emacs completion facilities. -->
    
<!-- -   Icomplete: Emacs comes with the builtin `icomplete-vertical-mode`, which is a more bare-bone than Vertico. Vertico offers additional flexibility thanks to its [extensions](#extensions). -->


-   [Mct](https://git.sr.ht/~protesilaos/mct): ミニバッファーと補完の連携。Mctは候補選択、およびミニバッファーと補完バッファー間の移動を行うために、自動更新やキーバインディングを追加してデフォルトの`*Completions*`バッファーを強化して再利用している。Mctが使用するのはバッファーとして完全な機能をもった補完バッファーなので、バッファー内で慣れ親しんだバッファーコマンドを使用できるだろう。Verticoのアプローチとの主な違いは、`*Completions*`バッファーにマッチするすべての候補が表示される点だ。候補と自由にやり取りができ、IsearchやAvyで飛び回ることができることも利点だ。その一方で速度は必然的に低下してしまう。

-   [Selectrum](https://github.com/radian-software/selectrum): Verticoの前身であるSelectrumは、Verticoを支持する声によって時代遅れとなった。Selectrumから移行する際には[migration guide](https://github.com/minad/vertico/wiki/Migrating-from-Selectrum-to-Vertico)を一読して欲しい。
    Selectrumの技術的な欠点に対処するよう特に設計されたのがVerticoである。    SelectrumはEmacsのすべてのコマンドと動的テーブルへの完全な互換性はもっていない。なぜならフィルタリングにおいてEmacsの標準的な補完機能から逸脱した独自のインフラストラクチャを使用しているせいだ。
    
-   Icomplete: Emacsにはビルトインの`icomplete-vertical-mode`が同梱されているが、Verticoより更に必要最小限の機能しかもっていない。Verticoの方は[extensions](#extensions)のお陰で、さらなる柔軟性を提供できるのだ。

# リソース

<!-- If you want to learn more about Vertico and minibuffer completion, check out the following resources: -->

Verticoやミニバッファー補完についてもっと学びたければ、以下のリソースをチェックして欲しい:



<!-- -   Configurations which use Vertico and Corfu for completion: -->
<!--     -   [Doom Emacs Vertico Module](https://github.com/doomemacs/doomemacs/tree/master/modules/completion/vertico) -->
<!--     -   [Crafted Emacs Completion Module](https://github.com/SystemCrafters/crafted-emacs/blob/master/modules/crafted-completion.el) -->
<!--     -   [Prot's Emacs configuration](https://git.sr.ht/~protesilaos/dotfiles/tree/master/item/emacs/.emacs.d/) -->
    
<!-- -   Videos: -->
<!--     -   [Emacs Completion Explained](https://www.youtube.com/watch?v=fnE0lXoe7Y0) (2022-07-19) by Andrew Tropin. -->
<!--     -   [Emacs Minibuffer Completions](https://www.youtube.com/watch?v=w9hHMDyF9V4) (2022-02-12) by Greg Yut. -->
<!--     -   [Vertico Extensions for Emacs](https://www.youtube.com/watch?v=hPwDbx--Waw) (2022-01-08) by Karthik Chikmagalur. -->
<!--     -   [Using Emacs Episode 80 - Vertico, Marginalia, Consult and Embark](https://youtu.be/5ffb2at2d7w) (2021-10-26) by Mike Zamansky. -->
<!--     -   [System Crafters Live! - Replacing Ivy and Counsel with Vertico and Consult](https://www.youtube.com/watch?v=UtqE-lR2HCA) (2021-05-21) by David Wilson. -->
<!--     -   [Streamline Your Emacs Completions with Vertico](https://www.youtube.com/watch?v=J0OaRy85MOo) (2021-05-17) by David Wilson. -->
<!--     -   [Modern Emacs: all those new tools that make Emacs better and faster](https://www.youtube.com/watch?v=SOxlQ7ogplA&t=1952s) (2024-03-06) by Marie-Hélène Burle. -->


-   補完にたいしてVerticoCorfuを使用する構成:
    -   [Doom Emacs Vertico Module](https://github.com/doomemacs/doomemacs/tree/master/modules/completion/vertico)
    -   [Crafted Emacs Completion Module](https://github.com/SystemCrafters/crafted-emacs/blob/master/modules/crafted-completion.el)
    -   [Prot's Emacs configuration](https://git.sr.ht/~protesilaos/dotfiles/tree/master/item/emacs/.emacs.d/)
    
-   ビデオ:
    -   [Emacs Completion Explained](https://www.youtube.com/watch?v=fnE0lXoe7Y0) (2022-07-19) Andrew Tropin氏による
    -   [Emacs Minibuffer Completions](https://www.youtube.com/watch?v=w9hHMDyF9V4) (2022-02-12) Greg Yut氏による
    -   [Vertico Extensions for Emacs](https://www.youtube.com/watch?v=hPwDbx--Waw) (2022-01-08) Karthik Chikmagalurによる
    -   [Using Emacs Episode 80 - Vertico, Marginalia, Consult and Embark](https://youtu.be/5ffb2at2d7w) (2021-10-26) Mike Zamanskyによる
    -   [System Crafters Live! - Replacing Ivy and Counsel with Vertico and Consult](https://www.youtube.com/watch?v=UtqE-lR2HCA) (2021-05-21) David Wilsonによる
    -   [Streamline Your Emacs Completions with Vertico](https://www.youtube.com/watch?v=J0OaRy85MOo) (2021-05-17) David Wilsonによる
    -   [Modern Emacs: all those new tools that make Emacs better and faster](https://www.youtube.com/watch?v=SOxlQ7ogplA&t=1952s) (2024-03-06) Marie-Hélène Burleによる

# 貢献するには

<!-- Since this package is part of [GNU ELPA](https://elpa.gnu.org/packages/vertico.html) contributions require a copyright assignment to the FSF. -->

このパッケージは[GNU ELPA](https://elpa.gnu.org/packages/vertico.html)の一部なので、貢献においてはFSFの著作権の譲渡が必要になる。

# Verticoのデバッグ

<!-- When you observe an error in the `vertico--exhibit` post command hook, you should install an advice to enforce debugging. This allows you to obtain a stack trace in order to narrow down the location of the error. The reason is that post command hooks are automatically disabled (and not debugged) by Emacs. Otherwise Emacs would become unusable, given that the hooks are executed after every command. -->

`post-command-hook`で`vertico--exhibit`のエラーを発見したら、強制的にデバッグできるようにadviceをインストールするべきだ。これによりエラー発生箇所を絞り込むためのスタックトレースが得られるだろう。理由はEmacsによって`post-command-hook`が自動的に無効化されることにある(そしてデバッグされない)。すべてのコマンドの後にフックが実行された場合を考えれば、そうしないとEmacsが使い物にならなくなることが判るだろう。

```lisp
    (setq debug-on-error t)
    
    (defun force-debug (func &rest args)
      (condition-case e
          (apply func args)
        ((debug error) (signal (car e) (cdr e)))))
    
    (advice-add #'vertico--exhibit :around #'force-debug)
```

# 問題の発生しがちな補完コマンド

<!-- Vertico is robust in most scenarios. However some completion commands make certain assumptions about the completion styles and the completion UI. Some of these assumptions may not hold in Vertico or other UIs and require minor workarounds.  -->

ほとんどのシナリオにおいてVerticoは堅牢だ。ただし一部の補完コマンドの中には、補完のスタイルやユーザーインターフェイスにたいして何かを決めてかかるものが存在する。Verticoやその他のUIはこれらの先入観をもっていないものの、軽微な対処が必要な場合もあるかもしれない。

## org-refile

<!-- `org-refile` uses `org-olpath-completing-read` to complete the outline path in steps, when `org-refile-use-outline-path` is non-nil.  -->

`org-refile`は`org-refile-use-outline-path`が非`nil`だと、アウトラインパス(訳注: アウトライン構造をディレクトリーのパスのように表現したもの)の補完ステップの中で`org-olpath-completing-read`を使用する。

<!-- Unfortunately the implementation of this Org completion table assumes that the `basic` completion style is used. The table is incompatible with completion styles like `substring`, `flex` or `orderless`. In order to fix the issue at the root, the completion table should make use of completion boundaries similar to the built-in file completion table. In your user configuration you can prioritize `basic` before `orderless`. -->

残念ながらこのOrgの補完テーブルは、補完スタイルに`basic`が使用されている前提で実装されている。これは`substring`、`flex`、`orderless`といった補完スタイルと互換性がない。この問題に根本的に対処するためには、ビルトインのファイル補完テーブルのように補完テーブルに補完境界(completion boundary)を使用させる必要があるだろう。構成で対処する場合には`orderless`より`basic`の優先度を高くすればよい。

```lisp
    ;; 選択肢その1: 補完スタイルbasicを使う
    (setq org-refile-use-outline-path 'file
          org-outline-path-complete-in-steps t)
    
    (advice-add #'org-olpath-completing-read :around #'vertico-enforce-basic-completion)
    
    (defun vertico-enforce-basic-completion (&rest args)
      (minibuffer-with-setup-hook
          (:append
           (lambda ()
             (let ((map (make-sparse-keymap)))
               (define-key map [tab] #'minibuffer-complete)
               (use-local-map (make-composed-keymap (list map) (current-local-map))))
             (setq-local completion-styles (cons 'basic completion-styles)
                         vertico-preselect 'prompt)))
        (apply args)))
```

<!-- Alternatively you may want to disable the outline path completion in steps. The completion on the full path can be quicker since the input string matches directly against substrings of the full path, which is useful with Orderless. However the list of possible completions becomes much more cluttered. -->


アウトラインパスにたいする補完のステップで補完を無効にしたいと思うかもしれない。フルパスにたいして補完すれば、フルパスの部分文字列にたいして入力文字列を直接マッチさせるので高速になる筈だ。ただし適用可能な補完はより乱雑になるだろう。

```lisp
    ;; 選択肢その2: フルパスを補完する
    (setq org-refile-use-outline-path 'file
          org-outline-path-complete-in-steps nil)
```

## org-agenda-filterとorg-tags-view

<!-- Similar to `org-refile`, the commands `org-agenda-filter` and `org-tags-view` do not make use of completion boundaries. The internal completion tables are `org-agenda-filter-completion-function` and `org-tags-completion-function`. Unfortunately `TAB` completion (`minibuffer-complete`) does not work for this reason with arbitrary completion styles like `substring`, `flex` or `orderless`. This affects Vertico and also the Emacs default completion system. For example if you enter `+tag<0 TAB` the input is replaced with `0:10` which is not correct. With preserved completion boundaries, the expected result would be `+tag<0:10`. Completion boundaries are used for example by file completion, where each part of the path can be completed separately. Ideally this issue would be fixed in Org.  -->

コマンド`org-agenda-filter`および`org-tags-view`は、`org-refile`と同じように補完境界を使用しない。内部的な補完テーブルは`org-agenda-filter-completion-function`と`org-tags-completion-function`だ。この理由により`substring`、`flex`、`orderless`のような自由裁量の補完スタイルには、残念ながら`TAB`補完(`minibuffer-complete`)が機能しない。これはVerticoだけではなく、Emacsのデフォルトの補完システムにも影響を及ぼす。たとえば`+tag<0 TAB`と入力すると`0:10`に置き換えられるが、これは間違いだ。補完境界に保護されていれば、結果は`+tag<0:10`になっただろう。たとえばファイル補完に使用されている補完境界は、パスの部分それぞれを別個に補完するために使用されている。理屈ではOrgで以下のようにすればこの問題は解決する筈だ。

```lisp
    (advice-add #'org-make-tags-matcher :around #'vertico-enforce-basic-completion)
    (advice-add #'org-agenda-filter :around #'vertico-enforce-basic-completion)
```

## tmm-menubar

<!-- **NOTE**: I have implemented a fix for this problem which is part of Emacs 31. You can set `completion-eager-display` to `nil` in your configuration. See [bug#74616](https://debbugs.gnu.org/cgi/bugreport.cgi?bug=74616) for the upstream bug report. -->


**注意**: わたしは以下の問題にたいする修正を実装した。Emacs 31に含まれることになるだろう。構成で`completion-eager-display`に`nil`をセットするのだ。アップストリームのバグレポートについては[bug#74616](https://debbugs.gnu.org/cgi/bugreport.cgi?bug=74616)を参照のこと。

<!-- The text menu bar works well with Vertico but always shows a `*Completions*` buffer, which is unwanted if Vertico is used. Right now the completion buffer can be disabled with an advice. If you disabled the standard GUI menu bar and prefer the Vertico interface you may also overwrite the default F10 keybinding.  -->

Verticoでもテキストメニューバーは良好に機能する。しかし常に`*Completions*`を表示することについては、Verticoを使っていれば望ましくない点だろう。adviceすることで補完バッファーは今すぐ無効にできる。標準的なGUIのメニューバーを無効にしていて、かつVerticoのインターフェイスが気に入ったのであれば、`F10`にたいするデフォルトのキーバインディングも上書きしたいと思うかもしれない。

```lisp
    (keymap-global-set "<f10>" #'tmm-menubar)
    (advice-add #'tmm-add-prompt :after #'minibuffer-hide-completions)
```

## ffap-menu

<!-- **NOTE**: I have implemented a fix for this problem which is part of Emacs 31. You can set `completion-eager-display` to `nil` in your configuration. See [bug#74616](https://debbugs.gnu.org/cgi/bugreport.cgi?bug=74616) for the upstream bug report. -->

**注意**: わたしは以下の問題にたいする修正を実装した。Emacs 31に含まれることになるだろう。構成で`completion-eager-display`に`nil`をセットするのだ。アップストリームのバグレポートについては[bug#74616](https://debbugs.gnu.org/cgi/bugreport.cgi?bug=74616)を参照のこと。

<!-- The command `ffap-menu` shows the `*Completions*` buffer by default like `tmm-menubar`, which is unwanted if Vertico is used. The completions buffer can be disabled as follows. -->

コマンド`ffap-menu`はデフォルトでは`tmm-menubar`と同じように`*Completions*`を表示するが、Verticoを使っているのであれば望ましくないと思う。以下のようにして補完バッファーを無効にできる。

```lisp
    (advice-add #'ffap-menu-ask :around
                (lambda (&rest args)
                  (cl-letf (((symbol-function #'minibuffer-completion-help)
                             #'ignore))
                    (apply args))))
```

## completion-table-dynamic

<!-- Dynamic completion tables (`completion-table-dynamic`, `completion-table-in-turn`, &#x2026;) should work well with Vertico. The only requirement is that the `basic` completion style is enabled. The `basic` style performs prefix filtering by passing the input to the completion table (or the dynamic completion table function). The `basic` completion style must not necessarily be configured with highest priority, it can also come after other completion styles like `orderless`, `substring` or `flex`, as is also recommended by the Orderless documentation because of `completion-table-dynamic`. -->

動的な補完テーブル(`completion-table-dynamic`、`completion-table-in-turn`、...)にたいしてVerticoは良好に機能する筈だ。唯一必要なのは補完スタイル`basic`が有効になっていることだけである。`basic`スタイルは入力を補完テーブル(または動的補完テーブル関数)に入力を渡すことで、プレフィックスのフィルタリングを処理している。補完スタイルとして`basic`が最高の優先度で構成されている必要はない。`orderless`、`substring`、`flex`のような補完の補完スタイルより低い優先度で問題ない。これはOrderlessのドキュメントで推奨されているように、`completion-table-dynamic`のためだ。

```lisp
    (setq completion-styles '(basic))
    ;; (setq completion-styles '(orderless basic))
    (completing-read "Dynamic: "
                     (completion-table-dynamic
                      (lambda (str)
                        (list (concat str "1")
                              (concat str "2")
                              (concat str "3")))))
```

## 空文字列の入力

<!-- The commands `multi-occur`, `auto-insert`, `bbdb-create` read multiple arguments from the minibuffer with `completing-read`, one at a time, until you submit an empty string. You should type `M-RET` (`vertico-exit-input`) to finish the loop. Directly pressing `RET` (`vertico-exit`) does not work since the first candidate is preselected. -->

`multi-occur`、`auto-insert`、`bbdb-create`といったコマンドは`completing-read`を用いてミニバッファーから複数の引数を読み取る。空の文字列が入力されるまで1回ずつ読み取るのだ。このループを終了させるには`M-RET` (`vertico-exit-input`)をタイプするべきだろう。最初の候補が事前選択されているので、直接`RET` (`vertico-exit`)を押下しても機能しないのだ。

<!-- The underlying issue is that `completing-read` always allows you to exit with the empty string, which is called the *null completion*, even if the `REQUIRE-MATCH` argument is non-nil. Try the following two calls to `completing-read` with `C-x C-e`: -->

ループから抜け出すために`completing-read`が常に空文字列を許容するという点に問題が隠れている。これはたとえ引数`REQUIRE-MATCH`が非`nil`であったとしても、*NULL補完(null completion)*と呼ばれる補完なのだ。`C-x C-e`で以下の2つの`completing-read`を呼び出してみよう:

```lisp
    (completing-read "Select: " '("first" "second" "third") nil 'require-match)
    (completing-read "Select: " '("first" "second" "third") nil 'require-match nil nil "")
```

<!-- In both cases the empty string can be submitted. In the first case no explicit default value is specified and Vertico preselects the **first** candidate. In order to exit with the empty string, press `M-RET`. In the second case the explicit default value "" is specified and Vertico preselects the prompt, such that exiting with the empty string is possible by pressing `RET` only. -->

どちらの場合でも空文字列が入力される。1つ目はデフォルトの値が明示的に指定されておらず、Verticoが事前に**1つ目**の候補を選択している場合だ。空文字列で終えるためには`M-RET`を押下する必要がある。2つ目ではデフォルトの値として""が明示的に指定されているのでVerticoが事前に選択するのはプロンプトだ。これなら`RET`を押下するだけで空文字列で終えることが可能である。

## Trampでのhostname/usernameの補完

<!-- **NOTE:** On Emacs 29.2 and Tramp 2.7 the workarounds described in this section are not necessary anymore, since the relevant completion tables have been improved. -->

**注意:** Emacs 29.2とTramp 2.7では関連する補完テーブルが改良されたので、このセクションに記した回避策は不要になった。

<!-- In combination with Orderless or other non-prefix completion styles like `substring` or `flex`, host names and user names are not made available for completion after entering `/ssh:`. In order to avoid this problem, the `basic` completion style should be specified for the file completion category, such that `basic` is tried before `orderless`. This can be achieved by putting `basic` first in the completion style overrides for the file completion category. -->

Orderlessや`substring`、`flex`といった非プレフィックスな補完スタイルでは、`/ssh:`を入力した後はホスト名やユーザー名で補完が利用できなくなる。この問題を回避するためには、ファイルの補完カテゴリーで`orderless`の前に`basic`が試行されるように`basic`補完スタイルを指定する必要がある。これはファイルの補完カテゴリーをオーバーライドするように、補完スタイルの最初に`basic`を配置することで実現できるだろう。

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

<!-- If you are familiar with the `completion-style` machinery, you may also define a custom completion style which activates only for remote files. The custom completion style ensures that you can always match substrings within non-remote file names, since `orderless` will stay the preferred style for non-remote files. -->

`completion-style`の仕組みに馴染みがあれば、リモートのファイルにたいしてのみアクティブになるカスタム補完テーブルの定義もできる。このカスタム補完スタイルでリモート以外のファイル名の一部にマッチするようにすれば、リモート以外のファイルにたいしては依然として`orderless`スタイルの優先が維持されるだろう。

```lisp
    (defun basic-remote-try-completion (string table pred point)
      (and (vertico--remote-p string)
           (completion-basic-try-completion string table pred point)))
    (defun basic-remote-all-completions (string table pred point)
      (and (vertico--remote-p string)
           (completion-basic-all-completions string table pred point)))
    (add-to-list
     'completion-styles-alist
     '(basic-remote basic-remote-try-completion basic-remote-all-completions nil))
    (setq completion-styles '(orderless basic)
          completion-category-defaults nil
          completion-category-overrides '((file (styles basic-remote partial-completion))))
```