[elpa] externals/auto-correct 84101c5 05/11: auto-correct: Changed default predicate to a function and added examples

[Stefan Monnier]

branch: externals/auto-correct
commit 84101c5207ba505be148376171961548b54f665f
Author: Ian Dunn <dunni@gnu.org>
Commit: Ian Dunn <dunni@gnu.org>

    auto-correct: Changed default predicate to a function and added examples
    
    * packages/auto-correct/auto-correct.el (Commentary): Added predicate 
examples
      (auto-correct--default-predicate): New defun
      (auto-correct-predicate): Make it the default
      (auto-correct-expand-p): Don't check for predicate being nil
---
 auto-correct.el | 46 ++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 40 insertions(+), 6 deletions(-)

diff --git a/auto-correct.el b/auto-correct.el
index 73b41a4..a792724 100644
--- a/auto-correct.el
+++ b/auto-correct.el
@@ -36,10 +36,33 @@
 ;; from then on.
 
 ;; Corrections are only made when `auto-correct-mode' is enabled.  Expansion is
-;; case-insensitive, so trying to fix alice as Alice won't work.
+;; case-insensitive, so trying to fix alice as Alice won't work.  Use the
+;; captain package for this instead.
 
-;; For more fine-grained control over when corrections are made, set the
-;; buffer-local variable `auto-correct-predicate'.
+;; Auto-correct is controlled further by `auto-correct-predicate'.  In order to
+;; enable auto-correct in a given buffer, the function to which
+;; `auto-correct-predicate' is set must return true at the current point.
+
+;; For example, the following will tell auto-correct to only correct mistakes 
in
+;; a programming mode buffer that fall within a comment:
+
+;; (add-hook 'prog-mode-hook
+;;    (lambda ()
+;;      (setq auto-correct-predicate (lambda () (nth 8 (syntax-ppss 
(point)))))))
+
+;; Or for text modes, work all the time:
+
+;; (add-hook 'text-mode-hook
+;;           (lambda ()
+;;             (setq auto-correct-predicate (lambda () t))))
+
+;; Or don't work in source blocks in Org mode:
+
+;; (add-hook
+;;  'org-mode-hook
+;;  (lambda ()
+;;    (setq auto-correct-predicate
+;;          (lambda () (not (org-in-src-block-p))))))
 
 ;; Behind the scenes, auto-correct uses an abbrev table, so in order to clean
 ;; out or modify any fixes auto-correct has learned, use `list-abbrevs'.  This
@@ -75,19 +98,30 @@
 
 ;; Core Functionality
 
-(defvar-local auto-correct-predicate nil
+(defun auto-correct--default-predicate ()
+  "The default predicate for determining whether auto-correct should run.
+
+Disabled by default."
+  nil)
+
+(defvar-local auto-correct-predicate #'auto-correct--default-predicate
   "Predicate to check whether automatic corrections should be made.
 
 This should be a function of no arguments that returns non-nil if
 auto-correct should operate on the current text.
 
-This is nil by default so auto-correct must be explicitly enabled.")
+This is buffer-local so it can be set to a value that works best
+with each different mode.
+
+This is `auto-correct--default-predicate' by default, which keeps
+auto-correct disabled.  This is to prevent auto-correct from
+happening all the time.")
 
 (defun auto-correct-expand-p ()
   "Return non-nil if auto-correct should operate on the current point.
 
 To customize this behavior, set `auto-correct-predicate'."
-  (when auto-correct-predicate (funcall auto-correct-predicate)))
+  (funcall auto-correct-predicate))
 
 (define-abbrev-table 'auto-correct-abbrev-table nil
   "Abbrev table where automatic corrections are stored."