tomling 0.3.0

tomling is a TOML parser API, that is designed to have minimal dependencies and is no_std compatible. The main target is Cargo manifests (Cargo.toml files) and hence why specific API is provided for that purpose as well.

Abandoned

As of 2025-07-09, this crate has been abandoned in favor of toml crate, which now supports all the important use cases this crate provides, has minimal dependencies, supports no_std and (unlike this crate) provides full compatibility with the specification.

The only feature of tomling that toml does not provide, is the specific Cargo API. However, that can be easily developed on top of toml. If you're interested in that, feel free to take the relevant code from this crate (specifically the cargo module) and port it (which should be trivial) on top of toml. @zeenix may do that at some point. :)

Usage

//
// Using the `Cargo.toml` specific API:
//

# #[cfg(feature = "cargo-toml")]
# {
use tomling::cargo::{Manifest, ResolverVersion, RustEdition};
let manifest: Manifest = tomling::from_str(CARGO_TOML).unwrap();

let package = manifest.package().unwrap();
assert_eq!(package.name(), "example");
assert_eq!(package.version().unwrap(), "0.1.0".into());
assert_eq!(package.edition().unwrap().uninherited_ref().unwrap(), &RustEdition::E2021);
assert_eq!(package.resolver().unwrap(), ResolverVersion::V2);
let authors = package.authors().unwrap();
let mut authors = authors.uninherited().unwrap();
let alice = authors.next().unwrap();
assert_eq!(alice.name(), "Alice Great");
assert_eq!(alice.email(), Some("foo@bar.com"));
let bob = authors.next().unwrap();
assert_eq!(bob.name(), "Bob Less");
assert_eq!(bob.email(), None);

let serde = manifest.dependencies().unwrap().by_name("serde").unwrap();
assert_eq!(serde.version(), Some("1.0"));
assert_eq!(
  serde
    .features()
    .map(|f| f.map(|s| &*s).collect::<Vec<_>>())
    .as_deref(),
  Some(&["std", "derive"][..]),
);

let regex = manifest.dependencies().unwrap().by_name("regex").unwrap();
assert_eq!(regex.version(), Some("1.5"));

let cc = manifest
    .targets()
    .unwrap()
    .by_name("cfg(unix)")
    .unwrap()
    .build_dependencies()
    .unwrap()
    .by_name("cc")
    .unwrap();
assert_eq!(cc.version(), Some("1.0.3"));

let default = manifest.features().unwrap().by_name("default").unwrap();
assert_eq!(default, &["serde"]);

let binary = &manifest.binaries().unwrap()[0];
assert_eq!(binary.name(), "some-binary");
assert_eq!(binary.path(), Some("src/bin/my-binary.rs"));
# }

//
// Using the generic raw `TOML` parsing API:
//
let manifest = tomling::parse(CARGO_TOML).unwrap();
let package = manifest.get("package").unwrap().as_table().unwrap();
assert_eq!(package.get("name").unwrap().as_str().unwrap(), "example");
assert_eq!(package.get("version").unwrap().as_str().unwrap(), "0.1.0");
assert_eq!(package.get("edition").unwrap().as_str().unwrap(), "2021");
assert_eq!(package.get("resolver").unwrap().as_str().unwrap(), "2");

let deps = manifest.get("dependencies").unwrap().as_table().unwrap();
let serde = deps.get("serde").unwrap().as_table().unwrap();
assert_eq!(serde.get("version").unwrap().as_str().unwrap(), "1.0");
let serde_features =
    serde.get("features").unwrap().as_array().unwrap().as_slice();
assert_eq!(serde_features, &[tomling::Value::from("std"), "derive".into()]);
let regex = deps.get("regex").unwrap().as_str().unwrap();
assert_eq!(regex, "1.5");

const CARGO_TOML: &'static str = r#"
[package]
name = "example"
version = "0.1.0"
edition = "2021"
authors = ["Alice Great <foo@bar.com>", "Bob Less"]
resolver = "2"

[dependencies]
serde = { version = "1.0", features = [
    "std",
    "derive", # and here.
] }
regex = "1.5"

[target.'cfg(unix)'.build-dependencies]
cc = "1.0.3"

[features]
default = ["serde"]

[[bin]]
name = "some-binary"
path = "src/bin/my-binary.rs"

"#;

Dependencies

• winnow with alloc and simd features enabled.
• serde (optional) with alloc and derive features enabled.

Features

• serde - Enables Serde support.
• cargo-toml - Enables Cargo manifest specific API. This requires serde.
• simd - Enables the simd feature of winnow for SIMD acceleration for parsing.
• std - Enables some features, like std::error::Error implementation for Error type. It also enables std feature of winnow and serde.

All features are enabled by default.

Comparison with toml crate

The toml crate is great but it being based on toml_edit, it ends up requiring indexmap crate and its dependencies. tomling was created specifically to avoid most of these dependencies by focusing completely on the parsing of TOML documents only.

(As of 2025-07-09, the above is no longer the case and that's why this crate is now abandoned in favor of toml crate)

Having said that, some of the code (especially the low-level parsing code) is inspired (or in some cases, copied) from the toml_edit crate.

Goals

• Simple parser/deserializer API.
• Minimum dependencies. The only mandatory dependency is winnow with only 2 features enabled.
• Primary target: Cargo manifests.

Non-goals

• Encoder/Serializer API.

License

MIT

The Name

The name "tomling" is a portmanteau of "TOML" and "ling" (a suffix meaning "a small thing"). Coincidentally, it also means a "male kitten" in English, with all the stress on the "kitten" part 😸 and none on the "male" part.