Expression which is evaluated to format a range of lines for the gq operator or automatic formatting (see 'formatoptions'). When this option is empty 'formatprg' is used.

The v:lnum variable holds the first line to be formatted. The v:count variable holds the number of lines to be formatted. The v:char variable holds the character that is going to be inserted if the expression is being evaluated due to automatic formatting. This can be empty. Don't insert it yet!

Example:

:set formatexpr=mylang#Format()

This will invoke the mylang#Format() function in the autoload/mylang.vim file in 'runtimepath'. autoload

The advantage of using a function call without arguments is that it is faster, see expr-option-function.

The expression is also evaluated when 'textwidth' is set and adding text beyond that limit. This happens under the same conditions as when internal formatting is used. Make sure the cursor is kept in the same spot relative to the text then! The mode() function will return "i" or "R" in this situation.

When the expression evaluates to non-zero Vim will fall back to using the internal format mechanism.

If the expression starts with s: or <SID>, then it is replaced with the script ID (local-function). Example:

set formatexpr=s:MyFormatExpr()
set formatexpr=<SID>SomeFormatExpr()

Otherwise, the expression is evaluated in the context of the script where the option was set, thus script-local items are available.

The expression will be evaluated in the sandbox when set from a modeline, see sandbox-option. That stops the option from working, since changing the buffer text is not allowed. This option cannot be set in a modeline when 'modelineexpr' is off. NOTE: This option is set to "" when 'compatible' is set.

(default "")

not available when compiled without the +eval feature