[elpa] externals/company 828f07e6f8 1/3: Rename 'auto-commit' user options

[ELPA Syncer]

branch: externals/company
commit 828f07e6f8a0acd8d5c7a3ea852f4352f9bca126
Author: YugaEgo <yet@ego.team>
Commit: YugaEgo <yet@ego.team>

    Rename 'auto-commit' user options
    
    Based on #1264.
---
 NEWS.md            |  3 +++
 company.el         | 70 ++++++++++++++++++++++++++++++++++--------------------
 doc/company.texi   | 38 ++++++++++++-----------------
 test/core-tests.el | 20 ++++++++--------
 4 files changed, 72 insertions(+), 59 deletions(-)

diff --git a/NEWS.md b/NEWS.md
index 84abd06a15..d98dbd95c2 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -2,6 +2,9 @@
 
 ## Next
 
+* `company-auto-commit` and `company-auto-commit-chars` have been renamed to
+  `company-insertion-on-trigger` and `company-insertion-triggers` respectively
+  ([#1270](https://github.com/company-mode/company-mode/pull/1270)).
 * New command `company-complete-common-or-show-delayed-tooltip`
   ([#1214](https://github.com/company-mode/company-mode/discussions/1214)).
 * Faces `company-scrollbar-fg` and `company-scrollbar-bg` have been renamed to
diff --git a/company.el b/company.el
index a7ee3fa9da..5f89dae2a5 100644
--- a/company.el
+++ b/company.el
@@ -566,7 +566,8 @@ doesn't match anything or finish it manually, e.g. with 
RET."
 This can be a function do determine if a match is required.
 
 This can be overridden by the backend, if it returns t or `never' to
-`require-match'.  `company-auto-commit' also takes precedence over this."
+`require-match'.  `company-insertion-on-trigger' also takes precedence over
+this."
   :type '(choice (const :tag "Off" nil)
                  (function :tag "Predicate function")
                  (const :tag "On, if user interaction took place"
@@ -578,11 +579,18 @@ This can be overridden by the backend, if it returns t or 
`never' to
   'company-auto-commit
   "0.9.14")
 
-(defcustom company-auto-commit nil
-  "Determines whether to auto-commit.
-If this is enabled, all characters from `company-auto-commit-chars'
-trigger insertion of the selected completion candidate.
-This can also be a function."
+(define-obsolete-variable-alias
+  'company-auto-commit
+  'company-insertion-on-trigger
+  "0.9.14")
+
+(defcustom company-insertion-on-trigger nil
+  "If enabled, allow triggering insertion of the selected candidate.
+This can also be a predicate function, for example,
+`company-explicit-action-p'.
+
+See `company-insertion-triggers' for more details on how to define
+triggers."
   :type '(choice (const :tag "Off" nil)
                  (function :tag "Predicate function")
                  (const :tag "On, if user interaction took place"
@@ -595,16 +603,24 @@ This can also be a function."
   'company-auto-commit-chars
   "0.9.14")
 
-(defcustom company-auto-commit-chars '(?\  ?\) ?.)
-  "Determines which characters trigger auto-commit.
-See `company-auto-commit'.  If this is a string, each character in it
-triggers auto-commit.  If it is a list of syntax description characters (see
-`modify-syntax-entry'), characters with any of those syntaxes do that.
+(define-obsolete-variable-alias
+  'company-auto-commit-chars
+  'company-insertion-triggers
+  "0.9.14")
+
+(defcustom company-insertion-triggers '(?\  ?\) ?.)
+  "Determine triggers for `company-insertion-on-trigger'.
+
+If this is a string, then each character in it can trigger insertion of the
+selected candidate.  If it is a list of syntax description characters (see
+`modify-syntax-entry'), then characters with any of those syntaxes can act
+as triggers.
 
-This can also be a function, which is called with the new input and should
-return non-nil if company should auto-commit.
+This can also be a function, which is called with the new input.  To
+trigger insertion, the function should return a non-nil value.
 
-A character that is part of a valid completion never triggers auto-commit."
+Note that a character that is part of a valid completion never triggers
+insertion."
   :type '(choice (string :tag "Characters")
                  (set :tag "Syntax"
                       (const :tag "Whitespace" ?\ )
@@ -1954,18 +1970,20 @@ prefix match (same case) will be prioritized."
                  (funcall company-require-match)
                (eq company-require-match t))))))
 
-(defun company-auto-commit-p (input)
-  "Return non-nil if INPUT should trigger auto-commit."
-  (and (if (functionp company-auto-commit)
-           (funcall company-auto-commit)
-         company-auto-commit)
-       (if (functionp company-auto-commit-chars)
-           (funcall company-auto-commit-chars input)
-         (if (consp company-auto-commit-chars)
+(defun company-insertion-on-trigger-p (input)
+  "Return non-nil if INPUT should trigger insertion.
+For more details see `company-insertion-on-trigger' and
+`company-insertion-triggers'."
+  (and (if (functionp company-insertion-on-trigger)
+           (funcall company-insertion-on-trigger)
+         company-insertion-on-trigger)
+       (if (functionp company-insertion-triggers)
+           (funcall company-insertion-triggers input)
+         (if (consp company-insertion-triggers)
              (memq (char-syntax (string-to-char input))
-                   company-auto-commit-chars)
+                   company-insertion-triggers)
            (string-match (regexp-quote (substring input 0 1))
-                          company-auto-commit-chars)))))
+                         company-insertion-triggers)))))
 
 (defun company--incremental-p ()
   (and (> (point) company-point)
@@ -2030,8 +2048,8 @@ prefix match (same case) will be prioritized."
       (company-update-candidates c)
       c)
      ((and (characterp last-command-event)
-           (company-auto-commit-p (string last-command-event)))
-      ;; auto-commit
+           (company-insertion-on-trigger-p (string last-command-event)))
+      ;; Insertion on trigger.
       (save-excursion
         (goto-char company-point)
         (company-complete-selection)
diff --git a/doc/company.texi b/doc/company.texi
index 4e7d6366ba..a22d542367 100644
--- a/doc/company.texi
+++ b/doc/company.texi
@@ -3,7 +3,7 @@
 @setfilename company.info
 @settitle Company User Manual
 @set VERSION 0.9.14snapshot
-@set UPDATED 28 December 2021
+@set UPDATED 8 January 2022
 @documentencoding UTF-8
 @documentlanguage en
 @paragraphindent asis
@@ -494,20 +494,11 @@ enabled @emph{company-mode} in the mode line.  The 
default value is
 @samp{company}.
 @end defopt
 
-@anchor{company-auto-commit}
-@defopt company-auto-commit
+@defopt company-insertion-on-trigger
 One more pair of the user options may instruct Company to complete
 with the selected candidate by typing one of the
-@code{company-auto-commit-chars} @footnote{The options
-@code{company-auto-commit} and @code{company-auto-commit-chars} used
-to be called @code{company-auto-complete} and
-@code{company-auto-complete-chars} respectively, which was in more
-accordance with the terminology given in this manual.  But the
-resulting combination of the words @samp{auto-complete} present in
-those names made it seem the role of these user options was to
-configure Company's auto-start behavior.  Hence, it was chosen to
-rename the options to, hopefully, less confusing names.}.  The user
-option @code{company-auto-commit} can be enabled or disabled by
+@code{company-insertion-triggers}.  The user option
+@code{company-insertion-on-trigger} can be enabled or disabled by
 setting its value to one of: @code{nil}, @code{t}, or a predicate
 function name.
 @ifnothtml
@@ -519,16 +510,17 @@ See 
@uref{https://www.gnu.org/software/emacs/manual/html_node/eintr/Wrong-Type-o
 @end ifhtml
 @end defopt
 
-@anchor{company-auto-commit-chars}
-@defopt company-auto-commit-chars
-This option acts only when @code{company-auto-commit} is enabled.  The
-value can be one of: a string of characters, a list of syntax
-description characters (@pxref{Syntax Class Table,,,elisp}), or a
-predicate function.  By default, @code{company-auto-commit-chars} is
-set to the list of the syntax characters: @w{@code{(?\ ?\) ?.)}},
-which translates to the whitespaces, close parenthesis, and
-punctuation.  The particular convenience of this user option values is
-they do not act as triggers when they are part of valid completion.
+@defopt company-insertion-triggers
+This option has an effect only when
+@w{@code{company-insertion-on-trigger}} is enabled.  The value can be
+one of: a string of characters, a list of syntax description
+characters (@pxref{Syntax Class Table,,,elisp}), or a predicate
+function.  By default, this user option is set to the list of the
+syntax characters: @w{@code{(?\ ?\) ?.)}}, which translates to the
+whitespaces, close parenthesis, and punctuation.  It is safe to
+configure the value to a character that can potentially be part of a
+valid completion; in this case, Company does not treat such characters
+as triggers.
 @end defopt
 
 @subheading Hooks
diff --git a/test/core-tests.el b/test/core-tests.el
index 4c48cbd265..e0af4c1c43 100644
--- a/test/core-tests.el
+++ b/test/core-tests.el
@@ -273,7 +273,7 @@
     (insert "ab")
     (company-mode)
     (let (company-frontends
-          company-auto-commit
+          company-insertion-on-trigger
           (company-require-match t)
           (company-backends
            (list (lambda (command &optional _)
@@ -373,13 +373,13 @@
       (should (string= "a" (buffer-string)))
       (should (null company-candidates)))))
 
-(ert-deftest company-auto-commit-explicit ()
+(ert-deftest company-insertion-on-trigger-explicit ()
   (with-temp-buffer
     (insert "ab")
     (company-mode)
     (let (company-frontends
-          (company-auto-commit 'company-explicit-action-p)
-          (company-auto-commit-chars '(? ))
+          (company-insertion-on-trigger 'company-explicit-action-p)
+          (company-insertion-triggers '(? ))
           (company-backends
            (list (lambda (command &optional _)
                    (cl-case command
@@ -391,14 +391,14 @@
         (company-call 'self-insert-command 1))
       (should (string= "abcd " (buffer-string))))))
 
-(ert-deftest company-auto-commit-with-electric-pair ()
+(ert-deftest company-insertion-on-trigger-with-electric-pair ()
   (with-temp-buffer
     (insert "foo(ab)")
     (forward-char -1)
     (company-mode)
     (let (company-frontends
-          (company-auto-commit t)
-          (company-auto-commit-chars '(? ?\)))
+          (company-insertion-on-trigger t)
+          (company-insertion-triggers '(? ?\)))
           (company-backends
            (list (lambda (command &optional _)
                    (cl-case command
@@ -416,13 +416,13 @@
           (electric-pair-mode -1)))
       (should (string= "foo(abcd)" (buffer-string))))))
 
-(ert-deftest company-no-auto-commit-when-idle ()
+(ert-deftest company-no-insertion-on-trigger-when-idle ()
   (with-temp-buffer
     (insert "ab")
     (company-mode)
     (let (company-frontends
-          (company-auto-commit 'company-explicit-action-p)
-          (company-auto-commit-chars '(? ))
+          (company-insertion-on-trigger 'company-explicit-action-p)
+          (company-insertion-triggers '(? ))
           (company-minimum-prefix-length 2)
           (company-backends
            (list (lambda (command &optional _)