[elpa] externals/altcaps 122bd6fade: Add altcaps-force-character-casing user option

[ELPA Syncer]

branch: externals/altcaps
commit 122bd6fadef542f4400b90a5c697e11fda9c713c
Author: Protesilaos Stavrou <info@protesilaos.com>
Commit: Protesilaos Stavrou <info@protesilaos.com>

    Add altcaps-force-character-casing user option
    
    Thanks to Cédric Barreteau for the idea of forcing a given letter case
    on specified characters.  I think that giving users the option keeps
    our code simple, while providing a useful point of customisation.
    
    Cédric is the author of the nvim-altcaps: 
<https://github.com/cbarrete/nvim-altcaps>.
---
 README.org | 51 ++++++++++++++++++++++++++++++++++++++++++++++++++
 altcaps.el | 63 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++----
 2 files changed, 110 insertions(+), 4 deletions(-)

diff --git a/README.org b/README.org
index fa06e40492..ae3cb30eb5 100644
--- a/README.org
+++ b/README.org
@@ -102,6 +102,34 @@ Use any of the following commands to achieve the desired 
results:
   Else invoke ~altcaps-word~ with optional =NUM=, per that command's
   functionality (read its documentation).
 
+[ The following is part of {{{development-version}}}. ]
+
+#+vindex: altcaps-force-character-casing
+The user option ~altcaps-force-character-casing~ forces the given
+letter casing for specified characters.  Its value is an alist of
+=(CHARACTER . CASE)= pairs.  =CHARACTER= is a single character
+(satisfies the ~characterp~ condition), while =CASE= is the ~upcase~
+or ~downcase~ symbol (code sample further below).
+
+The idea is to always render certain characters in lower or upper
+case, in consideration of their legibility in context.  For example,
+the default altcaps algorithm produces this:
+
+: iLlIcIt IlLiBeRaL sIlLiNeSs
+
+Whereas if the value of this variable declares =i= to always be lower
+case and =L= uppercase, then we get this:
+
+: iLLiCiT iLLiBeRaL siLLiNeSs
+
+The code to do this:
+
+#+begin_src emacs-lisp
+(setq altcaps-force-character-casing
+      '((?i . downcase)
+        (?l . upcase)))
+#+end_src
+
 * Installation
 :PROPERTIES:
 :CUSTOM_ID: h:d40db8b2-b481-4d6c-bb1e-8e79cf5dff62
@@ -164,6 +192,11 @@ Everything is in place to set up the package.
 #+begin_src emacs-lisp
 (require 'altcaps)
 
+;; Force letter casing for certain characters (for legibility).
+(setq altcaps-force-character-casing
+      '((?i . downcase)
+        (?l . upcase)))
+
 ;; We do not bind any keys, but you are free to do so:
 (define-key global-map (kbd "C-x C-a") #'altcaps-dwim)
 
@@ -174,6 +207,24 @@ Everything is in place to set up the package.
 ;; - `altcaps-dwim'
 #+end_src
 
+* Acknowledgements
+:PROPERTIES:
+:CUSTOM_ID: h:399afb8b-7bb3-40b4-b10f-3123714d9614
+:END:
+#+cindex: Contributors
+
+aLtCaPs is meant to be a collective effort.  Every bit of help
+matters.
+
++ Author/maintainer :: Protesilaos Stavrou.
+
++ Ideas and/or user feedback :: Cédric Barreteau.
+
+Cédric is the author of an =altcaps=-inspired package for NeoVim, from
+whence I got the idea of forcing a given letter case for certain
+characters (I do it with the ~altcaps-force-character-casing~ user
+option): <https://github.com/cbarrete/nvim-altcaps>.
+
 * GNU Free Documentation License
 :PROPERTIES:
 :APPENDIX: t
diff --git a/altcaps.el b/altcaps.el
index cceccd7dc8..dfb80f23ad 100644
--- a/altcaps.el
+++ b/altcaps.el
@@ -56,6 +56,29 @@
 ;;   `altcaps-region'.  Else invoke `altcaps-word' with optional NUM,
 ;;   per that command's functionality (read its documentation).
 ;;
+;; The user option `altcaps-force-character-casing' forces the given
+;; letter casing for specified characters.  Its value is an alist of
+;; (CHARACTER . CASE) pairs.  CHARACTER is a single character
+;; (satisfies the `characterp' condition), while CASE is the `upcase'
+;; or `downcase' symbol (code sample further below).
+;;
+;; The idea is to always render certain characters in lower or upper
+;; case, in consideration of their legibility in context.  For
+;; example, the default altcaps algorithm produces this:
+;;
+;;     iLlIcIt IlLiBeRaL sIlLiNeSs
+;;
+;; Whereas if the value of this variable declares `i' to always be
+;; lower case and `L' uppercase, then we get this:
+;;
+;;     iLLiCiT iLLiBeRaL siLLiNeSs
+;;
+;; The code to do this:
+;;
+;;     (setq altcaps-force-character-casing
+;;           '((?i . downcase)
+;;             (?l . upcase)))
+;;
 ;; Backronyms of ALTCAPS: Alternating Letters Transform Casual Asides
 ;; to Playful Statements.  ALTCAPS Lets Trolls Convert Aphorisms to
 ;; Proper Shitposts.
@@ -77,6 +100,33 @@ The `altcaps' package thus makes you more effective at 
textual
 communication.  Plus, you appear more sophisticated.  tRuSt Me."
   :group 'editing)
 
+(defcustom altcaps-force-character-casing nil
+  "Force the given letter casing for specified characters.
+This is an alist of (CHARACTER . CASE).  CHARACTER must satisfy
+`characterp', while CASE is the symbol `upcase' or `downcase'.
+
+The idea is to always render certain characters in lower or upper
+case, in consideration of their legibility in context.  For
+example, the default altcaps algorithm produces this:
+
+    iLlIcIt IlLiBeRaL sIlLiNeSs
+
+Whereas if the value of this variable declares `i' to always be
+lower case and `L' uppercase, then we get this (check the manual
+for a code sample):
+
+    iLLiCiT iLLiBeRaL siLLiNeSs
+
+You do want to communicate mockery or sarcasm, though legibility
+still matters!  (Though I encourage everyone to use a decent font
+that disambiguates characters.)"
+  :type '(alist
+          :key-type (character :tag "Single character")
+          :value-type (radio :tag "Letter casing"
+                             (const :tag "Lower case" downcase)
+                             (const :tag "Upper case" upcase)))
+  :group 'altcaps)
+
 (defun altcaps--transform (string)
   "Make STRING use alternating letter casing."
   (let ((s (vconcat (downcase string)))
@@ -84,11 +134,16 @@ communication.  Plus, you appear more sophisticated.  
tRuSt Me."
         chars)
     (mapc (lambda (c)
             (unless (string-blank-p (char-to-string c))
-              (if (eq casing 'down)
-                  (setq c (upcase c)
-                        casing 'up)
+              (cond
+               ((when-let ((force-case (alist-get c 
altcaps-force-character-casing)))
+                  (setq c (funcall force-case c)
+                        casing force-case)))
+               ((eq casing 'downcase)
+                (setq c (upcase c)
+                      casing 'upcase))
+               (t
                 (setq c (downcase c)
-                      casing 'down)))
+                      casing 'downcase))))
             (push c chars))
           s)
     (concat (reverse chars))))