kittage 0.1.5

Interact with all aspects of the kitty terminal graphics protocol
Documentation 
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

//! Types and functions to facilitate [`crate::action::Action::Delete`]

use std::{io::Write, ops::RangeInclusive};

use crate::{ImageId, ImageNumber, PlacementId};

/// What to delete when using [`crate::action::Action::Delete`]
#[derive(PartialEq, Debug, Clone)]
pub struct DeleteConfig {
	/// Whether to just clear the specified images from the screen ([`ClearOrDelete::Clear`]) or
	/// completely delete them from memory ([`ClearOrDelete::Delete`])
	pub effect: ClearOrDelete,
	/// Specifying exactly how to determine which images to delete
	pub which: WhichToDelete
}

/// Whether to clear the specified images from the screen or completely delete them from memory
#[derive(PartialEq, Debug, Clone, Copy)]
pub enum ClearOrDelete {
	/// just clear them from the screen
	Clear,
	/// clear them from the screen AND delete them from memory
	Delete
}

impl ClearOrDelete {
	/// Make `c` uppercase if `self == Self::Delete`, otherwise keep it the same. This corresponds
	/// with the behavior that kitty expects us to use to specify what to do with the deletions.
	fn maybe_upper(self, c: char) -> char {
		match self {
			Self::Delete => c.to_ascii_uppercase(),
			Self::Clear => c
		}
	}
}

/// An (x, y) index of a specific cell on the terminal (i.e. specific location where a single
/// character could be printed)
#[derive(PartialEq, Debug, Clone)]
pub struct CellLocation {
	/// The x-index
	pub x: u16,
	/// The y-index
	pub y: u16
}

/// A [`CellLocation`] with an associated z-index (such as is used with
/// [`crate::display::DisplayLocation::z_index`])
#[derive(PartialEq, Debug, Clone)]
pub struct CellLocationZ {
	/// The x and y of the location
	pub x_y: CellLocation,
	/// The z-index
	pub z: i32
}

/// A filter to specify exactly which images should be deleted
#[derive(PartialEq, Debug, Clone)]
pub enum WhichToDelete {
	/// Every single visible image (does not include non-visible)
	All,
	/// Only delete those with the specific [`ImageId`]. If a [`PlacementId`] is specified, then
	/// this only deletes images with both the [`ImageId`] AND the [`PlacementId`]
	ImageId(ImageId, Option<PlacementId>),
	/// Only delete those with the specific [`ImageNumber`]. If a [`PlacementId`] is specified, then
	/// this only deletes images with both the [`ImageId`] AND the [`PlacementId`]
	NewestWithNumber(ImageNumber, Option<PlacementId>),
	/// Only delete images which intersect with the cursor's current position
	IntersectingWithCursor,
	/// Delete all animation frames
	AnimationFrames,
	/// Delete all images that intersect at all with the given cell
	PlacementsIntersectingCell(CellLocation),
	/// Delete all images that intersect at all with the given cell (whose location includes a
	/// z-index that also must be matched)
	PlacementsIntersectingCellWithZ(CellLocationZ),
	/// Delete all images whose ids are contained in the given range
	IdRange(RangeInclusive<ImageId>),
	/// Delete all placements that intersect with the given cell column
	PlacementsIntersectingColumn(u16),
	/// Delete all placements that intersect with the given cell row
	PlacementsIntersectingRow(u16),
	/// Delete all placements that intersect with the given z-index
	PlacementsWithZIndex(i32)
}

impl DeleteConfig {
	/// Encode this [`DeleteConfig`] into a string to be sent to kitty to communicate this deletion
	pub(crate) fn write_to<W: Write>(&self, mut w: W) -> std::io::Result<W> {
		let e = self.effect;

		write!(w, ",d=")?;

		match &self.which {
			WhichToDelete::All => write!(w, "{}", e.maybe_upper('a'))?,
			WhichToDelete::ImageId(img_id, placement_id) => {
				write!(w, "{},i={img_id}", e.maybe_upper('i'))?;
				if let Some(p_id) = placement_id {
					write!(w, ",p={p_id}")?;
				}
			}
			WhichToDelete::NewestWithNumber(img_num, placement_id) => {
				write!(w, "{},I={img_num}", e.maybe_upper('n'))?;
				if let Some(p_id) = placement_id {
					write!(w, ",p={p_id}")?;
				}
			}
			WhichToDelete::IntersectingWithCursor => write!(w, "{}", e.maybe_upper('c'))?,
			WhichToDelete::AnimationFrames => write!(w, "{}", e.maybe_upper('f'))?,
			WhichToDelete::PlacementsIntersectingCell(CellLocation { x, y }) =>
				write!(w, "{},x={x},y={y}", e.maybe_upper('p'))?,
			WhichToDelete::PlacementsIntersectingCellWithZ(CellLocationZ {
				x_y: CellLocation { x, y },
				z
			}) => write!(w, "{},x={x},y={y},z={z}", e.maybe_upper('q'))?,
			WhichToDelete::IdRange(range) => write!(
				w,
				"{},x={},y={}",
				e.maybe_upper('r'),
				range.start(),
				range.end()
			)?,
			WhichToDelete::PlacementsIntersectingColumn(col) =>
				write!(w, "{},x={col}", e.maybe_upper('x'))?,
			WhichToDelete::PlacementsIntersectingRow(row) =>
				write!(w, "{},y={row}", e.maybe_upper('y'))?,
			WhichToDelete::PlacementsWithZIndex(z) => write!(w, "{},z={z}", e.maybe_upper('z'))?
		}

		write!(w, "\x1b\\")?;
		Ok(w)
	}
}