Poly Symbols

Poly Symbol Query Executor

The main part of the framework is PolySymbolQueryExecutor, which supports three simple queries:

• list symbols

• get code completions

• match symbols with a name

It uses symbols from scopes provided through PolySymbolQueryScopeContributor.

The list of scopes is built similarly to how code completion works. Various contributors define patterns for PsiElements for which they provide symbol scopes. For each instance of PolySymbolQueryExecutor, the list of scopes is built anew depending on the provided PSI location.

During query execution, the executor gets symbols or completion items from each scope on the list to build the query results. The results of the queries may be customized by PolySymbolQueryResultsCustomizer allowing for a very robust way to filter or alter the results of any query.

The PolySymbolQueryExecutor can be used in many places to provide symbols, but the main consumers of the API are reference and code completion providers. The PolySymbolQueryExecutor simplifies reference and code completion providers by delegating the actual symbol resolution to PolySymbolScope. The executor provides a customization layer as well and abstracts language integration from symbol sources allowing for symbols to be provided from various sources (e.g. source code, library code, or static symbol definitions, like Web Types).

Symbol Patterns

PolySymbolQueryExecutor's main advantage is the ability to evaluate symbol patterns.

Many frameworks or libraries have custom syntaxes as a meta-language over regular language syntax. Examples for this are various web frameworks (e.g. HTML attribute name microsyntax - see Model Queries example for Vue directive syntax), but also message bundle keys, or plugin extension points defined in XML. Using symbol patterns, it is relatively easy to define that micro syntax. The pattern evaluator based on that information is able to recognize symbols making up a name of another symbol.

With none or minimal customizations required, for such symbols, the Poly Symbols framework provides:

• code completion

• reference resolution

• documentation

• navigation

• semantic highlighting

• occurrences highlighting

• find usages

• rename refactoring

This is possible because neither reference nor completion providers use PolySymbolScopes directly, but instead they depend on the query results from the PolySymbolQueryExecutor. The executor can return a composite symbol for a reference provider, which then is split into name segments, and each of the recognized symbols has its own reference range.

For a code completion provider, on the other hand, it can provide a set of completion items, which are results of evaluating all possible symbol names for the given patterns. Pattern evaluator supports also multistaged completion, so it's possible to first complete a name prefix and then continue with completion of the rest of the pattern.

Summary

Overall, the Poly Symbols framework can serve as a base for a language support, or can work on a meta-level, to support frameworks or libraries, which are giving additional meaning to the existing language features.

Currently, IDEs provide built-in integration for the following language features (see Poly Symbols Integration with Language Features):

• HTML: elements, attributes, and attribute values

• CSS: properties, custom properties, functions, classes, pseudo-elements, pseudo-classes, and parts

• JavaScript: string-literals, object properties, object literals, and symbols (in JavaScript and TypeScript)

The following sections provide information on how to implement Poly Symbols for plugins and how to define them statically through JSON schemas:

• Implementing Poly Symbols

• Web Types

PolyContext

Poly Symbols framework provides a convenient way to manage enablement of features through PolyContext API.