Documentation
¶
Overview ¶
Package highlight is the syntax highlighter behind the editor.
It reads micro-compatible syntax definitions — YAML files with a file-type header and a list of rules per syntax group — and turns them into line matches: for every line, a map from the byte position where the colour changes to the Group that applies from there on. The editor consumes those matches in its CellView, which resolves each group to a tcell.Style through the active colorscheme.
Parsing and highlighting are separate steps, which is what makes incremental rehighlighting possible:
file, err := highlight.ParseFile(data) // the rules of one grammar header, err := highlight.ParseHeader(data) // how to detect the file type def, err := highlight.ParseDef(file, header) highlight.ResolveIncludes(def, files) // pull in "include" rules h := highlight.NewHighlighter(def) h.HighlightStates(buf) // end-of-line state per line h.HighlightMatches(buf, 0, buf.LinesNum()) // groups per line
The buffer passed in must implement LineStates: a way to store, and read back, the highlighter state at the end of every line. States are what keep a construct that spans lines — a block comment, a multi-line string — correct when only part of the buffer is re-highlighted, and ReHighlightStates and ReHighlightLine are the incremental entry points the editor uses for that.
Index ¶
- Variables
- func ResolveIncludes(def *Def, files []*File)
- type Def
- type File
- type Group
- type Header
- type Highlighter
- func (h *Highlighter) HighlightMatches(input LineStates, startline, endline int)
- func (h *Highlighter) HighlightStates(input LineStates)
- func (h *Highlighter) HighlightString(input string) []LineMatch
- func (h *Highlighter) ReHighlightLine(input LineStates, lineN int)
- func (h *Highlighter) ReHighlightStates(input LineStates, startline int)
- type LineMatch
- type LineStates
- type State
Constants ¶
This section is empty.
Variables ¶
var Groups map[string]Group
Groups contains all of the groups that are defined You can access them in the map via their string name
Functions ¶
func ResolveIncludes ¶
ResolveIncludes will sort out the rules for including other filetypes You should call this after parsing all the Defs
Types ¶
type Def ¶
type Def struct {
*Header
// contains filtered or unexported fields
}
A Def is a full syntax definition for a language It has a filetype, information about how to detect the filetype based on filename or header (the first line of the file) Then it has the rules which define how to highlight the file
type File ¶
type File struct {
FileType string
// contains filtered or unexported fields
}
File is a syntax definition that has been read but not yet compiled: its file type plus the raw YAML it came from. Pairs of files and headers are what ParseDef turns into the rules a Highlighter runs.
type Header ¶
type Header struct {
FileType string
FileNameRegex *regexp.Regexp
HeaderRegex *regexp.Regexp
SignatureRegex *regexp.Regexp
}
Header describes how a syntax definition recognizes its file type: the name of the type it claims, plus the patterns that identify it. Files are matched through FileNameRegex (typically an extension or a well-known name), and contents through HeaderRegex — tried against the whole first line — or SignatureRegex, which may match any part of it.
func ParseHeader ¶
ParseHeader reads the header of a syntax definition — the "filetype" and "detect" keys — without compiling the rules. It is what a program calls to find out which grammar claims a file, before deciding to use it.
type Highlighter ¶
type Highlighter struct {
Def *Def
// contains filtered or unexported fields
}
A Highlighter contains the information needed to highlight a string
func NewHighlighter ¶
func NewHighlighter(def *Def) *Highlighter
NewHighlighter returns a new highlighter from the given syntax definition
func (*Highlighter) HighlightMatches ¶
func (h *Highlighter) HighlightMatches(input LineStates, startline, endline int)
HighlightMatches sets the matches for each line in between startline and endline It sets all other matches in the buffer to nil to conserve memory This assumes that all the states are set correctly
func (*Highlighter) HighlightStates ¶
func (h *Highlighter) HighlightStates(input LineStates)
HighlightStates correctly sets all states for the buffer
func (*Highlighter) HighlightString ¶
func (h *Highlighter) HighlightString(input string) []LineMatch
HighlightString syntax highlights a string Use this function for simple syntax highlighting and use the other functions for more advanced syntax highlighting. They are optimized for quick rehighlighting of the same text with minor changes made
func (*Highlighter) ReHighlightLine ¶
func (h *Highlighter) ReHighlightLine(input LineStates, lineN int)
ReHighlightLine will rehighlight the state and match for a single line
func (*Highlighter) ReHighlightStates ¶
func (h *Highlighter) ReHighlightStates(input LineStates, startline int)
ReHighlightStates will scan down from `startline` and set the appropriate end of line state for each line until it comes across the same state in two consecutive lines
type LineMatch ¶
LineMatch represents the syntax highlighting matches for one line. Each index where the coloring is changed is marked with that color's group (represented as one byte)
Source Files