vendor/gix-attributes/src/lib.rs

   1 //! Parse `.gitattribute` files and provide utilities to match against them.
   2 //!
   3 //! ## Feature Flags
   4 #![cfg_attr(
   5     feature = "document-features",
   6     cfg_attr(doc, doc = ::document_features::document_features!())
   7 )]
   8 #![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
   9 #![deny(missing_docs, rust_2018_idioms, unsafe_code)]
  10
  11 pub use gix_glob as glob;
  12 use kstring::{KString, KStringRef};
  13
  14 mod assignment;
  15 ///
  16 pub mod name;
  17 ///
  18 pub mod state;
  19
  20 ///
  21 pub mod search;
  22
  23 ///
  24 pub mod parse;
  25
  26 /// Parse attribute assignments line by line from `bytes`, and fail the operation on error.
  27 ///
  28 /// For leniency, ignore errors using `filter_map(Result::ok)` for example.
  29 pub fn parse(bytes: &[u8]) -> parse::Lines<'_> {
  30     parse::Lines::new(bytes)
  31 }
  32
  33 /// The state an attribute can be in, referencing the value.
  34 ///
  35 /// Note that this doesn't contain the name.
  36 #[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone, Copy)]
  37 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
  38 pub enum StateRef<'a> {
  39     /// The attribute is listed, or has the special value 'true'
  40     Set,
  41     /// The attribute has the special value 'false', or was prefixed with a `-` sign.
  42     Unset,
  43     /// The attribute is set to the given value, which followed the `=` sign.
  44     /// Note that values can be empty.
  45     #[cfg_attr(feature = "serde", serde(borrow))]
  46     Value(state::ValueRef<'a>),
  47     /// The attribute isn't mentioned with a given path or is explicitly set to `Unspecified` using the `!` sign.
  48     Unspecified,
  49 }
  50
  51 /// The state an attribute can be in, owning the value.
  52 ///
  53 /// Note that this doesn't contain the name.
  54 #[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone)]
  55 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
  56 pub enum State {
  57     /// The attribute is listed, or has the special value 'true'
  58     Set,
  59     /// The attribute has the special value 'false', or was prefixed with a `-` sign.
  60     Unset,
  61     /// The attribute is set to the given value, which followed the `=` sign.
  62     /// Note that values can be empty.
  63     Value(state::Value),
  64     /// The attribute isn't mentioned with a given path or is explicitly set to `Unspecified` using the `!` sign.
  65     Unspecified,
  66 }
  67
  68 /// Represents a validated attribute name
  69 #[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone)]
  70 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
  71 pub struct Name(pub(crate) KString);
  72
  73 /// Holds a validated attribute name as a reference
  74 #[derive(Copy, Clone, PartialEq, Eq, Debug, Hash, Ord, PartialOrd)]
  75 pub struct NameRef<'a>(KStringRef<'a>);
  76
  77 /// Name an attribute and describe it's assigned state.
  78 #[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone)]
  79 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
  80 pub struct Assignment {
  81     /// The validated name of the attribute.
  82     pub name: Name,
  83     /// The state of the attribute.
  84     pub state: State,
  85 }
  86
  87 /// Holds validated attribute data as a reference
  88 #[derive(Copy, Clone, PartialEq, Eq, Debug, Hash, Ord, PartialOrd)]
  89 pub struct AssignmentRef<'a> {
  90     /// The name of the attribute.
  91     pub name: NameRef<'a>,
  92     /// The state of the attribute.
  93     pub state: StateRef<'a>,
  94 }
  95
  96 /// A grouping of lists of patterns while possibly keeping associated to their base path in order to find matches.
  97 ///
  98 /// Pattern lists with base path are queryable relative to that base, otherwise they are relative to the repository root.
  99 #[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone, Default)]
 100 pub struct Search {
 101     /// A list of pattern lists, each representing a patterns from a file or specified by hand, in the order they were
 102     /// specified in.
 103     ///
 104     /// When matching, this order is reversed.
 105     patterns: Vec<gix_glob::search::pattern::List<search::Attributes>>,
 106 }
 107
 108 /// A list of known global sources for git attribute files in order of ascending precedence.
 109 ///
 110 /// This means that values from the first variant will be returned first.
 111 #[derive(Clone, Copy, Debug, Eq, PartialEq, Hash, Ord, PartialOrd)]
 112 pub enum Source {
 113     /// The attribute file that the installation itself ships with.
 114     GitInstallation,
 115     /// System-wide attributes file. This is typically defined as
 116     /// `$(prefix)/etc/gitattributes` (where prefix is the git-installation directory).
 117     System,
 118     /// This is `<xdg-config-home>/git/attributes` and is git application configuration per user.
 119     ///
 120     /// Note that there is no `~/.gitattributes` file.
 121     Git,
 122     /// The configuration of the repository itself, located in `$GIT_DIR/info/attributes`.
 123     Local,
 124 }
 125
 126 mod source;