home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 5 Edit / 05-Edit.zip / vim53os2.zip / vim-5.3 / doc / quickfix.txt < prev    next >
Text File  |  1998-08-30  |  11KB  |  250 lines
  1. *quickfix.txt*  For Vim version 5.3.  Last modification: 1998 Jun 25
  2.  
  3.  
  4.           VIM REFERENCE MANUAL    by Bram Moolenaar
  5.  
  6.  
  7. {Vi does not have any of these commands}
  8.  
  9. The quickfix commands are not available when the |+quickfix| feature was
  10. disabled at compile time.
  11.  
  12.  
  13. Using the QuickFix mode                    *quickfix*
  14.  
  15. Vim has a special mode to speedup the edit-compile-edit cycle.  This is
  16. inspired by the quickfix option of the Manx's Aztec C compiler on the Amiga.
  17. The idea is to save the error messages from the compiler in a file and use
  18. Vim to jump to the errors one by one.  You can then examine each problem and
  19. fix it, without having to remember all the error messages.
  20.  
  21. If you are using Manx's Aztec C compiler on the Amiga you should do the
  22. following:
  23. - Set the CCEDIT environment variable with the command
  24.     mset "CCEDIT=vim -q"
  25. - Compile with the -qf option.  If the compiler finds any errors, Vim is
  26.   started and the cursor is positioned on the first error.  The error message
  27.   will be displayed on the last line.  You can go to other errors with the
  28.   commands mentioned below.  You can fix the errors and write the file(s).
  29. - If you exit Vim normally the compiler will re-compile the same file.  If you
  30.   exit with the :cq command, the compiler will terminate.  Do this if you
  31.   cannot fix the error, or if another file needs to be compiled first.
  32.  
  33. If you are using another compiler you should save the error messages in a
  34. file and start Vim with "vim -q filename".  An easy way to do this is with
  35. the ":make" command (see below).  The 'errorformat' option should be set to
  36. match the error messages from your compiler (see below).
  37.  
  38. The following commands can be used if you are in QuickFix mode:
  39.  
  40.                             *:cc*
  41. :cc[!] [nr]        Display error [nr].  If [nr] is omitted, the same
  42.             error is displayed again.  Without [!] this doesn't
  43.             work when jumping to another buffer, the current buffer
  44.             has been changed, there is the only window for the
  45.             buffer and both 'hidden' and 'autowrite' are off.
  46.             When jumping to another buffer with [!] any changes to
  47.             the current buffer are lost, unless 'hidden' is set or
  48.             there is another window for this buffer.
  49.  
  50.                             *:cn* *:cnext*
  51. :[count]cn[ext][!]    Display the [count] next error in the list that
  52.             includes a file name.  If there are no file names at
  53.             all, go the the [count] next error.  See |:cc| for
  54.             [!].
  55.  
  56. :[count]cN[ext][!]            *:cp* *:cprevious* *:cN* *:cNext*
  57. :[count]cp[revious][!]    Display the [count] previous error in the list that
  58.             includes a file name.  If there are no file names at
  59.             all, go the the [count] previous error.  See |:cc| for
  60.             [!].
  61.  
  62.                             *:crewind* *:cr*
  63. :cr[ewind][!] [nr]    Display error [nr].  If [nr] is omitted, the FIRST
  64.             error is displayed.  See |:cc|.
  65.  
  66.                             *:clast* *:cla*
  67. :cla[st][!] [nr]    Display error [nr].  If [nr] is omitted, the LAST
  68.             error is displayed.  See |:cc|.
  69.  
  70.                             *:cq* *:cquit*
  71. :cq[uit]        Quit Vim with an error code, so that the compiler
  72.             will not compile the same file again.
  73.  
  74.                             *:cf* *:cfile*
  75. :cf[ile][!] [errorfile]    Read the error file and jump to the first error.
  76.             This is done automatically when Vim is started with
  77.             the -q option.  You can use this command when you
  78.             keep Vim running while compiling.  If you give the
  79.             name of the errorfile, the 'errorfile' option will
  80.             be set to [errorfile].  See |:cc| for [!].
  81.  
  82.                             *:cl* *:clist*
  83. :cl[ist]        List all errors that include a file name.
  84.  
  85. :cl[ist]!        List all errors.
  86.  
  87.                             *:mak* *:make*
  88. :mak[e] [arguments]    1. If the 'autowrite' option is on, write any changed
  89.                buffers
  90.             2. An errorfile name is made from 'makeef'.  If
  91.                'makeef' doesn't contain "##", and a file with this
  92.                name already exists, it is deleted.
  93.             3. The program given with the 'makeprg' option is
  94.                started (default "make") with the optional
  95.                [arguments] and the output is saved in the
  96.                errorfile (for Unix it is also echoed on the
  97.                screen).
  98.             4. The errorfile is then read and the first error is
  99.                jumped to.
  100.             5. The errorfile is deleted.
  101.  
  102.                                 *:gr* *:grep*
  103. :gr[ep] [arguments]    Just like ":make", but use 'grepprg' instead of
  104.             'makeprg' and 'grepformat' instead of 'errorformat'.
  105.             See |grep|.
  106.  
  107. A template for the errorfile name can be set with the 'makeef' option.  If it
  108. includes "##", Vim will replace this with a number to make it a unique name.
  109.  
  110. The format of the file from the Aztec compiler is:
  111.  
  112.     filename>linenumber:columnnumber:errortype:errornumber:errormessage
  113.  
  114.     filename    name of the file in which the error was detected
  115.     linenumber    line number where the error was detected
  116.     columnnumber    column number where the error was detected
  117.     errortype    type of the error, normally a single 'E' or 'W'
  118.     errornumber    number of the error (for lookup in the manual)
  119.     errormessage    description of the error
  120.  
  121.                             *errorformat*
  122. Another compiler is likely to use a different format.  You should set the
  123. 'errorformat' option to a scanf-like string that describes the format.
  124. First, you need to know how scanf works.  Look in the documentation of your
  125. C compiler.  Vim will understand eight conversion characters.  Others are
  126. invalid.
  127.     %f        file name (finds a string)
  128.     %l        line number (finds a number)
  129.     %c        column number (finds a number)
  130.     %t        error type (finds a single character)
  131.     %n        error number (finds a number)
  132.     %m        error message (finds a string)
  133.     %*<conv>    any scanf non-assignable conversion
  134.     %%        the single '%' character
  135.  
  136. Examples:
  137. %f>%l:%c:%t:%n:%m"            for the AztecC.Err file
  138. %f:%l:\ %t%*[^0123456789]%n:\ %m    for Manx/Aztec C error messages
  139.                     (scanf() doesn't understand [0-9])
  140. %f\ %l\ %t%*[^0-9]%n:\ %m        for SAS C
  141. \"%f\"\\,%*[^0-9]%l:\ %m        for generic C compilers
  142. %f:%l:\ %m                for GCC
  143. %f(%l)\ :\ %*[^:]:\ %m            old SCO C compiler (pre-OS5)
  144. %f(%l)\ :\ %t%*[^0-9]%n:\ %m        idem, with error type and number
  145. %f:%l:\ %m,In\ file\ included\ from\ %f:%l:,\^I\^Ifrom\ %f:%l%m
  146.                     for GCC, with some extras
  147.  
  148. Note the backslash in front of a space and double quote.  It is required for
  149. the :set command.  There are two backslashes in front of a comma, one for the
  150. :set command and one to avoid recognizing the comma as a separator of error
  151. formats.
  152.  
  153. The "%f" and "%m" conversions have to detect the end of the string.  They
  154. should be followed by a character that cannot be in the string.  Everything
  155. up to that character is included in the string.  Be careful: "%f%l" will
  156. include everything up to the first '%' in the file name.  If the "%f" or "%m"
  157. is at the end, everything up to the end of the line is included.
  158.  
  159. To be able to detect output from several compilers, several format patterns
  160. may be put in 'errorformat', separated by commas (note: blanks after the comma
  161. are ignored).  The first pattern that has a complete match is used.  If no
  162. match is found, matching parts from the last one will be used, although the
  163. file name is removed and the error message is set to the whole message.  If
  164. there is a pattern that may match output from several compilers (but not in a
  165. right way), put it after one that is more restrictive.  To include a comma in
  166. a pattern precede it with a backslash (you have to type two in a set command).
  167. To include a backslash itself give two backslashes (you have to type four in a
  168. set command).
  169.  
  170. If a line is detected that does not completely match the 'errorformat', the
  171. whole line is put in the error message and the entry is marked "not valid"
  172. These lines are skipped with the ":cn" and ":cp" commands (unless there is
  173. no valid line at all).  You can use ":cl!" to display all the error messages.
  174.  
  175. If the error format does not contain a file name Vim cannot switch to the
  176. correct file.  You will have to do this by hand.
  177.  
  178. If you have a compiler that produces error messages that do not fit in the
  179. format string, you could write a program that translates the error messages
  180. into this format.  You can use this program with the ":make" command by
  181. changing the 'makeprg' option.  For example:
  182. >  :set mp=make\ \\\|&\ error_filter
  183. The backslashes before the pipe character are required to avoid it to be
  184. recognized as a command separator.  The backslash before each space is
  185. required for the set command.
  186.  
  187.                         *quickfix-error-lists*
  188. So far has been assumed that there is only one list of errors.  Actually the
  189. ten last used lists are remembered.  When starting a new list, the previous
  190. ones are automatically kept.  Two commands can be used to access older error
  191. lists.  They set one of the existing error lists as the current one.
  192.  
  193.                         *:colder* *:col*
  194. :col[der] [count]    Go to older error list.  When [count] is given, do
  195.             this [count] times.  When already at the oldest error
  196.             list, an error message is given.
  197.  
  198.                         *:cnewer* *:cnew*
  199. :cnew[er] [count]    Go to newer error list.  When [count] is given, do
  200.             this [count] times.  When already at the newest error
  201.             list, an error message is given.
  202.  
  203. When adding a new error list, it becomes the current list.
  204.  
  205.  
  206.                         *:make_makeprg*
  207. The ":make" command executes the command given with the 'makeprg' option.
  208. This is done by passing the command to the shell given with the 'shell'
  209. option.  This works almost like typing
  210.  
  211.     ":!{makeprg} [arguments] {shellpipe} {errorfile}".
  212.  
  213. {makeprg} is the string given with the 'makeprg' option.  Any command can be
  214. used, not just "make".  Characters '%' and '#' are expanded as usual on a
  215. command-line.  You can use "#<" to insert the current file name without
  216. extension, for example:
  217. >  :set makeprg=make\ #<.o
  218.  
  219. [arguments] is anything that is typed after ":make".
  220. {shellpipe} is the 'shellpipe' option.
  221. {errorfile} is the 'makeef' option, with ## replaced to make it unique.
  222.  
  223. The 'shellpipe' option defaults to ">" for the Amiga, MS-DOS and Win32.  This
  224. means that the output of the compiler is saved in a file and not shown on the
  225. screen directly.  For Unix "| tee" is used.  The compiler output is shown on
  226. the screen and saved in a file the same time.  Depending on the shell used
  227. "|& tee" or "2>&1| tee" is the default, so stderr output will be included.
  228.  
  229. If 'shellpipe' is empty, the {errorfile} part will be omitted.  This is useful
  230. for compilers that write to an errorfile themselves (Manx's Amiga C).
  231.  
  232. There are some restrictions to the Quickfix mode on the Amiga.  The
  233. compiler only writes the first 25 errors to the errorfile (Manx's
  234. documentation does not say how to get more).  If you want to find the others,
  235. you will have to fix a few errors and exit the editor.  After recompiling,
  236. up to 25 remaining errors will be found.
  237.  
  238. On the Amiga, if Vim was started from the compiler, the :sh and some :!
  239. commands will not work, because Vim is then running in the same process as the
  240. compiler and stdin (standard input) will not be interactive.
  241.  
  242. If you insert or delete lines, mostly the correct error location is still
  243. found because hidden marks are used (Manx's Z editor does not do this).
  244. Sometimes, when the mark has been deleted for some reason, the message "line
  245. changed" is shown to warn you that the error location may not be correct.  If
  246. you quit Vim and start again the marks are lost and the error locations may
  247. not be correct anymore.
  248.  
  249.  vim:tw=78:ts=8:sw=8:
  250.