New-member primer.

The fastest path from “what is MOML?” to using it correctly in an application.

What MOML is

MOML is a lightweight configuration language. It deliberately stores strings and structure rather than inferring application types. The app’s Gatekeeper decides what those strings mean.

Core principleCode should be logic. Data in MOML.

The architecture

APP↔Gatekeeper↔MOML parser↔.m2

The app should not import the parser directly. Reads go through typed accessors; writes go through the Gatekeeper, which converts app values to MOML-safe strings.

A small example

# MOML 2.0

settings {
    enabled = true
    max_items = 10
    theme_color = 085041
    log_path = C:\Users\Karim\Documents
    dictate_keys = #h, +#h
}

The parser returns strings. The Gatekeeper can turn enabled into a Boolean, max_items into an integer, and theme_color into the app-facing #085041.

Why the Gatekeeper matters

Schema knowledge belongs at the application boundary. MOML should not guess that 085041 is a number, that true is a Boolean, or that #h is a hotkey. The Gatekeeper knows because the app knows.

Rule 7 is a deliberate round-trip compromise

There is one unavoidable ambiguity in a typeless format: models = llama4 cannot tell MOML whether the application intended a scalar or a list containing one item. MOML therefore writes a conceptual one-item inline list as:

models = llama4, ""

The trailing "" is a structural sentinel. It keeps the value list-shaped through a parser/write/read round trip. The Gatekeeper, which knows the setting is a list, may remove exactly one trailing structural empty before giving the value to the application.

Why this is intentionalThe alternative is to add brackets, type markers, schema inference, or another special one-item-list syntax. MOML contains the compromise to this single edge case so ordinary scalars, paths, hotkeys, colors, blocks, and multi-item lists stay clean and punctuation-light.

How to learn the format

Read the language reference.
Open the browser playground and intentionally break examples.
Read one sample Gatekeeper and one example app in your language.
Run the deterministic spec suite.
Run the fuzz suite before modifying parser behavior.

Parser family

Python is the reference executable behavior; PHP, JavaScript and AutoHotkey v2 are ports of the same language contract. Language-specific quirks are handled in the ports without changing MOML itself.

Testing philosophy

Spec tests lock known behavior and regressions. Fuzz tests search for combinations nobody thought to hand-write. Bugs discovered by fuzzing are promoted into permanent regression tests.

The full 14-page onboarding document is available above in PDF and DOCX form.