gen

Documentation

Index

• Constants
• Variables
• func FormatDocComments(docs string, indent bool) string
• func Imports(imports map[string]string) []byte
• func IsReserved(name string) bool
• func PackagePath(dir string) (string, error)
• func ParseSelector(s string) (path, name string)
• func UniqueName(name string, filters ...func(string) bool) string
• type File
  • func NewFile(pkg *Package, name string) *File
  • func (f *File) Bytes() ([]byte, error)
  • func (f *File) DeclareName(name string) string
  • func (f *File) HasContent() bool
  • func (f *File) Import(path string) string
  • func (f *File) IsGo() bool
  • func (f *File) RelativeName(pkg *Package, name string) string
  • func (f *File) Write(content []byte) (int, error)
  • func (f *File) WriteString(s string) (int, error)
• type Ident
• type Package
  • func NewPackage(path string) *Package
  • func (pkg *Package) File(name string) *File
  • func (pkg *Package) HasContent() bool
  • func (pkg *Package) HasPackageDocs() bool
• type Scope
  • func NewScope(parent Scope) Scope
  • func Reserved() Scope

Constants

const (
	DocCommentPrefix = "//"
	LineLength       = 80
)

const HeaderPattern = `// Code generated by %s. DO NOT EDIT.`

Variables

var Initialisms = mapWords(
	"acl",
	"abi",
	"api",
	"ascii",
	"cabi",
	"cpu",
	"css",
	"cwd",
	"dns",
	"eof",
	"fifo",
	"guid",
	"html",
	"http",
	"https",
	"id",
	"imap",
	"io",
	"ip",
	"js",
	"json",
	"lhs",
	"mime",
	"ok",
	"posix",
	"qps",
	"ram",
	"rhs",
	"rpc",
	"sla",
	"smtp",
	"sql",
	"ssh",
	"tcp",
	"tls",
	"ttl",
	"tty",
	"udp",
	"ui",
	"uid",
	"uuid",
	"uri",
	"url",
	"utf8",
	"vm",
	"xml",
	"xmpp",
	"xsrf",
	"xss",
)

Initialisms is a set of common initialisms.

Functions

func FormatDocComments

func FormatDocComments(docs string, indent bool) string

FormatDocComments formats documentation comment text (without // or /*) into multiple lines of max length LineLength, prefixed by //, suitable for inclusion as documentation comments in Go source code.

func Imports

func Imports(imports map[string]string) []byte

Imports returns Go import syntax for imports. The imports argument is a map of import path to local name.

func IsReserved

func IsReserved(name string) bool

IsReserved returns true for any name that is a Go keyword or predeclared identifier.

func PackagePath

func PackagePath(dir string) (string, error)

PackagePath returns the Go module path and optional package directory path(s) for the given directory path dir. Returns an error if dir or its parent directories do not contain a go.mod file.

func ParseSelector

func ParseSelector(s string) (path, name string)

ParseSelector parses string s into a package path and short name. It does not validate the input or resulting values. Examples: "io" -> "io", "io" "encoding/json" -> "encoding/json", "json" "encoding/json#Decoder" -> "encoding/json", "Decoder" "wasi/clocks/wall#DateTime" -> "wasi/clocks/wall", "DateTime"

func UniqueName

func UniqueName(name string, filters ...func(string) bool) string

UniqueName tests name against filters and modifies name until all filters return false. Use IsReserved to filter out Go keywords and predeclared identifiers.

Exported names that start with a capital letter will be appended with an underscore. Non-exported names are prefixed with an underscore.

Types

type File

type File struct {
	// Name is the short name of the file.
	// If Name ends in ".go" this file will be treated as a Go file.
	Name string

	// GeneratedBy is the name of the program that generated this file.
	// Leave empty to omit the "Code generated by ..." header.
	GeneratedBy string

	// GoBuild contains build tags, serialized as //go:build ...
	// Ignored if this is not a Go file.
	GoBuild string

	// PackageDocs are doc comments that preceed the package declaration.
	// These will be wrapped and each line prefixed with // when serialized.
	// Ignored if this is not a Go file.
	PackageDocs string

	// Package this file belongs to.
	Package *Package

	// Scope is the naming scope of this file, used for package import names.
	Scope

	// Imports maps Go package imports from package path to local name, e.g. {"encoding/json": "json"}.
	Imports map[string]string

	// Header is the file header, written before content.
	Header string

	// Content is the file content.
	Content []byte

	// Trailer is the file trailer, written after content.
	Trailer string
}

File represents a generated file. It may be a Go file

func NewFile

func NewFile(pkg *Package, name string) *File

NewFile returns a newly initialized file.

func (*File) Bytes

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

Bytes returns the byte values of this file.

func (*File) DeclareName

func (f *File) DeclareName(name string) string

DeclareName adds a package-scoped identifier to File f. It additionally checks the file-scoped declarations (local package names). It returns the package-unique name (which may be different than name).

func (*File) HasContent

func (f *File) HasContent() bool

HasContent returns true if f contains any content.

func (*File) Import

func (f *File) Import(path string) string

Import imports the Go package specified by path, returning the local name for the imported package. The path argument may have an optional "#name" suffix to specify the local name. The returned local name may differ from the specified local name.

func (*File) IsGo

func (f *File) IsGo() bool

IsGo returns true if f represents a Go file.

func (*File) RelativeName

func (f *File) RelativeName(pkg *Package, name string) string

RelativeName returns a file and package-relative string for a Package and name. If f belongs to pkg, it returns the local name. If f belongs to a different package, it first imports the package, then returns a name prefixed with the imported package name.

func (*File) Write

func (f *File) Write(content []byte) (int, error)

Write implements io.Writer.

func (*File) WriteString

func (f *File) WriteString(s string) (int, error)

WriteString implements io.StringWriter.

type Ident

type Ident struct {
	Package *Package
	Name    string
}

Ident represents a package-level Go declaration.

type Package

type Package struct {
	// Path is the Go package path, e.g. "encoding/json"
	Path string

	// Name is the short Go package name, e.g. "json"
	Name string

	// Files is the list of Go and non-Go files in this package.
	Files map[string]*File

	// Declared tracks declared package-scoped identifiers,
	// including constants, variables, and functions.
	Scope
}

Package represents a Go package, containing zero or more files of generated code, along with zero or more declarations.

func NewPackage

func NewPackage(path string) *Package

NewPackage returns a newly instantiated Package for path. The local name may optionally be specified with a "#name" suffix.

func (*Package) File

func (pkg *Package) File(name string) *File

File finds or adds a new file named name to pkg.

func (*Package) HasContent

func (pkg *Package) HasContent() bool

HasContent returns true if pkg contains at least 1 File with non-empty content.

func (*Package) HasPackageDocs

func (pkg *Package) HasPackageDocs() bool

HasPackageDocs returns true if pkg contains at least 1 File with a non-empty PackageDocs field.

type Scope

type Scope interface {
	// DeclareName declares name within this scope, modifying it as necessary to avoid
	// colliding with any preexisting names. It returns the unique generated name.
	// Subsequent calls to GetName will return the unique name.
	// Subsequent calls to HasName with the returned name will return true.
	// Subsequent calls to DeclareName will return a different name.
	DeclareName(name string) string

	// GetName returns the first declared unique name for name, if declared.
	GetName(name string) string

	// HasName returns true if this scope or any of its parent scopes contains name.
	HasName(name string) bool
}

Scope represents a Go name scope, like a package, file, interface, struct, or function blocks.

func NewScope

func NewScope(parent Scope) Scope

NewScope returns an initialized Scope that's ready to use. If parent is nil, Reserved will be used.

func Reserved

func Reserved() Scope

Reserved returns a preset Scope with the default Go keywords and predeclared identifiers. Calls to its UniqueName method will panic, as the scope is immutable.