source

package
v0.10.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 13, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package source owns the original encoded bytes used by the YAML engine.

It is the source/decoder checkpoint of wiki spec 0008 (D3, D78, D79 and D182), not a YAML parser. The existing public package is not yet wired to this engine. Buffers are immutable; returned byte slices are copies. Admission requires an explicit byte limit until measured public defaults have been approved.

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrEncoding identifies malformed original code units, not scalar errors.
	ErrEncoding = errors.NewSentinel("yamldoc.source.encoding", "invalid source encoding")
	// ErrVersion identifies an unsupported coordinate line-break convention.
	ErrVersion = errors.NewSentinel("yamldoc.source.version", "invalid source language version")
	// ErrCursor identifies an uninitialized cursor.
	ErrCursor = errors.NewSentinel("yamldoc.source.cursor", "uninitialized source cursor")
)
View Source
var (
	// ErrInputLimit identifies refusal before source ownership is acquired.
	ErrInputLimit = errors.NewSentinel("yamldoc.source.input_limit", "source exceeds byte limit")
	// ErrInvalidLimit identifies an absent or nonpositive admission budget.
	ErrInvalidLimit = errors.NewSentinel("yamldoc.source.invalid_limit", "source byte limit must be positive")
	// ErrSpan identifies a range outside the retained source.
	ErrSpan = errors.NewSentinel("yamldoc.source.span", "invalid source byte span")
)
View Source
var ErrEncode = errors.NewSentinel("yamldoc.source.encode", "invalid text or replacement encoding")

Functions

func Encode

func Encode(text string, encoding Encoding, limit int) ([]byte, error)

Encode returns replacement code units without introducing a byte-order mark. It checks the exact output size before allocation. YAML lexical escaping is a renderer responsibility; this operation only converts valid Unicode text.

Types

type Buffer

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

Buffer retains source independently of caller-owned memory.

func New

func New(input []byte, maxBytes int) (*Buffer, error)

New admits and copies input. maxBytes is the caller's source-byte budget.

func (*Buffer) Bytes

func (b *Buffer) Bytes() []byte

Bytes returns an independent copy, including the preamble and all trivia.

func (*Buffer) Cursor

func (b *Buffer) Cursor(version Version) (*Cursor, error)

Cursor starts after the encoding preamble, which is not a text column.

func (*Buffer) Encoding

func (b *Buffer) Encoding() Encoding

Encoding reports the detected source encoding without rewriting its bytes.

func (*Buffer) Len

func (b *Buffer) Len() int

Len reports retained encoded bytes without materializing a copy.

func (*Buffer) Preamble

func (b *Buffer) Preamble() Span

Preamble returns the original encoding marker's span, empty when unmarked.

func (*Buffer) Slice

func (b *Buffer) Slice(span Span) ([]byte, error)

Slice copies an original byte range without decoding or normalizing it.

func (*Buffer) View

func (b *Buffer) View(span Span) ([]byte, error)

View is Slice without the copy, for a reader that only inspects the bytes and never retains or writes them; the buffer is immutable, the slice aliases it.

type Character

type Character struct {
	Rune       rune
	Span       Span
	Start, End Position
}

Character describes one decoded source character, without scalar interpretation.

type Cursor

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

Cursor decodes incrementally without retaining a second copy of the text. Separate cursors may read a Buffer concurrently; one cursor is not shared.

func (*Cursor) Bytes

func (c *Cursor) Bytes(span Span) ([]byte, error)

Bytes copies an original source range from this cursor's owned buffer snapshot, without advancing it or exposing the caller's replaceable Buffer handle.

func (*Cursor) Next

func (c *Cursor) Next() (Character, error)

Next returns the next character, io.EOF, or an encoding error without repair.

func (*Cursor) Relocate

func (c *Cursor) Relocate(buffer *Buffer, offset int, position Position) (Cursor, error)

Relocate copies a cursor onto a planned revision's buffer at known coordinates. Returning the cursor by value avoids a temporary heap allocation per token. It preserves language and CRLF state. This checks range admission, not whether the supplied position matches a fresh decode; commit validation establishes that.

func (*Cursor) RelocateOnto

func (c *Cursor) RelocateOnto(buffer *Buffer, offset int, position Position) (Cursor, error)

RelocateOnto is Relocate without the defensive copy: the caller owns buffer, never writes it, and keeps it for the cursor's lifetime. A reviser relocating every token of a file onto one private snapshot uses it; the copy per token was the largest allocation of a working revision.

func (*Cursor) Run

func (c *Cursor) Run(accept func(byte) bool) int

Run advances over consecutive UTF-8 ASCII bytes accepted by the predicate, each one column and never a line break, and returns the count. It is the scanner's fast path through the body of a plain scalar; a rune that needs decoding, or a byte the predicate refuses, ends the run untouched. The predicate must refuse '\r' and '\n' so the position stays right.

func (*Cursor) SetVersion

func (c *Cursor) SetVersion(version Version) error

SetVersion changes the convention for unread characters only. Prior source coordinates and CRLF state survive; copied cursors retain their own version. Invalid selection leaves the cursor unchanged and never clears a failure.

func (*Cursor) View

func (c *Cursor) View(span Span) ([]byte, error)

View is Bytes without the copy; see Buffer.View.

type Encoding

type Encoding uint8

Encoding identifies the original code-unit representation.

const (
	UTF8 Encoding = iota
	UTF16LE
	UTF16BE
	UTF32LE
	UTF32BE
)

The supported encodings cover the YAML 1.1/1.2 input encoding repertoire.

func (Encoding) String

func (e Encoding) String() string

type Fault

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

Fault retains admitted source after decoding fails. Its lifetime can retain the whole input; accessors expose copies, not mutable inspection state.

func (*Fault) Bytes

func (f *Fault) Bytes() []byte

Bytes returns an independent copy of the entire admitted source.

func (*Fault) Error

func (f *Fault) Error() string

func (*Fault) Location

func (f *Fault) Location() Location

Location returns the byte range and only the coordinates known reliably.

func (*Fault) Unwrap

func (f *Fault) Unwrap() error

Unwrap preserves the in-house error identity for inspection.

type Location

type Location struct {
	Span             Span
	Start, End       Position
	HasStart, HasEnd bool
}

Location distinguishes reliable source coordinates from unavailable ones. Byte spans always refer to existing original bytes, including any preamble.

type Position

type Position struct{ Line, Column int }

Position counts one-based source lines and Unicode code-point columns.

type Span

type Span struct{ Start, End int }

Span is an inclusive-start, exclusive-end range of original encoded bytes.

func (Span) Contains

func (s Span) Contains(other Span) bool

Contains reports whether other lies entirely within s.

type Version

type Version uint8

Version selects the grammar's source line-break convention.

const (
	YAML11 Version = 11
	YAML12 Version = 12
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL