Struct Skim 

pub struct Skim<Backend = CrosstermBackend<BufWriter<Stderr>>>
where
    Backend: Backend,
    Backend::Error: Send + Sync + 'static,
{ /* private fields */ }

Main entry point for running skim

Implementations

impl Skim

pub fn run_with( options: SkimOptions, source: Option<SkimItemReceiver>, ) -> Result<SkimOutput>

Run skim, collecting items from the source and using options

Params

• options: the “complex” options that control how skim behaves
• source: a stream of items to be passed to skim for filtering. If None is given, skim will invoke the command given to fetch the items.

Returns

• None: on internal errors.
• SkimOutput: the collected key, event, query, selected items, etc.

Errors

Returns an error if skim initialization or the TUI loop fails.

Panics

Panics if the tui fails to initialize

pub fn run_items<I, T>(options: SkimOptions, items: I) -> Result<SkimOutput>

where I: IntoIterator<Item = T>, T: SkimItem,

Run skim with a Vec of items

Errors

Returns an error if sending items to the channel or running skim fails.

use skim::prelude::*;

let opts = SkimOptionsBuilder::default().multi(true).build().unwrap();
Skim::run_items(opts, ["foo", "bar"]);

pub fn init_tui(&mut self) -> Result<()>

Initialize the TUI with the default crossterm backend, but do not enter it yet

Errors

Returns an error if the TUI backend cannot be initialized.

pub fn new( options: SkimOptions, source: Option<SkimItemReceiver>, ) -> Result<Self>

Initialize and start skim without entering the terminal UI.

Errors

Returns an error if skim or the TUI backend cannot be initialized.

pub fn new_items<I, T>(options: SkimOptions, items: I) -> Result<Self>

where I: IntoIterator<Item = T>, T: SkimItem,

Initialize and start skim with items without entering the terminal UI.

Errors

Returns an error if sending items or initializing skim or its TUI fails.

impl<Backend: Backend + 'static> Skim<Backend>

where Backend::Error: Send + Sync + 'static,

pub fn init( options: SkimOptions, source: Option<SkimItemReceiver>, ) -> Result<Self>

Initialize skim, without starting anything yet

Errors

Returns an error if parsing the height or other options fails.

pub fn start(&mut self)

Start the reader and matcher, but do not enter the TUI yet

pub fn handle_reload(&mut self, new_cmd: &str)

Handle a reload event by killing the current reader, clearing items, and starting a new reader.

This encapsulates the reload logic from the main event loop so it can be reused by test harnesses without reimplementing it.

pub fn check_reader(&mut self) -> bool

Check if the reader has finished and restart the matcher if needed.

This encapsulates the reader-status check from the main event loop so it can be reused by test harnesses.

Returns true if the reader has completed.

pub fn reader_done(&self) -> bool

Returns true if the reader is done (has finished producing items).

pub fn matcher_stopped(&self) -> bool

Returns true if the matcher is stopped

pub fn init_tui_with(&mut self, tui: Tui<Backend>)

Initialize the TUI with a caller-provided instance.

Use this instead of init_tui() when you need a non-default backend (e.g. TestBackend for snapshot tests).

pub fn app(&self) -> &App

Returns a shared reference to the application state.

pub fn app_mut(&mut self) -> &mut App

Returns a mutable reference to the application state.

pub fn tui_ref(&self) -> &Tui<Backend>

Returns a shared reference to the TUI.

Panics

Panics if the TUI has not been initialized yet.

pub fn tui_mut(&mut self) -> &mut Tui<Backend>

Returns a mutable reference to the TUI.

Panics

Panics if the TUI has not been initialized yet.

pub fn app_and_tui(&mut self) -> (&mut App, &mut Tui<Backend>)

Returns mutable references to both the app and the TUI simultaneously.

This is useful when you need to call app.handle_event(tui, ...) or tui.draw(|frame| frame.render_widget(app, ...)), which require disjoint mutable borrows of both fields.

Panics

Panics if the TUI has not been initialized yet.

pub fn final_event(&self) -> &Event

Returns a shared reference to the final event that caused skim to quit.

pub fn event_sender(&self) -> Sender<Event>

Returns a clone of the TUI event sender.

Use this to send events (e.g. Event::Render, Event::Action) to the running skim instance from outside the event loop. The sender is cheap to clone and can be moved into async blocks or other tasks.

Must be called after init_tui().

Panics

Panics if init_tui has not been called before this method.

pub async fn enter(&mut self) -> Result<()>

Enter the TUI

Errors

Returns an error if the TUI cannot be entered or the input listener fails.

Panics

Panics if init_tui has not been called before this method.

Async

This will call init_listener, which requires a tokio runtime Though it is not technically async code, this is a good hint.

pub fn should_enter(&mut self) -> bool

Checks read-0 select-1, filter, and sync to wait and returns whether or not we should enter

Panics

Panics if start has not been called before this method.

pub fn output(self) -> SkimOutput

Capture self and extract the output This will perform cleanup

Panics

Panics if the selected items or current item cannot be retrieved.

pub fn should_quit(&self) -> bool

Returns true if skim has finished (the user accepted or aborted)

pub async fn tick(&mut self) -> Result<bool>

Process a single event loop iteration.

This awaits the next event from the TUI, matcher, or IPC listener, processes it, and returns. Use this in your own event loop when you need fine-grained control over the application lifecycle.

Returns Ok(true) if skim should quit, Ok(false) to continue.

Errors

Returns an error if the TUI cannot produce the next event or if event handling fails.

Panics

Panics if init_tui has not been called before this method.

Example

while !skim.tick().await? {
    // do your own work between ticks
}

pub async fn run(&mut self) -> Result<()>

Run the event loop on the current task until skim quits.

This is a convenience wrapper around tick() that loops until the user accepts or aborts. Use tick() directly if you need to interleave your own logic between iterations.

Errors

Returns an error if any tick in the event loop fails.

pub async fn run_until<F: Future + 'static>( self, user_task: F, ) -> Result<SkimOutput>

Spawn the event loop and run a user-provided future concurrently.

This consumes self, spawns the event loop as a local task, and runs user_task alongside it. When the user accepts or aborts in the TUI, the event loop completes and the SkimOutput is returned — regardless of whether user_task has finished.

Use this when you need to send items or do other work concurrently while the TUI is running.

Errors

Returns an error if the event loop or the task join fails.

Example

let output = skim.run_until(async {
    for i in 1..=10 {
        tx.send(vec![Arc::new(format!("item {i}"))]);
        tokio::time::sleep(Duration::from_millis(100)).await;
    }
}).await?;