[nongnu] elpa/bash-completion 21df87bf0d 1/2: Add bash-completion-capf-nonexclusive

[ELPA Syncer]

branch: elpa/bash-completion
commit 21df87bf0d0caaa17578b4905a85307f0ef7272b
Author: Xiaoyue Chen <xchen@vvvu.org>
Commit: Xiaoyue Chen <xchen@vvvu.org>

    Add bash-completion-capf-nonexclusive
---
 README.md          | 55 ++++++++++++++++++++++++++----------------------------
 bash-completion.el | 25 +++++++++++++++++++++++++
 2 files changed, 51 insertions(+), 29 deletions(-)

diff --git a/README.md b/README.md
index ca82aa4cb1..c6219ddb51 100644
--- a/README.md
+++ b/README.md
@@ -64,41 +64,38 @@ from normal shell processes.
 
 ### Completion at point
 
-Additionally, you can enable bash completion in any buffer that contains bash 
-commands. To do that, call 
+You can also use bash completion as an additional completion function
+in any buffer that contains bash commands. To do that, add
+`bash-completion-capf-nonexclusive` to the buffer-local
+`completion-at-point-functions`. For example, you can setup bash
+completion in `eshell-mode` by invoking
+
 ```elisp
-(bash-completion-dynamic-complete-nocomint COMP-START COMP-POS DYNAMIC-TABLE)
-``` 
-from a function added to `completion-at-point-functions`. 
+(add-hook 'eshell-mode-hook
+          (lambda ()
+            (add-hook 'completion-at-point-functions
+                      'bash-completion-capf-nonexclusive nil t)))
+```
 
-The trickiest part is setting COMP-START to where the bash command starts;
-It depends on the mode of the calling buffer and might, in some cases, span 
-multiple lines.
+There is also a lower-level function
+`bash-completion-dynamic-complete-nocomint` which allows you to
+construct your own `completion-at-point` function.
 
-COMP-POS is usually the current position of the cursor.
+```elisp
+(bash-completion-dynamic-complete-nocomint COMP-START COMP-POS DYNAMIC-TABLE)
+```
 
-When calling from `completion-at-point`, make sure to pass a non-nil value 
-to the DYNAMIC-TABLE argument so it returns a function instead of a list
-of strings. This isn't just an optimization: returning a function instead 
-of a list tells Emacs it should avoids post-filtering the results and 
-possibly discarding useful completion from bash.
+COMP-START is where the bash command starts --- it depends on the mode
+of the calling buffer. In most cases, `line-beginning-position` works
+because it uses `field` boundaries.
 
-For example, here's a function to to do bash completion from an 
-eshell buffer. To try it out, add the function below to your init file
-and bind `bash-completion-from-eshell` to a custom shortcut.
+COMP-POS is usually the current position of the cursor.
 
-```elisp
-(defun bash-completion-from-eshell ()
-  (interactive)
-  (let ((completion-at-point-functions
-         '(bash-completion-eshell-capf)))
-    (completion-at-point)))
-
-(defun bash-completion-eshell-capf ()
-  (bash-completion-dynamic-complete-nocomint
-   (save-excursion (eshell-bol) (point))
-   (point) t))
-```
+When calling from `completion-at-point`, make sure to pass a non-nil
+value to the DYNAMIC-TABLE argument so it returns a function instead
+of a list of strings. This isn't just an optimization: returning a
+function instead of a list tells Emacs it should avoids post-filtering
+the results and possibly discarding useful completion from bash.
 
 ## TROUBLESHOOTING
 
diff --git a/bash-completion.el b/bash-completion.el
index 6123ed084e..070f94a1a3 100644
--- a/bash-completion.el
+++ b/bash-completion.el
@@ -33,6 +33,17 @@
 ;;
 ;; to your initialisation file.
 ;;
+;; You can also use bash completion as an additional completion
+;; function in any buffer that contains bash commands. To do that, add
+;; `bash-completion-capf-nonexclusive' to the buffer-local
+;; `completion-at-point-functions'. For example, you can setup bash
+;; completion in `eshell-mode' by invoking
+;;
+;; (add-hook 'eshell-mode-hook
+;;           (lambda ()
+;;             (add-hook 'completion-at-point-functions
+;;                       'bash-completion-capf-nonexclusive nil t)))
+;;
 ;; The completion will be aware of bash builtins, alii and functions.
 ;; It does file expansion does file expansion inside of
 ;; colon-separated variables and after redirections (> or <), and
@@ -524,6 +535,20 @@ When doing completion outside of a comint buffer, call
       (if message-timer
           (cancel-timer message-timer)))))
 
+;;;###autoload
+(defun bash-completion-capf-nonexclusive ()
+  "Bash completion function for `completion-at-point-functions'.
+
+Returns the same list as the one returned by
+`bash-completion-dynamic-complete-nocomint' appended with
+\(:exclusive no) so that other completion functions are tried
+when bash-completion fails to match the text at point."
+  (let ((compl (bash-completion-dynamic-complete-nocomint
+                (line-beginning-position)
+                (point) t)))
+    (when compl
+      (append compl '(:exclusive no)))))
+
 ;;;###autoload
 (defun bash-completion-dynamic-complete-nocomint
     (comp-start &optional comp-pos dynamic-table)