When using a recursive mapping, why is there no infinite recursion when RHS starts with LHS?

Question

I noticed that the following mapping does not cause an infinite recursion (when pressing x).

:map x x

I didn't see anything in Vim's documentation that would explain this.

Further experimentation seems to suggest that when the right-hand-side of a mapping starts with the left-hand-side, there is no infinite recursion. For example, :map x Xx causes infinite recursion, but :map x xX doesn't (when pressing x).

My expectation is that when the contents of the left-hand-side are included on the right-hand-side, this would result in an infinite recursion, regardless of the positioning within the right-hand-side.

Is there some documented reason for the behavior I'm observing (e.g., special handling if the beginning of the right-hand-side matches the left-hand-side)?

Answer 1

This behavior is documented in :help recursive_mapping:

There is one exception: If the {rhs} starts with {lhs}, the first character is not mapped again (this is Vi compatible).

For example:

:map ab abcd

will execute the a command and insert "bcd" in the text. The ab in the {rhs} will not be mapped again.

Answer 2

Normally vim prevent a mapping to go crazy by limiting the maximum number of recursion. You can set the value of the maxmapdepth option (see :help maxmapdepth):

                                                'maxmapdepth' 'mmd' E223
'maxmapdepth' 'mmd'     number  (default 1000)
                        global
        Maximum number of times a mapping is done without resulting in a
        character to be used.  This normally catches endless mappings, like
        ":map x y" with ":map y x".  It still does not catch ":map g wg",
        because the 'w' is used before the next mapping is done.  See also
        key-mapping.