tagparser

Documentation

Overview

Package tagparser parses struct-tag validation rules into a reusable representation shared by GoZod runtime code and codegen.

Callers should prefer FieldInfo helper methods such as FieldInfo.ValidationRules, FieldInfo.NeedsGeneratedOptional, and FieldInfo.RequiredImports instead of re-deriving schema-generation semantics from raw fields like Rules, Required, or Optional.

Use TagParser.ParseStructTags for compatibility-oriented callers that prefer empty results on non-struct input, or TagParser.ParseStructTagsStrict when non-struct input should be treated as a contract error.

A parser is configured with two tag names: the rule tag (default "gozod") and the field-name tag that supplies field names (default "json"). Use NewWithTags to select both, or FieldName to resolve a single field's name from a chosen field-name tag such as "yaml" or "toml".

Package tagparser provides shared tag parsing functionality for GoZod. Extracted from types/struct.go to enable reuse by cmd/gozodgen and other components.

Index

• Variables
• type FieldInfo
  • func (f FieldInfo) EffectiveTypeName() string
  • func (f FieldInfo) EnumRule() *TagRule
  • func (f FieldInfo) HasCoerceRule() bool
  • func (f FieldInfo) HasRule(name string) bool
  • func (f FieldInfo) HasRules() bool
  • func (f FieldInfo) HasSchemaSpec() bool
  • func (f FieldInfo) IsEnumStringField() bool
  • func (f FieldInfo) IsPointerType() bool
  • func (f FieldInfo) IsUUIDStringField() bool
  • func (f FieldInfo) NeedsCoreImport() bool
  • func (f FieldInfo) NeedsGeneratedOptional() bool
  • func (f FieldInfo) NeedsNetImport() bool
  • func (f FieldInfo) NeedsNetURLImport() bool
  • func (f FieldInfo) NeedsOptionalModifier() bool
  • func (f FieldInfo) NeedsPointerNilable() bool
  • func (f FieldInfo) NeedsPointerOptional() bool
  • func (f FieldInfo) NeedsRegexpImport() bool
  • func (f FieldInfo) NeedsStringsImport() bool
  • func (f FieldInfo) RequiredImports() []string
  • func (f FieldInfo) RulesExcept(names ...string) []TagRule
  • func (f FieldInfo) UsesTimeImport() bool
  • func (f FieldInfo) ValidationRules() []TagRule
  • func (f FieldInfo) ValidationRulesExcept(names ...string) []TagRule
• type FieldNameResult
  • func FieldName(tagName string, f reflect.StructField) FieldNameResult
• type FieldPlan
  • func CompileFieldPlan(field *FieldInfo) FieldPlan
  • func (p FieldPlan) OperationsExcept(names ...string) []RulePlan
• type OptionalPlacement
• type RuleOp
• type RulePlan
  • func CompileRule(rule TagRule) RulePlan
  • func (p RulePlan) FirstParam() (string, bool)
  • func (p RulePlan) JoinedValue() (string, bool)
• type TagParser
  • func New() *TagParser
  • func NewWithTagName(name string) *TagParser
  • func NewWithTags(ruleTag, fieldNameTag string) *TagParser
  • func (p *TagParser) ParseStructTags(typ reflect.Type) ([]FieldInfo, error)
  • func (p *TagParser) ParseStructTagsStrict(typ reflect.Type) ([]FieldInfo, error)
  • func (p *TagParser) ParseTagString(tag string) ([]TagRule, error)
• type TagRule

Variables

var ErrEmptyRuleName = errors.New("tagparser: empty rule name")

ErrEmptyRuleName indicates that a tag rule has no rule name.

var ErrRuleRequiresParam = errors.New("tagparser: rule requires a parameter")

ErrRuleRequiresParam indicates that a tag rule used "=" without a value.

var ErrTypeMustBeStruct = errors.New("tagparser: type must be a struct or pointer to struct")

ErrTypeMustBeStruct indicates that the input type is neither a struct nor a pointer to struct.

Types

type FieldInfo

type FieldInfo struct {
	Name     string       // Go field name
	Type     reflect.Type // field type
	TypeName string       // AST type name for circular reference detection
	FieldKey string       // from the field-name tag, or Go field name
	GoZodTag string       // raw gozod tag value
	Rules    []TagRule    // parsed tag rules before helper-level filtering
	Required bool         // whether the parsed rules include "required"
	Optional bool         // derived optionality for parsed-tag callers
	Nilable  bool         // whether the parsed rules include "nilable"
}

FieldInfo represents parsed information about a struct field.

func (FieldInfo) EffectiveTypeName

func (f FieldInfo) EffectiveTypeName() string

EffectiveTypeName returns the best available type name for codegen.

func (FieldInfo) EnumRule

func (f FieldInfo) EnumRule() *TagRule

EnumRule returns the enum rule if present.

func (FieldInfo) HasCoerceRule

func (f FieldInfo) HasCoerceRule() bool

HasCoerceRule reports whether the field enables coercion.

func (FieldInfo) HasRule

func (f FieldInfo) HasRule(name string) bool

HasRule reports whether a parsed rule with the given name exists.

func (FieldInfo) HasRules

func (f FieldInfo) HasRules() bool

HasRules reports whether the field has any parsed tag rules.

func (FieldInfo) HasSchemaSpec

func (f FieldInfo) HasSchemaSpec() bool

HasSchemaSpec reports whether the field has tag-derived schema semantics. Runtime/codegen consumers should prefer helper methods on FieldInfo instead of open-coding logic from the raw fields.

func (FieldInfo) IsEnumStringField

func (f FieldInfo) IsEnumStringField() bool

IsEnumStringField reports whether this field should use the Enum constructor.

func (FieldInfo) IsPointerType

func (f FieldInfo) IsPointerType() bool

IsPointerType reports whether the field type is a pointer.

func (FieldInfo) IsUUIDStringField

func (f FieldInfo) IsUUIDStringField() bool

IsUUIDStringField reports whether this field should use the UUID constructor.

func (FieldInfo) NeedsCoreImport

func (f FieldInfo) NeedsCoreImport() bool

NeedsCoreImport reports whether codegen should import core.

func (FieldInfo) NeedsGeneratedOptional

func (f FieldInfo) NeedsGeneratedOptional() bool

NeedsGeneratedOptional reports whether generated schema code should append .Optional() after applying all rules.

func (FieldInfo) NeedsNetImport

func (f FieldInfo) NeedsNetImport() bool

NeedsNetImport reports whether codegen should import net. IP tags generate root GoZod constructors and do not need net.

func (FieldInfo) NeedsNetURLImport

func (f FieldInfo) NeedsNetURLImport() bool

NeedsNetURLImport reports whether codegen should import net/url. URL tags generate root GoZod constructors and do not need net/url.

func (FieldInfo) NeedsOptionalModifier

func (f FieldInfo) NeedsOptionalModifier() bool

NeedsOptionalModifier reports whether generated schema code should append .Optional() for this field.

func (FieldInfo) NeedsPointerNilable

func (f FieldInfo) NeedsPointerNilable() bool

NeedsPointerNilable reports whether a pointer-backed schema should become nilable during struct-schema derivation.

func (FieldInfo) NeedsPointerOptional

func (f FieldInfo) NeedsPointerOptional() bool

NeedsPointerOptional reports whether pointer field rules should add Optional() at the end of parsed tag application.

func (FieldInfo) NeedsRegexpImport

func (f FieldInfo) NeedsRegexpImport() bool

NeedsRegexpImport reports whether codegen should import regexp.

func (FieldInfo) NeedsStringsImport

func (f FieldInfo) NeedsStringsImport() bool

NeedsStringsImport reports whether codegen should import strings.

func (FieldInfo) RequiredImports

func (f FieldInfo) RequiredImports() []string

RequiredImports returns the non-gozod imports needed to generate this field.

func (FieldInfo) RulesExcept

func (f FieldInfo) RulesExcept(names ...string) []TagRule

RulesExcept returns all parsed rules except those whose names are excluded.

func (FieldInfo) UsesTimeImport

func (f FieldInfo) UsesTimeImport() bool

UsesTimeImport reports whether codegen should import time for this field.

func (FieldInfo) ValidationRules

func (f FieldInfo) ValidationRules() []TagRule

ValidationRules returns tag rules that should become schema modifiers or checks at runtime/codegen. Structural rules are handled elsewhere.

func (FieldInfo) ValidationRulesExcept

func (f FieldInfo) ValidationRulesExcept(names ...string) []TagRule

ValidationRulesExcept returns validation rules except those explicitly excluded.

type FieldNameResult

type FieldNameResult struct {
	Name string
	Skip bool
}

FieldNameResult represents the resolved schema key for a struct field.

func FieldName

func FieldName(tagName string, f reflect.StructField) FieldNameResult

FieldName resolves the field name and skip marker for a struct field using the named struct tag (e.g. "json", "yaml", "toml"). An absent tag falls back to the Go field name; a tag value of "-" marks the field as skipped.

type FieldPlan

type FieldPlan struct {
	Operations             []RulePlan
	RuntimePointerOptional OptionalPlacement
	GeneratedOptional      OptionalPlacement
}

FieldPlan is the shared semantic plan for a parsed struct field.

func CompileFieldPlan

func CompileFieldPlan(field *FieldInfo) FieldPlan

CompileFieldPlan converts parsed field facts into semantic operations shared by runtime reflection and code generation.

func (FieldPlan) OperationsExcept

func (p FieldPlan) OperationsExcept(names ...string) []RulePlan

OperationsExcept returns planned operations except those for the named raw rules.

type OptionalPlacement

type OptionalPlacement string

OptionalPlacement describes where an Optional modifier belongs relative to field operations when a backend must express optionality as a fluent call.

const (
	// OptionalPlacementNone means no generated Optional modifier is needed.
	OptionalPlacementNone OptionalPlacement = "none"
	// OptionalPlacementBeforeOperations places Optional before planned rule operations.
	OptionalPlacementBeforeOperations OptionalPlacement = "before_operations"
	// OptionalPlacementAfterOperations places Optional after planned rule operations.
	OptionalPlacementAfterOperations OptionalPlacement = "after_operations"
)

type RuleOp

type RuleOp string

RuleOp identifies the semantic operation represented by a tag rule.

const (
	RuleStructural  RuleOp = "structural"
	RuleMethod      RuleOp = "method"
	RuleStringCheck RuleOp = "string_check"
	RuleTime        RuleOp = "time"
	RulePositive    RuleOp = "positive"
	RuleNegative    RuleOp = "negative"
	RuleFinite      RuleOp = "finite"
	RuleNonEmpty    RuleOp = "nonempty"
	RuleEnum        RuleOp = "enum"
	RuleLiteral     RuleOp = "literal"
	RuleDefault     RuleOp = "default"
	RulePrefault    RuleOp = "prefault"
	RuleUnsupported RuleOp = "unsupported"
)

RuleOp values describe shared tag-rule operations.

type RulePlan

type RulePlan struct {
	Rule   TagRule
	Op     RuleOp
	Method string
}

RulePlan is the shared semantic plan for a parsed tag rule.

func CompileRule

func CompileRule(rule TagRule) RulePlan

CompileRule converts a parsed tag rule into a shared semantic plan.

func (RulePlan) FirstParam

func (p RulePlan) FirstParam() (string, bool)

FirstParam returns the first parameter for rules that take one argument.

func (RulePlan) JoinedValue

func (p RulePlan) JoinedValue() (string, bool)

JoinedValue returns a single value for default-like rules.

type TagParser

type TagParser struct {
	// contains filtered or unexported fields
}

TagParser handles gozod tag parsing with configurable tag names. rulesTagName selects the rule tag (default "gozod"); fieldNameTag selects the tag that supplies field names (default "json").

func New

func New() *TagParser

New creates a TagParser with the default "gozod" rule tag and "json" field-name tag.

func NewWithTagName

func NewWithTagName(name string) *TagParser

NewWithTagName creates a TagParser with a custom rule tag and the default "json" field-name tag.

func NewWithTags

func NewWithTags(ruleTag, fieldNameTag string) *TagParser

NewWithTags creates a TagParser with custom rule and field-name tags. Empty values fall back to the defaults ("gozod" and "json").

func (*TagParser) ParseStructTags

func (p *TagParser) ParseStructTags(typ reflect.Type) ([]FieldInfo, error)

ParseStructTags parses all gozod tags in a struct type and returns FieldInfo for each exported field.

Non-struct input returns an empty slice and no error. Use [ParseStructTagsStrict] when non-struct input should fail.

func (*TagParser) ParseStructTagsStrict

func (p *TagParser) ParseStructTagsStrict(typ reflect.Type) ([]FieldInfo, error)

ParseStructTagsStrict parses all gozod tags in a struct type and returns ErrTypeMustBeStruct for non-struct input.

func (*TagParser) ParseTagString

func (p *TagParser) ParseTagString(tag string) ([]TagRule, error)

ParseTagString parses a single tag string into TagRule values.

type TagRule

type TagRule struct {
	Name   string   // e.g., "min", "max", "email"
	Params []string // e.g., ["2"] for "min=2"
}

TagRule represents a single validation rule parsed from a tag.