HUML (Human-oriented Markup Language)

HUML is a strict, unambiguous serialization language similar to YAML but without YAML's quirks and gotchas. It's designed for configuration files and data serialization where human readability matters.

Core Syntax Rules

Indentation

Strictly 2 spaces per nesting level (tabs not allowed)
No trailing spaces (except in multiline strings)

Keys and Values

Single colon : for scalar values (strings, numbers, booleans, null)
Double colon :: for vectors (lists and dicts)
Single space required after : and ::

name: "MyApp"           # scalar - single colon
settings::              # vector - double colon
  debug: true

Strings

Must be double-quoted (no barewords like YAML)
Escape \ and " with backslash
Multi-line strings use triple quotes """

simple: "hello world"
escaped: "path\\to\\file"
multiline: """
  Line one
  Line two
"""

Numbers

integer: 42
float: 3.14
scientific: 1.5e-3
hex: 0x1A
binary: 0b1010
special: inf, -inf, nan

Booleans and Null

enabled: true
disabled: false
empty: null

Lists

# Inline
tags:: "web", "api", "v2"

# Multiline
items::
  - "first"
  - "second"

# Empty
empty:: []

Dicts

# Inline (scalars only)
point:: x: 1, y: 2

# Multiline (supports nesting)
database::
  host: "localhost"
  port: 5432

# Empty
empty:: {}

Comments

# Comment (space after # required)
key: "value"  # inline comment

Version Directive (Optional)

%HUML v0.2.0

Quick Reference

Feature	HUML Syntax
String	`"quoted"`
Number	`42`, `3.14`, `0xFF`
Boolean	`true`, `false`
Null	`null`
Scalar key	`key: value`
Vector key	`key:: items`
List item	`- item`
Comment	`# text`

Common Patterns

Configuration File

%HUML v0.2.0

app::
  name: "MyService"
  port: 8080
  debug: false

database::
  host: "localhost"
  credentials::
    user: "admin"
    pass: "secret"

List of Objects

servers::
  - name: "web1"
    host: "10.0.0.1"
    port: 80
  - name: "web2"
    host: "10.0.0.2"
    port: 80

Validation

Use the bundled validation script to check HUML syntax and convert to JSON:

node scripts/validate.mjs path/to/file.huml

On success, outputs the parsed JSON. On failure, shows detailed error message.

Requirements: Node.js with @huml-lang/huml package installed.

Full Specification

See references/spec.md for the complete v0.2.0 specification including:

All number formats and escape sequences
Multiline string indentation rules
Key naming rules
Edge cases and formatting details

Resources

Official site: https://huml.io
Playground: https://huml.io/playground
npm package: @huml-lang/huml

huml

Safety Notice

Copy this and send it to your AI assistant to learn