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 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 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 PrepareSql(sql string) typed.RetainedFffiHolderTyped[c.CodeViewJobS]
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 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 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 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 ¶
This section is empty.
Source Files