4 Modules

One way to add functionality to ERC is to customize which of its many modules are loaded.

You can do this by typing C-h v erc-modules RET and clicking ‘customize’ near the bottom of the resulting help buffer, where it says “You can customize this variable.” When removing a module outside of Customize, you may wish to ensure it’s disabled by invoking its associated minor-mode toggle with a nonpositive prefix argument, for example, C-u - M-x erc-spelling-mode RET. Additionally, if you plan on loading third-party modules that perform atypical setup on activation, you may need to arrange for calling erc-update-modules in your init file. Examples of such setup might include registering an erc-before-connect hook, advising erc-open, and modifying erc-modules itself. On Emacs 29 and greater, you can also run erc-update-modules indirectly, via (setopt erc-modules erc-modules).

The following is a list of available modules.

autoaway

Set away status automatically

autojoin

Join channels automatically

bufbar

List buffers belonging to a connection in a side window; part of Custom group erc-status-sidebar

button

Buttonize URLs, nicknames, and other text

capab-identify

Mark unidentified users on freenode and other servers supporting CAPAB.

command-indicator

Echo command lines for “slash commands”, like /JOIN #erc and /HELP join

completion (aka pcomplete)

Complete nicknames and commands (programmable)

fill

Wrap long lines

identd

Launch an identd server on port 8113

irccontrols

Highlight or remove IRC control characters

keep-place

Remember your position in buffers

log

Save buffers in logs

match

Highlight pals, fools, and other keywords

menu

Display a menu in ERC buffers

netsplit

Detect netsplits

nicks

Automatically colorize nicks

nickbar

List participating nicks for the current target buffer in a side window; part of Custom group erc-speedbar

noncommands

Don’t display non-IRC commands after evaluation

notify

Notify when the online status of certain users changes

notifications

Send you a notification when you get a private message, or your nickname is mentioned

page

Process CTCP PAGE requests from IRC

querypoll

Update query participant data by continually polling the server

readonly

Make displayed lines read-only

replace

Replace text in messages

ring

Enable an input history

sasl

Enable SASL authentication

scrolltobottom

Scroll to the bottom of the buffer

services

Identify to Nickserv (IRC Services) automatically

smiley

Convert smileys to pretty icons

sound

Play sounds when you receive CTCP SOUND requests

spelling

Check spelling of messages

stamp

Add timestamps to messages

track

Track channel activity in the mode-line

truncate

Truncate buffers to a certain size

unmorse

Translate morse code in messages

Auxiliary Modules

For various reasons, the following modules aren’t currently listed in the Custom interface for erc-modules, but feel free to add them explicitly. They may be managed by another module or considered more useful when toggled interactively or just deemed experimental.

fill-wrap

Wrap long lines using visual-line-mode

keep-place-indicator

Remember your place in buffers with a visible reminder; activated interactively or via something like erc-join-hook

services-regain

Automatically ask NickServ to reclaim your nick when reconnecting; experimental as of ERC 5.6

Required Modules

Note that some modules are essential to core IRC operations and thus not listed above. You can nevertheless still remove these, but doing so demands special precautions to avoid degrading the user experience. At present, the only such module is networks, whose library ERC always loads anyway.

Local Modules

All modules operate as minor modes under the hood, and some newer ones may be defined as buffer-local. These so-called “local modules” are a work in progress and their behavior and interface are subject to change. As of ERC 5.5, the only practical differences are as follows:

1. “Control variables,” like erc-sasl-mode, retain their values across IRC sessions and override erc-module membership when influencing module activation.
2. Removing a local module from erc-modules via Customize not only disables its mode but also kills its control variable in all ERC buffers.
3. “Mode toggles,” like erc-sasl-mode and the complementary erc-sasl-enable/erc-sasl-disable pairing, behave differently than their global counterparts.

In target buffers, a local module’s activation state survives “reassociation” by default, but modules themselves always have the final say. For example, a module may reset all instances of itself in its network context upon reconnecting. Moreover, the value of a mode variable may be meaningless in buffers that its module has no interest in. For example, the value of erc-sasl-mode doesn’t matter in target buffers and may even remain non-nil after SASL has been disabled for the current connection (and vice versa).

When it comes to server buffers, a module’s activation state only persists for sessions revived via the automatic reconnection mechanism or a manual ‘/reconnect’ issued at the prompt. In other words, this doesn’t apply to sessions revived by an entry-point command, such as erc-tls, because such commands always ensure a clean slate by looking only to erc-modules. Although a session revived in this manner may indeed harvest other information from a previous server buffer, it simply doesn’t care which modules might have been active during that connection.

Lastly, a local mode’s toggle command, like erc-sasl-mode, only affects the current buffer, but its “non-mode” cousins, like erc-sasl-enable and erc-sasl-disable, operate on all buffers belonging to their connection (when called interactively). And unlike global toggles, none of these ever mutates erc-modules.

Loading

ERC loads internal modules in alphabetical order and third-party modules as they appear in erc-modules. When defining your own module, take care to ensure ERC can find it. An easy way to do that is by mimicking the example in the doc string for define-erc-module (also shown below). For historical reasons, ERC falls back to requireing features. For example, if some module my-module in erc-modules lacks a corresponding erc-my-module-mode command, ERC will attempt to load the library erc-my-module prior to connecting. If this fails, ERC signals an error. Users defining personal modules in an init file should (provide 'erc-my-module) somewhere to placate ERC. Dynamically generating modules on the fly is not supported.

Some older built-in modules have a second name along with a second minor-mode toggle, which is just a function alias for its primary counterpart. For practical reasons, ERC does not define a corresponding variable alias because contending with indirect variables complicates bookkeeping tasks, such as persisting module state across IRC sessions. New modules should definitely avoid defining aliases without a good reason.

Some packages have been known to autoload a module’s definition instead of its minor-mode command, which severs the link between the library and the module. This means that enabling the mode by invoking its command toggle isn’t enough to load its defining library. As such, packages should only supply module-related autoload cookies with an actual autoload form for their module’s minor-mode command, like so:

;;;###autoload(autoload 'erc-my-module-mode "erc-my-module" nil t)
(define-erc-module my-module nil
 "My doc string."
 ((add-hook 'erc-insert-post-hook #'erc-my-module-on-insert-post))
 ((remove-hook 'erc-insert-post-hook #'erc-my-module-on-insert-post)))

As implied earlier, packages can usually omit such cookies entirely so long as their module’s prefixed name matches that of its defining library and the library’s provided feature.

Finally, packages have also been observed to run erc-update-modules in top-level forms, forcing ERC to take special precautions to avoid recursive invocations. Another unfortunate practice is mutating erc-modules itself upon loading erc, possibly by way of an autoload. Doing this tricks Customize into displaying the widget for erc-modules incorrectly, with built-in modules moved from the predefined checklist to the user-provided free-form area.

Next: Advanced Usage, Previous: Keys Used in ERC, Up: ERC [Contents][Index]