Debian Codegraph @

README

raw
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