UP Parser for Go

Official Go implementation of the UP (Unified Properties) language parser.

📚 API Documentation | 🧪 Test Status | 📖 Specification

Reference Implementation - This is the canonical implementation of the UP specification.

Features

• ✅ Full UP Syntax Support - Scalars, blocks, lists, tables, multiline strings
• ✅ Type Annotations - Parse and preserve type hints (!int, !bool, etc.)
• ✅ Functional Design - Immutable data structures, functional parsing patterns
• ✅ Well-Tested - Comprehensive test suite with edge cases
• ✅ Zero Dependencies - Pure Go library implementation
• ✅ Performance - Efficient single-pass parser

Requirements

• Go 1.25 or later

Installation

As a Library

go get github.com/uplang/go

CLI Tool

The UP CLI tool is available in the tools repository:

# Main CLI
go install github.com/uplang/tools/up@latest

# Additional tools
go install github.com/uplang/tools/language-server@latest
go install github.com/uplang/tools/repl@latest

Quick Start

package main

import (
    "strings"
    up "github.com/uplang/go"
)

func main() {
    parser := up.NewParser()
    doc, err := parser.ParseDocument(strings.NewReader(`
        name Alice
        age!int 30
        config {
          debug!bool true
        }
    `))

    if err != nil {
        panic(err)
    }

    // Access parsed values
    for _, node := range doc.Nodes {
        println(node.Key, "=", node.Value)
    }
}

📖 For detailed examples and tutorials, see QUICKSTART.md

Documentation

• QUICKSTART.md - Getting started guide with examples
• DESIGN.md - Architecture and design decisions
• UP Specification - Complete language specification

API Overview

Core Types

• Parser - Main parser with configurable options
• Document - Parsed document containing nodes
• Node - Key-value pair with optional type annotation
• Value - Interface for all value types (scalar, block, list, table)

Basic Usage

// Create parser
parser := up.NewParser()

// Parse from io.Reader
doc, err := parser.ParseDocument(reader)

// Access nodes
for _, node := range doc.Nodes {
    fmt.Printf("%s: %v\n", node.Key, node.Value)
}

See DESIGN.md for complete API documentation and implementation details.

CLI Tool

# Parse and pretty-print
up parse -i config.up --pretty

# Validate syntax
up validate config.up

# Convert to JSON
up convert -i config.up -o config.json --format json

Testing

# Run all tests
go test ./...

# Run with coverage
go test -cover ./...

# Run with race detection
go test -race ./...

Project Structure

go/
├── parser.go           # Core parser implementation
├── types.go            # Data structures
├── parser_test.go      # Comprehensive tests
├── cmd/
│   └── up/            # CLI tool
│       └── main.go
├── README.md          # This file
├── QUICKSTART.md      # Getting started guide
├── DESIGN.md          # Architecture documentation
└── LICENSE            # GNU GPLv3

Contributing

Contributions are welcome! Please see the main CONTRIBUTING.md for guidelines.

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

Links

• UP Language Specification - Official language spec
• Syntax Reference - Quick syntax guide
• UP Namespaces - Official namespace plugins

Other Implementations

• Java - Modern Java 21+ with records and sealed types
• JavaScript/TypeScript - Browser and Node.js support
• Python - Pythonic implementation with dataclasses
• Rust - Zero-cost abstractions and memory safety
• C - Portable C implementation

Support

• Issues: github.com/uplang/go/issues
• Discussions: github.com/uplang/spec/discussions