From cd4e13f10ac61805de41e73c7483f56624e8f5d2 Mon Sep 17 00:00:00 2001 From: Aleksey Kladov Date: Sun, 28 Jan 2018 12:06:26 +0300 Subject: Document events a bit --- src/parser/event_parser/mod.rs | 48 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) (limited to 'src/parser') 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}; mod parser; mod grammar; + +/// `Parser` produces a flat list of `Event`s. +/// They are converted to a tree-structure in +/// a separate pass, via `TreeBuilder`. #[derive(Debug)] pub(crate) enum Event { + /// This event signifies the start of the node. + /// It should be either abandoned (in which case the + /// `kind` is `TOMBSTONE`, and the event is ignored), + /// or completed via a `Finish` event. + /// + /// All tokens between a `Start` and a `Finish` would + /// become the children of the respective node. + /// + /// For left-recursive syntactic constructs, the parser produces + /// a child node before it sees a parent. `forward_parent` + /// exists to allow to tweak parent-child relationships. + /// + /// Consider this path + /// + /// foo::bar + /// + /// The events for it would look like this: + /// + /// + /// START(PATH) IDENT('foo') FINISH START(PATH) COLONCOLON IDENT('bar') FINISH + /// | /\ + /// | | + /// +------forward-parent------+ + /// + /// And the tree would look like this + /// + /// +--PATH---------+ + /// | | | + /// | | | + /// | '::' 'bar' + /// | + /// PATH + /// | + /// 'foo' + /// + /// See also `CompleteMarker::precede`. Start { kind: SyntaxKind, forward_parent: Option, }, + + /// Complete the previous `Start` event Finish, + + /// Produce a single leaf-element. + /// `n_raw_tokens` is used to glue complex contextual tokens. + /// For example, lexer tokenizes `>>` as `>`, `>`, and + /// `n_raw_tokens = 2` is used to produced a single `>>`. Token { kind: SyntaxKind, n_raw_tokens: u8, }, + Error { message: String, }, -- cgit v1.2.3 From d3dedcace8a5fb1f047ecad05d23dce8745252d5 Mon Sep 17 00:00:00 2001 From: Aleksey Kladov Date: Sun, 28 Jan 2018 12:06:43 +0300 Subject: Document events a bit --- src/parser/event_parser/mod.rs | 1 - 1 file changed, 1 deletion(-) (limited to 'src/parser') diff --git a/src/parser/event_parser/mod.rs b/src/parser/event_parser/mod.rs index 1bb943b5d..7823c476c 100644 --- a/src/parser/event_parser/mod.rs +++ b/src/parser/event_parser/mod.rs @@ -4,7 +4,6 @@ use {SyntaxKind, Token}; mod parser; mod grammar; - /// `Parser` produces a flat list of `Event`s. /// They are converted to a tree-structure in /// a separate pass, via `TreeBuilder`. -- cgit v1.2.3