如何用Haxe的hxparse解析LuaDoc参数注释的联合类型

1. 简化多规则集切换逻辑 #

不用频繁切换独立规则集，而是在单个lexer内通过状态机区分不同解析阶段（参数名、类型、描述），让逻辑更紧凑，避免规则集切换的冗余代码。核心是给lexer定义状态枚举，匹配Token时根据当前状态生成对应类型，并自动切换状态进入下一阶段。

2. 实现联合类型解析与空格处理 #

空格处理 #

直接在lexer中忽略所有空格，不生成Whitespace Token——空格仅作为分隔符，无需参与语法逻辑判断，彻底避免解析时的空格分支问题。

联合类型解析 #

通过循环匹配处理任意数量的|分隔类型：先解析第一个基础类型，然后循环检测是否存在|，若存在则继续解析后续类型并收集到数组中，无需硬编码每个类型分支，解决编译器提示分支未使用的问题。

完整代码示例 #

Token枚举定义

enum Token {
    // 参数名称
    Name(s:String);
    // 单个类型名称
    TypeName(s:String);
    // 联合类型分隔符
    Pipe;
    // 参数描述
    Description(s:String);
}

Lexer实现（带状态机）

class DocLexer extends hxparse.Lexer<Token> {
    // 定义lexer的解析状态
    enum State {
        ExpectName;
        ExpectType;
        ExpectDescription;
    }

    var currentState:State = State.ExpectName;

    public function new() {
        super();
        // 全局忽略所有空格，不生成Token
        addRule(/\s+/, function(_) {});

        // 匹配参数名/类型名（根据当前状态区分）
        addRule(/[a-zA-Z_][a-zA-Z0-9_]*/, function(s) {
            switch currentState {
                case ExpectName:
                    currentState = ExpectType;
                    return Name(s);
                case ExpectType:
                    return TypeName(s);
                case ExpectDescription:
                    return null; // 描述阶段不再匹配名称/类型
            }
        });

        // 仅在类型阶段匹配联合类型分隔符|
        addRule(/\|/, function(_) {
            return currentState == ExpectType ? Pipe : null;
        });

        // 匹配描述（进入描述阶段后不再切换状态）
        addRule(/\S.*/, function(s) {
            if (currentState == ExpectType) {
                currentState = ExpectDescription;
                return Description(s.trim());
            }
            return null;
        });
    }
}

Parser实现（联合类型解析）

class DocParser extends hxparse.Parser<Token> {
    // 解析单个@param条目
    public function parseParam():{name:String, types:Array<String>, description:String} {
        // 1. 解析参数名称
        var nameToken = expect(Name);
        var name = nameToken.s;

        // 2. 解析联合类型
        var types = new Array<String>();
        // 先匹配第一个类型
        types.push(expect(TypeName).s);
        // 循环匹配后续的 | 类型
        while (lookahead(Pipe)) {
            consume(Pipe); // 吃掉|分隔符
            types.push(expect(TypeName).s);
        }

        // 3. 解析描述
        var description = expect(Description).s;

        return {name: name, types: types, description: description};
    }
}

使用示例 #

var input = "username string|number 用户登录账号";
var lexer = new DocLexer();
var tokens = lexer.tokenize(input);
var parser = new DocParser();
parser.setTokens(tokens);
var result = parser.parseParam();
trace(result); 
// 输出: { name: "username", types: ["string", "number"], description: "用户登录账号" }

内容的提问来源于stack exchange，提问作者Danielo515