How bensadeh/tailspin works
Main Components
• CLI Interface: Represented primarily by the files in src/cli (including command parsing, completions, and keyword processing). This is the entry point – it accepts command line arguments, flags (like --follow, --listen-command, and others), and options for customizing highlighting.
• Configuration & Theme Module: Shown in src/config and src/theme. These modules are responsible for reading and processing configuration files (like theme.toml) so that highlight styles and groups (e.g., dates, keywords, IP addresses) can be customized.
• Core Highlighter Logic: The heart lies in src/core. This module handles the actual log processing:
• It reads each log file line and uses various regular expressions (stored in src/core/highlighters) to detect and format parts of the log (e.g., dates, numbers, keywords).
• It includes common utilities (like normalization and splitting text) in src/core/utils and error handling in src/core/error.rs.
• Highlighter Builder: Found in src/highlighter_builder. This module aggregates built-in highlighters and possibly composes custom ones based on configuration or command-line parameters.
• Input/Output (I/O) Components: The IO part split into reading (src/io/reader) and writing/presenting (src/io/writer & src/io/presenter). The reader handles both file input and piped input (including the functionality for listening to other commands), whereas the presenter decides whether to output directly to stdout or to integrate with external utilities like the “less” pager.
• Utilities & Build Scripts: There are utility scripts (in the util directory) for generating documentation (man pages) and shell completions, which are useful for distribution and integration. Testing folders also exist to validate the core functionality.
Component Relationships and Data Flow
• Configuration Flow: Early in the execution path, the configuration module loads the default settings (and overrides from ~/.config/tailspin/theme.toml if provided) and passes the configuration to the core modules.
• Data Processing in the Core: The core module iterates line by line over the log file or live stream, using a series of regex-based highlighters. The highlighter builder helps by selecting the appropriate highlighters (either built-in or customized via the configuration) and applying them.
• I/O Flow: Processed (highlighted) data is handed off to the presenter. Depending on the parameters, it is either forwarded directly to stdout or piped through “less” (with navigation support such as following mode and search capabilities).
• External Dependencies: The system integrates with external tools, notably “less” (for paged display) and the manifold crate that provides underlying functionality for log highlighting.
Architectural Patterns & Design Principles
• Modular Separation: Components are separated into distinct modules (CLI, Core, Config, I/O, Theme). This clear, layered architecture reduces coupling.
• Pipeline/Data Flow: Highlighting is performed in a streaming pipeline – input is read, processed, and forwarded, which is ideal for log file processing.
• Extensibility: The design supports new highlighters, custom regexes, and additional configuration options without modifying the core processing loop.