aboutsummaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorOnur Gündüz <ogunduz@gmail.com>2026-09-29 14:03:41 +0200
committerOnur Gündüz <ogunduz@gmail.com>2026-09-29 14:03:41 +0200
commite3eb58307419a9f7314e061c393d579fd14b75ab (patch)
tree8e232ec9ee70bd07ebe46bbc9fd86643cb411642 /README.md
parent93fd7757dc4900da697b9d5e884e1a343e2facda (diff)
downloadele-e3eb58307419a9f7314e061c393d579fd14b75ab.tar.gz
ele-e3eb58307419a9f7314e061c393d579fd14b75ab.zip
Compile filters once and reject unsupported evaluation
Diffstat (limited to 'README.md')
-rw-r--r--README.md13
1 files changed, 9 insertions, 4 deletions
diff --git a/README.md b/README.md
index a2c63db..4c1656b 100644
--- a/README.md
+++ b/README.md
@@ -28,7 +28,9 @@ usage: aip-filter [-p|--print] <expr> [file...]
* An unquoted boolean field name evaluates that field. A dotted name resolves a field path first and otherwise becomes a global literal. Quote a search term to prevent field lookup, for example `'"active"'` or `'"example.com"'`.
* String `=` and `!=` ignore ASCII case and support one leading or trailing `*`. The two operators are opposites.
* String `:` matches words or phrases bounded by whitespace or ASCII punctuation, or a leading/trailing wildcard. Lists match any element; maps match keys. `field:*` tests for a non-default value, including a nonempty list or map.
-* Functions are parsed but not evaluated. Regexes are validated when parsing and recompiled during evaluation. Filters are limited to 64 KiB, 512 non-whitespace tokens, 64 recursive parser calls, and an expression tree of at most 128 levels and 512 nodes. Excessive filters return errors instead of recursing without a bound.
+* Functions can be parsed and printed, but evaluation rejects the entire filter if any function is present, including inside a negation or unused branch.
+* The CLI compiles filters before reading records. Regexes, numeric literals, and field paths are reused across records. Filters can contain at most 32 regexes; each regex has a 1 MiB compiled-size limit and a 256 KiB DFA cache limit.
+* Filters are limited to 64 KiB, 512 non-whitespace tokens, 64 recursive parser calls, and an expression tree of at most 128 levels and 512 nodes. Excessive filters return errors instead of recursing without a bound.
### Examples
@@ -50,7 +52,9 @@ echo '{"user": {"settings": {"theme": "dark"}}}' | \
## API
-Implement `Filterable` for your type, then call `Expr::evaluate`:
+Implement `Filterable` for your type, compile the expression once with `Expr::compile`, and reuse `CompiledFilter::evaluate`. Compilation returns errors for unsupported expressions before any records are read. `serde_json::Value` implements `Filterable` directly and borrows arrays and objects without copying them.
+
+`Expr::evaluate` is a convenience method for one record: it compiles on every call and returns false if compilation fails. Use `Expr::compile` when errors must be reported.
Bare-literal matching also requires overriding `all_field_values` or `matches_global`; the default searches no values. Override `matches_global` to search borrowed data without building a list of values. `Value::matches_global` provides recursive matching for individual values.
@@ -78,14 +82,15 @@ impl Filterable for Issue {
fn main() {
let expr = parse("state = \"open\"").unwrap().unwrap();
+ let filter = expr.compile().unwrap();
let issue = Issue { state: "open".into(), priority: 1, labels: vec![] };
- if expr.evaluate(&issue) {
+ if filter.evaluate(&issue) {
println!("got match");
} else {
println!("no match");
}
- assert!(expr.evaluate(&issue));
+ assert!(filter.evaluate(&issue));
}
```