makeover_layout/text.rs
1use crate::Intent;
2
3// Names this module's prose links to, resolved for rustdoc.
4#[allow(unused_imports)]
5use crate::Column;
6
7/// What a run of source code is, once something has classified it.
8///
9/// The description carries the classification and never the source. An app that browses
10/// source already has a lexer; a renderer does not and should not grow one, and
11/// three renderers each growing their own would disagree about the same file.
12///
13/// # Why the app classifies and the renderer colours
14///
15/// Measured on MNW's source browser, which is the only consumer in the tree.
16/// It highlights server-side with syntect and had already reduced syntect's
17/// scope space to seven colours held fixed across all 31 themes, because a
18/// reader recognises a highlighting palette and re-tinting it per theme costs
19/// that recognition to gain nothing. So the classification existed on the app
20/// side already: the only question was whether to throw it away at the seam and
21/// have each renderer redo it. This is the answer.
22///
23/// The precedent is `docengine`'s `Emphasis`, which crosses the same seam the
24/// same way: `quasi-tui` maps its four flags onto terminal modifiers, a webview
25/// maps them onto elements, and neither parses markdown to do it.
26///
27/// # The eight, and why these eight
28///
29/// The seven MNW's palette fixes, plus [`Plain`](Self::Plain) for a run nothing
30/// claimed. `Plain` is not an absence: a lexer that ran and found ordinary code
31/// is saying something a renderer wants, and an `Option<Syntax>` would have made
32/// "unclassified" and "not classified yet" one value.
33///
34/// `#[non_exhaustive]` from the first commit, deliberately. A ninth class is the
35/// obvious next request and it must not be a breaking release across three
36/// renderers and five apps.
37///
38/// # What it is not
39///
40/// A token type in a grammar. These are display classes, coarse on purpose:
41/// the distinctions a reader uses at a glance, not the ones a parser makes.
42/// A renderer wanting more has `language` on the node beside this and may do
43/// whatever it likes with it.
44#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
45#[non_exhaustive]
46pub enum Syntax {
47 /// Ordinary code nothing else claimed.
48 ///
49 /// The default, and a real answer rather than a missing one. See the type's
50 /// docs for why this is not an `Option`.
51 #[default]
52 Plain,
53 /// A language keyword, and the storage and modifier words with it.
54 Keyword,
55 /// A string or character literal.
56 String,
57 /// A comment.
58 Comment,
59 /// A literal that is not a string: a number, a boolean, a constant name.
60 Constant,
61 /// A name being defined: a function, a type, a module.
62 Entity,
63 /// A name being used: a variable, a parameter, a field.
64 Variable,
65 /// Something the language or its library provides rather than this file.
66 Support,
67}
68
69impl Syntax {
70 /// The stable lowercase name, for a renderer keying its own palette off it.
71 ///
72 /// Named here rather than agreed between each renderer and each host, for
73 /// the reason every other spelling in this crate is: that is how one
74 /// renderer ends up calling it `str` and the next `string`, and a theme
75 /// written against one stops working under the other.
76 ///
77 /// Not an [`Intent`] token, and the difference is worth stating. An intent
78 /// resolves against a `makeover` theme token, and there are none for syntax
79 /// colours: a highlighting palette is deliberately outside the theme, held
80 /// fixed while everything around it changes. So this is a name a renderer
81 /// maps however it can, and a renderer with no colours to spend maps every
82 /// one of them onto the same face and is not wrong.
83 #[must_use]
84 pub const fn name(self) -> &'static str {
85 match self {
86 Self::Plain => "plain",
87 Self::Keyword => "keyword",
88 Self::String => "string",
89 Self::Comment => "comment",
90 Self::Constant => "constant",
91 Self::Entity => "entity",
92 Self::Variable => "variable",
93 Self::Support => "support",
94 // Exhaustive rather than wildcarded, which is `State`'s rule one
95 // type up: within this crate `#[non_exhaustive]` does not apply, so
96 // a class added here has to be given a spelling rather than
97 // inheriting "plain" in silence. Consumers outside the crate take
98 // the wildcard, and for them "plain" is the right degradation.
99 }
100 }
101}
102
103/// What one line of a diff is: added, removed, or neither.
104///
105/// The other half of that rule. A diff is a table of lines and the
106/// only thing the vocabulary was missing was a way for a line to say which side
107/// of the change it is on, so this rides on [`Column`] rather than arriving as a
108/// `Node::Diff` carrying git's data model.
109///
110/// # Why three and not two
111///
112/// [`Context`](Self::Context) is a line that did not change, and it is most of
113/// a diff. Said as `Option<Change>` with `None` for context, a renderer could
114/// not tell an unchanged line from a line nobody marked, which is the same
115/// argument [`Syntax::Plain`] makes one type up.
116///
117/// `#[non_exhaustive]` for [`Syntax`]'s reason. A fourth kind (a moved line, a
118/// conflict side) is a plausible request and must not be a breaking release.
119#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
120#[non_exhaustive]
121pub enum Change {
122 /// The line is in both sides and did not change.
123 #[default]
124 Context,
125 /// The line is only in the new side.
126 Added,
127 /// The line is only in the old side.
128 Removed,
129}
130
131impl Intent for Change {
132 fn token(self) -> &'static str {
133 match self {
134 // The status axis, reused rather than given a palette of its own.
135 // A diff's green and red mean exactly what success and danger mean
136 // everywhere else in the system, and an app that wants them held
137 // fixed across themes says so in its own sheet, which is what MNW's
138 // `--diff-add` / `--diff-del` pair already does.
139 Self::Added => "success",
140 Self::Removed => "danger",
141 // Context is the bulk of a diff and is ordinary content. Muting it
142 // would be the axis deciding that unchanged lines are less worth
143 // reading, which is a renderer's call about a particular view.
144 //
145 // Exhaustive for `Syntax::name`'s reason: a fourth kind must answer
146 // this rather than inherit an answer.
147 Self::Context => "content",
148 }
149 }
150}