Next: Advanced Usage, Previous: Keys Used in ERC, Up: ERC [Contents][Index]
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 (local) ¶ 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 (local) ¶ 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
readonly ¶ Make displayed lines read-only
replace ¶ Replace text in messages
ring ¶ Enable an input history
sasl (local) ¶ 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
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 just deemed too
niche or experimental.
fill-wrap (local) ¶ Wrap long lines using visual-line-mode
keep-place-indicator (local) ¶ Remember your place in buffers with a visible reminder; activated
interactively or via something like erc-join-hook
querypoll (local) ¶ Update query participant data by continually polling the server
services-regain (local) ¶ Automatically ask NickServ to reclaim your nick when reconnecting; experimental as of ERC 5.6
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.
All modules operate as minor modes under the hood, and newer ones are mostly 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.6, the only practical differences are as follows:
erc-sasl-mode, retain their values across IRC sessions.
erc-modules via Customize not only
disables its mode but also kills its mode variable in all ERC buffers.
erc-sasl-mode and its one-way variants
erc-sasl-enable and erc-sasl-disable, behave differently
than their global counterparts.
To detect whether a module is local, examine its mode variable. For
example, if you run C-h v erc-sasl-mode RET, you’ll notice
it says “Automatically becomes buffer-local when set”. You can do the
same in Lisp code with (local-variable-if-set-p 'erc-sasl-mode).
In an ERC buffer, a local module is either enabled or disabled if its
mode variable has a local binding. This activation state may
contradict a module’s presence in erc-modules, namely, in buffers
where it isn’t applicable or has otherwise been disabled. In fact, a
local module’s membership in erc-modules does nothing more than
guarantee
In keeping with this, all built-in local modules disable themselves in inapplicable buffers rather than remain no-ops. Some also take strides to enable themselves elsewhere when needed or at least emit a helpful error. For example, the ‘nicks’ module does both in server buffers, where it shares resources among the target buffers it primarily services. ERC expects third-party local modules to mimic this pattern and to document what buffer types they operate in: server, query, or channel. (In the case of ‘nicks’, it would be all three: it’s session-local.)
In ERC, you can think of an IRC session as a group of buffers sharing the same connection to a server. After a connection ends, this association endures so that ERC can revive the session when reconnecting. As it does with connection parameters, ERC therefore persists a local module’s activation state through reconnections, reenabling modules that were previously active while ensuring others are disabled. A couple related things to note here are
erc-modules between sessions
When it comes to a local module’s various activation commands, the
primary mode command, like erc-sasl-mode, for example, only
affects the current buffer, but its unidirectional 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.
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]