Crate git_config[−][src]
Expand description
git_config
This crate is a high performance git-config
file reader and writer. It
exposes a high level API to parse, read, and write git-config
files,
which are loosely based on the INI file format.
This crate has a few primary offerings and various accessory functions. The table below gives a brief explanation of all offerings, loosely in order from the highest to lowest abstraction.
Offering | Description | Zero-copy? |
---|---|---|
GitConfig | Accelerated wrapper for reading and writing values. | On some reads1 |
Parser | Syntactic event emitter for git-config files. | Yes |
Value | Wrappers for git-config value types. | Yes |
This crate also exposes efficient value normalization which unescapes
characters and removes quotes through the normalize_*
family of functions,
located in the values
module.
Zero-copy versus zero-alloc
We follow nom
’s definition of “zero-copy”:
If a parser returns a subset of its input data, it will return a slice of that input, without copying.
Due to the syntax of git-config
, we must allocate at the parsing level
(and thus higher level abstractions must allocate as well) in order to
provide a meaningful event stream. That being said, all operations with the
parser is still zero-copy. Higher level abstractions may have operations
that are zero-copy, but are not guaranteed to do so.
However, we intend to be performant as possible, so allocations are limited restricted and we attempt to avoid copying whenever possible.
When read values do not need normalization. ↩
Modules
This module provides a high level wrapper around a single git-config
file.
This module handles parsing a git-config
file. Generally speaking, you
want to use a higher abstraction such as GitConfig
unless you have some
explicit reason to work with events instead.
Rust containers for valid git-config
types.