| 1 |
NAME |
| 2 |
Vi::QuickFix - Support for vim's QuickFix mode |
| 3 |
|
| 4 |
SYNOPSIS |
| 5 |
use Vi::QuickFix; |
| 6 |
use Vi::QuickFix <errorfile>; |
| 7 |
use Vi::QuickFix <options>; |
| 8 |
use Vi::QuickFix <options> <errorfile>; |
| 9 |
|
| 10 |
where "<options>" is one or more of "silent", "sig", "tie", and "fork". |
| 11 |
|
| 12 |
DESCRIPTION |
| 13 |
When "Vi::QuickFix" is active, Perl logs errors and warnings to an |
| 14 |
*error file* named, by default, "errors.err". This file is picked up |
| 15 |
when you type ":cf" in a running vim editor. Vim will jump to the |
| 16 |
location of the first error recorded in the error file. ":cn" takes you |
| 17 |
to the next error, switching files if necessary. There are more QuickFix |
| 18 |
commands in vim. Type ":help quickfix" for a description. |
| 19 |
|
| 20 |
To activate QuickFix support for a Perl source, add |
| 21 |
|
| 22 |
use Vi::QuickFix; |
| 23 |
|
| 24 |
or, specifying an error file |
| 25 |
|
| 26 |
use Vi::QuickFix '/my/errorfile'; |
| 27 |
|
| 28 |
early in the main program, before other "use" statements. |
| 29 |
|
| 30 |
To leave the program file unaltered, Vi::QuickFix can be invoked from |
| 31 |
the command line as |
| 32 |
|
| 33 |
perl -MVi::QuickFix program |
| 34 |
or |
| 35 |
perl -MVi::QuickFix=/my/errorfile program |
| 36 |
|
| 37 |
"Vi::QuickFix" is meant to be used as a development tool, not to remain |
| 38 |
in a distributed product. When the program ends, a warning is issued, |
| 39 |
indicating that "Vi::QuickFix" was active. This has the side effect that |
| 40 |
there is always an entry in the error file which points to the source |
| 41 |
file where "Vi::QuickFix" was invoked, normally the main program. ":cf" |
| 42 |
will take you there when other error entries don't point it elsewhere. |
| 43 |
Use the "silent" option with "Vi::QuickFix" to suppress this warning. |
| 44 |
|
| 45 |
When the error file cannot be opened, a warning is issued and the |
| 46 |
program continues running without QuickFix support. If the error file is |
| 47 |
empty after the run (can only happen with "silent"), it is removed. |
| 48 |
|
| 49 |
ENVIRONMENT |
| 50 |
"Vi::QuickFix" recognizes the environment variable |
| 51 |
"VI_QUICKFIX_SOURCEFILE" |
| 52 |
|
| 53 |
When Perl reads its source from "STDIN", error messages and warnings |
| 54 |
will contain the string "-" where the source file name would otherwise |
| 55 |
appear. The environment variable "VI_QUICKFIX_SOURCEFILE" can be set to |
| 56 |
a filename, which will replace "-" in those messages. If no "-" appears |
| 57 |
as a file name, setting the variable has no effect. |
| 58 |
|
| 59 |
This somewhat peculiar behavior can be useful if you call perl (with |
| 60 |
"Vi::QuickFix") from within a vim run, as in ":w !perl -MVi::QickFix". |
| 61 |
When you set the environment variable "VI_QUICKFIX_SOURCEFILE" to the |
| 62 |
name of the file you are editing, this fools vim into doing the right |
| 63 |
thing when it encounters the modified messages. |
| 64 |
|
| 65 |
This is an experimental feature, the behavior may change in future |
| 66 |
releases. |
| 67 |
|
| 68 |
USAGE |
| 69 |
The module file .../Vi/QuickFix.pm can also be called as an executable. |
| 70 |
In that mode, it behaves basically like the "cat" command, but also |
| 71 |
monitors the stream and logs Perl warnings and error messages to the |
| 72 |
error file. The error file can be set through the switches "-f" or "-q". |
| 73 |
No warning about QuickFix activity is issued in this mode. |
| 74 |
|
| 75 |
Called with -v, it prints the version and exits. |
| 76 |
|
| 77 |
IMPLEMENTATION |
| 78 |
For a debugging tool, an implementation note is in order. |
| 79 |
|
| 80 |
Perl offers three obvious ways to watch and capture its error output. |
| 81 |
One is through the (pseudo-) signal handlers $SIG{__WARN__} and |
| 82 |
$SIG{__DIE__}. The other is through "tie"-ing the "STDERR" file handle. |
| 83 |
A third method involves forking a child process for the capturing and |
| 84 |
redirect "STDERR" to there. |
| 85 |
|
| 86 |
"Vi::QuickFix" can use these three methods to create the error file. As |
| 87 |
it turns out, the ability to tie "STDERR" is relatively new with Perl, |
| 88 |
as of version 5.8.1. With Versions 5.8.0 and earlier, a number of |
| 89 |
internal errors and warnings don't respect tie, so this method cannot be |
| 90 |
used. With Perl versions ealier than 5.8.1, "Vi::QuickFix" uses %SIG |
| 91 |
handlers to catch messages. With newer versions, "Vi::Quickfix" ties |
| 92 |
"STDERR" so that it (additionally) writes to the error file. The forking |
| 93 |
method can be used with any version of Perl. |
| 94 |
|
| 95 |
A specific method can be requested through the options "sig", "tie" and |
| 96 |
"fork", as in |
| 97 |
|
| 98 |
use Vi::QuickFix qw(sig); |
| 99 |
use Vi::QuickFix qw(tie); |
| 100 |
use Vi::QuickFix qw(fork); |
| 101 |
|
| 102 |
The forking method appears to work well in practice, but a race |
| 103 |
condition exists that intermittently leads to failing tests. It is not |
| 104 |
tested in the standard test suite and must be considered experimental. |
| 105 |
|
| 106 |
Requesting "tie" with a Perl version that can't handle it is a fatal |
| 107 |
error, so the only option that does anything useful is "sig" with a |
| 108 |
new-ish Perl. It can be useful when "tie"-ing "STDERR" conflicts with |
| 109 |
the surrounding code. |
| 110 |
|
| 111 |
CONFLICTS |
| 112 |
Similar conflicts can occur with the "sig" method as well, and it can |
| 113 |
happen in two ways. Either "Vi::QuickFix" already finds a resource (a |
| 114 |
%SIG handler or a tie on "STDERR") occupied at "use" time, or the |
| 115 |
surrounding code commandeers the resource after the fact. |
| 116 |
|
| 117 |
However, if "STDERR" is already tied when "Vi::QuickFix" is "use"d, it |
| 118 |
cannot employ the "tie" method, and by default reverts to "sig". If the |
| 119 |
"tie" method is specifically requested, a fatal error results. |
| 120 |
|
| 121 |
If the "sig" method finds one of the handlers ("__WARN__" and "__DIE__") |
| 122 |
already occupied, it chains to the previous handler after doing its |
| 123 |
thing, so that is not considered an obstacle. "Chaining" file ties is |
| 124 |
harder, and has not been attempted. |
| 125 |
|
| 126 |
If "Vi::QuickFix" is already active, the surrounding code may later |
| 127 |
occupy a resource it is using. There is little that can be done when |
| 128 |
that happens, except issue a warning which is also logged to the error |
| 129 |
file. This can help in finding the source of the conflict. In "silent" |
| 130 |
mode, no such warning is given. |
| 131 |
|
| 132 |
The warning is triggered when the corresponding resource is overwritten, |
| 133 |
except when the overwriting program keeps a copy of it. It is then |
| 134 |
assumed that the program will keep it functioning. Since we're still |
| 135 |
talking implementation -- it is actually triggered through a DESTROY |
| 136 |
method when the corresponding object goes out of scope. %SIG handlers |
| 137 |
are code objects just for this reason. |
| 138 |
|
| 139 |
VERSION |
| 140 |
This document pertains to "Vi::Quickfix" version 1.134 |
| 141 |
|
| 142 |
BUGS |
| 143 |
"no Vi::QuickFix" has no effect |
| 144 |
|
| 145 |
AUTHOR |
| 146 |
Anno Siegel |
| 147 |
CPAN ID: ANNO |
| 148 |
[email protected] |
| 149 |
http://www.tu-berlin.de/~siegel |
| 150 |
|
| 151 |
COPYRIGHT |
| 152 |
This program is free software; you can redistribute it and/or modify it |
| 153 |
under the same terms as Perl itself. |
| 154 |
|
| 155 |
The full text of the license can be found in the LICENSE file included |
| 156 |
with this module. |
| 157 |
|
| 158 |
SEE ALSO |
| 159 |
perl(1), vim(1). |
| 160 |
|