TOON Parser - Header-Only Standalone Library

TOON (Token-Oriented Object Notation) is a lightweight, human-readable data serialization format designed as an alternative to TOML, YAML, and JSON.

Features

• Header-only: Just include toon_parser.h - no compilation needed
• Zero dependencies: Only uses C++ standard library
• Fully compliant: Implements TOON v3.0 specification
• Type-safe: Strong typing with std::variant backend
• Easy to use: Intuitive API with safe value access

Quick Start

#include "toon_parser.h"

// Parse a file
auto result = toon::Parser::parse_file("config.toon");
if (!result) {
    std::cerr << "Parse error: " << result.error << "\n";
    return;
}

auto config = result.table;
std::string title = config->get("title").as_string();
int64_t port = config->get("database").as_table()->get("port").as_int();

TOON Specification (v3.0)

Basic Syntax

TOON is line-oriented and indentation-based:

# Comments start with #
title: My Application
version: 1
debug: true

Data Types

• String: name: "Hello World" or name: Hello (unquoted if no spaces)
• Integer: count: 42
• Float: pi: 3.14159
• Boolean: enabled: true or enabled: false
• Null: value: null

Nested Tables

Use indentation to create nested structures:

database:
  host: localhost
  port: 5432
  credentials:
    username: admin
    password: secret

Arrays

Simple arrays with optional length declaration:

features[3]:
  fast
  secure
  scalable

Tabular Arrays

For structured data, use column headers with delimiters:

servers[2]:
  {ip,port,role}
  192.168.1.10, 5432, primary
  192.168.1.11, 5432, backup

Supported delimiters: comma (,), tab (\t), pipe (|)

String Escaping

TOON supports standard escape sequences in quoted strings:

path: "C:\\Users\\Name"
message: "Line 1\nLine 2"

Escape sequences: \\, \", \n, \r, \t

Multi-line Strings

Use quotes for multi-line content:

description: "This is a long description
that spans multiple lines
and preserves formatting."

C++ API Reference

Value Types

class Value {
public:
    // Type checking
    bool is_string() const;
    bool is_int() const;
    bool is_float() const;
    bool is_bool() const;
    bool is_null() const;
    bool is_table() const;
    bool is_array() const;
    
    // Value access (throws on type mismatch)
    std::string as_string() const;
    int64_t as_int() const;
    double as_float() const;
    bool as_bool() const;
    std::shared_ptr<Table> as_table() const;
    std::shared_ptr<Array> as_array() const;
    
    // Safe access with default values
    template<typename T>
    T value_or(const T& default_value) const;
};

Table Operations

class Table {
public:
    bool contains(const std::string& key) const;
    Value& get(const std::string& key);
    const Value& get(const std::string& key) const;
    void insert(const std::string& key, const Value& value);
    
    // Iteration
    auto begin();
    auto end();
    size_t size() const;
};

Array Operations

class Array {
public:
    size_t size() const;
    Value& at(size_t index);
    const Value& at(size_t index) const;
    void push_back(const Value& value);
    
    // Iteration
    auto begin();
    auto end();
};

Parsing

class Parser {
public:
    // Parse from file
    static ParseResult parse_file(const std::string& filename);
    
    // Parse from string
    static ParseResult parse_string(const std::string& content);
};

struct ParseResult {
    std::shared_ptr<Table> table;
    std::string error;
    
    // Conversion to bool (true if successful)
    operator bool() const;
};

Usage Examples

See toon_example.cpp for comprehensive examples covering:

1. Basic file parsing
2. Safe value access with defaults
3. Array processing
4. Programmatic construction
5. Parsing from strings

TOON vs. Other Formats

Feature	TOON	TOML	YAML	JSON
Human-readable	✓	✓	✓	✓
Minimal quoting	✓	-	✓	-
Indentation-based	✓	-	✓	-
Tabular arrays	✓	-	-	-
Comments	✓	✓	✓	-
Multi-delimiter	✓	-	-	-
Type safety	✓	✓	-	-

Specification Details

§1-6: Core Syntax

• Line-oriented with key-value pairs
• Colon separator: key: value
• Comments with #
• Whitespace insensitive (except in strings)

§7: String Escaping

• Double quotes for explicit strings
• Unquoted strings for simple values
• Escape sequences: \\, \", \n, \r, \t

§8-10: Tabular Arrays

• Column header declaration: {col1,col2,col3}
• Array length: arrayname[N]:
• Data rows use same delimiter as header

§11: Multi-Delimiter Support

• Comma: a, b, c
• Tab: a b c
• Pipe: a | b | c

§12: Indentation-Based Nesting

• 2-space indentation for nested tables
• Consistent indentation required
• Tabs converted to spaces

Integration

As a Configuration Library

// Read application config
auto config = toon::Parser::parse_file("config.toon");
int port = config.table->get("server").as_table()->get("port").as_int();

As a Data Exchange Format

// Create programmatically
auto data = std::make_shared<toon::Table>();
data->insert("status", toon::Value("success"));
data->insert("count", toon::Value(42));

Requirements

• C++17 or later
• Standard library headers: <string>, <memory>, <variant>, <vector>, <map>, <fstream>, <sstream>, <stdexcept>, <cctype>

License

This is a standalone implementation of the TOON specification. See https://github.com/toon-format/toon for the official TOON project.

Notes

• Parser handles both Windows (\r\n) and Unix (\n) line endings
• Case-sensitive keys and values
• Whitespace around values is trimmed
• Empty lines and comment-only lines are ignored
• Indentation must be consistent (2 spaces per level)

Error Handling

The parser provides detailed error messages:

auto result = toon::Parser::parse_file("config.toon");
if (!result) {
    std::cerr << "Parse failed: " << result.error << "\n";
    // Error contains line number and description
}

Errors include:

• Syntax errors (missing colons, invalid indentation)
• Type mismatches (accessing int as string)
• Array bounds violations
• File I/O errors