source

Documentation

Overview

Package source reads type declarations out of Go files and turns them into the descriptions pattern recipes take.

It is what closes the loop: without it, a generator has to describe every type it generates for by hand. With it, the input is the source you already have.

Field types come back as gogol nodes rather than text, which is the part that matters. A field declared time.Time becomes gogol.QualType("time", "time.Time")'s node, carrying the import path resolved from the file's own import block — so generating into a different file gets the import right, and generating into a file that already imports time under an alias uses the alias. Copying the text "time.Time" across would get both wrong.

Index

• func ParseFile(filename string, src []byte) Result[*File]
• type File
  • func (f *File) Package() string
  • func (f *File) Scope() gogol.Scope
  • func (f *File) TypeAt(line int) Result[TypeDecl]
  • func (f *File) TypeNamed(name string) Result[TypeDecl]
  • func (f *File) Types() []TypeDecl
• type Kind
  • func (k Kind) String() string
• type NotFoundError
  • func (e *NotFoundError) Error() string
• type TypeDecl

Functions

func ParseFile

func ParseFile(filename string, src []byte) Result[*File]

ParseFile parses src. filename is used for positions and error messages only; pass an empty string when the source did not come from a file.

Types

type File

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

File is a parsed Go source file.

func (*File) Package

func (f *File) Package() string

Package returns the file's package name.

func (*File) Scope

func (f *File) Scope() gogol.Scope

Scope reports the identifier each imported package is known by in this file, keyed by import path.

Hand it to gogol.RenderScoped when the generated code is being inserted back into this same file. Without it a fragment guesses a qualifier from the import path, which is wrong for every package whose name is not its last path segment — and wrong for every aliased import, however ordinary the package.

The file's own package is included under the empty path with an empty name, so that a type from it prints unqualified.

func (*File) TypeAt

func (f *File) TypeAt(line int) Result[TypeDecl]

TypeAt finds the type declaration covering line, 1-based.

When several declarations cover it — a struct type nested inside another — the innermost wins, which is what a cursor position implies.

func (*File) TypeNamed

func (f *File) TypeNamed(name string) Result[TypeDecl]

TypeNamed finds the type declaration with the given name.

func (*File) Types

func (f *File) Types() []TypeDecl

Types returns every type declaration in the file, in source order.

type Kind

type Kind int

Kind describes the shape of a type declaration, which decides which recipes apply to it.

const (
	// KindStruct is a struct type. Every recipe applies.
	KindStruct Kind = iota
	// KindNamed is a defined type over some other underlying type. Only
	// [pattern.Wrap] applies.
	KindNamed
	// KindInterface is an interface type. No recipe applies: interfaces are
	// implemented, not constructed.
	KindInterface
)

func (Kind) String

func (k Kind) String() string

type NotFoundError

type NotFoundError struct {
	// What describes the request: a line number or a type name.
	What string
}

NotFoundError reports that nothing matched the request.

func (*NotFoundError) Error

func (e *NotFoundError) Error() string

type TypeDecl

type TypeDecl struct {
	// Struct carries the name, type parameters and fields, ready to hand to a
	// recipe. Fields is empty unless Kind is [KindStruct].
	pattern.Struct
	// Kind is the declaration's shape.
	Kind Kind
	// Underlying is set when Kind is [KindNamed]: the type on the right of the
	// declaration.
	Underlying gogol.Type
	// StartLine and EndLine bracket the declaration, 1-based and inclusive.
	// EndLine is where an editor should insert generated code.
	StartLine, EndLine int
}

TypeDecl is a located type declaration.