More verbose compiler status

[clason]

Vimtex provides vimtex#compiler#is_running() to check whether continuous compilation has been activated (in which case it returns 1), which is very convenient for statuslines.

What would be even more convenient is if the status could distinguish "currently compiling", "finished compiling successfully", and "finished compiling with errors" (say, by returning 1, 2, and either 3 or -1) -- which I could then display in my statusline using different symbols.

For a statusline, the maximal convenience would be to have a buffer variable b:vimtex_compiler_status with these three values that is updated by vimtex itself.

I know I can probably finagle the current function and vimtex#compiler#callback() to achieve this, but it seems both easier (for me ;)) and more efficient to not poll these functions on every redraw?

[clason]

(Easiest for me would be 0 for "not running (continuosly)", 1 for "compiling started", 2 for "compiled successfully" and 3 for "compiled with errors" -- then I could just use

({'⟳', '✓', '✗'})[vim.b.vimtex_compiler_status]

in my statusline!)

[lervag]

Hmm. This is more tricky than just relying on the callback function. We need to know that "compiling started", which may be tricky. One possibility could be to add a BufWrite type autocmd for each VimTeX buffer that toggles the status flag.

Pseudocode:

• VimtexCompile && status == 0 -> let status = 1
• VimtexCompile && status > 0 -> Stop compiler
• vimtex#compiler#callback -> let status = 2 or 3 depending on result
• BufWrite autocmd && status > 0 -> let status = 1

Does this make sense, or do I miss something?

What is the benefit of b:vimtex_compiler_status over b:vimtex.compiler.status? The latter has the large benefit that it is shared for all buffers in the same multi-file project.

[clason]

Well, the big benefit is that it is a lot cheaper to read a variable than to call a function -- which might happen very often in a statusline.

I did not think that would involve a lot of changes, to be honest -- just setting or updating a variable whenever vimtex (or a callback) performs an action. But I see your point about getting information about the external compiler starting a new run. It's probably easier to realize with VimtexCompileSS...

[clason]

Hmm. I guess there are three different issues at play here, of increasing complexity:

1. Add 2 and 3 (last run ended in success and failure, respectively) to the output of vimtex#compiler#is_running() -- without necessarily going back to 1 (currently running).
2. Expose this information (also) through a static buffer variable (which I understand is more complicated due to different buffers possibly sharing one compiler -- by the way, I can't find b:vimtex.compiler.status() anywhere in the documentation?)
3. Detect that the compiler is currently running (a BufWrite autocommand would be the easiest way, I agree, but might give incorrect information in edge cases).

Step 3 is something I've found myself wishing for on occasion ("is latexmk actually running or did something go wrong?"), so that would be nice to have.

[clason]

Oh, I just found something: from man latexmk:

$compiling_cmd [""], $failure_cmd [""], $warning_cmd [""], $success_cmd [""]

      These variables specify commands that are executed at certain points of compilations.
      One motivation for their existance is to allow very useful convenient visual
      indications of compilation status even when the window receiving the screen output of
      the compilation is hidden.  This is particularly useful in preview-continuous mode.

      The commands are executed at the following points: $compiling_cmd at the start of
      compilation, $success_cmd at the end of a completely successful compilation,
      $failure_cmd at the end of an unsuccessful compilation, $warning_cmd at the of an
      otherwise successful compilation that gives warnings about undefined citations or
      references or about multiply defined references. If any of above variables is
      undefined or blank (the default situation), then the corresponding command is not
      executed.

      However, when $warning_cmd is not set, then in the case of a compilation with
      warnings about references or citations, but with no other error, one or other of
      $success_cmd or $failure_cmd is used (if it is set) according to the setting of
      $warnings_as_errors.

So at least latexmk (which I'm using) does provide a callback for everything I'm asking for?

[lervag]

Well, the big benefit is that it is a lot cheaper to read a variable than to call a function ...

Yes, of course; I suggested b:vimtex.compiler.status to be a variable. It does not currently exist.

1. Add 2 and 3 (last run ended in success and failure, respectively) to the output of vimtex#compiler#is_running() -- without necessarily going back to 1 (currently running).

Yes - this is more or less trivial.

2. Expose this information (also) through a static buffer variable (which I understand is more complicated due to different buffers possibly sharing one compiler -- by the way, I can't find b:vimtex.compiler.status() anywhere in the documentation?)

I think this is also more or less trivial, and again, I propose b:vimtex.compiler.status as the buffer variable because it is shared by all related buffers. If we add it, it can be initialized to -1 to ensure it exists. -1 would then indicate that the compiler has not been started at all, whereas 0 would typically mean it is started and then stopped.

3. Detect that the compiler is currently running (a BufWrite autocommand would be the easiest way, I agree, but might give incorrect information in edge cases).

This is the most complex part. I believe a BufWrite can work, but the $compiling_cmd seems a much better approach from the latexmk side.

I think this is all a good idea, and the most complex part is to "generalize" to get a more or less consistent behaviour across different backends. I believe one idea is this:

• Add a b:vimtex.compiler.status variable for all backends. Define a consistent scheme (Enum like), e.g.:
  • -1 : Not started
  • 0 : Not running
  • 1 : Compiling
  • 2 : Complete - Success
  • 3 : Complete - Failed
• Some backends may not allow to distinguish all states.
• Simplify the is_running() function to return the status variable. I believe it could then also be used in statuslines. I'm not sure if the overhead is noticable.

[lervag]

But I believe it may be beneficial to do some refactoring and improvement to the compiler backend code. I notice there's a lot of redundant code. :p

[clason]

Yes, of course; I suggested b:vimtex.compiler.status to be a variable. It does not currently exist.

Oh, sorry, then I misunderstood! Yes, of course, the name was just a placeholder -- name it however it fits best!

... Some backends may not allow to distinguish all states.

Yes, that sounds like a good approach.

Simplify the is_running() function to return the status variable. I believe it could then also be used in statuslines. I'm not sure if the overhead is noticable.

Not worse than now, so that's of course fine. But would you ever use the function instead of the variable? I can't think of a situation, but may be missing something. (Of course, backwards compatibility is a good reason.)

[clason]

Simplify the is_running() function to return the status variable.

Just to make sure I understand this: would you be able to access the status variable directly, or only through the is_running function?

[lervag]

Simplify the is_running() function to return the status variable. I believe it could then also be used in statuslines. I'm not sure if the overhead is noticable.

Not worse than now, so that's of course fine. But would you ever use the function instead of the variable?

Good question! I might go back on this, because is_running now also checks more explicitly for a running process, and as such, it also notices if a process was stopped by unexpected reasons. I think it could be better to rely on the variable and let is_running be more or less the same, except it may update the status flag if there is an unexpected change.

I can't think of a situation, but may be missing something. (Of course, backwards compatibility is a good reason.)

This was my original thought. I think is_running should be considered different than the status flag, because it indicates if there is a process running or not. So, it really should return a boolean.

Let me think on this for a bit. I will first do some refactoring here which should also simplify the process of making such a change. I think. :)

[lervag]

I've just done the first step of the refactoring. The latest commit replaces 1077 lines with 399 lines. Not too bad... :)

[lervag]

(Let's just hope I didn't break anything... I'm probably moving too fast!)

[clason]

I'm sure someone will let you know when something breaks ;)

(Still working so far :))

[lervag]

Did more refactoring now. And now I'm happy with it, so I'll resolve this issue next thing when I get the time!