pub struct Events { /* private fields */ }Expand description
A git-config file parser.
This parser exposes low-level syntactic events from a git-config file.
Generally speaking, you’ll want to use File as it wraps
around the parser to provide a higher-level abstraction to a git-config
file, including querying, modifying, and updating values.
This parser guarantees that the events emitted are sufficient to
reconstruct a git-config file identical to the source git-config
when writing it.
§Differences between a .ini parser
While the git-config format closely resembles the .ini file format,
there are subtle differences that make them incompatible. For one, the file
format is not well defined, and there exists no formal specification to
adhere to.
For concrete examples, some notable differences are:
git-configsections permit subsections via either a quoted string ([some-section "subsection"]) or via the deprecated dot notation ([some-section.subsection]). Successful parsing these section names is not well defined in typical.iniparsers. This parser will handle these cases perfectly.- Comment markers are not strictly defined either. This parser will always and only handle a semicolon or octothorpe (also known as a hash or number sign).
- Global properties before the first section are accepted for compatibility
with Git, even though they are uncommon in
.gitconfigfiles. - Only
\t,\n,\b\\are valid escape characters. - Quoted and semi-quoted values will be parsed (but quotes will be included
in event outputs). An example of a semi-quoted value is
5"hello world", which should be interpreted as5hello worldafter normalization. - Line continuations via a
\character is supported (inside or outside of quotes) - Whitespace handling similarly follows the
git-configspecification as closely as possible, where excess whitespace after a non-quoted value are trimmed, and line continuations onto a new line with excess spaces are kept. - Only equal signs (optionally padded by spaces) are valid name/value delimiters.
Note that things such as case-sensitivity or duplicate sections are
not handled. This parser is a low level syntactic interpreter
and higher level wrappers around this parser should handle semantic values.
This also means
that string-like values are not interpreted. For example, hello"world"
would be read at a high level as helloworld but this parser will return
the former instead, with the extra quotes. This is because it is not the
responsibility of the parser to interpret these values, and doing so would
necessarily require a copy, which this parser avoids.
§Trait Implementations
- This struct does not implement
FromStrdue to lifetime constraints implied on the requiredfrom_strmethod. Instead, it providesFrom<&'_ str>.
§Idioms
If you do want to use this parser, there are some idioms that may help you with interpreting sequences of events.
§Value events do not immediately follow Key events
Consider the following git-config example:
[core]
autocrlf = inputBecause this parser guarantees near-perfect reconstruction, there are many non-significant events that occur in addition to the ones you may expect:
assert_eq!(events.iter().collect::<Vec<_>>(), vec![
EventRef::SectionHeader {
name: "core".into(),
separator: None,
subsection_name: None,
},
EventRef::Newline("\n".into()),
EventRef::Whitespace(" ".into()),
EventRef::SectionValueName("autocrlf".into()),
EventRef::Whitespace(" ".into()),
EventRef::KeyValueSeparator,
EventRef::Whitespace(" ".into()),
EventRef::Value("input".into()),
]);In particular, EventRef::SectionValueName and EventRef::Value are separated by two
EventRef::Whitespace events around an EventRef::KeyValueSeparator. If the config instead
had autocrlf=input, those whitespace events would not be present.
§KeyValueSeparator event is not guaranteed to emit
Consider the following git-config example:
[core]
autocrlfThis is a valid config with a autocrlf key having an implicit true
value. This means that there is not a = separating the key and value,
which means that the corresponding event won’t appear either:
§Quoted values are not unquoted
Consider the following git-config example:
[core]
autocrlf=true""
filemode=fa"lse"Both these events, when fully processed, should normally be true and
false. However, because this parser preserves the original event stream, we cannot process
partially quoted values, such as the false example. As a result, to
maintain consistency, the parser will just take all values as literals. The
relevant event stream emitted is thus emitted as:
§Whitespace after line continuations are part of the value
Consider the following git-config example:
[some-section]
file=a\
cBecause how git-config treats continuations, the whitespace preceding c
are in fact part of the value of file. The fully interpreted key/value
pair is actually file=a c. As a result, the parser will provide this
split value accordingly:
Implementations§
Source§impl Events
impl Events
Sourcepub fn from_bytes(
input: &[u8],
filter: Option<fn(EventRef<'_>) -> bool>,
) -> Result<Events, Error>
pub fn from_bytes( input: &[u8], filter: Option<fn(EventRef<'_>) -> bool>, ) -> Result<Events, Error>
Attempt to parse the provided bytes.
Inputs larger than u32::MAX bytes are rejected because event spans use 32-bit offsets.
Use filter to only include those events for which it returns true.
Sourcepub fn from_str(input: &str) -> Result<Events, Error>
pub fn from_str(input: &str) -> Result<Events, Error>
Attempt to parse the provided input string.
Prefer the from_bytes() method if UTF8 encoding
isn’t guaranteed.
Sourcepub fn iter(&self) -> impl Iterator<Item = EventRef<'_>> + '_
pub fn iter(&self) -> impl Iterator<Item = EventRef<'_>> + '_
Return all contained events as borrowed views.
Sourcepub fn frontmatter(&self) -> impl Iterator<Item = EventRef<'_>> + '_
pub fn frontmatter(&self) -> impl Iterator<Item = EventRef<'_>> + '_
Return all events before the first section as borrowed views.
Sourcepub fn sections(&self) -> impl Iterator<Item = SectionRef<'_>> + '_
pub fn sections(&self) -> impl Iterator<Item = SectionRef<'_>> + '_
Return all parsed sections as borrowed views.