Struct gix_config::parse::Events

pub struct Events<'a> {
    pub frontmatter: FrontMatterEvents<'a>,
    pub sections: Vec<Section<'a>>,
}

A zero-copy git-config file parser.

This is 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-config sections 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 .ini parsers. 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 may be allowed in .ini parsers, but is strictly disallowed by this parser.
• 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 as 5hello world after normalization.
• Line continuations via a \ character is supported (inside or outside of quotes)
• Whitespace handling similarly follows the git-config specification 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, which may or may not be zero-copy, 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 FromStr due to lifetime constraints implied on the required from_str method. Instead, it provides From<&'_ 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 = input

Because this parser guarantees perfect reconstruction, there are many non-significant events that occur in addition to the ones you may expect:

Event::SectionHeader(section_header),
Event::Newline(Cow::Borrowed("\n".into())),
Event::Whitespace(Cow::Borrowed("  ".into())),
Event::SectionKey(section::Key::try_from("autocrlf")?),
Event::Whitespace(Cow::Borrowed(" ".into())),
Event::KeyValueSeparator,
Event::Whitespace(Cow::Borrowed(" ".into())),
Event::Value(Cow::Borrowed("input".into())),

Note the two whitespace events between the key and value pair! Those two events actually refer to the whitespace between the name and value and the equal sign. So if the config instead had autocrlf=input, those whitespace events would no longer be present.

KeyValueSeparator event is not guaranteed to emit

Consider the following git-config example:

[core]
  autocrlf

This 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:

Event::SectionHeader(section_header),
Event::Newline(Cow::Borrowed("\n".into())),
Event::Whitespace(Cow::Borrowed("  ".into())),
Event::SectionKey(section::Key::try_from("autocrlf")?),
Event::Value(Cow::Borrowed("".into())),

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 is zero-copy, 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:

Event::SectionHeader(section_header),
Event::Newline(Cow::Borrowed("\n".into())),
Event::SectionKey(section::Key::try_from("autocrlf")?),
Event::KeyValueSeparator,
Event::Value(Cow::Borrowed(r#"true"""#.into())),
Event::Newline(Cow::Borrowed("\n".into())),
Event::SectionKey(section::Key::try_from("filemode")?),
Event::KeyValueSeparator,
Event::Value(Cow::Borrowed(r#"fa"lse""#.into())),

Whitespace after line continuations are part of the value

Consider the following git-config example:

[some-section]
file=a\
    c

Because 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:

Event::SectionHeader(section_header),
Event::Newline(Cow::Borrowed("\n".into())),
Event::SectionKey(section::Key::try_from("file")?),
Event::KeyValueSeparator,
Event::ValueNotDone(Cow::Borrowed("a".into())),
Event::Newline(Cow::Borrowed("\n".into())),
Event::ValueDone(Cow::Borrowed("    c".into())),

Fields

frontmatter: FrontMatterEvents<'a>

Events seen before the first section.

sections: Vec<Section<'a>>

All parsed sections.

Implementations

impl Events<'static>

pub fn from_bytes_owned<'a>( input: &'a [u8], filter: Option<fn(_: &Event<'a>) -> bool> ) -> Result<Events<'static>, Error>

Parses the provided bytes, returning an Events that contains allocated and owned events. This is similar to Events::from_bytes(), but performance is degraded as it requires allocation for every event.

Use filter to only include those events for which it returns true.

impl<'a> Events<'a>

pub fn from_bytes( input: &'a [u8], filter: Option<fn(_: &Event<'a>) -> bool> ) -> Result<Events<'a>, Error>

Attempt to zero-copy parse the provided bytes. On success, returns a Events that provides methods to accessing leading comments and sections of a git-config file and can be converted into an iterator of Event for higher level processing.

Use filter to only include those events for which it returns true.

pub fn from_str(input: &'a str) -> Result<Events<'a>, Error>

Attempt to zero-copy parse the provided input string.

Prefer the from_bytes() method if UTF8 encoding isn’t guaranteed.

pub fn into_iter(self) -> impl FusedIterator<Item = Event<'a>>

Consumes the parser to produce an iterator of all contained events.

pub fn into_vec(self) -> Vec<Event<'a>>

Place all contained events into a single Vec.

Trait Implementations

impl<'a> Clone for Events<'a>

fn clone(&self) -> Events<'a>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Debug for Events<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> Default for Events<'a>

fn default() -> Events<'a>

Returns the “default value” for a type.

impl<'a> Hash for Events<'a>

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<'a> Ord for Events<'a>

fn cmp(&self, other: &Events<'a>) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

impl<'a> PartialEq for Events<'a>

fn eq(&self, other: &Events<'a>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a> PartialOrd for Events<'a>

fn partial_cmp(&self, other: &Events<'a>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<'a> TryFrom<&'a [u8]> for Events<'a>

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: &'a [u8]) -> Result<Self, Self::Error>

Performs the conversion.

impl<'a> TryFrom<&'a str> for Events<'a>

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: &'a str) -> Result<Self, Self::Error>

Performs the conversion.

impl<'a> Eq for Events<'a>

impl<'a> StructuralPartialEq for Events<'a>