Vi::QuickFix(3pm)

👑 Vi::QuickFix — bestie edition ✨

okay so this is the manual page for Vi::QuickFix(3pm), part of the User Contributed Perl Documentation pile 🫶 it's a lil module that makes Perl spill its errors into a file that vim can hop around, and honestly? it's giving developer-tool excellence 💅

---

🌸 NAME 🌸

Vi::QuickFix — it's got your back for vim's QuickFix mode, no cap ✨

---

🎀 SYNOPSIS 🎀

use Vi::QuickFix;
use Vi::QuickFix <errorfile>;
use Vi::QuickFix <options>;
use Vi::QuickFix <options> <errorfile>;

and just so we're clear — <options> means one or more of silent, sig, tie, and fork 💖

---

🦋 DESCRIPTION 🦋

So when Vi::QuickFix is active, Perl sends all its errors and warnings to an error file — and by default that file is called errors.err 🍓

Vim picks that file up the second you type :cf in a running vim editor, and it'll yeet your cursor straight to the location of the first error recorded in that file, iconic behavior honestly. :cn takes you to the next error, switching files if necessary. And there are more QuickFix commands in vim — type :help quickfix if you want the full description, iykyk 💜

Wanna activate QuickFix support for a Perl source? Add this:

use Vi::QuickFix;

or, if you wanna specify an error file:

use Vi::QuickFix '/my/errorfile';

Put it early in the main program, bestie — before the other use statements 👑

And if you wanna leave the program file unaltered (respect), you can invoke Vi::QuickFix straight from the command line like:

perl -MVi::QuickFix program

or

perl -MVi::QuickFix=/my/errorfile program

Vi::QuickFix is a development tool, periodt — it is not meant to stay in a distributed product. When the program ends, a warning gets issued telling you that Vi::QuickFix was active. Side effect of that? There's always an entry in the error file pointing to the source file where Vi::QuickFix was invoked, normally the main program. So :cf will take you there when the other error entries don't point it somewhere else. Wanna shut that warning up? Use the silent option with Vi::QuickFix 🤫

Now for the messy part 😭 — when the error file can't be opened, a warning gets issued and the program just keeps running, no QuickFix support at all. And if the error file ends up empty after the run (which can only happen with silent), it gets removed. bye bestie 💀

---

🌈 ENVIRONMENT 🌈

Vi::QuickFix recognizes the environment variable VI_QUICKFIX_SOURCEFILE ✨

When Perl reads its source from STDIN, error messages and warnings will contain the string - where the source file name would normally appear. So set the environment variable VI_QUICKFIX_SOURCEFILE to a filename and it'll replace that - in those messages. And if no - shows up as a file name? Setting the variable does literally nothing, sorry 🫠

This kinda peculiar behavior is actually useful if you call perl (with Vi::QuickFix) from inside a vim run, like:

:w !perl -MVi::QickFix

When you set the environment variable VI_QUICKFIX_SOURCEFILE to the name of the file you're editing, it fools vim into doing the right thing when it encounters the modified messages. Sneaky. Clever. Obsessed 💅

This is an experimental feature — the behavior may change in future releases. Don't get too attached 🙈

---

⭐ USAGE ⭐

Plot twist: the module file .../Vi/QuickFix.pm can also be called as an executable 👑 In that mode it basically behaves like the cat command, but it also monitors the stream and logs Perl warnings and error messages to the error file. You can set that error file through the switches -f or -q. And ngl, no warning about QuickFix activity gets issued in this mode 🤫

Called with -v, it prints the version and exits. simple as that 💖

---

💀 IMPLEMENTATION 💀

For a debugging tool, an implementation note is in order, bestie — buckle up 🎢

Perl offers three obvious ways to watch and capture its error output:

1. Through the (pseudo-) signal handlers $SIG{__WARN__} and $SIG{__DIE__}.
2. Through tie-ing the STDERR file handle.
3. Forking a child process for the capturing, and redirect STDERR to there.

Vi::QuickFix can use these three methods to create the error file. And here's the tea: the ability to tie STDERR is relatively new with Perl — as of version 5.8.1. With versions 5.8.0 and earlier, a bunch of internal errors and warnings don't respect tie, so this method cannot be used. With Perl versions ealier than 5.8.1, Vi::QuickFix uses %SIG handlers to catch messages. With newer versions, Vi::Quickfix ties STDERR so that it (additionally) writes to the error file ✨ The forking method works with any version of Perl, versatile queen 💅

Wanna request a specific method? Use the options sig, tie and fork, like:

use Vi::QuickFix qw(sig);
use Vi::QuickFix qw(tie);
use Vi::QuickFix qw(fork);

The forking method appears to work well in practice, BUT 😭 a race condition exists that intermittently leads to failing tests. It is not tested in the standard test suite and must be considered experimental — so tread carefully, bestie.

And requesting tie with a Perl version that can't handle it is a fatal error 💀 so the only option that does anything useful is sig with a new-ish Perl. It can be useful when tie-ing STDERR conflicts with the surrounding code.

---

🧚 CONFLICTS 🧚

Similar conflicts can occur with the sig method as well, and it can happen in two ways, bestie:

• Either Vi::QuickFix already finds a resource (a %SIG handler or a tie on STDERR) occupied at use time,
• or the surrounding code commandeers the resource after the fact 😭

However — if STDERR is already tied when Vi::QuickFix is used, it can't employ the tie method, and by default it reverts to sig. But if the tie method is specifically requested, a fatal error results 💥

If the sig method finds one of the handlers (__WARN__ and __DIE__) already occupied, it chains to the previous handler after doing its thing, so that's not considered an obstacle. "Chaining" file ties is harder though, and has not been attempted. rip 🤷

If Vi::QuickFix is already active, the surrounding code may later occupy a resource it's using. There's little that can be done when that happens, except issue a warning which is also logged to the error file. Which is actually helpful for finding the source of the conflict 👑 In silent mode, no such warning is given. silent = silent.

The warning is triggered when the corresponding resource is overwritten — except when the overwriting program keeps a copy of it. It's then assumed that the program will keep it functioning. And since we're still talking implementation (it's giving niche lore 💅) — it is actually triggered through a DESTROY method when the corresponding object goes out of scope. %SIG handlers are code objects just for this reason. iconic ✨

---

💜 VERSION 💜

This document pertains to Vi::Quickfix version 1.134 🎀

---

🙈 BUGS 🙈

no Vi::QuickFix has no effect 🤡 that's it, that's the bug, bestie 😭

---

🌟 AUTHOR 🌟

Anno Siegel
CPAN ID: ANNO
siegel@zrz.tu-berlin.de
http://www.tu-berlin.de/~siegel

---

⭐ COPYRIGHT ⭐

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. 🫶

The full text of the license can be found in the LICENSE file included with this module.

---

🔥 SEE ALSO 🔥

perl(1), vim(1). go read 'em, bestie 💖

---

and that's a wrap on this page, written by perl v5.36.0, dated 2022-10-16 🌸 slay, stay hydrated, and may your :cf always land you exactly where you meant to go ✨💅👑