doomemacs/modules/app/irc/README.org

#+title:    :app irc
#+subtitle: How neckbeards socialize
#+created:  June 11, 2017
#+since:    2.0.3

* Description :unfold:
This module turns Emacs into an IRC client, capable of OS notifications.

** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]

** Module flags
/This module has no flags./

** Packages
- [[doom-package:circe]]
- [[doom-package:circe-notifications]]

** Hacks
/No hacks documented for this module./

** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./

* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]

This module requires:
- [[https://www.gnutls.org/][GnuTLS]], for secure IRC connections to work.

This should be available through your OS package manager.

** macOS
#+begin_src sh
brew install gnutls
#+end_src

** Debian / Ubuntu
#+begin_src sh
apt install gnutls-bin
#+end_src

** Arch Linux
#+begin_src sh
pacman -S gnutls
#+end_src
** NixOS
#+begin_src nix
environment.systemPackages = [ pkgs.gnutls ];
#+end_src

* TODO Usage
#+begin_quote
 󱌣 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote

To connect to IRC use ~M-x =irc~.

When in a circe buffer these keybindings will be available:
| command                     | key             | description                                  |
|-----------------------------+-----------------+----------------------------------------------|
| ~+irc/tracking-next-buffer~ | [[kbd:][<localleader> a]] | Switch to the next active buffer             |
| ~circe-command-JOIN~        | [[kbd:][<localleader> j]] | Join a channel                               |
| ~+irc/send-message~         | [[kbd:][<localleader> m]] | Send a private message                       |
| ~circe-command-NAMES~       | [[kbd:][<localleader> n]] | List the names of the current channel        |
| ~circe-command-PART~        | [[kbd:][<localleader> p]] | Part the current channel                     |
| ~+irc/quit~                 | [[kbd:][<localleader> Q]] | Kill the current circe session and workgroup |
| ~circe-reconnect~           | [[kbd:][<localleader> R]] | Reconnect the current server                 |

* TODO Configuration
#+begin_quote
 󱌣 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote

Use ~set-irc-server! SERVER PLIST~ to configure IRC servers. Its second argument
(a plist) takes the same arguments as ~circe-network-options~:
#+begin_src emacs-lisp
;; if you omit =:host=, ~SERVER~ will be used instead.
(after! circe
  (set-irc-server! "irc.libera.chat"
    `(:tls t
      :port 6697
      :nick "doom"
      :sasl-username "myusername"
      :sasl-password "mypassword"
      :channels ("#emacs"))))
#+end_src

However, *it is a obviously a bad idea to store your password in plaintext,* so
[[https://github.com/emacs-circe/circe/wiki/Configuration#safer-password-management][it's recommend]] that you use ~auth-source~ (built into Emacs) to safely pull
passwords from a password manager or OS keychain (remember to enable the :os
macos or :tools pass modules if you want integration into the MacOS keychain or
[[https://www.passwordstore.org/][Pass]]):
#+begin_src emacs-lisp
;;; in $DOOMDIR/config.el
(after! circe
  (defun fetch-password (&rest params)
    (require 'auth-source)
    (if-let* ((match (car (apply #'auth-source-search params)))
              (secret (plist-get match :secret)))
        (if (functionp secret)
            (funcall secret)
          secret)
      (user-error "Password not found for %S" params)))

  (set-irc-server! "irc.libera.chat"
    '(:tls t
      :port 6697
      :nick "doom"
      :sasl-password
      (lambda (server)
        (fetch-password :user "forcer" :host "irc.libera.chat"))
      :channels ("#emacs"))))
#+end_src

If Doom's [[doom-module::tools pass]] module is enabled, ~auth-source~ can integrate
with [[https://www.passwordstore.org/][Pass]].

#+begin_quote
  A common mistake is to interpolate the return value of your secrets retrieval
    function into the plist you pass to ~set-irc-server!~. This means that not
    only will your secrets will be stored, in plaintext, somewhere in Emacs
    state, but your password manager (or GnuPG) will likely prompt you for your
    GPG key passphrase when the ~set-irc-server!~ call is made! For example,
    don't do this!

      (set-irc-server! "irc.libera.chat"
        `(:tls t
          :port 6697
          :nick "doom"
          :sasl-username ,(fetch-password "irc/libera.chat")
          :sasl-password ,(fetch-password "irc/libera.chat")
          :channels ("#emacs")))

    Do this, instead:

      (set-irc-server! "irc.libera.chat"
        '(:tls t
          :port 6697
          :nick "doom"
          :sasl-username (+pass-get-user   "irc/libera.chat")
          :sasl-password (+pass-get-secret "irc/libera.chat")
          :channels ("#emacs")))
#+end_quote

* TODO Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]

* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]

* TODO Appendix
#+begin_quote
 󱌣 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote