up

README

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

Documentation

Overview

Package up provides functional parsing capabilities for UP documents.

Package up provides templating support for UP documents

Package up defines the core data structures for UP parsing.

Index

• func Unmarshal(data []byte, v any) error
• func UnmarshalDocument(doc *Document, v any) error
• type Block
• type Document
• type List
• type Node
• type ParseFunc
• type Parser
  • func NewParser() *Parser
  • func (p *Parser) ParseDocument(r io.Reader) (*Document, error)
  • func (p *Parser) WithDedentFunc(fn func(string, int) string) *Parser
  • func (p *Parser) WithSkipComment(fn func(string) bool) *Parser
  • func (p *Parser) WithSkipEmptyLine(fn func(string) bool) *Parser
• type Scanner
  • func NewScanner(r io.Reader) *Scanner
  • func (s *Scanner) NextLine() (int, string, bool)
• type Table
• type TemplateEngine
  • func NewTemplateEngine() *TemplateEngine
  • func (e *TemplateEngine) ProcessTemplate(filename string) (*Document, error)
  • func (e *TemplateEngine) ProcessTemplateFromReader(r io.Reader) (*Document, error)
  • func (e *TemplateEngine) WithOptions(opts TemplateOptions) *TemplateEngine
  • func (e *TemplateEngine) WithVars(vars map[string]any) *TemplateEngine
• type TemplateOptions
• type Value

Functions

func Unmarshal

func Unmarshal(data []byte, v any) error

Unmarshal parses UP document and stores the result in the value pointed to by v. If v is not a pointer to a struct, Unmarshal returns an error.

Unmarshal uses struct tags to determine how to map UP keys to struct fields:

• `up:"fieldname"` - maps UP key "fieldname" to this struct field
• `up:"fieldname,omitempty"` - omits field if value is empty
• `up:"-"` - ignores this field

Example:

type Config struct {
    Host     string `up:"host"`
    Port     int    `up:"port"`
    Enabled  bool   `up:"enabled"`
    Tags     []string `up:"tags"`
    Database struct {
        Host string `up:"host"`
        Port int    `up:"port"`
    } `up:"database"`
}

func UnmarshalDocument

func UnmarshalDocument(doc *Document, v any) error

UnmarshalDocument unmarshals a parsed Document into v.

Types

type Block

type Block map[string]Value

Block represents a UP block structure.

type Document

type Document struct {
	Nodes []Node
}

Document represents a parsed UP document.

type List

type List []Value

List represents a UP list structure.

type Node

type Node struct {
	Key   string
	Type  string
	Value Value
}

Node represents a key-value pair with optional type annotation.

type ParseFunc

type ParseFunc[T any] func(*Scanner, string) (T, error)

ParseFunc represents a parsing function type.

type Parser

type Parser struct {
	// contains filtered or unexported fields
}

Parser provides configurable parsing functionality.

func NewParser

func NewParser() *Parser

NewParser creates a new Parser with default configuration.

func (*Parser) ParseDocument

func (p *Parser) ParseDocument(r io.Reader) (*Document, error)

ParseDocument parses a UP document from an io.Reader.

func (*Parser) WithDedentFunc

func (p *Parser) WithDedentFunc(fn func(string, int) string) *Parser

WithDedentFunc configures the dedent function.

func (*Parser) WithSkipComment

func (p *Parser) WithSkipComment(fn func(string) bool) *Parser

WithSkipComment configures the comment skip function.

func (*Parser) WithSkipEmptyLine

func (p *Parser) WithSkipEmptyLine(fn func(string) bool) *Parser

WithSkipEmptyLine configures the empty line skip function.

type Scanner

type Scanner struct {
	*bufio.Scanner
	// contains filtered or unexported fields
}

Scanner wraps a bufio.Scanner with additional functionality.

func NewScanner

func NewScanner(r io.Reader) *Scanner

NewScanner creates a new Scanner from an io.Reader.

func (*Scanner) NextLine

func (s *Scanner) NextLine() (int, string, bool)

NextLine advances the scanner and returns the current line number and text.

type Table

type Table struct {
	Columns []any
	Rows    []any
}

Table represents a UP table with columns and rows.

type TemplateEngine

type TemplateEngine struct {
	// contains filtered or unexported fields
}

TemplateEngine processes UP templates with overlays, includes, and variables

func NewTemplateEngine

func NewTemplateEngine() *TemplateEngine

NewTemplateEngine creates a new template engine

func (*TemplateEngine) ProcessTemplate

func (e *TemplateEngine) ProcessTemplate(filename string) (*Document, error)

ProcessTemplate processes a UP template file

func (*TemplateEngine) ProcessTemplateFromReader

func (e *TemplateEngine) ProcessTemplateFromReader(r io.Reader) (*Document, error)

ProcessTemplateFromReader processes a template from an io.Reader

func (*TemplateEngine) WithOptions

func (e *TemplateEngine) WithOptions(opts TemplateOptions) *TemplateEngine

WithOptions sets template options

func (*TemplateEngine) WithVars

func (e *TemplateEngine) WithVars(vars map[string]any) *TemplateEngine

WithVars sets initial variables

type TemplateOptions

type TemplateOptions struct {
	MergeStrategy string // "deep", "shallow", "replace"
	ListStrategy  string // "append", "replace", "unique"
	BaseDir       string // base directory for relative includes
}

TemplateOptions configures template processing

type Value

type Value any

Value represents any UP value.