tabnassemver

README

semver (Go)

A tabnas grammar plugin that parses Semantic Versioning 2.0.0 version strings into Go values, exactly as the specification defines them. The parser is the specification's own grammar, compiled from ABNF by github.com/tabnas/abnf/go when the plugin is installed.

Install

go get github.com/tabnas/semver/go@latest

import tabnassemver "github.com/tabnas/semver/go"

One example

tabnassemver.Parse is the one-call entry point: pass a string, get a value and an error:

v, err := tabnassemver.Parse("1.2.3-alpha.1+build.5")
// map[string]any{
//   "major": float64(1), "minor": float64(2), "patch": float64(3),
//   "prerelease": []any{"alpha", float64(1)},
//   "build":      []any{"build", "5"},
// }

c, err := tabnassemver.Compare(a, b) // -1, 0 or 1 by precedence (§11)
s, err := tabnassemver.Format(v)     // "1.2.3-alpha.1+build.5"

Integer components come back as float64, or as *big.Int above 2^53 − 1. Parse reuses a cached engine and is safe for concurrent use; for a hot loop, build one instance with tabnassemver.Make and reuse it on one goroutine.

Documentation

Full documentation follows the Diátaxis framework:

• Tutorial. A guided first parse, start to finish.
• How-to guide. Short recipes for individual tasks.
• Reference. The public API, the value shape, and the complete syntax accepted.
• Concepts. How the plugin turns the specification's grammar into a parser, and how the Go version differs from TypeScript.

For the canonical TypeScript implementation, see ../ts/README.md.

Grammar

The grammar is defined once in the top-level semver-grammar.abnf and embedded into this Go source (semver.go) and the TypeScript source during the build. Edit the grammar there, not in the generated source. It is also exported, as Grammar, for tooling that wants the text.

C library

clib/ builds libtabnassemver, the parser as a C shared library with the fleet's uniform five-symbol ABI, for languages with no tabnas port.

License

Copyright (c) 2026 Richard Rodger and other contributors, MIT License.

Documentation

Overview

Package tabnassemver is a tabnas plugin that parses Semantic Versioning 2.0.0 version strings (https://semver.org).

The parser IS the specification's grammar: semver-grammar.abnf at the repository root (embedded below) is the semver.org BNF transcribed into RFC 5234 ABNF, and github.com/tabnas/abnf/go compiles it into the engine's rule set when the plugin is installed. Nothing here decides what a valid version is — the grammar accepts or rejects — and the only code that runs during a parse is the one action that turns the accepted text into the result value.

v, err := tabnassemver.Parse("1.2.3-alpha.1+build.5")
// map[string]any{
//   "major": float64(1), "minor": float64(2), "patch": float64(3),
//   "prerelease": []any{"alpha", float64(1)},
//   "build":      []any{"build", "5"},
// }

Compare implements the specification's precedence rules (§11) over two parsed values, and Format renders a value back to its string.

This is the Go port of the canonical TypeScript implementation in ts/src/semver.ts; the two must produce the same value for the same input.

Index

• Constants
• Variables
• func Compare(a, b any) (int, error)
• func Format(v any) (string, error)
• func Make() *tabnas.Tabnas
• func Parse(src string) (any, error)
• func Semver(j *tabnas.Tabnas, _ map[string]any) error

Constants

const Grammar = grammarText

Grammar is the grammar as ABNF text — the same text the plugin compiles.

const MaxSafeInteger = 1<<53 - 1

MaxSafeInteger is the largest integer a numeric component is returned as a float64 for; anything larger is a *big.Int. It is 2^53 - 1, JavaScript's Number.MAX_SAFE_INTEGER, so the two runtimes switch representation at the same value.

const VERSION = "0.0.6"

VERSION is this module's version. It MUST equal ts/package.json "version": the release orchestrator rewrites both, and TestVersionMatchesPackageJSON fails the build if they drift.

Variables

var Defaults = map[string]any{}

Defaults holds the default plugin options. There are none yet; the map exists so UseDefaults(Semver, Defaults) reads like every other plugin and a future option has a declared home. Mirrors TS `Semver.defaults`.

Functions

func Compare

func Compare(a, b any) (int, error)

Compare orders two parsed values by precedence, as the specification defines it (§11): -1 when a ranks below b, 1 when above, 0 when they are the same version. Build metadata is ignored (§10, §11.1): 1.0.0+a and 1.0.0+b compare equal.

func Format

func Format(v any) (string, error)

Format renders a parsed value back to its version string. For a value that came out of Parse this is the exact input text.

func Make

func Make() *tabnas.Tabnas

Make returns a new engine with the Semver plugin installed. Build one and reuse it: compiling the grammar dominates a parse. The instance is not safe for concurrent Parse calls; see Parse for a shared one.

func Parse

func Parse(src string) (any, error)

Parse parses one version string. On success the value is a map[string]any with the keys "major", "minor", "patch" (float64, or *big.Int above MaxSafeInteger), "prerelease" ([]any of string, float64 or *big.Int — numeric identifiers are numbers) and "build" ([]any of string). On failure the error is the engine's *tabnas.TabnasError with Code "unexpected".

Parse is safe for concurrent use.

func Semver

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

Semver is the tabnas plugin. Install it on a bare engine:

j := tabnas.Make()
err := j.Use(Semver)

or use Make, which does exactly that.