# **rfgrep TUI: Purpose, Design, and Implementation**
## **🎯 What is the TUI for?**
The **TUI (Terminal User Interface)** in rfgrep is designed to provide an **interactive, visual file search experience** directly in the terminal. It transforms rfgrep from a traditional command-line tool into a modern, interactive application that combines the power of command-line searching with the convenience of a graphical interface.
### **Primary Purpose**
- **Interactive File Search**: Provide a visual, interactive way to search through files
- **Real-time Results**: Show search results as they're found, with live updates
- **Visual Navigation**: Allow users to browse through files and matches visually
- **Enhanced User Experience**: Make file searching more intuitive and efficient
## **🖥️ How Should the TUI Work?**
### **1. Core Functionality**
#### **Interactive Search Interface**
```
┌─────────────────────────────────────────────────────────────┐
│ rfgrep TUI - Pattern: 'function' │ ← Header
├─────────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌─────────────────────────────────────────┐ │
│ │ Files │ │ Matches │ │ ← Dual-pane layout
│ │ ┌─────────┐ │ │ ┌─────┬─────────────────────────────────┐ │ │
│ │ │file1.rs │ │ │ │ 42 │ pub fn calculate_total() { │ │ │
│ │ │file2.rs │ │ │ │ 15 │ let result = function(); │ │ │
│ │ │file3.rs │ │ │ │ 78 │ function.call(); │ │ │
│ │ └─────────┘ │ │ └─────┴─────────────────────────────────┘ │ │
│ └─────────────┘ └─────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────┤
```
#### **Real-time Search Process**
1. **Pattern Input**: User enters search pattern (via CLI or interactively)
2. **Live Search**: TUI performs search across files in real-time
3. **Visual Results**: Shows results in organized, scrollable format
4. **Interactive Navigation**: User can navigate through files and matches
### **2. User Interface Design**
#### **Layout Structure**
- **Header**: Shows current search pattern and status
- **Main Content**: Split into two panes
- **Left Pane**: List of files containing matches
- **Right Pane**: Detailed matches with line numbers and content
- **Status Bar**: Shows statistics and current settings
- **Help Overlay**: Context-sensitive help (toggleable)
#### **Visual Elements**
- **Color Coding**: Different colors for selected items, matches, etc.
- **Highlighting**: Current selection highlighted in yellow
- **Scrollbars**: Visual indicators for scrollable content
- **Status Updates**: Real-time status messages
### **3. Interaction Model**
#### **Keyboard Controls**
| `h` | Toggle Help | Show/hide help overlay |
| `q` | Quit | Exit the TUI |
| `↑/↓` or `j/k` | Navigate Matches | Move through search results |
| `←/→` or `h/l` | Navigate Files | Switch between files |
| `n/N` | Next/Previous Match | Jump to next/previous match |
| `c` | Toggle Case | Toggle case sensitivity |
| `m` | Cycle Mode | Switch between Text/Word/Regex |
| `a` | Cycle Algorithm | Switch search algorithms |
| `r` | Refresh Search | Re-run current search |
| `Enter` | Open File | Open current file in editor |
| `Page Up/Down` | Scroll | Scroll through results |
#### **Search Modes**
- **Text Mode**: Plain text search (default)
- **Word Mode**: Whole word matching with boundaries
- **Regex Mode**: Regular expression search
#### **Algorithms**
- **Boyer-Moore**: Fast string matching (default)
- **Regex**: Regular expression engine
- **Simple**: Basic string search
- **SIMD**: Vectorized search for performance
### **4. Technical Implementation**
#### **Architecture**
```rust
pub struct TuiApp {
pub state: TuiState, // Application state
plugin_manager: Arc<EnhancedPluginManager>, // Search engine
streaming_pipeline: Option<StreamingSearchPipeline>, // Async search
list_state: ListState, // File list state
table_state: TableState, // Match table state
scrollbar_state: ScrollbarState, // Scrollbar state
should_quit: bool, // Exit flag
}
```
#### **State Management**
```rust
pub struct TuiState {
pub pattern: String, // Current search pattern
pub matches: Vec<SearchMatch>, // Search results
pub current_file_index: usize, // Selected file
pub current_match_index: usize, // Selected match
pub files: Vec<String>, // Files with matches
pub search_mode: SearchMode, // Text/Word/Regex
pub algorithm: SearchAlgorithm, // Search algorithm
pub case_sensitive: bool, // Case sensitivity
pub context_lines: usize, // Context around matches
pub show_help: bool, // Help overlay state
pub status_message: String, // Status bar message
pub search_in_progress: bool, // Search state
pub scroll_offset: usize, // Scroll position
}
```
### **5. Integration with rfgrep**
#### **CLI Integration**
```bash
# Basic TUI usage
rfgrep tui "search pattern"
# TUI with options
rfgrep tui "pattern" --algorithm regex --case-sensitive --path src/
# Interactive TUI (enter pattern later)
rfgrep tui
```
#### **Search Engine Integration**
- **Plugin System**: Uses rfgrep's plugin architecture
- **Async Search**: Non-blocking search operations
- **File Discovery**: Integrates with rfgrep's file walking
- **Result Processing**: Uses rfgrep's search result format
### **6. User Workflow**
#### **Typical Usage Flow**
1. **Launch TUI**: `rfgrep tui "pattern"` or `rfgrep tui`
2. **Search Execution**: TUI performs search across files
3. **Result Browsing**: User navigates through files and matches
4. **Interactive Refinement**: User can change settings and refresh
5. **File Access**: User can open files in external editor
6. **Exit**: User quits when done
#### **Advanced Usage**
1. **Pattern Refinement**: Change search pattern and refresh
2. **Mode Switching**: Switch between text/word/regex modes
3. **Algorithm Comparison**: Try different algorithms for performance
4. **Case Sensitivity**: Toggle case sensitivity on the fly
5. **Context Adjustment**: Change context lines around matches
### **7. Benefits of the TUI**
#### **For Users**
- **Visual Feedback**: See results immediately and visually
- **Interactive Exploration**: Browse through results interactively
- **Real-time Refinement**: Adjust search parameters on the fly
- **Efficient Navigation**: Quick access to files and specific matches
- **Context Awareness**: See surrounding code context
#### **For Developers**
- **Modern Interface**: Professional, modern terminal interface
- **Extensible Design**: Easy to add new features and controls
- **Performance**: Efficient rendering and search operations
- **Maintainable**: Clean, well-structured code
### **8. Design Principles**
#### **User Experience**
- **Intuitive**: Easy to learn and use
- **Responsive**: Fast, smooth interactions
- **Consistent**: Predictable behavior and controls
- **Accessible**: Full keyboard navigation
#### **Technical Design**
- **Modular**: Clean separation of concerns
- **Extensible**: Easy to add new features
- **Performant**: Efficient algorithms and rendering
- **Robust**: Comprehensive error handling
### **9. Future Enhancements**
#### **Planned Features**
- **Fuzzy Search**: Approximate string matching
- **Search History**: Previous search patterns
- **Bookmarks**: Save interesting matches
- **Export Results**: Save search results to file
- **Custom Themes**: User-configurable colors
- **Plugin Integration**: Extensible search plugins
#### **Advanced Features**
- **Multi-pattern Search**: Search for multiple patterns
- **Filtering**: Filter results by file type, size, etc.
- **Sorting**: Sort results by relevance, file, etc.
- **Preview**: Inline file preview without opening
## **🎯 Summary**
The rfgrep TUI is designed to be a **modern, interactive terminal interface** that transforms file searching from a command-line operation into a visual, interactive experience. It combines the power of rfgrep's search engine with the convenience of a graphical interface, providing users with:
- **Visual file search** with real-time results
- **Interactive navigation** through files and matches
- **Live parameter adjustment** for search refinement
- **Professional user experience** with modern terminal UI
- **Seamless integration** with rfgrep's existing functionality
The TUI represents a significant advancement in terminal-based file search tools, making rfgrep not just a powerful search tool, but a complete interactive file exploration platform.
---
*This design document outlines the purpose, functionality, and implementation of the rfgrep TUI as a modern, interactive terminal interface for file searching.*