| | 230 | POD comments are filtered out from the input. This is implemented in [source:/trunk/compilers/pirc/src/hdocprep.l#L287 lines 287 to 301]). |
| | 231 | Note that [source:/trunk/compilers/pirc/src/hdocprep.l#L287 line 287] is very important: it matches a "=cut" directive (which ends a POD comment) in the INITIAL state (so, when no previous POD comment was seen yet). If this pattern wouldn't be matched in the INITIAL state, the "=cut" directive would actually activate the POD state. This is because "=cut" starts with a "=", which is the first character of a POD directive ([source:/trunk/compilers/pirc/src/hdocprep.l#L289 see line 289]). |
| | 232 | |
| | 233 | ==== include directives ==== |
| | 234 | |
| | 235 | The {{{.include}}} directive is logically a macro expansion directive. It takes one argument, which is the name of a file. If the {{{.include}}} directive is encountered, the lexer switches to the specified file, and starts reading from that file. Once the end of the file has been reached, the lexer switches back to the original file. |
| | 236 | |
| | 237 | The {{{.include}}} directive is implemented in the heredoc preprocessor. This is necessary in order to be able to use heredoc strings in the included file. If the directive would have been implemented in the normal PIR lexer (that implements macro expansion), then the heredoc preprocessor would have to be invoked first on the included file. |
| | 238 | |
| | 239 | Once the {{{.include}}} directive is read, the lexer switches state from INITIAL to INCLUDE ([source:/trunk/compilers/pirc/src/hdocprep.l#L479 line 479]). This is done using the built-in state stack in the Flex-generated lexer. The INCLUDE state is pushed onto the state stack, and immediately activated. (Once the state is popped off, the lexer switches to the state that's then the new top-of-stack. Since an included file can include other files, a stack is used to keep track of this. Four different input patterns are distinguished: |
| | 240 | |
| | 241 | 1. whitespace ([source:/trunk/compilers/pirc/src/hdocprep.l#L483 line 483]). Whitespace is skipped. |
| | 242 | |
| | 243 | 2. a quoted string, which is the name of the file to be included ([source:/trunk/compilers/pirc/src/hdocprep.l#L485 line 485]). Once the quoted string is stripped from its quotes, the file is located and the lexer will start processing that file. |
| | 244 | |
| | 245 | 3. end of line ([source:/trunk/compilers/pirc/src/hdocprep.l#L528 line 528]). This would be the end-of-line after the quoted string that was included. Once this is encountered, the included file has already been completely processed. Therefore, the lexer's state is popped off the lexer state stack. |
| | 246 | |
| | 247 | 4. any other character ([source:/trunk/compilers/pirc/src/hdocprep.l#L532 line 532]), resulting in an error message. |
| | 248 | |
