abnf

package
v1.1.0 Latest Latest
Warning

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

Go to latest
Published: Aug 10, 2026 License: MIT, MIT Imports: 9 Imported by: 0

Documentation

Overview

Package abnf provides ABNF (RFC 5234, with the RFC 7405 char-val extension) grammar parsing and input matching.

ParseABNF parses an ABNF grammar definition into a Grammar, and Parse matches an input against a rule of such a grammar, producing match Paths.

The package is derived from github.com/pandatix/go-abnf v0.4.2, Copyright (c) 2024 Lucas TESSON - PandatiX, licensed under the MIT License (see the LICENSE file in this directory), restructured for this module and reduced to grammar parsing and input matching.

Index

Constants

This section is empty.

Variables

View Source
var ErrNoSolutionFound = errors.New("no solution found, the input ABNF grammar may be invalid")

ErrNoSolutionFound is returned when parsing an ABNF grammar definition yields no solution, meaning the definition is invalid.

Functions

This section is empty.

Types

type Alternation

type Alternation struct {
	Concatenations []*Concatenation
}

Alternation is an ABNF alternation: a choice between concatenations.

func (*Alternation) String

func (alternation *Alternation) String() string

type CharValElement

type CharValElement struct {
	Sensitive bool
	Value     string
}

CharValElement is an ABNF char-val element: a literal string of printable US-ASCII characters. Matching is case-insensitive unless Sensitive is set (the RFC 7405 "%s" form).

func (*CharValElement) String

func (element *CharValElement) String() string

type Concatenation

type Concatenation struct {
	Repetitions []*Repetition
}

Concatenation is an ABNF concatenation: an ordered sequence of repetitions.

func (*Concatenation) String

func (concatenation *Concatenation) String() string

type CoreRuleModificationError

type CoreRuleModificationError struct {
	Rulename string
}

CoreRuleModificationError is returned when a grammar attempts to redefine or extend a core rule.

func (*CoreRuleModificationError) Error

func (coreRuleModificationError *CoreRuleModificationError) Error() string

type DependencyNotFoundError

type DependencyNotFoundError struct {
	Rulename string
}

DependencyNotFoundError is returned during semantic validation when a rule references a rule that does not exist.

func (*DependencyNotFoundError) Error

func (dependencyNotFoundError *DependencyNotFoundError) Error() string

type DuplicatedRuleError

type DuplicatedRuleError struct {
	Rulename string
}

DuplicatedRuleError is returned when a grammar defines the same rule more than once.

func (*DuplicatedRuleError) Error

func (duplicatedRuleError *DuplicatedRuleError) Error() string

type Element

type Element interface {
	fmt.Stringer
	// contains filtered or unexported methods
}

Element is the interface implemented by all ABNF element variants: *RulenameElement, *GroupElement, *OptionElement, *CharValElement, *NumValElement and *ProseValElement.

type Grammar

type Grammar struct {
	// Rulemap indexes the rules by lowercase rule name.
	Rulemap map[string]*Rule
}

Grammar is an ABNF grammar as defined by RFC 5234: a set of uniquely named rules.

func ParseABNF

func ParseABNF(input []byte) (*Grammar, error)

ParseABNF parses an ABNF grammar definition as specified by RFC 5234, with the RFC 7405 char-val extension. The input must use CRLF line endings, including on the last line. The resulting grammar is semantically validated.

func (*Grammar) String

func (grammar *Grammar) String() string

String returns an ABNF representation of the grammar, using CRLF line endings as the specification requires. The rule order is unspecified.

type GroupElement

type GroupElement struct {
	Alternation *Alternation
}

GroupElement is an ABNF group element: a parenthesised alternation.

func (*GroupElement) String

func (element *GroupElement) String() string

type InvalidNumeralError

type InvalidNumeralError struct {
	Base, Value string
}

InvalidNumeralError is returned when a num-val numeral cannot be represented as a Unicode code point in its base.

func (*InvalidNumeralError) Error

func (invalidNumeralError *InvalidNumeralError) Error() string

type InvalidRepetitionError

type InvalidRepetitionError struct {
	Repetition *Repetition
}

InvalidRepetitionError is returned during semantic validation when a repetition has a minimum greater than its maximum.

func (*InvalidRepetitionError) Error

func (invalidRepetitionError *InvalidRepetitionError) Error() string

type MultipleSolutionsFoundError

type MultipleSolutionsFoundError struct {
	Paths []*Path
}

MultipleSolutionsFoundError is returned when parsing found multiple solutions where at most one was expected.

func (*MultipleSolutionsFoundError) Error

func (multipleSolutionsFoundError *MultipleSolutionsFoundError) Error() string

type NumValElement

type NumValElement struct {
	// Base is the num-val base character: "b", "d" or "x".
	Base   string
	Status NumValStatus
	Values []string
}

NumValElement is an ABNF num-val element: numeric character values in a given base, either as a series or as a range.

func (*NumValElement) String

func (element *NumValElement) String() string

type NumValStatus

type NumValStatus int

NumValStatus defines how the values of a NumValElement combine.

const (
	// NumValStatusSeries matches each value in order.
	NumValStatusSeries NumValStatus = iota
	// NumValStatusRange matches any value within the two bounds.
	NumValStatusRange
)

type OptionElement

type OptionElement struct {
	Alternation *Alternation
}

OptionElement is an ABNF option element: a bracketed alternation, equivalent to a 0*1 repetition of it.

func (*OptionElement) String

func (element *OptionElement) String() string

type Path

type Path struct {
	// Subpaths are the ordered child paths.
	Subpaths []*Path
	// MatchRule is the name of the matched rule in the source grammar, or
	// empty for structural paths.
	MatchRule string
	// Start and End delimit the matched input bytes; Start <= End.
	Start, End int
}

Path describes a portion of an input that matched a grammar rule, from a start index to an end index, with a composite structure.

func Parse

func Parse(input []byte, grammar *Grammar, rootRulename string) ([]*Path, error)

Parse parses input using the given grammar, starting from the named root rule. It uses a top-down parsing strategy with backtracking and returns every solution that consumed the whole input. The grammar must be semantically valid, as produced by ParseABNF.

The backtracking makes the worst-case running time exponential in the input length; callers parsing untrusted input should bound its length. TODO: If hardening against pathological inputs is ever needed, the options are, in increasing order of effort:

  1. An operation budget in the solve functions that turns pathological inputs into an error, without changing matching behavior.
  2. Memoizing rule results by (rulename, index), which removes the redundant recomputation behind the exponential blowup, but requires making cached paths immutable first (MatchRule is stamped and subpath slices are truncated on shared results after the fact).
  3. Returning a shared packed parse forest, as the all-solutions return type can itself be exponentially large for ambiguous grammars; this also affects path consumers such as pkg/abnf/utils.

type ProseValElement

type ProseValElement struct {
	Value string
}

ProseValElement is an ABNF prose-val element: a free-form prose description that cannot be matched against input.

func (*ProseValElement) String

func (element *ProseValElement) String() string

type Repetition

type Repetition struct {
	Min, Max int
	Element  Element
}

Repetition is an ABNF repetition of an element. Max may be inf (-1) for an unbounded repetition.

func (*Repetition) String

func (repetition *Repetition) String() string

type Rule

type Rule struct {
	// Name is the rule name, case-insensitive according to RFC 5234
	// Section 2.1.
	Name        string
	Alternation *Alternation
}

Rule is an ABNF rule: a unique name and its defining alternation.

func (*Rule) String

func (rule *Rule) String() string

type RuleNotFoundError

type RuleNotFoundError struct {
	Rulename string
}

RuleNotFoundError is returned when a rule is not part of the grammar.

func (*RuleNotFoundError) Error

func (ruleNotFoundError *RuleNotFoundError) Error() string

type RulenameElement

type RulenameElement struct {
	// Name is the referenced rule name, case-insensitive according to
	// RFC 5234 Section 2.1.
	Name string
}

RulenameElement is an ABNF rulename element: a reference to another rule.

func (*RulenameElement) String

func (element *RulenameElement) String() string

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL