inject

Documentation

Overview

Package inject finds the injections of a text and parses the layer of each (D27). An injection is a range of the text that another grammar parses, such as a <script> element of HTML, or a SQL statement in the input of usql. A layer is one tree of one language over the ranges of its injections.

The package ports the part of crates/highlight of upstream tree-sitter that finds injections and parses their layers. The part that highlights is not ported. Upstream has no public API for this part, so D72 sets the API: NewConfig compiles the injection query of a language, and Config.Layers gives every layer of a text at once. The text is UTF-8 (D71).

The examples of Layers and WithReplacer are in the grammar package github.com/xo/transit/grammars/html, because they need the grammars of HTML and JavaScript.

Index

• type Config
  • func NewConfig(language *transit.Language, name, injectionQuery string) (*Config, error)
  • func (c *Config) Language() *transit.Language
  • func (c *Config) Layers(ctx context.Context, p *transit.Parser, src []byte, ...) ([]Layer, error)
  • func (c *Config) Name() string
• type Layer
• type Option
  • func WithReplacer(r Replacer) Option
• type Replacer

Types

type Config

type Config struct {
	// contains filtered or unexported fields
}

Config holds the language, the name and the injection query of a language. It does not change after NewConfig, so goroutines can share it.

Config is the injection part of HighlightConfiguration.

func NewConfig

func NewConfig(language *transit.Language, name, injectionQuery string) (*Config, error)

NewConfig compiles the injection query of a language. name is the name of the language, which injection.self gives. The error wraps a *transit.QueryError.

NewConfig is HighlightConfiguration::new, with no highlight query and no locals query (D72).

func (*Config) Language

func (c *Config) Language() *transit.Language

Language returns the language.

func (*Config) Layers

func (c *Config) Layers(ctx context.Context, p *transit.Parser, src []byte, lookup func(name string) (*Config, bool), opts ...Option) ([]Layer, error)

Layers parses src with c, finds every injection, and parses the layer of each. lookup gives the configuration of an injected language name, and an injection whose name it does not find is skipped. The parser p parses every layer. Layers clears the included ranges of p before it returns, and the language of the last layer stays set.

The layers come sorted by the start of their first range, then by depth, so the root layer comes first. Two layers that are equal on both keep the order in which Layers finds them (D72). A layer with no range is not built, and neither is a layer whose ranges the parser rejects. When the parser cannot take the language of a layer, or when ctx ends, Layers returns the error, wrapped, and no layers.

As upstream does, injection.parent gives the name of the root language at every depth, and there is no limit on the depth (hard rule 6).

The options are an API that upstream does not have (D28). WithReplacer replaces the text of nodes before a layer is parsed.

Layers runs HighlightIterLayer::new for the root layer, and the injection part of the Iterator of HighlightIter for each layer, as Highlighter::highlight does when its events are read to the end.

func (*Config) Name

func (c *Config) Name() string

Name returns the name of the language.

type Layer

type Layer struct {
	// Name is the language name that the injection query gave, such as
	// "js". For the root layer it is the name of its Config.
	Name string
	// Config is the configuration that the lookup of Layers gave for Name.
	Config *Config
	// Tree is the tree of the layer.
	Tree *transit.Tree
	// Ranges are the ranges of the text that the layer parses. The root
	// layer has one range, from the start of the text to the largest byte
	// and point that the parser takes.
	Ranges []transit.Range
	// Depth is 0 for the root layer, and one more than the depth of its
	// parent for another layer.
	Depth int
}

Layer is one tree of one language over the ranges of its injections.

type Option

type Option func(*options)

Option changes what Layers does.

func WithReplacer

func WithReplacer(r Replacer) Option

WithReplacer makes Layers ask r about the nodes of the parent layer that an injected layer holds, before it parses that layer. Layers walks the named and anonymous nodes of the parent tree inside the ranges of the layer, from the root down. When r gives a text for a node, the layer parses that text in place of the text of the node, and Layers does not ask r about the children of the node. The root layer has no parent, so its text stays. The text of the other layers, and the text that the injection queries match, stay the text of src.

type Replacer

type Replacer func(name string, n transit.Node, src []byte) ([]byte, bool)

Replacer gives the text that takes the place of the node n of a parent layer in the text of the injected layer of the language name, and true. It returns false for a node whose text stays. src is the whole text. The text must have as many bytes as the node, so that every offset of the layer stays the same.