|Campbell Barton d22df33d35|
Completion, providing a suggestion preview while typing.
The following features are supported:
- Minimal overhead (runs on idle).
- Non-blocking interaction, where any key (besides completion) will continue editing as expected.
- Input simulation. Useful when recording macros, so the literal text input is replayed instead of re-running the completion in a different context which may give a different result.
- Context sensitive, so entirely different completions can be configured based on kind of text being edited.
- Buffer local configuration. Each buffer can have it's own local completion configuration that may include project-local expansions.
The motivation for writing this package was to achieve something similar to completion I was used to on the FISH-shell which can be configured to suggest something based on previously used commands. While text entry in an editor doesn't lend it's self to command reuse in quite the same way, an ability to complete the most "likely" candidate is still possible.
In contrast to most existing completion systems in emacs, mono-complete focuses on providing a useful suggestion instead of a comprehensive list of candidates. This works well with natural language input (text input typically found on phone keyboards). Where statistical analysis can run on existing text (including code-comments, commit-logs and plain-text) to predict the most likely words to use based on previous words while typing.
Always previewing a completion is a convenient way to show text input might not have anticipated would be available in a way that isn't overly intrusive.
There can be multiple methods of generating suggestions which can all be enabled at once to increase the chance of showing a useful suggestion in any context.
The typical usage for this package is to enable the minor mode
mono-complete-mode, then bind a key to
Aside from this you may wish to customize the available back-ends, depending on the mode and language.
Enable mono-complete mode.
Expand the completion.
Expand the completion or run
mono-complete-fallback-commandwhen no preview is visible.
A list of back-ends (see Included Backends). For example
(list 'dabbrev 'filesystem 'word-predict).
Completion back-ends are evaluated in-order, the first back-end to return a result defines the suggestion that is shown.
Optionally this can be a function which takes a single
is-contextargument. When nil, return all backends which may be used, otherwise fewer backends may be returned based on the current context.
Using a function has the advantage that the back-ends returned can be context sensitive.
(setq mono-complete-backends (lambda (is-context) (cond (is-context (let* ((result (list)) (state (syntax-ppss)) (is-string (nth 3 state)) (is-comment (nth 4 state))) (when (or is-string is-comment) (push 'filesystem result)) (push 'dabbrev result) result)) (t (list 'dabbrev 'filesystem)))))
How long to wait until displaying the preview after a keystroke (in seconds).
A list of commands after which to show a preview.
The command to use when
mono-complete-expand-or-fallbackwas called without a preview.
Simulate literal text input.
When enabled replaying this action as a macro re-inserts the literal text instead of performing the completion action (which may give different results).
Restrict to insert mode when used in combination with
The directory to store mono-complete cache data.
The function to use to detect the project root from the current buffer.
default-directoryis used when this function returns nil.
Face used to display the preview.
Here is an example using
(use-package mono-complete :config (setq mono-complete-fallback-command 'tab-to-tab-stop) (define-key mono-complete-mode-map (kbd "<tab>") 'mono-complete-expand-or-fallback) :commands (mono-complete-mode) :hook ((prog-mode) . mono-complete-mode))
Complete using emacs built-in completion-at-point.
The completion-at-point function to use or nil to use the default (
Complete using words in the buffer.
Complete using paths on the file-system.
Complete the word using the
Complete whole lines.
How to treat text trailing the cursor.
- "Match Trailing" completion lines must match text after the cursor. This text is trimmed from the completion suggestion.
- "No Trailing" completion is only performed when there is no trailing text.
- "Ignore Trailing" completion ignores text after the cursor.
Predict the next word using previous words based on a simple statistical model (N-grams).
This handles both extracting data from source code & text files as well as using that data for completion.
Note that this depends on Python.
A list of file extensions to match as source files (only code comments are extracted).
A list of file extensions to match as regular text (all text is extracted).
Files larger than this are skipped.
List of paths used for extracting text (an empty string uses the projects root).
Method used for validating the model, a symbol in:
when-missing: extract data if it doesn't exist.
from-manifest: extract data when files are outdated.