hide Query and QueryMatch private APIs (#1431)

also fixed a minor bug where CST query matches used to return
`undefined` instead of empty arrays for unmatched named captures.

Author: OmarTawfik

.changeset/tall-towns-tan.md

@@ -0,0 +1,5 @@
+---
+"@nomicfoundation/slang": patch
+---
+
+fix CST query matches to return an empty array for unmatched named captures, instead of `undefined`.

crates/codegen/runtime/cargo/crate/src/runtime/cst/mod.rs

@@ -23,7 +23,7 @@ pub use terminal_kind::TerminalKind;
 
 /// The base type of all nonterminals, terminals, and edges.
 #[derive(Clone, Debug, PartialEq, Eq, serde::Serialize)]
-pub enum KindTypes {
+pub struct KindTypes {
     // These derives are because default #[derive(...)] on a generic type implements only the trait
     // with default bounds also implied for the generic types as well, i.e.
     //
@@ -79,6 +79,10 @@ pub type AncestorsIterator = metaslang_cst::cursor::AncestorsIterator<KindTypes>
 /// for detailed information about the query syntax and how to use queries to find matches.
 pub type Query = metaslang_cst::query::Query<KindTypes>;
 
+/// A single capture matched by a query, containing the capture name,
+/// and a list of [`Cursor`]s to the location of each captured node in the parse tree.
+pub type Capture<'a> = metaslang_cst::query::Capture<'a, KindTypes>;
+
 pub use metaslang_cst::query::QueryError;
 /// Represents a match found by executing queries on a cursor.
 pub type QueryMatch = metaslang_cst::query::QueryMatch<KindTypes>;

crates/metaslang/cst/generated/public_api.txt

@@ -8,7 +8,6 @@ use super::model::{
     OptionalASTNode, Query, SequenceASTNode,
 };
 use crate::kinds::{KindTypes, NodeKind, TerminalKindExtensions};
-use crate::query::CaptureQuantifier;
 
 impl<T: KindTypes + 'static> Cursor<T> {
     /// Returns an iterator over all matches of the given queries in the syntax tree.
@@ -145,14 +144,10 @@ impl<T: KindTypes + 'static> ASTNode<T> {
 
 /// Represents a match found by executing queries on a cursor.
 pub struct QueryMatch<T: KindTypes> {
-    /// The queries that were matched.
-    pub queries: Rc<Vec<Query<T>>>,
-    /// The index of the matched query within the list of queries.
-    pub query_index: usize,
-    /// The cursor that was used to find the match.
-    pub root_cursor: Cursor<T>,
-    /// The capture definitions in the query
-    pub captures: BTreeMap<String, Vec<Cursor<T>>>,
+    queries: Rc<Vec<Query<T>>>,
+    query_index: usize,
+    root_cursor: Cursor<T>,
+    captures: BTreeMap<String, Vec<Cursor<T>>>,
 }
 
 impl<T: KindTypes> QueryMatch<T> {
@@ -161,46 +156,70 @@ impl<T: KindTypes> QueryMatch<T> {
         &self.queries[self.query_index]
     }
 
+    /// The index of the matched query within the list of queries.
+    pub fn query_index(&self) -> usize {
+        self.query_index
+    }
+
+    /// The cursor that was used to find the match.
+    pub fn root_cursor(&self) -> &Cursor<T> {
+        &self.root_cursor
+    }
+
     /// Returns an iterator over all of the capture names matched by this query.
     pub fn capture_names(&self) -> impl Iterator<Item = &String> {
-        self.query().capture_quantifiers.keys()
+        self.query().capture_quantifiers().keys()
     }
 
-    /// Returns an iterator over all of the captures matched by this query. The iterator item
-    /// is a 3-tuple containing the capture name, a [`CaptureQuantifier`], and an iterator yielding
-    /// a [`Cursor`] to the location of each capture in the parse tree.
-    pub fn captures(
-        &self,
-    ) -> impl Iterator<Item = (&String, CaptureQuantifier, impl Iterator<Item = Cursor<T>>)> {
-        let query = self.query();
-        query.capture_quantifiers.iter().map(|(name, quantifier)| {
-            let captures = self
-                .captures
-                .get(name)
-                .unwrap_or(&vec![])
-                .clone()
-                .into_iter();
-            (name, *quantifier, captures)
+    /// Returns an iterator over all of the captures matched by this query. Each [`Capture`] contains the capture name,
+    /// and a list of [`Cursor`]s to the location of each captured node in the parse tree.
+    pub fn captures(&self) -> impl Iterator<Item = Capture<'_, T>> {
+        self.query().capture_quantifiers().keys().map(|name| {
+            let cursors = match self.captures.get(name) {
+                Some(cursors) => &cursors[..],
+                None => &[],
+            };
+
+            Capture { name, cursors }
         })
     }
 
-    /// Try to find a single capture matched by this query. If no captures exist with the name `name`,
-    /// this will return `None`. If captures do exist, then this will return a tuple containing a [`CaptureQuantifier`]
-    /// and an iterator yielding a [`Cursor`] to the location of each capture in the parse tree.
-    pub fn capture(
-        &self,
-        name: &str,
-    ) -> Option<(CaptureQuantifier, impl Iterator<Item = Cursor<T>>)> {
-        let query = self.query();
-        query.capture_quantifiers.get(name).map(|quantifier| {
-            let captures = self
-                .captures
-                .get(name)
-                .unwrap_or(&vec![])
-                .clone()
-                .into_iter();
-            (*quantifier, captures)
-        })
+    /// Try to find a single capture matched by this query.
+    /// If no captures exist with the name `name`, this will return `None`.
+    /// If a capture does exist, then this will return a [`Capture`] containing the capture name,
+    /// and a list of [`Cursor`]s to the location of each captured node in the parse tree.
+    pub fn capture(&self, name: &str) -> Option<Capture<'_, T>> {
+        let name = self
+            .query()
+            .capture_quantifiers()
+            .keys()
+            .find(|key| key == &name)?;
+
+        let cursors = match self.captures.get(name) {
+            Some(cursors) => &cursors[..],
+            None => &[],
+        };
+
+        Some(Capture { name, cursors })
+    }
+}
+
+/// A single capture matched by a query, containing the capture name,
+/// and a list of [`Cursor`]s to the location of each captured node in the parse tree.
+pub struct Capture<'a, T: KindTypes> {
+    name: &'a str,
+    cursors: &'a [Cursor<T>],
+}
+
+impl<T: KindTypes> Capture<'_, T> {
+    /// The name of the capture.
+    pub fn name(&self) -> &str {
+        self.name
+    }
+
+    /// A list of cursors to the location of each captured node in the parse tree.
+    pub fn cursors(&self) -> &[Cursor<T>] {
+        self.cursors
     }
 }
 
@@ -225,7 +244,7 @@ impl<T: KindTypes + 'static> QueryMatchIterator<T> {
     fn advance_to_next_possible_matching_query(&mut self) {
         while !self.cursor.is_completed() {
             while self.query_index < self.queries.len() {
-                let ast_node = &self.queries[self.query_index].ast_node;
+                let ast_node = &self.queries[self.query_index].ast_node();
                 if ast_node.can_match(&self.cursor) {
                     // The first matcher in the query should allow implicit matches
                     self.matcher = Some(ast_node.create_matcher(self.cursor.clone(), false));

crates/metaslang/cst/src/query/engine.rs

@@ -4,6 +4,6 @@ mod engine;
 mod model;
 mod parser;
 
-pub use engine::{QueryMatch, QueryMatchIterator};
+pub use engine::{Capture, QueryMatch, QueryMatchIterator};
 pub use model::Query;
 pub use parser::{CaptureQuantifier, QueryError};

crates/metaslang/cst/src/query/mod.rs

@@ -17,10 +17,8 @@ use crate::text_index::TextIndex;
 /// for detailed information about the query syntax and how to use queries to find matches.
 #[derive(Clone, Debug)]
 pub struct Query<T: KindTypes> {
-    /// The abstract syntax tree (AST) representation of the query.
-    pub ast_node: ASTNode<T>,
-    /// A map of capture names to their quantifiers, used to define how many times a capture can occur.
-    pub capture_quantifiers: BTreeMap<String, CaptureQuantifier>,
+    ast_node: ASTNode<T>,
+    capture_quantifiers: BTreeMap<String, CaptureQuantifier>,
 }
 
 impl<T: KindTypes> Query<T> {
@@ -107,6 +105,16 @@ impl<T: KindTypes> Query<T> {
             capture_quantifiers,
         })
     }
+
+    /// The abstract syntax tree (AST) representation of the query.
+    pub(crate) fn ast_node(&self) -> &ASTNode<T> {
+        &self.ast_node
+    }
+
+    /// A map of capture names to their quantifiers, used to define how many times a capture can occur.
+    pub fn capture_quantifiers(&self) -> &BTreeMap<String, CaptureQuantifier> {
+        &self.capture_quantifiers
+    }
 }
 
 impl<T: KindTypes> fmt::Display for Query<T> {

crates/metaslang/cst/src/query/model.rs

@@ -163,7 +163,7 @@ impl<KT: KindTypes> ast::Stanza<KT> {
 
         let all_captures = self
             .query
-            .capture_quantifiers
+            .capture_quantifiers()
             .keys()
             .into_iter()
             .map(|cn| Identifier::from(cn.as_str()))
@@ -607,7 +607,7 @@ impl ast::Capture {
         ctx: &mut StanzaCheckContext<'_, KT>,
     ) -> Result<ExpressionResult, CheckError> {
         let name = self.name.to_string();
-        if let Some(quantifier) = ctx.stanza_query.capture_quantifiers.get(&name) {
+        if let Some(quantifier) = ctx.stanza_query.capture_quantifiers().get(&name) {
             self.quantifier = *quantifier;
             ctx.used_captures.insert(self.name.clone());
             Ok(ExpressionResult {

crates/metaslang/graph_builder/generated/public_api.txt

@@ -5,6 +5,7 @@
 // Please see the LICENSE-APACHE or LICENSE-MIT files in this distribution for license details.
 // ------------------------------------------------------------------------------------------------
 
+use metaslang_cst::cursor::Cursor;
 use metaslang_cst::kinds::KindTypes;
 use metaslang_cst::query::{CaptureQuantifier, QueryMatch};
 use thiserror::Error;
@@ -143,30 +144,16 @@ pub struct Match<KT: KindTypes> {
 impl<KT: KindTypes> Match<KT> {
     /// Return the top-level matched node.
     pub fn full_capture(&self) -> metaslang_cst::cursor::Cursor<KT> {
-        self.mat.root_cursor.clone()
+        self.mat.root_cursor().clone()
     }
 
     /// Return the matched nodes for a named capture.
-    pub fn named_captures(
-        &self,
-    ) -> impl Iterator<
-        Item = (
-            &String,
-            CaptureQuantifier,
-            impl Iterator<Item = metaslang_cst::cursor::Cursor<KT>>,
-        ),
-    > {
+    pub fn named_captures(&self) -> impl Iterator<Item = metaslang_cst::query::Capture<'_, KT>> {
         self.mat.captures()
     }
 
     /// Return the matched nodes for a named capture.
-    pub fn named_capture(
-        &self,
-        name: &str,
-    ) -> Option<(
-        CaptureQuantifier,
-        impl Iterator<Item = metaslang_cst::cursor::Cursor<KT>>,
-    )> {
+    pub fn named_capture(&self, name: &str) -> Option<metaslang_cst::query::Capture<'_, KT>> {
         self.mat.capture(name)
     }
 
@@ -248,27 +235,28 @@ impl CancellationFlag for NoCancellation {
 pub struct CancellationError(pub &'static str);
 
 impl Value {
-    pub fn from_nodes<KT: KindTypes, CI: IntoIterator<Item = metaslang_cst::cursor::Cursor<KT>>>(
+    pub fn from_nodes<KT: KindTypes>(
         graph: &mut Graph<KT>,
-        cursors: CI,
+        cursors: &[Cursor<KT>],
         quantifier: CaptureQuantifier,
     ) -> Value {
         let mut cursors = cursors.into_iter();
         match quantifier {
             CaptureQuantifier::One => {
-                let syntax_node = graph.add_syntax_node(cursors.next().expect("missing capture"));
+                let cursor = cursors.next().expect("missing capture").clone();
+                let syntax_node = graph.add_syntax_node(cursor);
                 syntax_node.into()
             }
             CaptureQuantifier::ZeroOrMore | CaptureQuantifier::OneOrMore => {
                 let syntax_nodes = cursors
-                    .map(|c| graph.add_syntax_node(c).into())
+                    .map(|c| graph.add_syntax_node(c.clone()).into())
                     .collect::<Vec<Value>>();
                 syntax_nodes.into()
             }
             CaptureQuantifier::ZeroOrOne => match cursors.next() {
                 None => Value::Null.into(),
                 Some(cursor) => {
-                    let syntax_node = graph.add_syntax_node(cursor);
+                    let syntax_node = graph.add_syntax_node(cursor.clone());
                     syntax_node.into()
                 }
             },