aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorOnur Gündüz <ogunduz@gmail.com>2026-09-29 16:20:03 +0200
committerOnur Gündüz <ogunduz@gmail.com>2026-09-29 16:20:03 +0200
commit5c51cd28a928c44232e625279691da17e55858de (patch)
tree86062d1c17d1e77dfe0161adf017eabf88aa2b6e
parentba26ee29b4ebebd35e4e7296815824c885322115 (diff)
downloadele-5c51cd28a928c44232e625279691da17e55858de.tar.gz
ele-5c51cd28a928c44232e625279691da17e55858de.zip
Simplify README usage guide
-rw-r--r--README.md137
1 files changed, 28 insertions, 109 deletions
diff --git a/README.md b/README.md
index 3382a58..3fbcae1 100644
--- a/README.md
+++ b/README.md
@@ -12,132 +12,51 @@ cargo install --path . --locked
## CLI usage
-```bash
-usage: aip-filter [-p|--print] [--max-record-bytes N] [--] <expr> [file...]
-```
-
-* `--help` and `--version` print information and exit successfully without reading input.
-* Unknown long options fail. Use `--` before an expression that starts with `--`, including filter comments.
-* `--print` prints the parsed expression instead of evaluating it.
-* If no files are given, reads from stdin.
-* Input is newline-delimited JSON, with one value per line. Matching lines are preserved, with a newline inserted between records when a preceding input file has no trailing newline. A final unterminated record is otherwise left unchanged.
-* An empty filter copies the selected input unchanged; `--print` with an empty filter prints nothing.
-* Invalid JSON lines are reported and skipped. Any invalid JSON or input/output error causes a nonzero exit status.
-* Records are limited to 8 MiB by default, including the newline. `--max-record-bytes N` sets a positive byte limit. Oversized records are reported and skipped without buffering the rest of the line; later records are still processed and the exit status indicates failure. The limit does not apply to an empty filter, which copies bytes directly.
-* Memory depends on the largest allowed record and its parsed JSON values, not on the total number of records. The record limit is not a process-memory limit.
-* Exit status is 0 for successful processing, even with no matches; 1 for filter, data, or I/O errors; and 2 for invalid command-line usage.
-
-### Matching rules
-
-* Bare literals search values recursively, including nested objects and arrays, but not object keys. String searches are case-insensitive substrings.
-* 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.
-* Top-level `field:*` tests for a non-default value, including a nonempty list or map. For a map entry, `m.foo:*` tests whether the key exists, even when its value is zero, false, empty, or null. JSON objects and `Value::Map` use map semantics; custom message paths use non-default presence.
-* The `:` operator can traverse repeated values: `r.foo:42` matches if an element has a matching `foo` value. A grouped right-hand side applies to one resolved element. Ordinary comparisons do not traverse arrays, and numeric path segments are never array indices.
-* 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.
-
-### Compatibility
+The CLI reads one JSON value per line from files or standard input and prints matching records without reformatting.
-This is a schema-free evaluator, not a complete implementation of a typed AIP-160 API. Missing fields are non-matches, and operand types are determined from each record. There is no schema validation, timestamp or duration type, or function registry. Regex operators, quoted left-hand literals, boolean field shorthand, and list equality are extensions. The matching rules above define the supported behavior.
-
-### Examples
-
-```bash
-# Match if price is between 10 and 100, and status is active
-echo '{"price": 93, "status": "active"}' | \
- aip-filter "price > 10 AND price < 100 AND status = active"
-
-# Match if 'foobar' appears in any field (bare-literal match)
-echo '{"id": 1, "msg": "hello foobar"}' | aip-filter "foobar"
-
-# Match if 'tags' contains 'beta'
-echo '{"tags": ["stable", "beta"]}' | aip-filter "tags:beta"
-
-# Nested field access
-echo '{"user": {"settings": {"theme": "dark"}}}' | \
- aip-filter "user.settings.theme = dark"
+```text
+aip-filter [-p|--print] [--max-record-bytes N] [--] <expr> [file...]
```
-## Development and release checks
-
```bash
-cargo fmt --all -- --check
-cargo clippy --all-targets --locked -- -D warnings
-cargo test --locked
-cargo test --locked --features serde_json/arbitrary_precision
-cargo test --release --locked
-cargo package --locked
-```
-
-CI checks Rust 1.88 and stable Rust on Linux, macOS, and Windows. The quality job also checks formatting, linting, and the packaged crate. Do not tag or publish until the hosted CI checks are complete.
-
-## Performance
-
-Release builds optimize for speed rather than minimum executable size. The evaluator reuses compiled regexes and literals, borrows JSON collections, and searches overlapping phrases in linear time. JSON parsing still allocates memory for each record.
+echo '{"price":93,"status":"active"}' | aip-filter 'price > 10 AND status = active'
-To compare two release binaries, use Python 3:
-
-```bash
-python3 bench/benchmark.py ./target/baseline ./target/release/aip-filter \
- --records 100000 --runs 5
+aip-filter '"timeout"' events.jsonl
+aip-filter 'tags:beta' events.jsonl
+aip-filter 'user.settings.theme = dark' events.jsonl
```
-The benchmark generates JSON lines under `target/benchmarks`, checks that both binaries produce identical output, and reports median elapsed times for seven workloads. It alternates execution order and discards output during timing. Results depend on the machine and data.
+* `--print` prints the parsed expression instead of filtering input.
+* `--help` and `--version` print information and exit. `--` ends option parsing.
+* Records are limited to 8 MiB, including the newline. `--max-record-bytes N` changes this limit.
+* An empty filter copies input unchanged without applying the record limit.
-For a smaller binary, Cargo also supports a size-oriented build without changing the configuration:
+Invalid or oversized records are reported and skipped. Exit codes are `0` for success, including no matches; `1` for filter, data, or I/O errors; and `2` for invalid arguments.
-```bash
-CARGO_PROFILE_RELEASE_OPT_LEVEL=z cargo build --release --locked
-```
-
-## API
+### Matching rules
-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.
+* Bare literals search nested values, not object keys. String searches are case-insensitive substrings. Quote a search term to prevent field lookup.
+* String `=` and `!=` ignore ASCII case and support a leading or trailing `*` wildcard.
+* Regex matching uses `=~` and `!~`.
+* String `:` matches whole words or phrases. On lists, it matches any element; on maps, it matches keys.
+* `field:*` tests for a non-default value. `map.key:*` tests whether the key exists, even when its value is zero, false, empty, or null.
+* `r.foo:42` searches the `foo` fields of repeated elements. Ordinary comparisons do not traverse arrays, and numeric path segments are not array indices.
-`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.
+Function calls are not supported during evaluation.
-JSON numbers use `i64`, `u64`, or finite `f64` when representable. If another crate enables `serde_json/arbitrary_precision`, larger values are retained as `Value::JsonNumber` without panicking or converting to infinity. Numeric comparisons against an out-of-range value return false, including `!=`; presence checks and exact bare-literal matching of its JSON number text remain available. This does not provide arbitrary-precision arithmetic.
+## Rust API
-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.
+Compile an expression once and reuse the filter. `serde_json::Value` is supported directly; implement `Filterable` for other types.
```rust
-use aip_filter::{parse, Value, Filterable};
-
-struct Issue {
- state: String,
- priority: i64,
- labels: Vec<String>,
-}
-
-impl Filterable for Issue {
- fn field(&self, name: &str) -> Option<Value<'_>> {
- match name {
- "state" => Some(Value::String(&self.state)),
- "priority" => Some(Value::Int(self.priority)),
- "labels" => Some(Value::List(
- self.labels.iter().map(|l| Value::String(l)).collect()
- )),
- _ => None,
- }
- }
-}
-
-fn main() {
- let expr = parse("state = \"open\"").unwrap().unwrap();
- let filter = expr.compile().unwrap();
- let issue = Issue { state: "open".into(), priority: 1, labels: vec![] };
+use aip_filter::parse;
+use serde_json::json;
- if filter.evaluate(&issue) {
- println!("got match");
- } else {
- println!("no match");
- }
+let expr = parse("state = open AND priority > 3").unwrap().unwrap();
+let filter = expr.compile().unwrap();
+let record = json!({"state": "open", "priority": 5});
- assert!(filter.evaluate(&issue));
-}
+assert!(filter.evaluate(&record));
```
## License