source

package
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Aug 27, 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 ErrDirectiveSourceAnchorChanged = errors.New("directive source anchor changed")

ErrDirectiveSourceAnchorChanged identifies a formatter validation failure caused by moving one or more directive comments across physical source anchors.

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 DirectiveAnchorError 

type DirectiveAnchorError struct {
	Changed []Directive
}

DirectiveAnchorError identifies the original directives whose physical source anchors changed.

func (*DirectiveAnchorError) Error 

func (e *DirectiveAnchorError) Error() string

func (*DirectiveAnchorError) Unwrap 

func (e *DirectiveAnchorError) Unwrap() error

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
	DirectiveGlippySuppression
	DirectiveLegacyGoxSuppression
	DirectiveExternalSuppression
	DirectiveCgoPreamble
)

type File 

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

File is an immutable physical source unit.

func CaptureParsedBytes 

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

CaptureParsedBytes retains immutable bytes for source that the package loader has already parsed successfully without constructing the formatter's token, trivia, comment, directive, and reconstruction indexes.

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) ByteSize 

func (f *File) ByteSize() int64

ByteSize returns the exact number of immutable physical source bytes retained by the file without cloning them.

func (*File) Bytes 

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

Bytes returns an independent copy of the physical source bytes.

func (*File) CanAnalyze 

func (f *File) CanAnalyze() bool

CanAnalyze reports whether package analysis can use the retained immutable bytes. Compact dependency sources are analyzable but intentionally lack the formatter indexes required by CanFormat.

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) TokensInRange 

func (f *File) TokensInRange(range_ Range) ([]Token, bool)

TokensInRange returns the lexical tokens intersecting one valid physical byte range without copying the complete file 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.