Unreleased APIs from PR #2. Not in 0.2.1. Stable 0.2.1 reference.
LOOM Unreleased (PR #2) / TEXT, MARKDOWN, AND EDITING
TextDocument
Each entry has a stable identity, cached layout, and display options. Visible entries are separated by a blank row. Appending/replacing rebuilds affected layouts; resize and restyle rebuild all entries. Hiding removes display rows but retains the source and identity. Collapsing substitutes a summary. Missing IDs usually yield nil, false, or a no-op. Selection coordinates use document rows; subtract viewport origin and add scroll before querying. clear removes entries without reusing previous identities.
Standard inherited Swift protocol operations such as synthesized equality and OptionSet set operations are not repeated. The public declarations below are extracted from the exact source revision listed in the coverage manifest.
Example
var document = TextDocument(width: 60)
let id = document.append("First message", wrapping: .word)
document.replace(id, with: [TextSpan("Updated message")])
document.setCollapsed(true, for: id)
_ = DocumentView(document)Members on this page
Feature guides and release status
TextDocument
struct TextDocumentConforms to: Swift.Sendable, Swift.SendableMetatype.
Cached entry layouts used for drawing, scrolling, selection, and navigation.
Appending or replacing text rebuilds only the affected entry. Scrolling and selection reuse cached geometry. Entry IDs survive reflow and folding.
Source · TextDocument.swift:17layouts
var layouts: [TextLayout] { get }Cached layouts, in entry order, including hidden entries.
Source · TextDocument.swift:18starts
var starts: [Int] { get }Document row offsets corresponding to entry layouts.
Source · TextDocument.swift:19width
var width: Int { get }Width in terminal cells.
Source · TextDocument.swift:20layoutBuildCount
var layoutBuildCount: Int { get }Cumulative count of entry layout builds, useful for diagnostics.
Source · TextDocument.swift:21rowCount
var rowCount: Int { get }Total visible document rows, including entry separation.
Source · TextDocument.swift:45init(width:)
init(width: Int)Creates a value with the supplied arguments. Default arguments are shown in the declaration.
Parameters (1)
width- Available columns in terminal cells.
append(_:wrapping:options:)
@discardableResult mutating func append(_ text: String, wrapping: TextWrapping = .grapheme, options: TextWrapOptions = TextWrapOptions()) -> TextDocumentEntryIDAppends an entry, separated from its predecessor by one blank row.
Parameters (3)
text- Source text.
wrapping- Grapheme or word wrapping policy.
options- Terminal policies selected when opening.
Returns TextDocumentEntryID.
append(_:background:wrapping:verticalPadding:options:)
@discardableResult mutating func append(_ spans: [TextSpan], background: Color = .terminalDefault, wrapping: TextWrapping = .grapheme, verticalPadding: Int = 0, options: TextWrapOptions = TextWrapOptions()) -> TextDocumentEntryIDAppends styled text and returns a stable identity for later updates.
Parameters (5)
spans- Styled source spans, in order.
background- Argument type and any default are shown in the declaration; see the behavior notes above.
wrapping- Grapheme or word wrapping policy.
verticalPadding- Argument type and any default are shown in the declaration; see the behavior notes above.
options- Terminal policies selected when opening.
Returns TextDocumentEntryID.
insert(_:before:background:wrapping:options:)
@discardableResult mutating func insert(_ spans: [TextSpan], before target: TextDocumentEntryID, background: Color = .terminalDefault, wrapping: TextWrapping = .grapheme, options: TextWrapOptions = TextWrapOptions()) -> TextDocumentEntryID?Inserts styled text before an existing entry without changing any existing identities.
Parameters (5)
spans- Styled source spans, in order.
before- Argument type and any default are shown in the declaration; see the behavior notes above.
background- Argument type and any default are shown in the declaration; see the behavior notes above.
wrapping- Grapheme or word wrapping policy.
options- Terminal policies selected when opening.
Returns TextDocumentEntryID?.
remove(_:)
mutating func remove(_ id: TextDocumentEntryID)Removes an entry while leaving every other entry identity unchanged.
Parameters (1)
id- Stable entry/icon identity, not an array index.
replaceLast(_:)
mutating func replaceLast(_ text: String)Replaces the last entry, or appends it when the document is empty.
Parameters (1)
text- Source text.
replaceLast(_:)
mutating func replaceLast(_ spans: [TextSpan])Replaces the last entry while retaining its background, wrapping, and identity.
Parameters (1)
spans- Styled source spans, in order.
replace(_:with:)
mutating func replace(_ id: TextDocumentEntryID, with spans: [TextSpan])Replaces one entry without changing its identity or collapse state.
Parameters (2)
id- Stable entry/icon identity, not an array index.
with- Argument type and any default are shown in the declaration; see the behavior notes above.
setVerticalPadding(_:for:)
mutating func setVerticalPadding(_ rows: Int, for id: TextDocumentEntryID)Changes presentation spacing without changing source text or entry identity.
Parameters (2)
rows- Row count or signed row movement, according to the method.
for- Argument type and any default are shown in the declaration; see the behavior notes above.
setWidthLimit(_:for:)
mutating func setWidthLimit(_ columns: Int?, for id: TextDocumentEntryID)Caps an entry's wrapping width independently of the document viewport.
Parameters (2)
columns- Cell-column count or signed column movement, according to the method.
for- Argument type and any default are shown in the declaration; see the behavior notes above.
setTrailingReservedColumns(_:for:)
mutating func setTrailingReservedColumns(_ columns: Int, for id: TextDocumentEntryID)Reserves terminal cells at the right edge when wrapping an entry.
The reservation follows document resizes and never changes the selectable source.
Parameters (2)
columns- Cell-column count or signed column movement, according to the method.
for- Argument type and any default are shown in the declaration; see the behavior notes above.
setDisplayPrefix(_:continuation:for:)
mutating func setDisplayPrefix(_ prefix: TextSpan, continuation: String, for id: TextDocumentEntryID)Adds a visible, non-copyable prefix to each display line of an entry.
Wrapped and explicit new lines use the continuation prefix. The stored spans, search text, and copied selections remain the original source.
Parameters (3)
prefix- Argument type and any default are shown in the declaration; see the behavior notes above.
continuation- Argument type and any default are shown in the declaration; see the behavior notes above.
for- Argument type and any default are shown in the declaration; see the behavior notes above.
setCollapsed(_:for:summary:)
mutating func setCollapsed(_ collapsed: Bool, for id: TextDocumentEntryID, summary: [TextSpan] = [TextSpan("▶ Collapsed")])Shows a one-line summary in place of an entry while retaining its full source.
Parameters (3)
collapsed- Argument type and any default are shown in the declaration; see the behavior notes above.
for- Argument type and any default are shown in the declaration; see the behavior notes above.
summary- Argument type and any default are shown in the declaration; see the behavior notes above.
isCollapsed(_:)
func isCollapsed(_ id: TextDocumentEntryID) -> BoolReports whether the entry is currently represented by a summary.
Parameters (1)
id- Stable entry/icon identity, not an array index.
Returns Bool.
setTailPreview(_:for:reservedHeaderRows:omissionStyle:)
mutating func setTailPreview(_ rows: Int?, for id: TextDocumentEntryID, reservedHeaderRows: Int = 0, omissionStyle: Style? = nil)Limits expanded presentation to the last wrapped rows; nil restores all rows.
Full source remains available through spans and search, including after resize.
Parameters (4)
rows- Row count or signed row movement, according to the method.
for- Argument type and any default are shown in the declaration; see the behavior notes above.
reservedHeaderRows- Argument type and any default are shown in the declaration; see the behavior notes above.
omissionStyle- Argument type and any default are shown in the declaration; see the behavior notes above.
setHeadPreview(_:for:)
mutating func setHeadPreview(_ rows: Int?, for id: TextDocumentEntryID)Limits a prompt to its first wrapped rows while retaining its full source and padding.
Parameters (2)
rows- Row count or signed row movement, according to the method.
for- Argument type and any default are shown in the declaration; see the behavior notes above.
hasHeadPreview(_:)
func hasHeadPreview(_ id: TextDocumentEntryID) -> BoolReturns true if the entry has a configured head-row limit; false for a missing ID.
Parameters (1)
id- Stable entry/icon identity, not an array index.
Returns Bool.
entryID(at:)
func entryID(at row: Int) -> TextDocumentEntryID?Returns the entry that contains or immediately precedes a document row.
Parameters (1)
at- Argument type and any default are shown in the declaration; see the behavior notes above.
Returns TextDocumentEntryID?.
entryID(atIndex:)
func entryID(atIndex index: Int) -> TextDocumentEntryID?Returns the identity at a layout index, including hidden entries.
Parameters (1)
atIndex- Argument type and any default are shown in the declaration; see the behavior notes above.
Returns TextDocumentEntryID?.
row(for:)
func row(for id: TextDocumentEntryID) -> Int?Returns the current first row for an entry identity.
Parameters (1)
for- Argument type and any default are shown in the declaration; see the behavior notes above.
Returns Int?.
entryIndex(for:)
func entryIndex(for id: TextDocumentEntryID) -> Int?Returns an entry's position even when its rows are hidden.
Parameters (1)
for- Argument type and any default are shown in the declaration; see the behavior notes above.
Returns Int?.
spans(for:)
func spans(for id: TextDocumentEntryID) -> [TextSpan]?Returns the full styled content, including when the entry is collapsed.
Parameters (1)
for- Argument type and any default are shown in the declaration; see the behavior notes above.
Returns [TextSpan]?.
wrapping(for:)
func wrapping(for id: TextDocumentEntryID) -> TextWrapping?Returns the entry's wrapping policy.
Parameters (1)
for- Argument type and any default are shown in the declaration; see the behavior notes above.
Returns TextWrapping?.
find(_:after:)
func find(_ query: String, after row: Int = -1) -> TextDocumentEntryID?Finds the next entry containing text, wrapping around at the end.
Search covers the full source of collapsed entries. The caller can expand a found entry before showing its contents.
Parameters (2)
query- Text to search for.
after- Argument type and any default are shown in the declaration; see the behavior notes above.
Returns TextDocumentEntryID?.
resize(width:)
mutating func resize(width: Int)Reflows all entries when the available width changes.
Parameters (1)
width- Available columns in terminal cells.
restyle(style:background:)
mutating func restyle(style transformStyle: (Style) -> Style, background transformBackground: (Color) -> Color)Restyles cached source and collapsed summaries without changing entry identities or text metadata.
A theme change must rebuild layouts already on screen. This also retains folding, tail previews, wrapping, links, and code-block source for later expansion and copying.
Parameters (2)
style- Text/cell appearance.
background- Argument type and any default are shown in the declaration; see the behavior notes above.
clear()
mutating func clear()Removes entries and cached layout/start arrays. Keeps the document width, build counter, and next identity counter.
Source · TextDocument.swift:337selectedText(_:)
func selectedText(_ selection: TextSelection) -> StringCopies visible source text across entries, retaining their separation.
Parameters (1)
selection- Selection using the containing type’s coordinate convention.
Returns String.
wordSelection(at:)
func wordSelection(at point: Point) -> TextSelection?Finds a word under a document cell, retaining entry-relative wrapping and padding.
Parameters (1)
at- Argument type and any default are shown in the declaration; see the behavior notes above.
Returns TextSelection?.
paragraphSelection(at:)
func paragraphSelection(at point: Point) -> TextSelection?Finds a source paragraph under a document cell, even when it soft-wraps.
Parameters (1)
at- Argument type and any default are shown in the declaration; see the behavior notes above.
Returns TextSelection?.
paint(in:scroll:selection:buffer:)
func paint(in area: Rect, scroll: Int, selection: TextSelection?, buffer: inout Buffer)Draws the visible document rows into the supplied area.
Parameters (4)
in- Argument type and any default are shown in the declaration; see the behavior notes above.
scroll- Number of document/layout rows skipped above the viewport.
selection- Selection using the containing type’s coordinate convention.
buffer- Mutable destination cell grid.