roffman 0.4.0

Crate to generate ROFF files used for manual pages.
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

//!
//!
//!

pub fn escape<T: AsRef<str>>(text: T) -> String {
    let text = text.as_ref();
    let mut out = String::new();
    for token in text.chars().map(EscapeToken::from) {
        if let Some(ch) = token.unescaped_char() {
            out.push(ch);
        } else {
            out.push_str(token.escape_sequence());
        }
    }

    // Escapes dots at the beginning of the line so that they don't get interpreted as
    // roff macros.
    out.replace("\n.", "\n\\&.")
}

enum EscapeToken {
    Dash,
    LatinApostrophe,
    OpeningQuote,
    ClosingQuote,
    DoubleQuote,
    LeftDoubleQuote,
    RightDoubleQuote,
    GraveAccent,
    CircumflexAccent,
    ReverseSolidus,
    Tilde,
    Unescaped(char),
}

impl From<char> for EscapeToken {
    fn from(ch: char) -> Self {
        use EscapeToken::*;
        match ch {
            '-' => Dash,
            '\'' => LatinApostrophe,
            '‘' => OpeningQuote,
            '’' => ClosingQuote,
            '"' => DoubleQuote,
            '“' => LeftDoubleQuote,
            '”' => RightDoubleQuote,
            '`' => GraveAccent,
            '^' => CircumflexAccent,
            '\\' => ReverseSolidus,
            '~' => Tilde,
            ch => Unescaped(ch),
        }
    }
}

impl EscapeToken {
    fn escape_sequence(&self) -> &'static str {
        use EscapeToken::*;
        match self {
            Dash => "\\-",
            LatinApostrophe => "\\(aq",
            OpeningQuote => "\\(oq",
            ClosingQuote => "\\(cq",
            DoubleQuote => "\\(dq",
            LeftDoubleQuote => "\\(lq",
            RightDoubleQuote => "\\(rq",
            GraveAccent => "\\(ga",
            CircumflexAccent => "\\(ha",
            ReverseSolidus => "\\e",
            Tilde => "\\(ti",
            Unescaped(_) => "",
        }
    }

    fn unescaped_char(&self) -> Option<char> {
        if let EscapeToken::Unescaped(ch) = &self {
            Some(*ch)
        } else {
            None
        }
    }
}

#[cfg(test)]
mod tests {
    use super::escape;

    #[test]
    fn it_escapes() {
        let input = r#"~/docs/$ bash -c "awk '' ``""#;

        assert_eq!(
            escape(input),
            "\\(ti/docs/$ bash \\-c \\(dqawk \\(aq\\(aq \\(ga\\(ga\\(dq"
        );

        let dot_on_new_line = "\n.some dot on new line";

        assert_eq!(escape(dot_on_new_line), "\n\\&.some dot on new line")
    }
}