merge (helix-editor#12275) syntax symbol pickers

Author: nikvoid

Cargo.lock

@@ -26,3 +26,4 @@
   - [Adding indent queries](./guides/indent.md)
   - [Adding injection queries](./guides/injection.md)
   - [Adding rainbow bracket queries](./guides/rainbow_bracket_queries.md)
+  - [Adding symbols queries](./guides/symbols.md)

book/src/SUMMARY.md

@@ -103,10 +103,10 @@
 | `code_action` | Perform code action | normal: `` <space>a ``, select: `` <space>a `` |
 | `buffer_picker` | Open buffer picker | normal: `` <space>b ``, select: `` <space>b `` |
 | `jumplist_picker` | Open jumplist picker | normal: `` <space>j ``, select: `` <space>j `` |
-| `symbol_picker` | Open symbol picker | normal: `` <space>s ``, select: `` <space>s `` |
+| `symbol_picker` | Open symbol picker |  |
 | `changed_file_picker` | Open changed file picker | normal: `` <space>g ``, select: `` <space>g `` |
 | `select_references_to_symbol_under_cursor` | Select symbol references | normal: `` <space>h ``, select: `` <space>h `` |
-| `workspace_symbol_picker` | Open workspace symbol picker | normal: `` <space>S ``, select: `` <space>S `` |
+| `workspace_symbol_picker` | Open workspace symbol picker |  |
 | `diagnostics_picker` | Open diagnostic picker | normal: `` <space>d ``, select: `` <space>d `` |
 | `workspace_diagnostics_picker` | Open workspace diagnostic picker | normal: `` <space>D ``, select: `` <space>D `` |
 | `last_picker` | Open last picker | normal: `` <space>' ``, select: `` <space>' `` |
@@ -294,3 +294,7 @@
 | `extend_to_word` | Extend to a two-character label | select: `` gw `` |
 | `goto_next_tabstop` | goto next snippet placeholder |  |
 | `goto_prev_tabstop` | goto next snippet placeholder |  |
+| `syntax_symbol_picker` | Open a picker of symbols from the syntax tree |  |
+| `syntax_workspace_symbol_picker` | Open a picker of symbols for the workspace based on syntax trees |  |
+| `lsp_or_syntax_symbol_picker` | Open an LSP symbol picker if available, or syntax otherwise | normal: `` <space>s ``, select: `` <space>s `` |
+| `lsp_or_syntax_workspace_symbol_picker` | Open a workspace LSP symbol picker if available, or syntax workspace symbol picker otherwise | normal: `` <space>S ``, select: `` <space>S `` |

book/src/generated/static-cmd.md

@@ -0,0 +1,30 @@
+## Adding symbols queries
+
+Helix provides LSP-like features such as document and workspace symbol pickers
+which extract symbols only from the syntax of source files. To be analyzed a
+language must have a tree-sitter grammar and a `symbols.scm` query file which
+pattern matches symbols.
+
+Query files should be placed in `runtime/queries/{language}/symbols.scm`
+when contributing to Helix. You may place these under your local runtime
+directory (`~/.config/helix/runtime` in Linux for example) for the sake of
+testing.
+
+The following [captures][tree-sitter-captures] are recognized:
+
+| Capture name           |
+|---                     |
+| `definition.function`  |
+| `definition.macro`     |
+| `definition.module`    |
+| `definition.constant`  |
+| `definition.struct`    |
+| `definition.interface` |
+| `definition.type`      |
+| `definition.class`     |
+
+[Example query files][example-queries] can be found in the Helix GitHub
+repository.
+
+[tree-sitter-captures]: https://tree-sitter.github.io/tree-sitter/using-parsers#capturing-nodes
+[example-queries]: https://github.com/search?q=repo%3Ahelix-editor%2Fhelix+path%3A%2A%2A/symbols.scm&type=Code&ref=advsearch&l=&l=

book/src/guides/symbols.md

@@ -154,6 +154,8 @@ pub struct LanguageConfiguration {
     #[serde(skip)]
     pub(crate) indent_query: OnceCell<Option<Query>>,
     #[serde(skip)]
+    symbols_query: OnceCell<Option<Query>>,
+    #[serde(skip)]
     pub(crate) textobject_query: OnceCell<Option<TextObjectQuery>>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub debugger: Option<DebugAdapterConfig>,
@@ -804,6 +806,12 @@ impl LanguageConfiguration {
             .as_ref()
     }
 
+    pub fn symbols_query(&self) -> Option<&Query> {
+        self.symbols_query
+            .get_or_init(|| self.load_query("symbols.scm"))
+            .as_ref()
+    }
+
     pub fn textobject_query(&self) -> Option<&TextObjectQuery> {
         self.textobject_query
             .get_or_init(|| {
@@ -1491,6 +1499,51 @@ impl Syntax {
         QueryIter { layers }
     }
 
+    pub fn captures<'a>(
+        &'a self,
+        query: &'a Query,
+        source: RopeSlice<'a>,
+        range: Option<std::ops::Range<usize>>,
+    ) -> impl Iterator<Item = (QueryMatch<'a, 'a>, usize)> + 'a {
+        struct Captures<'a> {
+            // The query cursor must live as long as the captures iterator so
+            // we need to bind them together in this struct.
+            _cursor: QueryCursor,
+            captures: QueryCaptures<'a, 'a, RopeProvider<'a>, &'a [u8]>,
+        }
+
+        impl<'a> Iterator for Captures<'a> {
+            type Item = (QueryMatch<'a, 'a>, usize);
+
+            fn next(&mut self) -> Option<Self::Item> {
+                self.captures.next()
+            }
+        }
+
+        let mut cursor = PARSER.with(|ts_parser| {
+            let highlighter = &mut ts_parser.borrow_mut();
+            highlighter.cursors.pop().unwrap_or_default()
+        });
+
+        // The `captures` iterator borrows the `Tree` and the `QueryCursor`, which
+        // prevents them from being moved. But both of these values are really just
+        // pointers, so it's actually ok to move them.
+        let cursor_ref = unsafe {
+            mem::transmute::<&mut tree_sitter::QueryCursor, &mut tree_sitter::QueryCursor>(
+                &mut cursor,
+            )
+        };
+
+        cursor_ref.set_byte_range(range.clone().unwrap_or(0..usize::MAX));
+        cursor_ref.set_match_limit(TREE_SITTER_MATCH_LIMIT);
+
+        let captures = cursor_ref.captures(query, self.tree().root_node(), RopeProvider(source));
+        Captures {
+            _cursor: cursor,
+            captures,
+        }
+    }
+
     /// Iterate over the highlighted regions for a given slice of source code.
     pub fn highlight_iter<'a>(
         &'a self,

helix-core/src/syntax.rs

@@ -230,7 +230,12 @@ pub fn merge_toml_values(left: toml::Value, right: toml::Value, merge_depth: usi
 /// Otherwise (workspace, false) is returned
 pub fn find_workspace() -> (PathBuf, bool) {
     let current_dir = current_working_dir();
-    for ancestor in current_dir.ancestors() {
+    find_workspace_in(current_dir)
+}
+
+pub fn find_workspace_in(dir: impl AsRef<Path>) -> (PathBuf, bool) {
+    let dir = dir.as_ref();
+    for ancestor in dir.ancestors() {
         if ancestor.join(".git").exists()
             || ancestor.join(".svn").exists()
             || ancestor.join(".jj").exists()
@@ -240,7 +245,7 @@ pub fn find_workspace() -> (PathBuf, bool) {
         }
     }
 
-    (current_dir, true)
+    (dir.to_owned(), true)
 }
 
 fn default_config_file() -> PathBuf {

helix-loader/src/lib.rs

@@ -72,6 +72,8 @@ serde = { version = "1.0", features = ["derive"] }
 grep-regex = "0.1.13"
 grep-searcher = "0.1.14"
 
+dashmap = "6.0"
+
 [target.'cfg(not(windows))'.dependencies]  # https://github.com/vorner/signal-hook/issues/100
 signal-hook-tokio = { version = "0.3", features = ["futures-v0_3"] }
 libc = "0.2.169"

helix-term/Cargo.toml

@@ -1,5 +1,6 @@
 pub(crate) mod dap;
 pub(crate) mod lsp;
+pub(crate) mod syntax;
 pub(crate) mod typed;
 
 pub use dap::*;
@@ -11,6 +12,7 @@ use helix_stdx::{
 };
 use helix_vcs::{FileChange, Hunk};
 pub use lsp::*;
+pub use syntax::*;
 use tui::text::Span;
 pub use typed::*;
 
@@ -587,6 +589,10 @@ impl MappableCommand {
         extend_to_word, "Extend to a two-character label",
         goto_next_tabstop, "goto next snippet placeholder",
         goto_prev_tabstop, "goto next snippet placeholder",
+        syntax_symbol_picker, "Open a picker of symbols from the syntax tree",
+        syntax_workspace_symbol_picker, "Open a picker of symbols for the workspace based on syntax trees",
+        lsp_or_syntax_symbol_picker, "Open an LSP symbol picker if available, or syntax otherwise",
+        lsp_or_syntax_workspace_symbol_picker, "Open a workspace LSP symbol picker if available, or syntax workspace symbol picker otherwise",
     );
 }
 
@@ -6526,3 +6532,38 @@ fn jump_to_word(cx: &mut Context, behaviour: Movement) {
     }
     jump_to_label(cx, words, behaviour)
 }
+
+fn lsp_or_syntax_symbol_picker(cx: &mut Context) {
+    let doc = doc!(cx.editor);
+
+    if doc
+        .language_servers_with_feature(LanguageServerFeature::DocumentSymbols)
+        .next()
+        .is_some()
+    {
+        lsp::symbol_picker(cx);
+    } else if doc.syntax().is_some()
+        && doc
+            .language_config()
+            .is_some_and(|config| config.symbols_query().is_some())
+    {
+        syntax_symbol_picker(cx);
+    } else {
+        cx.editor
+            .set_error("No language server supporting document symbols or syntax info available");
+    }
+}
+
+fn lsp_or_syntax_workspace_symbol_picker(cx: &mut Context) {
+    let doc = doc!(cx.editor);
+
+    if doc
+        .language_servers_with_feature(LanguageServerFeature::WorkspaceSymbols)
+        .next()
+        .is_some()
+    {
+        lsp::workspace_symbol_picker(cx);
+    } else {
+        syntax_workspace_symbol_picker(cx);
+    }
+}