mojo-toml v0.2.0 πŸ”₯

The first native TOML 1.0 parser for the Mojo programming language!

This release provides full TOML parsing with proper nested table structures. Thanks to feedback from the Modular Discord community, we discovered the correct Dict iteration pattern and implemented nested tables from the start!

πŸš€ What’s New

Core Parser - Fully Functional

  • βœ… 79 tests passing across 7 comprehensive test suites
  • βœ… Parses real-world TOML files (including pixi.toml)
  • βœ… Zero Python dependencies at runtime
  • βœ… Clear error messages with line/column information

Supported TOML Features

  • Key-value pairs: key = "value"
  • Comments: # comment
  • Strings: basic, literal, multiline variants
  • Numbers: integers, floats, special values (inf, nan)
  • Booleans: true, false
  • Arrays: [1, 2, 3] with nesting and mixed types
  • Inline tables: {name = "value"} with nesting
  • Table headers: [section] with proper nested structures ✨
  • Dotted headers: [a.b.c] with deep nesting ✨
  • Datetime strings (ISO 8601)

πŸ“¦ Installation

Alternative: Direct Copy

git clone https://github.com/databooth/mojo-toml
cp -r mojo-toml/src/toml your-project/lib/toml
mojo -I your-project/lib your_app.mojo

Compiled Package

Download toml.mojopkg from this release (see compatibility note below).

πŸ’» Usage Example

from toml import parse

fn main() raises:
    var config = parse("""
        title = "MyApp"
        version = "1.0.0"
        
        [database]
        host = "localhost"
        port = 5432
    """)
    
    # Access root-level keys
    print(config["title"].as_string())  # "MyApp"
    
    # Access nested tables (proper structure!)
    var db = config["database"].as_table()
    print(db["host"].as_string())  # "localhost"
    print(db["port"].as_int())      # 5432

πŸŽ‰ Major Feature: Nested Table Structures

Tables are now properly nested using Dict structures:

# Simple nesting:
var db = config["database"].as_table()
var host = db["host"].as_string()

# Deep nesting:
# [database.primary]
var db = config["database"].as_table()
var primary = db["primary"].as_table()
var host = primary["host"].as_string()

This was made possible by discovering that Mojo’s Dict iterator works with entry.key and entry.value directly!

🚧 Known Limitations

Not yet implemented (planned for v0.3.0 - TOML 1.0 Compliance): - Array of tables: [[array]] - Duplicate key detection - Hex/Octal/Binary integers: 0xDEADBEEF, 0o755, 0b11010110 - Dotted keys in standalone key-value pairs: a.b.c = "value" - Native datetime parsing (currently returns ISO 8601 strings)

Planned for v0.4.0+: - Writer/serialiser functionality

πŸ§ͺ Testing

All 79 tests passing: - 25 lexer tests - 10 parser tests - 4 real-world file tests - 5 fixture tests - 14 array tests - 13 inline table tests - 8 table header tests

Run tests yourself:

git clone https://github.com/databooth/mojo-toml
cd mojo-toml
pixi install
pixi run test-all

πŸ“š Documentation

πŸ”§ Compatibility

  • Mojo Version: Tested with Mojo 2025/2026 (via pixi)
  • Platforms: macOS (Apple Silicon), Linux
  • Python: Zero dependencies for runtime

⚠️ .mojopkg Compatibility Note: The compiled package is built with the Mojo version shown in the build artifacts. It may not work with different Mojo versions. Source installation is recommended for maximum compatibility.

πŸ—ΊοΈ Roadmap

v0.3.0 (Next) - TOML 1.0 Compliance

  • Array of tables: [[array]]
  • Duplicate key detection
  • Hex/Octal/Binary integers
  • Dotted keys in key-value pairs
  • Native datetime types
  • Enhanced error messages

v0.4.0

  • SIMD optimisations
  • Performance benchmarks
  • Advanced optimizations

πŸ™ Acknowledgements

Built with inspiration from: - Python tomli - Reference implementation - mojo-dotenv - Proven parser patterns - TOML Specification - Excellent config format by Tom Preston-Werner

πŸ’¬ Feedback & Support

Full Changelog: See CHANGELOG.md for complete details.