Paradoxical 札记

Mon May 12 2025

#笔记 #Rust

最近把 neorg 作为笔记和规划系统有点上头，但苦于没一个好用的 Language Server，自己又对编译器前端方面略有了解于是决定写下这篇大概会持续更新的札记

我们的最终目的是实现一个不错的 Language Server 并且可以在 neovim/helix 上跑起来

为什么是 neovim/helix 呢？因为我暂时不会继续用 VSCode 了

流水线设计

考虑到我希望 paradoxical 有如下两个功能

重新格式化 neorg 文档
良好的补全

因此我决定采用如下流水线设计：

1
Text  →  Lexer (RawTokenKind)  →  CST  →  Typed AST/HIR  →  Semantic Analysis  →  LSP Server  →  Editor
2
| src |     Lazy Lexer         |  CST  |                 AST                   |

需要着重说明的是，我们使用 rope 来保存和编辑源文件，这样我们所有的操作的时间复杂度都是

目标

阶段 0

NOTE

该阶段起始于 2025-05-16

在阶段 0 需要实现最基本的功能：解析

但由于 neorg 的格式内容较多所以在这个阶段只考虑实现一个子集

标题
有序/无序列表
文本段
- 文本类型 Paragraph：这种类型允许使用 neorg 的修饰符例如 {} // $||$ 等，这些修饰符可以正常执行其对应的功能
- 逐字类型 VerbatimParagrah: 这种类型的文本段不会处理 neorg 的修饰符，所有输入的修饰符都应该原样输出
标签 Tag

NOTE

请注意，由于 neorg 设计上要求的非歧义解析，所有解析失败的内容都应该回归为 文本类型 Paragraph

`Token` 设计

基于 Token 的功能和现在的目标，我设计出如下的 RawTokenKind

1
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
2
pub enum RawTokenKind {
3
    Punct(char),
4
    NormalChar(char),
5
    Tag,
6
    Linending(LinendingKind),
7
}
8

9
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
10
pub enum LinendingKind {
11
    LF,
12
    CRLF,
13
}

以上的代码省略了对于 Display trait 的实现

`Token` 解析规则

我们使用 nom 这个库来实现解析，因为 neorg 的文档风格非常适合使用组合子解析器的方式进行解析。

不自己编写递归下降解析器是因为 neorg 的规范实际上比较简单，而且 neorg 的二义性情况很容易被判断，因此我们直接使用组合子解析器来实现解析就好

由于我们需要保留 Token 在文档里的位置信息，因此基于 RawTokenKind 派生出 RawToken，添加 span 字段保留当前 Token 的在文档里的位置信息（以偏移表示）

1
#[derive(Debug, Clone)]
2
pub struct RawToken {
3
    pub kind: RawTokenKind,
4
    pub span: Range<usize>,
5
}

接下来我们开始编写对于几个类型 Token 的组合子

1
pub const AVAILIABLE_PUNCT: &[char] = &['(', ')', '-', '~', '*', '/', '{', '}', '[', ']'];
2

3
fn parse_punct(input: Span) -> IResult<Span, RawToken> {
4
    let (input, pos) = position(input)?;
5
    let (input, matched) = nom::character::complete::one_of(AVAILIABLE_PUNCT)(input)?;
6

7
    let token = RawToken {
8
        kind: RawTokenKind::Punct(matched),
9
        span: pos.location_offset()..(pos.location_offset() + matched.len_utf8()),
10
    };
11

12
    Ok((input, token))
13
}
14

15
fn parse_normal_char(input: Span) -> IResult<Span, RawToken> {
16
    let (input, pos) = position(input)?;
17
    let (input, matched) = nom::character::complete::satisfy(|c| {
18
        !AVAILIABLE_PUNCT.contains(&c) && c != '@' && c != '\n' && c != '\r'
19
    })(input)?;
20

21
    let token = RawToken {
22
        kind: RawTokenKind::NormalChar(matched),
23
        span: pos.location_offset()..(pos.location_offset() + matched.len_utf8()),
24
    };
25

26
    Ok((input, token))
27
}
28

29
fn parse_tag(input: Span) -> IResult<Span, RawToken> {
30
    let (input, pos) = position(input)?;
31
    let (input, matched) = nom::character::complete::char('@')(input)?;
32

33
    let token = RawToken {
34
        kind: RawTokenKind::Tag,
35
        span: pos.location_offset()..(pos.location_offset() + matched.len_utf8()),
36
    };
37

38
    Ok((input, token))
39
}
40

41
fn parse_linending(input: Span) -> IResult<Span, RawToken> {
42
    let (input, pos) = position(input)?;
43
    let (input, ending) = nom::branch::alt((
44
        nom::combinator::map(nom::bytes::complete::tag("\n"), |_| LinendingKind::LF),
45
        nom::combinator::map(nom::bytes::complete::tag("\r\n"), |_| LinendingKind::CRLF),
46
    ))
47
    .parse(input)?;
48

49
    let token = RawToken {
50
        kind: RawTokenKind::Linending(ending),
51
        span: pos.location_offset()..(pos.location_offset() + ending.to_string().len()),
52
    };
53

54
    Ok((input, token))
55
}

对于 RawTokenKind::Tag 我们直接提取 @ 字符就好
对于 RawTokenKind::Linending 我们需要判断并且保留文档里的换行符类型
- \n：UNIX 平台所使用的换行符
- \r\n：Windows 平台所使用的换行符
对于其他的标点符号，我们引入一个常量 AVAILIABLE_PUNCT 表示可以出现在 RawTokenKind::Punct 内的字符（相当于白名单）
如果在以上情况之外，则归类为 RawTokenKind::NormalChar

因此，我们可以总结出如下的 lexer

1
let rope = Rope::from_str(source);
2
let mut tokens = Vec::new();
3
let mut input = Span::new(source);
4

5
let mut parsers = nom::branch::alt((
6
    Self::parse_tag,
7
    Self::parse_linending,
8
    Self::parse_punct,
9
    Self::parse_normal_char,
10
));
11

12
while !input.fragment().is_empty() {
13
    let Ok((rest, token)) = parsers.parse(input) else {
14
        return Err(error::Error::Lexer);
15
    };
16

17
    tokens.push(token);
18
    input = rest;
19
}
20

21
Ok(Self { text: rope, tokens })

单元测试也是不可少的一部分，因为包括对于中文的解析是略微麻烦也需要验证的

1
#[cfg(test)]
2
mod tests {
3
    use super::*;
4
    use crate::token::{LinendingKind, RawTokenKind};
5

6
    #[test]
7
    fn test_raw_document_parsing() {
8
        let input = "@hello\n-world\r\n";
9
        let doc = RawDocument::new(input).expect("Failed to parse document");
10

11
        let expected = vec![
12
            RawToken {
13
                kind: RawTokenKind::Tag,
14
                span: 0..1,
15
            },
16
            RawToken {
17
                kind: RawTokenKind::NormalChar('h'),
18
                span: 1..2,
19
            },
20
            RawToken {
21
                kind: RawTokenKind::NormalChar('e'),
22
                span: 2..3,
23
            },
24
            RawToken {
25
                kind: RawTokenKind::NormalChar('l'),
26
                span: 3..4,
27
            },
28
            RawToken {
29
                kind: RawTokenKind::NormalChar('l'),
30
                span: 4..5,
31
            },
32
            RawToken {
33
                kind: RawTokenKind::NormalChar('o'),
34
                span: 5..6,
35
            },
36
            RawToken {
37
                kind: RawTokenKind::Linending(LinendingKind::LF),
38
                span: 6..7,
39
            },
40
            RawToken {
41
                kind: RawTokenKind::Punct('-'),
42
                span: 7..8,
43
            },
44
            RawToken {
45
                kind: RawTokenKind::NormalChar('w'),
46
                span: 8..9,
47
            },
48
            RawToken {
49
                kind: RawTokenKind::NormalChar('o'),
50
                span: 9..10,
51
            },
52
            RawToken {
53
                kind: RawTokenKind::NormalChar('r'),
54
                span: 10..11,
55
            },
56
            RawToken {
57
                kind: RawTokenKind::NormalChar('l'),
58
                span: 11..12,
59
            },
60
            RawToken {
61
                kind: RawTokenKind::NormalChar('d'),
62
                span: 12..13,
63
            },
64
            RawToken {
65
                kind: RawTokenKind::Linending(LinendingKind::CRLF),
66
                span: 13..15,
67
            },
68
        ];
69

70
        assert_eq!(doc.tokens, expected);
71
    }
72

73
    #[test]
74
    fn test_raw_document_parsing_with_chinese() {
75
        let input = "@你好\n-世界\r\n";
76
        let doc = RawDocument::new(input).expect("Failed to parse document");
77

78
        let expected = vec![
79
            RawToken {
80
                kind: RawTokenKind::Tag,
81
                span: 0..1,
82
            },
83
            RawToken {
84
                kind: RawTokenKind::NormalChar('你'),
85
                span: 1..4,
86
            },
87
            RawToken {
88
                kind: RawTokenKind::NormalChar('好'),
89
                span: 4..7,
90
            },
91
            RawToken {
92
                kind: RawTokenKind::Linending(LinendingKind::LF),
93
                span: 7..8,
94
            },
95
            RawToken {
96
                kind: RawTokenKind::Punct('-'),
97
                span: 8..9,
98
            },
99
            RawToken {
100
                kind: RawTokenKind::NormalChar('世'),
101
                span: 9..12,
102
            },
103
            RawToken {
104
                kind: RawTokenKind::NormalChar('界'),
105
                span: 12..15,
106
            },
107
            RawToken {
108
                kind: RawTokenKind::Linending(LinendingKind::CRLF),
109
                span: 15..17,
110
            },
111
        ];
112

113
        assert_eq!(doc.tokens, expected);
114
    }
115
}

Paradoxical 札记

流水线设计

目标

阶段 0

Token 设计

Token 解析规则

`Token` 设计

`Token` 解析规则