Picleo

A fuzzy picker/matcher CLI using nucleo, as well as a library to implement this functionality in other programs.

Picleo was inspired by and is most similar to nucleo-picker but with different/expanded functionality e.g. selection of multiple items, and adding non-existing items to the "selection" that should be created.

Additionally, this crate is a test for AI coding using Aider and Claude 3.7 (at least initially). Code that is AI generated is marked with (aider) in the author field of git commit messages. Though all code is checked and refactored by the author.

Status

This is currently alpha phase software. It is feature incomplete compared to Skim, fzf, and other fuzzy finders, though it does handle some basic tasks.

The current development focus is on integrating this into a larger project as a selector widget. As such, it's unlikely to gain feature parity with other CLI fuzzy finders in the near future.

Features and TODOs

This is a mix of feature list and roadmap. Checked features are present in the current version. Unchecked features may be added in any order.

• Can handle selection of multiple items
• Can handle input on stdin
• List directory contents, with recursive option
• List file contents
• Preview command functionality
• Allows for the creation of new items not originally in the input
• Is fast for large numbers of items
• Allows the core functionality to be embedded in other software as a library
• Can wrap arbitrary object types and return the whole objects after matches
• Supports mouse scroll wheel
• Middle-click to toggle item selection
• Click on items to toggle item selection
• Running commands on selected entries
• Support config via args and file
• Add interactive modification of config options
  • displaying ASCII colors
  • column delimiters
  • columns to display
  • columns to output
  • post-processing commands for existing items
  • post-processing commands for requested items
• Builder pattern for config when used as a library
• Allows custom sorting and re-sorting of items
• Customizable headers and header lines
• Support multi-column chooser with column naming
• Choose columns to display with delimiter pattern
• Choose columns to output with join string
• Support prefix based filters and args e.g. title:
• Has filtering options for fields besides those shown and fuzzy matched against
• Need to ensure that we restore the normal screen before printing error messages on panic
• Add help command to remind users of available options in both search and editing mode
• Add default prefix to be used with/instead of autocomplete
• Allow non-prefixed output? Maybe this should be a flag or just allow it if the prefix is not set.
• When finishing editing, take the version with the prefix
• Make all selected matches sort to the top of the results...unless there are too many?
• Need to ensure that lines do not mess up display via multi-width chars or other odd bytes e.g. when asked to take the head of binary files
• Ensure that displayed lines fit within the space alloted
• Limit the amount of data read from commands to about what fits in the preview area
• Provide preview command variables e.g. &LINES
• Make preview command execution async
  • Cache command output for a few seconds so rapidly moving arrows up or down does not re-run commands unnecessarily
• Allow preview commands to interrogate the terminal to get proper size and width
• Add flag to run command in shell and respect shell functions and aliases if possible
• Update match as indexing completes
• Make autocomplete in editing mode case insensitive, or allow toggling
• Allow editing of the preview command without restarting picleo
• Allow specification of post-processing commands for
  • Selected items
  • Requested items (double check whether requested items exist, edit mode can add them)
  • Allow invoking processing commands with the entire output in one go
  • Also allow invoking processing commands with lines as separate, possible parallel invocations

Due to the excellent design of nucleo we are able to load matches in separate threads while the user starts searching. Currently, the --threaded option controls whether we perform item loads in separate threads. Only one thread is used to load arguments from STDIN while one thread per arg is used when passing file path arguments.

Usage

Picleo allows fuzzy finding of items from potentially enormous item lists. It's been tested with 300k+ items and the performance is good i.e. no user-noticeable delay.

• The currently selected item will be returned when pressing the return key.
• Multiple items can be selected by typing Tab or middle-clicking via the mouse.
• Escape causes picleo to exit and return nothing.

The TUI is rendered on STDERR in Alternate Screen Mode.

• Rendering on STDERR allows for easy redirection of the output on STDOUT into other files or programs.
• Alternate Screen mode is used so as not to interfere with other terminal output and scrollback.

Search Syntax

Picleo supports the fzf style search syntax that nucleo::pattern::AtomKind supports.

Picleo can currently be used in two modes:

Input Mode

Lines can be piped directly into picleo via STDIN.

ls | picleo

Directory Listing Mode

If one or more directories are specified on the command line, their contents will be listed in picleo. Recursive traversal can be achieved with the --recursive flag.

picleo --recursive ~/Movies