UP Parser for Java

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

📚 API Documentation | 🧪 Test Status | 📖 Specification

Modern Java 21+ - Uses records, sealed types, and pattern matching

Features

• ✅ Full UP Syntax Support - Scalars, blocks, lists, tables, multiline strings
• ✅ Type Annotations - Parse and preserve type hints (!int, !bool, etc.)
• ✅ Modern Java 21+ - Records, sealed interfaces, pattern matching
• ✅ Immutable Data Structures - Thread-safe, functional design
• ✅ Type-Safe - Exhaustive pattern matching with sealed types
• ✅ Well-Tested - Comprehensive JUnit 5 test suite
• ✅ Zero Dependencies - No external runtime dependencies
• ✅ Maven-Based - Standard Java build tooling

Requirements

• Java 21 or later
• Maven 3.6+ (for building)

Installation

Maven

<dependency>
    <groupId>com.uplang</groupId>
    <artifactId>up-parser</artifactId>
    <version>1.0.0</version>
</dependency>

Build from Source

git clone https://github.com/uplang/java
cd java
mvn clean install

Quick Start

import com.uplang.parser.*;

public class Example {
    public static void main(String[] args) throws Exception {
        // Create a parser
        Parser parser = new Parser();

        // Parse UP content
        Document doc = parser.parseString("""
            name Alice
            age!int 30
            config {
              debug!bool true
            }
            """);

        // Access values
        String name = doc.getScalar("name").orElse("Unknown");
        System.out.println("Name: " + name);

        // Pattern matching (Java 21+)
        for (Node node : doc.nodes()) {
            switch (node.value()) {
                case Value.Scalar s -> System.out.println(s.value());
                case Value.Block b -> System.out.println("Block: " + b.entries().size());
                default -> System.out.println("Other type");
            }
        }
    }
}

📖 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 Classes

• Parser - Main parser for converting UP text into documents
• Document - Immutable collection of nodes with convenient access methods
• Node - Key-value pair with optional type annotation (record)
• Value - Sealed interface with subtypes (Scalar, Block, List, Table, Multiline)

Basic Usage

Parser parser = new Parser();

// Parse from String
Document doc = parser.parseString(content);

// Parse from Reader
Document doc = parser.parse(new FileReader("config.up"));

// Access values
Optional<String> name = doc.getScalar("name");
Optional<Value.Block> server = doc.getBlock("server");
Optional<Value.List> tags = doc.getList("tags");

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

Testing

# Run all tests
mvn test

# Run with verbose output
mvn test -Dsurefire.printSummary=true

# Run specific test
mvn test -Dtest=ParserTest

Project Structure

java/
├── src/main/java/com/uplang/parser/
│   ├── Value.java          # Sealed value types
│   ├── Node.java           # Key-value record
│   ├── Document.java       # Parsed document
│   ├── Parser.java         # Main parser
│   ├── Scanner.java        # Line scanner
│   ├── ParseException.java # Error handling
│   └── Example.java        # Usage examples
├── src/test/java/com/uplang/parser/
│   └── ParserTest.java     # Comprehensive tests
├── pom.xml                 # Maven configuration
├── 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

• Go - Reference implementation
• 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/java/issues
• Discussions: github.com/uplang/spec/discussions