public API overhaul

.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,