@casadi/casadi-reader 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,3 +1,14 @@
+# 0.2.0
+
+- Generate JavaScript, Python, C/C++, MATLAB and Julia readers from the compact serialization scheme, with language-specific runtime templates.
+- Decode MX/SX expression vectors and their ordered dependencies, in ordinary and debug files.
+- Refresh serializer layouts, including irregular nonzero assignments and finite differences.
+- Preserve typed fields and shared references for generic Function property inspection.
+- Remove structural `offset` and `byteLength` fields; keep `root` and `roots`. Lazy byte payload handles retain their I/O metadata.
+- Use explicit layout calls instead of runtime inheritance resolution.
+
+Breaking change: structural records no longer expose byte spans. npm publication remains JavaScript-only; the other language readers are available as source.
+
 # 0.1.0
 
 - Replace MX graph interpretation with a schema-driven structural reader.

package/NOTICE

@@ -1,7 +1,7 @@
 casadi-reader's implementation is licensed under the MIT License (LICENSE).
 
-The vendored schemes/serialization_scheme.json contains serializer source
-excerpts from CasADi 3.8.1, https://github.com/casadi/casadi. Those excerpts
+The vendored schemes/serialization_scheme.json contains decoding metadata derived
+from CasADi 3.8.1, https://github.com/casadi/casadi. The upstream sources
 retain CasADi's LGPL-3.0-or-later license; they are not relicensed by this
 repository's MIT License. License texts are in LICENSES/.
 
@@ -11,7 +11,7 @@ Copyright (C) 2010-2023 Joel Andersson, Joris Gillis, Moritz Diehl,
 Copyright (C) 2011-2014 Greg Horn
 Additional source-file notices remain available in the referenced CasADi tree.
 
-The published reader runtime assets contain generated protocol metadata,
-not the scheme's serializer source excerpts. The full scheme is included in
+The published reader runtime assets contain generated decoding metadata.
+Neither these assets nor the vendored scheme contains serializer source bodies. The full scheme is included in
 this source repository and Python source distributions as a generation/test
 input; it is not needed by the installed readers.

package/README.md

@@ -8,8 +8,9 @@ reconstruct entry mappings, or build visualization graphs. Those tasks belong
 in [casadi-viz](https://github.com/casadi/casadi-viz). An ONNX-backed function is
 read as serialized configuration and model bytes; the reader never runs ONNX.
 
-The current development and release focus is npm. Other language prototypes in
-this repository are deferred and still use the earlier MX-specific API.
+JavaScript, Python, C, C++, MATLAB and Julia expose the same structural document
+contract. C and C++ share a native engine; MATLAB and Julia bind that engine.
+Only JavaScript packaging and publishing are currently enabled in CI.
 
 ## API
 
@@ -39,26 +40,23 @@ The output is ordinary JavaScript data:
     {
       type: 'Function',
       fields: [
-        {name: 'Function::null', type: 'bool', value: false, offset: 19, byteLength: 1},
+        {name: 'Function::null', type: 'bool', value: false},
         // Serialized field order and duplicate field names are preserved.
       ],
-      layouts: ['MXFunction::serialize_body', /* base layouts ... */],
-      offset: 18,
-      byteLength: 1234
+      layouts: ['MXFunction::serialize_body', /* base layouts ... */]
     }
   ]
 }
 ```
 
-The example's indices and byte counts are illustrative. `$ref` values are
+The example's indices are illustrative. `$ref` values are
 zero-based indices into `objects`. Shared definitions appear once, even when
 referenced by several functions. Inline structures have their own `type` and
 `fields`. Vectors are arrays, pairs are two-element arrays, and maps are
 `{$map: [[key, value], ...]}` so arbitrary key types and field order survive.
 Repeated serializer fields remain repeated entries, not overwritten properties.
 64-bit integers outside JavaScript's exact range use `{$integer: "..."}`;
-nonfinite floating-point values use `{$float: "..."}`. Byte offsets count decoded
-wire bytes from the stream start, not characters in its a–p encoding.
+nonfinite floating-point values use `{$float: "..."}`. Records and fields contain no source byte ranges.
 
 A file can contain several roots; `roots` retains them in order. `root` is a
 convenience index for a single shared-object root, otherwise null.
@@ -110,13 +108,20 @@ Python 3.9+ and the development dependencies in package-lock.json.
 ## Scheme and coverage
 
 CasADi's `misc/generate_serialization_scheme.py` produces the vendored
-`schemes/serialization_scheme.json`, including lowered reader layouts.
-`npm run generate` compiles that data into reader assets. The JavaScript engine
-executes field, base-layout, repetition, condition and discriminator instructions;
-it contains no SX/MX-specific decoding methods.
+`schemes/serialization_scheme.json`: decoding rules and validation metadata,
+without source bodies, pack expressions, source locations or extraction offsets.
+Field bindings are retained only when decoding expressions can reference them.
+`npm run generate` generates all six readers. The generic engines
+execute field, base-layout, repetition, condition and discriminator instructions;
+they contain no SX/MX-specific decoding methods. A small `Generator` base class
+and language subclasses in `scripts/reader_generators.py` emit scheme data and
+copy runtime templates from `scripts/templates`. Edit templates, then regenerate.
+Use `--scheme PATH --output-root DIR` with `scripts/generate-reader-assets.py`
+to generate readers for another extracted scheme without changing this checkout.
 
 The extractor includes inline serializers, inheritance and tensor metadata
-helpers. It derives operation dispatch families from CasADi's native dispatcher
+helpers. Inherited serializers and template aliases are explicit layouts with
+call instructions; readers perform no C++ inheritance lookup. It derives operation dispatch families from CasADi's native dispatcher
 and plugin registrations from the source. No mathematical evaluation occurs.
 
 Coverage is still experimental. Native plain/debug fixture pairs validate MX,
@@ -145,6 +150,34 @@ extracted npm tarball over HTTP and verify one JavaScript request with no scheme
 JSON or CasADi runtime request. Native CasADi is used only when regenerating the
 fixtures, via `scripts/generate-fixtures.py` and the Resource fixture generator.
 
+## Other languages
+
+Python is dependency-free: `PYTHONPATH=python python3 -m casadi_reader model.casadi`.
+`casadi_reader.read_casadi(path)` returns the same typed records as JavaScript;
+`to_json(document)` makes them portable to the viewer. Use `lazy=True` for byte
+handles and keep their source open while reading them.
+
+Build the standalone native library and CLI using the root `CMakeLists.txt`.
+C uses `cr_open_type` for files or `cr_decode` for copied encoded input;
+`cr_json` exposes the structural JSON, valid until `cr_close`.
+C++ wraps this lifetime in `casadi_reader::Document`. Both accept an optional
+raw root type, such as `Resource`. Lazy byte access checks ranges and requires
+an open document. The native engine limits collection/eager byte counts to one
+million, nesting to 256, and input size to 1 GiB; larger opaque payloads can use
+lazy mode within the file limit.
+
+MATLAB uses `casadi_reader.read(path)` or a `casadi_reader.Document` for lazy
+bytes; compile `matlab/casadi_reader_mex.cpp` with the native engine.
+Julia uses `CasadiReader.read_casadi(path)` or `Document(path; lazy=true)` and
+loads the native library through `CASADI_READER_LIBRARY`.
+
+`python/tests/test_reader.py` compares every field against JavaScript
+on all plain/debug fixtures, and also checks the native CLI when
+`CASADI_READER_NATIVE` points to it. `scripts/test-bindings.py` runs the same
+fixture comparisons in MATLAB/Julia; see its `--help` for local paths. Native
+`native/tests/api.c` exercises the C ABI, copied input and lazy payload bounds.
+These local language tests do not add language packaging to CI.
+
 ## Publishing
 
 `publish.yml` publishes on a published GitHub release, after tests. The release
@@ -156,5 +189,5 @@ repository `casadi-reader`, workflow `publish.yml`, with no environment name and
 with direct `npm publish` allowed. Publishing uses OIDC and provenance, with no
 npm token secret. See [npm's documentation](https://docs.npmjs.com/trusted-publishers/).
 
-The reader implementation is MIT licensed. Source excerpts in the vendored
-scheme retain CasADi's original license; see NOTICE.
+The reader implementation is MIT licensed. The vendored scheme is derived from
+CasADi; upstream attribution and license texts are retained in NOTICE and LICENSES.