perspective_migrate/plugin.rs
1// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
2// ┃ ██████ ██████ ██████ █ █ █ █ █ █▄ ▀███ █ ┃
3// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█ ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄ ▀█ █ ▀▀▀▀▀ ┃
4// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄ █ ▄▄▄▄▄ ┃
5// ┃ █ ██████ █ ▀█▄ █ ██████ █ ███▌▐███ ███████▄ █ ┃
6// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
7// ┃ Copyright (c) 2017, the Perspective Authors. ┃
8// ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
9// ┃ This file is part of the Perspective library, distributed under the terms ┃
10// ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
11// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
12
13use crate::step::Step;
14
15/// The migrations of a plugin's `plugin_config` and `columns_config`, whose
16/// [`Step::at`] versions are the Perspective release that wrote a token rather
17/// than releases of the plugin itself.
18///
19/// # Example
20///
21/// ```
22/// use perspective_migrate::{Kind, Migrator, PluginMigration, Step, StepCx, Version};
23/// use serde_json::{Map, Value, json};
24///
25/// struct Sparkline;
26///
27/// fn rename_width(
28/// token: &mut Map<String, Value>,
29/// _cx: &mut StepCx,
30/// ) -> Result<(), perspective_migrate::MigrateError> {
31/// if let Some(Value::Object(config)) = token.get_mut("plugin_config")
32/// && let Some(width) = config.remove("width")
33/// {
34/// config.insert("line_width".to_owned(), width);
35/// }
36///
37/// Ok(())
38/// }
39///
40/// impl PluginMigration for Sparkline {
41/// fn plugins(&self) -> &[&'static str] {
42/// &["Sparkline"]
43/// }
44///
45/// fn steps(&self) -> Vec<Step> {
46/// vec![Step {
47/// at: Version::new(3, 0, 0),
48/// id: "sparkline.line_width",
49/// apply: rename_width,
50/// }]
51/// }
52/// }
53///
54/// let migrated = Migrator::new()
55/// .with_plugin(Sparkline)
56/// .migrate(Kind::Viewer, None, json!({
57/// "version": "2.10.0",
58/// "plugin": "Sparkline",
59/// "plugin_config": {"width": 2}
60/// }))
61/// .unwrap();
62///
63/// assert_eq!(migrated.value["plugin_config"], json!({"line_width": 2}));
64/// ```
65pub trait PluginMigration {
66 /// The `plugin` names whose payloads this migration owns.
67 fn plugins(&self) -> &[&'static str];
68
69 /// The plugin-layer steps, in any order.
70 fn steps(&self) -> Vec<Step>;
71}