assembler/glyph.rs
1//! Implement the `@...@` constructs in the source code.
2//!
3//! We use `@...@` to represent the characters that ther TX-2 supports
4//! but which Unicode does not. For example, `@sub_A@` which
5//! represents a subscripted letter A.
6//!
7//! We use the word "glyph" to denote the characters in the source
8//! code. This includes spacing characters (Tab, Backspace, Space but
9//! not carriage return) but not shift codes (COLOR BLACK, SUPER,
10//! NORMAL, SUB, COLOR RED) or special keys which would not appear in
11//! source code (WORD EXAM, LINE FEED DOWN, LINE FEED UP, LOWER CASE,
12//! UPPER CASE, STOP).
13//!
14//! We also do not include the NULLIFY character. This would
15//! certainly have been used in the input to the TX-2 assembler ("M4")
16//! to indicate that a character on the paper tape was deleted (but
17//! punching out all the holes, setting all the bits to 1). But this
18//! would have no role in the preparation of source code on a modern
19//! computer system (e.g. with a text editor) so we don't currently
20//! support this in the input.
21//!
22//! Due to the complexities of lexing and representing the TX-2's compound characters
23//! (see for example [section 6-2.3 of the Users Handbook, "RULES FOR SYMEX FORMATION"](https://archive.org/details/tx-2-users-handbook-nov-63/page/n158/mode/1up)) we might later include additinal glyphs to represent compound characters.
24//!
25//! The [`base::charset`] module deals with similar things, but this
26//! module deals with concerns that are unique to the assembler itself
27//! (that is, concerns which are not relevant to the implementation of
28//! the TX-2 emulator).
29use std::collections::HashMap;
30use std::error::Error;
31use std::fmt::{self, Debug, Display, Formatter, Write};
32use std::hash::Hash;
33use std::sync::OnceLock;
34
35use base::charset::{Script, subscript_char, superscript_char};
36
37/// Identifies a Unicode character or a `@...@` glyph in the input
38/// which does not correspond to something understood by the M4
39/// assembler.
40///
41/// We make an exception for characters that appear only in comments
42/// or annotations.
43#[derive(Debug, PartialEq, Eq, Clone)]
44pub(crate) enum Unrecognised {
45 /// A Unicode character is unknown on the TX-2.
46 InvalidChar(char),
47 /// `@foo@` was used but we did not recognise `foo` as the name of
48 /// a known glyph.
49 UnrecognisedGlyph(String),
50}
51
52impl Display for Unrecognised {
53 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
54 match self {
55 Unrecognised::InvalidChar(ch) => write!(
56 f,
57 "'{ch}' is not part of the TX-2 assembler's character set"
58 ),
59 Unrecognised::UnrecognisedGlyph(name) => {
60 write!(f, "'@{name}@' is not a recognised glyph name")
61 }
62 }
63 }
64}
65
66impl Error for Unrecognised {}
67
68/// Indicates the super/sub/normal script of something.
69///
70/// `Elevated<T>` indicates that a `T` appears in superscript,
71/// subscript or normal script. This changes the meaning (and
72/// numerical value) of that item in the TX-2 assembly language.
73#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
74pub(crate) struct Elevated<T> {
75 inner: T,
76 script: Script,
77}
78
79impl<T> Elevated<T> {
80 pub(crate) fn script(&self) -> Script {
81 self.script
82 }
83
84 pub(crate) fn get(&self) -> &T {
85 &self.inner
86 }
87}
88
89trait AsStr {
90 fn as_str(&self) -> &str;
91}
92
93impl AsStr for &str {
94 fn as_str(&self) -> &str {
95 self
96 }
97}
98
99impl AsStr for String {
100 fn as_str(&self) -> &str {
101 self.as_str()
102 }
103}
104
105impl<T: AsStr> Display for Elevated<T> {
106 fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
107 match self.script {
108 Script::Normal => write!(f, "{}", self.inner.as_str()),
109 Script::Super => {
110 for ch in self.inner.as_str().chars() {
111 match superscript_char(ch) {
112 Ok(superchar) => {
113 f.write_char(superchar)?;
114 }
115 Err(_) => match glyph_of_char(ch) {
116 Ok(elevated_glyph) => {
117 let glyph = elevated_glyph.get();
118 if let Some(superchar) = glyph.superscript {
119 f.write_char(superchar)?;
120 } else {
121 write!(f, "@sup_{}@", glyph.name)?;
122 }
123 }
124 Err(_) => {
125 unimplemented!("superscript variant of {ch}")
126 }
127 },
128 }
129 }
130 Ok(())
131 }
132 Script::Sub => {
133 for ch in self.inner.as_str().chars() {
134 match subscript_char(ch) {
135 Ok(subchar) => {
136 f.write_char(subchar)?;
137 }
138 Err(_) => match glyph_of_char(ch) {
139 Ok(elevated_glyph) => {
140 let glyph = elevated_glyph.get();
141 if let Some(superchar) = glyph.superscript {
142 f.write_char(superchar)?;
143 } else {
144 write!(f, "@sub_{}@", glyph.name)?;
145 }
146 }
147 Err(_) => {
148 unimplemented!("find subscript variant of {ch}")
149 }
150 },
151 }
152 }
153 Ok(())
154 }
155 }
156 }
157}
158
159impl<T> From<(Script, T)> for Elevated<T> {
160 fn from((script, inner): (Script, T)) -> Elevated<T> {
161 Elevated { inner, script }
162 }
163}
164
165/// Create an instance of [`Elevated<T>`].
166pub(crate) fn elevate<T>(script: Script, inner: T) -> Elevated<T> {
167 Elevated { inner, script }
168}
169
170/// A character which might appear in source code.
171///
172/// We include mappings to Unicode representation where this exists.
173/// However, there are also cases where more than one Unicode
174/// character (in the assembler input) might get mapped to the same
175/// Glyph; see [`canonicalise_char`].
176#[derive(Debug, PartialEq, Eq)]
177pub(crate) struct Glyph {
178 /// Indicates the shape of the glyph without regard to its
179 /// (superscript/subscript/normal) position with respect to the
180 /// character baseline.
181 pub(crate) shape: GlyphShape,
182 /// The name of the glyph as we would use it inside `@...@`.
183 pub(crate) name: &'static str,
184 /// The Unicode representation of this glyph when in normal
185 /// script.
186 pub(crate) normal: Option<char>,
187 /// The Unicode representation of this glyph when in superscript.
188 pub(crate) superscript: Option<char>,
189 /// The Unicode representation of this glyph when in subscript.
190 pub(crate) subscript: Option<char>,
191 /// When advance is false, this glyph does not advance the Lincoln
192 /// Writer's print carriage. This appears to be true for
193 /// character codes 0o12 (underbar, overbar) and 0o13 (circle,
194 /// square). We should provide a reference for this, but just now
195 /// I'm taking this info from the code in base/src/charset.rs
196 /// which deals with these character codes.
197 ///
198 /// We try to use combining characters for these.
199 pub(crate) advance: bool,
200}
201
202impl Glyph {
203 pub(crate) fn shape(&self) -> GlyphShape {
204 self.shape
205 }
206
207 pub(crate) fn get_char(&self, script: Script) -> Option<char> {
208 match script {
209 Script::Normal => self.normal,
210 Script::Super => self.superscript,
211 Script::Sub => self.subscript,
212 }
213 }
214}
215
216#[test]
217fn test_subscript_char_agreement() {
218 for g in ALL_GLYPHS {
219 if let Some(ch) = g.normal
220 && let Some(glyph_sub_ch) = g.subscript
221 && let Ok(charset_sub_ch) = subscript_char(ch)
222 {
223 assert_eq!(
224 glyph_sub_ch,
225 charset_sub_ch,
226 "glyph {g:?} maps {ch} to {glyph_sub_ch} ({}) but subscript_char maps it to {charset_sub_ch} ({})",
227 glyph_sub_ch.escape_unicode(),
228 charset_sub_ch.escape_unicode(),
229 );
230 }
231 }
232}
233
234#[test]
235fn test_superscript_char_agreement() {
236 for g in ALL_GLYPHS {
237 if let Some(ch) = g.normal
238 && let Some(glyph_sup_ch) = g.superscript
239 && let Ok(charset_sup_ch) = superscript_char(ch)
240 {
241 assert_eq!(
242 glyph_sup_ch,
243 charset_sup_ch,
244 "glyph {g:?} maps {ch} to {glyph_sup_ch} ({}) but superscript_char maps it to {charset_sup_ch} ({})",
245 glyph_sup_ch.escape_unicode(),
246 charset_sup_ch.escape_unicode(),
247 );
248 }
249 }
250}
251
252#[test]
253fn test_glyph_names_do_not_contain_underscore() {
254 // Because sup_ and sub_ use an underscore as a kind of separator,
255 // it's probably too confusing to allow them in glyph names. So
256 // this test prevents someone using one.
257 //
258 // I am currently also considering a convention in which a
259 // combining character is specified by including the name of the
260 // second character inside @...@. For example @square_minus@ to
261 // denote a square (which does not advance the carriage) followed
262 // by a minus sign (which does). This plan would require us to
263 // treat '_' as a glyph name separator.
264 for g in ALL_GLYPHS {
265 assert!(
266 !g.name.contains('_'),
267 "glyph name {} should not contain an underscore",
268 g.name
269 );
270 }
271}
272
273// TODO: probably doesn't need to be a module.
274mod shape {
275 //! Used to limit effect of `allow(non_camel_case_types)`;
276 //! probably not needed.
277
278 /// Lincoln Writer character shapes.
279 ///
280 /// All character shapes in the character set table from page 2 of
281 /// the documentation on the Lincoln Writer channels (65, 66).
282 /// TX-2 Users Handbook, July 1961.
283 #[allow(non_camel_case_types)]
284 #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Clone, Copy)]
285 pub(crate) enum GlyphShape {
286 Digit0,
287 Digit1,
288 Digit2,
289 Digit3,
290 Digit4,
291 Digit5,
292 Digit6,
293 Digit7,
294 Digit8,
295 Digit9,
296 Underscore,
297 Circle,
298 A,
299 B,
300 C,
301 D,
302 E,
303 F,
304 G,
305 H,
306 I,
307 J,
308 K,
309 L,
310 M,
311 N,
312 O,
313 P,
314 Q,
315 R,
316 S,
317 T,
318 U,
319 V,
320 W,
321 X,
322 Y,
323 Z,
324 LeftParen,
325 RightParen,
326 Add,
327 Minus,
328 Comma,
329 Dot,
330 // No CARRIAGE RETURN
331 Tab,
332 Backspace,
333 // No COLOR BLACK, SUPER, NORMAL, SUB, COLOR RED
334 Space,
335 // No WORD EXAM, LINE FEED DOWN, LINE FEED UP, LOWER CASE, UPPER
336 // CASE, STOP, NULLIFY.
337 Hand,
338 Sigma,
339 Pipe,
340 DoublePipe,
341 Solidus,
342 Times,
343 Hash,
344 Arrow,
345 LessThan,
346 GreaterThan,
347 Overbar,
348 Square,
349 n,
350 SubsetOf,
351 Or,
352 q,
353 Gamma,
354 t,
355 w,
356 x,
357 i,
358 y,
359 z,
360 Query,
361 Union,
362 Intersection,
363 j,
364 k,
365 Alpha,
366 Delta,
367 p,
368 Epsilon,
369 h,
370 SupersetOf,
371 Beta,
372 And,
373 Xor,
374 Lambda,
375 Tilde,
376 LeftBrace,
377 RightBrace,
378 IdenticalTo, /* hamb */
379 Equals,
380 Apostrophe,
381 Asterisk,
382 }
383}
384pub(crate) use shape::GlyphShape;
385
386/// Indicates that a Unicode character does not exist in the TX-2 character set.
387#[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Clone, Copy)]
388pub(crate) struct NotInCharacterSet(pub char);
389
390impl Display for NotInCharacterSet {
391 fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
392 write!(
393 f,
394 "Character '{}' is not in the TX-2's Lincoln Writer character set",
395 self.0
396 )
397 }
398}
399
400impl Error for NotInCharacterSet {}
401
402/// Convert a superscript/subscript/normal Unicode character, if we
403/// recognise it, into [`Elevated<&'static Glyph>`].
404pub(crate) fn glyph_of_char(original: char) -> Result<Elevated<&'static Glyph>, Unrecognised> {
405 let ch: char = canonicalise_char(original);
406 let mapping = glyph_map();
407 match mapping.get(ch) {
408 Some(elevated) => Ok(elevated),
409 None => Err(Unrecognised::InvalidChar(original)),
410 }
411}
412
413#[test]
414fn test_space_is_normal() {
415 match glyph_of_char(' ') {
416 Ok(elevated) => {
417 assert_eq!(elevated.script(), Script::Normal);
418 }
419 Err(e) => {
420 panic!("unexpected failure to look up space: {e:?}");
421 }
422 }
423}
424
425impl TryFrom<char> for Elevated<&'static Glyph> {
426 type Error = NotInCharacterSet;
427
428 fn try_from(ch: char) -> Result<Self, Self::Error> {
429 glyph_of_char(ch).map_err(|_| NotInCharacterSet(ch))
430 }
431}
432
433#[test]
434fn test_glyph_of_dot() {
435 assert_eq!(glyph_of_char('.'), glyph_of_char('·'));
436}
437
438//const fn code_point_of_shape(g: GlyphShape) -> (LwCase, Unsigned6Bit) {
439// use base::charset::LwCase;
440// use base::Pu6, Unsigned6Bit};
441// // Information taken from the character set table from page 2 of
442// // the documentation on the Lincoln Writer channels (65, 66).
443// // TX-2 Users Handbook, July 1961.
444// const L: LwCase = LwCase::Lower;
445// const U: LwCase = LwCase::Upper;
446// match g {
447// GlyphShape::Digit0 => (L, u6!(0)),
448// GlyphShape::Digit1 => (L, u6!(1)),
449// GlyphShape::Digit2 => (L, u6!(2)),
450// GlyphShape::Digit3 => (L, u6!(3)),
451// GlyphShape::Digit4 => (L, u6!(4)),
452// GlyphShape::Digit5 => (L, u6!(5)),
453// GlyphShape::Digit6 => (L, u6!(6)),
454// GlyphShape::Digit7 => (L, u6!(7)),
455// GlyphShape::Digit8 => (L, u6!(0o10)),
456// GlyphShape::Digit9 => (L, u6!(0o11)),
457// GlyphShape::Underscore => (L, u6!(0o12)),
458// GlyphShape::Circle => (L, u6!(0o13)),
459// GlyphShape::A => (L, u6!(0o20)),
460// GlyphShape::B => (L, u6!(0o21)),
461// GlyphShape::C => (L, u6!(0o22)),
462// GlyphShape::D => (L, u6!(0o23)),
463// GlyphShape::E => (L, u6!(0o24)),
464// GlyphShape::F => (L, u6!(0o25)),
465// GlyphShape::G => (L, u6!(0o26)),
466// GlyphShape::H => (L, u6!(0o27)),
467// GlyphShape::I => (L, u6!(0o30)),
468// GlyphShape::J => (L, u6!(0o31)),
469// GlyphShape::K => (L, u6!(0o32)),
470// GlyphShape::L => (L, u6!(0o33)),
471// GlyphShape::M => (L, u6!(0o34)),
472// GlyphShape::N => (L, u6!(0o35)),
473// GlyphShape::O => (L, u6!(0o36)),
474// GlyphShape::P => (L, u6!(0o37)),
475// GlyphShape::Q => (L, u6!(0o40)),
476// GlyphShape::R => (L, u6!(0o41)),
477// GlyphShape::S => (L, u6!(0o42)),
478// GlyphShape::T => (L, u6!(0o43)),
479// GlyphShape::U => (L, u6!(0o44)),
480// GlyphShape::V => (L, u6!(0o45)),
481// GlyphShape::W => (L, u6!(0o46)),
482// GlyphShape::X => (L, u6!(0o47)),
483// GlyphShape::Y => (L, u6!(0o50)),
484// GlyphShape::Z => (L, u6!(0o51)),
485// GlyphShape::LeftParen => (L, u6!(0o52)),
486// GlyphShape::RightParen => (L, u6!(0o53)),
487// GlyphShape::Add => (L, u6!(0o54)),
488// GlyphShape::Minus => (L, u6!(0o55)),
489// GlyphShape::Comma => (L, u6!(0o56)),
490// GlyphShape::Dot => (L, u6!(0o57)),
491// GlyphShape::Tab => (L, u6!(0o61)),
492// GlyphShape::Backspace => (L, u6!(0o62)),
493// // 0o63 is COLOR BLACK
494// //
495// // 0o64 is SUPER
496// //
497// // 0o65 is NORMAL
498// //
499// // 0o66 is SUB
500// //
501// // 0o67 is COLOR RED
502// GlyphShape::Space => (L, u6!(0o70)),
503// // 0o71 is WORD EXAM
504// //
505// // 0o72 is LINE FEED DOWN
506// //
507// // 0o73 is LINE FEED UP
508// //
509// // 0o74 is LOWER CASE
510// //
511// // 0o75 is UPPER CASE
512// //
513// // 0o76 is STOP
514// //
515// // 0o77 is NULLIFY
516// GlyphShape::Hand => (U, u6!(0)),
517// GlyphShape::Sigma => (U, u6!(1)),
518// GlyphShape::Pipe => (U, u6!(2)),
519// GlyphShape::DoublePipe => (U, u6!(3)),
520// GlyphShape::Solidus => (U, u6!(4)),
521// GlyphShape::Times => (U, u6!(5)),
522// GlyphShape::Hash => (U, u6!(6)),
523// GlyphShape::Arrow => (U, u6!(7)),
524// GlyphShape::LessThan => (U, u6!(0o10)),
525// GlyphShape::GreaterThan => (U, u6!(0o11)),
526// GlyphShape::Overbar => (U, u6!(0o12)),
527// GlyphShape::Square => (U, u6!(0o13)),
528// // 0o14 is "READ IN"
529// //
530// // 0o15 is "BEGIN"
531// //
532// // 0o16 is "NO"
533// //
534// // 0o17 is "YES"
535// GlyphShape::n => (U, u6!(0o20)),
536// GlyphShape::SubsetOf => (U, u6!(0o21)),
537// GlyphShape::Or => (U, u6!(0o22)),
538// GlyphShape::q => (U, u6!(0o23)),
539// GlyphShape::Gamma => (U, u6!(0o24)),
540// GlyphShape::t => (U, u6!(0o25)),
541// GlyphShape::w => (U, u6!(0o26)),
542// GlyphShape::x => (U, u6!(0o27)),
543// GlyphShape::i => (U, u6!(0o30)),
544// GlyphShape::y => (U, u6!(0o31)),
545// GlyphShape::z => (U, u6!(0o32)),
546// GlyphShape::Query => (U, u6!(0o33)),
547// GlyphShape::Union => (U, u6!(0o34)),
548// GlyphShape::Intersection => (U, u6!(0o35)),
549// GlyphShape::j => (U, u6!(0o36)),
550// GlyphShape::k => (U, u6!(0o37)),
551// GlyphShape::Alpha => (U, u6!(0o40)),
552// GlyphShape::Delta => (U, u6!(0o41)),
553// GlyphShape::p => (U, u6!(0o42)),
554// GlyphShape::Epsilon => (U, u6!(0o43)),
555// GlyphShape::h => (U, u6!(0o44)),
556// GlyphShape::SupersetOf => (U, u6!(0o45)),
557// GlyphShape::Beta => (U, u6!(0o46)),
558// GlyphShape::And => (U, u6!(0o47)),
559// GlyphShape::Lambda => (U, u6!(0o50)),
560// GlyphShape::Tilde => (U, u6!(0o51)),
561// GlyphShape::LeftBrace => (U, u6!(0o52)),
562// GlyphShape::RightBrace => (U, u6!(0o53)),
563// GlyphShape::IdenticalTo => (U, u6!(0o54)), // @hamb@
564// GlyphShape::Equals => (U, u6!(0o55)),
565// GlyphShape::Apostrophe => (U, u6!(0o56)),
566// GlyphShape::Asterisk => (U, u6!(0o57)),
567// // Code points 0o60 to 0o77 are non-graphinc characters.
568// }
569//}
570
571/// Used to save typing to provide defaults in the definitions in
572/// [`ALL_GLYPHS`].
573const GDEF: Glyph = Glyph {
574 shape: GlyphShape::Hand,
575 name: "",
576 normal: None,
577 superscript: None,
578 subscript: None,
579 advance: true,
580};
581
582/// Symbols understood by the M4 assembler (other than compound
583/// symbols).
584///
585/// Information taken from the character set table from page 2 of
586/// the documentation on the Lincoln Writer channels (65, 66).
587/// TX-2 Users Handbook, July 1961.
588const ALL_GLYPHS: &[Glyph] = &[
589 Glyph {
590 shape: GlyphShape::Digit0,
591 name: "0",
592 normal: Some('0'),
593 superscript: Some('⁰'),
594 subscript: Some('₀'),
595 ..GDEF
596 },
597 Glyph {
598 shape: GlyphShape::Digit1,
599 name: "1",
600 normal: Some('1'),
601 subscript: Some('₁'),
602 superscript: Some('¹'),
603 ..GDEF
604 },
605 Glyph {
606 shape: GlyphShape::Digit2,
607 name: "2",
608 normal: Some('2'),
609 subscript: Some('₂'),
610 superscript: Some('²'),
611 ..GDEF
612 },
613 Glyph {
614 shape: GlyphShape::Digit3,
615 name: "3",
616 normal: Some('3'),
617 subscript: Some('₃'),
618 superscript: Some('³'),
619 ..GDEF
620 },
621 Glyph {
622 shape: GlyphShape::Digit4,
623 name: "4",
624 normal: Some('4'),
625 subscript: Some('₄'),
626 superscript: Some('⁴'),
627 ..GDEF
628 },
629 Glyph {
630 shape: GlyphShape::Digit5,
631 name: "5",
632 normal: Some('5'),
633 subscript: Some('₅'),
634 superscript: Some('⁵'),
635 ..GDEF
636 },
637 Glyph {
638 shape: GlyphShape::Digit6,
639 name: "6",
640 normal: Some('6'),
641 subscript: Some('₆'),
642 superscript: Some('⁶'),
643 ..GDEF
644 },
645 Glyph {
646 shape: GlyphShape::Digit7,
647 name: "7",
648 normal: Some('7'),
649 subscript: Some('₇'),
650 superscript: Some('⁷'),
651 ..GDEF
652 },
653 Glyph {
654 shape: GlyphShape::Digit8,
655 name: "8",
656 normal: Some('8'),
657 subscript: Some('₈'),
658 superscript: Some('⁸'),
659 ..GDEF
660 },
661 Glyph {
662 shape: GlyphShape::Digit9,
663 name: "9",
664 normal: Some('9'),
665 subscript: Some('₉'),
666 superscript: Some('⁹'),
667 ..GDEF
668 },
669 Glyph {
670 shape: GlyphShape::Underscore,
671 name: "underscore",
672 // This character does not advance the carriage, so instead of
673 // representing it with ASCII \x5F (underscore) we use a
674 // combining low line.
675 normal: Some('\u{0332}'), // U+0332, combining low line
676 advance: false,
677 ..GDEF
678 },
679 Glyph {
680 shape: GlyphShape::Circle,
681 name: "circle",
682 // U+25CB, Unicode white circle, '○', advances the cursor
683 // position, which the Lincoln Writer code (0o13) doesn't do.
684 // So we use a combining character.
685 normal: Some('\u{20DD}'), // U+20DD, combining enclosing circle
686 advance: false,
687 ..GDEF
688 },
689 // 0o14 is "READ IN"
690 //
691 // 0o15 is "BEGIN"
692 //
693 // 0o16 is "NO"
694 //
695 // 0o17 is "YES"
696 Glyph {
697 shape: GlyphShape::A,
698 name: "A",
699 normal: Some('A'),
700 superscript: Some('ᴬ'),
701 ..GDEF
702 },
703 Glyph {
704 shape: GlyphShape::B,
705 name: "B",
706 normal: Some('B'),
707 superscript: Some('ᴮ'),
708 ..GDEF
709 },
710 Glyph {
711 shape: GlyphShape::C,
712 name: "C",
713 normal: Some('C'),
714 superscript: Some('ꟲ'), // U+A7F2 (we don't use U+1D9C, that's the lower-case C)
715 ..GDEF
716 },
717 Glyph {
718 shape: GlyphShape::D,
719 name: "D",
720 normal: Some('D'),
721 superscript: Some('ᴰ'),
722 ..GDEF
723 },
724 Glyph {
725 shape: GlyphShape::E,
726 name: "E",
727 normal: Some('E'),
728 superscript: Some('ᴱ'),
729 ..GDEF
730 },
731 Glyph {
732 shape: GlyphShape::F,
733 name: "F",
734 normal: Some('F'),
735 superscript: Some('ꟳ'),
736 ..GDEF
737 },
738 Glyph {
739 shape: GlyphShape::G,
740 name: "G",
741 normal: Some('G'),
742 superscript: Some('ᴳ'),
743 ..GDEF
744 },
745 Glyph {
746 shape: GlyphShape::H,
747 name: "H",
748 normal: Some('H'),
749 superscript: Some('ᴴ'),
750 ..GDEF
751 },
752 Glyph {
753 shape: GlyphShape::I,
754 name: "I",
755 normal: Some('I'),
756 superscript: Some('ᴵ'),
757 ..GDEF
758 },
759 Glyph {
760 shape: GlyphShape::J,
761 name: "J",
762 normal: Some('J'),
763 superscript: Some('ᴶ'),
764 ..GDEF
765 },
766 Glyph {
767 shape: GlyphShape::K,
768 name: "K",
769 normal: Some('K'),
770 superscript: Some('ᴷ'),
771 ..GDEF
772 },
773 Glyph {
774 shape: GlyphShape::L,
775 name: "L",
776 normal: Some('L'),
777 superscript: Some('ᴸ'),
778 ..GDEF
779 },
780 Glyph {
781 shape: GlyphShape::M,
782 name: "M",
783 normal: Some('M'),
784 superscript: Some('ᴹ'),
785 ..GDEF
786 },
787 Glyph {
788 shape: GlyphShape::N,
789 name: "N",
790 normal: Some('N'),
791 superscript: Some('ᴺ'),
792 ..GDEF
793 },
794 Glyph {
795 shape: GlyphShape::O,
796 name: "O",
797 normal: Some('O'),
798 superscript: Some('ᴼ'),
799 ..GDEF
800 },
801 Glyph {
802 shape: GlyphShape::P,
803 name: "P",
804 normal: Some('P'),
805 superscript: Some('ᴾ'),
806 ..GDEF
807 },
808 Glyph {
809 shape: GlyphShape::Q,
810 name: "Q",
811 normal: Some('Q'),
812 superscript: Some('ꟴ'),
813 ..GDEF
814 },
815 Glyph {
816 shape: GlyphShape::R,
817 name: "R",
818 normal: Some('R'),
819 superscript: Some('ᴿ'),
820 ..GDEF
821 },
822 Glyph {
823 shape: GlyphShape::S,
824 name: "S",
825 normal: Some('S'),
826 // There is no Unicode superscript 'S', U+2E2 is a superscript 's'.
827 superscript: None,
828 ..GDEF
829 },
830 Glyph {
831 shape: GlyphShape::T,
832 name: "T",
833 normal: Some('T'),
834 superscript: Some('ᵀ'),
835 ..GDEF
836 },
837 Glyph {
838 shape: GlyphShape::U,
839 name: "U",
840 normal: Some('U'),
841 superscript: Some('ᵁ'),
842 ..GDEF
843 },
844 Glyph {
845 shape: GlyphShape::V,
846 name: "V",
847 normal: Some('V'),
848 superscript: Some('ⱽ'),
849 ..GDEF
850 },
851 Glyph {
852 shape: GlyphShape::W,
853 name: "W",
854 normal: Some('W'),
855 superscript: Some('ᵂ'),
856 ..GDEF
857 },
858 Glyph {
859 shape: GlyphShape::X,
860 name: "X",
861 normal: Some('X'),
862 // There is no superscript X in Unicode.
863 ..GDEF
864 },
865 Glyph {
866 shape: GlyphShape::Y,
867 name: "Y",
868 normal: Some('Y'),
869 // There is no superscript Y in Unicode.
870 ..GDEF
871 },
872 Glyph {
873 shape: GlyphShape::Z,
874 name: "Z",
875 normal: Some('Z'),
876 // There is no superscript Z in Unicode.
877 ..GDEF
878 },
879 Glyph {
880 shape: GlyphShape::LeftParen,
881 name: "lparen",
882 normal: Some('('),
883 subscript: Some('₍'),
884 ..GDEF
885 },
886 Glyph {
887 shape: GlyphShape::RightParen,
888 name: "rparen",
889 normal: Some(')'),
890 subscript: Some('₎'),
891 ..GDEF
892 },
893 Glyph {
894 shape: GlyphShape::Add,
895 name: "add", // following sub.py
896 normal: Some('+'),
897 superscript: Some('⁺'),
898 subscript: Some('₊'),
899 ..GDEF
900 },
901 Glyph {
902 shape: GlyphShape::Minus,
903 name: "minus", // following sub.py
904 normal: Some('-'),
905 superscript: Some('⁻'),
906 subscript: Some('₋'),
907 ..GDEF
908 },
909 Glyph {
910 shape: GlyphShape::Comma,
911 name: "comma",
912 normal: Some(','),
913 ..GDEF
914 },
915 Glyph {
916 shape: GlyphShape::Dot,
917 name: "dot",
918 // This is a centre dot, not a period. We use a centre dot so
919 // that it's not confused with a subscript dot.
920 normal: Some('\u{00B7}'), // ·
921
922 // Using an ASCII full stop / period (".") would be too
923 // confusing for the user, who (when preparing source code
924 // input) might expect this to be interpreted as the
925 // normal-script PERIOD. So for subscript we instead use
926 // U+2024, "One Dot Leader".
927 subscript: Some('\u{2024}'), // "․" (not ASCII ".")
928 superscript: None,
929 ..GDEF
930 },
931 // CARRIAGE RETURN is missing.
932 Glyph {
933 shape: GlyphShape::Tab,
934 name: "tab",
935 normal: Some('\t'),
936 ..GDEF
937 },
938 Glyph {
939 // backspace is used in some combining-character symexes.
940 shape: GlyphShape::Backspace,
941 name: "backspace",
942 normal: None, // better to say @backspace@.
943 ..GDEF
944 },
945 // 0o63 is COLOR BLACK
946 //
947 // 0o64 is SUPER
948 //
949 // 0o65 is NORMAL
950 //
951 // 0o66 is SUB
952 //
953 // 0o67 is COLOR RED
954 Glyph {
955 shape: GlyphShape::Space,
956 name: "space",
957 normal: Some(' '),
958 subscript: Some(' '),
959 superscript: Some(' '),
960 ..GDEF
961 },
962 // 0o71 is WORD EXAM
963 //
964 // 0o72 is LINE FEED DOWN
965 //
966 // 0o73 is LINE FEED UP
967 //
968 // 0o74 is LOWER CASE
969 //
970 // 0o75 is UPPER CASE
971 //
972 // 0o76 is STOP
973 //
974 // 0o77 is NULLIFY
975 //
976 //
977 // Right-hand column of the character set table follows.
978 Glyph {
979 shape: GlyphShape::Hand,
980 name: "hand",
981 normal: Some('☛'), // U+261B
982 ..GDEF
983 },
984 Glyph {
985 shape: GlyphShape::Sigma,
986 name: "sigma",
987 normal: Some('Σ'), // U+03A3
988 ..GDEF
989 },
990 Glyph {
991 shape: GlyphShape::Pipe,
992 name: "pipe",
993 normal: Some('|'),
994 ..GDEF
995 },
996 Glyph {
997 shape: GlyphShape::DoublePipe,
998 name: "doublepipe",
999 normal: Some('‖'),
1000 ..GDEF
1001 },
1002 Glyph {
1003 shape: GlyphShape::Solidus,
1004 name: "solidus", // better known as "slash".
1005 normal: Some('/'),
1006 ..GDEF
1007 },
1008 Glyph {
1009 shape: GlyphShape::Times,
1010 name: "times",
1011 normal: Some('×'),
1012 ..GDEF
1013 },
1014 Glyph {
1015 shape: GlyphShape::Hash,
1016 name: "hash",
1017 normal: Some('#'),
1018 ..GDEF
1019 },
1020 Glyph {
1021 shape: GlyphShape::Arrow,
1022 // arr not arrow to follow Jurij's sub.py
1023 name: "arr",
1024 normal: Some('\u{2192}'), // →
1025 ..GDEF
1026 },
1027 Glyph {
1028 shape: GlyphShape::LessThan,
1029 name: "lessthan",
1030 normal: Some('<'),
1031 ..GDEF
1032 },
1033 Glyph {
1034 shape: GlyphShape::GreaterThan,
1035 name: "greaterthan",
1036 normal: Some('>'),
1037 ..GDEF
1038 },
1039 Glyph {
1040 shape: GlyphShape::Overbar,
1041 name: "overbar",
1042 // This character does not advance the carriage, so we use a
1043 // combining character for it.
1044 normal: Some('\u{0305}'), // U+0305, combining overline
1045 superscript: None,
1046 subscript: None,
1047 advance: false,
1048 },
1049 Glyph {
1050 shape: GlyphShape::Square,
1051 name: "square",
1052 // This character does not advance the carriage, so instead of
1053 // using a character like U+25A1 ('□'), we use a combining
1054 // character.
1055 normal: Some('\u{20DE}'), // U+20DE, combining enclosing square
1056 subscript: None,
1057 superscript: None,
1058 advance: false,
1059 },
1060 // 0o14 is "READ IN"
1061 //
1062 // 0o15 is "BEGIN"
1063 //
1064 // 0o16 is "NO"
1065 //
1066 // 0o17 is "YES"
1067 Glyph {
1068 shape: GlyphShape::n,
1069 name: "n",
1070 normal: Some('n'),
1071 superscript: Some('ⁿ'),
1072 subscript: Some('ₙ'), // U+2099
1073 ..GDEF
1074 },
1075 Glyph {
1076 shape: GlyphShape::SubsetOf,
1077 name: "subsetof",
1078 normal: Some('\u{2282}'), // Subset of, ⊂
1079 ..GDEF
1080 },
1081 Glyph {
1082 shape: GlyphShape::Or,
1083 name: "or",
1084 normal: Some('∨'),
1085 ..GDEF
1086 },
1087 Glyph {
1088 shape: GlyphShape::q,
1089 name: "q",
1090 normal: Some('q'),
1091 superscript: None,
1092 // U+107A5 is a subscript q, but this is not widely supported,
1093 // so we don't use it. Instead the user should use "@sub_q@".
1094 subscript: None,
1095 ..GDEF
1096 },
1097 Glyph {
1098 shape: GlyphShape::Gamma,
1099 name: "gamma",
1100 normal: Some('γ'), // U+03B3, Greek small letter gamma
1101 superscript: Some('ᵞ'),
1102 subscript: Some('ᵧ'),
1103 ..GDEF
1104 },
1105 Glyph {
1106 shape: GlyphShape::t,
1107 name: "t",
1108 normal: Some('t'),
1109 superscript: Some('ᵗ'), // U+1D57
1110 subscript: Some('ₜ'), // U+209C
1111 ..GDEF
1112 },
1113 Glyph {
1114 shape: GlyphShape::w,
1115 name: "w",
1116 normal: Some('w'),
1117 superscript: Some('ʷ'),
1118 subscript: None,
1119 ..GDEF
1120 },
1121 Glyph {
1122 shape: GlyphShape::x,
1123 name: "x",
1124 normal: Some('x'),
1125 superscript: Some('ˣ'),
1126 subscript: Some('ₓ'), // U+2093
1127 ..GDEF
1128 },
1129 Glyph {
1130 shape: GlyphShape::i,
1131 name: "i",
1132 normal: Some('i'),
1133 superscript: Some('ⁱ'),
1134 subscript: Some('ᵢ'),
1135 ..GDEF
1136 },
1137 Glyph {
1138 shape: GlyphShape::y,
1139 name: "y",
1140 normal: Some('y'),
1141 superscript: Some('ʸ'),
1142 subscript: None,
1143 ..GDEF
1144 },
1145 Glyph {
1146 shape: GlyphShape::z,
1147 name: "z",
1148 normal: Some('z'),
1149 subscript: None,
1150 superscript: Some('ᶻ'),
1151 ..GDEF
1152 },
1153 Glyph {
1154 shape: GlyphShape::Query, // A question mark.
1155 name: "?",
1156 normal: Some('?'),
1157 superscript: Some('ˀ'), // dot is missing but it's the best we can do.
1158 // U+FE56, "Small Question Mark" is not really a subscript
1159 // character, but let's try it out.
1160 subscript: Some('﹖'),
1161 ..GDEF
1162 },
1163 Glyph {
1164 shape: GlyphShape::Union,
1165 name: "union",
1166 normal: Some('∪'),
1167 superscript: None,
1168 subscript: None,
1169 ..GDEF
1170 },
1171 Glyph {
1172 shape: GlyphShape::Intersection,
1173 name: "intersection",
1174 normal: Some('\u{2229}'),
1175 subscript: None,
1176 superscript: None,
1177 ..GDEF
1178 },
1179 Glyph {
1180 shape: GlyphShape::j,
1181 name: "j",
1182 normal: Some('j'),
1183 superscript: Some('ʲ'), // U+02B2
1184 subscript: Some('ⱼ'), // U+2C7C
1185 ..GDEF
1186 },
1187 Glyph {
1188 shape: GlyphShape::k,
1189 name: "k",
1190 normal: Some('k'),
1191 superscript: Some('ᵏ'),
1192 subscript: Some('ₖ'), // U+2096
1193 ..GDEF
1194 },
1195 Glyph {
1196 shape: GlyphShape::Alpha,
1197 name: "alpha",
1198 normal: Some('α'), // U+03B1, alpha
1199 // this is actually a Latin superscript alpha, but it will normally look the same.
1200 superscript: Some('ᵅ'),
1201 subscript: None,
1202 ..GDEF
1203 },
1204 Glyph {
1205 shape: GlyphShape::Delta,
1206 name: "delta",
1207 normal: Some('Δ'), // U+0395, capital delta
1208 ..GDEF
1209 },
1210 Glyph {
1211 shape: GlyphShape::p,
1212 name: "p",
1213 normal: Some('p'),
1214 superscript: Some('ᵖ'),
1215 subscript: Some('ₚ'), // U+209A
1216 ..GDEF
1217 },
1218 Glyph {
1219 shape: GlyphShape::Epsilon,
1220 name: "eps",
1221 normal: Some('ε'), // U+03B5, Epsilon (not ∈, Element of)
1222 superscript: Some('ᵋ'), // U+1D4B
1223 subscript: None,
1224 ..GDEF
1225 },
1226 Glyph {
1227 shape: GlyphShape::h,
1228 name: "h",
1229 normal: Some('h'),
1230 superscript: Some('ʰ'),
1231 subscript: Some('ₕ'),
1232 ..GDEF
1233 },
1234 Glyph {
1235 shape: GlyphShape::SupersetOf,
1236 name: "sup", // name aligns with Jurij's sub.py
1237 normal: Some('⊃'), // U+2283, superset of
1238 superscript: None,
1239 subscript: None,
1240 ..GDEF
1241 },
1242 Glyph {
1243 shape: GlyphShape::Beta,
1244 name: "beta",
1245 normal: Some('β'), // U+03B2, Greek beta symbol
1246 superscript: Some('ᵝ'), // U+1D5D
1247 subscript: Some('ᵦ'), // U+1D66
1248 ..GDEF
1249 },
1250 Glyph {
1251 shape: GlyphShape::And,
1252 name: "and",
1253 normal: Some('∧'), // U+2227, Logical And
1254 superscript: None,
1255 subscript: None,
1256 ..GDEF
1257 },
1258 // M4 writes XOR as a compound circled logical-OR glyph. U+22BB is
1259 // a readable Unicode and markup substitute for source input.
1260 Glyph {
1261 shape: GlyphShape::Xor,
1262 name: "xor",
1263 normal: Some('⊻'), // U+22BB, XOR
1264 superscript: None,
1265 subscript: None,
1266 ..GDEF
1267 },
1268 Glyph {
1269 shape: GlyphShape::Lambda,
1270 name: "lambda",
1271 normal: Some('λ'), // U+3BB, Greek letter lambda
1272 superscript: None,
1273 subscript: None,
1274 ..GDEF
1275 },
1276 Glyph {
1277 shape: GlyphShape::Tilde,
1278 name: "tilde",
1279 normal: Some('~'),
1280 ..GDEF
1281 },
1282 Glyph {
1283 shape: GlyphShape::LeftBrace,
1284 name: "leftbrace",
1285 normal: Some('{'),
1286 ..GDEF
1287 },
1288 Glyph {
1289 shape: GlyphShape::RightBrace,
1290 name: "rightbrace",
1291 normal: Some('}'),
1292 ..GDEF
1293 },
1294 Glyph {
1295 shape: GlyphShape::IdenticalTo,
1296 name: "hamb", // following Jurij's sub.py
1297 normal: Some('≡'), // U+2261, Identical to (Jurij used ☰, U+2630, Trigram For Heaven)
1298 ..GDEF
1299 },
1300 Glyph {
1301 shape: GlyphShape::Equals,
1302 name: "equals",
1303 normal: Some('='),
1304 subscript: Some('₌'),
1305 ..GDEF
1306 },
1307 Glyph {
1308 shape: GlyphShape::Apostrophe,
1309 name: "apostrophe",
1310 normal: Some('\''),
1311 ..GDEF
1312 },
1313 Glyph {
1314 shape: GlyphShape::Asterisk,
1315 name: "asterisk",
1316 normal: Some('*'),
1317 subscript: None,
1318 superscript: None,
1319 ..GDEF
1320 },
1321 // Code points 0o60 to 0o77 are non-graphinc characters.
1322];
1323
1324/// Maps Unicode characters onto [`Glyph`] instances describing them.
1325#[derive(Debug, Clone, PartialEq, Eq)]
1326pub(crate) struct GlyphMapByChar {
1327 mapping: HashMap<char, Elevated<&'static Glyph>>,
1328}
1329
1330/// Read-only shared instance of [`GlyphMapByChar`].
1331static GLYPH_MAP_BY_CHAR: OnceLock<GlyphMapByChar> = OnceLock::new();
1332
1333impl Default for GlyphMapByChar {
1334 fn default() -> Self {
1335 let mut mapping = HashMap::new();
1336 for g in ALL_GLYPHS {
1337 for script in [Script::Sub, Script::Super, Script::Normal] {
1338 if g.normal == Some(' ') && script != Script::Normal {
1339 // Note that the space character has the same
1340 // representation in normal script, superscript
1341 // and subscript. We have a convention that space
1342 // is always deemed to be in normal script.
1343 continue;
1344 }
1345 if let Some(key) = g.get_char(script) {
1346 let value = elevate(script, g);
1347 if let Some(prev) = mapping.insert(key, value) {
1348 panic!("duplicate glyph mapping for character '{key}': {g:?} and {prev:?}");
1349 }
1350 }
1351 }
1352 }
1353 Self { mapping }
1354 }
1355}
1356
1357impl GlyphMapByChar {
1358 fn get(&self, ch: char) -> Option<Elevated<&'static Glyph>> {
1359 self.mapping.get(&ch).copied()
1360 }
1361}
1362
1363/// Return a reference to the shared instance of [`GlyphMapByChar`].
1364pub(crate) fn glyph_map() -> &'static GlyphMapByChar {
1365 GLYPH_MAP_BY_CHAR.get_or_init(GlyphMapByChar::default)
1366}
1367
1368/// Additional mappings of Unicode input to prevent user confusion.
1369///
1370/// We use the centre dot ("·", U+00B7) as a decimal point, but also
1371/// accept "." U+002E, because the latter is likely to be a common
1372/// choice.
1373///
1374/// We also provide ":" as a synonym for "h" in setting the hold bit
1375/// in order to accept source code from earlier papers which used the
1376/// older convention, such as H. Philip Peterson's "[Some Examples of
1377/// TX-2
1378/// Programming](http://www.bitsavers.org/pdf/mit/tx-2/6M-5780_Some_Examples_of_TX-2_Programming_Jul1958.pdf)"
1379/// (Lincoln Lab memo 6M-5780, 23 July 1958).
1380fn canonicalise_char(ch: char) -> char {
1381 match ch {
1382 // We don't convert U+A7F2 (ꟲ) to U+1D9C because the former is
1383 // a majuscule (captial) letter and the latter is a minuscule
1384 // (lower-case) letter.
1385 '.' => '\u{00B7}', // . -> ·
1386
1387 // The TX-2 character set doesn't include ':', but some of the
1388 // older sources use ':' to signal that the hold bit should be
1389 // set in an instruction. In the Users Handbook (in 1961 at
1390 // least) this function is performed by 'h'.
1391 ':' => 'h',
1392 _ => ch,
1393 }
1394}
1395
1396/// Convert a Unicode character into its `@...@` synonym.
1397pub(crate) fn name_from_glyph(mut ch: char) -> Option<&'static str> {
1398 // TODO: do we need both this and glyph_from_name?
1399 ch = canonicalise_char(ch);
1400 ALL_GLYPHS
1401 .iter()
1402 .find(|g| g.normal == Some(ch))
1403 .map(|g| g.name)
1404}
1405
1406/// Convert a Unicode string into [`Elevated<&'static Glyph>`].
1407///
1408/// Return `None` if the name of the glyph is not recognised.
1409pub(crate) fn glyph_from_name(name: &str) -> Option<Elevated<&'static Glyph>> {
1410 let (script, glyph_base_name) = if let Some(suffix) = name.strip_prefix("sub_") {
1411 (Script::Sub, suffix)
1412 } else if let Some(suffix) = name.strip_prefix("sup_") {
1413 (Script::Super, suffix)
1414 } else {
1415 (Script::Normal, name)
1416 };
1417 ALL_GLYPHS
1418 .iter()
1419 .find(|g| g.name == glyph_base_name)
1420 .map(|g| elevate(script, g))
1421}
1422
1423/// Return true if this character is allowed in a symex (symbol name).
1424///
1425/// Specified in Users Handbook section 6-2.3 item 6.
1426pub(crate) fn is_allowed_in_symex(g: GlyphShape) -> bool {
1427 match g {
1428 // Eeasier to understand if we don't re-order the match arms.
1429 #![allow(clippy::match_same_arms)]
1430 GlyphShape::Digit0 |
1431 GlyphShape::Digit1 |
1432 GlyphShape::Digit2 |
1433 GlyphShape::Digit3 |
1434 GlyphShape::Digit4 |
1435 GlyphShape::Digit5 |
1436 GlyphShape::Digit6 |
1437 GlyphShape::Digit7 |
1438 GlyphShape::Digit8 |
1439 GlyphShape::Digit9 |
1440 GlyphShape::A |
1441 GlyphShape::B |
1442 GlyphShape::C |
1443 GlyphShape::D |
1444 GlyphShape::E |
1445 GlyphShape::F |
1446 GlyphShape::G |
1447 GlyphShape::H |
1448 GlyphShape::I |
1449 GlyphShape::J |
1450 GlyphShape::K |
1451 GlyphShape::L |
1452 GlyphShape::M |
1453 GlyphShape::N |
1454 GlyphShape::O |
1455 GlyphShape::P |
1456 GlyphShape::Q |
1457 GlyphShape::R |
1458 GlyphShape::S |
1459 GlyphShape::T |
1460 GlyphShape::U |
1461 GlyphShape::V |
1462 GlyphShape::W |
1463 GlyphShape::X |
1464 GlyphShape::Y |
1465 GlyphShape::Z |
1466 GlyphShape::Alpha|
1467 GlyphShape::Beta |
1468 GlyphShape::Gamma |
1469 GlyphShape::Delta |
1470 GlyphShape::Epsilon |
1471 GlyphShape::Lambda |
1472 // Note: h is not allowed.
1473 GlyphShape::i |
1474 GlyphShape::j |
1475 GlyphShape::k |
1476 GlyphShape::n |
1477 GlyphShape::p |
1478 GlyphShape::q |
1479 GlyphShape::t |
1480 GlyphShape::w |
1481 GlyphShape::x |
1482 GlyphShape::y |
1483 GlyphShape::z |
1484 GlyphShape::Dot |
1485 GlyphShape::Apostrophe |
1486 GlyphShape::Underscore |
1487 GlyphShape::Overbar |
1488 GlyphShape::Square |
1489 GlyphShape::Circle => true,
1490 GlyphShape::Space => {
1491 // Space bar is allowed in a symex, per section 6-2.3.
1492 // But that doesn't necessarily mean that other space
1493 // characters are. However, we treat space and tab the
1494 // same, and don't include them in the symex syllable
1495 // token (instead we join symex syllables together in the
1496 // parser).
1497 true
1498 }
1499 _ => false,
1500 }
1501}