documentation: exact syntax of line directives #24183
Description
This is a follow-up on #22662 and #24143 which implement line directives that permit column specification. While the overall mechanism is now defined and implemented, details of what makes a valid line directive were defined "ad-hoc". We should pin those details down.
The current implementation work as follows:
- Line directives have one of the following forms:
//line :<line>
//line :<line>:<col>
//line <filename>:<line>
//line <filename>:<line>:<col>
/*line :<line>*/
/*line :<line>:<col>*/
/*line <filename>:<line>*/
/*line <filename>:<line>:<col>*/
- Line directives of the
//lineform (using a line comment) must start at the beginning of the line or they are ignored (they are just ordinary line comments). - A line directive specifies the position for the character immediately following the directive: For a
//linecomment, this is the first character of the next line, for a/*linecomment this is the character immediately following the closing*/. - If no filename is given, the filename is empty (
"") for line directives that don't specify a column number (for backward compatibility); and it is the currently used filename (actual filename, or filename specified by previous line directive) if a column number is present. - When reporting (errors), a position p is printed with (a relative) column number if the most recent line directive before p (in the source) specified a column value, or if there is no line directive before p. Otherwise no column value is printed. If a column value is printed, it is relative to the line directive's column if on the same line to which the directive applies (which is the next line for
//linedirectives), otherwise it is the absolute column (i.e., relative to the beginning of the line).
The following details are somewhat arbitrary and these are the ones we should decide upon:
a) A line directive that doesn't contain a : is ignored (considered a regular comment)
b) Column and line numbers are "scanned from the back": first the last :xxx is peeled off from the directive text. If xxx is a valid number > 0, it is accepted. Then the 2nd (now last) :xxx is peeled off and is accepted if xxx is a valid number > 0. The reason for this is to be able to deal with Windows filenames that may contain :. Finally, everything before that : and immediately after the initial line (incl. blank) is considered the filename.
There are several questions here:
-
What should happen if the
xxxare not valid numbers? Should it be an error (to highlight a well-meant but wrong line directive)? What about anxxxof the form123(extra blank)? Currently, the compiler reports an error. Alternatively, the line directive could be silently ignored. -
What should happen with filenames that contain leading and trailing blanks? Currently, the compiler accepts them. Alternatively, the line directive could trim whitespace. (As an aside, gccgo trims whitespace in the front but not in the back for filenames).