segment-matcher/dist/cjs/pattern_parser.d.ts

Segment Matcher - TypeScript version with dual ESM/CJS format support

import { PatternToken } from './pattern_token';
/**
 * 模式解析器类
 *
 * 负责将命令模式字符串解析为令牌数组。
 * 支持多种模式元素：字面量、类型化字面量、必需参数、可选参数、剩余参数等。
 *
 * @example
 * ```typescript
 * const tokens = PatternParser.parse('hello <name:text> [count:number=1]');
 * // 返回解析后的令牌数组
 * ```
 */
export declare class PatternParser {
    /**
     * 解析命令模式字符串
     *
     * 将模式字符串解析为令牌数组，支持以下模式元素：
     * - 普通字面量：`hello`
     * - 类型化字面量：`{text:start}`, `{face:1}`, `{image:avatar.png}`
     * - 必需参数：`<name:text>`, `<count:number>`
     * - 可选参数：`[message:text]`, `[count:number=1]`
     * - 剩余参数：`[...rest]`, `[...rest:face]`
     *
     * @param pattern - 命令模式字符串
     * @returns 解析后的令牌数组
     *
     * @throws {PatternParseError} 当模式格式错误或解析失败时抛出
     *
     * @example
     * ```typescript
     * // 基础模式
     * const tokens1 = PatternParser.parse('hello <name:text>');
     *
     * // 复杂模式
     * const tokens2 = PatternParser.parse('{text:start}<command:text>[count:number=1][...rest]');
     * ```
     */
    static parse(pattern: string): PatternToken[];
    /**
     * 优化参数之间的空格
     *
     * 将参数与参数之间的单个空格标记为可选的分隔符。
     * 超过一个空格的部分保持为必需的字面量。
     *
     * 规则：
     * 1. 如果字面量以单个空格结尾，且后面是参数，则将该空格分离为可选空格
     * 2. 如果单个空格字面量后面是参数类型，则将该空格标记为可选
     *
     * @param tokens - 解析后的令牌数组
     */
    private static optimizeParameterSpaces;
    /**
     * 清除解析缓存
     *
     * 在内存紧张或需要强制重新解析时调用。
     */
    static clearCache(): void;
    /**
     * 获取缓存统计信息
     */
    static getCacheStats(): {
        size: number;
    };
    /**
     * 解析类型化字面量
     *
     * 解析格式为 `{type:value}` 的类型化字面量。
     * 支持各种消息段类型，如 text、face、image、at 等。
     *
     * @param pattern - 完整的模式字符串
     * @param startIndex - 开始解析的位置（'{' 的位置）
     * @returns 解析后的类型化字面量令牌
     *
     * @example
     * ```typescript
     * // 文本类型化字面量
     * const token1 = PatternParser.parseTypedLiteral('{text:start}', 0);
     *
     * // 表情类型化字面量
     * const token2 = PatternParser.parseTypedLiteral('{face:1}', 0);
     *
     * // 图片类型化字面量
     * const token3 = PatternParser.parseTypedLiteral('{image:avatar.png}', 0);
     * ```
     */
    private static parseTypedLiteral;
    /**
     * 解析必需参数
     *
     * 解析格式为 `<name:type>` 的必需参数。
     * 必需参数在匹配时必须提供，否则匹配失败。
     *
     * @param pattern - 完整的模式字符串
     * @param startIndex - 开始解析的位置（'<' 的位置）
     * @returns 解析后的必需参数令牌
     *
     * @example
     * ```typescript
     * // 文本参数
     * const token1 = PatternParser.parseRequiredParameter('<name:text>', 0);
     *
     * // 数字参数
     * const token2 = PatternParser.parseRequiredParameter('<count:number>', 0);
     *
     * // 表情参数
     * const token3 = PatternParser.parseRequiredParameter('<emoji:face>', 0);
     * ```
     */
    private static parseRequiredParameter;
    /**
     * 解析可选参数
     *
     * 解析格式为 `[name:type]` 或 `[name:type=default]` 的可选参数。
     * 支持默认值语法，包括字符串、数字、JSON 对象等。
     * 还支持剩余参数语法 `[...rest]` 和 `[...rest:type]`。
     *
     * @param pattern - 完整的模式字符串
     * @param startIndex - 开始解析的位置（'[' 的位置）
     * @returns 解析后的可选参数令牌
     *
     * @example
     * ```typescript
     * // 基础可选参数
     * const token1 = PatternParser.parseOptionalParameter('[message:text]', 0);
     *
     * // 带默认值的可选参数
     * const token2 = PatternParser.parseOptionalParameter('[count:number=1]', 0);
     *
     * // 带 JSON 默认值的可选参数
     * const token3 = PatternParser.parseOptionalParameter('[emoji:face={"id":1}]', 0);
     *
     * // 剩余参数
     * const token4 = PatternParser.parseOptionalParameter('[...rest]', 0);
     * const token5 = PatternParser.parseOptionalParameter('[...rest:face]', 0);
     * ```
     */
    private static parseOptionalParameter;
    /**
     * 解析默认值
     *
     * 解析字符串、数字、JSON 对象等类型的默认值。
     * 支持嵌套的 JSON 结构，如对象和数组。
     *
     * @param defaultValueStr - 默认值字符串
     * @returns 解析后的默认值
     *
     * @example
     * ```typescript
     * // 字符串默认值
     * PatternParser.parseDefaultValue('hello'); // 'hello'
     *
     * // 数字默认值
     * PatternParser.parseDefaultValue('42'); // 42
     *
     * // JSON 对象默认值
     * PatternParser.parseDefaultValue('{"id":1,"name":"test"}'); // {id: 1, name: "test"}
     *
     * // 数组默认值
     * PatternParser.parseDefaultValue('[1,2,3]'); // [1, 2, 3]
     * ```
     */
    private static parseDefaultValue;
    /**
     * 解析普通字面量
     *
     * 解析连续的普通字符作为字面量令牌。
     * 遇到特殊字符（'{', '<', '['）时停止解析。
     *
     * @param pattern - 完整的模式字符串
     * @param startIndex - 开始解析的位置
     * @returns 解析结果，包含令牌和新的解析位置
     *
     * @example
     * ```typescript
     * // 解析简单字面量
     * const result1 = PatternParser.parseLiteral('hello<name>', 0);
     * // result1.token.value === 'hello', result1.newIndex === 5
     *
     * // 解析包含空格的字面量
     * const result2 = PatternParser.parseLiteral('hello world <name>', 0);
     * // result2.token.value === 'hello world ', result2.newIndex === 12
     * ```
     */
    private static parseLiteral;
    /**
     * 查找匹配的闭合括号
     *
     * 从指定的开始位置查找匹配的闭合括号。
     * 支持嵌套的括号结构，如 `{[...]}`。
     *
     * @param pattern - 完整的模式字符串
     * @param startIndex - 开始位置（开括号的位置）
     * @returns 闭合括号的位置
     *
     * @throws {PatternParseError} 当找不到匹配的闭合括号时抛出
     *
     * @example
     * ```typescript
     * // 简单括号匹配
     * PatternParser.findClosingBrace('{text:hello}', 0); // 返回 11
     *
     * // 嵌套括号匹配
     * PatternParser.findClosingBrace('{[text:hello]}', 0); // 返回 13
     * ```
     */
    private static findClosingBrace;
}