tabnasdebug

README

tabnas-debug (Go)

Debug / introspection plugin for the tabnas parser engine, package tabnasdebug.

It makes a grammar visible: Describe dumps an instance's installed grammar (tokens, rules, plugins) as labelled text, Abnf re-expresses it as ABNF, and trace logs a parse step by step. A dev/test aid — never a runtime dependency.

This is the Go port of the canonical TypeScript implementation in ../ts; the TypeScript version is authoritative and this package tracks it. The Go engine exposes tracing and introspection through different idioms, so the surface differs in shape — notably, Go has no structured model(). See the concepts doc and reference for the details.

Install

go get github.com/tabnas/parser/go
go get github.com/tabnas/debug/go

Use

package main

import (
	"fmt"

	tabnas "github.com/tabnas/parser/go"
	tabnasdebug "github.com/tabnas/debug/go"
)

func main() {
	j := tabnas.Make()

	// Describe the grammar. Describe returns (string, error): it never
	// panics, surfacing any failure as an "internal"-code error instead.
	report, err := tabnasdebug.Describe(j)
	if err != nil {
		panic(err)
	}
	fmt.Println(report)

	// Trace a parse (lex + rule events go to stdout by default).
	j.Use(tabnasdebug.Debug, map[string]any{"trace": true})
	j.Parse("a:1")
}

Documentation

• Tutorial — zero to a working inspection, step by step.
• How-to guide — focused recipes.
• Reference — the exact exports, options and output.
• Concepts — how it works and how it differs from the TypeScript version.

Build and test

This repository consumes the engine from source. From the repository root, fetch it first, then build and test:

./scripts/fetch-parser.sh   # downloads + builds the engine into vendor/
cd go && go build ./... && go vet ./... && go test ./...

Or, from the repository root, make test-go does all of the above. The go.mod replace directive points the github.com/tabnas/parser/go requirement at the fetched copy in ../vendor.

License

MIT.

Documentation

Overview

Package debug is the Go implementation of the tabnas Debug plugin.

It mirrors the canonical TypeScript implementation in ../ts: a Debug plugin that traces a parse, and a Describe function that dumps a parser instance's active grammar (tokens, token sets, rules, alternates, lexer matchers and plugins). The TypeScript version is authoritative.

The Go tabnas engine exposes tracing through instance subscribers (Tabnas.Sub) rather than the TypeScript context-log hook, and its introspection is read through exported accessors (Config, RSM, TinName, TokenSet, Plugins). The output here therefore tracks the TypeScript behaviour as closely as the Go engine API allows; see ../docs/reference.md for the documented differences.

Index

• Constants
• Variables
• func Abnf(j *tabnas.Tabnas) (out string, err error)
• func Describe(j *tabnas.Tabnas) (out string, err error)

Constants

const Version = "0.2.0"

Version is the module version, injected at release by `make publish-go`.

Variables

var Debug tabnas.Plugin = func(j *tabnas.Tabnas, opts map[string]any) (err error) {
	defer func() {
		if r := recover(); r != nil {
			err = internalError("Debug", r)
		}
	}()

	if traceEnabled(opts) {
		var out io.Writer = os.Stdout
		if w, ok := opts["out"].(io.Writer); ok && w != nil {
			out = w
		}
		addTrace(j, out)
	}
	return nil
}

Debug is the tabnas plugin entry point. Load it with

j.Use(debug.Debug, map[string]any{"trace": true})

and call debug.Describe(j) for a grammar dump. When tracing is enabled (see traceEnabled) the plugin installs lex and rule subscribers that log each parse event.

Trace output goes to os.Stdout by default; pass an io.Writer under opts["out"] to capture it (e.g. for tests).

Loading via j.Use already runs under the engine's no-panic guard, but Debug guards itself too so that calling it directly cannot panic the caller: any panic while wiring trace subscribers is returned as an "internal"-code error.

var Defaults = map[string]any{
	"trace": true,
}

Defaults are the option values used when the plugin is loaded without an explicit configuration. They mirror the canonical TypeScript DEFAULTS, where tracing is on by default.

Functions

func Abnf

func Abnf(j *tabnas.Tabnas) (out string, err error)

Abnf returns an ABNF representation of the instance's live grammar, mirroring the canonical TypeScript tabnas.debug.abnf(). Unlike the TypeScript form, which returns a bare string, the Go form returns (string, error) to uphold the engine's no-panic guarantee: a malformed grammar spec is rendered defensively and any remaining panic is recovered and returned as an "internal"-code *tabnas.TabnasError with an empty string. On success the error is nil.

func Describe

func Describe(j *tabnas.Tabnas) (out string, err error)

Describe returns a human-readable description of a parser instance's active configuration, mirroring the sections of the canonical TypeScript describe(): tokens, token sets, rules, alternates, lexer matchers and plugins.

Unlike the TypeScript describe(), which returns a bare string, the Go form returns (string, error): it upholds the engine's no-panic guarantee. Malformed grammar specs (a nil config, a nil rule spec, a nil alternate) are rendered defensively rather than dereferenced, and any remaining panic is recovered and returned as an "internal"-code error with an empty string. On success the error is nil. This divergence is intentional; see ../docs/reference.md.