asp/keep
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: Add comprehensive rustdoc to filter plugin modules

Browse Source 
Co-authored-by: aider (openai/andrew/openrouter/sonoma-sky-alpha) <aider@aider.chat>
This commit is contained in:
Andrew Phillips
2025-09-10 10:46:39 -03:00
parent d894f686a1
commit edfe0fcd6e
8 changed files with 219 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
src/filter_plugin/exec.rs
View File

@@ -4,6 +4,7 @@ use std::process::{Command, Stdio, Child};
use which::which;
use log::*;
/// A filter that executes an external program and pipes input through it.
#[derive(Debug, Clone)]
pub struct ExecFilter {
program: String,
@@ -16,6 +17,13 @@ pub struct ExecFilter {
}
impl ExecFilter {
/// Creates a new `ExecFilter` for the specified program and arguments.
///
/// # Arguments
///
/// * `program` - The name or path of the program to execute.
/// * `args` - The arguments to pass to the program.
/// * `split_whitespace` - Whether to split arguments on whitespace.
pub fn new(
program: &str,
args: Vec<&str>,
@@ -37,6 +45,12 @@ impl ExecFilter {
}
impl FilterPlugin for ExecFilter {
/// Filters the input by piping it through the external program and writing the output.
///
/// # Arguments
///
/// * `reader` - The input reader.
/// * `writer` - The output writer.
fn filter(&mut self, mut reader: Box<&mut dyn Read>, mut writer: Box<&mut dyn Write>) -> Result<()> {
if !self.supported {
return Err(std::io::Error::new(
@@ -146,6 +160,7 @@ impl FilterPlugin for ExecFilter {
Ok(())
}
/// Clones this filter into a new boxed instance.
fn clone_box(&self) -> Box<dyn FilterPlugin> {
Box::new(ExecFilter {
program: self.program.clone(),
@@ -158,6 +173,7 @@ impl FilterPlugin for ExecFilter {
})
}
/// Returns the configuration options for this filter.
fn options(&self) -> Vec<FilterOption> {
vec![
FilterOption {

18
src/filter_plugin/grep.rs
View File

@@ -2,11 +2,21 @@ use super::{FilterPlugin, FilterOption};
use std::io::{Result, Read, Write, BufRead};
use regex::Regex;
/// A filter that matches lines against a regular expression pattern.
pub struct GrepFilter {
regex: Regex,
}
impl GrepFilter {
/// Creates a new `GrepFilter` with the specified regex pattern.
///
/// # Arguments
///
/// * `pattern` - The regular expression pattern to match.
///
/// # Errors
///
/// Returns an error if the pattern is invalid.
pub fn new(pattern: String) -> Result<Self> {
let regex = Regex::new(&pattern)
.map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidInput, e))?;
@@ -17,6 +27,12 @@ impl GrepFilter {
}
impl FilterPlugin for GrepFilter {
/// Filters the input by writing only lines that match the regex pattern.
///
/// # Arguments
///
/// * `reader` - The input reader.
/// * `writer` - The output writer.
fn filter(&mut self, mut reader: Box<&mut dyn Read>, mut writer: Box<&mut dyn Write>) -> Result<()> {
let mut buf_reader = std::io::BufReader::new(&mut *reader);
for line in buf_reader.by_ref().lines() {
@@ -28,12 +44,14 @@ impl FilterPlugin for GrepFilter {
Ok(())
}
/// Clones this filter into a new boxed instance.
fn clone_box(&self) -> Box<dyn FilterPlugin> {
Box::new(Self {
regex: self.regex.clone(),
})
}
/// Returns the configuration options for this filter.
fn options(&self) -> Vec<FilterOption> {
vec![
FilterOption {

28
src/filter_plugin/head.rs
View File

@@ -3,11 +3,17 @@ use std::io::{Result, Read, Write, BufRead};
use crate::common::PIPESIZE;
use crate::services::filter_service::register_filter_plugin;
/// A filter that reads the first N bytes from the input stream.
pub struct HeadBytesFilter {
remaining: usize,
}
impl HeadBytesFilter {
/// Creates a new `HeadBytesFilter` that will read up to the specified number of bytes.
///
/// # Arguments
///
/// * `count` - The maximum number of bytes to read.
pub fn new(count: usize) -> Self {
Self {
remaining: count,
@@ -16,6 +22,12 @@ impl HeadBytesFilter {
}
impl FilterPlugin for HeadBytesFilter {
/// Filters the input by reading only the first N bytes and writing them to the output.
///
/// # Arguments
///
/// * `reader` - The input reader.
/// * `writer` - The output writer.
fn filter(&mut self, mut reader: Box<&mut dyn Read>, mut writer: Box<&mut dyn Write>) -> Result<()> {
if self.remaining == 0 {
return Ok(());
@@ -34,12 +46,14 @@ impl FilterPlugin for HeadBytesFilter {
Ok(())
}
/// Clones this filter into a new boxed instance.
fn clone_box(&self) -> Box<dyn FilterPlugin> {
Box::new(Self {
remaining: self.remaining,
})
}
/// Returns the configuration options for this filter.
fn options(&self) -> Vec<FilterOption> {
vec![
FilterOption {
@@ -51,11 +65,17 @@ impl FilterPlugin for HeadBytesFilter {
}
}
/// A filter that reads the first N lines from the input stream.
pub struct HeadLinesFilter {
remaining: usize,
}
impl HeadLinesFilter {
/// Creates a new `HeadLinesFilter` that will read up to the specified number of lines.
///
/// # Arguments
///
/// * `count` - The maximum number of lines to read.
pub fn new(count: usize) -> Self {
Self {
remaining: count,
@@ -64,6 +84,12 @@ impl HeadLinesFilter {
}
impl FilterPlugin for HeadLinesFilter {
/// Filters the input by reading only the first N lines and writing them to the output.
///
/// # Arguments
///
/// * `reader` - The input reader.
/// * `writer` - The output writer.
fn filter(&mut self, mut reader: Box<&mut dyn Read>, mut writer: Box<&mut dyn Write>) -> Result<()> {
if self.remaining == 0 {
return Ok(());
@@ -81,12 +107,14 @@ impl FilterPlugin for HeadLinesFilter {
Ok(())
}
/// Clones this filter into a new boxed instance.
fn clone_box(&self) -> Box<dyn FilterPlugin> {
Box::new(Self {
remaining: self.remaining,
})
}
/// Returns the configuration options for this filter.
fn options(&self) -> Vec<FilterOption> {
vec![
FilterOption {

74
src/filter_plugin/mod.rs
View File

@@ -17,6 +17,7 @@ pub use skip::{SkipBytesFilter, SkipLinesFilter};
pub use grep::GrepFilter;
pub use strip_ansi::StripAnsiFilter;
/// Represents an option for a filter plugin.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, utoipa::ToSchema)]
pub struct FilterOption {
pub name: String,
@@ -25,13 +26,26 @@ pub struct FilterOption {
pub required: bool,
}
/// Trait for filter plugins that process input streams.
pub trait FilterPlugin: Send {
/// Processes the input stream and writes the filtered output.
///
/// # Arguments
///
/// * `reader` - The input reader.
/// * `writer` - The output writer.
///
/// # Returns
///
/// A `Result` indicating success or failure.
fn filter(&mut self, reader: Box<&mut dyn Read>, writer: Box<&mut dyn Write>) -> Result<()>;
/// Clones this plugin into a new boxed instance.
fn clone_box(&self) -> Box<dyn FilterPlugin>;
// Get the filter options definition
/// Returns the configuration options for this plugin.
fn options(&self) -> Vec<FilterOption>;
}
/// Enum representing the different types of filters.
#[derive(Debug, EnumString, strum::VariantNames, strum::Display)]
#[strum(serialize_all = "snake_case")]
pub enum FilterType {
@@ -45,11 +59,13 @@ pub enum FilterType {
StripAnsi,
}
/// A chain of filter plugins applied sequentially.
pub struct FilterChain {
plugins: Vec<Box<dyn FilterPlugin>>,
}
impl Clone for FilterChain {
/// Clones this filter chain.
fn clone(&self) -> Self {
let mut plugins = Vec::with_capacity(self.plugins.len());
for plugin in &self.plugins {
@@ -60,22 +76,35 @@ impl Clone for FilterChain {
}
impl Clone for Box<dyn FilterPlugin> {
/// Clones the boxed filter plugin.
fn clone(&self) -> Self {
self.clone_box()
}
}
impl FilterChain {
/// Creates a new empty filter chain.
pub fn new() -> Self {
Self {
plugins: Vec::new(),
}
}
/// Adds a plugin to the chain.
pub fn add_plugin(&mut self, plugin: Box<dyn FilterPlugin>) {
self.plugins.push(plugin);
}
/// Applies the filter chain to the input and writes to the output.
///
/// # Arguments
///
/// * `reader` - The input reader.
/// * `writer` - The output writer.
///
/// # Returns
///
/// A `Result` indicating success or failure.
pub fn filter(&mut self, reader: &mut dyn Read, writer: &mut dyn Write) -> Result<()> {
if self.plugins.is_empty() {
// If no plugins, just copy the input to output
@@ -112,7 +141,15 @@ impl FilterChain {
}
}
// Helper function to parse filter string and create appropriate plugins
/// Parses a filter string into a `FilterChain`.
///
/// # Arguments
///
/// * `filter_str` - The filter string (e.g., "head_lines(10)|grep(pattern=error)").
///
/// # Returns
///
/// A `Result` containing the parsed `FilterChain` or an error if invalid.
pub fn parse_filter_string(filter_str: &str) -> Result<FilterChain> {
let mut chain = FilterChain::new();
@@ -183,7 +220,17 @@ pub fn parse_filter_string(filter_str: &str) -> Result<FilterChain> {
Ok(chain)
}
// Helper function to create filter with proper option handling
/// Creates a filter plugin with the given options.
///
/// # Arguments
///
/// * `filter_type` - The type of filter to create.
/// * `unnamed_params` - Unnamed parameters.
/// * `named_options` - Named options.
///
/// # Returns
///
/// A `Result` containing the boxed filter plugin.
fn create_filter_with_options(
filter_type: FilterType,
unnamed_params: &[serde_json::Value],
@@ -250,7 +297,16 @@ fn create_filter_with_options(
create_specific_filter(filter_type, &options)
}
// Helper to create specific filter instances based on options
/// Creates a specific filter instance based on type and options.
///
/// # Arguments
///
/// * `filter_type` - The type of filter.
/// * `options` - The processed options.
///
/// # Returns
///
/// A `Result` containing the boxed filter plugin.
fn create_specific_filter(
filter_type: FilterType,
options: &HashMap<String, serde_json::Value>,
@@ -338,7 +394,15 @@ fn create_specific_filter(
}
}
// Helper function to parse option values
/// Parses an option value from a string into a JSON value.
///
/// # Arguments
///
/// * `input` - The input string.
///
/// # Returns
///
/// A `Result` containing the parsed JSON value.
fn parse_option_value(input: &str) -> Result<serde_json::Value> {
// Remove quotes if present
let input = input.trim_matches(|c| c == '\'' || c == '"');

30
src/filter_plugin/skip.rs
View File

@@ -3,17 +3,24 @@ use std::io::{Result, Read, Write, BufRead};
use crate::common::PIPESIZE;
use crate::services::filter_service::register_filter_plugin;
/// A filter that skips the first N bytes from the input stream.
pub struct SkipBytesFilter {
remaining: usize,
}
impl SkipBytesFilter {
/// Creates a new `SkipBytesFilter` that will skip the specified number of bytes.
///
/// # Arguments
///
/// * `count` - The number of bytes to skip.
pub fn new(count: usize) -> Self {
Self {
remaining: count,
}
}
/// Creates a new instance from options.
pub fn create(options: Option<serde_json::Value>) -> Result<Box<dyn FilterPlugin>> {
let options = options.ok_or_else(|| {
std::io::Error::new(
@@ -37,6 +44,12 @@ impl SkipBytesFilter {
}
impl FilterPlugin for SkipBytesFilter {
/// Filters the input by skipping the first N bytes and writing the rest to the output.
///
/// # Arguments
///
/// * `reader` - The input reader.
/// * `writer` - The output writer.
fn filter(&mut self, mut reader: Box<&mut dyn Read>, mut writer: Box<&mut dyn Write>) -> Result<()> {
// Skip bytes in chunks
if self.remaining > 0 {
@@ -56,12 +69,14 @@ impl FilterPlugin for SkipBytesFilter {
Ok(())
}
/// Clones this filter into a new boxed instance.
fn clone_box(&self) -> Box<dyn FilterPlugin> {
Box::new(Self {
remaining: self.remaining,
})
}
/// Returns the configuration options for this filter.
fn options(&self) -> Vec<FilterOption> {
vec![
FilterOption {
@@ -73,17 +88,24 @@ impl FilterPlugin for SkipBytesFilter {
}
}
/// A filter that skips the first N lines from the input stream.
pub struct SkipLinesFilter {
remaining: usize,
}
impl SkipLinesFilter {
/// Creates a new `SkipLinesFilter` that will skip the specified number of lines.
///
/// # Arguments
///
/// * `count` - The number of lines to skip.
pub fn new(count: usize) -> Self {
Self {
remaining: count,
}
}
/// Creates a new instance from options.
pub fn create(options: Option<serde_json::Value>) -> Result<Box<dyn FilterPlugin>> {
let options = options.ok_or_else(|| {
std::io::Error::new(
@@ -107,6 +129,12 @@ impl SkipLinesFilter {
}
impl FilterPlugin for SkipLinesFilter {
/// Filters the input by skipping the first N lines and writing the rest to the output.
///
/// # Arguments
///
/// * `reader` - The input reader.
/// * `writer` - The output writer.
fn filter(&mut self, mut reader: Box<&mut dyn Read>, mut writer: Box<&mut dyn Write>) -> Result<()> {
let mut buf_reader = std::io::BufReader::new(&mut *reader);
for line in buf_reader.by_ref().lines() {
@@ -120,12 +148,14 @@ impl FilterPlugin for SkipLinesFilter {
Ok(())
}
/// Clones this filter into a new boxed instance.
fn clone_box(&self) -> Box<dyn FilterPlugin> {
Box::new(Self {
remaining: self.remaining,
})
}
/// Returns the configuration options for this filter.
fn options(&self) -> Vec<FilterOption> {
vec![
FilterOption {

10
src/filter_plugin/strip_ansi.rs
View File

@@ -2,25 +2,35 @@ use std::io::{Result, Read, Write};
use strip_ansi_escapes::Writer;
use super::{FilterPlugin, FilterOption};
/// A filter that removes ANSI escape sequences from the input.
pub struct StripAnsiFilter;
impl StripAnsiFilter {
/// Creates a new `StripAnsiFilter`.
pub fn new() -> Self {
Self
}
}
impl FilterPlugin for StripAnsiFilter {
/// Filters the input by stripping ANSI escape sequences and writing the plain text to the output.
///
/// # Arguments
///
/// * `reader` - The input reader.
/// * `writer` - The output writer.
fn filter(&mut self, mut reader: Box<&mut dyn Read>, mut writer: Box<&mut dyn Write>) -> Result<()> {
let mut ansi_writer = Writer::new(&mut *writer);
std::io::copy(&mut *reader, &mut ansi_writer)?;
ansi_writer.flush()
}
/// Clones this filter into a new boxed instance.
fn clone_box(&self) -> Box<dyn FilterPlugin> {
Box::new(Self)
}
/// Returns the configuration options for this filter (none required).
fn options(&self) -> Vec<FilterOption> {
Vec::new() // strip_ansi doesn't take any options
}

30
src/filter_plugin/tail.rs
View File

@@ -4,12 +4,18 @@ use std::collections::VecDeque;
use crate::common::PIPESIZE;
use crate::services::filter_service::register_filter_plugin;
/// A filter that reads the last N bytes from the input stream.
pub struct TailBytesFilter {
buffer: VecDeque<u8>,
count: usize,
}
impl TailBytesFilter {
/// Creates a new `TailBytesFilter` that will keep the last specified number of bytes.
///
/// # Arguments
///
/// * `count` - The number of bytes to keep from the end.
pub fn new(count: usize) -> Self {
Self {
buffer: VecDeque::with_capacity(count),
@@ -17,6 +23,7 @@ impl TailBytesFilter {
}
}
/// Creates a new instance from options.
pub fn create(options: Option<serde_json::Value>) -> Result<Box<dyn FilterPlugin>> {
let options = options.ok_or_else(|| {
std::io::Error::new(
@@ -40,6 +47,12 @@ impl TailBytesFilter {
}
impl FilterPlugin for TailBytesFilter {
/// Filters the input by keeping only the last N bytes and writing them to the output.
///
/// # Arguments
///
/// * `reader` - The input reader.
/// * `writer` - The output writer.
fn filter(&mut self, mut reader: Box<&mut dyn Read>, mut writer: Box<&mut dyn Write>) -> Result<()> {
let mut temp_buffer = vec![0; PIPESIZE];
loop {
@@ -63,6 +76,7 @@ impl FilterPlugin for TailBytesFilter {
Ok(())
}
/// Clones this filter into a new boxed instance.
fn clone_box(&self) -> Box<dyn FilterPlugin> {
Box::new(Self {
buffer: self.buffer.clone(),
@@ -70,6 +84,7 @@ impl FilterPlugin for TailBytesFilter {
})
}
/// Returns the configuration options for this filter.
fn options(&self) -> Vec<FilterOption> {
vec![
FilterOption {
@@ -81,12 +96,18 @@ impl FilterPlugin for TailBytesFilter {
}
}
/// A filter that reads the last N lines from the input stream.
pub struct TailLinesFilter {
lines: VecDeque<String>,
count: usize,
}
impl TailLinesFilter {
/// Creates a new `TailLinesFilter` that will keep the last specified number of lines.
///
/// # Arguments
///
/// * `count` - The number of lines to keep from the end.
pub fn new(count: usize) -> Self {
Self {
lines: VecDeque::with_capacity(count),
@@ -94,6 +115,7 @@ impl TailLinesFilter {
}
}
/// Creates a new instance from options.
pub fn create(options: Option<serde_json::Value>) -> Result<Box<dyn FilterPlugin>> {
let options = options.ok_or_else(|| {
std::io::Error::new(
@@ -117,6 +139,12 @@ impl TailLinesFilter {
}
impl FilterPlugin for TailLinesFilter {
/// Filters the input by keeping only the last N lines and writing them to the output.
///
/// # Arguments
///
/// * `reader` - The input reader.
/// * `writer` - The output writer.
fn filter(&mut self, mut reader: Box<&mut dyn Read>, mut writer: Box<&mut dyn Write>) -> Result<()> {
let mut buf_reader = std::io::BufReader::new(&mut *reader);
for line in buf_reader.by_ref().lines() {
@@ -134,6 +162,7 @@ impl FilterPlugin for TailLinesFilter {
Ok(())
}
/// Clones this filter into a new boxed instance.
fn clone_box(&self) -> Box<dyn FilterPlugin> {
Box::new(Self {
lines: self.lines.clone(),
@@ -141,6 +170,7 @@ impl FilterPlugin for TailLinesFilter {
})
}
/// Returns the configuration options for this filter.
fn options(&self) -> Vec<FilterOption> {
vec![
FilterOption {

20
src/filter_plugin/utils.rs
View File

@@ -1,11 +1,27 @@
use std::io::Result;
/// Helper function to create a filter chain from a string
/// Creates a filter chain from a filter string specification.
///
/// # Arguments
///
/// * `filter_str` - The string describing the filter chain (e.g., "head_lines(10)|grep(pattern=error)").
///
/// # Returns
///
/// A `Result` containing an optional `FilterChain` if parsing succeeds.
pub fn create_filter_chain(filter_str: &str) -> Result<Option<super::FilterChain>> {
super::parse_filter_string(filter_str).map(Some)
}
/// Helper function to parse a number from a string with error handling
/// Parses a string into a number of type T.
///
/// # Arguments
///
/// * `s` - The string to parse.
///
/// # Returns
///
/// A `Result` containing the parsed number or an error if invalid.
pub fn parse_number<T: std::str::FromStr>(s: &str) -> Result<T> {
s.parse::<T>()
.map_err(|_| std::io::Error::new(std::io::ErrorKind::InvalidInput, "Invalid number"))