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).