Documentation
¶
Overview ¶
Package codeview composes the egui2 CodeViewJob primitive with the project's SQL, JSON, and Go highlighters into a small set of retained- holder builders. The three highlighters share the same shape — palette intern at init → run highlighter → emit one CodeViewJob.Section per span → Keep — so they live in one package.
Naming convention: Build* re-tokenises every call; Prepare* memoises, returning the same retained holder for a source it has already seen (ADR-0125). The two were once the same function with the distinction living in this comment, which read as though Prepare* were cached and cost four call sites a full re-highlight per frame.
Reach for Prepare* by default — a probe is 30 ns for a query against 129 µs to re-parse it, and SQL is the expensive case (highlight.Highlight runs a full nanopass.Parse, not a lex). Reach for Build* when the work is one-shot, or when the caller already holds a cheaper key than the source text and its own cache: play's detail pane keys on (result, row) because it must cache a parsed markdown tree and decoded image pixels anyway, and hashing a megabyte-sized cell per frame would be the more expensive half.
The memo is bounded by a byte budget and is safe for concurrent use; builds run outside its lock. See memo.go.
The Go view additionally exposes BuildGoLines / PrepareGoLines, which render a byte slice covering a 1-based [firstLine, lastLine] window with a right-aligned line-number gutter. The line-window machinery is internally generic; SQL/JSON equivalents can be added when a caller needs them.
Index ¶
- Variables
- func BuildGo(src string) typed.RetainedFffiHolderTyped[c.CodeViewJobS]
- func BuildGoLines(src string, firstLine int32, lastLine int32) typed.RetainedFffiHolderTyped[c.CodeViewJobS]
- func BuildJson(src string) typed.RetainedFffiHolderTyped[c.CodeViewJobS]
- func BuildMarkdown(src string) typed.RetainedFffiHolderTyped[c.CodeViewJobS]
- func BuildRegex(src string) typed.RetainedFffiHolderTyped[c.CodeViewJobS]
- func BuildRegexList(src string) typed.RetainedFffiHolderTyped[c.CodeViewJobS]
- func BuildSql(sql string) typed.RetainedFffiHolderTyped[c.CodeViewJobS]
- func BuildSqlFromSpans(sql string, spans []highlight.Span) typed.RetainedFffiHolderTyped[c.CodeViewJobS]
- func BuildSqlLex(sql string) typed.RetainedFffiHolderTyped[c.CodeViewJobS]
- func BuildStyledSections(secs []StyledSection) (job typed.RetainedFffiHolderTyped[c.StyledSectionsS], ok bool)
- func PrepareGo(src string) typed.RetainedFffiHolderTyped[c.CodeViewJobS]
- func PrepareGoLines(src string, firstLine int32, lastLine int32) typed.RetainedFffiHolderTyped[c.CodeViewJobS]
- func PrepareJson(src string) typed.RetainedFffiHolderTyped[c.CodeViewJobS]
- func PrepareMarkdown(src string) typed.RetainedFffiHolderTyped[c.CodeViewJobS]
- func PrepareRegex(src string) typed.RetainedFffiHolderTyped[c.CodeViewJobS]
- func PrepareRegexList(src string) typed.RetainedFffiHolderTyped[c.CodeViewJobS]
- func PrepareSql(sql string) typed.RetainedFffiHolderTyped[c.CodeViewJobS]
- type StyleFlagE
- type StyledSection
Constants ¶
This section is empty.
Variables ¶
var PackageProps = packageprops.Props{ WASMWASI: packageprops.WASMBlocked, WASMJS: packageprops.WASMBlocked, WASMFreestanding: packageprops.WASMCompiles, }
PackageProps records this package's curated properties (ADR-0080). Seeded by `wasmsurvey props generate`; curate by hand, then `wasmsurvey props verify`.
Functions ¶
func BuildGo ¶
func BuildGo(src string) typed.RetainedFffiHolderTyped[c.CodeViewJobS]
BuildGo highlights Go source and returns a retained CodeViewJob. Every call re-highlights — use it for one-shot work, or when you already hold a cheaper key than the source text. Use PrepareGo otherwise.
func BuildGoLines ¶
func BuildGoLines(src string, firstLine int32, lastLine int32) typed.RetainedFffiHolderTyped[c.CodeViewJobS]
BuildGoLines highlights src and renders the byte slice covering 1-based lines [firstLine, lastLine] (inclusive) with a right-aligned line-number gutter prefixed to each line. The full source is parsed so AST refinement applies — spans that cross the window boundary are clipped at the edges.
firstLine/lastLine are clamped to the source's line range. An out-of-bounds window returns an empty retained holder.
func BuildJson ¶
func BuildJson(src string) typed.RetainedFffiHolderTyped[c.CodeViewJobS]
BuildJson highlights JSON and returns a retained CodeViewJob. Every call re-tokenises — use it for one-shot work, or when you already hold a cheaper key than the source text. Use PrepareJson otherwise.
func BuildMarkdown ¶
func BuildMarkdown(src string) typed.RetainedFffiHolderTyped[c.CodeViewJobS]
BuildMarkdown canonicalises and highlights markdown source, returning a retained CodeViewJob. Each call re-renders; use PrepareMarkdown for static documents.
IMPORTANT: the rendered text is a *canonical* form of the input, not the source verbatim. gofmt-style: lists become `-`, emphasis becomes `*` / `**`, frontmatter keys sort alphabetically, indented code blocks lose their 4-space marker. The text displayed in the CodeView is what this function returns, not what was passed in. See package markdownhighlight for the full canonicalisation rules.
func BuildRegex ¶ added in v0.0.17
func BuildRegex(src string) typed.RetainedFffiHolderTyped[c.CodeViewJobS]
BuildRegex highlights one RE2 pattern and returns a retained CodeViewJob. Every call re-lexes.
This is the per-keystroke span source for the ADR-0130 editor path (TextEdit.HighlightJob), and it is deliberately uncached for the same reason as BuildSqlLex: editor content is new on every keystroke, so the ADR-0125 memo would only churn. Unlike the read-only builders, no tab expansion is applied — the job's text must equal the editor buffer byte-for-byte for the Rust-side reconcile to line up.
There is no semantic/async second tier here (ADR-0015 §SD4): the lexer is O(n) over a pattern of tens of bytes, orders of magnitude below the SQL parse that forced ADR-0130's split.
func BuildRegexList ¶ added in v0.0.17
func BuildRegexList(src string) typed.RetainedFffiHolderTyped[c.CodeViewJobS]
BuildRegexList highlights a newline-separated *list* of RE2 patterns — one independent pattern per line, with group depth reset at each newline. Every call re-lexes; this is the editor path, see BuildRegex.
Named List rather than Lines on purpose: in this package the `*Lines` suffix means a line-numbered gutter window over one document (BuildGoLines), which is a different operation.
func BuildSql ¶
func BuildSql(sql string) typed.RetainedFffiHolderTyped[c.CodeViewJobS]
BuildSql highlights SQL and returns a retained CodeViewJob. Every call re-tokenises — and SQL is the expensive one: highlight.Highlight runs a full nanopass.Parse plus a CST walk, so this is ~129 µs for a one-line query and ~3.5 ms for a three-line CTE. Use it for one-shot work, or when you already hold a cheaper key than the SQL text. Use PrepareSql otherwise.
func BuildSqlFromSpans ¶ added in v0.0.14
func BuildSqlFromSpans(sql string, spans []highlight.Span) typed.RetainedFffiHolderTyped[c.CodeViewJobS]
BuildSqlFromSpans serializes highlighter spans somebody else already computed into a retained CodeViewJob with the SQL palette. This is the render-thread half of the ADR-0130 L2 split: a background goroutine runs the expensive highlight.Highlight (pure Go, no c.* calls), and the render thread pays only this serialization. `sql` must be the exact text the spans describe — like BuildSqlLex, no tab expansion is applied.
func BuildSqlLex ¶ added in v0.0.14
func BuildSqlLex(sql string) typed.RetainedFffiHolderTyped[c.CodeViewJobS]
BuildSqlLex highlights SQL at the lexical tier only (no parse): keywords, literals, comments, operators, and peek-ahead function names — ~26 µs for a 180 B statement vs ~5.7 ms for the full semantic build. This is the per-keystroke span source for the ADR-0130 editor path (TextEdit.HighlightJob), which is why it is deliberately uncached: editor content is new on every keystroke, so the ADR-0125 memo would only churn.
The job's text must equal the editor buffer byte-for-byte for the Rust-side reconcile to line up, so — unlike the read-only builders — no tab expansion is applied.
func BuildStyledSections ¶ added in v0.0.17
func BuildStyledSections(secs []StyledSection) (job typed.RetainedFffiHolderTyped[c.StyledSectionsS], ok bool)
BuildStyledSections serializes overlays into a retained StyledSections holder for TextEdit.SectionStyled.
Deliberately uncached, like BuildSqlLex: producers rebuild this list per frame from a handful of spans (an error token, the statement under the caret, unfilled placeholders), which is cheap enough that a memo would only churn — and unlike the colour job, the inputs change on caret movement, not only on edits. An empty list returns ok=false so callers can skip the builder method entirely.
func PrepareGo ¶
func PrepareGo(src string) typed.RetainedFffiHolderTyped[c.CodeViewJobS]
PrepareGo highlights Go source through the package memo: the same source prepared again returns the same retained holder without re-highlighting (ADR-0125).
func PrepareGoLines ¶
func PrepareGoLines(src string, firstLine int32, lastLine int32) typed.RetainedFffiHolderTyped[c.CodeViewJobS]
PrepareGoLines renders a line window through the package memo: the same (source, window) prepared again returns the same retained holder without re-highlighting (ADR-0125). The window is part of the key, so two windows over one source are two entries — and neither collides with PrepareGo over that source, which would otherwise serve the whole file for PrepareGoLines(src, 0, 0).
func PrepareJson ¶
func PrepareJson(src string) typed.RetainedFffiHolderTyped[c.CodeViewJobS]
PrepareJson highlights JSON through the package memo: the same source prepared again returns the same retained holder without re-tokenising (ADR-0125).
func PrepareMarkdown ¶
func PrepareMarkdown(src string) typed.RetainedFffiHolderTyped[c.CodeViewJobS]
PrepareMarkdown highlights markdown source through the package memo: the same source prepared again returns the same retained holder without re-tokenising (ADR-0125). The canonicalisation described on BuildMarkdown still applies — the memo caches its result, it does not change it.
func PrepareRegex ¶ added in v0.0.17
func PrepareRegex(src string) typed.RetainedFffiHolderTyped[c.CodeViewJobS]
PrepareRegex highlights one RE2 pattern through the package memo: the same pattern prepared again returns the same retained holder without re-lexing (ADR-0125). Prefer this for read-only surfaces that show the same pattern across frames; use BuildRegex for an editor buffer.
func PrepareRegexList ¶ added in v0.0.17
func PrepareRegexList(src string) typed.RetainedFffiHolderTyped[c.CodeViewJobS]
PrepareRegexList highlights a pattern list through the package memo (ADR-0125). Keyed distinctly from PrepareRegex, so the same source prepared both ways does not serve one lexing for the other.
func PrepareSql ¶
func PrepareSql(sql string) typed.RetainedFffiHolderTyped[c.CodeViewJobS]
PrepareSql highlights SQL through the package memo: the same statement prepared again returns the same retained holder without re-parsing (ADR-0125). Prefer this anywhere the same SQL is shown across frames.
Types ¶
type StyleFlagE ¶ added in v0.0.17
type StyleFlagE uint32
StyleFlagE is the style vocabulary a styled section can express — exactly what egui's TextFormat carries natively (ADR-0130 L3). Flags compose: an error underline inside a tinted statement is two sections over the same bytes, and both reach the color sections they overlap.
A wavy squiggle is deliberately absent: TextFormat cannot express one, and painting over galley rows is deferred until the straight underline proves insufficient in use.
const ( StyleUnderline StyleFlagE = 1 << iota StyleBackground StyleStrikethrough StyleItalics )
type StyledSection ¶ added in v0.0.17
type StyledSection struct {
Start uint32
Stop uint32
Flags StyleFlagE
Color color.Color
}
StyledSection is one sparse overlay over a byte range of the buffer the consuming widget holds. Offsets are byte offsets into that buffer; Color is the stroke color for underline/strikethrough and the fill for background (italics ignores it).
Unlike the colour tier this channel does not have to cover the buffer — uncovered bytes simply carry no styling, and Rust-side normalization drops inverted, empty, and flagless sections rather than gap-filling around them.
Source Files