Function: define-erc-module

define-erc-module is a macro defined in erc-common.el.gz.

Signature

(define-erc-module NAME ALIAS DOC ENABLE-BODY DISABLE-BODY &optional LOCAL-P)

Documentation

Define a new minor mode using ERC conventions.

Expect NAME to be the module's name and ALIAS, when non-nil, to be a retired name used only for compatibility purposes. In new code, assume NAME is the same symbol users should specify when customizing erc-modules (see info node (erc) Module Loading for more on naming).

DOC is the documentation string to use for the minor mode. ENABLE-BODY is a list of expressions used to enable the mode. DISABLE-BODY is a list of expressions used to disable the mode. If LOCAL-P is non-nil, the mode will be created as a buffer-local mode, rather than a global one.

This will define a minor mode called erc-NAME-mode, possibly an alias erc-ALIAS-mode, as well as the helper functions erc-NAME-enable, and erc-NAME-disable.

With LOCAL-P, these helpers take on an optional argument that, when non-nil, causes them to act on all buffers of a connection. This feature is mainly intended for interactive use and does not carry over to their respective minor-mode toggles. Beware that for global modules, these helpers and toggles all mutate erc-modules.

Example:

  ;;;###autoload(autoload 'erc-replace-mode "erc-replace")
  (define-erc-module replace nil
    "This mode replaces incoming text according to `erc-replace-alist'."
    ((add-hook 'erc-insert-modify-hook
               #'erc-replace-insert))
    ((remove-hook 'erc-insert-modify-hook
                  #'erc-replace-insert)))

Source Code

;; Defined in /usr/src/emacs/lisp/erc/erc-common.el.gz
(defmacro define-erc-module (name alias doc enable-body disable-body
                                  &optional local-p)
  "Define a new minor mode using ERC conventions.
Expect NAME to be the module's name and ALIAS, when non-nil, to
be a retired name used only for compatibility purposes.  In new
code, assume NAME is the same symbol users should specify when
customizing `erc-modules' (see info node `(erc) Module Loading'
for more on naming).

DOC is the documentation string to use for the minor mode.
ENABLE-BODY is a list of expressions used to enable the mode.
DISABLE-BODY is a list of expressions used to disable the mode.
If LOCAL-P is non-nil, the mode will be created as a buffer-local
mode, rather than a global one.

This will define a minor mode called erc-NAME-mode, possibly
an alias erc-ALIAS-mode, as well as the helper functions
erc-NAME-enable, and erc-NAME-disable.

With LOCAL-P, these helpers take on an optional argument that,
when non-nil, causes them to act on all buffers of a connection.
This feature is mainly intended for interactive use and does not
carry over to their respective minor-mode toggles.  Beware that
for global modules, these helpers and toggles all mutate
`erc-modules'.

Example:

  ;;;###autoload(autoload \\='erc-replace-mode \"erc-replace\")
  (define-erc-module replace nil
    \"This mode replaces incoming text according to `erc-replace-alist'.\"
    ((add-hook \\='erc-insert-modify-hook
               #\\='erc-replace-insert))
    ((remove-hook \\='erc-insert-modify-hook
                  #\\='erc-replace-insert)))"
  (declare (doc-string 3) (indent defun))
  (let* ((sn (symbol-name name))
         (mode (intern (format "erc-%s-mode" (downcase sn))))
         (enable (intern (format "erc-%s-enable" (downcase sn))))
         (disable (intern (format "erc-%s-disable" (downcase sn))))
         (nmodule (erc--normalize-module-symbol name))
         (amod (and alias (intern (format "erc-%s-mode"
                                          (downcase (symbol-name alias)))))))
    `(progn
       (define-minor-mode
         ,mode
         ,(erc--fill-module-docstring (format "Toggle ERC %s mode%s.
If called interactively, enable `%s' if ARG is positive,
and disable it otherwise.  If called from Lisp, enable the mode
if ARG is omitted or nil.
\n%s" name (if local-p " locally" "") mode doc))
         :global ,(not local-p)
         :group (erc--find-group ',name ,(and alias (list 'quote alias)))
         ,@(unless local-p `(:require ',(erc--find-feature name alias)))
         ,@(unless local-p `(:type ,(erc--prepare-custom-module-type name)))
         (let ((erc--module-toggle-prefix-arg arg))
           (if ,mode (,enable) (,disable))))
       ,(erc--assemble-toggle local-p name enable mode t enable-body)
       ,(erc--assemble-toggle local-p name disable mode nil disable-body)
       ,@(and amod `((defalias ',amod #',mode)
                     (put ',amod 'erc-module ',nmodule)))
       (put ',mode 'erc-module ',nmodule)
       ;; For find-function and find-variable.
       (put ',mode    'definition-name ',name)
       (put ',enable  'definition-name ',name)
       (put ',disable 'definition-name ',name))))