markers

Documentation

Index

• func EachType(col Collector, pkg *loader.Package, cb TypeCallback) error
• type Argument
  • func ArgumentFromType(rawType reflect.Type) (Argument, error)
  • func (a *Argument) Parse(scanner *sc.Scanner, raw string, out reflect.Value)
• type ArgumentType
• type Collector
  • func NewCollector(ctx context.Context) Collector
• type Definition
  • func MakeAnyTypeDefinition(name string, target TargetType, output interface{}) (*Definition, error)
  • func MakeDefinition(name string, target TargetType, output interface{}) (*Definition, error)
  • func Must(def *Definition, err error) *Definition
  • func (r *Definition) AnonymousField() bool
  • func (r *Definition) Empty() bool
  • func (r *Definition) Parse(rawMarker string) (interface{}, error)
• type DefinitionHelp
  • func SimpleHelp(category, summary string) *DefinitionHelp
• type DetailedHelp
• type FieldInfo
• type MarkerValues
  • func PackageMarkers(col Collector, pkg *loader.Package) (MarkerValues, error)
  • func (v MarkerValues) Get(name string) any
• type RawArguments
• type Registry
  • func NewRegistry(ctx context.Context) Registry
• type ScannerError
  • func (e *ScannerError) Error() string
• type TargetType
• type TypeCallback
• type TypeInfo

Functions

func EachType

func EachType(col Collector, pkg *loader.Package, cb TypeCallback) error

EachType collects all markers, then calls the given callback for each type declaration in a package. Each individual spec is considered separate, so

type (
    Foo string
    Bar int
    Baz struct{}
)

yields three calls to the callback.

Types

type Argument

type Argument struct {
	// Type is the type of this argument For non-scalar types (map and slice),
	// further information is specified in ItemType.
	Type ArgumentType
	// Optional indicates if this argument is optional.
	Optional bool
	// Pointer indicates if this argument was a pointer (this is really only
	// needed for deserialization, and should alway imply optional)
	Pointer bool

	// ItemType is the type of the slice item for slices, and the value type
	// for maps.
	ItemType *Argument
}

Argument is the type of a marker argument.

func ArgumentFromType

func ArgumentFromType(rawType reflect.Type) (Argument, error)

ArgumentFromType constructs an Argument by examining the given raw reflect.Type. It can construct arguments from the Go types corresponding to any of the types listed in ArgumentType.

func (*Argument) Parse

func (a *Argument) Parse(scanner *sc.Scanner, raw string, out reflect.Value)

Parse attempts to consume the argument from the given scanner (based on the given raw input as well for collecting ranges of content), and places the output value in the given reflect.Value. Errors are reported via the given scanner.

type ArgumentType

type ArgumentType int

ArgumentType is the kind of a marker argument type. It's roughly analogous to a subset of reflect.Kind, with an extra "AnyType" to represent the empty interface.

const (
	// Invalid represents a type that can't be parsed, and should never be used.
	InvalidType ArgumentType = iota
	// IntType is an int
	IntType
	// NumberType is a float64
	NumberType
	// StringType is a string
	StringType
	// BoolType is a bool
	BoolType
	// AnyType is the empty interface, and matches the rest of the content
	AnyType
	// SliceType is any slice constructed of the ArgumentTypes
	SliceType
	// MapType is any map constructed of string keys, and ArgumentType values.
	// Keys are strings, and it's common to see AnyType (non-uniform) values.
	MapType
	// RawType represents content that gets passed directly to the marker
	// without any parsing. It should *only* be used with anonymous markers.
	RawType
)

type Collector

type Collector interface {
	MarkersInPackage(pkg *loader.Package) (map[ast.Node]MarkerValues, error)
	Print()
}

Collector collects and parses marker comments defined in the registry from package source code.

func NewCollector

func NewCollector(ctx context.Context) Collector

type Definition

type Definition struct {
	// Output is the deserialized Go type of the marker.
	Output reflect.Type
	// Name is the marker's name.
	Name string
	// Target indicates which kind of node this marker can be associated with.
	Target TargetType
	// Fields lists out the types of each field that this marker has, by
	// argument name as used in the marker (if the output type isn't a struct,
	// it'll have a single, blank field name).  This only lists exported fields,
	// (as per reflection rules).
	Fields map[string]Argument
	// FieldNames maps argument names (as used in the marker) to struct field name
	// in the output type.
	FieldNames map[string]string
	// Strict indicates that this definition should error out when parsing if
	// not all non-optional fields were seen.
	Strict bool
}

Definition is a parsed definition of a marker.

func MakeAnyTypeDefinition

func MakeAnyTypeDefinition(name string, target TargetType, output interface{}) (*Definition, error)

MakeAnyTypeDefinition constructs a definition for an output struct with a field named `Value` of type `interface{}`. The argument to the marker will be parsed as AnyType and assigned to the field named `Value`.

func MakeDefinition

func MakeDefinition(name string, target TargetType, output interface{}) (*Definition, error)

MakeDefinition constructs a definition from a name, type, and the output type. All such definitions are strict by default. If a struct is passed as the output type, its public fields will automatically be populated into Fields (and similar fields in Definition). Other values will have a single, empty-string-named Fields entry.

func Must

func Must(def *Definition, err error) *Definition

Must panics on errors creating definitions.

func (*Definition) AnonymousField

func (r *Definition) AnonymousField() bool

AnonymousField indicates that the definition has one field, (actually the original object), and thus the field doesn't get named as part of the name.

func (*Definition) Empty

func (r *Definition) Empty() bool

Empty indicates that this definition has no fields.

func (*Definition) Parse

func (r *Definition) Parse(rawMarker string) (interface{}, error)

Parse uses the type information in this Definition to parse the given raw marker in the form `+a:b:c=arg,d=arg` into an output object of the type specified in the definition.

type DefinitionHelp

type DefinitionHelp struct {
	// DetailedHelp contains the overall help for the marker.
	DetailedHelp
	// Category describes what kind of marker this is.
	Category string
	// DeprecatedInFavorOf marks the marker as deprecated.
	// If non-nil & empty, it's assumed to just mean deprecated permanently.
	// If non-empty, it's assumed to be a marker name.
	DeprecatedInFavorOf *string

	// FieldHelp defines the per-field help for this marker, *in terms of the
	// go struct field names.  Use the FieldsHelp method to map this to
	// marker argument names.
	FieldHelp map[string]DetailedHelp
}

DefinitionHelp contains overall help for a marker Definition, as well as per-field help.

func SimpleHelp

func SimpleHelp(category, summary string) *DefinitionHelp

SimpleHelp returns help that just has marker-level summary information (e.g. for use with empty or primitive-typed markers, where Godoc-based generation isn't possible).

type DetailedHelp

type DetailedHelp struct {
	Summary string
	Details string
}

DetailedHelp contains brief help, as well as more details. For the "full" help, join the two together.

type FieldInfo

type FieldInfo struct {
	// Name is the name of the field (or "" for embedded fields)
	Name string
	// Doc is the Godoc of the field, pre-processed to remove markers and joine
	// single newlines together.
	Doc string
	// Tag struct tag associated with this field (or "" if non existed).
	Tag reflect.StructTag

	// Markers are all registered markers associated with this field.
	Markers MarkerValues

	// RawField is the raw, underlying field AST object that this field represents.
	RawField *ast.Field
}

FieldInfo contains marker values and commonly used information for a struct field.

type MarkerValues

type MarkerValues map[string][]any

MarkerValues are all the values for some set of markers.

func PackageMarkers

func PackageMarkers(col Collector, pkg *loader.Package) (MarkerValues, error)

PackageMarkers collects all the package-level marker values for the given package.

func (MarkerValues) Get

func (v MarkerValues) Get(name string) any

Get fetches the first value that for the given marker, returning nil if no values are available.

type RawArguments

type RawArguments []byte

RawArguments is a special type that can be used for a marker to receive *all* raw, underparsed argument data for a marker. You probably want to use `interface{}` to match any type instead. Use *only* for legacy markers that don't follow Definition's normal parsing logic. It should *not* be used as a field in a marker struct.

type Registry

type Registry interface {
	Register(def *Definition) error
	Lookup(name string, target TargetType) *Definition
	AddHelp(def *Definition, help *DefinitionHelp)
	Print()
}

Registry keeps track of registered definitions, and allows for easy lookup.

func NewRegistry

func NewRegistry(ctx context.Context) Registry

type ScannerError

type ScannerError struct {
	Msg string
	Pos sc.Position
}

func (*ScannerError) Error

func (e *ScannerError) Error() string

type TargetType

type TargetType int

TargetType describes which kind of node a given marker is associated with.

const (
	// DescribesPackage indicates that a marker is associated with a package.
	DescribesPackage TargetType = iota
	// DescribesType indicates that a marker is associated with a type declaration.
	DescribesType
	// DescribesField indicates that a marker is associated with a struct field.
	DescribesField
)

type TypeCallback

type TypeCallback func(info *TypeInfo)

TypeCallback is a callback called for each type declaration in a package.

type TypeInfo

type TypeInfo struct {
	// Name is the name of the type.
	Name string
	// Doc is the Godoc of the type, pre-processed to remove markers and joine
	// single newlines together.
	Doc string

	// Markers are all registered markers associated with the type.
	Markers MarkerValues

	// Fields are all the fields associated with the type, if it's a struct.
	// (if not, Fields will be nil).
	Fields []FieldInfo

	// RawDecl contains the raw GenDecl that the type was declared as part of.
	RawDecl *ast.GenDecl
	// RawSpec contains the raw Spec that declared this type.
	RawSpec *ast.TypeSpec
	// RawFile contains the file in which this type was declared.
	RawFile *ast.File
}

TypeInfo contains marker values and commonly used information for a type declaration.