doc

Documentation

Overview

Package doc provides the language-neutral document model used by the Glippy formatter. The Phase 0 surface is intentionally small while the renderer's bounded behavior is proven.

Index

• type Arena
  • func NewArena() *Arena
  • func NewArenaWithCapacity(capacity int) *Arena
  • func (a *Arena) BreakParent() ID
  • func (a *Arena) Concat(parts ...ID) ID
  • func (a *Arena) Empty() ID
  • func (a *Arena) Group(body ID) ID
  • func (a *Arena) GroupWithIndependentTail(body, lookahead, tail ID) ID
  • func (a *Arena) HardLine() ID
  • func (a *Arena) IfBreak(broken, flat ID) ID
  • func (a *Arena) Indent(body ID) ID
  • func (a *Arena) Line() ID
  • func (a *Arena) LineSuffix(body ID) ID
  • func (a *Arena) LineSuffixBoundary() ID
  • func (a *Arena) Render(root ID, options Options) (string, error)
  • func (a *Arena) RenderWithMarkers(root ID, options Options) (RenderResult, error)
  • func (a *Arena) SoftLine() ID
  • func (a *Arena) SourceMarker(mark SourceMark) ID
  • func (a *Arena) Text(value string) ID
  • func (a *Arena) Verbatim(value string) ID
• type ID
• type Options
• type RenderResult
• type RenderedMarker
• type SourceMark

Types

type Arena

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

Arena owns document nodes. Nodes never change after they are appended, so a completed document may be rendered concurrently while the Arena is no longer being built.

func NewArena

func NewArena() *Arena

NewArena constructs an Arena containing the shared empty document.

func NewArenaWithCapacity

func NewArenaWithCapacity(capacity int) *Arena

NewArenaWithCapacity constructs an Arena with a caller-supplied node capacity hint. The hint changes allocation only; it does not limit growth.

func (*Arena) BreakParent

func (a *Arena) BreakParent() ID

BreakParent prevents an enclosing group from selecting its flat form.

func (*Arena) Concat

func (a *Arena) Concat(parts ...ID) ID

Concat returns the ordered concatenation of parts.

func (*Arena) Empty

func (a *Arena) Empty() ID

Empty returns a document that emits no content.

func (*Arena) Group

func (a *Arena) Group(body ID) ID

Group selects a flat form when it fits and a broken form otherwise.

func (*Arena) GroupWithIndependentTail

func (a *Arena) GroupWithIndependentTail(body, lookahead, tail ID) ID

GroupWithIndependentTail selects body layout using only body and lookahead, then renders tail with an independent layout decision. A broken body gives tail one continuation indentation level.

func (*Arena) HardLine

func (a *Arena) HardLine() ID

HardLine always emits a newline and prevents an enclosing group from flattening across it.

func (*Arena) IfBreak

func (a *Arena) IfBreak(broken, flat ID) ID

IfBreak selects broken when the current group is broken and flat otherwise.

func (*Arena) Indent

func (a *Arena) Indent(body ID) ID

Indent increases logical indentation after line breaks within body.

func (*Arena) Line

func (a *Arena) Line() ID

Line emits one space in flat mode and a newline in broken mode.

func (*Arena) LineSuffix

func (a *Arena) LineSuffix(body ID) ID

LineSuffix defers body until immediately before the next rendered line boundary or the end of the document.

func (*Arena) LineSuffixBoundary

func (a *Arena) LineSuffixBoundary() ID

LineSuffixBoundary emits a line boundary when a suffix is pending.

func (*Arena) Render

func (a *Arena) Render(root ID, options Options) (string, error)

Render renders root without backtracking. Fit simulation is capped by the configured command budget; exhausting the budget chooses a conservative broken layout.

func (*Arena) RenderWithMarkers

func (a *Arena) RenderWithMarkers(root ID, options Options) (RenderResult, error)

RenderWithMarkers renders root and returns physical source-to-output marker mappings. Output offsets are bytes.

func (*Arena) SoftLine

func (a *Arena) SoftLine() ID

SoftLine emits nothing in flat mode and a newline in broken mode.

func (*Arena) SourceMarker

func (a *Arena) SourceMarker(mark SourceMark) ID

SourceMarker records the current rendered byte offset without emitting text.

func (*Arena) Text

func (a *Arena) Text(value string) ID

Text returns a literal text document.

func (*Arena) Verbatim

func (a *Arena) Verbatim(value string) ID

Verbatim returns content whose bytes, including embedded newlines, are emitted exactly. It is used for source tokens such as multiline raw strings, not for ordinary layout text.

type ID

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

ID identifies an immutable document node owned by one Arena.

type Options

type Options struct {
	Width     int
	TabWidth  int
	FitBudget int
}

Options controls deterministic rendering.

type RenderResult

type RenderResult struct {
	Text    string
	Markers []RenderedMarker
}

RenderResult contains rendered text and ordered source marker mappings.

type RenderedMarker

type RenderedMarker struct {
	Source       SourceMark
	OutputOffset int
}

RenderedMarker maps a source marker to a byte offset in rendered output.

type SourceMark

type SourceMark struct {
	Offset int
}

SourceMark identifies a physical source offset carried through rendering.