diff options
| -rw-r--r-- | src/filters/values.rs | 42 |
1 files changed, 42 insertions, 0 deletions
diff --git a/src/filters/values.rs b/src/filters/values.rs index 543b59c..f64d6dd 100644 --- a/src/filters/values.rs +++ b/src/filters/values.rs @@ -1,3 +1,16 @@ +//! Value extractor system for raidgrep filters. +//! +//! [`Comparators`][Comparator] are special filters that work by first producing a value from a +//! given log (via the [`Producer`][Producer]) trait and then applying a comparison operator +//! ([`CompOp`][CompOp]) between the results. This type of filter gives a lot of flexibility, as it +//! can reduce the number of hard-coded filters one has to create (for example, `-before` and +//! `-after` can be merged). +//! +//! A [`Comparator`][Comparator] can only compare producers which produce the same type of value, +//! and that value must define a total order (i.e. it must implement [`Ord`][Ord]). Note that the +//! actual comparison is done on filter time, that is a [`Comparator`][Comparator] is basically a +//! filter that first uses the producers to produce a value from the given log, and then compares +//! the two resulting values with the given comparison operator. use std::{ cmp::Ordering, fmt::{self, Debug}, @@ -8,22 +21,41 @@ use chrono::{DateTime, Duration, Utc}; use super::{log::LogFilter, Filter}; use crate::{EarlyLogResult, LogResult}; +/// A producer for a given value. +/// +/// A producer is something that produces a value of a certain type from a log, which can then be +/// used by [`Comparators`][Comparator] to do the actual comparison. pub trait Producer: Send + Sync + Debug { + /// Type of the value that will be produced. type Output; + /// Early production. + /// + /// This function should be implemented if the value can already be produced without the + /// complete log being parsed. This can speed up filtering if a lot of logs end up being thrown + /// away. + /// + /// If a value cannot be produced early, `None` should be returned. fn produce_early(&self, _early_log: &EarlyLogResult) -> Option<Self::Output> { None } + /// Produce the value from the given log. fn produce(&self, log: &LogResult) -> Self::Output; } +/// The comparison operator to be used. #[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)] pub enum CompOp { + /// The first value must be strictly less than the second value. Less, + /// The first value must be less or equal to the second value. LessEqual, + /// Both values must be equal. Equal, + /// The first value must be greater or equal to the second value. GreaterEqual, + /// The first value must be strictly greater than the second value. Greater, } @@ -41,6 +73,7 @@ impl fmt::Display for CompOp { } impl CompOp { + /// Check whether the comparison operator matches the given ordering. pub fn matches(self, cmp: Ordering) -> bool { match cmp { Ordering::Less => self == CompOp::Less || self == CompOp::LessEqual, @@ -75,6 +108,12 @@ where } } +/// Create a log filter that works by comparing two values. +/// +/// The values will be produced by the given producers. +/// +/// This function acts as a "bridge" between the value producers and the log filter system by +/// actually evaluating the comparison. pub fn comparison<V: 'static>( lhs: Box<dyn Producer<Output = V>>, op: CompOp, @@ -100,6 +139,7 @@ impl<V: Send + Sync + Debug + Clone> Producer for ConstantProducer<V> { } } +/// A producer that always produces the given constant, regardless of the log. pub fn constant<V: Send + Sync + Debug + Clone + 'static>( value: V, ) -> Box<dyn Producer<Output = V>> { @@ -124,6 +164,7 @@ impl Producer for TimeProducer { } } +/// A producer that produces the time at which a log was created. pub fn time() -> Box<dyn Producer<Output = DateTime<Utc>>> { Box::new(TimeProducer) } @@ -139,6 +180,7 @@ impl Producer for DurationProducer { } } +/// A producer that produces the duration that a fight lasted in the log. pub fn duration() -> Box<dyn Producer<Output = Duration>> { Box::new(DurationProducer) } |