source

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Aug 13, 2026 License: 0BSD Imports: 18 Imported by: 0

Documentation

Overview

Package source owns immutable physical Go source units and their lexical reconstruction data.

Index

Constants

View Source 
const MaxFileSize int64 = 64 << 20

MaxFileSize is the largest complete file or physical fragment accepted by the source frontend.

Variables

View Source 
var ErrTooLarge = errors.New("Go source is too large")

ErrTooLarge reports source input that exceeds MaxFileSize.

Functions

func ReadAll 

func ReadAll(reader io.Reader) ([]byte, error)

ReadAll reads one bounded source stream.

func ReadFile 

func ReadFile(path string) ([]byte, error)

ReadFile reads one bounded source file and detects growth beyond the limit.

func ValidateEquivalent 

func ValidateEquivalent(before, after *File) error

ValidateEquivalent verifies the normalized syntax and source-accounting invariants required before formatted output can be accepted.

func ValidateFragmentEquivalent 

func ValidateFragmentEquivalent(before, after *Fragment) error

ValidateFragmentEquivalent verifies normalized syntax and physical source-accounting invariants for two fragments of the same kind.

func ValidateSize 

func ValidateSize(size int64) error

ValidateSize rejects a complete source file or physical fragment that exceeds the shared frontend limit.

Types

type Comment 

type Comment struct {
	ID    CommentID
	Range Range
	Raw   string
}

Comment is one exact physical source comment.

type CommentID 

type CommentID uint32

CommentID is a stable per-file comment identity.

type Digest 

type Digest [sha256.Size]byte

Digest identifies the exact bytes used to construct a File.

type Directive 

type Directive struct {
	Kind  DirectiveKind
	Range Range
	Raw   string
}

Directive is a classified physical source comment.

type DirectiveKind 

type DirectiveKind uint8

DirectiveKind identifies comments whose placement has tool or language semantics. 

const (
	DirectiveBuildConstraint DirectiveKind = iota + 1
	DirectiveGoGenerate
	DirectiveGoEmbed
	DirectiveCompiler
	DirectiveLine
	DirectiveGenerated
	DirectiveGoxSuppression
	DirectiveExternalSuppression
	DirectiveCgoPreamble
)

type File 

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

File is an immutable physical source unit.

func Load 

func Load(path string, input []byte) (*File, error)

Load constructs a physical source unit. Invalid Go returns the lossless diagnostic-only File together with the parse or scan error.

func (*File) Bytes 

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

Bytes returns an independent copy of the physical source bytes.

func (*File) CanFormat 

func (f *File) CanFormat() bool

CanFormat reports whether parsing and physical reconstruction accepted the complete file.

func (*File) Comments 

func (f *File) Comments() []Comment

Comments returns exact source comments with stable per-file identities.

func (*File) Digest 

func (f *File) Digest() Digest

Digest returns the exact source digest.

func (*File) Directives 

func (f *File) Directives() []Directive

Directives returns classified directive comments in physical order.

func (*File) Metadata 

func (f *File) Metadata() Metadata

Metadata returns physical file metadata.

func (*File) Path 

func (f *File) Path() string

Path returns the normalized physical source identity supplied to Load.

func (*File) PhysicalOffset 

func (f *File) PhysicalOffset(position token.Pos) (int, bool)

PhysicalOffset maps a parsed position to the exact source byte offset.

func (*File) Pieces 

func (f *File) Pieces() []Piece

Pieces returns the ordered physical reconstruction ledger.

func (*File) Position 

func (f *File) Position(offset int) (Position, bool)

Position maps a UTF-8 byte boundary to a physical line and byte column.

func (*File) PreviousSignificantToken 

func (f *File) PreviousSignificantToken(position token.Pos) (Token, bool)

PreviousSignificantToken returns the lexical token immediately before a parsed position, ignoring comments and inserted semicolons.

func (*File) RawToken 

func (f *File) RawToken(position token.Pos) (string, bool)

RawToken returns the exact physical spelling of the token at position.

func (*File) ReadSyntax 

func (f *File) ReadSyntax(read func(*ast.File) error) error

ReadSyntax provides an isolated parsed syntax view to a run-owned consumer.

func (*File) ReadSyntaxView 

func (f *File) ReadSyntaxView(read func(*token.FileSet, *ast.File) error) error

ReadSyntaxView provides one isolated syntax tree and its matching file set.

func (*File) Slice 

func (f *File) Slice(sourceRange Range) (string, bool)

Slice returns exact physical source text for a valid byte range.

func (*File) TokenRangeAtOffset 

func (f *File) TokenRangeAtOffset(offset int) (Range, bool)

TokenRangeAtOffset returns the exact lexical token beginning at a physical byte offset without exposing the immutable token ledger.

func (*File) Tokens 

func (f *File) Tokens() []Token

Tokens returns the physical token ledger.

func (*File) Trivia 

func (f *File) Trivia() []Trivia

Trivia returns exact physical token gaps in source order.

type Fragment 

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

Fragment is an immutable physical source fragment parsed through a fixed synthetic Go file. Synthetic wrapper bytes never enter its physical ledger.

func LoadFragment 

func LoadFragment(path string, kind FragmentKind, input []byte) (*Fragment, error)

LoadFragment constructs a physical source fragment using the fixed wrapper for kind. Invalid fragments retain their physical ledger for diagnostics.

func (*Fragment) Bytes 

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

Bytes returns an independent copy of the physical fragment bytes.

func (*Fragment) CanFormat 

func (f *Fragment) CanFormat() bool

CanFormat reports whether parsing and physical reconstruction accepted the selected fragment boundary.

func (*Fragment) Comments 

func (f *Fragment) Comments() []Comment

Comments returns exact physical comments with stable fragment identities.

func (*Fragment) Digest 

func (f *Fragment) Digest() Digest

Digest returns the exact physical fragment digest.

func (*Fragment) Directives 

func (f *Fragment) Directives() []Directive

Directives returns classified physical comment directives.

func (*Fragment) Kind 

func (f *Fragment) Kind() FragmentKind

Kind returns the explicit grammar boundary used to parse the fragment.

func (*Fragment) Metadata 

func (f *Fragment) Metadata() Metadata

Metadata returns physical fragment metadata.

func (*Fragment) Path 

func (f *Fragment) Path() string

Path returns the normalized physical source identity supplied to LoadFragment.

func (*Fragment) PhysicalOffset 

func (f *Fragment) PhysicalOffset(position token.Pos) (int, bool)

PhysicalOffset maps a selected synthetic AST position to the exact fragment byte offset. Wrapper positions are deliberately unmappable.

func (*Fragment) Pieces 

func (f *Fragment) Pieces() []Piece

Pieces returns the physical reconstruction ledger without wrapper bytes.

func (*Fragment) RawToken 

func (f *Fragment) RawToken(position token.Pos) (string, bool)

RawToken returns the exact physical token spelling at a synthetic AST position owned by the fragment.

func (*Fragment) ReadSyntax 

func (f *Fragment) ReadSyntax(read func(FragmentSyntax) error) error

ReadSyntax provides an isolated selected AST boundary to a run-owned consumer.

func (*Fragment) Slice 

func (f *Fragment) Slice(sourceRange Range) (string, bool)

Slice returns exact physical fragment text for a valid byte range.

func (*Fragment) Tokens 

func (f *Fragment) Tokens() []Token

Tokens returns the physical token ledger without synthetic wrapper tokens.

func (*Fragment) Trivia 

func (f *Fragment) Trivia() []Trivia

Trivia returns exact physical token gaps in source order.

type FragmentError 

type FragmentError struct {
	Path    string
	Offset  int
	Line    int
	Column  int
	Message string
}

FragmentError reports one syntax failure at a physical fragment byte offset.

func (*FragmentError) Error 

func (e *FragmentError) Error() string

type FragmentKind 

type FragmentKind uint8

FragmentKind identifies one explicitly selected standard-input grammar boundary. 

const (
	FragmentDeclaration FragmentKind = iota + 1
	FragmentStatement
	FragmentExpression
)

type FragmentSyntax 

type FragmentSyntax struct {
	Declarations []ast.Decl
	Statements   []ast.Stmt
	Expression   ast.Expr
}

FragmentSyntax is the single AST boundary selected from a synthetic parse. The field corresponding to the fragment kind is selected; an empty declaration or statement list may be nil.

type Metadata 

type Metadata struct {
	HasBOM       bool
	Newlines     NewlineStyle
	FinalNewline bool
	Generated    bool
}

Metadata describes physical file properties relevant to formatting.

type NewlineStyle 

type NewlineStyle uint8

NewlineStyle is the physical line-ending policy observed in a source file. 

const (
	NewlineNone NewlineStyle = iota
	NewlineLF
	NewlineCRLF
	NewlineMixed
)

type Piece 

type Piece struct {
	Kind  PieceKind
	Range Range
	Raw   []byte
}

Piece is one non-overlapping physical source segment.

type PieceKind 

type PieceKind uint8

PieceKind identifies the role of a physical reconstruction segment. 

const (
	PieceTrivia PieceKind = iota
	PieceToken
)

type Position 

type Position struct {
	Offset int
	Line   int
	Column int
}

Position is one 1-based physical byte location in immutable source.

type Range 

type Range struct {
	Start int
	End   int
}

Range is a half-open physical byte range.

type SemicolonKind 

type SemicolonKind uint8

SemicolonKind records whether a semicolon was present in source or inserted by the Go scanner. 

const (
	SemicolonNone SemicolonKind = iota
	SemicolonExplicit
	SemicolonInserted
)

type Token 

type Token struct {
	Kind      token.Token
	Range     Range
	Raw       string
	Semicolon SemicolonKind
}

Token is one physical lexical token.

type Trivia 

type Trivia struct {
	Kind  TriviaKind
	Range Range
	Raw   string
}

Trivia is one exact physical token gap or accepted byte-order mark.

type TriviaKind 

type TriviaKind uint8

TriviaKind identifies physical bytes between lexical tokens. 

const (
	TriviaWhitespace TriviaKind = iota
	TriviaBOM
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.