tabnasabnf

README

github.com/tabnas/abnf/go

Go port of @tabnas/abnf — an ABNF grammar compiler for the tabnas parsing engine.

Takes ABNF source — the RFC 5234 dialect (= and /, not ::=) — and emits a tabnas GrammarSpec that, installed on an engine, parses inputs in that grammar and builds a {rule, src, kids} AST. Also emits "pure-data" jsonic (recognition / full-AST specs), supports user actions, and ships a CLI (tabnas-abnf).

The Go package tracks the canonical TypeScript implementation in ../ts; both compile the same .abnf fixtures (in ../ts/test/grammar/) and produce the same parse output.

Install

go get github.com/tabnas/abnf/go

Use

package main

import (
	"fmt"

	abnf "github.com/tabnas/abnf/go"
	tabnas "github.com/tabnas/parser/go"
)

func main() {
	spec, _ := abnf.Abnf(`greet = "hi" / "hello"`, nil)
	j := tabnas.Make()
	j.Grammar(spec)
	out, _ := j.Parse("hi")
	fmt.Println(out) // map[kids:[] rule:greet src:hi]
}

Documentation

Four-quadrant Diátaxis docs:

• tutorial.md — learning-oriented: zero to a working parser, step by step.
• guide.md — task-oriented recipes for real problems.
• reference.md — the exact exported API and CLI flags.
• concepts.md — how it works, plus differences from the TS version.

CLI

go run ./cmd/tabnas-abnf -f grammar.abnf
go run ./cmd/tabnas-abnf 'greet = "hi" / "hello"' --parse 'hi'
go run ./cmd/tabnas-abnf -C 'greet = "hi"'   # compile to pure-data jsonic
go run ./cmd/tabnas-abnf -m 'op = "inc" / "dec"'  # list action marks

License

MIT.

Documentation

Overview

Package tabnasabnf is an ABNF -> tabnas GrammarSpec compiler for the tabnas parsing engine (github.com/tabnas/parser/go). It is a faithful Go port of the @tabnas/abnf TypeScript package.

Given a small ABNF dialect it produces a function-free (when requested) GrammarSpec that, installed on a tabnas engine, parses inputs in that grammar and builds a {rule, src, kids} AST. It also emits "pure-data" jsonic (recognition / pure specs) and supports user actions.

The package mirrors the TS sources:

• converter.ts -> converter.go (AST, parseAbnf, abnfRules, desugar, core rules, left-recursion elimination, probe-dispatch rewriter, FIRST sets, emitGrammarSpec, token allocation, Abnf entry) and parser_abnf.go (the ABNF-for-ABNF parser grammar).
• compile.ts -> compile.go (AbnfCompile, ToRecognitionSpec, ToPureSpec, ToJsonic, AttachActions, MarkListing).
• abnf.ts -> facade.go (Abnf, ParseAbnf, EmitGrammarSpec, EliminateLeftRecursion, Install — the public facade).

Index

• Constants
• func Abnf(src string, opts *AbnfConvertOptions) (*tabnas.GrammarSpec, error)
• func AbnfCompile(src string, opts *AbnfCompileOptions) (string, error)
• func AttachActionSlots(spec *tabnas.GrammarSpec, refNames []string) error
• func AttachActions(spec *tabnas.GrammarSpec, actions ActionsMap) error
• func EliminateLeftRecursion(grammar *abnfGrammar) *abnfGrammar
• func EmitGrammarSpec(grammar *abnfGrammar, opts *AbnfConvertOptions) (*tabnas.GrammarSpec, error)
• func Install(j *tabnas.Tabnas, src string, opts *AbnfConvertOptions, actions ActionsMap) (*tabnas.GrammarSpec, error)
• func MarkListing(spec *tabnas.GrammarSpec) string
• func ParseAbnf(src string) (*abnfGrammar, error)
• func Plugin(j *tabnas.Tabnas, _ map[string]any) error
• func SpecToData(spec *tabnas.GrammarSpec) map[string]any
• func SpecToJSON(spec *tabnas.GrammarSpec, indent int) string
• func ToJsonic(value any, strict bool, indent int) string
• type AbnfActionError
  • func (e *AbnfActionError) Error() string
• type AbnfCompileError
  • func (e *AbnfCompileError) Error() string
• type AbnfCompileOptions
• type AbnfConvertOptions
• type AbnfParseError
  • func (e *AbnfParseError) Error() string
  • func (e *AbnfParseError) Unwrap() error
• type ActionFn
• type ActionsMap

Constants

const Version = "0.2.0"

Version is the current version of the module.

Functions

func Abnf

func Abnf(src string, opts *AbnfConvertOptions) (*tabnas.GrammarSpec, error)

Abnf converts ABNF source into a tabnas GrammarSpec.

func AbnfCompile

func AbnfCompile(src string, opts *AbnfCompileOptions) (string, error)

AbnfCompile compiles ABNF source into pure-data jsonic text.

func AttachActionSlots

func AttachActionSlots(spec *tabnas.GrammarSpec, refNames []string) error

AttachActionSlots declares user-action slots by name on a pure-data spec, without supplying functions.

func AttachActions

func AttachActions(spec *tabnas.GrammarSpec, actions ActionsMap) error

AttachActions attaches user semantic actions to a spec in place.

func EliminateLeftRecursion

func EliminateLeftRecursion(grammar *abnfGrammar) *abnfGrammar

EliminateLeftRecursion rewrites direct + indirect left recursion via Paull's algorithm (exported to mirror the TS export).

func EmitGrammarSpec

func EmitGrammarSpec(grammar *abnfGrammar, opts *AbnfConvertOptions) (*tabnas.GrammarSpec, error)

EmitGrammarSpec converts an already-parsed grammar into a GrammarSpec.

func Install

func Install(j *tabnas.Tabnas, src string, opts *AbnfConvertOptions, actions ActionsMap) (*tabnas.GrammarSpec, error)

Install converts src and installs the resulting grammar on j. With actions supplied, conversion runs in closure mode with marks and the actions are attached. Mirrors the TS `tn.abnf(src, opts)` callable.

func MarkListing

func MarkListing(spec *tabnas.GrammarSpec) string

MarkListing returns a human-readable listing of compiler-assigned marks.

func ParseAbnf

func ParseAbnf(src string) (*abnfGrammar, error)

ParseAbnf parses ABNF source into a grammar AST (exported for callers inspecting productions). Returns *abnfGrammar via the internal type; for external use prefer Abnf.

func Plugin

func Plugin(j *tabnas.Tabnas, _ map[string]any) error

Plugin is the tabnas Plugin form: it installs a default grammar only if AbnfSource is set via options; primarily Abnf/Install are used directly. Provided for parity with the TS plugin shape.

func SpecToData

func SpecToData(spec *tabnas.GrammarSpec) map[string]any

SpecToData converts a *GrammarSpec into a plain data tree (map/slice/scalar/regexHolder). Action/condition refs are emitted as their `@`-name strings. Closures in spec.Ref are dropped — like the TS CLI's JSON output, which serialises actions as FuncRef strings. Used by the CLI's default (spec-dump) mode.

func SpecToJSON

func SpecToJSON(spec *tabnas.GrammarSpec, indent int) string

SpecToJSON renders a spec as JSON text (the CLI default output).

func ToJsonic

func ToJsonic(value any, strict bool, indent int) string

ToJsonic serialises a (function-free) data value as jsonic text.

Types

type AbnfActionError

type AbnfActionError struct{ Message string }

AbnfActionError is raised for a malformed or unresolvable action ref.

func (*AbnfActionError) Error

func (e *AbnfActionError) Error() string

type AbnfCompileError

type AbnfCompileError struct {
	Message string
	Rules   []string
}

AbnfCompileError is raised when a grammar can't be compiled to a pure-data spec.

func (*AbnfCompileError) Error

func (e *AbnfCompileError) Error() string

type AbnfCompileOptions

type AbnfCompileOptions struct {
	Start       string
	Tag         string
	Strict      bool
	Indent      int
	Recognition *bool // default true
}

AbnfCompileOptions controls compilation. Mirrors AbnfCompileOptions.

type AbnfConvertOptions

type AbnfConvertOptions struct {
	Start    string
	Tag      string
	Builtins bool
	Marks    bool
}

AbnfConvertOptions controls conversion. Mirrors the TS type.

type AbnfParseError

type AbnfParseError struct {
	Message string
	Line    int
	Column  int
	Cause   error
}

AbnfParseError is raised when the ABNF source itself can't be parsed.

func (*AbnfParseError) Error

func (e *AbnfParseError) Error() string

func (*AbnfParseError) Unwrap

func (e *AbnfParseError) Unwrap() error

type ActionFn

type ActionFn = tabnas.AltAction

ActionFn is a user semantic action.

type ActionsMap

type ActionsMap map[string][]ActionFn

ActionsMap maps action refs to a function or list of functions.