在Antlr 3中生成自定義JavaDoci

Question

我在Antlr 3中爲我的公司實現了一種語法語言。目前，代碼生成時沒有評論。我想編碼評論，以便自定義評論出現。例如：

/** 
* This class does something. 
* @author name 
*/ 
public class GrammarLanguageExample() { 
} 

語法語言的一個例子如下所示：

grammar Example; 

options { 
output=AST; 
} 

@header { 
package com.example; 
} 

@rulecatch { 
// ANTLR does not generate its normal rule try/catch 
catch(RecognitionException e) { 
    throw e; 
} 
} 


insert  : 'INSERT INTO table' 'VALUES'; 
QUOTE  : '"'; 
SPECIALCHAR : '-'|'~'|; 
STRING : QUOTE('a'..'z'|'A'..'Z'|SPECIALCHAR|WS)+QUOTE; 
WS: (' '|'\t'|'\f'|'\n'|'\r')+ { $channel = HIDDEN;}; // hide token from parser 

上面語法僅是一個例子，並且不是完整的語法。當代碼由AntlrWorks 3.4生成時會發生什麼：

我得到兩個Java文件：ExampleLexer和ExampleParser。

在ExampleLexer中，沒有包信息。我期望它進入com.example包，而ExampleParser包含com.example包。每次語法發生變化時，我都必須輸入Lexer代碼的com.example進行編譯。如何更改語法中的代碼以便添加包信息？

另外，如何添加自定義JavaDoc註釋？我想在此格式：

package com.example; 

Then import statements; 

/** 
* This class is used for Lexer. 
* @author name 
*/ 
public class ExampleLexer() { 
} 

package com.example; 

Then import statements 

/** 
* This class is used for parsing. 
* @author 
*/ 
public class ExampleParser() { 
} 

我也想取消自動包信息，生成語法時，告訴之前生成的註釋。這怎麼可能？

我希望你能幫上忙。我在Google上搜索過，但找不到任何關於此的內容。

Answer 1

在ExampleLexer中，沒有包信息。 [...]如何更改語法中的代碼，以便添加包信息？

用於組合的語法文件（一個同時產生詞法分析器和令牌解析器），指定包名需要指定兩個header部分：一個用於詞法分析器和一個用於解析器。正如你發現的，@header只適用於解析器。下面是一個使用兩個頭部分的例子：

@parser::header { 
    package com.example; 
    //parser's imports go here. 
} 

@lexer::header { 
    package com.example; 
    //lexer's imports go here. 
} 

此外，我將如何添加自定義的JavaDoc註釋？

我認爲組合語法只能爲解析器類而不是詞法分析器指定Javadoc註釋。這是由語法聲明之前增加一個文檔註釋完成：

/** 
* This class is used for parsing. 
* @author name 
*/ 
grammar Example; 

輸出你所期望：

/** 
* This class is used for parsing. 
* @author name. 
*/ 
@SuppressWarnings({"all", "warnings", "unchecked"}) 
public class ExampleParser extends Parser { 
//etc 

我認爲以獲取詞法分析器Javadoc註釋的唯一途徑類是創建一個特定的語法文件的詞法分析器，並給它一個文檔註釋：

/** 
* Lexer! 
* @author name 
*/ 
lexer grammar ExampleLexer; 

的輸出是：

/** 
* Lexer! 
* @author name 
*/ 
@SuppressWarnings({"all", "warnings", "unchecked"}) 
public class ExampleLexer extends Lexer { 
    //etc 

因此，您必須決定是否希望僅在解析器上使用Javadoc的組合語法文件，或者只使用兩個語法文件和您可以處理的所有Javadoc。

我還想在封裝信息之前刪除自動生成的註釋，它告訴何時生成語法。這怎麼可能？

ANTLR不提供command line option來允許這樣做，所以它不可能自動完成。

如果你期望有很多訪問者在你生成的文件中四處遊蕩（聽起來像你這樣做），考慮清楚這些文件實際上已經生成，並且讀者應該在其他地方查看完整的文檔（並且應該不做更改）。您可以通過在文件頂部添加一個大而難看的評論來輕鬆完成此操作，例如：

@parser::header { 

    //!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! 
    //!!!               !!! 
    //!!! THIS CODE IS AUTOMATICALLY GENERATED! DO NOT MODIFY!  !!! 
    //!!! Please refer to file Example.g for grammar documentation. !!! 
    //!!!               !!! 
    //!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! 

    package com.example; 
}