]>
Commit | Line | Data |
---|---|---|
c63539ff ML |
1 | .. |
2 | Copyright 1988-2022 Free Software Foundation, Inc. | |
3 | This is part of the GCC manual. | |
4 | For copying conditions, see the copyright.rst file. | |
5 | ||
6 | .. _error-handling: | |
7 | ||
8 | Error Handling | |
9 | ************** | |
10 | ||
11 | The GNU Fortran compiler's parser operates by testing each piece of | |
12 | source code against a variety of matchers. In some cases, if these | |
13 | matchers do not match the source code, they will store an error message | |
14 | in a buffer. If the parser later finds a matcher that does correctly | |
15 | match the source code, then the buffered error is discarded. However, | |
16 | if the parser cannot find a match, then the buffered error message is | |
17 | reported to the user. This enables the compiler to provide more | |
18 | meaningful error messages even in the many cases where (erroneous) | |
19 | Fortran syntax is ambiguous due to things like the absence of reserved | |
20 | keywords. | |
21 | ||
22 | As an example of how this works, consider the following line: | |
23 | ||
24 | .. code-block:: c++ | |
25 | ||
26 | IF = 3 | |
27 | ||
28 | Hypothetically, this may get passed to the matcher for an ``IF`` | |
29 | statement. Since this could plausibly be an erroneous ``IF`` | |
30 | statement, the matcher will buffer an error message reporting the | |
31 | absence of an expected :samp:`(` following an ``IF``. Since no | |
32 | matchers reported an error-free match, however, the parser will also try | |
33 | matching this against a variable assignment. When ``IF`` is a valid | |
34 | variable, this will be parsed as an assignment statement, and the error | |
35 | discarded. However, when ``IF`` is not a valid variable, this | |
36 | buffered error message will be reported to the user. | |
37 | ||
38 | The error handling code is implemented in :samp:`error.cc`. Errors are | |
39 | normally entered into the buffer with the ``gfc_error`` function. | |
40 | Warnings go through a similar buffering process, and are entered into | |
41 | the buffer with ``gfc_warning``. There is also a special-purpose | |
42 | function, ``gfc_notify_std``, for things which have an error/warning | |
43 | status that depends on the currently-selected language standard. | |
44 | ||
45 | The ``gfc_error_check`` function checks the buffer for errors, | |
46 | reports the error message to the user if one exists, clears the buffer, | |
47 | and returns a flag to the user indicating whether or not an error | |
48 | existed. To check the state of the buffer without changing its state or | |
49 | reporting the errors, the ``gfc_error_flag_test`` function can be | |
50 | used. The ``gfc_clear_error`` function will clear out any errors in | |
51 | the buffer, without reporting them. The ``gfc_warning_check`` and | |
52 | ``gfc_clear_warning`` functions provide equivalent functionality for | |
53 | the warning buffer. | |
54 | ||
55 | Only one error and one warning can be in the buffers at a time, and | |
56 | buffering another will overwrite the existing one. In cases where one | |
57 | may wish to work on a smaller piece of source code without disturbing an | |
58 | existing error state, the ``gfc_push_error``, ``gfc_pop_error``, | |
59 | and ``gfc_free_error`` mechanism exists to implement a stack for the | |
60 | error buffer. | |
61 | ||
62 | For cases where an error or warning should be reported immediately | |
63 | rather than buffered, the ``gfc_error_now`` and | |
64 | ``gfc_warning_now`` functions can be used. Normally, the compiler | |
65 | will continue attempting to parse the program after an error has | |
66 | occurred, but if this is not appropriate, the ``gfc_fatal_error`` | |
67 | function should be used instead. For errors that are always the result | |
68 | of a bug somewhere in the compiler, the ``gfc_internal_error`` | |
69 | function should be used. | |
70 | ||
71 | The syntax for the strings used to produce the error/warning message in | |
72 | the various error and warning functions is similar to the ``printf`` | |
73 | syntax, with :samp:`%`-escapes to insert variable values. The details, | |
74 | and the allowable codes, are documented in the ``error_print`` | |
3ed1b4ce | 75 | function in :samp:`error.cc`. |