csonpath 0.16.0__tar.gz → 0.18.0__tar.gz

{csonpath-0.16.0 → csonpath-0.18.0}/Makefile

@@ -5,7 +5,7 @@ YYJSON_LDFLAGS=$(shell pkg-config --libs yyjson)
 
 include config.mk
 
-all: test-json-c-get-a test-json-update test-json-filter test-json-subpath test-json-c-array-root test-json-filter-and-missing-key test-json-get-array-big-index test-json-union test-json-audit-bugs test-json-crash-vectors
+all: test-json-c-get-a test-json-update test-json-filter test-json-subpath test-json-c-array-root test-json-filter-and-missing-key test-json-get-array-big-index test-json-union test-json-audit-bugs test-json-crash-vectors test-json-my-fuzz test-json-regex-overflow
 
 YYJSON_TESTS=test-yyjson
 
@@ -15,7 +15,7 @@ bench:
 bench-clean:
 	make -C bench clean
 
-.PHONY: all clean tests pip-dev pip-dev bench bench-clean
+.PHONY: all clean tests pip-dev pip-dev bench bench-clean tests-cli tests-rust cov
 
 CFLAGS+= -Wall -Wextra -Wno-unused-function -Wno-unused-parameter -O0 -g
 
@@ -49,10 +49,22 @@ test-json-audit-bugs: tests/json-c/audit-bugs.c csonpath_json-c.h csonpath.h cso
 test-json-crash-vectors: tests/json-c/crash-vectors.c csonpath_json-c.h csonpath.h csonpath_do.h
 	$(CC) tests/json-c/crash-vectors.c $(EXTRA_FILES) $(JSON_C_CFLAGS) $(CFLAGS) -Wno-format -I./ -o test-json-crash-vectors  $(JSON_C_LDFLAGS) $(LDFLAGS)
 
-test-yyjson: tests/yyjson/test-yyjson.c csonpath_yyjson.h csonpath.h csonpath_do.h
+test-json-my-fuzz: tests/json-c/my_fuzz.c csonpath_json-c.h csonpath_my_fuzzing.h csonpath.h csonpath_do.h
+	$(CC) tests/json-c/my_fuzz.c $(EXTRA_FILES) $(JSON_C_CFLAGS) $(CFLAGS) -Wno-format -I./ -o test-json-my-fuzz $(JSON_C_LDFLAGS) $(LDFLAGS)
+
+test-json-regex-overflow: tests/json-c/regex-overflow.c csonpath_json-c.h csonpath.h csonpath_do.h
+	$(CC) tests/json-c/regex-overflow.c $(EXTRA_FILES) $(JSON_C_CFLAGS) $(CFLAGS) -Wno-format -I./ -o test-json-regex-overflow $(JSON_C_LDFLAGS) $(LDFLAGS)
+
+test-yyjson: tests/yyjson/test-yyjson.c csonpath_yyjson_const.h csonpath.h csonpath_do.h
 	$(CC) tests/yyjson/test-yyjson.c $(EXTRA_FILES) $(YYJSON_CFLAGS) $(CFLAGS) -Wno-format -I./ -o test-yyjson $(YYJSON_LDFLAGS) $(LDFLAGS)
 
- tests-c: test-json-c-get-a test-json-update test-json-filter test-json-subpath test-json-c-array-root test-json-filter-and-missing-key test-json-get-array-big-index test-json-union test-json-audit-bugs test-json-crash-vectors test-yyjson
+test-yyjson-mixed: tests/yyjson/test-yyjson-mixed.c csonpath_yyjson.h csonpath_yyjson_const.h csonpath_yyjson_mut.h csonpath.h csonpath_do.h
+	$(CC) tests/yyjson/test-yyjson-mixed.c $(EXTRA_FILES) $(YYJSON_CFLAGS) $(CFLAGS) -Wno-format -I./ -o test-yyjson-mixed $(YYJSON_LDFLAGS) $(LDFLAGS)
+
+test-multi-backend-prefix: tests/multi-backend-prefix.c csonpath_json-c.h csonpath_yyjson.h csonpath_yyjson_const.h csonpath_yyjson_mut.h csonpath.h csonpath_do.h
+	$(CC) tests/multi-backend-prefix.c $(EXTRA_FILES) $(JSON_C_CFLAGS) $(YYJSON_CFLAGS) $(CFLAGS) -Wno-format -I./ -o test-multi-backend-prefix $(JSON_C_LDFLAGS) $(YYJSON_LDFLAGS) $(LDFLAGS)
+
+tests-c: test-json-c-get-a test-json-update test-json-filter test-json-subpath test-json-c-array-root test-json-filter-and-missing-key test-json-get-array-big-index test-json-union test-json-audit-bugs test-json-crash-vectors test-yyjson test-yyjson-mixed test-json-my-fuzz test-multi-backend-prefix test-json-regex-overflow
 	./test-json-c-get-a
 	./test-json-update
 	./test-json-filter
@@ -64,6 +76,16 @@ test-yyjson: tests/yyjson/test-yyjson.c csonpath_yyjson.h csonpath.h csonpath_do
 	./test-json-audit-bugs
 	./test-json-crash-vectors
 	./test-yyjson
+	./test-yyjson-mixed
+	./test-json-my-fuzz
+	./test-multi-backend-prefix
+	./test-json-regex-overflow
+
+csonpath: cli/csonpath_cli.c csonpath_json-c.h csonpath.h csonpath_do.h
+	$(CC) cli/csonpath_cli.c $(EXTRA_FILES) $(JSON_C_CFLAGS) $(CFLAGS) -I./ -o csonpath $(JSON_C_LDFLAGS) $(LDFLAGS)
+
+tests-cli: csonpath
+	bash tests/cli/run.sh
 
 pip-dev:
 	pip install -e .[dev] --force-reinstall
@@ -71,8 +93,34 @@ pip-dev:
 tests-py: pip-dev
 	python -m pytest
 
-tests: tests-py tests-c
+tests-rust:
+	cargo test --manifest-path rust/Cargo.toml
+
+cov:
+	$(MAKE) clean
+	rm -rf coverage-c coverage-c.html coverage-py coverage-rust build
+	find . -name '*.gcov' -delete
+	$(MAKE) CFLAGS='--coverage -O0 -g' LDFLAGS='--coverage' tests-c
+	CFLAGS='--coverage -O0' LDFLAGS='--coverage' python setup.py build_ext --inplace --force
+	python -m coverage run -m pytest
+	python -m coverage html -d coverage-py
+	python -m gcovr -r . \
+		--gcov-object-directory "$$(ls -d build/temp.* 2>/dev/null | head -1)" \
+		--filter 'csonpath\.h' --filter 'csonpath_do\.h' --filter 'csonpath_python\.c' \
+		--html-details coverage-c.html
+	PATH="$$HOME/.cargo/bin:$$PATH" \
+		LLVM_COV="$$(find $$HOME/.rustup/toolchains -name llvm-cov -print -quit)" \
+		LLVM_PROFDATA="$$(find $$HOME/.rustup/toolchains -name llvm-profdata -print -quit)" \
+		cargo llvm-cov --manifest-path rust/Cargo.toml --html --output-dir coverage-rust
+	@echo "Coverage reports:"
+	@echo "  coverage-c.html"
+	@echo "  coverage-py/index.html"
+	@echo "  coverage-rust/html/index.html"
+
+tests: tests-py tests-c tests-cli tests-rust
 
 clean:
-	rm -rvf test-json-c-get-a test-json-update test-json-filter test-json-subpath test-json-c-array-root test-json-filter-and-missing-key test-json-get-array-big-index test-json-union test-json-audit-bugs test-json-crash-vectors test-yyjson
+	rm -rvf test-json-c-get-a test-json-update test-json-filter test-json-subpath test-json-c-array-root test-json-filter-and-missing-key test-json-get-array-big-index test-json-union test-json-audit-bugs test-json-crash-vectors test-yyjson test-yyjson-mixed test-json-my-fuzz test-multi-backend-prefix test-json-regex-overflow csonpath
+	find . -name '*.gcda' -delete
+	find . -name '*.gcno' -delete
 

{csonpath-0.16.0/csonpath.egg-info → csonpath-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: csonpath
-Version: 0.16.0
+Version: 0.18.0
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Provides-Extra: dev
@@ -13,9 +13,9 @@ Dynamic: license-file
 
 [![Project Sandbox](https://docs.outscale.com/fr/userguide/_images/Project-Sandbox-yellow.svg)](https://docs.outscale.com/en/userguide/Open-Source-Projects.html)
 
-**csonpath** is a partial [JSONPath](https://goessner.net/articles/JsonPath/) implementation in C, with Python bindings. It allows you to query, update, and remove data from JSON objects using path expressions.
+**csonpath** is a partial [JSONPath](https://goessner.net/articles/JsonPath/) implementation in C. It is **backend-agnostic**: the same core engine can query, update, and remove data from any value representation that supports array, object, and scalar semantics—not just JSON.
 
-Unlike many JSONPath libraries, csonpath is **backend-agnostic**: it can work with any C library or environment that manipulates array, object, and scalar types—not just JSON. Out of the box, backends for [json-c](https://github.com/json-c/json-c) and Python are provided.
+Out of the box it ships with C backends for [json-c](https://github.com/json-c/json-c) and [yyjson](https://github.com/ibireme/yyjson), plus language bindings for **Python** and **Rust**.
 
 ---
 
@@ -62,6 +62,8 @@ Unlike many JSONPath libraries, csonpath is **backend-agnostic**: it can work wi
 - [Usage](#-usage)
 - [C API Reference](#-c-api-reference)
 - [Python API Reference](#-python-api-reference)
+- [CLI](#%EF%B8%8F-cli)
+- [Using Multiple Backends](#-using-multiple-backends)
 - [Custom Backends](#-custom-backends)
 - [Running Tests](#-running-tests)
 - [Directory Structure](#-directory-structure)
@@ -72,12 +74,12 @@ Unlike many JSONPath libraries, csonpath is **backend-agnostic**: it can work wi
 
 ## 📦 Installation
 
-### Prerequisites
-- C compiler (`gcc` or `clang`)
-- [json-c](https://github.com/json-c/json-c) library (for C usage)
-- Python 3.x (for Python bindings)
+csonpath is a C library at its core. Pick the instructions for the language you want to use it from.
 
 ### C (json-c)
+
+**Prerequisites:** C compiler (`gcc`, `clang`, or `tcc`), [json-c](https://github.com/json-c/json-c).
+
 Just include the header in your project. There is no separate install step required:
 ```c
 #include "csonpath_json-c.h"
@@ -87,7 +89,23 @@ Make sure to link against `json-c` when compiling:
 gcc myapp.c -o myapp $(pkg-config --cflags --libs json-c)
 ```
 
+### C (yyjson)
+
+**Prerequisites:** C compiler (`gcc`, `clang`, or `tcc`), [yyjson](https://github.com/ibireme/yyjson).
+
+```c
+#include "csonpath_yyjson.h"
+```
+
+Link against `yyjson` when compiling:
+```sh
+gcc myapp.c -o myapp $(pkg-config --cflags --libs yyjson)
+```
+
 ### Python
+
+**Prerequisites:** Python 3.x.
+
 Install from PyPI:
 ```sh
 pip install csonpath
@@ -100,6 +118,23 @@ pip install .
 make pip-dev
 ```
 
+### Rust
+
+**Prerequisites:** Rust toolchain.
+
+The Rust crate is located in `rust/`. Build and test it with:
+```sh
+cd rust
+cargo build
+cargo test
+```
+
+To depend on it from another Rust project:
+```toml
+[dependencies]
+csonpath = { path = "rust" }
+```
+
 ---
 
 ## 🛠️ Usage
@@ -180,6 +215,8 @@ p.update_or_create_callback(dst, my_sync_fn, userdata)
 
 ## 📘 C API Reference
 
+The reference below uses the **json-c** backend as an example (`struct json_object *`). All backends expose the same functions with their own value type.
+
 ```c
 struct csonpath *csonpath_new(const char *path);
 ```
@@ -252,15 +289,117 @@ Free the csonpath object.
 
 ---
 
+## 🖥️ CLI
+
+A standalone C CLI is available in `cli/csonpath_cli.c`. It links directly against `json-c` and the csonpath C core, so it works without Python.
+
+```sh
+make csonpath          # build ./csonpath
+make tests-cli         # run shell tests
+```
+
+It reads JSON from stdin, a file (`-f`), or a string (`-s`) and exposes the library operations through action flags.
+
+```sh
+# Get the first match (default)
+echo '{"a": "value", "array": [1, 2, 3]}' | ./csonpath '$.a'
+# => "value"
+
+# Find all matches
+echo '{"items": [{"price": 5}, {"price": 15}]}' | ./csonpath -a '$.items[?price > 10]'
+# => [{"price":15}]
+
+# One match per line
+echo '{"array": [1, 2, 3]}' | ./csonpath -a -o lines '$.array[*]'
+# => 1
+# => 2
+# => 3
+
+# Set or create a value
+echo '{"a": 1}' | ./csonpath --set '42' '$.x.y.z'
+# => {"a":1,"x":{"y":{"z":42}}}
+
+# Or with a positional value
+echo '{"a": 1}' | ./csonpath '$.x.y.z' '42'
+
+# Remove matches
+echo '{"a": 1, "b": 2}' | ./csonpath -d '$.b'
+# => {"a":1}
+
+# Edit a file in place
+./csonpath -f data.json -p -i --set '"2.0"' '$.version'
+```
+
+### Options
+
+| Option | Description |
+|---|---|
+| `-a`, `--all` | Return all matches instead of the first one. |
+| `-d`, `--delete` | Remove matches and print the modified JSON. |
+| `--set VALUE` | Set `PATH` to `VALUE` (JSON). |
+| `VALUE` (positional) | Alternative to `--set`. |
+| `-r`, `--raw` | Treat the value as a raw string. |
+| `-i`, `--in-place` | Edit `FILE` in place (requires `--file`). |
+| `--strict` | Exit with an error if `--delete` removes nothing. |
+| `-f FILE`, `--file FILE` | Read JSON from `FILE` instead of stdin. |
+| `-s JSON`, `--string JSON` | Read JSON from a string. |
+| `-j`, `--jq-like` | Allow jq-style paths without a leading `$`. |
+| `-p`, `--pretty` | Pretty-print JSON output. |
+| `-o {json,pretty,raw,lines}` | Output format (default: `json`). |
+| `-e`, `--empty-array` | Return `[]` instead of nothing when `-a` matches nothing. |
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Success. |
+| `1` | No match found, or `--strict` delete found nothing. |
+| `EINVAL` | Usage error, JSON parse error, JSONPath compilation error, or invalid JSON value. |
+| `errno` | I/O error (e.g. `ENOENT`, `EACCES`). |
+
+---
+
+## 🧩 Using Multiple Backends
+
+You can include more than one csonpath backend in the same translation unit, provided you prefix all but one of them to avoid symbol collisions. Define `CSONPATH_USE_PREFIX` before a backend header to prefix its API with the backend name.
+
+For example, to use both json-c and the immutable yyjson backend in the same file:
+
+```c
+#define CSONPATH_USE_PREFIX
+#include "csonpath_json-c.h"
+
+#undef CSONPATH_USE_PREFIX
+#include "csonpath_yyjson_const.h"
+```
+
+To use both yyjson backends (immutable and mutable) together, include the aggregator header:
+
+```c
+#include "csonpath_yyjson.h"
+```
+
+When using the mutable yyjson backend, assign the document pointer to `backend_ctx` before mutable operations:
+
+```c
+struct csonpath *mp = yyjson_mut_csonpath_new("$.a");
+mp->backend_ctx = mdoc;
+yyjson_mut_csonpath_update_or_create(mp, mroot, new_val);
+```
+
+---
+
 ## 🔌 Custom Backends
 
-csonpath is designed to be backend-agnostic. It can work with any data structure that supports array, object, and scalar semantics.
+csonpath is designed to be backend-agnostic. The C core manipulates opaque value pointers through a small set of macros, so it can work with any data structure that supports array, object, and scalar semantics.
 
-To create a custom backend, define the required macros and types in a header file (similar to `csonpath_json-c.h` or `csonpath_python.c`), then include your backend header before `csonpath.h`. This allows you to adapt csonpath for manipulating data in any format that supports array/object semantics, giving you full flexibility beyond just JSON.
+A backend is an adapter that implements those macros for a concrete value representation. To create a custom backend, define the required macros and types in a header file (similar to `csonpath_json-c.h` or `csonpath_yyjson.h`), then include your backend header before `csonpath.h`.
 
-For more details, see the existing backend implementations:
-- `csonpath_json-c.h` — json-c backend
-- `csonpath_python.c` — Python backend
+Existing backend adapters:
+- `csonpath_json-c.h` — json-c values
+- `csonpath_yyjson.h` — yyjson values
+- `csonpath_python.c` — Python C API values (used by the Python bindings)
+- `rust/csonpath_rust_backend.h` — Rust `serde_json::Value` (used by the Rust crate)
 
 ---
 
@@ -271,6 +410,12 @@ For more details, see the existing backend implementations:
 make tests-c
 ```
 
+### Rust Tests
+```sh
+cd rust
+cargo test
+```
+
 ### Python Tests
 ```sh
 make tests-py
@@ -289,7 +434,10 @@ make tests
 |---|---|
 | `csonpath.h`, `csonpath_do.h` | Core implementation (header-only style) |
 | `csonpath_json-c.h` | json-c backend |
+| `csonpath_yyjson.h` | yyjson backend |
 | `csonpath_python.c` | Python C extension backend |
+| `rust/` | Rust crate and its C backend adapter |
+| `csonpath_my_fuzzing.h` | Fuzzer helpers (C) |
 | `tests/` | C and Python test suites |
 | `bench/` | Performance benchmarks |
 

{csonpath-0.16.0 → csonpath-0.18.0}/README.md

@@ -4,9 +4,9 @@
 
 [![Project Sandbox](https://docs.outscale.com/fr/userguide/_images/Project-Sandbox-yellow.svg)](https://docs.outscale.com/en/userguide/Open-Source-Projects.html)
 
-**csonpath** is a partial [JSONPath](https://goessner.net/articles/JsonPath/) implementation in C, with Python bindings. It allows you to query, update, and remove data from JSON objects using path expressions.
+**csonpath** is a partial [JSONPath](https://goessner.net/articles/JsonPath/) implementation in C. It is **backend-agnostic**: the same core engine can query, update, and remove data from any value representation that supports array, object, and scalar semantics—not just JSON.
 
-Unlike many JSONPath libraries, csonpath is **backend-agnostic**: it can work with any C library or environment that manipulates array, object, and scalar types—not just JSON. Out of the box, backends for [json-c](https://github.com/json-c/json-c) and Python are provided.
+Out of the box it ships with C backends for [json-c](https://github.com/json-c/json-c) and [yyjson](https://github.com/ibireme/yyjson), plus language bindings for **Python** and **Rust**.
 
 ---
 
@@ -53,6 +53,8 @@ Unlike many JSONPath libraries, csonpath is **backend-agnostic**: it can work wi
 - [Usage](#-usage)
 - [C API Reference](#-c-api-reference)
 - [Python API Reference](#-python-api-reference)
+- [CLI](#%EF%B8%8F-cli)
+- [Using Multiple Backends](#-using-multiple-backends)
 - [Custom Backends](#-custom-backends)
 - [Running Tests](#-running-tests)
 - [Directory Structure](#-directory-structure)
@@ -63,12 +65,12 @@ Unlike many JSONPath libraries, csonpath is **backend-agnostic**: it can work wi
 
 ## 📦 Installation
 
-### Prerequisites
-- C compiler (`gcc` or `clang`)
-- [json-c](https://github.com/json-c/json-c) library (for C usage)
-- Python 3.x (for Python bindings)
+csonpath is a C library at its core. Pick the instructions for the language you want to use it from.
 
 ### C (json-c)
+
+**Prerequisites:** C compiler (`gcc`, `clang`, or `tcc`), [json-c](https://github.com/json-c/json-c).
+
 Just include the header in your project. There is no separate install step required:
 ```c
 #include "csonpath_json-c.h"
@@ -78,7 +80,23 @@ Make sure to link against `json-c` when compiling:
 gcc myapp.c -o myapp $(pkg-config --cflags --libs json-c)
 ```
 
+### C (yyjson)
+
+**Prerequisites:** C compiler (`gcc`, `clang`, or `tcc`), [yyjson](https://github.com/ibireme/yyjson).
+
+```c
+#include "csonpath_yyjson.h"
+```
+
+Link against `yyjson` when compiling:
+```sh
+gcc myapp.c -o myapp $(pkg-config --cflags --libs yyjson)
+```
+
 ### Python
+
+**Prerequisites:** Python 3.x.
+
 Install from PyPI:
 ```sh
 pip install csonpath
@@ -91,6 +109,23 @@ pip install .
 make pip-dev
 ```
 
+### Rust
+
+**Prerequisites:** Rust toolchain.
+
+The Rust crate is located in `rust/`. Build and test it with:
+```sh
+cd rust
+cargo build
+cargo test
+```
+
+To depend on it from another Rust project:
+```toml
+[dependencies]
+csonpath = { path = "rust" }
+```
+
 ---
 
 ## 🛠️ Usage
@@ -171,6 +206,8 @@ p.update_or_create_callback(dst, my_sync_fn, userdata)
 
 ## 📘 C API Reference
 
+The reference below uses the **json-c** backend as an example (`struct json_object *`). All backends expose the same functions with their own value type.
+
 ```c
 struct csonpath *csonpath_new(const char *path);
 ```
@@ -243,15 +280,117 @@ Free the csonpath object.
 
 ---
 
+## 🖥️ CLI
+
+A standalone C CLI is available in `cli/csonpath_cli.c`. It links directly against `json-c` and the csonpath C core, so it works without Python.
+
+```sh
+make csonpath          # build ./csonpath
+make tests-cli         # run shell tests
+```
+
+It reads JSON from stdin, a file (`-f`), or a string (`-s`) and exposes the library operations through action flags.
+
+```sh
+# Get the first match (default)
+echo '{"a": "value", "array": [1, 2, 3]}' | ./csonpath '$.a'
+# => "value"
+
+# Find all matches
+echo '{"items": [{"price": 5}, {"price": 15}]}' | ./csonpath -a '$.items[?price > 10]'
+# => [{"price":15}]
+
+# One match per line
+echo '{"array": [1, 2, 3]}' | ./csonpath -a -o lines '$.array[*]'
+# => 1
+# => 2
+# => 3
+
+# Set or create a value
+echo '{"a": 1}' | ./csonpath --set '42' '$.x.y.z'
+# => {"a":1,"x":{"y":{"z":42}}}
+
+# Or with a positional value
+echo '{"a": 1}' | ./csonpath '$.x.y.z' '42'
+
+# Remove matches
+echo '{"a": 1, "b": 2}' | ./csonpath -d '$.b'
+# => {"a":1}
+
+# Edit a file in place
+./csonpath -f data.json -p -i --set '"2.0"' '$.version'
+```
+
+### Options
+
+| Option | Description |
+|---|---|
+| `-a`, `--all` | Return all matches instead of the first one. |
+| `-d`, `--delete` | Remove matches and print the modified JSON. |
+| `--set VALUE` | Set `PATH` to `VALUE` (JSON). |
+| `VALUE` (positional) | Alternative to `--set`. |
+| `-r`, `--raw` | Treat the value as a raw string. |
+| `-i`, `--in-place` | Edit `FILE` in place (requires `--file`). |
+| `--strict` | Exit with an error if `--delete` removes nothing. |
+| `-f FILE`, `--file FILE` | Read JSON from `FILE` instead of stdin. |
+| `-s JSON`, `--string JSON` | Read JSON from a string. |
+| `-j`, `--jq-like` | Allow jq-style paths without a leading `$`. |
+| `-p`, `--pretty` | Pretty-print JSON output. |
+| `-o {json,pretty,raw,lines}` | Output format (default: `json`). |
+| `-e`, `--empty-array` | Return `[]` instead of nothing when `-a` matches nothing. |
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Success. |
+| `1` | No match found, or `--strict` delete found nothing. |
+| `EINVAL` | Usage error, JSON parse error, JSONPath compilation error, or invalid JSON value. |
+| `errno` | I/O error (e.g. `ENOENT`, `EACCES`). |
+
+---
+
+## 🧩 Using Multiple Backends
+
+You can include more than one csonpath backend in the same translation unit, provided you prefix all but one of them to avoid symbol collisions. Define `CSONPATH_USE_PREFIX` before a backend header to prefix its API with the backend name.
+
+For example, to use both json-c and the immutable yyjson backend in the same file:
+
+```c
+#define CSONPATH_USE_PREFIX
+#include "csonpath_json-c.h"
+
+#undef CSONPATH_USE_PREFIX
+#include "csonpath_yyjson_const.h"
+```
+
+To use both yyjson backends (immutable and mutable) together, include the aggregator header:
+
+```c
+#include "csonpath_yyjson.h"
+```
+
+When using the mutable yyjson backend, assign the document pointer to `backend_ctx` before mutable operations:
+
+```c
+struct csonpath *mp = yyjson_mut_csonpath_new("$.a");
+mp->backend_ctx = mdoc;
+yyjson_mut_csonpath_update_or_create(mp, mroot, new_val);
+```
+
+---
+
 ## 🔌 Custom Backends
 
-csonpath is designed to be backend-agnostic. It can work with any data structure that supports array, object, and scalar semantics.
+csonpath is designed to be backend-agnostic. The C core manipulates opaque value pointers through a small set of macros, so it can work with any data structure that supports array, object, and scalar semantics.
 
-To create a custom backend, define the required macros and types in a header file (similar to `csonpath_json-c.h` or `csonpath_python.c`), then include your backend header before `csonpath.h`. This allows you to adapt csonpath for manipulating data in any format that supports array/object semantics, giving you full flexibility beyond just JSON.
+A backend is an adapter that implements those macros for a concrete value representation. To create a custom backend, define the required macros and types in a header file (similar to `csonpath_json-c.h` or `csonpath_yyjson.h`), then include your backend header before `csonpath.h`.
 
-For more details, see the existing backend implementations:
-- `csonpath_json-c.h` — json-c backend
-- `csonpath_python.c` — Python backend
+Existing backend adapters:
+- `csonpath_json-c.h` — json-c values
+- `csonpath_yyjson.h` — yyjson values
+- `csonpath_python.c` — Python C API values (used by the Python bindings)
+- `rust/csonpath_rust_backend.h` — Rust `serde_json::Value` (used by the Rust crate)
 
 ---
 
@@ -262,6 +401,12 @@ For more details, see the existing backend implementations:
 make tests-c
 ```
 
+### Rust Tests
+```sh
+cd rust
+cargo test
+```
+
 ### Python Tests
 ```sh
 make tests-py
@@ -280,7 +425,10 @@ make tests
 |---|---|
 | `csonpath.h`, `csonpath_do.h` | Core implementation (header-only style) |
 | `csonpath_json-c.h` | json-c backend |
+| `csonpath_yyjson.h` | yyjson backend |
 | `csonpath_python.c` | Python C extension backend |
+| `rust/` | Rust crate and its C backend adapter |
+| `csonpath_my_fuzzing.h` | Fuzzer helpers (C) |
 | `tests/` | C and Python test suites |
 | `bench/` | Performance benchmarks |