Function: evil-define-motion

evil-define-motion is a macro defined in evil-macros.el.

Signature

(evil-define-motion MOTION (COUNT ARGS...) DOC [[KEY VALUE]...] BODY...)

Documentation

Define a motion command MOTION.

ARGS is a list of arguments. Motions can have any number of arguments, but the first (if any) has the predefined meaning of count. BODY must execute the motion by moving point.

Optional keyword arguments are:
- :type - determines how the motion works after an operator (one of
  inclusive, line, block and exclusive, or a self-defined
  motion type)
- :jump - if non-nil, the previous position is stored in the jump
  list, so that it can be restored with C-o (evil-jump-backward)

Source Code

;; Defined in ~/.emacs.d/elpa/evil-20251108.138/evil-macros.el
(defmacro evil-define-motion (motion args &rest body)
  "Define a motion command MOTION.
ARGS is a list of arguments.  Motions can have any number of
arguments, but the first (if any) has the predefined meaning of
count.  BODY must execute the motion by moving point.

Optional keyword arguments are:
- `:type' - determines how the motion works after an operator (one of
  `inclusive', `line', `block' and `exclusive', or a self-defined
  motion type)
- `:jump' - if non-nil, the previous position is stored in the jump
  list, so that it can be restored with \
\\<evil-motion-state-map>\\[evil-jump-backward]

\(fn MOTION (COUNT ARGS...) DOC [[KEY VALUE]...] BODY...)"
  (declare (indent defun)
           (doc-string 3)
           (debug (&define name lambda-list
                           [&optional stringp]
                           [&rest keywordp sexp]
                           [&optional ("interactive" [&rest form])]
                           def-body)))
  (let (arg doc interactive key keys)
    (when args
      (setq args `(&optional ,@(delq '&optional args))
            ;; the count is either numerical or nil
            interactive '("<c>")))
    ;; collect docstring
    (when (and (> (length body) 1)
               (or (eq (car-safe (car body)) #'format)
                   (stringp (car body))))
      (setq doc (pop body)))
    ;; collect keywords
    (setq keys (plist-put keys :repeat 'motion))
    (while (keywordp (car body))
      (setq key (pop body)
            arg (pop body)
            keys (plist-put keys key arg)))
    ;; collect `interactive' specification
    (when (eq (car-safe (car body)) 'interactive)
      (setq interactive (cdr (pop body))))
    ;; macro expansion
    `(progn
       ;; refresh echo area in Eldoc mode
       (when ',motion
         (eval-after-load 'eldoc
           '(and (fboundp 'eldoc-add-command)
                 (eldoc-add-command ',motion))))
       (evil-define-command ,motion (,@args)
         ,@(when doc `(,doc))         ; avoid nil before `interactive'
         ,@keys
         :keep-visual t
         (interactive ,@interactive)
         ,@body))))