gix_attributes/
lib.rs

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

gix_attributes/
lib.rs
