Skip to content
soml-langPublic

About

Rust implementation of SOML

Topics

Resources

Stars

6 stars

Watchers

1 watching

Forks

Repository files navigation

soml-lang

SOML for Rust: a strict reader, serde support, and a lossless syntax tree

Note

SOML is a config format for humans. The format is a draft.

Highlights

  • Checks every rule in the spec: duplicate keys, the int64 range, date, instant, and duration ranges, raw control characters, the nesting limit, and more
  • Errors give a line and a column, also when a valid document does not fit your type
  • Writes members in field order, or in canonical form, where the same value always gives the same bytes
  • A lossless syntax tree that keeps comments and the author's spelling when you change a document
  • A formatter that changes layout and nothing else
  • Spanned<T> for the position of any value, and error messages with a code frame
  • Reads and writes std::time::Duration, and reads jiff and chrono instants and durations, with optional features for native dates, instants, and durations
  • Passes the language-neutral conformance suite of the spec
  • No unsafe code, and two required dependencies: serde_core and zmij

Install

cargo add soml-lang

The package is soml-lang, and the library is soml.

Usage

API documentation

Read

use serde::Deserialize;

#[derive(Deserialize)]
#[serde(rename_all = "kebab-case")]
struct Config {
	name: String,
	replicas: u32,
	timeout: std::time::Duration,
	deployed_at: soml::Instant,
	launch_date: soml::Date,
	labels: Vec<String>,
	postgres: Postgres,
}

#[derive(Deserialize)]
struct Postgres {
	host: String,
	port: u16,
}

fn main() -> Result<(), soml::Error> {
	let config: Config = soml::from_str("
		/* The edge service. */
		name: 'api-gateway'
		replicas: 3
		timeout: 1m30s # Including retries.
		deployed-at: 2026-09-19T14:00:00Z
		launch-date: 2027-09-19
		labels: ['prod', 'eu-west']
		postgres: {host: 'db.internal', port: 5432}
	")?;

	assert_eq!(config.postgres.port, 5432);
	assert_eq!(config.timeout.as_secs(), 90);
	Ok(())
}

Indentation never matters in SOML, so a document can be indented like the code around it.

Write

#[derive(serde::Serialize)]
struct Server {
	port: u16,
	hosts: Vec<&'static str>,
}

fn main() -> Result<(), soml::Error> {
	let server = Server { port: 8080, hosts: vec!["a", "b"] };
	assert_eq!(soml::to_string(&server)?, "port: 8080\nhosts: [\n\t'a'\n\t'b'\n]\n");
	assert_eq!(soml::to_string_canonical(&server)?, "hosts: [\n\t'a'\n\t'b'\n]\nport: 8080\n");
	Ok(())
}

soml::to_string writes one member or item per line, with tab indentation and no commas. Members keep the order of the value: a struct's fields in declaration order, and a map's entries in iteration order.

soml::to_string_canonical also sorts members by key, so the same value always gives the same bytes. Use it to hash, sign, or compare documents, and to write a HashMap, whose order changes on each run.

Values of unknown shape

fn main() -> Result<(), soml::Error> {
	let value: soml::Value = "port: 8080\nhosts: ['a', 'b']".parse()?;

	assert_eq!(value.get("port").and_then(soml::Value::as_i64), Some(8080));
	assert_eq!(value.get("hosts").and_then(|hosts| hosts.get(1)).and_then(soml::Value::as_str), Some("b"));
	Ok(())
}

An int and a float are different types, so as_f64() does not convert an int. A soml::Value keeps object members sorted by key, because member order is not part of a value. Use soml::Document to keep the written order.

Change a document and keep its comments

fn main() -> Result<(), soml::Error> {
	let mut document: soml::Document = "/* The edge service. */\nport: 0x1F90 # The default.\nserver: {host: 'a'}\n".parse()?;

	document.set(["port"], 8080)?;
	document.set(["server", "port"], 443)?;
	document.set(["replicas"], 3)?;

	assert_eq!(document.to_string(), "/* The edge service. */\nport: 8080 # The default.\nserver: {host: 'a', port: 443}\nreplicas: 3\n");
	Ok(())
}

An unchanged document prints the exact text it was parsed from. A changed one keeps the comments, blank lines, indentation, member order, and spelling of everything outside the change. Changes follow the spec's editing rules: a new member goes after the last member of its object, a removed member or item takes its own comments with it, and a formatted document stays formatted. remove returns whether it removed something, and removing a missing value is not an error. Every parsed node also has its position, for linters and editors.

Format

fn main() -> Result<(), soml::Error> {
	assert_eq!(soml::format("a: {b: 1, c: [2,3]}  # Note.")?, "a: {b: 1, c: [2, 3]} # Note.\n");
	assert_eq!(soml::format("a: {\nb: 1, c: [2,3]}")?, "a: {\n\tb: 1\n\tc: [2, 3]\n}\n");
	Ok(())
}

The formatter changes layout and nothing else: one tab per level, one member or item per line, no commas, at most one blank line in a row, and no trailing whitespace. An object or array whose brackets are on one line stays on one line, with a comma and a space between its members or items. Put a line break anywhere inside it to expand it. Comments, member order, block strings, and the spelling of every value stay as they are. Formatting is idempotent. The spec's formatter rules are normative, so every conforming formatter gives the same text. The tree module lists them.

Errors

#[derive(serde::Deserialize, Debug)]
struct Server {
	port: u16,
}

let text = "host: 'a'\nport: 70000";
let error = soml::from_str::<Server>(text).unwrap_err();

assert_eq!(error.to_string(), "invalid value: integer `70000`, expected u16 at line 2, column 7");
assert_eq!(error.kind(), soml::ErrorKind::Data);

// For a terminal:
assert_eq!(error.code_frame(text).unwrap(), "  1 | host: 'a'\n> 2 | port: 70000\n    |       ^");

An error has a kind: Syntax for text that is not valid SOML, Data for a valid document that does not fit your type or a path that does not fit a Document, Write for a value that SOML cannot represent or a Document::set that would make the document invalid, and Io for reading and writing.

Error messages and code frames replace terminal controls and bidirectional controls with �. Tabs stay, and messages other than syntax errors may contain line breaks.

Positions of values

#[derive(serde::Deserialize)]
struct Server {
	port: soml::Spanned<u16>,
}

fn main() -> Result<(), soml::Error> {
	let text = "port: 0";
	let server: Server = soml::from_str(text)?;

	if *server.port == 0 {
		let start = server.port.span().unwrap().start;
		let error = soml::Error::with_position("Port 0 is reserved", text, start);
		assert_eq!(error.to_string(), "Port 0 is reserved at line 1, column 7");
	}

	Ok(())
}

Spanned<T> reads any value with its byte range, so your own checks after reading can point at the right place. The span is None for a value from from_value or another format, for a map key, and inside #[serde(flatten)], untagged enums, and internally tagged enums (see Limitations).

Build a value

let value = soml::soml!({
	name: "api",
	"deployed-at": soml::Instant::from_unix(1_789_826_400, 0),
	replicas: 3,
	tags: ["prod", "eu-west"],
	owner: null,
});

assert_eq!(value.get("replicas").and_then(soml::Value::as_i64), Some(3));

A key is an identifier or a string literal, and a value is null, {…}, […], or any expression that converts to a Value. A key that is there twice panics.

Readers and writers

soml::from_reader, soml::to_writer, and soml::to_writer_canonical read from an io::Read and write to an io::Write. A document is only valid as a whole, so from_reader reads everything first.

Types

Rust SOML Notes
bool bool
i8…i128, u8…u128 int Range-checked both ways. An int is 64-bit, so a larger value cannot be written.
f32, f64 float An int reads into a float only when it converts exactly. A float never reads into an int. An f32 round-trips with its own shortest digits, so 0.1f32 is 0.1. A float too large for the type reads as infinity, as in serde_json. NaN cannot be written.
String, &str, char string A &str borrows from the input when the string is '...' or "..." without escapes. Use String or Cow<str> when a document may hold other strings.
Option<T> null or the value A missing field reads as None.
(), a unit struct null
Vec<T>, a tuple array
a struct, HashMap, BTreeMap object A map key can be a string, a char, a bool, an integer (404: 'x'), or a unit enum variant.
an enum string, or a one-member object A unit variant is a string. The others are {variant: value}.
soml::Date date Validated proleptic Gregorian year, month, and day, years 0001 through 9999, without a timezone.
soml::Instant instant Exact, with nanoseconds.
soml::Duration, std::time::Duration duration A negative duration does not fit a std::time::Duration. serde has no duration type, so a std::time::Duration is recognized by its shape: a struct named Duration with the fields secs and nanos. Your own struct with that shape is also written as a duration.
soml::Value any value

Field names come from serde, so use #[serde(rename_all = "kebab-case")] for the usual SOML key style.

Adjacently tagged enums (#[serde(tag = "type", content = "value")]) keep native SOML types and spans in either field order, including when unknown fields are ignored.

A soml::Date preserves calendar components exactly: soml::Date::new(1582, 10, 10) validates them, and "2027-09-19".parse::<soml::Date>() requires exact ASCII syntax. It stays distinct from strings and instants in the native value tree and typed decoding. JSON sees its canonical string.

Dates, instants, and durations from other crates

jiff::Timestamp, jiff::SignedDuration, chrono::DateTime<Utc>, and humantime fields read SOML instants and durations, because they ask for text, and an instant or a duration gives its canonical text. humantime reads only instants from 1970 on. As a result, a String field also accepts an instant or a duration. chrono::TimeDelta does not ask for text, so it needs soml::chrono::time_delta.

For chrono::NaiveDate and jiff::civil::Date, use the date modules below for native reading and writing. They convert Gregorian components directly and reject years outside SOML’s range. Their option modules handle nullable dates. A String field rejects a native date.

Those types write themselves as strings, such as '2026-09-19T14:00:00Z'. To write native instants and durations, use soml::Instant and soml::Duration, or turn on a feature and use its module with #[serde(with)]:

cargo add soml-lang --features jiff
#[derive(serde::Serialize, serde::Deserialize)]
struct Deploy {
	#[serde(with = "soml::jiff::timestamp")]
	at: jiff::Timestamp,
	#[serde(with = "soml::jiff::signed_duration::option", default)]
	took: Option<jiff::SignedDuration>,
}
Feature Modules Conversions
jiff soml::jiff::date, soml::jiff::timestamp, soml::jiff::signed_duration civil::Date, Timestamp, and SignedDuration to and from native SOML values
chrono soml::chrono::naive_date, soml::chrono::date_time, soml::chrono::time_delta NaiveDate, DateTime<Utc>, and TimeDelta to and from native SOML values

Each module has an option submodule for an Option, which needs #[serde(default)] to read a missing member as None. The modules read only native values, not strings (except through serde's buffer, see Limitations), and a value outside SOML's range is an error. jiff's timestamps end at 9999-12-30T22:00:00.999999999Z, about a day before SOML's.

Format

Documents follow the SOML specification.

  • File extension: .soml
  • Encoding: UTF-8 without a byte order mark, with LF line endings
  • Media type: application/soml
  • Uniform type identifier: com.sindresorhus.soml
  • Nesting limit: 100 levels, counting every object and array, including the document's own

Performance

cargo run --release --manifest-path bench/Cargo.toml -- --instructions

Millions of instructions to read, write, and format the spec's benchmark fixtures on an Apple M4 Pro with Rust 1.99.0, taking the median of three runs. Each fixture holds the same data in SOML, JSON, and TOML, and the sizes are of the SOML files. service and earthquakes are read into a struct and written from it, with JSON and TOML durations and JSON instants as jiff types. platform has hundreds of settings, so it is read into each library's value type (soml::Value, serde_json::Value, and toml::Table).

soml-lang serde_json toml
Read service (3 KB) 0.13 M 0.073 M 0.36 M
Read platform (35 KB) 1.4 M 0.88 M 3.2 M
Read earthquakes (733 KB) 34 M 20 M 99 M
Write service 0.066 M 0.063 M 0.30 M
Write platform 0.46 M 0.41 M 2.2 M
Write earthquakes 16 M 16 M 82 M
Format service 0.51 M
Format platform 3.9 M
Format earthquakes 140 M

soml::Document reads each fixture in 51% to 62% of the instructions of toml_edit::DocumentMut. Instruction counts are used instead of times because they stay stable on a busy machine. --instructions works only on macOS. Without it, the benchmark prints times.

Reading and writing check every rule of the spec, such as duplicate keys in a map, which serde_json does not check.

Limitations

  • #[serde(flatten)], untagged enums, and internally tagged enums read values through serde's buffer, which has no date, instant, or duration type and no positions. There, a date, instant, or duration is its text: a soml::Value holds it as a string, soml::Date, soml::Instant, and soml::Duration still read it, and a std::time::Duration cannot be read. An int reads into a float even when the float does not hold it exactly. An f32 is read through an f64, as in serde_json, so 2 of the 4.3 billion f32 values read back one step away. A Spanned value has no span.
  • A document with an error, or one that does not fit the type, is read a second time to find the first error, so a Deserialize impl with side effects, such as logging, runs twice for it. Likewise, a value that to_string cannot write, or whose Serialize impl catches an error and goes on, is serialized a second time.
  • The soml! macro reads one item or member at a time, so a literal with more than about 120 of them at one level reaches the compiler's recursion limit, as with json!.

About

Rust implementation of SOML

Topics

Resources

Stars

6 stars

Watchers

1 watching

Forks

Releases

Contributors

Languages