X-Git-Url: https://code.delx.au/gnu-emacs-elpa/blobdiff_plain/27c913afb9446971d1e0f1f3b272e5650a6206c5..433ae926feed34b90251e94ad5df7fb26a786e5a:/company.el diff --git a/company.el b/company.el index 8bb7ea338..96bfbf06a 100644 --- a/company.el +++ b/company.el @@ -27,12 +27,12 @@ ;;; Commentary: ;; ;; Company is a modular completion mechanism. Modules for retrieving completion -;; candidates are called back-ends, modules for displaying them are front-ends. +;; candidates are called backends, modules for displaying them are frontends. ;; -;; Company comes with many back-ends, e.g. `company-elisp'. These are +;; Company comes with many backends, e.g. `company-elisp'. These are ;; distributed in separate files and can be used individually. ;; -;; Place company.el and the back-ends you want to use in a directory and add the +;; Place company.el and the backends you want to use in a directory and add the ;; following to your .emacs: ;; (add-to-list 'load-path "/path/to/company") ;; (autoload 'company-mode "company" nil t) @@ -40,11 +40,11 @@ ;; Enable company-mode with M-x company-mode. For further information look at ;; the documentation for `company-mode' (C-h f company-mode RET) ;; -;; If you want to start a specific back-end, call it interactively or use +;; If you want to start a specific backend, call it interactively or use ;; `company-begin-backend'. For example: ;; M-x company-abbrev will prompt for and insert an abbrev. ;; -;; To write your own back-end, look at the documentation for `company-backends'. +;; To write your own backend, look at the documentation for `company-backends'. ;; Here is a simple example completing "foo": ;; ;; (defun company-my-backend (command &optional arg &rest ignored) @@ -54,9 +54,9 @@ ;; (`candidates (list "foobar" "foobaz" "foobarbaz")) ;; (`meta (format "This value is named %s" arg)))) ;; -;; Sometimes it is a good idea to mix several back-ends together, for example to +;; Sometimes it is a good idea to mix several backends together, for example to ;; enrich gtags with dabbrev-code results (to emulate local variables). -;; To do this, add a list with both back-ends as an element in company-backends. +;; To do this, add a list with both backends as an element in company-backends. ;; ;;; Change Log: ;; @@ -74,7 +74,7 @@ (add-to-list 'debug-ignored-errors "^Company not ") (add-to-list 'debug-ignored-errors "^No candidate number ") (add-to-list 'debug-ignored-errors "^Cannot complete at point$") -(add-to-list 'debug-ignored-errors "^No other back-end$") +(add-to-list 'debug-ignored-errors "^No other backend$") ;;; Compatibility (eval-and-compile @@ -212,8 +212,8 @@ buffer-local wherever it is set." (defcustom company-frontends '(company-pseudo-tooltip-unless-just-one-frontend company-preview-if-just-one-frontend company-echo-metadata-frontend) - "The list of active front-ends (visualizations). -Each front-end is a function that takes one argument. It is called with + "The list of active frontends (visualizations). +Each frontend is a function that takes one argument. It is called with one of the following arguments: `show': When the visualization should start. @@ -323,25 +323,25 @@ This doesn't include the margins and the scroll bar." (company-dabbrev-code company-gtags company-etags company-keywords) company-oddmuse company-files company-dabbrev) - "The list of active back-ends (completion engines). + "The list of active backends (completion engines). -Only one back-end is used at a time. The choice depends on the order of +Only one backend is used at a time. The choice depends on the order of the items in this list, and on the values they return in response to the -`prefix' command (see below). But a back-end can also be a \"grouped\" +`prefix' command (see below). But a backend can also be a \"grouped\" one (see below). -`company-begin-backend' can be used to start a specific back-end, -`company-other-backend' will skip to the next matching back-end in the list. +`company-begin-backend' can be used to start a specific backend, +`company-other-backend' will skip to the next matching backend in the list. -Each back-end is a function that takes a variable number of arguments. -The first argument is the command requested from the back-end. It is one +Each backend is a function that takes a variable number of arguments. +The first argument is the command requested from the backend. It is one of the following: -`prefix': The back-end should return the text to be completed. It must be +`prefix': The backend should return the text to be completed. It must be text immediately before point. Returning nil from this command passes -control to the next back-end. The function should return `stop' if it +control to the next backend. The function should return `stop' if it should complete but cannot (e.g. if it is in the middle of a string). -Instead of a string, the back-end may return a cons where car is the prefix +Instead of a string, the backend may return a cons where car is the prefix and cdr is used instead of the actual prefix length in the comparison against `company-minimum-prefix-length'. It must be either number or t, and in the latter case the test automatically succeeds. @@ -354,7 +354,8 @@ prefix, but match it in some backend-defined way). Backends that use this feature must disable cache (return t to `no-cache') and might also want to respond to `match'. -Optional commands: +Optional commands +================= `sorted': Return t here to indicate that the candidates are sorted and will not need to be sorted again. @@ -363,16 +364,23 @@ not need to be sorted again. from the list. `no-cache': Usually company doesn't ask for candidates again as completion -progresses, unless the back-end returns t for this command. The second +progresses, unless the backend returns t for this command. The second argument is the latest prefix. +`ignore-case': Return t here if the backend returns case-insensitive +matches. This value is used to determine the longest common prefix (as +used in `company-complete-common'), and to filter completions when fetching +them from cache. + `meta': The second argument is a completion candidate. Return a (short) documentation string for it. `doc-buffer': The second argument is a completion candidate. Return a -buffer with documentation for it. Preferably use `company-doc-buffer', +buffer with documentation for it. Preferably use `company-doc-buffer'. If +not all buffer contents pertain to this candidate, return a cons of buffer +and window start position. -`location': The second argument is a completion candidate. Return the cons +`location': The second argument is a completion candidate. Return a cons of buffer and buffer location, or of file and line number where the completion candidate was defined. @@ -394,35 +402,39 @@ backends. The default value nil gives the user that choice with `company-require-match'. Return value `never' overrides that option the other way around. -`init': Called once for each buffer. The back-end can check for external +`init': Called once for each buffer. The backend can check for external programs and files and load any required libraries. Raising an error here -will show up in message log once, and the back-end will not be used for +will show up in message log once, and the backend will not be used for completion. `post-completion': Called after a completion candidate has been inserted into the buffer. The second argument is the candidate. Can be used to modify it, e.g. to expand a snippet. -The back-end should return nil for all commands it does not support or +The backend should return nil for all commands it does not support or does not know about. It should also be callable interactively and use `company-begin-backend' to start itself in that case. -Grouped back-ends: - -An element of `company-backends' can also itself be a list of back-ends, -then it's considered to be a \"grouped\" back-end. +Grouped backends +================ -When possible, commands taking a candidate as an argument are dispatched to -the back-end it came from. In other cases, the first non-nil value among -all the back-ends is returned. +An element of `company-backends' can also be a list of backends. The +completions from backends in such groups are merged, but only from those +backends which return the same `prefix'. -The latter is the case for the `prefix' command. But if the group contains -the keyword `:with', the back-ends after it are ignored for this command. +If a backend command takes a candidate as an argument (e.g. `meta'), the +call is dispatched to the backend the candidate came from. In other +cases (except for `duplicates' and `sorted'), the first non-nil value among +all the backends is returned. -The completions from back-ends in a group are merged (but only from those -that return the same `prefix'). +The group can also contain keywords. Currently, `:with' and `:sorted' +keywords are defined. If the group contains keyword `:with', the backends +listed after this keyword are ignored for the purpose of the `prefix' +command. If the group contains keyword `:sorted', the final list of +candidates is not sorted after concatenation. -Asynchronous back-ends: +Asynchronous backends +===================== The return value of each command can also be a cons (:async . FETCHER) where FETCHER is a function of one argument, CALLBACK. When the data @@ -431,15 +443,15 @@ value, as described above. True asynchronous operation is only supported for command `candidates', and only during idle completion. Other commands will block the user interface, -even if the back-end uses the asynchronous calling convention." +even if the backend uses the asynchronous calling convention." :type `(repeat (choice - :tag "Back-end" + :tag "backend" ,@(mapcar (lambda (b) `(const :tag ,(cdr b) ,(car b))) company-safe-backends) (symbol :tag "User defined") - (repeat :tag "Merged Back-ends" - (choice :tag "Back-end" + (repeat :tag "Merged backends" + (choice :tag "backend" ,@(mapcar (lambda (b) `(const :tag ,(cdr b) ,(car b))) company-safe-backends) @@ -457,7 +469,7 @@ without duplicates." :type '(choice (const :tag "None" nil) (const :tag "Sort by occurrence" (company-sort-by-occurrence)) - (const :tag "Sort by back-end importance" + (const :tag "Sort by backend importance" (company-sort-by-backend-importance)) (repeat :tag "User defined" (function)))) @@ -478,7 +490,7 @@ aborted manually." The hook is called with the selected candidate as an argument. If you indend to use it to post-process candidates from a specific -back-end, consider using the `post-completion' command instead." +backend, consider using the `post-completion' command instead." :type 'hook) (defcustom company-minimum-prefix-length 3 @@ -496,7 +508,7 @@ prefix it was started from." "If enabled, disallow non-matching input. This can be a function do determine if a match is required. -This can be overridden by the back-end, if it returns t or `never' to +This can be overridden by the backend, if it returns t or `never' to `require-match'. `company-auto-complete' also takes precedence over this." :type '(choice (const :tag "Off" nil) (function :tag "Predicate function") @@ -651,7 +663,7 @@ asynchronous call into synchronous.") (error (put backend 'company-init 'failed) (unless (memq backend company--disabled-backends) - (message "Company back-end '%s' could not be initialized:\n%s" + (message "Company backend '%s' could not be initialized:\n%s" backend (error-message-string err))) (cl-pushnew backend company--disabled-backends) nil))) @@ -699,9 +711,12 @@ Completions can be searched with `company-search-candidates' or inactive, as well. The completion data is retrieved using `company-backends' and displayed -using `company-frontends'. If you want to start a specific back-end, call +using `company-frontends'. If you want to start a specific backend, call it interactively or use `company-begin-backend'. +By default, the completions list is sorted alphabetically, unless the +backend chooses otherwise, or `company-transformers' changes it later. + regular keymap (`company-mode-map'): \\{company-mode-map} @@ -864,7 +879,7 @@ means that `company-mode' is always turned on except in `message-mode' buffers." (lambda (result) (setq res result))) (while (eq res 'trash) (if (> (- (time-to-seconds) start) company-async-timeout) - (error "Company: Back-end %s async timeout with args %s" + (error "Company: backend %s async timeout with args %s" backend args) (sleep-for company-async-wait))) res)))) @@ -874,7 +889,7 @@ means that `company-mode' is always turned on except in `message-mode' buffers." (if (functionp company-backend) (apply company-backend args) (apply #'company--multi-backend-adapter company-backend args)) - (error (error "Company: Back-end %s error \"%s\" with args %s" + (error (error "Company: backend %s error \"%s\" with args %s" company-backend (error-message-string err) args)))) (defun company--multi-backend-adapter (backends command &rest args) @@ -882,14 +897,17 @@ means that `company-mode' is always turned on except in `message-mode' buffers." when (not (and (symbolp b) (eq 'failed (get b 'company-init)))) collect b))) - (setq backends - (if (eq command 'prefix) - (butlast backends (length (member :with backends))) - (delq :with backends))) + + (when (eq command 'prefix) + (setq backends (butlast backends (length (member :with backends))))) + + (unless (memq command '(sorted)) + (setq backends (cl-delete-if #'keywordp backends))) + (pcase command (`candidates (company--multi-backend-adapter-candidates backends (car args))) - (`sorted nil) + (`sorted (memq :sorted backends)) (`duplicates t) ((or `prefix `ignore-case `no-cache `require-match) (let (value) @@ -1006,7 +1024,7 @@ Controlled by `company-auto-complete'.") (defmacro company-with-candidate-inserted (candidate &rest body) "Evaluate BODY with CANDIDATE temporarily inserted. -This is a tool for back-ends that need candidates inserted before they +This is a tool for backends that need candidates inserted before they can retrieve meta-data for them." (declare (indent 1)) `(let ((inhibit-modification-hooks t) @@ -1054,7 +1072,7 @@ can retrieve meta-data for them." (dolist (frontend company-frontends) (condition-case-unless-debug err (funcall frontend command) - (error (error "Company: Front-end %s error \"%s\" on command %s" + (error (error "Company: frontend %s error \"%s\" on command %s" frontend (error-message-string err) command))))) (defun company-set-selection (selection &optional force-update) @@ -1282,8 +1300,8 @@ Keywords and function definition names are ignored." (defun company-sort-by-backend-importance (candidates) "Sort CANDIDATES as two priority groups. If `company-backend' is a function, do nothing. If it's a list, move -candidates from back-ends before keyword `:with' to the front. Candidates -from the rest of the back-ends in the group, if any, will be left at the end." +candidates from backends before keyword `:with' to the front. Candidates +from the rest of the backends in the group, if any, will be left at the end." (if (functionp company-backend) candidates (let ((low-priority (cdr (memq :with company-backend)))) @@ -1347,7 +1365,7 @@ from the rest of the back-ends in the group, if any, will be left at the end." (when (ignore-errors (company-begin-backend backend)) (cl-return t)))) (unless company-candidates - (error "No other back-end"))) + (error "No other backend"))) (defun company-require-match-p () (let ((backend-value (company-call-backend 'require-match))) @@ -1462,10 +1480,14 @@ from the rest of the back-ends in the group, if any, will be left at the end." (setq company-prefix (company--prefix-str prefix) company-backend backend c (company-calculate-candidates company-prefix)) - ;; t means complete/unique. We don't start, so no hooks. (if (not (consp c)) - (when company--manual-action - (message "No completion found")) + (progn + (when company--manual-action + (message "No completion found")) + (when (eq c t) + ;; t means complete/unique. + ;; Run the hooks anyway, to e.g. clear the cache. + (company-cancel 'unique))) (when company--manual-action (setq company--manual-prefix prefix)) (company-update-candidates c) @@ -1560,6 +1582,7 @@ from the rest of the back-ends in the group, if any, will be left at the end." (if company-candidates (company-call-frontends 'post-command) (and (numberp company-idle-delay) + (not defining-kbd-macro) (company--should-begin) (setq company-timer (run-with-timer company-idle-delay nil @@ -1941,6 +1964,20 @@ With ARG, move by that many elements." (current-prefix-arg arg)) (call-interactively 'company-select-next)))))) +(defun company-indent-or-complete-common () + "Indent the current line or region, or complete the common part." + (interactive) + (cond + ((use-region-p) + (indent-region (region-beginning) (region-end))) + ((let ((old-point (point)) + (old-tick (buffer-chars-modified-tick)) + (tab-always-indent t)) + (call-interactively #'indent-for-tab-command) + (when (and (eq old-point (point)) + (eq old-tick (buffer-chars-modified-tick))) + (company-complete-common)))))) + (defun company-complete () "Insert the common part of all candidates or the current selection. The first time this is called, the common part is inserted, the second @@ -1956,7 +1993,7 @@ inserted." (defun company-complete-number (n) "Insert the Nth candidate visible in the tooltip. -To show the number next to the candidates in some back-ends, enable +To show the number next to the candidates in some backends, enable `company-show-numbers'. When called interactively, uses the last typed character, stripping the modifiers. That character must be a digit." (interactive @@ -2061,11 +2098,14 @@ character, stripping the modifiers. That character must be a digit." (company--electric-do (let* ((selected (nth company-selection company-candidates)) (doc-buffer (or (company-call-backend 'doc-buffer selected) - (error "No documentation available")))) + (error "No documentation available"))) + start) + (when (consp doc-buffer) + (setq start (cdr doc-buffer) + doc-buffer (car doc-buffer))) (setq other-window-scroll-buffer (get-buffer doc-buffer)) - (with-current-buffer doc-buffer - (goto-char (point-min))) - (display-buffer doc-buffer t))))) + (let ((win (display-buffer doc-buffer t))) + (set-window-start win (if start start (point-min)))))))) (put 'company-show-doc-buffer 'company-keep t) (defun company-show-location () @@ -2100,7 +2140,7 @@ character, stripping the modifiers. That character must be a digit." (defun company-begin-backend (backend &optional callback) "Start a completion at point using BACKEND." - (interactive (let ((val (completing-read "Company back-end: " + (interactive (let ((val (completing-read "Company backend: " obarray 'functionp nil "company-"))) (when val @@ -2333,7 +2373,7 @@ If SHOW-VERSION is non-nil, show the version in the echo area." (while (and (not (eobp)) ; http://debbugs.gnu.org/19553 (> (setq lines-moved (vertical-motion 1)) 0) (<= (point) end)) - (let ((bound (min end (1- (point))))) + (let ((bound (min end (point)))) ;; A visual line can contain several physical lines (e.g. with outline's ;; folding overlay). Take only the first one. (push (buffer-substring beg @@ -2381,8 +2421,12 @@ If SHOW-VERSION is non-nil, show the version in the echo area." (or (cdr margins) 0))))) (when (and word-wrap (version< emacs-version "24.4.51.5")) - ;; http://debbugs.gnu.org/18384 + ;; http://debbugs.gnu.org/19300 (cl-decf ww)) + ;; whitespace-mode with newline-mark + (when (and buffer-display-table + (aref buffer-display-table ?\n)) + (cl-decf ww (1- (length (aref buffer-display-table ?\n))))) ww)) (defun company--replacement-string (lines old column nl &optional align-top) @@ -2417,8 +2461,7 @@ If SHOW-VERSION is non-nil, show the version in the echo area." (company--offset-line (pop lines) offset)) new)) - (let ((str (concat (when nl " ") - "\n" + (let ((str (concat (when nl " \n") (mapconcat 'identity (nreverse new) "\n") "\n"))) (font-lock-append-text-property 0 (length str) 'face 'default str) @@ -2570,7 +2613,7 @@ Returns a negative number if the tooltip should be displayed above point." (end (save-excursion (move-to-window-line (+ row (abs height))) (point))) - (ov (make-overlay (if nl beg (1- beg)) end nil t)) + (ov (make-overlay beg end nil t)) (args (list (mapcar 'company-plainify (company-buffer-lines beg end)) column nl above))) @@ -2611,7 +2654,9 @@ Returns a negative number if the tooltip should be displayed above point." (defun company-pseudo-tooltip-hide-temporarily () (when (overlayp company-pseudo-tooltip-overlay) (overlay-put company-pseudo-tooltip-overlay 'invisible nil) - (overlay-put company-pseudo-tooltip-overlay 'after-string nil))) + (overlay-put company-pseudo-tooltip-overlay 'line-prefix nil) + (overlay-put company-pseudo-tooltip-overlay 'after-string nil) + (overlay-put company-pseudo-tooltip-overlay 'display nil))) (defun company-pseudo-tooltip-unhide () (when company-pseudo-tooltip-overlay @@ -2619,12 +2664,15 @@ Returns a negative number if the tooltip should be displayed above point." (disp (overlay-get ov 'company-display))) ;; Beat outline's folding overlays, at least. (overlay-put ov 'priority 1) - ;; `display' could be better (http://debbugs.gnu.org/18285), but it - ;; doesn't work when the overlay is empty, which is what happens at eob. - ;; It also seems to interact badly with `cursor'. - ;; We deal with priorities by having the overlay start before the newline. - (overlay-put ov 'after-string disp) - (overlay-put ov 'invisible t) + ;; No (extra) prefix for the first line. + (overlay-put ov 'line-prefix "") + ;; `display' is better + ;; (http://debbugs.gnu.org/18285, http://debbugs.gnu.org/20847), + ;; but it doesn't work on 0-length overlays. + (if (< (overlay-start ov) (overlay-end ov)) + (overlay-put ov 'display disp) + (overlay-put ov 'after-string disp) + (overlay-put ov 'invisible t)) (overlay-put ov 'window (selected-window))))) (defun company-pseudo-tooltip-guard () @@ -2639,7 +2687,7 @@ Returns a negative number if the tooltip should be displayed above point." (when (>= overhang 0) overhang)))))) (defun company-pseudo-tooltip-frontend (command) - "`company-mode' front-end similar to a tooltip but based on overlays." + "`company-mode' frontend similar to a tooltip but based on overlays." (cl-case command (pre-command (company-pseudo-tooltip-hide-temporarily)) (post-command @@ -2719,7 +2767,7 @@ Returns a negative number if the tooltip should be displayed above point." (setq company-preview-overlay nil))) (defun company-preview-frontend (command) - "`company-mode' front-end showing the selection as if it had been inserted." + "`company-mode' frontend showing the selection as if it had been inserted." (pcase command (`pre-command (company-preview-hide)) (`post-command (company-preview-show-at-point (point))) @@ -2829,19 +2877,19 @@ Returns a negative number if the tooltip should be displayed above point." (company-echo-show))) (defun company-echo-frontend (command) - "`company-mode' front-end showing the candidates in the echo area." + "`company-mode' frontend showing the candidates in the echo area." (pcase command (`post-command (company-echo-show-soon 'company-echo-format)) (`hide (company-echo-hide)))) (defun company-echo-strip-common-frontend (command) - "`company-mode' front-end showing the candidates in the echo area." + "`company-mode' frontend showing the candidates in the echo area." (pcase command (`post-command (company-echo-show-soon 'company-echo-strip-common-format)) (`hide (company-echo-hide)))) (defun company-echo-metadata-frontend (command) - "`company-mode' front-end showing the documentation in the echo area." + "`company-mode' frontend showing the documentation in the echo area." (pcase command (`post-command (company-echo-show-when-idle 'company-fetch-metadata)) (`hide (company-echo-hide))))