doomemacs/modules/app/irc/README.org

:app irc

• Description
  • Maintainers
  • Module flags
  • Packages
  • Hacks
  • Changelog
• Installation
  • macOS
  • Debian / Ubuntu
  • Arch Linux
  • NixOS
• Usage
• Configuration
• Troubleshooting
• Frequently asked questions
• Appendix

Description   unfold

This module turns Emacs into an IRC client, capable of OS notifications.

Maintainers

This module has no dedicated maintainers. 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 module does not have a changelog yet.

Installation

Enable this module in your doom! block.

This module requires:

• GnuTLS, for secure IRC connections to work.

This should be available through your OS package manager.

macOS

brew install gnutls

Debian / Ubuntu

apt install gnutls-bin

Arch Linux

pacman -S gnutls

NixOS

environment.systemPackages = [ pkgs.gnutls ];

TODO Usage

󱌣 This module's usage documentation is incomplete. Complete it?

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	<localleader> a	Switch to the next active buffer
circe-command-JOIN	<localleader> j	Join a channel
+irc/send-message	<localleader> m	Send a private message
circe-command-NAMES	<localleader> n	List the names of the current channel
circe-command-PART	<localleader> p	Part the current channel
+irc/quit	<localleader> Q	Kill the current circe session and workgroup
circe-reconnect	<localleader> R	Reconnect the current server

TODO Configuration

󱌣 This module's configuration documentation is incomplete. Complete it?

Use set-irc-server! SERVER PLIST to configure IRC servers. Its second argument (a plist) takes the same arguments as circe-network-options:

;; 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"))))

However, it is a obviously a bad idea to store your password in plaintext, so 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 Pass):

;;; 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"))))

If Doom's doom-module::tools pass module is enabled, auth-source can integrate with Pass.

 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")))

TODO Troubleshooting

There are no known problems with this module. Report one?

Frequently asked questions

This module has no FAQs yet. Ask one?

TODO Appendix

󱌣 This module has no appendix yet. Write one?