Using the -range
flag when defining a user-command usually allows the user to provide a range to the command:
command -range Mine echo <range> <line1> ',' <line2>
%Mine
1,/bar/Mine
" the next one is equivalent to .Mine by default
Mine
However, sometimes you want to be able to do
0Mine
Or else use the number provided as a <count>
:
command! -range=1 Mine echo <count>
You can also use the -count
attribute for this, though then the count is allowed to come as the first argument or in the range position.
See this paragraph:
Range handling ~
*E177* *E178* *:command-range* *:command-count*
By default, user-defined commands do not accept a line number range. However,
it is possible to specify that the command does take a range (the -range
attribute), or that it takes an arbitrary count value, either in the line
number position (-range=N, like the |:split| command) or as a "count"
argument (-count=N, like the |:Next| command). The count will then be
available in the argument with |<count>|.
Possible attributes are:
-range Range allowed, default is current line
-range=% Range allowed, default is whole file (1,$)
-range=N A count (default N) which is specified in the line
number position (like |:split|); allows for zero line
number.
-count=N A count (default N) which is specified either in the line
number position, or as an initial argument (like |:Next|).
-count acts like -count=0
Note that -range=N and -count=N are mutually exclusive - only one should be
specified.
Re: :split
, there's something easy to miss in this line from the docs:
:[N]sp[lit] [++opt] [+cmd] [file] *:sp* *:split*
That sneaky little [N]
is what indicates a count can be given as a range (usually, N
is used for counts and [range]
for ranges).
Then later, we read
Make the new window N high (default is to use half the height
of the current window). Reduces the current window height to
create room (and others, if the 'equalalways' option is set,
'eadirection' isn't "hor", and one of them is higher than the
current or the new window).
So the count in this case is used to set the window-height, à la :10split