jsonatapy 2.2.4__tar.gz → 2.2.5__tar.gz

{jsonatapy-2.2.4 → jsonatapy-2.2.5}/CHANGELOG.md

@@ -19,6 +19,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Security
 
+## [2.2.5] - 2026-07-14
+
+### Added
+- C API (`capi` cargo feature): use the engine from C, C++, or any language with C interop.
+  Eight functions, JSON text in/out (`jsonata_compile`, `jsonata_evaluate`, `jsonata_bind_var`,
+  `jsonata_free_expr`, `jsonata_free_string`, `jsonata_last_error_message`,
+  `jsonata_last_error_code`, `jsonata_version`), thread-local error slot, and engine panics
+  caught at the boundary instead of aborting the host process. Ships with a hand-written
+  header (`bindings/c/jsonata.h`), build/link/CMake documentation (`bindings/c/README.md`),
+  and a CI-gated smoke test compiled as both C and C++. Build with
+  `cargo build --release --features capi`.
+
+### Fixed
+- Performance regression in v2.2.4 on small/fast expressions (issue #74): the
+  `JSONATAPY_FORCE_TREE_WALKER` test toggle read the environment variable on every
+  evaluation (both `evaluate()` and `evaluate_json()`), costing ~100-200ns per call —
+  10-30% of a sub-microsecond expression. The toggle is now a process-wide atomic seeded
+  from the environment once at import (whole-process forcing works unchanged) and flippable
+  via a private test hook. Small-expression benchmarks recover 5-16%; the remaining few
+  percent vs v2.2.3 on tiny payloads is the documented cost of lazy conversion (which makes
+  realistic workloads up to 48% faster, see 2.2.4 notes).
+
+### Changed
+- Benchmark tooling: PR benchmark comments and release regression issues now state their
+  comparison baseline explicitly (which commit/release, recorded when, on which runner),
+  and the vs-jsonata-js comparison is labeled as such.
+
 ## [2.2.4] - 2026-07-13
 
 ### Added

{jsonatapy-2.2.4 → jsonatapy-2.2.5}/Cargo.lock

@@ -586,7 +586,7 @@ dependencies = [
 
 [[package]]
 name = "jsonata-core"
-version = "2.2.4"
+version = "2.2.5"
 dependencies = [
  "assert_cmd",
  "base64",

{jsonatapy-2.2.4 → jsonatapy-2.2.5}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "jsonata-core"
-version = "2.2.4"
+version = "2.2.5"
 edition = "2021"
 authors = ["txjmb <txjmb@users.noreply.github.com>"]
 description = "High-performance Rust implementation of JSONata query and transformation language"
@@ -63,6 +63,7 @@ simd = ["dep:simd-json"]
 python = ["dep:pyo3"]
 cli = ["dep:clap"]
 bench = []   # exposes _bench facade for Criterion benchmarks
+capi = []
 
 [dev-dependencies]
 criterion = "0.8"

{jsonatapy-2.2.4 → jsonatapy-2.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jsonatapy
-Version: 2.2.4
+Version: 2.2.5
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -151,6 +151,24 @@ echo '{"orders":[{"product":"Laptop","price":1200}]}' | jsonatapy 'orders[price
 
 See [CLI Reference](docs/cli.md) for the full flag/exit-code contract.
 
+## C / C++ quick start
+
+The engine exposes a small C ABI (8 functions, JSON text in/out), usable
+from C, C++, or any language with C interop:
+
+```c
+JsonataExpr *expr = jsonata_compile("$sum(items.price)");
+char *result = jsonata_evaluate(expr, "{\"items\":[{\"price\":2},{\"price\":3}]}");
+// result: "5"
+jsonata_free_string(result);
+jsonata_free_expr(expr);
+```
+
+Build with `cargo build --release --features capi` and include
+[`bindings/c/jsonata.h`](bindings/c/jsonata.h). See the
+[C API guide](bindings/c/README.md) for linking (gcc/clang, Makefile,
+CMake), the memory/threading contract, and error handling.
+
 ---
 
 ## What is JSONata?

{jsonatapy-2.2.4 → jsonatapy-2.2.5}/README.md

@@ -102,6 +102,24 @@ echo '{"orders":[{"product":"Laptop","price":1200}]}' | jsonatapy 'orders[price
 
 See [CLI Reference](docs/cli.md) for the full flag/exit-code contract.
 
+## C / C++ quick start
+
+The engine exposes a small C ABI (8 functions, JSON text in/out), usable
+from C, C++, or any language with C interop:
+
+```c
+JsonataExpr *expr = jsonata_compile("$sum(items.price)");
+char *result = jsonata_evaluate(expr, "{\"items\":[{\"price\":2},{\"price\":3}]}");
+// result: "5"
+jsonata_free_string(result);
+jsonata_free_expr(expr);
+```
+
+Build with `cargo build --release --features capi` and include
+[`bindings/c/jsonata.h`](bindings/c/jsonata.h). See the
+[C API guide](bindings/c/README.md) for linking (gcc/clang, Makefile,
+CMake), the memory/threading contract, and error handling.
+
 ---
 
 ## What is JSONata?

jsonatapy-2.2.5/bindings/c/README.md

@@ -0,0 +1,160 @@
+# jsonata-core C API
+
+Use [JSONata](https://jsonata.org) — the JSON query and transformation
+language — from C, C++, or any language with C interop, backed by
+[jsonata-core](https://github.com/txjmb/jsonata-core), a high-performance
+Rust implementation with 100% reference-suite compatibility against
+jsonata-js.
+
+The API is deliberately small: JSON text in, JSON text out, eight
+functions. See [`jsonata.h`](jsonata.h) for the authoritative contract.
+
+```c
+#include "jsonata.h"
+#include <stdio.h>
+
+int main(void) {
+    JsonataExpr *expr = jsonata_compile("$sum(order.items.(price * qty))");
+    if (!expr) {
+        char *err = jsonata_last_error_message();
+        fprintf(stderr, "compile failed: %s\n", err);
+        jsonata_free_string(err);
+        return 1;
+    }
+
+    char *result = jsonata_evaluate(expr,
+        "{\"order\":{\"items\":[{\"price\":9.99,\"qty\":2},{\"price\":5,\"qty\":1}]}}");
+    if (result) {
+        printf("total: %s\n", result);   /* total: 24.98 */
+        jsonata_free_string(result);
+    } else {
+        char *err = jsonata_last_error_message();
+        if (err) {                        /* error */
+            fprintf(stderr, "evaluate failed: %s\n", err);
+            jsonata_free_string(err);
+        } else {                          /* JSONata "undefined" — no match */
+            printf("no result\n");
+        }
+    }
+
+    jsonata_free_expr(expr);
+    return 0;
+}
+```
+
+## Building the shared library
+
+Requires a Rust toolchain (rustc 1.70+, [rustup.rs](https://rustup.rs)):
+
+```sh
+git clone https://github.com/txjmb/jsonata-core
+cd jsonata-core
+cargo build --release --features capi
+```
+
+This produces the shared library in `target/release/`:
+
+| Platform | Library |
+|---|---|
+| Linux | `libjsonata_core.so` |
+| macOS | `libjsonata_core.dylib` |
+| Windows | `jsonata_core.dll` (+ `jsonata_core.dll.lib` import lib) |
+
+The only header you need is `bindings/c/jsonata.h`.
+
+## Compiling and linking
+
+**C** (gcc/clang):
+
+```sh
+gcc -Wall -o myapp myapp.c -I/path/to/jsonata-core/bindings/c \
+    -L/path/to/jsonata-core/target/release -ljsonata_core
+LD_LIBRARY_PATH=/path/to/jsonata-core/target/release ./myapp
+```
+
+**C++**: the header is C++-safe (`extern "C"` guarded); compile and link
+exactly as above with `g++`/`clang++`.
+
+For deployment, install the library somewhere on the loader path (or set
+`rpath`): `-Wl,-rpath,/opt/myapp/lib` at link time avoids
+`LD_LIBRARY_PATH` at run time.
+
+**Makefile snippet:**
+
+```make
+JSONATA_DIR := /path/to/jsonata-core
+CFLAGS  += -I$(JSONATA_DIR)/bindings/c
+LDFLAGS += -L$(JSONATA_DIR)/target/release -Wl,-rpath,$(JSONATA_DIR)/target/release
+LDLIBS  += -ljsonata_core
+
+myapp: myapp.o
+	$(CC) $(LDFLAGS) -o $@ $^ $(LDLIBS)
+```
+
+**CMake snippet:**
+
+```cmake
+set(JSONATA_DIR /path/to/jsonata-core)
+
+add_library(jsonata_core SHARED IMPORTED)
+set_target_properties(jsonata_core PROPERTIES
+    IMPORTED_LOCATION ${JSONATA_DIR}/target/release/libjsonata_core.so
+    INTERFACE_INCLUDE_DIRECTORIES ${JSONATA_DIR}/bindings/c)
+
+target_link_libraries(myapp PRIVATE jsonata_core)
+```
+
+(Optionally wrap the `cargo build` in a CMake `add_custom_command` so the
+Rust library rebuilds with your project.)
+
+## API rules (the short version)
+
+1. **Ownership:** every `char*` the library returns is yours — free it with
+   `jsonata_free_string()`. The single exception is `jsonata_version()`
+   (static; never free). Never free library strings with your own
+   `free()` — allocators may differ.
+2. **NULL from `jsonata_evaluate` is ambiguous by design:** check
+   `jsonata_last_error_message()`. Non-NULL → error. NULL → the JSONata
+   result was *undefined* (a normal outcome — e.g. a path that matched
+   nothing). This mirrors JSONata semantics, where `undefined` and `null`
+   are distinct.
+3. **Error codes:** `jsonata_last_error_code()` returns the JSONata spec
+   code (`"T2002"`, `"S0201"`, `"D3030"`, …) when the failure has one,
+   NULL otherwise. Error source positions are not exposed (the engine
+   does not currently track them).
+4. **Threading:** one `JsonataExpr*` per thread — create, use, and free a
+   handle on the same thread. Handles are cheap; compile per thread rather
+   than sharing. Different threads with their own handles are fine, and
+   the error slot is thread-local.
+5. **Reuse handles:** `jsonata_compile` once, `jsonata_evaluate` many
+   times — the expression is JIT-compiled to bytecode on first evaluation
+   and reused. Compilation is the expensive step.
+6. **Variables:** `jsonata_bind_var(expr, "x", "[1,2,3]")` binds `$x` for
+   all subsequent evaluations on that handle (values are JSON text;
+   re-binding replaces).
+7. **Panics:** internal engine panics are caught at the boundary and
+   surface as errors prefixed `internal error:` — they will not abort
+   your process.
+
+## Smoke test
+
+[`examples/smoke.c`](examples/smoke.c) exercises the full API surface and
+doubles as usage documentation. Build and run it from the repo root:
+
+```sh
+cargo build --release --features capi
+gcc -Wall -Wextra -Werror -o smoke bindings/c/examples/smoke.c \
+    -Ltarget/release -ljsonata_core
+LD_LIBRARY_PATH=target/release ./smoke
+```
+
+CI compiles and runs it (as both C and C++) on every change to the C ABI.
+
+## Related
+
+- [jsonatapy](https://pypi.org/project/jsonatapy/) — the Python binding of
+  this engine (PyPI, zero runtime dependencies).
+- [`jsonata` CLI](../../docs/) — a jq-style command-line interface to the
+  same engine.
+- [jsonata-js](https://github.com/jsonata-js/jsonata) — the reference
+  implementation this engine tracks (1682/1682 reference tests passing).

jsonatapy-2.2.5/bindings/c/examples/smoke.c

@@ -0,0 +1,133 @@
+/*
+ * smoke.c — compile-and-run smoke test for the jsonata-core C ABI.
+ *
+ * Exercises every function in jsonata.h against the real library and exits
+ * non-zero on the first failure. CI builds and runs this on every PR that
+ * touches the C ABI; see bindings/c/README.md for the manual build/run
+ * commands.
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include "../jsonata.h"
+
+static int failures = 0;
+
+#define CHECK(cond, name)                                                    \
+    do {                                                                     \
+        if (cond) {                                                          \
+            printf("PASS  %s\n", name);                                      \
+        } else {                                                             \
+            printf("FAIL  %s (line %d)\n", name, __LINE__);                  \
+            failures++;                                                      \
+        }                                                                    \
+    } while (0)
+
+static char *take_error(void) { return jsonata_last_error_message(); }
+
+int main(void) {
+    /* version */
+    const char *v = jsonata_version();
+    CHECK(v != NULL && strlen(v) > 0, "version non-empty");
+
+    /* simple path */
+    {
+        JsonataExpr *e = jsonata_compile("user.name");
+        CHECK(e != NULL, "compile simple path");
+        char *r = jsonata_evaluate(e, "{\"user\":{\"name\":\"Alice\"}}");
+        CHECK(r != NULL && strcmp(r, "\"Alice\"") == 0, "evaluate simple path");
+        jsonata_free_string(r);
+        jsonata_free_expr(e);
+    }
+
+    /* object construction + arithmetic */
+    {
+        JsonataExpr *e = jsonata_compile("{\"n\": a + b}");
+        char *r = jsonata_evaluate(e, "{\"a\":1,\"b\":2}");
+        CHECK(r != NULL && strcmp(r, "{\"n\":3}") == 0, "object result");
+        jsonata_free_string(r);
+        jsonata_free_expr(e);
+    }
+
+    /* undefined result: NULL with EMPTY error slot */
+    {
+        JsonataExpr *e = jsonata_compile("missing.path");
+        char *r = jsonata_evaluate(e, "{\"a\":1}");
+        char *err = take_error();
+        CHECK(r == NULL && err == NULL, "undefined -> NULL + empty error");
+        jsonata_free_string(err);
+        jsonata_free_expr(e);
+    }
+
+    /* parse error: NULL handle + message */
+    {
+        JsonataExpr *e = jsonata_compile("a.b[");
+        char *err = take_error();
+        CHECK(e == NULL && err != NULL && strlen(err) > 0,
+              "parse error -> NULL + message");
+        jsonata_free_string(err);
+    }
+
+    /* coded evaluation error: message + spec code */
+    {
+        JsonataExpr *e = jsonata_compile("$number(b)");
+        char *r = jsonata_evaluate(e, "{\"b\":[1]}");
+        char *err = take_error();
+        char *code = jsonata_last_error_code();
+        CHECK(r == NULL && err != NULL, "eval error -> NULL + message");
+        CHECK(code != NULL && strcmp(code, "D3030") == 0,
+              "eval error -> spec code D3030");
+        jsonata_free_string(err);
+        jsonata_free_string(code);
+        jsonata_free_expr(e);
+    }
+
+    /* variable binding */
+    {
+        JsonataExpr *e = jsonata_compile("$sum($xs) + n");
+        int rc = jsonata_bind_var(e, "$xs", "[1,2,3]");
+        CHECK(rc == 0, "bind_var succeeds");
+        char *r = jsonata_evaluate(e, "{\"n\":10}");
+        CHECK(r != NULL && strcmp(r, "16") == 0, "evaluate with bound var");
+        jsonata_free_string(r);
+        jsonata_free_expr(e);
+    }
+
+    /* invalid input JSON: NULL + uncoded message */
+    {
+        JsonataExpr *e = jsonata_compile("a");
+        char *r = jsonata_evaluate(e, "{not json");
+        char *err = take_error();
+        char *code = jsonata_last_error_code();
+        CHECK(r == NULL && err != NULL && strstr(err, "invalid input JSON") != NULL,
+              "invalid input JSON -> message");
+        CHECK(code == NULL, "invalid input JSON -> no spec code");
+        jsonata_free_string(err);
+        jsonata_free_string(code);
+        jsonata_free_expr(e);
+    }
+
+    /* multibyte UTF-8 round trip */
+    {
+        JsonataExpr *e = jsonata_compile("$uppercase(name)");
+        char *r = jsonata_evaluate(e, "{\"name\":\"h\xC3\xA9llo \xE2\x9C\x93\"}");
+        CHECK(r != NULL && strcmp(r, "\"H\xC3\x89LLO \xE2\x9C\x93\"") == 0,
+              "multibyte UTF-8 round trip");
+        jsonata_free_string(r);
+        jsonata_free_expr(e);
+    }
+
+    /* NULL tolerance of free functions */
+    jsonata_free_expr(NULL);
+    jsonata_free_string(NULL);
+    CHECK(1, "free(NULL) is a no-op");
+
+    if (failures == 0) {
+        printf("SMOKE OK (jsonata-core %s)\n", v);
+        return 0;
+    }
+    printf("SMOKE FAILED: %d failure(s)\n", failures);
+    return 1;
+}

jsonatapy-2.2.5/bindings/c/jsonata.h

@@ -0,0 +1,104 @@
+/*
+ * jsonata.h — C API for jsonata-core, a high-performance Rust implementation
+ * of the JSONata query and transformation language (https://jsonata.org).
+ *
+ * Implemented by src/capi.rs (build with `cargo build --release --features
+ * capi`, link against the produced libjsonata_core.{so,dylib} /
+ * jsonata_core.dll). This header is hand-maintained; CI compiles
+ * bindings/c/examples/smoke.c against it to keep the two in sync.
+ *
+ * ── Contract ────────────────────────────────────────────────────────────
+ *
+ * Strings.  All strings crossing the boundary are UTF-8, NUL-terminated.
+ * JSON documents and results cross as JSON text; there is no C-visible
+ * structured value model. Every char* RETURNED by this library is owned by
+ * the caller and must be released with jsonata_free_string() — except
+ * jsonata_version(), which returns a static string that must never be
+ * freed.
+ *
+ * Errors.  Failures are reported through a thread-local "last error" slot:
+ *   - jsonata_compile() returns NULL and sets the slot on failure.
+ *   - jsonata_evaluate() returns NULL in TWO cases, disambiguated by the
+ *     slot: if jsonata_last_error_message() returns non-NULL it was an
+ *     error; if it returns NULL the JSONata result was *undefined* (a
+ *     legitimate result — e.g. a path that matched nothing).
+ *   - jsonata_bind_var() returns 0 on success, -1 on failure (slot set).
+ * Successful calls clear the slot. jsonata_last_error_code() additionally
+ * extracts the JSONata specification error code ("T2002", "S0201",
+ * "D3030", ...) when the failure has one; errors without a spec code
+ * (e.g. invalid input JSON) yield NULL. Error source positions are not
+ * available — the engine does not currently track them.
+ *
+ * Threading.  A JsonataExpr* must be created, used, and freed on a single
+ * thread (the engine's value model is reference-counted without atomics).
+ * Different threads may each use their own handles concurrently; the error
+ * slot is thread-local, so per-thread error reporting never races.
+ *
+ * Panics.  Internal engine panics are caught at this boundary and reported
+ * as errors (message prefixed "internal error:"); they neither unwind into
+ * the caller nor abort the host process.
+ */
+
+#ifndef JSONATA_CORE_H
+#define JSONATA_CORE_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* An opaque compiled-expression handle. Not thread-safe; see header notes. */
+typedef struct JsonataExpr JsonataExpr;
+
+/*
+ * Compile a JSONata expression (UTF-8).
+ * Returns a handle, or NULL on failure (check jsonata_last_error_message).
+ * Free with jsonata_free_expr().
+ */
+JsonataExpr *jsonata_compile(const char *expr_utf8);
+
+/*
+ * Evaluate the compiled expression against a JSON document (UTF-8 JSON
+ * text). Returns the result as JSON text (caller frees with
+ * jsonata_free_string), or NULL — meaning *undefined* if
+ * jsonata_last_error_message() is NULL, otherwise an error.
+ * The handle may be reused for any number of evaluations; the expression
+ * is compiled to bytecode lazily on first use.
+ */
+char *jsonata_evaluate(JsonataExpr *expr, const char *json_utf8);
+
+/*
+ * Bind a variable ($name) on the expression from a JSON value (UTF-8 JSON
+ * text). Applies to every subsequent jsonata_evaluate() on this handle.
+ * A leading '$' in name is accepted and stripped; re-binding an existing
+ * name replaces its value. Returns 0 on success, -1 on error (slot set).
+ */
+int jsonata_bind_var(JsonataExpr *expr, const char *name,
+                     const char *json_value_utf8);
+
+/* Free a handle returned by jsonata_compile(). NULL is a no-op. */
+void jsonata_free_expr(JsonataExpr *expr);
+
+/* Free a string returned by this library. NULL is a no-op. */
+void jsonata_free_string(char *s);
+
+/*
+ * The last error message on this thread, as a fresh copy (caller frees
+ * with jsonata_free_string), or NULL if the last call succeeded.
+ */
+char *jsonata_last_error_message(void);
+
+/*
+ * The JSONata spec code of the last error on this thread ("T2002", ...),
+ * as a fresh copy (caller frees with jsonata_free_string), or NULL when
+ * there is no error or the error carries no spec code.
+ */
+char *jsonata_last_error_code(void);
+
+/* The jsonata-core version, e.g. "2.2.4". Static string — do NOT free. */
+const char *jsonata_version(void);
+
+#ifdef __cplusplus
+} /* extern "C" */
+#endif
+
+#endif /* JSONATA_CORE_H */

{jsonatapy-2.2.4 → jsonatapy-2.2.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "jsonatapy"
-version = "2.2.4"
+version = "2.2.5"
 description = "High-performance Python/Rust implementation of JSONata query and transformation language"
 authors = [
     {name = "txjmb", email = "txjmb@users.noreply.github.com"}

{jsonatapy-2.2.4 → jsonatapy-2.2.5}/python/jsonatapy/__init__.py

@@ -28,6 +28,11 @@ from ._jsonatapy import (
     __jsonata_version__,
     __version__,
 )
+
+# Private test hooks (not public API): runtime toggle forcing the
+# tree-walking evaluator; seeded from JSONATAPY_FORCE_TREE_WALKER at import.
+from ._jsonatapy import _get_force_tree_walker as _get_force_tree_walker
+from ._jsonatapy import _set_force_tree_walker as _set_force_tree_walker
 from ._jsonatapy import (
     compile as _compile,
 )