Why `v:lnum` doesn't return 1 for the first line?

Question

I really want to know why doesn't Vim's v:lnum return 1 for very first line. I tried googling and searching in Vim's docs, but I can't find an answer.

I understand that v:lnum returns line number, but I don't understand which line v:lnum is referring to..? A little aside; from help v:lnum I understand that you can only use v:lnum with some expressions including indentexpr (the one I'm interested in the most for my indentation script).

workflow test 1

1. make a .vim file. e.g check.vim
2. append echo v:lnum
3. open new vim window and :source check.vim
4. append some text to the file and :source check.vim again
5. no matter how many lines I add to the file I always get 0 back

I think I understand this, since Vim docs say that v:lnum only works in conjunction with some specific expressions then you would expect 0 when I'm trying to use v:lnum by itself.

workflow test 2

1. make check.vim file

2. append

   setlocal indentexpr=Check()
   function! Check()
     let line = getline(v:lnum)
     echo v:lnum line
   endfunction
   

3. open new vim window and :source check.vim

4. append some text to the file and :call Check() function
5. I DON'T get first line no matter what I do.. I can get any other lines.. e.g
   • if I only type in one line into the file and :call Check() I get 0 and ''
   • if I type in second line into the file and :call Check() I get 2 and check line two back
   • if I keep adding lines to the file and run :call Check() on lets say the fifths line I get 5 and check line five

I think I understand that v:lnum returns index of the last line typed into the file. But why doesn't it return the index of the very first line type?

Answer 1

v:lnum is a Vim internal variable, that is only valid while evaluating the indentexpr, foldexpr, formatexpr options. In other contexts this does nothing.

This means, that in you indentexpr or formatexpr you can find out, what line is currently being evaluated and react accordingly.

For indentexpr this means, it will get filled, once you start indenting your file, e.g. using gg=G, for formatexpr this will be evaluated when defining your foldmethod and folding is enabled and formatexpr will be evaluated using the gq command.

In other context, this is really invalid. It should actually be always 0 so there might be a (minor) bug there.