This pull request adds two new features (as discussed in issue #11728):

1. A single argument name in a functions -a/--argument-names list can end in ..., the variable (with the ... removed) will be set to a list containing as many arguments as possible, whilst still leaving arguments to be assigned to the rest of the parameters.
2. A new -A/--strict-argument-names option is added that works like -a/--argument-names, but you will get an error if you use the function with an incorrect number of arguments.

I also 'fixed' a few strange related behaviours that I noticed (see below).

I've documented everything and added test cases, however there is one bug (in my last commit): the error message produced by -A cannot be redirected away, e.g.:

function foo -A arg; end
foo &>/dev/null # Still prints an error message

However, this is consistent with the behaviour of calling a non-existent function/command.
Please let me know if you have any idea how to fix this.

Details

Copied from the documentation for function, with changed behaviour in bold:

• -a NAMES or --argument-names NAMES
  Assigns the value of successive command-line arguments to the names given in NAMES (separated by spaces). These are the same arguments given in argv, and are still available there (unless --inherit-variable argv was used or one of the given NAMES is argv). See also Argument Handling.

  A single argument name given can end in ..., in which case a variable number of arguments are saved in a variable with that name (excluding the ... part), as many as possible whilst still leaving arguments for each of the other named arguments. If this cannot be done (because the number of arguments is smaller than the number of argument names), the argument with a ... is set to the empty list, and the other arguments are asigned values as if the ... one was not there.

  See the Argument Names Caveats section below for what happens when the number of arguments passed differs from the number of argument NAMES.

• -A NAMES or --strict-argument-names NAMES
  This behaves like like -a / --argument-names, except that calling the function with an incorrect number of arguments will print an error, return 2, and not execute the body of the function.
  If none of the given NAMES use a ..., this error will trigger when the number of actual arguments does not equal the number of NAMES.
  Otherwise, (if ... was used) the error will trigger if the number of actual arguments is less than the number NAMES minus 1.

  Unlike the -a/--argument-names option, the given NAMES list can be empty, in which case an error will be generated if the function is called with a non-empty list of arguments.

Argument Names Caveats

(this section is new, but some of it describes existing behaviour)

The -a / --argument-names flag does not validate the number of arguments passed: if an argument is missing the corresponding variable will be assigned to an empty list. For example:

function two -a x y
    set -l
end
two 1
# prints:
#    argv 1
#    x 1
#    y

In contrast, if the -A / --strict-argument-names option where used instead, the above call to two would produce an error.

Similarly, if -a / --argument-names is used and none of the argument names end in ..., any extra arguments are ignored, but they are still accessible in $argv. Continuing the previous example:

two 1 2 3
# prints:
#    argv '1'  '2'  '3'
#    x 1
#    y 2

Using -A / --strict-argument-names will make the above call to two an error.

If on the other hand the last argument name does end in ..., any extra arguments are stored in that variable. For example:

function one_or_more -a x y...
    set -l
end
one_or_more 1 2 3
# prints:
#    argv '1'  '2'  '3'
#    x 1
#    y '2'  '3'

The same behaviour occurs with the -A / --strict-argument-names option.

If the argument named with a ... is not the last, then if possible, it will leave enough arguments for the subsequent argument names. For example:

function more_or_one -a x... y
    set -l
end
more_or_one 1 2 3
# prints:
#    argv '1'  '2'  '3'
#    x '1'  '2'
#    y 3

The argument with a ... is however set to the empty list if there are not enough arguments to satisfy all the argument names. For example:

function more_or_two -a x... y z
    set -l
end
more_or_two 1
# prints:
#    argv 1
#    x
#    y 1
#    z

However, with the -A / --strict-argument-names option, the above call to more_or_two would produce an error.

The Commits

This first group of changes are not necessary for the rest of the functionality, so I'm happy to remove them if you don't like them:

1. f7f60b3 Use idiomatic Rust error handling for function builtin.

   This simply does the same thing as Convert builtin functions return type from Option<c_int> to Result<StatusOk, StatusError>. #10948, but for the function builtin.

2. 6a7667d Output function argument-names in one group.

   This makes it so that printing a function definition will only use one
   --argument-names group, instead of one for argument name.
   For example, "function foo -a x y; ..." will print with "function foo
   --argument-names x y" instead of "function foo --argument-names x
   --argument-names y", which is very bizarre.

   Moreover, the documentation no longer says that argument-names "Has to
   be the last option.". This sentence appears to have been introduced in
   error by pull Explain function --argument-names in more detail. #10524, since the ability to have options afterwards was
   deliberately added by pull Fix options after --argument-names to function #6188.

3. cd8c938 Allow overwriting argv with function -a and -V

   Previously, if you called a function parameter 'argv', within the body
   of the function, argv would be set to all the arguments to the
   function, and not the one indicated by the parameter name.
   The same behaviour happened if you inherited a variable named 'argv'.
   Both behaviours were quite surprising, so this commit makes things more
   obvious, although they could alternatively simply be made errors.

4. c813ea2 Prohibit duplicate variable names with function -a and -V options

   It is now an error to use the same variable name twice with
   --inherit-variable and/pr --argument-names.
   The previous behaviour was:
   1. duplicate --inherit-variable's worked as if you only inherited
   the variable once
   2. Later --argument-names override earlier ones
   3. An --inherit-variable overrides an --argument-names
   Thus this change is backwards incompatible, however, such duplicate
   names are not useful and where likely unintentional, and none of the
   test cases were depending on the old behaviour.

   (I do note that there was code written to specifically remove any
   duplicate --inherit-variable's, but the only difference this made was
   that the duplicates wouldn't be displayed by the functions or type
   builtin. This seems to have been done to preserve the prior behaviour
   when it was a HashMap.)

The next commit adds a section to the documentation that the remaining commits add to:

5. 4ee163d Added more documentation for function --argument-names

   Specifically, this adds a section to the "function" builtin
   documentation explaining what happens when you call a function defined
   with --argument-names, but with a different number of arguments than
   argument-names.

6. 6ad3d9e Allow variadic function --argument-names

   Specifically, this allows the last --argument-names in a function
   definition to be suffixed with ... This causes any leftover arguments in
   argv to be appended to the affixed variable name.

   The documentation has been updating giving details on how different
   numbers of argument names and argv elements are reconciled, with and
   without the new ...

7. 181c8f9 Do not require the variadic --argument-names to be the last one (note: I made this a seperate commit in case it's too strange/useless)

   This commit makes it so that an argument-name ending with a ...
   in a function's --argument-names list is not required to be the last.
   There can still only be one such argument name.
   The idea is that a '...' argument name will consume as many arguments
   from argv as possible, whilst still leaving one argument for each normal
   argument name (if possible).

8. 25a79d4 Add an -A/--strict-argument-names option to function

   The new -A/--strict-argument-names option behave like the existing
   -a/--argument-names option to function, but with the following
   differences:

   • If none of the argument names contains a ... suffix, it will be
     an error to call the function with a different number of arguments
     compared to the number of argument names.
   • If one of the argument names does contain a ... suffix, it will
     be an error to call it with less arguments, than non-... argument
     names.
   • it cannot be used together with -a/--argument-names (e.g.
     function f -A x -A y, and function f -a x -a y are allowed, but
     function f -A x -a y is not.)
   • It can be used without any argument argument names
     (e.g. function f -A), indicating that the function takes no arguments.

   An error is produced as follows:
   - An error message of the following form is printed to stderr:
   error: : function requires exactly arguments, but where supplied
   - The function is not called
   - A status code of 2 is returned (similarly to other builtins
   when you provide them with an incorrect number/format of arguments)

   Note that the error message is printed before the function is called,
   so any redirections on the function call statement are not applied,
   this is a bug that should be fixed.

   This new feature fixes make functions defined in fish spit error on invalid argument count (suggestion/enhancement) #11728.

Future Stuff

If this pull request is accepted, I would like to add:

• Add -a/--argument-names and -A/--strict-argument-names to argparse (although I note similar suggestions were previously rejected in We should be able to specify an array that argparse will alter/set #5778 and Enhance argparse with option to set variable names. #5946, but they didn't include my new ... feature).
• Add -m/--multiple and -M/--strict-multiple to set (fixing Add option to set for unwrapping, i.e. splitting and assigning to two multiple variables #11457), that would be similar to -a and -A, the usage would be:

  set <options> -m <var>... -- <values>

  Where <options> are any existing set options that make sense. Each <var> part could be anything that set currently supports (e.g. foo[1 3]), or a name followed by ....

So let me know if you think any of my changes would not be suitable for argparse or set.