//! The command abstraction: static metadata, the run contract and the //! effects a command asks its host to carry out. use serde::Serialize; use serde_json::Value; use crate::{EngineError, Event, State}; /// Static metadata of a command. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub struct CommandSpec { /// Unique id, `area.action` in camelCase, e.g. `app.about`. pub id: &'static str, /// Label for menus and the command palette, in English. pub label: &'static str, /// Menu path with `/` separators, e.g. `Help/About Lutra`. pub menu_path: Option<&'static str>, /// Default shortcut in Lutra notation; `Mod` is Ctrl, or Cmd on macOS. pub default_shortcut: Option<&'static str>, /// Documentation of the params object, `none` if the command takes none. pub params: &'static str, } /// Something the engine asks its host to do after a command returns, /// because it needs a layer the engine cannot reach (windows, the process). #[derive(Debug, Clone, PartialEq, Eq, Serialize)] #[serde(tag = "kind", rename_all = "camelCase")] pub enum Effect { /// Quit the application. Quit, /// Show the native folder picker and run `project.open` with the chosen /// folder. Cancelling the picker does nothing and is not an error. PickFolder, } /// Result of a successful command. #[derive(Debug, Clone, PartialEq, Default)] pub struct Outcome { /// JSON result returned to the caller. pub value: Value, /// Effects for the host to apply, in order. pub effects: Vec, /// State changes for the host to publish, oldest first. Filled by the /// engine from the events the command queued; commands leave it empty. pub events: Vec, } impl Outcome { /// An outcome with a value and no effects. pub fn value(value: Value) -> Self { Self { value, effects: Vec::new(), events: Vec::new(), } } /// An outcome with a null value and one effect. pub fn effect(effect: Effect) -> Self { Self { value: Value::Null, effects: vec![effect], events: Vec::new(), } } } /// A user-visible action. /// /// Implementations are stateless; everything they change lives in [`State`]. pub trait Command: Send + Sync { /// Static metadata. fn spec(&self) -> &CommandSpec; /// Whether the command can run in the given state. Defaults to always. fn enabled(&self, _state: &State) -> bool { true } /// Runs the command. /// /// # Errors /// Returns [`EngineError::InvalidParams`] for params that don't match /// [`CommandSpec::params`], and [`EngineError::Failed`] when the action /// itself fails. fn run(&self, state: &mut State, params: Value) -> Result; } /// Description of a command for menus, the palette, keymaps and agents. #[derive(Debug, Clone, PartialEq, Eq, Serialize)] #[serde(rename_all = "camelCase")] pub struct CommandInfo { /// Command id. pub id: String, /// Label. pub label: String, /// Menu path, if the command is in a menu. pub menu_path: Option, /// Default shortcut, if any. pub default_shortcut: Option, /// Params documentation. pub params: String, /// Whether the command can run in the current state. pub enabled: bool, /// Message-catalog key of the label; set for UI commands, whose `label` /// is the same key because the engine has no English text for them. #[serde(skip_serializing_if = "Option::is_none")] pub label_key: Option, /// Whether the frontend registered the command (`ui.registerCommands`) /// and runs it; running it through the engine emits `uiCommand`. pub ui: bool, } impl CommandInfo { /// Builds the description from a spec and the current enabled state. pub fn new(spec: &CommandSpec, enabled: bool) -> Self { Self { id: spec.id.to_string(), label: spec.label.to_string(), menu_path: spec.menu_path.map(str::to_string), default_shortcut: spec.default_shortcut.map(str::to_string), params: spec.params.to_string(), enabled, label_key: None, ui: false, } } }