#![forbid(unsafe_code)]// #![warn(missing_docs)]// #![warn(clippy::pedantic, clippy::nursery)] //! # `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 reads[^1] |//! | [`Parser`]    | Syntactic event emitter for `git-config` files.     | Yes               |//! | [`values`]    | 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.//!//! [^1]: When read values do not need normalization.//!//! [`git-config` files]: https://git-scm.com/docs/git-config#_configuration_file//! [INI file format]: https://en.wikipedia.org/wiki/INI_file//! [`GitConfig`]: crate::file::GitConfig//! [`Parser`]: crate::parser::Parser//! [`values`]: crate::values//! [`nom`]: https://github.com/Geal/nom // Cargo.toml cannot have self-referential dependencies, so you can't just// specify the actual serde crate when you define a feature called serde. We// instead call the serde crate as serde_crate and then rename the crate to// serde, to get around this in an intuitive manner.#[cfg(feature = "serde")]extern crate serde_crate as serde; pub mod lookup {     /// The error when looking up a value.    #[derive(Debug, thiserror::Error)]    pub enum Error<E> {        #[error(transparent)]        ValueMissing(#[from] crate::lookup::existing::Error),        #[error(transparent)]        FailedConversion(E),    }     pub mod existing {        /// The error when looking up a value that doesn't exist.        #[derive(Debug, thiserror::Error)]        pub enum Error {            #[error("The requested section does not exist")]            SectionMissing,            #[error("The requested subsection does not exist")]            SubSectionMissing,            #[error("The key does not exist in the requested section")]            KeyMissing,        }    }} pub mod file;pub mod fs;pub mod parser;pub mod values;/// The future home of the `values` module (TODO).pub mod value {    pub mod parse {        use bstr::BString;         /// The error returned when creating `Integer` from byte string.        #[derive(Debug, thiserror::Error, Eq, PartialEq)]        #[allow(missing_docs)]        #[error("Could not decode '{}': {}", .input, .message)]        pub struct Error {            pub message: &'static str,            pub input: BString,            #[source]            pub utf8_err: Option<std::str::Utf8Error>,        }         impl Error {            pub(crate) fn new(message: &'static str, input: impl Into<BString>) -> Self {                Error {                    message,                    input: input.into(),                    utf8_err: None,                }            }             pub(crate) fn with_err(mut self, err: std::str::Utf8Error) -> Self {                self.utf8_err = Some(err);                self            }        }    }} mod permissions {    use crate::Permissions;     impl Permissions {        /// Allow everything which usually relates to a fully trusted environment        pub fn all() -> Self {            use git_sec::Permission::*;            Permissions {                system: Allow,                global: Allow,                user: Allow,                repository: Allow,                worktree: Allow,                env: Allow,                includes: Allow,            }        }         /// If in doubt, this configuration can be used to safely load configuration from sources which is usually trusted,        /// that is system and user configuration. Do load any configuration that isn't trusted as it's now owned by the current user.        pub fn secure() -> Self {            use git_sec::Permission::*;            Permissions {                system: Allow,                global: Allow,                user: Allow,                repository: Deny,                worktree: Deny,                env: Allow,                includes: Deny,            }        }    }} /// Configure security relevant options when loading a git configuration.#[derive(Copy, Clone, Ord, PartialOrd, PartialEq, Eq, Debug, Hash)]#[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]pub struct Permissions {    /// How to use the system configuration.    /// This is defined as `$(prefix)/etc/gitconfig` on unix.    pub system: git_sec::Permission,    /// How to use the global configuration.    /// This is usually `~/.gitconfig`.    pub global: git_sec::Permission,    /// How to use the user configuration.    /// Second user-specific configuration path; if `$XDG_CONFIG_HOME` is not    /// set or empty, `$HOME/.config/git/config` will be used.    pub user: git_sec::Permission,    /// How to use the repository configuration.    pub repository: git_sec::Permission,    /// How to use worktree configuration from `config.worktree`.    // TODO: figure out how this really applies and provide more information here.    pub worktree: git_sec::Permission,    /// How to use the configuration from environment variables.    pub env: git_sec::Permission,    /// What to do when include files are encountered in loaded configuration.    pub includes: git_sec::Permission,} #[cfg(test)]pub mod test_util;