Repository navigation
Expand file tree
/
Copy pathlib.rs
More file actions
177 lines (160 loc) · 6.59 KB
/
Copy pathlib.rs
File metadata and controls
177 lines (160 loc) · 6.59 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
//! A local draft of a value, independent of rendering and the application's undo engine.
//!
//! The host validates proposals and owns all document mutations. Dropping a session cancels
//! only its local draft. Store small parameters here, not a full document per pointer event.
//! A context must include stable document/target identity and a revision that changes on
//! every relevant edit (including undo/redo). Comparing values alone cannot detect ABA edits.
//! Values must be independent snapshots: `Clone` alone does not guarantee isolation if a
//! value shares mutable storage with the host. Equality must cover all relevant fields.
#![no_std]
#![forbid(unsafe_code)]
/// Why a draft cannot be committed to the current host state.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum FinishError {
/// The most recent proposal was rejected. Correct it before finishing.
InvalidProposal,
/// Document, target, selection or relevant revision has changed.
ContextChanged,
/// The live value changed without the context being updated.
ValueChanged,
}
impl core::fmt::Display for FinishError {
fn fmt(&self, formatter: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
formatter.write_str(match self {
Self::InvalidProposal => "the latest proposal is invalid",
Self::ContextChanged => "the edit context has changed",
Self::ValueChanged => "the live value has changed",
})
}
}
impl core::error::Error for FinishError {}
/// A proposed change. The caller must apply it through its existing command engine.
#[derive(Debug, PartialEq, Eq)]
pub struct Change<T> {
/// The snapshot captured when the session began.
pub before: T,
/// The last accepted proposal, to be applied by the host.
pub after: T,
}
/// A single-use edit. It never writes to a document or records history itself.
///
/// This type intentionally does not implement `Clone`. `finish` consumes it, so the same
/// session cannot accidentally emit two commits. A failed finish also consumes the draft;
/// call `check` first if invalid input should remain editable in the UI.
#[must_use = "a draft must be retained, finished, or deliberately cancelled"]
#[derive(Debug)]
pub struct EditSession<T, C> {
original: T,
preview: T,
context: C,
valid: bool,
}
impl<T: Clone, C> EditSession<T, C> {
/// Begin from a value already validated by the application.
///
/// Cloning `original` must produce an independently editable snapshot. Shared mutable
/// pointers such as `Rc<RefCell<_>>` can let edits change the original or live document
/// and defeat cancellation/conflict checks. Use owned fields or immutable shared data.
/// The context must also remain a stable snapshot until the session ends.
pub fn new(original: T, context: C) -> Self {
Self {
preview: original.clone(),
original,
context,
valid: true,
}
}
/// Restore the original preview and clear invalid input, keeping the draft open.
///
/// The original value and context are retained: this does not rebase a stale draft
/// or change the live document. The host must refresh its displayed preview itself.
pub fn reset(&mut self) {
self.preview = self.original.clone();
self.valid = true;
}
}
impl<T, C> EditSession<T, C> {
/// The validated value captured when editing began.
pub fn original(&self) -> &T {
&self.original
}
/// Last valid preview, even when a later incomplete/invalid input is present.
pub fn preview(&self) -> &T {
&self.preview
}
/// The host context captured when editing began; never changed by this session.
pub fn context(&self) -> &C {
&self.context
}
/// Whether the latest proposal was accepted. This does not check live host state.
pub fn is_valid(&self) -> bool {
self.valid
}
/// Accept a host-validated proposal. Errors invalidate commit without replacing the
/// last valid preview. Units, mixed values, finite checks and bounds belong to the host.
pub fn propose<E>(&mut self, proposal: Result<T, E>) -> Result<(), E> {
match proposal {
Ok(value) => {
self.preview = value;
self.valid = true;
Ok(())
}
Err(error) => {
self.valid = false;
Err(error)
}
}
}
/// Discard the local draft. No rollback commands or history entries are generated.
pub fn cancel(self) {}
}
impl<T: PartialEq, C: PartialEq> EditSession<T, C> {
/// Check whether the draft still belongs to the current host state, independently
/// of invalid input. Useful when deciding whether an open editor must be dismissed.
///
/// This never returns `InvalidProposal` and does not authorize a commit. Use `check`
/// or `finish` immediately before applying on the host's serialized command path.
/// Context conflicts take precedence over value conflicts. No lock is acquired.
pub fn check_live(&self, live: &T, context: &C) -> Result<(), FinishError> {
if *context != self.context {
Err(FinishError::ContextChanged)
} else if *live != self.original {
Err(FinishError::ValueChanged)
} else {
Ok(())
}
}
/// Check live host state and proposal validity immediately before applying on the
/// host's serialized command path. Live conflicts take precedence over invalid input.
/// This comparison is not a lock and is not a distributed transaction.
pub fn check(&self, live: &T, context: &C) -> Result<(), FinishError> {
self.check_live(live, context)?;
if !self.valid {
Err(FinishError::InvalidProposal)
} else {
Ok(())
}
}
/// Emit at most one change; a no-op emits none, preserving the host's redo stack.
/// The host still validates and applies the command and handles execution failure.
pub fn finish(self, live: &T, context: &C) -> Result<Option<Change<T>>, FinishError> {
self.check(live, context)?;
if self.original == self.preview {
Ok(None)
} else {
Ok(Some(Change {
before: self.original,
after: self.preview,
}))
}
}
}
/// A session cannot be finished twice.
///
/// ```compile_fail
/// use edit_session::EditSession;
/// let draft = EditSession::new(100, ("document", 7));
/// let _ = draft.finish(&100, &("document", 7));
/// let _ = draft.finish(&100, &("document", 7));
/// ```
const _: () = ();