@@ -4,48 +4,50 @@ use regex::Regex;
44use std::num::NonZeroUsize;
55use std::time::{Duration, Instant};
66
7−// Stores the history of changes to a buffer.
8−//
9−// Currently the history is represented as a vector of revisions. The vector
10−// always has at least one element: the empty root revision. Each revision
11−// with the exception of the root has a parent revision, a [Transaction]
12−// that can be applied to its parent to transition from the parent to itself,
13−// and an inversion of that transaction to transition from the parent to its
14−// latest child.
15−//
16−// When using `u` to undo a change, an inverse of the stored transaction will
17−// be applied which will transition the buffer to the parent state.
18−//
19−// Each revision with the exception of the last in the vector also has a
20−// last child revision. When using `U` to redo a change, the last child transaction
21−// will be applied to the current state of the buffer.
22−//
23−// The current revision is the one currently displayed in the buffer.
24−//
25−// Commiting a new revision to the history will update the last child of the
26−// current revision, and push a new revision to the end of the vector.
27−//
28−// Revisions are commited with a timestamp. :earlier and :later can be used
29−// to jump to the closest revision to a moment in time relative to the timestamp
30−// of the current revision plus (:later) or minus (:earlier) the duration
31−// given to the command. If a single integer is given, the editor will instead
32−// jump the given number of revisions in the vector.
33−//
34−// Limitations:
35−// * Changes in selections currently don't commit history changes. The selection
36−// will only be updated to the state after a commited buffer change.
37−// * The vector of history revisions is currently unbounded. This might
38−// cause the memory consumption to grow significantly large during long
39−// editing sessions.
40−// * Because delete transactions currently don't store the text that they
41−// delete, we also store an inversion of the transaction.
7+/// Stores the history of changes to a buffer.
8+///
9+/// Currently the history is represented as a vector of revisions. The vector
10+/// always has at least one element: the empty root revision. Each revision
11+/// with the exception of the root has a parent revision, a [Transaction]
12+/// that can be applied to its parent to transition from the parent to itself,
13+/// and an inversion of that transaction to transition from the parent to its
14+/// latest child.
15+///
16+/// When using `u` to undo a change, an inverse of the stored transaction will
17+/// be applied which will transition the buffer to the parent state.
18+///
19+/// Each revision with the exception of the last in the vector also has a
20+/// last child revision. When using `U` to redo a change, the last child transaction
21+/// will be applied to the current state of the buffer.
22+///
23+/// The current revision is the one currently displayed in the buffer.
24+///
25+/// Commiting a new revision to the history will update the last child of the
26+/// current revision, and push a new revision to the end of the vector.
27+///
28+/// Revisions are commited with a timestamp. :earlier and :later can be used
29+/// to jump to the closest revision to a moment in time relative to the timestamp
30+/// of the current revision plus (:later) or minus (:earlier) the duration
31+/// given to the command. If a single integer is given, the editor will instead
32+/// jump the given number of revisions in the vector.
33+///
34+/// Limitations:
35+/// * Changes in selections currently don't commit history changes. The selection
36+/// will only be updated to the state after a commited buffer change.
37+/// * The vector of history revisions is currently unbounded. This might
38+/// cause the memory consumption to grow significantly large during long
39+/// editing sessions.
40+/// * Because delete transactions currently don't store the text that they
41+/// delete, we also store an inversion of the transaction.
42+///
43+/// Using time to navigate the history: https://github.com/helix-editor/helix/pull/194
4244#[derive(Debug)]
4345pub struct History {
4446 revisions: Vec<Revision>,
4547 current: usize,
4648}
4749
48−// A single point in history. See [History] for more information.
50+/// A single point in history. See [History] for more information.
4951#[derive(Debug)]
5052struct Revision {
5153 parent: usize,
@@ -111,6 +113,7 @@ impl History {
111113 self.current == 0
112114 }
113115
116+ /// Undo the last edit.
114117 pub fn undo(&mut self) -> Option<&Transaction> {
115118 if self.at_root() {
116119 return None;
@@ -121,6 +124,7 @@ impl History {
121124 Some(¤t_revision.inversion)
122125 }
123126
127+ /// Redo the last edit.
124128 pub fn redo(&mut self) -> Option<&Transaction> {
125129 let current_revision = &self.revisions[self.current];
126130 let last_child = current_revision.last_child?;
@@ -147,8 +151,8 @@ impl History {
147151 }
148152 }
149153
150− // List of nodes on the way from `n` to 'a`. Doesn`t include `a`.
151− // Includes `n` unless `a == n`. `a` must be an ancestor of `n`.
154+ /// List of nodes on the way from `n` to 'a`. Doesn`t include `a`.
155+ /// Includes `n` unless `a == n`. `a` must be an ancestor of `n`.
152156 fn path_up(&self, mut n: usize, a: usize) -> Vec<usize> {
153157 let mut path = Vec::new();
154158 while n != a {
@@ -158,6 +162,7 @@ impl History {
158162 path
159163 }
160164
165+ /// Create a [`Transaction`] that will jump to a specific revision in the history.
161166 fn jump_to(&mut self, to: usize) -> Vec<Transaction> {
162167 let lca = self.lowest_common_ancestor(self.current, to);
163168 let up = self.path_up(self.current, lca);
@@ -171,10 +176,12 @@ impl History {
171176 up_txns.chain(down_txns).collect()
172177 }
173178
179+ /// Creates a [`Transaction`] that will undo `delta` revisions.
174180 fn jump_backward(&mut self, delta: usize) -> Vec<Transaction> {
175181 self.jump_to(self.current.saturating_sub(delta))
176182 }
177183
184+ /// Creates a [`Transaction`] that will redo `delta` revisions.
178185 fn jump_forward(&mut self, delta: usize) -> Vec<Transaction> {
179186 self.jump_to(
180187 self.current
@@ -183,7 +190,7 @@ impl History {
183190 )
184191 }
185192
186− // Helper for a binary search case below.
193+ /// Helper for a binary search case below.
187194 fn revision_closer_to_instant(&self, i: usize, instant: Instant) -> usize {
188195 let dur_im1 = instant.duration_since(self.revisions[i - 1].timestamp);
189196 let dur_i = self.revisions[i].timestamp.duration_since(instant);
@@ -194,6 +201,8 @@ impl History {
194201 }
195202 }
196203
204+ /// Creates a [`Transaction`] that will match a revision created at around
205+ /// `instant`.
197206 fn jump_instant(&mut self, instant: Instant) -> Vec<Transaction> {
198207 let search_result = self
199208 .revisions
@@ -209,6 +218,8 @@ impl History {
209218 self.jump_to(revision)
210219 }
211220
221+ /// Creates a [`Transaction`] that will match a revision created `duration` ago
222+ /// from the timestamp of current revision.
212223 fn jump_duration_backward(&mut self, duration: Duration) -> Vec<Transaction> {
213224 match self.revisions[self.current].timestamp.checked_sub(duration) {
214225 Some(instant) => self.jump_instant(instant),
@@ -216,6 +227,8 @@ impl History {
216227 }
217228 }
218229
230+ /// Creates a [`Transaction`] that will match a revision created `duration` in
231+ /// the future from the timestamp of the current revision.
219232 fn jump_duration_forward(&mut self, duration: Duration) -> Vec<Transaction> {
220233 match self.revisions[self.current].timestamp.checked_add(duration) {
221234 Some(instant) => self.jump_instant(instant),
@@ -223,6 +236,7 @@ impl History {
223236 }
224237 }
225238
239+ /// Creates an undo [`Transaction`].
226240 pub fn earlier(&mut self, uk: UndoKind) -> Vec<Transaction> {
227241 use UndoKind::*;
228242 match uk {
@@ -231,6 +245,7 @@ impl History {
231245 }
232246 }
233247
248+ /// Creates a redo [`Transaction`].
234249 pub fn later(&mut self, uk: UndoKind) -> Vec<Transaction> {
235250 use UndoKind::*;
236251 match uk {
@@ -240,13 +255,14 @@ impl History {
240255 }
241256}
242257
258+/// Whether to undo by a number of edits or a duration of time.
243259#[derive(Debug, PartialEq)]
244260pub enum UndoKind {
245261 Steps(usize),
246262 TimePeriod(std::time::Duration),
247263}
248264
249−// A subset of sytemd.time time span syntax units.
265+/// A subset of sytemd.time time span syntax units.
250266const TIME_UNITS: &[(&[&str], &str, u64)] = &[
251267 (&["seconds", "second", "sec", "s"], "seconds", 1),
252268 (&["minutes", "minute", "min", "m"], "minutes", 60),
@@ -254,11 +270,20 @@ const TIME_UNITS: &[(&[&str], &str, u64)] = &[
254270 (&["days", "day", "d"], "days", 24 * 60 * 60),
255271];
256272
273+/// Checks if the duration input can be turned into a valid duration. It must be a
274+/// positive integer and denote the [unit of time.](`TIME_UNITS`)
275+/// Examples of valid durations:
276+/// * `5 sec`
277+/// * `5 min`
278+/// * `5 hr`
279+/// * `5 days`
257280static DURATION_VALIDATION_REGEX: Lazy<Regex> =
258281 Lazy::new(|| Regex::new(r"^(?:\d+\s*[a-z]+\s*)+$").unwrap());
259282
283+/// Captures both the number and unit as separate capture groups.
260284static NUMBER_UNIT_REGEX: Lazy<Regex> = Lazy::new(|| Regex::new(r"(\d+)\s*([a-z]+)").unwrap());
261285
286+/// Parse a string (e.g. "5 sec") and try to convert it into a [`Duration`].
262287fn parse_human_duration(s: &str) -> Result<Duration, String> {
263288 if !DURATION_VALIDATION_REGEX.is_match(s) {
264289 return Err("duration should be composed \