validators

package
v0.4.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 11, 2025 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	ListMapKeyTagName = "k8s:listMapKey"
)

Variables

This section is empty.

Functions

func RegisterTagValidator 

func RegisterTagValidator(tv TagValidator)

RegisterTagValidator must be called by any validator which wants to run when a specific tag is found.

func RegisterTypeValidator 

func RegisterTypeValidator(tv TypeValidator)

RegisterTypeValidator must be called by any validator which wants to run against every type definition.

Types

type Conditions 

type Conditions struct {
	// OptionEnabled specifies an option name that must be set to true for the condition to be true.
	OptionEnabled string

	// OptionDisabled specifies an option name that must be set to false for the condition to be true.
	OptionDisabled string
}

Conditions defines what conditions must be true for a resource to be validated. If any of the conditions are not true, the resource is not validated.

func (Conditions) Empty 

func (c Conditions) Empty() bool

type Config 

type Config struct {
	// GengoContext provides gengo's generator Context.  This allows validators
	// to look up all sorts of other information.
	GengoContext *generator.Context

	// Validator provides a way to compose validations.
	//
	// For example, it is possible to define a validation such as
	// "+myValidator=+format=IP" by using the registry to extract the
	// validation for the embedded "+format=IP" and use those to
	// create the final Validations returned by the "+myValidator" tag.
	//
	// This field MUST NOT be used during init, since other validators may not
	// be initialized yet.
	Validator Validator
}

Config carries optional configuration information for use by validators.

type Context 

type Context struct {
	// Scope is where the validation is being considered.
	Scope Scope

	// Type provides details about the type being validated.  When Scope is
	// ScopeType, this is the underlying type.  When Scope is ScopeField, this
	// is the field's type (including any pointerness).  When Scope indicates a
	// list-value, map-key, or map-value, this is the type of that key or
	// value.
	Type *types.Type

	// Parent provides details about the logical parent type of the type being
	// validated, when applicable.  When Scope is ScopeType, this is the
	// newly-defined type (when it exists - gengo handles struct-type
	// definitions differently that other "alias" type definitions).  When
	// Scope is ScopeField, this is the field's parent struct's type.  When
	// Scope indicates a list-value, map-key, or map-value, this is the type of
	// the whole list or map.
	//
	// Because of how gengo handles struct-type definitions, this field may be
	// nil in those cases.
	Parent *types.Type

	// Member provides details about a field within a struct, when Scope is
	// ScopeField.  For all other values of Scope, this will be nil.
	Member *types.Member

	// Path provides the field path to the type or field being validated. This
	// is useful for identifying an exact context, e.g. to track information
	// between related tags.
	Path *field.Path
}

Context describes where a tag was used, so that the scope can be checked and so validators can handle different cases if they need.

type FunctionFlags 

type FunctionFlags uint32

FunctionFlags define optional properties of a validator. Most validators can just use DefaultFlags. 

const (
	// DefaultFlags is defined for clarity.
	DefaultFlags FunctionFlags = 0

	// ShortCircuit indicates that further validations should be skipped if
	// this validator fails. Most validators are not fatal.
	ShortCircuit FunctionFlags = 1 << iota

	// NonError indicates that a failure of this validator should not be
	// accumulated as an error, but should trigger other aspects of the failure
	// path (e.g. early return when combined with ShortCircuit).
	NonError
)

func (FunctionFlags) IsSet 

func (ff FunctionFlags) IsSet(wanted FunctionFlags) bool

IsSet returns true if all of the wanted flags are set.

type FunctionGen 

type FunctionGen interface {
	// TagName returns the tag which triggers this validator.
	TagName() string

	// SignatureAndArgs returns the function name and all extraArg value literals that are passed when the function
	// invocation is generated.
	//
	// The function signature must be of the form:
	//   func(op operation.Operation,
	//        fldPath field.Path,
	//        value, oldValue <ValueType>,     // always nilable
	//        extraArgs[0] <extraArgs[0]Type>, // optional
	//        ...,
	//        extraArgs[N] <extraArgs[N]Type>)
	//
	// extraArgs may contain:
	// - data literals comprised of maps, slices, strings, ints, floats and bools
	// - references, represented by types.Type (to reference any type in the universe), and types.Member (to reference members of the current value)
	//
	// If validation function to be called does not have a signature of this form, please introduce
	// a function that does and use that function to call the validation function.
	SignatureAndArgs() (function types.Name, extraArgs []any)

	// TypeArgs assigns types to the type parameters of the function, for invocation.
	TypeArgs() []types.Name

	// Flags returns the options for this validator function.
	Flags() FunctionFlags

	// Conditions returns the conditions that must true for a resource to be
	// validated by this function.
	Conditions() Conditions
}

FunctionGen provides validation-gen with the information needed to generate a validation function invocation.

func Function 

func Function(tagName string, flags FunctionFlags, function types.Name, extraArgs ...any) FunctionGen

Function creates a FunctionGen for a given function name and extraArgs.

func GenericFunction 

func GenericFunction(tagName string, flags FunctionFlags, function types.Name, typeArgs []types.Name, extraArgs ...any) FunctionGen

func WithCondition 

func WithCondition(fn FunctionGen, conditions Conditions) FunctionGen

type FunctionLiteral 

type FunctionLiteral struct {
	Parameters []ParamResult
	Results    []ParamResult
	Body       string
}

FunctionLiteral describes a function-literal expression that can be used as an argument to a validator. Unlike WrapperFunction, this does not necessarily have the same signature as a regular validation function.

type Identifier 

type Identifier types.Name

Identifier is a name that the generator will output as an identifier. Identifiers are generated using the RawNamer strategy.

type LateTagValidator 

type LateTagValidator interface {
	LateTagValidator()
}

LateTagValidator is an optional extension to TagValidator. Any TagValidator which implements this interface will be evaluated after all TagValidators which do not.

type Literal 

type Literal string

Literal is a literal value that, when used as an argument to a validator, will be emitted without any further interpretation. Use this with caution, it will not be subject to Namers.

type ParamResult 

type ParamResult struct {
	Name string
	Type *types.Type
}

ParamResult represents a parameter or a result of a function.

type PrivateVar 

type PrivateVar types.Name

PrivateVar is a variable name that the generator will output as a private identifier. PrivateVars are generated using the PrivateNamer strategy.

type Scope 

type Scope string

Scope describes where a validation (or potential validation) is located. 

const (
	// ScopeAny indicates that a validator may be use in any context.  This value
	// should never appear in a Context struct, since that indicates a
	// specific use.
	ScopeAny Scope = "anywhere"

	// ScopeType indicates a validation on a type definition, which applies to
	// all instances of that type.
	ScopeType Scope = "type definitions"

	// ScopeField indicates a validation on a particular struct field, which
	// applies only to that field of that struct.
	ScopeField Scope = "struct fields"

	// ScopeListVal indicates a validation which applies to all elements of a
	// list field or type.
	ScopeListVal Scope = "list values"

	// ScopeMapKey indicates a validation which applies to all keys of a map
	// field or type.
	ScopeMapKey Scope = "map keys"

	// ScopeMapVal indicates a validation which applies to all values of a map
	// field or type.
	ScopeMapVal Scope = "map values"
)

Note: All of these values should be strings which can be used in an error message such as "may not be used in %s".

type TagArgDoc 

type TagArgDoc struct {
	// Description is a short description of this arg (e.g. `<name>`).
	Description string
}

TagArgDoc describes an argument for a tag (e.g. `+tagName(tagArg)`.

type TagDoc 

type TagDoc struct {
	// Tag is the tag name, without the leading '+'.
	Tag string
	// Args lists any arguments this tag might take.
	Args []TagArgDoc
	// Usage is how the tag is used, including arguments.
	Usage string
	// Description is a short description of this tag's purpose.
	Description string
	// Docs is a human-oriented string explaining this tag.
	Docs string
	// Scopes lists the place or places this tag may be used.
	Scopes []Scope
	// Payloads lists zero or more varieties of value for this tag. If this tag
	// never has a payload, this list should be empty, but if the payload is
	// optional, this list should include an entry for "<none>".
	Payloads []TagPayloadDoc
}

TagDoc describes a comment-tag and its usage.

type TagPayloadDoc 

type TagPayloadDoc struct {
	// Description is a short description of this payload (e.g. `<number>`).
	Description string
	// Docs is a human-orientd string explaining this payload.
	Docs string
	// Schema details a JSON payload's contents.
	Schema []TagPayloadSchema
}

TagPayloadDoc describes a value for a tag (e.g. `+tagName=tagValue`). Some tags upport multiple payloads, including <none> (e.g. `+tagName`).

type TagPayloadSchema 

type TagPayloadSchema struct {
	Key     string
	Value   string
	Docs    string
	Default string
}

TagPayloadSchema describes a JSON tag payload.

type TagValidator 

type TagValidator interface {
	// Init initializes the implementation.  This will be called exactly once.
	Init(cfg Config)

	// TagName returns the full tag name (without the "marker" prefix) for this
	// tag.
	TagName() string

	// ValidScopes returns the set of scopes where this tag may be used.
	ValidScopes() sets.Set[Scope]

	// GetValidations returns any validations described by this tag.
	GetValidations(context Context, args []string, payload string) (Validations, error)

	// Docs returns user-facing documentation for this tag.
	Docs() TagDoc
}

TagValidator describes a single validation tag and how to use it.

type TypeValidator 

type TypeValidator interface {
	// Init initializes the implementation.  This will be called exactly once.
	Init(cfg Config)

	// Name returns a unique name for this validator.  This is used for sorting
	// and logging.
	Name() string

	// GetValidations returns any validations imposed by this validator for the
	// given context.
	//
	// The way gengo handles type definitions varies between structs and other
	// types.  For struct definitions (e.g. `type Foo struct {}`), the realType
	// is the struct itself (the Kind field will be `types.Struct`) and the
	// parentType will be nil.  For other types (e.g. `type Bar string`), the
	// realType will be the underlying type and the parentType will be the
	// newly defined type (the Kind field will be `types.Alias`).
	GetValidations(context Context) (Validations, error)
}

TypeValidator describes a validator which runs on every type definition.

type Validations 

type Validations struct {
	Functions     []FunctionGen
	Variables     []VariableGen
	Comments      []string
	OpaqueType    bool
	OpaqueKeyType bool
	OpaqueValType bool
}

Validations defines the function calls and variables to generate to perform validation.

func ForEachKey 

func ForEachKey(_ *field.Path, t *types.Type, fn FunctionGen) (Validations, error)

ForEachKey returns a validation that applies a function to each key of a map.

func ForEachVal 

func ForEachVal(fldPath *field.Path, t *types.Type, fn FunctionGen) (Validations, error)

ForEachVal returns a validation that applies a function to each element of a list or map.

func (*Validations) Add 

func (v *Validations) Add(o Validations)

func (*Validations) AddComment 

func (v *Validations) AddComment(comment string)

func (*Validations) AddFunction 

func (v *Validations) AddFunction(f FunctionGen)

func (*Validations) AddVariable 

func (v *Validations) AddVariable(variable VariableGen)

func (*Validations) Empty 

func (v *Validations) Empty() bool

func (*Validations) Len 

func (v *Validations) Len() int

type Validator 

type Validator interface {
	// ExtractValidations considers the given context (e.g. a type definition) and
	// evaluates registered validators.  This includes type validators (which run
	// against all types) and tag validators which run only if a specific tag is
	// found in the associated comment block.  Any matching validators produce zero
	// or more validations, which will later be rendered by the code-generation
	// logic.
	ExtractValidations(context Context, comments []string) (Validations, error)

	// Docs returns documentation for each known tag.
	Docs() []TagDoc
}

Validator represents an aggregation of validator plugins.

func InitGlobalValidator 

func InitGlobalValidator(c *generator.Context) Validator

InitGlobalValidator must be called exactly once by the main application to initialize and safely access the global tag registry. Once this is called, no more validators may be registered.

type VariableGen 

type VariableGen interface {
	// TagName returns the tag which triggers this validator.
	TagName() string

	// Var returns the variable identifier.
	Var() PrivateVar

	// Init generates the function call that the variable is assigned to.
	Init() FunctionGen
}

VariableGen provides validation-gen with the information needed to generate variable. Variables typically support generated functions by providing static information such as the list of supported symbols for an enum.

func Variable 

func Variable(variable PrivateVar, init FunctionGen) VariableGen

Variable creates a VariableGen for a given function name and extraArgs.

type WrapperFunction 

type WrapperFunction struct {
	Function FunctionGen
	ObjType  *types.Type
}

WrapperFunction describes a function literal which has the fingerprint of a regular validation function (op, fldPath, obj, oldObj) and calls another validation function with the same signature, plus extra args if needed.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.