From bd29f671425c8172e4f30ca6c86207a63ad8179d Mon Sep 17 00:00:00 2001 From: Edward Shen Date: Sat, 6 Mar 2021 01:51:05 -0500 Subject: [PATCH] update readme --- README.md | 59 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 58 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index ece86f7..f0edfd8 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,61 @@ **git-config is a library for interacting with `git-config` files.** +This crate intents to be a performant Rust implementation for reading and +writing `git-config` files. It exposes tiers of abstractions, from simple +config value wrappers to a high level reader and writer. + +The highlight of this crate is the zero-copy parser. We employ techniques to +avoid copying where necessary, and reads that do not need normalization are +guaranteed to be zero-copy. Higher level abstractions maintain this guarantee, +and utilizes acceleration structures for increased performance. + +Currently, this is _not_ a binary. While we do intent to have a drop-in +replacement for the `git config` sub-command, we're currently missing +system-level abstractions to do so. + +## Examples + +Reading and writing to a config: + +```rust +use git_config::file::GitConfig; +use git_config::values::Boolean; +use std::fs::read_to_string; + +let input = read_to_string(r#" +[core] + some-bool = true + +[other "internal"] + hello = world +"#)?; +let mut config = GitConfig::from(input)?; +let boolean = config.get_config::("core", None, "some-bool"); +config.set_value("other", Some("internal"), "hello", "clippy!"); +``` + +## Contributing + +Contributions are always welcome! + +### Code quality + +This repository enables pedantic, cargo, and nursery `clippy` lints. Make sure +to run `cargo clean && cargo clippy` (the clean stage is very important!) to +ensure your code is linted. + +### Testing + +Since this is a performance oriented crate, in addition to well tested code via +`cargo test`, we also perform benchmarks to measure notable gains or losses in +performance. We use [`criterion`] so benches can be run via `cargo bench` after +installing it via `cargo install cargo-criterion`. + +Changes to `parser.rs` may include a request to fuzz to ensure that it cannot +panic on inputs. This can be done by executing `cargo fuzz parser` after +installing the `fuzz` sub-command via `cargo install cargo-fuzz`. + #### License @@ -15,4 +70,6 @@ Licensed under either of Apache License, Version Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in git-config by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions. - \ No newline at end of file + + +[`criterion`]: https://github.com/bheisler/criterion.rs \ No newline at end of file