shell_input

A high-performance, embedded-friendly input handling library for building interactive shell and REPL applications in Rust. Designed for both standard and no_std environments with configurable heap/stack allocation.

Features

• 🚀 Zero-Copy Input Processing - Efficient text buffer with inline editing using heapless data structures
• ⌨️ Comprehensive Key Binding Support - Full keyboard event handling including arrows, Ctrl combinations, and special keys
• 📜 Command History - Browsable command history with navigation (Up/Down/PageUp/PageDown)
• ✨ Smart Autocomplete - Real-time context-aware command completion with Tab cycling
• 🎨 Custom Rendering - Flexible display system for prompts, inline suggestions, and visual feedback
• 🔧 Embedded-Ready - Configurable compile-time buffer sizes with optional heap allocation
• 💡 Built-in Help System - Integrated command listing and inline shortcuts (#, ##, #h, etc.)
• 🎯 Generic Type System - Const generics for zero-runtime-cost configuration

Installation

Add this to your Cargo.toml:

[dependencies]
shell_input = "0.1.0"

Feature Flags

[dependencies.shell_input]
version = "0.1.0"
features = ["heap-history", "heap-input-buffer"]

• heap-history - Allocate history on the heap (default: stack)

• heap-input-buffer - Allocate input buffer on the heap (default: stack)

Type Parameters Explained

InputParser<NC, FNL, IML, HTC, HME>

• NC: Number of autocomplete candidates (max commands to suggest)
• FNL: Function Name Length - max characters used for autocomplete matching
• IML: Input Max Length - maximum characters in input buffer
• HTC: History Total Capacity - number of history entries
• HME: History Max Entry - maximum characters per history entry

Key Bindings

Editing

Navigation

Completion

Built-in Commands

The parser provides special hashtag-prefixed commands:

• #q - Quit/exit (returns false from parse_input)
• # - List available commands
• ## - Show full help (commands + shortcuts + arg types)
• #h - Display command history
• #c - Clear command history
• #N - Execute history entry at index N (e.g., #0, #5)

Architecture

shell_input/
├── input/
│   ├── buffer.rs      - InputBuffer: Text editing with cursor management
│   │                    • Insertion, deletion, cursor movement
│   │                    • Clear, overwrite operations
│   │                    • Bounded buffer with compile-time size
│   │
│   ├── key_reader.rs  - Key: Platform-specific keyboard event capture
│   │                    • Raw key reading (arrows, Ctrl, special keys)
│   │                    • Cross-platform abstraction layer
│   │
│   ├── parser.rs      - InputParser: Main orchestrator (primary API)
│   │                    • Command autocompletion engine
│   │                    • History navigation integration
│   │                    • Key binding dispatch
│   │                    • Built-in help system
│   │
│   └── renderer.rs    - DisplayRenderer: Terminal output
│                        • Prompt rendering with cursor positioning
│                        • ANSI escape sequences
│                        • Visual feedback (bell, boundary markers)
│
├── history/
│   └── mod.rs         - History: Command history with circular buffer
│                        • Up/Down navigation
│                        • PageUp/PageDown for first/last entry
│                        • Clear and indexed retrieval
│
├── autocomplete/
│   └── mod.rs         - Autocomplete: Real-time suggestion engine
│                        • Prefix matching with candidate cycling
│                        • Tab/Shift+Tab for forward/backward
│                        • Preserves text beyond match window
│
└── terminal/
    └── mod.rs         - Terminal: Low-level terminal control
                         • Raw mode management
                         • Terminal state restoration
                         • RAII-based cleanup

Design Philosophy

Embedded-First

All data structures use compile-time sizing with heapless collections, making the library suitable for embedded systems and no_std environments. Optional heap allocation features provide flexibility for standard applications.

Type-Safe Configuration

Const generics eliminate runtime configuration overhead and catch size mismatches at compile time:

// Compiler error if you try to store 128-char commands in 64-char history
let parser = InputParser::<10, 32, 64, 20, 128>::new(...);

Zero-Cost Abstractions

The library uses Rust's type system to ensure optimal performance:

• No dynamic dispatch
• Compile-time size checking
• Inline-friendly implementations
• Minimal allocations

Platform Support

Currently supports:

• Unix-like systems (Linux, macOS, BSD)
• Raw terminal mode input handling
• ANSI escape sequence rendering

Windows support is planned for future releases.

Performance Characteristics

• Input latency: < 1ms for key processing
• Memory footprint: Configurable, typically 1-4KB stack or heap
• No runtime allocations: After initialization (without heap features)
• Autocomplete: O(n) where n = number of candidates

Use Cases

• 🖥️ Interactive shell applications
• 🔧 REPL environments for embedded devices
• 🎮 Text-based game consoles
• 📟 CLI tools with advanced input requirements
• 🤖 Serial console interfaces
• 🔬 Debugging interfaces and test harnesses

Integration with Shell Framework

shell_input is designed as the core input layer and can be used standalone or as part of a larger shell framework. For complete shell applications with command dispatching, see the shell crate which provides a higher-level wrapper around InputParser.

Contributing

Contributions are welcome! Areas of interest:

• Windows platform support
• Additional key bindings
• Unicode input handling
• History persistence backends

Please submit issues and PRs to the repository.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Acknowledgments

Built with:

• heapless - Static data structures for embedded systems
• Raw terminal mode input handling
• ANSI escape sequences for rendering