Struct git_config::parser::Parser [−][src]
pub struct Parser<'a> { /* fields omitted */ }
Expand description
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 as5hello 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 requiredfrom_str
method. 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 = 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
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.
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
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.
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.
Consumes the parser to produce an iterator of Events.
Trait Implementations
This method returns an ordering between self
and other
values if one exists. Read more
This method tests less than (for self
and other
) and is used by the <
operator. Read more
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
This method tests greater than (for self
and other
) and is used by the >
operator. Read more
Auto Trait Implementations
impl<'a> RefUnwindSafe for Parser<'a>
impl<'a> UnwindSafe for Parser<'a>
Blanket Implementations
Mutably borrows from an owned value. Read more