parser

Documentation

Overview

Package parser provides an extensible parsing system for swagger directives. It allows registering custom parsers for different contexts (meta, route, model, etc.) and provides a thread-safe registry for managing parsers.

Index

• func Register(directive Directive, parser TagParser)
• type BaseParser
  • func NewBaseParser(name string, parserType ParserType, contexts []Context, setters SetterMap) BaseParser
  • func (p *BaseParser) ApplyWithSetter(target any, value any, ctx Context) error
  • func (p *BaseParser) Contexts() []Context
  • func (p *BaseParser) GetSetter(ctx Context) (SetterFunc, bool)
  • func (p *BaseParser) Name() string
  • func (p *BaseParser) SupportsContext(ctx Context) bool
  • func (p *BaseParser) Type() ParserType
• type Context
• type Directive
• type ErrInvalidTarget
  • func (e *ErrInvalidTarget) Error() string
• type ErrNoSetterForContext
  • func (e *ErrNoSetterForContext) Error() string
• type ErrParseFailure
  • func (e *ErrParseFailure) Error() string
  • func (e *ErrParseFailure) Unwrap() error
• type ErrParserNotFound
  • func (e *ErrParserNotFound) Error() string
• type ParserType
• type Registry
  • func Global() *Registry
  • func NewRegistry() *Registry
  • func (r *Registry) Clear()
  • func (r *Registry) Count() int
  • func (r *Registry) GetParsers(directive Directive) []TagParser
  • func (r *Registry) List() map[Directive][]string
  • func (r *Registry) Parse(directive Directive, comments *ast.CommentGroup, target any, ctx Context) error
  • func (r *Registry) ParseAll(directive Directive, comments *ast.CommentGroup, targets map[Context]any) error
  • func (r *Registry) Register(directive Directive, parser TagParser)
  • func (r *Registry) Unregister(directive Directive, parserName string)
• type SetterFunc
• type SetterMap
• type TagParser

Functions

func Register

func Register(directive Directive, parser TagParser)

Register adds a parser for a specific directive to the global registry.

Types

type BaseParser

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

BaseParser provides common functionality for all parsers. Embed this in your parser implementation to get default behaviors.

func NewBaseParser

func NewBaseParser(name string, parserType ParserType, contexts []Context, setters SetterMap) BaseParser

NewBaseParser creates a new BaseParser with the given configuration.

func (*BaseParser) ApplyWithSetter

func (p *BaseParser) ApplyWithSetter(target any, value any, ctx Context) error

ApplyWithSetter applies a value using the context's setter function.

func (*BaseParser) Contexts

func (p *BaseParser) Contexts() []Context

Contexts returns the supported contexts.

func (*BaseParser) GetSetter

func (p *BaseParser) GetSetter(ctx Context) (SetterFunc, bool)

GetSetter returns the setter function for a specific context.

func (*BaseParser) Name

func (p *BaseParser) Name() string

Name returns the parser name.

func (*BaseParser) SupportsContext

func (p *BaseParser) SupportsContext(ctx Context) bool

SupportsContext checks if the parser supports a specific context.

func (*BaseParser) Type

func (p *BaseParser) Type() ParserType

Type returns the parser type.

type Context

type Context string

Context defines the context where parsing is happening. Different contexts may have different parsing rules and targets.

const (
	// ContextMeta is used when parsing swagger:meta comments.
	ContextMeta Context = "meta"

	// ContextRoute is used when parsing swagger:route comments.
	ContextRoute Context = "route"

	// ContextModel is used when parsing swagger:model comments.
	ContextModel Context = "model"

	// ContextField is used when parsing field-level comments in models.
	ContextField Context = "field"

	// ContextParameter is used when parsing swagger:parameters comments.
	ContextParameter Context = "parameter"

	// ContextEnum is used when parsing swagger:enum comments.
	ContextEnum Context = "enum"
)

type Directive

type Directive string

Directive represents a swagger directive type.

const (
	DirectiveMeta       Directive = "swagger:meta"
	DirectiveRoute      Directive = "swagger:route"
	DirectiveModel      Directive = "swagger:model"
	DirectiveParameters Directive = "swagger:parameters"
	DirectiveEnum       Directive = "swagger:enum"
	DirectiveAllOf      Directive = "swagger:allOf"
	DirectiveStrFmt     Directive = "swagger:strfmt"
)

type ErrInvalidTarget

type ErrInvalidTarget struct {
	ParserName   string
	ExpectedType string
	ActualType   string
}

ErrInvalidTarget is returned when the target type doesn't match what the parser expects.

func (*ErrInvalidTarget) Error

func (e *ErrInvalidTarget) Error() string

type ErrNoSetterForContext

type ErrNoSetterForContext struct {
	ParserName string
	Context    Context
}

ErrNoSetterForContext is returned when a parser doesn't have a setter for the given context.

func (*ErrNoSetterForContext) Error

func (e *ErrNoSetterForContext) Error() string

type ErrParseFailure

type ErrParseFailure struct {
	ParserName string
	Context    Context
	Cause      error
}

ErrParseFailure is returned when parsing fails.

func (*ErrParseFailure) Error

func (e *ErrParseFailure) Error() string

func (*ErrParseFailure) Unwrap

func (e *ErrParseFailure) Unwrap() error

type ErrParserNotFound

type ErrParserNotFound struct {
	Directive Directive
}

ErrParserNotFound is returned when no parser is registered for a directive.

func (*ErrParserNotFound) Error

func (e *ErrParserNotFound) Error() string

type ParserType

type ParserType int

ParserType indicates how the parser processes comments.

const (
	// ParserTypeSingleLine parses a single line (e.g., "Summary: text").
	ParserTypeSingleLine ParserType = iota

	// ParserTypeMultiLine parses multiple lines (e.g., "Description:\n line1\n line2").
	ParserTypeMultiLine

	// ParserTypeYAML parses YAML content from comments.
	ParserTypeYAML

	// ParserTypeJSON parses JSON content from comments.
	ParserTypeJSON

	// ParserTypeList parses comma or space-separated lists.
	ParserTypeList

	// ParserTypeKeyValue parses key:value pairs.
	ParserTypeKeyValue
)

type Registry

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

Registry maintains a thread-safe registry of all available parsers. Parsers can be registered for specific directives and are executed in the order they were registered.

func Global

func Global() *Registry

Global returns the global parser registry.

func NewRegistry

func NewRegistry() *Registry

NewRegistry creates a new empty parser registry.

func (*Registry) Clear

func (r *Registry) Clear()

Clear removes all registered parsers. Useful for testing.

func (*Registry) Count

func (r *Registry) Count() int

Count returns the total number of registered parsers.

func (*Registry) GetParsers

func (r *Registry) GetParsers(directive Directive) []TagParser

GetParsers returns all parsers registered for a directive.

func (*Registry) List

func (r *Registry) List() map[Directive][]string

List returns a map of all registered directives and their parser names.

func (*Registry) Parse

func (r *Registry) Parse(
	directive Directive,
	comments *ast.CommentGroup,
	target any,
	ctx Context,
) error

Parse executes all matching parsers for a directive with a specific context. It iterates through all registered parsers for the directive and: 1. Checks if the parser matches the comment 2. Parses the value 3. Applies the value to the target

func (*Registry) ParseAll

func (r *Registry) ParseAll(
	directive Directive,
	comments *ast.CommentGroup,
	targets map[Context]any,
) error

ParseAll executes parsers for multiple contexts with their respective targets.

func (*Registry) Register

func (r *Registry) Register(directive Directive, parser TagParser)

Register adds a parser for a specific directive. Multiple parsers can be registered for the same directive.

func (*Registry) Unregister

func (r *Registry) Unregister(directive Directive, parserName string)

Unregister removes a parser by name from a directive.

type SetterFunc

type SetterFunc func(target any, value any) error

SetterFunc is a function that applies a value to a target object. It's used to decouple parsing from applying values.

type SetterMap

type SetterMap map[Context]SetterFunc

SetterMap maps contexts to their corresponding setter functions. This allows a single parser to have different behaviors for different contexts.

type TagParser

type TagParser interface {
	// Name returns the unique name of this parser.
	Name() string

	// Contexts returns the contexts where this parser is applicable.
	// For example, a "Description" parser might work in both ContextRoute and ContextModel.
	Contexts() []Context

	// Matches checks if this parser can handle the given comment in the specified context.
	Matches(comment string, ctx Context) bool

	// Parse extracts the value from the comment group.
	// Returns the parsed value and any error encountered.
	Parse(comments *ast.CommentGroup, ctx Context) (any, error)

	// Apply applies the parsed value to the target object.
	// The target type depends on the context (e.g., *spec.Operation for ContextRoute).
	Apply(target any, value any, ctx Context) error
}

TagParser is the interface that all tag/directive parsers must implement. Parsers are responsible for: 1. Matching comments they can handle 2. Extracting values from comments 3. Applying values to target objects