2

I can't understand the vim help for :command-range, it states

    -range=N    A count (default N) which is specified in the line
            number position (like :split); allows for zero line
            number.

The documentation for :split is not helpful either. I'd also like to know the meaning of -range=0 if not obvious from the description of -range=N

3

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

| improve this answer | |
  • 1
    Great answer! From the OP: "The documentation for :split is not helpful either." So maybe you should address how you can use :10split to create a new window 10 lines high? And perhaps highlight the <code>:<b>[N]</b>split</code> in the help for :split that illustrates that use? – filbranden Apr 28 at 15:52
  • The command command -range Mine echo <range> <line1>,<line2> is not working for me I think updating to command -range Mine echo <range> <line1> <line2> would make it correct. – PiersyP Apr 28 at 15:53
  • Could you also explain why there are 2 ways to set a count -range=N and -count=N? – PiersyP Apr 28 at 16:02
  • @PiersyP I think I did—-range only allows the count in range position, while -count also allows it as the first argument (e.g., command! -count Mine echo <count>, then :123Mine is the same as :Mine 123) – D. Ben Knoble Apr 28 at 16:03

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.