Struct git_config::parser::Parser

pub struct Parser<'a> { /* fields omitted */ }

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 GitConfig 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.

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. Thus, attempting to use an .ini parser on a git-config file may successfully parse invalid configuration files.

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.
• Line continuations via a \ character is supported.
• 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 that things such as case-sensitivity or duplicate sections are not handled. This parser is a low level syntactic interpreter (as a parser should be), 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")),
Event::Whitespace(Cow::Borrowed("  ")),
Event::Key(Key(Cow::Borrowed("autocrlf"))),
Event::Whitespace(Cow::Borrowed(" ")),
Event::KeyValueSeparator,
Event::Whitespace(Cow::Borrowed(" ")),
Event::Value(Cow::Borrowed(b"input")),

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")),
Event::Whitespace(Cow::Borrowed("  ")),
Event::Key(Key(Cow::Borrowed("autocrlf"))),
Event::Value(Cow::Borrowed(b"")),

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")),
Event::Key(Key(Cow::Borrowed("autocrlf"))),
Event::KeyValueSeparator,
Event::Value(Cow::Borrowed(br#"true"""#)),
Event::Newline(Cow::Borrowed("\n")),
Event::Key(Key(Cow::Borrowed("filemode"))),
Event::KeyValueSeparator,
Event::Value(Cow::Borrowed(br#"fa"lse""#)),

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")),
Event::Key(Key(Cow::Borrowed("file"))),
Event::KeyValueSeparator,
Event::ValueNotDone(Cow::Borrowed(b"a")),
Event::Newline(Cow::Borrowed("\n")),
Event::ValueDone(Cow::Borrowed(b"    c")),

Implementations

impl<'a> Parser<'a>

#[must_use]pub fn frontmatter(&self) -> &[Event<'a>]

Returns the leading events (any comments, whitespace, or newlines before a section) from the parser. Consider Parser::take_frontmatter if you need an owned copy only once. If that function was called, then this will always return an empty slice.

pub fn take_frontmatter(&mut self) -> Vec<Event<'a>>

Takes the leading events (any comments, whitespace, or newlines before a section) from the parser. Subsequent calls will return an empty vec. Consider Parser::frontmatter if you only need a reference to the frontmatter

#[must_use]pub fn sections(&self) -> &[ParsedSection<'a>]

Returns the parsed sections from the parser. Consider Parser::take_sections if you need an owned copy only once. If that function was called, then this will always return an empty slice.

pub fn take_sections(&mut self) -> Vec<ParsedSection<'a>>

Takes the parsed sections from the parser. Subsequent calls will return an empty vec. Consider Parser::sections if you only need a reference to the comments.

#[must_use]pub fn into_vec(self) -> Vec<Event<'a>>

Consumes the parser to produce a Vec of Events.

#[must_use = "iterators are lazy and do nothing unless consumed"]pub fn into_iter(self) -> impl Iterator<Item = Event<'a>> + FusedIterator

Consumes the parser to produce an iterator of Events.

Trait Implementations

impl<'a> Clone for Parser<'a>

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for Parser<'a>

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

Formats the value using the given formatter.

impl<'a> Default for Parser<'a>

fn default() -> Parser<'a>

Returns the “default value” for a type.

impl<'a> Eq for Parser<'a>

impl<'a> From<Parser<'a>> for GitConfig<'a>

fn from(parser: Parser<'a>) -> Self

Performs the conversion.

impl<'a> Hash for Parser<'a>

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

Feeds this value into the given Hasher.

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

Feeds a slice of this type into the given Hasher.

impl<'a> Ord for Parser<'a>

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

This method returns an Ordering between self and other.

#[must_use]pub fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use]pub fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use]pub fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl<'a> PartialEq<Parser<'a>> for Parser<'a>

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

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

fn ne(&self, other: &Parser<'a>) -> bool

This method tests for !=.

impl<'a> PartialOrd<Parser<'a>> for Parser<'a>

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

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

#[must_use]pub fn lt(&self, other: &Rhs) -> bool

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

#[must_use]pub fn le(&self, other: &Rhs) -> bool

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

#[must_use]pub fn gt(&self, other: &Rhs) -> bool

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

#[must_use]pub 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> StructuralEq for Parser<'a>

impl<'a> StructuralPartialEq for Parser<'a>

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

type Error = Error<'a>

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 Parser<'a>

type Error = Error<'a>

The type returned in the event of a conversion error.

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

Performs the conversion.