add-next-line(2)

NAME

add-next-line - Define the searching behavior of command output

SYNOPSIS

n add-next-line "buffer-name" [ "string" ]

DESCRIPTION

add-next-line is used to set up the next-line functionality which is used by the get-next-line(2) command. The next-line feature is aimed at giving the user easy access to file locations which are stored in another buffer. This buffer may typically be the output from the grep(1) command or a compiler (e.g. cc(1)) and needs to contain the file name and line number of the required location.

As long as the format of the buffer is consistent and there is a maximum of one location per line, the next-line feature can be successfully configured.

The first argument, "buffer-name", gives the name the aforementioned buffer, this is "*grep*" for the grep(3) command etc. There is no limit on the number of next-line formats, nor on the number of add-next-line strings which are given. While there is no real need to initialize each new type, it is advised that the first add-next-line is called with a numerical argument of zero, e.g.:

0 add-next-line "*grep*" 
add-next-line "*grep*" "....." 

This tells MicroEmacs to reinitialize the type by freeing off any strings currently stored, note that the "string" argument is not used in this case. Resetting the next-line type safe guards against duplicate strings being added to it, a common problem if MicroEmacs is reinitialized.

Following is a typical output from grep:

foo.c: 45:      printf("hello world\n") ; 
foo.c: 46:      printf("hello again\n") ; 

If we replace the file name with "%f" and the line number with "%l", this becomes:

%f: %l:      printf("hello world\n") ; 

get-next-line works on a left to right basis, as soon as it has enough information from the line it does not need to continue. Therefore the previous example can be reduced to just "%f: %l:". This is the string argument that should be given for the above example, i.e.:

add-next-line "*grep*" "%f: %l:" 

get-next-line takes the given string and replaces the "%f" with $file-template(5) and the "%l" with the $line-template(5) and then uses the resultant string as a regular expression search string to find the next location. Crudely these could be set to "foo.c" and "45" respectively to find the first example, but this would fail to find any other. As a result the templates are usually magic search strings which will match any file and line number.

Similarly, following is an example output of the gcc(1) compiler:

basic.c:522: warning: `jj' might be used uninitialized in this command 
display.c:833: warning: implicit declaration of function `ScreenPutChar' 

In this case the add-next-line given needs to be:

add-next-line "*compile*" "%f:%l:" 

If a negative numerical argument is given to add-next-line the given 'next-line' is ignored, this can be useful when some warnings are to be ignored. For example a common warning from gcc is given when a variable might be used uninitialized, given as follows:

bind.c:578: warning: `ssc' might be used uninitialized in this function 

These warnings can be ignored using the following:

-1 add-next-line "*compile*" ... 
    ... "%f:%l: warning: `.*' might be used uninitialized in this function" 

Some versions of grep(1) give the file name first and then the lines on the following lines. This is not a major problem as get-next-line remembers the last file name. The only problem occurs when skipping some parts of the list at which point the last file name parsed may not be the current file. Following is an example output of such a grep and the setup required:

File foo.c: 
Line 45:      printf("hello world\n") ; 
Line 46:      printf("hello again\n") ; 

The configuration to locate the lines is defined as:

0 add-next-line "*grep*" 
add-next-line "*grep*" "File %f:" 
add-next-line "*grep*" "Line %l:" 

NOTES

The reinitialize command format of this command changed in January 2001, the format changed from:

add-next-line "*grep*" "" 

SEE ALSO

$file-template(5), $line-template(5), cc(1), compile(3), get-next-line(2), grep(1), grep(3).

(c) Copyright JASSPA 2009
Last Modified: 2009/08/29
Generated On: 2009/10/12