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.

Symbol NAME is the name of the module. Symbol ALIAS is the alias to use, or nil. 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.
Symbol NAME is the name of the module.
Symbol ALIAS is the alias to use, or nil.
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))))
         (group (intern (format "erc-%s" (downcase sn))))
         (enable (intern (format "erc-%s-enable" (downcase sn))))
         (disable (intern (format "erc-%s-disable" (downcase sn)))))
    `(progn
       (define-minor-mode
         ,mode
         ,(format "Toggle ERC %S mode.
With a prefix argument ARG, enable %s if ARG is positive,
and disable it otherwise.  If called from Lisp, enable the mode
if ARG is omitted or nil.
%s" name name doc)
         ;; FIXME: We don't know if this group exists, so this `:group' may
         ;; actually just silence a valid warning about the fact that the var
         ;; is not associated with any group.
         :global ,(not local-p) :group (quote ,group)
         (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-let* ((alias)
                    ((not (eq name alias)))
                    (aname (intern (format "erc-%s-mode"
                                           (downcase (symbol-name alias))))))
           `((defalias ',aname #',mode)
             (put ',aname 'erc-module ',(erc--normalize-module-symbol name))))
       (put ',mode 'erc-module ',(erc--normalize-module-symbol name))
       ;; For find-function and find-variable.
       (put ',mode    'definition-name ',name)
       (put ',enable  'definition-name ',name)
       (put ',disable 'definition-name ',name))))