yini

README

yini-parser-go

Go library for parsing YINI files and inline YINI text. The first alpha release, v1.0.0-alpha.2, targets the YINI 1.0.0 RC.6 syntax.

The module supports Go 1.22 or newer. It uses ANTLR-generated Go code and the pinned ANTLR Go runtime; applications need only the Go module, not Java.

---

Install

go get github.com/YINI-lang/yini-parser-go@v1.0.0-alpha.2

---

Parse inline text

package main

import (
    "fmt"

    yini "github.com/YINI-lang/yini-parser-go"
)

func main() {
    result, err := yini.ParseString("^ Service\nport = 8080\n", yini.Options{})
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(result.Document.Values()["Service"].(map[string]any)["port"]) // 8080
}

Options{} selects lenient mode. Choose strict mode explicitly:

result, err := yini.ParseFile("settings.strict.yini", yini.Options{Mode: yini.ModeStrict})

Strict mode requires one explicit top-level section and /END, and rejects orphan members. The .strict.yini filename suffix and @yini declaration do not select the mode; Options.Mode does. A file can end immediately after its final assignment in lenient mode or /END in strict mode.

---

Results and diagnostics

ParseString, ParseFile, and ParseReader return a Result and a Go error. The result contains a structured Document with section/member source positions and all diagnostics. On malformed input, the document may be partial and the error is a *yini.ParseError with a line and column. Warnings remain in Result.Diagnostics without causing an error. Library calls do not print diagnostics.

Document.Values() returns a deep-copy map[string]any for application code. Lenient orphan members and top-level sections appear side by side in this map. Values use string, bool, nil, int64, float64, []any, and map[string]any. Integers outside signed 64-bit range and floating literals that overflow or lose a nonzero value to zero produce errors.

For editors and other tools, ParseForTooling returns diagnostics and recoverable document content without returning an error for normal YINI syntax failures.

See usage for mode and diagnostic details and development for the Taskfile commands and repository layout. The checked-in RC.6 specification is in spec/.

---

Shared conformance tests

The Go adapter in cmd/yini-test-adapter/ runs this parser against the external yini-test-suite. It accepts a YINI file and an explicit lenient or strict mode, then writes parsed JSON to stdout and diagnostics to stderr. See the development guide for build and run commands. CI runs the smoke suite in both modes; all 20 smoke cases currently pass. The full conformance suite still has known failures.

---

Help and bug reports

For questions, bug reports, or feature requests, open an issue. For parser problems, include a small YINI example, the selected mode, the expected result, and the actual result or diagnostics.

---

License

This project is licensed under the MIT License.

---

^YINI ≡

Documentation

Overview

Package yini parses YINI configuration documents.

Parsing is lenient by default. Set Options.Mode to ModeStrict to enforce strict document rules. Parse results include diagnostics even when an error is returned.

Index

• type Diagnostic
• type Document
  • func (d *Document) Values() map[string]any
• type Member
• type Mode
• type Options
• type ParseError
  • func (e *ParseError) Error() string
• type Position
• type Result
  • func ParseFile(path string, options Options) (Result, error)
  • func ParseForTooling(content string, options Options) (Result, error)
  • func ParseReader(reader io.Reader, options Options) (Result, error)
  • func ParseString(content string, options Options) (Result, error)
  • func (r Result) HasErrors() bool
• type Section
• type Severity

Types

type Diagnostic

type Diagnostic struct {
	Severity Severity
	Code     string
	Message  string
	Position Position
}

Diagnostic describes a problem found while parsing or validating input.

type Document

type Document struct {
	Members  []*Member
	Sections []*Section
}

Document is the structured result of parsing a YINI document. Members at this level are lenient-mode orphan members.

func (*Document) Values

func (d *Document) Values() map[string]any

Values returns a deep copy of the document's application-facing values. Orphan members and top-level sections appear beside one another.

type Member

type Member struct {
	Name     string
	Value    any
	Position Position
}

Member is a key and its parsed value. Values are strings, int64, float64, bool, nil, []any, or map[string]any.

type Mode

type Mode string

Mode selects the YINI validation rules.

const (
	ModeLenient Mode = "lenient"
	ModeStrict  Mode = "strict"
)

type Options

type Options struct {
	Mode Mode
}

Options controls parsing. The zero value selects lenient mode.

type ParseError

type ParseError struct {
	Diagnostic Diagnostic
}

ParseError reports a syntax or validation failure. The corresponding Result retains the complete list of diagnostics.

func (*ParseError) Error

func (e *ParseError) Error() string

type Position

type Position struct {
	Line   int
	Column int
}

Position identifies a location in the original input. Lines and columns start at one.

type Result

type Result struct {
	Document    *Document
	Diagnostics []Diagnostic
}

Result contains parsed data and all diagnostics collected from the input. Document may be partial when errors were reported.

func ParseFile

func ParseFile(path string, options Options) (Result, error)

ParseFile reads and parses a UTF-8 YINI file. The filename does not select the parsing mode; a .strict.yini file parsed leniently gets a warning.

func ParseForTooling

func ParseForTooling(content string, options Options) (Result, error)

ParseForTooling returns diagnostics and any recoverable document content without returning a Go error for normal YINI syntax and validation issues.

func ParseReader

func ParseReader(reader io.Reader, options Options) (Result, error)

ParseReader parses YINI content from a reader.

func ParseString

func ParseString(content string, options Options) (Result, error)

ParseString parses inline YINI content. A result with diagnostics is returned even when the input is invalid.

func (Result) HasErrors

func (r Result) HasErrors() bool

HasErrors reports whether the result contains an error diagnostic.

type Section

type Section struct {
	Name     string
	Level    int
	Position Position
	Members  []*Member
	Sections []*Section
}

Section is an explicit YINI section and its nested content.

type Severity

type Severity string

Severity is the level of a parse diagnostic.

const (
	SeverityWarning Severity = "warning"
	SeverityError   Severity = "error"
)