@@ -5,7 +5,7 @@ use bstr::{BStr, ByteSlice};
5
5
use gix_hash:: oid;
6
6
7
7
use super :: Cache ;
8
- use crate :: PathOidMapping ;
8
+ use crate :: PathIdMapping ;
9
9
10
10
#[ derive( Clone ) ]
11
11
pub enum State {
@@ -32,6 +32,7 @@ pub enum State {
32
32
}
33
33
34
34
#[ cfg( debug_assertions) ]
35
+ /// debug builds only for use in tests.
35
36
impl Cache {
36
37
pub fn set_case ( & mut self , case : gix_glob:: pattern:: Case ) {
37
38
self . case = case;
@@ -65,32 +66,40 @@ pub struct Platform<'a> {
65
66
is_dir : Option < bool > ,
66
67
}
67
68
69
+ /// Initialization
68
70
impl Cache {
69
- /// Create a new instance with `worktree_root` being the base for all future paths we handle, assuming it to be valid which includes
70
- /// symbolic links to be included in it as well.
71
- /// The `case` configures attribute and exclusion query case sensitivity.
71
+ /// Create a new instance with `worktree_root` being the base for all future paths we match.
72
+ /// `state` defines the capabilities of the cache.
73
+ /// The `case` configures attribute and exclusion case sensitivity at *query time*, which should match the case that
74
+ /// `state` might be configured with.
75
+ /// `buf` is used when reading files, and `id_mappings` should have been created with [State::id_mappings_from_index()].
72
76
pub fn new (
73
77
worktree_root : impl Into < PathBuf > ,
74
78
state : State ,
75
79
case : gix_glob:: pattern:: Case ,
76
80
buf : Vec < u8 > ,
77
- attribute_files_in_index : Vec < PathOidMapping > ,
81
+ id_mappings : Vec < PathIdMapping > ,
78
82
) -> Self {
79
83
let root = worktree_root. into ( ) ;
80
84
Cache {
81
85
stack : gix_fs:: Stack :: new ( root) ,
82
86
state,
83
87
case,
84
88
buf,
85
- attribute_files_in_index ,
89
+ id_mappings ,
86
90
}
87
91
}
92
+ }
88
93
89
- /// Append the `relative` path to the root directory the cache contains and efficiently create leading directories
90
- /// unless `is_dir` is known (`Some(…)`) then `relative` points to a directory itself in which case the entire resulting
94
+ /// Mutable Access
95
+ impl Cache {
96
+ /// Append the `relative` path to the root directory of the cache and efficiently create leading directories, while assuring that no
97
+ /// symlinks are in that path.
98
+ /// Unless `is_dir` is known with `Some(…)`, then `relative` points to a directory itself in which case the entire resulting
91
99
/// path is created as directory. If it's not known it is assumed to be a file.
100
+ /// `find` maybe used to lookup objects from an [id mapping][crate::cache::State::id_mappings_from_index()], with mappnigs
92
101
///
93
- /// Provide access to cached information for that `relative` entry via the platform returned.
102
+ /// Provide access to cached information for that `relative` path via the returned platform .
94
103
pub fn at_path < Find , E > (
95
104
& mut self ,
96
105
relative : impl AsRef < Path > ,
@@ -101,19 +110,27 @@ impl Cache {
101
110
Find : for < ' a > FnMut ( & oid , & ' a mut Vec < u8 > ) -> Result < gix_object:: BlobRef < ' a > , E > ,
102
111
E : std:: error:: Error + Send + Sync + ' static ,
103
112
{
104
- let mut delegate = platform :: StackDelegate {
113
+ let mut delegate = StackDelegate {
105
114
state : & mut self . state ,
106
115
buf : & mut self . buf ,
107
116
is_dir : is_dir. unwrap_or ( false ) ,
108
- attribute_files_in_index : & self . attribute_files_in_index ,
117
+ id_mappings : & self . id_mappings ,
109
118
find,
110
119
} ;
111
120
self . stack . make_relative_path_current ( relative, & mut delegate) ?;
112
121
Ok ( Platform { parent : self , is_dir } )
113
122
}
114
123
115
- /// **Panics** on illformed UTF8 in `relative`
116
- // TODO: more docs
124
+ /// Obtain a platform for lookups from a repo-`relative` path, typically obtained from an index entry. `is_dir` should reflect
125
+ /// whether it's a directory or not, or left at `None` if unknown.
126
+ /// `find` maybe used to lookup objects from an [id mapping][crate::cache::State::id_mappings_from_index()].
127
+ /// All effects are similar to [`at_path()`][Self::at_path()].
128
+ ///
129
+ /// If `relative` ends with `/` and `is_dir` is `None`, it is automatically assumed to be a directory.
130
+ ///
131
+ /// ### Panics
132
+ ///
133
+ /// on illformed UTF8 in `relative`
117
134
pub fn at_entry < ' r , Find , E > (
118
135
& mut self ,
119
136
relative : impl Into < & ' r BStr > ,
@@ -130,10 +147,17 @@ impl Cache {
130
147
self . at_path (
131
148
relative_path,
132
149
is_dir. or_else ( || relative. ends_with_str ( "/" ) . then_some ( true ) ) ,
133
- // is_dir,
134
150
find,
135
151
)
136
152
}
153
+ }
154
+
155
+ /// Access
156
+ impl Cache {
157
+ /// Return the state for introspection.
158
+ pub fn state ( & self ) -> & State {
159
+ & self . state
160
+ }
137
161
138
162
/// Return the base path against which all entries or paths should be relative to when querying.
139
163
///
@@ -143,6 +167,9 @@ impl Cache {
143
167
}
144
168
}
145
169
170
+ mod delegate;
171
+ use delegate:: StackDelegate ;
172
+
146
173
mod platform;
147
174
///
148
175
pub mod state;
0 commit comments