[nongnu] elpa/bash-completion 8f33a2aac4 257/313: Better document calling bash-completion from completion-at-point.

[ELPA Syncer]

branch: elpa/bash-completion
commit 8f33a2aac4af5a850d7a96e1ba4a762abc3b2d54
Author: Stephane Zermatten <szermatt@gmx.net>
Commit: Stephane Zermatten <szermatt@gmx.net>

    Better document calling bash-completion from completion-at-point.
    
    Also make the argument COMP-START in
    bash-completion-dynamic-complete-nocomint required.
---
 README.md                                | 110 +++++++++++++++----------------
 bash-completion.el                       |  32 +++++++--
 test/bash-completion-integration-test.el |   4 +-
 3 files changed, 83 insertions(+), 63 deletions(-)

diff --git a/README.md b/README.md
index 29126c54f2..e072bb387b 100644
--- a/README.md
+++ b/README.md
@@ -1,21 +1,17 @@
 # bash-completion 
[![test](https://github.com/szermatt/emacs-bash-completion/workflows/test/badge.svg)](https://github.com/szermatt/emacs-bash-completion/actions)
 
[![melpa](https://melpa.org/packages/bash-completion-badge.svg)](https://melpa.org/#/bash-completion)
 
[![melpa-stable](https://stable.melpa.org/packages/bash-completion-badge.svg)](https://stable.melpa.org/#/bash-completion)
 
 
-bash-completion.el defines dynamic completion hooks for shell-mode and
-shell-command prompts that are based on bash completion.
+bash-completion.el defines dynamic completion hooks for shell-mode,
+shell-command prompts and that are based on bash completion.
 
-Bash completion for emacs:
+Bash completion for Emacs:
 
 - is aware of bash builtins, aliases and functions
 - does file expansion inside of colon-separated variables
   and after redirections (> or <)
 - escapes special characters when expanding file names
 - is configurable through programmable bash completion
-
-When the first completion is requested in shell model or a shell
-command, bash-completion.el starts a separate bash
-process.  Bash-completion.el then uses this process to do the actual
-completion and includes it into Emacs completion suggestions.
+- works on remote shells, through TRAMP.
 
 A simpler and more complete alternative to bash-completion.el is to
 run a bash shell in a buffer in term mode(M-x `ansi-term').
@@ -23,14 +19,20 @@ Unfortunately, many Emacs editing features are not 
available when
 running in term mode.  Also, term mode is not available in
 shell-command prompts.
 
-Bash completion can also be run programatically, outside of a
-shell-mode command by calling
-`bash-completion-dynamic-complete-nocomint`.
-
 ## INSTALLATION
 
-1. copy bash-completion.el into a directory that's on Emacs load-path
-2. add this into your .emacs file:
+Copy bash-completion.el into a directory that's on Emacs load-path.
+You can do that manually, or by installing it from
+[MELPA](https://melpa.org/#/getting-started).
+
+### Shell completion
+
+To enable bash completion in shell buffers as well as in command
+prompts, such as the prompt started by `compile`, add the hook
+`bash-completion-dynamic-complete` to
+`shell-dynamic-complete-fuctions`.
+
+For example:
 
 ```elisp
         (setq bash-completion-use-separate-processes nil)
@@ -41,7 +43,7 @@ shell-mode command by calling
           'bash-completion-dynamic-complete)
 ```
 
-  or simpler, but forces you to load this file at startup:
+or simpler, but forces you to load bash-completion at startup:
 
 ```elisp
         (setq bash-completion-use-separate-processes nil)
@@ -54,25 +56,40 @@ shell-mode command by calling
   versions of `bash-completion.el`. See the section
   
[bash-completion-use-separate-processes](#bash-completion-use-separate-processes)
   for more details.
+  
+After that reload your .emacs (M-x `eval-buffer') or restart.
 
-3. reload your .emacs (M-x `eval-buffer') or restart
+### Completion at point
 
-Once this is done, use <TAB> as usual to do dynamic completion from
-shell mode or a shell command minibuffer, such as the one started
-for M-x `compile'. Note that the first completion is slow, as emacs
-launches a new bash process.
+Additionally, you can enable bash completion in any buffer that contains bash 
+commands. To do that, call `bash-completion-dynamic-complete-nocomint' from a 
+function added to `completion-at-point-functions`. 
 
-You'll get better results if you turn on programmable bash completion.
-On Ubuntu, this means running:
+The tricky part is figuring out where the bash command starts, because that 
+depends on  the mode of the calling buffer and might, in some cases, span 
+multiple lines.
 
-```sh
-    sudo apt-get install bash-completion
-```
+In any cases, when calling from `completion-at-point', make sure to pass a
+non-nil value to DYNAMIC-TABLE argument. 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.
 
-and then adding this to your .bashrc:
+Here's, for example, 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.
 
-```sh
-    . /etc/bash_completion
+```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))
 ```
 
 ## bash-completion-use-separate-processes
@@ -81,16 +98,12 @@ TL;DR Set `bash-completion-use-separate-processes` to `nil` 
and avoid
 the issues and complications described in this section.
 
 When `bash-completion-use-separate-processes` is `t`, completion
-always runs in a separate process from the shell process, even when 
-called from a shell process running bash.
-
-This might be useful in some cases, as it allows interrupting slow
-completions, when necessary.
+always runs in a separate process from the shell process. When it is 
+nil and when using shell-mode, bash-completion can use the same 
+bash process as shell mode, when it is available.
 
-However using a separate process for doing the completion has several
-important disadvantages:
+Running a separate process just for completion has several downsides:
 
-- bash completion is slower than standard emacs completion
 - it relies on directory tracking working correctly on Emacs
 - the first completion can take a long time, since a new bash process
   needs to be started and initialized
@@ -102,32 +115,17 @@ important disadvantages:
         $ myal<TAB>
 
   and bash would propose the new alias.
-  Bash-completion.el cannot do that, as it is not aware of anything
-  configured in the current shell. To make bash-completion.el aware
-  of a new alias, you need to add it to .bashrc and restart the
-  completion process using `bash-completion-reset'.
+  
+  Bash-completion.el can only do that if completion and shell are
+  running in the same process. 
 
 When using separate processes, right after enabling programmable bash
 completion, and whenever you make changes to you .bashrc, call
-`bash-completion-reset' to make sure bash completion takes your new
+`bash-completion-reset` to make sure bash completion takes your new
 settings into account.
 
-Loading /etc/bash_completion often takes time, and is not necessary
-in shell mode, since completion is done by a separate process, not
-the process shell-mode process.
-
-To turn off bash completion when running from emacs but keep it on
-for processes started by bash-completion.el, add this to your .bashrc:
-
-```bash
-    if [[ ( -z "$INSIDE_EMACS" || "$EMACS_BASH_COMPLETE" = "t" ) &&\
-         -f /etc/bash_completion ]]; then
-      . /etc/bash_completion
-    fi
-```
-
 Emacs sets the environment variable INSIDE_EMACS to the processes
-started from it. Processes started by bash-completion.el have
+started from it. Local processes started by bash-completion.el have
 the environment variable EMACS_BASH_COMPLETE set to t.
 
 ## COMPATIBILITY
diff --git a/bash-completion.el b/bash-completion.el
index 8bd28a4584..38fb66abb7 100644
--- a/bash-completion.el
+++ b/bash-completion.el
@@ -529,15 +529,35 @@ When doing completion outside of a comint buffer, call
 
 ;;;###autoload
 (defun bash-completion-dynamic-complete-nocomint
-    (&optional comp-start comp-pos dynamic-table)
+    (comp-start &optional comp-pos dynamic-table)
   "Return completion information for bash command at an arbitrary position.
 
 The bash command to be completed begins at COMP-START in the
-current buffer. COMP-POS is the point where completion should
-happen.
-
-This function is meant to be usable even in non comint buffers.
-It is meant to be called directly from any completion engine.
+current buffer. This must specify where the current command
+starts, usually right after the prompt. 
+
+COMP-POS is the point where completion should happen, usually
+just (point). Note that a bash command can span across multiple
+line, so COMP-START is not necessarily on the same line as
+COMP-POS.
+
+This function does not assume that the current buffer is a shell
+or even comint buffer. It can safely be called from any buffer
+where a bash command appears, including `completion-at-point'.
+
+If DYNAMIC-TABLE is passed a non-nil value, the resulting
+collection will be a function that fetches the result lazily,
+when it's called.
+
+When calling from `completion-at-point', make sure to pass a
+non-nil value to DYNAMIC-TABLE. 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.
+
+When calling from another completion engine, make sure to treat
+the returned completion as reliable and not post-process them
+further.
 
 Returns (list stub-start stub-end completions) with
  - stub-start, the position at which the completed region starts
diff --git a/test/bash-completion-integration-test.el 
b/test/bash-completion-integration-test.el
index 97e0238590..0c82c82d51 100644
--- a/test/bash-completion-integration-test.el
+++ b/test/bash-completion-integration-test.el
@@ -204,7 +204,9 @@ for testing completion."
    "function somefunction { echo ok; }\n"
    nil ; use-separate-process=nil will be ignored
    (with-temp-buffer
-     (let ((completion-at-point-functions 
'(bash-completion-dynamic-complete-nocomint)))
+     (let ((completion-at-point-functions
+            (list (lambda () (bash-completion-dynamic-complete-nocomint
+                              (line-beginning-position) (point) t)))))
        ;; complete bash builtin
        (should (equal "readonly "
                       (bash-completion_test-complete "reado")))