feat: prepare public API for alpha release

- created a `slang_solidity::syntax` module, with sub-modules `nodes`, `parsing`, and `visitors`. - renamed `codegen_parser` to `codegen_syntax` accourdingly. - renamed `Visitable::visit()` to `Receiver::receive()` for correctness. - renamed `ParserOutput` to `ParseResult` to match. - changed a few internal helpers/constructors to `pub(crate)` instead. Tested using `cargo rustdoc`.
NomicFoundation · Mar 29, 2023 · 5a69f34 · 5a69f34
1 parent 32fb1ea
commit 5a69f34
Show file tree

Hide file tree

Showing 57 changed files with 686 additions and 680 deletions.
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,8 +1,8 @@
 [workspace]
 members = [
     "crates/codegen/ebnf",
-    "crates/codegen/parser",
-    "crates/codegen/parser_templates",
+    "crates/codegen/syntax",
+    "crates/codegen/syntax_templates",
     "crates/codegen/schema",
     "crates/codegen/spec",
     "crates/codegen/testing",
@@ -29,7 +29,7 @@ ariadne = { version = "0.2.0" }
 bson = { version = "2.6.1" }
 clap = { version = "4.1.13", features = ["derive"] }
 codegen_ebnf = { path = "crates/codegen/ebnf" }
-codegen_parser = { path = "crates/codegen/parser" }
+codegen_syntax = { path = "crates/codegen/syntax" }
 codegen_schema = { path = "crates/codegen/schema" }
 codegen_spec = { path = "crates/codegen/spec" }
 codegen_testing = { path = "crates/codegen/testing" }

diff --git a/crates/codegen/parser/Cargo.toml → crates/codegen/syntax/Cargo.toml b/crates/codegen/parser/Cargo.toml → crates/codegen/syntax/Cargo.toml
@@ -1,5 +1,5 @@
 [package]
-name = "codegen_parser"
+name = "codegen_syntax"
 version.workspace = true
 rust-version.workspace = true
 edition.workspace = true

diff --git a/crates/codegen/parser/src/char_set.rs → crates/codegen/syntax/src/char_set.rs b/crates/codegen/parser/src/char_set.rs → crates/codegen/syntax/src/char_set.rs
diff --git a/crates/codegen/parser/src/code_generator.rs → crates/codegen/syntax/src/code_generator.rs b/crates/codegen/parser/src/code_generator.rs → crates/codegen/syntax/src/code_generator.rs
@@ -285,11 +285,11 @@ impl CodeGenerator {
             .map(|(name, parser)| {
                 let kind = format_ident!("{name}");
                 let internal_function_name = format_ident!("parse_{name}", name = name.to_snake_case());
-                let (functions, dispatch_function_name) = parser.to_function_body(&internal_function_name, quote! {ParseResult});
+                let (functions, dispatch_function_name) = parser.to_function_body(&internal_function_name, quote! {ParserResult});
                 if parser.is_defined_for_all_versions() {
                     let internal_function = quote! {
                         #[inline]
-                        pub(crate) fn #internal_function_name(&self, stream: &mut Stream) -> ParseResult {
+                        pub(crate) fn #internal_function_name(&self, stream: &mut Stream) -> ParserResult {
                             match self.#dispatch_function_name(stream) {
                                 Pass{ node, error } => Pass{ node: cst::Node::top_level_rule(RuleKind::#kind, node), error },
                                 fail => fail
@@ -300,7 +300,7 @@ impl CodeGenerator {
                 } else {
                     let external_function_name = format_ident!("maybe_parse_{name}", name = name.to_snake_case());
                     let external_function = quote! {
-                        pub(crate) fn #external_function_name(&self, stream: &mut Stream) -> Option<ParseResult> {
+                        pub(crate) fn #external_function_name(&self, stream: &mut Stream) -> Option<ParserResult> {
                             self.#dispatch_function_name(stream).map(|body|
                                 match body {
                                     Pass{ node, error } => Pass{ node: cst::Node::top_level_rule(RuleKind::#kind, node), error },
@@ -311,7 +311,7 @@ impl CodeGenerator {
                     };
                     let internal_function = quote! {
                         #[inline]
-                        pub(crate) fn #internal_function_name(&self, stream: &mut Stream) -> ParseResult {
+                        pub(crate) fn #internal_function_name(&self, stream: &mut Stream) -> ParserResult {
                             self.#external_function_name(stream).expect("Validation should have checked that references are valid between versions")
                         }
                     };
@@ -377,14 +377,14 @@ impl CodeGenerator {
         codegen.track_input_dir(
             &codegen
                 .repo_root
-                .join("crates/codegen/parser_templates/src"),
+                .join("crates/codegen/syntax_templates/src"),
         );
 
         codegen
             .copy_file(
                 &codegen
                     .repo_root
-                    .join("crates/codegen/parser_templates/src/shared/cst.rs"),
+                    .join("crates/codegen/syntax_templates/src/shared/cst.rs"),
                 &output_dir.join("cst.rs"),
             )
             .unwrap();
@@ -393,7 +393,7 @@ impl CodeGenerator {
             .read_file(
                 &codegen
                     .repo_root
-                    .join("crates/codegen/parser_templates/src/shared/macros.rs"),
+                    .join("crates/codegen/syntax_templates/src/shared/macros.rs"),
             )
             .unwrap();
 
@@ -422,7 +422,7 @@ impl CodeGenerator {
             let content = format!(
                 "
                 use super::language::*;
-                use super::language::ParseResult::*;
+                use super::language::ParserResult::*;
 
                 {scanning_macros}
                     

diff --git a/.../codegen/parser/src/combinator_context.rs → .../codegen/syntax/src/combinator_context.rs b/.../codegen/parser/src/combinator_context.rs → .../codegen/syntax/src/combinator_context.rs
diff --git a/crates/codegen/parser/src/combinator_node.rs → crates/codegen/syntax/src/combinator_node.rs b/crates/codegen/parser/src/combinator_node.rs → crates/codegen/syntax/src/combinator_node.rs
diff --git a/crates/codegen/parser/src/combinator_tree.rs → crates/codegen/syntax/src/combinator_tree.rs b/crates/codegen/parser/src/combinator_tree.rs → crates/codegen/syntax/src/combinator_tree.rs
diff --git a/crates/codegen/parser/src/first_set.rs → crates/codegen/syntax/src/first_set.rs b/crates/codegen/parser/src/first_set.rs → crates/codegen/syntax/src/first_set.rs
diff --git a/crates/codegen/parser/src/grammar.rs → crates/codegen/syntax/src/grammar.rs b/crates/codegen/parser/src/grammar.rs → crates/codegen/syntax/src/grammar.rs
diff --git a/crates/codegen/parser/src/lib.rs → crates/codegen/syntax/src/lib.rs b/crates/codegen/parser/src/lib.rs → crates/codegen/syntax/src/lib.rs
diff --git a/...gen/parser/src/rust_lib_code_generator.rs → ...gen/syntax/src/rust_lib_code_generator.rs b/...gen/parser/src/rust_lib_code_generator.rs → ...gen/syntax/src/rust_lib_code_generator.rs
@@ -35,7 +35,7 @@ impl CodeGenerator {
             .copy_file(
                 &codegen
                     .repo_root
-                    .join("crates/codegen/parser_templates/src/rust/cst_visitor.rs"),
+                    .join("crates/codegen/syntax_templates/src/rust/cst_visitor.rs"),
                 &output_dir.join("cst_visitor.rs"),
             )
             .unwrap();
@@ -44,7 +44,7 @@ impl CodeGenerator {
             .copy_file(
                 &codegen
                     .repo_root
-                    .join("crates/codegen/parser_templates/src/rust/parser_output.rs"),
+                    .join("crates/codegen/syntax_templates/src/rust/parser_output.rs"),
                 &output_dir.join("parser_output.rs"),
             )
             .unwrap();
@@ -83,15 +83,15 @@ impl CodeGenerator {
                         &self.version
                     }}
 
-                    pub fn parse(&self, production_kind: ProductionKind, input: &str) -> ParserOutput {{
+                    pub fn parse(&self, production_kind: ProductionKind, input: &str) -> ParseResult {{
                         let output = match production_kind {{
                             {scanner_invocations},
                             {parser_invocations},
                         }};
                         
                         output.unwrap_or_else(|| {{
                             let message = format!(\"ProductionKind {{production_kind}} is not valid in this version of {grammar_title}\");
-                            ParserOutput {{
+                            ParseResult {{
                                 parse_tree: None,
                                 errors: vec![ParseError::new(0, message)]
                             }}
@@ -103,7 +103,7 @@ impl CodeGenerator {
                     .read_file(
                         &codegen
                             .repo_root
-                            .join("crates/codegen/parser_templates/src/shared/language.rs"),
+                            .join("crates/codegen/syntax_templates/src/shared/language.rs"),
                     )
                     .unwrap(),
                 version_flag_declarations = self.version_flag_declarations(),

diff --git a/crates/codegen/parser/src/to_parser_code.rs → crates/codegen/syntax/src/to_parser_code.rs b/crates/codegen/parser/src/to_parser_code.rs → crates/codegen/syntax/src/to_parser_code.rs
diff --git a/crates/codegen/parser/src/to_scanner_code.rs → crates/codegen/syntax/src/to_scanner_code.rs b/crates/codegen/parser/src/to_scanner_code.rs → crates/codegen/syntax/src/to_scanner_code.rs
diff --git a/crates/codegen/parser/src/trie.rs → crates/codegen/syntax/src/trie.rs b/crates/codegen/parser/src/trie.rs → crates/codegen/syntax/src/trie.rs
diff --git a/...rser/src/typescript_lib_code_generator.rs → ...ntax/src/typescript_lib_code_generator.rs b/...rser/src/typescript_lib_code_generator.rs → ...ntax/src/typescript_lib_code_generator.rs
@@ -35,7 +35,7 @@ impl CodeGenerator {
             .copy_file(
                 &codegen
                     .repo_root
-                    .join("crates/codegen/parser_templates/src/typescript/cst_types.rs"),
+                    .join("crates/codegen/syntax_templates/src/typescript/cst_types.rs"),
                 &output_dir.join("cst_types.rs"),
             )
             .unwrap();
@@ -44,7 +44,7 @@ impl CodeGenerator {
             .copy_file(
                 &codegen
                     .repo_root
-                    .join("crates/codegen/parser_templates/src/typescript/parser_output.rs"),
+                    .join("crates/codegen/syntax_templates/src/typescript/parser_output.rs"),
                 &output_dir.join("parser_output.rs"),
             )
             .unwrap();
@@ -83,7 +83,7 @@ impl CodeGenerator {
                     }}
 
                     #[napi]
-                    pub fn parse(&self, production_kind: ProductionKind, input: String) -> ParserOutput {{
+                    pub fn parse(&self, production_kind: ProductionKind, input: String) -> ParseResult {{
                         let input = input.as_str();
                         match production_kind {{
                             {scanner_invocations},
@@ -96,7 +96,7 @@ impl CodeGenerator {
                     .read_file(
                         &codegen
                             .repo_root
-                            .join("crates/codegen/parser_templates/src/shared/language.rs"),
+                            .join("crates/codegen/syntax_templates/src/shared/language.rs"),
                     )
                     .unwrap(),
                 version_flag_declarations = self.version_flag_declarations(),

diff --git a/crates/codegen/parser_templates/Cargo.toml → crates/codegen/syntax_templates/Cargo.toml b/crates/codegen/parser_templates/Cargo.toml → crates/codegen/syntax_templates/Cargo.toml
@@ -1,5 +1,5 @@
 [package]
-name = "codegen_parser_templates"
+name = "codegen_syntax_templates"
 version.workspace = true
 rust-version.workspace = true
 edition.workspace = true

diff --git a/crates/codegen/parser_templates/src/lib.rs → crates/codegen/syntax_templates/src/lib.rs b/crates/codegen/parser_templates/src/lib.rs → crates/codegen/syntax_templates/src/lib.rs
diff --git a/.../parser_templates/src/rust/cst_visitor.rs → .../syntax_templates/src/rust/cst_visitor.rs b/.../parser_templates/src/rust/cst_visitor.rs → .../syntax_templates/src/rust/cst_visitor.rs
@@ -61,21 +61,21 @@ pub enum VisitorExitResponse {
     StepIn,
 }
 
-pub trait Visitable<T: Visitor<E>, E> {
-    fn visit(&self, visitor: &mut T) -> Result<VisitorExitResponse, E>;
-    fn visit_with_path(
+pub trait Receiver<T: Visitor<E>, E> {
+    fn receive(&self, visitor: &mut T) -> Result<VisitorExitResponse, E>;
+    fn receive_with_path(
         &self,
         visitor: &mut T,
         path: &mut Vec<Rc<Node>>,
     ) -> Result<VisitorExitResponse, E>;
 }
 
-impl<T: Visitor<E>, E> Visitable<T, E> for Rc<Node> {
-    fn visit(&self, visitor: &mut T) -> Result<VisitorExitResponse, E> {
-        self.visit_with_path(visitor, &mut Vec::new())
+impl<T: Visitor<E>, E> Receiver<T, E> for Rc<Node> {
+    fn receive(&self, visitor: &mut T) -> Result<VisitorExitResponse, E> {
+        self.receive_with_path(visitor, &mut Vec::new())
     }
 
-    fn visit_with_path(
+    fn receive_with_path(
         &self,
         visitor: &mut T,
         path: &mut Vec<Rc<Node>>,
@@ -92,7 +92,7 @@ impl<T: Visitor<E>, E> Visitable<T, E> for Rc<Node> {
                     VisitorEntryResponse::StepIn => {
                         path.push(self.clone());
                         for child in children {
-                            match child.visit_with_path(visitor, path)? {
+                            match child.receive_with_path(visitor, path)? {
                                 VisitorExitResponse::Quit => {
                                     path.pop();
                                     return Ok(VisitorExitResponse::Quit);
@@ -116,7 +116,7 @@ impl<T: Visitor<E>, E> Visitable<T, E> for Rc<Node> {
                     VisitorEntryResponse::StepIn => {
                         path.push(self.clone());
                         for child in trivia {
-                            match child.visit_with_path(visitor, path)? {
+                            match child.receive_with_path(visitor, path)? {
                                 VisitorExitResponse::Quit => {
                                     path.pop();
                                     return Ok(VisitorExitResponse::Quit);

diff --git a/...odegen/parser_templates/src/rust/kinds.rs → ...odegen/syntax_templates/src/rust/kinds.rs b/...odegen/parser_templates/src/rust/kinds.rs → ...odegen/syntax_templates/src/rust/kinds.rs
diff --git a/.../codegen/parser_templates/src/rust/mod.rs → .../codegen/syntax_templates/src/rust/mod.rs b/.../codegen/parser_templates/src/rust/mod.rs → .../codegen/syntax_templates/src/rust/mod.rs
diff --git a/...arser_templates/src/rust/parser_output.rs → ...yntax_templates/src/rust/parser_output.rs b/...arser_templates/src/rust/parser_output.rs → ...yntax_templates/src/rust/parser_output.rs
@@ -6,12 +6,12 @@ use super::{
 };
 
 #[derive(PartialEq)]
-pub struct ParserOutput {
+pub struct ParseResult {
     pub(crate) parse_tree: Option<Rc<cst::Node>>,
     pub(crate) errors: Vec<ParseError>,
 }
 
-impl ParserOutput {
+impl ParseResult {
     pub fn parse_tree(&self) -> Option<Rc<cst::Node>> {
         self.parse_tree.clone()
     }

diff --git a/...odegen/parser_templates/src/shared/cst.rs → ...odegen/syntax_templates/src/shared/cst.rs b/...odegen/parser_templates/src/shared/cst.rs → ...odegen/syntax_templates/src/shared/cst.rs
@@ -51,7 +51,8 @@ impl Node {
         }
     }
 
-    pub fn rule(kind: RuleKind, children: Vec<Rc<Self>>) -> Rc<Self> {
+    #[allow(dead_code)]
+    pub(crate) fn rule(kind: RuleKind, children: Vec<Rc<Self>>) -> Rc<Self> {
         let mut flattened_children: Vec<Rc<Self>> = Vec::new();
         for child in children.into_iter() {
             match child.as_ref() {
@@ -97,7 +98,8 @@ impl Node {
         });
     }
 
-    pub fn token(
+    #[allow(dead_code)]
+    pub(crate) fn token(
         kind: TokenKind,
         range: Range<usize>,
         leading_trivia: Option<Rc<Self>>,
@@ -117,7 +119,8 @@ impl Node {
         })
     }
 
-    pub fn top_level_rule(kind: RuleKind, node: Rc<Self>) -> Rc<Self> {
+    #[allow(dead_code)]
+    pub(crate) fn top_level_rule(kind: RuleKind, node: Rc<Self>) -> Rc<Self> {
         match node.as_ref() {
             Self::Rule {
                 kind: RuleKind::_SEQUENCE,