gix_config/lib.rs
1//! # `gix_config`
2//!
3//! This crate is a high performance `git-config` file reader and writer. It
4//! exposes a high level API to parse, read, and write [`git-config` files].
5//!
6//! This crate has a few primary offerings and various accessory functions. The
7//! table below gives a brief explanation of all offerings, loosely in order
8//! from the highest to lowest abstraction.
9//!
10//! | Offering | Description | Zero-copy? |
11//! | ------------- | --------------------------------------------------- | ----------------- |
12//! | [`File`] | Accelerated wrapper for reading and writing values. | On some reads[^1] |
13//! | [`parse::State`] | Syntactic events for `git-config` files. | Yes |
14//! | value wrappers | Wrappers for `git-config` value types. | Yes |
15//!
16//! This crate also exposes efficient value normalization which unescapes
17//! characters and removes quotes through the `normalize_*` family of functions,
18//! located in the [`value`] module.
19//!
20//! # Examples
21//!
22//! ## Read And Update Values
23//!
24//! ```
25//! use bstr::ByteSlice;
26//! use std::str::FromStr;
27//!
28//! const SAMPLE: &str = "[core]\neditor = vim\nbare = false\n[remote \"origin\"]\nurl = https://example.com/gitoxide.git\n";
29//! let mut config = gix_config::File::from_str(SAMPLE).unwrap();
30//! assert_eq!(config.string_by("core", None, "editor").unwrap().as_ref(), "vim");
31//! assert_eq!(config.boolean_by("core", None, "bare").unwrap().unwrap(), false);
32//!
33//! let previous = config.set_raw_value(&"core.editor", "nvim").unwrap().unwrap();
34//! assert_eq!(previous.as_ref(), "vim");
35//! assert_eq!(config.raw_value("core.editor").unwrap().as_ref(), "nvim");
36//! assert!(config.to_bstring().find(b"nvim").is_some());
37//! ```
38//!
39//! # Known differences to the `git config` specification
40//!
41//! - Legacy headers like `[section.subsection]` are supposed to be turned into to lower case and compared
42//! case-sensitively. We keep its case and compare case-insensitively.
43//!
44//! [^1]: When read values do not need normalization and it wasn't parsed in 'owned' mode.
45//!
46//! [`git-config` files]: https://git-scm.com/docs/git-config#_configuration_file
47//! [`File`]: crate::File
48//! [`parse::State`]: crate::parse::Events
49//! [`nom`]: https://github.com/Geal/nom
50//!
51//! ## Feature Flags
52#![cfg_attr(
53 all(doc, feature = "document-features"),
54 doc = ::document_features::document_features!()
55)]
56#![cfg_attr(all(doc, feature = "document-features"), feature(doc_cfg))]
57#![deny(missing_docs, unsafe_code)]
58
59pub mod file;
60
61///
62pub mod lookup;
63pub mod parse;
64///
65pub mod value;
66pub use gix_config_value::{color, integer, path, Boolean, Color, Integer, Path};
67
68mod key;
69pub use key::{AsKey, KeyRef};
70mod types;
71pub use types::{File, Source};
72///
73pub mod source;