JetBrains/intellij-community / .claude/skills/poly-symbols
poly-symbols
VerifiedImplement PolySymbols completion, references, and rename.
| File | Kind | Size |
|---|---|---|
| OWNERSHIP | other | 25 B |
| SKILL.md | skill md | 16.8 KB |
| references/case-studies.md | markdown | 23.6 KB |
| references/migration.md | markdown | 11.7 KB |
| references/patterns.md | markdown | 8.7 KB |
| references/query-model.md | markdown | 43.7 KB |
| references/testing.md | markdown | 15.3 KB |
| references/web-types.md | markdown | 6.0 KB |
references/patterns.md
View on GitHub# PolySymbols patterns (microsyntax)
Part of [poly-symbols](../SKILL.md). Patterns let a symbol match more than just its literal name —
they evaluate a "microsyntax" that a framework/library layers on top of base language syntax (HTML
attribute name syntax carrying a Vue directive, an event-binding name carrying Angular modifiers, a
message-bundle key embedded in a Java string).
## Why patterns exist
Because reference/completion providers work off *query results*, not scopes directly, a symbol with
a pattern gets an entire suite of IDE features for free once matched: code completion, reference
resolution, documentation, navigation, semantic highlighting, occurrence highlighting, find usages,
rename refactoring. Mechanically: for reference resolution the executor returns a composite symbol
(`PolySymbolMatch`) that splits into name segments, each with its own reference range; for
completion it evaluates every possible pattern-matching name to build completion items, and supports
**multistaged completion** — complete a name prefix first, then continue completing the rest of the
pattern.
## `PolySymbolWithPattern` and the match result
```kotlin
interface PolySymbolWithPattern : PolySymbol { val pattern: PolySymbolPattern }
```
Matching produces a `PolySymbolMatch` (a `CompositePolySymbol`) whose `nameSegments` is a list of
`PolySymbolNameSegment`, each describing a name range that may itself reference other symbols and
carry a `MatchProblem` (`UNKNOWN_SYMBOL`, `MISSING_REQUIRED_PART`, `DUPLICATED`). Programmatic
pattern creation is possible via the DSL below, but **Web Types JSON is the usual approach** for
static vocabularies — see [web-types.md](web-types.md) for the JSON shape, which mirrors this DSL
almost 1:1 (`template`/`items`/`delegate`/`repeat`/`required`).
## The pattern DSL
`community/platform/polySymbols/shared/src/com/intellij/polySymbols/patterns/PolySymbolPatternDsl.kt`:
```kotlin
val pattern = polySymbolPattern {
literal("v-")
symbolReference() // resolves against the enclosing symbols{} block or a custom resolver
sequence { ... } // ordered sub-patterns, all must match
oneOf { branch { ... }; branch { ... } } // alternatives
group { // richest construct — see below
symbols { from(SOME_KIND) }
symbolReference()
}
optional { ... }
repeating { unique(true); ... }
completionPopup() // completion-only marker; discards the typed prefix, "..." placeholder
completionPopupWithPrefixKept()
}
```
Seven conceptual pattern kinds (per the docs, mirrored by the DSL builders above):
1. **String match** — exact, case-sensitive literal text (`literal`).
2. **Regex match** — `regex(pattern, caseSensitive)`.
3. **Symbol reference placeholder** — `symbolReference()`; resolves via the enclosing pattern's
symbol resolver. Unmatched → `MatchProblem.UNKNOWN_SYMBOL`. The matched symbol can itself be a
`PolySymbolMatch`, enabling nesting.
4. **Pattern sequence** — `sequence { }`; ordered, all sub-patterns required unless wrapped in
`optional`. Missing a required part → `MatchProblem.MISSING_REQUIRED_PART`.
5. **Complex pattern / group** — `group { }` — the most capable construct: treats children as
alternatives, can carry a `symbolsResolver`/`symbols { from(kind) { ... } }` block for nested
`symbolReference()`s, `additionalScope(...)` to extend the resolve stack while matching its
children, can be `optional { }` (absence isn't an error), `repeating { unique(...) }` (with
`MatchProblem.DUPLICATED` on repeats), and can `priority(...)`/`apiStatus(...)`/
`overrideMatchProperties { }` to override the resulting match's properties.
6. **Completion auto-popup** — `completionPopup()`/`completionPopupWithPrefixKept()` — marks a
completion-only stopping point; selecting an item reopens completion for the next segment.
7. **Single symbol reference** (since 2023.2) — matches text against a symbol name while inserting
a reference to another element.
Segment matching consumes text "up to the static prefixes of the following patterns" — a symbol
reference or regex must be terminated by static text or the end of the pattern; it can't be
open-ended in the middle of a sequence.
## Worked example: Vue's `v-on:click.once.alt`
The canonical example from the docs, and — in this repo — **declared entirely as Web Types JSON**,
not the Kotlin DSL (`contrib/vuejs/vuejs-backend/resources/web-types/vue@3.5.0.web-types.json`):
```json
{
"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"] }
]
}
}
```
Segment breakdown for `v-on:click.once.alt`:
| Segment | Meaning |
|---|---|
| `v-` | literal prefix of the directive pattern |
| `on` | resolves to the Vue `on` directive symbol (`/html/vue-directives`) |
| `:` | literal separator |
| `click` | resolves as the directive's `argument` — for `on`, that's `/js/events` + `/html/vue-dynamic-argument`, i.e. a DOM event name |
| `.` `once` | first modifier — general modifier list (`stop`/`prevent`/`capture`/`self`/`once`/`passive`) |
| `.` `alt` | second modifier — **conditionally legal** because `click` also matches the "Mouse button"/"System event" modifier sub-patterns nested under `js.events` in the same file, which add `left`/`right`/`middle` and `ctrl`/`alt`/`shift`/`meta`/`exact` respectively |
The key lesson: "which modifiers are legal" is itself pattern-conditional on the *already-matched*
event name, not a fixed list for the whole directive — nested `items`/`template` blocks keyed by a
sub-pattern (`{"or": ["click", "dblclick", ...]}`) let a static Web Types file express that
conditionality without any code.
`@`/`:` shorthand forms (`v-on` → `@`, `v-bind` → `:`) reuse the exact same modifiers pattern via
`"delegate": "/html/vue-directives/on"` — declare the pattern skeleton once, reuse it for every
alias.
Angular's analogous microsyntax — extended key-event modifiers (`(keydown.control.shift.enter)`) —
is also Web Types-declared, under the `js/ng-custom-events` kind
(`angular-base@0.0.0.web-types.json`). A companion test fixture
(`contrib/Angular/angular-tests/testData/highlighting/customUserEvents/`) demonstrates that *any*
library can add its own event-modifier microsyntax purely via a `js/ng-custom-events` Web Types
contribution — no Kotlin required — and get full validation ("Unrecognized modifier"/"Unrecognized
event"/duplicate-modifier detection) and completion for free from the core pattern engine.
## Hand-written DSL example
Static Web Types can't express "match literally anything" — for wildcard/catch-all symbols, use the
DSL directly. Vue's `VueAnySymbol`/`VueAnySlot`
(`contrib/vuejs/vuejs-backend/src/org/jetbrains/vuejs/web/symbols/VueAnySymbol.kt`):
```kotlin
class VueAnySymbol(...) : PolySymbolWithPattern, VueSymbol {
override val pattern: PolySymbolPattern
get() = polySymbolPattern { regex(".*") }
}
```
## "Symbol standing in for another kind" — `ReferencingPolySymbol`
A different but related need: making one symbol kind resolve/complete as if it were another kind,
without duplicating data. Example from the docs: message-bundle property keys referenced as Java
string literals — a scope contributor supplies both the real symbols *and* a reference symbol that
maps one qualified kind onto another.
`community/platform/polySymbols/shared/src/com/intellij/polySymbols/utils/ReferencingPolySymbol.kt`
builds exactly this: a `PolySymbolWithPattern` whose pattern is, conceptually,
`group { symbols { kinds.forEach { from(it) } }; symbolReference(name) }` — any symbol of the listed
other kinds matches, and a reference/usage gets registered under the given name.
Angular's `PolySymbolReferencingScope`
(`contrib/Angular/angular-backend/src/org/angular2/web/scopes/PolySymbolReferencingScope.kt`) is a
thin `PolySymbolScope` wrapper around exactly this factory call — it doesn't reimplement the
mechanism, it just packages it as an injectable scope for the registrar DSL. Angular Forms inlines
the same idea directly (no wrapper class) in `Angular2FormsSymbolQueryScopeContributor`'s
`attributeValueMappingScope`, to remap `HTML_ATTRIBUTE_VALUES` onto the referenced form-control-prop
kind for `formControlName="..."` (see [case-studies.md](case-studies.md#angular)).
## Related
- [Query model](query-model.md) — how a matched pattern's segments interact with the scope stack (`queryScope` chaining).
- [Web Types](web-types.md) — the declarative JSON equivalent of this DSL, and how it's loaded.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |