diff options
Diffstat (limited to 'README.org')
| -rw-r--r-- | README.org | 221 |
1 files changed, 0 insertions, 221 deletions
diff --git a/README.org b/README.org deleted file mode 100644 index 55f7330..0000000 --- a/README.org +++ /dev/null @@ -1,221 +0,0 @@ -#+title: cape.el - Let your completions fly! -#+author: Daniel Mendler -#+language: en -#+export_file_name: cape.texi -#+texinfo_dir_category: Emacs -#+texinfo_dir_title: Cape: (cape). -#+texinfo_dir_desc: Completion At Point Extensions - -#+html: <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> -#+html: <a href="http://elpa.gnu.org/packages/cape.html"><img alt="GNU ELPA" src="https://elpa.gnu.org/packages/cape.svg"/></a> -#+html: <a href="http://elpa.gnu.org/devel/cape.html"><img alt="GNU-devel ELPA" src="https://elpa.gnu.org/devel/cape.svg"/></a> -#+html: <a href="https://melpa.org/#/cape"><img alt="MELPA" src="https://melpa.org/packages/cape-badge.svg"/></a> -#+html: <a href="https://stable.melpa.org/#/cape"><img alt="MELPA Stable" src="https://stable.melpa.org/packages/cape-badge.svg"/></a> -#+html: <img src="https://upload.wikimedia.org/wikipedia/en/3/35/Supermanflying.png" align="right"> - -* Introduction - -Cape provides a bunch of Completion At Point Extensions which can be used in -combination with my [[https://github.com/minad/corfu][Corfu]] completion UI or the default completion UI. The -completion backends used by ~completion-at-point~ are so called -~completion-at-point-functions~ (Capfs). In principle, the Capfs provided by Cape -can also be used by [[https://github.com/company-mode/company-mode][Company]]. - -You can register the ~cape-*~ functions in the ~completion-at-point-functions~ list. -This makes the backends available for completion, which is usually invoked by -pressing ~TAB~ or ~M-TAB~. The functions can also be invoked interactively to -trigger the respective completion at point. You can bind them directly to a key -in your user configuration. Notable commands/capfs are ~cape-line~ for completion -of a line from the current buffer and ~cape-file~ for completion of a file name. -The command ~cape-symbol~ is particularily useful for documentation of Elisp -packages or configurations, since it completes elisp symbols anywere. - -On the more experimental side, Cape has the super power to transform Company -backends into Capfs and merge multiple Capfs into a Super-Capf! These -transformers allow you to still take advantage of Company backends even if you -are not using Company as frontend. - -* Available Capfs - -+ ~cape-dabbrev~: Complete word from current buffers -+ ~cape-file~: Complete file name -+ ~cape-keyword~: Complete programming language keyword -+ ~cape-symbol~: Complete Elisp symbol -+ ~cape-abbrev~: Complete abbreviation (~add-global-abbrev~, ~add-mode-abbrev~) -+ ~cape-ispell~: Complete word from Ispell dictionary -+ ~cape-dict~: Complete word from dictionary file -+ ~cape-line~: Complete entire line from file -+ ~cape-tex~: Complete unicode char from TeX command, e.g. ~\hbar~. -+ ~cape-sgml~: Complete unicode char from Sgml entity, e.g., ~&alpha~. -+ ~cape-rfc1345~: Complete unicode char using RFC 1345 mnemonics. - -* Configuration - -Cape is available from MELPA. In the long term some of the Capfs provided by -this package should be upstreamed into Emacs itself. - -#+begin_src emacs-lisp - ;; Enable Corfu completion UI - ;; See the Corfu README for more configuration tips. - (use-package corfu - :init - (corfu-global-mode)) - - ;; Add extensions - (use-package cape - ;; Bind dedicated completion commands - :bind (("C-c p p" . completion-at-point) ;; capf - ("C-c p t" . complete-tag) ;; etags - ("C-c p d" . cape-dabbrev) ;; or dabbrev-completion - ("C-c p f" . cape-file) - ("C-c p k" . cape-keyword) - ("C-c p s" . cape-symbol) - ("C-c p a" . cape-abbrev) - ("C-c p i" . cape-ispell) - ("C-c p l" . cape-line) - ("C-c p w" . cape-dict) - ("C-c p \\" . cape-tex) - ("C-c p &" . cape-sgml) - ("C-c p r" . cape-rfc1345)) - :init - ;; Add `completion-at-point-functions', used by `completion-at-point'. - (add-to-list 'completion-at-point-functions #'cape-file) - (add-to-list 'completion-at-point-functions #'cape-tex) - (add-to-list 'completion-at-point-functions #'cape-dabbrev) - (add-to-list 'completion-at-point-functions #'cape-keyword) - ;;(add-to-list 'completion-at-point-functions #'cape-sgml) - ;;(add-to-list 'completion-at-point-functions #'cape-rfc1345) - ;;(add-to-list 'completion-at-point-functions #'cape-abbrev) - ;;(add-to-list 'completion-at-point-functions #'cape-ispell) - ;;(add-to-list 'completion-at-point-functions #'cape-dict) - ;;(add-to-list 'completion-at-point-functions #'cape-symbol) - ;;(add-to-list 'completion-at-point-functions #'cape-line) - ) -#+end_src - -* Experimental features - -** Company adapter - -/Wrap your Company backend in a Cape and turn it into a Capf!/ - -Cape provides an adapter for Company backends ~cape-company-to-capf~. The adapter -transforms Company backends to Capfs which are understood by the built-in Emacs -completion mechanism. The function is approximately the inverse of the -~company-capf~ backend from Company. The adapter is still experimental and may -have certain edge cases. The adapter can be used as follows: - -#+begin_src emacs-lisp - ;; Use Company backends as Capfs. - (setq-local completion-at-point-functions - (mapcar #'cape-company-to-capf - (list #'company-files #'company-ispell #'company-dabbrev))) -#+end_src - -Note that the adapter does not require Company to be installed. Backends -implementing the Company specification do not necessarily have to depend on -Company, however in practice most backends do. The following shows a small -example completion backend, which can be used with both ~completion-at-point~ -(Corfu, default completion) and Company. - -#+begin_src emacs-lisp - (defvar emojis - '((":-D" . "😀") - (";-)" . "😉") - (":-/" . "😕") - (":-(" . "🙁") - (":-*" . "😙"))) - - (defun emoji-backend (action &optional arg &rest _) - (pcase action - ('prefix (and (memq (char-before) '(?: ?\;)) - (cons (string (char-before)) t))) - ('candidates (all-completions arg emojis)) - ('annotation (concat " " (cdr (assoc arg emojis)))) - ('post-completion - (let ((str (buffer-substring (- (point) 3) (point)))) - (delete-region (- (point) 3) (point)) - (insert (cdr (assoc str emojis))))))) - - ;; Register emoji backend with `completion-at-point' - (setq completion-at-point-functions - (list (cape-company-to-capf #'emoji-backend))) - - ;; Register emoji backend with Company. - (setq company-backends '(emoji-backend)) -#+end_src - -It is possible to merge/group multiple Company backends and use them as a single -Capf using the ~company--multi-backend-adapter~ function from Company. The adapter -transforms multiple Company backends into a single Company backend, which can -then be used as a Capf via ~cape-company-to-capf~. - -#+begin_src emacs-lisp - (require 'company) - ;; Use the company-dabbrev and company-elisp backends together. - (setq completion-at-point-functions - (list - (cape-company-to-capf - (apply-partially #'company--multi-backend-adapter - '(company-dabbrev company-elisp))))) -#+end_src - -** Super-Capf - Merging multiple Capfs - -/Throw multiple Capfs under the Cape and get a Super-Capf!/ - -Cape supports merging multiple Capfs using the function ~cape-super-capf~. This -feature is experimental and should only be used in special scenarios. - -Note that ~cape-super-capf~ is not needed if you want to use multiple Capfs which -are tried one by one, e.g., it is perfectly possible to use ~cape-file~ together -with the lsp-mode Capf or other programming mode Capfs by adding ~cape-file~ to -the ~completion-at-point-functions~ list. The file completion will be available in -comments and string literals. ~cape-super-capf~ is only needed if you want to -combine multiple Capfs, such that the candidates from multiple sources appear -/together/ in the completion list at the same time. - -Completion table merging works only for tables which are sufficiently -well-behaved and tables which do not define completion boundaries. -~cape-super-capf~ has the same restrictions as ~completion-table-merge~ and -~completion-table-in-turn~. - -#+begin_src emacs-lisp - ;; Merge the dabbrev, dict and keyword capfs, display candidates together. - (setq-local completion-at-point-functions - (list (cape-super-capf #'cape-dabbrev #'cape-dict #'cape-keyword))) -#+end_src - -See also the aforementioned ~company--multi-backend-adapter~ from Company, which -allows you to merge multiple Company backends. - -** Capf-Buster - Cache busting - -/The Capf-Buster ensures that you always get a fresh set of candidates!/ - -If a Capf caches the candidates for too long we can use a cache busting -Capf-transformer. For example the Capf merging function ~cape-super-capf~ creates -a Capf, which caches the candidates for the whole lifetime of the Capf. -Therefore you may want to combine a merged Capf with a cache buster under some -circumstances. It is noteworthy that the ~company-capf~ backend from Company -refreshes the completion table frequently. With the ~cape-capf-buster~ we can -achieve a similarly refreshing strategy. - -#+begin_src emacs-lisp - (setq-local completion-at-point-functions - (list (cape-capf-buster #'some-caching-capf))) -#+end_src - -** Other Capf transformers - -- ~cape-silent-capf~: Wrap a chatty Capf and silence it. -- ~cape-noninterruptible-capf~: Protect a Capf which does not like to be interrupted. -- ~cape-interactive-capf~: Create a Capf which can be called interactively. -- ~cape-capf-case-fold~: Create a Capf which is case insensitive. -- ~cape-capf-with-properties~: Add completion properties to a Capf. -- ~cape-capf-with-predicate~: Add candidate predicate to a Capf. - -* Contributions - -Since this package is part of [[http://elpa.gnu.org/packages/marginalia.html][GNU ELPA]] contributions require a copyright -assignment to the FSF. |