Documentation
¶
Overview ¶
Package document is Silk's shared text-document model: the single copy of a file's text that every view of that file agrees on, plus the revision counter, change notifications and stable positions an IDE needs on top of it.
It exists because the editor owns its text per widget. When a tab is split, ged.EditorTabs.ToggleSplit creates a second gui.CodeEditor, copies the primary pane's text into it and cross-wires the two SigChanged callbacks; each pane then keeps its own buffer and the panes drift apart as soon as anything is not a plain full-text echo. With a Document the text lives in one place: no pane owns the truth, each one subscribes with OnChanged and applies the ChangeEvent it is handed.
Conventions:
Offsets are BYTE offsets into Text(). Slicing a string by byte offset is what an edit ultimately does, so callers hand over the offsets they already have; a caller that works in runes converts before calling.
Lines are 0-based, matching gui.CodeEditor's line-keyed maps (breakpoints, bookmarks, coverage, diff markers).
Every edit funnels through Replace: it bumps the revision, remaps the document's AnchorSet, then notifies subscribers. SetText is Replace over the whole text, so there is exactly one change path.
A Document is not safe for concurrent use: like the widgets that own it, it expects to be touched from the UI thread only.
Index ¶
- type Anchor
- type AnchorID
- type AnchorSet
- type ChangeEvent
- type Document
- func (d *Document) Anchors() *AnchorSet
- func (d *Document) IsDirty() bool
- func (d *Document) Len() int
- func (d *Document) LineCount() int
- func (d *Document) LineOf(offset int) int
- func (d *Document) LineStart(line int) int
- func (d *Document) MarkSaved()
- func (d *Document) NewLineAnchor(line int) *LineAnchor
- func (d *Document) OnChanged(fn func(ev ChangeEvent)) func()
- func (d *Document) Replace(start, end int, s string)
- func (d *Document) Revision() int
- func (d *Document) SetText(text string)
- func (d *Document) Text() string
- type LineAnchor
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Anchor ¶
Anchor is a snapshot of one anchor: where it currently sits and whether the text it pointed at has been deleted. It is a value, so reading one out of a set cannot accidentally mutate it.
type AnchorID ¶
type AnchorID int
AnchorID identifies one anchor inside an AnchorSet. Owners keep the id, never a raw offset — the offset is what moves.
type AnchorSet ¶
type AnchorSet struct {
// contains filtered or unexported fields
}
AnchorSet holds positions that stay attached to the text they were created on. Everything an IDE pins to a location — bookmarks, breakpoints, fold regions, diagnostics, a saved caret — is a byte offset that must survive edits made somewhere else in the file, which a plain int cannot do: insert one character above a breakpoint and every raw offset below it is wrong. gui.CodeEditor documents exactly this gap ("breakpoints are NOT re-mapped when lines are inserted/deleted").
Apply moves the whole set through one edit. For an edit that replaced [Start,End) with NewText:
- offset <= Start: unchanged. Left gravity — text inserted at an anchor lands after it, so the anchor keeps pointing at what it pointed at.
- offset >= End: shifted by the edit's Delta.
- Start < offset < End: collapsed to Start and marked Deleted. The text it addressed is gone, so the anchor stays at the edit's start offset and its owner decides whether to drop it or keep showing it.
Deleted is sticky: later edits keep moving the anchor, but nothing clears the flag.
func NewAnchorSet ¶
func NewAnchorSet() *AnchorSet
NewAnchorSet returns an empty set. A zero-value AnchorSet is also usable; Add creates the map on demand.
func (*AnchorSet) Add ¶
Add pins a new anchor at the byte offset (clamped at 0) and returns its id. The set does not know the text length, so the caller is responsible for passing an offset that is inside the document.
func (*AnchorSet) All ¶
All returns every anchor ordered by id, i.e. in creation order. Ordered so callers and tests get a stable list out of the underlying map.
func (*AnchorSet) Apply ¶
func (s *AnchorSet) Apply(ev ChangeEvent)
Apply remaps every anchor through one applied edit, per the rules on AnchorSet. A Document does this for its own set on each Replace; call it directly on a set that is fed from a subscription instead.
type ChangeEvent ¶
ChangeEvent describes one edit that has already been applied to the document. Start and End are byte offsets into the text as it was BEFORE the edit ([Start,End) is the range that went away); NewText is what took its place, and Revision is the document revision after the edit.
An insertion at p is {Start: p, End: p}; a deletion of [a,b) is {Start: a, End: b, NewText: ""}.
func (ChangeEvent) Delta ¶
func (ev ChangeEvent) Delta() int
Delta reports how many bytes the edit added (positive) or removed (negative). Every offset at or after End shifts by exactly this much.
type Document ¶
type Document struct {
// Path is the file this document stands for, kept as handed in (the
// document itself never touches the filesystem). Empty for a scratch
// buffer.
Path string
// contains filtered or unexported fields
}
Document is one file's text shared by every view of it.
The zero value is a usable empty document; New sets a Path and initial text.
func New ¶
New returns a document holding text, tagged with path. The result is clean: revision 0 is treated as the saved state, so freshly loaded text is not dirty.
func (*Document) Anchors ¶
Anchors returns the document's anchor set. Every Replace remaps it, so positions registered here follow the text without the owner wiring anything up.
func (*Document) LineCount ¶
LineCount returns the number of lines, counting the empty last line that a trailing newline creates. An empty document has one line.
func (*Document) LineOf ¶
LineOf returns the 0-based line containing the byte offset. A newline belongs to the line it terminates, and the offset is clamped into the document first.
func (*Document) LineStart ¶
LineStart returns the byte offset at which the 0-based line begins. Out-of-range lines clamp: a negative line gives 0, a line past the last gives the document length.
func (*Document) MarkSaved ¶
func (d *Document) MarkSaved()
MarkSaved records that the current text is what sits on disk, clearing the dirty flag. Call it after a successful write.
func (*Document) NewLineAnchor ¶
func (d *Document) NewLineAnchor(line int) *LineAnchor
NewLineAnchor pins an anchor to the start of the 0-based line and returns the handle. The anchor lives in the document's own AnchorSet, so it is remapped by every Replace.
func (*Document) OnChanged ¶
func (d *Document) OnChanged(fn func(ev ChangeEvent)) func()
OnChanged subscribes fn to every applied edit and returns the function that cancels the subscription. Handlers run in registration order, after the text and the anchors have been updated, so a handler sees the new state through Text() and Anchors().
Cancelling is idempotent and safe from inside a handler. A view MUST cancel when it goes away — the leak the split editor works around today by saving and restoring the previous callback.
func (*Document) Replace ¶
Replace is the document's one edit primitive: it drops the byte range [start,end) and puts s in its place, which covers insertion (start == end), deletion (s == "") and replacement in a single compound step. One revision, one ChangeEvent, one anchor remap — an editor that expressed a replacement as delete-then-insert would move anchors twice and let subscribers observe an intermediate text that never really existed.
The range is forgiving: it is ordered if reversed and clamped to the document, so a stale offset cannot panic. An edit that would not change the text is dropped: the revision does not move, no event is sent, and anchors stay put (a replacement by identical text has not deleted anything).
func (*Document) Revision ¶
Revision returns the number of edits applied to the document. It only ever grows, so a view can cheaply tell whether it is looking at stale text by remembering the revision it last rendered.
func (*Document) SetText ¶
SetText replaces the entire document with text. It is Replace over the full range, so subscribers see one ChangeEvent and anchors are remapped by the usual rules — which means anchors strictly inside the old text collapse to offset 0 and are marked deleted. Callers that reload a file and want line-keyed marks back should re-create them from the new text.
Setting the text it already has is a no-op.
type LineAnchor ¶
type LineAnchor struct {
// contains filtered or unexported fields
}
LineAnchor is a line-keyed anchor: an anchor pinned to the start of a line, which reports the line it has drifted to rather than an offset. Bookmarks and breakpoints are line-keyed, so this is the shape they want — store a LineAnchor instead of an int and ask Line() when rendering.
Because it sits at the line's START offset, deleting the whole line leaves the anchor at the start of the following line: the mark survives and is not flagged Deleted (that flag is for an anchor swallowed strictly inside a deleted range). An owner that would rather drop such a mark can compare Line() before and after the edit.
func (*LineAnchor) Deleted ¶
func (a *LineAnchor) Deleted() bool
Deleted reports whether the anchor was swallowed by a deletion, or has been removed from the set outright.
func (*LineAnchor) ID ¶
func (a *LineAnchor) ID() AnchorID
ID returns the underlying anchor id in the document's AnchorSet.
func (*LineAnchor) Line ¶
func (a *LineAnchor) Line() int
Line returns the 0-based line the anchor now sits on, or -1 once the anchor has been removed from the set.
func (*LineAnchor) Offset ¶
func (a *LineAnchor) Offset() int
Offset returns the anchor's current byte offset, or -1 once it has been removed.
func (*LineAnchor) Remove ¶
func (a *LineAnchor) Remove()
Remove drops the anchor from the document's set. Call it when the mark it backs is deleted, otherwise the set grows for the life of the document.