From 412ac63ff517c7eab5e1cfe0bf239616bd2c13a1 Mon Sep 17 00:00:00 2001
From: Aleksey Kladov <aleksey.kladov@gmail.com>
Date: Thu, 21 Feb 2019 15:24:42 +0300
Subject: docs
---
crates/ra_parser/src/event.rs | 7 +++---
crates/ra_parser/src/lib.rs | 46 +++++++++++++++++++++++++++++----------
crates/ra_parser/src/token_set.rs | 1 +
3 files changed, 39 insertions(+), 15 deletions(-)
(limited to 'crates/ra_parser')
diff --git a/crates/ra_parser/src/event.rs b/crates/ra_parser/src/event.rs
index d6e8454d4..6361d5d86 100644
--- a/crates/ra_parser/src/event.rs
+++ b/crates/ra_parser/src/event.rs
@@ -113,12 +113,11 @@ pub(super) fn process(sink: &mut dyn TreeSink, mut events: Vec<Event>) {
// append `B`'s forward_parent `C` in the next stage.
}
- for (j, kind) in forward_parents.drain(..).rev().enumerate() {
- let is_root_node = i == 0 && j == 0;
- sink.start_branch(kind, is_root_node);
+ for kind in forward_parents.drain(..).rev() {
+ sink.start_branch(kind);
}
}
- Event::Finish => sink.finish_branch(i == events.len() - 1),
+ Event::Finish => sink.finish_branch(),
Event::Token { kind, n_raw_tokens } => {
sink.leaf(kind, n_raw_tokens);
}
diff --git a/crates/ra_parser/src/lib.rs b/crates/ra_parser/src/lib.rs
index 7931b5189..ddc08e462 100644
--- a/crates/ra_parser/src/lib.rs
+++ b/crates/ra_parser/src/lib.rs
@@ -1,3 +1,17 @@
+//! The Rust parser.
+//!
+//! The parser doesn't know about concrete representation of tokens and syntax
+//! trees. Abstract `TokenSource` and `TreeSink` traits are used instead. As a
+//! consequence, this crates does not contain a lexer.
+//!
+//! The `Parser` struct from the `parser` module is a cursor into the sequence
+//! of tokens. Parsing routines use `Parser` to inspect current state and
+//! advance the parsing.
+//!
+//! The actual parsing happens in the `grammar` module.
+//!
+//! Tests for this crate live in `ra_syntax` crate.
+
#[macro_use]
mod token_set;
mod syntax_kind;
@@ -12,30 +26,34 @@ pub use syntax_kind::SyntaxKind;
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct ParseError(pub String);
+/// `TokenSource` abstracts the source of the tokens parser operates one.
+///
+/// Hopefully this will allow us to treat text and token trees in the same way!
+pub trait TokenSource {
+ /// What is the current token?
+ fn token_kind(&self, pos: usize) -> SyntaxKind;
+ /// Is the current token joined to the next one (`> >` vs `>>`).
+ fn is_token_joint_to_next(&self, pos: usize) -> bool;
+ /// Is the current token a specified keyword?
+ fn is_keyword(&self, pos: usize, kw: &str) -> bool;
+}
+
/// `TreeSink` abstracts details of a particular syntax tree implementation.
pub trait TreeSink {
/// Adds new leaf to the current branch.
fn leaf(&mut self, kind: SyntaxKind, n_tokens: u8);
/// Start new branch and make it current.
- fn start_branch(&mut self, kind: SyntaxKind, root: bool);
+ fn start_branch(&mut self, kind: SyntaxKind);
/// Finish current branch and restore previous
/// branch as current.
- fn finish_branch(&mut self, root: bool);
+ fn finish_branch(&mut self);
fn error(&mut self, error: ParseError);
}
-/// `TokenSource` abstracts the source of the tokens parser operates one.
-///
-/// Hopefully this will allow us to treat text and token trees in the same way!
-pub trait TokenSource {
- fn token_kind(&self, pos: usize) -> SyntaxKind;
- fn is_token_joint_to_next(&self, pos: usize) -> bool;
- fn is_keyword(&self, pos: usize, kw: &str) -> bool;
-}
-
+/// Parse given tokens into the given sink as a rust file.
pub fn parse(token_source: &dyn TokenSource, tree_sink: &mut dyn TreeSink) {
let mut p = parser::Parser::new(token_source);
grammar::root(&mut p);
@@ -43,9 +61,11 @@ pub fn parse(token_source: &dyn TokenSource, tree_sink: &mut dyn TreeSink) {
event::process(tree_sink, events);
}
+/// A parsing function for a specific braced-block.
pub struct Reparser(fn(&mut parser::Parser));
impl Reparser {
+ /// If the node is a braced block, return the corresponding `Reparser`.
pub fn for_node(
node: SyntaxKind,
first_child: Option<SyntaxKind>,
@@ -54,6 +74,10 @@ impl Reparser {
grammar::reparser(node, first_child, parent).map(Reparser)
}
+ /// Re-parse given tokens using this `Reparser`.
+ ///
+ /// Tokens must start with `{`, end with `}` and form a valid brace
+ /// sequence.
pub fn parse(self, token_source: &dyn TokenSource, tree_sink: &mut dyn TreeSink) {
let Reparser(r) = self;
let mut p = parser::Parser::new(token_source);
diff --git a/crates/ra_parser/src/token_set.rs b/crates/ra_parser/src/token_set.rs
index 24152a38a..79121b35f 100644
--- a/crates/ra_parser/src/token_set.rs
+++ b/crates/ra_parser/src/token_set.rs
@@ -1,5 +1,6 @@
use crate::SyntaxKind;
+/// A bit-set of `SyntaxKind`s
#[derive(Clone, Copy)]
pub(crate) struct TokenSet(u128);
--
cgit v1.2.3