public API overhaul (#647)

- rename `with_colour` to `with_color` as we are using a single `en-US`
locale in the entire project.
- use `SUPPORTED_VERSIONS.binary_search()` in `Language::new()`
- use functions instead of properties for expensive operations -> #628
- require specifying an initial offset when creating a CST cursor ->
#628

.changeset/weak-turkeys-lie.md

@@ -0,0 +1,5 @@
+---
+"@nomicfoundation/slang": minor
+---
+
+Require specifying an initial offset when creating a CST cursor.

crates/codegen/parser/runtime/src/cst.rs

@@ -46,8 +46,8 @@ impl Node {
         }
     }
 
-    pub fn cursor(&self) -> Cursor {
-        Cursor::new(self.clone())
+    pub fn create_cursor(&self, text_offset: TextIndex) -> Cursor {
+        Cursor::new(self.clone(), text_offset)
     }
 
     pub fn as_rule(&self) -> Option<&Rc<RuleNode>> {

crates/codegen/parser/runtime/src/cursor.rs

@@ -87,13 +87,13 @@ impl Iterator for Cursor {
 }
 
 impl Cursor {
-    pub(crate) fn new(node: Node) -> Self {
+    pub(crate) fn new(node: Node, text_offset: TextIndex) -> Self {
         Self {
             path: vec![],
             current: PathNode {
                 node,
                 child_number: 0,
-                text_offset: Default::default(),
+                text_offset,
             },
             is_completed: false,
         }

crates/codegen/parser/runtime/src/napi/napi_cst.rs

@@ -42,7 +42,7 @@ impl RuleNode {
         (&self.0.text_len).into()
     }
 
-    #[napi(getter, ts_return_type = "Array<cst.RuleNode | cst.TokenNode>")]
+    #[napi(ts_return_type = "Array<cst.RuleNode | cst.TokenNode>")]
     pub fn children(&self, env: Env) -> Vec<JsObject> {
         self.0
             .children
@@ -51,9 +51,11 @@ impl RuleNode {
             .collect()
     }
 
-    #[napi(getter, ts_return_type = "cursor.Cursor")]
-    pub fn cursor(&self) -> Cursor {
-        Cursor::new(RustNode::Rule(self.0.clone()).cursor())
+    #[napi(ts_return_type = "cursor.Cursor")]
+    pub fn create_cursor(&self, text_offset: TextIndex) -> Cursor {
+        RustNode::Rule(self.0.clone())
+            .create_cursor((&text_offset).into())
+            .into()
     }
 }
 
@@ -83,9 +85,11 @@ impl TokenNode {
         self.0.text.clone()
     }
 
-    #[napi(getter, ts_return_type = "cursor.Cursor")]
-    pub fn cursor(&self) -> Cursor {
-        Cursor::new(RustNode::Token(self.0.clone()).cursor())
+    #[napi(ts_return_type = "cursor.Cursor")]
+    pub fn create_cursor(&self, text_offset: TextIndex) -> Cursor {
+        RustNode::Token(self.0.clone())
+            .create_cursor((&text_offset).into())
+            .into()
     }
 }
 

crates/codegen/parser/runtime/src/napi/napi_cursor.rs

@@ -10,6 +10,12 @@ use napi_text_index::*;
 #[napi(namespace = "cursor")]
 pub struct Cursor(Box<RustCursor>);
 
+impl From<RustCursor> for Cursor {
+    fn from(value: RustCursor) -> Self {
+        Self(value.into())
+    }
+}
+
 #[napi(namespace = "cursor")]
 impl Cursor {
     pub(crate) fn new(cursor: RustCursor) -> Self {
@@ -41,7 +47,7 @@ impl Cursor {
         self.0.is_completed()
     }
 
-    #[napi(getter, ts_return_type = "cst.RuleNode | cst.TokenNode")]
+    #[napi(ts_return_type = "cst.RuleNode | cst.TokenNode")]
     pub fn node(&self, env: Env) -> JsObject {
         self.0.node().to_js(&env)
     }
@@ -56,7 +62,7 @@ impl Cursor {
         (&self.0.text_range()).into()
     }
 
-    #[napi(getter, ts_return_type = "Array<cst.RuleNode>")]
+    #[napi(ts_return_type = "Array<cst.RuleNode>")]
     pub fn path_rule_nodes(&self, env: Env) -> Vec<JsObject> {
         self.0
             .path_rule_nodes()

crates/codegen/parser/runtime/src/napi/napi_parse_error.rs

@@ -29,7 +29,7 @@ impl ParseError {
     }
 
     #[napi(namespace = "parse_error")]
-    pub fn to_error_report(&self, source_id: String, source: String, with_colour: bool) -> String {
-        self.0.to_error_report(&source_id, &source, with_colour)
+    pub fn to_error_report(&self, source_id: String, source: String, with_color: bool) -> String {
+        self.0.to_error_report(&source_id, &source, with_color)
     }
 }

crates/codegen/parser/runtime/src/napi/napi_parse_output.rs

@@ -14,12 +14,12 @@ impl From<RustParseOutput> for ParseOutput {
 
 #[napi(namespace = "parse_output")]
 impl ParseOutput {
-    #[napi(getter, ts_return_type = "cst.RuleNode | cst.TokenNode")]
-    pub fn parse_tree(&self, env: Env) -> napi::JsObject {
-        return self.0.parse_tree().to_js(&env);
+    #[napi(ts_return_type = "cst.RuleNode | cst.TokenNode")]
+    pub fn tree(&self, env: Env) -> napi::JsObject {
+        return self.0.tree().to_js(&env);
     }
 
-    #[napi(getter, ts_return_type = "Array<parse_error.ParseError>")]
+    #[napi(ts_return_type = "Array<parse_error.ParseError>")]
     pub fn errors(&self) -> Vec<napi_parse_error::ParseError> {
         self.0.errors().iter().map(|x| x.clone().into()).collect()
     }
@@ -28,4 +28,10 @@ impl ParseOutput {
     pub fn is_valid(&self) -> bool {
         self.0.is_valid()
     }
+
+    /// Creates a cursor that starts at the root of the parse tree.
+    #[napi(ts_return_type = "cursor.Cursor")]
+    pub fn create_tree_cursor(&self) -> napi_cursor::Cursor {
+        return self.0.create_tree_cursor().into();
+    }
 }

crates/codegen/parser/runtime/src/napi/napi_text_index.rs

@@ -20,6 +20,16 @@ impl From<&RustTextIndex> for TextIndex {
     }
 }
 
+impl From<&TextIndex> for RustTextIndex {
+    fn from(value: &TextIndex) -> Self {
+        Self {
+            utf8: value.utf8 as usize,
+            utf16: value.utf16 as usize,
+            char: value.char as usize,
+        }
+    }
+}
+
 #[napi(object, namespace = "text_index")]
 #[derive(Copy, Clone)]
 pub struct TextRange {

crates/codegen/parser/runtime/src/parse_error.rs

@@ -28,8 +28,8 @@ impl ParseError {
             .collect();
     }
 
-    pub fn to_error_report(&self, source_id: &str, source: &str, with_colour: bool) -> String {
-        return render_error_report(self, source_id, source, with_colour);
+    pub fn to_error_report(&self, source_id: &str, source: &str, with_color: bool) -> String {
+        return render_error_report(self, source_id, source, with_color);
     }
 }
 

crates/codegen/parser/runtime/src/parse_output.rs

@@ -1,4 +1,4 @@
-use super::{cst, parse_error::ParseError};
+use crate::{cst, cursor::Cursor, parse_error::ParseError};
 
 #[derive(Debug, PartialEq)]
 pub struct ParseOutput {
@@ -7,7 +7,7 @@ pub struct ParseOutput {
 }
 
 impl ParseOutput {
-    pub fn parse_tree(&self) -> cst::Node {
+    pub fn tree(&self) -> cst::Node {
         return self.parse_tree.clone();
     }
 
@@ -18,4 +18,9 @@ impl ParseOutput {
     pub fn is_valid(&self) -> bool {
         return self.errors.is_empty();
     }
+
+    /// Creates a cursor that starts at the root of the parse tree.
+    pub fn create_tree_cursor(&self) -> Cursor {
+        return self.parse_tree.create_cursor(Default::default());
+    }
 }

crates/codegen/parser/runtime/src/support/choice_helper.rs

@@ -146,7 +146,7 @@ pub fn total_not_skipped_span(result: &ParserResult) -> usize {
 
     nodes
         .iter()
-        .flat_map(cst::Node::cursor)
+        .flat_map(|node| cst::Node::create_cursor(node, Default::default()))
         .filter_map(|node| match node {
             cst::Node::Token(token) if token.kind != TokenKind::SKIPPED => Some(token.text.len()),
             _ => None,

crates/codegen/parser/runtime/src/support/parser_function.rs

@@ -95,7 +95,7 @@ where
                     debug_assert_eq!(
                         errors.len() > 0,
                         parse_tree
-                            .cursor()
+                            .create_cursor(Default::default())
                             .any(|x| x.as_token_with_kind(&[TokenKind::SKIPPED]).is_some())
                     );
 

crates/codegen/parser/runtime/src/support/parser_result.rs

@@ -93,7 +93,7 @@ impl Match {
     pub fn is_full_recursive(&self) -> bool {
         self.nodes
             .iter()
-            .flat_map(cst::Node::cursor)
+            .flat_map(|node| cst::Node::create_cursor(node, Default::default()))
             .all(|node| node.as_token_with_kind(&[TokenKind::SKIPPED]).is_none())
     }
 }

crates/codegen/parser/runtime/src/templates/language.rs.jinja2

@@ -49,7 +49,7 @@ impl Language {
     ];
 
     pub fn new(version: Version) -> std::result::Result<Self, Error> {
-        if Self::SUPPORTED_VERSIONS.contains(&version) {
+        if Self::SUPPORTED_VERSIONS.binary_search(&version).is_ok() {
             Ok(Self {
                 {%- for version in code.referenced_versions %}
                     version_is_at_least_{{ version | replace(from=".", to="_") }}: Version::new({{ version | split(pat=".") | join(sep=", ") }}) <= version,