Compare commits
4 Commits
release-pl
...
main
| Author | SHA1 | Date | |
|---|---|---|---|
|
720303e806 | ||
|
|
5f0331ec89 | ||
|
|
eeed03cba2 | ||
|
|
c3b575e24e |
18
.github/workflows/ci.yml
vendored
18
.github/workflows/ci.yml
vendored
@@ -37,7 +37,7 @@ jobs:
|
||||
toolchain: nightly
|
||||
components: rustfmt
|
||||
- uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
|
||||
- uses: taiki-e/install-action@0e76c5c569f13f7eb21e8e5b26fe710062b57b62 # v2
|
||||
- uses: taiki-e/install-action@3522286d40783523f9c7880e33f785905b4c20d0 # v2
|
||||
with:
|
||||
tool: taplo-cli
|
||||
- run: cargo xtask format --check
|
||||
@@ -51,7 +51,7 @@ jobs:
|
||||
- uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
|
||||
with:
|
||||
persist-credentials: false
|
||||
- uses: crate-ci/typos@5c19779cb52ea50e151f5a10333ccd269227b5ae # master
|
||||
- uses: crate-ci/typos@bb4666ad77b539a6b4ce4eda7ebb6de553704021 # master
|
||||
|
||||
# Check for any disallowed dependencies in the codebase due to license / security issues.
|
||||
# See <https://github.com/EmbarkStudios/cargo-deny>
|
||||
@@ -68,7 +68,7 @@ jobs:
|
||||
- uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
|
||||
with:
|
||||
persist-credentials: false
|
||||
- uses: EmbarkStudios/cargo-deny-action@76cd80eb775d7bbbd2d80292136d74d39e1b4918 # v2
|
||||
- uses: EmbarkStudios/cargo-deny-action@3fd3802e88374d3fe9159b834c7714ec57d6c979 # v2
|
||||
with:
|
||||
rust-toolchain: stable
|
||||
log-level: info
|
||||
@@ -139,7 +139,7 @@ jobs:
|
||||
with:
|
||||
toolchain: stable
|
||||
components: llvm-tools
|
||||
- uses: taiki-e/install-action@0e76c5c569f13f7eb21e8e5b26fe710062b57b62 # v2
|
||||
- uses: taiki-e/install-action@3522286d40783523f9c7880e33f785905b4c20d0 # v2
|
||||
with:
|
||||
tool: cargo-llvm-cov
|
||||
- uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
|
||||
@@ -165,7 +165,7 @@ jobs:
|
||||
- uses: dtolnay/rust-toolchain@f7ccc83f9ed1e5b9c81d8a67d7ad1a747e22a561 # master
|
||||
with:
|
||||
toolchain: ${{ matrix.toolchain }}
|
||||
- uses: taiki-e/install-action@0e76c5c569f13f7eb21e8e5b26fe710062b57b62 # v2
|
||||
- uses: taiki-e/install-action@3522286d40783523f9c7880e33f785905b4c20d0 # v2
|
||||
with:
|
||||
tool: cargo-hack
|
||||
- uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
|
||||
@@ -204,7 +204,7 @@ jobs:
|
||||
with:
|
||||
persist-credentials: false
|
||||
- uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
|
||||
- uses: taiki-e/install-action@0e76c5c569f13f7eb21e8e5b26fe710062b57b62 # v2
|
||||
- uses: taiki-e/install-action@3522286d40783523f9c7880e33f785905b4c20d0 # v2
|
||||
with:
|
||||
tool: cargo-rdme
|
||||
- run: cargo xtask readme --check
|
||||
@@ -226,7 +226,7 @@ jobs:
|
||||
- uses: dtolnay/install@74f735cdf643820234e37ae1c4089a08fd266d8a # master
|
||||
with:
|
||||
crate: cargo-docs-rs
|
||||
- uses: taiki-e/install-action@0e76c5c569f13f7eb21e8e5b26fe710062b57b62 # v2
|
||||
- uses: taiki-e/install-action@3522286d40783523f9c7880e33f785905b4c20d0 # v2
|
||||
with:
|
||||
tool: cargo-hack
|
||||
- uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
|
||||
@@ -244,7 +244,7 @@ jobs:
|
||||
- uses: dtolnay/rust-toolchain@f7ccc83f9ed1e5b9c81d8a67d7ad1a747e22a561 # master
|
||||
with:
|
||||
toolchain: stable
|
||||
- uses: taiki-e/install-action@0e76c5c569f13f7eb21e8e5b26fe710062b57b62 # v2
|
||||
- uses: taiki-e/install-action@3522286d40783523f9c7880e33f785905b4c20d0 # v2
|
||||
with:
|
||||
tool: cargo-hack
|
||||
- uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
|
||||
@@ -265,7 +265,7 @@ jobs:
|
||||
- uses: dtolnay/rust-toolchain@f7ccc83f9ed1e5b9c81d8a67d7ad1a747e22a561 # master
|
||||
with:
|
||||
toolchain: stable
|
||||
- uses: taiki-e/install-action@0e76c5c569f13f7eb21e8e5b26fe710062b57b62 # v2
|
||||
- uses: taiki-e/install-action@3522286d40783523f9c7880e33f785905b4c20d0 # v2
|
||||
with:
|
||||
tool: cargo-hack
|
||||
- uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
|
||||
|
||||
@@ -109,19 +109,28 @@ use crate::layout::{Position, Size};
|
||||
mod test;
|
||||
pub use self::test::TestBackend;
|
||||
|
||||
/// Enum representing the different types of clearing operations that can be performed
|
||||
/// on the terminal screen.
|
||||
/// Defines which region of the terminal's visible display area is cleared.
|
||||
///
|
||||
/// Clearing operates on character cells in the active display surface. It does not move, hide, or
|
||||
/// reset the cursor position. If the cursor lies inside the cleared region, the character cell at
|
||||
/// the cursor position is cleared as well.
|
||||
///
|
||||
/// Clearing applies to the terminal's visible display area, not just content previously drawn by
|
||||
/// Ratatui. No guarantees are made about scrollback, history, or off-screen buffers.
|
||||
#[derive(Debug, Display, EnumString, Clone, Copy, Eq, PartialEq, Hash)]
|
||||
pub enum ClearType {
|
||||
/// Clear the entire screen.
|
||||
/// Clears all character cells in the visible display area.
|
||||
All,
|
||||
/// Clear everything after the cursor.
|
||||
/// Clears all character cells from the cursor position (inclusive) through the end of the
|
||||
/// display area.
|
||||
AfterCursor,
|
||||
/// Clear everything before the cursor.
|
||||
/// Clears all character cells from the start of the display area through the cursor position
|
||||
/// (inclusive).
|
||||
BeforeCursor,
|
||||
/// Clear the current line.
|
||||
/// Clears all character cells in the cursor's current line.
|
||||
CurrentLine,
|
||||
/// Clear everything from the cursor until the next newline.
|
||||
/// Clears all character cells from the cursor position (inclusive) to the end of the current
|
||||
/// line.
|
||||
UntilNewLine,
|
||||
}
|
||||
|
||||
@@ -237,7 +246,14 @@ pub trait Backend {
|
||||
self.set_cursor_position(Position { x, y })
|
||||
}
|
||||
|
||||
/// Clears the whole terminal screen
|
||||
/// Clears all character cells in the terminal's visible display area.
|
||||
///
|
||||
/// This operation preserves the cursor position. If the cursor lies within the cleared
|
||||
/// region, the character cell at the cursor position is cleared. No guarantees are made about
|
||||
/// scrollback, history, or off-screen buffers.
|
||||
///
|
||||
/// This is equivalent to calling [`clear_region`](Self::clear_region) with
|
||||
/// [`ClearType::All`].
|
||||
///
|
||||
/// # Example
|
||||
///
|
||||
@@ -251,7 +267,13 @@ pub trait Backend {
|
||||
/// ```
|
||||
fn clear(&mut self) -> Result<(), Self::Error>;
|
||||
|
||||
/// Clears a specific region of the terminal specified by the [`ClearType`] parameter
|
||||
/// Clears a specific region of the terminal's visible display area, as defined by
|
||||
/// [`ClearType`].
|
||||
///
|
||||
/// This operation preserves the cursor position. If the cursor lies within the cleared
|
||||
/// region, the character cell at the cursor position is cleared. Clearing applies to the
|
||||
/// active display surface only and does not make guarantees about scrollback, history, or
|
||||
/// off-screen buffers.
|
||||
///
|
||||
/// This method is optional and may not be implemented by all backends. The default
|
||||
/// implementation calls [`clear`] if the `clear_type` is [`ClearType::All`] and returns an
|
||||
|
||||
@@ -288,12 +288,12 @@ impl Backend for TestBackend {
|
||||
let region = match clear_type {
|
||||
ClearType::All => return self.clear(),
|
||||
ClearType::AfterCursor => {
|
||||
let index = self.buffer.index_of(self.pos.0, self.pos.1) + 1;
|
||||
let index = self.buffer.index_of(self.pos.0, self.pos.1);
|
||||
&mut self.buffer.content[index..]
|
||||
}
|
||||
ClearType::BeforeCursor => {
|
||||
let index = self.buffer.index_of(self.pos.0, self.pos.1);
|
||||
&mut self.buffer.content[..index]
|
||||
&mut self.buffer.content[..=index]
|
||||
}
|
||||
ClearType::CurrentLine => {
|
||||
let line_start_index = self.buffer.index_of(0, self.pos.1);
|
||||
@@ -633,7 +633,7 @@ mod tests {
|
||||
backend.assert_buffer_lines([
|
||||
"aaaaaaaaaa",
|
||||
"aaaaaaaaaa",
|
||||
"aaaa ",
|
||||
"aaa ",
|
||||
" ",
|
||||
" ",
|
||||
]);
|
||||
@@ -657,7 +657,7 @@ mod tests {
|
||||
" ",
|
||||
" ",
|
||||
" ",
|
||||
" aaaaa",
|
||||
" aaaa",
|
||||
"aaaaaaaaaa",
|
||||
]);
|
||||
}
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
use crate::backend::{Backend, ClearType};
|
||||
use crate::buffer::Buffer;
|
||||
use crate::layout::Position;
|
||||
use crate::buffer::{Buffer, Cell};
|
||||
use crate::layout::{Position, Rect};
|
||||
use crate::terminal::{Frame, Terminal, Viewport};
|
||||
|
||||
impl<B: Backend> Terminal<B> {
|
||||
@@ -101,41 +101,77 @@ impl<B: Backend> Terminal<B> {
|
||||
/// - [`Viewport::Inline`]: clears after the viewport's origin, leaving any content above the
|
||||
/// viewport untouched.
|
||||
///
|
||||
/// Current behavior: for [`Viewport::Inline`], clearing runs from the viewport origin through
|
||||
/// the end of the visible display area, not just the viewport's rectangle. This is an
|
||||
/// implementation detail rather than a contract; do not rely on it.
|
||||
///
|
||||
/// This preserves the cursor position.
|
||||
///
|
||||
/// This also resets the "previous" buffer so the next [`Terminal::flush`] redraws the full
|
||||
/// viewport. [`Terminal::resize`] calls this internally.
|
||||
///
|
||||
/// Implementation note: this uses [`ClearType::AfterCursor`] starting at the viewport origin.
|
||||
pub fn clear(&mut self) -> Result<(), B::Error> {
|
||||
let original_cursor = self.backend.get_cursor_position()?;
|
||||
match self.viewport {
|
||||
Viewport::Fullscreen => self.backend.clear_region(ClearType::All)?,
|
||||
Viewport::Inline(_) => {
|
||||
self.backend
|
||||
.set_cursor_position(self.viewport_area.as_position())?;
|
||||
// TODO: `ClearType::AfterCursor` is exclusive of the cursor cell in `TestBackend`
|
||||
// (and in terminals that interpret this as "after" rather than "from"), which can
|
||||
// leave the viewport origin cell uncleared. Consider switching to a clear that
|
||||
// includes the cursor cell when fixing clear semantics.
|
||||
self.backend.clear_region(ClearType::AfterCursor)?;
|
||||
}
|
||||
Viewport::Fixed(_) => {
|
||||
let area = self.viewport_area;
|
||||
for y in area.top()..area.bottom() {
|
||||
// TODO: Fixed viewports can start at x > 0 and have a limited width. Clearing
|
||||
// from x = 0 clears outside the viewport. Consider clearing only within
|
||||
// `viewport_area` (respecting both x offset and width) when fixing clear
|
||||
// semantics.
|
||||
self.backend.set_cursor_position(Position { x: 0, y })?;
|
||||
// TODO: `ClearType::AfterCursor` is exclusive of the cursor cell in
|
||||
// `TestBackend`, so the first cell of each cleared row can remain. Consider a
|
||||
// clear mode that includes the cursor cell when fixing clear semantics.
|
||||
self.backend.clear_region(ClearType::AfterCursor)?;
|
||||
}
|
||||
self.clear_fixed_viewport(area)?;
|
||||
}
|
||||
}
|
||||
self.backend.set_cursor_position(original_cursor)?;
|
||||
// Reset the back buffer to make sure the next update will redraw everything.
|
||||
self.buffers[1 - self.current].reset();
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Clears a fixed viewport using terminal clear commands when possible.
|
||||
///
|
||||
/// Terminal clear commands can be faster than per-cell updates.
|
||||
fn clear_fixed_viewport(&mut self, area: Rect) -> Result<(), B::Error> {
|
||||
if area.is_empty() {
|
||||
return Ok(());
|
||||
}
|
||||
let size = self.backend.size()?;
|
||||
let is_full_width = area.x == 0 && area.width == size.width;
|
||||
let ends_at_bottom = area.bottom() == size.height;
|
||||
if is_full_width && ends_at_bottom {
|
||||
self.backend.set_cursor_position(area.as_position())?;
|
||||
self.backend.clear_region(ClearType::AfterCursor)?;
|
||||
} else if is_full_width {
|
||||
self.clear_full_width_rows(area)?;
|
||||
} else {
|
||||
self.clear_region_cells(area)?;
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Clears full-width rows using line clear commands.
|
||||
///
|
||||
/// This avoids per-cell writes when the viewport spans the full width.
|
||||
fn clear_full_width_rows(&mut self, area: Rect) -> Result<(), B::Error> {
|
||||
for y in area.top()..area.bottom() {
|
||||
self.backend.set_cursor_position(Position { x: 0, y })?;
|
||||
self.backend.clear_region(ClearType::CurrentLine)?;
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Clears a non-full-width region by writing empty cells directly.
|
||||
///
|
||||
/// This is used when line-based clears would affect cells outside the viewport.
|
||||
fn clear_region_cells(&mut self, area: Rect) -> Result<(), B::Error> {
|
||||
let clear_cell = Cell::default();
|
||||
let updates = area.positions().map(|pos| (pos.x, pos.y, &clear_cell));
|
||||
self.backend.draw(updates)?;
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
@@ -222,83 +258,123 @@ mod tests {
|
||||
|
||||
#[test]
|
||||
fn clear_inline_clears_after_viewport_origin_and_resets_back_buffer() {
|
||||
// Characterization test:
|
||||
// The current implementation clears using ClearType::AfterCursor, which is exclusive of
|
||||
// the cursor cell. This yields somewhat surprising results (the origin cell is left
|
||||
// untouched). We'll fix the clear semantics later; this test locks down current behavior.
|
||||
//
|
||||
// Inline clear is implemented as:
|
||||
// 1) move the backend cursor to the viewport origin
|
||||
// 2) call ClearType::AfterCursor once
|
||||
//
|
||||
// Note: TestBackend's ClearType::AfterCursor clears *after the cursor position*, keeping
|
||||
// the cell at the cursor intact, and clears through the end of the screen buffer.
|
||||
let mut backend = TestBackend::with_lines(["aaa", "bbb", "ccc"]);
|
||||
backend.set_cursor_position((0, 1)).unwrap();
|
||||
let mut terminal = Terminal::with_options(
|
||||
backend,
|
||||
TerminalOptions {
|
||||
viewport: Viewport::Inline(1),
|
||||
},
|
||||
)
|
||||
.unwrap();
|
||||
let mut backend = TestBackend::with_lines([
|
||||
"before 1 ",
|
||||
"before 2 ",
|
||||
"viewport 1",
|
||||
"viewport 2",
|
||||
"after 1 ",
|
||||
"after 2 ",
|
||||
]);
|
||||
backend
|
||||
.set_cursor_position(Position { x: 2, y: 2 })
|
||||
.unwrap();
|
||||
let options = TerminalOptions {
|
||||
viewport: Viewport::Inline(2),
|
||||
};
|
||||
let mut terminal = Terminal::with_options(backend, options).unwrap();
|
||||
terminal
|
||||
.backend_mut()
|
||||
.set_cursor_position(Position { x: 2, y: 2 })
|
||||
.unwrap();
|
||||
|
||||
terminal.buffers[1][(2, 1)] = Cell::new("x");
|
||||
terminal.buffers[1][(2, 2)] = Cell::new("x");
|
||||
terminal.clear().unwrap();
|
||||
|
||||
terminal
|
||||
.backend()
|
||||
.assert_buffer_lines(["aaa", "b ", " "]);
|
||||
// Inline viewport is anchored to the cursor row (y = 2) with height 2. Clear runs from
|
||||
// the viewport origin through the end of the display, including the rows after it.
|
||||
terminal.backend().assert_buffer_lines([
|
||||
"before 1 ",
|
||||
"before 2 ",
|
||||
" ",
|
||||
" ",
|
||||
" ",
|
||||
" ",
|
||||
]);
|
||||
assert_eq!(
|
||||
terminal.buffers[1 - terminal.current],
|
||||
Buffer::empty(terminal.viewport_area)
|
||||
);
|
||||
// The inline branch also explicitly sets the cursor to the viewport origin before
|
||||
// clearing, so the backend cursor ends up at that origin.
|
||||
assert_eq!(
|
||||
terminal.backend().cursor_position(),
|
||||
Position { x: 0, y: 1 }
|
||||
Position { x: 2, y: 2 }
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn clear_fixed_clears_viewport_rows_and_resets_back_buffer() {
|
||||
// Characterization test:
|
||||
// The current implementation clears using ClearType::AfterCursor, which is exclusive of
|
||||
// the cursor cell. This yields somewhat surprising results (each row's first cell is left
|
||||
// untouched, and TestBackend clears through the end of the screen). We'll fix the clear
|
||||
// semantics later; this test locks down current behavior.
|
||||
//
|
||||
// Fixed clear is implemented as: for each viewport row, set the cursor to the start of
|
||||
// the row (x = 0) and call ClearType::AfterCursor.
|
||||
//
|
||||
// Note: TestBackend's ClearType::AfterCursor clears from *after the cursor* through the
|
||||
// end of the screen buffer (not just the current line). That means the first iteration
|
||||
// clears everything below the viewport's first row too.
|
||||
let backend = TestBackend::with_lines(["aaa", "bbb", "ccc"]);
|
||||
let mut terminal = Terminal::with_options(
|
||||
backend,
|
||||
TerminalOptions {
|
||||
viewport: Viewport::Fixed(Rect::new(0, 1, 3, 2)),
|
||||
},
|
||||
)
|
||||
.unwrap();
|
||||
// For full-width fixed viewports that reach the terminal bottom, clear uses
|
||||
// ClearType::AfterCursor starting at the viewport origin.
|
||||
let mut backend = TestBackend::with_lines(["before 1 ", "viewport 1", "viewport 2"]);
|
||||
backend.set_cursor_position((2, 0)).unwrap();
|
||||
let options = TerminalOptions {
|
||||
viewport: Viewport::Fixed(Rect::new(0, 1, 10, 2)),
|
||||
};
|
||||
let mut terminal = Terminal::with_options(backend, options).unwrap();
|
||||
|
||||
terminal.buffers[1][(2, 1)] = Cell::new("x");
|
||||
terminal.clear().unwrap();
|
||||
|
||||
terminal
|
||||
.backend()
|
||||
.assert_buffer_lines(["aaa", "b ", " "]);
|
||||
.assert_buffer_lines(["before 1 ", " ", " "]);
|
||||
assert_eq!(
|
||||
terminal.buffers[1 - terminal.current],
|
||||
Buffer::empty(terminal.viewport_area)
|
||||
);
|
||||
// The fixed branch sets the cursor for each row it processes; after the loop, the cursor
|
||||
// is left at the start of the last processed row.
|
||||
assert_eq!(
|
||||
terminal.backend().cursor_position(),
|
||||
Position { x: 0, y: 2 }
|
||||
Position { x: 2, y: 0 }
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn clear_fixed_full_width_not_at_bottom() {
|
||||
let mut backend =
|
||||
TestBackend::with_lines(["before 1 ", "viewport 1", "viewport 2", "after 1 "]);
|
||||
backend.set_cursor_position((1, 0)).unwrap();
|
||||
let options = TerminalOptions {
|
||||
viewport: Viewport::Fixed(Rect::new(0, 1, 10, 2)),
|
||||
};
|
||||
let mut terminal = Terminal::with_options(backend, options).unwrap();
|
||||
|
||||
terminal.clear().unwrap();
|
||||
|
||||
terminal.backend().assert_buffer_lines([
|
||||
"before 1 ",
|
||||
" ",
|
||||
" ",
|
||||
"after 1 ",
|
||||
]);
|
||||
assert_eq!(
|
||||
terminal.backend().cursor_position(),
|
||||
Position { x: 1, y: 0 }
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn clear_fixed_respects_non_full_width_viewport() {
|
||||
let mut backend =
|
||||
TestBackend::with_lines(["before 1 ", "viewport 1", "viewport 2", "after 1 "]);
|
||||
backend.set_cursor_position((3, 0)).unwrap();
|
||||
let options = TerminalOptions {
|
||||
viewport: Viewport::Fixed(Rect::new(1, 1, 3, 2)),
|
||||
};
|
||||
let mut terminal = Terminal::with_options(backend, options).unwrap();
|
||||
|
||||
terminal.clear().unwrap();
|
||||
|
||||
terminal.backend().assert_buffer_lines([
|
||||
"before 1 ",
|
||||
"v port 1",
|
||||
"v port 2",
|
||||
"after 1 ",
|
||||
]);
|
||||
assert_eq!(
|
||||
terminal.backend().cursor_position(),
|
||||
Position { x: 3, y: 0 }
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -572,7 +572,7 @@ mod tests {
|
||||
"1111111111",
|
||||
"2222222222",
|
||||
"INSERTLINE",
|
||||
"4 ",
|
||||
" ",
|
||||
" ",
|
||||
" ",
|
||||
" ",
|
||||
@@ -639,7 +639,7 @@ mod tests {
|
||||
"5555555555",
|
||||
"INSERTED1 ",
|
||||
"INSERTED2 ",
|
||||
"8 ",
|
||||
" ",
|
||||
" ",
|
||||
" ",
|
||||
" ",
|
||||
|
||||
Reference in New Issue
Block a user