//! 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, 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, /// An answer the command is still waiting for (a language server /// request). The host waits for it with [`Pending::wait`] without the /// engine lock and finishes it with [`crate::Engine::resolve`]; the /// caller's result is the resolved value, not [`Outcome::value`]. pub pending: Option, } impl Outcome { /// An outcome with a value and no effects. pub fn value(value: Value) -> Self { Self { value, ..Self::default() } } /// An outcome with a null value and one effect. pub fn effect(effect: Effect) -> Self { Self { effects: vec![effect], ..Self::default() } } /// An outcome whose value comes later from `pending`. pub fn pending(pending: Pending) -> Self { Self { pending: Some(pending), ..Self::default() } } } /// The answer a language server request delivers: its result, its error, /// or `None` when it never came (timeout, the session ended). pub type Reply = Option>; /// Turns a [`Reply`] into the command's value, under the engine lock. type Finish = Box Result + Send>; /// A command result that waits for an answer from outside the engine. /// /// Waiting never holds the engine lock: hosts call [`Pending::wait`] after /// releasing it, then [`crate::Engine::resolve`] with the lock to turn the /// answer into the value (which may change the state, as a rename does). pub struct Pending { /// Where the answer arrives. receiver: std::sync::mpsc::Receiver>, /// How long to wait at most. timeout: std::time::Duration, /// What to do with it. finish: Finish, } impl std::fmt::Debug for Pending { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { f.debug_struct("Pending") .field("timeout", &self.timeout) .finish_non_exhaustive() } } impl Pending { /// A pending result. /// /// # Parameters /// - `receiver`: receives the answer; a dropped sender counts as no /// answer. /// - `timeout`: the longest wait; the request's own timeout should be /// shorter, so it reports first. /// - `finish`: builds the value from the answer, under the lock. pub fn new( receiver: std::sync::mpsc::Receiver>, timeout: std::time::Duration, finish: impl FnOnce(&mut State, Reply) -> Result + Send + 'static, ) -> Self { Self { receiver, timeout, finish: Box::new(finish), } } /// Blocks until the answer arrives, the sender is dropped or the /// timeout (plus one second of grace) passes. Call it without the /// engine lock. pub fn wait(self) -> Answered { let reply = self .receiver .recv_timeout(self.timeout + std::time::Duration::from_secs(1)) .ok(); Answered { reply, finish: self.finish, } } } /// A [`Pending`] whose answer arrived (or never will); pass it to /// [`crate::Engine::resolve`]. pub struct Answered { /// The answer. reply: Reply, /// What to do with it. finish: Finish, } impl std::fmt::Debug for Answered { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { f.debug_struct("Answered") .field("reply", &self.reply) .finish_non_exhaustive() } } impl Answered { /// Builds the value; for [`crate::Engine::resolve`]. pub(crate) fn finish(self, state: &mut State) -> Result { (self.finish)(state, self.reply) } } /// 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, } } }