treesitter

Documentation

Overview

Package treesitter is the syntax tier (docs/SPEC.md §10, §37.1): a `ds:def` in a comment binds to the next declaration as the grammar sees it, so blocks end where the language says they end and hashes are taken over the token stream, so formatters never cry wolf. Go, TypeScript, JavaScript, Python, and SQL ship here; any other tree-sitter grammar is registered through New with a Grammar describing its declaration nodes.

This module is cgo: the grammars compile from C on first build.

Index

• func All() []extract.Extractor
• func Go() extract.Extractor
• func JavaScript() extract.Extractor
• func New(g Grammar) extract.Extractor
• func Python() extract.Extractor
• func SQL() extract.Extractor
• func TSX() extract.Extractor
• func TypeScript() extract.Extractor
• type Grammar

Functions

func All

func All() []extract.Extractor

All returns every shipped tier, for docsync.WithExtractor(All()...).

func Go

func Go() extract.Extractor

Go returns the Go syntax tier.

func JavaScript

func JavaScript() extract.Extractor

JavaScript returns the JavaScript tier.

func New

func New(g Grammar) extract.Extractor

New returns an extractor for the grammar. It panics on a Grammar without a Name, Exts, or Language: that is a programming error at registration, not a runtime condition.

func Python

func Python() extract.Extractor

Python returns the Python tier.

func SQL

func SQL() extract.Extractor

SQL returns the SQL tier.

func TSX

func TSX() extract.Extractor

TSX returns the TypeScript tier for .tsx files.

func TypeScript

func TypeScript() extract.Extractor

TypeScript returns the TypeScript tier for .ts files.

Types

type Grammar

type Grammar struct {
	// Name is the tier name `check --explain` prints and Extractor.Name
	// returns, e.g. "go".
	Name string
	// Exts are the lowercase extensions this grammar claims, with the dot.
	Exts []string
	// Language is the compiled grammar.
	Language *sitter.Language
	// Kinds maps declaration node types to the block kind they define.
	// Node types absent here bind only under the generic rule: a type
	// named "statement" or ending in "_statement" or "_declaration" is a
	// statement.
	Kinds map[string]block.Kind
	// Wrappers are node types that hold a declaration rather than being
	// one (`export_statement`, `decorated_definition`). The value says
	// whether the block keeps the wrapper's range (true: `export function`
	// includes `export`) or the inner declaration's (false: decorators are
	// skipped, per §7.1).
	Wrappers map[string]bool
	// Groups are node types that hold sibling declarations rather than
	// qualifying them: a Go `const ( … )` contains const_specs, and the group
	// is not part of any entry's name. A type listed here may also appear in
	// Kinds -- Kinds says a directive above the group binds the whole group,
	// Groups says the group never contributes a segment to a name inside it.
	// Without it a grouped `type ( Shape … )` was named "Shape.Shape", because
	// the group takes its own name from its first entry.
	Groups map[string]bool
	// Comments are node types hashed only for frozen blocks.
	Comments map[string]bool
	// Literals are node types that make a one-name declaration a value: the
	// block's content is the literal, not the statement (§10 "a value only
	// when the block is a single literal").
	Literals map[string]bool
	// Symbol names a declaration node; nil uses the node's `name` field.
	Symbol func(n *sitter.Node, src []byte) string
	// Qualifier returns an extra leading segment for a node's symbol, for
	// languages whose methods name their type outside the nesting (Go
	// receivers). nil adds nothing.
	Qualifier func(n *sitter.Node, src []byte) string
}

Grammar describes how one language's tree maps to docsync blocks. Only the fields a language needs are set; the zero value of each means "the generic rule applies".