1 #LyX 1.5.0svn created this file. For more info see http://www.lyx.org/
5 \textclass literate-article
10 \paperfontsize default
17 \paperorientation portrait
20 \paragraph_separation indent
22 \quotes_language english
25 \paperpagestyle default
26 \tracking_changes false
34 LyX and Literate Programming
43 edmar-w-jr@technologist.com
47 \begin_layout Standard
49 Modified by Bernard Michael Hurley bernardh@westherts.ac.uk ---- Don't blame
50 Edmar for any errors that have crept in!
58 \begin_layout Abstract
64 This example program is provided for educational use only.
65 The functionality in this C program has been superceded by the equivalent
68 examples/listerrors.lyx
70 which should be installed in the LyX scripts directory.
79 \begin_layout Standard
90 \begin_layout Standard
93 \begin_inset LatexCommand \tableofcontents{}
100 \begin_layout Section
105 \begin_layout Standard
107 After typesetting a document, LyX scans the LaTeX log file looking for errors.
108 For each error found, the line number is obtained and a error box is displayed
109 in the LyX screen at that position.
112 \begin_layout Standard
114 To use this feature to view compilation errors while working with literate
115 documents, we need a program that filters the compilation errors and puts
116 them in a format suitable for LyX reading it.
120 \begin_layout Standard
122 In this document we present a filter that recognizes compilation error messages
123 from noweb, gnu C, and the IBM C compiler (xlc).
126 \begin_layout Standard
128 The filter is required to read from standard input, parse for error messages
129 and copy the error messages to the standard output.
130 During the output process, the filter must present the error messages in
131 a format that LyX can interpret, currently, the LaTeX error message format.
132 Of course, nothing will prevent future LyX releases from being able to
133 read other formats as well (like gcc error messages for example).
134 This mechanism is necessary to fully explore the literate programming tool's
138 \begin_layout Section
149 main (int argc, char **argv)
155 switch (argv[1][0]) {
159 <<Scan input for noweb error messages>>
165 <<Scan input for xlc error messages>>
171 <<AIX system using both noweb and xlc>>
179 <<Solaris and Linux systems using both noweb and gcc>>
187 <<Scan input for gcc error messages>>
195 <<Scan input for gcc error messages>>
206 <<Function prototypes>>=
208 int main (int argc, char **argv);
213 \begin_layout Section
218 \begin_layout Standard
220 We resort to some global variables to allow access from several different
222 These are the buffer and related pointers used during the parse of the
228 <<Global variables>>=
230 char buffer[200][200];
241 \begin_layout Section
246 \begin_layout Standard
248 The output format mimics the TeX error messages format.
249 This function prints a number of lines residing in the global variable
254 , a program name and line number.
255 There is no special requirement on the input strings, they can be anything.
259 \begin_layout Standard
261 This function has been slightly changed from EW's original to make scanning
262 a bit easier with LaTeX::scanLogFile().
263 The test has been added because LyX can crash if empty lines are allowed
264 here --- I can't figure out why! --- BMH
278 output_error (int buf_size, int error_line, char *tool)
286 fprintf(stdout, "! Build Error: ==> %s ==>
290 fprintf(stdout, " ...
300 for (i=0; i<buf_size; i++)
302 if (strlen(buffer[i]) != 0)
304 fprintf(stdout, "%s", buffer[i]);
319 <<Function prototypes>>=
321 void output_error (int buf_size, int error_line, char *tool);
326 \begin_layout Section
328 Functions Implementation
331 \begin_layout Standard
333 Both noweave and notangle routines, always output one single line for each
334 error found, thus to scan the buffer for noweb error messages is enough
335 to exam one input line at a time.
336 Note that the noweb software does not provide a line error number, so all
337 errors boxes related to noweb messages will be displayed at the beginning
343 <<Scan input for noweb error messages>>=
349 while (fgets(buffer[0], 200, stdin)) {
353 output_error(1, err_line, "noweb");
362 \begin_layout Standard
364 The examination itself is very inefficient.
365 Unfortunately noweb doesn't have any characteristic that would help to
366 identify one of its error messages.
367 The solution is to collect all possible output messages in an array of
368 strings, and turn the examination process into a linear search in this
374 <<Global variables>>=
376 char *noweb_msgs[] = {
378 "couldn't open file",
380 "couldn't open temporary file",
382 "error writing temporary file",
388 "Bad format sequence",
390 "Can't open output file",
392 "Can't open temporary file",
394 "Capacity exceeded:",
396 "Ignoring unknown option -",
398 "This can't happen:",
400 "non-numeric line number in"
406 char *noweb_msgs_mimic_gcc[] = {
408 ": unescaped << in documentation chunk"
415 \begin_layout Standard
417 A noweb error message can be any string that contains a matching pair of
421 > >, or any of the above strings
430 noweb_try (int buf_line)
440 b = buffer[buf_line];
446 for (i=0; i<1; i++) {
448 s = (char *)strstr (b, noweb_msgs_mimic_gcc[i]);
452 t = (char *)strchr(buffer[buf_line], ':');
454 err_line = atoi(t+1);
456 t = buffer[buf_line];
460 while (*(t++) = *(s++));
468 s = (char *)strstr(b, "<<");
472 s = (char *)strstr(s+2, ">>");
482 for (i = 0; i < 12; ++i) {
484 s = (char *)strstr (b, noweb_msgs[i]);
505 <<Function prototypes>>=
507 int noweb_try (int buf_line);
512 \begin_layout Standard
514 The xlc compiler always outputs one single line for each error found, thus
515 to scan the buffer for xlc error messages it is enough to exam one input
521 <<Scan input for xlc error messages>>=
527 while (fgets(buffer[last_buf_line], 200, stdin)) {
531 output_error(1, err_line, "xlc");
540 \begin_layout Standard
542 A xlc error message is easy to identify.
543 Every error message starts with a quoted string with no spaces, a comma,
545 \begin_inset Quotes eld
549 \begin_inset Quotes erd
552 , a space, and some variable text.
553 The following routine tests if a given buffer line matches this criteria:
562 xlc_try (int buf_line)
570 t = buffer[buf_line];
574 while (*s != '"' && *s != ' ' && *s != '
580 if (*t != '"' || *s != '"' || strncmp(s+1, ", line ", 7) != 0)
597 <<Function prototypes>>=
599 int xlc_try (int buf_line);
604 \begin_layout Standard
606 The gcc compiler error messages are more complicated to scan.
607 Each error can span more than one line in the buffer.
608 The good news is that every buffer line on each error has the same pattern,
609 and share the same line number.
610 Thus the strategy will be to accumulate lines in the buffer while the reported
611 line number is still the same.
612 At the time they differ, all the accumulated lines, except the last one,
613 will belong to one single error message, which now can be output-ed to
617 \begin_layout Standard
619 Every gcc error message contains a string with no space followed by a
620 \begin_inset Quotes eld
624 \begin_inset Quotes eld
628 If the next character is a space, then this line is a header of a error
629 message and the next line will detail the line number of the source code
630 where the error was found.
631 Otherwise, the next thing is a integer number followed by another
632 \begin_inset Quotes eld
636 \begin_inset Quotes eld
644 <<Scan input for gcc error messages>>=
654 while (fgets(buffer[last_buf_line], 200, stdin)) {
656 /****** Skip lines until I find an error */
658 s = (char *)strpbrk(buffer[last_buf_line], " :");
660 if (s == NULL || *s == ' ')
662 continue; /* No gcc error found here */
666 <<gcc error message criteria is to find a "...:999:" or a "...: ">>
668 /****** OK It is an error message, get line number */
670 err_line = atoi(s+1);
672 if (last_err_line == 0 || last_err_line == err_line) {
674 last_err_line = err_line;
676 continue; /* It's either a header or a continuation, don't output
681 /****** Completed the scan of one error message, output it to LyX
688 } while (fgets(buffer[last_buf_line], 200, stdin));
692 /****** EOF completes the scan of whatever was being scanned */
703 <<gcc error message criteria is to find a "...:999:" or a "...: ">>=
705 /****** Search first ":" in the error number */
707 s = (char *)strpbrk(buffer[last_buf_line], " :");
711 if (s == NULL || *s == ' ')
713 <<No gcc error found here, but it might terminate the scanning of a previous
716 /****** Search second ":" in the error number */
718 t = (char *)strpbrk(s+1, " :");
720 if (t == NULL || *t == ' ')
722 <<No gcc error found here, but it might terminate the scanning of a previous
725 /****** Verify if is all digits between ":" */
727 if (t != s+1+strspn(s+1, "0123456789"))
729 <<No gcc error found here, but it might terminate the scanning of a previous
737 <<No gcc error found here, but it might terminate the scanning of a previous
753 \begin_layout Standard
755 As we mentioned, when the scan of one gcc error message is completed everything
756 in the buffer except the last line is one single error message.
757 But if the scan terminates with a EOF or through finding one line that
758 does not match the gcc error message criteria, then there is no
759 \begin_inset Quotes eld
763 \begin_inset Quotes erd
766 in the buffer to be concerned with.
767 In those cases we empty the buffer completely.
776 discharge_buffer (int save_last)
780 if (last_err_line != 0) {
782 clean_gcc_messages();
784 if (save_last != 0) {
786 output_error(last_buf_line-1, last_err_line, "gcc");
788 strcpy (buffer[0], buffer[last_buf_line-1]);
790 last_err_line = err_line;
798 clean_gcc_messages();
800 output_error(last_buf_line-1, last_err_line, "gcc");
817 <<Function prototypes>>=
819 void discharge_buffer (int save_last);
824 \begin_layout Standard
827 \begin_inset Quotes eld
831 \begin_inset Quotes erd
834 superfluous information from gcc messages, namely the name of the noweb
835 file and the line number of the Error.
839 \begin_layout Standard
842 For instance, some way of distinguishing between gcc Errors and Warnings
857 clean_gcc_messages ()
867 int search_len = sprintf(search, ".nw:%d:", last_err_line);
871 for (index = 0; index < last_buf_line-1; index++) {
873 tail = (char *)strstr (buffer[index], search);
877 tail = (char *) strstr (buffer[index], ".nw:");
893 head = buffer[index];
895 while (*(head++) = *(tail++));
908 <<Function prototypes>>=
910 void clean_gcc_messages ();
915 \begin_layout Standard
917 To combine the scan of noweb error messages and xlc error messages is very
919 We just try each one for every input line:
924 <<AIX system using both noweb and xlc>>=
930 while (fgets(buffer[0], 200, stdin)) {
934 output_error(1, err_line, "noweb");
938 output_error(1, err_line, "xlc");
947 \begin_layout Standard
949 To combine the scan of noweb error messages and gcc error messages is simple
950 if we realize that it is not possible to find a noweb error message in
951 the middle of a gcc error message.
952 So we just repeat the gcc procedure and test for noweb error messages in
953 the beginning of the scan:
958 <<Solaris and Linux systems using both noweb and gcc>>=
968 while (fgets(buffer[last_buf_line], 200, stdin)) {
970 /****** Skip lines until I find an error */
972 if (last_buf_line == 0 && noweb_try(0)) {
974 output_error(1, err_line, "noweb");
980 s = (char *)strpbrk(buffer[last_buf_line], " :");
982 if (s == NULL || *s == ' ')
984 continue; /* No gcc error found here */
988 <<gcc error message criteria is to find a "...:999:" or a "...: ">>
990 /****** OK It is an error, get line number */
992 err_line = atoi(s+1);
994 if (last_err_line == 0 || last_err_line == err_line) {
996 last_err_line = err_line;
998 continue; /* It's either a header or a continuation, don't output
1003 /****** Completed the scan of one error message, output it to LyX
1006 discharge_buffer(1);
1010 } while (fgets(buffer[last_buf_line], 200, stdin));
1014 /****** EOF completes the scan of whatever was being scanned */
1016 discharge_buffer(0);
1023 \begin_layout Section
1025 Wrapping the code into a file
1034 #include <strings.h>
1038 <<Global variables>>
1040 <<Function prototypes>>
1047 \begin_layout Standard
1049 To build this program, we want to add the
1050 \begin_inset Quotes eld
1054 \begin_inset Quotes erd
1057 option in the tangle command to force gdb to load the file
1066 In accordance with this, we pass the
1067 \begin_inset Quotes eld
1071 \begin_inset Quotes erd
1083 if [ -z "$NOWEB_SOURCE" ]; then NOWEB_SOURCE=Literate.nw; fi
1085 notangle -L -Rlisterrors.c ${NOWEB_SOURCE} > listerrors.c
1087 gcc -g -o listerrors listerrors.c
1092 \begin_layout Standard
1094 This project can be tangled and compiled from LyX if you set
1100 to call a generic script that always extracts a scrap named
1105 Here is a example of such generic script:
1108 \begin_layout LyX-Code
1112 notangle -Rbuild-script $1 | env NOWEB_SOURCE=$1 sh
1115 \begin_layout LyX-Code