pattern

Documentation

Overview

Package pattern parses Go 1.22+ net/http.ServeMux pattern strings.

Index

• func IsOpenAPIMethod(s string) bool
• type Pattern
  • func MustParsePattern(s string) *Pattern
  • func ParsePattern(s string) (*Pattern, error)
  • func (p *Pattern) HasMethod() bool
  • func (p *Pattern) Path() string
  • func (p *Pattern) String() string
  • func (p *Pattern) WildcardNames() []string
• type PatternKind
• type Segment

Functions

func IsOpenAPIMethod

func IsOpenAPIMethod(s string) bool

IsOpenAPIMethod reports whether s is one of the eight fixed Path Item operation keys shared by OpenAPI 3.0 and 3.1. (OpenAPI 3.2 additionally allows "query" and arbitrary methods via additionalOperations; that version-specific logic lives in the emitter.) The "head" key is a special case: it is allowed in OpenAPI but is *also* implicitly registered by registering "get" (per RFC 7231); stdocs emits "head" only if the user registered it explicitly.

Types

type Pattern

type Pattern struct {
	// Original is the original pattern string, exactly as passed to ServeMux.
	Original string
	// Method is the upper-case HTTP method (e.g. "GET"), or "" if no method was specified.
	Method string
	// Host is the literal host (e.g. "example.com"), or "" if no host was specified.
	Host string
	// Segments is the ordered list of path segments. The leading slash is implicit.
	Segments []Segment
	// IsPrefix is true if the path ends in "/" (i.e. a prefix match).
	// Trailing-slash patterns expand to an implicit Multi("") at parse time.
	IsPrefix bool
}

Pattern is a parsed stdlib ServeMux pattern.

Examples:

"GET /users/{id}"        -> Method="GET", Host="", Segments=[Literal("users"), Wildcard("id")]
"/files/{path...}"       -> Method="",   Host="", Segments=[Literal("files"), Multi("path")]
"example.com/posts/{$}"  -> Method="",   Host="example.com", Segments=[Literal("posts"), Trailing]
"/"                      -> Method="",   Host="", Segments=[]

func MustParsePattern

func MustParsePattern(s string) *Pattern

MustParsePattern is like ParsePattern but panics on error.

func ParsePattern

func ParsePattern(s string) (*Pattern, error)

ParsePattern parses a stdlib net/http.ServeMux pattern string (Go 1.22+). The syntax is "[METHOD ] [HOST]/[PATH]" where METHOD, HOST, and PATH are independently optional. METHOD is one of GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS/CONNECT. HOST is a literal hostname. PATH consists of slash-separated segments which may include the wildcards "{name}" (single segment), "{name...}" (rest of path, must be the last segment), and "{$}" (trailing-slash anchor, must be the last segment).

Trailing slashes are treated as prefix matches: "/posts/" matches "/posts/", "/posts/123", etc. They are represented internally as a KindMulti("") wildcard.

The original stdlib parsePattern lives in src/net/http/pattern.go. This is a from-scratch implementation that produces a Pattern value suitable for OpenAPI spec generation. ParsePattern parses a Go 1.22+ http.ServeMux pattern. See the package-level comment for the supported subset.

func (*Pattern) HasMethod

func (p *Pattern) HasMethod() bool

HasMethod reports whether the pattern specifies an HTTP method.

func (*Pattern) Path

func (p *Pattern) Path() string

Path returns the OpenAPI-style path string with literal "{" and "}" in wildcards preserved. The returned path always starts with "/".

"GET /users/{id}"  -> "/users/{id}"
"/files/{path...}" -> "/files/{path}"  (Go's "..." syntax collapses)
"/posts/{$}"       -> "/posts/"
"/posts/"          -> "/posts/"
"/"                -> "/"

func (*Pattern) String

func (p *Pattern) String() string

String returns the original pattern string.

func (*Pattern) WildcardNames

func (p *Pattern) WildcardNames() []string

WildcardNames returns the names of all named wildcards in declaration order. Multi wildcards and single-segment wildcards are both included. The special "{$}" trailing-anchor has no name and is not included. Anonymous wildcards (those with an empty Value, produced implicitly by trailing slashes) are also filtered out — they are not valid OpenAPI path parameters and emitting them produces a spec-invalid empty-name parameter.

type PatternKind

type PatternKind uint8

PatternKind classifies a parsed stdlib ServeMux pattern segment.

const (
	// KindLiteral matches an exact path segment.
	KindLiteral PatternKind = iota
	// KindWildcard matches a single path segment and captures it under Name.
	KindWildcard
	// KindMulti matches the remainder of the path and captures it under Name.
	KindMulti
	// KindTrailing is the literal "/" used in /foo/{$} for the exact-trailing-slash anchor.
	KindTrailing
)

type Segment

type Segment struct {
	// Kind is the kind of segment.
	Kind PatternKind
	// Value is the literal value for KindLiteral, the wildcard name for KindWildcard
	// and KindMulti, and "/" for KindTrailing.
	Value string
}

Segment is one piece of a parsed path.