docs

README.md

@@ -1,5 +1,5 @@
 # JSONFilter
-`jsonfilter` is a Rust crate designed to facilitate filtering and comparing JSON values based on specified criteria. It provides functions for comparing JSON values, applying filters to JSON objects, and determining if a filter matches a given JSON object. Think of MongoDBs `find()` function but as a filter function.
+`jsonfilter` is a Rust crate designed to facilitate filtering and comparing JSON values based on specified criteria. It provides functions for comparing JSON values, applying filters to JSON objects, and determining if a filter matches a given JSON object. Think of MongoDBs `find()` function but as a filter function. For a full syntax guide, see the [Filter Documentation](./docs/filter.md)
 
 ## Usage
 To use `jsonfilter`, add it to your `Cargo.toml` and add the following to your Rust code:

docs/filter.md

@@ -0,0 +1,133 @@
+# Filter Syntax
+Every filter is a JSON object. At its simplest form, a filter acts as a mask, checking if the values of the filter match those of the object being filtered.
+```json
+{
+    "key": "value",
+    "nested": {
+        "key": "value"
+    }
+}
+```
+
+This filter would match against an object like:
+```json
+{
+    "key": "value",
+    "other": "data",
+    "nested": {
+        "key": "value"
+    }
+}
+```
+
+## Advanced Filtering with Operators
+Operators enable complex filtering by allowing operations on keys and values.
+
+### **Example**: Logical Chaining and Regex
+```json
+{
+    "$or": [
+        { "key": { "$regex": "^L" }},
+        { "key": { "$regex": "in$" }},
+    ]
+}
+```
+
+This filter would match all of these objects:
+```json
+{ "key": "Login" }
+{ "key": "Lenin"}
+```
+but not:
+```json
+{ "key": "Lol"}
+```
+
+## Operators
+### `$and`
+Chain multiple filters together. All must evaluate to `true`
+```json
+{
+    "$and": [
+        { "key": "val" },
+        { "another": "filter" }
+    ]
+}
+```
+
+### `$or`
+Chain multiple filters together. At least one must evaluate to `true`
+```json
+{
+    "$or": [
+        { "key": "val" },
+        { "another": "filter" }
+    ]
+}
+```
+
+### `$not`
+Inverts the result of the nested filter expression.
+```json
+{ "$not": { "key": "value" }}
+```
+
+### `$lt` & `$lte`
+Evaluates to `true` if the value is less than or less than equal the specified value.
+```json
+{ "key": { "$lt": 5 }}
+```
+
+### `$gt` & `$gte`
+Evaluates to `true` if the value is greater than or greater than equal the specified value.
+```json
+{ "key": { "$gt": 5 }}
+```
+
+### `$ne`
+Evaluates to `true` if the value is not equal to the specified value.
+```json
+{ "key": { "$ne": "value" }}
+```
+
+### `$in`
+Evaluates to `true` if the value exists in the specified array.
+```json
+{ "array": { "$in": "value" }}
+```
+
+### `$nin`
+Evaluates to `true` if the value does not exist in the specified array.
+```json
+{ "array": { "$nin": "value" }}
+```
+
+### `$exists`
+Checks wether the key exists in the object.
+```json
+{"key": { "$exists": true }}
+{"key": { "$exists": false }}
+```
+
+### `$size`
+Evaluates to `true` if the array length matches the specified value
+```json
+{ "array": { "$size": 5 }}
+```
+
+### `$regex`
+Evaluates to `true` if the value matches the regular expression pattern.
+```json
+{ "key": { "$regex": "^regex" }}
+```
+
+### `$type`
+Evaluates to `true` if the value matches the specified type.
+```json
+{ "key": { "$type": "null" }}
+{ "key": { "$type": "string" }}
+{ "key": { "$type": "number" }}
+{ "key": { "$type": "object" }}
+{ "key": { "$type": "array" }}
+{ "key": { "$type": "boolean" }}
+```