Language Registry

Register tree-sitter grammars for custom languages

The LanguageRegistry service manages tree-sitter-based language definitions for syntax highlighting and parsing. Each registry is scoped to a specific language.

Accessing the LanguageRegistry

private val languageRegistries: LanguageRegistry<*> by plugin()

Registering a language

Register a new tree-sitter language definition:

val registration: LanguageRegistration = languageRegistries.register(
    descriptor = LanguageDescriptor(
        name = "MyLang",
        extensions = listOf("myext"),
        fileNames = listOf("Myfile"),
        languageId = "mylang",
        displayName = "MyLang"
    ),
    grammarProvider = MyGrammarProvider(),
    queries = MyQueryProvider(),
    theme = MyThemeProvider()
) {}

LanguageDescriptor

Property	Type	Description
name	String	Language name
extensions	List<String>	File extensions (without dot)
fileNames	List<String>	Exact file names (e.g. “Makefile”)
languageId	String	LSP language ID (defaults to name)
displayName	String	Human-readable name (defaults to name)

LanguageGrammarProvider

A fun interface that provides the tree-sitter grammar:

fun interface LanguageGrammarProvider {
    fun provide(): Long  // Returns the grammar ID
}

LanguageThemeProvider

An optional fun interface for syntax highlighting theme support:

fun interface LanguageThemeProvider {
    fun getStyleForCapture(captureName: String): CaptureStyle?
}

QueryProvider

Provides tree-sitter queries for the language:

interface QueryProvider {
    fun highlights(): String           // Required: highlight queries
    fun indents(): String? = null      // Optional: indent queries
    fun folds(): String? = null        // Optional: fold queries
    fun locals(): String? = null       // Optional: local variable queries
    fun injections(): String? = null   // Optional: injection queries
    fun tags(): String? = null         // Optional: tag queries
}

LanguageRegistration

Method	Description
unregister()	Removes the language registry

LanguageRegistry methods

Method	Description
register(descriptor, grammarProvider, queries, theme)	Register a language (requires KlyxPlugin context)
unregister(id)	Unregister a language by ID
getDescriptor(name)	Get a language descriptor by name
getExtensions()	Map of extension to language name
getFileNames()	Map of file name to language name

CaptureStyle

Generated highlight spans use CaptureStyle to define how tree-sitter nodes are styled:

data class CaptureStyle(
    val editorColorKey: ColorKey = ColorKey.TEXT_NORMAL,
    val bold: Boolean = false,
    val italic: Boolean = false,
    val strikethrough: Boolean = false
)

ColorKey values

Key	Description
KEYWORD	Language keywords
IDENTIFIER_NAME	Identifier names
FUNCTION_NAME	Function/method names
IDENTIFIER_VAR	Variable names
LITERAL	String/number literals
COMMENT	Comments
ANNOTATION	Annotations
OPERATOR	Operators
HTML_TAG	Markup tags
ATTRIBUTE_NAME	Object attributes
ATTRIBUTE_VALUE	Attribute values
PROBLEM_ERROR	Error indicators
PROBLEM_WARNING	Warning indicators
TEXT_NORMAL	Default text

Predefined CaptureStyle constants

CaptureStyle provides convenient constants for common styles:

Constant	Description
CaptureStyle.KEYWORD	Bold keyword style
CaptureStyle.TYPE	Identifier name style
CaptureStyle.FUNCTION	Italic function name style
CaptureStyle.VARIABLE	Variable name style
CaptureStyle.STRING	Literal string style
CaptureStyle.COMMENT	Italic comment style
CaptureStyle.ANNOTATION	Annotation style
CaptureStyle.OPERATOR	Operator style
CaptureStyle.TAG	Bold HTML tag style
CaptureStyle.ATTRIBUTE_NAME	Attribute name style
CaptureStyle.ATTRIBUTE_VALUE	Attribute value style
CaptureStyle.ERROR	Error indicator style
CaptureStyle.WARNING	Warning indicator style

Unregistering

languageRegistries.unregister("mylang")
// or via handle:
registration.unregister()

Listing registered languages

val allRegistries: List<LanguageRegistry<*>> = languageRegistries.all
val byName: LanguageDescriptor? = languageRegistries.getDescriptor("MyLang")

Example

Register a language registry for a custom file extension:

class MyLangGrammarProvider : LanguageGrammarProvider {
    override fun provide(): Long = loadGrammar("mylang.so")
}

class MyQueryProvider : QueryProvider {
    override fun highlights(): String = """
        (function_call) @function
        (string) @string
        (comment) @comment
    """.trimIndent()
}

class MyThemeProvider : LanguageThemeProvider {
    override fun getStyleForCapture(captureName: String): CaptureStyle? = when (captureName) {
        "function" -> CaptureStyle.FUNCTION
        "string" -> CaptureStyle.STRING
        "comment" -> CaptureStyle.COMMENT
        else -> null
    }
}

override suspend fun onLoad() {
    languageRegistries.register(
        descriptor = LanguageDescriptor(
            name = "MyLang",
            extensions = listOf("myext")
        ),
        grammarProvider = MyLangGrammarProvider(),
        queries = MyQueryProvider(),
        theme = MyThemeProvider()
    )
}