Using `gq` to correctly wrap function arguments

Question

Consider editing the code

foo = long_function_name(var_one, var_two, var_three, var_four)

where the textwidth 'column' occurs just after var_two.

I would like to be able to press gqq on the line and it get formatted to:

foo = long_function_name(var_one, var_two, 
                         var_three, var_four)

Currently it does this:

foo = long_function_name(var_one, var_two, 
    var_three, var_four)

How can this be done?

Answer 1

Assuming you are editing a file recognized by Vim as source code and therefore Vim's more sophisticated indenting is enabled¹ (check with :set cindent?) you can just do this:

:set cinoptions=(0

With :set textwidth=50 I get this formatting of your example line:

foo = long_function_name(var_one, var_two,
                         var_three, var_four)

cinoptions allows you to tune how Vim indents various code constructs.

The (N option is described, in part, in :h cino-( thusly...

(N    ... When N is 0 or the unclosed parentheses
      is the first non-white character in its line, line up with the
      next non-white character after the unclosed parentheses.

But for this particular case the help for WN (:h cino-W) actually has a (counter) example that is more in line with your case:

WN    When in unclosed parentheses and N is non-zero and either
      using "(0" or "u0" ...

    cino=(0                         cino=(0,W4
      a_long_line(                    a_long_line(
                  argument,               argument,
                  argument);              argument);
      a_short_line(argument,          a_short_line(argument,
                   argument);                      argument);

We want it to look like the example on the left so cinoptions=(0.

Take a look at :h cinoptions-values for heaps of other ways to tune the indentation.

¹ _{This doesn't apply to all languages. See the comments/chat for discussion about Python files having nocindent by default.}