tabnasyaml

README

@tabnas/yaml (Go)

A Tabnas grammar plugin that parses a core subset of YAML into Go values (map[string]any, []any, float64, string, bool, nil), built on the relaxed-JSON jsonic grammar.

Install

go get github.com/tabnas/yaml/go

Requires github.com/tabnas/jsonic/go.

Example

The simplest entry point is the package-level Parse:

package main

import (
    "fmt"
    tabnasyaml "github.com/tabnas/yaml/go"
)

func main() {
    result, err := tabnasyaml.Parse("name: Alice\nitems:\n  - one\n  - two\n")
    if err != nil {
        panic(err)
    }
    fmt.Println(result)
    // map[items:[one two] name:Alice]
}

For repeated parsing, build a reusable parser with tabnasyaml.MakeJsonic().

Documentation

The docs follow the Diátaxis four-quadrant structure:

• Tutorial — parse your first document, step by step.
• How-to guide — focused task recipes (flow collections, block scalars, anchors, multi-document streams, the Meta option).
• Reference — the public API, every option, and the full list of accepted syntax.
• Concepts — how the plugin extends the engine, and the differences from the TypeScript version.

The TypeScript port lives in ../ts with its own docs.

Grammar diagram

The grammar is shared with the TypeScript implementation, generated from the live grammar with @tabnas/railroad:

ASCII version: ../ts/doc/grammar.txt.

License

MIT. Copyright (c) Richard Rodger.

Documentation

Index

• Constants
• func MakeJsonic(opts ...YamlOptions) *jsonic.Jsonic
• func Parse(src string) (any, error)
• func Yaml(j *jsonic.Jsonic, opts map[string]any) error
• type DocMeta
• type MetaResult
• type YamlOptions

Constants

const Version = "0.2.1"

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

Functions

func MakeJsonic

func MakeJsonic(opts ...YamlOptions) *jsonic.Jsonic

MakeJsonic creates a jsonic instance configured for YAML parsing. If a YamlOptions is passed, its fields are propagated to the plugin.

func Parse

func Parse(src string) (any, error)

func Yaml

func Yaml(j *jsonic.Jsonic, opts map[string]any) error

Yaml is a jsonic plugin that adds YAML parsing support.

Types

type DocMeta

type DocMeta struct {
	Directives []string `json:"directives"`
	Explicit   bool     `json:"explicit"`
	Ended      bool     `json:"ended"`
}

DocMeta holds per-document metadata captured by the stream rule.

type MetaResult

type MetaResult struct {
	Meta    any `json:"meta"`
	Content any `json:"content"`
}

MetaResult is the return shape when YamlOptions.Meta is true. Meta is either a *DocMeta (single doc) or []*DocMeta (multi-doc). Content is either the doc value (single) or []any (multi-doc).

type YamlOptions

type YamlOptions struct {
	// When true, Parse returns a struct {Meta, Content} instead of bare
	// content. Mirrors the TypeScript `meta` option.
	Meta bool
}

YamlOptions configures the YAML parser plugin. Currently empty — reserved for future extension.