add_ed/io/
mod.rs

1//! Defines IO Trait, LocalIO (if enabled) and some testing implementations.
2//!
3//! Used to abstract filesystem and shell interactions.
4
5type Result<T> = core::result::Result<T, crate::error::IOError>;
6
7use crate::UILock;
8use crate::LinesIter;
9
10pub mod fake_io;
11pub mod dummy_io;
12
13#[cfg(feature = "local_io")]
14pub mod local_io;
15#[cfg(feature = "local_io")]
16pub use local_io::LocalIO;
17
18/// Trait that abstracts file interactions and running shell commands
19///
20/// Intended to allow modifying how and where system interactions occur.
21/// Example cases for replacing this:
22/// - Dummy IO to prevent filesystem modifications while testing.
23/// - SSH forwarding to save to remote system and run commands remotely.
24/// - Restricted IO to forbid command running and restrict file paths.
25pub trait IO {
26  /// Run a lone command (unrelated from the buffer)
27  ///
28  /// Stdin, Stdout and Stderr passed through to UI
29  fn run_command(&mut self,
30    // UI handle. Created by setting up the UI for passing through
31    // std-in/-out/-err to the child process.
32    ui: &mut UILock,
33    // Command string from user (with basic substitutions interpreted)
34    command: String,
35  ) -> Result<()>;
36
37  /// Run a read command, collecting stdout to add into buffer
38  ///
39  /// Stdin and Stderr should be passed through to UI
40  ///
41  /// The returned string will be split into lines and added into the buffer.
42  /// All line endings are converted into '\n' when adding into the buffer.
43  fn run_read_command(&mut self,
44    // UI handle. Created by setting up the UI for passing through
45    // std-in/-err to child process.
46    ui: &mut UILock,
47    // Command string from user (with basic substitutions interpreted)
48    command: String,
49  ) -> Result<String>;
50
51  /// Run a write command, receiving part of buffer via stdin
52  ///
53  /// Stdout and Stderr should be passed through to UI
54  /// Returns number of bytes written
55  ///
56  /// The LinesIter contains string slices over '\n' terminated lines. If you
57  /// with to use "\r\n" line endings in the command input this should be
58  /// handled in the IO implementation.
59  fn run_write_command(&mut self,
60    // UI handle. Created by setting up the UI for passing through std-in/-err
61    // to child process.
62    ui: &mut UILock,
63    // Command string from user (with basic substitutions interpreted)
64    command: String,
65    // Iterator over string slices to send over stdin
66    input: LinesIter,
67  ) -> Result<usize>;
68
69  /// Run a transform command, taking part of buffer via stdin and returning it
70  /// via stdout.
71  ///
72  /// Stderr should be passed through to UI
73  ///
74  /// The LinesIter contains string slices over '\n' terminated lines. If you
75  /// with to use "\r\n" line endings in the command input this should be
76  /// handled in the IO implementation.
77  ///
78  /// The returned string will be split into lines and added into the buffer.
79  /// All line endings are converted into '\n' when adding into the buffer.
80  fn run_transform_command(&mut self,
81    // UI handle. Created by setting up the UI for passing through
82    // std-in/-out/-err to child process.
83    ui: &mut UILock,
84    // Command string from user (with basic substitutions interpreted)
85    command: String,
86    // Iterator over string slices to send over stdin
87    input: LinesIter,
88  ) -> Result<String>;
89
90  /// Normal file write
91  ///
92  /// Returns number of bytes written
93  ///
94  /// The LinesIter contains string slices over '\n' terminated lines. If you
95  /// with to write "\r\n" line endings into the file this should be handled in
96  /// the IO implementation.
97  fn write_file(&mut self,
98    // Path to file as give by user. Not checked beyond shell escape parsing
99    path: &str,
100    // If appending
101    append: bool,
102    // Data to write to file
103    data: LinesIter,
104  ) -> Result<usize>;
105
106  /// Normal file read
107  ///
108  /// The returned string will be split into lines and added into the buffer.
109  /// All line endings are converted into '\n' when adding into the buffer.
110  fn read_file(&mut self,
111    // Path to file as given by user. Not checked beyond shell escape parsing
112    path: &str,
113    // If true the method should error if no file is found at path
114    must_exist: bool,
115  ) -> Result<String>;
116}
add_ed/io/mod.rs

add_ed/io/
mod.rs
