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