Crate ini_roundtrip

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, eg. if escape sequences are necessary they must be processed by the caller.

Structs

• Parser
  Ini streaming parser.

Enums

• Item
  A parsed element of syntatic meaning