feat!: internally compute indexes at match time (removes get/set_index) (#1001)

* chore: remove skim::Item run_items wrapper

* fix: properly trigger re-render on custom previews

* feat: add AppendItems event

* feat!: internally compute indexes at match time (removes get/set_index)

* chore: generate completions & manpage

* chore: better benchmarks

---------

Co-authored-by: Skim bot <skim-bot@skim-rs.github.io>

Author: LoricAndre

benches/filter.rs

@@ -12,7 +12,7 @@ use skim::fuzzy_matcher::frizbee::FrizbeeMatcher;
 use skim::prelude::SkimMatcherV2;
 
 fn load_lines() -> Vec<String> {
-    let data = fs::read_to_string("benches/fixtures/1M.txt").expect("1M.txt missing");
+    let data = fs::read_to_string("benches/fixtures/100K.txt").expect("100K.txt missing");
     data.lines().map(|l| l.to_string()).collect()
 }
 

benches/matcher_micro.rs

@@ -5,7 +5,7 @@ fn main() -> color_eyre::Result<()> {
     let res = Skim::run_items(opts, ["hello", "world"])?;
 
     for item in res.selected_items {
-        println!("Selected {} (id {})", item.output(), item.get_index());
+        println!("Selected {} (id {})", item.output(), item.rank.index);
     }
 
     Ok(())

examples/base.rs

@@ -7,12 +7,13 @@ use std::io::Cursor;
 /// This example demonstrates how to bind custom action callbacks to keyboard shortcuts.
 ///
 /// It shows how to:
-/// 1. Create custom action callbacks
+/// 1. Create custom action callbacks (both sync and async)
 /// 2. Bind them to specific key combinations
 /// 3. Use them interactively in skim
 fn main() {
-    // Create a custom callback that adds a prefix to the query
-    let add_prefix_callback = ActionCallback::new(|app: &mut skim::tui::App| {
+    // Create a synchronous callback that adds a prefix to the query.
+    // Use `new_sync` for plain closures that do not need to await anything.
+    let add_prefix_callback = ActionCallback::new_sync(|app: &mut skim::tui::App| {
         // Get current query and add prefix
         let current_query = app.input.value.clone();
 
@@ -32,14 +33,17 @@ fn main() {
         Ok(events)
     });
 
-    // Create a callback that selects all and exits
+    // Create an async callback that selects all and exits.
+    // Use `new` for async closures or blocks that may await futures.
     let select_all_callback = ActionCallback::new(|app: &mut skim::tui::App| {
         let count = app.item_pool.len();
-
-        Ok(vec![
-            Event::Action(Action::SelectAll),
-            Event::Action(Action::Accept(Some(format!("Selected {count} items")))),
-        ])
+        async move {
+            // Async work could go here (e.g. HTTP requests, file I/O, …).
+            Ok(vec![
+                Event::Action(Action::SelectAll),
+                Event::Action(Action::Accept(Some(format!("Selected {count} items")))),
+            ])
+        }
     });
 
     // Build basic options

examples/custom_action_keybinding.rs

@@ -23,10 +23,12 @@ fn main() {
     let options = SkimOptionsBuilder::default()
         .height("50%")
         .multi(true)
-        .preview(String::new()) // preview should be specified to enable preview window
+        .preview("") // preview should be specified to enable preview window
         .build()
         .unwrap();
 
+    env_logger::init();
+
     let (tx_item, rx_item): (SkimItemSender, SkimItemReceiver) = unbounded();
     let _ = tx_item.send(vec![
         Arc::new(MyItem {

examples/custom_item.rs

@@ -7,7 +7,6 @@ use skim::prelude::*;
 #[derive(Debug, Clone)]
 struct Item {
     text: String,
-    index: usize,
 }
 
 impl SkimItem for Item {
@@ -18,14 +17,6 @@ impl SkimItem for Item {
     fn preview(&self, _context: PreviewContext) -> ItemPreview {
         ItemPreview::Text(self.text.to_owned())
     }
-
-    fn get_index(&self) -> usize {
-        self.index
-    }
-
-    fn set_index(&mut self, index: usize) {
-        self.index = index
-    }
 }
 
 pub fn main() {
@@ -39,18 +30,9 @@ pub fn main() {
     let (tx, rx): (SkimItemSender, SkimItemReceiver) = unbounded();
 
     tx.send(vec![
-        Arc::new(Item {
-            text: "a".into(),
-            index: 0,
-        }) as Arc<dyn SkimItem>,
-        Arc::new(Item {
-            text: "b".into(),
-            index: 1,
-        }) as Arc<dyn SkimItem>,
-        Arc::new(Item {
-            text: "c".into(),
-            index: 2,
-        }) as Arc<dyn SkimItem>,
+        Arc::new(Item { text: "a".into() }) as Arc<dyn SkimItem>,
+        Arc::new(Item { text: "b".into() }) as Arc<dyn SkimItem>,
+        Arc::new(Item { text: "c".into() }) as Arc<dyn SkimItem>,
     ])
     .unwrap();
 
@@ -60,7 +42,7 @@ pub fn main() {
         .map(|out| out.selected_items)
         .unwrap_or_default()
         .iter()
-        .map(|selected_item| (**selected_item).as_any().downcast_ref::<Item>().unwrap().to_owned())
+        .map(|selected_item| selected_item.downcast_item::<Item>().unwrap().to_owned())
         .collect::<Vec<Item>>();
 
     for item in selected_items {

examples/downcast.rs

@@ -258,7 +258,7 @@ _sk() {
                     return 0
                     ;;
                 --flags)
-                    COMPREPLY=($(compgen -W "no-preview-pty show-score" -- "${cur}"))
+                    COMPREPLY=($(compgen -W "no-preview-pty show-score show-index" -- "${cur}"))
                     return 0
                     ;;
                 --hscroll-off)

shell/completion.bash

@@ -88,7 +88,8 @@ complete -c sk -l tmux -d 'Run in a tmux popup' -r
 complete -c sk -l log-level -d 'Set the log level' -r
 complete -c sk -l log-file -d 'Pipe log output to a file' -r
 complete -c sk -l flags -d 'Feature flags' -r -f -a "no-preview-pty\t'Disable preview PTY on linux'
-show-score\t'Display the item\'s match score before its value in the item list (for matcher debugging)'"
+show-score\t'Display the item\'s match score before its value in the item list (for matcher debugging)'
+show-index\t'Display the item\'s index before its value in the item list'"
 complete -c sk -l hscroll-off -r
 complete -c sk -l jump-labels -r
 complete -c sk -l tail -r

shell/completion.fish

@@ -33,7 +33,7 @@ module completions {
   }
 
   def "nu-complete sk flags" [] {
-    [ "no-preview-pty" "show-score" ]
+    [ "no-preview-pty" "show-score" "show-index" ]
   }
 
   # Fuzzy Finder in rust!

shell/completion.nu

@@ -89,7 +89,8 @@ zsh\:"Zsh"))' \
 '--log-level=[Set the log level]:LOG_LEVEL:_default' \
 '--log-file=[Pipe log output to a file]:LOG_FILE:_default' \
 '*--flags=[Feature flags]:FLAGS:((no-preview-pty\:"Disable preview PTY on linux"
-show-score\:"Display the item'\''s match score before its value in the item list (for matcher debugging)"))' \
+show-score\:"Display the item'\''s match score before its value in the item list (for matcher debugging)"
+show-index\:"Display the item'\''s index before its value in the item list"))' \
 '--hscroll-off=[]:HSCROLL_OFF:_default' \
 '--jump-labels=[]:JUMP_LABELS:_default' \
 '--tail=[]:TAIL:_default' \