Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion .claude/skills/plotjuggler-plugin/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
13 changes: 13 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion VERSION
Original file line number Diff line number Diff line change
@@ -1 +1 @@
1.1.0
1.2.0
5 changes: 5 additions & 0 deletions pj_base/include/pj_base/data_source_protocol.h
Original file line number Diff line number Diff line change
Expand Up @@ -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). */
Expand Down
12 changes: 12 additions & 0 deletions pj_plugins/docs/data-source-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand Down
8 changes: 8 additions & 0 deletions pj_plugins/include/pj_plugins/host/plugin_catalog.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -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<std::string> per_file_config_keys;
/// Widget plugins only: the widget types the library offers (non-empty for kWidget).
/// @since 0.39.0
std::vector<WidgetTypeDescriptor> widgets;
Expand Down
19 changes: 19 additions & 0 deletions pj_plugins/src/plugin_catalog.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -349,6 +349,24 @@ Expected<PluginDescriptor> 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;
Expand All @@ -358,6 +376,7 @@ Expected<PluginDescriptor> 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) {
Expand Down
23 changes: 23 additions & 0 deletions pj_plugins/tests/plugin_catalog_test.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -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<std::string>{"/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,
Expand Down
Loading