goscan

Documentation

Overview

Package goscan discovers entity structs in Go packages.

Entities are explicit. A struct becomes one by carrying a directive naming the table it corresponds to:

//orm:table users
type User struct { ... }

//orm:table analytics.events
type Event struct { ... }

Nothing is inferred: no pluralisation, no snake-casing of the type name, no convention that a type called User must live in users. A table name that is not written down does not exist. Column names are the one exception, and only because a struct field's name is a much narrower thing than a type's: a field maps to the lower_snake_case of its name unless a column: tag says otherwise.

//orm:view is recognised so that it can be rejected with a specific finding rather than being silently ignored as an unmarked struct.

Resolved types, not source text

Everything here goes through golang.org/x/tools/go/packages with full type information. Relation fields are recognised by asking go/types whether a field's type is the generic type One or Many declared by this module's runtime package — not by matching the string "orm.One". Import aliases, dot imports and a local type also called One therefore all behave correctly.

Index

• Constants
• func ParseTags(structTag string) (model.FieldTags, error)
• type Package
• type Result
  • func Scan(ctx context.Context, root string, targets []Target) (*Result, error)
• type TagError
  • func (e *TagError) Error() string
  • func (e *TagError) Unwrap() error
• type Target

Constants

const RuntimePkgPath = "github.com/AlexAli29/orm"

RuntimePkgPath is the import path of this module's runtime package. Relation fields are recognised by resolved identity against it, so a type named One in any other package is an ordinary field.

const TagKey = "orm"

TagKey is the struct tag key the scanner reads.

Functions

func ParseTags

func ParseTags(structTag string) (model.FieldTags, error)

ParseTags parses the `orm` key of a struct tag. It returns the directives it understood together with the first error, so that a field with one bad directive still contributes the rest.

Types

type Package

type Package struct {
	Path string
	Name string
	Dir  string
	// Idents maps every package-level identifier to the base name of the file
	// declaring it.
	//
	// A generator needs this to know which names are already taken, and needs
	// the file to tell the author's declarations from its own previous output:
	// on the second run its own identifiers are in scope, and treating those as
	// collisions would make generation succeed exactly once.
	Idents map[string]string
}

Package is one scanned package.

type Result

type Result struct {
	// Entities are sorted by package path and then by type name.
	Entities []*model.GoEntity
	// TagErrors are sorted by position.
	TagErrors []*TagError
	// Packages are sorted by import path.
	Packages []Package
	// Decls are the schema declarations written on types that are not entities
	// — an enum on the named string type that uses it, an extension on
	// whatever type happened to need it. They are package-level schema objects
	// and belong to the schema rather than to one table.
	Decls []model.SchemaDecl
}

Result is everything the scanner learned.

func Scan

func Scan(ctx context.Context, root string, targets []Target) (*Result, error)

Scan loads targets with full type information and returns the entities they declare. Source positions are reported relative to root.

type TagError

type TagError struct {
	Entity string
	Field  string
	Tag    string
	Pos    model.Position
	Err    error
}

TagError is a malformed or misapplied `orm` struct tag. It is returned alongside the entities rather than as a hard failure, because a bad tag is a finding about the author's code, not a failure of the tool.

func (*TagError) Error

func (e *TagError) Error() string

func (*TagError) Unwrap

func (e *TagError) Unwrap() error

type Target

type Target struct {
	// Dir is the absolute directory of the package.
	Dir string
	// OutputDir is the absolute directory generated code for the package would
	// be written to.
	OutputDir string
}

Target is one package to scan.