crates/parser/src/lib.rs

   1 //! The Rust parser.
   2 //!
   3 //! The parser doesn't know about concrete representation of tokens and syntax
   4 //! trees. Abstract [`TokenSource`] and [`TreeSink`] traits are used instead.
   5 //! As a consequence, this crate does not contain a lexer.
   6 //!
   7 //! The [`Parser`] struct from the [`parser`] module is a cursor into the
   8 //! sequence of tokens.  Parsing routines use [`Parser`] to inspect current
   9 //! state and advance the parsing.
  10 //!
  11 //! The actual parsing happens in the [`grammar`] module.
  12 //!
  13 //! Tests for this crate live in the `syntax` crate.
  14 //!
  15 //! [`Parser`]: crate::parser::Parser
  16 #![allow(rustdoc::private_intra_doc_links)]
  17
  18 mod token_set;
  19 mod syntax_kind;
  20 mod event;
  21 mod parser;
  22 mod grammar;
  23
  24 pub(crate) use token_set::TokenSet;
  25
  26 pub use syntax_kind::SyntaxKind;
  27
  28 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
  29 pub struct ParseError(pub Box<String>);
  30
  31 /// `TokenSource` abstracts the source of the tokens parser operates on.
  32 ///
  33 /// Hopefully this will allow us to treat text and token trees in the same way!
  34 pub trait TokenSource {
  35     fn current(&self) -> Token;
  36
  37     /// Lookahead n token
  38     fn lookahead_nth(&self, n: usize) -> Token;
  39
  40     /// bump cursor to next token
  41     fn bump(&mut self);
  42
  43     /// Is the current token a specified keyword?
  44     fn is_keyword(&self, kw: &str) -> bool;
  45 }
  46
  47 /// `Token` abstracts the cursor of `TokenSource` operates on.
  48 #[derive(Debug, Copy, Clone, Eq, PartialEq)]
  49 pub struct Token {
  50     /// What is the current token?
  51     pub kind: SyntaxKind,
  52
  53     /// Is the current token joined to the next one (`> >` vs `>>`).
  54     pub is_jointed_to_next: bool,
  55 }
  56
  57 /// `TreeSink` abstracts details of a particular syntax tree implementation.
  58 pub trait TreeSink {
  59     /// Adds new token to the current branch.
  60     fn token(&mut self, kind: SyntaxKind, n_tokens: u8);
  61
  62     /// Start new branch and make it current.
  63     fn start_node(&mut self, kind: SyntaxKind);
  64
  65     /// Finish current branch and restore previous
  66     /// branch as current.
  67     fn finish_node(&mut self);
  68
  69     fn error(&mut self, error: ParseError);
  70 }
  71
  72 /// rust-analyzer parser allows you to choose one of the possible entry points.
  73 ///
  74 /// The primary consumer of this API are declarative macros, `$x:expr` matchers
  75 /// are implemented by calling into the parser with non-standard entry point.
  76 #[derive(Debug, Clone, Copy, Eq, PartialEq, Hash)]
  77 pub enum ParserEntryPoint {
  78     SourceFile,
  79     Path,
  80     Expr,
  81     Statement,
  82     StatementOptionalSemi,
  83     Type,
  84     Pattern,
  85     Item,
  86     Block,
  87     Visibility,
  88     MetaItem,
  89     Items,
  90     Statements,
  91     Attr,
  92 }
  93
  94 /// Parse given tokens into the given sink as a rust file.
  95 pub fn parse_source_file(token_source: &mut dyn TokenSource, tree_sink: &mut dyn TreeSink) {
  96     parse(token_source, tree_sink, ParserEntryPoint::SourceFile);
  97 }
  98
  99 pub fn parse(
 100     token_source: &mut dyn TokenSource,
 101     tree_sink: &mut dyn TreeSink,
 102     entry_point: ParserEntryPoint,
 103 ) {
 104     let entry_point: fn(&'_ mut parser::Parser) = match entry_point {
 105         ParserEntryPoint::SourceFile => grammar::entry_points::source_file,
 106         ParserEntryPoint::Path => grammar::entry_points::path,
 107         ParserEntryPoint::Expr => grammar::entry_points::expr,
 108         ParserEntryPoint::Type => grammar::entry_points::type_,
 109         ParserEntryPoint::Pattern => grammar::entry_points::pattern,
 110         ParserEntryPoint::Item => grammar::entry_points::item,
 111         ParserEntryPoint::Block => grammar::entry_points::block_expr,
 112         ParserEntryPoint::Visibility => grammar::entry_points::visibility,
 113         ParserEntryPoint::MetaItem => grammar::entry_points::meta_item,
 114         ParserEntryPoint::Statement => grammar::entry_points::stmt,
 115         ParserEntryPoint::StatementOptionalSemi => grammar::entry_points::stmt_optional_semi,
 116         ParserEntryPoint::Items => grammar::entry_points::macro_items,
 117         ParserEntryPoint::Statements => grammar::entry_points::macro_stmts,
 118         ParserEntryPoint::Attr => grammar::entry_points::attr,
 119     };
 120
 121     let mut p = parser::Parser::new(token_source);
 122     entry_point(&mut p);
 123     let events = p.finish();
 124     event::process(tree_sink, events);
 125 }
 126
 127 /// A parsing function for a specific braced-block.
 128 pub struct Reparser(fn(&mut parser::Parser));
 129
 130 impl Reparser {
 131     /// If the node is a braced block, return the corresponding `Reparser`.
 132     pub fn for_node(
 133         node: SyntaxKind,
 134         first_child: Option<SyntaxKind>,
 135         parent: Option<SyntaxKind>,
 136     ) -> Option<Reparser> {
 137         grammar::reparser(node, first_child, parent).map(Reparser)
 138     }
 139
 140     /// Re-parse given tokens using this `Reparser`.
 141     ///
 142     /// Tokens must start with `{`, end with `}` and form a valid brace
 143     /// sequence.
 144     pub fn parse(self, token_source: &mut dyn TokenSource, tree_sink: &mut dyn TreeSink) {
 145         let Reparser(r) = self;
 146         let mut p = parser::Parser::new(token_source);
 147         r(&mut p);
 148         let events = p.finish();
 149         event::process(tree_sink, events);
 150     }
 151 }