PolySymbols 模式微语法Pattern DSL实战让符号匹配超越字面名称【免费下载链接】intellij-communityIntelliJ IDEA IntelliJ Platform项目地址: https://gitcode.com/GitHub_Trending/in/intellij-community本文聚焦 IntelliJ 平台 PolySymbols 框架中的模式Pattern机制——一种叠加在宿主语言语法之上的微语法microsyntax匹配体系。它让一个符号不仅能按字面名称匹配还能解析v-on:click.once.alt这类指令式属性名、(keydown.control.shift.enter)这类事件修饰符链。读完本文你将掌握 pattern DSL 的 7 种模式种类、PolySymbolMatch的匹配结果结构、Vue 指令的 Web Types JSON 声明方式以及ReferencingPolySymbol的符号替身用法并了解其与查询模型、Web Types 的协作关系。本文以仓库内技能文档 patterns.md 为主体展开。为什么需要模式PatternPolySymbols 的引用/补全提供者工作在查询结果之上而非直接操作作用域。因此一旦一个符号携带了模式并被成功匹配它就能免费获得一整套 IDE 能力代码补全、引用解析、文档、导航、语义高亮、出现高亮、查找用法Find Usages、重命名重构。机制上分两条链路引用解析执行器返回一个复合符号PolySymbolMatch它被拆分为多个名称段name segment每段拥有独立的引用范围reference range代码补全执行器会评估所有可能的模式匹配名称来构建补全项并且支持多阶段补全multistaged completion——先补全名称前缀再继续补全模式的其余部分。这背后依赖整个 PolySymbols 框架其核心模块与接口清单可参考 SKILL.md 中的接口速查表PolySymbol、PolySymbolScope、PolySymbolQueryExecutor等。PolySymbolWithPattern与匹配结果携带模式的符号通过PolySymbolWithPattern接口暴露模式定义interface PolySymbolWithPattern : PolySymbol { val pattern: PolySymbolPattern }匹配过程产生一个PolySymbolMatch本质是一个CompositePolySymbol其nameSegments是PolySymbolNameSegment的列表。每个名称段描述一个名称范围该范围本身可以引用其他符号并携带一个MatchProblem取值包括UNKNOWN_SYMBOL—— 符号未匹配到任何已知符号MISSING_REQUIRED_PART—— 缺少必需的组成部分DUPLICATED—— 重复出现的部分。模式可以通过下面的 DSL 以编程方式创建但对于静态词表static vocabulariesWeb Types JSON 才是常规做法——其 JSON 形态几乎与 DSL 一一对应template/items/delegate/repeat/required详见 web-types.md。Pattern DSL 全览DSL 定义于community/platform/polySymbols/src/com/intellij/polySymbols/patterns/PolySymbolPatternDsl.kt文档记载路径典型用法如下val pattern polySymbolPattern { literal(v-) symbolReference() // 解析到包围它的 symbols{} 块或自定义 resolver sequence { ... } // 有序子模式全部必须匹配 oneOf { branch { ... }; branch { ... } } // 备选分支 group { // 最富表达力的构造见下文 symbols { from(SOME_KIND) } symbolReference() } optional { ... } repeating { unique(true); ... } completionPopup() // 仅补全用的标记丢弃已输入前缀...占位 completionPopupWithPrefixKept() }七种模式种类文档将其归纳为 7 种概念模式与上述 DSL 构建器一一对应字符串匹配String match—— 精确、区分大小写的字面文本对应literal。正则匹配Regex match——regex(pattern, caseSensitive)按正则表达式匹配文本。符号引用占位Symbol reference placeholder——symbolReference()通过包围该模式的符号解析器解析。未匹配时产生MatchProblem.UNKNOWN_SYMBOL。被匹配的符号本身也可以是PolySymbolMatch从而支持嵌套。模式序列Pattern sequence——sequence { }有序除包裹在optional中的部分外全部必需。缺少必需部分产生MatchProblem.MISSING_REQUIRED_PART。复合模式/分组Complex pattern / group——group { }能力最强的构造把子项视为备选分支可携带symbolsResolver或symbols { from(kind) { ... } }块为嵌套的symbolReference()提供解析作用域可用additionalScope(...)在匹配其子项时扩展解析栈可以是optional { }缺席不视为错误可以是repeating { unique(...) }重复时产生MatchProblem.DUPLICATED还可以用priority(...)/apiStatus(...)/overrideMatchProperties { }覆盖最终匹配结果的属性。补全自动弹出Completion auto-popup——completionPopup()/completionPopupWithPrefixKept()标记一个仅补全用的停顿点选中一项后补全会为下一段重新弹出。单一符号引用Single symbol reference自 2023.2 起—— 按符号名称匹配文本同时向另一元素插入一个引用。一个重要的匹配约束段匹配会消耗文本直到后续模式的静态前缀。符号引用或正则必须由静态文本或模式结尾终止不能在一个序列中间无界地开放延伸——这是保证解析可终止、可预测的关键。实战示例Vue 的v-on:click.once.alt这是文档中的经典示例且在本仓库中被完全以 Web Types JSON 声明而非 Kotlin DSL实现。文档记载其声明位于contrib/vuejs/vuejs-backend/resources/web-types/vue3.5.0.web-types.jsonJSON 结构如下{ name: Vue directive, virtual: true, exclusive-contributions: [/html/modifiers], pattern: { items: /html/vue-directives, template: [ v-, #item:Vue directive, { delegate: argument, required: false, template: [:, #..., #item:argument] }, { items: /html/modifiers, required: false, repeat: true, template: [., #item:modifier] } ] } }对v-on:click.once.alt的段拆分如下段含义v-指令模式的字面前缀on解析为 Vue 的on指令符号/html/vue-directives:字面分隔符click解析为指令的argument—— 对on而言是/js/events/html/vue-dynamic-argument即一个 DOM 事件名.once第一个修饰符 —— 通用修饰符列表stop/prevent/capture/self/once/passive.alt第二个修饰符 ——条件性合法因为click同时也匹配同一文件中嵌套在js.events下的 Mouse button/System event 修饰符子模式分别追加left/right/middle与ctrl/alt/shift/meta/exact这个例子揭示的关键教训是哪些修饰符合法本身是条件性的取决于已经匹配到的事件名而不是整个指令的一个固定列表。嵌套的items/template块配合子模式键如{or: [click, dblclick, ...]}让一个静态的 Web Types 文件就能表达这种条件性——无需任何代码。/:简写形式v-on→v-bind→:则通过delegate: /html/vue-directives/on复用完全相同的修饰符模式——模式骨架只声明一次所有别名共用。Angular 的同类微语法Angular 也有类似的微语法——扩展按键事件修饰符(keydown.control.shift.enter)同样以 Web Types 声明位于js/ng-custom-eventskindangular-base0.0.0.web-types.json文档记载路径。配套测试夹具文档记载于contrib/Angular/angular-tests/testData/highlighting/customUserEvents/证明任何库都能仅通过js/ng-custom-eventsWeb Types contribution 添加自己的事件修饰符微语法——无需 Kotlin——即可从核心模式引擎免费获得完整校验Unrecognized modifier/Unrecognized event/重复修饰符检测和补全。手写 DSL 的场景通配符符号静态 Web Types 无法表达匹配任意文本——对于通配/兜底catch-all符号必须直接使用 DSL。典型例子是 Vue 的VueAnySymbol/VueAnySlot文档记载位于contrib/vuejs/vuejs-backend/src/org/jetbrains/vuejs/web/symbols/VueAnySymbol.ktclass VueAnySymbol(...) : PolySymbolWithPattern, VueSymbol { override val pattern: PolySymbolPattern get() polySymbolPattern { regex(.*) } }一个regex(.*)模式即实现了匹配一切的兜底语义这正是 DSL 相比 JSON 的不可替代之处。ReferencingPolySymbol让一个符号替身另一种 kind另一个相关但不同的需求是让一种符号 kind 像另一种 kind 一样被解析/补全而无需复制数据。文档中的例子是消息束message-bundle的属性键被当作 Java 字符串字面量引用——作用域贡献者同时提供真实符号和一种引用符号将一种限定 kind 映射到另一种。community/platform/polySymbols/src/com/intellij/polySymbols/utils/ReferencingPolySymbol.kt文档记载路径正是为此而建一个PolySymbolWithPattern其模式在概念上是group { symbols { kinds.forEach { from(it) } }; symbolReference(name) }——所列其他 kind 的任何符号都能匹配并在给定名称下注册一个引用/用法。Angular 的PolySymbolReferencingScope文档记载位于contrib/Angular/angular-backend/src/org/angular2/web/scopes/PolySymbolReferencingScope.kt是围绕该工厂调用的薄PolySymbolScope包装——它不重新实现机制只是把它打包成可在注册器 DSL 中注入的作用域。Angular Forms 则在Angular2FormsSymbolQueryScopeContributor的attributeValueMappingScope中直接内联了同样的思路无包装类把HTML_ATTRIBUTE_VALUES重新映射到formControlName...所引用的表单控件属性 kind 上详见 case-studies.md 中的 Angular 一节。模式与周边机制的协作查询模型匹配后各名称段如何与作用域栈交互queryScope链式解析是理解模式匹配结果流向补全/引用的关键见 query-model.mdWeb Types本文多处提到的声明式 JSON 等价物及加载机制见 web-types.md框架全貌模式只是 PolySymbols 集成工作流中的一环——完整的接入清单启用语言、贡献作用域、解析引用、提供声明、接线补全见 SKILL.md。小结模式让符号从字面名称匹配升级为微语法匹配从而一次获得补全、引用、文档、导航、高亮、查找用法、重命名全套 IDE 能力7 种模式种类literal、regex、symbolReference、sequence、group、completion 标记、单符号引用覆盖了从简单前缀到条件性修饰符链的全部形态静态词表优先用 Web Types JSONtemplate/items/delegate/repeat/required与 DSL 几乎一一对应匹配任意文本等动态需求才需要手写 DSL修饰符合法性可以是条件性的——取决于已匹配的前置段纯 JSON 即可表达ReferencingPolySymbol提供了符号 kind 之间的替身映射让一种 kind 以另一种 kind 的身份参与解析与补全Angular 与 Vue 均基于它构建了各自的作用域封装。【免费下载链接】intellij-communityIntelliJ IDEA IntelliJ Platform项目地址: https://gitcode.com/GitHub_Trending/in/intellij-community创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考