common-part: rename to `match' and document

diff --git a/NEWS.md b/NEWS.md
index 8fe5ee69afe52905fab2d646942ac3b79762d471..6dd9005a4a27ba9f2d4618382870e063ab6056c3 100644 (file)
--- a/NEWS.md
+++ b/NEWS.md
@@ -2,6 +2,7 @@
 
 ## Next
 
+* New back-end command, `match`, for non-prefix completion.
 * New user option `company-continue-commands`.
 * New back-end command, `annotation`, for text displayed inline in the popup
   that's not a part of completion candidate.

diff --git a/company-capf.el b/company-capf.el
index eeb543b22e1d23d4fb148927943f33c222b2bf10..17be772126736ab282b2524fd509c8cc190a9c7f 100644 (file)
--- a/company-capf.el
+++ b/company-capf.el
@@ -88,7 +88,7 @@ Requires Emacs 24.1 or newer."
                       (buffer-substring (nth 1 res) (nth 2 res))
                       (nth 3 res) (plist-get (nthcdr 4 res) :predicate))))
            (cdr (assq 'display-sort-function meta))))))
-    (`common-part
+    (`match
      ;; Can't just use 0 when base-size (see above) is non-zero.
      (let ((start (if (get-text-property 0 'font-lock-face arg)
                       0

diff --git a/company.el b/company.el
index 235e8e135118f792583b29454830b824b07a914f..6275dea30a748d5d8c8d9acf6308c8a29bbbcb3b 100644 (file)
--- a/company.el
+++ b/company.el
@@ -315,11 +315,16 @@ text immediately before point.  Returning nil passes control to the next
 back-end.  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 and cdr is used in
-`company-minimum-prefix-length' test. It's either number or t, in which
-case the test automatically succeeds.
+`company-minimum-prefix-length' test.  It must be either number or t, and
+in the latter case the test automatically succeeds.
 
 `candidates': The second argument is the prefix to be completed.  The
-return value should be a list of candidates that start with the prefix.
+return value should be a list of candidates that match the prefix.
+
+Non-prefix matches are also supported (candidates that don't start with the
+prefix, but match it in some backend-defined way).  Backends that use this
+feature must disable cache (return t to `no-cache') and should also respond
+to `match'.
 
 Optional commands:
 
@@ -343,13 +348,18 @@ buffer with documentation for it.  Preferably use `company-doc-buffer',
 of buffer and buffer location, or of file and line number where the
 completion candidate was defined.
 
-`annotation': The second argument is a completion candidate.  Returns a
+`annotation': The second argument is a completion candidate.  Return a
 string to be displayed inline with the candidate in the popup.  If
 duplicates are removed by company, candidates with equal string values will
 be kept if they have different annotations.  For that to work properly,
-backends should store the related information with candidates using text
+backends should store the related information on candidates using text
 properties.
 
+`match': The second argument is a completion candidate.  Backends that
+provide non-prefix completions should return the position of the end of
+text in the candidate that matches `prefix'.  It will be used when
+rendering the popup.
+
 `require-match': If this returns t, the user is not allowed to enter
 anything not offered as a candidate.  Use with care!  The default value nil
 gives the user that choice with `company-require-match'.  Return value
@@ -1837,7 +1847,7 @@ Example: \(company-begin-with '\(\"foo\" \"foobar\" \"foobarbaz\"\)\)"
 
 (defun company-fill-propertize (value annotation width selected left right)
   (let* ((margin (length left))
-         (common (+ (or (company-call-backend 'common-part value)
+         (common (+ (or (company-call-backend 'match value)
                         (length company-common)) margin))
          (ann-start (+ margin (length value)))
          (line (concat left