markers

Documentation

Overview

markers is a helper used to extract marker information from types. A marker is a comment line preceded with `+` that indicates to a generator something about the field or type.

The package returns a Markers interface, which can be used to access markers associated with a struct or a field within a struct.

Example:

inspect := pass.ResultOf[inspect.Analyzer].(*inspector.Inspector)
markersAccess := pass.ResultOf[markers.Analyzer].(markers.Markers)

// Filter to structs so that we can iterate over fields in a struct.
nodeFilter := []ast.Node{
	(*ast.StructType)(nil),
}

inspect.Preorder(nodeFilter, func(n ast.Node) {
	sTyp, ok := n.(*ast.StructType)
	if !ok {
		return
	}

	if sTyp.Fields == nil {
		return
	}

	for _, field := range sTyp.Fields.List {
		if field == nil || len(field.Names) == 0 {
			continue
		}

		structMarkers := markersAccess.StructMarkers(sTyp)
		fieldMarkers := markersAccess.FieldMarkers(field)

		...
	}
})

The result of StructMarkers or StructFieldMarkers is a MarkerSet which can be used to determine the presence of a marker, and the value of the marker. The MarkerSet is indexed based on the value of the marker, once the prefix `+` is removed.

Additional information about the marker can be found in the Marker struct, for each marker on the field.

Example:

fieldMarkers := markersAccess.FieldMarkers(field)

if fieldMarkers.Has("required") {
	requiredMarker := fieldMarkers["required"]
	...
}

Index

• Variables
• type Marker
• type MarkerSet
  • func NewMarkerSet(markers ...Marker) MarkerSet
  • func (ms MarkerSet) Has(value string) bool
  • func (ms MarkerSet) Insert(markers ...Marker)
• type Markers

Variables

var Analyzer = &analysis.Analyzer{
	Name:       "markers",
	Doc:        "Iterates over declarations within a package and parses the comments to extract markers",
	Run:        run,
	Requires:   []*analysis.Analyzer{inspect.Analyzer},
	ResultType: reflect.TypeOf(newMarkers()),
}

Analyzer is the analyzer for the markers package. It iterates over declarations within a package and parses the comments to extract markers.

Types

type Marker

type Marker struct {
	// Value is the value of the marker once the leading comment and '+' are trimmed.
	Value string

	// RawComment is the raw comment line, unfiltered.
	RawComment string

	// Pos is the starting position in the file for the comment line containing the marker.
	Pos token.Pos

	// End is the ending position in the file for the coment line containing the marker.
	End token.Pos
}

Marker represents a marker extracted from a comment on a declaration.

type MarkerSet

type MarkerSet map[string]Marker

MarkerSet is a set implementation for Markers that uses the Marker value as the key, but returns the full Marker as the result.

func NewMarkerSet

func NewMarkerSet(markers ...Marker) MarkerSet

NewMarkerSet initialises a new MarkerSet with the provided values. If any markers have the same value, the latter marker in the list will take precedence, no duplication checks are implemented.

func (MarkerSet) Has

func (ms MarkerSet) Has(value string) bool

Has returns whether a marker with the value given is present in the MarkerSet.

func (MarkerSet) Insert

func (ms MarkerSet) Insert(markers ...Marker)

Insert add the given markers to the MarkerSet. If any markers have the same value, the latter marker in the list will take precedence, no duplication checks are implemented.

type Markers

type Markers interface {
	// FieldMarkers returns markers associated to the field.
	FieldMarkers(*ast.Field) MarkerSet

	// StructMarkers returns markers associated to the given sturct.
	StructMarkers(*ast.StructType) MarkerSet

	// TypeMarkers returns markers associated to the given type.
	TypeMarkers(*ast.TypeSpec) MarkerSet
}

Markers allows access to markers extracted from the go types.