parser

Documentation

Overview

Package parser provides text parsing utilities for extracting structured information from comments.

This package contains pure text parsing logic with no AST dependencies. It parses:

• Test values from "Examples:" sections in doc comments
• Tagged comments (domain, maintainer, note, mention)
• Domain descriptions from package-level comments

The parsers use regular expressions to identify sections and extract values. All parsing is case-insensitive and supports multiple formatting styles.

Index

• func DomainFromExtraComments(taggedComments []model.ExtraComment) string
• func ParseDomainDescriptions(text string) []model.ExtraComment
• func ParseExprWithFileSet(fset *token.FileSet, filename string, input string) ([]model.TestValue, error)
• func ParseTaggedComments(text string) []model.ExtraComment
• func ParseTestExamples(text string) []model.Test
• func ParseTestValues(input string) []model.TestValue
• func RelocateTestValue(tv model.TestValue, fromPkg, toPkg string) model.TestValue
• func StartAnotherSection(text string) bool
• func StartSectionFunc(placeholder string) func(string) bool
• func StartValueFunc(placeholder string) func(string) (string, bool)

Functions

func DomainFromExtraComments

func DomainFromExtraComments(taggedComments []model.ExtraComment) string

DomainFromExtraComments retrieves the domain from preparsed extra (tagged) comment.

func ParseDomainDescriptions

func ParseDomainDescriptions(text string) []model.ExtraComment

ParseDomainDescriptions extracts domain descriptions from package-level comment text.

It looks for a "Domains:" or "Domain:" section with entries like:

• string: assertions on strings
• json: assertions on JSON documents

The domain name is normalized to lowercase.

func ParseExprWithFileSet

func ParseExprWithFileSet(fset *token.FileSet, filename string, input string) ([]model.TestValue, error)

ParseExprWithFileSet is like ParseTestValues but uses a provided FileSet for better error reporting with file/line/column information.

The filename parameter is used for error messages (e.g., "assertion.go:42").

func ParseTaggedComments

func ParseTaggedComments(text string) []model.ExtraComment

ParseTaggedComments extracts tagged comments from text.

Recognized tags:

• domain: <value> - single-line domain tag
• maintainer: <value> - multi-line maintainer note
• note: <value> - multi-line note
• mention: <value> - single-line mention

Multi-line tags continue until the next tagged line or end of text.

func ParseTestExamples

func ParseTestExamples(text string) []model.Test

ParseTestExamples extracts test examples from doc comment text.

It looks for an "Examples:" or "Example:" section and parses lines like:

• success: <test values>
• failure: <test values>
• panic: <assertion message>

After each value line, an optional comment line can provide an assertion message. Empty values or values marked "// NOT IMPLEMENTED" are skipped.

func ParseTestValues

func ParseTestValues(input string) []model.TestValue

ParseTestValues parses a comma-separated list of Go expressions.

Examples:

• "123, 456" → two integer literals
• "assertions.ErrTest, nil" → selector expression and nil
• "[]int{1,2,3}, []int{4,5,6}" → two composite literals
• `"a,b", "c,d"` → two string literals with commas inside

Implementation: Wraps input in []any{...} and parses as composite literal, then extracts the elements. This leverages Go's parser to handle all edge cases (strings, runes, comments, nesting, etc.) correctly.

func RelocateTestValue

func RelocateTestValue(tv model.TestValue, fromPkg, toPkg string) model.TestValue

RelocateTestValue relocates a test value expression from one package to another.

It walks the AST and:

1. Changes qualified identifiers: fromPkg.X → toPkg.X (except exceptions)
2. Qualifies unqualified exported identifiers: X → toPkg.X

Exception: PanicTestFunc always stays with assertions package.

func StartAnotherSection

func StartAnotherSection(text string) bool

StartAnotherSection checks if a line starts a new section.

A line starts a new section if it either:

• Starts with a capital letter and ends with a colon (e.g., "Usage:")
• Starts with "# " (markdown header)

func StartSectionFunc

func StartSectionFunc(placeholder string) func(string) bool

StartSectionFunc creates a matcher function for section headers.

A section header can be:

• "# Placeholder" or "# Placeholders" (markdown-style)
• "Placeholder:" or "Placeholders:" (simple colon-style)

Matching is case-insensitive.

func StartValueFunc

func StartValueFunc(placeholder string) func(string) (string, bool)

StartValueFunc creates a matcher function for key-value lines.

A value line has the format: "placeholder: value" Returns the value part (everything after the colon) and true if matched. Matching is case-insensitive.