3

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

1 Answer 1

4

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

5
  • 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, 2020 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, 2020 at 15:53
  • Could you also explain why there are 2 ways to set a count -range=N and -count=N?
    – PiersyP
    Apr 28, 2020 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, 2020 at 16:03
  • @D.BenKnoble, thanks. I understand the difference between the 2 ways to set the count. and the effect it has. I'm still not sure why the designers of vim would allow 2 different ways to set the count. It seems to be something that would lead to confusion?
    – PiersyP
    Jul 31, 2020 at 11:15

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

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