rougelex

Documentation

Overview

Package rougelex is the batteries-included syntax highlighter for github.com/go-widgets/toolkit's CodeEditor, backed by the pure-Go github.com/go-rouge/rouge lexers (Go, Ruby, Python, JavaScript, CSS, HTML, JSON, YAML, SQL, shell, Markdown, LaTeX, diff, …).

It lives in its own module so importing the core toolkit never pulls a lexing engine — and its transitive regexp dependency — into a consumer that only wants buttons and boxes. A code surface opts in with a single import:

ed := toolkit.NewCodeEditor(src)
ed.Language = "go"
ed.Syntax = rougelex.New()

The highlighter maps rouge's token stream onto a small Palette of ink colours. The zero-value Palette derives its colours from the theme handed to Highlight, so an editor colours itself consistently with the surrounding UI; set an explicit Palette to pin a fixed scheme. A set of shared named schemes (Monokai, Solarized, GitHub, Dracula, plus the theme-derived "Default") is available via ThemeNames and PaletteByName for a scheme picker:

pal, _ := rougelex.PaletteByName("Monokai")
ed.Syntax = &rougelex.Highlighter{Palette: pal}

Index

• func ThemeNames() []string
• type Highlighter
  • func New() *Highlighter
  • func (h *Highlighter) Highlight(language string, lines []string, theme *toolkit.Theme) [][]toolkit.TextSpan
• type Palette
  • func DefaultPalette(theme *toolkit.Theme) Palette
  • func PaletteByName(name string) (Palette, bool)

Functions

func ThemeNames

func ThemeNames() []string

ThemeNames returns the shared palette names in display order, with the theme-derived "Default" first. It mirrors the ordered set a scheme picker walks to build its menu.

Types

type Highlighter

type Highlighter struct {
	// Palette overrides the token colours. When it is the zero value the
	// colours are derived from the theme passed to Highlight.
	Palette Palette
}

Highlighter is a rouge-backed toolkit.Highlighter. The zero value is usable (equivalent to New()) and colours against the theme; set Palette to pin a fixed scheme.

func New

func New() *Highlighter

New returns a theme-derived rouge highlighter.

func (*Highlighter) Highlight

func (h *Highlighter) Highlight(language string, lines []string, theme *toolkit.Theme) [][]toolkit.TextSpan

Highlight tokenises the buffer with the rouge lexer named by language (an unknown or empty name falls back to plain text, i.e. no colouring) and maps the token stream to per-line TextSpans. Multi-line tokens are split at line breaks so each line receives the spans that fall within it, in that line's rune coordinates.

type Palette

type Palette struct {
	Default     toolkit.RGBA
	Keyword     toolkit.RGBA
	Type        toolkit.RGBA
	Function    toolkit.RGBA
	Class       toolkit.RGBA
	Builtin     toolkit.RGBA
	Tag         toolkit.RGBA
	Variable    toolkit.RGBA
	Attribute   toolkit.RGBA
	String      toolkit.RGBA
	Number      toolkit.RGBA
	Comment     toolkit.RGBA
	Operator    toolkit.RGBA
	Punctuation toolkit.RGBA
}

Palette maps coarse syntactic categories to ink colours. A rouge token is resolved to one of these via its category ancestry (a Name.Function token takes Function, a Literal.String.Double takes String, and so on); anything unmatched takes Default.

Tag, Variable and Attribute cover the Name subtypes that markup, templating and LaTeX lean on: Name.Tag is an HTML/XML element and a LaTeX \begin{env}/\end{env}; Name.Variable is a template/shell variable and a LaTeX math control sequence (\alpha); Name.Attribute is an HTML attribute and a LaTeX command's optional argument ([width=1cm]).

The zero value (every field's alpha 0) is the sentinel for "derive from the theme": Highlight then fills the palette with DefaultPalette(theme).

func DefaultPalette

func DefaultPalette(theme *toolkit.Theme) Palette

DefaultPalette derives a theme-consistent palette from a toolkit theme: keywords take the accent, comments a dimmed ink, strings and numbers an ink/accent blend, and plain names the ordinary ink. Tags and variables read as structural, so they lean toward the accent; attributes lean toward the ink, like strings. It is what Highlight uses when the Highlighter's Palette is the zero value.

func PaletteByName

func PaletteByName(name string) (Palette, bool)

PaletteByName returns the shared Palette registered under name and true, or the zero Palette and false for an unknown name. The "Default" scheme yields the zero Palette (with true): assigned to a Highlighter.Palette it keeps the highlighter theme-derived, exactly as the zero value does; every other scheme yields a fixed, fully-opaque Palette that pins that scheme regardless of the toolkit theme.