struct2ui 0.1.0__tar.gz → 0.3.0__tar.gz

struct2ui-0.3.0/PKG-INFO

@@ -0,0 +1,362 @@
+Metadata-Version: 2.4
+Name: struct2ui
+Version: 0.3.0
+Summary: Render C struct / JSON schema as editable PySide6 UI, export to C/JSON/bin
+Author: Jay
+License: MIT License
+        
+        Copyright (c) 2026 Jay
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Keywords: qt,pyside6,gui,c-struct,json-schema,code-generation,parameter-tuning
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: User Interfaces
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Qt.py>=1.3
+Provides-Extra: pyside6
+Requires-Dist: PySide6>=6.4; extra == "pyside6"
+Provides-Extra: pyqt6
+Requires-Dist: PyQt6>=6.4; extra == "pyqt6"
+Provides-Extra: elf
+Requires-Dist: pyelftools>=0.29; extra == "elf"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pyelftools>=0.29; extra == "dev"
+Dynamic: license-file
+
+# struct2ui
+
+Render C structs / JSON schemas as an **editable PySide6 UI**, and convert freely between **C / JSON / bin**. Built for algorithm parameter tuning: describe a C interface in JSON, auto-generate a Qt form, edit it, then export back to C source, JSON, or binary.
+
+## Features
+
+- **JSON → UI**: describe C structs / enums / arrays with minimal JSON and auto-render Qt widgets (int→QSpinBox, float→QDoubleSpinBox, enum→QComboBox, etc.).
+- **Embeddable**: `StructEditor` is a plain `QWidget` that drops into any PySide6 / PyQt UI.
+- **Multi-format export**: edited results export to C source, JSON, or binary; C source can also be parsed back into a schema.
+- **Validation**: keyword spell-checking (with “Did you mean X?” hints), semantic audits (`min<=max`, `step>0`), and pipeline cross-validation.
+- **Qt-binding agnostic**: built on [Qt.py](https://github.com/mottosso/Qt.py) — works with PySide6 / PyQt6 / PySide2 / PyQt5.
+
+## Installation
+
+```bash
+pip install struct2ui
+
+# Pick a Qt binding (choose one)
+pip install "struct2ui[pyside6]"
+pip install "struct2ui[pyqt6]"
+
+# Enable ELF layout verification (optional)
+pip install "struct2ui[elf]"
+```
+
+> The library itself only depends on `Qt.py`; you must install a Qt binding (PySide6 / PyQt6 / etc.) yourself.
+> ELF verification depends on `pyelftools`, installed via the `[elf]` extra.
+
+## Quick Start
+
+```python
+from Qt import QtWidgets
+from struct2ui import StructEditor
+
+app = QtWidgets.QApplication([])
+
+editor = StructEditor(
+    flow_file="abc.json",   # pipeline definition file (optional)
+    cfg_dir="cfg_t",        # modules dir: *.json holding struct/enum/typedef (optional)
+)
+editor.resize(480, 600)
+editor.show()
+
+app.exec_()
+```
+
+## JSON Schema Reference
+
+This is the core of the library: you describe your C types in JSON and the UI is
+generated from it. Files live in the **modules directory** (`cfg_dir`), one
+`*.json` per logical group. Each file is a flat object whose keys are either
+**type names** (your structs / enums) or the reserved key `typedefs`.
+
+### File layout
+
+```jsonc
+{
+  // optional free-form metadata (ignored by the loader, allowed anywhere)
+  "version": "1.0",
+  "description": "audio EQ parameters",
+
+  // type aliases: map a custom C type to a primitive
+  "typedefs": { "gain_t": "int32_t", "freq_t": "float" },
+
+  // a struct definition
+  "eq_cfg_t": {
+    "type": "struct",
+    "items": [
+      { "name": "enabled", "type": "uint8_t", "value": 1 },
+      { "name": "gain",    "type": "gain_t",  "value": 0,
+        "min": -12, "max": 12, "step": 1, "unit": "dB",
+        "tip": "output gain", "when": { "enabled": 1 } }
+    ]
+  },
+
+  // an enum definition
+  "mode_t": {
+    "type": "enum",
+    "items": { "OFF": 0, "LOW": 1, "HIGH": 2 }
+  }
+}
+```
+
+### Top-level blocks
+
+| Block type | Keys | Notes |
+| --- | --- | --- |
+| `struct` | `type`, `items` (list of field specs) | `items` is required |
+| `enum` | `type`, `items` (object `{NAME: value}`) | reads back the enumerator name |
+| `typedefs` | object `{alias: real_type}` | resolved before field building |
+
+Free-form metadata keys are allowed and ignored at any level: `version`,
+`description`, `author`, `comment`, `note`.
+
+### Field properties (inside a struct's `items`)
+
+Each entry in `items` is a **field spec**. Only the following keys are
+recognized — any other key triggers an "unknown keyword" error (with a
+"Did you mean …?" hint):
+
+| Property | Applies to | Description |
+| --- | --- | --- |
+| `name` | all | **Required.** C field name. |
+| `type` | all | **Required.** C type or a `typedefs` alias (e.g. `int32_t`, `float`, `char`, an enum/struct name). |
+| `value` | all | Default value. For arrays, a list (per element) or a scalar (applied to every element). |
+| `count` | arrays | Makes the field an array. Integer, a `#define` name, an expression (`N - 1`), or a list for multi-dim (`[3, 4]`, stored flat as 12). |
+| `min` / `max` | int, float | Numeric bounds. Validated `min <= max`. Drive spin-box / slider / dial ranges. |
+| `step` | int, float | Increment, must be `> 0`. |
+| `decimals` | float | Number of fractional digits shown/stored. Non-negative integer; defaults to digits implied by `step`. |
+| `unit` | all | Unit suffix shown in the label, e.g. `gain (dB)`. |
+| `tip` | all | Tooltip text. |
+| `choices` | int, float, `char[N]` | Discrete value set rendered as a combo (see below). |
+| `when` | all | Conditional enable/disable (see below). |
+| `widget` | all | Override the auto-picked editor (see table below). |
+
+### `widget` values
+
+When omitted, the widget is inferred from `type` (and from `min/max`,
+`choices`). Override it explicitly with `widget`:
+
+| `widget` | Valid for | Renders as |
+| --- | --- | --- |
+| `checkbox` | int | Check box (also auto-picked when `min:0, max:1`). |
+| `toggle` | bool/int | Toggle push-button. |
+| `combo` | int, float, `char[N]` | Combo box; pair with `choices`. |
+| `slider` | int | Slider with min/max labels (requires `min` & `max`). |
+| `dial` | int | Rotary dial popup (requires `min` & `max`). |
+| `file` | array | Path label + Browse button; loads array values from a text file. |
+| `multiline` | array | Single-line shell that pops up a multi-line editor. |
+| `table` | struct array | Force grid layout (one column per struct member). |
+
+Numeric fields without an explicit `widget` become a `QSpinBox` /
+`QDoubleSpinBox`; scalar arrays become a comma-separated line edit.
+
+### `choices` (discrete values)
+
+A non-enum integer / float / `char[N]` field can be constrained to a fixed set.
+Two forms are accepted:
+
+```jsonc
+"choices": [0, 1, 2, 3]                              // label = str(value)
+"choices": [{ "Off": 0 }, { "Low": 1 }, { "High": 2 }]  // explicit labels
+```
+
+The combo **reads back the underlying value** (not the label), so C / JSON / bin
+export still emits the number (or string for `char[N]`). Audits enforce: each
+value within `[min, max]` when declared, and `value` (the default) must be one
+of the choices.
+
+### `when` (conditional enable/disable)
+
+A field can be greyed out unless other fields hold specific values. `when` is an
+object mapping a **sibling field name** to its required value; all entries must
+match (logical AND):
+
+```jsonc
+{ "name": "cutoff", "type": "float", "when": { "enabled": 1, "mode": "HIGH" } }
+```
+
+The dependency name is matched against the dotted leaf name in scope. When a
+dependency is not found, the field stays enabled.
+
+### `count` expressions & multi-dimensional arrays
+
+`count` may be an integer, a `#define` constant name, or an integer expression
+of those using `+ - * / % ()` (e.g. `MAX_BAND_NUM - 1`). A list makes a
+multi-dimensional array that is **stored flat** to match the C ABI:
+
+```jsonc
+{ "name": "matrix", "type": "float", "count": [3, 4] }  // 12 contiguous floats, shown as [3][4]
+```
+
+`char[N]` is treated as a C string by default (use `widget` to override).
+
+### Validation
+
+Loading runs three layers of checks, surfaced in the **load report** panel:
+
+- **Keyword spelling** — unknown keys report "Did you mean `tip`?" style hints.
+- **Semantic audits** — `min <= max`, `step > 0`, `count > 0`, choices within
+  bounds, default is one of the choices.
+- **Pipeline cross-validation** — values in the pipeline file are checked
+  against the schema (range, choices, enum membership).
+
+## Embedding into an Existing UI
+
+`StructEditor` is a regular `QWidget`; just put it into a layout:
+
+```python
+from Qt import QtWidgets
+from struct2ui import StructEditor
+
+class MyWindow(QtWidgets.QMainWindow):
+    def __init__(self):
+        super().__init__()
+        editor = StructEditor(
+            "abc.json", "cfg_t",
+            settings_org="MyCompany",   # custom QSettings scope to
+            settings_app="MyApp",       # avoid clashing with the host app
+        )
+        self.setCentralWidget(editor)
+```
+
+### Constructor Parameters
+
+| Parameter | Description |
+| --- | --- |
+| `flow_file` | Path to the pipeline JSON file (pipeline definition), defaults to `None`; pick it in the UI when omitted |
+| `cfg_dir` | Modules directory holding `*.json` (struct / enum / typedef definitions), defaults to `None`; pick it in the UI when omitted |
+| `parent` | Qt parent object, defaults to `None` |
+| `elf_path` | Path to an ELF for layout verification, defaults to `None`; pick it in the UI when omitted |
+| `appearance` | Button appearance overrides, `{key: {'mode': ..., 'icon': ..., 'text': ...}}` |
+| `settings_org` | QSettings organization name, defaults to `'struct2ui'` |
+| `settings_app` | QSettings application name, defaults to `'StructEditor'` |
+| `toolbar_orientation` | Toolbar layout, `'horizontal'` (default) or `'vertical'` |
+| `custom_button_position` | Where `add_custom_button()` drops buttons relative to the built-ins: `'end'` (after, default) or `'start'` (before / far left) |
+
+## Custom Toolbar Buttons
+
+Host applications can add their own buttons to the top path bar via
+`add_custom_button()`. All custom buttons form a single group, separated from
+the built-in buttons by a divider that is added automatically — you only choose
+which side they sit on (once, via the `custom_button_position` constructor arg).
+
+```python
+editor = StructEditor("abc.json", "cfg_t", custom_button_position="end")
+
+def on_send():
+    print(editor.current_values())
+
+btn = editor.add_custom_button(
+    "Send",                 # tooltip / accessible label (shown when no icon)
+    on_send,                # callable invoked on click (no arguments)
+    icon="icons/send.png",  # optional; falls back to text when missing
+    checkable=False,        # optional; make the button toggleable
+)
+# `btn` is the created QPushButton, returned so you can tweak it further.
+```
+
+| Parameter | Description |
+| --- | --- |
+| `text` | Tooltip / accessible label, also shown when no icon is given. **Required.** |
+| `on_click` | Callable invoked on click, takes no arguments. **Required.** |
+| `icon` | Path to an icon file; falls back to `text` when the path is missing/empty. |
+| `checkable` | Make the button toggleable, defaults to `False`. |
+
+Returns the created `QPushButton`.
+
+## Programmatic API
+
+Beyond the UI, `StructEditor` exposes methods to read state and drive exports
+from code (e.g. wired to a custom button):
+
+| Method | Description |
+| --- | --- |
+| `current_values() -> dict` | Live editor values of the active section, keyed by field name (empty dict when no parameter section is shown). |
+| `current_paths() -> dict` | Current `{'modules', 'pipeline', 'elf'}` file paths; an empty string means that slot is unset. |
+| `export_bin(path, show_dialogs=False) -> bool` | Write the current pipeline to a `.bin` at `path` — the programmatic equivalent of clicking Export → Binary. Returns `True` when there are no ELF layout errors (or no ELF is selected), `False` otherwise. |
+
+`export_bin` verifies the ELF layout first when an ELF is selected (the file is
+still written, matching the UI flow). With `show_dialogs=True` it pops the same
+success / ELF-mismatch / failure dialogs the UI shows; with the default
+`show_dialogs=False` no dialogs appear and render/write failures are raised as
+exceptions for the caller to handle.
+
+```python
+paths = editor.current_paths()           # {'modules': ..., 'pipeline': ..., 'elf': ...}
+name = paths['pipeline']                  # derive an output name from the pipeline
+ok = editor.export_bin("out/speech.bin")  # True when ELF layout is clean
+```
+
+## Export API
+
+The low-level export functions can be used standalone, without any UI:
+
+```python
+from struct2ui.schema import SchemaRegistry
+from struct2ui.exporters import (
+    emit_c,          # sections + registry -> C source string
+    dumps_json,      # -> JSON string
+    emit_bin,        # -> binary bytes
+    merge_abi,       # merge ABI info
+    verify_sections, # verify .bin layout against an ELF
+    parse_c_source,  # C source -> parse result
+    build_schema_dict,
+)
+```
+
+## Architecture
+
+| Layer | Module | Responsibility |
+| --- | --- | --- |
+| Schema (pure data, no Qt) | `struct2ui.schema` | Parse `*.json` into a Field tree; spell-checking, semantic audits, pipeline cross-validation |
+| UI rendering | `struct2ui.ui` | `WidgetFactory`, `FormRenderer`/`TreeRenderer`, array tables, `when` conditional binding |
+| Export | `struct2ui.exporters` | C / JSON / bin export, C source reverse parsing, ELF verification |
+| Top-level widget | `struct2ui.StructEditor` | Path bar / action buttons / content area; load report panel; QSettings path memory |
+
+## Development
+
+```bash
+pip install -e ".[dev]" --no-build-isolation
+python -m pytest
+```
+
+Tests live under `tests/` and drive real Qt widgets headlessly on the offscreen platform.
+
+## License
+
+[MIT](LICENSE) © Jay

struct2ui-0.3.0/README.md

@@ -0,0 +1,309 @@
+# struct2ui
+
+Render C structs / JSON schemas as an **editable PySide6 UI**, and convert freely between **C / JSON / bin**. Built for algorithm parameter tuning: describe a C interface in JSON, auto-generate a Qt form, edit it, then export back to C source, JSON, or binary.
+
+## Features
+
+- **JSON → UI**: describe C structs / enums / arrays with minimal JSON and auto-render Qt widgets (int→QSpinBox, float→QDoubleSpinBox, enum→QComboBox, etc.).
+- **Embeddable**: `StructEditor` is a plain `QWidget` that drops into any PySide6 / PyQt UI.
+- **Multi-format export**: edited results export to C source, JSON, or binary; C source can also be parsed back into a schema.
+- **Validation**: keyword spell-checking (with “Did you mean X?” hints), semantic audits (`min<=max`, `step>0`), and pipeline cross-validation.
+- **Qt-binding agnostic**: built on [Qt.py](https://github.com/mottosso/Qt.py) — works with PySide6 / PyQt6 / PySide2 / PyQt5.
+
+## Installation
+
+```bash
+pip install struct2ui
+
+# Pick a Qt binding (choose one)
+pip install "struct2ui[pyside6]"
+pip install "struct2ui[pyqt6]"
+
+# Enable ELF layout verification (optional)
+pip install "struct2ui[elf]"
+```
+
+> The library itself only depends on `Qt.py`; you must install a Qt binding (PySide6 / PyQt6 / etc.) yourself.
+> ELF verification depends on `pyelftools`, installed via the `[elf]` extra.
+
+## Quick Start
+
+```python
+from Qt import QtWidgets
+from struct2ui import StructEditor
+
+app = QtWidgets.QApplication([])
+
+editor = StructEditor(
+    flow_file="abc.json",   # pipeline definition file (optional)
+    cfg_dir="cfg_t",        # modules dir: *.json holding struct/enum/typedef (optional)
+)
+editor.resize(480, 600)
+editor.show()
+
+app.exec_()
+```
+
+## JSON Schema Reference
+
+This is the core of the library: you describe your C types in JSON and the UI is
+generated from it. Files live in the **modules directory** (`cfg_dir`), one
+`*.json` per logical group. Each file is a flat object whose keys are either
+**type names** (your structs / enums) or the reserved key `typedefs`.
+
+### File layout
+
+```jsonc
+{
+  // optional free-form metadata (ignored by the loader, allowed anywhere)
+  "version": "1.0",
+  "description": "audio EQ parameters",
+
+  // type aliases: map a custom C type to a primitive
+  "typedefs": { "gain_t": "int32_t", "freq_t": "float" },
+
+  // a struct definition
+  "eq_cfg_t": {
+    "type": "struct",
+    "items": [
+      { "name": "enabled", "type": "uint8_t", "value": 1 },
+      { "name": "gain",    "type": "gain_t",  "value": 0,
+        "min": -12, "max": 12, "step": 1, "unit": "dB",
+        "tip": "output gain", "when": { "enabled": 1 } }
+    ]
+  },
+
+  // an enum definition
+  "mode_t": {
+    "type": "enum",
+    "items": { "OFF": 0, "LOW": 1, "HIGH": 2 }
+  }
+}
+```
+
+### Top-level blocks
+
+| Block type | Keys | Notes |
+| --- | --- | --- |
+| `struct` | `type`, `items` (list of field specs) | `items` is required |
+| `enum` | `type`, `items` (object `{NAME: value}`) | reads back the enumerator name |
+| `typedefs` | object `{alias: real_type}` | resolved before field building |
+
+Free-form metadata keys are allowed and ignored at any level: `version`,
+`description`, `author`, `comment`, `note`.
+
+### Field properties (inside a struct's `items`)
+
+Each entry in `items` is a **field spec**. Only the following keys are
+recognized — any other key triggers an "unknown keyword" error (with a
+"Did you mean …?" hint):
+
+| Property | Applies to | Description |
+| --- | --- | --- |
+| `name` | all | **Required.** C field name. |
+| `type` | all | **Required.** C type or a `typedefs` alias (e.g. `int32_t`, `float`, `char`, an enum/struct name). |
+| `value` | all | Default value. For arrays, a list (per element) or a scalar (applied to every element). |
+| `count` | arrays | Makes the field an array. Integer, a `#define` name, an expression (`N - 1`), or a list for multi-dim (`[3, 4]`, stored flat as 12). |
+| `min` / `max` | int, float | Numeric bounds. Validated `min <= max`. Drive spin-box / slider / dial ranges. |
+| `step` | int, float | Increment, must be `> 0`. |
+| `decimals` | float | Number of fractional digits shown/stored. Non-negative integer; defaults to digits implied by `step`. |
+| `unit` | all | Unit suffix shown in the label, e.g. `gain (dB)`. |
+| `tip` | all | Tooltip text. |
+| `choices` | int, float, `char[N]` | Discrete value set rendered as a combo (see below). |
+| `when` | all | Conditional enable/disable (see below). |
+| `widget` | all | Override the auto-picked editor (see table below). |
+
+### `widget` values
+
+When omitted, the widget is inferred from `type` (and from `min/max`,
+`choices`). Override it explicitly with `widget`:
+
+| `widget` | Valid for | Renders as |
+| --- | --- | --- |
+| `checkbox` | int | Check box (also auto-picked when `min:0, max:1`). |
+| `toggle` | bool/int | Toggle push-button. |
+| `combo` | int, float, `char[N]` | Combo box; pair with `choices`. |
+| `slider` | int | Slider with min/max labels (requires `min` & `max`). |
+| `dial` | int | Rotary dial popup (requires `min` & `max`). |
+| `file` | array | Path label + Browse button; loads array values from a text file. |
+| `multiline` | array | Single-line shell that pops up a multi-line editor. |
+| `table` | struct array | Force grid layout (one column per struct member). |
+
+Numeric fields without an explicit `widget` become a `QSpinBox` /
+`QDoubleSpinBox`; scalar arrays become a comma-separated line edit.
+
+### `choices` (discrete values)
+
+A non-enum integer / float / `char[N]` field can be constrained to a fixed set.
+Two forms are accepted:
+
+```jsonc
+"choices": [0, 1, 2, 3]                              // label = str(value)
+"choices": [{ "Off": 0 }, { "Low": 1 }, { "High": 2 }]  // explicit labels
+```
+
+The combo **reads back the underlying value** (not the label), so C / JSON / bin
+export still emits the number (or string for `char[N]`). Audits enforce: each
+value within `[min, max]` when declared, and `value` (the default) must be one
+of the choices.
+
+### `when` (conditional enable/disable)
+
+A field can be greyed out unless other fields hold specific values. `when` is an
+object mapping a **sibling field name** to its required value; all entries must
+match (logical AND):
+
+```jsonc
+{ "name": "cutoff", "type": "float", "when": { "enabled": 1, "mode": "HIGH" } }
+```
+
+The dependency name is matched against the dotted leaf name in scope. When a
+dependency is not found, the field stays enabled.
+
+### `count` expressions & multi-dimensional arrays
+
+`count` may be an integer, a `#define` constant name, or an integer expression
+of those using `+ - * / % ()` (e.g. `MAX_BAND_NUM - 1`). A list makes a
+multi-dimensional array that is **stored flat** to match the C ABI:
+
+```jsonc
+{ "name": "matrix", "type": "float", "count": [3, 4] }  // 12 contiguous floats, shown as [3][4]
+```
+
+`char[N]` is treated as a C string by default (use `widget` to override).
+
+### Validation
+
+Loading runs three layers of checks, surfaced in the **load report** panel:
+
+- **Keyword spelling** — unknown keys report "Did you mean `tip`?" style hints.
+- **Semantic audits** — `min <= max`, `step > 0`, `count > 0`, choices within
+  bounds, default is one of the choices.
+- **Pipeline cross-validation** — values in the pipeline file are checked
+  against the schema (range, choices, enum membership).
+
+## Embedding into an Existing UI
+
+`StructEditor` is a regular `QWidget`; just put it into a layout:
+
+```python
+from Qt import QtWidgets
+from struct2ui import StructEditor
+
+class MyWindow(QtWidgets.QMainWindow):
+    def __init__(self):
+        super().__init__()
+        editor = StructEditor(
+            "abc.json", "cfg_t",
+            settings_org="MyCompany",   # custom QSettings scope to
+            settings_app="MyApp",       # avoid clashing with the host app
+        )
+        self.setCentralWidget(editor)
+```
+
+### Constructor Parameters
+
+| Parameter | Description |
+| --- | --- |
+| `flow_file` | Path to the pipeline JSON file (pipeline definition), defaults to `None`; pick it in the UI when omitted |
+| `cfg_dir` | Modules directory holding `*.json` (struct / enum / typedef definitions), defaults to `None`; pick it in the UI when omitted |
+| `parent` | Qt parent object, defaults to `None` |
+| `elf_path` | Path to an ELF for layout verification, defaults to `None`; pick it in the UI when omitted |
+| `appearance` | Button appearance overrides, `{key: {'mode': ..., 'icon': ..., 'text': ...}}` |
+| `settings_org` | QSettings organization name, defaults to `'struct2ui'` |
+| `settings_app` | QSettings application name, defaults to `'StructEditor'` |
+| `toolbar_orientation` | Toolbar layout, `'horizontal'` (default) or `'vertical'` |
+| `custom_button_position` | Where `add_custom_button()` drops buttons relative to the built-ins: `'end'` (after, default) or `'start'` (before / far left) |
+
+## Custom Toolbar Buttons
+
+Host applications can add their own buttons to the top path bar via
+`add_custom_button()`. All custom buttons form a single group, separated from
+the built-in buttons by a divider that is added automatically — you only choose
+which side they sit on (once, via the `custom_button_position` constructor arg).
+
+```python
+editor = StructEditor("abc.json", "cfg_t", custom_button_position="end")
+
+def on_send():
+    print(editor.current_values())
+
+btn = editor.add_custom_button(
+    "Send",                 # tooltip / accessible label (shown when no icon)
+    on_send,                # callable invoked on click (no arguments)
+    icon="icons/send.png",  # optional; falls back to text when missing
+    checkable=False,        # optional; make the button toggleable
+)
+# `btn` is the created QPushButton, returned so you can tweak it further.
+```
+
+| Parameter | Description |
+| --- | --- |
+| `text` | Tooltip / accessible label, also shown when no icon is given. **Required.** |
+| `on_click` | Callable invoked on click, takes no arguments. **Required.** |
+| `icon` | Path to an icon file; falls back to `text` when the path is missing/empty. |
+| `checkable` | Make the button toggleable, defaults to `False`. |
+
+Returns the created `QPushButton`.
+
+## Programmatic API
+
+Beyond the UI, `StructEditor` exposes methods to read state and drive exports
+from code (e.g. wired to a custom button):
+
+| Method | Description |
+| --- | --- |
+| `current_values() -> dict` | Live editor values of the active section, keyed by field name (empty dict when no parameter section is shown). |
+| `current_paths() -> dict` | Current `{'modules', 'pipeline', 'elf'}` file paths; an empty string means that slot is unset. |
+| `export_bin(path, show_dialogs=False) -> bool` | Write the current pipeline to a `.bin` at `path` — the programmatic equivalent of clicking Export → Binary. Returns `True` when there are no ELF layout errors (or no ELF is selected), `False` otherwise. |
+
+`export_bin` verifies the ELF layout first when an ELF is selected (the file is
+still written, matching the UI flow). With `show_dialogs=True` it pops the same
+success / ELF-mismatch / failure dialogs the UI shows; with the default
+`show_dialogs=False` no dialogs appear and render/write failures are raised as
+exceptions for the caller to handle.
+
+```python
+paths = editor.current_paths()           # {'modules': ..., 'pipeline': ..., 'elf': ...}
+name = paths['pipeline']                  # derive an output name from the pipeline
+ok = editor.export_bin("out/speech.bin")  # True when ELF layout is clean
+```
+
+## Export API
+
+The low-level export functions can be used standalone, without any UI:
+
+```python
+from struct2ui.schema import SchemaRegistry
+from struct2ui.exporters import (
+    emit_c,          # sections + registry -> C source string
+    dumps_json,      # -> JSON string
+    emit_bin,        # -> binary bytes
+    merge_abi,       # merge ABI info
+    verify_sections, # verify .bin layout against an ELF
+    parse_c_source,  # C source -> parse result
+    build_schema_dict,
+)
+```
+
+## Architecture
+
+| Layer | Module | Responsibility |
+| --- | --- | --- |
+| Schema (pure data, no Qt) | `struct2ui.schema` | Parse `*.json` into a Field tree; spell-checking, semantic audits, pipeline cross-validation |
+| UI rendering | `struct2ui.ui` | `WidgetFactory`, `FormRenderer`/`TreeRenderer`, array tables, `when` conditional binding |
+| Export | `struct2ui.exporters` | C / JSON / bin export, C source reverse parsing, ELF verification |
+| Top-level widget | `struct2ui.StructEditor` | Path bar / action buttons / content area; load report panel; QSettings path memory |
+
+## Development
+
+```bash
+pip install -e ".[dev]" --no-build-isolation
+python -m pytest
+```
+
+Tests live under `tests/` and drive real Qt widgets headlessly on the offscreen platform.
+
+## License
+
+[MIT](LICENSE) © Jay

{struct2ui-0.1.0 → struct2ui-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "struct2ui"
-version = "0.1.0"
+version = "0.3.0"
 description = "Render C struct / JSON schema as editable PySide6 UI, export to C/JSON/bin"
 readme = "README.md"
 requires-python = ">=3.9"

{struct2ui-0.1.0 → struct2ui-0.3.0}/src/struct2ui/__init__.py

@@ -1,4 +1,4 @@
 from .editor import StructEditor
 
-__version__ = "0.1.0"
+__version__ = "0.3.0"
 __all__ = ["StructEditor"]