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.

OfferingDescriptionZero-copy?
GitConfigAccelerated wrapper for reading and writing values.On some reads1
ParserSyntactic event emitter for git-config files.Yes
ValueWrappers 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.


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