Crate ini_roundtrip
source ·Expand description
§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
andvalue
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.
Structs§
- Ini streaming parser.
Enums§
- A parsed element of syntatic meaning