Fast format preserving (round-tripping) INI-parser

[ crates.io ] [ lib.rs ] [ docs.rs ]

ini-roundtrip is a fast format preserving (round-tripping) streaming INI parser that attempts to work on arbitrary INI files.

The code is inspired by and heavily based on ini_core.

MSRV

Current minimum supported Rust version is 1.74.0. This may be updated as needed. MSRV bump is not considered a semver breaking change.

lib.rs:

Format preserving Ini streaming parser

Simple INI parser with the following features:

Features:

• Format-preserving (you can write out again and get identical result)
• Fast!
• Streaming
• no_std support

Caveats:

• The Display trait on [Item] does not preserve formatting, if this is something you want, make sure to use the raw attributes to extract the raw line instead.
• Newlines are not saved. It is up to the caller to keep track of the type of newline in use. Mixed newline (e.g. a mix of CR, CRLF and LF) is supported on loading, but not on saving.

Examples

use ini_roundtrip as ini;

let document = "\
[SECTION]
;this is a comment
Key = Value  ";

let elements = [
ini::Item::SectionEnd,
ini::Item::Section{name: "SECTION", raw: "[SECTION]"},
ini::Item::Comment{raw: ";this is a comment"},
ini::Item::Property{key: "Key", val: Some("Value"), raw: "Key = Value  "},
ini::Item::SectionEnd,
];

for (index, item) in ini::Parser::new(document).enumerate() {
assert_eq!(item, elements[index]);
}

The SectionEnd pseudo-element is returned before a new section and at the end of the document. This helps processing sections after their properties finished parsing.

The parser is very much line-based, it will continue no matter what and return nonsense as an item:

use ini_roundtrip as ini;

let document = "\
[SECTION
nonsense";

let elements = [
ini::Item::SectionEnd,
ini::Item::Error("[SECTION"),
ini::Item::Property{key: "nonsense", val: None, raw: "nonsense"},
ini::Item::SectionEnd,
];

for (index, item) in ini::Parser::new(document).enumerate() {
assert_eq!(item, elements[index]);
}

Lines starting with [ but contain either no closing ] or a closing ] not followed by a newline are returned as Item::Error. Lines missing a = are returned as Item::Property with None value. See below for more details.

Format

INI is not a well specified format, this parser tries to make as little assumptions as possible, but it does make decisions.

• Newline is either "\r\n", "\n" or "\r". It can be mixed in a single document but this is not recommended.
• Section header is "[" section "]" newline. section can be anything except contain newlines.
• Property is key "=" value newline. key and value can be anything except contain newlines.
• Comment is the raw line for lines starting with ; or #
• Blank is just newline.

Padding whitespace is always trimmed, but the raw line is always stored as well.

No further processing of the input is done, e.g. if escape sequences are necessary they must be processed by the caller.