NAME¶
Vi::QuickFix - Support for vim's QuickFix mode
SYNOPSIS¶
use Vi::QuickFix;
use Vi::QuickFix <errorfile>;
use Vi::QuickFix <options>;
use Vi::QuickFix <options> <errorfile>;
where "<options>" is one or more of "silent",
"sig", "tie", and "fork".
DESCRIPTION¶
When "Vi::QuickFix" is active, Perl logs errors and warnings to an
error file named, by default, "errors.err". This file is
picked up when you type ":cf" in a running vim editor. Vim will jump
to the location of the first error recorded in the error file. ":cn"
takes you to the next error, switching files if necessary. There are more
QuickFix commands in vim. Type ":help quickfix" for a description.
To activate QuickFix support for a Perl source, add
use Vi::QuickFix;
or, specifying an error file
use Vi::QuickFix '/my/errorfile';
early in the main program, before other "use" statements.
To leave the program file unaltered, Vi::QuickFix can be invoked from the
command line as
perl -MVi::QuickFix program
or
perl -MVi::QuickFix=/my/errorfile program
"Vi::QuickFix" is meant to be used as a development tool, not to
remain in a distributed product. When the program ends, a warning is issued,
indicating that "Vi::QuickFix" was active. This has the side effect
that there is always an entry in the error file which points to the source
file where "Vi::QuickFix" was invoked, normally the main program.
":cf" will take you there when other error entries don't point it
elsewhere. Use the "silent" option with "Vi::QuickFix" to
suppress this warning.
When the error file cannot be opened, a warning is issued and the program
continues running without QuickFix support. If the error file is empty after
the run (can only happen with "silent"), it is removed.
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
otherwise appear. The environment variable "VI_QUICKFIX_SOURCEFILE"
can be set to a filename, which will replace "-" in those messages.
If no "-" appears as a file name, setting the variable has no
effect.
This somewhat peculiar behavior can be useful if you call perl (with
"Vi::QuickFix") from within a vim run, as in ":w !perl
-MVi::QickFix". When you set the environment variable
"VI_QUICKFIX_SOURCEFILE" to the name of the file you are editing,
this fools vim into doing the right thing when it encounters the modified
messages.
This is an experimental feature, the behavior may change in future releases.
USAGE¶
The module file .../Vi/QuickFix.pm can also be called as an executable. In that
mode, it behaves basically like the "cat" command, but also monitors
the stream and logs Perl warnings and error messages to the error file. The
error file can be set through the switches "-f" or "-q".
No warning about QuickFix activity is issued in this mode.
Called with -v, it prints the version and exits.
IMPLEMENTATION¶
For a debugging tool, an implementation note is in order.
Perl offers three obvious ways to watch and capture its error output. One is
through the (pseudo-) signal handlers $SIG{__WARN__} and $SIG{__DIE__}. The
other is through "tie"-ing the "STDERR" file handle. A
third method involves forking a child process for the capturing and redirect
"STDERR" to there.
"Vi::QuickFix" can use these three methods to create the error file.
As it turns out, the ability to tie "STDERR" is relatively new with
Perl, as of version 5.8.1. With Versions 5.8.0 and earlier, a number 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 can be used with any version of Perl.
A specific method can be requested through the options "sig",
"tie" and "fork", as in
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.
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. 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
"use"d, it cannot employ the "tie" method, and by default
reverts to "sig". 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 is not considered an obstacle.
"Chaining" file ties is harder, and has not been attempted.
If "Vi::QuickFix" is already active, the surrounding code may later
occupy a resource it is using. There is little that can be done when that
happens, except issue a warning which is also logged to the error file. This
can help in finding the source of the conflict. In "silent" mode, no
such warning is given.
The warning is triggered when the corresponding resource is overwritten, except
when the overwriting program keeps a copy of it. It is then assumed that the
program will keep it functioning. Since we're still talking implementation --
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.
VERSION¶
This document pertains to "Vi::Quickfix" version 1.134
BUGS¶
"no Vi::QuickFix" has no effect
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).