diff --git a/.claude/skills/plotjuggler-plugin/SKILL.md b/.claude/skills/plotjuggler-plugin/SKILL.md index 13155a8c..3a0cef5b 100644 --- a/.claude/skills/plotjuggler-plugin/SKILL.md +++ b/.claude/skills/plotjuggler-plugin/SKILL.md @@ -186,7 +186,9 @@ The host routes payloads by these case-sensitive names, and admits only the registered ones: `PJ::registeredParserEncodings()` in `pj_plugins/host/parser_claim_catalog.hpp` is the list. A parser claiming any other name is refused when its claims are admitted. -DataSource may add `"file_extensions": [".csv"]`. A Widget manifest needs +DataSource may add `"file_extensions": [".csv"]`, and `"per_file_config_keys": +["/time_column"]` for config members chosen for one file (see the data-source +guide's config rules). A Widget manifest needs `widgets` and `qt_modules` (see `references/widget.md`). `pj_emit_plugin_manifest` (the pre-0.25 name) still works but is deprecated. diff --git a/CHANGELOG.md b/CHANGELOG.md index 0a717c66..710c8227 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,19 @@ All notable changes to `plotjuggler_sdk` are recorded here. Versioning policy is in [`CLAUDE.md`](./CLAUDE.md) → "Release Versioning". +## [1.2.0] — Unreleased + +Host contract: unchanged (no floor impact). +Declarative, like `badge`: no ABI, vtable or capability change. A plugin declares the key in its +manifest without a new `min_sdk_required`; a host built before 1.2.0 ignores it. + +- Manifest: optional `per_file_config_keys`, an array of JSON Pointers (RFC 6901) to the config + members that describe one particular file, e.g. `["/time_column_index"]`. Decoded into + `PluginDescriptor::per_file_config_keys` (empty when absent); a non-array, a non-string entry or + an entry that is not a pointer to a member invalidates the manifest. A host that pre-fills the + loader dialog with the config saved for another file drops these members. +- Data-source guide: the pre-fill rule next to the other config rules, and the manifest table row. + ## [1.1.0] Host contract: extended: PJ_widget_host_vtable_t::notify_config_changed (floor 1.1.0). The slot is diff --git a/VERSION b/VERSION index 9084fa2f..26aaba0e 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -1.1.0 +1.2.0 diff --git a/pj_base/include/pj_base/data_source_protocol.h b/pj_base/include/pj_base/data_source_protocol.h index 7a79dfb8..a2b552b1 100644 --- a/pj_base/include/pj_base/data_source_protocol.h +++ b/pj_base/include/pj_base/data_source_protocol.h @@ -572,6 +572,11 @@ typedef struct PJ_data_source_vtable_t { * FINITE_IMPORT SHOULD include this so the host * can build file-dialog filters without * instantiating the plugin. + * "per_file_config_keys" — array of JSON Pointers (RFC 6901) to the + * config members that describe one particular + * file. A host pre-filling the dialog with the + * config saved for another file drops them first. + * Since 1.2.0; older hosts ignore it. */ const char* manifest_json; /** [main-thread] Return capability bitmask (PJ_DATA_SOURCE_CAPABILITY_* flags). */ diff --git a/pj_plugins/docs/data-source-guide.md b/pj_plugins/docs/data-source-guide.md index 174f8c79..38b48f53 100644 --- a/pj_plugins/docs/data-source-guide.md +++ b/pj_plugins/docs/data-source-guide.md @@ -607,6 +607,17 @@ The config is a UTF-8 JSON object. The rules (normative text on - `saveConfig()` may return `"filepath"` and `"_parser_config"` (a file layout replays `saveConfig()` output, so that is how its parser config survives), never `"__pj_saved_filepath"` (the reference host strips it). +- The host pre-fills a file loader's dialog with the config its dialog saved + last, with `"filepath"` set to the new file. Members that only make sense for + the file they were chosen for (a time column picked by index from its header, + a mode forced for its data) would then apply to a different file. List them + in the manifest's `per_file_config_keys` as JSON Pointers + (`["/time_column_index"]`): the reference host drops them when the saved + `"filepath"` names another file (or none), and keeps them when the same file + is opened again. `loadConfig()` must accept the config without them and fall + back to its defaults. Layout replay and the Reload action apply the config + recorded for that file and drop nothing. A host older than 1.2.0 ignores the + key and pre-fills the whole config. ### Progress reporting @@ -702,6 +713,7 @@ it without instantiating the plugin. | `version` | string | yes | Semver version string. | | `description` | string | no | Short description of the plugin. | | `file_extensions` | string[] | no | File extensions this source handles, e.g. `[".csv", ".tsv"]`. Plugins declaring `kCapabilityFiniteImport` SHOULD include this so the host can build file-dialog filters. | +| `per_file_config_keys` | string[] | no | JSON Pointers to the config members that describe one particular file, e.g. `["/time_column_index"]` (1.2.0). A host pre-filling the dialog for a different file drops them; see the config rules above. A malformed pointer invalidates the manifest. Read as `PluginDescriptor::per_file_config_keys`. | `min_sdk_required`, `suggested_sdk_version` (with a `floor_test`) and the deprecated `min_plotjuggler_version` are optional compatibility keys common to diff --git a/pj_plugins/include/pj_plugins/host/plugin_catalog.hpp b/pj_plugins/include/pj_plugins/host/plugin_catalog.hpp index 12becaaa..13b838ff 100644 --- a/pj_plugins/include/pj_plugins/host/plugin_catalog.hpp +++ b/pj_plugins/include/pj_plugins/host/plugin_catalog.hpp @@ -77,6 +77,14 @@ struct PluginDescriptor { /// nothing) is host policy. At most 8 characters are advised; a host may truncate. /// @since 0.38.0 std::string badge; + /// Data sources: JSON Pointers (RFC 6901, e.g. "/time_column") to the members of the + /// plugin's config that describe one particular file, such as a column picked from its + /// header or a mode forced for its data; empty when undeclared. A host that pre-fills the + /// loader dialog with the config saved for another file drops these members first, so the + /// plugin falls back to its defaults; reopening the same file keeps them. Declarative: a + /// host built before 1.2.0 ignores it. + /// @since 1.2.0 + std::vector per_file_config_keys; /// Widget plugins only: the widget types the library offers (non-empty for kWidget). /// @since 0.39.0 std::vector widgets; diff --git a/pj_plugins/src/plugin_catalog.cpp b/pj_plugins/src/plugin_catalog.cpp index 55d27c2c..e66dd2c8 100644 --- a/pj_plugins/src/plugin_catalog.cpp +++ b/pj_plugins/src/plugin_catalog.cpp @@ -349,6 +349,24 @@ Expected decodeManifest( if (!capabilities) { return unexpected(capabilities.error()); } + auto per_file_config_keys = readStringArray(j, "per_file_config_keys"); + if (!per_file_config_keys) { + return unexpected(per_file_config_keys.error()); + } + for (const auto& key : *per_file_config_keys) { + // "" is the whole config, not a member a host could drop. + bool member_pointer = !key.empty(); + try { + (void)nlohmann::json::json_pointer(key); + } catch (const nlohmann::json::exception&) { + member_pointer = false; + } + if (!member_pointer) { + return unexpected( + fmt::format( + "plugin embedded manifest per_file_config_keys entry is not a JSON pointer to a member: \"{}\"", key)); + } + } d.description = *description; d.category = *category; @@ -358,6 +376,7 @@ Expected decodeManifest( d.badge = *badge; d.file_extensions = *file_extensions; d.capabilities = *capabilities; + d.per_file_config_keys = std::move(*per_file_config_keys); auto encoding = readStringArray(j, "encoding"); if (!encoding) { diff --git a/pj_plugins/tests/plugin_catalog_test.cpp b/pj_plugins/tests/plugin_catalog_test.cpp index e90db44f..fdbb5a14 100644 --- a/pj_plugins/tests/plugin_catalog_test.cpp +++ b/pj_plugins/tests/plugin_catalog_test.cpp @@ -407,6 +407,29 @@ TEST_F(PluginCatalogTest, BadgeRejectsNonString) { EXPECT_NE(descriptor.error().find("badge"), std::string::npos); } +TEST_F(PluginCatalogTest, PerFileConfigKeysDecodeAndDefaultToEmpty) { + auto declared = decodeManifest( + "static:csv", PluginFamily::kDataSource, + R"({"id":"csv","name":"CSV","version":"1.0.0","per_file_config_keys":["/time_column","/a~1b/c"]})"); + ASSERT_TRUE(declared.has_value()) << declared.error(); + EXPECT_EQ(declared->per_file_config_keys, (std::vector{"/time_column", "/a~1b/c"})); + + auto absent = + decodeManifest("static:csv", PluginFamily::kDataSource, R"({"id":"csv","name":"CSV","version":"1.0.0"})"); + ASSERT_TRUE(absent.has_value()) << absent.error(); + EXPECT_TRUE(absent->per_file_config_keys.empty()); +} + +TEST_F(PluginCatalogTest, PerFileConfigKeysRejectWhatIsNotAMemberPointer) { + for (const char* keys : {R"("time_column")", R"(["time_column"])", R"([""])", R"(["/a~2"])", R"([3])"}) { + const std::string manifest = + std::string(R"({"id":"csv","name":"CSV","version":"1.0.0","per_file_config_keys":)") + keys + "}"; + auto descriptor = decodeManifest("static:csv", PluginFamily::kDataSource, manifest); + ASSERT_FALSE(descriptor.has_value()) << keys; + EXPECT_NE(descriptor.error().find("per_file_config_keys"), std::string::npos) << descriptor.error(); + } +} + TEST_F(PluginCatalogTest, CapabilityTagsAreDeclarativeWithEmptyFallback) { auto editor = decodeManifest( "static:editor", PluginFamily::kToolbox,