Merge pull request #717 from MarkRedeman/circe-keybindings

Add keybindings for circe

modules/app/irc/README.org

@@ -3,10 +3,12 @@
 This module turns adds an IRC client to Emacs ([[https://github.com/jorgenschaefer/circe][~circe~)]] with native notifications ([[https://github.com/eqyiel/circe-notifications][circe-notifications]]).
 
 * Table of Contents :TOC:
-- [[#dependencies][Dependencies]]
-- [[#configure][Configure]]
-  - [[#pass-the-unix-password-manager][Pass: the unix password manager]]
-  - [[#emacs-auth-source-api][Emacs' auth-source API]]
+- [[Dependencies][Dependencies]]
+- [[Configure][Configure]]
+  - [[Pass: the unix password manager][Pass: the unix password manager]]
+  - [[Emacs' auth-source API][Emacs' auth-source API]]
+- [[Appendix][Appendix]]
+  - [[Commands][Commands]]
 
 * Dependencies
 This module has no dependencies, besides =gnutls-cli= or =openssl= for secure connections.
@@ -52,6 +54,15 @@ But wait, there's more! This stores your password in a public variable which cou
 
 And you're good to go!
 
+Note that =+pass-get-user= tries to find your username by looking for the fields
+listed in =+pass-user-fields= (by default =login=, =user==, =username== and =email=)=).
+An example configuration looks like
+
+#+BEGIN_SRC txt :tangle no
+mysecretpassword
+username: myusername
+#+END_SRC
+
 ** Emacs' auth-source API
 ~auth-source~ is built into Emacs. As suggested [[https://github.com/jorgenschaefer/circe/wiki/Configuration#safer-password-management][in the circe wiki]], you can store (and retrieve) encrypted passwords with it.
 
@@ -78,3 +89,24 @@ And you're good to go!
       :channels ("#emacs")))
 #+END_SRC
 
+* Appendix
+** Commands
+
+To connect to IRC you can invoke the ~=irc~ function using =M-x= or your own
+custom keybinding.
+
+| command | description                               |
+|---------+-------------------------------------------|
+| ~=irc~  | Connect to IRC and all configured servers |
+
+When in a circe buffer these keybindings will be available.
+
+| command                | key       | description                                  |
+|------------------------+-----------+----------------------------------------------|
+| ~tracking-next-buffer~ | =SPC m a= | Switch to the next active buffer             |
+| ~circe-command-JOIN~   | =SPC m j= | Join a channel                               |
+| ~+irc/send-message~    | =SPC m m= | Send a private message                       |
+| ~circe-command-NAMES~  | =SPC m n= | List the names of the current channel        |
+| ~circe-command-PART~   | =SPC m p= | Part the current channel                     |
+| ~+irc/quit~            | =SPC m Q= | Kill the current circe session and workgroup |
+| ~circe-reconnect~      | =SPC m R= | Reconnect the current server                 |

modules/app/irc/autoload/irc.el

@@ -36,6 +36,12 @@ workspace for it."
   (and (+irc-setup-wconf inhibit-workspace)
        (call-interactively #'circe)))
 
+;;;###autoload
+(defun +irc/send-message (who what)
+  "Send WHO a message containing WHAT."
+  (interactive "sWho: \nsWhat: ")
+  (circe-command-MSG who what))
+
 ;;;###autoload
 (defun +irc/quit ()
   "Kill current circe session and workgroup."

modules/app/irc/config.el

@@ -125,7 +125,23 @@ playback.")
 
   (after! solaire-mode
     ;; distinguish chat/channel buffers from server buffers.
-    (add-hook 'circe-chat-mode-hook #'solaire-mode)))
+    (add-hook 'circe-chat-mode-hook #'solaire-mode))
+
+  (map!
+   (:localleader
+     (:map circe-mode-map
+       :desc "Next active buffer"     :n "a" #'tracking-next-buffer
+       :desc "Join channel"           :n "j" #'circe-command-JOIN
+       :desc "Send private message"   :n "m" #'+irc/send-message
+       :desc "Part current channel"   :n "p" #'circe-command-PART
+       :desc "Quit irc"               :n "Q" #'+irc/quit
+       :desc "Reconnect"              :n "R" #'circe-reconnect
+
+       (:when (featurep! :completion ivy)
+         :desc "Jump to channel"      :n "c" #'+irc/ivy-jump-to-channel))
+
+     (:map circe-channel-mode-map
+       :desc "Show names"           :n "n" #'circe-command-NAMES))))
 
 
 (def-package! circe-color-nicks