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 ¶
- Variables
- type Alternation
- type CharValElement
- type Concatenation
- type CoreRuleModificationError
- type DependencyNotFoundError
- type DuplicatedRuleError
- type Element
- type Grammar
- type GroupElement
- type InvalidNumeralError
- type InvalidRepetitionError
- type MultipleSolutionsFoundError
- type NumValElement
- type NumValStatus
- type OptionElement
- type Path
- type ProseValElement
- type Repetition
- type Rule
- type RuleNotFoundError
- type RulenameElement
Constants ¶
This section is empty.
Variables ¶
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 ¶
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 ¶
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.
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 ¶
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:
- An operation budget in the solve functions that turns pathological inputs into an error, without changing matching behavior.
- 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).
- 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 ¶
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.
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