Skip to main content

max / makeover-layout

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