When do I have to escape special characters with backslashes in expr-mappings? #19929

Hello! I'm trying to understand how <expr> mappings work, so I can reduce unnecessary backslashes in my mappings and make sure that they work as intended in all cases.

I went through the following help sections:

• :help expr-quote
• :help expr-'
• :help ternary
• :help :map-cmd
• :help :map-expression
• :help i_CTRL-R_=
• :help ins-completion (in particular, :help E565)
• :help ins-autocompletion-example
• :help compatible
• :help cpoptions (in particular, the B, k, < flags)

I tested some mappings using vim --clean and :set noshowmode so I can see what's being displayed. The Vim version is 9.1.1-2045.

Based on my understanding, it seems that every special character returned by the expression (e.g., <Tab>, <Cmd>, <CR>, <C-Y>, etc.) needs to be escaped with a backslash and needs to be enclosed in double-quotes, not single-quotes. For example, this mapping works as expected (i.e., pressing <C-T> in insert mode echoes 1):

inoremap <expr> <C-T> "\<Cmd>echo 1\<CR>"

I was surprised to see that this also works:

inoremap <expr> <C-T> '<Cmd>echo 1<CR>'

However, if I define this function:

function! g:Test() abort
  return '<Cmd> echo 1<CR>'
endfunction

and update the mapping:

inoremap <expr> <C-T> g:Test()

, then thee mapping does not work (i.e., it inserts the <Cmd>echo 1<CR> text literally into the buffer). If I replace the function with this:

function! g:Test(value) abort
  return "\<Cmd> echo 1\<CR>"
endfunction

, then the mapping works again.

I was not able to find anywhere in the documentation why I don't have to use double-quotes and backslashes when I inline the expression into the mapping, but I have to if the expression is returned by a function. Programmatically, they should be equivalent.

Am I missing something? Is this simplified inlined expression mapping inteded behavior, and can I rely on it in my config? Any thoughts to help me understand how this works would be greatly appreciated!