diff options
author | Aleksey Kladov <[email protected]> | 2018-01-28 09:06:26 +0000 |
---|---|---|
committer | Aleksey Kladov <[email protected]> | 2018-01-28 09:06:26 +0000 |
commit | cd4e13f10ac61805de41e73c7483f56624e8f5d2 (patch) | |
tree | 14c5716c9d97781275df68bae362d32796d5d0a2 /src | |
parent | 52104f7d250470bc35c640904ee2bc32633dbd7e (diff) |
Document events a bit
Diffstat (limited to 'src')
-rw-r--r-- | src/parser/event_parser/mod.rs | 48 |
1 files changed, 48 insertions, 0 deletions
diff --git a/src/parser/event_parser/mod.rs b/src/parser/event_parser/mod.rs index 65aea017b..1bb943b5d 100644 --- a/src/parser/event_parser/mod.rs +++ b/src/parser/event_parser/mod.rs | |||
@@ -4,17 +4,65 @@ use {SyntaxKind, Token}; | |||
4 | mod parser; | 4 | mod parser; |
5 | mod grammar; | 5 | mod grammar; |
6 | 6 | ||
7 | |||
8 | /// `Parser` produces a flat list of `Event`s. | ||
9 | /// They are converted to a tree-structure in | ||
10 | /// a separate pass, via `TreeBuilder`. | ||
7 | #[derive(Debug)] | 11 | #[derive(Debug)] |
8 | pub(crate) enum Event { | 12 | pub(crate) enum Event { |
13 | /// This event signifies the start of the node. | ||
14 | /// It should be either abandoned (in which case the | ||
15 | /// `kind` is `TOMBSTONE`, and the event is ignored), | ||
16 | /// or completed via a `Finish` event. | ||
17 | /// | ||
18 | /// All tokens between a `Start` and a `Finish` would | ||
19 | /// become the children of the respective node. | ||
20 | /// | ||
21 | /// For left-recursive syntactic constructs, the parser produces | ||
22 | /// a child node before it sees a parent. `forward_parent` | ||
23 | /// exists to allow to tweak parent-child relationships. | ||
24 | /// | ||
25 | /// Consider this path | ||
26 | /// | ||
27 | /// foo::bar | ||
28 | /// | ||
29 | /// The events for it would look like this: | ||
30 | /// | ||
31 | /// | ||
32 | /// START(PATH) IDENT('foo') FINISH START(PATH) COLONCOLON IDENT('bar') FINISH | ||
33 | /// | /\ | ||
34 | /// | | | ||
35 | /// +------forward-parent------+ | ||
36 | /// | ||
37 | /// And the tree would look like this | ||
38 | /// | ||
39 | /// +--PATH---------+ | ||
40 | /// | | | | ||
41 | /// | | | | ||
42 | /// | '::' 'bar' | ||
43 | /// | | ||
44 | /// PATH | ||
45 | /// | | ||
46 | /// 'foo' | ||
47 | /// | ||
48 | /// See also `CompleteMarker::precede`. | ||
9 | Start { | 49 | Start { |
10 | kind: SyntaxKind, | 50 | kind: SyntaxKind, |
11 | forward_parent: Option<u32>, | 51 | forward_parent: Option<u32>, |
12 | }, | 52 | }, |
53 | |||
54 | /// Complete the previous `Start` event | ||
13 | Finish, | 55 | Finish, |
56 | |||
57 | /// Produce a single leaf-element. | ||
58 | /// `n_raw_tokens` is used to glue complex contextual tokens. | ||
59 | /// For example, lexer tokenizes `>>` as `>`, `>`, and | ||
60 | /// `n_raw_tokens = 2` is used to produced a single `>>`. | ||
14 | Token { | 61 | Token { |
15 | kind: SyntaxKind, | 62 | kind: SyntaxKind, |
16 | n_raw_tokens: u8, | 63 | n_raw_tokens: u8, |
17 | }, | 64 | }, |
65 | |||
18 | Error { | 66 | Error { |
19 | message: String, | 67 | message: String, |
20 | }, | 68 | }, |